350 lines
14 KiB
Markdown
350 lines
14 KiB
Markdown
---
|
|
domain: infotech
|
|
repo: glas-harness
|
|
updated: "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:
|
|
|
|
```text
|
|
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.
|
|
|
|
```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 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.**
|