diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..230dd44 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,316 @@ +--- +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.** \ No newline at end of file