chainlesschain 0.162.29 → 0.162.31

package/src/commands/agent.js

@@ -6,7 +6,56 @@
  * AI reads files, writes code, runs commands, and explains what it's doing.
  */
 
+import path from "node:path";
+import fs from "node:fs";
 import { createAgentRuntimeFactory } from "../runtime/runtime-factory.js";
+import { resolvePromptText } from "../runtime/system-prompt.js";
+import { makeFallbackChatFn } from "../runtime/fallback-model.js";
+
+/**
+ * Resolve + validate `--add-dir` values into absolute, existing, de-duped
+ * directories. Invalid entries are skipped with a stderr warning rather than
+ * aborting the run. Relative paths resolve against the process cwd.
+ *
+ * @param {string[]} [rawDirs]
+ * @returns {string[]} absolute directory paths
+ */
+export function resolveAddDirs(rawDirs) {
+  const out = [];
+  for (const d of rawDirs || []) {
+    const abs = path.resolve(process.cwd(), d);
+    try {
+      if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+        if (!out.includes(abs)) out.push(abs);
+      } else {
+        process.stderr.write(`--add-dir: skipping non-directory "${d}"\n`);
+      }
+    } catch {
+      process.stderr.write(`--add-dir: skipping unreadable "${d}"\n`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Read all of stdin as a UTF-8 string. Resolves "" immediately when stdin is a
+ * TTY (nothing piped) so we never block an interactive invocation.
+ */
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
 
 export function registerAgentCommand(program) {
   program
@@ -15,6 +64,10 @@ export function registerAgentCommand(program) {
     .description(
       "Start an agentic AI session (reads/writes files, runs commands)",
     )
+    .argument(
+      "[task...]",
+      "Headless task — when given (or with -p / piped stdin), runs non-interactively",
+    )
     .option("--model <model>", "Model name")
     .option(
       "--provider <provider>",
@@ -23,6 +76,19 @@ export function registerAgentCommand(program) {
     .option("--base-url <url>", "API base URL")
     .option("--api-key <key>", "API key")
     .option("--session <id>", "Resume a previous agent session")
+    .option(
+      "-c, --continue",
+      "Resume the most recent session (no id needed — claude --continue parity)",
+    )
+    .option(
+      "--resume [id]",
+      "Resume a session by id (no id → most recent — claude --resume parity)",
+    )
+    .option(
+      "--add-dir <dir>",
+      "Extra working directory the agent may read/search/edit (repeatable)",
+      (val, prev) => (prev || []).concat([val]),
+    )
     .option("--agent-id <id>", "Agent id for scoped memory recall")
     .option("--recall-limit <n>", "Top-K memories to inject into system prompt")
     .option("--recall-query <q>", "Query string for startup memory recall")
@@ -36,7 +102,235 @@ export function registerAgentCommand(program) {
       "--bundle <path>",
       "Agent bundle directory (chainless-agent.toml + AGENTS.md + skills/ + mcp.json + USER.md)",
     )
-    .action(async (options) => {
+    // ── Headless / print mode (Claude-Code `claude -p` parity) ───────────
+    .option(
+      "-p, --print [prompt]",
+      "Headless: run one non-interactive turn and exit",
+    )
+    .option(
+      "--output-format <fmt>",
+      "Headless output: text | json | stream-json",
+      "text",
+    )
+    .option("--max-turns <n>", "Cap agent loop iterations (headless)")
+    .option(
+      "--allowed-tools <list>",
+      "Comma/space-separated tool allow-list (headless)",
+    )
+    .option(
+      "--disallowed-tools <list>",
+      "Comma/space-separated tool deny-list (headless)",
+    )
+    .option(
+      "--permission-mode <mode>",
+      "default | plan | acceptEdits | bypassPermissions (headless)",
+    )
+    .option(
+      "--no-file-refs",
+      "Disable @path file-reference expansion in the prompt (headless)",
+    )
+    .option(
+      "--system-prompt <text>",
+      "Replace the built-in system prompt (literal text or @file)",
+    )
+    .option(
+      "--append-system-prompt <text>",
+      "Append extra guidance to the system prompt (literal text or @file)",
+    )
+    .option(
+      "--input-format <fmt>",
+      "Headless input: text | stream-json (NDJSON user events on stdin, multi-turn)",
+      "text",
+    )
+    .option(
+      "--fallback-model <model>",
+      "Retry once on this model when the primary fails (overload/network)",
+    )
+    .action(async (task, options) => {
+      // `--continue` / `--resume` resolve a session id so the user need not
+      // copy it. Explicit `--session <id>` always wins. `--resume <id>` targets
+      // a specific session; `--continue` or a bare `--resume` pick the most
+      // recent. All three funnel into `options.session`, which both the headless
+      // runner and the interactive runtime use to replay prior history.
+      if (typeof options.resume === "string" && !options.session) {
+        options.session = options.resume;
+      }
+      if ((options.continue || options.resume === true) && !options.session) {
+        const { bootstrap } = await import("../runtime/bootstrap.js");
+        const ctx = await bootstrap({ verbose: program.opts().verbose });
+        // Headless intent also means "no interactive picker is possible": -p,
+        // a positional task, an explicit --output-format, or a non-TTY stdin.
+        const headlessIntent =
+          options.print !== undefined ||
+          (Array.isArray(task) && task.length > 0) ||
+          options.outputFormat !== "text" ||
+          !process.stdin.isTTY;
+        if (headlessIntent) {
+          // Headless replays the JSONL store only, so resolve "most recent"
+          // from there — a DB-only id would resume into an empty transcript.
+          const { getLastSessionId } =
+            await import("../harness/jsonl-session-store.js");
+          options.session = getLastSessionId();
+        } else {
+          // Interactive: picker across both stores (agent REPL rebuilds either).
+          const { pickRecentSession } =
+            await import("../lib/session-picker.js");
+          const picked = await pickRecentSession(ctx, {
+            message: "Resume which agent session?",
+          });
+          options.session = picked.id;
+        }
+        if (!options.session) {
+          process.stderr.write(
+            "No previous session to continue. Start one with `cc agent`.\n",
+          );
+          process.exit(1);
+        }
+      }
+
+      // Extra workspace roots (--add-dir) — shared by headless + interactive.
+      const additionalDirectories = resolveAddDirs(options.addDir);
+
+      // --fallback-model: a chatFn that retries once on the backup model when
+      // the primary errors out (overload / rate-limit / network). Passed into
+      // the headless runners via options.chatFn (the agent loop's seam), so no
+      // runner changes are needed. Notice goes to stderr to keep stdout clean.
+      const fallbackChatFn = options.fallbackModel
+        ? makeFallbackChatFn({
+            fallbackModel: options.fallbackModel,
+            onFallback: ({ from, to, error }) =>
+              process.stderr.write(
+                `Note: model "${from}" failed (${error}); retrying with --fallback-model "${to}".\n`,
+              ),
+          })
+        : undefined;
+
+      // ── Streaming-input mode (--input-format stream-json) ────────────────
+      // A persistent multi-turn conversation driven by NDJSON user events on
+      // stdin; output is always NDJSON. Routed before single-prompt handling
+      // so stdin is consumed as events, not as one prompt.
+      if (options.inputFormat === "stream-json") {
+        const { runAgentHeadlessStream } =
+          await import("../runtime/headless-stream.js");
+        const { parseToolList } = await import("../runtime/headless-runner.js");
+        const cwd = process.cwd();
+        let outcome;
+        try {
+          outcome = await runAgentHeadlessStream({
+            model: options.model,
+            provider: options.provider,
+            baseUrl: options.baseUrl,
+            apiKey: options.apiKey,
+            sessionId: options.session,
+            permissionMode: options.permissionMode,
+            allowedTools: parseToolList(options.allowedTools),
+            disallowedTools: parseToolList(options.disallowedTools),
+            additionalDirectories,
+            maxTurns: options.maxTurns
+              ? parseInt(options.maxTurns, 10)
+              : undefined,
+            expandFileRefs: options.fileRefs !== false,
+            systemPrompt: resolvePromptText(options.systemPrompt, { cwd }),
+            appendSystemPrompt: resolvePromptText(options.appendSystemPrompt, {
+              cwd,
+            }),
+            chatFn: fallbackChatFn,
+          });
+        } catch (err) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          process.exit(1);
+        }
+        process.exit(outcome.exitCode);
+        return;
+      }
+      if (options.inputFormat && options.inputFormat !== "text") {
+        process.stderr.write(
+          `Invalid --input-format "${options.inputFormat}". Expected: text | stream-json.\n`,
+        );
+        process.exit(1);
+      }
+
+      // Resolve the headless prompt from: --print value, positional task, or
+      // piped stdin (in that precedence). Any of them → headless mode.
+      const positional =
+        Array.isArray(task) && task.length > 0 ? task.join(" ") : "";
+      let prompt = "";
+      if (typeof options.print === "string" && options.print.trim()) {
+        prompt = options.print.trim();
+      } else if (positional) {
+        prompt = positional;
+      }
+      // -p with no inline value, or an explicit --output-format, signals
+      // headless intent; pull the prompt from piped stdin when one is present.
+      const wantsHeadless =
+        options.print !== undefined ||
+        Boolean(positional) ||
+        options.outputFormat !== "text";
+      if (!prompt && (wantsHeadless || !process.stdin.isTTY)) {
+        const piped = (await readStdin()).trim();
+        if (piped) prompt = piped;
+      }
+
+      if (prompt) {
+        // Resume requested onto a session with no headless (JSONL) transcript?
+        // Warn instead of silently starting empty — headless resume rebuilds
+        // from the JSONL store only (DB-only sessions are not replayable here).
+        const resumeRequested =
+          Boolean(options.continue) || options.resume !== undefined;
+        if (resumeRequested && options.session) {
+          const { sessionExists } =
+            await import("../harness/jsonl-session-store.js");
+          if (!sessionExists(options.session)) {
+            process.stderr.write(
+              `Note: no headless transcript for session "${options.session}" — ` +
+                "starting fresh (headless resume reads JSONL sessions only).\n",
+            );
+          }
+        }
+        const { runAgentHeadless, parseToolList } =
+          await import("../runtime/headless-runner.js");
+        const maxTurns = options.maxTurns
+          ? parseInt(options.maxTurns, 10)
+          : undefined;
+        let outcome;
+        try {
+          outcome = await runAgentHeadless({
+            prompt,
+            model: options.model,
+            provider: options.provider,
+            baseUrl: options.baseUrl,
+            apiKey: options.apiKey,
+            sessionId: options.session,
+            // A resolved --session/--continue/--resume id means "replay this
+            // conversation and persist the new turns"; the runner loads prior
+            // history when the id already exists and creates it otherwise.
+            resume: options.session,
+            outputFormat: options.outputFormat,
+            permissionMode: options.permissionMode,
+            allowedTools: parseToolList(options.allowedTools),
+            disallowedTools: parseToolList(options.disallowedTools),
+            additionalDirectories,
+            maxTurns,
+            // commander maps --no-file-refs → options.fileRefs === false
+            expandFileRefs: options.fileRefs !== false,
+            // --system-prompt / --append-system-prompt (literal or @file)
+            systemPrompt: resolvePromptText(options.systemPrompt, {
+              cwd: process.cwd(),
+            }),
+            appendSystemPrompt: resolvePromptText(options.appendSystemPrompt, {
+              cwd: process.cwd(),
+            }),
+            // --fallback-model: retry once on a backup model on transient errors
+            chatFn: fallbackChatFn,
+          });
+        } catch (err) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          process.exit(1);
+        }
+        process.exit(outcome.exitCode);
+        return;
+      }
+
       const runtime = createAgentRuntimeFactory().createAgentRuntime({
         model: options.model,
         provider: options.provider,
@@ -50,6 +344,17 @@ export function registerAgentCommand(program) {
         noStream: options.stream === false, // true when --no-stream
         parkOnExit: options.parkOnExit, // false when --no-park-on-exit
         bundlePath: options.bundle || null,
+        additionalDirectories,
+        // --system-prompt / --append-system-prompt (literal or @file) also
+        // apply to interactive sessions, composed in startAgentRepl.
+        systemPrompt: resolvePromptText(options.systemPrompt, {
+          cwd: process.cwd(),
+        }),
+        appendSystemPrompt: resolvePromptText(options.appendSystemPrompt, {
+          cwd: process.cwd(),
+        }),
+        // --fallback-model also applies interactively (wrapper built in the REPL)
+        fallbackModel: options.fallbackModel || null,
       });
       await runtime.startAgentSession();
     });

package/src/commands/ask.js

@@ -25,9 +25,28 @@ import ora from "ora";
 import { logger } from "../lib/logger.js";
 import { BUILT_IN_PROVIDERS } from "../lib/llm-providers.js";
 import { loadConfig } from "../lib/config-manager.js";
+import { expandFileRefs } from "../runtime/file-ref-expander.js";
 
 const ANDROID_LOCAL_OLLAMA_URL = "http://127.0.0.1:18484";
 
+/**
+ * Expand `@path` file references in the question (Claude-Code parity), unless
+ * disabled. Returns the (possibly augmented) prompt plus any warnings for
+ * typo'd paths. Exported so the wiring is unit-testable without a live LLM.
+ *
+ * @param {string} question
+ * @param {object} [opts] { cwd, enabled }
+ * @returns {{ prompt:string, warnings:string[] }}
+ */
+export function expandQuestionRefs(
+  question,
+  { cwd = process.cwd(), enabled = true } = {},
+) {
+  if (!enabled) return { prompt: question, warnings: [] };
+  const { prompt, warnings } = expandFileRefs(question, { cwd });
+  return { prompt, warnings };
+}
+
 /**
  * Resolve effective Ollama base URL given CLI options, env, and config.
  * Exported for unit testing.
@@ -144,6 +163,10 @@ export function registerAskCommand(program) {
       "--prefer-android-local",
       "Route ollama provider at the Android in-APK LocalLlmServer (127.0.0.1:18484). One-shot equivalent of `cc config set llm.preferAndroidLocal true`.",
     )
+    .option(
+      "--no-file-refs",
+      "Do not expand @path file references in the question",
+    )
     .option("--json", "Output as JSON")
     .action(async (question, options) => {
       const config = loadConfig();
@@ -167,9 +190,20 @@ export function registerAskCommand(program) {
         resolvedOptions.baseUrl = options.baseUrl || config.llm?.baseUrl;
       }
 
+      // Expand @path references (e.g. `cc ask "summarize @notes.md"`) before
+      // sending to the model. The original question is preserved for --json
+      // output; only the LLM sees the injected file contents.
+      const { prompt: expandedQuestion, warnings } = expandQuestionRefs(
+        question,
+        { enabled: options.fileRefs !== false },
+      );
+      for (const w of warnings) {
+        process.stderr.write(`[@ref] ${w}\n`);
+      }
+
       const spinner = ora("Thinking...").start();
       try {
-        const answer = await queryLLM(question, resolvedOptions);
+        const answer = await queryLLM(expandedQuestion, resolvedOptions);
 
         spinner.stop();
 

package/src/commands/checkpoint.js

@@ -0,0 +1,239 @@
+/**
+ * cc checkpoint — manual file-state snapshot / rewind (Claude-Code rewind parity).
+ *
+ *   cc checkpoint create <paths...> [--label <l>]   snapshot files/dirs
+ *   cc checkpoint list                              list checkpoints
+ *   cc checkpoint show <id> [--diff]                manifest, or diff vs current
+ *   cc checkpoint restore <id> [--dry-run] [--force]  roll files back
+ *   cc checkpoint delete <id> [--force]             remove a checkpoint
+ *
+ * Restore takes an automatic safety snapshot of the current contents first, so
+ * a rewind is itself reversible. Distinct from `cc workflow checkpoint`
+ * (workflow execution state, not files).
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+export function registerCheckpointCommand(program) {
+  const cp = program
+    .command("checkpoint")
+    .description("Snapshot / rewind file state (manual checkpoints)");
+
+  cp.command("create <paths...>")
+    .description("Snapshot the given files/directories")
+    .option("--label <label>", "Human label for this checkpoint")
+    .option("--json", "Output as JSON")
+    .action(async (paths, options) => {
+      try {
+        const { createCheckpoint } = await import("../lib/file-checkpoint.js");
+        const m = createCheckpoint(paths, { label: options.label });
+        if (options.json) {
+          console.log(JSON.stringify(m, null, 2));
+          return;
+        }
+        logger.log(
+          chalk.green(`✓ checkpoint ${chalk.bold(m.id)}`) +
+            (m.label ? chalk.gray(`  "${m.label}"`) : ""),
+        );
+        logger.log(chalk.gray(`  ${m.fileCount} file(s) snapshotted`));
+      } catch (err) {
+        logger.error(chalk.red(`checkpoint create failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cp.command("list")
+    .alias("ls")
+    .description("List checkpoints (newest first)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const { listCheckpoints } = await import("../lib/file-checkpoint.js");
+        const all = listCheckpoints();
+        if (options.json) {
+          console.log(JSON.stringify(all, null, 2));
+          return;
+        }
+        if (all.length === 0) {
+          logger.log(
+            chalk.gray(
+              "No checkpoints. Create one: cc checkpoint create <paths...>",
+            ),
+          );
+          return;
+        }
+        for (const c of all) {
+          logger.log(
+            `${chalk.cyan(c.id.padEnd(22))} ${chalk.gray(c.createdAt)}  ` +
+              `${String(c.fileCount).padStart(4)} files` +
+              (c.label ? chalk.gray(`  "${c.label}"`) : ""),
+          );
+        }
+      } catch (err) {
+        logger.error(chalk.red(`checkpoint list failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cp.command("show <id>")
+    .description("Show a checkpoint's files, or its diff vs current state")
+    .option("--diff", "Compare snapshot against current on-disk files")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const { getCheckpoint, diffCheckpoint } =
+          await import("../lib/file-checkpoint.js");
+        if (options.diff) {
+          const d = diffCheckpoint(id);
+          if (options.json) {
+            console.log(JSON.stringify(d, null, 2));
+            return;
+          }
+          logger.log(chalk.bold(`Diff vs current — ${id}`));
+          logger.log(`  ${chalk.yellow("modified")}: ${d.modified.length}`);
+          d.modified.forEach((f) => logger.log(chalk.yellow(`    M ${f}`)));
+          logger.log(`  ${chalk.red("deleted")}:  ${d.deleted.length}`);
+          d.deleted.forEach((f) => logger.log(chalk.red(`    D ${f}`)));
+          logger.log(chalk.gray(`  unchanged: ${d.unchanged.length}`));
+          return;
+        }
+        const m = getCheckpoint(id);
+        if (!m) {
+          logger.error(chalk.red(`no such checkpoint: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+        if (options.json) {
+          console.log(JSON.stringify(m, null, 2));
+          return;
+        }
+        logger.log(chalk.bold(`Checkpoint ${m.id}`));
+        if (m.label) logger.log(chalk.gray(`  label: ${m.label}`));
+        logger.log(
+          chalk.gray(`  created: ${m.createdAt}  files: ${m.fileCount}`),
+        );
+        for (const f of m.files) {
+          logger.log(`  ${chalk.gray(String(f.bytes).padStart(8))}  ${f.rel}`);
+        }
+      } catch (err) {
+        logger.error(chalk.red(`checkpoint show failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cp.command("restore <id>")
+    .description(
+      "Restore files from a checkpoint (auto-snapshots current state first)",
+    )
+    .option("--dry-run", "Show what would change without writing")
+    .option("--force", "Restore without the interactive confirm prompt")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const { restoreCheckpoint, diffCheckpoint } =
+          await import("../lib/file-checkpoint.js");
+
+        if (options.dryRun) {
+          const r = restoreCheckpoint(id, { dryRun: true });
+          if (options.json) {
+            console.log(JSON.stringify(r, null, 2));
+            return;
+          }
+          logger.log(chalk.bold(`Dry-run restore — ${id}`));
+          logger.log(`  would restore: ${r.restored.length} file(s)`);
+          r.restored.forEach((f) => logger.log(chalk.yellow(`    ~ ${f}`)));
+          logger.log(chalk.gray(`  already matching: ${r.unchanged.length}`));
+          if (r.missingBlob.length) {
+            logger.log(
+              chalk.red(`  missing blobs: ${r.missingBlob.join(", ")}`),
+            );
+          }
+          return;
+        }
+
+        // Destructive: overwrites current files. Require --force when not a TTY;
+        // prompt when interactive.
+        if (!options.force) {
+          const d = diffCheckpoint(id);
+          const willChange = d.modified.length + d.deleted.length;
+          if (process.stdin.isTTY) {
+            const { confirm } = await import("@inquirer/prompts");
+            const ok = await confirm({
+              message: `Restore ${id}? ${willChange} file(s) will be overwritten (a safety checkpoint is taken first).`,
+              default: false,
+            }).catch(() => false);
+            if (!ok) {
+              logger.log(chalk.gray("Aborted."));
+              return;
+            }
+          } else {
+            logger.error(
+              chalk.red(
+                `Refusing to restore without --force (non-interactive). ${willChange} file(s) would change. Re-run with --dry-run to preview or --force to proceed.`,
+              ),
+            );
+            process.exitCode = 1;
+            return;
+          }
+        }
+
+        const r = restoreCheckpoint(id);
+        if (options.json) {
+          console.log(JSON.stringify(r, null, 2));
+          return;
+        }
+        logger.log(
+          chalk.green(`✓ restored ${r.restored.length} file(s) from ${id}`),
+        );
+        r.restored.forEach((f) => logger.log(chalk.gray(`    ~ ${f}`)));
+        if (r.safetyId) {
+          logger.log(
+            chalk.gray(
+              `  safety checkpoint of prior state: ${r.safetyId} (undo with: cc checkpoint restore ${r.safetyId})`,
+            ),
+          );
+        }
+        if (r.missingBlob.length) {
+          logger.log(
+            chalk.red(`  missing blobs (skipped): ${r.missingBlob.join(", ")}`),
+          );
+        }
+      } catch (err) {
+        logger.error(chalk.red(`checkpoint restore failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cp.command("delete <id>")
+    .alias("rm")
+    .description("Delete a checkpoint")
+    .option("--force", "Skip confirmation")
+    .action(async (id, options) => {
+      try {
+        const { deleteCheckpoint, getCheckpoint } =
+          await import("../lib/file-checkpoint.js");
+        if (!getCheckpoint(id)) {
+          logger.error(chalk.red(`no such checkpoint: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+        if (!options.force && process.stdin.isTTY) {
+          const { confirm } = await import("@inquirer/prompts");
+          const ok = await confirm({
+            message: `Delete checkpoint ${id}?`,
+            default: false,
+          }).catch(() => false);
+          if (!ok) {
+            logger.log(chalk.gray("Aborted."));
+            return;
+          }
+        }
+        deleteCheckpoint(id);
+        logger.log(chalk.green(`✓ deleted ${id}`));
+      } catch (err) {
+        logger.error(chalk.red(`checkpoint delete failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}