@agent-native/core 0.56.1 → 0.58.0

package/docs/content/agent-surfaces.md

@@ -0,0 +1,273 @@
+---
+title: "Agent Surfaces"
+description: "Use Agent-Native headlessly, as rich chat, inside an existing app, or as a full agent-native application."
+search: "headless agent rich chat full app BYO agent runtime AgentChatRuntime embed actions MCP A2A HTTP CLI"
+---
+
+# Agent Surfaces
+
+Agent-Native is deliberately composable. You can use the agent without much UI,
+use the UI without the built-in agent runtime, or use both together as a full
+application.
+
+The useful way to choose is not by protocol first. Choose the product surface
+you want, then use the matching primitive.
+
+| Surface                       | Use it when                                                                                                 | Start with                                                         |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `defineAction`, HTTP, CLI, MCP, A2A                                |
+| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | `<AgentChatSurface>`, `<AssistantChat>`, `createAgentChatPlugin()` |
+| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`            |
+| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`         |
+| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                   |
+
+Those are stages, not separate products. A workflow can start as a headless
+action, appear in chat as a table or chart, and later become a full screen in an
+app without changing the operation the agent calls.
+
+## Headless agent/actions {#headless}
+
+Use the headless path when no one needs to stare at a custom app screen while
+the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
+another agent, or an existing product calling into Agent-Native.
+
+Most headless integrations should start with actions:
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+One action is then callable as:
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
+- **A2A** — from another agent-native app or agent peer
+- **UI** — through `useActionQuery`, `useActionMutation`, or `callAction`
+- **Agent tool** — from the built-in chat loop
+
+If you need the whole agent loop headlessly, use the server API from a worker,
+job, integration webhook, or custom host. This is lower-level than actions: you
+provide the engine, model, messages, actions, and event sink yourself.
+
+```ts
+import {
+  actionsToEngineTools,
+  resolveEngine,
+  runAgentLoop,
+} from "@agent-native/core/server";
+
+const engine = await resolveEngine({ engineOption: undefined });
+const model = engine.defaultModel;
+const controller = new AbortController();
+
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt: "You are the reporting agent for this workspace.",
+  actions,
+  tools: actionsToEngineTools(actions),
+  messages: [
+    {
+      role: "user",
+      content: [{ type: "text", text: "Summarize this week's forms." }],
+    },
+  ],
+  send: (event) => {
+    // Persist, log, stream, or translate AgentChatEvent objects.
+  },
+  signal: controller.signal,
+  ownerEmail: user.email,
+  orgId: user.orgId,
+});
+```
+
+For most apps, scheduled prompts and integration webhooks already call this loop
+for you. Reach for direct `runAgentLoop()` when you are building a custom
+headless host, eval runner, or server-side orchestration surface.
+
+## Rich chat on Agent-Native {#rich-chat}
+
+Use the built-in chat when the user should talk to the agent, see tool calls,
+approve work, inspect native results, and keep a durable thread history.
+
+The simplest full-page chat:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+The simplest embedded chat with your own chrome:
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+Actions can return explicit native widget results so chat output is not just
+text. Tables, charts, and typed product cards render as first-party React
+components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-ui).
+
+## Rich chat on your agent {#byo-agent}
+
+Use this path when your agent is already built with another framework or
+runtime and you want Agent-Native's chat UI around it.
+
+`AgentChatRuntime` is the boundary. Your runtime streams normalized events;
+Agent-Native renders the composer, transcript, tool calls, approvals, native
+widgets, and app layout.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:support-agent",
+  label: "Support agent",
+  endpoint: "/api/support-agent/chat",
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+Use `createOpenAIAgentsChatRuntime()`,
+`createOpenAIResponsesChatRuntime()`, `createClaudeAgentChatRuntime()`,
+`createVercelAiChatRuntime()`, or `createAgUiChatRuntime()` when your endpoint
+already streams one of those event shapes. Use `createHttpAgentChatRuntime()`
+when your agent streams Agent-Native's normalized event shape directly:
+
+```ts
+import { createOpenAIAgentsChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agent/chat",
+});
+```
+
+The endpoint can stream SSE or NDJSON events:
+
+```txt
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"I found 34 submissions."}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"formId":"form_123"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+For a trivial integration, returning `{ "text": "..." }` also works. For richer
+integrations, stream `message-*`, `tool-*`, `approval-request`, `status`,
+`artifact`, `file`, `usage`, `error`, and `done` events. Tool results can carry
+`chatUI` metadata so the same native table/chart/card renderers work with your
+agent too.
+
+This is the right place to adapt the OpenAI Agents SDK, Claude Agent SDK, Vercel
+AI SDK, Mastra, Flue, Eve, LangGraph, a custom service, or an AG-UI-compatible
+event stream. Do not use ACP as the default end-user app chat protocol; ACP is
+better framed as coding-agent/editor interoperability. Agent-Native does not
+currently claim A2UI support.
+
+## Embedded sidecar {#embedded-sidecar}
+
+Use the embedded sidecar when the main product already exists and you want an
+agent beside it.
+
+The server plugin mounts Agent-Native routes into your host app and resolves
+host identity server-side:
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+The React sidecar passes page context and host commands:
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+See [Embedding SDK](/docs/embedding-sdk) for host auth, database isolation,
+iframe/picker mode, and lower-level bridge APIs.
+
+## Full application {#full-application}
+
+Use the full app path when users need durable objects and workflows: forms,
+dashboards, calendars, inboxes, editors, documents, assets, or reports.
+
+Full apps add product UI around the same action and agent contract:
+
+- **SQL state** — app data, navigation, settings, and chat history are durable.
+- **Context awareness** — the agent knows the current route, selection, and focused object.
+- **Live sync** — agent changes update the UI, and UI changes update the agent's context.
+- **Deep links** — action results can open the right app view.
+- **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline.
+
+Start from a [template](/docs/cloneable-saas) when you want a complete app, or
+from [Starter](/docs/template-starter) when you want only the framework wiring.
+
+## How to choose {#how-to-choose}
+
+| If you are thinking...                                          | Choose                    |
+| --------------------------------------------------------------- | ------------------------- |
+| "I just need a callable tool or workflow."                      | Headless action           |
+| "I want the framework's agent, but chat should be the main UI." | Rich chat on Agent-Native |
+| "I already have an agent; I need a polished chat UI for it."    | Rich chat on your agent   |
+| "I already have a SaaS app; add an agent beside it."            | Embedded sidecar          |
+| "The agent and UI should evolve together as the product."       | Full application          |
+
+Keep the contract small: define durable operations as actions, return explicit
+widget results when chat needs rich UI, and add full screens only when users
+need to browse, compare, configure, or collaborate over persistent objects.
+
+## Related docs {#related-docs}
+
+- [Actions](/docs/actions) — define the headless operation once.
+- [Native Chat UI](/docs/native-chat-ui) — render typed action results in chat.
+- [Drop-in Agent](/docs/drop-in-agent) — mount chat, sidebar, or panel surfaces.
+- [Component API](/docs/components) — lower-level React chat/composer pieces.
+- [Embedding SDK](/docs/embedding-sdk) — add Agent-Native to an existing app.
+- [External Agents](/docs/external-agents) — connect MCP-compatible hosts to an app.
+- [A2A Protocol](/docs/a2a-protocol) — call agents from other agents.

package/docs/content/components.md

@@ -27,23 +27,31 @@ so bundlers choose the browser-safe entry.
 
 ## Agent And Chat UI {#agent-chat-ui}
 
-| API                        | Import path                                   | Use when                                                                                         |
-| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `<AgentSidebar>`           | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
-| `<AgentToggleButton>`      | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
-| `<AgentPanel>`             | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
-| `<AgentChatSurface>`       | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
-| `<AssistantChat>`          | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
-| `<MultiTabAssistantChat>`  | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
-| `createAgentChatAdapter()` | `@agent-native/core/client` or `/client/chat` | You are adapting a BYO assistant-ui transport into the Agent-Native chat runtime.                |
-| `useChatThreads()`         | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
-| `sendToAgentChat()`        | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
-
-In docs, `AgentChatRuntime` means this standard runtime posture: assistant-ui
-thread state, Agent-Native streaming, run recovery, attachments, model
-selection, approvals, native tool widgets, and SQL-backed sync. It is not a
-separate protocol replacement. BYO agents should adapt into this runtime with
-`createAgentChatAdapter()` when they want the normal app chat experience.
+| API                                  | Import path                                   | Use when                                                                                         |
+| ------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<AgentSidebar>`                     | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
+| `<AgentToggleButton>`                | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
+| `<AgentPanel>`                       | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
+| `<AgentChatSurface>`                 | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
+| `<AssistantChat>`                    | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
+| `<MultiTabAssistantChat>`            | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
+| `createHttpAgentChatRuntime()`       | `@agent-native/core/client` or `/client/chat` | You have a BYO agent endpoint that streams normalized chat events.                               |
+| `createOpenAIAgentsChatRuntime()`    | `@agent-native/core/client` or `/client/chat` | You have an OpenAI Agents SDK stream and want the standard chat UI around it.                    |
+| `createOpenAIResponsesChatRuntime()` | `@agent-native/core/client` or `/client/chat` | You have an OpenAI Responses event stream and want it normalized into the chat UI.               |
+| `createAgUiChatRuntime()`            | `@agent-native/core/client` or `/client/chat` | You have an AG-UI event stream and want it normalized into the chat UI.                          |
+| `createClaudeAgentChatRuntime()`     | `@agent-native/core/client` or `/client/chat` | You have a Claude Agent SDK stream and want it normalized into the chat UI.                      |
+| `createVercelAiChatRuntime()`        | `@agent-native/core/client` or `/client/chat` | You have a Vercel AI SDK stream and want it normalized into the chat UI.                         |
+| `createAgentChatRuntimeAdapter()`    | `@agent-native/core/client` or `/client/chat` | You need to adapt an `AgentChatRuntime` into assistant-ui yourself.                              |
+| `createAgentChatAdapter()`           | `@agent-native/core/client` or `/client/chat` | You need the built-in Agent-Native SSE transport as a low-level assistant-ui adapter.            |
+| `useChatThreads()`                   | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
+| `sendToAgentChat()`                  | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
+
+`AgentChatRuntime` is the BYO-agent contract for the standard chat shell. Pass
+`runtime` to `<AssistantChat>` when an external agent should power the
+conversation while Agent-Native keeps the composer, transcript, tool cards, and
+native widget rendering. If you are choosing between headless actions, rich
+chat, embedded sidecar, and full app shapes, see
+[Agent Surfaces](/docs/agent-surfaces).
 
 The shortest custom route is still a pre-wired surface:
 
@@ -77,6 +85,27 @@ function CustomChat({ projectSlug }: { projectSlug: string }) {
 }
 ```
 
+For a bring-your-own agent endpoint:
+
+```tsx
+import {
+  AssistantChat,
+  createOpenAIAgentsChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/my-agent/chat",
+  label: "My agent",
+});
+
+export function MyAgentChat() {
+  return <AssistantChat runtime={runtime} />;
+}
+```
+
+Use `createHttpAgentChatRuntime()` instead when your endpoint already emits
+Agent-Native normalized events.
+
 ## Chat Field And Composer {#composer}
 
 Use `@agent-native/core/client/composer` when you need to place the same chat

package/docs/content/drop-in-agent.md

@@ -184,20 +184,25 @@ framework own the agent runtime:
 - **`@agent-native/core/client/conversation`** — use this for transcript
   rendering without the full chat runtime.
 - **`createAgentChatAdapter()`** — use this only when building a custom
-  assistant-ui transport for the standard Agent-Native chat runtime. It
+  assistant-ui transport for the built-in Agent-Native chat endpoint. It
   connects to the same `/_agent-native/agent-chat` stream and preserves
   run-manager recovery, attachments, model selection, native widgets, and
   thread metadata.
+- **`createHttpAgentChatRuntime()`** — use this when a BYO agent exposes a
+  POST endpoint that streams `AgentChatRuntime` events. Pass the runtime to
+  `<AssistantChat runtime={runtime} />`.
 
 Avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
 lower-level helper is missing for a real custom surface, add that named helper
 first so client code does not learn a second, ad hoc transport.
 
 For BYO agent runtimes, keep actions and SQL-backed app state as the contract.
-Adapt the runtime into `<AssistantChat createAdapter={...} />` when you want
-Agent-Native chat behavior, or use `PromptComposer` by itself only when the
-external runtime owns the transcript and loop. See
-[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).
+Adapt the runtime into `<AssistantChat runtime={...} />` when you want
+Agent-Native chat behavior. Use `<AssistantChat createAdapter={...} />` only
+for lower-level assistant-ui transports, or `PromptComposer` by itself only
+when the external runtime owns the transcript and loop. See
+[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) and
+[Agent Surfaces](/docs/agent-surfaces#byo-agent).
 
 ### Build your own sidebar from pieces {#build-your-own-sidebar}
 

package/docs/content/embedding-sdk.md

@@ -29,6 +29,10 @@ pnpm add @agent-native/core
 
 ## Choosing a mode {#choosing-a-mode}
 
+This page is for embedding Agent-Native into an existing product. If you are
+still deciding between headless actions, rich chat, an embedded sidecar, or a
+full app, start with [Agent Surfaces](/docs/agent-surfaces).
+
 | Mode                                 | Use it when                                                                                         | Package                                                  |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | **EmbeddedApp picker**               | Launching a full Agent-Native app as a focused iframe (asset picker, form builder, approval panel). | `@agent-native/embedding`                                |

package/docs/content/external-agents.md

@@ -13,6 +13,7 @@ The external-agent bridge closes the loop. First you connect your own agent to a
 ## Which agent path do you need? {#which-agent-path}
 
 - **External MCP host:** use this page when Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP-compatible host should call your hosted agent-native app.
+- **Your own runtime behind Agent-Native chat:** see [Agent Surfaces](/docs/agent-surfaces#byo-agent) and [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) when an agent built with another framework should power `<AssistantChat runtime={...}>`.
 - **Your app consuming MCP tools:** see [MCP Clients](/docs/mcp-clients) when an agent-native app needs to call tools exposed by another MCP server.
 - **Another app or agent via A2A:** use [Agent Mentions](/docs/agent-mentions) and [A2A](/docs/a2a-protocol) when agent-native apps should discover and delegate to each other.
 - **Local custom sub-agents:** use [Workspace](/docs/workspace) when you want custom agent profiles inside the agent-native workspace itself.

package/docs/content/getting-started.md

@@ -13,6 +13,7 @@ Start with the path that matches what you want to do next:
 
 - **Use a starter app.** Browse the [template gallery](/templates). Hosted apps already include sign-in, data, and the agent sidebar. No install required.
 - **Build or customize your own app.** Continue with [Create a local app](#create-your-app). You'll scaffold a template, run it locally, then change the code, brand, data model, and integrations.
+- **Choose headless, chat, embedded, or full app.** Use [Agent Surfaces](/docs/agent-surfaces) when you know the workflow but not how much UI belongs around it.
 - **Add agent-native skills to a code tool.** Jump to [Try it with a skill](#try-with-a-skill) to add Plans or PR Recaps to Claude Code, Codex, or Cursor without scaffolding an app.
 - **Connect an external agent to an app.** Use [External Agents](/docs/external-agents) to connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host to an existing app.
 
@@ -122,6 +123,7 @@ Once your app is running, the usual next step is small and concrete:
 Useful follow-up docs:
 
 - [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions, polling sync, and context awareness
+- [Agent Surfaces](/docs/agent-surfaces) for choosing headless, rich chat, embedded sidecar, or full app
 - [Workspace](/docs/workspace) for instructions, skills, memory, and per-user MCP connections
 - [Messaging](/docs/messaging) for Slack, email, Telegram, and other ways to reach the agent
 - [FAQ](/docs/faq) for setup and product questions

package/docs/content/harness-agents.md

@@ -0,0 +1,232 @@
+---
+title: "Harness Agents"
+description: "Run Claude Code, Codex, Pi, and other full coding harnesses as embedded agents inside Agent-Native, with their own loop, sandbox, native tools, and resumable SQL-backed sessions."
+search: "harness agents AgentHarness ai-sdk HarnessAgent Claude Code Codex Pi Cursor Mastra embedded coding agent resolveAgentHarness startAgentHarnessRun resumable session sandbox host tools"
+---
+
+# Harness Agents
+
+A harness agent is a full agent runtime — Claude Code, Codex, Pi, and similar —
+that owns its own loop, workspace, native file tools, session state, compaction,
+approval model, and sandbox behavior. Agent-Native runs these through the
+**`AgentHarness`** substrate in `@agent-native/core/agent/harness`, streams their
+events into the normal transcript, and persists their native session so a thread
+can pause and resume.
+
+This is different from the built-in chat agent and from bringing your own chat
+runtime. The built-in agent and `AgentEngine` are for one model round trip
+beneath `runAgentLoop`. A harness is not an `AgentEngine` provider — it runs its
+own loop end to end, so Agent-Native drives it as a session, not as a single
+model call.
+
+| You want to…                                                               | Use                                                           |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | **Harness agents** (this page)                                |
+| Put an agent you built elsewhere behind Agent-Native's **chat UI**         | [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes) |
+| Let an external MCP host (Claude Code, Cursor, …) **call into your app**   | [External Agents](/docs/external-agents)                      |
+| Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui)                  |
+| Spawn background / sub-agent runs and teams                                | [Custom Agents & Teams](/docs/agent-teams)                    |
+
+## Built-in harnesses {#built-in}
+
+`registerBuiltinAgentHarnesses()` registers three adapters backed by the AI SDK
+`HarnessAgent`:
+
+| Name                         | Runtime     | Sandbox | Approvals |
+| ---------------------------- | ----------- | ------- | --------- |
+| `ai-sdk-harness:claude-code` | Claude Code | yes     | yes       |
+| `ai-sdk-harness:codex`       | Codex       | yes     | no        |
+| `ai-sdk-harness:pi`          | Pi          | no      | yes       |
+
+Their runtime packages are **optional peer dependencies** and load lazily, so an
+app that never uses a harness does not pay for it. Each adapter carries an
+`installPackage` hint (for example `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` throws a clear install
+error if the packages are missing, and `isAgentHarnessPackageInstalled(entry)`
+lets you check first.
+
+## Register and resolve {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` returns an `AgentHarnessAdapter`. The
+optional `config` is forwarded to the adapter factory — for the AI SDK adapters
+that maps to `AiSdkHarnessAdapterOptions` (`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions`). Use `listAgentHarnesses()`
+to enumerate what is registered for a picker.
+
+## Run a turn {#run-a-turn}
+
+`startAgentHarnessRun` bridges a harness session into the shared run-manager
+lifecycle. It creates (or reuses) the native session, persists it, streams the
+turn, translates each harness event into transcript events, and detaches the
+resumable state when the turn completes.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` returns the `ActiveRun` from the run-manager, so the turn
+shows up through the existing run routes, transcript, and cancellation just like
+any other agent run. Pass an already-created `session` instead of `createSession`
+to continue a session you are holding in memory.
+
+## Sessions and resume {#sessions}
+
+A harness owns long-lived native session state. Agent-Native persists it in SQL
+so a thread can survive across turns, processes, and deploys. The `resumeState`
+is **opaque** — Agent-Native stores it and hands it back, but never inspects or
+interprets it.
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+The store also exposes `saveAgentHarnessSession`, `updateAgentHarnessSession`,
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped`, and `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` calls the save/update/stop paths for you; reach for them
+directly only in a custom host.
+
+## Host tools and permissions {#host-tools}
+
+A harness brings its own native tools (read, edit, write, shell, and so on), so
+you do **not** re-expose file editing as host tools. Pass only a **narrow,
+intentional set** of Agent-Native actions through `createSession.tools` when you
+want the harness to reach specific app operations — and keep `defineAction`
+auth, request context, timeouts, truncation, and read-only metadata intact when
+you do.
+
+`permissionMode` gates what the harness may do without approval:
+
+| Mode          | Meaning                                            |
+| ------------- | -------------------------------------------------- |
+| `allow-reads` | Default. Reads run; edits and risky actions prompt |
+| `allow-edits` | Reads and edits run; other risky actions prompt    |
+| `allow-all`   | No approval gating                                 |
+
+When a harness pauses for approval it emits an `approval-request` event and the
+session is marked `idle` with the pending approval recorded, so the UI can
+surface it and resume on the user's decision. See
+[Human Approval](/docs/human-approval) for the approval surface.
+
+## Events {#events}
+
+A harness session streams `AgentHarnessEvent` values, which Agent-Native
+translates to the standard `AgentChatEvent` stream with
+`agentHarnessEventToAgentChatEvents`. The event union covers `text-delta`,
+`thinking-delta`, `activity`, `tool-start`, `tool-done` (which can carry an
+`mcpApp` payload for native widgets), `approval-request`, `file-change`,
+`compaction`, `usage`, `error`, and `done`. Because tool results flow through the
+same translation, action-declared native widgets still render — see
+[Native Chat UI](/docs/native-chat-ui).
+
+## Background runs and the UI {#background-runs}
+
+Harness runs project into the shared `BackgroundAgentRun` shape with
+`createAgentHarnessBackgroundAgentController()` and are available through the
+existing run routes as `goalId=agent-harness`. That means a long-running Claude
+Code or Codex session appears in the same background-run and transcript surfaces
+as Agent Teams and other adapters, with `listAgentHarnessBackgroundRuns`,
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun`, and
+`stopAgentHarnessBackgroundRun` available for custom hosts.
+
+## Custom adapters {#custom-adapters}
+
+To wrap a runtime that is not one of the built-ins, implement
+`AgentHarnessAdapter` and register it. The adapter declares its capabilities and
+creates sessions; a session exposes `streamTurn` and optional `continueTurn`,
+`approve`, `detach`, `stop`, and `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+Keep the runtime package optional with a dynamic import in `createSession` and an
+`installPackage` hint. For bridge-backed coding harnesses, require a real
+sandbox/workspace provider rather than running an arbitrary coding agent in the
+host process — see [Sandbox Adapters](/docs/sandbox-adapters). The AI SDK adapter
+(`createAiSdkHarnessAdapter`, backed by `HarnessAgent` from `@ai-sdk/harness`) is
+one implementation of this contract, not the public abstraction.
+
+## Don't {#donts}
+
+- Don't add Claude Code, Codex, Cursor, Mastra, or Pi as an `AgentEngine`. They
+  own their loop; running one under `AgentEngine.stream()` double-runs the loop
+  and loses session lifecycle semantics.
+- Don't replay full Agent-Native chat history into a harness each turn. Resume
+  the harness session with its `resumeState` instead.
+- Don't store `resumeState` in `application_state`. It belongs in the harness
+  session SQL table.
+- Don't expose every app action to every harness session by default. Hand it a
+  small, intentional tool set.
+
+## Related docs {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — put your own agent behind the chat UI with `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces) — choose headless, chat, sidecar, or full-app.
+- [Agent-Native Code UI](/docs/code-agents-ui) — the reusable coding workspace surface.
+- [Custom Agents & Teams](/docs/agent-teams) — background runs and sub-agent delegation.
+- [Sandbox Adapters](/docs/sandbox-adapters) — pluggable execution backends for coding harnesses.
+- [Human Approval](/docs/human-approval) — the approval surface harness runs use.