@devmarketplacenpm/devmp 0.1.1-beta.5

package/lib/interactive.js

@@ -0,0 +1,1269 @@
+"use strict";
+
+const os = require("os");
+const path = require("path");
+const { randomUUID } = require("crypto");
+const { stdin, stdout } = require("process");
+const { createScreen } = require("./tty/screen");
+const { displayWidth, wrap } = require("./tty/ansi");
+const { createComposer } = require("./tty/composer");
+const { createMarkdownStream } = require("./markdown");
+const { expandMentions } = require("./mentions");
+const { findProjectInstructionsFile } = require("./instructions");
+const { completeInput } = require("./completion");
+const { connectInteractiveSession } = require("./interactive-tunnel");
+const { loadConversation, saveConversation } = require("./session");
+const { createCheckpointManager } = require("./checkpoints");
+const { checkpointDiff, diffStats, styleDiffLines } = require("./diff");
+const { getGitInfo } = require("./git");
+const { collectStatus, renderStatusCard, renderDoctor } = require("./status");
+const { setApprovalDriver, clearApprovalDriver } = require("./prompt");
+const { startDeviceAuth, pollDeviceAuth } = require("./api");
+const { openBrowser } = require("./browser");
+const {
+  color,
+  fmt,
+  SPINNER_FRAMES,
+  formatNumber,
+  formatDuration,
+} = require("./ui");
+
+const MODES = new Set(["auto", "chat", "plan", "act"]);
+const PROVIDERS = new Set(["openai", "anthropic", "ollama"]);
+const PERMISSIONS = ["ask", "edits", "commands", "auto"];
+const SPINNER_INTERVAL_MS = 80;
+// Review budgets: enough to judge the change, not so much that the prompt
+// scrolls off the screen before you can answer it.
+const DIFF_MAX_LINES = 60;
+const CREATE_PREVIEW_LINES = 16;
+// Below this, the live per-file lines are recap enough on their own.
+const FOOTER_PATH_RECAP_THRESHOLD = 6;
+
+/** Home-relative path, so a turn footer does not wrap on a long absolute one. */
+function shortPath(value) {
+  const home = os.homedir();
+  return value.startsWith(home) ? `~${value.slice(home.length)}` : value;
+}
+
+/** Browser target for the device flow; signup lands on register first. */
+function authUrl(config, userCode, mode) {
+  if (mode === "signup") {
+    const url = new URL(`${config.frontendBaseUrl}/register`);
+    url.searchParams.set("callbackUrl", `/cli-auth?code=${userCode}`);
+    url.searchParams.set("cli", "1");
+    return url.toString();
+  }
+  const url = new URL(`${config.frontendBaseUrl}/cli-auth`);
+  url.searchParams.set("code", userCode);
+  url.searchParams.set("cli", "1");
+  return url.toString();
+}
+
+const ACTIVITY_LABELS = {
+  list_files: "Scanning workspace",
+  search_files: "Searching",
+  search_marketplace: "Searching marketplace",
+  read_repo: "Reading gig source",
+  read_file: "Reading",
+  write_file: "Writing",
+  append_file: "Appending",
+  edit_file: "Editing",
+  delete_file: "Requesting delete",
+  move_file: "Requesting move",
+  run_command: "Running",
+  start_background_command: "Starting background job",
+  check_background_command: "Checking background job",
+  stop_background_command: "Stopping background job",
+  finish_project: "Finalizing",
+};
+
+const OUTCOME_STYLES = {
+  created: (value) => color.green(value),
+  updated: (value) => color.yellow(value),
+  deleted: (value) => color.red(value),
+  moved: (value) => color.yellow(value),
+  skipped: (value) => color.dim(value),
+};
+
+function permissionSummary(value) {
+  if (value === "auto") return "auto edits + commands";
+  if (value === "edits") return "auto edits, ask commands";
+  if (value === "commands") return "ask edits, auto commands";
+  return "review every edit and command";
+}
+
+/**
+ * Render the marketplace gigs the agent found. This is the CLI's counterpart to
+ * the web's gig cards, and the reason the CLI is not just another coding agent:
+ * the user sees the real catalog entries their build is grounded in, priced and
+ * linked, while it happens.
+ *
+ * Lines are returned rather than printed — the screen owns every write.
+ */
+function gigCardLines(query, gigs, columns) {
+  const width = Math.max(20, columns || 80);
+  const INDENT = "         "; // 9 columns, clearing the `    #<id>  ` gutter
+
+  // Every line is clipped against its own prefix, not one shared budget: the
+  // screen counts rows by where text wraps, so a single over-wide line
+  // desynchronizes its erase arithmetic for the rest of the turn.
+  const fit = (text, budget) => {
+    const value = String(text);
+    if (budget < 2) return "";
+    return displayWidth(value) > budget
+      ? `${value.slice(0, Math.max(1, budget - 1))}…`
+      : value;
+  };
+
+  const heading = `${gigs.length} marketplace gig${gigs.length === 1 ? "" : "s"}`;
+  // `  ◆ ` + heading, then ` for "<query>"`.
+  const queryBudget = width - displayWidth(heading) - 4 - 7;
+  const clippedQuery = queryBudget >= 8 ? fit(query, queryBudget) : "";
+
+  const lines = [
+    "",
+    `  ${color.cyan("◆")} ${color.bold(heading)}${
+      clippedQuery ? color.dim(` for "${clippedQuery}"`) : ""
+    }`,
+  ];
+
+  for (const gig of gigs) {
+    const id = `#${gig.id}`;
+    lines.push(
+      `    ${color.cyan(id)}  ${color.bold(
+        fit(gig.title, width - displayWidth(id) - 6)
+      )}`
+    );
+
+    const meta = [
+      typeof gig.price === "number" ? `$${gig.price}` : null,
+      typeof gig.ratings === "number" && gig.ratings > 0
+        ? `★ ${gig.ratings.toFixed(1)}`
+        : null,
+      typeof gig.score === "number" ? `match ${gig.score.toFixed(2)}` : null,
+    ]
+      .filter(Boolean)
+      .join(" · ");
+    const detail = [
+      Array.isArray(gig.tech) && gig.tech.length ? gig.tech.join(", ") : null,
+      meta || null,
+    ]
+      .filter(Boolean)
+      .join("   ");
+
+    const detailBudget = width - INDENT.length;
+    if (detail) lines.push(`${INDENT}${color.dim(fit(detail, detailBudget))}`);
+    if (gig.summary) {
+      lines.push(`${INDENT}${color.dim(fit(gig.summary, detailBudget))}`);
+    }
+    // A clipped URL is a broken URL — drop it rather than print one that
+    // cannot be opened.
+    if (gig.url && displayWidth(gig.url) <= detailBudget) {
+      lines.push(`${INDENT}${color.dim(gig.url)}`);
+    }
+  }
+
+  lines.push("");
+  return lines;
+}
+
+function helpLines(columns = process.stdout.columns || 80) {
+  const rows = [
+    ["/help", "Show this help"],
+    ["/status", "Account, tokens, workspace, model and mode"],
+    ["/doctor", "Diagnose environment and API connectivity"],
+    ["/login [signup]", "Re-authenticate without leaving the session"],
+    ["/mode auto|chat|plan|act", "How the next turns behave"],
+    ["/plan [prompt]", "Toggle plan mode, or plan one prompt"],
+    ["/model [provider] [id]", "Change provider/model for later turns"],
+    ["/permissions [ask|edits|commands|auto]", "Edit and command approvals"],
+    ["/diff", "Show the latest agent turn diff"],
+    ["/undo", "Safely restore the latest agent checkpoint"],
+    ["/jobs [stop <id>|all]", "List or stop background processes"],
+    ["/gigs [query]", "Marketplace gigs from this session, or search"],
+    ["/init [update]", "Write an AGENTS.md so later turns know this project"],
+    ["/new", "Clear this workspace conversation"],
+    ["/compact", "Summarize earlier turns to free up context"],
+    ["/resume", "Show the automatically resumed session"],
+    ["/quit", "Exit the session"],
+  ];
+  const width = Math.max(...rows.map(([name]) => name.length));
+  // `/permissions [ask|edits|commands|auto]` is 38 columns wide, which leaves
+  // almost nothing for the description on an 80-column terminal. Descriptions
+  // used to run past the edge and wrap to column 0, breaking the alignment that
+  // makes a two-column list readable at all. Wrap them under themselves, and on
+  // a terminal too narrow for two columns give the description its own row.
+  const available = Math.max(0, columns - width - 4);
+  const stacked = available < 24;
+  const descWidth = stacked ? Math.max(20, columns - 6) : available;
+
+  return [
+    ...fmt.section("Session commands"),
+    ...rows.flatMap(([name, description]) => {
+      const wrapped = wrap(description, descWidth);
+      if (stacked) {
+        return [
+          `  ${color.cyan(name)}`,
+          ...wrapped.map((piece) => `      ${color.dim(piece)}`),
+        ];
+      }
+      return wrapped.map((piece, i) =>
+        i === 0
+          ? `  ${color.cyan(name.padEnd(width))}  ${color.dim(piece)}`
+          : `  ${" ".repeat(width)}  ${color.dim(piece)}`
+      );
+    }),
+    "",
+    ...fmt.section("Keys"),
+    ...[
+      ["Tab", "Complete a /command or an @path"],
+      ["@path", "Attach a file to the prompt — the agent reads it directly"],
+      ["Enter", "Send · while the agent works, queue a follow-up"],
+      ["Ctrl-J", "Newline without sending"],
+      ["↑ / ↓", "Earlier prompts, including from previous sessions"],
+      ["Esc", "Clear the input, or the queue"],
+      ["Ctrl-C", "Cancel the turn · twice on an empty line to exit"],
+    ].flatMap(([keys, description]) => {
+      const keyWidth = 8;
+      const wrapped = wrap(description, Math.max(20, columns - keyWidth - 6));
+      return wrapped.map((piece, i) =>
+        i === 0
+          ? `  ${color.cyan(keys.padEnd(keyWidth))}  ${color.dim(piece)}`
+          : `  ${" ".repeat(keyWidth)}  ${color.dim(piece)}`
+      );
+    }),
+    "",
+    color.dim("  Paste multi-line text freely — it stays one prompt."),
+  ];
+}
+
+async function runInteractiveShell({
+  session,
+  rootDir: requestedRoot,
+  provider,
+  model,
+  maxFiles,
+  yes,
+  allowCommands,
+  config,
+}) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error(
+      '`devmp` interactive mode needs a terminal. Use `devmp run "…"` in scripts.'
+    );
+  }
+
+  // Declared before anything can call stop(): the composer starts reading
+  // stdin well before the rest of this function has run, so a Ctrl-D during
+  // startup used to reach stop() while these were still in their dead zone and
+  // crash with a raw ReferenceError. stop() touches all three, so all three are
+  // declared here, before anything can call it.
+  let stopped = false;
+  let resolveExit;
+  const exited = new Promise((resolve) => {
+    resolveExit = resolve;
+  });
+
+  const rootDir = path.resolve(requestedRoot || process.cwd());
+  const checkpoints = createCheckpointManager({ rootDir });
+  const saved = (await loadConversation(session.apiBaseUrl, rootDir)) || {};
+  const state = {
+    sessionId: saved.sessionId,
+    history: Array.isArray(saved.history) ? saved.history : [],
+    mode: MODES.has(saved.mode) ? saved.mode : "auto",
+    provider: provider || saved.provider,
+    model: model || saved.model,
+    permissions:
+      yes && allowCommands
+        ? "auto"
+        : yes
+        ? "edits"
+        : allowCommands
+        ? "commands"
+        : PERMISSIONS.includes(saved.permissions)
+        ? saved.permissions
+        : "ask",
+    /** Gigs the agent surfaced this session, newest search first — `/gigs`
+     * reads this. Deliberately in-memory: it is turn context, not a
+     * conversation transcript, and a stale price on resume would mislead. */
+    gigs: [],
+    gigQuery: null,
+    /** Prompt lines for up-arrow recall. Persisted, so the shell remembers
+     *  what you asked it yesterday. */
+    inputHistory: Array.isArray(saved.inputHistory) ? saved.inputHistory : [],
+  };
+
+  const screen = createScreen({ stream: stdout });
+
+  const persist = () =>
+    saveConversation(session.apiBaseUrl, rootDir, {
+      sessionId: state.sessionId,
+      history: state.history,
+      mode: state.mode,
+      provider: state.provider,
+      model: state.model,
+      permissions: state.permissions,
+      inputHistory: state.inputHistory,
+    }).catch(() => undefined);
+
+  // ── live turn state ──────────────────────────────────────────────────────
+  // `active` is non-null exactly while a turn is in flight. Everything the
+  // spinner line shows is read from it, so there is one place to look when the
+  // status line and reality disagree.
+  let active = null;
+  let spinnerTick = 0;
+  let spinnerTimer = null;
+
+  function statusLines() {
+    if (!active) return [];
+    const frame = SPINNER_FRAMES[spinnerTick % SPINNER_FRAMES.length];
+    const parts = [color.cyan(frame), active.label];
+    parts.push(color.dim(formatDuration(Date.now() - active.startedAt)));
+    if (active.detail) parts.push(color.dim(`· ${active.detail}`));
+    if (active.tokens) {
+      parts.push(color.dim(`· ${formatNumber(active.tokens)} tokens`));
+    }
+    const partial = active.markdown ? active.markdown.partial() : [];
+    return [...partial, "", `  ${parts.join(" ")}`];
+  }
+
+  /**
+   * Join hints most-useful-first, dropping the tail rather than wrapping. A
+   * hint row that wraps costs a line of transcript on every redraw, and the
+   * least useful hint is the one worth losing on a narrow terminal.
+   */
+  function fitHints(pieces) {
+    const budget = Math.max(20, screen.columns - 4);
+    const kept = [];
+    let used = 0;
+    for (const piece of pieces) {
+      const cost = kept.length ? piece.length + 3 : piece.length;
+      if (used + cost > budget) break;
+      kept.push(piece);
+      used += cost;
+    }
+    return `  ${(kept.length ? kept : [pieces[0]]).join(" · ")}`;
+  }
+
+  function hintLines() {
+    if (active) {
+      return [
+        color.dim(
+          fitHints([
+            "ctrl-c cancels",
+            "enter queues a follow-up",
+            "esc clears the queue",
+          ])
+        ),
+      ];
+    }
+    if (composer.interruptArmed) {
+      return [color.yellow("  press ctrl-c again to exit")];
+    }
+    return [
+      color.dim(
+        fitHints([
+          "/help for commands",
+          "tab completes",
+          "@file attaches a file",
+          "ctrl-c twice to exit",
+        ])
+      ),
+    ];
+  }
+
+  const composer = createComposer({
+    screen,
+    statusLines,
+    hintLines,
+    promptLabel: () => "›",
+    placeholder: "Describe a task, ask a question, or /help",
+    onSubmit: (value) => void handleSubmit(value),
+    onCancel: () => {
+      // Some waits are not turns (connecting, logging in) and own their own
+      // abort; ask them to stop rather than sending a turn cancellation.
+      if (active?.abort) {
+        active.abort();
+        active.label = "Cancelling";
+        composer.refresh();
+        return;
+      }
+      // Ctrl-C before the tunnel exists can only mean "give up connecting".
+      if (!tunnel) {
+        stop();
+        return;
+      }
+      if (!active?.turnId) return;
+      tunnel.cancel(active.turnId);
+      active.label = "Cancelling";
+      composer.refresh();
+    },
+    onExit: () => stop(),
+    // A big paste is otherwise silent: the box scrolls rather than growing, so
+    // without this there is nothing to confirm the whole thing arrived.
+    completer: (value, caret) => completeInput(rootDir, value, caret),
+    initialHistory: state.inputHistory,
+    onHistoryChange: (list) => {
+      state.inputHistory = list;
+      void persist();
+    },
+    onPaste: (lines) => {
+      if (lines < 4) return;
+      screen.write(
+        color.dim(`  pasted ${lines} lines — enter to send, esc to discard`)
+      );
+    },
+  });
+
+  function startSpinner() {
+    if (spinnerTimer) return;
+    spinnerTimer = setInterval(() => {
+      spinnerTick += 1;
+      composer.refresh();
+    }, SPINNER_INTERVAL_MS);
+    spinnerTimer.unref?.();
+  }
+
+  function stopSpinner() {
+    if (!spinnerTimer) return;
+    clearInterval(spinnerTimer);
+    spinnerTimer = null;
+  }
+
+  // ── connect ──────────────────────────────────────────────────────────────
+  // No standalone banner: the status card's title already carries it, and on
+  // the expired-session retry path the shell runs twice, which printed it twice.
+  composer.start();
+  active = { label: "Connecting", startedAt: Date.now(), markdown: null };
+  startSpinner();
+
+  let tunnel;
+  // The composer accepts input from the moment it starts, which is before the
+  // tunnel has finished connecting. Keeping the in-flight connect lets a prompt
+  // typed during that window wait for it instead of reaching an undefined
+  // tunnel — typing early is a normal thing to do while "Connecting" is on
+  // screen, and it used to end the turn with a TypeError.
+  let connecting;
+  let statusInfo;
+  // Mutable: `/login` replaces the credentials mid-session.
+  let currentSession = session;
+
+  /** Open a tunnel for the given credentials, keeping the conversation id and
+   *  visible history so a reconnect resumes rather than starting over. */
+  const openTunnel = (forSession) =>
+    connectInteractiveSession({
+      session: forSession,
+      rootDir,
+      sessionId: state.sessionId,
+      history: state.history,
+      yes: state.permissions === "edits" || state.permissions === "auto",
+      allowCommands:
+        state.permissions === "commands" || state.permissions === "auto",
+      checkpoint: checkpoints,
+      onSession: (next) => {
+        state.sessionId = next.sessionId;
+        state.history = next.history;
+        void persist();
+      },
+      // Command output must go through the screen, never straight to stdout,
+      // or it lands inside the live region and desyncs the row accounting.
+      onNotice: (text) => screen.write(text),
+    });
+
+  connecting = Promise.all([
+    openTunnel(currentSession),
+    collectStatus({ session: currentSession, rootDir }),
+  ]);
+  try {
+    [tunnel, statusInfo] = await connecting;
+    active = null;
+    stopSpinner();
+  } catch (error) {
+    // The terminal is already in raw mode with a live region painted; hand it
+    // back before the error propagates or the user's shell is left wrecked.
+    active = null;
+    stopSpinner();
+    composer.stop();
+    screen.close();
+    throw error;
+  }
+
+  screen.writeLines(renderStatusCard(statusInfo, { rootDir, env: config?.env, inShell: true }));
+  screen.write(
+    tunnel.session.resumed
+      ? fmt.success(
+          `Conversation resumed · ${Math.floor(
+            (state.history?.length || 0) / 2
+          )} previous turn(s)`
+        )
+      : fmt.success("Interactive session ready.")
+  );
+
+  // Approvals are raised deep inside the executor and command runner, which
+  // have no handle on the shell — the driver is how they reach this screen.
+  setApprovalDriver({
+    showText: (text) => screen.write(`  ${text}`),
+    showDiff: (diff, { isCreate, path } = {}) => {
+      const { added } = diffStats(diff);
+      if (isCreate) {
+        // Show the shape of a new file, not all of it.
+        screen.write(
+          `  ${color.green("create")}  ${path} ${color.dim(`(${added} lines)`)}`
+        );
+        screen.writeLines(
+          styleDiffLines(diff, { indent: "  ", maxLines: CREATE_PREVIEW_LINES })
+        );
+        return;
+      }
+      screen.writeLines(
+        styleDiffLines(diff, { indent: "  ", maxLines: DIFF_MAX_LINES })
+      );
+    },
+    choose: ({ question, hint, choices, defaultValue }) =>
+      composer.question({ question, hint, choices, defaultValue }),
+  });
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    resolveExit();
+  }
+
+  // ── turns ────────────────────────────────────────────────────────────────
+
+  /** Commit any half-finished markdown line before writing something else, so
+   *  narration and tool activity land in the order they actually happened. */
+  function flushPartial() {
+    if (!active?.markdown) return;
+    const rest = active.markdown.flush();
+    if (rest.length) screen.writeLines(rest);
+  }
+
+  function renderDoneLines(event, sawText) {
+    const lines = [];
+    const files = Array.isArray(event.files) ? event.files : [];
+    const changes = Array.isArray(event.localChanges) ? event.localChanges : [];
+
+    if (!sawText && event.summary) lines.push(`  ${event.summary}`);
+
+    if (changes.length) {
+      // Each path was already announced live as it was applied; re-listing them
+      // all here just doubles the output. Recap the count, and only spell out
+      // paths when there were too many to have followed in the stream.
+      lines.push(
+        fmt.success(`${changes.length} reviewed change(s) in ${shortPath(rootDir)}`)
+      );
+      if (changes.length > FOOTER_PATH_RECAP_THRESHOLD) {
+        for (const change of changes) {
+          const style = OUTCOME_STYLES[change.kind] || color.dim;
+          const detail =
+            change.kind === "moved"
+              ? `${change.fromPath} → ${change.path}`
+              : change.path;
+          lines.push(`  ${style(String(change.kind).padEnd(8))} ${detail}`);
+        }
+      }
+      if (event.checkpoint) {
+        lines.push(
+          color.dim(
+            `  checkpoint ${event.checkpoint.id.slice(0, 8)} · /diff or /undo`
+          )
+        );
+      }
+    } else if (files.length) {
+      lines.push(
+        fmt.success(`${files.length} file(s) changed in ${shortPath(rootDir)}`)
+      );
+      for (const file of files) lines.push(`  ${color.dim("changed")}  ${file}`);
+    }
+
+    const commands = Array.isArray(event.executedCommands)
+      ? event.executedCommands
+      : [];
+    if (commands.length) {
+      lines.push(fmt.line("Commands", commandTally(commands)));
+    }
+
+    if (event.checkpointError) {
+      lines.push(fmt.warn(`Checkpoint warning: ${event.checkpointError}`));
+    }
+    if (event.partial) {
+      lines.push(fmt.warn("The turn stopped before the agent reported completion."));
+    }
+
+    const used = event.usage
+      ? Number(event.usage.inputTokens || 0) + Number(event.usage.outputTokens || 0)
+      : 0;
+    const elapsed = active ? Date.now() - active.startedAt : 0;
+    const footer = [];
+    if (used) footer.push(`${formatNumber(used)} tokens`);
+    if (elapsed) footer.push(formatDuration(elapsed));
+    if (footer.length) lines.push(color.dim(`  ${footer.join(" · ")}`));
+
+    return lines;
+  }
+
+  async function runTurn(promptText) {
+    const turnId = randomUUID();
+    const markdown = createMarkdownStream({
+      width: () => screen.columns,
+      indent: "  ",
+    });
+    active = {
+      turnId,
+      startedAt: Date.now(),
+      label: "Thinking",
+      detail: null,
+      tokens: 0,
+      markdown,
+    };
+    let sawText = false;
+
+    screen.writeLines(["", `${color.cyan("›")} ${color.bold(promptText)}`, ""]);
+    composer.setBusy(true);
+    startSpinner();
+
+    if (!tunnel) {
+      // Typed before the connection came up: wait for it rather than fail.
+      await connecting?.catch(() => undefined);
+    }
+    if (!tunnel) {
+      stopSpinner();
+      composer.setBusy(false);
+      active = null;
+      screen.writeLines([fmt.fail("Not connected to the agent yet — try again.")]);
+      return;
+    }
+
+    const mentioned = await expandMentions(rootDir, promptText).catch(() => ({
+      prompt: promptText,
+      attached: [],
+    }));
+    if (mentioned.attached.length) {
+      screen.writeLines([
+        color.dim(
+          `  attached ${mentioned.attached.map((f) => f.path).join(", ")}`,
+        ),
+      ]);
+    }
+
+    const terminal = await tunnel.runTurn({
+      turnId,
+      prompt: mentioned.prompt,
+      mode: state.mode,
+      provider: state.provider,
+      model: state.model,
+      maxFiles,
+      onEvent: (event) => {
+        if (event.type === "text") {
+          sawText = true;
+          active.label = "Responding";
+          const committed = markdown.push(event.delta);
+          if (committed.length) screen.writeLines(committed);
+          composer.refresh();
+          return;
+        }
+        if (event.type === "activity") {
+          flushPartial();
+          active.label = "Working";
+          active.detail = event.detail
+            ? `${ACTIVITY_LABELS[event.tool] || event.tool} ${event.detail}`
+            : ACTIVITY_LABELS[event.tool] || event.tool;
+          screen.write(
+            `  ${color.dim("•")} ${ACTIVITY_LABELS[event.tool] || event.tool}${
+              event.detail ? ` ${color.cyan(event.detail)}` : ""
+            }`
+          );
+          return;
+        }
+        if (event.type === "gigs") {
+          flushPartial();
+          const gigs = Array.isArray(event.gigs) ? event.gigs : [];
+          if (!gigs.length) return;
+          state.gigs = gigs;
+          state.gigQuery = event.query || null;
+          screen.writeLines(
+            gigCardLines(event.query || "", gigs, screen.columns)
+          );
+          composer.refresh();
+          return;
+        }
+        if (event.type === "file-local") {
+          flushPartial();
+          const style = OUTCOME_STYLES[event.outcome] || color.yellow;
+          screen.write(
+            `  ${style(event.outcome)}  ${
+              event.fromPath ? `${event.fromPath} → ` : ""
+            }${event.path}`
+          );
+          return;
+        }
+        if (event.type === "usage" && event.usage) {
+          active.tokens =
+            Number(event.usage.inputTokens || 0) +
+            Number(event.usage.outputTokens || 0);
+          composer.refresh();
+        }
+      },
+    });
+
+    flushPartial();
+    stopSpinner();
+
+    if (terminal.type === "done") {
+      screen.writeLines(renderDoneLines(terminal, sawText));
+      const git = await getGitInfo(rootDir).catch(() => null);
+      if (git?.isRepo) {
+        screen.write(
+          fmt.line("Git", `${git.branch} · ${git.changed} changed path(s)`)
+        );
+      }
+    } else if (terminal.type === "cancelled") {
+      screen.write(fmt.warn("Turn cancelled. You can continue the conversation."));
+      if (terminal.localChanges?.length) {
+        screen.write(
+          fmt.warn(
+            `${terminal.localChanges.length} partial change(s) checkpointed; use /diff or /undo.`
+          )
+        );
+      }
+    } else {
+      screen.write(fmt.fail(terminal.message || "The turn failed."));
+      if (terminal.localChanges?.length) {
+        screen.write(
+          fmt.warn(
+            `${terminal.localChanges.length} partial change(s) checkpointed; use /diff or /undo.`
+          )
+        );
+      }
+    }
+
+    active = null;
+    composer.setBusy(false);
+  }
+
+  // ── re-authentication ────────────────────────────────────────────────────
+
+  /**
+   * Run the device flow without leaving the session, then rebuild the tunnel on
+   * the new credentials. The WebSocket authenticated with the old token, so a
+   * fresh token is only useful once the socket is reopened with it; the
+   * conversation id and visible history carry across, so the session resumes.
+   */
+  async function reauthenticate(mode) {
+    if (active) {
+      screen.write(fmt.warn("Finish or cancel the current turn first."));
+      return;
+    }
+
+    const authConfig = {
+      apiBaseUrl: currentSession.apiBaseUrl,
+      frontendBaseUrl:
+        currentSession.frontendBaseUrl || config?.frontendBaseUrl,
+    };
+    if (!authConfig.frontendBaseUrl) {
+      screen.write(fmt.fail("No frontend URL configured; run `devmp login`."));
+      return;
+    }
+
+    const controller = new AbortController();
+    active = {
+      label: mode === "signup" ? "Waiting for signup" : "Waiting for approval",
+      startedAt: Date.now(),
+      markdown: null,
+      // Ctrl-C during the wait aborts the poll rather than cancelling a turn.
+      abort: () => controller.abort(),
+    };
+    composer.setBusy(true);
+    startSpinner();
+
+    try {
+      const start = await startDeviceAuth(authConfig);
+      const url = authUrl(authConfig, start.userCode, mode);
+      screen.writeLines([
+        "",
+        `  ${color.dim("Code")}  ${color.bold(color.cyan(start.userCode))}`,
+        `  ${color.dim("URL ")}  ${url}`,
+        color.dim("  Approve this in your browser. Ctrl-C to cancel."),
+      ]);
+      if (!openBrowser(url)) {
+        screen.write(fmt.warn("Could not open the browser — use the URL above."));
+      }
+
+      const next = await pollDeviceAuth(authConfig, start, {
+        signal: controller.signal,
+      });
+
+      // Point the new session at the same backend this shell is already
+      // talking to, so a re-login cannot silently move the workspace.
+      currentSession = { ...next, apiBaseUrl: currentSession.apiBaseUrl };
+
+      tunnel.close();
+      tunnel = await openTunnel(currentSession);
+      screen.write(
+        fmt.success(
+          `Signed in as ${currentSession.user?.email || "your account"}.`
+        )
+      );
+
+      const info = await collectStatus({ session: currentSession, rootDir });
+      screen.writeLines(
+        renderStatusCard(info, { rootDir, env: config?.env, inShell: true })
+      );
+    } catch (error) {
+      screen.write(fmt.fail(error?.message || "Login failed."));
+      screen.write(
+        color.dim("  The previous session is unchanged. Try /login again.")
+      );
+    } finally {
+      active = null;
+      stopSpinner();
+      composer.setBusy(false);
+    }
+  }
+
+  // ── slash commands ───────────────────────────────────────────────────────
+
+  /** Returns the prompt to run, or null when the input was fully handled. */
+  async function handleCommand(input) {
+    const [command, ...args] = input.split(/\s+/);
+    const rest = args.join(" ").trim();
+
+    switch (command) {
+      case "/quit":
+      case "/exit":
+        stop();
+        return null;
+
+      case "/help":
+        screen.writeLines(helpLines());
+        return null;
+
+      case "/status": {
+        const info = await collectStatus({ session: currentSession, rootDir });
+        screen.writeLines(
+          renderStatusCard(info, { rootDir, env: config?.env, inShell: true })
+        );
+        const latest = await checkpoints.latest();
+        screen.writeLines([
+          fmt.line("Session", state.sessionId || "new"),
+          fmt.line("Mode", state.mode),
+          fmt.line("Provider", state.provider || "server default"),
+          fmt.line("Model", state.model || "provider default"),
+          fmt.line("Permissions", permissionSummary(state.permissions)),
+          fmt.line("Destructive", "always ask for delete/move"),
+          fmt.line(
+            "History",
+            `${Math.floor((state.history?.length || 0) / 2)} turn(s)`
+          ),
+          fmt.line(
+            "Checkpoint",
+            latest
+              ? `${latest.id.slice(0, 8)} · ${latest.status}${
+                  latest.undoneAt ? " (undone)" : ""
+                }`
+              : "none"
+          ),
+        ]);
+        const running = tunnel.listJobs().filter((job) => job.running);
+        if (running.length) {
+          screen.write(
+            fmt.line(
+              "Jobs",
+              `${running.length} running · ${color.dim("/jobs")}`
+            )
+          );
+        }
+        return null;
+      }
+
+      case "/doctor":
+        screen.writeLines(
+          await renderDoctor({
+            config,
+            session: currentSession,
+            rootDir,
+            inShell: true,
+          })
+        );
+        return null;
+
+      case "/login":
+        await reauthenticate(rest === "signup" ? "signup" : "login");
+        return null;
+
+      case "/diff": {
+        const latest = await checkpoints.latest();
+        if (!latest) {
+          screen.write(fmt.warn("No agent checkpoint exists for this workspace yet."));
+          return null;
+        }
+        screen.writeLines(
+          fmt.section(
+            `Checkpoint ${latest.id.slice(0, 8)}${
+              latest.undoneAt ? " (undone)" : ""
+            }`
+          )
+        );
+        const diff = checkpointDiff(latest);
+        if (diff) screen.writeLines(styleDiffLines(diff));
+        else screen.write(fmt.warn("This checkpoint has no remaining file differences."));
+        return null;
+      }
+
+      case "/undo": {
+        const result = await checkpoints.undoLatest();
+        if (result.ok) {
+          screen.write(
+            fmt.success(
+              `Restored checkpoint ${result.checkpoint.id.slice(0, 8)} (${
+                result.checkpoint.changes.length
+              } change(s)).`
+            )
+          );
+        } else if (result.reason === "conflict") {
+          screen.write(
+            fmt.warn("Undo stopped because these files changed after the agent turn:")
+          );
+          screen.writeLines(result.conflicts.map((file) => `    ${file}`));
+          screen.write(
+            color.dim("  Review or preserve those edits before trying again.")
+          );
+        } else {
+          screen.write(fmt.warn("There is no agent checkpoint to undo."));
+        }
+        return null;
+      }
+
+      case "/jobs": {
+        const jobs = tunnel.listJobs();
+        const [action, target] = args;
+
+        if (action && action !== "stop") {
+          screen.write(
+            fmt.warn(`/jobs has no "${action}" action. Use /jobs or /jobs stop <id>.`)
+          );
+          return null;
+        }
+
+        if (action === "stop") {
+          if (!target) {
+            screen.write(fmt.warn("Usage: /jobs stop <jobId>, or /jobs stop all."));
+            return null;
+          }
+          if (target === "all") {
+            const running = jobs.filter((job) => job.running);
+            if (!running.length) {
+              screen.write(color.dim("  No running background jobs."));
+              return null;
+            }
+            for (const job of running) tunnel.stopJob(job.jobId);
+            screen.write(
+              fmt.success(
+                `Stopping ${running.length} background job${
+                  running.length === 1 ? "" : "s"
+                }.`
+              )
+            );
+            return null;
+          }
+          // Job ids are eight hex characters; nobody types those in full.
+          const matches = jobs.filter((job) => job.jobId.startsWith(target));
+          if (matches.length > 1) {
+            screen.write(
+              fmt.warn(
+                `"${target}" matches ${matches.length} jobs: ${matches
+                  .map((job) => job.jobId)
+                  .join(", ")}.`
+              )
+            );
+            return null;
+          }
+          const id = matches[0]?.jobId ?? target;
+          const result = tunnel.stopJob(id);
+          screen.write(
+            result.found
+              ? result.stopped
+                ? fmt.success(`Stopping background job ${id}.`)
+                : fmt.warn(`Job ${id} had already exited.`)
+              : fmt.warn(`No background job with id ${target}.`)
+          );
+          return null;
+        }
+        if (!jobs.length) {
+          screen.write(
+            color.dim("  No background jobs. The agent starts these itself.")
+          );
+          return null;
+        }
+        screen.writeLines(fmt.section("Background jobs"));
+        screen.writeLines(
+          jobs.map((job) => {
+            const state_ = job.stopping
+              ? color.yellow("stopping")
+              : job.running
+              ? color.green("running")
+              : color.dim(`exited ${job.exitCode ?? "?"}`);
+            return `  ${color.cyan(job.jobId)}  ${state_}  ${job.command}`;
+          })
+        );
+        screen.write(color.dim("  /jobs stop <id> · /jobs stop all"));
+        return null;
+      }
+
+      case "/gigs": {
+        // With a query this becomes an ordinary turn: the agent owns retrieval,
+        // so asking it to search is both simpler and better than bolting a
+        // second search path onto the client.
+        if (rest) {
+          return (
+            `Search the DevMarketplace catalog for: ${rest}. ` +
+            `Show me what matches and which one you would build on, and why.`
+          );
+        }
+        if (!state.gigs.length) {
+          screen.write(
+            color.dim(
+              "  No marketplace gigs yet this session. Ask for something to build, or /gigs <what you need>."
+            )
+          );
+          return null;
+        }
+        screen.writeLines(
+          gigCardLines(state.gigQuery || "", state.gigs, screen.columns)
+        );
+        screen.write(
+          color.dim("  Ask me to build on one by id, e.g. “use #" +
+            state.gigs[0].id + " as the base”.")
+        );
+        return null;
+      }
+
+      case "/init": {
+        // Reading AGENTS.md is already wired in; there was no way to write one.
+        // It is the single highest-leverage file in the workspace: every later
+        // turn is shaped by it.
+        const existing = await findProjectInstructionsFile(rootDir);
+        if (existing && !rest) {
+          screen.write(
+            fmt.warn(`${existing} already exists — I will not overwrite it.`)
+          );
+          screen.write(
+            color.dim(
+              "  Use /init update to have me revise it against the current code."
+            )
+          );
+          return null;
+        }
+        const verb = existing
+          ? `Update ${existing} so it matches the code as it is now`
+          : "Write an AGENTS.md at the workspace root";
+        return (
+          `${verb}. First read enough of this project to describe it ` +
+          "accurately — do not guess. The file is instructions for a coding " +
+          "agent working here, so keep it short and specific: what this " +
+          "project is, how to run it, how to run the tests, the conventions " +
+          "worth following, and anything that would surprise someone new. " +
+          "Leave out anything you could not verify from the code."
+        );
+      }
+
+      case "/resume":
+        screen.write(
+          fmt.success(
+            `Session ${state.sessionId} is active and resumes automatically for this workspace.`
+          )
+        );
+        return null;
+
+      case "/new":
+        await tunnel.reset();
+        state.history = [];
+        await persist();
+        screen.write(
+          fmt.success("Conversation context cleared. Workspace files were not changed.")
+        );
+        return null;
+
+      case "/compact": {
+        const before = state.history.length;
+        const result = await tunnel.compact();
+        await persist();
+        screen.write(
+          result.compacted
+            ? fmt.success(
+                `Context compacted — ${before} → ${result.messages} messages. ` +
+                  "Earlier turns are kept as a summary."
+              )
+            : fmt.warn(
+                "Nothing to compact yet — the conversation is still short enough to keep in full."
+              )
+        );
+        return null;
+      }
+
+      case "/mode":
+        if (!MODES.has(rest)) {
+          screen.write(fmt.warn("Use /mode auto, /mode chat, /mode plan, or /mode act."));
+        } else {
+          state.mode = rest;
+          await persist();
+          screen.write(fmt.success(`Mode set to ${state.mode}.`));
+        }
+        return null;
+
+      case "/plan":
+        if (!rest) {
+          state.mode = state.mode === "plan" ? "auto" : "plan";
+          await persist();
+          screen.write(fmt.success(`Mode set to ${state.mode}.`));
+          return null;
+        }
+        state.mode = "plan";
+        await persist();
+        return rest;
+
+      case "/model":
+        if (!args.length) {
+          screen.writeLines([
+            fmt.line("Provider", state.provider || "server default"),
+            fmt.line("Model", state.model || "provider default"),
+          ]);
+        } else if (PROVIDERS.has(args[0])) {
+          state.provider = args[0];
+          state.model = args.slice(1).join(" ") || undefined;
+          await persist();
+          screen.write(
+            fmt.success(
+              `Provider set to ${state.provider}${
+                state.model ? ` (${state.model})` : ""
+              }.`
+            )
+          );
+        } else {
+          state.model = rest;
+          await persist();
+          screen.write(fmt.success(`Model set to ${state.model}.`));
+        }
+        return null;
+
+      case "/permissions":
+        if (!rest) {
+          screen.write(fmt.line("Permissions", permissionSummary(state.permissions)));
+        } else if (!PERMISSIONS.includes(rest)) {
+          screen.write(fmt.warn("Use /permissions ask, edits, commands, or auto."));
+        } else {
+          state.permissions = rest;
+          tunnel.setPermissions({
+            overwriteAll: rest === "edits" || rest === "auto",
+            commandsAll: rest === "commands" || rest === "auto",
+          });
+          await persist();
+          screen.write(fmt.success(`Permissions set to ${rest}.`));
+          if (rest === "auto") {
+            screen.write(
+              fmt.warn("Edits and commands are auto-approved; delete/move still ask.")
+            );
+          }
+        }
+        return null;
+
+      default:
+        screen.write(fmt.warn(`Unknown session command: ${command}. Type /help.`));
+        return null;
+    }
+  }
+
+  let draining = false;
+
+  /** Run queued prompts one at a time until the queue empties. */
+  async function drainQueue() {
+    if (draining) return;
+    draining = true;
+    try {
+      let next = composer.shiftQueued();
+      while (next && !stopped) {
+        await dispatch(next);
+        next = composer.shiftQueued();
+      }
+    } finally {
+      draining = false;
+    }
+  }
+
+  async function dispatch(value) {
+    if (value.startsWith("/")) {
+      const inlinePrompt = await handleCommand(value);
+      if (!inlinePrompt) return;
+      await runTurn(inlinePrompt);
+      return;
+    }
+    await runTurn(value);
+  }
+
+  async function handleSubmit(value) {
+    if (stopped) return;
+    try {
+      await dispatch(value);
+      await drainQueue();
+    } catch (error) {
+      active = null;
+      stopSpinner();
+      composer.setBusy(false);
+      screen.write(fmt.fail(error?.message || String(error)));
+    }
+  }
+
+  composer.refresh();
+
+  try {
+    await exited;
+  } finally {
+    stopSpinner();
+    clearApprovalDriver();
+    // Say what is about to be killed — a dev server disappearing silently on
+    // exit is the kind of thing you debug for ten minutes.
+    const running = tunnel.listJobs().filter((job) => job.running);
+    composer.stop();
+    screen.close();
+    await tunnel.close();
+    await persist();
+    for (const job of running) {
+      console.log(fmt.warn(`Stopped background job ${job.jobId}: ${job.command}`));
+    }
+    console.log("");
+  }
+}
+
+/**
+ * One-line summary of what a turn's commands did. A background job has no exit
+ * code yet — that is the point of it — so it is counted as started, never as
+ * failed. Counting it as a failure told people their dev server had crashed
+ * while it was in fact running fine.
+ */
+function commandTally(commands) {
+  const started = commands.filter((item) => item.background);
+  const finished = commands.filter((item) => !item.background);
+  const passed = finished.filter((item) => item.exitCode === 0).length;
+  const failed = finished.filter(
+    (item) => !item.refused && item.exitCode !== 0
+  ).length;
+  const refused = finished.filter((item) => item.refused).length;
+
+  const parts = [];
+  if (finished.length) {
+    parts.push(
+      `${passed} passed${failed ? `, ${failed} failed` : ""}${
+        refused ? `, ${refused} skipped` : ""
+      }`
+    );
+  }
+  if (started.length) {
+    parts.push(
+      `${started.length} background job${started.length === 1 ? "" : "s"} started`
+    );
+  }
+  return parts.join(" · ");
+}
+
+module.exports = { runInteractiveShell, helpLines, gigCardLines, commandTally };