glas-harness/INTENT.md

domain	repo	updated
infotech	glas-harness	2026-08-20

INTENT

glas-harness is the Coulomb meta-framework for agent harnesses — a unified API and extension platform for running agentic assistants with tools, memory, channels, and subagent delegation, while consuming sand-boxer for isolated execution. The implemented nucleus is a versioned, profile-driven execution router over concrete reins.

---

Why it exists

Custodian needs agents that work across channels (CLI, chat, scheduled jobs) with persistent memory, skills, and tool access — without every product reinventing a gateway, session model, and sandbox wiring.

The industry ships capable but fragmented harnesses: OpenClaw (personal assistant

• optional Docker/SSH/OpenShell sandboxing), Hermes Agent (multi-backend terminal, skills, subagents, Modal/Daytona), Claude Code, Codex, and dozens of channel- specific bots. Each bundles harness concerns (gateway, tools, memory) with runtime concerns (where code runs) in different shapes.

Coulomb splits that stack deliberately:

Layer	Owner
Harness — gateway, tools, memory, channels, subagents	glas-harness
Sandbox establishment — profiles, isolation, placement	sand-boxer
Validation — e2e, health, pass/fail	wise-validator
Code generation — specs, generation, PR output	snuggle-inventor

glas-harness exists to be the harness side of that split: one consistent way to execute assigned agent work, with extensions for channels and tool backends, and a single integration path to sand-boxer when tools need isolation.

sand-boxer is OpenRouter for sandboxes. glas-harness is the parallel harness router — not for LLM inference routing (that stays with model providers and llm-connect), but for agent runtime composition: which gateway, which tool policy, which sandbox profile, which channel surface.

---

The governing principle

glas-harness is the agent harness service — gateway lifecycle, tool orchestration, session semantics, memory and skills, channel bridges, subagent delegation, and sandbox consumption. Nothing more.

It answers:

1. How does an agent session run? Gateway, turn loop, tool dispatch, actor attribution (adm / agt / atm).
2. What can the agent invoke? Tool catalog, policies, elevated escape hatches.
3. What does the agent remember? Memory, skills, identity documents, cron.
4. Where does the user interact? Channel extensions (CLI, chat, email, …).
5. When do tools run in isolation? A named sand-boxer profile selected by the Glas profile — fulfilled by sand-boxer, not implemented here.
6. How are subagents delegated? Isolated sub-sessions with bounded context.
7. What happened? Session and tool audit events to State Hub.

It must not become the sandbox provisioner, the e2e validator, the code generator, the scheduler, work-state authority, tunnel/CA owner, or production service host on Railiance01.

Relationship to leadership and workforce management

Leadership and workforce management govern responsibility: roles, duties, goals, assignments, resource envelopes, escalation, and who may initiate work. Glas governs execution after that decision. Its request can carry opaque assignment_ref, role_ref, duty_ref, goal_refs, and resource_envelope_refs so evidence remains attributable without duplicating the organizational records.

This separation is intentional:

leadership / workforce authority
  -> authorized assignment + organizational references
  -> Glas ExecutionRequest + explicit harness profile
  -> resolved rein/model/sandbox/tool-policy constellation
  -> normalized evidence linked back to the assignment

Glas may refuse an unavailable or incompatible execution profile. It does not choose a leader, allocate a worker, reinterpret a duty, compile a role into a blueprint, or decide when work should run. Those decisions remain inspectable in their owning system while Glas supplies a stable, replaceable execution boundary.

---

Coulomb sibling boundaries

sand-boxer — sandbox establishment

sand-boxer owns: Profiles, extensions, provision/teardown, placement, lifecycle registration, SaaS metering for sandbox backends.

glas-harness owns: Requesting a sandbox, configuring when tools use it, executing tools inside the returned environment via reachability descriptor.

glas-harness calls sand-boxer; it does not embed compose-ssh, VM provisioners, or extension adapters.

glas-harness                          sand-boxer
─────────────                         ──────────
sandbox policy (mode/scope/access)  → POST /v1/sandboxes
receive sandbox_id + reachability   ← profile + extension + host
exec/read/write via SSH/tunnel/exec   (harness-owned tool path)

Reference: sand-boxer/INTENT.md, sand-boxer/research/02-reference-frameworks.md (OpenClaw/Hermes patterns).

wise-validator — e2e test and health

wise-validator owns: Validation workflows, health semantics, test orchestration, structured results.

glas-harness does not own e2e compose orchestration or pass/fail reporting. Agents may trigger validation jobs; wise-validator runs them.

snuggle-inventor — code generation

snuggle-inventor owns: Code generation pipelines, tech specs, PR-oriented output, human review gates.

glas-harness does not generate product codebases. It may host agents that invoke snuggle-inventor as a tool or workflow consumer.

Boundary diagram

  Channels / CLI / cron
           │
           ▼
    glas-harness  ──request sandbox──▶  sand-boxer
    (harness)              │                  │
           │               │                  ▼
           │               │            extensions
           ├─invoke───────▶│ wise-validator (e2e)
           └─invoke───────▶│ snuggle-inventor (codegen)

Existing Custodian repos

Concern	Owner
Workstream, task, progress state	state-hub
Cron and orchestration	activity-core
SSH reverse tunnels	ops-bridge
SSH certificate issuance	ops-warden
Canon and agent instruction canon	the-custodian
Capability federation hub	reuse-surface
LLM inference routing	llm-connect
Production on Railiance01	railiance-apps / domain repos

glas-harness consumes sand-boxer, ops-bridge, ops-warden, llm-connect, and State Hub; it does not subsume them.

---

What it is

glas-harness is a meta-framework with four pillars (preliminary):

1. Unified harness API

One versioned surface for session lifecycle across channel and automation consumers. The implemented gateway accepts an explicit ExecutionRequest, resolves a harness profile, executes one bounded rein session, and returns ExecutionEvidence. Longer-lived sessions and subagent join semantics remain future work.

• Start / resume / end sessions; subagent spawn and join
• Tool dispatch with policy checks and audit metadata
• Sandbox policy resolution → sand-boxer create / destroy
• Actor attribution on every tool and channel action

Early consumers: Custodian coding agents, activity-core-triggered agent jobs, human operators via CLI.

2. Harness profile catalog

Named, versioned harness profiles (distinct from sand-boxer sandbox profiles) are runtime inputs, not documentation. They currently bind:

• concrete rein and required capabilities;
• sand-boxer profile;
• tool profile;
• model provider, route, class, and explicit model identifier;
• token, timeout, and turn limits; and
• credential-route references without credential values.

Resolution is deterministic and fail-closed. Governed execution has no implicit rein, model, sandbox, or tool policy.

Example pairing:

Harness profile	sand-boxer profile
harness.agent-dev	profile.agent-dev
harness.channel-bot	profile.agent-dev or host-local
harness.ci-agent	profile.compose-e2e (validator runs tests)

3. Extension platform

Extensions delegate harness capabilities:

Extension class	Examples
Channel	CLI, Slack, Telegram, email bridge, MCP gateway
Tool backend	Local exec, sandbox exec (via sand-boxer handle), MCP servers
Memory store	Filesystem layout, future vector stores
Harness adapter	Optional wrappers for OpenClaw- or Hermes-compatible configs

Extensions implement a harness contract; they do not provision sandboxes directly.

4. Observability and governance

• Structured audit log: tool name, actor, sandbox id, model hash (if applicable)
• State Hub progress and session events
• Elevated tool paths explicitly marked and configurable (OpenClaw tools.elevated lesson: bypass must be visible, not accidental)

---

What it is not

Concern	Owner
Sandbox runtimes, profiles, placement	sand-boxer
E2e tests, health checks, validation	wise-validator
Code generation, tech specs, AAP	snuggle-inventor
When jobs run	activity-core
Task/workstream state	state-hub
Tunnels	ops-bridge
Certs	ops-warden
Model API keys and inference routing	llm-connect

glas-harness orchestrates agent behavior. sand-boxer establishes where dangerous work runs. Confusing the two recreates the monolith Coulomb is splitting apart.

---

Lineage and research inputs

glas-harness consolidates harness patterns from the ecosystem, not sandbox runtimes:

Source	Harness ideas to adopt
OpenClaw	Gateway on host; sandbox mode / scope / workspaceAccess; channel matrix; skills mirroring; elevated exec policy
Hermes Agent	Subagent delegation; labeled Docker reuse policy; home_mode; cron; multi-channel gateway
NemoClaw + OpenShell	Credential brokering at boundary (consume via sand-boxer + ops-warden, not reimplement)

Sandbox research lives in sand-boxer/research/ — glas-harness references it for integration design only.

Migration from ad hoc agent setups

Today	Future owner
Per-repo agent instructions without gateway	glas-harness profiles
OpenClaw/Hermes sandbox config duplicated	glas-harness policy → sand-boxer API
Agent tool exec on workstation filesystem	sand-boxer-backed profiles via harness
Channel bots one-off per integration	glas-harness channel extensions

---

Intended users

• Human operators (adm) — configure harness profiles, channels, tool policies
• LLM agents (agt) — run inside glas-harness sessions (primary runtime)
• Deterministic automations (atm) — activity-core and CI invoke harness API
• Extension authors — channel and tool backend plugins
• Domain repos — consume harness profiles; do not fork gateway code

---

Design principles

• Harness meta-framework, not monolith — one API; extensions for channels and tools
• sand-boxer for isolation — never embed provisioners; request profiles explicitly
• Gateway stays on control plane — tools may run remote; gateway does not move into sandbox
• Profiles over one-offs — named harness recipes, paired with sand-boxer profiles
• Observable by default — every tool call and sandbox transition attributable
• Elevated paths are explicit — bypass sandbox only through configured escape hatches
• Registry-first reuse — register harness capabilities in registry/
• Channel neutrality — same session semantics across CLI and chat surfaces
• Subagents are bounded — isolated context, own tool policy, optional sandbox scope

---

Sandbox consumption contract

When harness policy requires isolation, glas-harness:

1. Resolves the sandbox profile id from the versioned harness profile
2. Calls sand-boxer create with consumer: { harness: glas-harness, session_id, actor }
3. Stores sandbox_id and reachability descriptor on the session
4. Routes exec, read, write, edit, and related tools through that handle
5. Calls sand-boxer destroy or recreate on session end or policy transition

Harness owns tool semantics; sand-boxer owns environment lifecycle.

Open integration questions:

• Does glas-harness proxy exec or delegate SSH/tunnel to the agent client?
• How are mirror vs remote-canonical workspace modes exposed to tool implementations?

Document answers in docs/integrations/sand-boxer.md when sand-boxer SAND-WP-0002 T08 lands.

---

Implemented nucleus and next outcomes

Implemented: strict contract version 1.0, executable profile catalog, rein-registry validation, explicit CLI/channel selection, sand-boxer lifecycle, two concrete rein constellations, and normalized State Hub evidence.

Next outcomes should be driven by real consumers: an additional channel, memory/skills integration, bounded subagent delegation, and an organizational assignment adapter. None should weaken explicit profile selection or move workforce authority into Glas.

---

Maturity target

A mature glas-harness is Coulomb's default agent runtime:

• Coding agents request sandboxes through one harness API, not per-backend config
• Channels share memory, skills, and sandbox policy across surfaces
• activity-core triggers agent sessions without workstation-local gateway installs
• Operators inspect tool and sandbox audit trails in State Hub
• Extensions add channels and tool backends without forking core gateway logic

The harness thinks and coordinates. sand-boxer establishes the box. wise-validator proves correctness. snuggle-inventor invents code. glas-harness runs the agent.