chainlesschain 0.162.32 → 0.162.34

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,10 @@ 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 { 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 +455,10 @@ export function createProgram(opts = {}) {
   registerRCacheCommand(program);
   registerSessionCommand(program);
   registerCostCommand(program);
+  registerContextCommand(program);
   registerCheckpointCommand(program);
   registerGoalCommand(program);
+  registerCommandCommand(program);
   registerCompactCommand(program);
   registerConsolCommand(program);
 

package/src/lib/goal-assess.js

@@ -0,0 +1,228 @@
+/**
+ * goal-assess — run-end LLM self-assessment of goal progress (cc goal Phase 2).
+ *
+ * After an agent run bound to a goal (--goal-assess), an LLM is asked to judge,
+ * from the run transcript, whether the goal advanced — and to propose key-result
+ * updates, a one-line progress note, and any concerns. The proposal is then
+ * persisted through goal-store (progress / key results / agent note / drift).
+ *
+ * This is OPT-IN because it spends extra tokens (one bonus completion per run).
+ * The LLM call is injected as `chat(promptString) => Promise<string>` so the
+ * orchestration is deterministically unit-testable without a provider.
+ *
+ * Parsing is deliberately tolerant: models wrap JSON in prose / code fences, so
+ * we extract the first balanced `{...}` block and validate the fields we use.
+ */
+
+import {
+  recordProgress,
+  setKeyResult,
+  addDriftFlags,
+  getGoal,
+} from "./goal-store.js";
+
+/** Bound the transcript we feed the judge so the assessment stays cheap. */
+const MAX_FINAL_TEXT = 2000;
+const MAX_TOOLS = 40;
+
+/**
+ * Build the assessment prompt. Asks for a strict JSON object describing whether
+ * the goal advanced + proposed updates.
+ * @param {object} goal
+ * @param {object} transcript { prompt, finalText, toolCalls:[{tool,args}] }
+ */
+export function buildAssessPrompt(goal, transcript = {}) {
+  const krLines = (goal.keyResults || [])
+    .map(
+      (k) =>
+        `  - id=${k.id} | "${k.text}"` +
+        (k.target != null ? ` | ${k.current ?? 0}/${k.target}` : "") +
+        (k.done ? " | DONE" : ""),
+    )
+    .join("\n");
+
+  const tools = (transcript.toolCalls || [])
+    .slice(0, MAX_TOOLS)
+    .map((t) => t.tool)
+    .join(", ");
+
+  const finalText = String(transcript.finalText || "").slice(0, MAX_FINAL_TEXT);
+
+  return [
+    "You are assessing whether a single agent run advanced a long-running goal.",
+    "",
+    `GOAL: ${goal.objective}`,
+    `CURRENT PROGRESS: ${goal.progress ?? 0}%`,
+    goal.keyResults?.length
+      ? `KEY RESULTS:\n${krLines}`
+      : "KEY RESULTS: (none)",
+    "",
+    `RUN TASK: ${String(transcript.prompt || "").slice(0, 500)}`,
+    tools ? `TOOLS USED: ${tools}` : "TOOLS USED: (none)",
+    `RUN RESULT:\n${finalText || "(no final text)"}`,
+    "",
+    "Reply with ONLY a JSON object (no prose, no code fence) of this shape:",
+    "{",
+    '  "advanced": true|false,            // did this run move the goal forward?',
+    '  "progress": <0-100 or null>,        // your estimate of new overall progress, or null to leave unchanged',
+    '  "keyResults": [                     // updates for specific key results (omit if none)',
+    '    {"id": "<kr-id>", "current": <number or null>, "done": true|false}',
+    "  ],",
+    '  "note": "<one short sentence summarizing what changed>",',
+    '  "concerns": ["<short concern>", ...]   // anything blocking/at-risk (omit if none)',
+    "}",
+  ].join("\n");
+}
+
+/**
+ * Tolerantly parse the judge's reply into a normalized assessment, or null.
+ * @param {string} text
+ * @returns {{advanced:boolean, progress:number|null, keyResults:object[], note:string, concerns:string[]}|null}
+ */
+export function parseAssessment(text) {
+  if (!text || typeof text !== "string") return null;
+  const json = extractFirstJsonObject(text);
+  if (!json) return null;
+  let obj;
+  try {
+    obj = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== "object") return null;
+
+  const progress =
+    obj.progress == null || obj.progress === "" ? null : clampPct(obj.progress);
+
+  const keyResults = Array.isArray(obj.keyResults)
+    ? obj.keyResults
+        .filter((k) => k && k.id)
+        .map((k) => ({
+          id: String(k.id),
+          current:
+            k.current == null || k.current === "" ? null : Number(k.current),
+          done: k.done === true,
+        }))
+    : [];
+
+  const concerns = Array.isArray(obj.concerns)
+    ? obj.concerns.map((c) => String(c)).filter(Boolean)
+    : [];
+
+  return {
+    advanced: obj.advanced === true,
+    progress,
+    keyResults,
+    note: obj.note ? String(obj.note) : "",
+    concerns,
+  };
+}
+
+function clampPct(v) {
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(100, n));
+}
+
+/** Extract the first balanced top-level {...} block from text (fence-tolerant). */
+function extractFirstJsonObject(text) {
+  const start = text.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Persist a parsed assessment to the goal via goal-store. Each sub-update is
+ * isolated (a bad key-result id can't void the progress note). Returns the
+ * final goal state.
+ * @param {string} goalId
+ * @param {object} a  output of parseAssessment
+ * @param {object} [opts] { root }
+ */
+export function applyAssessment(goalId, a, opts = {}) {
+  if (!a) return getGoal(goalId, opts);
+
+  // Key-result updates first (they may drive derived progress).
+  for (const kr of a.keyResults || []) {
+    try {
+      setKeyResult(goalId, kr.id, { current: kr.current, done: kr.done }, opts);
+    } catch {
+      /* unknown / stale key-result id — skip, don't void the rest */
+    }
+  }
+
+  // Explicit progress and/or the agent note.
+  if (a.progress != null || a.note) {
+    try {
+      recordProgress(
+        goalId,
+        { pct: a.progress, note: a.note, by: "agent" },
+        opts,
+      );
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // Drift: a no-advance run, plus any explicit concerns.
+  const flags = [];
+  if (!a.advanced) {
+    flags.push({ kind: "no-progress", detail: "run did not advance the goal" });
+  }
+  for (const c of a.concerns || []) flags.push({ kind: "concern", detail: c });
+  if (flags.length) {
+    try {
+      addDriftFlags(goalId, flags, opts);
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  return getGoal(goalId, opts);
+}
+
+/**
+ * Full orchestration: prompt → chat → parse → apply. Returns
+ * `{ assessment, goal }` (assessment is null when the judge gave no usable JSON).
+ * @param {object} params { goal, transcript, chat, opts }
+ *        chat: (promptString) => Promise<string>
+ */
+export async function assessGoalProgress({
+  goal,
+  transcript,
+  chat,
+  opts = {},
+}) {
+  if (!goal || typeof chat !== "function") {
+    return { assessment: null, goal: goal || null };
+  }
+  const prompt = buildAssessPrompt(goal, transcript);
+  let reply;
+  try {
+    reply = await chat(prompt);
+  } catch {
+    return { assessment: null, goal };
+  }
+  const assessment = parseAssessment(reply);
+  if (!assessment) return { assessment: null, goal };
+  const updated = applyAssessment(goal.id, assessment, opts);
+  return { assessment, goal: updated };
+}

package/src/lib/goal-store.js

@@ -270,6 +270,39 @@ export function setStatus(id, status, opts = {}) {
   );
 }
 
+/**
+ * Append drift flags to a goal's `drift.flags` list. Each flag is normalized to
+ * `{ at, kind, detail }`. Used by the run-end assessment (cc goal Phase 2) to
+ * record "no progress this run" / concern signals. Capped at 20 (newest kept).
+ * @param {string} id
+ * @param {Array<string|object>} flags
+ */
+export function addDriftFlags(id, flags, opts = {}) {
+  const list = (Array.isArray(flags) ? flags : [flags]).filter(Boolean);
+  if (list.length === 0) return getGoal(id, opts);
+  return mutate(
+    id,
+    (g) => {
+      for (const f of list) {
+        const flag =
+          typeof f === "string"
+            ? { at: nowIso(), kind: "concern", detail: f }
+            : {
+                at: nowIso(),
+                kind: f.kind || "concern",
+                detail: f.detail || "",
+              };
+        g.drift.flags.push(flag);
+      }
+      // Keep only the most recent 20 to bound the file size.
+      if (g.drift.flags.length > 20) {
+        g.drift.flags = g.drift.flags.slice(-20);
+      }
+    },
+    opts,
+  );
+}
+
 /** Delete a goal. Returns true if it existed. */
 export function deleteGoal(id, opts = {}) {
   const root = opts.root || defaultRoot();