npm - @agent-native/core - Versions diffs - 0.101.4 → 0.101.6 - Mend

@agent-native/core 0.101.4 → 0.101.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (87) hide show

package/dist/server/agent-chat/context-tools.js CHANGED Viewed

@@ -228,6 +228,10 @@ export function createRefreshScreenEntry() {
             // distinct `screen-refresh` poll event. Don't double-emit a generic
             // `action` event on top of that.
             readOnly: true,
+            // Refetching volatile on-screen state is the entire point of this
+            // tool — an identical repeat call (even with the same scope) is a
+            // legitimate re-refresh, not a redundant read to skip.
+            dedupe: false,
             tool: {
                 description: "Manually refresh the user's current screen. The framework ALREADY auto-refreshes after any successful mutating action tool call (template actions and any enabled raw DB write tools) — you do NOT need to call this after a normal action. Use it only when (a) you mutated data via a path the framework can't detect (e.g. a direct write to an external system the app mirrors), or (b) you want to pass a `scope` hint so the UI narrows which queries to refetch. The UI re-fetches its queries without a full page reload.",
                 parameters: {

package/dist/server/agent-chat/context-tools.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"context-tools.js","sourceRoot":"","sources":["../../../src/server/agent-chat/context-tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { ACTION_CHAT_UI_DATA_WIDGET_RENDERER } from \"../../action-ui.js\";\nimport type { ActionEntry } from \"../../agent/production-agent.js\";\nimport { dataWidgetResultSchema } from \"../../data-widgets/index.js\";\nimport { getRequestRunContext } from \"../request-context.js\";\n\n// ---------------------------------------------------------------------------\n// Framework-owned \"context\" action entries: get-framework-context,\n// refresh-screen, the URL/ask-question tools, and the native data-widget\n// renderer. These are generic, template-agnostic tools registered into every\n// app's tool surface.\n// ---------------------------------------------------------------------------\n\n/*\n Verbose framework sections returned by the `get-framework-context` tool.\n * Keyed by topic so the agent can request specific sections.\n * Not template-specific — lives outside buildFrameworkPrompts().\n /\nexport const FRAMEWORK_CONTEXT_SECTIONS: Record<string, string> = {\n embeds: `### Inline Embeds\n\nYou can embed an interactive view inline in your chat reply by writing an \\`embed\\` fenced code block. The chat renderer swaps the fence for a sandboxed iframe pointing at a route inside this app.\n\nSyntax:\n\n\\`\\`\\`\\`\n\\`\\`\\`embed\nsrc: /some/path?param=value\naspect: 16/9\ntitle: Optional label\n\\`\\`\\`\n\\`\\`\\`\\`\n\nKeys:\n- \\`src\\` (required) — must be a same-origin path starting with \\`/\\`. Cross-origin URLs are blocked. No \\`javascript:\\` or \\`data:\\` URLs.\n- \\`aspect\\` (optional) — one of \\`16/9\\` (default), \\`4/3\\`, \\`3/2\\`, \\`2/1\\`, \\`21/9\\`, \\`1/1\\`.\n- \\`title\\` (optional) — accessible label / hover tooltip.\n- \\`height\\` (optional) — fixed pixel height when aspect ratio isn't a good fit.\n\nUse for charts, visualizations, previews. Don't use for simple text/tables or external sites.`,\n\n \"chat-history\": `### Chat History\n\nYou can search and restore previous chat conversations using \\`chat-history\\`:\n- \\`chat-history\\` (action: \"search\") — Search or list past chat threads by keyword. Archived threads are excluded by default; pass \\`includeArchived: true\\` to also see them.\n- \\`chat-history\\` (action: \"open\") — Open a chat thread in the UI as a new tab and focus it\n- \\`chat-history\\` (actions: \"rename\", \"pin\", \"unpin\", \"archive\") — Organize a known chat thread by ID. Archiving a thread hides it from the default chat list and search.\n\nWhen the user asks to find a previous conversation, use \\`chat-history\\` with action \"search\" first to find matching threads, then action \"open\" to restore the one they want.`,\n\n \"agent-teams\": `### Agent Teams — Orchestration\n\nYou can delegate to background sub-agents with the \\`agent-teams\\` tool:\n- \\`agent-teams\\` (action: \"spawn\") — Launch a sub-agent on a task. It runs in its own thread with a clean context while you stay available; a live preview card appears in the chat. The spawn result confirms launch only, not completion. Optionally pass a custom agent profile from \\`agents/.md\\` via the \\`agent\\` parameter.\n- \\`agent-teams\\` (action: \"status\") — Check a running sub-agent's progress.\n- \\`agent-teams\\` (action: \"read-result\") — Read a finished sub-agent's output.\n- \\`agent-teams\\` (action: \"send\") — Message a running sub-agent.\n- \\`agent-teams\\` (action: \"list\") — List sub-agent tasks.\n\nSub-agents inherit all of your template tools but cannot spawn sub-agents themselves — only you orchestrate.\n\nUser intent phrases. If the user asks you to use a \"sub-agent\" or \"background agent\", that is explicit delegation intent. Also treat phrases like \"run these in the background\", \"kick off the rest\", \"run the queued items\", \"batch run these jobs\", \"parallelize this\", or \"start the next batch\" as delegation intent when the context is a set of independent work items.\n\nSpawn is not completion. A successful \\`spawn\\` call means the sub-agent started and is running. Tell the user it started, show the task id if useful, and then use \\`status\\`/\\`list\\`/\\`read-result\\` to monitor it. Never say the delegated task \"completed\", \"ran successfully\", or \"finished\" until \\`status\\` or \\`read-result\\` reports \\`completed\\` or \\`errored\\`. If a task is still running, say that plainly.\n\nDefault to doing the work yourself in this thread. A sub-agent costs real tokens and adds a merge step, so reach for one only when delegation clearly pays for that overhead.\n\nDelegate ONE sub-agent when a task is self-contained and heavy: deep research, long multi-step content generation, or a noisy scan whose intermediate steps would clutter this thread. The sub-agent gets its own clean context and hands you back a distilled result.\n\nFan out to MULTIPLE sub-agents ONLY for units of work that are genuinely independent and don't depend on each other's decisions — e.g. research three unrelated competitors, summarize five separate threads, draft sections that don't reference one another. Each gets a distinct slice.\n\nDo NOT parallelize tightly-coupled work — one cohesive artifact, edits that must agree with each other, or anything needing a single consistent voice or style. Parallel sub-agents can't see each other's choices and their outputs will clash. For coupled work, do it yourself, or chain sub-agents one at a time, feeding each result into the next.\n\nCap fan-out: aim for 1, use up to ~3, and go beyond that only for clearly independent bulk work. More sub-agents means more tokens and a harder merge.\n\nBriefing contract. A sub-agent starts in a fresh thread and can only see the brief you give it — it cannot see this conversation or ask you to clarify before it runs. Make every brief self-contained:\n1. Objective — what \"done\" looks like, in a sentence or two.\n2. Context — the specific facts it needs from this conversation: IDs, names, the user's actual goal, constraints, prior decisions. Paste the specifics; don't assume it knows them.\n3. Output format — what to return and how (e.g. \"a 3-bullet summary with source links\", \"the drafted email body only\") so the result drops cleanly into your synthesis.\n4. Boundaries — what NOT to do, and for parallel sub-agents, which slice is theirs so they don't overlap.\n\nPut the objective and output format in \\`task\\`; put longer context in \\`instructions\\`.\n\nSynthesis discipline. After the sub-agents you depend on finish, poll \\`status\\`/\\`list\\` until they're complete, then pull each one's output with \\`read-result\\`. Do NOT paste their outputs back to back. Read all results, reconcile any disagreements, de-duplicate, and write ONE integrated answer in your own voice. If two sub-agents conflict, resolve it or flag the discrepancy explicitly rather than presenting both. When findings came from distinct investigations, briefly note which finding came from where so the user can trust the merge.`,\n\n \"recurring-jobs\": `### Recurring Jobs\n\nYou can create recurring jobs that run on a cron schedule. Jobs are resource files under \\`jobs/\\`.\n\n- \\`manage-jobs\\` (action: \"create\") — Create a new recurring job with a cron schedule and instructions\n- \\`manage-jobs\\` (action: \"list\") — List all recurring jobs and their status\n- \\`manage-jobs\\` (action: \"update\") — Update a job's schedule, instructions, or toggle enabled/disabled\n- Delete a job with the \\`resources\\` tool: \\`action: \"delete\"\\`, \\`path: \"jobs/<name>.md\"\\`\n\nConvert natural language to 5-field cron format:\n- \"every morning\" / \"daily at 9am\" → \\`0 9 * * \\`\n- \"every weekday at 9am\" → \\`0 9 * 1-5\\`\n- \"every hour\" → \\`0 * * * \\`\n- \"every monday at 9am\" → \\`0 9 * 1\\`\n\n#### Suggesting \"Save as automation\"\n\nWhen you finish a task that has obvious recurring value — daily inbox triage, weekly metrics summaries, archive sweeps, status digests, anything the user would plausibly want re-run on a fresh cadence — close the response with ONE short line offering to save it. Examples:\n\n- After \"Summarize my unread emails\": _\"Want me to run this every morning?\"_\n- After \"What's our top traffic source this week\": _\"Want a weekly digest on Mondays?\"_\n- After \"Archive emails older than 30 days\": _\"Should I run this every Sunday?\"_\n\nIf the user says yes, call \\`manage-jobs\\` (action: \"create\") with the original prompt as the job's instructions and the cadence they confirmed.\n\nDo NOT add this offer for one-shot work: lookups (find Alice, what's the schema, who reported X), single drafts/replies, navigation requests, or any task whose value is in the moment. Skip it when the prompt is already explicitly recurring (the user said \"every morning…\" — you'd be asking what they already told you). One short sentence at most; do not turn it into a list of cadence options.`,\n\n builder: `### Connecting Builder.io\n\nWhen the user asks to connect Builder.io or you hit a \"Builder not configured\" error, call the \\`connect-builder\\` tool. It renders a Connect/code-change card inline — do NOT write out multi-step setup instructions yourself. Inspect the returned \\`builderEnabled\\` flag: \\`true\\` means Builder Cloud Agents can take the code-change handoff, while \\`false\\` means this requires a code change and the user should edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like. If Builder Cloud Agents are not available for this workspace, never send the user to Builder org settings or beta settings.`,\n\n browser: `### Browser Automation\n\nYou can activate a real Chrome browser via Builder.io for tasks that need full page rendering:\n- Extracting design tokens from JS-heavy or SPA websites (computed styles, rendered colors/fonts)\n- Taking screenshots of live pages\n- Testing interactive flows on deployed URLs\n- Reading content from pages that require JavaScript execution\n\nHow to use:\n1. In local development, call \\`set-browser-control\\` with \\`{\"enabled\":true,\"backend\":\"chrome-devtools\"}\\` after confirming once with the user. In production, use \\`activate-browser\\` for Builder-provisioned Chrome.\n2. On your next action, use \\`mcp__chrome-devtools__navigate_page\\`, \\`mcp__chrome-devtools__evaluate_script\\`, \\`mcp__chrome-devtools__take_screenshot\\`, etc.\n3. If Builder is not connected, call \\`connect-builder\\` first\n\nWhen to recommend browser automation:\n- User wants to import a design system from a URL (JS-rendered sites give almost no useful data from plain HTML fetch)\n- User asks you to check how a deployed site looks or behaves\n- Any task involving reading computed/rendered page state\n- When \\`web-request\\` returns minimal/skeleton HTML from a modern SPA\n\nPrefer \\`web-request\\` for simple API calls and static pages. Use browser automation when you need the real rendered page.`,\n\n \"call-agent\": `### call-agent — External Apps Only\n\nThe \\`call-agent\\` tool sends a message to a DIFFERENT, separately-deployed app's agent (A2A protocol). It is not for calling actions within the current app.\n\nNEVER use \\`call-agent\\` to:\n- Call your own app by name\n- Perform tasks you can accomplish with your own registered tools\n\nONLY use \\`call-agent\\` when:\n- The user explicitly asks you to communicate with a different app\n- You need data that only another deployed app can provide\n- You need brand-consistent generated media and this app does not have a native generation action; call agent \"assets\" and keep returned asset IDs and URLs verbatim\n\nIf \\`call-agent\\` says a downstream agent accepted the subtask and will post its result separately, do not call that same agent again for the same subtask. Continue any remaining work and answer with the completed results you have.`,\n\n memory: `### Structured Memory\n\nYour memory index (\\`memory/MEMORY.md\\`) is loaded at the start of every conversation.\n\nTools:\n- \\`save-memory\\` — Create or update a memory (name, type, description, content)\n- \\`delete-memory\\` — Remove a memory and its index entry\n- \\`resources\\` with \\`action: \"read\"\\` and \\`path: \"memory/<name>.md\"\\` — Read the full content of a specific memory\n\nMemory types: user, feedback, project, reference\n\nWhen to save (proactively):\n- User corrects your approach → \\`feedback\\`\n- User shares preferences → \\`user\\`\n- Non-obvious pattern or gotcha → \\`feedback\\`\n- Personal context (contacts, team) → \\`user\\`\n- Project context to track → \\`project\\`\n\nRules:\n- Don't save things obvious from code or standard framework behavior\n- When updating, read first and merge — don't overwrite\n- Keep descriptions concise\n- One memory per logical topic`,\n\n \"sql-tools\": `### SQL Tools\n\nWhen database tools are enabled, \\`db-schema\\` refreshes the schema and \\`db-query\\` runs read-only SELECT queries with current user/org scoping. Raw SQL write tools are only available when the app explicitly opts into database write tools; by default, writes go through typed app actions. Some apps configure database tools as read-only or off; only use tools that are actually present in your tool list.\n\n- \\`db-schema\\` — refresh the full schema with indexes and foreign keys\n- \\`db-query\\` — run a SELECT (read-only; results already filtered to the current user/org)\n- \\`db-exec\\` — only when present: run INSERT / UPDATE / DELETE / REPLACE for scoped maintenance. For normal product data writes, use a typed app action instead.\n- \\`db-patch\\` — only when present: surgical search-and-replace on a large text column. If a typed app action exists for the resource, use that action.\n\n### When to pick which SQL tool\n- A template-specific action exists for the table → use that action (it encodes business rules and pushes live Yjs updates)\n- Read data → \\`db-query\\`. Never re-add \\`WHERE owner_email = ...\\` — scoping already applies it.\n- Raw write tools are present and no app action exists → use \\`db-exec\\` or \\`db-patch\\` only for deliberate maintenance, not normal product workflows.\n\n### External data sources vs the app database\nThe \\`db-\\` tools ONLY query the app's own SQL database. They do NOT reach external data warehouses. If the user asks about tables NOT in the schema, use the appropriate template action instead.`,\n};\n\nexport function createFrameworkContextEntry(): Record<string, ActionEntry> {\n const topicList = Object.keys(FRAMEWORK_CONTEXT_SECTIONS).join(\", \");\n return {\n \"get-framework-context\": {\n tool: {\n description: `Read detailed framework instructions for a specific capability. Available topics: ${topicList}. Call with topic=\"all\" to get everything.`,\n parameters: {\n type: \"object\" as const,\n properties: {\n topic: {\n type: \"string\",\n description: `Topic to read. One of: ${topicList}, or \"all\" for everything.`,\n },\n },\n required: [\"topic\"],\n },\n },\n run: async (args: Record<string, string>) => {\n const topic = String(args.topic ?? \"all\").toLowerCase();\n if (topic === \"all\") {\n return Object.values(FRAMEWORK_CONTEXT_SECTIONS).join(\"\\n\\n\");\n }\n const section = FRAMEWORK_CONTEXT_SECTIONS[topic];\n if (!section) {\n return `Unknown topic \"${topic}\". Available: ${topicList}`;\n }\n return section;\n },\n readOnly: true,\n },\n };\n}\n\n/\n Creates the `refresh-screen` tool. Writes a bump to `application_state`\n * under a well-known key; the client's `useDbSync` watches for this and\n * invalidates react-query caches so the on-screen UI re-fetches its data\n * without a full page reload.\n \n This is the standard way for the agent to say \"the data on the screen\n * just changed, please refresh it\" — e.g. after editing a dashboard config,\n * updating a form schema, or mutating a row that the current view renders.\n /\nexport function createRefreshScreenEntry(): Record<string, ActionEntry> {\n return {\n \"refresh-screen\": {\n // Writes __screen_refresh__ to application_state, which emits its own\n // distinct `screen-refresh` poll event. Don't double-emit a generic\n // `action` event on top of that.\n readOnly: true,\n tool: {\n description:\n \"Manually refresh the user's current screen. The framework ALREADY auto-refreshes after any successful mutating action tool call (template actions and any enabled raw DB write tools) — you do NOT need to call this after a normal action. Use it only when (a) you mutated data via a path the framework can't detect (e.g. a direct write to an external system the app mirrors), or (b) you want to pass a `scope` hint so the UI narrows which queries to refetch. The UI re-fetches its queries without a full page reload.\",\n parameters: {\n type: \"object\",\n properties: {\n scope: {\n type: \"string\",\n description:\n \"Optional hint describing what changed (e.g. 'dashboard', 'form', 'settings'). Templates may use it to narrow which queries to invalidate; if omitted, all queries are invalidated.\",\n },\n },\n },\n },\n run: async (args) => {\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n const nonce = Date.now();\n const scope = typeof args?.scope === \"string\" ? args.scope : undefined;\n await writeAppState(SCREEN_REFRESH_KEY, {\n nonce,\n ...(scope ? { scope } : {}),\n });\n return `refreshed${scope ? ` (scope: ${scope})` : \"\"}`;\n },\n },\n };\n}\n\n/* Well-known application-state key used by the refresh-screen tool. /\nconst SCREEN_REFRESH_KEY = \"__screen_refresh__\";\nconst SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nexport function appStateKeyForBrowserTab(\n key: string,\n browserTabId: unknown,\n): string {\n if (typeof browserTabId !== \"string\") return key;\n const trimmed = browserTabId.trim();\n return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? `${key}:${trimmed}` : key;\n}\n\n/\n Creates the `set-search-params` / `set-url-path` tools. Writes a one-shot\n * URL command to application_state; the client's URLSync component applies\n * it via react-router (no full page reload) and then deletes the command.\n \n This is how the agent edits URL state — filter query params, route\n * changes, hash — without needing a per-template navigate action. The\n * current URL is visible to the agent via the auto-injected `<current-url>`\n * block, which includes parsed search params.\n */\nexport function createUrlTools(): Record<string, ActionEntry> {\n return {\n \"set-search-params\": {\n // Writes __set_url__ to application_state, which the app-state watcher\n // already surfaces as a poll event. No need to double-emit.\n readOnly: true,\n tool: {\n description:\n \"Update the URL query string on the user's current page. Use this to change dashboard/list filters, search terms, or any other state the app stores in `?foo=bar` style query params. One-shot — the UI applies it in ~1s without a page reload. See the current URL + parsed search params in the auto-injected `<current-url>` block. Keys are the exact query param names as they appear in the URL (e.g. `f_pubDateStart`, not just `pubDateStart`). Set a value to null or empty string to clear that param. By default merges over existing params — pass `merge: false` to replace them all.\",\n parameters: {\n type: \"object\",\n properties: {\n params: {\n type: \"object\",\n description:\n 'Map of query param → value. Each value is a string, or null/\"\" to clear. Example: {\"f_pubDateStart\": null, \"f_cadence\": \"MONTH\"}.',\n },\n merge: {\n type: \"string\",\n description:\n '\"true\" (default) merges over existing params; \"false\" replaces them entirely.',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"params\"],\n },\n },\n run: async (args) => {\n const params = (args?.params ?? {}) as unknown as Record<\n string,\n string \| null\n >;\n const merge = (args as any)?.merge !== \"false\";\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"__set_url__\",\n getRequestRunContext()?.browserTabId,\n ),\n {\n searchParams: params,\n mergeSearchParams: merge,\n // Unique-per-write token. The client's URLSync hook dedups by this\n // so a fire-and-forget DELETE that loses its race against the next\n // polling refetch can't cause the same URL command to be applied\n // repeatedly (which caused the editor to bounce between slides\n // when an agent turn errored partway through).\n _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,\n },\n );\n const keys = Object.keys(params);\n return `set-search-params: ${keys.length} key${keys.length === 1 ? \"\" : \"s\"}${merge ? \"\" : \" (replace)\"}`;\n },\n },\n \"set-url-path\": {\n // Same as set-search-params — writes application_state, already emits\n // via the app-state watcher.\n readOnly: true,\n tool: {\n description:\n \"Navigate the user to a different pathname, optionally also setting search params. For most template-specific routing prefer the template's `navigate` action if it exists — this is the generic fallback. One-shot, applied by the client without a page reload.\",\n parameters: {\n type: \"object\",\n properties: {\n pathname: {\n type: \"string\",\n description: \"New URL pathname (e.g. '/adhoc/weekly').\",\n },\n params: {\n type: \"object\",\n description:\n 'Optional query params to set alongside the path change. String values set, null/\"\" clears.',\n },\n merge: {\n type: \"string\",\n description:\n '\"true\" (default) merges over existing params; \"false\" starts fresh.',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"pathname\"],\n },\n },\n run: async (args) => {\n const pathname = String(args?.pathname ?? \"\");\n if (!pathname.startsWith(\"/\")) {\n return \"Error: pathname must start with '/'.\";\n }\n const params = (args?.params ?? {}) as unknown as Record<\n string,\n string \| null\n >;\n const merge = (args as any)?.merge !== \"false\";\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"__set_url__\",\n getRequestRunContext()?.browserTabId,\n ),\n {\n pathname,\n searchParams: params,\n mergeSearchParams: merge,\n // See note in set-search-params: unique-per-write dedup token so a\n // race between GET and consume-DELETE in URLSync can't re-apply\n // this command.\n _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,\n },\n );\n return `set-url-path: ${pathname}`;\n },\n },\n \"ask-question\": {\n tool: {\n description:\n \"Ask the user a multiple-choice clarifying question and render it inline in the chat. Use this ONLY when you are genuinely blocked on a decision you cannot resolve from context and a wrong guess would be costly — an ambiguous metric, date range, or grain; a real fork in approach. Present 2-5 concrete options and mark the most likely one recommended. Do NOT use it for confirmations, for things the user already specified, or to dodge easy work you could just do. Ask at most once per turn. Calling this yields the turn: stop and wait for the user's answer.\",\n parameters: {\n type: \"object\",\n properties: {\n question: {\n type: \"string\",\n description:\n \"The complete question to ask the user. Clear, specific, ends with a question mark.\",\n },\n header: {\n type: \"string\",\n description:\n 'Optional very short label (max ~12 chars) shown as a chip/heading above the question, e.g. \"Date range\", \"Approach\", \"Library\".',\n },\n options: {\n type: \"string\",\n description:\n 'A JSON array of 2-4 distinct, mutually-exclusive options (unless `allowMultiple` is true), each `{ \"label\": string, \"value\"?: string, \"description\"?: string, \"preview\"?: string, \"recommended\"?: boolean }`. `label` is 1-5 words; `description` explains the trade-off; `preview` is optional content (mockup, code snippet, short comparison) rendered under the option. `value` defaults to `label` when omitted. Mark the most likely option `\"recommended\": true`. Do NOT add an \"Other\" option — free text is provided automatically when `allowFreeText` is on.',\n },\n allowFreeText: {\n type: \"string\",\n description:\n 'Whether the user may also type a free-text \"Other\" answer. \"true\" (default) or \"false\".',\n enum: [\"true\", \"false\"],\n },\n allowMultiple: {\n type: \"string\",\n description:\n 'Whether the user may select more than one option (multi-select). \"true\" or \"false\" (default).',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"question\", \"options\"],\n },\n },\n run: async (args) => {\n const question = String(args?.question ?? \"\").trim();\n if (!question) return \"Error: 'question' is required.\";\n const header = String(args?.header ?? \"\").trim();\n const allowMultiple = String(args?.allowMultiple ?? \"\") === \"true\";\n const allowFreeText = String(args?.allowFreeText ?? \"true\") !== \"false\";\n\n let parsedOptions: unknown;\n try {\n parsedOptions = JSON.parse(String(args?.options ?? \"[]\"));\n } catch {\n return \"Error: 'options' must be a JSON array of { label, value?, description?, recommended? }.\";\n }\n if (!Array.isArray(parsedOptions) \|\| parsedOptions.length === 0) {\n return \"Error: 'options' must be a non-empty JSON array of { label, value?, description?, recommended? }.\";\n }\n\n type AskOption = {\n label: string;\n value: string;\n description?: string;\n preview?: string;\n recommended?: boolean;\n };\n const options = parsedOptions\n .map((raw): AskOption \| null => {\n const opt = (raw ?? {}) as Record<string, unknown>;\n const label =\n typeof opt.label === \"string\" && opt.label.trim()\n ? opt.label.trim()\n : typeof opt.value === \"string\"\n ? String(opt.value).trim()\n : \"\";\n if (!label) return null;\n const value =\n typeof opt.value === \"string\" && opt.value.trim()\n ? opt.value.trim()\n : label;\n const option: AskOption = { label, value };\n if (typeof opt.description === \"string\" && opt.description.trim()) {\n option.description = opt.description.trim();\n }\n if (typeof opt.preview === \"string\" && opt.preview.trim()) {\n option.preview = opt.preview;\n }\n if (opt.recommended === true) option.recommended = true;\n return option;\n })\n .filter((opt): opt is AskOption => opt !== null);\n if (options.length === 0) {\n return \"Error: 'options' must contain at least one option with a label.\";\n }\n\n // Shape must match the GuidedQuestionFlow renderer in\n // client/guided-questions.tsx: a `text-options` question whose options\n // carry `value`, with `multiSelect` for multi-pick and `allowOther` for\n // free text. The renderer otherwise injects \"Explore\"/\"Decide\" options,\n // which would be noise for a focused clarifying question, so disable them.\n const payload = {\n questions: [\n {\n id: \"q1\",\n type: \"text-options\" as const,\n question,\n ...(header ? { header } : {}),\n required: !allowFreeText,\n multiSelect: allowMultiple,\n allowOther: allowFreeText,\n includeExplore: false,\n includeDecide: false,\n options,\n },\n ],\n };\n\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"guided-questions\",\n getRequestRunContext()?.browserTabId,\n ),\n payload,\n );\n return \"Asked the user a clarifying question and rendered it in the chat. Stop here and wait for their answer — do not proceed or assume an answer.\";\n },\n },\n };\n}\n\nexport function createDataWidgetActionEntries(): Record<string, ActionEntry> {\n return {\n \"render-data-widget\": {\n readOnly: true,\n parallelSafe: true,\n chatUI: {\n renderer: ACTION_CHAT_UI_DATA_WIDGET_RENDERER,\n title: \"Data widget\",\n description: \"Render a validated native data table or chart in chat.\",\n },\n tool: {\n description:\n \"Render a native Agent-Native chat data widget from compact, real data you already retrieved or the user provided. Use this for in-chat tables, charts, graphs, trends, and compact reports when no domain-specific action already returns a native widget. Never fabricate rows or metrics just to make a chart.\",\n parameters: {\n type: \"object\",\n properties: {\n widget: {\n type: \"string\",\n enum: [\"data-table\", \"data-chart\", \"data-insights\"],\n description:\n \"Widget kind. Use data-chart for a chart, data-table for a table, or data-insights for a combined summary/chart/table card.\",\n },\n widgetId: {\n type: \"string\",\n description: \"Optional stable widget identifier.\",\n },\n title: {\n type: \"string\",\n description: \"Optional widget title.\",\n },\n summary: {\n type: \"object\",\n description:\n \"Optional scalar summary values for data-insights cards.\",\n },\n display: {\n type: \"object\",\n description:\n \"Optional display metadata: title, description, primaryAction.\",\n },\n table: {\n type: \"object\",\n description:\n \"For data-table/data-insights: { title?, columns: [{ key, label, align? }], rows, totalRows?, sampledRows?, truncated? }.\",\n },\n chartSeries: {\n type: \"object\",\n description:\n \"For data-chart/data-insights: { type: 'bar'\|'line'\|'area', title?, xKey, series: [{ key, label, color? }], data, sampled? }.\",\n },\n },\n required: [\"widget\"],\n },\n },\n run: async (args) => dataWidgetResultSchema.parse(args),\n },\n };\n}\n"]}
1	+ {"version":3,"file":"context-tools.js","sourceRoot":"","sources":["../../../src/server/agent-chat/context-tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { ACTION_CHAT_UI_DATA_WIDGET_RENDERER } from \"../../action-ui.js\";\nimport type { ActionEntry } from \"../../agent/production-agent.js\";\nimport { dataWidgetResultSchema } from \"../../data-widgets/index.js\";\nimport { getRequestRunContext } from \"../request-context.js\";\n\n// ---------------------------------------------------------------------------\n// Framework-owned \"context\" action entries: get-framework-context,\n// refresh-screen, the URL/ask-question tools, and the native data-widget\n// renderer. These are generic, template-agnostic tools registered into every\n// app's tool surface.\n// ---------------------------------------------------------------------------\n\n/*\n Verbose framework sections returned by the `get-framework-context` tool.\n * Keyed by topic so the agent can request specific sections.\n * Not template-specific — lives outside buildFrameworkPrompts().\n /\nexport const FRAMEWORK_CONTEXT_SECTIONS: Record<string, string> = {\n embeds: `### Inline Embeds\n\nYou can embed an interactive view inline in your chat reply by writing an \\`embed\\` fenced code block. The chat renderer swaps the fence for a sandboxed iframe pointing at a route inside this app.\n\nSyntax:\n\n\\`\\`\\`\\`\n\\`\\`\\`embed\nsrc: /some/path?param=value\naspect: 16/9\ntitle: Optional label\n\\`\\`\\`\n\\`\\`\\`\\`\n\nKeys:\n- \\`src\\` (required) — must be a same-origin path starting with \\`/\\`. Cross-origin URLs are blocked. No \\`javascript:\\` or \\`data:\\` URLs.\n- \\`aspect\\` (optional) — one of \\`16/9\\` (default), \\`4/3\\`, \\`3/2\\`, \\`2/1\\`, \\`21/9\\`, \\`1/1\\`.\n- \\`title\\` (optional) — accessible label / hover tooltip.\n- \\`height\\` (optional) — fixed pixel height when aspect ratio isn't a good fit.\n\nUse for charts, visualizations, previews. Don't use for simple text/tables or external sites.`,\n\n \"chat-history\": `### Chat History\n\nYou can search and restore previous chat conversations using \\`chat-history\\`:\n- \\`chat-history\\` (action: \"search\") — Search or list past chat threads by keyword. Archived threads are excluded by default; pass \\`includeArchived: true\\` to also see them.\n- \\`chat-history\\` (action: \"open\") — Open a chat thread in the UI as a new tab and focus it\n- \\`chat-history\\` (actions: \"rename\", \"pin\", \"unpin\", \"archive\") — Organize a known chat thread by ID. Archiving a thread hides it from the default chat list and search.\n\nWhen the user asks to find a previous conversation, use \\`chat-history\\` with action \"search\" first to find matching threads, then action \"open\" to restore the one they want.`,\n\n \"agent-teams\": `### Agent Teams — Orchestration\n\nYou can delegate to background sub-agents with the \\`agent-teams\\` tool:\n- \\`agent-teams\\` (action: \"spawn\") — Launch a sub-agent on a task. It runs in its own thread with a clean context while you stay available; a live preview card appears in the chat. The spawn result confirms launch only, not completion. Optionally pass a custom agent profile from \\`agents/.md\\` via the \\`agent\\` parameter.\n- \\`agent-teams\\` (action: \"status\") — Check a running sub-agent's progress.\n- \\`agent-teams\\` (action: \"read-result\") — Read a finished sub-agent's output.\n- \\`agent-teams\\` (action: \"send\") — Message a running sub-agent.\n- \\`agent-teams\\` (action: \"list\") — List sub-agent tasks.\n\nSub-agents inherit all of your template tools but cannot spawn sub-agents themselves — only you orchestrate.\n\nUser intent phrases. If the user asks you to use a \"sub-agent\" or \"background agent\", that is explicit delegation intent. Also treat phrases like \"run these in the background\", \"kick off the rest\", \"run the queued items\", \"batch run these jobs\", \"parallelize this\", or \"start the next batch\" as delegation intent when the context is a set of independent work items.\n\nSpawn is not completion. A successful \\`spawn\\` call means the sub-agent started and is running. Tell the user it started, show the task id if useful, and then use \\`status\\`/\\`list\\`/\\`read-result\\` to monitor it. Never say the delegated task \"completed\", \"ran successfully\", or \"finished\" until \\`status\\` or \\`read-result\\` reports \\`completed\\` or \\`errored\\`. If a task is still running, say that plainly.\n\nDefault to doing the work yourself in this thread. A sub-agent costs real tokens and adds a merge step, so reach for one only when delegation clearly pays for that overhead.\n\nDelegate ONE sub-agent when a task is self-contained and heavy: deep research, long multi-step content generation, or a noisy scan whose intermediate steps would clutter this thread. The sub-agent gets its own clean context and hands you back a distilled result.\n\nFan out to MULTIPLE sub-agents ONLY for units of work that are genuinely independent and don't depend on each other's decisions — e.g. research three unrelated competitors, summarize five separate threads, draft sections that don't reference one another. Each gets a distinct slice.\n\nDo NOT parallelize tightly-coupled work — one cohesive artifact, edits that must agree with each other, or anything needing a single consistent voice or style. Parallel sub-agents can't see each other's choices and their outputs will clash. For coupled work, do it yourself, or chain sub-agents one at a time, feeding each result into the next.\n\nCap fan-out: aim for 1, use up to ~3, and go beyond that only for clearly independent bulk work. More sub-agents means more tokens and a harder merge.\n\nBriefing contract. A sub-agent starts in a fresh thread and can only see the brief you give it — it cannot see this conversation or ask you to clarify before it runs. Make every brief self-contained:\n1. Objective — what \"done\" looks like, in a sentence or two.\n2. Context — the specific facts it needs from this conversation: IDs, names, the user's actual goal, constraints, prior decisions. Paste the specifics; don't assume it knows them.\n3. Output format — what to return and how (e.g. \"a 3-bullet summary with source links\", \"the drafted email body only\") so the result drops cleanly into your synthesis.\n4. Boundaries — what NOT to do, and for parallel sub-agents, which slice is theirs so they don't overlap.\n\nPut the objective and output format in \\`task\\`; put longer context in \\`instructions\\`.\n\nSynthesis discipline. After the sub-agents you depend on finish, poll \\`status\\`/\\`list\\` until they're complete, then pull each one's output with \\`read-result\\`. Do NOT paste their outputs back to back. Read all results, reconcile any disagreements, de-duplicate, and write ONE integrated answer in your own voice. If two sub-agents conflict, resolve it or flag the discrepancy explicitly rather than presenting both. When findings came from distinct investigations, briefly note which finding came from where so the user can trust the merge.`,\n\n \"recurring-jobs\": `### Recurring Jobs\n\nYou can create recurring jobs that run on a cron schedule. Jobs are resource files under \\`jobs/\\`.\n\n- \\`manage-jobs\\` (action: \"create\") — Create a new recurring job with a cron schedule and instructions\n- \\`manage-jobs\\` (action: \"list\") — List all recurring jobs and their status\n- \\`manage-jobs\\` (action: \"update\") — Update a job's schedule, instructions, or toggle enabled/disabled\n- Delete a job with the \\`resources\\` tool: \\`action: \"delete\"\\`, \\`path: \"jobs/<name>.md\"\\`\n\nConvert natural language to 5-field cron format:\n- \"every morning\" / \"daily at 9am\" → \\`0 9 * * \\`\n- \"every weekday at 9am\" → \\`0 9 * 1-5\\`\n- \"every hour\" → \\`0 * * * \\`\n- \"every monday at 9am\" → \\`0 9 * 1\\`\n\n#### Suggesting \"Save as automation\"\n\nWhen you finish a task that has obvious recurring value — daily inbox triage, weekly metrics summaries, archive sweeps, status digests, anything the user would plausibly want re-run on a fresh cadence — close the response with ONE short line offering to save it. Examples:\n\n- After \"Summarize my unread emails\": _\"Want me to run this every morning?\"_\n- After \"What's our top traffic source this week\": _\"Want a weekly digest on Mondays?\"_\n- After \"Archive emails older than 30 days\": _\"Should I run this every Sunday?\"_\n\nIf the user says yes, call \\`manage-jobs\\` (action: \"create\") with the original prompt as the job's instructions and the cadence they confirmed.\n\nDo NOT add this offer for one-shot work: lookups (find Alice, what's the schema, who reported X), single drafts/replies, navigation requests, or any task whose value is in the moment. Skip it when the prompt is already explicitly recurring (the user said \"every morning…\" — you'd be asking what they already told you). One short sentence at most; do not turn it into a list of cadence options.`,\n\n builder: `### Connecting Builder.io\n\nWhen the user asks to connect Builder.io or you hit a \"Builder not configured\" error, call the \\`connect-builder\\` tool. It renders a Connect/code-change card inline — do NOT write out multi-step setup instructions yourself. Inspect the returned \\`builderEnabled\\` flag: \\`true\\` means Builder Cloud Agents can take the code-change handoff, while \\`false\\` means this requires a code change and the user should edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like. If Builder Cloud Agents are not available for this workspace, never send the user to Builder org settings or beta settings.`,\n\n browser: `### Browser Automation\n\nYou can activate a real Chrome browser via Builder.io for tasks that need full page rendering:\n- Extracting design tokens from JS-heavy or SPA websites (computed styles, rendered colors/fonts)\n- Taking screenshots of live pages\n- Testing interactive flows on deployed URLs\n- Reading content from pages that require JavaScript execution\n\nHow to use:\n1. In local development, call \\`set-browser-control\\` with \\`{\"enabled\":true,\"backend\":\"chrome-devtools\"}\\` after confirming once with the user. In production, use \\`activate-browser\\` for Builder-provisioned Chrome.\n2. On your next action, use \\`mcp__chrome-devtools__navigate_page\\`, \\`mcp__chrome-devtools__evaluate_script\\`, \\`mcp__chrome-devtools__take_screenshot\\`, etc.\n3. If Builder is not connected, call \\`connect-builder\\` first\n\nWhen to recommend browser automation:\n- User wants to import a design system from a URL (JS-rendered sites give almost no useful data from plain HTML fetch)\n- User asks you to check how a deployed site looks or behaves\n- Any task involving reading computed/rendered page state\n- When \\`web-request\\` returns minimal/skeleton HTML from a modern SPA\n\nPrefer \\`web-request\\` for simple API calls and static pages. Use browser automation when you need the real rendered page.`,\n\n \"call-agent\": `### call-agent — External Apps Only\n\nThe \\`call-agent\\` tool sends a message to a DIFFERENT, separately-deployed app's agent (A2A protocol). It is not for calling actions within the current app.\n\nNEVER use \\`call-agent\\` to:\n- Call your own app by name\n- Perform tasks you can accomplish with your own registered tools\n\nONLY use \\`call-agent\\` when:\n- The user explicitly asks you to communicate with a different app\n- You need data that only another deployed app can provide\n- You need brand-consistent generated media and this app does not have a native generation action; call agent \"assets\" and keep returned asset IDs and URLs verbatim\n\nIf \\`call-agent\\` says a downstream agent accepted the subtask and will post its result separately, do not call that same agent again for the same subtask. Continue any remaining work and answer with the completed results you have.`,\n\n memory: `### Structured Memory\n\nYour memory index (\\`memory/MEMORY.md\\`) is loaded at the start of every conversation.\n\nTools:\n- \\`save-memory\\` — Create or update a memory (name, type, description, content)\n- \\`delete-memory\\` — Remove a memory and its index entry\n- \\`resources\\` with \\`action: \"read\"\\` and \\`path: \"memory/<name>.md\"\\` — Read the full content of a specific memory\n\nMemory types: user, feedback, project, reference\n\nWhen to save (proactively):\n- User corrects your approach → \\`feedback\\`\n- User shares preferences → \\`user\\`\n- Non-obvious pattern or gotcha → \\`feedback\\`\n- Personal context (contacts, team) → \\`user\\`\n- Project context to track → \\`project\\`\n\nRules:\n- Don't save things obvious from code or standard framework behavior\n- When updating, read first and merge — don't overwrite\n- Keep descriptions concise\n- One memory per logical topic`,\n\n \"sql-tools\": `### SQL Tools\n\nWhen database tools are enabled, \\`db-schema\\` refreshes the schema and \\`db-query\\` runs read-only SELECT queries with current user/org scoping. Raw SQL write tools are only available when the app explicitly opts into database write tools; by default, writes go through typed app actions. Some apps configure database tools as read-only or off; only use tools that are actually present in your tool list.\n\n- \\`db-schema\\` — refresh the full schema with indexes and foreign keys\n- \\`db-query\\` — run a SELECT (read-only; results already filtered to the current user/org)\n- \\`db-exec\\` — only when present: run INSERT / UPDATE / DELETE / REPLACE for scoped maintenance. For normal product data writes, use a typed app action instead.\n- \\`db-patch\\` — only when present: surgical search-and-replace on a large text column. If a typed app action exists for the resource, use that action.\n\n### When to pick which SQL tool\n- A template-specific action exists for the table → use that action (it encodes business rules and pushes live Yjs updates)\n- Read data → \\`db-query\\`. Never re-add \\`WHERE owner_email = ...\\` — scoping already applies it.\n- Raw write tools are present and no app action exists → use \\`db-exec\\` or \\`db-patch\\` only for deliberate maintenance, not normal product workflows.\n\n### External data sources vs the app database\nThe \\`db-\\` tools ONLY query the app's own SQL database. They do NOT reach external data warehouses. If the user asks about tables NOT in the schema, use the appropriate template action instead.`,\n};\n\nexport function createFrameworkContextEntry(): Record<string, ActionEntry> {\n const topicList = Object.keys(FRAMEWORK_CONTEXT_SECTIONS).join(\", \");\n return {\n \"get-framework-context\": {\n tool: {\n description: `Read detailed framework instructions for a specific capability. Available topics: ${topicList}. Call with topic=\"all\" to get everything.`,\n parameters: {\n type: \"object\" as const,\n properties: {\n topic: {\n type: \"string\",\n description: `Topic to read. One of: ${topicList}, or \"all\" for everything.`,\n },\n },\n required: [\"topic\"],\n },\n },\n run: async (args: Record<string, string>) => {\n const topic = String(args.topic ?? \"all\").toLowerCase();\n if (topic === \"all\") {\n return Object.values(FRAMEWORK_CONTEXT_SECTIONS).join(\"\\n\\n\");\n }\n const section = FRAMEWORK_CONTEXT_SECTIONS[topic];\n if (!section) {\n return `Unknown topic \"${topic}\". Available: ${topicList}`;\n }\n return section;\n },\n readOnly: true,\n },\n };\n}\n\n/\n Creates the `refresh-screen` tool. Writes a bump to `application_state`\n * under a well-known key; the client's `useDbSync` watches for this and\n * invalidates react-query caches so the on-screen UI re-fetches its data\n * without a full page reload.\n \n This is the standard way for the agent to say \"the data on the screen\n * just changed, please refresh it\" — e.g. after editing a dashboard config,\n * updating a form schema, or mutating a row that the current view renders.\n /\nexport function createRefreshScreenEntry(): Record<string, ActionEntry> {\n return {\n \"refresh-screen\": {\n // Writes __screen_refresh__ to application_state, which emits its own\n // distinct `screen-refresh` poll event. Don't double-emit a generic\n // `action` event on top of that.\n readOnly: true,\n // Refetching volatile on-screen state is the entire point of this\n // tool — an identical repeat call (even with the same scope) is a\n // legitimate re-refresh, not a redundant read to skip.\n dedupe: false,\n tool: {\n description:\n \"Manually refresh the user's current screen. The framework ALREADY auto-refreshes after any successful mutating action tool call (template actions and any enabled raw DB write tools) — you do NOT need to call this after a normal action. Use it only when (a) you mutated data via a path the framework can't detect (e.g. a direct write to an external system the app mirrors), or (b) you want to pass a `scope` hint so the UI narrows which queries to refetch. The UI re-fetches its queries without a full page reload.\",\n parameters: {\n type: \"object\",\n properties: {\n scope: {\n type: \"string\",\n description:\n \"Optional hint describing what changed (e.g. 'dashboard', 'form', 'settings'). Templates may use it to narrow which queries to invalidate; if omitted, all queries are invalidated.\",\n },\n },\n },\n },\n run: async (args) => {\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n const nonce = Date.now();\n const scope = typeof args?.scope === \"string\" ? args.scope : undefined;\n await writeAppState(SCREEN_REFRESH_KEY, {\n nonce,\n ...(scope ? { scope } : {}),\n });\n return `refreshed${scope ? ` (scope: ${scope})` : \"\"}`;\n },\n },\n };\n}\n\n/* Well-known application-state key used by the refresh-screen tool. /\nconst SCREEN_REFRESH_KEY = \"__screen_refresh__\";\nconst SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nexport function appStateKeyForBrowserTab(\n key: string,\n browserTabId: unknown,\n): string {\n if (typeof browserTabId !== \"string\") return key;\n const trimmed = browserTabId.trim();\n return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? `${key}:${trimmed}` : key;\n}\n\n/\n Creates the `set-search-params` / `set-url-path` tools. Writes a one-shot\n * URL command to application_state; the client's URLSync component applies\n * it via react-router (no full page reload) and then deletes the command.\n \n This is how the agent edits URL state — filter query params, route\n * changes, hash — without needing a per-template navigate action. The\n * current URL is visible to the agent via the auto-injected `<current-url>`\n * block, which includes parsed search params.\n */\nexport function createUrlTools(): Record<string, ActionEntry> {\n return {\n \"set-search-params\": {\n // Writes __set_url__ to application_state, which the app-state watcher\n // already surfaces as a poll event. No need to double-emit.\n readOnly: true,\n tool: {\n description:\n \"Update the URL query string on the user's current page. Use this to change dashboard/list filters, search terms, or any other state the app stores in `?foo=bar` style query params. One-shot — the UI applies it in ~1s without a page reload. See the current URL + parsed search params in the auto-injected `<current-url>` block. Keys are the exact query param names as they appear in the URL (e.g. `f_pubDateStart`, not just `pubDateStart`). Set a value to null or empty string to clear that param. By default merges over existing params — pass `merge: false` to replace them all.\",\n parameters: {\n type: \"object\",\n properties: {\n params: {\n type: \"object\",\n description:\n 'Map of query param → value. Each value is a string, or null/\"\" to clear. Example: {\"f_pubDateStart\": null, \"f_cadence\": \"MONTH\"}.',\n },\n merge: {\n type: \"string\",\n description:\n '\"true\" (default) merges over existing params; \"false\" replaces them entirely.',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"params\"],\n },\n },\n run: async (args) => {\n const params = (args?.params ?? {}) as unknown as Record<\n string,\n string \| null\n >;\n const merge = (args as any)?.merge !== \"false\";\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"__set_url__\",\n getRequestRunContext()?.browserTabId,\n ),\n {\n searchParams: params,\n mergeSearchParams: merge,\n // Unique-per-write token. The client's URLSync hook dedups by this\n // so a fire-and-forget DELETE that loses its race against the next\n // polling refetch can't cause the same URL command to be applied\n // repeatedly (which caused the editor to bounce between slides\n // when an agent turn errored partway through).\n _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,\n },\n );\n const keys = Object.keys(params);\n return `set-search-params: ${keys.length} key${keys.length === 1 ? \"\" : \"s\"}${merge ? \"\" : \" (replace)\"}`;\n },\n },\n \"set-url-path\": {\n // Same as set-search-params — writes application_state, already emits\n // via the app-state watcher.\n readOnly: true,\n tool: {\n description:\n \"Navigate the user to a different pathname, optionally also setting search params. For most template-specific routing prefer the template's `navigate` action if it exists — this is the generic fallback. One-shot, applied by the client without a page reload.\",\n parameters: {\n type: \"object\",\n properties: {\n pathname: {\n type: \"string\",\n description: \"New URL pathname (e.g. '/adhoc/weekly').\",\n },\n params: {\n type: \"object\",\n description:\n 'Optional query params to set alongside the path change. String values set, null/\"\" clears.',\n },\n merge: {\n type: \"string\",\n description:\n '\"true\" (default) merges over existing params; \"false\" starts fresh.',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"pathname\"],\n },\n },\n run: async (args) => {\n const pathname = String(args?.pathname ?? \"\");\n if (!pathname.startsWith(\"/\")) {\n return \"Error: pathname must start with '/'.\";\n }\n const params = (args?.params ?? {}) as unknown as Record<\n string,\n string \| null\n >;\n const merge = (args as any)?.merge !== \"false\";\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"__set_url__\",\n getRequestRunContext()?.browserTabId,\n ),\n {\n pathname,\n searchParams: params,\n mergeSearchParams: merge,\n // See note in set-search-params: unique-per-write dedup token so a\n // race between GET and consume-DELETE in URLSync can't re-apply\n // this command.\n _writeId: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,\n },\n );\n return `set-url-path: ${pathname}`;\n },\n },\n \"ask-question\": {\n tool: {\n description:\n \"Ask the user a multiple-choice clarifying question and render it inline in the chat. Use this ONLY when you are genuinely blocked on a decision you cannot resolve from context and a wrong guess would be costly — an ambiguous metric, date range, or grain; a real fork in approach. Present 2-5 concrete options and mark the most likely one recommended. Do NOT use it for confirmations, for things the user already specified, or to dodge easy work you could just do. Ask at most once per turn. Calling this yields the turn: stop and wait for the user's answer.\",\n parameters: {\n type: \"object\",\n properties: {\n question: {\n type: \"string\",\n description:\n \"The complete question to ask the user. Clear, specific, ends with a question mark.\",\n },\n header: {\n type: \"string\",\n description:\n 'Optional very short label (max ~12 chars) shown as a chip/heading above the question, e.g. \"Date range\", \"Approach\", \"Library\".',\n },\n options: {\n type: \"string\",\n description:\n 'A JSON array of 2-4 distinct, mutually-exclusive options (unless `allowMultiple` is true), each `{ \"label\": string, \"value\"?: string, \"description\"?: string, \"preview\"?: string, \"recommended\"?: boolean }`. `label` is 1-5 words; `description` explains the trade-off; `preview` is optional content (mockup, code snippet, short comparison) rendered under the option. `value` defaults to `label` when omitted. Mark the most likely option `\"recommended\": true`. Do NOT add an \"Other\" option — free text is provided automatically when `allowFreeText` is on.',\n },\n allowFreeText: {\n type: \"string\",\n description:\n 'Whether the user may also type a free-text \"Other\" answer. \"true\" (default) or \"false\".',\n enum: [\"true\", \"false\"],\n },\n allowMultiple: {\n type: \"string\",\n description:\n 'Whether the user may select more than one option (multi-select). \"true\" or \"false\" (default).',\n enum: [\"true\", \"false\"],\n },\n },\n required: [\"question\", \"options\"],\n },\n },\n run: async (args) => {\n const question = String(args?.question ?? \"\").trim();\n if (!question) return \"Error: 'question' is required.\";\n const header = String(args?.header ?? \"\").trim();\n const allowMultiple = String(args?.allowMultiple ?? \"\") === \"true\";\n const allowFreeText = String(args?.allowFreeText ?? \"true\") !== \"false\";\n\n let parsedOptions: unknown;\n try {\n parsedOptions = JSON.parse(String(args?.options ?? \"[]\"));\n } catch {\n return \"Error: 'options' must be a JSON array of { label, value?, description?, recommended? }.\";\n }\n if (!Array.isArray(parsedOptions) \|\| parsedOptions.length === 0) {\n return \"Error: 'options' must be a non-empty JSON array of { label, value?, description?, recommended? }.\";\n }\n\n type AskOption = {\n label: string;\n value: string;\n description?: string;\n preview?: string;\n recommended?: boolean;\n };\n const options = parsedOptions\n .map((raw): AskOption \| null => {\n const opt = (raw ?? {}) as Record<string, unknown>;\n const label =\n typeof opt.label === \"string\" && opt.label.trim()\n ? opt.label.trim()\n : typeof opt.value === \"string\"\n ? String(opt.value).trim()\n : \"\";\n if (!label) return null;\n const value =\n typeof opt.value === \"string\" && opt.value.trim()\n ? opt.value.trim()\n : label;\n const option: AskOption = { label, value };\n if (typeof opt.description === \"string\" && opt.description.trim()) {\n option.description = opt.description.trim();\n }\n if (typeof opt.preview === \"string\" && opt.preview.trim()) {\n option.preview = opt.preview;\n }\n if (opt.recommended === true) option.recommended = true;\n return option;\n })\n .filter((opt): opt is AskOption => opt !== null);\n if (options.length === 0) {\n return \"Error: 'options' must contain at least one option with a label.\";\n }\n\n // Shape must match the GuidedQuestionFlow renderer in\n // client/guided-questions.tsx: a `text-options` question whose options\n // carry `value`, with `multiSelect` for multi-pick and `allowOther` for\n // free text. The renderer otherwise injects \"Explore\"/\"Decide\" options,\n // which would be noise for a focused clarifying question, so disable them.\n const payload = {\n questions: [\n {\n id: \"q1\",\n type: \"text-options\" as const,\n question,\n ...(header ? { header } : {}),\n required: !allowFreeText,\n multiSelect: allowMultiple,\n allowOther: allowFreeText,\n includeExplore: false,\n includeDecide: false,\n options,\n },\n ],\n };\n\n const { writeAppState } =\n await import(\"../../application-state/script-helpers.js\");\n await writeAppState(\n appStateKeyForBrowserTab(\n \"guided-questions\",\n getRequestRunContext()?.browserTabId,\n ),\n payload,\n );\n return \"Asked the user a clarifying question and rendered it in the chat. Stop here and wait for their answer — do not proceed or assume an answer.\";\n },\n },\n };\n}\n\nexport function createDataWidgetActionEntries(): Record<string, ActionEntry> {\n return {\n \"render-data-widget\": {\n readOnly: true,\n parallelSafe: true,\n chatUI: {\n renderer: ACTION_CHAT_UI_DATA_WIDGET_RENDERER,\n title: \"Data widget\",\n description: \"Render a validated native data table or chart in chat.\",\n },\n tool: {\n description:\n \"Render a native Agent-Native chat data widget from compact, real data you already retrieved or the user provided. Use this for in-chat tables, charts, graphs, trends, and compact reports when no domain-specific action already returns a native widget. Never fabricate rows or metrics just to make a chart.\",\n parameters: {\n type: \"object\",\n properties: {\n widget: {\n type: \"string\",\n enum: [\"data-table\", \"data-chart\", \"data-insights\"],\n description:\n \"Widget kind. Use data-chart for a chart, data-table for a table, or data-insights for a combined summary/chart/table card.\",\n },\n widgetId: {\n type: \"string\",\n description: \"Optional stable widget identifier.\",\n },\n title: {\n type: \"string\",\n description: \"Optional widget title.\",\n },\n summary: {\n type: \"object\",\n description:\n \"Optional scalar summary values for data-insights cards.\",\n },\n display: {\n type: \"object\",\n description:\n \"Optional display metadata: title, description, primaryAction.\",\n },\n table: {\n type: \"object\",\n description:\n \"For data-table/data-insights: { title?, columns: [{ key, label, align? }], rows, totalRows?, sampledRows?, truncated? }.\",\n },\n chartSeries: {\n type: \"object\",\n description:\n \"For data-chart/data-insights: { type: 'bar'\|'line'\|'area', title?, xKey, series: [{ key, label, color? }], data, sampled? }.\",\n },\n },\n required: [\"widget\"],\n },\n },\n run: async (args) => dataWidgetResultSchema.parse(args),\n },\n };\n}\n"]}

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.4",
+  "version": "0.101.6",
   "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": {