@mutagent/cli 0.1.268 → 0.1.269

package/dist/bin/cli.js

@@ -6417,25 +6417,32 @@ async function fetchSandboxTraces(id) {
 }
 async function openAttachStream(id, options = {}) {
   const query = options.since === undefined ? "" : `?since=${String(options.since)}`;
-  return openStream(`/api/sandbox/${encodeURIComponent(id)}/stream${query}`, id, options);
+  return openStream(`/api/sandbox/${encodeURIComponent(id)}/stream${query}`, { id, retryHint: `Retry with: mutagent helix attach ${id}` }, options);
 }
 async function openExecStream(id, body, options = {}) {
-  return openStream(`/api/sandbox/${encodeURIComponent(id)}/exec?stream=1`, id, options, {
+  return openStream(`/api/sandbox/${encodeURIComponent(id)}/exec?stream=1`, { id, retryHint: `Retry with: mutagent helix attach ${id}` }, options, {
     method: "POST",
     body: JSON.stringify(body),
     headers: { "Content-Type": "application/json" }
   });
 }
-async function openStream(path, sandboxId, options, init = {}) {
+async function openAgentRunStream(body, options = {}) {
+  return openStream("/api/sandbox/agent/run?stream=1", { retryHint: "Retry the turn, or run it blocking with: mutagent helix run ... --no-stream" }, options, {
+    method: "POST",
+    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json" }
+  });
+}
+async function openStream(path, sandbox, options, init = {}) {
   const { response } = await sandboxFetch(path, {
     ...init,
     headers: { Accept: "text/event-stream", ...toHeaderRecord(init.headers) },
     signal: options.signal
   });
   if (!response.ok)
-    throw await toCliError(response, sandboxId);
+    throw await toCliError(response, sandbox.id);
   if (!response.body) {
-    throw new MutagentError("EMPTY_STREAM", "The server accepted the stream request but sent no body.", `Retry with: mutagent helix attach ${sandboxId}`);
+    throw new MutagentError("EMPTY_STREAM", "The server accepted the stream request but sent no body.", sandbox.retryHint);
   }
   return response.body;
 }
@@ -6463,6 +6470,31 @@ function parseStatusPayload(data) {
     exitCode: typeof record.exitCode === "number" ? record.exitCode : null
   };
 }
+function parseSandboxRunPayload(data) {
+  const record = parseRecord(data);
+  if (!record)
+    return null;
+  const { sandboxId, preset } = record;
+  if (typeof sandboxId !== "string" || sandboxId === "")
+    return null;
+  return { sandboxId, preset: typeof preset === "string" ? preset : "" };
+}
+function parseSandboxResultPayload(data) {
+  const record = parseRecord(data);
+  if (!record)
+    return null;
+  const { sandboxId, preset, exitCode, timedOut, tornDown, error } = record;
+  if (typeof sandboxId !== "string" || sandboxId === "")
+    return null;
+  return {
+    sandboxId,
+    preset: typeof preset === "string" ? preset : "",
+    exitCode: typeof exitCode === "number" ? exitCode : null,
+    timedOut: timedOut === true,
+    tornDown: tornDown === true,
+    ...typeof error === "string" ? { error } : {}
+  };
+}
 function parseErrorPayload(data) {
   const record = parseRecord(data);
   const message = record && typeof record.message === "string" ? record.message : data.trim();
@@ -6580,12 +6612,24 @@ async function runStreamSession(options) {
   const retry = options.retry ?? DEFAULT_RETRY;
   const sleep2 = options.sleep ?? delay;
   const { sink, signal } = options;
+  const onDisconnect = options.onDisconnect ?? "survives";
   let lastSeq = options.since ?? 0;
   let exitCode = null;
   let reconnects = 0;
   let gaps = 0;
   let attempt = 0;
-  const detached = () => ({ end: "detached", lastSeq, exitCode, reconnects, gaps });
+  let sandbox;
+  let result;
+  const outcome = (end) => ({
+    end,
+    lastSeq,
+    exitCode,
+    reconnects,
+    gaps,
+    ...sandbox === undefined ? {} : { sandbox },
+    ...result === undefined ? {} : { result }
+  });
+  const detached = () => outcome("detached");
   const isAborted = () => signal.aborted;
   for (;; ) {
     if (isAborted())
@@ -6600,7 +6644,7 @@ async function runStreamSession(options) {
         throw error;
       attempt += 1;
       if (attempt > retry.attempts)
-        throw exhausted(lastSeq, error);
+        throw exhausted(lastSeq, error, onDisconnect);
       reconnects += 1;
       sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
       await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
@@ -6625,6 +6669,20 @@ async function runStreamSession(options) {
             sink.stderr(payload.text, payload.seq);
           continue;
         }
+        if (event.event === "sandbox") {
+          const payload = parseSandboxRunPayload(event.data);
+          if (payload) {
+            sandbox = payload;
+            options.onSandbox?.(payload);
+          }
+          continue;
+        }
+        if (event.event === "result") {
+          const payload = parseSandboxResultPayload(event.data);
+          if (payload)
+            result = payload;
+          continue;
+        }
         if (event.event === "status") {
           const payload = parseStatusPayload(event.data);
           if (payload?.state === "exited") {
@@ -6650,19 +6708,19 @@ async function runStreamSession(options) {
         return detached();
       attempt += 1;
       if (attempt > retry.attempts)
-        throw exhausted(lastSeq, error);
+        throw exhausted(lastSeq, error, onDisconnect);
       reconnects += 1;
       sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
       await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
       continue;
     }
     if (exited)
-      return { end: "exited", lastSeq, exitCode, reconnects, gaps };
+      return outcome("exited");
     if (isAborted())
       return detached();
     attempt += 1;
     if (attempt > retry.attempts)
-      throw exhausted(lastSeq, null);
+      throw exhausted(lastSeq, null, onDisconnect);
     reconnects += 1;
     sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
     await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
@@ -6678,9 +6736,10 @@ function gapNotice(lastSeq, nextSeq) {
   const missing = nextSeq - lastSeq - 1;
   return `Output gap: ${String(missing)} event(s) between seq ${String(lastSeq)} and ` + `${String(nextSeq)} are unavailable — the server buffer rolled past the resume point. ` + "What follows is not continuous with what came before.";
 }
-function exhausted(lastSeq, cause) {
+function exhausted(lastSeq, cause, onDisconnect) {
   const detail = cause instanceof Error ? ` (${cause.message})` : "";
-  return new MutagentError("STREAM_DISCONNECTED", `Lost the sandbox stream and could not reconnect${detail}.`, `The sandbox is still running — nothing was destroyed. Resume with: mutagent helix attach <id> --since ${String(lastSeq)}`, 5);
+  const guidance = onDisconnect === "released" ? "This was a one-shot run: the server releases the sandbox as soon as the connection drops, so nothing is left running and there is nothing to re-attach to. Run the turn again, or use --no-stream to wait for the whole result in one reply." : `The sandbox is still running — nothing was destroyed. Resume with: mutagent helix attach <id> --since ${String(lastSeq)}`;
+  return new MutagentError("STREAM_DISCONNECTED", `Lost the sandbox stream and could not reconnect${detail}.`, guidance, 5);
 }
 function mentionsLostBuffer(message) {
   return /buffer|rolled|expired|evicted|no longer available|too old/i.test(message);
@@ -6754,29 +6813,45 @@ async function attachToSandbox(options) {
       open: options.open,
       sink,
       since: options.since,
-      signal: controller.signal
+      signal: controller.signal,
+      ...options.retry === undefined ? {} : { retry: options.retry },
+      ...options.onDisconnect === undefined ? {} : { onDisconnect: options.onDisconnect },
+      ...options.onSandbox === undefined ? {} : { onSandbox: options.onSandbox }
     });
-    reportOutcome(options.id, result, sink);
+    reportOutcome(options.id, result, sink, options.onDisconnect ?? "survives");
     return result;
   } finally {
     process.removeListener("SIGINT", onSigint);
   }
 }
-function reportOutcome(id, result, sink) {
+function reportOutcome(id, result, sink, onDisconnect) {
+  const box = result.sandbox?.sandboxId ?? id;
   if (result.end === "detached") {
-    sink.notice(`Detached. Sandbox ${id} is still running — nothing was destroyed.`);
-    sink.notice(`Re-attach with: ${reattachHint(id, result.lastSeq)}`);
-    sink.notice(`Destroy it with: mutagent helix rm ${id} --force`);
+    if (onDisconnect === "released") {
+      sink.notice(box === "" ? "Stopped. The turn was cancelled and the sandbox released — nothing is left running." : `Stopped. The turn was cancelled and sandbox ${box} released — nothing is left running.`);
+      sink.notice("Run the turn again to retry, or add --keep next time to hold the sandbox open.");
+      return;
+    }
+    sink.notice(`Detached. Sandbox ${box} is still running — nothing was destroyed.`);
+    sink.notice(`Re-attach with: ${reattachHint(box, result.lastSeq)}`);
+    sink.notice(`Destroy it with: mutagent helix rm ${box} --force`);
     return;
   }
   if (result.gaps > 0) {
     sink.notice(`Session ended, but ${String(result.gaps)} gap(s) occurred — the output above is not complete.`);
   }
+  if (result.result !== undefined && result.result.tornDown === false) {
+    sink.notice(`Sandbox ${result.result.sandboxId} was NOT torn down. Destroy it with: mutagent helix rm ${result.result.sandboxId} --force`);
+  }
+  if (result.result?.timedOut === true) {
+    sink.notice("The turn timed out.");
+  }
   if (result.exitCode === null) {
-    sink.notice(`Sandbox ${id} exited (no exit code reported).`);
+    const why = result.result?.error;
+    sink.notice(why === undefined ? `Sandbox ${box} exited (no exit code reported).` : `The turn did not complete: ${why}`);
     return;
   }
-  sink.notice(`Sandbox ${id} exited with code ${String(result.exitCode)}.`);
+  sink.notice(`Sandbox ${box} exited with code ${String(result.exitCode)}.`);
   if (result.exitCode !== 0) {
     process.exitCode = result.exitCode;
   }
@@ -7004,7 +7079,7 @@ AI Agent Directive:
 import chalk22 from "chalk";
 init_errors();
 function registerRunCommand(parent) {
-  parent.command("run").description("Run one Helix agent turn in a fresh sandbox").argument("<task...>", "WHAT to do this turn").requiredOption("--prompt <definition>", "WHO the agent is — the agent definition").option("--preset <name>", "Preset to run on (default: the backend default)").option("--keep", "Keep the sandbox afterwards instead of tearing it down").option("--timeout-ms <n>", "Per-command timeout in milliseconds").addHelpText("after", `
+  parent.command("run").description("Run one Helix agent turn in a fresh sandbox").argument("<task...>", "WHAT to do this turn").requiredOption("--prompt <definition>", "WHO the agent is — the agent definition").option("--preset <name>", "Preset to run on (default: the backend default)").option("--keep", "Keep the sandbox afterwards instead of tearing it down").option("--timeout-ms <n>", "Per-command timeout in milliseconds").option("--no-stream", "Wait for the whole turn instead of watching it happen").addHelpText("after", `
 Examples:
   ${chalk22.dim("$")} mutagent helix run "summarise the failing tests" --prompt "You are a test triage agent."
   ${chalk22.dim("$")} mutagent helix run fix the flaky login spec --prompt "$(cat agent.md)"
@@ -7022,13 +7097,27 @@ and tears the sandbox down. There is no sandbox id argument because there is no
 endpoint that runs an agent turn inside an existing box. Pass --keep to hold the
 sandbox open; the id is reported so you can attach or exec against it.
 
-The turn is blocking and does not stream — the server returns the whole result.
-Its exit code becomes this command's exit code. See 'mutagent helix presets' for
-what --preset accepts.
+The turn STREAMS by default — output appears as the agent produces it, and the
+sandbox id is printed before the first line so you always know what is running.
+Its exit code becomes this command's exit code.
+
+Ctrl-C CANCELS THE TURN. This is the one place in 'mutagent helix' where it does:
+a one-shot sandbox belongs to this connection, so leaving releases it. Elsewhere
+Ctrl-C detaches and the box keeps running. Use --keep if you want it to survive.
+
+There is no reconnect on a streamed run. If the connection drops the turn is
+lost, and you are told so — retrying would spawn a second sandbox and run the
+turn again. Use --no-stream over a flaky link.
+
+See 'mutagent helix presets' for what --preset accepts.
 
 AI Agent Directive:
-  --json returns ONE object: { success, result: { sandboxId, exitCode, stdout,
-  stderr, timedOut, tornDown }, _links }. No NDJSON here — the call is blocking.
+  --no-stream --json returns ONE object: { success, result: { sandboxId,
+  exitCode, stdout, stderr, timedOut, tornDown }, _links }. Prefer it for a
+  result you intend to parse.
+  --json while streaming emits NDJSON — one object per line — and the LAST line
+  is a complete summary object, so '| tail -1' still yields one object. Same
+  convention as 'mutagent helix exec'.
   Both --prompt and the task are required; do not fold one into the other.
       `).action(async (taskParts, options) => {
     const isJson = getJsonFlag(parent);
@@ -7043,17 +7132,62 @@ AI Agent Directive:
         throw new MutagentError("MISSING_ARGUMENTS", "--prompt is required — it is WHO the agent is, not what it should do.", `The task you already passed is the WHAT. Add the agent definition:
   --prompt "You are a ..." (or --prompt "$(cat agent.md)")`);
       }
-      const result = await agentRun({
+      const body = {
         prompt,
         task,
         ...oneShotFields(options.preset, options.keep, options.timeoutMs)
-      });
-      reportResult(result, output, isJson, { prompt, task });
+      };
+      if (options.stream === false) {
+        const result = await agentRun(body);
+        reportResult(result, output, isJson, { prompt, task });
+        return;
+      }
+      await streamAgentTurn(body, isJson, options.keep === true);
     } catch (error) {
       handleError(error, isJson);
     }
   });
 }
+async function streamAgentTurn(body, isJson, keep) {
+  let sandboxId;
+  let opened = false;
+  const session = await attachToSandbox({
+    id: "",
+    isJson,
+    onDisconnect: keep ? "survives" : "released",
+    retry: { attempts: 0, baseDelayMs: 0 },
+    onSandbox: (sandbox) => {
+      sandboxId = sandbox.sandboxId;
+    },
+    open: ({ signal }) => {
+      if (opened) {
+        throw new MutagentError("STREAM_DISCONNECTED", "The turn’s stream dropped and cannot be resumed.", "A one-shot run cannot be reconnected — the server released the sandbox when the connection dropped, and re-opening would run the whole turn again in a new box. Run it again, or use --no-stream.", 5);
+      }
+      opened = true;
+      return openAgentRunStream(body, { signal });
+    }
+  });
+  if (isJson) {
+    console.log(JSON.stringify({
+      success: true,
+      prompt: body.prompt,
+      task: body.task,
+      sandboxId: session.result?.sandboxId ?? sandboxId ?? null,
+      preset: session.result?.preset ?? session.sandbox?.preset ?? null,
+      end: session.end,
+      exitCode: session.exitCode,
+      timedOut: session.result?.timedOut ?? false,
+      tornDown: session.result?.tornDown ?? null,
+      ...session.result?.error === undefined ? {} : { error: session.result.error },
+      lastSeq: session.lastSeq,
+      gaps: session.gaps,
+      ...sandboxId === undefined ? {} : { _links: sandboxLinks(sandboxId) }
+    }));
+  }
+  if (session.end === "exited" && session.exitCode === null) {
+    process.exitCode = 1;
+  }
+}
 function registerExecCommand(parent) {
   parent.command("exec").description("Run a command in a sandbox — an existing one, or a fresh one").argument("<argv...>", "Command and arguments (argv, not a shell string)").option("--sandbox <id>", "Run in this existing sandbox instead of a fresh one").option("--preset <name>", "Preset for the fresh sandbox (ignored with --sandbox)").option("--keep", "Keep the fresh sandbox afterwards (ignored with --sandbox)").option("--cwd <dir>", "Working directory inside the sandbox").option("--timeout-ms <n>", "Command timeout in milliseconds").option("--no-stream", "Wait for the full result instead of streaming it").addHelpText("after", `
 Examples:
@@ -7675,5 +7809,5 @@ program.addCommand(createFeedbackCommand());
 program.addCommand(createTraceCommand());
 program.parse();
 
-//# debugId=8A72E382D57F3D0964756E2164756E21
+//# debugId=84C2BB73F467526664756E2164756E21
 //# sourceMappingURL=cli.js.map