deepseek-cli-mode 0.0.0-stage → 1.0.0

package/runner/runner.js

@@ -0,0 +1,1298 @@
+// dsh-cli runner — an interactive, Claude-Code-style driver for DeepSeek Harness.
+//
+// Loaded by the `dsh-cli` profile as a Cordis plugin (name: "./runner.js"), this
+// plugin keeps ONE live Agent across many turns in a single process, so the
+// session log, tool state, approvals, and the model's request prefix stay warm
+// between messages — real multi-turn continuity, unlike the one-shot
+// `headless` profile.
+//
+// Modes (read from the launcher's cmdlineArgs):
+//   deepseek                     interactive REPL (offers to resume the last session)
+//   deepseek "task..."           one-shot: run the task, print the answer, exit
+//   deepseek -r | --resume       resume the most recent session in this directory
+//   deepseek -r <id>             resume a specific session
+//   deepseek -c | --continue     continue the most recent session, no prompting
+//   deepseek --list              list recent sessions in this directory
+//   deepseek -y | --yes          auto-approve actions that would ask
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve as resolvePath } from "node:path";
+import { createInterface } from "node:readline";
+import { zstdDecompressSync } from "node:zlib";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { installModelSelection } from "@deepseek-ai/dsh-agent";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+
+/** Stable Cordis plugin name. */
+export const name = "cli-runner";
+/** Core services required before a turn can start. */
+export const inject = ["agents", "agentDefaultModel", "sessionPersistence"];
+
+const VERSION = process.env.DSH_CLI_VERSION ?? "0.1.0";
+
+// ---------------------------------------------------------------------------
+// Terminal helpers
+// ---------------------------------------------------------------------------
+const tty = process.stdout.isTTY && !process.env.NO_COLOR;
+const showReasoning = process.env.DSH_CLI_REASONING === "1";
+const paint = (fn, s) => (tty ? fn(s) : s);
+const ansi = {
+  dim: (s) => `\x1b[2m${s}\x1b[22m`,
+  bold: (s) => `\x1b[1m${s}\x1b[22m`,
+  italic: (s) => `\x1b[3m${s}\x1b[23m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[39m`,
+  green: (s) => `\x1b[32m${s}\x1b[39m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[39m`,
+  red: (s) => `\x1b[31m${s}\x1b[39m`,
+  magenta: (s) => `\x1b[35m${s}\x1b[39m`,
+  blue: (s) => `\x1b[94m${s}\x1b[39m`,
+};
+
+let out = (s) => process.stdout.write(s);
+let err = (s) => process.stderr.write(s);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function truncate(s, max) {
+  const text = String(s);
+  return text.length <= max ? text : text.slice(0, max - 1) + "…";
+}
+
+/** Error text with an optional stack for DSH_CLI_DEBUG=1. */
+function describeError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (process.env.DSH_CLI_DEBUG === "1" && error instanceof Error && error.stack) return `${message}\n${error.stack}`;
+  return message;
+}
+
+/** Compact token counts for the per-turn usage line. */
+function formatTokens(n) {
+  if (!Number.isFinite(n) || n <= 0) return "0";
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+}
+
+// ---------------------------------------------------------------------------
+// Markdown-lite line formatter (tty only; piped output stays raw)
+// ---------------------------------------------------------------------------
+function createFormatter() {
+  let inFence = false;
+  return function format(line) {
+    if (!tty) return line;
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("```")) {
+      inFence = !inFence;
+      return paint(ansi.dim, paint(ansi.cyan, line));
+    }
+    if (inFence) return paint(ansi.cyan, line);
+    let text = line;
+    // Headings
+    text = text.replace(/^(\s*)#{1,6}\s+(.*)$/, (_, lead, body) => lead + paint(ansi.bold, body));
+    // Bold, inline code
+    text = text.replace(/\*\*([^*\n]+)\*\*/g, (_, body) => paint(ansi.bold, body));
+    text = text.replace(/`([^`\n]+)`/g, (_, body) => paint(ansi.cyan, body));
+    return text;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tool-call previews
+// ---------------------------------------------------------------------------
+const TOOL_ICONS = {
+  read: "◇",
+  write: "✎",
+  edit: "✎",
+  str_replace_editor: "✎",
+  bash: "$",
+  pwsh: "$",
+  glob: "⌕",
+  grep: "⌕",
+  web_search: "◎",
+  web_fetch: "◎",
+  todo_write: "☑",
+  subagent: "⑂",
+  goal: "◈",
+  skill: "◆",
+  present: "▣",
+  ask_user_question: "?",
+};
+
+function previewToolCall(name, rawArgs) {
+  let args;
+  try {
+    args = JSON.parse(rawArgs);
+  } catch {
+    return truncate(rawArgs ?? "", 80);
+  }
+  if (args === null || typeof args !== "object") return "";
+  const pick = args.path ?? args.file_path ?? args.filePath ?? args.command ?? args.cmd
+    ?? args.pattern ?? args.query ?? args.url ?? args.description ?? args.task ?? args.id;
+  if (typeof pick !== "string") {
+    const json = JSON.stringify(args);
+    return json && json !== "{}" ? truncate(json, 80) : "";
+  }
+  return truncate(pick.replace(/\s+/g, " "), 90);
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/**
+ * @param {object} options
+ * @param {(text: string) => void} options.write where transcript text goes
+ * @param {boolean} options.capture collect assistant text instead of printing it
+ */
+function createRenderer({ write, capture }) {
+  const format = createFormatter();
+  let buffer = ""; // partial text line
+  let reasoning = ""; // this attempt's reasoning text
+  let lastReasoning = ""; // across the whole session, for /thinking
+  let streamedThisTurn = false;
+  let lineDirty = false; // something was written without a trailing newline
+  let lastAssistantText = "";
+  let lastTurnKind = undefined;
+  let lastTodos = [];
+  let turnUsage = { input: 0, output: 0 };
+
+  const endLine = () => {
+    if (lineDirty) {
+      write("\n");
+      lineDirty = false;
+    }
+  };
+
+  const feed = (text) => {
+    if (capture) return;
+    buffer += text;
+    let index;
+    while ((index = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      write(format(line) + "\n");
+      lineDirty = false;
+    }
+    if (buffer !== "") {
+      lineDirty = true;
+    }
+  };
+
+  const flushText = () => {
+    if (buffer !== "") {
+      if (!capture) {
+        write(format(buffer) + "\n");
+        lineDirty = false;
+      }
+      buffer = "";
+    }
+  };
+
+  return {
+    get lastReasoning() {
+      return lastReasoning;
+    },
+    get lastAssistantText() {
+      return lastAssistantText;
+    },
+    get lastTurnKind() {
+      return lastTurnKind;
+    },
+    get lastTodos() {
+      return lastTodos;
+    },
+    resetTurn() {
+      streamedThisTurn = false;
+      reasoning = "";
+      turnUsage = { input: 0, output: 0 };
+    },
+    /** Process one live assistant-stream frame. */
+    frame(frame) {
+      if (frame.type === "start") {
+        // A new attempt/step begins: never glue its text onto the previous line.
+        flushText();
+        endLine();
+        streamedThisTurn = false;
+        return;
+      }
+      if (frame.type === "chunk") {
+        const chunk = frame.chunk;
+        if (chunk.type === "text-delta") {
+          streamedThisTurn = true;
+          feed(chunk.text);
+        } else if (chunk.type === "reasoning-delta") {
+          reasoning += chunk.text;
+          if (showReasoning && !capture) {
+            write(paint(ansi.dim, paint(ansi.italic, chunk.text)));
+            lineDirty = true;
+          }
+        }
+      }
+    },
+    /** Process one durable session event. */
+    event(event) {
+      const data = event.data;
+      switch (event.type) {
+        case "tool/call": {
+          if (data.name === "todo_write") break; // the checklist below is the presentation
+          endLine();
+          const icon = TOOL_ICONS[data.name] ?? "⏺";
+          const preview = previewToolCall(data.name, data.arguments);
+          write(paint(ansi.dim, paint(ansi.italic, `  ${icon} ${data.name}${preview ? " " + preview : ""}`)) + "\n");
+          break;
+        }
+        case "tool/result": {
+          if (data.error) {
+            write(paint(ansi.dim, paint(ansi.italic, `  ✗ ${data.error.name}: ${data.error.code}`)) + "\n");
+          }
+          break;
+        }
+        case "assistant/message": {
+          const blocks = data.message?.content ?? [];
+          const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
+          if (text !== "") lastAssistantText = text;
+          if (data.usage) {
+            turnUsage.input += data.usage.inputTokens ?? 0;
+            turnUsage.output += data.usage.outputTokens ?? 0;
+          }
+          if (!streamedThisTurn) {
+            // Non-streaming adapter: print the assembled message.
+            if (!capture) feed(text);
+          }
+          break;
+        }
+        case "todo/write": {
+          const todos = data.todos ?? [];
+          const previous = new Map(lastTodos.map((todo) => [todo.content, todo.status]));
+          const firstRender = lastTodos.length === 0;
+          lastTodos = todos;
+          if (capture) break;
+          endLine();
+          flushText();
+          const done = todos.filter((todo) => todo.status === "completed").length;
+          write(paint(ansi.dim, `  ☑ todos ${done}/${todos.length}`) + "\n");
+          // Print the whole list once; later writes show only the items that moved.
+          const shown = firstRender ? todos : todos.filter((todo) => previous.get(todo.content) !== todo.status);
+          for (const todo of shown) {
+            const mark =
+              todo.status === "completed"
+                ? paint(ansi.green, "✓")
+                : todo.status === "in_progress"
+                  ? paint(ansi.yellow, "▸")
+                  : paint(ansi.dim, "☐");
+            const content = todo.status === "completed" ? paint(ansi.dim, todo.content) : todo.content;
+            write(`    ${mark} ${content}\n`);
+          }
+          break;
+        }
+        case "turn/end": {
+          flushText();
+          endLine();
+          const kind = data.reason?.kind;
+          lastTurnKind = kind;
+          if (kind === "error") {
+            write(paint(ansi.red, `  ⚠ turn failed: ${data.reason.error?.message ?? "unknown error"}\n`));
+          } else if (kind === "max-tokens") {
+            write(paint(ansi.yellow, "  ⚠ hit the output-token ceiling\n"));
+          } else if (kind === "aborted") {
+            write(paint(ansi.yellow, "  ⏹ interrupted\n"));
+          }
+          if (reasoning !== "") lastReasoning = reasoning;
+          if (!showReasoning && reasoning.length > 0 && tty && !capture) {
+            write(paint(ansi.dim, paint(ansi.italic, `  · thought ${reasoning.length} chars (use /thinking)`)) + "\n");
+          }
+          if (!capture && tty && (turnUsage.input > 0 || turnUsage.output > 0)) {
+            write(paint(ansi.dim, `  · ${formatTokens(turnUsage.input)} in / ${formatTokens(turnUsage.output)} out`) + "\n");
+          }
+          write("\n");
+          streamedThisTurn = false;
+          reasoning = "";
+          break;
+        }
+        default:
+          break;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Session discovery — mirrors the JSONL persistence layout:
+//   $DSH_HOME/sessions/<project-key>/<session-id>/session.v4.jsonl.zstd
+// ---------------------------------------------------------------------------
+function projectKey(cwd) {
+  if (cwd.length === 0) throw new Error("cannot encode an empty project path");
+  let readable = "";
+  let separatorRun = false;
+  for (let i = 0; i < cwd.length; i++) {
+    const code = cwd.charCodeAt(i);
+    const ch = String.fromCharCode(code);
+    if (ch === "/" || ch === "\\" || ch === ":") {
+      if (!separatorRun) readable += "-";
+      separatorRun = true;
+    } else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) {
+      readable += ch;
+      separatorRun = false;
+    } else {
+      readable += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+      separatorRun = false;
+    }
+  }
+  return `--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--`;
+}
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+/** Last few zstd frames of a session log, decoded to turn-lifecycle records. */
+function readSessionTail(sessionDir) {
+  try {
+    const file = join(sessionDir, "session.v4.jsonl.zstd");
+    const buf = readFileSync(file);
+    const positions = [];
+    let at = 0;
+    while ((at = buf.indexOf(ZSTD_MAGIC, at)) !== -1) {
+      positions.push(at);
+      at += 4;
+    }
+    const events = [];
+    for (let i = Math.max(0, positions.length - 5); i < positions.length; i++) {
+      const start = positions[i];
+      const end = i + 1 < positions.length ? positions[i + 1] : buf.length;
+      let text;
+      try {
+        text = zstdDecompressSync(buf.subarray(start, end)).toString("utf8");
+      } catch {
+        continue;
+      }
+      for (const line of text.split("\n")) {
+        if (line === "") continue;
+        try {
+          const event = JSON.parse(line);
+          if (event.type === "turn/start" || event.type === "turn/end" || event.type === "step/start" || event.type === "tool/call") {
+            events.push({ type: event.type });
+          }
+        } catch {}
+      }
+    }
+    return events;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a session's log ends inside a turn (live elsewhere, or abandoned). */
+function hasOpenTurn(sessionDir) {
+  const events = readSessionTail(sessionDir);
+  if (events === null || events.length === 0) return false;
+  let open = false;
+  for (const event of events) {
+    if (event.type === "turn/end") open = false;
+    else if (event.type === "turn/start" || event.type === "step/start" || event.type === "tool/call") open = true;
+  }
+  return open;
+}
+
+function listSessions(cwd = process.cwd()) {
+  const dir = join(resolveDshHome(), "sessions", projectKey(cwd));
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith("session-")) continue;
+    const sessionDir = join(dir, entry.name);
+    let newest = 0;
+    try {
+      for (const file of readdirSync(sessionDir)) {
+        const st = statSync(join(sessionDir, file));
+        if (st.mtimeMs > newest) newest = st.mtimeMs;
+      }
+    } catch {
+      continue;
+    }
+    if (newest > 0) sessions.push({ id: entry.name, mtime: newest, openTurn: hasOpenTurn(sessionDir) });
+  }
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  return sessions;
+}
+
+function timeAgo(ms) {
+  const diff = Date.now() - ms;
+  if (diff < 60000) return `${Math.max(1, Math.floor(diff / 1000))}s ago`;
+  if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
+  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
+  return `${Math.floor(diff / 86400000)}d ago`;
+}
+
+function printSessionList(sessions, write = out) {
+  if (sessions.length === 0) {
+    write(paint(ansi.dim, "  no sessions in this directory yet\n"));
+    return;
+  }
+  write(`  Recent sessions in ${process.cwd()}:\n`);
+  sessions.slice(0, 10).forEach((session, index) => {
+    const running = session.openTurn ? paint(ansi.yellow, "  ▶ running") : "";
+    write(`   ${paint(ansi.cyan, String(index + 1))}) ${paint(ansi.dim, session.id)}  (${paint(ansi.dim, timeAgo(session.mtime))})${running}\n`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Help / banner
+// ---------------------------------------------------------------------------
+function printBanner(model) {
+  const art = [
+    "        ooo",
+    '       " """',
+    '      "   "',
+    '   ___:____      "  "|',
+    " ,'        \\.     \\//",
+    " |  O        \\___/  |",
+    "~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~^~",
+  ];
+  out("\n");
+  for (const line of art) out(paint(ansi.blue, line) + "\n");
+  out(`${paint(ansi.bold, "deepseek")} ${paint(ansi.dim, VERSION)} — DeepSeek Harness in your terminal\n`);
+  out(paint(ansi.dim, `model: ${model.provider}/${model.model}${model.reasoningEffort ? ` · ${model.reasoningEffort}` : ""}`) + "\n");
+  out(paint(ansi.dim, `cwd: ${process.cwd()}`) + "\n");
+  out(paint(ansi.dim, "type /help for commands, Ctrl+C to interrupt or exit") + "\n\n");
+}
+
+function printHelp(write = out) {
+  write(`deepseek ${VERSION} — DeepSeek Harness in your terminal.
+
+Usage:
+  deepseek                       start an interactive session
+  deepseek "task text..."        answer one task and exit (scriptable)
+  deepseek -r, --resume [id]     resume a session (newest in this directory by default)
+  deepseek -c, --continue        continue the newest session without prompting
+  deepseek --list                list recent sessions in this directory
+  deepseek -y, --yes             auto-approve actions that would ask
+  deepseek --model <id>          override the model for this run
+  deepseek --reasoning <effort>  override the reasoning effort (off|high|max)
+
+Interactive commands:
+  /help              this list (plus the Harness commands below)
+  /new               start a fresh session
+  /sessions          list recent sessions in this directory
+  /resume <id>       switch to another session
+  /model [id]        show or switch the model (e.g. /model deepseek-v4-pro)
+  /reasoning [off|high|max]   show or set the reasoning effort
+  /permissions [p]   show or switch the permission preset (native: /permission)
+  /skills            list the skills discovered in this workspace
+  /jobs              list this session's background jobs
+  /todos             show the current todo list
+  /image <path>      attach an image to the next message (or mention @photo.png)
+  /export [file]     write this run's transcript as markdown
+  /thinking          show the last turn's reasoning
+  /session           print the current session id (for --resume)
+  /clear             clear the screen
+  /quit, /exit       leave (also Ctrl+C at an empty prompt)
+
+Harness commands (shared with the Web and Desktop apps):
+  /compact, /goal, /plan, and any command a plugin registers.
+  Type /help inside a session to see the live list.
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const options = {
+    mode: "interactive",
+    resume: undefined,
+    continue: false,
+    list: false,
+    yes: false,
+    model: undefined,
+    reasoning: undefined,
+    help: false,
+    version: false,
+    task: undefined,
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--version" || arg === "-v") options.version = true;
+    else if (arg === "--list" || arg === "--sessions") options.list = true;
+    else if (arg === "--continue" || arg === "-c") options.continue = true;
+    else if (arg === "--yes" || arg === "-y") options.yes = true;
+    else if (arg === "--model") options.model = argv[++i];
+    else if (arg === "--reasoning") options.reasoning = argv[++i];
+    else if (arg === "--resume" || arg === "-r") {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        options.resume = next;
+        i++;
+      } else {
+        options.resume = true;
+      }
+    } else if (arg === "--") {
+      rest.push(...argv.slice(i + 1));
+      break;
+    } else if (arg.startsWith("-")) {
+      rest.push(arg);
+    } else {
+      rest.push(arg);
+    }
+  }
+  if (rest.length > 0) {
+    options.mode = "oneshot";
+    options.task = rest.join(" ");
+  }
+  return options;
+}
+
+// ---------------------------------------------------------------------------
+// Core driver
+// ---------------------------------------------------------------------------
+async function run(ctx, options, exit) {
+  await ctx.get("loader")?.await();
+  const agents = ctx.get("agents");
+  const defaultModel = ctx.get("agentDefaultModel");
+  const persistence = ctx.get("sessionPersistence");
+  if (agents === undefined || defaultModel === undefined || persistence === undefined) {
+    throw new Error("cli-runner: agents / agentDefaultModel / sessionPersistence services missing");
+  }
+  // Optional Harness services: each one adds native parity when the profile
+  // composes it, and every use is guarded so a narrower profile still runs.
+  const commands = ctx.get("commands");
+  const skills = ctx.get("skills");
+  const jobs = ctx.get("jobs");
+  const planMode = ctx.get("planMode");
+  const permissionPresets = ctx.get("permissionPresets");
+  const attachments = ctx.get("attachments");
+
+  if (options.list) {
+    printSessionList(listSessions());
+    exit(0);
+    return;
+  }
+
+  const selection = { ...defaultModel.currentSelection() };
+  if (options.model) selection.model = options.model;
+  if (options.reasoning) selection.reasoningEffort = options.reasoning;
+
+  const interactive = options.mode === "interactive";
+  const autoYes = options.yes || process.env.DSH_CLI_YES === "1";
+
+  let handle = null;
+  let busy = false;
+  let quitting = false;
+  let cancelSent = false;
+  let selectionRef = { current: { ...selection }, assembled: undefined };
+  let currentAsk = null;
+  let pendingLine = null;
+  const lineQueue = [];
+  let paused = false;
+  let lastInterrupt = 0;
+  let ready = false;
+  let stdinClosed = false;
+
+  const write = (text) => process.stdout.write(text);
+
+  // ---- line input ---------------------------------------------------------
+  // One-shot mode must not own stdin: a piped/closed stdin would deliver EOF
+  // and tear the runtime down before the task runs.
+  const rlInterface = interactive
+    ? createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdin.isTTY,
+        historySize: 200,
+        removeHistoryDuplicates: true,
+      })
+    : null;
+  // Hold the input until the first agent is ready: buffered piped lines must
+  // not be consumed (and dropped) while the profile is still starting.
+  if (rlInterface) {
+    try {
+      rlInterface.pause();
+      paused = true;
+    } catch {}
+  }
+
+  function setPaused(value) {
+    if (!rlInterface || paused === value) return;
+    paused = value;
+    try {
+      if (value) rlInterface.pause();
+      else rlInterface.resume();
+    } catch {}
+  }
+
+  rlInterface?.on("line", (line) => {
+    if (pendingLine) {
+      const deliver = pendingLine;
+      pendingLine = null;
+      deliver(line);
+    } else {
+      lineQueue.push(line);
+    }
+  });
+
+  /**
+   * Ask one line. Resolves null when the question is interrupted (Ctrl+C) or
+   * stdin closes. A permanent listener queues ahead-of-time lines (piped input,
+   * or typing while the model works), so no line is ever dropped.
+   * @param {string} prompt
+   * @returns {Promise<string | null>}
+   */
+  function ask(prompt) {
+    return new Promise((resolve) => {
+      if (!rlInterface) {
+        resolve(null);
+        return;
+      }
+      if (lineQueue.length > 0) {
+        resolve(lineQueue.shift());
+        return;
+      }
+      if (stdinClosed) {
+        resolve(null);
+        return;
+      }
+      setPaused(false);
+      rlInterface.setPrompt(prompt);
+      rlInterface.prompt();
+      pendingLine = (value) => {
+        currentAsk = null;
+        if (busy) setPaused(true);
+        resolve(value);
+      };
+      currentAsk = {
+        done: (value) => {
+          const answer = pendingLine;
+          pendingLine = null;
+          answer?.(value);
+        },
+      };
+    });
+  }
+
+  function closeInput() {
+    try {
+      rlInterface?.close();
+    } catch {}
+  }
+
+  const shutdown = async (code) => {
+    if (quitting) return;
+    quitting = true;
+    closeInput();
+    if (handle) {
+      try {
+        await Promise.race([persistence.flush(), sleep(2000)]);
+      } catch {}
+      try {
+        await Promise.race([handle.dispose(), sleep(3000)]);
+      } catch {}
+      handle = null;
+    }
+    exit(code);
+  };
+
+  rlInterface?.on("SIGINT", handleInterrupt);
+  process.on("SIGINT", handleInterrupt);
+  rlInterface?.on("close", () => {
+    stdinClosed = true;
+    if (currentAsk) {
+      const done = currentAsk.done;
+      done(lineQueue.length > 0 ? lineQueue.shift() : null);
+      return;
+    }
+    if (quitting || busy) return;
+    if (lineQueue.length > 0) return; // the loop drains the buffered lines
+    if (ready) shutdown(0);
+  });
+
+  /** One Ctrl+C path shared by readline and the process signal. */
+  function handleInterrupt() {
+    const now = Date.now();
+    if (now - lastInterrupt < 150) return; // one physical keypress, one action
+    lastInterrupt = now;
+    if (currentAsk) {
+      const done = currentAsk.done;
+      process.stdout.write("\n");
+      done(null);
+      return;
+    }
+    if (busy) {
+      if (!cancelSent) {
+        cancelSent = true;
+        out(paint(ansi.yellow, "\n  ⏹ cancelling…\n"));
+        try {
+          handle?.agent.cancel({ kind: "user" });
+        } catch {}
+        return;
+      }
+      shutdown(130);
+      return;
+    }
+    shutdown(0);
+  }
+
+  // ---- terminal questions for tools (plan mode, ask_user_question) ---------
+  // Answered per agent through the same `user-questions/request` waterfall the
+  // Web client uses, so plan review and ask_user_question behave identically.
+  const answerQuestions = async (request) => {
+    const answers = [];
+    const questions = request?.questions ?? [];
+    for (const question of questions) {
+      out("\n");
+      if (question.header) out(paint(ansi.bold, `  ${question.header}`) + "\n");
+      out(`  ${question.question}\n`);
+      if (question.detail) out(paint(ansi.dim, question.detail.replace(/^/gm, "  | ")) + "\n");
+      const options = question.options ?? [];
+      options.forEach((option, index) => {
+        out(`   ${paint(ansi.cyan, String(index + 1))}) ${option.label}${option.description ? paint(ansi.dim, ` — ${option.description}`) : ""}\n`);
+      });
+      if (!interactive) {
+        answers.push({ id: question.id, selected: options[0] ? [options[0].label] : [], custom: options[0] ? undefined : "one-shot mode: no interactive answer" });
+        continue;
+      }
+      const answer = await ask(paint(ansi.green, options.length > 0 ? "  choose: " : "  answer: "));
+      const text = (answer ?? "").trim();
+      const index = Number.parseInt(text, 10) - 1;
+      if (options.length > 0 && index >= 0 && index < options.length) answers.push({ id: question.id, selected: [options[index].label] });
+      else answers.push({ id: question.id, selected: [], custom: text });
+    }
+    return { answers };
+  };
+
+  // ---- agent lifecycle ----------------------------------------------------
+  const makeAgentOptions = () => ({ ...selectionRef.current });
+
+  const wire = (agent) => {
+    agent.ctx.on("session/event", (session, event) => {
+      if (session === agent.session) renderer.event(event);
+    });
+    agent.ctx.on("agent/assistant-stream", (payload) => {
+      if (payload.agent === agent) renderer.frame(payload.frame);
+    });
+    agent.ctx.on("user-questions/request", async (request) => answerQuestions(request));
+    agent.ctx.on("approval/request", async (request) => {
+      const toolName = request.toolName ?? "tool";
+      if (autoYes) return "allowed-once";
+      if (request.reason) {
+        out(paint(ansi.dim, paint(ansi.italic, `  ⚠ ${toolName} needs approval: ${request.reason}`)) + "\n");
+      }
+      if (!interactive || !process.stdin.isTTY) return "rejected";
+      const answer = await ask(paint(ansi.yellow, `  ⚠ Allow ${paint(ansi.cyan, toolName)}? `) + paint(ansi.dim, "[y/N] "));
+      if (answer === null) return "rejected";
+      return /^y(es)?$/i.test(answer.trim()) ? "allowed-once" : "rejected";
+    });
+  };
+
+  const startAgent = async (sessionId, resumeId) => {
+    if (handle) {
+      try {
+        await Promise.race([handle.dispose(), sleep(3000)]);
+      } catch {}
+      handle = null;
+    }
+    selectionRef = { current: { ...selectionRef.current }, assembled: undefined };
+    const setup = (agentCtx) => {
+      installModelSelection(agentCtx, selectionRef);
+    };
+    const created = resumeId
+      ? await agents.resume({ resumeSessionId: SessionId(resumeId), agentOptions: makeAgentOptions(), setup })
+      : await agents.create({
+          sessionId,
+          meta: { cwd: process.cwd() },
+          agentOptions: makeAgentOptions(),
+          setup,
+        });
+    handle = created;
+    wire(created.agent);
+    await created.agent.whenIdle();
+    return created.agent;
+  };
+
+  const runTurn = async (agent, text) => {
+    const content = await buildUserContent(text);
+    transcript.push({ role: "user", text });
+    const previousAnswer = renderer.lastAssistantText;
+    busy = true;
+    cancelSent = false;
+    renderer.resetTurn();
+    setPaused(true);
+    try {
+      agent.followup(createUserMessage({ content, source: { kind: "user" } }));
+      await agent.whenIdle();
+      await persistence.flush();
+    } finally {
+      busy = false;
+      setPaused(false);
+      if (renderer.lastAssistantText && renderer.lastAssistantText !== previousAnswer) {
+        transcript.push({ role: "assistant", text: renderer.lastAssistantText });
+      }
+    }
+  };
+
+  const renderer = createRenderer({
+    write: (text) => {
+      if (options.mode !== "oneshot") write(text);
+    },
+    capture: options.mode === "oneshot",
+  });
+
+  const modelDesc = () => {
+    const current = selectionRef.current;
+    return `${current.provider}/${current.model}${current.reasoningEffort ? ` · ${current.reasoningEffort}` : ""}`;
+  };
+
+  // ---- parity helpers -----------------------------------------------------
+  const transcript = [];
+  const pendingImages = [];
+  const IMAGE_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
+
+  /** Image paths mentioned with `@…` in a message. */
+  function mentionedImages(text) {
+    const paths = [];
+    for (const match of text.matchAll(/(?:^|\s)@([^\s@]+)/g)) {
+      const extension = match[1].split(".").pop()?.toLowerCase() ?? "";
+      if (!(extension in IMAGE_TYPES)) continue;
+      const target = resolvePath(process.cwd(), match[1]);
+      if (existsSync(target)) paths.push(target);
+    }
+    return paths;
+  }
+
+  /** Build the user message: text (with @file inlining) plus attached images. */
+  async function buildUserContent(text) {
+    const expanded = expandMentions(text);
+    const images = [...pendingImages, ...mentionedImages(text)];
+    pendingImages.length = 0;
+    const blocks = [{ type: "text", text: expanded }];
+    for (const imagePath of [...new Set(images)]) {
+      if (attachments === undefined) {
+        out(paint(ansi.yellow, "  ⚠ this profile has no attachment store; image ignored\n"));
+        continue;
+      }
+      try {
+        const extension = imagePath.split(".").pop()?.toLowerCase() ?? "";
+        const refs = await attachments.saveImages([
+          { data: readFileSync(imagePath), mediaType: IMAGE_TYPES[extension], name: basename(imagePath) },
+        ]);
+        if (refs[0] !== undefined) blocks.push({ type: "image", attachment: refs[0] });
+      } catch (error) {
+        out(paint(ansi.yellow, `  ⚠ cannot attach ${imagePath}: ${describeError(error)}`) + "\n");
+      }
+    }
+    if (blocks.length > 1) out(paint(ansi.dim, `  ▣ ${blocks.length - 1} image(s) attached`) + "\n");
+    return blocks;
+  }
+
+  /** Run one native Harness slash command; false when no such command exists. */
+  async function runNativeCommand(agent, line) {
+    if (commands === undefined) return false;
+    const controller = new AbortController();
+    try {
+      const execution = await commands.execute(agent, line, [], controller.signal);
+      if (execution === undefined) return false;
+      const result = execution.result;
+      if (result.kind === "error") out(paint(ansi.red, `  ✘ ${result.text ?? "command failed"}`) + "\n");
+      else if (result.text) out(paint(ansi.dim, `  ${result.text}`) + "\n");
+      else out(paint(ansi.dim, "  ✓ done") + "\n");
+      return true;
+    } catch (error) {
+      out(paint(ansi.red, `  ✘ ${describeError(error)}`) + "\n");
+      return true;
+    }
+  }
+
+  /** List the Harness commands this profile registers (/compact, /goal, …). */
+  function printNativeCommands(agent) {
+    if (commands === undefined) return;
+    let list = [];
+    try {
+      list = commands.list(agent);
+    } catch {}
+    if (list.length === 0) return;
+    out(paint(ansi.bold, "Harness commands:") + "\n");
+    for (const entry of list) out(`  /${entry.name.padEnd(12)} ${paint(ansi.dim, entry.description)}\n`);
+  }
+
+  /**
+   * Expand `@path` mentions into attached file text, so the model can read a
+   * file the same way a Web client attaches one.
+   */
+  function expandMentions(text) {
+    const mentions = [...new Set([...text.matchAll(/(?:^|\s)@([^\s@]+)/g)].map((match) => match[1]))];
+    if (mentions.length === 0) return text;
+    let extra = "";
+    for (const mention of mentions) {
+      try {
+        const target = resolvePath(process.cwd(), mention);
+        if (!existsSync(target)) continue;
+        const stat = statSync(target);
+        if (!stat.isFile()) continue;
+        if (stat.size > 200_000) {
+          extra += `\n\n--- attached: ${mention} (skipped, ${stat.size} bytes > 200 KB) ---\n`;
+          continue;
+        }
+        if (/\.(png|jpe?g|webp|gif)$/i.test(target)) continue; // handled as an image attachment
+        if (/\.(pdf|zip|exe|dll|bin)$/i.test(target)) {
+          extra += `\n\n--- attached: ${mention} (binary, not inlined) ---\n`;
+          continue;
+        }
+        const body = readFileSync(target, "utf8");
+        extra += `\n\n--- attached file: ${mention} ---\n${body}\n--- end ${mention} ---\n`;
+      } catch {}
+    }
+    return extra === "" ? text : text + extra;
+  }
+
+  /** Write the current run's transcript as markdown. */
+  function exportTranscript(agent, target) {
+    const lines = [
+      `# DeepSeek Harness session ${agent.session.id}`,
+      "",
+      `- model: ${modelDesc()}`,
+      `- cwd: ${process.cwd()}`,
+      `- exported: ${new Date().toISOString()}`,
+      "",
+    ];
+    if (transcript.length === 0) lines.push("_(no turns in this run)_", "");
+    for (const entry of transcript) {
+      lines.push(entry.role === "user" ? "## You" : "## Assistant", "", entry.text, "");
+    }
+    const file = target === "" ? `deepseek-${String(agent.session.id).replace(/^session-/, "").slice(0, 8)}.md` : target;
+    writeFileSync(file, lines.join("\n"), "utf8");
+    return file;
+  }
+
+  // ---- subagent progress --------------------------------------------------
+  // Root-scoped listeners: child agents created by this session are reported as
+  // one-line progress notes, like the Web UI's subagent cards.
+  ctx.on("agent/created", (payload) => {
+    try {
+      if (handle !== null && agents.isOwnedBy(payload.agent.id, handle.agent)) {
+        out(paint(ansi.dim, paint(ansi.italic, `  ↳ subagent ${String(payload.agent.id).slice(-8)} started`)) + "\n");
+      }
+    } catch {}
+  });
+  ctx.on("agent/disposed", (payload) => {
+    try {
+      if (handle !== null && agents.isOwnedBy(payload.agent.id, handle.agent)) {
+        out(paint(ansi.dim, paint(ansi.italic, `  ↳ subagent ${String(payload.agent.id).slice(-8)} finished`)) + "\n");
+      }
+    } catch {}
+  });
+
+  // ---- resolve a session to resume, if any --------------------------------
+  let resumeTarget = options.resume === true ? true : typeof options.resume === "string" ? options.resume : undefined;
+  if (options.continue) resumeTarget = true;
+
+  if (resumeTarget === true) {
+    const sessions = listSessions();
+    const candidate = sessions.find((session) => !session.openTurn);
+    if (candidate === undefined) {
+      out(paint(ansi.yellow, "  no resumable sessions in this directory; starting fresh\n"));
+      resumeTarget = undefined;
+    } else {
+      resumeTarget = candidate.id;
+    }
+  }
+
+  if (interactive && resumeTarget === undefined && process.stdin.isTTY) {
+    const candidate = listSessions().find((session) => !session.openTurn);
+    if (candidate !== undefined) {
+      const answer = await ask(
+        paint(ansi.yellow, `  Resume previous session (${candidate.id}, ${timeAgo(candidate.mtime)})? `) + paint(ansi.dim, "[y/N] ")
+      );
+      if (answer !== null && /^y(es)?$/i.test(answer.trim())) resumeTarget = candidate.id;
+    }
+  }
+
+  // ---- one-shot -----------------------------------------------------------
+  if (options.mode === "oneshot") {
+    const task = options.task?.trim();
+    if (!task) {
+      err("deepseek: no task given\n");
+      await shutdown(1);
+      return;
+    }
+    let agent;
+    try {
+      agent = resumeTarget ? await startAgent(undefined, resumeTarget) : await startAgent(SessionId(`session-${randomUUID()}`), undefined);
+    } catch (error) {
+      err(`deepseek: ${describeError(error)}\n`);
+      await shutdown(1);
+      return;
+    }
+    await runTurn(agent, task);
+    const answer = renderer.lastAssistantText;
+    if (answer !== "") process.stdout.write(answer.endsWith("\n") ? answer : answer + "\n");
+    await shutdown(renderer.lastTurnKind === "completed" ? 0 : 1);
+    return;
+  }
+
+  // ---- interactive --------------------------------------------------------
+  let agent;
+  try {
+    agent = resumeTarget ? await startAgent(undefined, resumeTarget) : await startAgent(SessionId(`session-${randomUUID()}`), undefined);
+  } catch (error) {
+    err(`deepseek: cannot start a session: ${error instanceof Error ? error.message : String(error)}\n`);
+    await shutdown(1);
+    return;
+  }
+
+  ready = true;
+  if (stdinClosed) {
+    await shutdown(0);
+    return;
+  }
+
+  printBanner(selectionRef.current);
+  if (resumeTarget) {
+    out(paint(ansi.green, `▶ resumed `) + paint(ansi.dim, resumeTarget) + "\n");
+    out(paint(ansi.dim, "  (history is in the session log; continue the conversation below)") + "\n\n");
+  } else {
+    out(paint(ansi.dim, `session: ${agent.session.id}  (resume with: deepseek --resume ${agent.session.id})`) + "\n\n");
+  }
+
+  while (!quitting) {
+    const line = await ask(paint(ansi.green, "❯ "));
+    if (line === null) break;
+    const text = line.trim();
+    if (text === "") continue;
+
+    if (text.startsWith("/")) {
+      const [command, ...rest] = text.split(/\s+/);
+      const argument = rest.join(" ");
+      switch (command) {
+        case "/help":
+          printHelp(write);
+          printNativeCommands(agent);
+          continue;
+        case "/quit":
+        case "/exit":
+          await shutdown(0);
+          return;
+        case "/new": {
+          out(paint(ansi.dim, "  ↻ new session\n"));
+          try {
+            agent = await startAgent(SessionId(`session-${randomUUID()}`), undefined);
+            out(paint(ansi.dim, `  session: ${agent.session.id}\n`));
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${error instanceof Error ? error.message : String(error)}\n`));
+          }
+          continue;
+        }
+        case "/sessions":
+          printSessionList(listSessions(), write);
+          continue;
+        case "/resume": {
+          if (argument === "") {
+            out(paint(ansi.yellow, "  usage: /resume <session-id> (see /sessions)\n"));
+            continue;
+          }
+          try {
+            out(paint(ansi.dim, `  ↻ resuming ${argument}\n`));
+            agent = await startAgent(undefined, argument);
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${error instanceof Error ? error.message : String(error)}\n`));
+          }
+          continue;
+        }
+        case "/session":
+          out(paint(ansi.dim, `  ${agent.session.id}\n`));
+          continue;
+        case "/model": {
+          if (argument === "") {
+            out(paint(ansi.dim, `  model: ${modelDesc()}\n`));
+            continue;
+          }
+          const next = { ...selectionRef.current, model: argument };
+          try {
+            await defaultModel.saveSelection(next);
+            selectionRef.current = next;
+            out(paint(ansi.green, `  ✓ model set: ${next.provider}/${next.model} (next message)\n`));
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${error instanceof Error ? error.message : String(error)}\n`));
+          }
+          continue;
+        }
+        case "/reasoning": {
+          if (argument === "") {
+            out(paint(ansi.dim, `  reasoning: ${selectionRef.current.reasoningEffort ?? "default"}\n`));
+            continue;
+          }
+          const next = { ...selectionRef.current, reasoningEffort: argument === "default" ? undefined : argument };
+          try {
+            await defaultModel.saveSelection(next);
+            selectionRef.current = next;
+            out(paint(ansi.green, `  ✓ reasoning set: ${argument} (next message)\n`));
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${error instanceof Error ? error.message : String(error)}\n`));
+          }
+          continue;
+        }
+        case "/thinking": {
+          const reasoning = renderer.lastReasoning;
+          if (reasoning === "") out(paint(ansi.dim, "  no reasoning recorded yet\n"));
+          else out(paint(ansi.dim, paint(ansi.italic, reasoning)) + "\n");
+          continue;
+        }
+        case "/image": {
+          if (argument === "") {
+            out(paint(ansi.yellow, "  usage: /image <path>  (or mention @photo.png in a message)\n"));
+            continue;
+          }
+          const target = resolvePath(process.cwd(), argument);
+          if (!existsSync(target)) {
+            out(paint(ansi.red, `  ✘ no such file: ${argument}\n`));
+            continue;
+          }
+          pendingImages.push(target);
+          out(paint(ansi.green, `  ▣ attached ${basename(target)} to the next message\n`));
+          continue;
+        }
+        case "/todos": {
+          const todos = renderer.lastTodos;
+          if (todos.length === 0) {
+            out(paint(ansi.dim, "  no todo list in this session yet\n"));
+            continue;
+          }
+          const done = todos.filter((todo) => todo.status === "completed").length;
+          out(paint(ansi.dim, `  ☑ todos ${done}/${todos.length}`) + "\n");
+          for (const todo of todos) {
+            const mark = todo.status === "completed" ? "✓" : todo.status === "in_progress" ? "▸" : "☐";
+            out(`    ${mark} ${todo.content}\n`);
+          }
+          continue;
+        }
+        case "/skills": {
+          if (skills === undefined) {
+            out(paint(ansi.yellow, "  this profile does not compose the skill registry\n"));
+            continue;
+          }
+          try {
+            const list = await skills.list();
+            if (list.length === 0) out(paint(ansi.dim, "  no skills discovered in this workspace\n"));
+            else {
+              out(paint(ansi.bold, "Skills:") + "\n");
+              for (const skill of list) out(`  ${paint(ansi.cyan, skill.name)} — ${paint(ansi.dim, skill.description)}\n`);
+            }
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${describeError(error)}\n`));
+          }
+          continue;
+        }
+        case "/jobs": {
+          if (jobs === undefined) {
+            out(paint(ansi.yellow, "  this profile does not compose the job registry\n"));
+            continue;
+          }
+          let list = [];
+          try {
+            list = jobs.list(agent.session.id);
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${describeError(error)}\n`));
+            continue;
+          }
+          if (list.length === 0) out(paint(ansi.dim, "  no background jobs\n"));
+          else {
+            out(paint(ansi.bold, "Background jobs:") + "\n");
+            for (const job of list) {
+              const state = job.status === "running" ? paint(ansi.yellow, job.status) : paint(ansi.dim, job.status);
+              out(`  ${job.id}  ${state}  ${job.label}${job.progress ? paint(ansi.dim, ` · ${job.progress}`) : ""}\n`);
+            }
+          }
+          continue;
+        }
+        case "/permissions": {
+          if (permissionPresets === undefined) {
+            out(paint(ansi.yellow, "  this profile does not compose permission presets\n"));
+            continue;
+          }
+          try {
+            const catalog = permissionPresets.catalog();
+            if (argument === "") {
+              out(paint(ansi.bold, "Permission presets:") + "\n");
+              for (const option of catalog.options) {
+                out(`  ${paint(ansi.cyan, option.value.padEnd(18))} ${option.name}${option.description ? paint(ansi.dim, ` — ${option.description}`) : ""}\n`);
+              }
+              out(paint(ansi.dim, `  default: ${catalog.defaultPreset}`) + "\n");
+            } else {
+              permissionPresets.set(agent.session, argument);
+              out(paint(ansi.green, `  ✓ permissions: ${argument} (applies to the next tool call)\n`));
+            }
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${describeError(error)}\n`));
+          }
+          continue;
+        }
+        case "/export": {
+          try {
+            const file = exportTranscript(agent, argument);
+            out(paint(ansi.green, `  ✓ exported ${transcript.length} message(s) to ${file}\n`));
+          } catch (error) {
+            out(paint(ansi.red, `  ✘ ${describeError(error)}\n`));
+          }
+          continue;
+        }
+        case "/clear":
+          out("\x1b[2J\x1b[3J\x1b[H");
+          continue;
+        default: {
+          // Anything the Harness itself registers (/compact, /goal, /plan, …)
+          // runs through the shared command registry, so CLI and Web stay in sync.
+          if (await runNativeCommand(agent, text)) continue;
+          if (planMode !== undefined && command === "/plan") {
+            try {
+              const current = planMode.get(agent);
+              const next = argument === "off" ? false : argument === "" ? !current.active : true;
+              const outcome = planMode.set(agent, next);
+              out(paint(ansi.green, `  ✓ plan mode ${next ? "on" : "off"} (${outcome})\n`));
+            } catch (error) {
+              out(paint(ansi.red, `  ✘ ${describeError(error)}\n`));
+            }
+            continue;
+          }
+          out(paint(ansi.yellow, `  unknown command ${command} — try /help\n`));
+          continue;
+        }
+      }
+    }
+
+    out("\n" + paint(ansi.green, "❯ ") + text + "\n\n");
+    await runTurn(agent, text);
+  }
+
+  await shutdown(0);
+}
+
+// ---------------------------------------------------------------------------
+// Cordis plugin entry
+// ---------------------------------------------------------------------------
+export function apply(ctx) {
+  const exit = ctx.get("appExit");
+  if (exit === undefined) {
+    throw new Error("cli-runner: the launcher must provide ctx.appExit before the tree mounts");
+  }
+  const argv = ctx.get("cmdlineArgs")?.get() ?? [];
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp();
+    exit(0);
+    return;
+  }
+  if (options.version) {
+    console.log(VERSION);
+    exit(0);
+    return;
+  }
+  run(ctx, options, exit).catch((error) => {
+    const detail = process.env.DSH_CLI_DEBUG === "1" && error instanceof Error ? `\n${error.stack}` : "";
+    process.stderr.write(`deepseek: ${error instanceof Error ? error.message : String(error)}${detail}\n`);
+    try {
+      exit(1);
+    } catch {}
+  });
+}