chainlesschain 0.162.159 → 0.162.161

package/src/lib/event-seq-replay.js

@@ -0,0 +1,167 @@
+/**
+ * Event-stream gap-detection + replay primitives — the server→client (event)
+ * counterpart to the client→server RemoteCommandLedger (harness/
+ * remote-command-ledger.js). Both give a reconnecting peer an at-most-once,
+ * totally-ordered view over a lossy transport; the ledger orders *commands*,
+ * this orders *events*.
+ *
+ * A producer keeps a bounded buffer of recently emitted, seq-stamped frames
+ * (EventReplayBuffer); a reconnecting consumer reports its last-seen seq and
+ * gets the tail re-sent, or is told to full-resync when the missed range has
+ * already been evicted. A consumer detects holes with SeqGapTracker.
+ *
+ * Pure + deterministic: no I/O, no timers, no globals. The `seq` it stamps is
+ * the same additive protocol-v1 notion used on the stream-json surface
+ * (agent-sdk docs/PROTOCOL.md §1.2.1) — 1-based, monotonic, per producer
+ * instance; consumers MUST tolerate its absence and MUST NOT require gap-free
+ * numbering across a producer restart (a fresh instance rewinds to 1).
+ */
+
+const DEFAULT_MAX_EVENTS = 512;
+const DEFAULT_MAX_BYTES = 1 << 20; // 1 MiB — bound memory on a chatty session
+
+/** Best-effort byte size of a frame (overridable for deterministic tests). */
+function approxBytes(frame) {
+  try {
+    return Buffer.byteLength(JSON.stringify(frame));
+  } catch {
+    return 0; // circular / unserializable — don't let sizing throw
+  }
+}
+
+/**
+ * Producer-side bounded replay buffer. `record(frame)` stamps the next `seq`
+ * onto a shallow copy, retains it (evicting the oldest beyond count/byte
+ * bounds), and returns the stamped frame ready to send. `replaySince(cursor)`
+ * returns the frames a consumer with last-seen seq `cursor` still needs.
+ */
+export class EventReplayBuffer {
+  constructor({
+    maxEvents = DEFAULT_MAX_EVENTS,
+    maxBytes = DEFAULT_MAX_BYTES,
+    sizeOf,
+  } = {}) {
+    this._max = Math.max(1, Math.floor(maxEvents) || DEFAULT_MAX_EVENTS);
+    this._maxBytes = Math.max(0, Math.floor(maxBytes) || 0);
+    this._sizeOf = typeof sizeOf === "function" ? sizeOf : approxBytes;
+    this._buf = []; // [{ seq, frame, bytes }] oldest → newest
+    this._seq = 0;
+    this._bytes = 0;
+  }
+
+  /** Highest seq stamped so far (0 before anything is recorded). */
+  get latestSeq() {
+    return this._seq;
+  }
+
+  /** Oldest seq still retained (== latestSeq when the buffer is empty). */
+  get oldestSeq() {
+    return this._buf.length ? this._buf[0].seq : this._seq;
+  }
+
+  /** Number of frames currently retained. */
+  get size() {
+    return this._buf.length;
+  }
+
+  /**
+   * Stamp the next seq onto `frame` (shallow copy), retain it, evict overflow.
+   * @returns the stamped frame (`{ ...frame, seq }`) to hand straight to send.
+   */
+  record(frame) {
+    const seq = ++this._seq;
+    const stamped = { ...frame, seq };
+    const bytes = this._sizeOf(stamped) || 0;
+    this._buf.push({ seq, frame: stamped, bytes });
+    this._bytes += bytes;
+    this._evict();
+    return stamped;
+  }
+
+  _evict() {
+    // Always keep at least the newest frame even if it alone exceeds maxBytes.
+    while (
+      this._buf.length > this._max ||
+      (this._maxBytes > 0 &&
+        this._bytes > this._maxBytes &&
+        this._buf.length > 1)
+    ) {
+      const dropped = this._buf.shift();
+      this._bytes -= dropped.bytes;
+    }
+  }
+
+  /**
+   * Frames a consumer whose last-seen seq is `cursor` still needs.
+   *  - `cursor >= latestSeq` → nothing missed → `{ frames: [], truncated: false }`.
+   *  - `cursor` still within the retained window → the exact tail after it.
+   *  - `cursor` older than what's retained → the gap was evicted →
+   *    `truncated: true` (consumer MUST full-resync; the returned frames are
+   *    only the retained suffix, not the whole hole).
+   * @param {number} cursor last seq the consumer acknowledged (default 0 = all)
+   */
+  replaySince(cursor = 0) {
+    const c = Number.isFinite(cursor) ? cursor : 0;
+    if (c >= this._seq) {
+      return { frames: [], truncated: false, from: c, to: this._seq };
+    }
+    // The lowest cursor we can honor without a hole is (oldest retained − 1).
+    const floor = this._buf.length ? this._buf[0].seq - 1 : this._seq;
+    const truncated = c < floor;
+    const frames = this._buf.filter((e) => e.seq > c).map((e) => e.frame);
+    return { frames, truncated, from: c, to: this._seq };
+  }
+}
+
+const OK = Object.freeze({ status: "ok" });
+
+/**
+ * Consumer-side sequence tracker. Feed it each received frame's `seq`; it
+ * reports contiguity so the consumer can request a replay on a hole and drop
+ * duplicates a reconnect re-sent. One tracker per producer epoch — reset it
+ * when the transport hands you a fresh producer instance (e.g. a non-reattach
+ * bg-attach reply), since a fresh producer rewinds seq to 1.
+ */
+export class SeqGapTracker {
+  constructor() {
+    this._last = 0;
+    this._started = false;
+  }
+
+  /** Last contiguous seq accepted (0 before the first frame). */
+  get lastSeq() {
+    return this._last;
+  }
+
+  /**
+   * @param {number} seq the received frame's seq (absent/NaN on older
+   *   producers that don't stamp — treated as always-ok, never a gap).
+   * @returns {{status:"ok"}|{status:"duplicate"}|{status:"gap",from:number,to:number}}
+   *   - `ok`: contiguous (or the first frame, or an unstamped frame).
+   *   - `duplicate`: `seq <= lastSeq` — already seen; drop it.
+   *   - `gap`: `seq > lastSeq + 1` — frames `(from, to)` were missed; ask the
+   *     producer for `replaySince(from)`. The tracker adopts `to` as current.
+   */
+  observe(seq) {
+    if (!Number.isFinite(seq)) return OK; // unstamped producer — tolerate
+    if (!this._started) {
+      this._started = true;
+      this._last = seq;
+      return OK;
+    }
+    if (seq === this._last + 1) {
+      this._last = seq;
+      return OK;
+    }
+    if (seq <= this._last) return { status: "duplicate" };
+    const from = this._last;
+    this._last = seq; // adopt new position; caller replays the (from, to) hole
+    return { status: "gap", from, to: seq };
+  }
+
+  /** Forget all history (call when attaching to a fresh producer instance). */
+  reset() {
+    this._last = 0;
+    this._started = false;
+  }
+}

package/src/lib/exit-codes.cjs

@@ -0,0 +1,77 @@
+/**
+ * Headless exit-code taxonomy (gap-analysis 2026-07-11, P0 "确定性 Headless"):
+ * scripted callers can tell apart WHY a run ended without parsing stderr.
+ *
+ * Backward compatibility: every failure is still non-zero, 0 stays success,
+ * 2 stays "settings hook blocked the prompt" (pre-existing), 130/143 stay the
+ * signal-interrupt codes. The new codes carve budget/turn exhaustion and
+ * config errors out of the generic 1.
+ */
+
+const HEADLESS_EXIT_CODES = Object.freeze({
+  OK: 0,
+  /** generic failure (tool/loop/unclassified error) */
+  ERROR: 1,
+  /** a settings hook blocked the prompt (pre-existing semantic) */
+  HOOK_BLOCKED: 2,
+  /** the turn budget (--max-turns / loop iteration cap) ran out first */
+  MAX_TURNS: 3,
+  /** the --max-budget-usd cost cap stopped the run */
+  MAX_BUDGET: 4,
+  /** the LLM call itself failed (provider/model/network error) */
+  MODEL_ERROR: 5,
+  /** bad run configuration (--mcp-config / --permission-prompt-tool / settings) */
+  CONFIG_ERROR: 6,
+  /** user interrupt (SIGINT) — 128+2, shell convention */
+  INTERRUPT_SIGINT: 130,
+  /** termination (SIGTERM) — 128+15, shell convention */
+  INTERRUPT_SIGTERM: 143,
+});
+
+/**
+ * Best-effort classifier for errors thrown out of the agent loop: provider /
+ * transport failures → MODEL_ERROR, everything else → generic ERROR. Checks
+ * structural markers (HTTP status, network error codes) before falling back —
+ * never message-text guessing beyond the explicit LLM markers.
+ */
+function classifyLoopError(err) {
+  if (!err) return HEADLESS_EXIT_CODES.ERROR;
+  const status = err.status ?? err.statusCode ?? err.response?.status;
+  if (Number.isFinite(Number(status))) return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  const code = err.code || err.cause?.code;
+  if (
+    typeof code === "string" &&
+    /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|UND_ERR)/.test(
+      code,
+    )
+  ) {
+    return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  }
+  if (typeof err.name === "string" && /LLM|Provider|Api/i.test(err.name)) {
+    return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  }
+  return HEADLESS_EXIT_CODES.ERROR;
+}
+
+/**
+ * Map a finished run's endReason (+ error flag) to an exit code.
+ * @param {string} endReason  "complete" | "max_turns" | "budget-exhausted" |
+ *                            "cost-budget-exhausted" | "no-response" | ...
+ * @param {boolean} isError
+ */
+function exitCodeForEndReason(endReason, isError) {
+  if (!isError) return HEADLESS_EXIT_CODES.OK;
+  if (endReason === "max_turns" || endReason === "budget-exhausted") {
+    return HEADLESS_EXIT_CODES.MAX_TURNS;
+  }
+  if (endReason === "cost-budget-exhausted") {
+    return HEADLESS_EXIT_CODES.MAX_BUDGET;
+  }
+  return HEADLESS_EXIT_CODES.ERROR;
+}
+
+module.exports = {
+  HEADLESS_EXIT_CODES,
+  classifyLoopError,
+  exitCodeForEndReason,
+};

package/src/lib/goal-condition-engine.js

@@ -0,0 +1,369 @@
+/**
+ * Session-level completion-condition engine (P1 §"会话级完成条件引擎").
+ *
+ * Distinct from `cc goal` (long-term, cross-session OKR progress) and from
+ * `cc loop` (a timer that re-runs ONE command): this drives the agent's OUTER
+ * turns. After each outer turn an independent evaluator judges a completion
+ * CONDITION; if unmet, the runner starts the next outer turn — until the
+ * condition is met (`completed`) or a budget is exhausted (`exhausted`).
+ *
+ * The engine is a pure reducer over usage + per-turn evaluations, so it is
+ * deterministically testable without a model or the real agent loop. It:
+ *   - supports model-judged conditions AND deterministic checkers
+ *     (exit-zero / file-exists / contains / regex),
+ *   - enforces max_outer_turns and token / cost / time budgets,
+ *   - emits the SDK event taxonomy (goal_started / goal_evaluated /
+ *     goal_completed / goal_exhausted) with structured reason, evidence and
+ *     turn/token/cost/time, and
+ *   - snapshots/restores so a condition survives `--resume`.
+ *
+ * The clock is injected (`now`) and NEVER read implicitly, so snapshots replay
+ * identically and tests are deterministic.
+ */
+
+/** SDK event taxonomy for the completion-condition loop. */
+export const GOAL_EVENTS = Object.freeze({
+  STARTED: "goal_started",
+  EVALUATED: "goal_evaluated",
+  COMPLETED: "goal_completed",
+  EXHAUSTED: "goal_exhausted",
+});
+
+/** Terminal decisions the reducer can return alongside `continue`. */
+export const GOAL_DECISION = Object.freeze({
+  CONTINUE: "continue",
+  COMPLETE: "complete",
+  EXHAUSTED: "exhausted",
+});
+
+/** Default budget — a bounded outer-turn count; other axes unbounded (null). */
+export const DEFAULT_GOAL_BUDGET = Object.freeze({
+  maxOuterTurns: 10,
+  maxTokens: null,
+  maxCostUsd: null,
+  maxTimeMs: null,
+});
+
+// A hard ceiling so a misconfigured condition can never spin forever.
+const OUTER_TURN_HARD_CAP = 100;
+
+function positiveIntOrNull(value, cap) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const floored = Math.floor(n);
+  return cap ? Math.min(floored, cap) : floored;
+}
+
+function positiveNumOrNull(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/** Normalize a budget: sane defaults, positive values, hard outer-turn cap. */
+export function normalizeGoalBudget(input = {}) {
+  const maxOuterTurns =
+    positiveIntOrNull(input.maxOuterTurns, OUTER_TURN_HARD_CAP) ??
+    DEFAULT_GOAL_BUDGET.maxOuterTurns;
+  return {
+    maxOuterTurns,
+    maxTokens: positiveIntOrNull(input.maxTokens),
+    maxCostUsd: positiveNumOrNull(input.maxCostUsd),
+    maxTimeMs: positiveIntOrNull(input.maxTimeMs),
+  };
+}
+
+/**
+ * Parse a `--goal-condition` spec into a condition descriptor. A `kind:` prefix
+ * selects a deterministic checker; anything else (or an explicit `model:`) is
+ * model-judged natural language.
+ *
+ *   exit-zero:npm test        → run the command, met iff exit 0
+ *   file-exists:dist/app.js   → met iff the path exists
+ *   contains:ALL GREEN        → met iff the last output contains the text
+ *   regex:^BUILD OK$          → met iff the last output matches
+ *   model:the tests pass      → a model judges the transcript
+ *   the tests pass            → (bare) model-judged
+ */
+export function parseGoalCondition(spec) {
+  const raw = String(spec ?? "").trim();
+  if (!raw) throw new Error("goal condition is required");
+  const idx = raw.indexOf(":");
+  const prefix = idx === -1 ? "" : raw.slice(0, idx).trim().toLowerCase();
+  const rest = idx === -1 ? "" : raw.slice(idx + 1).trim();
+  switch (prefix) {
+    case "exit-zero":
+    case "exit0":
+      if (!rest) throw new Error("exit-zero condition needs a command");
+      return { kind: "exit-zero", command: rest, source: raw };
+    case "file-exists":
+    case "file":
+      if (!rest) throw new Error("file-exists condition needs a path");
+      return { kind: "file-exists", path: rest, source: raw };
+    case "contains":
+      if (!rest) throw new Error("contains condition needs text");
+      return { kind: "contains", text: rest, source: raw };
+    case "regex":
+      if (!rest) throw new Error("regex condition needs a pattern");
+      return { kind: "regex", pattern: rest, source: raw };
+    case "model":
+      if (!rest) throw new Error("model condition needs a description");
+      return { kind: "model", text: rest, source: raw };
+    default:
+      return { kind: "model", text: raw, source: raw };
+  }
+}
+
+/** True when a condition is a deterministic checker (not model-judged). */
+export function isDeterministicCondition(condition) {
+  return Boolean(condition) && condition.kind !== "model";
+}
+
+/**
+ * Evaluate a deterministic condition against gathered evidence — PURE.
+ * `evidence` supplies `output` (last turn text), `exitCode`, and a
+ * `fileExists(path) => boolean` predicate. Returns `{met, reason, evidence}`.
+ */
+export function checkDeterministicCondition(condition, evidence = {}) {
+  const output = String(evidence.output ?? "");
+  switch (condition?.kind) {
+    case "contains": {
+      const met = output.includes(condition.text);
+      return {
+        met,
+        reason: met
+          ? `output contains "${condition.text}"`
+          : `output does not contain "${condition.text}"`,
+        evidence: { kind: "contains", matched: met },
+      };
+    }
+    case "regex": {
+      let re;
+      try {
+        re = new RegExp(condition.pattern, condition.flags || "m");
+      } catch (err) {
+        return {
+          met: false,
+          reason: `invalid regex: ${err.message}`,
+          evidence: { kind: "regex", error: true },
+        };
+      }
+      const met = re.test(output);
+      return {
+        met,
+        reason: met
+          ? `output matches /${condition.pattern}/`
+          : `output does not match /${condition.pattern}/`,
+        evidence: { kind: "regex", matched: met },
+      };
+    }
+    case "exit-zero": {
+      const met = Number(evidence.exitCode) === 0;
+      return {
+        met,
+        reason: `\`${condition.command}\` exited ${evidence.exitCode}`,
+        evidence: { kind: "exit-zero", exitCode: evidence.exitCode ?? null },
+      };
+    }
+    case "file-exists": {
+      const fx = typeof evidence.fileExists === "function";
+      const met = fx ? evidence.fileExists(condition.path) === true : false;
+      return {
+        met,
+        reason: met
+          ? `${condition.path} exists`
+          : `${condition.path} does not exist`,
+        evidence: { kind: "file-exists", path: condition.path, met },
+      };
+    }
+    default:
+      return {
+        met: false,
+        reason: `not a deterministic condition (${condition?.kind})`,
+        evidence: { kind: condition?.kind ?? "unknown" },
+      };
+  }
+}
+
+/**
+ * Gather evidence and run a deterministic check. Deps (`spawnSync`,
+ * `existsSync`) are injected for tests; `lastOutput` feeds contains/regex.
+ */
+export function runDeterministicCheck(condition, deps = {}) {
+  const evidence = { output: deps.lastOutput ?? "" };
+  if (condition.kind === "exit-zero") {
+    const spawnSync = deps.spawnSync;
+    if (typeof spawnSync !== "function") {
+      return {
+        met: false,
+        reason: "no spawnSync available for exit-zero",
+        evidence: { kind: "exit-zero", error: true },
+      };
+    }
+    const res = spawnSync(condition.command, {
+      cwd: deps.cwd,
+      shell: true,
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    evidence.exitCode = res?.status ?? (res?.error ? 1 : null);
+  } else if (condition.kind === "file-exists") {
+    const existsSync = deps.existsSync;
+    evidence.fileExists = (p) =>
+      typeof existsSync === "function" ? existsSync(p) === true : false;
+  }
+  return checkDeterministicCondition(condition, evidence);
+}
+
+function usageSnapshot(state, nowMs) {
+  return {
+    outerTurns: state.outerTurns,
+    tokens: state.tokens,
+    costUsd: state.costUsd,
+    elapsedMs: Math.max(0, nowMs - state.startedAtMs),
+  };
+}
+
+function whichLimitHit(state, budget, nowMs) {
+  if (budget.maxOuterTurns != null && state.outerTurns >= budget.maxOuterTurns)
+    return "max_outer_turns";
+  if (budget.maxTokens != null && state.tokens >= budget.maxTokens)
+    return "max_tokens";
+  if (budget.maxCostUsd != null && state.costUsd >= budget.maxCostUsd)
+    return "max_cost";
+  if (
+    budget.maxTimeMs != null &&
+    Math.max(0, nowMs - state.startedAtMs) >= budget.maxTimeMs
+  )
+    return "max_time";
+  return null;
+}
+
+/**
+ * The pure decision step. Given the accumulated `state`, this turn's
+ * `evaluation` ({met, reason, evidence}), the `budget`, and the current time,
+ * decide `complete | continue | exhausted` and produce events. Always emits a
+ * `goal_evaluated`; adds a terminal `goal_completed` / `goal_exhausted` when
+ * the loop stops. Does NOT mutate `state` — returns the next one.
+ */
+export function evaluateGoalStep(state, evaluation, budget, opts = {}) {
+  const nowMs = Number(opts.now ?? state.startedAtMs);
+  const next = {
+    ...state,
+    outerTurns: state.outerTurns + 1,
+  };
+  const usage = usageSnapshot(next, nowMs);
+  const met = evaluation?.met === true;
+  const evaluated = {
+    type: GOAL_EVENTS.EVALUATED,
+    met,
+    reason: evaluation?.reason ?? null,
+    evidence: evaluation?.evidence ?? null,
+    ...usage,
+  };
+  if (met) {
+    return {
+      state: { ...next, done: true, outcome: "completed" },
+      decision: GOAL_DECISION.COMPLETE,
+      events: [
+        evaluated,
+        {
+          type: GOAL_EVENTS.COMPLETED,
+          reason: evaluation?.reason ?? "condition met",
+          evidence: evaluation?.evidence ?? null,
+          ...usage,
+        },
+      ],
+    };
+  }
+  const limit = whichLimitHit(next, budget, nowMs);
+  if (limit) {
+    return {
+      state: { ...next, done: true, outcome: "exhausted", limit },
+      decision: GOAL_DECISION.EXHAUSTED,
+      events: [
+        evaluated,
+        {
+          type: GOAL_EVENTS.EXHAUSTED,
+          limit,
+          reason: `budget exhausted (${limit})`,
+          ...usage,
+        },
+      ],
+    };
+  }
+  return { state: next, decision: GOAL_DECISION.CONTINUE, events: [evaluated] };
+}
+
+/**
+ * Stateful wrapper over the reducer for the runner. Inject `now` (a `() => ms`
+ * clock) so behavior is deterministic and snapshot-replayable.
+ */
+export class GoalConditionEngine {
+  constructor({ condition, budget, now } = {}) {
+    this.condition =
+      typeof condition === "string" ? parseGoalCondition(condition) : condition;
+    this.budget = normalizeGoalBudget(budget);
+    this._now = typeof now === "function" ? now : () => 0;
+    this.state = {
+      outerTurns: 0,
+      tokens: 0,
+      costUsd: 0,
+      startedAtMs: this._now(),
+      done: false,
+      outcome: null,
+    };
+  }
+
+  /** Emit the opening event; call once before the first outer turn. */
+  start() {
+    return {
+      type: GOAL_EVENTS.STARTED,
+      condition: this.condition,
+      budget: this.budget,
+      startedAtMs: this.state.startedAtMs,
+    };
+  }
+
+  /** Accumulate a turn's usage before evaluating it. */
+  recordTurnUsage({ tokens = 0, costUsd = 0 } = {}) {
+    this.state = {
+      ...this.state,
+      tokens: this.state.tokens + (Number(tokens) || 0),
+      costUsd: this.state.costUsd + (Number(costUsd) || 0),
+    };
+    return this.state;
+  }
+
+  /** Evaluate this outer turn; returns `{decision, events}`. */
+  evaluate(evaluation) {
+    const result = evaluateGoalStep(this.state, evaluation, this.budget, {
+      now: this._now(),
+    });
+    this.state = result.state;
+    return { decision: result.decision, events: result.events };
+  }
+
+  get done() {
+    return this.state.done === true;
+  }
+
+  /** Serialize for `--resume`. startedAtMs is preserved so time keeps counting. */
+  snapshot() {
+    return {
+      condition: this.condition,
+      budget: this.budget,
+      state: { ...this.state },
+    };
+  }
+
+  /** Restore a prior run (same clock injection contract). */
+  static fromSnapshot(snap, { now } = {}) {
+    const engine = new GoalConditionEngine({
+      condition: snap.condition,
+      budget: snap.budget,
+      now,
+    });
+    engine.state = { ...snap.state };
+    return engine;
+  }
+}