12 KiB
domain, repo, updated
| domain | repo | updated |
|---|---|---|
| infotech | glas-harness | 2026-06-22 |
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. This file is preliminary; refine as the harness boundary is implemented.
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 run agents, 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:
- How does an agent session run? Gateway, turn loop, tool dispatch, actor
attribution (
adm/agt/atm). - What can the agent invoke? Tool catalog, policies, elevated escape hatches.
- What does the agent remember? Memory, skills, identity documents, cron.
- Where does the user interact? Channel extensions (CLI, chat, email, …).
- When do tools run in isolation? Sandbox policy (
mode,scope,workspaceAccess) — fulfilled by sand-boxer, not implemented here. - How are subagents delegated? Isolated sub-sessions with bounded context.
- 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.
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 surface for session lifecycle across channel and automation consumers:
- 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):
- Default toolset and tool policy
- Sandbox policy defaults (
mode,scope,workspaceAccess) — OpenClaw-aligned - Memory and skills layout conventions
- Channel allowlist
- Model routing hints (consumer of
llm-connect, not owner) - Registered in
registry/via reuse-surface
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.elevatedlesson: 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 (preliminary)
When harness policy requires isolation, glas-harness:
- Resolves sandbox profile id (from harness profile or session override)
- Calls sand-boxer
createwithconsumer: { harness: glas-harness, session_id, actor } - Stores
sandbox_idand reachability descriptor on the session - Routes
exec,read,write,edit, and related tools through that handle - Calls sand-boxer
destroyorrecreateon session end or policy transition
Harness owns tool semantics; sand-boxer owns environment lifecycle.
Open questions (for first workplan):
- 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.
Near-term outcomes (preliminary)
- This charter —
INTENT.mdaligned with sand-boxer sibling boundaries - Harness profile schema sketch — distinct from sand-boxer profile schema
- sand-boxer integration doc — consumer contract (may start in sand-boxer repo)
- First harness profile —
harness.agent-devpaired withprofile.agent-dev - CLI gateway stub — minimal session + local tools (no channels yet)
- Registry entry — e.g.
capability.platform.agent-harness - State Hub session events — tool audit envelope
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.