@agent-native/core 0.7.19 → 0.7.20

package/dist/agent/production-agent.js

@@ -8,8 +8,10 @@ import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
 import { readAppState } from "../application-state/script-helpers.js";
 import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, } from "./run-manager.js";
 import { readBody } from "../server/h3-helpers.js";
-import { getRequestUserEmail } from "../server/request-context.js";
+import { getRequestOrgId, getRequestUserEmail, } from "../server/request-context.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
+import { createToolSearchEntry, TOOL_SEARCH_ACTION_NAME, } from "./tool-search.js";
+import { getDefaultMaxIterations, normalizeMaxIterations, readAgentLoopSettings, } from "./loop-settings.js";
 // Register built-in engines on first import
 registerBuiltinEngines();
 export { PROVIDER_TO_ENV };
@@ -129,7 +131,159 @@ export async function getOwnerActiveApiKey(ownerEmail) {
 export async function getOwnerAnthropicApiKey(ownerEmail) {
     return getOwnerApiKey("anthropic", ownerEmail);
 }
-const MAX_ITERATIONS = 100;
+export const PLAN_MODE_SYSTEM_PROMPT = `## Plan Mode Active
+
+You are in Plan mode. This turn is for research, clarification, and a proposed approach only.
+
+Hard rules:
+- Use only read-only tools. Do not edit files, write resources, run shell commands, mutate SQL rows, navigate the UI, send notifications, create jobs, create tools, call external agents, or change external systems.
+- If a needed detail is unclear, ask a concise clarifying question before proposing a plan.
+- When ready, present a concrete plan with the files/tools you expect to touch, the intended changes, validation steps, and notable risks.
+- Do not treat approval as implicit while Plan mode is still active. Tell the user to switch to Act mode with the mode selector, Shift+Tab, or /act before implementation.`;
+const PLAN_MODE_BLOCKED_READONLY_TOOLS = new Set([
+    "refresh-screen",
+    "set-search-params",
+    "set-url-path",
+]);
+const PLAN_MODE_ALLOWED_ACTIONS = {
+    resources: ["list", "read"],
+    "chat-history": ["search"],
+    "agent-teams": ["status", "read-result", "list"],
+    "manage-jobs": ["list"],
+    "manage-automations": ["list-events", "list"],
+    "manage-notifications": ["list"],
+    "manage-progress": ["list"],
+    "manage-agent-engine": ["list"],
+};
+const PLAN_MODE_WEB_REQUEST_METHODS = new Set(["GET", "HEAD"]);
+function getToolAction(name, args) {
+    const raw = args && typeof args === "object" && "action" in args
+        ? args.action
+        : undefined;
+    if (raw == null && name === "chat-history")
+        return "search";
+    return String(raw ?? "").toLowerCase();
+}
+function getWebRequestMethod(args) {
+    const raw = args && typeof args === "object" && "method" in args
+        ? args.method
+        : undefined;
+    return String(raw ?? "GET").toUpperCase();
+}
+function restrictActionEnum(parameters, allowedActions) {
+    if (!parameters)
+        return parameters;
+    const actionParam = parameters.properties.action;
+    if (!actionParam)
+        return parameters;
+    return {
+        ...parameters,
+        properties: {
+            ...parameters.properties,
+            action: {
+                ...actionParam,
+                enum: [...allowedActions],
+            },
+        },
+    };
+}
+function restrictWebRequestMethods(parameters) {
+    if (!parameters)
+        return parameters;
+    const methodParam = parameters.properties.method;
+    if (!methodParam)
+        return parameters;
+    return {
+        ...parameters,
+        properties: {
+            ...parameters.properties,
+            method: {
+                ...methodParam,
+                enum: [...PLAN_MODE_WEB_REQUEST_METHODS],
+            },
+        },
+    };
+}
+function planModeBlockedMessage(toolName, reason) {
+    return (`Plan mode blocked \`${toolName}\`` +
+        (reason ? ` (${reason})` : "") +
+        ". Switch to Act mode after the user approves the plan, then retry the action.");
+}
+export function isPlanModeToolCallAllowed(name, input, entry) {
+    if (PLAN_MODE_BLOCKED_READONLY_TOOLS.has(name))
+        return false;
+    if (name === "web-request") {
+        return PLAN_MODE_WEB_REQUEST_METHODS.has(getWebRequestMethod(input));
+    }
+    const allowedActions = PLAN_MODE_ALLOWED_ACTIONS[name];
+    if (allowedActions) {
+        return allowedActions.includes(getToolAction(name, input));
+    }
+    return entry.readOnly === true;
+}
+function createPlanModeGuardedAction(name, entry, allowedActions) {
+    return {
+        ...entry,
+        readOnly: true,
+        tool: {
+            ...entry.tool,
+            description: `${entry.tool.description}\n\nPlan mode: only these read-only actions are available: ` +
+                allowedActions.map((action) => `"${action}"`).join(", ") +
+                ".",
+            parameters: restrictActionEnum(entry.tool.parameters, allowedActions),
+        },
+        run: async (args, context) => {
+            const action = getToolAction(name, args);
+            if (!allowedActions.includes(action)) {
+                return planModeBlockedMessage(name, `action="${action || "(missing)"}"`);
+            }
+            return entry.run(args, context);
+        },
+    };
+}
+function createPlanModeWebRequestAction(entry) {
+    return {
+        ...entry,
+        readOnly: true,
+        tool: {
+            ...entry.tool,
+            description: `${entry.tool.description}\n\nPlan mode: only GET and HEAD requests are allowed.`,
+            parameters: restrictWebRequestMethods(entry.tool.parameters),
+        },
+        run: async (args, context) => {
+            const method = getWebRequestMethod(args);
+            if (!PLAN_MODE_WEB_REQUEST_METHODS.has(method)) {
+                return planModeBlockedMessage("web-request", `method="${method}"`);
+            }
+            return entry.run(args, context);
+        },
+    };
+}
+export function createPlanModeActionRegistry(actions) {
+    const filtered = {};
+    for (const [name, entry] of Object.entries(actions)) {
+        if (name === TOOL_SEARCH_ACTION_NAME)
+            continue;
+        if (PLAN_MODE_BLOCKED_READONLY_TOOLS.has(name))
+            continue;
+        const allowedActions = PLAN_MODE_ALLOWED_ACTIONS[name];
+        if (allowedActions) {
+            filtered[name] = createPlanModeGuardedAction(name, entry, allowedActions);
+            continue;
+        }
+        if (name === "web-request") {
+            filtered[name] = createPlanModeWebRequestAction(entry);
+            continue;
+        }
+        if (entry.readOnly === true) {
+            filtered[name] = entry;
+        }
+    }
+    if (actions[TOOL_SEARCH_ACTION_NAME]) {
+        filtered[TOOL_SEARCH_ACTION_NAME] = createToolSearchEntry(() => filtered);
+    }
+    return filtered;
+}
 const MAX_RETRIES = 3;
 const RETRY_BASE_DELAY_MS = 2000;
 function generateRunId() {
@@ -157,11 +311,22 @@ function isRetryableError(err) {
     if (!(err instanceof Error))
         return false;
     const msg = err.message.toLowerCase();
-    return (msg.includes("overloaded") ||
+    const code = err instanceof EngineError ? (err.errorCode ?? "").toLowerCase() : "";
+    return (code === "http_502" ||
+        code === "http_503" ||
+        code === "http_504" ||
+        code === "timeout" ||
+        msg.includes("overloaded") ||
         msg.includes("rate_limit") ||
         msg.includes("529") ||
+        msg.includes("502") ||
         msg.includes("503") ||
-        msg.includes("too many requests"));
+        msg.includes("504") ||
+        msg.includes("too many requests") ||
+        msg.includes("timeout") ||
+        msg.includes("gateway timeout") ||
+        msg.includes("inactivity timeout") ||
+        msg.includes("too much time has passed without sending any data"));
 }
 /** Wait with exponential backoff, respecting abort signal */
 function retryDelay(attempt, signal) {
@@ -268,14 +433,34 @@ function enrichMessage(message, references) {
  * Convert ActionEntry registry to EngineTool array.
  */
 export function actionsToEngineTools(actions) {
-    return Object.entries(actions).map(([name, entry]) => ({
-        name,
-        description: entry.tool.description,
-        inputSchema: (entry.tool.parameters ?? {
-            type: "object",
-            properties: {},
-        }),
-    }));
+    const tools = [];
+    for (const [name, entry] of Object.entries(actions)) {
+        const inputSchema = normalizeToolInputSchema(entry.tool.parameters);
+        if (!inputSchema) {
+            console.warn(`[agent] Skipping tool "${name}" because its input schema is not an object.`);
+            continue;
+        }
+        tools.push({
+            name,
+            description: entry.tool.description,
+            inputSchema,
+        });
+    }
+    return tools;
+}
+function normalizeToolInputSchema(schema) {
+    if (!schema)
+        return { type: "object", properties: {} };
+    if (schema.type !== "object")
+        return null;
+    return {
+        ...schema,
+        type: "object",
+        properties: schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {},
+        required: Array.isArray(schema.required) ? schema.required : [],
+    };
 }
 /**
  * The core agent loop — calls the engine iteratively until no more tool calls.
@@ -291,12 +476,13 @@ export async function runAgentLoop(opts) {
         cacheWriteTokens: 0,
         model,
     };
+    const maxIterations = normalizeMaxIterations(opts.maxIterations, getDefaultMaxIterations());
     let iterations = 0;
     while (true) {
         if (signal.aborted)
             break;
-        if (++iterations > MAX_ITERATIONS) {
-            send({ type: "loop_limit" });
+        if (++iterations > maxIterations) {
+            send({ type: "loop_limit", maxIterations });
             break;
         }
         let assistantContent;
@@ -372,9 +558,7 @@ export async function runAgentLoop(opts) {
         const toolCallParts = assistantContent.filter((p) => p.type === "tool-call");
         if (toolCallParts.length === 0)
             break;
-        // Run all tool calls in parallel — engines often return multiple tool-call
-        // blocks in one turn. Running them concurrently saves wall-clock time.
-        const toolResultParts = await Promise.all(toolCallParts.map(async (toolCall) => {
+        const runToolCall = async (toolCall) => {
             const actionEntry = actions[toolCall.name];
             if (!actionEntry) {
                 const result = `Error: Unknown tool "${toolCall.name}"`;
@@ -397,6 +581,18 @@ export async function runAgentLoop(opts) {
                 tool: toolCall.name,
                 input: toolCall.input,
             });
+            if (opts.executionMode === "plan" &&
+                !isPlanModeToolCallAllowed(toolCall.name, toolCall.input, actionEntry)) {
+                const result = planModeBlockedMessage(toolCall.name);
+                send({ type: "tool_done", tool: toolCall.name, result });
+                return {
+                    type: "tool-result",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    content: result,
+                    isError: true,
+                };
+            }
             const MAX_TOOL_RESULT_CHARS = 50_000;
             const TOOL_TIMEOUT_MS = 60_000;
             let result;
@@ -429,10 +625,14 @@ export async function runAgentLoop(opts) {
             if (!isError && actionEntry.readOnly !== true) {
                 try {
                     const { recordChange } = await import("../server/poll.js");
+                    const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
+                    const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
                     recordChange({
                         source: "action",
                         type: "change",
                         key: toolCall.name,
+                        ...(owner ? { owner } : {}),
+                        ...(orgId ? { orgId } : {}),
                     });
                 }
                 catch {
@@ -447,7 +647,24 @@ export async function runAgentLoop(opts) {
                 content: result,
                 ...(isError ? { isError } : {}),
             };
-        }));
+        };
+        const hasMutatingToolCall = toolCallParts.some((toolCall) => {
+            const entry = actions[toolCall.name];
+            return entry && entry.readOnly !== true;
+        });
+        // Engines can emit several tool-call blocks in one turn. Keep read-only
+        // calls parallel for latency, but serialize any batch containing a mutating
+        // call so DB writes and UI refresh events preserve model order and do not
+        // interleave or partially race.
+        const toolResultParts = [];
+        if (hasMutatingToolCall) {
+            for (const toolCall of toolCallParts) {
+                toolResultParts.push(await runToolCall(toolCall));
+            }
+        }
+        else {
+            toolResultParts.push(...(await Promise.all(toolCallParts.map(runToolCall))));
+        }
         messages.push({ role: "user", content: toolResultParts });
     }
     send({ type: "done" });
@@ -463,9 +680,9 @@ export function createProductionAgentHandler(options) {
     // the settings UI) show up to the LLM without a process restart. MCP tools
     // are also scope-filtered per request — a user-scope server added by Alice
     // must not appear in Bob's tool list in a shared-process deployment.
-    const getEngineTools = () => {
+    const getEngineTools = (actions = resolvedActions) => {
         const filtered = {};
-        for (const [name, entry] of Object.entries(resolvedActions)) {
+        for (const [name, entry] of Object.entries(actions)) {
             if (name.startsWith("mcp__") && !isMcpToolAllowedForRequest(name)) {
                 continue;
             }
@@ -487,6 +704,7 @@ export function createProductionAgentHandler(options) {
             return { error: "Invalid request body" };
         }
         const { message, history = [], references = [], threadId, attachments, model: requestModel, engine: requestEngine, } = body;
+        const requestMode = body.mode === "plan" ? "plan" : "act";
         if (!message) {
             setResponseStatus(event, 400);
             return { error: "message is required" };
@@ -578,6 +796,10 @@ export function createProductionAgentHandler(options) {
         // the DB or invokes an action; running them sequentially was the
         // single biggest contributor to pre-LLM latency.
         const enrichedMessage = enrichMessage(message, references);
+        const loopSettingsPromise = readAgentLoopSettings({
+            userEmail: ownerEmail ?? getRequestUserEmail() ?? null,
+            orgId: getRequestOrgId() ?? null,
+        }).catch(() => readAgentLoopSettings({}));
         let systemPromptError = null;
         const systemPromptPromise = (async () => {
             try {
@@ -732,12 +954,13 @@ export function createProductionAgentHandler(options) {
             }
             return filesContext;
         })();
-        const [systemPrompt, screenBlock, urlBlock, selectionBlock, filesContext] = await Promise.all([
+        const [systemPrompt, screenBlock, urlBlock, selectionBlock, filesContext, loopSettings,] = await Promise.all([
             systemPromptPromise,
             screenContextPromise,
             urlContextPromise,
             selectionContextPromise,
             filesContextPromise,
+            loopSettingsPromise,
         ]);
         if (systemPromptError) {
             setResponseHeader(event, "Content-Type", "text/event-stream");
@@ -752,11 +975,21 @@ export function createProductionAgentHandler(options) {
             });
         }
         const screenContext = screenBlock + urlBlock + selectionBlock;
+        const requestActions = requestMode === "plan"
+            ? createPlanModeActionRegistry(resolvedActions)
+            : resolvedActions;
+        const requestTools = getEngineTools(requestActions);
+        const requestSystemPrompt = requestMode === "plan"
+            ? `${systemPrompt}\n\n${PLAN_MODE_SYSTEM_PROMPT}`
+            : systemPrompt;
         // Pre-compute agent references for A2A resolution inside the run
         const agentRefs = references.filter((r) => r.type === "agent");
         const customAgentRefs = references.filter((r) => r.type === "custom-agent");
+        const planModeAgentNote = requestMode === "plan" && agentRefs.length > 0
+            ? "\n\n<plan-mode-note>Connected external agent mentions were not called because Plan mode is read-only. Mention that they can be called after the user switches to Act mode if the plan needs them.</plan-mode-note>"
+            : "";
         const userContent = buildUserContentWithAttachments({
-            text: enrichedMessage + screenContext + filesContext,
+            text: enrichedMessage + screenContext + filesContext + planModeAgentNote,
             attachments,
         });
         const messages = [
@@ -804,7 +1037,7 @@ export function createProductionAgentHandler(options) {
                         if (!profile) {
                             throw new Error("Profile not found");
                         }
-                        const profilePrompt = `${systemPrompt}\n\n<custom-agent-profile name="${profile.name}" path="${profile.path}">\n` +
+                        const profilePrompt = `${requestSystemPrompt}\n\n<custom-agent-profile name="${profile.name}" path="${profile.path}">\n` +
                             (profile.description ? `${profile.description}\n\n` : "") +
                             `${profile.instructions}\n</custom-agent-profile>`;
                         let responseText = "";
@@ -812,7 +1045,7 @@ export function createProductionAgentHandler(options) {
                             engine,
                             model: profile.model ?? model,
                             systemPrompt: profilePrompt,
-                            tools: getEngineTools(),
+                            tools: requestTools,
                             messages: [
                                 {
                                     role: "user",
@@ -821,7 +1054,7 @@ export function createProductionAgentHandler(options) {
                                     ],
                                 },
                             ],
-                            actions: resolvedActions,
+                            actions: requestActions,
                             send: (event) => {
                                 if (event.type === "text") {
                                     responseText += event.text;
@@ -834,6 +1067,8 @@ export function createProductionAgentHandler(options) {
                             },
                             signal,
                             providerOptions: options.providerOptions,
+                            executionMode: requestMode,
+                            maxIterations: loopSettings.maxIterations,
                         });
                         // Attribute custom-agent sub-calls under their own label
                         // so the Usage panel separates them from the main chat.
@@ -889,7 +1124,7 @@ export function createProductionAgentHandler(options) {
                 }
             }
             // Resolve connected agent @-mentions via A2A calls.
-            if (agentRefs.length > 0) {
+            if (agentRefs.length > 0 && requestMode !== "plan") {
                 const { A2AClient, callAgent } = await import("../a2a/client.js");
                 const results = await Promise.allSettled(agentRefs.map(async (ref) => {
                     send({
@@ -1003,13 +1238,17 @@ export function createProductionAgentHandler(options) {
             const agentLoopOpts = {
                 engine,
                 model: effectiveModel,
-                systemPrompt,
-                tools: getEngineTools(),
+                systemPrompt: requestSystemPrompt,
+                tools: requestTools,
                 messages,
-                actions: resolvedActions,
+                actions: requestActions,
                 send,
                 signal,
+                ownerEmail,
+                orgId: getRequestOrgId() ?? null,
                 providerOptions: options.providerOptions,
+                executionMode: requestMode,
+                maxIterations: loopSettings.maxIterations,
             };
             let loopUsage;
             let instrumented = false;