@mutagent/cli 0.1.351 → 0.1.353

package/dist/bin/cli.js

@@ -16783,7 +16783,7 @@ var init_sdk_debug = __esm(() => {
 });
 
 // src/lib/sdk-mappers.ts
-import { Provider as SDKProviderEnum } from "@mutagent/sdk/models";
+import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value2) {
   return PROVIDER_TYPES.includes(value2);
 }
@@ -17096,7 +17096,7 @@ class SDKClientWrapper {
   }
   async listProviders(filters) {
     try {
-      const response = await this.sdk.providerConfigs.listProviders({
+      const response = await this.sdk.llmProviders.listProviderConfigs({
         provider: filters?.type,
         includeInactive: true
       });
@@ -17114,7 +17114,7 @@ class SDKClientWrapper {
   }
   async getProvider(id) {
     try {
-      const response = await this.sdk.providerConfigs.getProvider({
+      const response = await this.sdk.llmProviders.getProviderConfig({
         id
       });
       return toProvider(response);
@@ -17190,7 +17190,7 @@ class SDKClientWrapper {
   }
   async testProvider(id) {
     try {
-      const response = await this.sdk.providerConfigs.testProvider({
+      const response = await this.sdk.llmProviders.testProviderConfig({
         id
       });
       return toProviderTestResult(response);
@@ -17236,7 +17236,7 @@ class SDKClientWrapper {
         });
         return scrubKnownSuccessDeep({ ...response2, workspaceId });
       }
-      const response = await this.sdk.providerConfigs.updateProvider({
+      const response = await this.sdk.llmProviders.updateProviderConfig({
         id,
         body: {
           name: data.name,
@@ -17255,7 +17255,7 @@ class SDKClientWrapper {
   async deleteProvider(id) {
     const workspaceId = this.requireUnambiguousWorkspace();
     try {
-      await this.sdk.providerConfigs.deleteProvider({ id });
+      await this.sdk.llmProviders.deleteProviderConfig({ id });
       return { workspaceId };
     } catch (error3) {
       this.handleError(error3);
@@ -17403,7 +17403,7 @@ function sessionView(row) {
   return { ...row, revision: nullableInteger(row.revision) };
 }
 function bindAgentDeploymentSDK(sdk, endpoint, workspaceId) {
-  const client = sdk.helixAgentDeployments;
+  const client = sdk.managedAgents;
   return {
     endpoint,
     workspaceId,
@@ -17540,8 +17540,8 @@ Run a managed agent with: mutagent helix agent @slug[:vN|:latest] [--env X] -p "
 
 The compiler needs Bun 1.3.14 (on PATH, or MUTAGENT_BUN_BIN). agent run needs a
 local Helix binary (mutagent install helix puts one at ~/.mutagent/bin/helix;
-MUTAGENT_HELIX_BIN selects another) and the LLM provider key for
-model on this machine.
+MUTAGENT_HELIX_BIN selects another) and, on this machine, the key of the
+LLM provider that model names.
 
 JSON: --json prints one result object on stdout. Revisions are numbers in JSON
 and vN in messages.
@@ -17565,7 +17565,7 @@ uploaded. The archive must be outside the agent folder; an existing file needs
 --force.
 Example: mutagent agent pack invoice/agent.md --output invoice.tgz --json`,
   run: `Compiles the folder and runs the task with the local Helix binary, in a
-temporary copy of the package on this machine; it is not isolated in a box. It
+temporary copy of the package on this machine; it is not isolated in a sandbox. It
 creates nothing in the workspace. The task is the positional text (or the words
 after --). A slug is refused: a managed agent runs with mutagent helix agent @slug.
 Example: mutagent agent run invoice/agent.md "Price three widget units."`,
@@ -19231,7 +19231,7 @@ init_sdk_client();
 import { Command as Command6 } from "commander";
 import chalk12 from "chalk";
 init_errors();
-import { Provider as ProviderCatalogId } from "@mutagent/sdk/models";
+import { LlmProviderType as ProviderCatalogId } from "@mutagent/sdk/models";
 
 // src/commands/providers/add.ts
 init_sdk_client();
@@ -19744,7 +19744,7 @@ AI Agent Directive:
       const isGateway = allowedFamilies !== undefined;
       if (options.hostedFamily) {
         if (!isGateway) {
-          throw new MutagentError("HOSTED_FAMILY_NOT_APPLICABLE", `'${providerType}' serves its own models, so it has no hosted family.`, `Drop --hosted-family, or pick a gateway provider: ${[...GATEWAY_PROVIDERS].join(", ")}`);
+          throw new MutagentError("HOSTED_FAMILY_NOT_APPLICABLE", `'${providerType}' serves its own models, so it has no hosted family.`, `Drop --hosted-family, or pick a gateway LLM provider: ${[...GATEWAY_PROVIDERS].join(", ")}`);
         }
         if (!allowedFamilies.includes(options.hostedFamily)) {
           throw new MutagentError("INVALID_HOSTED_FAMILY", `'${providerType}' does not host '${options.hostedFamily}'.`, `${providerType} hosts: ${allowedFamilies.join(", ")}`);
@@ -19780,7 +19780,7 @@ AI Agent Directive:
           _directive: directive
         });
       } else {
-        output.success(`Provider created: ${created.name}`);
+        output.success(`LLM provider created: ${created.name}`);
         console.log(`  ID:        ${created.id}`);
         console.log(`  Type:      ${providerType}`);
         if (options.hostedFamily) {
@@ -19792,7 +19792,7 @@ AI Agent Directive:
         console.log(`  Workspace: ${workspaceId}`);
         console.log(`  URL:       ${providerLink(created.id)}`);
         if (options.setDefault) {
-          console.log(chalk8.green("  Set as default provider"));
+          console.log(chalk8.green("  Set as the default LLM provider"));
         }
         console.log("");
         console.log(chalk8.dim("API key is encrypted server-side. Use `providers get` to see masked key."));
@@ -19803,12 +19803,12 @@ AI Agent Directive:
   });
 }
 function buildProviderCreatedDirective(provider, workspaceId) {
-  const title = `Provider Created — ${provider.name ?? "Unknown"}`;
+  const title = `LLM provider created: ${provider.name ?? "Unknown"}`;
   const dashboardUrl = providerLink(provider.id);
   const apiUrl = `/api/providers/${String(provider.id)}`;
   const rows = [
     { label: "Name", value: provider.name ?? "Unknown" },
-    { label: "Provider ID", value: String(provider.id) },
+    { label: "LLM provider ID", value: String(provider.id) },
     { label: "Workspace", value: workspaceId }
   ];
   const links = [
@@ -19888,7 +19888,7 @@ Only the fields you pass change. An update never sets the workspace default mode
           _directive: directive
         });
       } else {
-        output.success(`Provider updated: ${updated.name}`);
+        output.success(`LLM provider updated: ${updated.name}`);
         console.log(`  ID:        ${updated.id}`);
         if (updated.workspaceId) {
           console.log(`  Workspace: ${updated.workspaceId}`);
@@ -19905,11 +19905,11 @@ Only the fields you pass change. An update never sets the workspace default mode
 }
 function buildProviderUpdatedDirective(provider, requestId) {
   const id = provider.id ?? requestId;
-  const title = `Provider Updated — ${provider.name ?? String(id)}`;
+  const title = `LLM provider updated: ${provider.name ?? String(id)}`;
   const dashboardUrl = providerLink(id);
   const apiUrl = `/api/providers/${String(id)}`;
   const rows = [
-    { label: "Provider ID", value: String(id) },
+    { label: "LLM provider ID", value: String(id) },
     ...provider.name ? [{ label: "Name", value: provider.name }] : []
   ];
   const links = [
@@ -19952,7 +19952,7 @@ AI Agent Directive:
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       if (!options.force && !isJson) {
-        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting provider ${id} requires confirmation. ` + "Warning: encrypted API keys are irrecoverable after deletion.", `Run: mutagent providers delete --help
+        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting LLM provider ${id} requires confirmation. ` + "Warning: encrypted API keys are irrecoverable after deletion.", `Run: mutagent providers delete --help
 ` + `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
 ` + `Use --force to confirm: mutagent providers delete ${id} --force`);
       }
@@ -19972,7 +19972,7 @@ AI Agent Directive:
             });
             echoDirectiveToStderr(directive);
           } else {
-            output.success(`Provider ${id} already deleted (idempotent)`);
+            output.success(`LLM provider ${id} already deleted (idempotent)`);
           }
           return;
         }
@@ -19988,7 +19988,7 @@ AI Agent Directive:
           _directive: directive
         });
       } else {
-        output.success(`Deleted provider: ${id}`);
+        output.success(`Deleted LLM provider: ${id}`);
         if (deletedFrom) {
           console.log(`  Workspace: ${deletedFrom}`);
         }
@@ -20000,9 +20000,9 @@ AI Agent Directive:
   });
 }
 function buildProviderDeletedDirective(id) {
-  const title = `Provider Deleted — ${id}`;
+  const title = `LLM provider deleted: ${id}`;
   const settingsUrl = providerSettingsLink();
-  const rows = [{ label: "Provider ID", value: id }];
+  const rows = [{ label: "LLM provider ID", value: id }];
   const links = [{ label: "Settings", url: settingsUrl }];
   const next = [`mutagent providers list --json`];
   return {
@@ -20784,7 +20784,7 @@ Plan:`));
         output.output({
           success: failed.length === 0,
           cloudExecution: "not-verified",
-          modelRoster: "Explicit lists are authoritative; recognized native identities use the service-pinned catalogue when no list is declared. Other custom providers require declarations.",
+          modelRoster: "Explicit lists are authoritative; recognized native identities use the service-pinned catalogue when no list is declared. Other custom LLM providers require declarations.",
           workspaceId: target,
           endpoint: config.endpoint ?? "https://api.mutagent.io",
           agentDir,
@@ -20825,7 +20825,7 @@ var VALID_PROVIDER_TYPES = Object.values(ProviderCatalogId);
 function validateProviderType(type4) {
   const match = VALID_PROVIDER_TYPES.find((entry) => entry === type4);
   if (!match) {
-    throw new MutagentError("INVALID_PROVIDER_TYPE", `Invalid provider type: ${type4}`, `Valid types: ${VALID_PROVIDER_TYPES.join(", ")}`);
+    throw new MutagentError("INVALID_PROVIDER_TYPE", `Invalid LLM provider type: ${type4}`, `Valid types: ${VALID_PROVIDER_TYPES.join(", ")}`);
   }
   return match;
 }
@@ -20903,7 +20903,7 @@ Examples:
         output.output({ ...result, data: withLinks });
       } else {
         if (result.data.length === 0) {
-          output.info("No providers configured.");
+          output.info("No LLM providers configured.");
           output.info(`Configure at: ${providerSettingsLink()}`);
         } else {
           const formatted = result.data.map((p) => ({
@@ -20966,7 +20966,7 @@ ${chalk12.dim("Tests the connection and lists the models the LLM provider report
     try {
       const client = await getSDKClient();
       if (!isJson) {
-        output.info(`Testing provider ${id}...`);
+        output.info(`Testing LLM provider ${id}...`);
       }
       const result = scrubKnownSuccessDeep(await client.testProvider(id));
       if (isJson) {
@@ -20974,7 +20974,7 @@ ${chalk12.dim("Tests the connection and lists the models the LLM provider report
       } else {
         if (result.success) {
           const latency = typeof result.latencyMs === "number" ? ` (${String(result.latencyMs)}ms)` : "";
-          output.success(`Provider test passed${latency}`);
+          output.success(`LLM provider test passed${latency}`);
           console.log(chalk12.green(`Message: ${result.message}`));
           if (result.models && result.models.length > 0) {
             console.log(chalk12.bold(`
@@ -20984,7 +20984,7 @@ Available Models:`));
             });
           }
         } else {
-          output.error(`Provider test failed: ${result.message}`);
+          output.error(`LLM provider test failed: ${result.message}`);
           if (result.error) {
             console.log(chalk12.red(`Error: ${result.error}`));
           }
@@ -23868,13 +23868,13 @@ var TRANSPORT_TABLE = [
     takesValue: false,
     class: "cross",
     via: "args",
-    note: "The box runs the same launcher, so its diagnostics flag means the same there."
+    note: "The sandbox runs the same launcher, so its diagnostics flag means the same there."
   },
   {
     token: "--refresh-runtime",
     takesValue: false,
     class: "reject",
-    reason: "the box does not extract a runtime — its harness is baked into the image",
+    reason: "the sandbox image already contains Helix",
     alternative: "The image pins its own Helix build; see `mutagent sandbox presets`."
   },
   {
@@ -23895,7 +23895,7 @@ var TRANSPORT_TABLE = [
     takesValue: true,
     class: "translate",
     launcherClass: "cross",
-    note: "On `helix agent`, the definition selector: resolved against the LOCAL agent dirs when this machine has it — the definition body travels, because the box would resolve the same name to its BUNDLED agent first. A name not found here crosses as `--name <name>` in args and the box resolves it (bundled roster, then its agent dirs); the box refuses an unknown name rather than running a different one. See agent-argv.ts. On the launcher arms (bare `helix`, `helix --prime`), pi’s session label, forwarded as typed like `-n`."
+    note: "On `helix agent`, the definition selector: resolved against the LOCAL agent dirs when this machine has it, and the definition body is sent, because the sandbox would resolve the same name to its BUNDLED agent first. A name not found here is sent as `--name <name>` in args and the sandbox resolves it (bundled roster, then its agent dirs); the sandbox refuses an unknown name rather than running a different one. See agent-argv.ts. On the launcher arms (bare `helix`, `helix --prime`), pi’s session label, forwarded as typed like `-n`."
   },
   {
     token: "--agent",
@@ -23920,21 +23920,21 @@ var TRANSPORT_TABLE = [
     token: "--api-key",
     takesValue: true,
     class: "reject",
-    reason: "it would put a provider secret on the wire and in the box’s process table",
+    reason: "it would send an LLM provider key over the network and show it in the sandbox’s process list",
     alternative: "An LLM key for a cloud run belongs in the workspace’s LLM providers: `mutagent providers add -k <key> …`, or `mutagent providers mirror` to copy your local Helix logins."
   },
   {
     token: "--list-models",
     takesValue: true,
     class: "reject",
-    reason: "it prints a catalogue and exits without taking a turn, so a whole sandbox is spawned to answer a question the box cannot be asked interactively",
-    alternative: "Run it against a box you already hold: `mutagent sandbox exec --sandbox <id> -- helix --list-models`."
+    reason: "it prints the model list and exits; a cloud run would start a sandbox for it",
+    alternative: "Run: mutagent helix models"
   },
   {
     token: "--system-prompt",
     takesValue: true,
     class: "translate",
-    note: "pi reads the value as a FILE when the path exists (`resolvePromptInput`), so a value naming a local file is inlined here; anything else is text and crosses as it is. It was CROSS, so a local path crossed as a path the box does not have (DR-11)."
+    note: "A value that names a local file is read here and sent as text; any other value is sent as it is."
   },
   {
     token: "--append-system-prompt",
@@ -23958,7 +23958,7 @@ var TRANSPORT_TABLE = [
     takesValue: false,
     class: "cross",
     via: "args",
-    note: "Same flag as --no-skills. The box HAS skills, so switching them off there is a real and honourable request."
+    note: "Same flag as --no-skills. Turns off the skills in the sandbox image."
   },
   { token: "--no-prompt-templates", takesValue: false, class: "cross", via: "args" },
   { token: "-np", takesValue: false, class: "cross", via: "args" },
@@ -24011,7 +24011,7 @@ var TRANSPORT_TABLE = [
     token: "--tui-mode",
     takesValue: true,
     class: "reject",
-    reason: "there is no TUI in the box — the turn is non-interactive by construction",
+    reason: "a cloud run has no terminal",
     alternative: "Drop it."
   },
   {
@@ -24026,14 +24026,14 @@ var TRANSPORT_TABLE = [
     takesValue: true,
     class: "reject",
     reason: HOST_PATH,
-    alternative: "Capture the session you want to fork with `mutagent helix session checkpoint`, then restore it into a new box."
+    alternative: "Capture the session you want to fork with `mutagent helix session checkpoint`, then restore it into a new sandbox."
   },
   {
     token: "--session-dir",
     takesValue: true,
     class: "reject",
     reason: HOST_PATH,
-    alternative: "Sessions live inside the box; read them with `mutagent sandbox exec --sandbox <id>`."
+    alternative: "Sessions are stored inside the sandbox; read them with `mutagent sandbox exec --sandbox <id>`."
   },
   { token: "--no-session", takesValue: false, class: "cross", via: "args" },
   { token: "--session-id", takesValue: true, class: "cross", via: "args" },
@@ -24048,15 +24048,15 @@ var TRANSPORT_TABLE = [
     token: "--continue",
     takesValue: false,
     class: "reject",
-    reason: "there is no previous session in a fresh box to continue",
-    alternative: "Run against a box you kept: `mutagent helix agent --sandbox <id> …`, or restore a checkpoint."
+    reason: "there is no previous session in a new sandbox to continue",
+    alternative: "Run against a sandbox you kept: `mutagent helix agent --sandbox <id> …`, or restore a checkpoint."
   },
   {
     token: "-c",
     takesValue: false,
     class: "reject",
-    reason: "there is no previous session in a fresh box to continue",
-    alternative: "Run against a box you kept: `mutagent helix agent --sandbox <id> …`, or restore a checkpoint."
+    reason: "there is no previous session in a new sandbox to continue",
+    alternative: "Run against a sandbox you kept: `mutagent helix agent --sandbox <id> …`, or restore a checkpoint."
   },
   {
     token: "--resume",
@@ -24076,7 +24076,7 @@ var TRANSPORT_TABLE = [
     token: "--export",
     takesValue: true,
     class: "reject",
-    reason: "it writes a file on the machine the harness runs on, which is the box — the file would be destroyed with it",
+    reason: "it writes a file on the machine the harness runs on, which is the sandbox; the file is deleted with it",
     alternative: "Capture the stream instead: `mutagent helix agent … --json > run.ndjson`."
   },
   { token: "--verbose", takesValue: false, class: "cross", via: "args" },
@@ -24085,26 +24085,26 @@ var TRANSPORT_TABLE = [
     token: "--approve",
     takesValue: false,
     class: "drop",
-    notice: "--approve is dropped: a sandbox has no interactive trust prompt to pre-answer, and the box grants project trust by construction."
+    notice: "--approve is ignored: a cloud sandbox always trusts the project."
   },
   {
     token: "-a",
     takesValue: false,
     class: "drop",
-    notice: "-a is dropped: a sandbox has no interactive trust prompt to pre-answer, and the box grants project trust by construction."
+    notice: "-a is ignored: a cloud sandbox always trusts the project."
   },
   {
     token: "--no-approve",
     takesValue: false,
     class: "reject",
-    reason: "withholding project trust in a non-interactive box leaves the agent unable to read the workspace and unable to ask",
+    reason: "without project trust the agent cannot read the workspace, and a cloud run cannot ask you for it",
     alternative: "Drop it, or restrict the agent with --tools / --exclude-tools instead."
   },
   {
     token: "-na",
     takesValue: false,
     class: "reject",
-    reason: "withholding project trust in a non-interactive box leaves the agent unable to read the workspace and unable to ask",
+    reason: "without project trust the agent cannot read the workspace, and a cloud run cannot ask you for it",
     alternative: "Drop it, or restrict the agent with --tools / --exclude-tools instead."
   },
   {
@@ -24239,13 +24239,13 @@ function argumentLabel(args, i, files) {
 function checkArgsForRoute(args, files = []) {
   args.forEach((arg, i) => {
     if (arg === "") {
-      throw new MutagentError("INVALID_ARGUMENTS", `${argumentLabel(args, i, files)} is empty, and a session in a box refuses an empty argument.`, "Give it a value, or drop the flag.", 2);
+      throw new MutagentError("INVALID_ARGUMENTS", `${argumentLabel(args, i, files)} is empty, and a cloud session refuses an empty argument.`, "Give it a value, or drop the flag.", 2);
     }
   });
 }
 function checkSandboxId(value2) {
   if (value2?.trim().startsWith("-") === true) {
-    throw new MutagentError("INVALID_ARGUMENTS", `--sandbox needs a sandbox id, and got a flag instead: ${redactToken(value2.trim())}`, "Name the box: --sandbox <id>. 'mutagent sandbox ls' shows the running ones.", 2);
+    throw new MutagentError("INVALID_ARGUMENTS", `--sandbox needs a sandbox id, and got a flag instead: ${redactToken(value2.trim())}`, "Name the sandbox: --sandbox <id>. 'mutagent sandbox ls' shows the running ones.", 2);
   }
 }
 
@@ -24321,7 +24321,7 @@ function planAgentArgv(argv, deps, flags = {}) {
         continue;
       }
       if (token.startsWith("@")) {
-        throw rejection(redactToken(token), "an @file argument is read from the machine the harness runs on, and the box has no copy of it", "Inline the file’s contents into the task, or `mutagent sandbox exec` it into a box you kept. File upload does not exist yet.");
+        throw rejection(redactToken(token), "an @file argument is read from the machine the harness runs on, and the sandbox has no copy of it", "Inline the file’s contents into the task, or `mutagent sandbox exec` it into a sandbox you kept. File upload does not exist yet.");
       }
       if (token.startsWith("--")) {
         forwardFlag(token);
@@ -24333,7 +24333,7 @@ function planAgentArgv(argv, deps, flags = {}) {
         continue;
       }
       if (token.startsWith("-")) {
-        throw rejection(redactToken(token), "the harness rejects unknown short options outright, so forwarding it would fail inside the box instead of here", "Check the spelling against `helix agent --help`, or use the long form.");
+        throw rejection(redactToken(token), "the harness rejects unknown short options outright, so forwarding it would fail inside the sandbox instead of here", "Check the spelling against `helix agent --help`, or use the long form.");
       }
       if (i === 0 && source2 === undefined) {
         source2 = { kind: "prompt", value: token };
@@ -24405,7 +24405,7 @@ function planAgentArgv(argv, deps, flags = {}) {
   };
 }
 function rejection(token, reason, alternative) {
-  return new MutagentError("INVALID_ARGUMENTS", `${token} cannot cross to a cloud sandbox: ${reason}.`, alternative, 2);
+  return new MutagentError("INVALID_ARGUMENTS", `${token} is not supported in a cloud run: ${reason}.`, alternative, 2);
 }
 function resolveDefinition(source2, deps) {
   if (source2 === undefined) {
@@ -24435,7 +24435,7 @@ function resolveDefinition(source2, deps) {
   const path = findAgentFile(source2.value, roots, deps);
   if (path === undefined) {
     return {
-      origin: `--name ${source2.value} (not on this machine; resolved by the box — searched: ${roots.join(", ")})`,
+      origin: `--name ${source2.value} (not on this machine; resolved in the sandbox; searched: ${roots.join(", ")})`,
       forwardName: source2.value
     };
   }
@@ -24521,14 +24521,14 @@ function nativeMode(args, print, rpc = false) {
     return "json";
   if (print)
     return "text";
-  throw new MutagentError("NOT_SUPPORTED", "The Cloud CLI does not provide a terminal chat UI.", 'Use -p "<task>" for a complete run, --mode json "<task>" for events, or --mode rpc with a JSONL client.', 2);
+  throw new MutagentError("NOT_SUPPORTED", "mutagent helix has no terminal chat UI.", 'Use -p "<task>" for a complete run, --mode json "<task>" for events, or --mode rpc with a JSONL client.', 2);
 }
 function nativeTaskNotices(mode, messages) {
   if (mode === "rpc") {
-    return messages.length === 0 ? [] : ["Native RPC ignores positional messages; send prompt commands on JSONL stdin."];
+    return messages.length === 0 ? [] : ["An interactive session ignores positional messages; send the task as a prompt command on stdin."];
   }
   if (!messages.some((message) => message.trim() !== "")) {
-    throw new MutagentError("MISSING_ARGUMENTS", "A noninteractive Cloud run needs a task.", 'Add -p "<task>" or use --mode json "<task>".', 2);
+    throw new MutagentError("MISSING_ARGUMENTS", "A headless cloud run needs a task.", 'Add -p "<task>" or use --mode json "<task>".', 2);
   }
   return [];
 }
@@ -24947,7 +24947,7 @@ function parseSessionPayload(data) {
   const record3 = parseRecord(data);
   if (!record3)
     return null;
-  const { seq, ts: ts2, sessionId, status, exitCode, lastSeq, generation } = record3;
+  const { seq, ts: ts2, sessionId, status, exitCode, lastSeq, generation, mode } = record3;
   if (typeof seq !== "number" || typeof sessionId !== "string" || typeof status !== "string") {
     return null;
   }
@@ -24958,7 +24958,8 @@ function parseSessionPayload(data) {
     status,
     exitCode: typeof exitCode === "number" ? exitCode : null,
     lastSeq: typeof lastSeq === "number" ? lastSeq : -1,
-    generation: typeof generation === "number" ? generation : 0
+    generation: typeof generation === "number" ? generation : 0,
+    ...typeof mode === "string" ? { mode } : {}
   };
 }
 function parseLivePayload(data) {
@@ -25315,7 +25316,7 @@ async function runStreamSession(options) {
             break;
           }
           if (!alreadyDelivered(payload2.seq)) {
-            sink.notice(`Session ${payload2.sessionId} started.`);
+            sink.notice(`Session ${payload2.sessionId} started${payload2.mode === undefined ? "" : ` (${payload2.mode})`}.`);
           }
           continue;
         }
@@ -25409,7 +25410,7 @@ function gapNotice(lastSeq, nextSeq) {
 }
 function exhausted(lastSeq, cause, onDisconnect) {
   const detail = cause instanceof Error ? ` (${cause.message})` : "";
-  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 sandbox attach <id> --since ${String(lastSeq)}`;
+  const guidance = onDisconnect === "released" ? "This was a single-command run: the server deletes the sandbox when 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 sandbox attach <id> --since ${String(lastSeq)}`;
   return new MutagentError("STREAM_DISCONNECTED", `Lost the sandbox stream and could not reconnect${detail}.`, guidance, 5);
 }
 function isGapError(payload) {
@@ -25526,11 +25527,11 @@ async function runNativeSession(options) {
     }
     const closed = await options.closeInput(inputController.signal);
     if (!closed.closed) {
-      throw new MutagentError("RPC_INPUT_REJECTED", "The session did not confirm stdin closure.", "Inspect the live execution; no signal was sent as a substitute for EOF.", 1);
+      throw new MutagentError("RPC_INPUT_REJECTED", "The session did not confirm stdin closure.", "Check the session: mutagent helix session ls. No signal was sent in place of EOF.", 1);
     }
   };
   try {
-    notice("Session " + options.reference + (options.interrupt === undefined ? ". Ctrl-C detaches." : ". Ctrl-C sends SIGINT to this execution."));
+    notice("Session " + options.reference + (options.interrupt === undefined ? ". Ctrl-C detaches." : ". Ctrl-C stops the session (SIGINT)."));
     if (options.interruptRequested)
       onSigint();
     const result = await runStreamSession({
@@ -25610,15 +25611,15 @@ async function runCloudLaunch(plan, mode) {
   checkArgsForRoute(plan.args);
   const sandbox = plan.sandbox?.trim();
   if (sandbox && plan.preset !== undefined) {
-    throw new MutagentError("INVALID_ARGUMENTS", "--preset cannot select an existing --sandbox.", "Drop --sandbox for automatic placement, or drop --preset to use the existing box.", 2);
+    throw new MutagentError("INVALID_ARGUMENTS", "--preset cannot select an existing --sandbox.", "Drop --sandbox for automatic placement, or drop --preset to use that sandbox.", 2);
   }
   if (sandbox && plan.sandboxProvider !== undefined) {
-    throw new MutagentError("INVALID_ARGUMENTS", "--sandbox-provider cannot select an existing --sandbox.", "Drop --sandbox to place a fresh box on the named provider, or drop --sandbox-provider to use the existing box.", 2);
+    throw new MutagentError("INVALID_ARGUMENTS", "--sandbox-provider cannot select an existing --sandbox.", "Drop --sandbox to start a new sandbox on that sandbox provider, or drop --sandbox-provider to use that sandbox.", 2);
   }
   const args = plan.args;
   const body = {
     arm: plan.arm,
-    mode: mode === "rpc" ? "rpc" : "oneshot",
+    mode: mode === "rpc" ? "interactive" : "headless",
     ...args.length === 0 ? {} : { args },
     ...plan.environment === undefined ? {} : { environment: plan.environment },
     ...plan.cwd === undefined ? {} : { cwd: plan.cwd }
@@ -25635,10 +25636,10 @@ async function runCloudLaunch(plan, mode) {
       ...plan.sandboxProvider === undefined ? {} : { sandboxProvider: plan.sandboxProvider }
     });
     if (!session.reference) {
-      throw new MutagentError("INVALID_RESPONSE", "The server started a session without a live execution reference.", "Check that the server supports the Helix session API before launching again.", 1);
+      throw new MutagentError("INVALID_RESPONSE", "The server did not return a session reference.", "Run: mutagent helix doctor", 1);
     }
     if (session.arm !== plan.arm || session.mode !== body.mode) {
-      throw new MutagentError("INVALID_RESPONSE", "The server started a different harness arm or I/O mode.", "Inspect live session " + session.reference + " before retrying; it may still be running.", 1);
+      throw new MutagentError("INVALID_RESPONSE", "The server started the session with a different arm or mode than requested.", "Session " + session.reference + " may still be running. Check: mutagent helix session ls", 1);
     }
     process.removeListener("SIGINT", queueInterrupt);
     await attachLaunched({ reference: session.reference, sessionId: session.sessionId }, mode === "rpc", interruptRequested);
@@ -25665,16 +25666,15 @@ async function runManagedAgentLaunch(launch, write = (line) => {
       ...launch.sandboxProvider === undefined ? {} : { sandboxProvider: launch.sandboxProvider }
     });
     if (!session.reference || session.agent === undefined) {
-      throw new MutagentError("INVALID_RESPONSE", "The server did not return a managed agent session with a live execution reference.", "Check that the server supports managed agents (mutagent agent --help) before running again.", 1);
+      throw new MutagentError("INVALID_RESPONSE", "The server did not return a session reference for the managed agent run.", "Check that the server supports managed agents (mutagent agent --help) before running again.", 1);
     }
     if (session.arm !== "agent" || plan.mode !== undefined && session.mode !== plan.mode) {
-      throw new MutagentError("INVALID_RESPONSE", "The server started a different harness arm or I/O mode.", "Inspect live session " + session.reference + " before retrying; it may still be running.", 1);
+      throw new MutagentError("INVALID_RESPONSE", "The server started the session with a different arm or mode than requested.", "Session " + session.reference + " may still be running. Check: mutagent helix session ls", 1);
     }
-    const mode = session.mode === "rpc" ? "interactive" : "headless";
-    write("[mutagent] " + JSON.stringify({ reference: session.reference, sandboxId: session.sandboxId, agent: session.agent, mode }) + `
+    write("[mutagent] " + JSON.stringify({ reference: session.reference, sandboxId: session.sandboxId, agent: session.agent, mode: session.mode }) + `
 `);
     process.removeListener("SIGINT", queueInterrupt);
-    await attachLaunched(session, session.mode === "rpc", interruptRequested);
+    await attachLaunched(session, session.mode === "interactive", interruptRequested);
     return session;
   } finally {
     process.removeListener("SIGINT", queueInterrupt);
@@ -25749,14 +25749,14 @@ function planManagedAgentRun(argv, flags) {
     throw usage("-p runs headless and --rpc runs interactive, so pass one of them", `Run: ${example}  or  mutagent helix agent @${address.slug} --rpc`);
   }
   if (task !== undefined)
-    return { address, mode: "oneshot", task };
+    return { address, mode: "headless", task };
   if (flags.rpc === true)
-    return { address, mode: "rpc" };
+    return { address, mode: "interactive" };
   return { address };
 }
 
 // src/commands/helix/agent.ts
-var MISSING_TASK_MESSAGE = 'cloud runs are non-interactive: pass the task with -p "<task>"';
+var MISSING_TASK_MESSAGE = 'a cloud run needs a task: pass -p "<task>", or --rpc for an interactive session';
 function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
   const jsonSource = registration?.jsonSource ?? parent;
   parent.command("agent").description("Run a Helix agent in the cloud, or a managed agent by @slug").argument("[argv...]", "Agent definition, then the task and Helix flags; or @slug[:vN|:latest] for a managed agent").allowUnknownOption(true).allowExcessArguments(true).option("--sandbox <id>", "(internal) Run in an existing sandbox, by sandbox id").option("--preset <name>", "Sandbox preset (not with --sandbox)").option("--sandbox-provider <name>", "Run on this configured sandbox provider").option("--env <name>", "Workspace Environment to load for this run (see mutagent env ls)").option("--rpc", "Read JSON commands on stdin; write events on stdout").option("--cwd <path>", "Working directory in the sandbox").addHelpText("after", [
@@ -25791,12 +25791,12 @@ function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
     "  With --mode rpc, closing stdin ends the session's input; a dropped connection only detaches.",
     "  Output is Helix's own, even with --json.",
     "  Ctrl-C on a native launch sends SIGINT to the session, which stops it; the exit status is reported.",
-    "  A sandbox idle for 15 minutes is checkpointed and stopped.",
+    "  A sandbox idle for 15 minutes is stopped; an interactive session in it is checkpointed first.",
     "",
     "AI Agent Directive:",
     '  For a managed agent, run mutagent helix agent @slug --env <slot> -p "<task>" and keep the',
     "  reference from the stderr receipt; session attach, send and signal take it.",
-    "  Preserve the definition/task distinction and select an explicit headless mode.",
+    "  Keep the definition and the task separate, and pass -p, --mode json or --mode rpc explicitly.",
     "  Local paths that cannot travel are refused; read the recovery message."
   ].join(`
 `)).action(async (argv, options) => {
@@ -25876,7 +25876,7 @@ function withPlannedFlags(options, own) {
 init_errors();
 var LAUNCHER_OWN_FLAGS = ["--sandbox", "--preset", "--sandbox-provider", "--cwd", "--env", "--rpc"];
 function rejection2(token, reason, alternative) {
-  return new MutagentError("NOT_SUPPORTED", `${token} cannot cross to a cloud sandbox: ${reason}`, alternative, 2);
+  return new MutagentError("NOT_SUPPORTED", `${token} is not supported in a cloud run: ${reason}`, alternative, 2);
 }
 function planLauncherArgv(argv, deps = defaultPlanDeps()) {
   let arm = "classic";
@@ -25941,7 +25941,7 @@ function planLauncherArgv(argv, deps = defaultPlanDeps()) {
         continue;
       }
       if (token.startsWith("@")) {
-        throw rejection2(redactToken(token), "an @file argument is read from the machine the harness runs on, and the box has no copy of it", "Inline the file’s contents into the task, or `mutagent sandbox exec` it into a box you kept. File upload does not exist yet.");
+        throw rejection2(redactToken(token), "an @file argument is read from the machine the harness runs on, and the sandbox has no copy of it", "Inline the file’s contents into the task, or `mutagent sandbox exec` it into a sandbox you kept. File upload does not exist yet.");
       }
       if (token.startsWith("--")) {
         forwardFlag(token);
@@ -25953,7 +25953,7 @@ function planLauncherArgv(argv, deps = defaultPlanDeps()) {
         continue;
       }
       if (token.startsWith("-")) {
-        throw rejection2(redactToken(token), "the harness rejects unknown short options outright, so forwarding it would fail inside the box instead of here", "Check the spelling against `helix --help`, or use the long form.");
+        throw rejection2(redactToken(token), "the harness rejects unknown short options outright, so forwarding it would fail inside the sandbox instead of here", "Check the spelling against `helix --help`, or use the long form.");
       }
       task ??= token;
       messages.push(token);
@@ -26638,7 +26638,7 @@ Types:
 --line sends one JSON object as written, for a command the four types do not
 cover. It cannot be combined with --type or a message.
 
-Only rpc sessions (started with --mode rpc or --rpc) accept input, and a session
+Only interactive sessions (started with --mode rpc or --rpc) accept input, and a session
 that has ended refuses it; 'mutagent helix session ls' shows which are live.
 With a sandbox id and --session, if the sandbox is being stopped for idling, send
 waits the time the server asks and retries once. If the session's sandbox was stopped for idling,
@@ -26662,7 +26662,7 @@ AI Agent Directive:
         const built2 = buildLine(messageParts.join(" ").trim(), options);
         const result2 = await sendHelixInput(id, built2.line);
         if (!result2.accepted) {
-          throw new MutagentError("RPC_INPUT_REJECTED", "The session did not accept the command.", "Inspect the live execution before retrying; no reply is promised.", 1);
+          throw new MutagentError("RPC_INPUT_REJECTED", "The session did not accept the command.", "Check the session: mutagent helix session ls", 1);
         }
         if (isJson)
           output.output({ success: result2.accepted, reference: id, ...built2, ...result2, _links: { api: liveSessionPath(id) } });
@@ -26777,7 +26777,7 @@ when the agent has stopped reading its input.
 Exits non-zero if the session had already ended.
 The sandbox is not deleted: its files and event log stay, and
 'mutagent helix session attach <reference>' shows what the session did. A sandbox
-idle for 15 minutes is checkpointed and stopped.
+idle for 15 minutes is stopped; an interactive session in it is checkpointed first.
 
 AI Agent Directive:
   --json returns ONE object: { success, reference, signal, signalled, _links }.
@@ -26792,7 +26792,7 @@ AI Agent Directive:
         const signal2 = resolveSignal(options.type);
         const result2 = await signalHelixSession(id, signal2);
         if (!result2.signalled) {
-          throw new MutagentError("SESSION_SIGNAL_REJECTED", "The session was not signalled.", "Inspect the live execution before retrying.", 1);
+          throw new MutagentError("SESSION_SIGNAL_REJECTED", "The session was not signalled.", "Check the session: mutagent helix session ls", 1);
         }
         if (isJson)
           output.output({ success: result2.signalled, reference: id, signal: signal2, ...result2, _links: { api: liveSessionPath(id) } });
@@ -26853,7 +26853,7 @@ A session reference (hs1_...) is printed when a run starts and listed by 'sessio
 attach, send, signal, close-input, checkpoint, checkpoints and restore take it.
 start and 'ls <sandbox-id>' are internal and take a sandbox id.
 checkpoint saves a session's conversation; restore continues it in a rebuilt sandbox.
-A sandbox idle for 15 minutes is checkpointed and stopped; restore rebuilds it.
+A sandbox idle for 15 minutes is stopped; an interactive session in it is checkpointed first.
 
 AI Agent Directive:
   Start work with 'mutagent helix --mode rpc' and keep the session reference it
@@ -26885,7 +26885,7 @@ function withSessionFlags(options, own) {
   };
 }
 function registerStart(session, root) {
-  session.command("start").description("(internal) Start a Helix session in an existing sandbox, by sandbox id").argument("<sandbox-id>", "Sandbox to start the session in").argument("[args...]", "Helix flags (put -- before them)").allowUnknownOption(true).allowExcessArguments(true).option("--rpc", "Keep the session open for 'session send' (default: run once and end)").option("--cwd <path>", "Working directory (default: $HOME for an rpc session)").option("--env <name>", "Workspace Environment to load (see mutagent env ls)").addHelpText("after", `
+  session.command("start").description("(internal) Start a Helix session in an existing sandbox, by sandbox id").argument("<sandbox-id>", "Sandbox to start the session in").argument("[args...]", "Helix flags (put -- before them)").allowUnknownOption(true).allowExcessArguments(true).option("--rpc", "Start an interactive session that accepts 'session send' (default: headless, runs once and ends)").option("--cwd <path>", "Working directory (default: $HOME for an interactive session)").option("--env <name>", "Workspace Environment to load (see mutagent env ls)").addHelpText("after", `
 Examples:
   ${chalk27.dim("$")} mutagent helix session start sbx_123 --rpc
   ${chalk27.dim("$")} mutagent helix session start sbx_123 --rpc --env staging
@@ -26894,7 +26894,7 @@ Examples:
 
 Prints the session id. Address the session as <sandbox-id> --session <session-id>
 for send, signal and checkpoint, and watch it with 'mutagent sandbox attach <sandbox-id>'.
-Only an --rpc session accepts 'session send'; a one-shot session runs and ends.
+Only an interactive session (--rpc) accepts 'session send'; a headless session runs its task and ends.
 Flags after -- go to Helix. A flag that names a file on this machine is refused,
 because the sandbox cannot read it. A leading positional, --prompt, --file or
 --name is the agent definition, resolved on this machine first.
@@ -26913,7 +26913,7 @@ AI Agent Directive:
         process.stderr.write(`[mutagent] ${notice}
 `);
       const opts = withSessionFlags(options, planned.own);
-      const mode = opts.rpc === true ? "rpc" : "oneshot";
+      const mode = opts.rpc === true ? "interactive" : "headless";
       const args = planned.args;
       const result = await startSession(id, {
         mode,
@@ -26933,8 +26933,8 @@ AI Agent Directive:
           ...opts.env === undefined ? {} : { environment: opts.env },
           _links: sandboxLinks(id),
           _directive: {
-            instruction: mode === "rpc" ? "The session is live and reading its stdin. Attach to watch it; send to steer it." : "The session takes one turn and ends. Attach to watch it; it does not accept input.",
-            next: mode === "rpc" ? [
+            instruction: mode === "interactive" ? "The session is live and reading its stdin. Attach to watch it; send to steer it." : "The session runs its task to completion and ends. Attach to watch it; it does not accept input.",
+            next: mode === "interactive" ? [
               `mutagent sandbox attach ${id} --json`,
               `mutagent helix session send ${id} --session ${sessionId} "<message>" --json`
             ] : [`mutagent sandbox attach ${id} --json`]
@@ -26944,7 +26944,7 @@ AI Agent Directive:
       }
       output.success(`Session ${sessionId} started in ${id} (${mode})`);
       console.error(chalk27.dim(`  Watch it:   mutagent sandbox attach ${id}`));
-      if (mode === "rpc") {
+      if (mode === "interactive") {
         console.error(chalk27.dim(`  Talk to it: mutagent helix session send ${id} --session ${sessionId} "<message>"`));
       }
     } catch (error3) {
@@ -26965,7 +26965,7 @@ Examples:
 
 Every session in the workspace, live and ended, newest activity first.
 STATUS is live (running now), ended (finished; exitCode in --json), stopped-for-idling
-(its sandbox was idle for 15 minutes, then checkpointed and stopped) or restored
+(its sandbox was idle for 15 minutes and was stopped) or restored
 (running in a sandbox rebuilt from a checkpoint). AGENT is slug:vN for a session
 run from a managed agent (mutagent helix agent @slug) and blank otherwise. MODE is
 interactive or headless. ARM and MODE are blank for sessions older than those fields.
@@ -27000,7 +27000,7 @@ AI Agent Directive:
       if (isJson) {
         output.output({
           workspaceId,
-          sessions: sessions.map((row) => row.mode === undefined ? row : { ...row, mode: publicMode(row.mode) }),
+          sessions,
           count: sessions.length,
           ...nextCursor === undefined ? {} : { nextCursor }
         });
@@ -27009,7 +27009,7 @@ AI Agent Directive:
       if (sessions.length === 0) {
         console.log(chalk27.gray("No Helix sessions in this workspace yet."));
         console.log("");
-        console.log('  Launch one: mutagent helix launch --task "..."  (or session start <box>)');
+        console.log('  Start one: mutagent helix -p "<task>"  or  mutagent helix --rpc');
         return;
       }
       output.output(sessions.map((s) => ({
@@ -27017,7 +27017,7 @@ AI Agent Directive:
         SANDBOX: s.sandboxId,
         AGENT: s.agent ?? "",
         ARM: s.arm ?? "",
-        MODE: publicMode(s.mode),
+        MODE: s.mode ?? "",
         STATUS: s.status,
         "LAST ACTIVITY": s.lastActivityAt
       })));
@@ -27121,18 +27121,13 @@ function requireSession(raw, example) {
     return sessionId;
   throw new MutagentError("MISSING_ARGUMENTS", "--session is required — a sandbox can hold more than one session.", `Run: ${example} --session <session-id>`, 2);
 }
-function publicMode(mode) {
-  if (mode === undefined)
-    return "";
-  return mode === "rpc" ? "interactive" : "headless";
-}
 
 // src/commands/helix/models.ts
 import chalk28 from "chalk";
 init_errors();
 function printView(view, output) {
   if (view.models.length === 0) {
-    console.log(chalk28.gray("No Helix Cloud models: this workspace has no active LLM provider the box can use."));
+    console.log(chalk28.gray("No Helix Cloud models: this workspace has no active LLM provider that Helix can use."));
     console.log("");
     console.log("  Add one: mutagent providers add --provider <id> --name <name> --api-key <key>");
   } else {
@@ -27145,7 +27140,7 @@ function printView(view, output) {
     console.log(view.default === null ? chalk28.yellow("No default set — a run without --model answers 428. Set one: mutagent helix models default <provider/model>") : `Default: ${view.default}`);
   }
   if (view.unmapped.length > 0) {
-    console.log(chalk28.yellow(`Not usable in a box (no harness credential mapping): ${view.unmapped.join(", ")}`));
+    console.log(chalk28.yellow(`Not usable by Helix Cloud (Helix cannot load this LLM provider's key): ${view.unmapped.join(", ")}`));
   }
 }
 function registerModelsCommand(helix) {
@@ -27428,9 +27423,10 @@ function createHelixCommand() {
     "Each run prints its session reference (hs1_...) on stderr. Use it with",
     "mutagent helix session attach, send, signal and checkpoint.",
     "Ctrl-C sends SIGINT to the session, which stops it; the exit status is reported.",
-    "There is no interactive chat UI: choose -p, --mode json or --mode rpc.",
+    "There is no terminal chat UI: choose -p, --mode json or --mode rpc.",
     "With --mode rpc, closing stdin ends the session's input; a dropped connection only detaches.",
-    "A sandbox idle for 15 minutes is checkpointed and stopped; mutagent helix session restore rebuilds it.",
+    "A sandbox idle for 15 minutes is stopped; an interactive session in it is checkpointed first.",
+    "mutagent helix session restore continues a checkpointed session in a new sandbox.",
     "",
     "AI Agent Directive:",
     "  Choose -p, --mode json or --mode rpc explicitly.",
@@ -27564,7 +27560,7 @@ function resolveNetwork(requested, rules) {
   }
   const policy2 = requested.trim();
   if (!EGRESS_POLICIES.includes(policy2)) {
-    throw new MutagentError("INVALID_ARGUMENTS", `--egress must be one of ${EGRESS_POLICIES.join(", ")}, got "${requested}".`, "Use --egress allow to drive a Helix session; the default, deny, leaves the box with no network at all.");
+    throw new MutagentError("INVALID_ARGUMENTS", `--egress must be one of ${EGRESS_POLICIES.join(", ")}, got "${requested}".`, "Use --egress allow to drive a Helix session; the default, deny, leaves the sandbox without network access.");
   }
   if (policy2 !== "allowlist") {
     if (rules.length > 0) {
@@ -27676,7 +27672,7 @@ command and is removed unless --keep. With --sandbox, output streams as it is pr
 --preset and --keep are refused there. The sandbox command's exit code is this command's.
 
 AI Agent Directive:
-  Use --no-stream --json (or the one-shot form, which is always blocking) for a
+  Use --no-stream --json (or the single-command form, which is always blocking) for a
   result you intend to parse: one object, no NDJSON to reassemble.
   Run 'mutagent sandbox ls --json' first to confirm a --sandbox id is running.
       `).action(async (argv, options) => {
@@ -27741,7 +27737,7 @@ function rejectOneShotOnlyFlags(options) {
     offenders.push("--keep");
   if (offenders.length === 0)
     return;
-  throw new MutagentError("INVALID_ARGUMENTS", `${offenders.join(" and ")} ${offenders.length === 1 ? "applies" : "apply"} only to a fresh sandbox, but --sandbox names an existing one.`, "Drop --sandbox to run one-shot in a fresh box, or drop these flags to run in the existing one.");
+  throw new MutagentError("INVALID_ARGUMENTS", `${offenders.join(" and ")} ${offenders.length === 1 ? "applies" : "apply"} only to a fresh sandbox, but --sandbox names an existing one.`, "Drop --sandbox to run the command in a new sandbox, or drop these flags to run in the existing one.");
 }
 function createExecOpener(id, body) {
   let submitted = false;
@@ -28155,15 +28151,15 @@ Examples:
   ${chalk35.dim("$")} mutagent sandbox traces sbx_1
   ${chalk35.dim("$")} mutagent sandbox rm sbx_1 --force
 
-One-shot vs persistent:
+Single command vs kept sandbox:
   ${chalk35.bold("exec")} without --sandbox starts a fresh sandbox from a preset, runs one command
   and removes the sandbox. ${chalk35.bold("spawn")} starts a sandbox from an image and leaves it running
   for ${chalk35.bold("attach")} and ${chalk35.bold("exec --sandbox")}.
 
 Lifecycle:
   Ctrl-C, a dropped connection or a closed terminal detaches; the sandbox keeps running.
-  After 15 minutes with no input, attach, exec or agent turn, the server checkpoints
-  and stops it. A Helix session in it can be rebuilt with
+  After 15 minutes with no input, attach, exec or agent turn, the server stops it;
+  an interactive Helix session in it is checkpointed first and can be restored with
   \`mutagent helix session restore <reference>\`. \`sandbox rm\` destroys a sandbox now.
 
 Output:
@@ -28400,8 +28396,8 @@ Examples:
 Entries you name are set and the rest stay; the Environment is created if missing.
 --replace removes every entry you do not name, secrets included.
 Positional KEY=VALUE and --from-file are variables; --secret and --secrets-from-file are
-secrets (encrypted at rest, never returned). Both reach the box as env vars. A name
-cannot be both.
+secrets (encrypted at rest, never returned). Both are set as environment variables in
+the sandbox. A name cannot be both.
 --secret takes every KEY=VALUE after it, so put variables first:
   ${chalk36.dim("$")} mutagent env set demo A=1 --secret TOKEN=x
 A value may contain '=': TOKEN=a=b stores "a=b".
@@ -28476,8 +28472,8 @@ Examples:
   ${chalk36.dim("$")} mutagent env rm demo --force
   ${chalk36.dim("$")} mutagent env rm demo --json
 
-Deletes the Environment and its encrypted secrets. Boxes already running keep what
-they were handed; the next run naming this Environment fails.
+Deletes the Environment and its encrypted secrets. Sandboxes already running keep the
+values they were given; the next run naming this Environment fails.
 Without --force (and without --json) the command refuses; it never prompts.
 An unknown name is an error.
 
@@ -28708,8 +28704,8 @@ function helixKeyRefusal() {
 To pass the Mutagent platform key instead, put it before the command (mutagent --api-key <mutagent-key> helix …) or export MUTAGENT_API_KEY.`, 2);
 }
 function sandboxExecKeyRefusal() {
-  return new MutagentError("NOT_SUPPORTED", "--api-key after 'mutagent sandbox exec' and before a -- is refused: it reads as a flag of the command in the box, but the mutagent CLI would take it as its own platform key and send it to the Mutagent platform.", `${keyAlternative()}
-Arguments for the command in the box go after --: mutagent sandbox exec --sandbox <id> -- <command> [args…].
+  return new MutagentError("NOT_SUPPORTED", "--api-key after 'mutagent sandbox exec' and before a -- is refused: it reads as a flag of the command in the sandbox, but the mutagent CLI would take it as its own platform key and send it to the Mutagent platform.", `${keyAlternative()}
+Arguments for the command in the sandbox go after --: mutagent sandbox exec --sandbox <id> -- <command> [args…].
 To pass the Mutagent platform key instead, put it before the command (mutagent --api-key <mutagent-key> sandbox exec …) or export MUTAGENT_API_KEY.`, 2);
 }
 function rootValueOptionRefusal(option, label) {
@@ -29241,4 +29237,4 @@ if (isAgentInvocation(rawArgs)) {
   program.parse(argvForCommander, { from: "user" });
 }
 
-//# debugId=093DD78045AEB58864756E2164756E21
+//# debugId=EBAEE05DDF8C12AA64756E2164756E21

package/dist/index.js

@@ -708,7 +708,7 @@ var init_sdk_debug = __esm(() => {
 });
 
 // src/lib/sdk-mappers.ts
-import { Provider as SDKProviderEnum } from "@mutagent/sdk/models";
+import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value) {
   return PROVIDER_TYPES.includes(value);
 }
@@ -1021,7 +1021,7 @@ class SDKClientWrapper {
   }
   async listProviders(filters) {
     try {
-      const response = await this.sdk.providerConfigs.listProviders({
+      const response = await this.sdk.llmProviders.listProviderConfigs({
         provider: filters?.type,
         includeInactive: true
       });
@@ -1039,7 +1039,7 @@ class SDKClientWrapper {
   }
   async getProvider(id) {
     try {
-      const response = await this.sdk.providerConfigs.getProvider({
+      const response = await this.sdk.llmProviders.getProviderConfig({
         id
       });
       return toProvider(response);
@@ -1115,7 +1115,7 @@ class SDKClientWrapper {
   }
   async testProvider(id) {
     try {
-      const response = await this.sdk.providerConfigs.testProvider({
+      const response = await this.sdk.llmProviders.testProviderConfig({
         id
       });
       return toProviderTestResult(response);
@@ -1161,7 +1161,7 @@ class SDKClientWrapper {
         });
         return scrubKnownSuccessDeep({ ...response2, workspaceId });
       }
-      const response = await this.sdk.providerConfigs.updateProvider({
+      const response = await this.sdk.llmProviders.updateProviderConfig({
         id,
         body: {
           name: data.name,
@@ -1180,7 +1180,7 @@ class SDKClientWrapper {
   async deleteProvider(id) {
     const workspaceId = this.requireUnambiguousWorkspace();
     try {
-      await this.sdk.providerConfigs.deleteProvider({ id });
+      await this.sdk.llmProviders.deleteProviderConfig({ id });
       return { workspaceId };
     } catch (error) {
       this.handleError(error);
@@ -1480,4 +1480,4 @@ export {
   ApiError
 };
 
-//# debugId=F50D31F7C1A84A2764756E2164756E21
+//# debugId=0E9FCC198FD63F3C64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.1.351",
+  "version": "0.1.353",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
-    "@mutagent/sdk": "0.5.11",
+    "@mutagent/sdk": "0.6.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "cosmiconfig": "^9.0.0",