@agent-native/core 0.18.1 → 0.19.1

package/docs/content/external-agents.md

@@ -1,56 +1,90 @@
 ---
 title: "External Agents"
-description: "Connect Claude Code, Cowork, and Codex to an agent-native app over MCP — with deep links that drop the user back into the running UI and live artifact round-trip."
+description: "Connect your own Claude Code, Cowork, or Codex to a hosted agent-native app in one command — then round-trip artifacts back into the running UI with deep links."
 ---
 
 # External Agents
 
 An agent-native app is reachable by any external coding agent — Claude Code (desktop & CLI), Claude Cowork, Codex — over [MCP](/docs/mcp-protocol). External agents are great at producing artifacts (a draft, an event, a dashboard) but they live in a terminal or another app. Without a bridge, the user gets a wall of JSON and has to go find the thing.
 
-The external-agent bridge closes the loop: the agent does the work over MCP, then hands the user a single **"Open in <app> →"** link that opens the real app focused on exactly what was produced. It reuses the existing `navigate` / `application_state` contract the UI already drains every 2s (see [Context Awareness](/docs/context-awareness)) — there is no second navigation mechanism.
+The external-agent bridge closes the loop. First you connect your own agent to a **hosted** app — one command, no token copying. Then the agent does the work over MCP and hands the user a single **"Open in <app> →"** link that opens the real app focused on exactly what was produced. It reuses the existing `navigate` / `application_state` contract the UI already drains every 2s (see [Context Awareness](/docs/context-awareness)) — there is no second navigation mechanism.
 
-## Overview {#overview}
+## Connect in one command {#connect}
 
-- **One-command setup** — `agent-native mcp install --client <c>` writes the client config and provisions a token.
-- **`link` builder** — any action that produces or lists a navigable resource returns a deep link; MCP/A2A surfaces auto-append an "Open in … →" link.
-- **`/_agent-native/open` route** — a pure pointer (view + record ids + filters); the record-focusing write is always scoped to the **browser session**, never the agent's token.
-- **Ingest actions** — GET + `readOnly` + `publicAgent` actions let an external agent pull **live** app state into its own context.
-- **Generic cross-app verbs** — a stable verb set (`list_apps`, `open_app`, `ask_app`, `create_workspace_app`, `list_templates`) so an external agent has a predictable surface without guessing per-app action names.
+The first-party hosted apps live at `mail.agent-native.com`, `calendar.agent-native.com`, `analytics.agent-native.com`, and so on. To wire your own Claude Code (and Codex / Cowork if detected) to one of them:
 
-## Connect an external agent {#connect}
-
-The framework already mounts an HTTP MCP endpoint at `/_agent-native/mcp` (see [MCP Protocol](/docs/mcp-protocol)). Every `defineAction` is exposed as an MCP tool, plus the `ask-agent` meta-tool that runs the full agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). Hosted apps point an external agent at that URL with a bearer token (`ACCESS_TOKEN`, or an `A2A_SECRET` JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped).
+```bash
+npx @agent-native/core connect https://mail.agent-native.com
+```
 
-For local Claude Code / Codex / Cowork, one command writes the client config:
+This opens your browser at the app. You are already logged in, so you just click **Authorize** once. The command detects every installed agent client and writes the MCP config for each — no token to copy, no local server to run. Connect every first-party hosted app at once with:
 
 ```bash
-agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
-  [--app <id>] [--scope user|project]
+npx @agent-native/core connect --all
 ```
 
-It provisions a token (a random `ACCESS_TOKEN` into the workspace `.env` for local dev, or a signed JWT for a detected hosted deployment) and writes an idempotent stdio server entry:
+The connection is **per-user, scoped, and revocable**. The browser session you authorized with is the identity the agent acts as; nothing exposes the deployment's shared secret.
 
-- **claude-code / claude-code-cli** — an `mcpServers` entry in `.mcp.json` (project scope, default) or `~/.claude.json` (`--scope user`).
-- **cowork** — the same Claude Code JSON shape in `~/.cowork/mcp.json`.
-- **codex** — an `[mcp_servers.<name>]` block in `~/.codex/config.toml`.
+### No-CLI alternative {#no-cli}
 
-The entry runs `agent-native mcp serve --app <id>`, which by default is a **thin stdio proxy** to the running local app's `/_agent-native/mcp` — so the live action registry, HMR, and correct deep links stay the single source of truth. Pass `--standalone` to build the registry in-process instead. When `agent-native mcp install` detects a hosted origin (a non-localhost `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` in the workspace `.env`), it writes an `http` client entry pointing at `<origin>/_agent-native/mcp` with a `Bearer` JWT instead of a stdio entry.
+If you'd rather not run a command, open the app in your browser and use its **Connect** affordance (served at `https://<app>/_agent-native/mcp/connect`). While logged in, click **Connect / Authorize**. The page hands you either a one-click deep link that configures a detected agent, or a ready-to-paste `.mcp.json` block:
 
-Companion subcommands:
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "url",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
 
-| Command                                   | What it does                                                        |
-| ----------------------------------------- | ------------------------------------------------------------------- |
-| `agent-native mcp serve [--app <id>]`     | Run the MCP stdio transport (what client configs spawn).            |
-| `agent-native mcp install --client <c>`   | Provision a token + write the client's MCP config (idempotent).     |
-| `agent-native mcp uninstall --client <c>` | Remove the named MCP entry from a client's config (idempotent).     |
-| `agent-native mcp status`                 | Show resolved MCP URL/port, token state, and per-client entries.    |
-| `agent-native mcp token [--rotate]`       | Print (or rotate) the local `ACCESS_TOKEN` in the workspace `.env`. |
+Restart the agent client after connecting so it picks up the new MCP server.
 
-Restart the client after `install` so it picks up the new MCP server.
+## What you can do once connected {#what-you-can-do}
+
+Once your agent is connected, the app's full action surface is available as MCP tools, plus the `ask-agent` meta-tool that runs the full agent loop (the same entry point [A2A](/docs/a2a-protocol) uses). Ask your agent to do real work and it hands back a link straight into the running app:
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…")
+→ Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=…
+```
+
+Click that link and Mail opens with the draft restored — focused exactly where you, the logged-in user, are. The agent never had to know your session; it just produced the artifact.
+
+### Generic cross-app verbs {#cross-app}
+
+On top of the per-action tools the MCP server exposes a stable verb set, so an external agent has a predictable surface without guessing per-app action names:
+
+| Tool                                       | Side effects | Returns                                                                              |
+| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
+| `list_apps`                                | none         | workspace apps + their URLs / running state                                          |
+| `open_app({ app, view, params? })`         | none         | a `buildDeepLink` URL (surfaces as an "Open …" link)                                 |
+| `ask_app({ app, message })`                | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`) |
+| `create_workspace_app({ name, template })` | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link            |
+| `list_templates`                           | none         | the allow-listed templates only                                                      |
+
+`create_workspace_app` rejects any non-allow-listed template — the public template allow-list in `packages/shared-app-config/templates.ts` is authoritative and CI-guarded; an external agent cannot widen it. A same-named template action overrides a builtin (template-over-core precedence). Disable the whole set with `MCPConfig.builtinCrossAppTools: false`.
+
+### Per-app tour {#tour}
+
+Every allow-listed template that produces or lists a navigable resource ships a `link` builder, and the ingest-heavy ones ship a GET + `publicAgent` action so a connected agent can pull live state:
+
+- **Mail** — `manage-draft` returns a `compose`-encoded deep link; clicking it opens the inbox with the draft restored into a `compose-<id>`. `list-emails` / `search-emails` point at a filtered inbox view.
+- **Calendar** — `create-event` returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
+- **Analytics** — `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; the agent builds a dashboard over MCP and hands back "Open dashboard in Analytics".
+- **Design** — `get-design-snapshot` is the GET + `publicAgent` ingest action: it returns the **live** Yjs file contents plus the resolved tweak values so the agent continues from the tuned design, not the original tokens. `apply-tweaks` round-trips back with an "Open design" editor link.
+- **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
+- **Brain** — `ask-brain` / `search-everything` return a cited answer plus a deep link to the underlying knowledge/capture, so a terminal agent's lookup links straight back into the source in the running app.
 
-## The `link` builder {#link-builder}
+## Authoring: the `link` builder {#link-builder}
 
-`defineAction` accepts an optional `link` builder. When set, every MCP/A2A result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and a structured `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
+This section is for template authors. `defineAction` accepts an optional `link` builder. When set, every MCP/A2A result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and a structured `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
 
 Build the URL with `buildDeepLink(...)` — it is the single source of truth for the open-route format. Never hand-format the `/_agent-native/open` URL.
 
@@ -91,7 +125,7 @@ The `link` builder is **pure and synchronous — no I/O, no awaits**. It runs be
 
 `buildDeepLink({ app, view, params?, to?, compose? })` returns the app-relative path `/_agent-native/open?app=…&view=…&<recordId>=…`. The MCP layer turns that into an absolute web URL (`toAbsoluteOpenUrl`, using the request origin) and a desktop `agentnative://open?…` URL (`toDesktopOpenUrl`); the markdown link uses the desktop URL when the client signals `target: "desktop"`.
 
-## The `/_agent-native/open` route {#open-route}
+### The `/_agent-native/open` route {#open-route}
 
 When the user clicks the link in any browser or inline webview, `GET /_agent-native/open` (`createOpenRouteHandler`, mounted by the core routes plugin):
 
@@ -102,11 +136,11 @@ When the user clicks the link in any browser or inline webview, `GET /_agent-nat
 
 Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard). The route can be disabled per app via `disableOpenRoute`.
 
-### The browser-session identity rule {#identity-rule}
+#### The browser-session identity rule {#identity-rule}
 
 The link carries **no privileged state** — it is just `view` + record ids + filters. The record-focusing `navigate` write is scoped to whoever is logged into the **browser**, never the external agent's MCP token. So an agent authenticated as one identity can hand a user a link, and when that user clicks it the record opens where _the user_ is logged in. This is what makes the deep link safe to surface in a terminal or chat transcript. See [Context Awareness](/docs/context-awareness) for the `navigate` / `application_state` contract this bridges to.
 
-## Ingest actions {#ingest}
+### Ingest actions {#ingest}
 
 An action an external agent reads to pull live app state into its own context must be:
 
@@ -125,43 +159,86 @@ export default defineAction({
 
 `GET` + `readOnly` keeps the action side-effect-free and out of the screen-refresh poll. `publicAgent` is the **explicit opt-in** — a public web route never implies public MCP/A2A exposure; see [Actions](/docs/actions). Design/content ingest actions MUST read **live** state (the Yjs collaborative document, not the stale DB snapshot column) so the external agent sees what the user actually has on screen. Content's `pull-document` flushes any open live collab session to SQL first; design's `get-design-snapshot` returns the live Yjs file contents plus the user's resolved tweak values.
 
-## Generic cross-app verbs + scaffolding {#cross-app}
+## Advanced: local development & manual setup {#advanced}
 
-On top of the per-action tools the MCP server exposes a stable verb set so an external agent has a predictable surface without guessing per-app action names:
+The hosted `connect` flow above is the recommended path. The options below are for local development and hand-rolled setups.
 
-| Tool                                       | Side effects | Returns                                                                              |
-| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
-| `list_apps`                                | none         | workspace apps + their dev URLs / running state                                      |
-| `open_app({ app, view, params? })`         | none         | a `buildDeepLink` URL (surfaces as an "Open …" link)                                 |
-| `ask_app({ app, message })`                | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`) |
-| `create_workspace_app({ name, template })` | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link            |
-| `list_templates`                           | none         | the allow-listed templates only                                                      |
+### Local development {#local-dev}
 
-`create_workspace_app` rejects any non-allow-listed template — the public template allow-list in `packages/shared-app-config/templates.ts` is authoritative and CI-guarded; an external agent cannot widen it. A same-named template action overrides a builtin (template-over-core precedence). Disable the whole set with `MCPConfig.builtinCrossAppTools: false`.
+Run your app locally (`pnpm dev` / `agent-native dev`), then point a local agent at it with one command:
 
-## Per-app tour {#tour}
+```bash
+agent-native mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
 
-Every allow-listed template that produces or lists a navigable resource ships a `link` builder, and the ingest-heavy ones ship a GET + `publicAgent` action:
+It provisions a token (a random `ACCESS_TOKEN` into the workspace `.env` for local dev, or a signed JWT if it detects a hosted origin) and writes an idempotent stdio server entry:
 
-- **Mail** — `manage-draft` returns a `compose`-encoded deep link; clicking it opens the inbox with the draft restored into a `compose-<id>`. `list-emails` / `search-emails` point at a filtered inbox view.
-- **Calendar** — `create-event` returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
-- **Analytics** — `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; the agent builds a dashboard over MCP and hands back "Open dashboard in Analytics".
-- **Design** — `get-design-snapshot` is the GET + `publicAgent` ingest action: it returns the **live** Yjs file contents plus the resolved tweak values so the agent continues from the tuned design, not the original tokens. `apply-tweaks` round-trips back with an "Open design" editor link.
-- **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
-- **Brain** — `ask-brain` / `search-everything` return a cited answer plus a deep link to the underlying knowledge/capture, so a terminal agent's lookup links straight back into the source in the running app.
+- **claude-code / claude-code-cli** — an `mcpServers` entry in `.mcp.json` (project scope, default) or `~/.claude.json` (`--scope user`).
+- **cowork** — the same Claude Code JSON shape in `~/.cowork/mcp.json`.
+- **codex** — an `[mcp_servers.<name>]` block in `~/.codex/config.toml`.
+
+The entry runs `agent-native mcp serve --app <id>`, which by default is a **thin stdio proxy** to the running local app's `/_agent-native/mcp` — so the live action registry, HMR, and correct deep links stay the single source of truth. Pass `--standalone` to build the registry in-process instead. When `agent-native mcp install` detects a hosted origin (a non-localhost `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` in the workspace `.env`), it writes an `http` client entry pointing at `<origin>/_agent-native/mcp` with a `Bearer` JWT instead of a stdio entry.
+
+Companion subcommands:
+
+| Command                                   | What it does                                                        |
+| ----------------------------------------- | ------------------------------------------------------------------- |
+| `agent-native mcp serve [--app <id>]`     | Run the MCP stdio transport (what client configs spawn).            |
+| `agent-native mcp install --client <c>`   | Provision a token + write the client's MCP config (idempotent).     |
+| `agent-native mcp uninstall --client <c>` | Remove the named MCP entry from a client's config (idempotent).     |
+| `agent-native mcp status`                 | Show resolved MCP URL/port, token state, and per-client entries.    |
+| `agent-native mcp token [--rotate]`       | Print (or rotate) the local `ACCESS_TOKEN` in the workspace `.env`. |
+
+Restart the client after `install` so it picks up the new MCP server.
+
+### Manual `.mcp.json` HTTP entry {#manual-entry}
+
+You can also write the MCP client config by hand against any deployed endpoint with a token you supply yourself (an `ACCESS_TOKEN`, or an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "url",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+This is the unmanaged equivalent of what `connect` writes for you. See [MCP Protocol](/docs/mcp-protocol) for the full auth env-var matrix.
+
+### Dev vs production tool surface {#dev-vs-prod}
+
+In plain local dev (`NODE_ENV=development` and `AGENT_MODE !== "production"`) the MCP `tools/list` deliberately exposes only the generic builtins plus actions with `publicAgent.requiresAuth === false` — the per-app ingest actions (`requiresAuth: true`) and mutating actions (no `publicAgent`) are filtered out (`filterPublicAgentActions`). The full per-app surface appears when the request is authenticated as a real caller: a deployed / `AGENT_MODE=production` app, or a local app reached through `connect` / `agent-native mcp install` (which provisions a token so the caller has an identity). So if `tools/list` looks sparse, you are hitting an unauthenticated dev endpoint — connect (or present a token) rather than assuming the action is missing.
+
+## How it works & security {#how-it-works}
+
+The hosted `connect` flow never copies the deployment's shared secret. Instead:
+
+- A logged-in browser session mints a **per-user, scoped, revocable** token — an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` and a unique `jti`, so every tool run stays tenant-scoped via `runWithRequestContext`.
+- The existing `/_agent-native/mcp` endpoint accepts that token like any other bearer (see [MCP Protocol](/docs/mcp-protocol)) — no new endpoint, no new transport.
+- The same Connect page lists every token you've minted and lets you **revoke** any of them by `jti`. Treat them like personal access tokens: one per agent client, revoke when a machine is decommissioned.
+- The deep link the agent hands back carries no privileged state. The record-focusing `navigate` write is always scoped to the **browser** session, never the agent's token — so a link is safe to paste into a terminal or chat transcript.
 
 ## Do / Don't {#do-dont}
 
 **Do**
 
+- Connect your own agent to a hosted app with `npx @agent-native/core connect <url>` (or `--all`) — it's the frictionless path.
 - Add a `link` builder to any action that produces or lists a navigable resource (draft, event, dashboard, document).
 - Build the URL with `buildDeepLink(...)` — the single source of truth for the open-route format.
 - Keep `link` pure and synchronous; return `null` when there's nothing to open.
 - Make external-agent ingest actions GET + `readOnly` + `publicAgent`, and read live (Yjs) state, not the stale DB column.
 - Let the open route resolve the browser session; pass record ids as deep-link params and let the UI focus them via the polled `navigate` command.
+- Revoke a minted connect token by `jti` when an agent client is decommissioned.
 
 **Don't**
 
+- Copy a deployment's shared `ACCESS_TOKEN` / `A2A_SECRET` into a client config when `connect` can mint a per-user, revocable token instead.
 - Hand-format the `/_agent-native/open` URL — always go through `buildDeepLink`.
 - Do I/O, awaits, DB reads, or app-state reads inside a `link` builder.
 - Scope the `navigate` write to the agent token, or pass privileged state through the deep link — it's a pure pointer.
@@ -175,3 +252,5 @@ Every allow-listed template that produces or lists a navigable resource ships a
 - [A2A Protocol](/docs/a2a-protocol) — the `ask-agent` meta-tool and JSON-RPC peer calls.
 - [Actions](/docs/actions) — defining actions, `publicAgent`, GET / `readOnly`.
 - [Context Awareness](/docs/context-awareness) — the `navigate` / `application_state` contract the open route bridges to.
+  </content>
+  </invoke>

package/docs/content/frames.md

@@ -12,7 +12,7 @@ Agent-native apps run with an AI agent alongside the app UI. Locally, the agent
 - Ships with `@agent-native/core` — no separate package needed
 - Agent panel embedded directly in your app with chat and optional CLI terminal
 - Supports multiple AI coding CLIs — switch between them from the settings panel
-- Toggle between production mode (app tools only) and development mode (full filesystem, shell, and database access)
+- Toggle between production mode (app tools only) and development mode (shared `bash`/`read`/`edit`/`write` coding tools plus database access)
 - Great for local development, self-hosted production, and OSS
 
 ## Supported CLIs {#supported-clis}

package/docs/content/migration-workbench.md

@@ -59,6 +59,11 @@ code> /migrate ./my-next-app --out ../migrated-app
 code> /audit --url https://example.com
 ```
 
+Agent-Native Code uses the same minimal coding tools as the sidebar development
+agent: `bash` for discovery/search/tests/builds, `read` for line-numbered file
+reads, `edit` for exact replacements, and `write` for new files or full
+rewrites.
+
 The same goals can run directly from the command line:
 
 ```bash
@@ -209,7 +214,7 @@ In Agent-Native Code, Desktop, or the internal run surface, connect providers th
 
 ## Agent-Native Code
 
-Agent-Native Desktop includes a **Agent-Native Code** hub for long-running coding-agent sessions. It is the general Code app/surface in Desktop, and it pairs with the `agent-native code` shell as the primary CLI/Desktop coding experience. A bare prompt is the generic coding session, and `/migrate` is one specialized capability there: the hub shows recent and active runs, opens a transcript-first session view, renders tool events and artifacts, sends follow-up prompts, stops tracked runners, opens a terminal in the run workspace, and handles links like:
+Agent-Native Desktop includes a **Agent-Native Code** hub for long-running coding-agent sessions. It is the general Code app/surface in Desktop, and it pairs with the `agent-native code` shell as the primary CLI/Desktop coding experience. A bare prompt is the generic coding session, and `/migrate` is one specialized capability there: the hub shows recent and active runs, opens a transcript-first session view with compact tool summaries and artifacts, sends follow-up prompts, stops tracked runners, opens a terminal in the run workspace, and handles links like:
 
 ```text
 agentnative://open?goal=migrate&run=<runId>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -78,6 +78,7 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./code-agents": "./dist/code-agents/index.js",
+    "./code-agents/transcript-normalizer": "./dist/code-agents/transcript-normalizer.js",
     "./workspace-connections": "./dist/workspace-connections/index.js",
     "./notifications": "./dist/notifications/index.js",
     "./client/notifications": "./dist/client/notifications/index.js",