@agent-native/core 0.6.1 → 0.7.2

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

@@ -1,15 +1,20 @@
+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";
+import { McpClientManager, loadMcpConfig, autoDetectMcpConfig, mcpToolsToActionEntries, } from "../mcp-client/index.js";
 import { discoverAgents } from "./agent-discovery.js";
 import { loadSchemaPromptBlock } from "./schema-prompt.js";
 import { buildAssistantMessage, extractThreadMeta, } from "../agent/thread-data-builder.js";
 import { defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getQuery, } from "h3";
 import { getSession } from "./auth.js";
+import { getOrigin } from "./google-oauth.js";
 import { createThread, getThread, listThreads, searchThreads, updateThreadData, deleteThread, } from "../chat-threads/store.js";
 import { resourceListAccessible, resourceList, resourceGet, resourceGetByPath, ensurePersonalDefaults, SHARED_OWNER, } from "../resources/store.js";
 import nodePath from "node:path";
 import { readBody } from "./h3-helpers.js";
+import { getBuilderBrowserConnectUrl, requestBuilderBrowserConnection, } from "./builder-browser.js";
 // Lazy fs — loaded via dynamic import() on first use.
 // This avoids require() which bundlers convert to createRequire(import.meta.url)
 // that crashes on CF Workers where import.meta.url is undefined.
@@ -24,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)) {
@@ -68,16 +74,301 @@ 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.
+ */
+async function createDocsScriptEntries() {
+    try {
+        const mod = await import("../scripts/docs/search.js");
+        return {
+            "docs-search": wrapCliScript({
+                description: "Search and read agent-native framework documentation. Use --list to see all pages, --query to search, --slug to read a specific page.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search term to find relevant docs (e.g. 'actions', 'authentication', 'database')",
+                        },
+                        slug: {
+                            type: "string",
+                            description: "Read a specific doc page by slug (e.g. 'actions', 'authentication', 'database')",
+                        },
+                        list: {
+                            type: "string",
+                            description: 'Set to "true" to list all available doc pages',
+                            enum: ["true"],
+                        },
+                    },
+                },
+            }, mod.default, { readOnly: true }),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Creates resource ScriptEntries available in both prod and dev modes.
  */
 async function createResourceScriptEntries() {
     try {
-        const [list, read, write, del] = await Promise.all([
+        const [list, read, write, del, saveMem, delMem] = await Promise.all([
             import("../scripts/resources/list.js"),
             import("../scripts/resources/read.js"),
             import("../scripts/resources/write.js"),
             import("../scripts/resources/delete.js"),
+            import("../scripts/resources/save-memory.js"),
+            import("../scripts/resources/delete-memory.js"),
         ]);
         return {
             "resource-list": wrapCliScript({
@@ -164,6 +455,45 @@ async function createResourceScriptEntries() {
                     required: ["path"],
                 },
             }, del.default),
+            "save-memory": wrapCliScript({
+                description: "Save a memory for future conversations. Creates or updates a memory file and its index entry. Use proactively when you learn preferences, corrections, project context, or references.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "Short kebab-case identifier (e.g. 'coding-style', 'deploy-process'). Used as the filename.",
+                        },
+                        type: {
+                            type: "string",
+                            description: "Memory category",
+                            enum: ["user", "feedback", "project", "reference"],
+                        },
+                        description: {
+                            type: "string",
+                            description: "One-line summary shown in the memory index (keep under 80 chars)",
+                        },
+                        content: {
+                            type: "string",
+                            description: "The memory content in markdown. For updates, read first and provide full updated content.",
+                        },
+                    },
+                    required: ["name", "type", "description", "content"],
+                },
+            }, saveMem.default),
+            "delete-memory": wrapCliScript({
+                description: "Delete a memory entry and remove it from the memory index.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "The memory name to delete (e.g. 'coding-style')",
+                        },
+                    },
+                    required: ["name"],
+                },
+            }, delMem.default),
         };
     }
     catch {
@@ -260,6 +590,94 @@ async function createCallAgentScriptEntry(selfAppId) {
         return {};
     }
 }
+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.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        sessionId: {
+                            type: "string",
+                            description: "Stable browser session identifier. Reuse it to reconnect to the same browser session.",
+                        },
+                        projectId: {
+                            type: "string",
+                            description: "Optional Builder project or space identifier to scope the session.",
+                        },
+                        branchName: {
+                            type: "string",
+                            description: "Optional branch name for Builder preview sessions.",
+                        },
+                        proxyOrigin: {
+                            type: "string",
+                            description: "Optional source origin to proxy from when browsing a local app.",
+                        },
+                        proxyDefaultOrigin: {
+                            type: "string",
+                            description: "Optional default origin that the browser should use for proxied requests.",
+                        },
+                        proxyDestination: {
+                            type: "string",
+                            description: "Optional destination origin for proxying local development traffic.",
+                        },
+                    },
+                    required: ["sessionId"],
+                },
+            },
+            run: async (args) => {
+                if (!process.env.BUILDER_PRIVATE_KEY ||
+                    !process.env.BUILDER_PUBLIC_KEY) {
+                    return JSON.stringify({
+                        configured: false,
+                        message: "Builder browser access is not configured. Connect Builder from the workspace Resources panel before requesting a browser session.",
+                        connectUrl: getBuilderBrowserConnectUrl(deps.getOrigin()),
+                    });
+                }
+                const connection = await requestBuilderBrowserConnection({
+                    sessionId: args.sessionId,
+                    projectId: args.projectId,
+                    branchName: args.branchName,
+                    proxyOrigin: args.proxyOrigin,
+                    proxyDefaultOrigin: args.proxyDefaultOrigin,
+                    proxyDestination: args.proxyDestination,
+                });
+                return JSON.stringify({
+                    configured: true,
+                    sessionId: args.sessionId,
+                    ...connection,
+                });
+            },
+        },
+    };
+}
 /**
  * Creates agent team orchestration tools (spawn-task, task-status, read-task-result).
  * These let the main agent spawn sub-agents and coordinate work.
@@ -284,6 +702,10 @@ function createTeamTools(deps) {
                             type: "string",
                             description: "Short name for the sub-agent tab (e.g. 'Research', 'Draft email'). If omitted, derived from the task.",
                         },
+                        agent: {
+                            type: "string",
+                            description: "Optional custom agent profile from agents/*.md to use for this task.",
+                        },
                     },
                     required: ["task"],
                 },
@@ -302,14 +724,32 @@ function createTeamTools(deps) {
                     "list-tasks",
                 ]);
                 const subAgentActions = Object.fromEntries(Object.entries(deps.getActions()).filter(([name]) => !teamToolNames.has(name)));
+                let instructions = args.instructions;
+                let selectedModel = deps.getModel();
+                let selectedName = args.name || "";
+                if (args.agent) {
+                    const { findAccessibleCustomAgent } = await import("../resources/agents.js");
+                    const profile = await findAccessibleCustomAgent(deps.getOwner(), args.agent);
+                    if (!profile) {
+                        throw new Error(`Custom agent not found: ${args.agent}`);
+                    }
+                    const profileInstructions = `## Custom Agent Profile: ${profile.name}\n\n` +
+                        (profile.description ? `${profile.description}\n\n` : "") +
+                        profile.instructions;
+                    instructions = instructions
+                        ? `${profileInstructions}\n\n## Extra Task Context\n\n${instructions}`
+                        : profileInstructions;
+                    selectedModel = profile.model ?? selectedModel;
+                    selectedName = selectedName || profile.name;
+                }
                 const task = await spawnTask({
                     description: args.task,
-                    instructions: args.instructions,
+                    instructions,
                     ownerEmail: deps.getOwner(),
                     systemPrompt: deps.getSystemPrompt(),
                     actions: subAgentActions,
                     engine: deps.getEngine(),
-                    model: deps.getModel(),
+                    model: selectedModel,
                     parentThreadId: deps.getParentThreadId(),
                     parentSend: (event) => {
                         if (capturedSend)
@@ -321,7 +761,7 @@ function createTeamTools(deps) {
                     threadId: task.threadId,
                     status: task.status,
                     description: task.description,
-                    name: args.name || "",
+                    name: selectedName,
                 });
             },
         },
@@ -452,24 +892,56 @@ 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. **Resources for memory** — Use the Resources system for persistent notes and context. Update LEARNINGS.md when you learn user preferences or corrections. Update the shared AGENTS.md for instructions that should apply to all users.
+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
 
-You have access to a Resources system for persistent notes, learnings, and context files.
+You have access to a Resources system for persistent notes and context files.
 Use resource-list, resource-read, resource-write, and resource-delete to manage resources.
 Resources can be personal (per-user) or shared (team-wide). By default, resources are personal.
 
-When you learn something important (user corrections, preferences, patterns), update the "LEARNINGS.md" resource. Keep it tidy — revise, consolidate, and remove outdated entries rather than only appending.
-When the user gives instructions that should apply to all users/sessions, update the shared "AGENTS.md" resource instead.
+When the user gives instructions that should apply to all users/sessions, update the shared "AGENTS.md" resource.
 
 ### Navigation Rule
 
 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:
@@ -481,7 +953,7 @@ When the user asks to find a previous conversation, use \`search-chats\` first t
 ### Agent Teams — Orchestration
 
 You are an orchestrator. For complex or multi-step tasks, delegate to sub-agents:
-- \`spawn-task\` — Spawn a sub-agent for a task. It runs in its own thread while you stay available. A live preview card appears in the chat.
+- \`spawn-task\` — Spawn a sub-agent for a task. It runs in its own thread while you stay available. A live preview card appears in the chat. You can optionally choose a custom agent profile from \`agents/*.md\`.
 - \`task-status\` — Check the progress of a running sub-agent.
 - \`read-task-result\` — Read the result when a sub-agent finishes.
 
@@ -497,7 +969,7 @@ You are an orchestrator. For complex or multi-step tasks, delegate to sub-agents
 4. Use \`read-task-result\` to check results when needed, or the user can see live progress in the card.
 5. If the user's request has multiple steps, you can spawn one sub-agent per step, or chain them.
 
-Sub-agents have access to all template tools but **cannot spawn sub-agents themselves** — only you (the orchestrator) can do that. Give the sub-agent a specific, actionable task description — it will figure out which tools to use.
+Sub-agents have access to all template tools but **cannot spawn sub-agents themselves** — only you (the orchestrator) can do that. Give the sub-agent a specific, actionable task description — it will figure out which tools to use. If a matching custom agent profile exists, pass it via the \`agent\` parameter on \`spawn-task\`.
 
 ### Recurring Jobs
 
@@ -518,6 +990,18 @@ 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, 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.
+
 ### call-agent — External Apps Only
 
 The \`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.
@@ -534,15 +1018,34 @@ The \`call-agent\` tool sends a message to a DIFFERENT, separately-deployed app'
 
 If \`call-agent\` returns an error saying the agent is yourself — stop and use your own tools instead.
 
-### Auto-Memory
+### Structured Memory
 
-Proactively update \`LEARNINGS.md\` when you learn something important during conversations:
-- User corrects your approach → capture the correct way
-- User shares preferences (tone, style, workflow) → capture them
-- You discover a non-obvious pattern or gotcha → capture it
-- User provides personal context (contacts, team info, domain knowledge) → capture it
+You have a structured memory system. Your memory index (\`memory/MEMORY.md\`) is loaded at the start of every conversation (shown above). Individual memories are stored as separate files under \`memory/\`.
 
-**Don't ask permission — just save it.** Keep entries concise (one line each, grouped by category). Don't save things that are obvious from reading the code or that are temporary.
+**Tools:**
+- \`save-memory\` — Create or update a memory. Provide name, type, description, and content. Atomically updates both the memory file and the index.
+- \`delete-memory\` — Remove a memory and its index entry.
+- \`resource-read --path memory/<name>.md\` — Read the full content of a specific memory when you need details beyond the index.
+
+**Memory types:**
+- \`user\` — Preferences, role, personal context, contacts
+- \`feedback\` — Corrections ("don't do X, do Y instead"), confirmed approaches
+- \`project\` — Ongoing work context, decisions, status
+- \`reference\` — Pointers to external systems, URLs, API details
+
+**When to save (do it proactively, don't ask permission):**
+- User corrects your approach → save as \`feedback\`
+- User shares preferences (tone, style, workflow) → save as \`user\`
+- You discover a non-obvious pattern or gotcha → save as \`feedback\`
+- User provides personal context (contacts, team, domain) → save as \`user\`
+- A project gains enough context to track → save as \`project\`
+
+**Rules:**
+- Don't save things obvious from the code or standard framework behavior
+- When updating an existing memory, read it first and merge — don't overwrite blindly
+- Keep descriptions concise — the index is loaded every message
+- One memory per logical topic (e.g. 'coding-style', 'project-alpha')
+- Don't save temporary debugging notes or ephemeral task details
 `;
 const PROD_FRAMEWORK_PROMPT = `## Agent-Native Framework — Production Mode
 
@@ -552,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 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:
 
-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):
+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.
 
-> 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
-> \`\`\`
+**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.
 
-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.
+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
 
@@ -594,19 +1099,17 @@ ${FRAMEWORK_CORE}`;
 const DEFAULT_SYSTEM_PROMPT = PROD_FRAMEWORK_PROMPT;
 /**
  * Pre-load the agent's context: AGENTS.md (template instructions), the skills
- * index, and LEARNINGS.md (user notes). These all get appended to the system
- * prompt so the agent has everything it needs from the first turn — no tool
- * calls required to figure out "what is this app".
+ * index, shared LEARNINGS.md (team notes), and memory/MEMORY.md (personal
+ * structured memory index). These all get appended to the system prompt so
+ * the agent has everything it needs from the first turn.
  *
- * Three sources are layered:
+ * Four sources are layered:
  *
- *   1. `<template>` — AGENTS.md + skills index from the `virtual:agents-bundle`
- *      module (inlined at build time by the Vite plugin, falls back to a
- *      filesystem read from `process.cwd()` in dev). Canonical source for
- *      "what is this app, what can it do, what skills are available".
- *   2. `<shared>` — LEARNINGS.md from the SQL shared scope. Team-level notes.
- *   3. `<personal>` — LEARNINGS.md from the SQL personal scope. The current
- *      user's own notes.
+ *   1. `<workspace>` — AGENTS.md from the enterprise workspace core.
+ *   2. `<template>` — AGENTS.md + skills index from the Vite plugin bundle.
+ *   3. `<shared>` — LEARNINGS.md from the SQL shared scope. Team-level notes.
+ *   4. `<personal>` — memory/MEMORY.md from the SQL personal scope. The
+ *      current user's structured memory index.
  *
  * Each source is read independently — no copying between them. Editing
  * AGENTS.md and restarting the server is all it takes; Vite HMR invalidates
@@ -615,10 +1118,15 @@ const DEFAULT_SYSTEM_PROMPT = PROD_FRAMEWORK_PROMPT;
 async function loadResourcesForPrompt(owner) {
     await ensurePersonalDefaults(owner);
     const sections = [];
-    // 1. Template AGENTS.md + skills index — from the virtual bundle.
+    // 1. Workspace AGENTS.md + skills merged into the template bundle.
     try {
         const { loadAgentsBundle, generateSkillsPromptBlock } = await import("./agents-bundle.js");
         const bundle = await loadAgentsBundle();
+        // Workspace-core AGENTS.md (enterprise-wide instructions), if present.
+        if (bundle.workspaceAgentsMd && bundle.workspaceAgentsMd.trim()) {
+            sections.push(`<resource name="AGENTS.md" scope="workspace">\n${bundle.workspaceAgentsMd.trim()}\n</resource>`);
+        }
+        // 2. Template AGENTS.md.
         if (bundle.agentsMd.trim()) {
             sections.push(`<resource name="AGENTS.md" scope="template">\n${bundle.agentsMd.trim()}\n</resource>`);
         }
@@ -636,12 +1144,12 @@ async function loadResourcesForPrompt(owner) {
         }
     }
     catch { }
-    // 3. Personal SQL scope (skip if owner is the shared sentinel)
+    // 3. Personal memory index (skip if owner is the shared sentinel)
     if (owner !== SHARED_OWNER) {
         try {
-            const personal = await resourceGetByPath(owner, "LEARNINGS.md");
-            if (personal?.content?.trim()) {
-                sections.push(`<resource name="LEARNINGS.md" scope="personal">\n${personal.content.trim()}\n</resource>`);
+            const memoryIndex = await resourceGetByPath(owner, "memory/MEMORY.md");
+            if (memoryIndex?.content?.trim()) {
+                sections.push(`<resource name="memory/MEMORY.md" scope="personal">\n${memoryIndex.content.trim()}\n</resource>`);
             }
         }
         catch { }
@@ -656,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: process.env.AGENT_ORG_ID ?? null,
-            hasRawDbTools,
+            orgId: getRequestOrgId() ?? null,
+            hasRawDbTools: true,
         });
     }
     catch {
@@ -851,19 +1362,92 @@ 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.
+        let mcpConfig = loadMcpConfig();
+        if (!mcpConfig) {
+            mcpConfig = autoDetectMcpConfig();
+            if (mcpConfig) {
+                const detected = Object.keys(mcpConfig.servers).join(", ");
+                console.log(`[mcp-client] auto-detected ${detected}, registering as MCP server — set AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1 to opt out`);
+            }
+            else {
+                console.log("[mcp-client] no mcp.config.json and no auto-detectable servers — skipping MCP tools");
+            }
+        }
+        else if (mcpConfig.source) {
+            console.log(`[mcp-client] loaded config from ${mcpConfig.source} (${Object.keys(mcpConfig.servers).length} server(s))`);
+        }
+        const mcpManager = new McpClientManager(mcpConfig);
+        try {
+            await mcpManager.start();
+        }
+        catch (err) {
+            console.warn(`[mcp-client] start() failed: ${err?.message ?? err}. Continuing without MCP tools.`);
+        }
+        setGlobalMcpManager(mcpManager);
+        const mcpActionEntries = mcpToolsToActionEntries(mcpManager);
+        // Mount status route so tooling/onboarding can inspect MCP state.
+        mountMcpStatusRoute(nitroApp, mcpManager);
+        // Ensure we tear down child processes if the host shuts down cleanly.
+        if (typeof process !== "undefined" &&
+            typeof process.once === "function" &&
+            !globalThis.__agentNativeMcpExitHooked) {
+            globalThis.__agentNativeMcpExitHooked = true;
+            const stop = () => {
+                const mgr = getGlobalMcpManager();
+                if (mgr)
+                    void mgr.stop();
+            };
+            process.once("exit", stop);
+            process.once("SIGTERM", stop);
+            process.once("SIGINT", stop);
+        }
         // Resolve actions — prefer `actions`, fall back to deprecated `scripts`
         const rawActions = options?.actions ?? options?.scripts;
         const templateScripts = typeof rawActions === "function"
             ? await rawActions()
             : (rawActions ?? {});
-        // Resource, chat, 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()),
             ...engineScripts,
         };
         const callAgentScript = await createCallAgentScriptEntry(options?.appId);
+        let _currentRequestOrigin = "http://localhost:3000";
+        const browserTools = createBuilderBrowserTool({
+            getOrigin: () => _currentRequestOrigin,
+        });
         // Auto-mount A2A protocol endpoints so every app is discoverable
         // and callable by other agents via the standard protocol.
         // In dev mode, include dev scripts (filesystem-discovered) so the A2A agent
@@ -1001,16 +1585,23 @@ export function createAgentChatPlugin(options) {
         const allScripts = canToggle
             ? {
                 ...resourceScripts,
+                ...docsScripts,
                 ...chatScripts,
                 ...callAgentScript,
+                ...browserTools,
                 ...devScriptsForA2A,
             }
             : {
                 ...discoveredActions,
                 ...templateScripts,
                 ...resourceScripts,
+                ...docsScripts,
+                ...dbScripts,
+                ...refreshScreenTool,
+                ...urlTools,
                 ...chatScripts,
                 ...callAgentScript,
+                ...browserTools,
                 ...devScriptsForA2A,
             };
         const { mountA2A } = await import("../a2a/server.js");
@@ -1083,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 ??
@@ -1097,16 +1689,23 @@ 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,
                         ...chatScripts,
+                        ...browserTools,
                         ...devScriptsForA2A,
                     }
                     : {
                         ...templateScripts,
                         ...resourceScripts,
+                        ...docsScripts,
+                        ...dbScripts,
+                        ...refreshScreenTool,
+                        ...urlTools,
                         ...chatScripts,
+                        ...browserTools,
                     };
                 const a2aTools = actionsToEngineTools(a2aActions);
                 const a2aMessages = [
@@ -1189,21 +1788,27 @@ 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,
                         ...chatScripts,
                         ...devScriptsForA2A,
                     }
                     : {
                         ...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 = "";
@@ -1309,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
@@ -1317,21 +1923,31 @@ 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.
                     ...resourceScripts,
+                    ...docsScripts,
                     ...chatScripts,
                     ...devScriptsForA2A,
                 }
                 : {
                     ...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,
@@ -1352,22 +1968,44 @@ export function createAgentChatPlugin(options) {
         const prodActions = {
             ...templateScripts,
             ...resourceScripts,
+            ...docsScripts,
+            ...dbScripts,
+            ...refreshScreenTool,
+            ...urlTools,
             ...chatScripts,
             ...callAgentScript,
             ...teamTools,
             ...jobTools,
+            ...browserTools,
+            ...mcpActionEntries,
         };
         // 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 ??
@@ -1398,20 +2036,27 @@ export function createAgentChatPlugin(options) {
             // listed in the dev system prompt's "Available Actions" section.
             const devActions = {
                 ...resourceScripts,
+                ...docsScripts,
                 ...chatScripts,
                 ...callAgentScript,
                 ...teamTools,
                 ...jobTools,
+                ...browserTools,
+                ...mcpActionEntries,
                 ...(await createDevScriptRegistry()),
             };
             devHandler = createProductionAgentHandler({
                 actions: devActions,
                 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, true);
-                    _currentRunSystemPrompt = devPrompt + resources + schemaBlock;
+                    const extra = await resolveExtraContext(event, owner);
+                    _currentRunSystemPrompt = devPrompt + resources + schemaBlock + extra;
                     return _currentRunSystemPrompt;
                 },
                 model: options?.model,
@@ -1432,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") {
@@ -1452,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);
@@ -1470,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
@@ -1750,7 +2454,29 @@ export function createAgentChatPlugin(options) {
                             }
                         })());
                     }
-                    // 4. Peer agent discovery (network call — often slowest)
+                    // 4. Custom workspace agents
+                    sources.push((async () => {
+                        try {
+                            const owner = await getOwnerFromEvent(event);
+                            const { listAccessibleCustomAgents } = await import("../resources/agents.js");
+                            const agents = await listAccessibleCustomAgents(owner);
+                            flush(agents.map((agent) => ({
+                                id: `custom-agent:${agent.id}`,
+                                label: agent.name,
+                                description: agent.description || agent.path,
+                                icon: "agent",
+                                source: "agent:custom",
+                                refType: "custom-agent",
+                                refPath: agent.path,
+                                refId: agent.id,
+                                section: "Agents",
+                            })));
+                        }
+                        catch (e) {
+                            console.error("[agent-native] Custom agent discovery failed:", e);
+                        }
+                    })());
+                    // 5. Peer agent discovery (network call — often slowest)
                     sources.push((async () => {
                         try {
                             const agents = await discoverAgents(options?.appId);
@@ -1763,7 +2489,7 @@ export function createAgentChatPlugin(options) {
                                 refType: "agent",
                                 refPath: agent.url,
                                 refId: agent.id,
-                                section: "Agents",
+                                section: "Connected Agents",
                             })));
                         }
                         catch (e) {
@@ -1786,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") {
@@ -1795,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) };
@@ -1973,34 +2703,34 @@ export function createAgentChatPlugin(options) {
                 setResponseStatus(event, 404);
                 return { error: "Not found" };
             }
-            // Set AGENT_USER_EMAIL so scripts resolve the same owner as the session.
-            // Without this, scripts default to "local@localhost" and miss resources
-            // created by users who authenticated via OAuth (e.g., Gmail).
+            // Resolve per-request auth context
             const owner = await getOwnerFromEvent(event);
-            process.env.AGENT_USER_EMAIL = owner;
-            // Set AGENT_ORG_ID so db-query/db-exec scope by org_id when applicable.
-            // Priority: explicit resolveOrgId callback > session.orgId from Better Auth
-            let resolvedOrgId = null;
+            // Resolve org ID: explicit callback > session.orgId from Better Auth
+            let resolvedOrgId;
             if (options?.resolveOrgId) {
-                resolvedOrgId = await options.resolveOrgId(event);
+                resolvedOrgId = (await options.resolveOrgId(event)) ?? undefined;
             }
             else {
                 try {
                     const session = await getSession(event);
-                    resolvedOrgId = session?.orgId ?? null;
+                    resolvedOrgId = session?.orgId ?? undefined;
                 }
                 catch {
                     // Session not available
                 }
             }
+            // Also set process.env for backwards compat (CLI scripts, legacy readers)
+            process.env.AGENT_USER_EMAIL = owner;
             if (resolvedOrgId) {
                 process.env.AGENT_ORG_ID = resolvedOrgId;
             }
             else {
                 delete process.env.AGENT_ORG_ID;
             }
-            const handler = currentDevMode && devHandler ? devHandler : prodHandler;
-            return handler(event);
+            return runWithRequestContext({ userEmail: owner, orgId: resolvedOrgId }, () => {
+                const handler = currentDevMode && devHandler ? devHandler : prodHandler;
+                return handler(event);
+            });
         }));
         // ─── Recurring Jobs Scheduler ──────────────────────────────────────
         // Poll every 60 seconds for due recurring jobs and execute them.
@@ -2012,6 +2742,7 @@ export function createAgentChatPlugin(options) {
                 getActions: () => ({
                     ...templateScripts,
                     ...resourceScripts,
+                    ...docsScripts,
                     ...chatScripts,
                     ...jobTools,
                 }),
@@ -2045,4 +2776,35 @@ export function createAgentChatPlugin(options) {
  * In production, provides only the default system prompt.
  */
 export const defaultAgentChatPlugin = createAgentChatPlugin();
+// ---------------------------------------------------------------------------
+// MCP client glue — a shared manager reference + a /_agent-native/mcp/status
+// route so onboarding / settings UIs can see which MCP servers are live.
+// ---------------------------------------------------------------------------
+let _globalMcpManager = null;
+function setGlobalMcpManager(manager) {
+    _globalMcpManager = manager;
+}
+/** Internal: access the current process's MCP client manager, if any. */
+export function getGlobalMcpManager() {
+    return _globalMcpManager;
+}
+function mountMcpStatusRoute(nitroApp, manager) {
+    // Idempotent — agent-chat-plugin can be invoked once per process; guard anyway.
+    if (globalThis.__agentNativeMcpStatusMounted)
+        return;
+    globalThis.__agentNativeMcpStatusMounted = true;
+    try {
+        getH3App(nitroApp).use("/_agent-native/mcp/status", defineEventHandler(async (event) => {
+            if (getMethod(event) !== "GET") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            setResponseHeader(event, "Content-Type", "application/json");
+            return manager.getStatus();
+        }));
+    }
+    catch (err) {
+        console.warn(`[mcp-client] Failed to mount /_agent-native/mcp/status: ${err?.message ?? err}`);
+    }
+}
 //# sourceMappingURL=agent-chat-plugin.js.map