@delegance/claude-autopilot 5.2.2 → 6.2.2

package/dist/src/core/run-state/budget.js

@@ -0,0 +1,141 @@
+// src/core/run-state/budget.ts
+//
+// v6 Phase 4 — budget enforcement policy.
+//
+// Pure data + a pure decision function. No IO, no globals, no side effects.
+// `checkPhaseBudget` is the authoritative answer to "may this phase run?"
+// — `runPhase` consumes the result, emits a `budget.check` event with the
+// full payload, and throws `budget_exceeded` on hard-fail.
+//
+// Two-layer policy per spec (Codex CRITICAL #3 fold-in — estimates can fail
+// open, the runtime guard MUST run independently):
+//
+//   - Layer 1 (advisory)  — only fires when the phase declares
+//     `estimateCost`. Compares `actualSoFar + estimate.high` against
+//     `perRunUSD`. Pause-and-prompt (interactive) or hard-fail (CI mode)
+//     if it would exceed.
+//   - Layer 2 (mandatory) — ALWAYS runs. Compares `actualSoFar +
+//     conservativePhaseReserveUSD` against `perRunUSD`. Phases without
+//     estimates therefore still trigger budget gates. Default reserve is
+//     $5 (overridable in config).
+//   - `perPhaseUSD` gate — if set AND the larger of the per-phase estimate
+//     or reserve would push this phase's cost over the per-phase cap,
+//     applies the same pause/hard-fail rule.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Budget enforcement".
+/** Default Layer 2 reserve when none is configured. Conservative — phases
+ *  without an `estimateCost` are assumed to consume at least this much,
+ *  which keeps the cap from "failing open" the moment a phase forgets to
+ *  declare its cost shape. */
+export const DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD = 5;
+/** Policy decision for a single about-to-run phase. Pure — no IO. The
+ *  caller (`runPhase`) is responsible for emitting the `budget.check`
+ *  event with this payload and acting on the decision. */
+export function checkPhaseBudget(opts) {
+    const { budget, phaseName, phaseIdx, estimatedCost, actualSoFarUSD, nonInteractive, } = opts;
+    // v6.2.0 — `'phase'` (default for back-compat) vs `'run'` (orchestrator).
+    // The math is intentionally identical between the two; `actualSoFarUSD`
+    // is already the cross-phase sum produced by `sumRunCost` in
+    // phase-runner.ts. The flag exists so the `budget.check` event tells
+    // observers which scope generated the decision and so future policy
+    // tweaks (e.g. divergent perPhase reserves under run scope) have a
+    // place to land without an event-shape break.
+    const scope = budget.scope ?? 'phase';
+    const reserveFloor = typeof budget.conservativePhaseReserveUSD === 'number'
+        ? budget.conservativePhaseReserveUSD
+        : DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD;
+    // The reserve actually deducted is the larger of "what the phase says
+    // it will cost (high end)" and "the conservative floor we always apply".
+    // This is the core of Codex CRITICAL #3 — even if estimateCost is
+    // present and tiny, the floor still applies, and even if estimateCost
+    // is absent, the floor still applies.
+    const estimatedHigh = estimatedCost?.highUSD ?? null;
+    const reserveApplied = Math.max(estimatedHigh ?? 0, reserveFloor);
+    const projected = actualSoFarUSD + reserveApplied;
+    const capRemaining = budget.perRunUSD - projected;
+    // Layer 1 — ADVISORY using the explicit estimate. Runs FIRST so a precise
+    // estimate produces a precise reason ("estimate would exceed cap") instead
+    // of falling through to Layer 2's conservative-floor wording. Only fires
+    // when an estimate is present AND would push us past perRunUSD on its own.
+    // (Bugbot LOW on PR #89 caught the prior ordering, where Layer 2 always
+    // ran first and Layer 1 was provably unreachable since `reserveApplied =
+    // max(estimatedHigh, floor) >= estimatedHigh`.)
+    if (estimatedHigh !== null && actualSoFarUSD + estimatedHigh > budget.perRunUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining: budget.perRunUSD - (actualSoFarUSD + estimatedHigh),
+            reason: `advisory estimate would exceed run cap — actual ` +
+                `$${fmtUSD(actualSoFarUSD)} + estimate.high ` +
+                `$${fmtUSD(estimatedHigh)} > perRunUSD $${fmtUSD(budget.perRunUSD)}`,
+            scope,
+        };
+    }
+    // Layer 2 — MANDATORY floor against perRunUSD. Catches the case where the
+    // estimate is missing (Layer 1 didn't fire) OR present-but-tiny (estimate
+    // alone fits, but the conservative reserve floor pushes over). This is the
+    // safety net that prevents phases without `estimateCost` from sneaking
+    // past the cap.
+    if (projected > budget.perRunUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining,
+            reason: `run cap exceeded — actual $${fmtUSD(actualSoFarUSD)} + reserve ` +
+                `$${fmtUSD(reserveApplied)} = $${fmtUSD(projected)} > perRunUSD ` +
+                `$${fmtUSD(budget.perRunUSD)}`,
+            scope,
+        };
+    }
+    // perPhaseUSD gate — independent of the run cap. Applies the same
+    // reserve logic but compares against the per-phase cap.
+    if (typeof budget.perPhaseUSD === 'number' && reserveApplied > budget.perPhaseUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining,
+            reason: `per-phase cap exceeded — reserve $${fmtUSD(reserveApplied)} > ` +
+                `perPhaseUSD $${fmtUSD(budget.perPhaseUSD)}`,
+            scope,
+        };
+    }
+    return {
+        decision: 'proceed',
+        phase: phaseName,
+        phaseIdx,
+        estimatedHigh,
+        actualSoFar: actualSoFarUSD,
+        reserveApplied,
+        capRemaining,
+        reason: estimatedHigh !== null
+            ? `within budget — projected $${fmtUSD(projected)} of $${fmtUSD(budget.perRunUSD)}`
+            : `within budget (no estimate, applied $${fmtUSD(reserveApplied)} ` +
+                `reserve floor) — projected $${fmtUSD(projected)} of ` +
+                `$${fmtUSD(budget.perRunUSD)}`,
+        scope,
+    };
+}
+/** Format a USD amount with 2 decimal places for human-readable reasons.
+ *  Kept local — the run-state module doesn't have a shared formatter and
+ *  budget reasons are the only consumer. */
+function fmtUSD(n) {
+    // toFixed(2) returns "0.00" for 0; we keep the trailing zeros so the
+    // reason strings line up visually in CLI output.
+    return n.toFixed(2);
+}
+//# sourceMappingURL=budget.js.map

package/dist/src/core/run-state/cli-internal.d.ts

@@ -0,0 +1,21 @@
+/** Result of a single internal-CLI invocation. The dispatcher in
+ *  src/cli/index.ts converts this to an exit code + console output. Pure
+ *  data so we can unit-test the dispatch shape without spawning a child. */
+export interface RunInternalCliResult {
+    /** Process exit code. */
+    exit: number;
+    /** Lines to print on stdout (text mode only). */
+    stdout: string[];
+    /** Lines to print on stderr (text mode only). */
+    stderr: string[];
+}
+export interface RunInternalCliOptions {
+    /** argv after `claude-autopilot internal`. e.g. ['log-phase-event',
+     *  '--run-id', '01HZK', '--event', '{...}']. */
+    args: string[];
+    /** Working directory containing `.guardrail-cache/runs/`. Defaults to
+     *  process.cwd(). */
+    cwd?: string;
+}
+export declare function runInternalCli(opts: RunInternalCliOptions): Promise<RunInternalCliResult>;
+//# sourceMappingURL=cli-internal.d.ts.map

package/dist/src/core/run-state/cli-internal.js

@@ -0,0 +1,174 @@
+// src/core/run-state/cli-internal.ts
+//
+// Hidden CLI verb: `claude-autopilot internal log-phase-event`.
+//
+// Markdown-driven skills (brainstorm, plan, implement) can't directly import
+// the run-state module — they spawn `claude-autopilot` as a subprocess. This
+// helper gives them a one-shot way to append a typed event into a known run
+// without rewriting the skills as TypeScript modules.
+//
+// Surface:
+//
+//   claude-autopilot internal log-phase-event \
+//     --run-id 01HZK7... \
+//     --event '<json>' \
+//     [--cwd /path/to/repo]
+//
+// `<json>` is the RunEventInput shape (no seq/ts/runId/schema_version/
+// writerId — the appender fills those in). Examples:
+//
+//   --event '{"event":"phase.cost","phase":"plan","phaseIdx":1,
+//             "provider":"anthropic","inputTokens":1200,
+//             "outputTokens":3400,"costUSD":0.07}'
+//
+// The verb is HIDDEN — not in HELP_GROUPS, not in HELP_VERBS, not in the
+// welcome text. It is documented only via `claude-autopilot internal --help`
+// for diagnostics.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Phase contract" — the markdown
+// skills shell out to write events.
+import * as path from 'node:path';
+import { GuardrailError } from "../errors.js";
+import { appendEvent } from "./events.js";
+import { makeWriterId } from "./lock.js";
+import { runDirFor } from "./runs.js";
+const HELP_TEXT = `
+Usage: claude-autopilot internal <verb> [options]
+
+Internal / diagnostic verbs. NOT for end-user use — these are called by
+markdown-driven skills (brainstorm, plan, implement) that can't import the
+run-state TS module directly. Surface stability is best-effort; do NOT
+script against this in user-facing code.
+
+Verbs:
+  log-phase-event    Append a typed event to a run's events.ndjson
+
+Options (log-phase-event):
+  --run-id <id>      Required. ULID of the run to append to.
+  --event <json>     Required. RunEventInput JSON (no seq/ts/runId — those
+                     are filled in by the appender).
+  --cwd <path>       Optional. Repo root containing .guardrail-cache/runs/.
+                     Defaults to the current working directory.
+
+Examples:
+
+  claude-autopilot internal log-phase-event \\
+    --run-id 01HZK7XXXXXXXXXXXXXXXXXXXX \\
+    --event '{"event":"phase.cost","phase":"plan","phaseIdx":1,
+              "provider":"anthropic","inputTokens":1200,
+              "outputTokens":3400,"costUSD":0.07}'
+`;
+/** Parse argv pairs of the form `--name <value>`. Multi-value not supported
+ *  here — there is exactly one value per flag. Returns undefined when the
+ *  flag is missing, throws when the flag is present but its value is missing
+ *  or starts with another `--`. */
+function readFlag(args, name) {
+    const idx = args.indexOf(`--${name}`);
+    if (idx < 0)
+        return undefined;
+    const val = args[idx + 1];
+    if (val === undefined || val.startsWith('--')) {
+        throw new GuardrailError(`--${name} requires a value`, { code: 'user_input', provider: 'cli', details: { flag: name } });
+    }
+    return val;
+}
+export async function runInternalCli(opts) {
+    const args = opts.args;
+    const verb = args[0];
+    if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
+        return { exit: 0, stdout: [HELP_TEXT.trimStart()], stderr: [] };
+    }
+    if (verb !== 'log-phase-event') {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [
+                `[claude-autopilot] internal: unknown verb "${verb}"`,
+                HELP_TEXT.trimStart(),
+            ],
+        };
+    }
+    // log-phase-event
+    let runId;
+    let eventJson;
+    let cwdOverride;
+    try {
+        runId = readFlag(args, 'run-id');
+        eventJson = readFlag(args, 'event');
+        cwdOverride = readFlag(args, 'cwd');
+    }
+    catch (err) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] internal: ${err.message}`],
+        };
+    }
+    if (!runId) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] internal: --run-id is required`],
+        };
+    }
+    if (!eventJson) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] internal: --event is required`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(eventJson);
+    }
+    catch (err) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [
+                `[claude-autopilot] internal: --event is not valid JSON: ${err.message}`,
+            ],
+        };
+    }
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.event !== 'string') {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [
+                `[claude-autopilot] internal: --event must be an object with an "event" string field`,
+            ],
+        };
+    }
+    const cwd = cwdOverride ? path.resolve(cwdOverride) : (opts.cwd ?? process.cwd());
+    const runDir = runDirFor(cwd, runId);
+    // Best-effort writerId. The internal verb does NOT take the run's lock —
+    // the markdown skill that calls it is operating "out-of-band" of any
+    // currently-held lock by design (skills can't hold a lock across multiple
+    // bash invocations). Stamping the writerId of the calling process keeps
+    // the event auditable even though it sidesteps the single-writer
+    // invariant. Phase 6 may add a `--writer-id <id>` flag for stricter
+    // attribution; Phase 2 keeps the surface minimal.
+    const writerId = makeWriterId();
+    let appended;
+    try {
+        appended = appendEvent(runDir, parsed, { writerId, runId });
+    }
+    catch (err) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [
+                `[claude-autopilot] internal: appendEvent failed: ${err.message}`,
+            ],
+        };
+    }
+    return {
+        exit: 0,
+        stdout: [
+            `[claude-autopilot] internal: appended seq=${appended.seq} event=${appended.event} runId=${runId}`,
+        ],
+        stderr: [],
+    };
+}
+//# sourceMappingURL=cli-internal.js.map

package/dist/src/core/run-state/events.d.ts

@@ -0,0 +1,59 @@
+import { type RunEvent, type RunEventInput, type RunIndexEntry, type RunState, type WriterId } from './types.ts';
+export declare function eventsPath(runDir: string): string;
+export interface ReadEventsOptions {
+    /** Skip events with seq < this value. */
+    fromSeq?: number;
+    /** Return only the last N events. Applied after `fromSeq` filter. */
+    tail?: number;
+}
+export interface ReadEventsResult {
+    events: RunEvent[];
+    /** True if the last line of the file was a partial JSON write and was
+     *  ignored. The next append should emit a `run.recovery` event. */
+    truncatedTail: boolean;
+    /** Highest seq observed in the file (after dropping a truncated tail). */
+    maxSeq: number;
+}
+/** Stream all events from disk. Detects partial-JSON tail and signals
+ *  recovery via `truncatedTail`. Does NOT throw on individual line parse
+ *  errors that are NOT the last line — those produce a `partial_write`
+ *  GuardrailError because mid-log corruption is unrecoverable here. */
+export declare function readEvents(runDir: string, opts?: ReadEventsOptions): ReadEventsResult;
+/** Read just the highest seq from disk. Prefers the sidecar; falls back to
+ *  rescanning the events file. */
+export declare function readMaxSeq(runDir: string): number;
+export interface AppendEventOptions {
+    /** Override the runId stamped onto the event. Required for runs whose
+     *  ID isn't derivable from the runDir (almost never; we accept it for
+     *  test fixtures). */
+    runId?: string;
+    writerId: WriterId;
+}
+/** Append a single event to events.ndjson. Strict ordering:
+ *    1. open(O_APPEND), write line, fsync(fd), close.
+ *    2. Update sidecar with new seq (best-effort).
+ *
+ *  Returns the fully-formed RunEvent that landed on disk (with seq, ts,
+ *  schema_version, etc. filled in).
+ *
+ *  This is the ONLY supported way to append. Bypassing it with raw fs writes
+ *  will desync the seq sidecar and may break recovery. */
+export declare function appendEvent(runDir: string, input: RunEventInput, opts: AppendEventOptions): RunEvent;
+/** Replay events.ndjson into a fresh RunState snapshot. The events file is
+ *  the source of truth — this is always callable; if the file is missing or
+ *  empty, the result is a minimal "pending" state with no phases.
+ *
+ *  Throws GuardrailError(corrupted_state) if the log has internal
+ *  contradictions that prevent a coherent snapshot (e.g. seq gaps,
+ *  phase.success without a prior phase.start), OR if the persisted
+ *  `schema_version` falls outside this binary's supported window
+ *  (`RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION..RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION`).
+ *  Per v6.2.2 spec — the prior shape would fail with a cryptic
+ *  `cannot read property 'phases' of undefined` instead of an actionable
+ *  "this run dir is from a newer/older version" message. */
+export declare function replayState(runDir: string): RunState;
+export declare function foldEvents(runDir: string, events: RunEvent[]): RunState;
+/** Fold an in-memory state into a list-row used by `runs list`. Lives here
+ *  because it's a pure projection over RunState — no IO, no side effects. */
+export declare function stateToIndexEntry(state: RunState, recovered?: boolean): RunIndexEntry;
+//# sourceMappingURL=events.d.ts.map