loom-agent 1.2.37 → 1.3.3

package/src/providers/openai-compat.js

@@ -9,12 +9,17 @@ function formatMessages(messages, options) {
   for (const m of messages) {
     if (m.role === 'system') continue;
     if (m.role === 'tool') {
-      out.push({ role: 'tool', tool_call_id: m.toolCallId, content: String(m.content) });
+      // A tool row without its id would be rejected by the API ("missing
+      // field tool_call_id" — NVIDIA is strict about this). Skip orphans
+      // from hand-edited/resumed sessions instead of failing the turn.
+      const tcid = m.toolCallId || m.tool_call_id;
+      if (tcid) out.push({ role: 'tool', tool_call_id: tcid, content: String(m.content) });
       continue;
     }
     const msg = { role: m.role, content: m.content || '' };
-    if (m.toolCalls && m.toolCalls.length) {
-      msg.tool_calls = m.toolCalls.map(tc => ({
+    const calls = m.toolCalls || m.tool_calls;
+    if (calls && calls.length) {
+      msg.tool_calls = calls.map(tc => ({
         id: tc.id,
         type: 'function',
         function: { name: tc.name, arguments: typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input || {}) },
@@ -80,6 +85,7 @@ function normalize(resp) {
     content: message.content || '',
     toolCalls,
     usage: resp.usage,
+    finishReason: choice?.finish_reason || undefined,
   };
 }
 
@@ -208,10 +214,12 @@ function createOpenAICompatProvider({ getKey, providerId, envKeyHint, clientFact
       let content = '';
       let reasoning = '';
       let usage = null;
+      let finishReason = null;
       const toolAcc = new Map();
 
       for await (const chunk of s) {
         if (chunk.usage) usage = chunk.usage;
+        if (chunk.choices?.[0]?.finish_reason) finishReason = chunk.choices[0].finish_reason;
         const delta = chunk.choices?.[0]?.delta || {};
         // DeepSeek-style reasoning_content / OpenRouter reasoning deltas.
         const rt = delta.reasoning_content || delta.reasoning;
@@ -243,7 +251,7 @@ function createOpenAICompatProvider({ getKey, providerId, envKeyHint, clientFact
         toolCalls.push({ id: acc.id, name: acc.name, input });
       }
 
-      return { content, reasoning, toolCalls, usage };
+      return { content, reasoning, toolCalls, usage, finishReason: finishReason || undefined };
     } catch (err) {
       if (isAbortError(err)) throw err;
       throw wrapErr(err, options.model || '?', envKeyHint, getBaseUrl(providerId));

package/src/tools/index.js

@@ -186,7 +186,7 @@ const TOOLS = {
   },
   bash: {
     name: 'bash',
-    description: 'Execute a shell command.',
+    description: 'Execute a shell command on the user\'s machine.',
     parameters: {
       command: { type: 'string', required: true, description: 'The command to execute' },
       workdir: { type: 'string', required: false, description: 'Working directory' },
@@ -265,6 +265,32 @@ const TOOLS = {
       });
     }
   },
+  sandbox: {
+    name: 'sandbox',
+    description: 'Run a shell command INSIDE the Docker sandbox (isolated Linux container, project mounted at /workspace). Use ONLY when isolation is needed: the user asked for the sandbox, the command is risky (installs, deletions, untrusted scripts), or a Linux-only environment is required. For ordinary commands use bash (host). One command per call; the container idles in the background between calls.',
+    parameters: {
+      command: { type: 'string', required: true, description: 'The Linux shell command to run inside the container' },
+      workdir: { type: 'string', required: false, description: 'Working directory inside the container (host paths under the project map to /workspace/...)' },
+      timeoutMs: { type: 'number', required: false, description: 'Kill the command after this many ms (default 120000)' },
+    },
+    async execute(params, ctx) {
+      // Opt-in isolation path: nothing is routed here automatically. The
+      // container is revived/re-mounted on demand, then torn back to idle.
+      const sandbox = require('../core/sandbox');
+      const risk = params._approved ? null : commandRiskLabel(params.command);
+      if (risk) return { error: `Blocked by safety filter: ${risk}. Approve it via the permission prompt to run it anyway.` };
+      const stream = ctx && typeof ctx.stream === 'function' ? ctx.stream : null;
+      const res = await sandbox.runInSandbox(params.command, {
+        workdir: params.workdir || cwd,
+        timeoutMs: typeof params.timeoutMs === 'number' && params.timeoutMs > 0 ? params.timeoutMs : undefined,
+        onChunk: stream ? (text, which) => stream(text, which) : undefined,
+      });
+      if ('error' in res) return { error: res.error };
+      let out = res.output;
+      if (res.code !== 0) out += `\n[exit code: ${res.code}]`;
+      return out || 'command completed';
+    }
+  },
   grep: {
     name: 'grep',
     description: 'Search file contents using regular expressions.',

package/src/tui/App.tsx

@@ -52,7 +52,7 @@ import { prettyToolName, stripAnsi } from "./toolname.ts";
 import { toolDisplay } from "./tool-display.ts";
 import {
   ProviderPicker, SelectModal, InputModal, SettingsModal,
-  PaletteModal, McpModal, ConnectorsModal, GraphModal,
+  PaletteModal, McpModal, ConnectorsModal, GraphModal, SandboxModal,
   openModelPicker, openKeyModal, openBaseUrlEditor,
   showProvidersText, showHelpText, showAgentsText,
   openGraphModal,
@@ -65,6 +65,7 @@ import { snapshotBefore, snapshotAfter, snapshotBashBefore, diffBashAfter, clear
 import { createRestorePoint, listRestorePoints, restoreTo } from "../core/restore.js";
 import { PROVIDERS, PROVIDER_ORDER, PROVIDER_LABELS } from "../providers/index.js";
 import * as plugin from "../core/plugin-cmd.js";
+import * as sandbox from "../core/sandbox.js";
 import { on } from "../core/events.js";
 import { listSkills } from "../skills/skills-manager.js";
 
@@ -117,14 +118,15 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
     if (text.startsWith("/")) {
       var q = text.slice(1).toLowerCase();
       var hits = SLASH_LIST.filter(function(c) { return c.cmd.startsWith(q); }).map(function(c) {
-        var s: Suggestion = { label: "/" + c.cmd, desc: c.desc + (c.args ? " \u2014 " + c.args : "") };
+        // Popup stays terse: short desc only — syntax lives in /help (args).
+        var s: Suggestion = { label: "/" + c.cmd, desc: c.desc };
         return s;
       });
       // Custom commands (.loom/commands/*.md) join the picker after built-ins.
       try {
         const { listCustomCommands } = require("../core/custom-commands.js");
         for (const cc of listCustomCommands()) {
-          if (cc.name.toLowerCase().startsWith(q)) hits.push({ label: "/" + cc.name, desc: "custom command \u2014 " + cc.file });
+          if (cc.name.toLowerCase().startsWith(q)) hits.push({ label: "/" + cc.name, desc: "custom command" });
         }
       } catch {}
       setSuggestions(hits); setAutoKind("slash"); setAutoIndex(0);
@@ -163,6 +165,25 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
     if (raw.startsWith("/")) { recordPrompt(raw); setDraft(""); processSlash(raw); return; }
     if (raw.startsWith("!")) { recordPrompt(raw); setDraft(""); appendMessage({ role: "user", content: raw }); appendMessage({ role: "system", content: runShell(raw.slice(1)) }); return; }
 
+    // Docker-install resume: while an install is pending, "docker is ready"
+    // continues the sandbox setup in THIS session instead of going to the
+    // model. Outside the pending flow the phrase is ordinary conversation.
+    if (sandbox.isReadySignal(raw)) {
+      var st0 = sandbox.sandboxStatus();
+      if (st0.pending || st0.docker === "ready" && st0.container === "absent" && /set ?up|build|create|make/i.test(raw)) {
+        recordPrompt(raw); setDraft("");
+        appendMessage({ role: "user", content: raw });
+        if (st0.docker === "ready" || st0.docker === "no_daemon") {
+          appendMessage({ role: "system", content: "Docker detected \u2014 pick an OS to finish the sandbox setup." });
+          openModal({ type: "sandbox" });
+        } else {
+          sandbox.markInstallPending();
+          appendMessage({ role: "system", content: sandbox.installGuide() });
+        }
+        return;
+      }
+    }
+
     // "@agent …" delegates the whole turn to that subagent (same as the model
     // calling the task tool — but explicit). "@file …" still inlines the file.
     var agentId: string | null = null;
@@ -588,7 +609,15 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
     getSession().conversationId = id;
     var pendingParts: Record<string, any> = {};
     getSession().messages = data.messages.map(function(m) {
-      var clean: any = { role: m.role, content: m.content, toolCalls: m.toolCalls };
+      // toolCallId MUST survive the resume: the provider wire format sends it
+      // as tool_call_id / tool_use_id — dropping it makes the next turn fail
+      // with "400: missing field tool_call_id" (NVIDIA) after a resume.
+      var clean: any = {
+        role: m.role,
+        content: m.content,
+        toolCalls: m.toolCalls || (m as any).tool_calls,
+        toolCallId: m.toolCallId || (m as any).tool_call_id,
+      };
       if (m.reasoning) clean.reasoning = m.reasoning;
       return clean;
     });
@@ -1058,6 +1087,46 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
         openModal({ type: "connectors" });
         return;
       }
+      case "sandbox": {
+        var ssub = args[0];
+        var st = sandbox.sandboxStatus();
+        // The setup wizard is a modal: docker check (with download link) →
+        // OS pick → live build. Bare /sandbox and /sandbox setup open it.
+        if (!ssub || ssub === "setup" || ssub === "os") { openModal({ type: "sandbox" }); return; }
+        if (ssub === "guide") { appendMessage({ role: "system", content: sandbox.installGuide() }); return; }
+        if (ssub === "off") {
+          sandbox.setSandboxEnabled(false);
+          appendMessage({ role: "system", content: "Sandbox off — the sandbox tool is disabled; the agent works on your machine as usual. The container is kept (run /sandbox on to re-enable, /sandbox rm to delete it)." });
+          return;
+        }
+        if (ssub === "on") {
+          if (st.container !== "running") { appendMessage({ role: "system", content: "Sandbox container is not running. Run /sandbox setup first." }); return; }
+          sandbox.setSandboxEnabled(true);
+          appendMessage({ role: "system", content: "Sandbox on — the agent can use the sandbox tool for isolated commands inside " + sandbox.CONTAINER + " when needed. Everything else stays on your machine." });
+          return;
+        }
+        if (ssub === "rm") {
+          try {
+            require("child_process").execFileSync("docker", ["rm", "-f", sandbox.CONTAINER], { windowsHide: true, timeout: 30000, stdio: "ignore" });
+            sandbox.setSandboxEnabled(false);
+            appendMessage({ role: "system", content: "Sandbox container removed. Run /sandbox setup to rebuild it." });
+          } catch { appendMessage({ role: "system", content: "No sandbox container to remove." }); }
+          return;
+        }
+        if (ssub === "status") {
+          var line = "Sandbox: ";
+          if (st.docker === "not_installed") line += "Docker not installed";
+          else if (st.docker === "no_daemon") line += "Docker installed, daemon not running";
+          else line += "Docker " + st.dockerVersion + " \u00b7 container " + st.container + (st.enabled ? " \u00b7 sandbox tool on" : " \u00b7 sandbox tool off");
+          if (st.pending) line += "\nWaiting for you to install Docker \u2014 when it's done say \"docker is ready\" (or run /sandbox).";
+          else if (st.docker === "not_installed") line += "\nRun /sandbox for the setup wizard.";
+          else if (st.container === "absent") line += "\nRun /sandbox to build it.";
+          appendMessage({ role: "system", content: line });
+          return;
+        }
+        appendMessage({ role: "system", content: "Usage: /sandbox (wizard) | status | on | off | rm | guide" });
+        return;
+      }
       case "sessions": {
         const saved = listSessions();
         if (!saved.length) {
@@ -1527,6 +1596,16 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
         if (!autoPerm() && !permission() && !modal()) askSessionPermissions();
       }, 500);
     }
+    // Sandbox install pending from a previous session: remind on start so
+    // the user knows to come back with "docker is ready". Skipped in the
+    // test harness (same flag as the session prompt).
+    try {
+      if (!process.env.LOOM_NO_SESSION_PROMPT && sandbox.sandboxStatus().pending) {
+        setTimeout(function() {
+          appendMessage({ role: "system", content: "Docker sandbox setup is still pending. Install Docker (see /sandbox guide), then say \"docker is ready\" and I'll build it automatically." });
+        }, 800);
+      }
+    } catch {}
     _skillToastOff = on("trigger:skill", function(d: any) {
       const names = (d?.skills || []).join(", ");
       showToast("skill: " + names, "ok", 5000);
@@ -1596,6 +1675,7 @@ export function App(props: { initialPrompt?: string; resumeSession?: string; aut
             {m.type === "palette" ? <PaletteModal onPick={m.onPick} /> : null}
             {m.type === "mcp" ? <McpModal /> : null}
             {m.type === "connectors" ? <ConnectorsModal /> : null}
+            {m.type === "sandbox" ? <SandboxModal /> : null}
             {m.type === "graph" ? <GraphModal graph={m.graph} err={m.graphError} /> : null}
             {m.type === "subagents" ? <SubagentPanel /> : null}
             {m.type === "subagent_detail" ? <SubagentDetailPanel /> : null}

package/src/tui/components/Modals.tsx

@@ -1,5 +1,5 @@
 // Modals -- provider picker, model picker, key input, base URL, settings, palette.
-import { createSignal, createMemo, onMount } from "solid-js";
+import { createSignal, createMemo, onMount, onCleanup } from "solid-js";
 import { useKeyboard, usePaste } from "@opentui/solid";
 import { palette } from "../theme.ts";
 import * as kbs from "../keybinds.ts";
@@ -661,6 +661,225 @@ export function ConnectorsModal() {
   return <ServerBrowser kind="connector" />;
 }
 
+// ── Sandbox setup wizard ──
+// Three steps: docker check (with install link when missing) → OS pick →
+// live setup with a real progress bar (setup streams from the core layer —
+// the TUI never freezes). The container is global and idles in the
+// background; the agent's sandbox tool uses it on demand.
+export function SandboxModal() {
+  const sb = require("../../core/sandbox.js");
+  const [step, setStep] = createSignal<"docker" | "os" | "setup">("docker");
+  const [docker, setDocker] = createSignal(sb.detectDocker());
+  const [osSel, setOsSel] = createSignal(0);
+  const [logs, setLogs] = createSignal<string[]>([]);
+  const [busy, setBusy] = createSignal(false);
+  const [err, setErr] = createSignal<string | null>(null);
+  const [prog, setProg] = createSignal<{ stage: string; pct: number | null; step: number; total: number } | null>(null);
+  const [spin, setSpin] = createSignal(0);
+  let spinTimer: ReturnType<typeof setInterval> | null = null;
+  onCleanup(() => { if (spinTimer) clearInterval(spinTimer); });
+
+  // Spinner frames while setup is busy (drives the "working…" indicator).
+  function startSpinner() {
+    if (spinTimer) clearInterval(spinTimer);
+    spinTimer = setInterval(() => setSpin((s) => (s + 1) % 10), 120);
+  }
+  function stopSpinner() {
+    if (spinTimer) clearInterval(spinTimer);
+    spinTimer = null;
+  }
+  const SPIN_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+
+  const STAGE_LABELS: Record<string, string> = {
+    pull: "Pulling image",
+    create: "Creating container",
+    start: "Starting container",
+    essentials: "Installing essentials",
+    browser: "Installing browser",
+    done: "Ready",
+  };
+
+  // Docker already installed → advance straight to OS selection (with a
+  // brief "installed" flash so the user sees the check happened).
+  onMount(() => {
+    if (docker().state === "ready") {
+      setTimeout(() => { if (step() === "docker") setStep("os"); }, 600);
+    }
+  });
+
+  function recheck() {
+    const d = sb.detectDocker();
+    setDocker(d);
+    if (d.state === "ready") setStep("os");
+  }
+
+  function startSetup() {
+    const os = sb.OS_CATALOG[osSel()];
+    setStep("setup");
+    setBusy(true);
+    setErr(null);
+    setProg(null);
+    startSpinner();
+    setLogs(["Preparing " + os.label + " (" + os.image + ")…"]);
+    sb.setupSandbox({
+      osId: os.id,
+      onLog: (/** @type {string} */ l) => setLogs((xs) => [...xs, l]),
+      onProgress: (/** @type {{ stage: string; pct: number | null; step: number; total: number }} */ p) => setProg(p),
+    }).then((/** @type {{ ok: boolean, error?: string }} */ res) => {
+      setBusy(false);
+      stopSpinner();
+      if (res.ok) {
+        appendMessage({ role: "system", content: "Sandbox is live (" + os.label + "). The container idles in the background; the agent will use it via the sandbox tool whenever isolation is needed. Your project is mounted at /workspace." });
+        showToast("Sandbox ready — " + os.label, "ok");
+        closeModal();
+      } else {
+        setErr(res.error || "setup failed");
+      }
+    });
+  }
+
+  useKeyboard((key) => {
+    const ks = kbs.keyString(key);
+    if (kbs.is("modal_cancel", ks)) { closeModal(); return; }
+    const s = step();
+    if (s === "setup") {
+      // Retry after a failed setup; while busy esc is the only exit.
+      if (!busy() && err() && kbs.dialogIs("dialog_select_submit", ks)) { setErr(null); startSetup(); }
+      return;
+    }
+    if (kbs.dialogIs("dialog_select_prev", ks)) { if (s === "os") setOsSel((i) => Math.max(0, i - 1)); return; }
+    if (kbs.dialogIs("dialog_select_next", ks)) { if (s === "os") setOsSel((i) => Math.min(sb.OS_CATALOG.length - 1, i + 1)); return; }
+    if (kbs.dialogIs("dialog_select_submit", ks)) {
+      if (s === "docker") {
+        if (docker().state === "not_installed") {
+          sb.markInstallPending();
+          sb.openInstallPage();
+          appendMessage({ role: "system", content: "Opened the Docker download page. Install Docker (restart if asked), then run /sandbox again — or just say \"docker is ready\" in chat." });
+          closeModal();
+        } else if (docker().state === "no_daemon") {
+          recheck();
+        } else {
+          setStep("os");
+        }
+        return;
+      }
+      if (s === "os" && !busy()) startSetup();
+      return;
+    }
+  });
+
+  const link = sb.installLink();
+  const st = () => docker().state;
+
+  return (
+    <ModalFrame
+      title="Sandbox Setup"
+      subtitle={
+        step() === "docker" ? "Step 1/3 — Docker check"
+        : step() === "os" ? "Step 2/3 — pick a lightweight OS"
+        : "Step 3/3 — building the sandbox"
+      }
+      footer={
+        step() === "docker"
+          ? (st() === "not_installed" ? "enter open download page · esc close"
+             : st() === "no_daemon" ? "enter re-check · esc close"
+             : "checking…")
+          : step() === "os" ? "up/down pick · enter start setup · esc close"
+          : busy() ? "working… esc to keep running in background"
+          : "enter retry · esc close"
+      }
+    >
+      {step() === "docker" && st() === "not_installed" ? (
+        <box flexDirection="column">
+          <text fg={ui.warning}>Docker is not installed</text>
+          <text fg={ui.fgMuted} marginTop={1}>The sandbox needs Docker once. After that it is permanent.</text>
+          <box flexDirection="column" marginTop={1}>
+            <text fg={ui.fg}>1. Install Docker Desktop (restart if asked)</text>
+            <text fg={ui.primary}>   {link}</text>
+            <text fg={ui.fg}>2. Start it and wait for "running"</text>
+            <text fg={ui.fg}>3. Come back here and press enter</text>
+          </box>
+        </box>
+      ) : null}
+      {step() === "docker" && st() === "no_daemon" ? (
+        <box flexDirection="column">
+          <text fg={ui.warning}>Docker is installed but not running</text>
+          <text fg={ui.fgMuted} marginTop={1}>Start Docker Desktop (or: sudo systemctl start docker), wait for it, then press enter to re-check.</text>
+        </box>
+      ) : null}
+      {step() === "docker" && st() === "ready" ? (
+        <box flexDirection="column">
+          <text fg={ui.success}>Docker installed (v{docker().version})</text>
+          <text fg={ui.fgMuted} marginTop={1}>Opening OS selection…</text>
+        </box>
+      ) : null}
+      {step() === "os" ? (
+        <box flexDirection="column">
+          {sb.OS_CATALOG.map((/** @type {{ id: string, label: string, sizeNote: string, browser: boolean }} */ os, /** @type {number} */ i) => {
+            const active = i === osSel();
+            return (
+              <box
+                key={os.id} flexDirection="row" paddingY={0}
+                backgroundColor={active ? ui.bgPanelAlt : undefined}
+                onMouseDown={() => setOsSel(i)}
+                onMouseUp={() => { if (osSel() === i) startSetup(); }}
+              >
+                <text fg={active ? ui.primary : ui.fgDim}>{active ? "▸ " : "  "}{os.label}</text>
+                <text fg={active ? ui.fg : ui.fgMuted}>{"  " + os.sizeNote}</text>
+                {os.browser ? <text fg={ui.success}>  +browser</text> : null}
+              </box>
+            );
+          })}
+          <text fg={ui.fgMuted} marginTop={1}>All options include git, curl, ripgrep and a shell.</text>
+        </box>
+      ) : null}
+      {step() === "setup" ? (
+        <box flexDirection="column" maxWidth={72}>
+          {/* Stage checklist with a live pull-progress bar (pct from core). */}
+          {prog() ? (() => {
+            const p = prog()!;
+            const os = sb.OS_CATALOG[osSel()];
+            // Same stage order the core reports (browser only when offered).
+            const keys = ["pull", "create", "start", "essentials"]
+              .concat(os.browser ? ["browser"] : [], ["done"])
+              .slice(0, p.total);
+            return (
+              <box flexDirection="column" marginBottom={1}>
+                {keys.map((key, i) => {
+                  const done = i < p.step || p.stage === "done";
+                  const active = i === p.step && p.stage !== "done";
+                  const mark = done ? "✓" : active ? SPIN_FRAMES[spin()] : "○";
+                  const color = done ? ui.success : active ? ui.primary : ui.fgDim;
+                  let bar = "";
+                  if (active && p.pct != null) {
+                    const width = 20;
+                    const filled = Math.round((p.pct / 100) * width);
+                    bar = " [" + "█".repeat(filled) + "░".repeat(width - filled) + "] " + p.pct + "%";
+                  } else if (active) {
+                    bar = " …";
+                  }
+                  return (
+                    <text fg={color}>{mark + " " + STAGE_LABELS[key] + bar}</text>
+                  );
+                })}
+              </box>
+            );
+          })() : <text fg={ui.fgMuted}>Starting…</text>}
+          {logs().slice(-6).map((l) => <text fg={ui.fgMuted}>{"▸ " + l.slice(0, 68)}</text>)}
+          {busy() ? <text fg={ui.primary}>{SPIN_FRAMES[spin()] + " working — you can esc; setup continues in the background"}</text> : null}
+          {err() ? (
+            <box flexDirection="column" marginTop={1}>
+              <text fg={ui.error}>{err()}</text>
+              <text fg={ui.fgMuted}>press enter to retry, esc to close</text>
+            </box>
+          ) : null}
+          {!busy() && !err() ? <text fg={ui.success}>done</text> : null}
+        </box>
+      ) : null}
+    </ModalFrame>
+  );
+}
+
 // Palette modal (ctrl+p) - proper popup window
 export function PaletteModal(props: { onPick: (cmd: string) => void }) {
   const items = SLASH_LIST.map(c => ({ label: "/" + c.cmd, value: c.cmd, sub: c.desc }));

package/src/tui/store.ts

@@ -494,50 +494,51 @@ export function wireTodoEvents() {
 }
 
 // ─── Slash commands (for autocomplete) ───
+// Terse descs only: this list feeds the popup + command palette, so every
+// extra word adds clutter. Syntax lives in `args` and shows up in /help,
+// NOT in the popup. Aliases keep their handlers but stay out of the list:
+//   /model → /models · /thinking + /details → /settings · /rewind → /restore
 export interface SlashCmd { cmd: string; desc: string; args?: string; }
 
 export const SLASH_LIST: SlashCmd[] = [
-  { cmd: "help", desc: "Show help dialog" },
-  { cmd: "agents", desc: "List agents — primaries + subagents (@mention or task tool)" },
-  { cmd: "build", desc: "Build mode — full agent tools (Tab cycles)" },
-  { cmd: "plan", desc: "Plan mode — read-only analysis, no file changes" },
-  { cmd: "chat", desc: "Chat mode — conversation only, no tools" },
-  { cmd: "connect", desc: "Add/connect a provider", args: "[provider]" },
+  { cmd: "help", desc: "Show help" },
+  { cmd: "agents", desc: "List agents" },
+  { cmd: "build", desc: "Build mode — full tools" },
+  { cmd: "plan", desc: "Plan mode — read only" },
+  { cmd: "chat", desc: "Chat mode — no tools" },
+  { cmd: "connect", desc: "Connect a provider" },
   { cmd: "key", desc: "Edit API key" },
-  { cmd: "baseurl", desc: "Set provider base URL", args: "[provider] [url]" },
-  { cmd: "model", desc: "Pick the active model", args: "[model-id]" },
-  { cmd: "models", desc: "Open the model picker (grouped by provider)" },
-  { cmd: "providers", desc: "List supported providers" },
-  { cmd: "status", desc: "Show connection status" },
-  { cmd: "usage", desc: "Show token usage and billing" },
-  { cmd: "budget", desc: "Budget level: free | cheap | best | auto", args: "[level]" },
-  { cmd: "new", desc: "Start a new session" },
+  { cmd: "baseurl", desc: "Set provider base URL" },
+  { cmd: "models", desc: "Model picker" },
+  { cmd: "providers", desc: "List providers" },
+  { cmd: "status", desc: "Connection status" },
+  { cmd: "usage", desc: "Token usage & billing" },
+  { cmd: "budget", desc: "Budget level", args: "free | cheap | best | auto" },
+  { cmd: "new", desc: "New session" },
   { cmd: "clear", desc: "Clear the chat" },
-  { cmd: "restore", desc: "Restore project to an earlier state" },
-  { cmd: "settings", desc: "Toggle details/thinking display" },
-  { cmd: "sessions", desc: "Browse saved sessions (jump to one)" },
-  { cmd: "thinking", desc: "Toggle thinking visibility" },
-  { cmd: "details", desc: "Toggle tool detail visibility" },
+  { cmd: "restore", desc: "Restore earlier state" },
+  { cmd: "settings", desc: "Settings — details, thinking, sidebar" },
+  { cmd: "sessions", desc: "Browse saved sessions" },
   { cmd: "theme", desc: "Switch UI theme" },
-  { cmd: "graph", desc: "View the memory graph (nodes + links)" },
+  { cmd: "graph", desc: "Memory graph" },
   { cmd: "skills", desc: "Manage skills", args: "install <dir|git> | remove <name>" },
   { cmd: "mcp", desc: "Manage MCP servers", args: "add <name> <cmd> | remove | toggle" },
-  { cmd: "connectors", desc: "Manage connectors (hosting & cloud services)", args: "add <name> <cmd> | remove | toggle" },
-  { cmd: "permissions", desc: "Show saved permission rules", args: "| reset | auto" },
+  { cmd: "connectors", desc: "Manage connectors", args: "add <name> <cmd> | remove | toggle" },
+  { cmd: "permissions", desc: "Permission rules", args: "reset | auto" },
   { cmd: "exit", desc: "Quit Loom Code" },
   // Newer commands sit at the END so early rows (help/connect/…) keep their
   // popup positions — the interactive suite and muscle memory rely on it.
-  { cmd: "subagents", desc: "View subagent runs (live + history, cancel, details)" },
-  { cmd: "context", desc: "Show ~token breakdown of the current context window" },
-  { cmd: "think", desc: "Thinking budget", args: "off|low|medium|high" },
-  { cmd: "approve", desc: "Approve the plan & switch to Build (Plan mode)" },
-  { cmd: "tasks", desc: "List background tasks (bash background:true)" },
-  { cmd: "rewind", desc: "Pick a restore point and rewind files" },
-  { cmd: "share", desc: "Export this chat as a self-contained HTML file" },
-  { cmd: "worktree", desc: "New git worktree + branch for parallel work", args: "<name>" },
-  { cmd: "style", desc: "Output style preset or free text; empty clears" },
-  { cmd: "vim", desc: "Toggle vim modal editing (Esc = NORMAL)" },
-  { cmd: "remember", desc: "Save a fact to project LOOM.md (or type # fact)", args: "<fact>" },
+  { cmd: "subagents", desc: "Subagent runs" },
+  { cmd: "context", desc: "Context window usage" },
+  { cmd: "think", desc: "Thinking budget", args: "off | low | medium | high" },
+  { cmd: "approve", desc: "Approve plan → Build" },
+  { cmd: "tasks", desc: "Background tasks" },
+  { cmd: "share", desc: "Export chat as HTML" },
+  { cmd: "worktree", desc: "New git worktree", args: "<name>" },
+  { cmd: "sandbox", desc: "Docker sandbox", args: "setup | status | on | off | rm" },
+  { cmd: "style", desc: "Output style preset" },
+  { cmd: "vim", desc: "Toggle vim editing" },
+  { cmd: "remember", desc: "Save a fact to LOOM.md", args: "<fact>" },
 ];
 
 // ─── TUI prefs ───