@agent-native/core 0.101.5 → 0.101.7

package/dist/server/agent-chat/action-filters-a2a.js.map

@@ -1 +1 @@
-{"version":3,"file":"action-filters-a2a.js","sourceRoot":"","sources":["../../../src/server/agent-chat/action-filters-a2a.ts"],"names":[],"mappings":"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","sourcesContent":["import { getHeader } from \"h3\";\n\nimport {\n  appendA2AArtifactLinks,\n  type A2AArtifactResponseOptions,\n  type A2AToolResultSummary,\n} from \"../../a2a/artifact-response.js\";\nimport { collectFinalResponseTextFromAgentEvents } from \"../../a2a/response-text.js\";\nimport { resolveMainChatMaxOutputTokens } from \"../../agent/engine/output-tokens.js\";\nimport type { EngineTool } from \"../../agent/engine/types.js\";\nimport {\n  filterInitialEngineTools,\n  resolveAgentRequestReasoningEffort,\n  type ActionEntry,\n} from \"../../agent/production-agent.js\";\nimport { runAgentLoopDirectWithSoftTimeout } from \"../../agent/run-loop-with-resume.js\";\nimport type { AgentChatEvent } from \"../../agent/types.js\";\nimport { withConfiguredAppBasePath } from \"../app-base-path.js\";\nimport type { AgentChatPluginOptions } from \"./plugin-options.js\";\n\n// ---------------------------------------------------------------------------\n// Action-visibility filters (read-only / agent-exposed / public-agent-safe)\n// and the A2A (agent-to-agent) final-response assembly + delegated-run\n// helpers that share those filters.\n// ---------------------------------------------------------------------------\n\nexport function filterReadOnlyActions(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => entry.readOnly === true),\n  );\n}\n\n/** Drop actions that opted out of agent exposure via `agentTool: false`. They\n *  remain callable from the frontend / HTTP (mounted separately from this\n *  agent tool surface — see `httpActions`) but never appear in any agent tool\n *  list (in-app assistant, MCP, A2A, job/trigger runners) or actions prompt.\n *  Default-allow: only an explicit `false` is excluded. */\nexport function filterAgentTools(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => entry.agentTool !== false),\n  );\n}\n\nexport function filterPublicAgentActions(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => {\n      const config = entry.publicAgent;\n      return (\n        config?.expose === true &&\n        config.readOnly === true &&\n        config.requiresAuth !== true &&\n        config.isConsequential !== true\n      );\n    }),\n  );\n}\n\nexport function buildPublicAgentA2ASkills(\n  actions: Record<string, ActionEntry>,\n): Array<{\n  id: string;\n  name: string;\n  description: string;\n  publicAgent: ActionEntry[\"publicAgent\"];\n}> {\n  return Object.entries(filterPublicAgentActions(actions)).map(\n    ([name, entry]) => ({\n      id: name,\n      name,\n      description: entry.tool.description,\n      publicAgent: entry.publicAgent,\n    }),\n  );\n}\n\nexport function resolveArtifactBaseUrl(\n  event: any | undefined,\n): string | undefined {\n  const fromEnv =\n    process.env.APP_URL ||\n    process.env.URL ||\n    process.env.DEPLOY_URL ||\n    process.env.BETTER_AUTH_URL;\n  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));\n\n  try {\n    const proto = getHeader(event, \"x-forwarded-proto\") || \"https\";\n    const host = getHeader(event, \"host\");\n    if (host) return withConfiguredAppBasePath(`${proto}://${host}`);\n  } catch {}\n\n  return undefined;\n}\n\nexport function assembleA2AFinalResponse(\n  events: readonly AgentChatEvent[],\n  toolResults: readonly A2AToolResultSummary[],\n  options: A2AArtifactResponseOptions & { event?: any } = {},\n): { responseText: string; finalText: string } {\n  const terminalError = getA2ATerminalErrorEvent(events);\n  const responseText = collectFinalResponseTextFromAgentEvents(events, {\n    fallbackToPreToolText: !terminalError,\n  });\n  const finalText = appendA2AArtifactLinks(responseText, [...toolResults], {\n    baseUrl: options.baseUrl ?? resolveArtifactBaseUrl(options.event),\n    includeReferencedArtifacts: true,\n  });\n  if (terminalError && !finalText.trim()) {\n    throw new Error(formatA2ATerminalError(terminalError));\n  }\n  return { responseText, finalText };\n}\n\nfunction getA2ATerminalErrorEvent(\n  events: readonly AgentChatEvent[],\n): Extract<AgentChatEvent, { type: \"error\" }> | null {\n  for (let i = events.length - 1; i >= 0; i--) {\n    const event = events[i];\n    if (event.type === \"clear\") continue;\n    if (event.type === \"done\") return null;\n    if (event.type === \"error\") return event;\n    if (event.type === \"auto_continue\") {\n      return {\n        type: \"error\",\n        error: `Agent stopped before finishing (${event.reason}).`,\n        errorCode: event.reason,\n        recoverable: true,\n      };\n    }\n  }\n  return null;\n}\n\nfunction formatA2ATerminalError(\n  event: Extract<AgentChatEvent, { type: \"error\" }>,\n): string {\n  const parts = [\n    event.error || \"Agent failed before producing a final response.\",\n    event.errorCode ? `code: ${event.errorCode}` : \"\",\n    event.details ? `details: ${event.details}` : \"\",\n  ].filter(Boolean);\n  return parts.join(\"\\n\");\n}\n\ntype A2AAgentLoopRunner = typeof runAgentLoopDirectWithSoftTimeout;\n\nfunction runDelegatedAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner,\n) {\n  return runner(\n    {\n      ...runOptions,\n      // Delegated runs resolve their own model and do not pass through the\n      // interactive request handler's output-token setup. Use the same\n      // model-aware headroom here so reasoning models (notably GPT-5.x) do\n      // not spend the small internal default entirely on reasoning before\n      // emitting a tool call or answer. Preserve explicit test/caller values.\n      maxOutputTokens:\n        runOptions.maxOutputTokens ??\n        resolveMainChatMaxOutputTokens(runOptions.model),\n      reasoningEffort:\n        runOptions.reasoningEffort ??\n        resolveAgentRequestReasoningEffort({ model: runOptions.model }),\n      finalResponseGuard: pluginOptions.finalResponseGuard,\n    },\n    pluginOptions.runSoftTimeoutMs,\n    timeoutOptions,\n  );\n}\n\n/**\n * Run an A2A-delegated agent turn with the same final-response guard used by\n * the app's interactive chat surface.\n *\n * Keeping this in one helper prevents delegated calls from silently bypassing\n * template guarantees such as Analytics' requirement to query real data\n * before presenting metrics or exhaustive provider conclusions.\n */\nexport function runA2AAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,\n) {\n  return runDelegatedAgentLoop(\n    runOptions,\n    pluginOptions,\n    timeoutOptions,\n    runner,\n  );\n}\n\n/**\n * Run the MCP-local ask_app turn with the same app-level response guard as\n * A2A. Keeping this seam shared prevents hosted MCP callers from bypassing\n * template guarantees when the request cannot use the self-A2A route.\n */\nexport function runMCPAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,\n) {\n  return runDelegatedAgentLoop(\n    runOptions,\n    pluginOptions,\n    timeoutOptions,\n    runner,\n  );\n}\n\n/**\n * Keep delegated A2A turns on the same compact initial tool surface as\n * interactive chat. `tool-search` remains in the initial set, while the\n * complete registry is supplied separately so the run loop can load a matched\n * schema after a tool-search result.\n */\nexport function createA2AEngineToolSurface(\n  availableTools: EngineTool[],\n  initialToolNames?: string[],\n): { tools: EngineTool[]; availableTools: EngineTool[] } {\n  return {\n    tools: filterInitialEngineTools(availableTools, initialToolNames),\n    availableTools,\n  };\n}\n\nexport function resolveInitialToolNames(\n  templateActions: Record<string, ActionEntry>,\n  configured?: string[],\n): string[] {\n  return configured ?? Object.keys(templateActions);\n}\n"]}
+{"version":3,"file":"action-filters-a2a.js","sourceRoot":"","sources":["../../../src/server/agent-chat/action-filters-a2a.ts"],"names":[],"mappings":"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","sourcesContent":["import { getHeader } from \"h3\";\n\nimport {\n  appendA2AArtifactLinks,\n  type A2AArtifactResponseOptions,\n  type A2AToolResultSummary,\n} from \"../../a2a/artifact-response.js\";\nimport { collectFinalResponseTextFromAgentEvents } from \"../../a2a/response-text.js\";\nimport { resolveMainChatMaxOutputTokens } from \"../../agent/engine/output-tokens.js\";\nimport type { EngineTool } from \"../../agent/engine/types.js\";\nimport {\n  filterInitialEngineTools,\n  resolveAgentRequestReasoningEffort,\n  type ActionEntry,\n} from \"../../agent/production-agent.js\";\nimport { runAgentLoopDirectWithSoftTimeout } from \"../../agent/run-loop-with-resume.js\";\nimport type { AgentChatEvent } from \"../../agent/types.js\";\nimport { withConfiguredAppBasePath } from \"../app-base-path.js\";\nimport type { AgentChatPluginOptions } from \"./plugin-options.js\";\n\n// ---------------------------------------------------------------------------\n// Action-visibility filters (read-only / agent-exposed / public-agent-safe)\n// and the A2A (agent-to-agent) final-response assembly + delegated-run\n// helpers that share those filters.\n// ---------------------------------------------------------------------------\n\nexport function filterReadOnlyActions(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => entry.readOnly === true),\n  );\n}\n\n/** Drop actions that opted out of agent exposure via `agentTool: false`. They\n *  remain callable from the frontend / HTTP (mounted separately from this\n *  agent tool surface — see `httpActions`) but never appear in any agent tool\n *  list (in-app assistant, MCP, A2A, job/trigger runners) or actions prompt.\n *  Default-allow: only an explicit `false` is excluded. */\nexport function filterAgentTools(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => entry.agentTool !== false),\n  );\n}\n\nexport function filterPublicAgentActions(\n  actions: Record<string, ActionEntry>,\n): Record<string, ActionEntry> {\n  return Object.fromEntries(\n    Object.entries(actions).filter(([, entry]) => {\n      const config = entry.publicAgent;\n      return (\n        config?.expose === true &&\n        config.readOnly === true &&\n        config.requiresAuth !== true &&\n        config.isConsequential !== true\n      );\n    }),\n  );\n}\n\nexport function buildPublicAgentA2ASkills(\n  actions: Record<string, ActionEntry>,\n): Array<{\n  id: string;\n  name: string;\n  description: string;\n  publicAgent: ActionEntry[\"publicAgent\"];\n}> {\n  return Object.entries(filterPublicAgentActions(actions)).map(\n    ([name, entry]) => ({\n      id: name,\n      name,\n      description: entry.tool.description,\n      publicAgent: entry.publicAgent,\n    }),\n  );\n}\n\nexport function resolveArtifactBaseUrl(\n  event: any | undefined,\n): string | undefined {\n  const fromEnv =\n    process.env.APP_URL ||\n    process.env.URL ||\n    process.env.DEPLOY_URL ||\n    process.env.BETTER_AUTH_URL;\n  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));\n\n  try {\n    const proto = getHeader(event, \"x-forwarded-proto\") || \"https\";\n    const host = getHeader(event, \"host\");\n    if (host) return withConfiguredAppBasePath(`${proto}://${host}`);\n  } catch {}\n\n  return undefined;\n}\n\nexport function assembleA2AFinalResponse(\n  events: readonly AgentChatEvent[],\n  toolResults: readonly A2AToolResultSummary[],\n  options: A2AArtifactResponseOptions & { event?: any } = {},\n): { responseText: string; finalText: string } {\n  const terminalError = getA2ATerminalErrorEvent(events);\n  const responseText = collectFinalResponseTextFromAgentEvents(events, {\n    fallbackToPreToolText: !terminalError,\n  });\n  const finalText = appendA2AArtifactLinks(responseText, [...toolResults], {\n    baseUrl: options.baseUrl ?? resolveArtifactBaseUrl(options.event),\n    includeReferencedArtifacts: true,\n    includePersistedArtifactMarker: true,\n  });\n  if (terminalError && !finalText.trim()) {\n    throw new Error(formatA2ATerminalError(terminalError));\n  }\n  return { responseText, finalText };\n}\n\nfunction getA2ATerminalErrorEvent(\n  events: readonly AgentChatEvent[],\n): Extract<AgentChatEvent, { type: \"error\" }> | null {\n  for (let i = events.length - 1; i >= 0; i--) {\n    const event = events[i];\n    if (event.type === \"clear\") continue;\n    if (event.type === \"done\") return null;\n    if (event.type === \"error\") return event;\n    if (event.type === \"auto_continue\") {\n      return {\n        type: \"error\",\n        error: `Agent stopped before finishing (${event.reason}).`,\n        errorCode: event.reason,\n        recoverable: true,\n      };\n    }\n  }\n  return null;\n}\n\nfunction formatA2ATerminalError(\n  event: Extract<AgentChatEvent, { type: \"error\" }>,\n): string {\n  const parts = [\n    event.error || \"Agent failed before producing a final response.\",\n    event.errorCode ? `code: ${event.errorCode}` : \"\",\n    event.details ? `details: ${event.details}` : \"\",\n  ].filter(Boolean);\n  return parts.join(\"\\n\");\n}\n\ntype A2AAgentLoopRunner = typeof runAgentLoopDirectWithSoftTimeout;\n\nfunction runDelegatedAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner,\n) {\n  return runner(\n    {\n      ...runOptions,\n      // Delegated runs resolve their own model and do not pass through the\n      // interactive request handler's output-token setup. Use the same\n      // model-aware headroom here so reasoning models (notably GPT-5.x) do\n      // not spend the small internal default entirely on reasoning before\n      // emitting a tool call or answer. Preserve explicit test/caller values.\n      maxOutputTokens:\n        runOptions.maxOutputTokens ??\n        resolveMainChatMaxOutputTokens(runOptions.model),\n      reasoningEffort:\n        runOptions.reasoningEffort ??\n        resolveAgentRequestReasoningEffort({ model: runOptions.model }),\n      finalResponseGuard: pluginOptions.finalResponseGuard,\n    },\n    pluginOptions.runSoftTimeoutMs,\n    timeoutOptions,\n  );\n}\n\n/**\n * Run an A2A-delegated agent turn with the same final-response guard used by\n * the app's interactive chat surface.\n *\n * Keeping this in one helper prevents delegated calls from silently bypassing\n * template guarantees such as Analytics' requirement to query real data\n * before presenting metrics or exhaustive provider conclusions.\n */\nexport function runA2AAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,\n) {\n  return runDelegatedAgentLoop(\n    runOptions,\n    pluginOptions,\n    timeoutOptions,\n    runner,\n  );\n}\n\n/**\n * Run the MCP-local ask_app turn with the same app-level response guard as\n * A2A. Keeping this seam shared prevents hosted MCP callers from bypassing\n * template guarantees when the request cannot use the self-A2A route.\n */\nexport function runMCPAgentLoop(\n  runOptions: Parameters<A2AAgentLoopRunner>[0],\n  pluginOptions: Pick<\n    AgentChatPluginOptions,\n    \"finalResponseGuard\" | \"runSoftTimeoutMs\"\n  >,\n  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],\n  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,\n) {\n  return runDelegatedAgentLoop(\n    runOptions,\n    pluginOptions,\n    timeoutOptions,\n    runner,\n  );\n}\n\n/**\n * Keep delegated A2A turns on the same compact initial tool surface as\n * interactive chat. `tool-search` remains in the initial set, while the\n * complete registry is supplied separately so the run loop can load a matched\n * schema after a tool-search result.\n */\nexport function createA2AEngineToolSurface(\n  availableTools: EngineTool[],\n  initialToolNames?: string[],\n): { tools: EngineTool[]; availableTools: EngineTool[] } {\n  return {\n    tools: filterInitialEngineTools(availableTools, initialToolNames),\n    availableTools,\n  };\n}\n\nexport function resolveInitialToolNames(\n  templateActions: Record<string, ActionEntry>,\n  configured?: string[],\n): string[] {\n  return configured ?? Object.keys(templateActions);\n}\n"]}

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/docs/content/locales/ar-SA/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app هو Agent-Native app بلا متصفح من أجل schedul
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## أضف الدردشة لاحقاً {#add-chat-later}
+## أضف واجهة مستخدم لاحقاً {#add-chat-later}
 
-يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق دردشة في مكانه. عندما يحتاج الأشخاص إلى محادثة في المتصفح، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins و`<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن محادثة تستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
+يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق متصفح في مكانه. عندما يحتاج الأشخاص إلى واجهة مستخدم، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins. وإذا كانت الواجهة محادثة، أضف `<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن تدفق واجهة يستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
 
 ## ما هي الخطوة التالية
 

package/docs/content/locales/de-DE/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ Die Box, das Gerüst, der Repo-Zugriff und die Lauffreigabe sind jetzt an einem
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Chat später hinzufügen {#add-chat-later}
+## Später eine UI hinzufügen {#add-chat-later}
 
-`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Chat-App umwandelt. Wenn Menschen eine Browser-Unterhaltung brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell, Server-Plugins, `<AgentChatSurface>` sowie ein Chat-Plugin, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen Chat-Turn, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
+`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Browser-App umwandelt. Wenn Menschen eine UI brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell und Server-Plugins. Für eine Chat-Oberfläche kommen `<AgentChatSurface>` und ein Chat-Plugin hinzu, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen UI-Ablauf, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
 
 ## Was kommt als nächstes
 

package/docs/content/locales/es-ES/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ la caja, el andamio, el acceso al repositorio y el uso compartido de ejecuciones
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Añade chat más adelante {#add-chat-later}
+## Añade una UI más adelante {#add-chat-later}
 
-`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de chat. Cuando las personas necesiten una conversación en el navegador, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador, los plugins de servidor, `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un turno de chat que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
+`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de navegador. Cuando las personas necesiten una UI, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador y los plugins de servidor. Para una superficie de chat, añade `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un flujo de UI que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
 
 ## ¿Qué sigue?
 

package/docs/content/locales/fr-FR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ la boîte, l'échafaudage, l'accès au dépôt et le partage d'exécution se tro
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Ajouter le chat plus tard {#add-chat-later}
+## Ajouter une UI plus tard {#add-chat-later}
 
-`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application de chat. Quand les personnes ont besoin d'une conversation dans le navigateur, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur, les plugins serveur, `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un tour de chat appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
+`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application navigateur. Quand les personnes ont besoin d'une UI, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur et les plugins serveur. Pour une surface de chat, ajoutez `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un flux UI appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
 
 ## Quelle est la prochaine étape
 

package/docs/content/locales/hi-IN/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app scheduled jobs, queues, scripts, integration workers और
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## बाद में chat जोड़ें {#add-chat-later}
+## बाद में UI जोड़ें {#add-chat-later}
 
-`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place chat app में नहीं बदलती। जब लोगों को browser conversation चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell, server plugins, `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin जोड़ें। `pnpm typecheck` और एक ऐसा chat turn जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
+`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place browser app में नहीं बदलती। जब लोगों को UI चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell और server plugins जोड़ें। Chat surface के लिए `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin भी जोड़ें। `pnpm typecheck` और एक ऐसा UI flow जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
 
 ## आगे क्या है
 

package/docs/content/locales/ja-JP/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app は、scheduled jobs、queues、scripts、integration worke
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 後からチャットを追加する {#add-chat-later}
+## 後から UI を追加する {#add-chat-later}
 
-`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場で Chat アプリに変換する `agent-native` コマンドはありません。ブラウザーでの会話が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell、server plugins、`<AgentChatSurface>`、既存 actions を読み込む chat plugin を追加してください。`pnpm typecheck` と既存 action を呼ぶ chat turn を確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
+`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場でブラウザーアプリに変換する `agent-native` コマンドはありません。UI が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell と server plugins を追加してください。チャット surface には `<AgentChatSurface>` と既存 actions を読み込む chat plugin も追加します。`pnpm typecheck` と既存 action を呼ぶ UI フローを確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
 
 ## 次は何ですか
 

package/docs/content/locales/ko-KR/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app은 scheduled jobs, queues, scripts, integration workers, ex
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 나중에 채팅 추가하기 {#add-chat-later}
+## 나중에 UI 추가하기 {#add-chat-later}
 
-`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 Chat 앱으로 변환하는 `agent-native` 명령은 없습니다. 브라우저 대화가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell, server plugins, `<AgentChatSurface>`, 기존 actions를 로드하는 chat plugin을 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 chat turn을 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
+`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 브라우저 앱으로 변환하는 `agent-native` 명령은 없습니다. UI가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell과 server plugins를 추가합니다. Chat surface에는 `<AgentChatSurface>`와 기존 actions를 로드하는 chat plugin도 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 UI flow를 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
 
 ## 다음 단계
 

package/docs/content/locales/pt-BR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ a caixa, o scaffold, o acesso ao repositório e o compartilhamento de execução
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Adicione chat depois {#add-chat-later}
+## Adicione uma UI depois {#add-chat-later}
 
-`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de chat. Quando as pessoas precisarem de uma conversa no navegador, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador, os server plugins, `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um turno de chat que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
+`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de navegador. Quando as pessoas precisarem de uma UI, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador e os server plugins. Para uma superfície de chat, adicione `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um fluxo de UI que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
 
 ## O que vem a seguir
 

package/docs/content/locales/zh-CN/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是无浏览器的 Agent-Native app，用于 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍后添加聊天 {#add-chat-later}
+## 稍后添加 UI {#add-chat-later}
 
-`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为聊天应用的 `agent-native` 命令。当用户需要浏览器对话时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell、server plugins、`<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的聊天。`agent-native add` 用于 integration blueprints，不用于此转换。
+`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为浏览器应用的 `agent-native` 命令。当用户需要 UI 时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell 和 server plugins。对于聊天界面，再添加 `<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的 UI 流程。`agent-native add` 用于 integration blueprints，不用于此转换。
 
 ## 下一步是什么
 

package/docs/content/locales/zh-TW/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是無瀏覽器的 Agent-Native app，用於 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍後新增聊天 {#add-chat-later}
+## 稍後新增 UI {#add-chat-later}
 
-`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為聊天應用程式的 `agent-native` 命令。當使用者需要瀏覽器對話時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell、server plugins、`<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的聊天。`agent-native add` 用於 integration blueprints，不用於此轉換。
+`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為瀏覽器應用程式的 `agent-native` 命令。當使用者需要 UI 時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell 與 server plugins。對於聊天介面，再新增 `<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的 UI 流程。`agent-native add` 用於 integration blueprints，不用於此轉換。
 
 ## 下一步是什麼
 

package/docs/content/pure-agent-apps.mdx

@@ -95,22 +95,66 @@ The `--headless` flag only chooses the initial scaffold. It does not choose a
 different architecture. You can later move the same `actions/`, instructions,
 skills, and SQL state into a chat app or full application surface.
 
-## Add chat later {#add-chat-later}
+## Add a UI later {#add-chat-later}
 
 `--headless` is not a permanent runtime mode, and there is no `agent-native`
-command that converts an existing action-only project into a chat app in place.
-When people need a browser conversation surface, use the [Chat template](/docs/template-chat)
-as the migration reference and keep the durable action and database contract:
-
-1. Scaffold a temporary Chat app with the framework version you are migrating
-   to: `npx @agent-native/core@latest create my-chat-reference --template chat`.
-2. Bring its browser shell, server plugins, and UI dependencies into the
-   existing project. In particular, add the full-page `<AgentChatSurface>` and
-   an `agent-chat` plugin that loads the existing action registry.
-3. Keep your action names, Zod schemas, SQL data, instructions, and skills.
-   Chat calls those same actions; it does not replace them.
-4. Verify both surfaces: run `pnpm typecheck`, start the browser app with
-   `pnpm dev`, then complete one chat turn that calls an existing action.
+command that converts an existing action-only project into a browser app in
+place. When people need a UI, use the [Chat template](/docs/template-chat) as
+the migration reference and keep the durable action and database contract:
+
+<Diagram id="doc-block-ui-later" title="One contract, multiple surfaces" summary={"Start with a headless workflow, then add a browser UI without rewriting the actions, data, instructions, or skills underneath."}>
+
+```html
+<div class="diagram-ui-path">
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill accent">Start headless</span
+    ><small class="diagram-muted">jobs · CLI · external agents</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill">Add a UI</span
+    ><small class="diagram-muted">chat · routes · durable pages</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel ok" data-rough>
+    <span class="diagram-pill ok">Keep the contract</span
+    ><small class="diagram-muted">actions · SQL · instructions · skills</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-ui-path {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-ui-path .diagram-panel {
+  display: flex;
+  min-width: 150px;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  text-align: center;
+}
+.diagram-ui-path .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+1. Scaffold the first workflow with `npx @agent-native/core@latest create my-agent --headless`.
+2. When a browser surface becomes useful, bring in the template's shell, server
+   plugins, and UI dependencies. For chat, that includes `<AgentChatSurface>`
+   and an `agent-chat` plugin that loads the existing action registry.
+3. Keep your action names, Zod schemas, SQL data, instructions, and skills. A
+   UI calls those same actions; it does not replace them.
+4. Verify both surfaces with `pnpm typecheck`, `pnpm dev`, and one UI flow that
+   calls an existing action.
 
 Use `agent-native add` for integration blueprints, not for this conversion.
 Choose chat when people need conversational steering, approvals, or durable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.5",
+  "version": "0.101.7",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -335,8 +335,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.4.10",
-    "@agent-native/recap-cli": "0.4.0"
+    "@agent-native/recap-cli": "0.4.0",
+    "@agent-native/toolkit": "^0.4.10"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",