# Research: Hosted Agent Harnesses Survey of current agent harness, swarm, memory, and interoperability patterns for [capOS-Hosted Agent Swarms](../proposals/hosted-agent-swarm-proposal.md). The design question is how capOS should host OpenClaw-like personal agents without copying the ambient-host authority model common in desktop tools. ## Source Snapshot Checked on 2026-04-28: - OpenAI, Harness engineering: - OpenAI, Agents SDK harness/sandbox update: - OpenClaw docs: , , , , , , - DeepWiki secondary summaries: , , , , , - Karpathy, LLM Wiki: - Abdullin, Schema-Guided Reasoning: - MetaGPT: - Generative Agents: - Gas Town docs: , - Model Context Protocol: , - Agent2Agent Protocol: , - Microsoft AutoGen and Microsoft Agent Framework: , - LangGraph durable execution: - CrewAI: - CAMEL-AI: DeepWiki was accessible for the related projects above. It is useful as a code-linked summary layer, but this note treats it as secondary to primary project docs and papers. ## Design Consequences For capOS - Treat the harness as the product surface: workspace, memory, tool descriptors, approval, cancellation, audit, and task state matter as much as model choice. - Do not treat an agent workspace as a sandbox. In capOS, workspace boundaries should be enforced by capabilities, not by cwd conventions. - Keep the model out of the authority path. The model proposes structured tool calls; a trusted runner validates and invokes caps. - Use a persistent artifact model for agent knowledge. Raw sources, wiki pages, indexes, logs, and search indexes should be explicit, versioned, label-aware data, not hidden prompt history. - Borrow swarm patterns cautiously. Roles, review gates, and durable tasks are useful; anthropomorphic role names and unconstrained peer delegation are not. - Treat MCP and A2A as adapter protocols. They can carry descriptors, messages, and artifacts, not raw capOS authority. - Prefer deterministic harness proofs first: fake model, fake browser, fake mutating tool, explicit approval, and auditable transcript. ## OpenAI Harness Engineering OpenAI's Harness engineering article frames the key operational lesson: agents can only reason over context they can inspect. Repo-local files, schemas, tests, executable plans, and mechanically enforced architecture are therefore stronger harness material than knowledge left in chat, external docs, or tacit human convention. The 2026 Agents SDK update moves in the same direction: a model-native harness, controlled workspaces, sandbox execution, filesystem tools, MCP, skills, custom instructions, shell execution, and patch tools. The important point for capOS is not the Python API. It is the shape: agents need a runtime that makes inspection, action, state, and safety explicit. capOS implication: proposals, research notes, schemas, CUE manifests, QEMU proofs, and workplan files are not just documentation. They are harness inputs. They should be versioned, concise, indexed, and mechanically checked where possible. ## Applying Harness Engineering To This Repository The capOS repository is already partially harness-engineered: it has `AGENTS.md`, `CLAUDE.md`, `WORKPLAN.md`, `REVIEW_FINDINGS.md`, proposal and research indexes, CUE manifests, named Make targets, QEMU harnesses, and generated-code checks. The missing work is making those artifacts more agent-legible, mechanically navigable, and resistant to stale planning state. The normative repository plan is [capOS Repository Harness Engineering](../proposals/capos-repo-harness-engineering-proposal.md). The checklist below is retained as research-derived input, not as a separate planning baseline. Concrete work needed: 1. **Create a repo harness map.** Add a concise `docs/agent-harness.md` that tells future agents where to find current state, design authority, task selection rules, QEMU proofs, generated-code rules, security review rules, and known stale/superseded documents. It should link, not duplicate, `CLAUDE.md`, `WORKPLAN.md`, `REVIEW.md`, `REVIEW_FINDINGS.md`, roadmap, backlog, proposals, and research. 2. **Make task selection queryable.** `WORKPLAN.md` is human-readable but not easy to query mechanically. Add stable anchors or a small structured sidecar for selected milestone, immediate gates, active branches/worktrees, paused branches, and blocked findings. The sidecar can be generated from `WORKPLAN.md` later; the first step is stable headings and consistent checkbox syntax. 3. **Add a design-status linter.** Check that proposal status, proposal index, topics, `docs/SUMMARY.md`, `WORKPLAN.md` pointers, and superseded markers agree. The repo already has mdBook metadata tooling; extend it so stale status drift becomes a failed check. 4. **Add a harness inventory for run targets.** Generate or maintain a table of `make run-*` and `make qemu-*` targets with purpose, manifest, expected proof output, and owning proposal/backlog. Agents should not infer which QEMU proof applies by grepping Makefile fragments. 5. **Standardize research notes.** Require every new external-design proposal to cite a `docs/research/*.md` note with source snapshot date, primary sources, secondary sources, design consequences, and open research gaps. This prevents proposals from becoming opaque summaries with no reusable research artifact. 6. **Add decision records for major pivots.** The project currently records pivots in `WORKPLAN.md`, proposals, and changelog. Add short ADR-style records for high-impact direction changes such as endpoint badges to service-object capabilities to session-bound invocation context. Agents need a stable "why this changed" artifact that is not buried in a long proposal. 7. **Expose schema and interface intent.** For each important Cap'n Proto interface, add or generate a short doc page with authority semantics, granted-by paths, threat model, QEMU proofs, and known gaps. This maps the core capOS rule "interface is permission" into agent-readable harness context. 8. **Make stale document detection mechanical.** Add front matter fields for `status`, `supersedes`, `superseded_by`, `implemented_by`, and `last_reviewed` where missing. Then check links both ways. An agent should be warned when it opens a superseded proposal without the replacement. 9. **Record proof transcripts as artifacts.** QEMU harnesses validate behavior, but future agents often need the exact expected proof shape. Store bounded transcript excerpts or generated proof summaries under `docs/proofs/` or a similar directory, with links from proposals and run-target inventory. 10. **Add eval tasks for agents.** Create deterministic "agent can safely edit capOS" evals: find selected milestone, choose the right backlog, identify affected docs, avoid main-worktree edits, run the right check, and update status. These evals should be runnable without model calls by using scripted fixtures where possible. 11. **Create a local knowledge compilation path.** Use the LLM Wiki pattern for capOS itself: raw sources are proposals/research/changelog/review notes; compiled pages summarize current capability model, shell path, session model, networking status, and QEMU proofs; lint finds contradictions and stale status. This should be generated into a clearly marked `docs/agent-wiki/` tree or kept out of published docs until reviewed. 12. **Keep checks close to docs.** Every process rule that matters to agents should have either a check, a generated index, or a fixture. Free-form instructions are useful but insufficient; the harness should fail when architecture or workflow invariants drift. Near-term implementation order: 1. Add `docs/agent-harness.md`. 2. Add run-target inventory. 3. Extend mdBook metadata checks for proposal status/index drift. 4. Add front matter fields for superseded/replacement relationships. 5. Add the first reviewed `docs/agent-wiki/` compilation for the selected milestone only. ## OpenClaw Harness Controls OpenClaw is the closest current personal-agent analogue: - channel ingress through chat apps, webhooks, cron, and a gateway; - a local-first gateway security boundary; - an agent runtime with a workspace as the default tool cwd; - bootstrap instruction/memory/persona files injected into context; - built-in tools for read/write/edit, exec/process, browser, web, memory, and skills; - per-agent workspace, sandbox, and tool policy; - managed browser profiles and optional real-browser/remote-CDP routing; - markdown memory plus search/index plugins. Important controls: - Exec exposes host selection (`sandbox`, gateway, node), security mode (`deny`, allowlist, full), approval prompts, timeouts, background sessions, PTY support, and restrictions on PATH/loader environment overrides. - Browser automation uses a managed Chromium profile, snapshots, screenshots, action refs, profile routing, and CDP. Arbitrary JavaScript evaluation is explicitly risky. - Memory stores markdown as source of truth. Search returns bounded snippets, file paths, and line ranges rather than entire memory files by default. - Multi-agent routing can assign different workspaces, sandboxes, and tool allow/deny lists to different agents. DeepWiki adds code-linked observations: OpenClaw treats tools as functional capabilities and skills as `SKILL.md` extensions; includes a security audit surface; supports Docker/seccomp sandboxing; and uses a personal-assistant trust model. The OpenClaw skills summary also records the failure mode of a single growing `MEMORY.md`: context overflow, compaction loss, and poor retrieval. capOS implication: copy the harness knobs, not the host authority model. Workspace, exec, browser, memory, and skills should be separate caps with auditable grants. ## Memory and Wiki Systems Karpathy's LLM Wiki pattern shifts memory from query-time retrieval over raw chunks to a maintained artifact: immutable raw sources, an LLM-maintained markdown wiki, and a schema/instruction file that defines conventions. The key operations are ingest, query, and lint. The useful artifacts are `index.md`, `log.md`, page cross-links, source citations, and health checks for stale or contradictory pages. OpenClaw memory and DeepWiki's OpenClaw skills summary point to similar requirements: - daily append-only logs versus curated long-term memory; - markdown as human-inspectable source of truth; - local indexes using SQLite, FTS/vector search, or hybrid search; - snippets and line ranges for bounded recall; - background distillation, pruning, and health checks; - optional encryption or OS keychain integration for secret-adjacent memory. capOS implication: `AgentMemory` should expose source, wiki, index, log, lint, and search subcaps. Wiki pages should carry provenance and labels. Remote embedding should be denied for high-label data. ## Schema-Guided Reasoning Abdullin's Schema-Guided Reasoning describes using structured output schemas to force reasoning through predefined steps, produce auditable intermediate state, and validate outputs. It is especially relevant for local or weaker models. capOS should use SGR for: - task intake and risk classification; - plan decomposition; - tool-call approval summaries; - source ingest and citation extraction; - code/design/security review; - final handoff and memory updates. This is harness structure, not authority. A schema can make reasoning more testable, but the runner still enforces capabilities. ## Swarm and Multi-Agent Frameworks MetaGPT encodes standard operating procedures into multi-agent workflows. Its useful lesson is artifact gating: requirements, design, implementation, test, and review phases should produce intermediate outputs that later phases can inspect. Generative Agents / Smallville contributes the memory-stream, reflection, and planning pattern for long-lived simulated agents. It is useful for NPCs, companion agents, and social simulations, but it is not an authority model. Believable behavior is not safe behavior. Gas Town focuses on durable multi-agent engineering work: roles, workers, worktrees, convoys, merge queues, attribution, and handoff. Its strongest lesson is that work must survive chat-window loss and worker recycling. AutoGen emphasizes actor-style asynchronous agent communication, distributed runtimes, tools, memory, observability, and group/team patterns. Microsoft Agent Framework adds a production framing: graph workflows, checkpointing, human-in-the-loop, durable execution, telemetry, and MCP/A2A integrations. LangGraph's durable execution docs add a specific replay rule: side effects and non-determinism need task wrappers or idempotence so resumed workflows do not repeat external writes. CrewAI and CAMEL-AI show the common high-level framework shape: agents, crews or societies, flows/workflows, memory/knowledge, toolkits, RAG, structured outputs, observability, and human-in-the-loop triggers. OpenManus, summarized by DeepWiki, is a useful "general agent" reference: a think-act loop, multi-provider LLM support, MCP integration, sandboxed code and browser automation, and multiple entry points for general tasks, MCP, and data analysis. capOS implication: implement durable `AgentTask` and `SwarmScheduler` first. Do not start with free-form inter-agent chat as the substrate. ## Interoperability Protocols MCP provides standardized tool/resource/prompt discovery and execution over JSON-RPC, with stdio and HTTP transports. It is useful for external tool ecosystems, but it is not a capability security model by itself. capOS should translate MCP descriptors into capOS tool descriptors and execute through the trusted runner. Local stdio MCP servers should run with no ambient filesystem or network authority. Remote MCP should require explicit `HttpEndpoint` and credential caps. A2A is a primary reference for peer-agent interoperability. Its project describes agent cards for discovery, negotiation of text/forms/media modalities, collaboration on long-running tasks, and operation without exposing internal state, memory, or tools. Its documented feature set includes JSON-RPC 2.0 over HTTP(S), synchronous request/response, streaming, push notifications, and exchange of text, file, and structured JSON data. capOS should translate that into a stricter local bridge. Remote agents are untrusted peers. Agent cards map to reviewed descriptors, not authority. Incoming A2A messages become `AgentMessage` events delivered through an `AgentInbox`; task ids, causal parents, size limits, expiry, and sender identity are mandatory. Artifact references require separate caps before content is read. Requested actions become proposed tool calls. Requested authority becomes an approval request. Raw capOS caps should not cross an A2A bridge. For local swarms, the same rule applies without the network protocol: agents coordinate through task records, inbox messages, resource leases, resource watches, and merge/release queues, not through free-form chat that tries to remember who is editing a repo, todo item, wiki page, or browser profile. ## Research Still Missing - Primary security advisories for OpenClaw and comparable personal-agent runtimes, especially gateway exposure, node hosts, skills, browser profiles, exec approvals, memory, and provider credentials. - MCP security beyond the happy-path spec: tool poisoning, stdio command spawning, remote auth, marketplace signing, prompt injection, and lookalike tools. - A2A security and identity: authentication, authorization, task provenance, artifact integrity, and non-transfer of authority. - Browser automation containment: CDP risk, extension relays, logged-in profiles, downloads/uploads, arbitrary JS evaluation, clipboard, screenshots, SSRF/private-network policy, and deterministic testing. - Memory correctness: citation fidelity, contradiction detection, stale summaries, label propagation, hallucinated links, human review, and rollback. - Retrieval tradeoffs: index-first wiki navigation versus vector RAG, hybrid BM25/vector search, reranking, local embeddings, snippet budgets, and remote embedding denial. - Swarm evaluation: when parallel agents improve throughput, when they create coordination debt, how to assign work, and how to prevent review capture. - Local model viability for schema-following, tool calls, memory summarization, and offline embeddings. - Provider policy: data retention, regional routing, ephemeral credentials, revocation, spend controls, and audit of remote inference. - Formal authority model: prove that model text, memory text, remote agent messages, and MCP descriptors cannot mint capOS authority.