@agent-native/dispatch 0.11.0 → 0.11.1

package/README.md

@@ -16,9 +16,10 @@ The agent and the UI are equal citizens of the same system. Every action works b
 - **Per-user workspace** — Skills, memory, instructions, sub-agents, and MCP servers — SQL-backed, customizable per user. Claude-Code-level flexibility, SaaS-grade economics.
 - **Agents call agents** — Tag another agent from any app. They discover each other over A2A and take action across your stack.
 - **Reusable integrations** — Connect a provider once in Dispatch, keep secret values in the vault, then grant apps like Brain, Analytics, Mail, and Dispatch access to the shared account metadata and credential refs.
+- **Three shapes** — Build the same agent as a headless API, a rich chat experience, or a full application where agent and UI stay in sync.
 - **Apps that improve themselves** — Your apps get better on their own. The agent can add features, fix bugs, and refine the UI over time.
 - **Any database, any host** — Any SQL database Drizzle supports. Any hosting target Nitro supports. No lock-in.
-- **Any AI agent** — Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, or Builder.io. Use whichever agent you prefer.
+- **Bring the agent surface you need** — MCP-compatible hosts can call your apps, coding agents can install skills, native chat renders reusable app outputs, and BYO agent runtimes can stream into the Agent-Native chat shell.
 
 ## The framework for agent-native apps
 
@@ -45,6 +46,22 @@ export default defineAction({
 - **Agent runtime** — Chat, tools, skills, memory, jobs, observability, and handoffs ship together.
 - **Backend agnostic** — Plug in any Drizzle-supported SQL database and Nitro-compatible host.
 
+## One agent, three product shapes
+
+Agent-Native primitives let you choose how much UI to put around an agent without rebuilding the agent contract:
+
+| Shape         | What you ship                                                                                             | Same primitives underneath                                                  |
+| ------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| **Headless**  | Call the agent and actions from code, CLI, HTTP, MCP, or A2A.                                             | `defineAction`, auth, skills, memory, jobs, observability                   |
+| **Rich chat** | A standalone or embedded chat with native tables, charts, approvals, setup flows, and tool results.       | Shared chat runtime, BYO runtime adapters, action-declared native renderers |
+| **Whole app** | A full SaaS/product UI where chat can start central, move to the sidebar, and stay synced with app state. | SQL state, actions, context awareness, deep links, live sync                |
+
+Protocols come with the framework instead of becoming separate integrations per feature. Today that means A2A, MCP, MCP Apps, standard remote MCP OAuth, MCP clients, HTTP/CLI action calls, native chat widgets, `AgentChatRuntime` adapters, standard OpenAI, AG-UI, Claude Agent SDK, and Vercel AI SDK chat runtime connectors, and deep links all hang off the same action surface. ACP is best understood as the coding-agent/editor interoperability protocol, not the general BYO app-chat runtime.
+
+For the full decision guide — headless, rich chat on the built-in agent, rich chat on your own agent, embedded sidecar, or full app — see [Agent Surfaces](https://agent-native.com/docs/agent-surfaces).
+
+To connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host to your hosted app, see the [External Agents guide](https://agent-native.com/docs/external-agents).
+
 ## Try it with a skill
 
 Don't want to scaffold a whole app yet? Add visual planning and PR recaps to Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, and similar agents with one command:

package/dist/actions/provider-api-catalog.d.ts

@@ -15,6 +15,7 @@ declare const _default: import("@agent-native/core").ActionDefinition<{
         defaultHeaders: Record<string, string>;
         examples: readonly import("@agent-native/core/provider-api").ProviderApiExample[];
         notes: readonly string[];
+        corpusRecipes: readonly import("@agent-native/core/provider-api").ProviderApiCorpusRecipe[];
         templateUses: readonly import("@agent-native/core").WorkspaceConnectionTemplateUse[];
     }[];
     guidance: string;

package/dist/actions/provider-api-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-api-catalog.d.ts","sourceRoot":"","sources":["../../src/actions/provider-api-catalog.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;AAIA,wBAqBG"}
+{"version":3,"file":"provider-api-catalog.d.ts","sourceRoot":"","sources":["../../src/actions/provider-api-catalog.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAIA,wBAqBG"}

package/dist/server/lib/provider-api.d.ts

@@ -17,6 +17,7 @@ export declare function listProviderApiCatalog(provider?: string): {
     defaultHeaders: Record<string, string>;
     examples: readonly import("@agent-native/core/provider-api").ProviderApiExample[];
     notes: readonly string[];
+    corpusRecipes: readonly import("@agent-native/core/provider-api").ProviderApiCorpusRecipe[];
     templateUses: readonly import("@agent-native/core").WorkspaceConnectionTemplateUse[];
 }[] | Promise<unknown[]>;
 export declare function fetchProviderApiDocs(options: ProviderApiDocsOptions & {

package/dist/server/lib/provider-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-api.d.ts","sourceRoot":"","sources":["../../../src/server/lib/provider-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,sBAAsB,EAE3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAGzC,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,yBAAyB,kSAAmB,CAAC;AAC1D,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;AA0C1D,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;yBAEvD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,oBAGvD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,oBAErE"}
+{"version":3,"file":"provider-api.d.ts","sourceRoot":"","sources":["../../../src/server/lib/provider-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,sBAAsB,EAE3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAGzC,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,yBAAyB,kSAAmB,CAAC;AAC1D,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;AA0C1D,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;yBAEvD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,oBAGvD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,oBAErE"}

package/dist/server/plugins/agent-chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-chat.d.ts","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":";AAIA,wBAsCG"}
+{"version":3,"file":"agent-chat.d.ts","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":";AA4BA,wBAuCG"}

package/dist/server/plugins/agent-chat.js

@@ -1,8 +1,32 @@
 import { createAgentChatPlugin } from "@agent-native/core/server";
 import { getOrgContext } from "@agent-native/core/org";
 import { dispatchActions } from "../../actions/index.js";
+const INITIAL_TOOL_NAMES = [
+    "view-screen",
+    "list-workspace-apps",
+    "list-connected-agents",
+    "ask_app",
+    "open_app",
+    "list-workspace-resources",
+    "create-workspace-resource",
+    "update-workspace-resource",
+    "list-vault-secrets",
+    "request-vault-secret",
+    "create-vault-secret",
+    "list-destinations",
+    "upsert-destination",
+    "list-dreams",
+    "start-workspace-app-creation",
+    "list-available-workspace-templates",
+    "provider-api-catalog",
+    "provider-api-docs",
+    "provider-api-request",
+    "query-staged-dataset",
+    "navigate",
+];
 export default createAgentChatPlugin({
     appId: "dispatch",
+    initialToolNames: INITIAL_TOOL_NAMES,
     // Without this, AGENT_ORG_ID is never set on agent action calls and every
     // row written through the frontend (vault secrets, destinations, workspace
     // resources) lands with org_id=NULL — breaking data isolation across orgs.

package/dist/server/plugins/agent-chat.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-chat.js","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,eAAe,qBAAqB,CAAC;IACnC,KAAK,EAAE,UAAU;IACjB,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,EAAE,eAAe;IACxB,aAAa,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE;IAC1C,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;4EAuB4D;CAC3E,CAAC,CAAC","sourcesContent":["import { createAgentChatPlugin } from \"@agent-native/core/server\";\nimport { getOrgContext } from \"@agent-native/core/org\";\nimport { dispatchActions } from \"../../actions/index.js\";\n\nexport default createAgentChatPlugin({\n  appId: \"dispatch\",\n  // Without this, AGENT_ORG_ID is never set on agent action calls and every\n  // row written through the frontend (vault secrets, destinations, workspace\n  // resources) lands with org_id=NULL — breaking data isolation across orgs.\n  resolveOrgId: async (event) => {\n    const ctx = await getOrgContext(event);\n    return ctx.orgId;\n  },\n  // Read actions directly from the package's own action map rather than from\n  // a build-time-generated `.generated/actions-registry.ts` (the latter is a\n  // template-only construct that the Vite plugin emits next to actions/).\n  actions: dispatchActions,\n  codeExecution: { production: \"sandboxed\" },\n  systemPrompt: `You are the central dispatch for this workspace.\n\nDefault posture:\n- Treat Slack and Telegram as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A when another app owns the job.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Prefer replying in the current external thread unless the user explicitly asks you to send to a saved destination.\n\nUse the standard workspace primitives:\n- Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.\n- Use recurring jobs for scheduled behavior.\n- Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.\n- You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.\n- When answering whether workspace apps expose agent cards or A2A endpoints, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.\n- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.\n- If the starter template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.\n\nWhen a user asks for something like a digest, reminder, routing rule, or saved behavior:\n- First decide whether it should be a resource, a recurring job, a destination, or a delegated task.\n- Keep responses concise and operational.\n- Avoid inventing integrations or destinations that are not configured yet.`,\n});\n"]}
+{"version":3,"file":"agent-chat.js","sourceRoot":"","sources":["../../../src/server/plugins/agent-chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,kBAAkB,GAAG;IACzB,aAAa;IACb,qBAAqB;IACrB,uBAAuB;IACvB,SAAS;IACT,UAAU;IACV,0BAA0B;IAC1B,2BAA2B;IAC3B,2BAA2B;IAC3B,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,8BAA8B;IAC9B,oCAAoC;IACpC,sBAAsB;IACtB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,UAAU;CACX,CAAC;AAEF,eAAe,qBAAqB,CAAC;IACnC,KAAK,EAAE,UAAU;IACjB,gBAAgB,EAAE,kBAAkB;IACpC,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,EAAE,eAAe;IACxB,aAAa,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE;IAC1C,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;4EAuB4D;CAC3E,CAAC,CAAC","sourcesContent":["import { createAgentChatPlugin } from \"@agent-native/core/server\";\nimport { getOrgContext } from \"@agent-native/core/org\";\nimport { dispatchActions } from \"../../actions/index.js\";\n\nconst INITIAL_TOOL_NAMES = [\n  \"view-screen\",\n  \"list-workspace-apps\",\n  \"list-connected-agents\",\n  \"ask_app\",\n  \"open_app\",\n  \"list-workspace-resources\",\n  \"create-workspace-resource\",\n  \"update-workspace-resource\",\n  \"list-vault-secrets\",\n  \"request-vault-secret\",\n  \"create-vault-secret\",\n  \"list-destinations\",\n  \"upsert-destination\",\n  \"list-dreams\",\n  \"start-workspace-app-creation\",\n  \"list-available-workspace-templates\",\n  \"provider-api-catalog\",\n  \"provider-api-docs\",\n  \"provider-api-request\",\n  \"query-staged-dataset\",\n  \"navigate\",\n];\n\nexport default createAgentChatPlugin({\n  appId: \"dispatch\",\n  initialToolNames: INITIAL_TOOL_NAMES,\n  // Without this, AGENT_ORG_ID is never set on agent action calls and every\n  // row written through the frontend (vault secrets, destinations, workspace\n  // resources) lands with org_id=NULL — breaking data isolation across orgs.\n  resolveOrgId: async (event) => {\n    const ctx = await getOrgContext(event);\n    return ctx.orgId;\n  },\n  // Read actions directly from the package's own action map rather than from\n  // a build-time-generated `.generated/actions-registry.ts` (the latter is a\n  // template-only construct that the Vite plugin emits next to actions/).\n  actions: dispatchActions,\n  codeExecution: { production: \"sandboxed\" },\n  systemPrompt: `You are the central dispatch for this workspace.\n\nDefault posture:\n- Treat Slack and Telegram as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A when another app owns the job.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Prefer replying in the current external thread unless the user explicitly asks you to send to a saved destination.\n\nUse the standard workspace primitives:\n- Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.\n- Use recurring jobs for scheduled behavior.\n- Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.\n- You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.\n- When answering whether workspace apps expose agent cards or A2A endpoints, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.\n- When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.\n- If the starter template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.\n\nWhen a user asks for something like a digest, reminder, routing rule, or saved behavior:\n- First decide whether it should be a resource, a recurring job, a destination, or a delegated task.\n- Keep responses concise and operational.\n- Avoid inventing integrations or destinations that are not configured yet.`,\n});\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/dispatch",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "type": "module",
   "description": "Dispatch — workspace control plane for agent-native apps. Vault, integrations, destinations, scheduled jobs, and cross-app delegation, shipped as a single drop-in package.",
   "license": "MIT",
@@ -100,7 +100,7 @@
     "typescript": "^6.0.3",
     "vite": "8.0.3",
     "vitest": "^4.1.5",
-    "@agent-native/core": "0.54.0"
+    "@agent-native/core": "0.58.4"
   },
   "scripts": {
     "build": "tsc && tsc-alias --resolve-full-paths",

package/src/server/plugins/agent-chat.ts

@@ -2,8 +2,33 @@ import { createAgentChatPlugin } from "@agent-native/core/server";
 import { getOrgContext } from "@agent-native/core/org";
 import { dispatchActions } from "../../actions/index.js";
 
+const INITIAL_TOOL_NAMES = [
+  "view-screen",
+  "list-workspace-apps",
+  "list-connected-agents",
+  "ask_app",
+  "open_app",
+  "list-workspace-resources",
+  "create-workspace-resource",
+  "update-workspace-resource",
+  "list-vault-secrets",
+  "request-vault-secret",
+  "create-vault-secret",
+  "list-destinations",
+  "upsert-destination",
+  "list-dreams",
+  "start-workspace-app-creation",
+  "list-available-workspace-templates",
+  "provider-api-catalog",
+  "provider-api-docs",
+  "provider-api-request",
+  "query-staged-dataset",
+  "navigate",
+];
+
 export default createAgentChatPlugin({
   appId: "dispatch",
+  initialToolNames: INITIAL_TOOL_NAMES,
   // Without this, AGENT_ORG_ID is never set on agent action calls and every
   // row written through the frontend (vault secrets, destinations, workspace
   // resources) lands with org_id=NULL — breaking data isolation across orgs.