chainlesschain 0.162.33 → 0.162.35

package/src/commands/agents.js

@@ -0,0 +1,193 @@
+/**
+ * cc agents — user-defined subagents (Claude-Code parity, `.claude/agents/*.md`).
+ *
+ *   cc agents list [--json]                  list discovered agents
+ *   cc agents show <name>                    show metadata + system prompt
+ *   cc agents run <name> <task...> [opts]    run the task as this agent (headless)
+ *   cc agents new <name> [--description <d>]  scaffold an agent file
+ *
+ * Each `.claude/agents/<name>.md` (project, recursive) or `~/.claude/agents/`
+ * (personal) defines a subagent: the body is its system prompt; frontmatter
+ * declares `description`, `tools` (allow-list), `model`. `run` maps the agent
+ * onto a one-shot headless run (system prompt + tool scope + model), so a
+ * portable Claude-Code agent definition is runnable as-is. Distinct from `cc
+ * command` (prompt macros) and `cc skill` (AI-invoked capabilities).
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+export function registerAgentsCommand(program) {
+  const cmd = program
+    .command("agents")
+    .description("User-defined subagents (.claude/agents/*.md)");
+
+  // ── list ──────────────────────────────────────────────────────────────
+  cmd
+    .command("list")
+    .alias("ls")
+    .description("List discovered subagents (project + personal)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const { discoverAgents } = await import("../lib/agents.js");
+        const all = discoverAgents(process.cwd());
+        if (options.json) {
+          console.log(JSON.stringify(all, null, 2));
+          return;
+        }
+        if (all.length === 0) {
+          logger.log(
+            chalk.gray(
+              "No subagents found. Create one with: cc agents new <name>",
+            ),
+          );
+          return;
+        }
+        logger.log(chalk.bold(`Subagents (${all.length})`));
+        for (const a of all) {
+          const tools = a.tools ? a.tools.join(",") : "(all)";
+          logger.log(
+            `  ${chalk.cyan(a.name.padEnd(22))} ${chalk.gray(`[${a.scope}]`)} ` +
+              `${a.description || ""}`,
+          );
+          logger.log(
+            chalk.gray(
+              `    tools: ${tools}${a.model ? ` · model: ${a.model}` : ""}`,
+            ),
+          );
+        }
+      } catch (err) {
+        logger.error(chalk.red(`agents list failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── show ──────────────────────────────────────────────────────────────
+  cmd
+    .command("show <name>")
+    .description("Show an agent's metadata + system prompt")
+    .option("--json", "Output as JSON")
+    .action(async (name, options) => {
+      try {
+        const { getAgent } = await import("../lib/agents.js");
+        const a = getAgent(name, process.cwd());
+        if (!a) {
+          logger.error(chalk.red(`no such agent: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        if (options.json) {
+          console.log(JSON.stringify(a, null, 2));
+          return;
+        }
+        logger.log(chalk.bold(a.name) + chalk.gray(`  [${a.scope}]`));
+        if (a.description) logger.log(chalk.gray(`  ${a.description}`));
+        logger.log(
+          chalk.gray(
+            `  tools: ${a.tools ? a.tools.join(",") : "(all)"}` +
+              `${a.model ? ` · model: ${a.model}` : ""}`,
+          ),
+        );
+        logger.log(chalk.gray(`  file: ${a.file}`));
+        logger.log("");
+        logger.log(a.systemPrompt || chalk.gray("(empty system prompt)"));
+      } catch (err) {
+        logger.error(chalk.red(`agents show failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── run ───────────────────────────────────────────────────────────────
+  cmd
+    .command("run <name> [task...]")
+    .description("Run a task headlessly as the named subagent")
+    .option("--output-format <fmt>", "text | json | stream-json", "text")
+    .option("--model <model>", "Override the agent's model")
+    .option("--permission-mode <mode>", "ApprovalGate tier (see cc agent)")
+    .option("--add-dir <dir...>", "Extra workspace roots")
+    .action(async (name, task, options) => {
+      try {
+        const { getAgent } = await import("../lib/agents.js");
+        const a = getAgent(name, process.cwd());
+        if (!a) {
+          logger.error(chalk.red(`no such agent: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        const prompt = Array.isArray(task) ? task.join(" ").trim() : "";
+        if (!prompt) {
+          logger.error(
+            chalk.red(`agents run requires a task, e.g. cc agents run ${name} "review @src/x.js"`),
+          );
+          process.exitCode = 1;
+          return;
+        }
+        const { runAgentHeadless } = await import("../runtime/headless-runner.js");
+        const outcome = await runAgentHeadless({
+          prompt,
+          // The agent file's body becomes the system prompt (its persona).
+          systemPrompt: a.systemPrompt || undefined,
+          // Frontmatter `tools` scopes the run; null = inherit all.
+          allowedTools: a.tools || undefined,
+          model: options.model || a.model || undefined,
+          outputFormat: options.outputFormat,
+          permissionMode: options.permissionMode,
+          additionalDirectories: Array.isArray(options.addDir)
+            ? options.addDir
+            : [],
+        });
+        process.exit(outcome.exitCode);
+      } catch (err) {
+        logger.error(chalk.red(`agents run failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── new (scaffold) ────────────────────────────────────────────────────
+  cmd
+    .command("new <name>")
+    .description("Scaffold a new agent file under .claude/agents/")
+    .option("--description <d>", "Frontmatter description")
+    .option("--tools <list>", "Comma-separated tool allow-list")
+    .option("--personal", "Create under ~/.claude/agents instead of project")
+    .action(async (name, options) => {
+      try {
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const { homedir } = await import("node:os");
+        const safe = String(name).replace(/^\//, "").replace(/:/g, "/");
+        const root = options.personal
+          ? path.join(homedir(), ".claude", "agents")
+          : path.join(process.cwd(), ".claude", "agents");
+        const file = path.join(root, `${safe}.md`);
+        if (fs.existsSync(file)) {
+          logger.error(chalk.red(`already exists: ${file}`));
+          process.exitCode = 1;
+          return;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const toolsLine = options.tools
+          ? `tools: ${options.tools}\n`
+          : "# tools: read_file, search_files   # omit to inherit all tools\n";
+        const tpl = `---
+name: ${safe.replace(/\//g, ":")}
+description: ${options.description || name}
+${toolsLine}---
+
+You are a focused subagent. Describe its role, constraints, and output format
+here — this whole body becomes the system prompt for \`cc agents run ${safe.replace(/\//g, ":")}\`.
+`;
+        fs.writeFileSync(file, tpl, "utf-8");
+        logger.log(chalk.green(`✓ created ${file}`));
+        logger.log(
+          chalk.gray(
+            `  run it with: cc agents run ${safe.replace(/\//g, ":")} "<task>"`,
+          ),
+        );
+      } catch (err) {
+        logger.error(chalk.red(`agents new failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/command.js

@@ -0,0 +1,187 @@
+/**
+ * cc command — user-defined slash-command macros (Claude-Code parity).
+ *
+ *   cc command list [--json]                     list discovered commands
+ *   cc command show <name>                       show metadata + template body
+ *   cc command run <name> [args...] [opts]       expand the template and run it
+ *                                                headlessly (or --print-prompt)
+ *   cc command new <name> [--description <d>]    scaffold a command file
+ *
+ * Commands live in `.claude/commands/` (project, recursive) or
+ * `~/.claude/commands/` (personal). A file `git/commit.md` → command
+ * `git:commit`. Template body
+ * supports $ARGUMENTS / $1..$9, !`bash` bang execution, and @path file refs.
+ * Distinct from skills (AI-invoked); these are macros you run explicitly.
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+export function registerCommandCommand(program) {
+  const cmd = program
+    .command("command")
+    .alias("cmd")
+    .description("User-defined slash-command macros (.claude/commands/*.md)");
+
+  // ── list ──────────────────────────────────────────────────────────────
+  cmd
+    .command("list")
+    .alias("ls")
+    .description("List discovered command macros (project + personal)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const { discoverCommands } = await import("../lib/slash-commands.js");
+        const all = discoverCommands(process.cwd());
+        if (options.json) {
+          console.log(JSON.stringify(all, null, 2));
+          return;
+        }
+        if (all.length === 0) {
+          logger.log(
+            chalk.gray(
+              "No command macros. Create one: cc command new <name>  " +
+                "(or add .claude/commands/<name>.md)",
+            ),
+          );
+          return;
+        }
+        for (const c of all) {
+          const tag =
+            c.scope === "project" ? chalk.cyan("[proj]") : chalk.gray("[pers]");
+          logger.log(
+            `${chalk.bold("/" + c.name.padEnd(22))} ${tag} ${chalk.gray(c.description || "")}` +
+              (c.argumentHint ? chalk.dim(`  ${c.argumentHint}`) : ""),
+          );
+        }
+      } catch (err) {
+        logger.error(chalk.red(`command list failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── show ──────────────────────────────────────────────────────────────
+  cmd
+    .command("show <name>")
+    .description("Show a command's metadata and template body")
+    .option("--json", "Output as JSON")
+    .action(async (name, options) => {
+      try {
+        const { getCommand } = await import("../lib/slash-commands.js");
+        const c = getCommand(name, process.cwd());
+        if (!c) {
+          logger.error(chalk.red(`no such command: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        if (options.json) {
+          console.log(JSON.stringify(c, null, 2));
+          return;
+        }
+        logger.log(
+          chalk.bold(`/${c.name}`) + `  ${chalk.gray(`[${c.scope}]`)}`,
+        );
+        if (c.description) logger.log(chalk.gray(`  ${c.description}`));
+        if (c.argumentHint) logger.log(chalk.gray(`  args: ${c.argumentHint}`));
+        if (c.model) logger.log(chalk.gray(`  model: ${c.model}`));
+        if (c.allowedTools)
+          logger.log(chalk.gray(`  allowed-tools: ${c.allowedTools}`));
+        logger.log(chalk.gray(`  file: ${c.file}`));
+        logger.log(chalk.dim("  ───"));
+        logger.log(c.body);
+      } catch (err) {
+        logger.error(chalk.red(`command show failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── run ───────────────────────────────────────────────────────────────
+  cmd
+    .command("run <name> [args...]")
+    .description("Expand a command template and run it headlessly")
+    .option("--print-prompt", "Print the expanded prompt without running it")
+    .option("--no-bang", "Do not execute !`cmd` bang segments")
+    .option("--output-format <fmt>", "text | json | stream-json", "text")
+    .option("--model <model>", "Override the model")
+    .option("--permission-mode <mode>", "ApprovalGate tier (see cc agent)")
+    .action(async (name, args, options) => {
+      try {
+        const { getCommand, expandCommand } =
+          await import("../lib/slash-commands.js");
+        const c = getCommand(name, process.cwd());
+        if (!c) {
+          logger.error(chalk.red(`no such command: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        const { prompt, warnings } = expandCommand(c, args, {
+          cwd: process.cwd(),
+          allowBang: options.bang !== false, // commander maps --no-bang → bang:false
+        });
+        for (const w of warnings) process.stderr.write(`  @ref: ${w}\n`);
+
+        if (options.printPrompt) {
+          console.log(prompt);
+          return;
+        }
+
+        const { runAgentHeadless, parseToolList } =
+          await import("../runtime/headless-runner.js");
+        const outcome = await runAgentHeadless({
+          prompt,
+          outputFormat: options.outputFormat,
+          model: options.model || c.model || undefined,
+          permissionMode: options.permissionMode,
+          // A command's frontmatter allowed-tools scopes the run.
+          allowedTools: parseToolList(c.allowedTools),
+        });
+        process.exit(outcome.exitCode);
+      } catch (err) {
+        logger.error(chalk.red(`command run failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── new (scaffold) ────────────────────────────────────────────────────
+  cmd
+    .command("new <name>")
+    .description("Scaffold a new command file under .claude/commands/")
+    .option("--description <d>", "Frontmatter description")
+    .option("--personal", "Create under ~/.claude/commands instead of project")
+    .action(async (name, options) => {
+      try {
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const { homedir } = await import("node:os");
+        const safe = String(name).replace(/^\//, "").replace(/:/g, "/");
+        const root = options.personal
+          ? path.join(homedir(), ".claude", "commands")
+          : path.join(process.cwd(), ".claude", "commands");
+        const file = path.join(root, `${safe}.md`);
+        if (fs.existsSync(file)) {
+          logger.error(chalk.red(`already exists: ${file}`));
+          process.exitCode = 1;
+          return;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tpl = `---
+description: ${options.description || name}
+argument-hint: "[args]"
+---
+
+Describe the task here. Use $ARGUMENTS for all args, $1/$2 for positional,
+@path to inline file contents, and !\`git status\` to splice in command output.
+`;
+        fs.writeFileSync(file, tpl, "utf-8");
+        logger.log(chalk.green(`✓ created ${file}`));
+        logger.log(
+          chalk.gray(
+            `  run it with: cc command run ${safe.replace(/\//g, ":")} <args>`,
+          ),
+        );
+      } catch (err) {
+        logger.error(chalk.red(`command new failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/context.js

@@ -0,0 +1,189 @@
+/**
+ * cc context [sessionId] — context-window token breakdown for a session.
+ *
+ * Shows how a session's stored conversation fills the model context window,
+ * grouped by role (system / user / assistant / tool), with the share each takes
+ * and the headroom remaining. Reuses the SAME token estimator + window table as
+ * the headless auto-compactor (prompt-compressor.js) and the JSONL session store
+ * (rebuildMessages) — no new data is collected, this is purely a reporting view.
+ *
+ * Complements `cc cost` ($ spend) and `cc session usage` (raw token counts):
+ * this is the "how full is the window right now" view (Claude-Code `/context`).
+ *
+ *   cc context                       # most-recent headless session
+ *   cc context <sessionId>
+ *   cc context --model claude-sonnet-4-6   # size against a specific window
+ *   cc context --json
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+/**
+ * Bucket message tokens by role. tool_calls carried on assistant messages are
+ * counted separately so the breakdown reflects what actually fills the window.
+ */
+export function categorizeContext(messages, estimateTokens) {
+  const buckets = { system: 0, user: 0, assistant: 0, tool: 0, toolCalls: 0 };
+  const counts = { system: 0, user: 0, assistant: 0, tool: 0 };
+  for (const m of messages) {
+    if (!m) continue;
+    const role =
+      m.role === "system" || m.role === "user" || m.role === "tool"
+        ? m.role
+        : "assistant";
+    const content =
+      typeof m.content === "string"
+        ? m.content
+        : JSON.stringify(m.content || "");
+    buckets[role] += estimateTokens(content);
+    counts[role] += 1;
+    if (Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      buckets.toolCalls += estimateTokens(JSON.stringify(m.tool_calls));
+    }
+  }
+  const total =
+    buckets.system +
+    buckets.user +
+    buckets.assistant +
+    buckets.tool +
+    buckets.toolCalls;
+  return { buckets, counts, total };
+}
+
+function bar(frac, width = 24) {
+  const f = Math.max(0, Math.min(1, frac || 0));
+  const filled = Math.round(f * width);
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+export function registerContextCommand(program) {
+  program
+    .command("context")
+    .description(
+      "Context-window token breakdown for a session (Claude-Code /context parity)",
+    )
+    .argument("[id]", "Session ID (omit for the most-recent headless session)")
+    .option("--model <model>", "Size against this model's context window")
+    .option("--provider <provider>", "Provider (for the window default)")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      const {
+        rebuildMessages,
+        getLastSessionId,
+        sessionExists,
+        readEvents,
+      } = await import("../harness/jsonl-session-store.js");
+      const { estimateTokens, getContextWindow } = await import(
+        "../harness/prompt-compressor.js"
+      );
+
+      const sessionId = id || getLastSessionId();
+      if (!sessionId) {
+        logger.error(
+          'No session found. Run a headless agent with `--session <id>` first, or pass a session id.',
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (!sessionExists(sessionId)) {
+        logger.error(
+          `No headless transcript for session "${sessionId}" (headless sessions are JSONL-only).`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      const messages = rebuildMessages(sessionId) || [];
+
+      // Auto-detect the session's model/provider from its session_start header,
+      // overridable by flags so you can size the same transcript against a
+      // different window.
+      let recordedModel = "";
+      let recordedProvider = "";
+      try {
+        const start = (readEvents(sessionId) || []).find(
+          (e) => e.type === "session_start",
+        );
+        recordedModel = start?.data?.model || "";
+        recordedProvider = start?.data?.provider || "";
+      } catch {
+        // header optional — fall through to flags/defaults
+      }
+      const model = options.model || recordedModel || null;
+      const provider = options.provider || recordedProvider || "ollama";
+      const window = getContextWindow(model, provider);
+
+      const { buckets, counts, total } = categorizeContext(
+        messages,
+        estimateTokens,
+      );
+      const used = window > 0 ? total / window : 0;
+      const remaining = Math.max(0, window - total);
+
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              sessionId,
+              model: model || null,
+              provider,
+              contextWindow: window,
+              totalTokens: total,
+              usedFraction: Number(used.toFixed(4)),
+              remainingTokens: remaining,
+              messageCount: messages.length,
+              breakdown: buckets,
+              counts,
+              overflows: total > window,
+            },
+            null,
+            2,
+          ),
+        );
+        return;
+      }
+
+      logger.log(chalk.bold(`Context — session ${chalk.gray(sessionId.slice(0, 28))}`));
+      logger.log(
+        chalk.gray(
+          `  model ${model || "(default)"} · provider ${provider} · ` +
+            `window ${window.toLocaleString()} tokens · ${messages.length} messages`,
+        ),
+      );
+      logger.log("");
+
+      const rows = [
+        ["system", buckets.system, counts.system],
+        ["user", buckets.user, counts.user],
+        ["assistant", buckets.assistant, counts.assistant],
+        ["tool results", buckets.tool, counts.tool],
+        ["tool calls", buckets.toolCalls, null],
+      ];
+      for (const [label, tok, cnt] of rows) {
+        if (!tok) continue;
+        const frac = total ? tok / total : 0;
+        logger.log(
+          `  ${label.padEnd(13)} ${String(tok).padStart(7)}  ` +
+            `${chalk.cyan(bar(frac))} ${String(Math.round(frac * 100)).padStart(3)}%` +
+            `${cnt != null ? chalk.gray(`  (${cnt})`) : ""}`,
+        );
+      }
+
+      logger.log("");
+      const pct = (used * 100).toFixed(1);
+      const color = used > 0.9 ? chalk.red : used > 0.7 ? chalk.yellow : chalk.green;
+      logger.log(
+        `  ${chalk.bold("total".padEnd(11))} ${String(total).padStart(7)}  ` +
+          `${color(bar(used))} ${color(`${pct}% of window`)}`,
+      );
+      logger.log(
+        chalk.gray(`  headroom      ${String(remaining).padStart(7)} tokens remaining`),
+      );
+      if (total > window) {
+        logger.log(
+          chalk.red("  ⚠ exceeds the model context window — compaction required"),
+        );
+      }
+    });
+}

package/src/index.js

@@ -57,8 +57,11 @@ import { registerPermMemCommand } from "./commands/permmem.js";
 import { registerRCacheCommand } from "./commands/rcache.js";
 import { registerSessionCommand } from "./commands/session.js";
 import { registerCostCommand } from "./commands/cost.js";
+import { registerContextCommand } from "./commands/context.js";
+import { registerAgentsCommand } from "./commands/agents.js";
 import { registerCheckpointCommand } from "./commands/checkpoint.js";
 import { registerGoalCommand } from "./commands/goal.js";
+import { registerCommandCommand } from "./commands/command.js";
 import { registerCompactCommand } from "./commands/compact.js";
 import { registerConsolCommand } from "./commands/consol.js";
 import { registerImportCommand } from "./commands/import.js";
@@ -453,8 +456,11 @@ export function createProgram(opts = {}) {
   registerRCacheCommand(program);
   registerSessionCommand(program);
   registerCostCommand(program);
+  registerContextCommand(program);
+  registerAgentsCommand(program);
   registerCheckpointCommand(program);
   registerGoalCommand(program);
+  registerCommandCommand(program);
   registerCompactCommand(program);
   registerConsolCommand(program);