@agent-native/core 0.7.1 → 0.7.2

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

@@ -1,4 +1,5 @@
 import { runWithRequestContext, getRequestOrgId } from "./request-context.js";
+import { getSetting, putSetting } from "../settings/store.js";
 import { getH3App } from "./framework-request-handler.js";
 import { createProductionAgentHandler, runAgentLoop, actionsToEngineTools, getActiveRunForThreadAsync, abortRun, subscribeToRun, } from "../agent/production-agent.js";
 import { resolveEngine, createAnthropicEngine } from "../agent/engine/index.js";
@@ -28,9 +29,10 @@ async function lazyFs() {
  * Wraps a core CLI script (that writes to console.log) as a ActionEntry
  * by capturing stdout.
  */
-function wrapCliScript(tool, cliDefault) {
+function wrapCliScript(tool, cliDefault, opts) {
     return {
         tool,
+        ...(opts?.readOnly ? { readOnly: true } : {}),
         run: async (args) => {
             const cliArgs = [];
             for (const [k, v] of Object.entries(args)) {
@@ -72,6 +74,254 @@ function wrapCliScript(tool, cliDefault) {
         },
     };
 }
+/**
+ * Creates the `refresh-screen` tool. Writes a bump to `application_state`
+ * under a well-known key; the client's `useDbSync` watches for this and
+ * invalidates react-query caches so the on-screen UI re-fetches its data
+ * without a full page reload.
+ *
+ * This is the standard way for the agent to say "the data on the screen
+ * just changed, please refresh it" — e.g. after editing a dashboard config,
+ * updating a form schema, or mutating a row that the current view renders.
+ */
+function createRefreshScreenEntry() {
+    return {
+        "refresh-screen": {
+            // Writes __screen_refresh__ to application_state, which emits its own
+            // distinct `screen-refresh` poll event. Don't double-emit a generic
+            // `action` event on top of that.
+            readOnly: true,
+            tool: {
+                description: "Manually refresh the user's current screen. The framework ALREADY auto-refreshes after any successful mutating action tool call (template actions, db-exec, db-patch) — 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: {
+                    type: "object",
+                    properties: {
+                        scope: {
+                            type: "string",
+                            description: "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.",
+                        },
+                    },
+                },
+            },
+            run: async (args) => {
+                const { writeAppState } = await import("../application-state/script-helpers.js");
+                const nonce = Date.now();
+                const scope = typeof args?.scope === "string" ? args.scope : undefined;
+                await writeAppState(SCREEN_REFRESH_KEY, {
+                    nonce,
+                    ...(scope ? { scope } : {}),
+                });
+                return `refreshed${scope ? ` (scope: ${scope})` : ""}`;
+            },
+        },
+    };
+}
+/** Well-known application-state key used by the refresh-screen tool. */
+const SCREEN_REFRESH_KEY = "__screen_refresh__";
+/**
+ * Creates the `set-search-params` / `set-url-path` tools. Writes a one-shot
+ * URL command to application_state; the client's URLSync component applies
+ * it via react-router (no full page reload) and then deletes the command.
+ *
+ * This is how the agent edits URL state — filter query params, route
+ * changes, hash — without needing a per-template navigate action. The
+ * current URL is visible to the agent via the auto-injected `<current-url>`
+ * block, which includes parsed search params.
+ */
+function createUrlTools() {
+    return {
+        "set-search-params": {
+            // Writes __set_url__ to application_state, which the app-state watcher
+            // already surfaces as a poll event. No need to double-emit.
+            readOnly: true,
+            tool: {
+                description: "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.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        params: {
+                            type: "object",
+                            description: 'Map of query param → value. Each value is a string, or null/"" to clear. Example: {"f_pubDateStart": null, "f_cadence": "MONTH"}.',
+                        },
+                        merge: {
+                            type: "string",
+                            description: '"true" (default) merges over existing params; "false" replaces them entirely.',
+                            enum: ["true", "false"],
+                        },
+                    },
+                    required: ["params"],
+                },
+            },
+            run: async (args) => {
+                const params = (args?.params ?? {});
+                const merge = args?.merge !== "false";
+                const { writeAppState } = await import("../application-state/script-helpers.js");
+                await writeAppState("__set_url__", {
+                    searchParams: params,
+                    mergeSearchParams: merge,
+                });
+                const keys = Object.keys(params);
+                return `set-search-params: ${keys.length} key${keys.length === 1 ? "" : "s"}${merge ? "" : " (replace)"}`;
+            },
+        },
+        "set-url-path": {
+            // Same as set-search-params — writes application_state, already emits
+            // via the app-state watcher.
+            readOnly: true,
+            tool: {
+                description: "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.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        pathname: {
+                            type: "string",
+                            description: "New URL pathname (e.g. '/adhoc/weekly').",
+                        },
+                        params: {
+                            type: "object",
+                            description: 'Optional query params to set alongside the path change. String values set, null/"" clears.',
+                        },
+                        merge: {
+                            type: "string",
+                            description: '"true" (default) merges over existing params; "false" starts fresh.',
+                            enum: ["true", "false"],
+                        },
+                    },
+                    required: ["pathname"],
+                },
+            },
+            run: async (args) => {
+                const pathname = String(args?.pathname ?? "");
+                if (!pathname.startsWith("/")) {
+                    return "Error: pathname must start with '/'.";
+                }
+                const params = (args?.params ?? {});
+                const merge = args?.merge !== "false";
+                const { writeAppState } = await import("../application-state/script-helpers.js");
+                await writeAppState("__set_url__", {
+                    pathname,
+                    searchParams: params,
+                    mergeSearchParams: merge,
+                });
+                return `set-url-path: ${pathname}`;
+            },
+        },
+    };
+}
+/**
+ * Creates db-* tools (db-query, db-exec, db-patch, db-schema) as native tools.
+ * These let the agent read and write the app's own SQL database. Scoping to
+ * the current user/org is enforced automatically in production via temp views.
+ *
+ * In dev mode template actions are invoked via shell and the agent can call
+ * `pnpm action db-query ...` — but in production there is no shell, so these
+ * must be registered as native tools for the agent to reach the app DB at all.
+ */
+async function createDbScriptEntries() {
+    try {
+        const [schemaMod, queryMod, execMod, patchMod] = await Promise.all([
+            import("../scripts/db/schema.js"),
+            import("../scripts/db/query.js"),
+            import("../scripts/db/exec.js"),
+            import("../scripts/db/patch.js"),
+        ]);
+        return {
+            "db-schema": wrapCliScript({
+                description: "Show the app's SQL schema — all tables, columns, types, indexes, and foreign keys. Use this to understand the data model before querying.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        format: {
+                            type: "string",
+                            description: 'Output format: "json" or "text" (default: text)',
+                            enum: ["json", "text"],
+                        },
+                    },
+                },
+            }, schemaMod.default, { readOnly: true }),
+            "db-query": wrapCliScript({
+                description: "Read from the app's SQL database. Runs a SELECT (or WITH/EXPLAIN/PRAGMA) against the app's own tables — settings, application_state, and all template tables. Results are automatically scoped to the current user/org; DO NOT add `WHERE owner_email = ...` yourself. This queries the APP DATABASE — not any external data source.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        sql: {
+                            type: "string",
+                            description: "SELECT query to run, e.g. \"SELECT key, value FROM settings WHERE key LIKE 'sql-dashboard-%'\"",
+                        },
+                        format: {
+                            type: "string",
+                            description: 'Output format: "json" or "text" (default: text)',
+                            enum: ["json", "text"],
+                        },
+                        limit: {
+                            type: "string",
+                            description: "Append LIMIT N if the query doesn't already have one",
+                        },
+                    },
+                    required: ["sql"],
+                },
+            }, queryMod.default, { readOnly: true }),
+            "db-exec": wrapCliScript({
+                description: "Write to the app's SQL database. Runs INSERT / UPDATE / DELETE against the app's own tables. Writes are automatically scoped to the current user/org, and `owner_email` / `org_id` are auto-injected on INSERT. Use this to update rows in the settings table (e.g. edit a dashboard config stored under `o:<orgId>:sql-dashboard-<id>`). This writes to the APP DATABASE — not any external data source.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        sql: {
+                            type: "string",
+                            description: "INSERT / UPDATE / DELETE statement. Use parameterized placeholders (?) if possible.",
+                        },
+                    },
+                    required: ["sql"],
+                },
+            }, execMod.default),
+            "db-patch": wrapCliScript({
+                description: "Surgical patch on a large text/JSON column in the app's SQL database. Two modes: (1) text find/replace via `find`/`replace`/`edits` — best for small edits to documents, slide HTML, etc. (2) structural JSON ops via `json-ops` — STRONGLY PREFERRED when the column is JSON (dashboard configs, form schemas, slide decks) because it avoids all the brace/quote/comma surgery that text find/replace requires. Use `json-ops` to set/remove values at a JSON Pointer path, or to move/insert array items — e.g. reorder dashboard panels, add a filter, rename a field. Targets exactly one row (narrow `where` by primary key). Same per-user/org scoping as db-exec.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        table: {
+                            type: "string",
+                            description: "Table name (e.g. 'settings')",
+                        },
+                        column: {
+                            type: "string",
+                            description: "Text/JSON column to patch (e.g. 'value' for settings)",
+                        },
+                        where: {
+                            type: "string",
+                            description: "WHERE clause that matches exactly one row (e.g. \"key = 'o:org1:sql-dashboard-foo'\")",
+                        },
+                        find: {
+                            type: "string",
+                            description: "Text mode: substring to find. Must match EXACTLY ONE occurrence by default (like Claude Code's Edit tool). If 0 matches, you get 'NOT FOUND'. If >1 matches, you get surrounding context for each match — widen `find` with unique context and retry. Use `all: \"true\"` to replace every occurrence.",
+                        },
+                        replace: {
+                            type: "string",
+                            description: "Text mode: replacement substring",
+                        },
+                        edits: {
+                            type: "string",
+                            description: 'Text mode batch: JSON array of {find, replace} pairs. Same uniqueness rule applies to each `find`. Example: \'[{"find":"a","replace":"b"}]\'',
+                        },
+                        "json-ops": {
+                            type: "string",
+                            description: 'JSON mode: JSON array of structural ops. Each op is {op, path, value?, from?}. `op` is one of "set", "remove", "insert", "move", "move-before". `path` / `from` use JSON Pointer ("/panels/3/title"). Examples — reorder: \'[{"op":"move","from":"/panels/7","path":"/panels/1"}]\'; edit field: \'[{"op":"set","path":"/panels/0/title","value":"New"}]\'; delete filter: \'[{"op":"remove","path":"/filters/2"}]\'; add panel: \'[{"op":"insert","path":"/panels/0","value":{"id":"p","title":"..."}}]\'. Much safer than text find/replace for JSON columns.',
+                        },
+                        all: {
+                            type: "string",
+                            description: 'Text mode: set to "true" to replace every occurrence of each `find` (default requires exactly one match)',
+                            enum: ["true"],
+                        },
+                    },
+                    required: ["table", "column", "where"],
+                },
+            }, patchMod.default),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Creates the docs-search tool so agents can look up framework documentation.
  * Docs are bundled in @agent-native/core and read via fs at runtime.
@@ -100,7 +350,7 @@ async function createDocsScriptEntries() {
                         },
                     },
                 },
-            }, mod.default),
+            }, mod.default, { readOnly: true }),
         };
     }
     catch {
@@ -342,6 +592,32 @@ async function createCallAgentScriptEntry(selfAppId) {
 }
 function createBuilderBrowserTool(deps) {
     return {
+        "connect-builder": {
+            tool: {
+                description: "Render a Builder.io card inline in the chat. Call this IMMEDIATELY — no exploration, no planning — whenever (a) the user asks to add a feature, change the UI, edit code, create a component, add a route, add an integration, fix a bug in the app itself, or anything else that requires source-file edits while in hosted/production mode, OR (b) the user needs Builder for LLM access, browser automation, or any other Builder-gated capability. If Builder is already connected, the card shows a 'Send to Builder' button that hands the work off to Builder's cloud agent and returns a branch URL. When you call this for a code-change request, pass the user's request verbatim as the `prompt` arg so the card can forward it to Builder unchanged.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        prompt: {
+                            type: "string",
+                            description: "The user's feature / change request, verbatim. Forwarded to Builder's cloud agent when the user clicks Send. Omit only for generic 'connect Builder' requests that aren't tied to a specific code change.",
+                        },
+                    },
+                },
+            },
+            run: async (args) => {
+                const configured = !!(process.env.BUILDER_PRIVATE_KEY && process.env.BUILDER_PUBLIC_KEY);
+                const prompt = typeof args?.prompt === "string" ? args.prompt : "";
+                return JSON.stringify({
+                    kind: "connect-builder-card",
+                    configured,
+                    builderEnabled: !!process.env.ENABLE_BUILDER,
+                    connectUrl: getBuilderBrowserConnectUrl(deps.getOrigin()),
+                    orgName: process.env.BUILDER_ORG_NAME || null,
+                    prompt,
+                });
+            },
+        },
         "get-browser-connection": {
             tool: {
                 description: "Provision a Builder-backed browser session and return browser websocket connection details. If Builder browser access is not configured yet, this returns setup guidance instead.",
@@ -616,11 +892,12 @@ const FRAMEWORK_CORE = `
 ### Core Rules
 
 1. **Data lives in SQL** — All app state is in a SQL database (could be SQLite, Postgres, Turso, or Cloudflare D1 — never assume which). Use the available database tools.
-2. **Context awareness** — The user's current screen state is automatically included in each message as a \`<current-screen>\` block. Use it to understand what the user is looking at. You can still call \`view-screen\` for a more detailed snapshot if needed, but you should NOT need to call it before every action.
+2. **Context awareness** — The user's current screen state is automatically included in each message as a \`<current-screen>\` block, and the current URL (path + search params) as a \`<current-url>\` block. Use both to understand what the user is looking at — filters, search terms, and other URL-driven state live in \`<current-url>\`'s \`searchParams\`, NOT in the settings table. To change URL state (e.g. toggle a filter, clear a query string), use the \`set-search-params\` or \`set-url-path\` tools — never try to edit URL state by writing to settings or application_state directly.
 3. **Navigate the UI** — Use the \`navigate\` tool to switch views, open items, or focus elements for the user.
 4. **Application state** — Ephemeral UI state (drafts, selections, navigation) lives in \`application_state\`. Use \`readAppState\`/\`writeAppState\` to read and write it. When you write state, the UI updates automatically.
-5. **Memory** — Use the structured memory system to persist knowledge across sessions. Use \`save-memory\` proactively when you learn preferences, corrections, or project context. Update shared AGENTS.md for instructions that should apply to all users.
-6. **Security** — Always use \`defineAction\` with a Zod \`schema:\` for input validation. Never construct SQL with string concatenation — use parameterized queries via db-query/db-exec. Never use \`dangerouslySetInnerHTML\`, \`innerHTML\`, or \`eval()\`. Never expose secrets in responses or source code. Every table with user data must have \`owner_email\`.
+5. **Screen refresh is automatic after action calls** — The framework auto-emits a refresh event after any successful mutating tool call (template actions like \`log-meal\`, \`update-form\`, \`edit-document\`, and the \`db-exec\` / \`db-patch\` tools). The UI re-fetches its queries without a full page reload. You do NOT need to call \`refresh-screen\` after an action — it's already handled. Only call \`refresh-screen\` explicitly when (a) you mutated data via a path the framework can't detect (e.g. writing directly to an external system whose results the app mirrors), or (b) you want to pass a \`scope\` hint so the UI narrows which queries to refetch. Do NOT tell the user to reload the page.
+6. **Memory** — Use the structured memory system to persist knowledge across sessions. Use \`save-memory\` proactively when you learn preferences, corrections, or project context. Update shared AGENTS.md for instructions that should apply to all users.
+7. **Security** — Always use \`defineAction\` with a Zod \`schema:\` for input validation. Never construct SQL with string concatenation — use parameterized queries via db-query/db-exec. Never use \`dangerouslySetInnerHTML\`, \`innerHTML\`, or \`eval()\`. Never expose secrets in responses or source code. Every table with user data must have \`owner_email\`.
 
 ### Resources
 
@@ -634,6 +911,37 @@ When the user gives instructions that should apply to all users/sessions, update
 
 When the user says "show me", "go to", "open", "switch to", or similar navigation language, ALWAYS use the \`navigate\` action to update the UI. The user expects to SEE the result in the main app, not just read it in chat. Navigate first, then fetch/display data.
 
+### Inline Embeds
+
+You 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.
+
+Syntax:
+
+\`\`\`\`
+\`\`\`embed
+src: /some/path?param=value
+aspect: 16/9
+title: Optional label
+\`\`\`
+\`\`\`\`
+
+Keys:
+- \`src\` (required) — **must be a same-origin path starting with \`/\`**. Cross-origin URLs are blocked by the renderer. No \`javascript:\` or \`data:\` URLs.
+- \`aspect\` (optional) — one of \`16/9\` (default), \`4/3\`, \`3/2\`, \`2/1\`, \`21/9\`, \`1/1\`.
+- \`title\` (optional) — accessible label / hover tooltip.
+- \`height\` (optional) — fixed pixel height when aspect ratio isn't a good fit.
+
+**When to reach for it:**
+- Showing a chart, visualization, or map that benefits from being live/interactive.
+- Previewing a specific item (a thread, a doc, a record) inline with your explanation.
+- Anything where a screenshot-sized static image would undersell the result.
+
+**When NOT to use it:**
+- For simple prose answers, tables, or plain data — those should stay as markdown.
+- For external sites — the renderer blocks cross-origin iframes.
+
+Which routes are renderable as embeds is template-specific — the app's \`AGENTS.md\` will list them. If no embeddable routes exist in this template, don't emit \`embed\` fences.
+
 ### Chat History
 
 You can search and restore previous chat conversations:
@@ -682,11 +990,15 @@ When the user asks for something recurring ("every morning", "daily at 9am", "we
 
 Job instructions should be self-contained — include which actions to call, what conditions to check, and what to do with results. The agent executing the job has access to all the same tools you do.
 
+### Connecting Builder.io
+
+When the user asks to connect Builder.io, needs Builder for LLM access / browser automation, or you hit a "Builder not configured" error, call the \`connect-builder\` tool. It renders a one-click Connect card inline in the chat — do NOT write out multi-step setup instructions yourself (no "Option 1 / Option 2", no terminal commands). Just call the tool and let the card handle the rest.
+
 ### Browser Access
 
 Use \`get-browser-connection\` when you need a real browser session backed by Builder. It returns websocket connection details for a provisioned browser session.
 
-- If the tool says Builder is not configured, tell the user to connect Builder from the workspace Resources panel.
+- If the tool says Builder is not configured, call \`connect-builder\` to show the user a Connect card.
 - Reuse a stable \`sessionId\` when you want to reconnect to the same browser session.
 - Include proxy parameters when you need the browser to reach a local dev server through Builder's browser connection flow.
 
@@ -743,20 +1055,22 @@ The agent and the UI are equal partners — everything the UI can do, you can do
 
 **In production mode, you operate through registered actions exposed as tools.** These are your capabilities — use them to read data, take actions, and help the user. You cannot edit source code or access the filesystem directly. Your tools are the app's API.
 
-### Code Changes Not Available
+### Code Changes Not Available — Call \`connect-builder\` Immediately
 
-When the user asks you to change the UI, modify code, add features, fix bugs in the app itself, change styles, or do anything that requires editing source files — you MUST respond with this exact message (replacing APP_NAME with the current app name from the URL hostname):
+When the user asks you to change the UI, modify code, add a feature, fix a bug in the app itself, change styles, add a hook, create a component, add a route, add an integration, or anything else that requires editing source files — you MUST take exactly these steps, in order:
 
-> This app is running in hosted mode and I can't make code changes here. To customize this app:
->
-> **Option 1:** Connect to [Builder.io](https://www.builder.io/m/agent-native) for a full development environment
->
-> **Option 2:** Clone and run locally:
-> \`\`\`
-> npx agent-native create APP_NAME
-> \`\`\`
+1. Call the \`connect-builder\` tool, passing the user's full request verbatim as the \`prompt\` argument. This renders an inline card. If Builder is connected, the card hands the prompt off to Builder's cloud agent on one click and returns a branch URL; otherwise it shows a connect / waitlist flow. Either way, Builder writes the code — no local setup, no clone, no install.
+2. After the card renders, write a single short sentence telling the user to click Connect Builder to have this built for them in the cloud, and mention they can also clone the app locally with \`npx agent-native create <app-name>\` if they'd rather work offline.
 
-Do NOT attempt to work around this limitation. Do NOT say "I can't do that" without providing the options above. Always include both the Builder.io link and the CLI command.
+**Hard rules — do NOT break these:**
+- Do NOT read source files, list directories, or explore the codebase. You have no filesystem tools and don't need to look at code to recommend Builder.
+- Do NOT write an implementation plan. Do NOT write code in your response. Do NOT describe which files to create or modify. Builder will figure that out in its sandbox.
+- Do NOT save plans, specs, or code to \`resource-write\`. Resources are for app data, not implementation plans the user didn't ask for.
+- Do NOT spawn sub-agents (\`spawn-task\`) to design, plan, or research the feature. The answer is always: call \`connect-builder\`, say one sentence, stop. Sub-agents inherit these same rules and have no code-editing tools either.
+- Do NOT say "I don't have a request-code-change tool" or list what tools you lack. Just call \`connect-builder\`.
+- Do NOT wait for the user to ask "how" — call \`connect-builder\` the moment a code change is requested.
+
+Builder.io is the recommended path because it's one-click and runs in the cloud. Local dev is a fallback for users who want to work offline.
 ${FRAMEWORK_CORE}`;
 const DEV_FRAMEWORK_PROMPT = `## Agent-Native Framework — Development Mode
 
@@ -850,12 +1164,15 @@ async function loadResourcesForPrompt(owner) {
  * from the environment so scheduler/A2A/HTTP call sites all see whatever
  * org was just resolved for this request.
  */
-async function buildSchemaBlock(owner, hasRawDbTools) {
+async function buildSchemaBlock(owner, _legacyHasRawDbTools) {
+    // db-* tools are always registered (see createDbScriptEntries), in both dev
+    // and prod. The legacy boolean is kept for call-site compatibility but
+    // ignored — always advertise the tools to the agent.
     try {
         return await loadSchemaPromptBlock({
             owner,
             orgId: getRequestOrgId() ?? null,
-            hasRawDbTools,
+            hasRawDbTools: true,
         });
     }
     catch {
@@ -1045,6 +1362,29 @@ export function createAgentChatPlugin(options) {
         const canToggle = (env === "development" || env === "test") &&
             process.env.AGENT_MODE !== "production";
         const routePath = options?.path ?? "/_agent-native/agent-chat";
+        // Mutable mode flag — persisted to the `settings` table so a user who
+        // toggles to "Production" stays in prod mode across server restarts.
+        // Hoisted here (before any tool-registry / handler closures are built)
+        // so every runtime decision point can close over it and see live changes
+        // when the user toggles the Environment dropdown.
+        const AGENT_MODE_SETTING_KEY = "agent-chat.mode";
+        let currentDevMode = canToggle;
+        if (canToggle) {
+            try {
+                const persisted = await getSetting(AGENT_MODE_SETTING_KEY);
+                if (persisted && typeof persisted.devMode === "boolean") {
+                    currentDevMode = persisted.devMode;
+                }
+            }
+            catch {
+                // Settings table may not be ready yet — fall back to default.
+            }
+        }
+        // Every closure that picks between dev/prod tools, prompts, or handlers
+        // at request time should call this getter instead of reading `canToggle`.
+        // `canToggle` means "this environment allows toggling" (static); this
+        // function means "the user currently has dev mode ON" (live).
+        const isDevMode = () => currentDevMode;
         // Initialize MCP client (connects to user-configured local MCP servers).
         // Graceful-degrade: any failure yields zero MCP tools and agent-chat keeps
         // working as before. No-op outside Node runtimes.
@@ -1092,9 +1432,12 @@ export function createAgentChatPlugin(options) {
         const templateScripts = typeof rawActions === "function"
             ? await rawActions()
             : (rawActions ?? {});
-        // Resource, chat, docs, and cross-agent scripts are available in both prod and dev modes
+        // Resource, chat, docs, db, and cross-agent scripts are available in both prod and dev modes
         const resourceScripts = await createResourceScriptEntries();
         const docsScripts = await createDocsScriptEntries();
+        const dbScripts = await createDbScriptEntries();
+        const refreshScreenTool = createRefreshScreenEntry();
+        const urlTools = createUrlTools();
         const engineScripts = await createAgentEngineScriptEntries();
         const chatScripts = {
             ...(await createChatScriptEntries()),
@@ -1253,6 +1596,9 @@ export function createAgentChatPlugin(options) {
                 ...templateScripts,
                 ...resourceScripts,
                 ...docsScripts,
+                ...dbScripts,
+                ...refreshScreenTool,
+                ...urlTools,
                 ...chatScripts,
                 ...callAgentScript,
                 ...browserTools,
@@ -1328,12 +1674,13 @@ export function createAgentChatPlugin(options) {
                     apiKey: options?.apiKey,
                 });
                 // Use the same handler (dev or prod) that the interactive chat uses
-                const handler = canToggle && devHandler ? devHandler : prodHandler;
+                const devActive = isDevMode();
+                const handler = devActive && devHandler ? devHandler : prodHandler;
                 // Build the same system prompt the interactive agent uses
                 const owner = userEmail || "local@localhost";
                 const resources = await loadResourcesForPrompt(owner);
-                const schemaBlock = await buildSchemaBlock(owner, canToggle);
-                const systemPrompt = canToggle
+                const schemaBlock = await buildSchemaBlock(owner, devActive);
+                const systemPrompt = devActive
                     ? devPrompt + resources + schemaBlock
                     : basePrompt + resources + schemaBlock;
                 const model = options?.model ??
@@ -1342,7 +1689,7 @@ export function createAgentChatPlugin(options) {
                 // to prevent infinite recursive A2A loops (agent calling itself).
                 // In dev mode, template actions are invoked via shell (not native tools),
                 // so they're omitted from the tool registry — see allScripts comment.
-                const a2aActions = canToggle
+                const a2aActions = devActive
                     ? {
                         ...resourceScripts,
                         ...docsScripts,
@@ -1354,6 +1701,9 @@ export function createAgentChatPlugin(options) {
                         ...templateScripts,
                         ...resourceScripts,
                         ...docsScripts,
+                        ...dbScripts,
+                        ...refreshScreenTool,
+                        ...urlTools,
                         ...chatScripts,
                         ...browserTools,
                     };
@@ -1438,7 +1788,8 @@ export function createAgentChatPlugin(options) {
                     (canToggle ? "claude-sonnet-4-6" : "claude-haiku-4-5-20251001");
                 // Same actions as A2A — without call-agent to prevent loops.
                 // In dev mode, template actions go through shell, not native tools.
-                const mcpActions = canToggle
+                const devActiveMcp = isDevMode();
+                const mcpActions = devActiveMcp
                     ? {
                         ...resourceScripts,
                         ...docsScripts,
@@ -1449,12 +1800,15 @@ export function createAgentChatPlugin(options) {
                         ...templateScripts,
                         ...resourceScripts,
                         ...docsScripts,
+                        ...dbScripts,
+                        ...refreshScreenTool,
+                        ...urlTools,
                         ...chatScripts,
                     };
                 const mcpTools = actionsToEngineTools(mcpActions);
                 const resources = await loadResourcesForPrompt("local@localhost");
-                const schemaBlock = await buildSchemaBlock("local@localhost", canToggle);
-                const systemPrompt = canToggle
+                const schemaBlock = await buildSchemaBlock("local@localhost", devActiveMcp);
+                const systemPrompt = devActiveMcp
                     ? devPrompt + resources + schemaBlock
                     : basePrompt + resources + schemaBlock;
                 let accumulatedText = "";
@@ -1560,6 +1914,7 @@ export function createAgentChatPlugin(options) {
         // requests for different threads don't clobber each other.
         const _runSendByThread = new Map();
         let _currentRunOwner = "local@localhost";
+        let _currentRunUserApiKey;
         let _currentRunThreadId = "";
         let _currentRunSystemPrompt = basePrompt;
         // Default to Haiku in production mode to manage costs for hosted apps
@@ -1568,7 +1923,7 @@ export function createAgentChatPlugin(options) {
         const teamTools = createTeamTools({
             getOwner: () => _currentRunOwner,
             getSystemPrompt: () => _currentRunSystemPrompt,
-            getActions: () => canToggle
+            getActions: () => isDevMode()
                 ? {
                     // Sub-agents spawned in dev mode also invoke template actions
                     // via shell, so omit them from the native tool registry.
@@ -1581,10 +1936,18 @@ export function createAgentChatPlugin(options) {
                     ...templateScripts,
                     ...resourceScripts,
                     ...docsScripts,
+                    ...dbScripts,
+                    ...refreshScreenTool,
+                    ...urlTools,
                     ...chatScripts,
                 },
             getEngine: () => createAnthropicEngine({
-                apiKey: options?.apiKey ?? process.env.ANTHROPIC_API_KEY,
+                // Sub-agents must inherit the parent run's resolved key so a
+                // BYO-key user can't bypass the free-tier check on the parent
+                // run and then have spawn-task delegations bill the platform key.
+                apiKey: _currentRunUserApiKey ??
+                    options?.apiKey ??
+                    process.env.ANTHROPIC_API_KEY,
             }),
             getModel: () => resolvedModel,
             getParentThreadId: () => _currentRunThreadId,
@@ -1606,6 +1969,9 @@ export function createAgentChatPlugin(options) {
             ...templateScripts,
             ...resourceScripts,
             ...docsScripts,
+            ...dbScripts,
+            ...refreshScreenTool,
+            ...urlTools,
             ...chatScripts,
             ...callAgentScript,
             ...teamTools,
@@ -1616,15 +1982,30 @@ export function createAgentChatPlugin(options) {
         // Always build the production handler (includes resource tools + call-agent + team tools)
         // In production mode (!canToggle), enable usage tracking and limits
         const isHostedProd = !canToggle;
+        const resolveExtraContext = async (event, owner) => {
+            if (!options?.extraContext)
+                return "";
+            try {
+                const extra = await options.extraContext(event, owner);
+                return extra ? `\n\n${extra}` : "";
+            }
+            catch (err) {
+                console.warn("[agent-chat] extraContext threw:", err instanceof Error ? err.message : err);
+                return "";
+            }
+        };
         const prodHandler = createProductionAgentHandler({
             actions: prodActions,
             systemPrompt: async (event) => {
                 _currentRequestOrigin = getOrigin(event);
                 const owner = await getOwnerFromEvent(event);
                 _currentRunOwner = owner;
+                const { getOwnerAnthropicApiKey } = await import("../agent/production-agent.js");
+                _currentRunUserApiKey = await getOwnerAnthropicApiKey(owner);
                 const resources = await loadResourcesForPrompt(owner);
                 const schemaBlock = await buildSchemaBlock(owner, false);
-                _currentRunSystemPrompt = basePrompt + resources + schemaBlock;
+                const extra = await resolveExtraContext(event, owner);
+                _currentRunSystemPrompt = basePrompt + resources + schemaBlock + extra;
                 return _currentRunSystemPrompt;
             },
             model: options?.model ??
@@ -1670,9 +2051,12 @@ export function createAgentChatPlugin(options) {
                     _currentRequestOrigin = getOrigin(event);
                     const owner = await getOwnerFromEvent(event);
                     _currentRunOwner = owner;
+                    const { getOwnerAnthropicApiKey } = await import("../agent/production-agent.js");
+                    _currentRunUserApiKey = await getOwnerAnthropicApiKey(owner);
                     const resources = await loadResourcesForPrompt(owner);
                     const schemaBlock = await buildSchemaBlock(owner, true);
-                    _currentRunSystemPrompt = devPrompt + resources + schemaBlock;
+                    const extra = await resolveExtraContext(event, owner);
+                    _currentRunSystemPrompt = devPrompt + resources + schemaBlock + extra;
                     return _currentRunSystemPrompt;
                 },
                 model: options?.model,
@@ -1693,8 +2077,8 @@ export function createAgentChatPlugin(options) {
         const mentionProviders = typeof rawProviders === "function"
             ? await rawProviders()
             : (rawProviders ?? {});
-        // Mutable mode flag — starts in dev if environment allows
-        let currentDevMode = canToggle;
+        // currentDevMode + persistence were hoisted to the top of this function
+        // so every closure built below can close over the live flag.
         // Mount mode endpoint — GET returns current mode, POST toggles it (localhost only)
         getH3App(nitroApp).use(`${routePath}/mode`, defineEventHandler(async (event) => {
             if (getMethod(event) === "POST") {
@@ -1713,12 +2097,24 @@ export function createAgentChatPlugin(options) {
                 else {
                     currentDevMode = !currentDevMode;
                 }
+                try {
+                    await putSetting(AGENT_MODE_SETTING_KEY, {
+                        devMode: currentDevMode,
+                    });
+                }
+                catch {
+                    // Persistence is best-effort — in-memory flag still applies for
+                    // the lifetime of this process even if the settings write fails.
+                }
                 return { devMode: currentDevMode, canToggle };
             }
             return { devMode: currentDevMode, canToggle };
         }));
-        // Mount save-key BEFORE the prefix handler so it isn't shadowed
-        // Only functional in Node.js environments (writes to .env file)
+        // Mount save-key BEFORE the prefix handler so it isn't shadowed.
+        // Persists the user's key per-owner in the SQL settings table so it
+        // survives across serverless invocations (where mutating process.env
+        // and writing .env are both no-ops). Also updates process.env and
+        // .env when running locally for fast pickup by other handlers.
         getH3App(nitroApp).use(`${routePath}/save-key`, defineEventHandler(async (event) => {
             if (getMethod(event) !== "POST") {
                 setResponseStatus(event, 405);
@@ -1731,19 +2127,66 @@ export function createAgentChatPlugin(options) {
                 return { error: "API key is required" };
             }
             const trimmedKey = key.trim();
-            try {
-                const path = await import("path");
-                const { upsertEnvFile } = await import("./create-server.js");
-                const envPath = path.join(process.cwd(), ".env");
-                await upsertEnvFile(envPath, [
-                    { key: "ANTHROPIC_API_KEY", value: trimmedKey },
-                ]);
+            // Persist per-owner so the key survives cold starts in serverless
+            // and so the user's key isn't shared across users on multi-tenant
+            // hosted deployments. We require a real authenticated owner here —
+            // `local@localhost` is the unauthenticated fallback and must never
+            // become the shared key bucket on hosted deployments.
+            const ownerEmail = await getOwnerFromEvent(event);
+            if (isHostedProd && (!ownerEmail || ownerEmail === "local@localhost")) {
+                setResponseStatus(event, 401);
+                return { error: "Authentication required" };
             }
-            catch {
-                // Edge runtime — can't write .env, but can still update process.env
+            if (ownerEmail && ownerEmail !== "local@localhost") {
+                try {
+                    await putSetting(`user-anthropic-api-key:${ownerEmail}`, {
+                        key: trimmedKey,
+                    });
+                    // Verify the write actually landed — some managed DB drivers
+                    // swallow errors on degraded connections. Without this the
+                    // client sees "saved", reloads, and the usage-limit card
+                    // re-appears on the next message because the key isn't
+                    // really persisted.
+                    const check = await getSetting(`user-anthropic-api-key:${ownerEmail}`);
+                    if (!check ||
+                        typeof check.key !== "string" ||
+                        check.key !== trimmedKey) {
+                        throw new Error("settings write did not persist");
+                    }
+                }
+                catch (err) {
+                    if (isHostedProd) {
+                        console.error("[agent-chat] save-key persistence failed:", err instanceof Error ? err.message : err);
+                        setResponseStatus(event, 500);
+                        return {
+                            error: "Failed to persist API key. Please try again or contact support.",
+                        };
+                    }
+                    // Local dev falls through to the env-file path below.
+                }
+            }
+            // In hosted/multi-tenant mode we deliberately do NOT touch
+            // process.env or .env: the per-owner SQL lookup above is the
+            // single source of truth, and overwriting the shared env key
+            // would leak one tenant's credentials into every subsequent
+            // request that hit the same warm instance without its own key.
+            if (!isHostedProd) {
+                try {
+                    const path = await import("path");
+                    const { upsertEnvFile } = await import("./create-server.js");
+                    const envPath = path.join(process.cwd(), ".env");
+                    await upsertEnvFile(envPath, [
+                        { key: "ANTHROPIC_API_KEY", value: trimmedKey },
+                    ]);
+                }
+                catch {
+                    // Edge runtime — can't write .env, but can still update process.env
+                }
+                // Update process.env so the agent works immediately in the
+                // current local-dev invocation; the SQL persist above covers
+                // future invocations.
+                process.env.ANTHROPIC_API_KEY = trimmedKey;
             }
-            // Update process.env so the agent works immediately
-            process.env.ANTHROPIC_API_KEY = trimmedKey;
             return { ok: true };
         }));
         // Mount file search endpoint
@@ -2069,7 +2512,7 @@ export function createAgentChatPlugin(options) {
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
             }
-            await getOwnerFromEvent(event);
+            const ownerEmail = await getOwnerFromEvent(event);
             const body = await readBody(event);
             const message = body?.message;
             if (!message || typeof message !== "string") {
@@ -2078,7 +2521,11 @@ export function createAgentChatPlugin(options) {
             }
             // Strip mention markup: @[Name|type] → @Name
             const cleanMessage = message.replace(/@\[([^\]|]+)\|[^\]]*\]/g, "@$1");
-            const apiKey = process.env.ANTHROPIC_API_KEY;
+            // Mirror the chat-run resolution so BYO-key users have title
+            // generation billed to their own key instead of the platform key.
+            const { getOwnerAnthropicApiKey } = await import("../agent/production-agent.js");
+            const userApiKey = await getOwnerAnthropicApiKey(ownerEmail);
+            const apiKey = userApiKey ?? process.env.ANTHROPIC_API_KEY;
             if (!apiKey) {
                 // Fallback: truncate the message
                 return { title: cleanMessage.trim().slice(0, 60) };