@agent-native/core 0.7.12 → 0.7.13

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

@@ -14,7 +14,7 @@ import { createThread, getThread, listThreads, searchThreads, updateThreadData,
 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";
+import { getBuilderBrowserConnectUrl } 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.
@@ -74,6 +74,44 @@ function wrapCliScript(tool, cliDefault, opts) {
         },
     };
 }
+/**
+ * Creates the `get-framework-context` tool. Returns detailed instructions
+ * for framework capabilities that are summarized in the compact prompt.
+ * The agent calls this on-demand when it needs specifics about embeds,
+ * agent teams, recurring jobs, etc.
+ */
+function createFrameworkContextEntry() {
+    const topicList = Object.keys(FRAMEWORK_CONTEXT_SECTIONS).join(", ");
+    return {
+        "get-framework-context": {
+            tool: {
+                description: `Read detailed framework instructions for a specific capability. Available topics: ${topicList}. Call with topic="all" to get everything.`,
+                parameters: {
+                    type: "object",
+                    properties: {
+                        topic: {
+                            type: "string",
+                            description: `Topic to read. One of: ${topicList}, or "all" for everything.`,
+                        },
+                    },
+                    required: ["topic"],
+                },
+            },
+            run: async (args) => {
+                const topic = String(args.topic ?? "all").toLowerCase();
+                if (topic === "all") {
+                    return Object.values(FRAMEWORK_CONTEXT_SECTIONS).join("\n\n");
+                }
+                const section = FRAMEWORK_CONTEXT_SECTIONS[topic];
+                if (!section) {
+                    return `Unknown topic "${topic}". Available: ${topicList}`;
+                }
+                return section;
+            },
+            readOnly: true,
+        },
+    };
+}
 /**
  * Creates the `refresh-screen` tool. Writes a bump to `application_state`
  * under a well-known key; the client's `useDbSync` watches for this and
@@ -370,91 +408,87 @@ async function createResourceScriptEntries() {
             import("../scripts/resources/save-memory.js"),
             import("../scripts/resources/delete-memory.js"),
         ]);
+        // Wrap each CLI runner so it captures stdout and converts args properly
+        const listEntry = wrapCliScript({
+            description: "",
+            parameters: { type: "object", properties: {} },
+        }, list.default, { readOnly: true });
+        const readEntry = wrapCliScript({
+            description: "",
+            parameters: { type: "object", properties: {} },
+        }, read.default, { readOnly: true });
+        const writeEntry = wrapCliScript({
+            description: "",
+            parameters: { type: "object", properties: {} },
+        }, write.default);
+        const deleteEntry = wrapCliScript({
+            description: "",
+            parameters: { type: "object", properties: {} },
+        }, del.default);
         return {
-            "resource-list": wrapCliScript({
-                description: "List resources (persistent files/notes). Returns file paths, sizes, and metadata.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        prefix: {
-                            type: "string",
-                            description: "Filter by path prefix (e.g. 'notes/')",
-                        },
-                        scope: {
-                            type: "string",
-                            description: "Which resources to list: personal, shared, or all (default: all)",
-                            enum: ["personal", "shared", "all"],
-                        },
-                        format: {
-                            type: "string",
-                            description: 'Output format: "json" or "text" (default: text)',
-                            enum: ["json", "text"],
-                        },
-                    },
-                },
-            }, list.default),
-            "resource-read": wrapCliScript({
-                description: "Read a resource by path. Returns the file contents.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "Resource path (e.g. 'LEARNINGS.md', 'notes/ideas.md')",
-                        },
-                        scope: {
-                            type: "string",
-                            description: "personal or shared (default: personal, falls back to shared)",
-                            enum: ["personal", "shared"],
-                        },
-                    },
-                    required: ["path"],
-                },
-            }, read.default),
-            "resource-write": wrapCliScript({
-                description: "Write or update a resource. Creates the resource if it doesn't exist.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "Resource path (e.g. 'LEARNINGS.md', 'notes/ideas.md')",
-                        },
-                        content: {
-                            type: "string",
-                            description: "The content to write",
-                        },
-                        scope: {
-                            type: "string",
-                            description: "personal or shared (default: personal)",
-                            enum: ["personal", "shared"],
-                        },
-                        mime: {
-                            type: "string",
-                            description: "MIME type (default: inferred from extension)",
+            resources: {
+                tool: {
+                    description: 'Manage persistent user files and notes. Actions: "list" (browse), "read" (get contents), "write" (create/update), "delete" (remove).',
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            action: {
+                                type: "string",
+                                description: "The operation to perform",
+                                enum: ["list", "read", "write", "delete"],
+                            },
+                            path: {
+                                type: "string",
+                                description: "Resource path (e.g. 'LEARNINGS.md', 'notes/ideas.md'). Required for read/write/delete.",
+                            },
+                            content: {
+                                type: "string",
+                                description: "Content to write. Required for write.",
+                            },
+                            scope: {
+                                type: "string",
+                                description: "personal, shared, or all (default varies by action)",
+                                enum: ["personal", "shared", "all"],
+                            },
+                            prefix: {
+                                type: "string",
+                                description: "Filter by path prefix when listing (e.g. 'notes/')",
+                            },
+                            mime: {
+                                type: "string",
+                                description: "MIME type for write (default: inferred from extension)",
+                            },
+                            format: {
+                                type: "string",
+                                description: 'Output format for list: "json" or "text" (default: text)',
+                                enum: ["json", "text"],
+                            },
                         },
+                        required: ["action"],
                     },
-                    required: ["path", "content"],
                 },
-            }, write.default),
-            "resource-delete": wrapCliScript({
-                description: "Delete a resource by path.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "Resource path to delete",
-                        },
-                        scope: {
-                            type: "string",
-                            description: "personal or shared (default: personal)",
-                            enum: ["personal", "shared"],
-                        },
-                    },
-                    required: ["path"],
+                run: async (args) => {
+                    const { action: a, ...rest } = args;
+                    if (a === "list")
+                        return listEntry.run(rest);
+                    if (a === "read") {
+                        if (!rest.path)
+                            return "Error: path is required for read";
+                        return readEntry.run(rest);
+                    }
+                    if (a === "write") {
+                        if (!rest.path || !rest.content)
+                            return "Error: path and content are required for write";
+                        return writeEntry.run(rest);
+                    }
+                    if (a === "delete") {
+                        if (!rest.path)
+                            return "Error: path is required for delete";
+                        return deleteEntry.run(rest);
+                    }
+                    return `Error: unknown action "${a}". Use: list, read, write, delete`;
                 },
-            }, 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: {
@@ -502,7 +536,7 @@ async function createResourceScriptEntries() {
     }
 }
 /**
- * Creates chat management ActionEntries (search-chats, open-chat).
+ * Creates a unified chat-history ActionEntry that dispatches to search or open.
  */
 async function createChatScriptEntries() {
     try {
@@ -510,41 +544,80 @@ async function createChatScriptEntries() {
             import("../scripts/chat/search-chats.js"),
             import("../scripts/chat/open-chat.js"),
         ]);
-        return {
-            "search-chats": wrapCliScript({
-                description: "Search or list past agent chat threads. Use this to find previous conversations by keyword.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        query: {
-                            type: "string",
-                            description: "Search term to find chats by title, preview, or content",
-                        },
-                        limit: {
-                            type: "string",
-                            description: "Max number of results (default: 20)",
-                        },
-                        format: {
-                            type: "string",
-                            description: "Output format",
-                            enum: ["json", "text"],
-                        },
+        const searchEntry = wrapCliScript({
+            description: "Search or list past agent chat threads.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Search term to find chats by title, preview, or content",
+                    },
+                    limit: {
+                        type: "string",
+                        description: "Max number of results (default: 20)",
+                    },
+                    format: {
+                        type: "string",
+                        description: "Output format",
+                        enum: ["json", "text"],
                     },
                 },
-            }, searchMod.default),
-            "open-chat": wrapCliScript({
-                description: "Open a chat thread in the UI as a new tab and focus it. Use search-chats first to find the thread ID.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        id: {
-                            type: "string",
-                            description: "The chat thread ID to open",
+            },
+        }, searchMod.default);
+        const openEntry = wrapCliScript({
+            description: "Open a chat thread in the UI.",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: {
+                        type: "string",
+                        description: "The chat thread ID to open",
+                    },
+                },
+                required: ["id"],
+            },
+        }, openMod.default);
+        return {
+            "chat-history": {
+                tool: {
+                    description: "Manage past agent chat threads. Use action 'search' to find previous conversations by keyword, or 'open' to open a thread in the UI.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            action: {
+                                type: "string",
+                                description: "The operation to perform",
+                                enum: ["search", "open"],
+                            },
+                            query: {
+                                type: "string",
+                                description: "(search) Search term to find chats by title, preview, or content",
+                            },
+                            limit: {
+                                type: "string",
+                                description: "(search) Max number of results (default: 20)",
+                            },
+                            format: {
+                                type: "string",
+                                description: "(search) Output format",
+                                enum: ["json", "text"],
+                            },
+                            id: {
+                                type: "string",
+                                description: "(open) The chat thread ID to open",
+                            },
                         },
+                        required: ["action"],
                     },
-                    required: ["id"],
                 },
-            }, openMod.default),
+                run: async (args) => {
+                    if (args?.action === "open") {
+                        return openEntry.run(args);
+                    }
+                    return searchEntry.run(args);
+                },
+            },
         };
     }
     catch {
@@ -552,20 +625,14 @@ async function createChatScriptEntries() {
     }
 }
 /**
- * Creates agent engine management tools (list-agent-engines, set-agent-engine,
- * test-agent-engine). Let the agent inspect and configure the active LLM engine.
+ * Creates the consolidated manage-agent-engine tool (list / set / test).
+ * Let the agent inspect and configure the active LLM engine.
  */
 async function createAgentEngineScriptEntries() {
     try {
-        const [listMod, setMod, testMod] = await Promise.all([
-            import("../scripts/agent-engines/list-agent-engines.js"),
-            import("../scripts/agent-engines/set-agent-engine.js"),
-            import("../scripts/agent-engines/test-agent-engine.js"),
-        ]);
+        const mod = await import("../scripts/agent-engines/manage-agent-engine.js");
         return {
-            "list-agent-engines": { tool: listMod.tool, run: listMod.run },
-            "set-agent-engine": { tool: setMod.tool, run: setMod.run },
-            "test-agent-engine": { tool: testMod.tool, run: testMod.run },
+            "manage-agent-engine": { tool: mod.tool, run: mod.run },
         };
     }
     catch {
@@ -611,270 +678,178 @@ function createBuilderBrowserTool(deps) {
                 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.
+ * Creates the unified `agent-teams` tool that consolidates all sub-agent
+ * orchestration behind a single tool with an `action` parameter.
  */
 function createTeamTools(deps) {
     return {
-        "spawn-task": {
+        "agent-teams": {
             tool: {
-                description: "Spawn a sub-agent to handle a task in the background. The sub-agent runs independently with its own conversation thread. Use this to delegate work so the main chat stays free for new requests. A live preview card will appear in the chat showing the sub-agent's progress.",
+                description: "Manage sub-agent tasks. Use action 'spawn' to start a new sub-agent, 'status' to check progress, 'read-result' to get a finished task's output, 'send' to message a running sub-agent, or 'list' to see all tasks.",
                 parameters: {
                     type: "object",
                     properties: {
+                        action: {
+                            type: "string",
+                            enum: ["spawn", "status", "read-result", "send", "list"],
+                            description: "The operation to perform",
+                        },
                         task: {
                             type: "string",
-                            description: "Clear description of what the sub-agent should accomplish",
+                            description: "(spawn) Clear description of what the sub-agent should accomplish",
                         },
                         instructions: {
                             type: "string",
-                            description: "Optional additional instructions or context for the sub-agent",
+                            description: "(spawn) Optional additional instructions or context for the sub-agent",
                         },
                         name: {
                             type: "string",
-                            description: "Short name for the sub-agent tab (e.g. 'Research', 'Draft email'). If omitted, derived from the task.",
+                            description: "(spawn) 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.",
+                            description: "(spawn) Optional custom agent profile from agents/*.md to use for this task.",
                         },
-                    },
-                    required: ["task"],
-                },
-            },
-            run: async (args) => {
-                // Capture the send function NOW (at spawn time) so that
-                // concurrent runs don't clobber each other's send reference.
-                const capturedSend = deps.getSend();
-                const { spawnTask } = await import("./agent-teams.js");
-                // Filter out team orchestration tools so sub-agents can't spawn sub-agents
-                const teamToolNames = new Set([
-                    "spawn-task",
-                    "task-status",
-                    "read-task-result",
-                    "send-to-task",
-                    "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,
-                    ownerEmail: deps.getOwner(),
-                    systemPrompt: deps.getSystemPrompt(),
-                    actions: subAgentActions,
-                    engine: deps.getEngine(),
-                    model: selectedModel,
-                    parentThreadId: deps.getParentThreadId(),
-                    parentSend: (event) => {
-                        if (capturedSend)
-                            capturedSend(event);
-                    },
-                });
-                return JSON.stringify({
-                    taskId: task.taskId,
-                    threadId: task.threadId,
-                    status: task.status,
-                    description: task.description,
-                    name: selectedName,
-                });
-            },
-        },
-        "task-status": {
-            tool: {
-                description: "Check the status of a sub-agent task. Returns current status, preview of output, and current step.",
-                parameters: {
-                    type: "object",
-                    properties: {
                         taskId: {
                             type: "string",
-                            description: "The task ID returned by spawn-task",
+                            description: "(status, read-result, send) The task ID returned by a previous spawn",
                         },
-                    },
-                    required: ["taskId"],
-                },
-            },
-            run: async (args) => {
-                const { getTask } = await import("./agent-teams.js");
-                const task = await getTask(args.taskId);
-                if (!task)
-                    return JSON.stringify({ error: "Task not found" });
-                return JSON.stringify({
-                    taskId: task.taskId,
-                    threadId: task.threadId,
-                    status: task.status,
-                    description: task.description,
-                    preview: task.preview,
-                    currentStep: task.currentStep,
-                    summary: task.summary,
-                });
-            },
-        },
-        "read-task-result": {
-            tool: {
-                description: "Read the result of a completed sub-agent task. Returns the full output summary.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        taskId: {
+                        message: {
                             type: "string",
-                            description: "The task ID returned by spawn-task",
+                            description: "(send) Message to send to the sub-agent",
                         },
                     },
-                    required: ["taskId"],
+                    required: ["action"],
                 },
             },
             run: async (args) => {
-                const { getTask } = await import("./agent-teams.js");
-                const task = await getTask(args.taskId);
-                if (!task)
-                    return JSON.stringify({ error: "Task not found" });
-                if (task.status === "running") {
+                const action = args.action;
+                // ── spawn ──────────────────────────────────────────────
+                if (action === "spawn") {
+                    if (!args.task)
+                        throw new Error("'task' is required for spawn");
+                    // Capture the send function NOW (at spawn time) so that
+                    // concurrent runs don't clobber each other's send reference.
+                    const capturedSend = deps.getSend();
+                    const { spawnTask } = await import("./agent-teams.js");
+                    // Filter out the team tool so sub-agents can't spawn sub-agents
+                    const subAgentActions = Object.fromEntries(Object.entries(deps.getActions()).filter(([name]) => name !== "agent-teams"));
+                    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,
+                        ownerEmail: deps.getOwner(),
+                        systemPrompt: deps.getSystemPrompt(),
+                        actions: subAgentActions,
+                        engine: deps.getEngine(),
+                        model: selectedModel,
+                        parentThreadId: deps.getParentThreadId(),
+                        parentSend: (event) => {
+                            if (capturedSend)
+                                capturedSend(event);
+                        },
+                    });
                     return JSON.stringify({
-                        status: "running",
+                        taskId: task.taskId,
+                        threadId: task.threadId,
+                        status: task.status,
+                        description: task.description,
+                        name: selectedName,
+                    });
+                }
+                // ── status ─────────────────────────────────────────────
+                if (action === "status") {
+                    if (!args.taskId)
+                        throw new Error("'taskId' is required for status");
+                    const { getTask } = await import("./agent-teams.js");
+                    const task = await getTask(args.taskId);
+                    if (!task)
+                        return JSON.stringify({ error: "Task not found" });
+                    return JSON.stringify({
+                        taskId: task.taskId,
+                        threadId: task.threadId,
+                        status: task.status,
+                        description: task.description,
                         preview: task.preview,
-                        message: "Task is still running. Check back later.",
+                        currentStep: task.currentStep,
+                        summary: task.summary,
                     });
                 }
-                return JSON.stringify({
-                    taskId: task.taskId,
-                    status: task.status,
-                    summary: task.summary,
-                    preview: task.preview,
-                });
-            },
-        },
-        "send-to-task": {
-            tool: {
-                description: "Send a message or update to a running sub-agent. Use this to redirect, add context, or give feedback to a sub-agent while it's working.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        taskId: {
-                            type: "string",
-                            description: "The task ID returned by spawn-task",
-                        },
-                        message: {
-                            type: "string",
-                            description: "Message to send to the sub-agent",
-                        },
-                    },
-                    required: ["taskId", "message"],
-                },
-            },
-            run: async (args) => {
-                const { sendToTask } = await import("./agent-teams.js");
-                const result = await sendToTask(args.taskId, args.message);
-                return JSON.stringify(result);
-            },
-        },
-        "list-tasks": {
-            tool: {
-                description: "List all sub-agent tasks and their current status. Use this to see what's running, completed, or failed.",
-                parameters: {
-                    type: "object",
-                    properties: {},
-                },
-            },
-            run: async () => {
-                const { listTasks } = await import("./agent-teams.js");
-                const tasks = await listTasks();
-                if (tasks.length === 0) {
-                    return "No sub-agent tasks.";
-                }
-                return JSON.stringify(tasks.map((t) => ({
-                    taskId: t.taskId,
-                    threadId: t.threadId,
-                    description: t.description,
-                    status: t.status,
-                    currentStep: t.currentStep,
-                    hasResult: t.summary.length > 0,
-                })), null, 2);
+                // ── read-result ────────────────────────────────────────
+                if (action === "read-result") {
+                    if (!args.taskId)
+                        throw new Error("'taskId' is required for read-result");
+                    const { getTask } = await import("./agent-teams.js");
+                    const task = await getTask(args.taskId);
+                    if (!task)
+                        return JSON.stringify({ error: "Task not found" });
+                    if (task.status === "running") {
+                        return JSON.stringify({
+                            status: "running",
+                            preview: task.preview,
+                            message: "Task is still running. Check back later.",
+                        });
+                    }
+                    return JSON.stringify({
+                        taskId: task.taskId,
+                        status: task.status,
+                        summary: task.summary,
+                        preview: task.preview,
+                    });
+                }
+                // ── send ───────────────────────────────────────────────
+                if (action === "send") {
+                    if (!args.taskId)
+                        throw new Error("'taskId' is required for send");
+                    if (!args.message)
+                        throw new Error("'message' is required for send");
+                    const { sendToTask } = await import("./agent-teams.js");
+                    const result = await sendToTask(args.taskId, args.message);
+                    return JSON.stringify(result);
+                }
+                // ── list ───────────────────────────────────────────────
+                if (action === "list") {
+                    const { listTasks } = await import("./agent-teams.js");
+                    const tasks = await listTasks();
+                    if (tasks.length === 0) {
+                        return "No sub-agent tasks.";
+                    }
+                    return JSON.stringify(tasks.map((t) => ({
+                        taskId: t.taskId,
+                        threadId: t.threadId,
+                        description: t.description,
+                        status: t.status,
+                        currentStep: t.currentStep,
+                        hasResult: t.summary.length > 0,
+                    })), null, 2);
+                }
+                throw new Error(`Unknown action '${action}'. Use one of: spawn, status, read-result, send, list`);
             },
         },
     };
@@ -885,7 +860,157 @@ function createTeamTools(deps) {
  * Template AGENTS.md resources only need template-specific content.
  */
 /**
- * Framework instructions shared across both modes. The mode-specific
+ * Compact framework instructions for lazy-context mode. Keeps the critical
+ * behavioral rules but defers verbose details (chat history, agent teams,
+ * recurring jobs, builder.io, browser, A2A, structured memory) behind the
+ * `get-framework-context` tool.
+ */
+const FRAMEWORK_CORE_COMPACT = `
+### Core Rules
+
+1. **Data lives in SQL** — All app state is in a SQL database. Use the available database tools. Call \`db-schema\` to see the full schema when needed.
+2. **Context awareness** — The user's current screen state is in \`<current-screen>\`, current URL in \`<current-url>\`. Use both to understand what the user is looking at. To change URL state, use \`set-search-params\` or \`set-url-path\`.
+3. **Navigate the UI** — Use the \`navigate\` tool to switch views, open items, or focus elements.
+4. **Application state** — Ephemeral UI state lives in \`application_state\`. Use \`readAppState\`/\`writeAppState\`.
+5. **Screen refresh is automatic** — The framework auto-refreshes after mutating tool calls. Only call \`refresh-screen\` when you mutated data via a path the framework can't detect.
+6. **Memory** — Use \`save-memory\` proactively when you learn preferences, corrections, or project context.
+7. **Security** — Always use parameterized queries. Never \`dangerouslySetInnerHTML\`, \`innerHTML\`, or \`eval()\`.
+
+### Resources
+
+Use resource-list, resource-read, resource-write, resource-delete for persistent notes and context files.
+Resources are NOT an agent scratchpad — never create executable scripts, task plans, or work-in-progress files.
+
+### Navigation Rule
+
+When the user says "show me", "go to", "open", etc., ALWAYS use \`navigate\` first.
+
+### Extended Capabilities
+
+You also have tools for: inline embeds, chat history search, agent teams/sub-agents, recurring jobs, A2A cross-app calls, structured memory, and browser access. Call \`get-framework-context\` to read detailed instructions for any of these when needed.
+`;
+/**
+ * Verbose framework sections returned by the `get-framework-context` tool.
+ * Keyed by topic so the agent can request specific sections.
+ */
+const FRAMEWORK_CONTEXT_SECTIONS = {
+    embeds: `### 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. 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.
+
+Use for charts, visualizations, previews. Don't use for simple text/tables or external sites.`,
+    "chat-history": `### Chat History
+
+You can search and restore previous chat conversations using \`chat-history\`:
+- \`chat-history\` (action: "search") — Search or list past chat threads by keyword
+- \`chat-history\` (action: "open") — Open a chat thread in the UI as a new tab and focus it
+
+When the user asks to find a previous conversation, use \`chat-history\` with action "search" first to find matching threads, then action "open" to restore the one they want.`,
+    "agent-teams": `### Agent Teams — Orchestration
+
+You are an orchestrator. For complex or multi-step tasks, delegate to sub-agents using the \`agent-teams\` tool:
+- \`agent-teams\` (action: "spawn") — Spawn a sub-agent for a task. It runs in its own thread while you stay available.
+- \`agent-teams\` (action: "status") — Check the progress of a running sub-agent.
+- \`agent-teams\` (action: "read-result") — Read the result when a sub-agent finishes.
+- \`agent-teams\` (action: "send") — Send a message to a running sub-agent.
+- \`agent-teams\` (action: "list") — List all sub-agent tasks.
+
+**When to delegate vs do directly:**
+- **Delegate** when the task involves multiple tool calls, research, content generation, or anything that takes more than a few seconds.
+- **Do directly** for quick single-step tasks like navigation, reading state, or answering simple questions.
+- **Spawn multiple sub-agents** when the user asks for multiple independent things — they'll run in parallel.
+
+Sub-agents have access to all template tools but **cannot spawn sub-agents themselves**.`,
+    "recurring-jobs": `### Recurring Jobs
+
+You can create recurring jobs that run on a cron schedule. Jobs are resource files under \`jobs/\`.
+
+- \`manage-jobs\` (action: "create") — Create a new recurring job with a cron schedule and instructions
+- \`manage-jobs\` (action: "list") — List all recurring jobs and their status
+- \`manage-jobs\` (action: "update") — Update a job's schedule, instructions, or toggle enabled/disabled
+- Delete a job with \`resource-delete --path jobs/<name>.md\`
+
+Convert natural language to 5-field cron format:
+- "every morning" / "daily at 9am" → \`0 9 * * *\`
+- "every weekday at 9am" → \`0 9 * * 1-5\`
+- "every hour" → \`0 * * * *\`
+- "every monday at 9am" → \`0 9 * * 1\``,
+    builder: `### Connecting Builder.io
+
+When the user asks to connect Builder.io or you hit a "Builder not configured" error, call the \`connect-builder\` tool. It renders a one-click Connect card inline — do NOT write out multi-step setup instructions yourself.`,
+    browser: `### Browser Access
+
+Use \`connect-builder\` when you need browser access backed by Builder. It renders a Connect card that provisions a browser session.
+
+- If Builder is not configured, the card will guide the user through setup.`,
+    "call-agent": `### 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.
+
+**NEVER use \`call-agent\` to:**
+- Call your own app by name
+- Perform tasks you can accomplish with your own registered tools
+
+**ONLY use \`call-agent\` when:**
+- The user explicitly asks you to communicate with a different app
+- You need data that only another deployed app can provide`,
+    memory: `### Structured Memory
+
+Your memory index (\`memory/MEMORY.md\`) is loaded at the start of every conversation.
+
+**Tools:**
+- \`save-memory\` — Create or update a memory (name, type, description, content)
+- \`delete-memory\` — Remove a memory and its index entry
+- \`resource-read --path memory/<name>.md\` — Read the full content of a specific memory
+
+**Memory types:** user, feedback, project, reference
+
+**When to save (proactively):**
+- User corrects your approach → \`feedback\`
+- User shares preferences → \`user\`
+- Non-obvious pattern or gotcha → \`feedback\`
+- Personal context (contacts, team) → \`user\`
+- Project context to track → \`project\`
+
+**Rules:**
+- Don't save things obvious from code or standard framework behavior
+- When updating, read first and merge — don't overwrite
+- Keep descriptions concise
+- One memory per logical topic`,
+    "sql-tools": `### SQL Tools
+
+- \`db-schema\` — refresh the full schema with indexes and foreign keys
+- \`db-query\` — run a SELECT (read-only; results already filtered to the current user/org)
+- \`db-exec\` — run INSERT / UPDATE / DELETE (writes already scoped; owner_email and org_id are auto-injected on INSERT)
+- \`db-patch\` — surgical search-and-replace on a large text column. Use for edits to large fields instead of re-sending multi-kilobyte strings.
+
+### When to pick which SQL tool
+- Set a short column outright, update multiple columns, or do computed updates → \`db-exec UPDATE\`
+- Change a small slice of a large text/JSON column → \`db-patch\`
+- A template-specific action exists for the table → use that action (it encodes business rules and pushes live Yjs updates)
+- Read data → \`db-query\`. Never re-add \`WHERE owner_email = ...\` — scoping already applies it.
+
+### External data sources vs the app database
+The \`db-*\` tools ONLY query the app's own SQL database. They do NOT reach external data warehouses. If the user asks about tables NOT in the schema, use the appropriate template action instead.`,
+};
+/**
+ * Full framework instructions shared across both modes. The mode-specific
  * preamble is prepended by the prompt composition below.
  */
 const FRAMEWORK_CORE = `
@@ -902,12 +1027,12 @@ const FRAMEWORK_CORE = `
 ### Resources
 
 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.
+Use resource-list, resource-read, resource-write, resource-delete to manage resources.
 Resources can be personal (per-user) or shared (team-wide). By default, resources are personal.
 
 When the user gives instructions that should apply to all users/sessions, update the shared "AGENTS.md" resource.
 
-**Resources are NOT an agent scratchpad.** Never use \`resource-write\` to store executable scripts, task plans, retry notes, or work-in-progress files you're writing to yourself. Specifically, do NOT create resources under \`scripts/\` or \`tasks/\` unless the user explicitly asked for a file at that path, or a tool (like \`create-job\` or \`spawn-task\`) writes there as part of its contract. If you can't complete a task with the tools you have, say so — don't improvise by leaving behind \`FINAL-*.md\`, \`EXECUTE-NOW-*.js\`, or similar artifacts. Resources are visible to the user in the workspace sidebar; every file you write is something they'll see and have to clean up.
+**Resources are NOT an agent scratchpad.** Never use \`resource-write\` to store executable scripts, task plans, retry notes, or work-in-progress files you're writing to yourself. Specifically, do NOT create resources under \`scripts/\` or \`tasks/\` unless the user explicitly asked for a file at that path, or a tool (like \`manage-jobs\` or \`agent-teams\`) writes there as part of its contract. If you can't complete a task with the tools you have, say so — don't improvise by leaving behind \`FINAL-*.md\`, \`EXECUTE-NOW-*.js\`, or similar artifacts. Resources are visible to the user in the workspace sidebar; every file you write is something they'll see and have to clean up.
 
 ### Navigation Rule
 
@@ -946,18 +1071,20 @@ Which routes are renderable as embeds is template-specific — the app's \`AGENT
 
 ### Chat History
 
-You can search and restore previous chat conversations:
-- \`search-chats\` — Search or list past chat threads by keyword
-- \`open-chat\` — Open a chat thread in the UI as a new tab and focus it
+You can search and restore previous chat conversations using \`chat-history\`:
+- \`chat-history\` (action: "search") — Search or list past chat threads by keyword
+- \`chat-history\` (action: "open") — Open a chat thread in the UI as a new tab and focus it
 
-When the user asks to find a previous conversation, use \`search-chats\` first to find matching threads, then \`open-chat\` to restore the one they want.
+When the user asks to find a previous conversation, use \`chat-history\` with action "search" first to find matching threads, then action "open" to restore the one they want.
 
 ### 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. 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.
+You are an orchestrator. For complex or multi-step tasks, delegate to sub-agents using the \`agent-teams\` tool:
+- \`agent-teams\` (action: "spawn") — 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\`.
+- \`agent-teams\` (action: "status") — Check the progress of a running sub-agent.
+- \`agent-teams\` (action: "read-result") — Read the result when a sub-agent finishes.
+- \`agent-teams\` (action: "send") — Send a message to a running sub-agent.
+- \`agent-teams\` (action: "list") — List all sub-agent tasks.
 
 **When to delegate vs do directly:**
 - **Delegate** when the task involves multiple tool calls, research, content generation, or anything that takes more than a few seconds. Examples: "create a deck about X", "analyze the data and write a report", "look up Y and draft an email about it".
@@ -968,18 +1095,18 @@ You are an orchestrator. For complex or multi-step tasks, delegate to sub-agents
 1. When the user asks for something complex, spawn a sub-agent with a clear task description.
 2. Tell the user what you've started ("I'm having a sub-agent research that for you").
 3. You can keep chatting — sub-agents run independently.
-4. Use \`read-task-result\` to check results when needed, or the user can see live progress in the card.
+4. Use \`agent-teams\` (action: "read-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. If a matching custom agent profile exists, pass it via the \`agent\` parameter on \`spawn-task\`.
+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 \`agent-teams\` (action: "spawn").
 
 ### Recurring Jobs
 
 You can create recurring jobs that run on a cron schedule. Jobs are resource files under \`jobs/\`. Each job has a cron schedule and instructions that the agent executes automatically.
 
-- \`create-job\` — Create a new recurring job with a cron schedule and instructions
-- \`list-jobs\` — List all recurring jobs and their status (schedule, last run, next run, errors)
-- \`update-job\` — Update a job's schedule, instructions, or toggle enabled/disabled
+- \`manage-jobs\` (action: "create") — Create a new recurring job with a cron schedule and instructions
+- \`manage-jobs\` (action: "list") — List all recurring jobs and their status (schedule, last run, next run, errors)
+- \`manage-jobs\` (action: "update") — Update a job's schedule, instructions, or toggle enabled/disabled
 - Delete a job with \`resource-delete --path jobs/<name>.md\`
 
 When the user asks for something recurring ("every morning", "daily at 9am", "weekly on Mondays"), create a job. Convert natural language to 5-field cron format:
@@ -998,11 +1125,9 @@ When the user asks to connect Builder.io, needs Builder for LLM access / browser
 
 ### 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.
+Use \`connect-builder\` when you need browser access backed by Builder. It renders a Connect card that provisions a 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.
+- If Builder is not configured, the card will guide the user through setup.
 
 ### call-agent — External Apps Only
 
@@ -1068,7 +1193,7 @@ When the user asks you to change the UI, modify code, add a feature, fix a bug i
 - 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 spawn sub-agents (\`agent-teams\`) 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.
 
@@ -1098,6 +1223,34 @@ When editing code, follow the agent-native architecture:
 - No Node.js-specific APIs in server routes (must work on Cloudflare Workers, etc.)
 - Use shadcn/ui components and Tabler Icons for all UI work
 ${FRAMEWORK_CORE}`;
+const PROD_FRAMEWORK_PROMPT_COMPACT = `## Agent-Native Framework — Production Mode
+
+You are an AI agent in an agent-native application, running in **production mode**.
+
+The agent and the UI are equal partners — everything the UI can do, you can do via your tools, and vice versa. They share the same SQL database and stay in sync automatically.
+
+**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 — Call \`connect-builder\`
+
+When the user asks to change the UI, modify code, add a feature, or fix a bug in the app itself — call \`connect-builder\` immediately, passing the user's request as the \`prompt\`. Do NOT write code, list files, make plans, or spawn sub-agents for code changes. Builder handles it in the cloud. Mention \`npx agent-native create <app-name>\` as an offline fallback.
+${FRAMEWORK_CORE_COMPACT}`;
+const DEV_FRAMEWORK_PROMPT_COMPACT = `## Agent-Native Framework — Development Mode
+
+You are an AI agent in an agent-native application, running in **development mode**.
+
+The agent and the UI are equal partners — everything the UI can do, you can do via tools/scripts, and vice versa. They share the same SQL database and stay in sync automatically.
+
+**In development mode, you have UNRESTRICTED access.** You can run any shell command, read/write files, query the database, call external APIs, edit source code, and install packages.
+
+**Template-specific actions are invoked via shell, NOT as direct tools.** Run them with: \`shell({ command: 'pnpm action <name> --arg value' })\`. See the "Available Actions" section below for CLI syntax.
+
+When editing code, follow the agent-native architecture:
+- Every feature needs all four areas: UI + scripts + skills/instructions + application-state sync
+- All SQL must be dialect-agnostic (works on SQLite and Postgres)
+- No Node.js-specific APIs in server routes (must work on Cloudflare Workers, etc.)
+- Use shadcn/ui components and Tabler Icons for all UI work
+${FRAMEWORK_CORE_COMPACT}`;
 const DEFAULT_SYSTEM_PROMPT = PROD_FRAMEWORK_PROMPT;
 /**
  * Pre-load the agent's context: AGENTS.md (template instructions), the skills
@@ -1117,7 +1270,7 @@ const DEFAULT_SYSTEM_PROMPT = PROD_FRAMEWORK_PROMPT;
  * AGENTS.md and restarting the server is all it takes; Vite HMR invalidates
  * the bundle in dev so changes land instantly.
  */
-async function loadResourcesForPrompt(owner) {
+async function loadResourcesForPrompt(owner, compact = false) {
     await ensurePersonalDefaults(owner);
     const sections = [];
     // 1. Workspace AGENTS.md + skills merged into the template bundle.
@@ -1128,33 +1281,51 @@ async function loadResourcesForPrompt(owner) {
         if (bundle.workspaceAgentsMd && bundle.workspaceAgentsMd.trim()) {
             sections.push(`<resource name="AGENTS.md" scope="workspace">\n${bundle.workspaceAgentsMd.trim()}\n</resource>`);
         }
-        // 2. Template AGENTS.md.
+        // 2. Template AGENTS.md — always included (critical template instructions).
         if (bundle.agentsMd.trim()) {
             sections.push(`<resource name="AGENTS.md" scope="template">\n${bundle.agentsMd.trim()}\n</resource>`);
         }
-        const skillsBlock = generateSkillsPromptBlock(bundle);
-        if (skillsBlock)
-            sections.push(skillsBlock);
-    }
-    catch { }
-    // LEARNINGS.md from SQL (template-level instructions are in AGENTS.md above).
-    // 2. Shared SQL scope
-    try {
-        const shared = await resourceGetByPath(SHARED_OWNER, "LEARNINGS.md");
-        if (shared?.content?.trim()) {
-            sections.push(`<resource name="LEARNINGS.md" scope="shared">\n${shared.content.trim()}\n</resource>`);
+        // In compact mode, skip the full skills block — the agent can use
+        // `docs-search` to find skills when it needs them.
+        if (!compact) {
+            const skillsBlock = generateSkillsPromptBlock(bundle);
+            if (skillsBlock)
+                sections.push(skillsBlock);
+        }
+        else if (Object.keys(bundle.skills).length > 0) {
+            const names = Object.values(bundle.skills)
+                .map((s) => s.meta.name)
+                .join(", ");
+            sections.push(`<skills-summary>\nSkills available in .agents/skills/: ${names}. Use \`docs-search\` to read a skill before starting a task it applies to.\n</skills-summary>`);
         }
     }
     catch { }
-    // 3. Personal memory index (skip if owner is the shared sentinel)
-    if (owner !== SHARED_OWNER) {
+    if (compact) {
+        // In compact mode, skip learnings and memory in the prompt.
+        // The agent can access them via resource-read when needed.
+        // Add a brief pointer so the agent knows they exist.
+        sections.push(`<context-note>Shared learnings (LEARNINGS.md) and your personal memory (memory/MEMORY.md) are available via \`resource-read\`. Check them when making decisions that might benefit from prior context.</context-note>`);
+    }
+    else {
+        // LEARNINGS.md from SQL (template-level instructions are in AGENTS.md above).
+        // 2. Shared SQL scope
         try {
-            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>`);
+            const shared = await resourceGetByPath(SHARED_OWNER, "LEARNINGS.md");
+            if (shared?.content?.trim()) {
+                sections.push(`<resource name="LEARNINGS.md" scope="shared">\n${shared.content.trim()}\n</resource>`);
             }
         }
         catch { }
+        // 3. Personal memory index (skip if owner is the shared sentinel)
+        if (owner !== SHARED_OWNER) {
+            try {
+                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 { }
+        }
     }
     if (sections.length === 0)
         return "";
@@ -1272,11 +1443,9 @@ ${lines.join("\n")}`;
     }
     return `\n\n## Available Actions
 
-**Use these actions directly to accomplish tasks. Do NOT use \`db-schema\`, \`search-files\`, or \`shell\` to explore the app — these actions already connect to the correct database and services.**
-
-**For external data sources (BigQuery, HubSpot, Jira, GA4, etc.), use the data-source-specific action below — NOT \`db-query\`.** \`db-query\` only reaches the app's own internal database. If the user asks about tables not in the app schema, pick the matching action here.
+**Use these actions directly as tool calls.** They are your primary tools — they handle database access, validation, and business logic internally. Prefer these over lower-level tools like \`web-request\` or \`db-query\`.
 
-Parameter notation: \`name*\` = required, \`name?\` = optional. Always pass the tool's parameters as a JSON object to the tool_use call — never via shell or string-concatenated CLI flags.
+Parameter notation: \`name*\` = required, \`name?\` = optional. Pass parameters as a JSON object.
 
 ${lines.join("\n")}`;
 }
@@ -1467,16 +1636,31 @@ export function createAgentChatPlugin(options) {
                 process.once("SIGTERM", stop);
                 process.once("SIGINT", stop);
             }
-            // Resolve actions — prefer `actions`, fall back to deprecated `scripts`
+            // Resolve actions — prefer explicit `actions`, fall back to deprecated
+            // `scripts`. When neither is provided, auto-discover from the filesystem
+            // so templates that forget to pass `actions` still work in non-serverless
+            // deployments (serverless bundles need explicit imports).
             const rawActions = options?.actions ?? options?.scripts;
-            const templateScripts = typeof rawActions === "function"
+            let templateScripts = typeof rawActions === "function"
                 ? await rawActions()
                 : (rawActions ?? {});
+            if (!rawActions && Object.keys(templateScripts).length === 0) {
+                try {
+                    const { autoDiscoverActions } = await import("./action-discovery.js");
+                    templateScripts = await autoDiscoverActions(process.cwd());
+                }
+                catch {
+                    // Filesystem discovery unavailable (serverless bundle) — skip.
+                }
+            }
             // 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 frameworkContextTool = createFrameworkContextEntry();
+            const leanPrompt = options?.leanPrompt === true;
+            const lazyContext = options?.lazyContext !== false && !leanPrompt;
             const urlTools = createUrlTools();
             const engineScripts = await createAgentEngineScriptEntries();
             const chatScripts = {
@@ -1667,6 +1851,7 @@ export function createAgentChatPlugin(options) {
                 ? {
                     ...resourceScripts,
                     ...docsScripts,
+                    ...(lazyContext ? frameworkContextTool : {}),
                     ...chatScripts,
                     ...callAgentScript,
                     ...automationTools,
@@ -1683,6 +1868,7 @@ export function createAgentChatPlugin(options) {
                     ...docsScripts,
                     ...dbScripts,
                     ...refreshScreenTool,
+                    ...(lazyContext ? frameworkContextTool : {}),
                     ...urlTools,
                     ...chatScripts,
                     ...callAgentScript,
@@ -1767,8 +1953,10 @@ export function createAgentChatPlugin(options) {
                     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, devActive);
+                    const resources = await loadResourcesForPrompt(owner, lazyContext);
+                    const schemaBlock = lazyContext
+                        ? ""
+                        : await buildSchemaBlock(owner, devActive);
                     const systemPrompt = devActive
                         ? devPrompt + resources + schemaBlock
                         : basePrompt + resources + schemaBlock;
@@ -1782,6 +1970,7 @@ export function createAgentChatPlugin(options) {
                         ? {
                             ...resourceScripts,
                             ...docsScripts,
+                            ...(lazyContext ? frameworkContextTool : {}),
                             ...chatScripts,
                             ...browserTools,
                             ...devScriptsForA2A,
@@ -1792,6 +1981,7 @@ export function createAgentChatPlugin(options) {
                             ...docsScripts,
                             ...dbScripts,
                             ...refreshScreenTool,
+                            ...(lazyContext ? frameworkContextTool : {}),
                             ...urlTools,
                             ...chatScripts,
                             ...browserTools,
@@ -1852,11 +2042,26 @@ export function createAgentChatPlugin(options) {
             // Build system prompts — dynamic functions that pre-load resources per-request.
             // Production gets PROD_FRAMEWORK_PROMPT, dev gets DEV_FRAMEWORK_PROMPT.
             // Custom systemPrompt from options overrides the framework default entirely.
-            const prodPrompt = (options?.systemPrompt ?? PROD_FRAMEWORK_PROMPT) + prodActionsPrompt;
-            const devPrompt = (options?.devSystemPrompt
-                ? options.devSystemPrompt +
-                    (options?.systemPrompt ?? PROD_FRAMEWORK_PROMPT)
-                : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
+            const prodPrompt = (options?.systemPrompt ??
+                (lazyContext
+                    ? PROD_FRAMEWORK_PROMPT_COMPACT
+                    : PROD_FRAMEWORK_PROMPT)) + prodActionsPrompt;
+            // When template actions are registered as native tools in dev (via
+            // `nativeActionsInDev` or `leanPrompt`), the dev prompt's "invoke
+            // template actions via shell" guidance is wrong — use the prod prompt
+            // + tool-format action list instead, same as production.
+            const devNative = options?.nativeActionsInDev === true || leanPrompt;
+            const devPrompt = devNative
+                ? prodPrompt
+                : (options?.devSystemPrompt
+                    ? options.devSystemPrompt +
+                        (options?.systemPrompt ??
+                            (lazyContext
+                                ? PROD_FRAMEWORK_PROMPT_COMPACT
+                                : PROD_FRAMEWORK_PROMPT))
+                    : lazyContext
+                        ? DEV_FRAMEWORK_PROMPT_COMPACT
+                        : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
             // Keep legacy names for the composition below
             const basePrompt = prodPrompt;
             const devPrefix = options?.devSystemPrompt ?? DEFAULT_DEV_PROMPT;
@@ -1882,6 +2087,7 @@ export function createAgentChatPlugin(options) {
                         ? {
                             ...resourceScripts,
                             ...docsScripts,
+                            ...(lazyContext ? frameworkContextTool : {}),
                             ...chatScripts,
                             ...devScriptsForA2A,
                         }
@@ -1891,14 +2097,29 @@ export function createAgentChatPlugin(options) {
                             ...docsScripts,
                             ...dbScripts,
                             ...refreshScreenTool,
+                            ...(lazyContext ? frameworkContextTool : {}),
                             ...urlTools,
                             ...chatScripts,
                         };
                     const mcpTools = actionsToEngineTools(mcpActions);
-                    const resources = await loadResourcesForPrompt("local@localhost");
-                    const schemaBlock = await buildSchemaBlock("local@localhost", devActiveMcp);
+                    const resources = await loadResourcesForPrompt("local@localhost", lazyContext);
+                    const schemaBlock = lazyContext
+                        ? ""
+                        : await buildSchemaBlock("local@localhost", devActiveMcp);
+                    // Build the MCP handler's own prompt — always use the shell-based
+                    // dev prompt in dev mode because mcpActions routes template actions
+                    // through shell (`devScriptsForA2A`), regardless of `nativeActionsInDev`.
+                    const mcpDevPrompt = (options?.devSystemPrompt
+                        ? options.devSystemPrompt +
+                            (options?.systemPrompt ??
+                                (lazyContext
+                                    ? PROD_FRAMEWORK_PROMPT_COMPACT
+                                    : PROD_FRAMEWORK_PROMPT))
+                        : lazyContext
+                            ? DEV_FRAMEWORK_PROMPT_COMPACT
+                            : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
                     const systemPrompt = devActiveMcp
-                        ? devPrompt + resources + schemaBlock
+                        ? mcpDevPrompt + resources + schemaBlock
                         : basePrompt + resources + schemaBlock;
                     let accumulatedText = "";
                     const controller = new AbortController();
@@ -1931,7 +2152,7 @@ export function createAgentChatPlugin(options) {
                 }
             };
             // Auto-mount template actions as HTTP endpoints under /_agent-native/actions/
-            // Include engine management scripts so the UI can call list/set/test-agent-engine.
+            // Include engine management script so the UI can call manage-agent-engine.
             const httpActions = {
                 ...discoveredActions,
                 ...templateScripts,
@@ -2041,20 +2262,42 @@ export function createAgentChatPlugin(options) {
                 // Auto-checkpoint in dev mode after file-modifying agent turns
                 if (isDevMode()) {
                     try {
-                        const { createCheckpoint: gitCheckpoint, isGitRepo, hasUncommittedChanges, } = await import("../checkpoints/service.js");
+                        const { createCheckpoint: gitCheckpoint, isGitRepo, hasUncommittedChanges, getChangedFileNames, } = await import("../checkpoints/service.js");
                         const cwd = process.cwd();
                         if (isGitRepo(cwd) && hasUncommittedChanges(cwd)) {
-                            const toolNames = new Set();
+                            let summary = "";
+                            // Try to extract the first sentence of the assistant's text response
+                            let assistantText = "";
                             for (const { event } of run.events ?? []) {
-                                if (event.type === "tool_start" &&
-                                    typeof event.tool === "string") {
-                                    toolNames.add(event.tool);
+                                if (event.type === "text" && typeof event.text === "string") {
+                                    assistantText += event.text;
+                                }
+                            }
+                            assistantText = assistantText.trim();
+                            if (assistantText) {
+                                const firstSentence = assistantText
+                                    .split(/(?<=[.!?\n])\s/)[0]
+                                    ?.replace(/\n/g, " ")
+                                    .trim();
+                                if (firstSentence && firstSentence.length <= 120) {
+                                    summary = firstSentence;
+                                }
+                                else if (firstSentence) {
+                                    summary = firstSentence.slice(0, 117) + "...";
                                 }
                             }
-                            const summary = toolNames.size > 0
-                                ? `Used: ${[...toolNames].join(", ")}`
-                                : "Agent turn";
-                            const sha = gitCheckpoint(cwd, `[agent-native] ${summary}`);
+                            // Fall back to listing changed files
+                            if (!summary) {
+                                const files = getChangedFileNames(cwd);
+                                if (files.length > 0) {
+                                    summary = `Update ${files.join(", ")}`;
+                                }
+                            }
+                            if (!summary)
+                                summary = "Agent turn";
+                            if (summary.length > 120)
+                                summary = summary.slice(0, 117) + "...";
+                            const sha = gitCheckpoint(cwd, summary);
                             if (sha) {
                                 const { insertCheckpoint } = await import("../checkpoints/store.js");
                                 const cpId = `cp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -2092,6 +2335,7 @@ export function createAgentChatPlugin(options) {
                         // via shell, so omit them from the native tool registry.
                         ...resourceScripts,
                         ...docsScripts,
+                        ...(lazyContext ? frameworkContextTool : {}),
                         ...chatScripts,
                         ...devScriptsForA2A,
                     }
@@ -2101,6 +2345,7 @@ export function createAgentChatPlugin(options) {
                         ...docsScripts,
                         ...dbScripts,
                         ...refreshScreenTool,
+                        ...(lazyContext ? frameworkContextTool : {}),
                         ...urlTools,
                         ...chatScripts,
                     },
@@ -2108,7 +2353,7 @@ export function createAgentChatPlugin(options) {
                     createAnthropicEngine({
                         // 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.
+                        // run and then have agent-teams spawn delegations bill the platform key.
                         apiKey: _currentRunUserApiKey ??
                             options?.apiKey ??
                             process.env.ANTHROPIC_API_KEY,
@@ -2122,7 +2367,7 @@ export function createAgentChatPlugin(options) {
                 },
             });
             // Hook into the run lifecycle to set/clear the send reference.
-            // Job management tools (create-job, list-jobs, update-job)
+            // Job management tool (manage-jobs)
             let jobTools = {};
             try {
                 const { createJobTools } = await import("../jobs/tools.js");
@@ -2135,6 +2380,7 @@ export function createAgentChatPlugin(options) {
                 ...docsScripts,
                 ...dbScripts,
                 ...refreshScreenTool,
+                ...(lazyContext ? frameworkContextTool : {}),
                 ...urlTools,
                 ...chatScripts,
                 ...callAgentScript,
@@ -2169,26 +2415,39 @@ export function createAgentChatPlugin(options) {
                     return "";
                 }
             };
-            const leanPrompt = options?.leanPrompt === true;
             // Lean mode: use only the template's systemPrompt + actions list.
-            // Skip resource loading, schema block, and extraContext — those add
-            // DB round-trips and tokens that minimal/voice apps don't need.
+            // Skip resource loading and schema block — those add DB round-trips
+            // and tokens that minimal/voice apps don't need.
             const leanBasePrompt = (options?.systemPrompt ?? "") + prodActionsPrompt;
+            // Per-request preamble shared by both prod and dev handlers. Resolves
+            // owner + user API key (stashed on the closure so downstream tools can
+            // reach them) and the template-authored `extraContext`. `extraContext`
+            // runs in every prompt variant (lean, lazy, full) — if a template
+            // defined it, they opted in; framework-provided content is what the
+            // token-saving modes strip.
+            const prepareRun = async (event) => {
+                _currentRequestOrigin = getOrigin(event);
+                const owner = await getOwnerFromEvent(event);
+                _currentRunOwner = owner;
+                const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
+                _currentRunUserApiKey = await getOwnerActiveApiKey(owner);
+                const extra = await resolveExtraContext(event, owner);
+                return { owner, extra };
+            };
             const prodHandler = createProductionAgentHandler({
                 actions: prodActions,
                 systemPrompt: async (event) => {
-                    _currentRequestOrigin = getOrigin(event);
-                    const owner = await getOwnerFromEvent(event);
-                    _currentRunOwner = owner;
-                    const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                    _currentRunUserApiKey = await getOwnerActiveApiKey(owner);
+                    const { owner, extra } = await prepareRun(event);
                     if (leanPrompt) {
-                        _currentRunSystemPrompt = leanBasePrompt;
+                        _currentRunSystemPrompt = leanBasePrompt + extra;
                         return _currentRunSystemPrompt;
                     }
-                    const resources = await loadResourcesForPrompt(owner);
-                    const schemaBlock = await buildSchemaBlock(owner, false);
-                    const extra = await resolveExtraContext(event, owner);
+                    const resources = await loadResourcesForPrompt(owner, lazyContext);
+                    // In lazy context mode, skip embedding the full schema — the agent
+                    // calls `db-schema` on demand. This saves ~1-2K tokens per request.
+                    const schemaBlock = lazyContext
+                        ? ""
+                        : await buildSchemaBlock(owner, false);
                     _currentRunSystemPrompt =
                         basePrompt + resources + schemaBlock + extra;
                     return _currentRunSystemPrompt;
@@ -2224,14 +2483,16 @@ export function createAgentChatPlugin(options) {
                 // how Claude Code works locally and dramatically reduces the rate of
                 // degenerate empty-object tool calls. The CLI syntax for each action is
                 // listed in the dev system prompt's "Available Actions" section.
-                // In lean mode, expose the template's actions directly as native tools
-                // instead of routing through shell — the lean system prompt has no
-                // shell-usage guidance, so shell-based action invocation would break.
-                const devActions = leanPrompt
+                // In lean mode — or when `nativeActionsInDev` is set — expose the
+                // template's actions as native tools instead of routing through shell.
+                // Templates with structured-arg actions (objects/arrays) need this to
+                // avoid round-tripping JSON through the CLI parser.
+                const devActions = devNative
                     ? prodActions
                     : {
                         ...resourceScripts,
                         ...docsScripts,
+                        ...(lazyContext ? frameworkContextTool : {}),
                         ...chatScripts,
                         ...callAgentScript,
                         ...teamTools,
@@ -2245,8 +2506,8 @@ export function createAgentChatPlugin(options) {
                         ...(await createDevScriptRegistry()),
                     };
                 // Keep dev action dict in sync with runtime MCP additions. When
-                // leanPrompt is true, devActions === prodActions so the prod listener
-                // already covers it.
+                // native-actions mode is on (lean or `nativeActionsInDev`), devActions
+                // === prodActions so the prod listener already covers it.
                 if (devActions !== prodActions) {
                     mcpManager.onChange(() => {
                         syncMcpActionEntries(mcpManager, devActions);
@@ -2255,18 +2516,15 @@ export function createAgentChatPlugin(options) {
                 devHandler = createProductionAgentHandler({
                     actions: devActions,
                     systemPrompt: async (event) => {
-                        _currentRequestOrigin = getOrigin(event);
-                        const owner = await getOwnerFromEvent(event);
-                        _currentRunOwner = owner;
-                        const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                        _currentRunUserApiKey = await getOwnerActiveApiKey(owner);
+                        const { owner, extra } = await prepareRun(event);
                         if (leanPrompt) {
-                            _currentRunSystemPrompt = leanBasePrompt;
+                            _currentRunSystemPrompt = leanBasePrompt + extra;
                             return _currentRunSystemPrompt;
                         }
-                        const resources = await loadResourcesForPrompt(owner);
-                        const schemaBlock = await buildSchemaBlock(owner, true);
-                        const extra = await resolveExtraContext(event, owner);
+                        const resources = await loadResourcesForPrompt(owner, lazyContext);
+                        const schemaBlock = lazyContext
+                            ? ""
+                            : await buildSchemaBlock(owner, true);
                         _currentRunSystemPrompt =
                             devPrompt + resources + schemaBlock + extra;
                         return _currentRunSystemPrompt;
@@ -3130,6 +3388,7 @@ export function createAgentChatPlugin(options) {
                         ...templateScripts,
                         ...resourceScripts,
                         ...docsScripts,
+                        ...(lazyContext ? frameworkContextTool : {}),
                         ...chatScripts,
                         ...jobTools,
                         ...automationTools,
@@ -3138,8 +3397,10 @@ export function createAgentChatPlugin(options) {
                         ...fetchTool,
                     }),
                     getSystemPrompt: async (owner) => {
-                        const resources = await loadResourcesForPrompt(owner);
-                        const schemaBlock = await buildSchemaBlock(owner, false);
+                        const resources = await loadResourcesForPrompt(owner, lazyContext);
+                        const schemaBlock = lazyContext
+                            ? ""
+                            : await buildSchemaBlock(owner, false);
                         return basePrompt + resources + schemaBlock;
                     },
                     apiKey: options?.apiKey ?? process.env.ANTHROPIC_API_KEY,
@@ -3167,6 +3428,7 @@ export function createAgentChatPlugin(options) {
                         ...templateScripts,
                         ...resourceScripts,
                         ...docsScripts,
+                        ...(lazyContext ? frameworkContextTool : {}),
                         ...chatScripts,
                         ...jobTools,
                         ...automationTools,
@@ -3175,8 +3437,10 @@ export function createAgentChatPlugin(options) {
                         ...fetchTool,
                     }),
                     getSystemPrompt: async (owner) => {
-                        const resources = await loadResourcesForPrompt(owner);
-                        const schemaBlock = await buildSchemaBlock(owner, false);
+                        const resources = await loadResourcesForPrompt(owner, lazyContext);
+                        const schemaBlock = lazyContext
+                            ? ""
+                            : await buildSchemaBlock(owner, false);
                         return basePrompt + resources + schemaBlock;
                     },
                     apiKey: options?.apiKey ?? process.env.ANTHROPIC_API_KEY,