harness-agents

# Harness Agents ## Rule Full agent harnesses are not `AgentEngine` providers. Use the `AgentHarness` substrate in `@agent-native/core/agent/harness`. ## Why `AgentEngine` is for one model round trip beneath `runAgentLoop`. Harnesses like Claude Code, Codex, Pi, Cursor, and Mastra own their own loop, workspace, native tools, session state, compaction, approval model, and sandbox behavior. Putting a harness under `AgentEngine.stream()` double-runs the loop and loses session lifecycle semantics. ## How 1. Register or resolve a harness adapter. ```ts import { registerBuiltinAgentHarnesses, resolveAgentHarness, } from "@agent-native/core/agent/harness"; registerBuiltinAgentHarnesses(); const harness = resolveAgentHarness("ai-sdk-harness:codex"); ``` 2. Start a turn through the run-manager bridge. ```ts import { startAgentHarnessRun } from "@agent-native/core/agent/harness"; startAgentHarnessRun({ runId, threadId, adapter: harness, input: { prompt }, createSession: { sessionId, resumeState, instructions, sandbox, permissionMode: "allow-reads", }, ownerEmail, orgId, }); ``` 3. Persist native session state in SQL. Use `saveAgentHarnessSession`, `updateAgentHarnessSession`, and `getLatestAgentHarnessSessionForThread`. The `resumeState` is opaque; Agent Native stores it but does not inspect it. 4. Surface runs through background agents. Harness runs are projected into the shared `BackgroundAgentRun` shape with `createAgentHarnessBackgroundAgentController()` and are available through the existing run routes as `goalId=agent-harness`. ## ACP Agents Agent-Native can act as an [ACP](https://agentclientprotocol.com) (Agent Client Protocol) client and drive a local coding agent — Gemini CLI, Claude Code, or any ACP-compliant agent — through this same substrate. This is scoped to **local coding**: the agent is spawned as a child process speaking newline-delimited JSON-RPC over stdio, and inherits the parent environment so it reuses the user's local CLI login. It is not a hosted/sandboxed transport, and it is not a chat/A2A transport. ```ts import { registerBuiltinAgentHarnesses, resolveAgentHarness, } from "@agent-native/core/agent/harness"; registerBuiltinAgentHarnesses(); // Built-in presets (commands overridable via the resolve config): const gemini = resolveAgentHarness("acp:gemini"); const claude = resolveAgentHarness("acp:claude-code"); // Or any ACP agent by command: const custom = resolveAgentHarness("acp", { command: "gemini", args: ["--experimental-acp"], }); ``` - The protocol transport (`@zed-industries/agent-client-protocol`) is an optional dependency loaded lazily; `installPackage` surfaces a clear install hint. - The agent binary (e.g. `@google/gemini-cli`, `@zed-industries/claude-code-acp`) is a separate external CLI the user installs; presets launch it through `npx` by default and the command/args are overridable because agent ACP entry flags still evolve. - `permissionMode` maps onto ACP `session/request_permission` using the reported tool-call kind: reads always run, edits run under `allow-edits`, everything risky prompts unless `allow-all`. Approvals surface as `approval-request` events; answer them through the harness session's `approve()`. - `resumeState` carries the ACP `sessionId`; resume works when the agent advertises the `loadSession` capability and degrades to a fresh session otherwise. - `fs/read_text_file` and `fs/write_text_file` are served against the session workspace and refuse paths that escape it; terminal methods are not advertised (the agent uses its own shell). ## Adapter Guidance - Keep harness packages optional. Use dynamic imports in adapters and expose an install hint through `installPackage`. - Use the AI SDK harness adapter as one implementation, not as Agent-Native's public abstraction. - For bridge-backed coding harnesses, require a real sandbox/workspace provider. Do not run arbitrary coding agents in the host process by default. - Pass only a narrow, intentional set of Agent-Native actions as host tools. Preserve `defineAction` auth, request context, timeouts, truncation, and read-only metadata. ## Code Execution Sandbox - The `run-code` tool executes through a pluggable `SandboxAdapter` (`packages/core/src/coding-tools/sandbox/`). The default `LocalChildProcessAdapter` spawns a locked-down local Node child process; swap it via `AGENT_NATIVE_SANDBOX` or `registerSandboxAdapter()` for a Docker/remote backend. An adapter only runs the already-prepared, non-secret module source — it never sees app secrets. See the Sandbox Adapters doc; `agent-native add sandbox docker` emits a full Docker-adapter recipe. - Long compute exceeds the hosted ~40s run ceiling via the built-in durable background backend: per-call `background: true` on `run-code` (or `AGENT_NATIVE_SANDBOX=background` to queue every call) enqueues to the `sandbox_executions` table and executes out-of-band — self-dispatched to `/_agent-native/sandbox/_process-execution` on serverless, in-process on long-lived Node — with lease-based claiming, retries, and owner-scoped polling via `run-code {executionId}` / `get-code-execution`. ## Sub-Agent Delegation Depth - Sub-agent spawning is capped server-side (default depth `2`) so delegation chains can't fan out indefinitely. Override at deploy time with `AGENT_NATIVE_MAX_SUBAGENT_DEPTH` (`0` disables sub-agents; clamped to `16`). Enforcement is ambient via `evaluateSubagentDepth` in `packages/core/src/server/agent-teams.ts` — independent of any tool-level guard. See the Agent Teams doc for the depth model. ## Don't - Don't add Claude Code, Codex, Cursor, Mastra, or Pi as an `AgentEngine`. - Don't replay full Agent-Native chat history into a native harness each turn. Resume the harness session instead. - Don't store resume state in `application_state`; it belongs in the harness session SQL table. - Don't expose every app action to every harness session by default. ## Related Skills - `adding-a-feature` — feature parity across UI/actions/instructions/state. - `delegate-to-agent` — background agents use run-manager infrastructure. - `external-agents` — expose openable resources and external-agent surfaces. - `storing-data` — durable SQL state and additive schema changes.