glas-harness/INTENT.md

---
domain: infotech
repo: glas-harness
updated: "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:

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?** Sandbox policy (`mode`, `scope`,
   `workspaceAccess`) — 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.

---

## 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.

```text
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.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 (preliminary)

When harness policy requires isolation, glas-harness:

1. Resolves sandbox profile id (from harness profile or session override)
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 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)

1. **This charter** — `INTENT.md` aligned with sand-boxer sibling boundaries
2. **Harness profile schema sketch** — distinct from sand-boxer profile schema
3. **sand-boxer integration doc** — consumer contract (may start in sand-boxer repo)
4. **First harness profile** — `harness.agent-dev` paired with `profile.agent-dev`
5. **CLI gateway stub** — minimal session + local tools (no channels yet)
6. **Registry entry** — e.g. `capability.platform.agent-harness`
7. **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.**