@agent-native/core 0.65.0 → 0.66.1

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/docs/content/key-concepts.md

@@ -26,6 +26,33 @@ Every agent-native app is three things working together:
 
 Headless apps can run the same production app-agent loop from the folder with `pnpm agent`, while UI apps mount the embedded agent panel and run locally with `pnpm dev`. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
 
+## Agent building blocks {#agent-building-blocks}
+
+Every agent-native app has the same agent building blocks, regardless of whether
+the product surface is headless, chat-first, or a full UI:
+
+```an-file-tree title="Guidance and behavior"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, core rules, state keys, action index, skills index" },
+    { "path": ".agents/skills/<name>/SKILL.md", "note": "reusable behavior: workflow steps, policies, examples, references, and do/don't lists" },
+    { "path": "actions/<name>.ts", "note": "executable capability: typed operation exposed to the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks" }
+  ]
+}
+```
+
+| Building block   | Use it for                                                                                          | Loaded when                                           |
+| ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Instructions** | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes  | Every turn                                            |
+| **Skills**       | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output  | On demand when the skill description matches the task |
+| **Actions**      | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called |
+
+Skills and actions work together. A skill teaches the agent how to do a class of
+work; an action is the code path it can call while doing that work. For example,
+a `customer-research` skill might tell the agent which sources to inspect and
+how to summarize evidence, while `search-crm` and `create-brief` actions fetch
+and write the actual data.
+
 Six rules govern the architecture:
 
 1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM

package/docs/content/writing-agent-instructions.md

@@ -114,6 +114,26 @@ defineAction({
 });
 ```
 
+## Skills vs actions {#skills-vs-actions}
+
+Skills and actions are complementary. A skill is guidance the agent reads; an
+action is code the agent can run.
+
+| Need                                                                   | Use                                |
+| ---------------------------------------------------------------------- | ---------------------------------- |
+| The agent needs to follow a workflow, policy, checklist, or rubric     | **Skill**                          |
+| The agent needs examples, reference material, or domain-specific rules | **Skill**                          |
+| The agent needs to read or write app data                              | **Action**                         |
+| The agent needs to call an external API or perform an approval         | **Action**                         |
+| The agent calls the right operation but in the wrong way               | Improve the **skill**              |
+| The agent cannot reliably invoke the operation                         | Improve the **action**             |
+| The agent chooses the wrong tool                                       | Improve the **action description** |
+
+Most real features use both: the skill explains how to approach the task, and
+the action provides the typed operation. For example, an `invoice-review` skill
+can explain the review policy and escalation rules, while `list-invoices`,
+`flag-invoice`, and `approve-invoice` actions do the actual reads and writes.
+
 ## Bake in anti-fabrication and verify-before-done {#anti-fabrication}
 
 App instructions should make honesty and verification the default behavior:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.65.0",
+  "version": "0.66.1",
   "type": "module",
   "engines": {
     "node": ">=22"

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