@agent-native/core 0.64.1 → 0.66.0

package/dist/templates/workspace-core/.agents/skills/harness-agents/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: harness-agents
 description: >-
-  Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, or Mastra inside Agent Native.
+  Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, Mastra, or ACP agents inside Agent Native.
 scope: dev
 ---
 
@@ -68,6 +68,52 @@ 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

package/docs/content/agent-surfaces.md

@@ -295,8 +295,10 @@ export function SupportAgentChat() {
 Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude
 Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above
 for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is
-not the default end-user app chat protocol, and Agent-Native does not currently
-claim A2UI support.
+not the end-user app chat or A2A transport, and Agent-Native does not currently
+claim A2UI support. ACP is supported in one specific place — driving a local
+coding agent (Gemini CLI, Claude Code, …) through the
+[harness layer](/docs/harness-agents#acp), not as the chat runtime here.
 
 [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
 is the canonical home for the event shapes, the runtime helpers, and `chatUI`

package/docs/content/harness-agents.md

@@ -62,6 +62,65 @@ app that never uses a harness does not pay for it. Each adapter carries an
 error if the packages are missing, and `isAgentHarnessPackageInstalled(entry)`
 lets you check first.
 
+`registerBuiltinAgentHarnesses()` also registers the [ACP](#acp) harnesses
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## ACP agents {#acp}
+
+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. The agent runs as a
+local subprocess that speaks newline-delimited JSON-RPC over stdio; ACP's editor
+↔ agent model is exactly this shape.
+
+This adapter is scoped to **local coding**. The child process inherits the
+parent environment, so the agent reuses whatever local CLI login it already has
+(for example `gemini` or `claude` auth in the user's home dir). It is not a
+hosted or sandboxed transport, and it is not a chat/A2A transport — for those,
+see [Agent Surfaces](/docs/agent-surfaces).
+
+| Name              | Default command                                | Resumable\* |
+| ----------------- | ---------------------------------------------- | ----------- |
+| `acp`             | _(supply `command`/`args` via config)_         | yes         |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | yes         |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | yes         |
+
+\*Resume works when the agent advertises the `loadSession` capability and
+degrades to a fresh session otherwise.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// 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 through the `installPackage` hint, just like the AI SDK
+harnesses. The agent binary itself (`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`, …) is a separate external CLI; the presets
+launch it through `npx` and the command/args stay overridable because agent ACP
+entry flags still evolve.
+
+`permissionMode` maps onto ACP `session/request_permission` using the tool-call
+kind the agent reports: reads always run, edits run under `allow-edits`, and
+everything risky prompts unless `allow-all`. Approvals surface as the normal
+`approval-request` events. The adapter serves `fs/read_text_file` and
+`fs/write_text_file` against the session workspace (refusing paths that escape
+it) and writes emit `file-change` events; terminal methods are not advertised,
+so the agent uses its own shell.
+
 ## Codex auth: Code UI vs harness sandboxes {#codex-auth}
 
 There are two Codex surfaces, and they authenticate differently:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.64.1",
+  "version": "0.66.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -116,6 +116,11 @@
     "./router": "./dist/router/index.js",
     "./collab": "./dist/collab/index.js",
     "./a2a": "./dist/a2a/index.js",
+    "./embedding": "./dist/embedding/index.js",
+    "./embedding/react": "./dist/embedding/react.js",
+    "./embedding/bridge": "./dist/embedding/bridge.js",
+    "./embedding/agent": "./dist/embedding/agent.js",
+    "./embedding/protocol": "./dist/embedding/protocol.js",
     "./mcp": "./dist/mcp/index.js",
     "./mcp-client": "./dist/mcp-client/index.js",
     "./tracking": "./dist/tracking/index.js",

package/src/templates/workspace-core/.agents/skills/harness-agents/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: harness-agents
 description: >-
-  Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, or Mastra inside Agent Native.
+  Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, Mastra, or ACP agents inside Agent Native.
 scope: dev
 ---
 
@@ -68,6 +68,52 @@ 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