@mindstudio-ai/remy 0.1.36 → 0.1.37

package/dist/headless.js

@@ -593,6 +593,31 @@ async function* streamChatWithRetry(params, options) {
     return;
   }
 }
+var FALLBACK_ACK = "[Message sent to agent. Agent is working in the background and will report back with its results when finished.]";
+async function generateBackgroundAck(params) {
+  const url = `${params.apiConfig.baseUrl}/_internal/v2/agent/remy/generate-ack`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${params.apiConfig.apiKey}`
+      },
+      body: JSON.stringify({
+        agentName: params.agentName,
+        task: params.task
+      }),
+      signal: AbortSignal.timeout(2e4)
+    });
+    if (!res.ok) {
+      return FALLBACK_ACK;
+    }
+    const data = await res.json();
+    return data.message || FALLBACK_ACK;
+  } catch (err) {
+    return FALLBACK_ACK;
+  }
+}
 
 // src/tools/spec/readSpec.ts
 import fs5 from "fs/promises";
@@ -1275,8 +1300,12 @@ function runCli(cmd, options) {
     const maxBuffer = options?.maxBuffer ?? 1024 * 1024;
     const cmdWithLogs = options?.jsonLogs && !cmd.includes("--json-logs") ? cmd.replace(/^(mindstudio\s+\S+)/, "$1 --json-logs") : cmd;
     const child = spawn("sh", ["-c", cmdWithLogs], {
-      stdio: ["ignore", "pipe", "pipe"]
+      stdio: [options?.stdin ? "pipe" : "ignore", "pipe", "pipe"]
     });
+    if (options?.stdin) {
+      child.stdin.write(options.stdin);
+      child.stdin.end();
+    }
     const logs = [];
     let stdout = "";
     let stderr = "";
@@ -1430,20 +1459,27 @@ var searchGoogleTool = {
   }
 };
 
-// src/tools/common/setProjectName.ts
-var setProjectNameTool = {
+// src/tools/common/setProjectMetadata.ts
+var setProjectMetadataTool = {
   definition: {
-    name: "setProjectName",
-    description: `Set the project display name. Call this after intake once you have enough context to give the project a clear, descriptive name. Keep it short (2-4 words). Use the app's actual name if the user mentioned one, otherwise pick something descriptive ("Vendor Procurement App", "Recipe Manager").`,
+    name: "setProjectMetadata",
+    description: "Set project metadata. Can update any combination of: display name, app icon, and Open Graph share image. Provide only the fields you want to change.",
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
-          description: "The project name."
+          description: "Project display name. Keep it short (2-4 words). Use the app's actual name if the user mentioned one, otherwise pick something descriptive."
+        },
+        iconUrl: {
+          type: "string",
+          description: "URL for the app icon (square."
+        },
+        openGraphShareImageUrl: {
+          type: "string",
+          description: "URL for the Open Graph share image (1200x630)."
         }
-      },
-      required: ["name"]
+      }
     }
   },
   async execute() {
@@ -2066,7 +2102,7 @@ var restartProcessTool = {
 var runScenarioTool = {
   definition: {
     name: "runScenario",
-    description: "Run a scenario to seed the dev database with test data. Truncates all tables first, then executes the seed function and impersonates the scenario roles. Blocks until complete. Scenario IDs are defined in mindstudio.json. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for details.",
+    description: "Run a scenario to seed the dev database with test data. Truncates all tables first, then executes the seed function and impersonates the scenario roles. Blocks until complete. Scenario IDs are defined in mindstudio.json. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for details. Return synchronously - no need to sleep before checking results.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2087,7 +2123,7 @@ var runScenarioTool = {
 var runMethodTool = {
   definition: {
     name: "runMethod",
-    description: "Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details.",
+    description: "Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Return synchronously - no need to sleep before checking results.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2249,6 +2285,12 @@ function startStatusWatcher(config) {
 // src/subagents/common/cleanMessages.ts
 function cleanMessagesForApi(messages) {
   return messages.map((msg) => {
+    if (msg.role === "user" && typeof msg.content === "string" && msg.content.startsWith("@@automated::")) {
+      return {
+        ...msg,
+        content: msg.content.replace(/^@@automated::[^@]*@@\n?/, "")
+      };
+    }
     if (!Array.isArray(msg.content)) {
       return msg;
     }
@@ -2286,238 +2328,264 @@ async function runSubAgent(config) {
     apiConfig,
     model,
     subAgentId,
-    signal,
+    signal: parentSignal,
     parentToolId,
     onEvent,
     resolveExternalTool,
-    toolRegistry
+    toolRegistry,
+    background,
+    onBackgroundComplete
   } = config;
+  const bgAbort = background ? new AbortController() : null;
+  const signal = background ? bgAbort.signal : parentSignal;
   const emit2 = (e) => {
     onEvent({ ...e, parentToolId });
   };
-  const messages = [{ role: "user", content: task }];
-  function getPartialText(blocks) {
-    return blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
-  }
-  function abortResult(blocks) {
-    if (signal?.reason === "graceful") {
-      const partial = getPartialText(blocks);
-      return {
-        text: partial ? `[INTERRUPTED]
-
-${partial}` : "[INTERRUPTED] Sub-agent was interrupted before producing output.",
-        messages
-      };
-    }
-    return { text: "Error: cancelled", messages };
-  }
-  let lastToolResult = "";
-  while (true) {
-    if (signal?.aborted) {
-      return abortResult([]);
+  const run = async () => {
+    const messages = [{ role: "user", content: task }];
+    function getPartialText(blocks) {
+      return blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
+    }
+    function abortResult(blocks) {
+      if (signal?.reason === "graceful") {
+        const partial = getPartialText(blocks);
+        return {
+          text: partial ? `[INTERRUPTED - PARTIAL OUTPUT RETRIEVED] Note that partial output may include thinking text or other unfinalized decisions. It is NOT an authoritative response from this agent.
+
+${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
+          messages
+        };
+      }
+      return { text: "Error: cancelled", messages };
     }
-    const contentBlocks = [];
-    let thinkingStartedAt = 0;
-    let stopReason = "end_turn";
-    let currentToolNames = "";
-    const statusWatcher = startStatusWatcher({
-      apiConfig,
-      getContext: () => ({
-        assistantText: getPartialText(contentBlocks),
-        lastToolName: currentToolNames || void 0,
-        lastToolResult: lastToolResult || void 0
-      }),
-      onStatus: (label) => emit2({ type: "status", message: label }),
-      signal
-    });
-    const fullSystem = `${system}
+    let lastToolResult = "";
+    while (true) {
+      if (signal?.aborted) {
+        return abortResult([]);
+      }
+      const contentBlocks = [];
+      let thinkingStartedAt = 0;
+      let stopReason = "end_turn";
+      let currentToolNames = "";
+      const statusWatcher = startStatusWatcher({
+        apiConfig,
+        getContext: () => ({
+          assistantText: getPartialText(contentBlocks),
+          lastToolName: currentToolNames || void 0,
+          lastToolResult: lastToolResult || void 0
+        }),
+        onStatus: (label) => emit2({ type: "status", message: label }),
+        signal
+      });
+      const fullSystem = `${system}
 
 Current date/time: ${(/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace(/\.\d+Z$/, " UTC")}`;
-    try {
-      for await (const event of streamChatWithRetry({
-        ...apiConfig,
-        model,
-        subAgentId,
-        system: fullSystem,
-        messages: cleanMessagesForApi(messages),
-        tools: tools2,
-        signal
-      })) {
-        if (signal?.aborted) {
-          break;
-        }
-        switch (event.type) {
-          case "text": {
-            const lastBlock = contentBlocks.at(-1);
-            if (lastBlock?.type === "text") {
-              lastBlock.text += event.text;
-            } else {
-              contentBlocks.push({
-                type: "text",
-                text: event.text,
-                startedAt: event.ts
-              });
-            }
-            emit2({ type: "text", text: event.text });
+      try {
+        for await (const event of streamChatWithRetry(
+          {
+            ...apiConfig,
+            model,
+            subAgentId,
+            system: fullSystem,
+            messages: cleanMessagesForApi(messages),
+            tools: tools2,
+            signal
+          },
+          {
+            onRetry: (attempt) => emit2({
+              type: "status",
+              message: `Lost connection, retrying (attempt ${attempt + 2} of 3)...`
+            })
+          }
+        )) {
+          if (signal?.aborted) {
             break;
           }
-          case "thinking":
-            if (!thinkingStartedAt) {
-              thinkingStartedAt = event.ts;
+          switch (event.type) {
+            case "text": {
+              const lastBlock = contentBlocks.at(-1);
+              if (lastBlock?.type === "text") {
+                lastBlock.text += event.text;
+              } else {
+                contentBlocks.push({
+                  type: "text",
+                  text: event.text,
+                  startedAt: event.ts
+                });
+              }
+              emit2({ type: "text", text: event.text });
+              break;
             }
-            emit2({ type: "thinking", text: event.text });
-            break;
-          case "thinking_complete":
-            contentBlocks.push({
-              type: "thinking",
-              thinking: event.thinking,
-              signature: event.signature,
-              startedAt: thinkingStartedAt,
-              completedAt: event.ts
-            });
-            thinkingStartedAt = 0;
-            break;
-          case "tool_use":
-            contentBlocks.push({
-              type: "tool",
-              id: event.id,
-              name: event.name,
-              input: event.input,
-              startedAt: Date.now()
-            });
-            emit2({
-              type: "tool_start",
-              id: event.id,
-              name: event.name,
-              input: event.input
-            });
-            break;
-          case "done":
-            stopReason = event.stopReason;
-            break;
-          case "error":
-            return { text: `Error: ${event.error}`, messages };
+            case "thinking":
+              if (!thinkingStartedAt) {
+                thinkingStartedAt = event.ts;
+              }
+              emit2({ type: "thinking", text: event.text });
+              break;
+            case "thinking_complete":
+              contentBlocks.push({
+                type: "thinking",
+                thinking: event.thinking,
+                signature: event.signature,
+                startedAt: thinkingStartedAt,
+                completedAt: event.ts
+              });
+              thinkingStartedAt = 0;
+              break;
+            case "tool_use":
+              contentBlocks.push({
+                type: "tool",
+                id: event.id,
+                name: event.name,
+                input: event.input,
+                startedAt: Date.now()
+              });
+              emit2({
+                type: "tool_start",
+                id: event.id,
+                name: event.name,
+                input: event.input
+              });
+              break;
+            case "done":
+              stopReason = event.stopReason;
+              break;
+            case "error":
+              return { text: `Error: ${event.error}`, messages };
+          }
+        }
+      } catch (err) {
+        if (!signal?.aborted) {
+          throw err;
         }
       }
-    } catch (err) {
-      if (!signal?.aborted) {
-        throw err;
+      if (signal?.aborted) {
+        statusWatcher.stop();
+        return abortResult(contentBlocks);
       }
-    }
-    if (signal?.aborted) {
-      statusWatcher.stop();
-      return abortResult(contentBlocks);
-    }
-    messages.push({
-      role: "assistant",
-      content: contentBlocks
-    });
-    const toolCalls = contentBlocks.filter(
-      (b) => b.type === "tool"
-    );
-    if (stopReason !== "tool_use" || toolCalls.length === 0) {
-      statusWatcher.stop();
-      const text = contentBlocks.filter((b) => b.type === "text").map((b) => b.text).join("");
-      return { text, messages };
-    }
-    log.info("Sub-agent executing tools", {
-      parentToolId,
-      count: toolCalls.length,
-      tools: toolCalls.map((tc) => tc.name)
-    });
-    currentToolNames = toolCalls.map((tc) => tc.name).join(", ");
-    const results = await Promise.all(
-      toolCalls.map(async (tc) => {
-        if (signal?.aborted) {
-          return { id: tc.id, result: "Error: cancelled", isError: true };
-        }
-        let settle;
-        const resultPromise = new Promise((res) => {
-          settle = (result, isError) => res({ id: tc.id, result, isError });
-        });
-        let toolAbort = new AbortController();
-        const cascadeAbort = () => toolAbort.abort();
-        signal?.addEventListener("abort", cascadeAbort, { once: true });
-        let settled = false;
-        const safeSettle = (result, isError) => {
-          if (settled) {
-            return;
+      messages.push({
+        role: "assistant",
+        content: contentBlocks
+      });
+      const toolCalls = contentBlocks.filter(
+        (b) => b.type === "tool"
+      );
+      if (stopReason !== "tool_use" || toolCalls.length === 0) {
+        statusWatcher.stop();
+        const text = getPartialText(contentBlocks);
+        return { text, messages };
+      }
+      log.info("Sub-agent executing tools", {
+        parentToolId,
+        count: toolCalls.length,
+        tools: toolCalls.map((tc) => tc.name)
+      });
+      currentToolNames = toolCalls.map((tc) => tc.name).join(", ");
+      const results = await Promise.all(
+        toolCalls.map(async (tc) => {
+          if (signal?.aborted) {
+            return { id: tc.id, result: "Error: cancelled", isError: true };
           }
-          settled = true;
-          signal?.removeEventListener("abort", cascadeAbort);
-          settle(result, isError);
-        };
-        const run = async (input) => {
-          try {
-            let result;
-            if (externalTools.has(tc.name) && resolveExternalTool) {
-              result = await resolveExternalTool(tc.id, tc.name, input);
-            } else {
-              const onLog = (line) => emit2({
-                type: "tool_input_delta",
-                id: tc.id,
-                name: tc.name,
-                result: line
+          let settle;
+          const resultPromise = new Promise((res) => {
+            settle = (result, isError) => res({ id: tc.id, result, isError });
+          });
+          let toolAbort = new AbortController();
+          const cascadeAbort = () => toolAbort.abort();
+          signal?.addEventListener("abort", cascadeAbort, { once: true });
+          let settled = false;
+          const safeSettle = (result, isError) => {
+            if (settled) {
+              return;
+            }
+            settled = true;
+            signal?.removeEventListener("abort", cascadeAbort);
+            settle(result, isError);
+          };
+          const run2 = async (input) => {
+            try {
+              let result;
+              if (externalTools.has(tc.name) && resolveExternalTool) {
+                result = await resolveExternalTool(tc.id, tc.name, input);
+              } else {
+                const onLog = (line) => emit2({
+                  type: "tool_input_delta",
+                  id: tc.id,
+                  name: tc.name,
+                  result: line
+                });
+                result = await executeTool2(tc.name, input, tc.id, onLog);
+              }
+              safeSettle(result, result.startsWith("Error"));
+            } catch (err) {
+              safeSettle(`Error: ${err.message}`, true);
+            }
+          };
+          const entry = {
+            id: tc.id,
+            name: tc.name,
+            input: tc.input,
+            parentToolId,
+            abortController: toolAbort,
+            startedAt: Date.now(),
+            settle: safeSettle,
+            rerun: (newInput) => {
+              settled = false;
+              toolAbort = new AbortController();
+              signal?.addEventListener("abort", () => toolAbort.abort(), {
+                once: true
               });
-              result = await executeTool2(tc.name, input, tc.id, onLog);
+              entry.abortController = toolAbort;
+              entry.input = newInput;
+              run2(newInput);
             }
-            safeSettle(result, result.startsWith("Error"));
-          } catch (err) {
-            safeSettle(`Error: ${err.message}`, true);
-          }
-        };
-        const entry = {
-          id: tc.id,
-          name: tc.name,
-          input: tc.input,
-          parentToolId,
-          abortController: toolAbort,
-          startedAt: Date.now(),
-          settle: safeSettle,
-          rerun: (newInput) => {
-            settled = false;
-            toolAbort = new AbortController();
-            signal?.addEventListener("abort", () => toolAbort.abort(), {
-              once: true
-            });
-            entry.abortController = toolAbort;
-            entry.input = newInput;
-            run(newInput);
-          }
-        };
-        toolRegistry?.register(entry);
-        run(tc.input);
-        const r = await resultPromise;
-        toolRegistry?.unregister(tc.id);
-        emit2({
-          type: "tool_done",
-          id: tc.id,
-          name: tc.name,
-          result: r.result,
-          isError: r.isError
-        });
-        return r;
-      })
-    );
-    statusWatcher.stop();
-    lastToolResult = results.at(-1)?.result ?? "";
-    for (const r of results) {
-      const block = contentBlocks.find(
-        (b) => b.type === "tool" && b.id === r.id
+          };
+          toolRegistry?.register(entry);
+          run2(tc.input);
+          const r = await resultPromise;
+          toolRegistry?.unregister(tc.id);
+          emit2({
+            type: "tool_done",
+            id: tc.id,
+            name: tc.name,
+            result: r.result,
+            isError: r.isError
+          });
+          return r;
+        })
       );
-      if (block?.type === "tool") {
-        block.result = r.result;
-        block.isError = r.isError;
-        block.completedAt = Date.now();
+      statusWatcher.stop();
+      lastToolResult = results.at(-1)?.result ?? "";
+      for (const r of results) {
+        const block = contentBlocks.find(
+          (b) => b.type === "tool" && b.id === r.id
+        );
+        if (block?.type === "tool") {
+          block.result = r.result;
+          block.isError = r.isError;
+          block.completedAt = Date.now();
+        }
+        messages.push({
+          role: "user",
+          content: r.result,
+          toolCallId: r.id,
+          isToolError: r.isError
+        });
       }
-      messages.push({
-        role: "user",
-        content: r.result,
-        toolCallId: r.id,
-        isToolError: r.isError
-      });
     }
+  };
+  if (!background) {
+    return run();
   }
+  const ack = await generateBackgroundAck({
+    apiConfig,
+    agentName: subAgentId || "agent",
+    task
+  });
+  run().then((finalResult) => onBackgroundComplete?.(finalResult)).catch(
+    (err) => onBackgroundComplete?.({ text: `Error: ${err.message}`, messages: [] })
+  );
+  return { text: ack, messages: [], backgrounded: true };
 }
 
 // src/subagents/browserAutomation/tools.ts
@@ -2870,9 +2938,7 @@ async function execute3(input, onLog) {
     `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(imageUrl)} --output-key analysis --no-meta`,
     { timeout: 2e5, onLog }
   );
-  return isImageUrl ? analysis : `Screenshot: ${imageUrl}
-
-${analysis}`;
+  return JSON.stringify({ url: imageUrl, analysis });
 }
 
 // src/subagents/designExpert/tools/analyzeImage.ts
@@ -2884,7 +2950,7 @@ __export(analyzeImage_exports, {
 var DEFAULT_PROMPT = "Describe everything visible in this image \u2014 every element, its position, its size relative to the frame, its colors, its content. Be comprhensive, thorough and spatial. After the inventory, note anything that looks visually broken (overlapping elements, clipped text, misaligned components). Respond only with your analysis as Markdown and absolutely no other text. Do not use emojis - use unicode if you need symbols.";
 var definition4 = {
   name: "analyzeImage",
-  description: "Analyze an image by URL. Returns a detailed description of everything visible. Provide a custom prompt to ask a specific question instead of the default full description.",
+  description: "Analyze an image by URL using a vision model. Returns an objective description of what is visible \u2014 shapes, colors, layout, text, artifacts. Use for factual inventory of image contents, not for subjective design judgment - the vision model providing the analysis has no sense of design. You are the design expert - use the analysis tool for factual inventory, then apply your own expertise for quality and suitability assessments.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2982,10 +3048,12 @@ async function seedreamGenerate(opts) {
         }
       }
     }));
-    const batchResult = await runCli(
-      `mindstudio batch ${JSON.stringify(JSON.stringify(steps))} --no-meta`,
-      { jsonLogs: true, timeout: 2e5, onLog }
-    );
+    const batchResult = await runCli(`mindstudio batch --no-meta`, {
+      jsonLogs: true,
+      timeout: 2e5,
+      onLog,
+      stdin: JSON.stringify(steps)
+    });
     try {
       const parsed = JSON.parse(batchResult);
       imageUrls = parsed.map(
@@ -3358,6 +3426,10 @@ var designExpertTool = {
         task: {
           type: "string",
           description: "What you need, in natural language. Include context about the project when relevant."
+        },
+        background: {
+          type: "boolean",
+          description: "Run in background \u2014 returns immediately and doesn't block while continuing to do work in the background. Reports results when finished working."
         }
       },
       required: ["task"]
@@ -3380,7 +3452,16 @@ var designExpertTool = {
       parentToolId: context.toolCallId,
       onEvent: context.onEvent,
       resolveExternalTool: context.resolveExternalTool,
-      toolRegistry: context.toolRegistry
+      toolRegistry: context.toolRegistry,
+      background: input.background,
+      onBackgroundComplete: input.background ? (bgResult) => {
+        context.onBackgroundComplete?.(
+          context.toolCallId,
+          "visualDesignExpert",
+          bgResult.text,
+          bgResult.messages
+        );
+      } : void 0
     });
     context.subAgentMessages?.set(context.toolCallId, result.messages);
     return result.text;
@@ -3641,6 +3722,10 @@ var productVisionTool = {
         task: {
           type: "string",
           description: "Brief description of what happened or what is needed. Do not specify how many items to create, what topics to cover, or how to think. The agent reads the spec files and decides for itself."
+        },
+        background: {
+          type: "boolean",
+          description: "Run in background \u2014 returns immediately and doesn't block while continuing to do work in the background. Reports results when finished working."
         }
       },
       required: ["task"]
@@ -3663,7 +3748,16 @@ var productVisionTool = {
       parentToolId: context.toolCallId,
       onEvent: context.onEvent,
       resolveExternalTool: context.resolveExternalTool,
-      toolRegistry: context.toolRegistry
+      toolRegistry: context.toolRegistry,
+      background: input.background,
+      onBackgroundComplete: input.background ? (bgResult) => {
+        context.onBackgroundComplete?.(
+          context.toolCallId,
+          "productVision",
+          bgResult.text,
+          bgResult.messages
+        );
+      } : void 0
     });
     context.subAgentMessages?.set(context.toolCallId, result.messages);
     return result.text;
@@ -3840,7 +3934,7 @@ function getCommonTools() {
     askMindStudioSdkTool,
     fetchUrlTool,
     searchGoogleTool,
-    setProjectNameTool,
+    setProjectMetadataTool,
     designExpertTool,
     productVisionTool,
     codeSanityCheckTool
@@ -4167,7 +4261,7 @@ var EXTERNAL_TOOLS = /* @__PURE__ */ new Set([
   "runScenario",
   "runMethod",
   "browserCommand",
-  "setProjectName"
+  "setProjectMetadata"
 ]);
 function createAgentState() {
   return { messages: [] };
@@ -4185,7 +4279,8 @@ async function runTurn(params) {
     onEvent,
     resolveExternalTool,
     hidden,
-    toolRegistry
+    toolRegistry,
+    onBackgroundComplete
   } = params;
   const tools2 = getToolDefinitions(onboardingState);
   log.info("Turn started", {
@@ -4198,8 +4293,7 @@ async function runTurn(params) {
     }
   });
   onEvent({ type: "turn_started" });
-  const cleanMessage = userMessage.replace(/^@@automated::[^@]*@@/, "");
-  const userMsg = { role: "user", content: cleanMessage };
+  const userMsg = { role: "user", content: userMessage };
   if (hidden) {
     userMsg.hidden = true;
   }
@@ -4213,7 +4307,7 @@ async function runTurn(params) {
   state.messages.push(userMsg);
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
     "setProjectOnboardingState",
-    "setProjectName",
+    "setProjectMetadata",
     "clearSyncStatus",
     "editsFinished"
   ]);
@@ -4400,7 +4494,8 @@ async function runTurn(params) {
               id: event.id,
               name: event.name,
               input: event.input,
-              startedAt: event.ts
+              startedAt: event.ts,
+              ...event.input.background && { background: true }
             });
             const acc = toolInputAccumulators.get(event.id);
             const tool = getToolByName(event.name);
@@ -4522,6 +4617,7 @@ async function runTurn(params) {
                 toolCallId: tc.id,
                 subAgentMessages,
                 toolRegistry,
+                onBackgroundComplete,
                 onLog: (line) => wrappedOnEvent({
                   type: "tool_input_delta",
                   id: tc.id,
@@ -4745,6 +4841,54 @@ async function startHeadless(opts = {}) {
   const pendingTools = /* @__PURE__ */ new Map();
   const earlyResults = /* @__PURE__ */ new Map();
   const toolRegistry = new ToolRegistry();
+  const backgroundQueue = [];
+  function flushBackgroundQueue() {
+    if (backgroundQueue.length === 0) {
+      return;
+    }
+    const results = backgroundQueue.splice(0);
+    const xmlParts = results.map(
+      (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
+${r.result}
+</tool_result>`
+    ).join("\n\n");
+    const message = `@@automated::background_results@@
+<background_results>
+${xmlParts}
+</background_results>`;
+    handleMessage({ action: "message", text: message }, void 0);
+  }
+  function onBackgroundComplete(toolCallId, name, result, subAgentMessages) {
+    for (const msg of state.messages) {
+      if (!Array.isArray(msg.content)) {
+        continue;
+      }
+      for (const block of msg.content) {
+        if (block.type === "tool" && block.id === toolCallId) {
+          block.backgroundResult = result;
+          block.completedAt = Date.now();
+          if (subAgentMessages) {
+            block.subAgentMessages = subAgentMessages;
+          }
+        }
+      }
+    }
+    onEvent({
+      type: "tool_background_complete",
+      id: toolCallId,
+      name,
+      result
+    });
+    backgroundQueue.push({
+      toolCallId,
+      name,
+      result,
+      completedAt: Date.now()
+    });
+    if (!running) {
+      flushBackgroundQueue();
+    }
+  }
   const USER_FACING_TOOLS = /* @__PURE__ */ new Set([
     "promptUser",
     "confirmDestructiveAction",
@@ -4785,6 +4929,7 @@ async function startHeadless(opts = {}) {
       case "turn_done":
         completedEmitted = true;
         emit("completed", { success: true }, rid);
+        setTimeout(() => flushBackgroundQueue(), 0);
         return;
       case "turn_cancelled":
         completedEmitted = true;
@@ -4831,6 +4976,7 @@ async function startHeadless(opts = {}) {
             name: e.name,
             input: e.input,
             ...e.partial && { partial: true },
+            ...e.background && { background: true },
             ...e.parentToolId && { parentToolId: e.parentToolId }
           },
           rid
@@ -4849,6 +4995,18 @@ async function startHeadless(opts = {}) {
           rid
         );
         return;
+      case "tool_background_complete":
+        emit(
+          "tool_background_complete",
+          {
+            id: e.id,
+            name: e.name,
+            result: e.result,
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
       case "tool_stopped":
         emit(
           "tool_stopped",
@@ -4916,6 +5074,7 @@ async function startHeadless(opts = {}) {
     }
     let userMessage = parsed.text ?? "";
     const isCommand = !!parsed.runCommand;
+    const isHidden = isCommand || !!parsed.hidden;
     if (parsed.runCommand === "sync") {
       userMessage = loadActionPrompt("sync");
     } else if (parsed.runCommand === "publish") {
@@ -4940,8 +5099,9 @@ async function startHeadless(opts = {}) {
         signal: currentAbort.signal,
         onEvent,
         resolveExternalTool,
-        hidden: isCommand,
-        toolRegistry
+        hidden: isHidden,
+        toolRegistry,
+        onBackgroundComplete
       });
       if (!completedEmitted) {
         emit(