generated from coulomb/repo-seed
Seeded INTENT.md
This commit is contained in:
316
INTENT.md
Normal file
316
INTENT.md
Normal file
@@ -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.**
|
||||
Reference in New Issue
Block a user