@robmclarty/volley 0.5.1

package/dist/index.d.ts

@@ -0,0 +1,349 @@
+import { UsageTotals, FinishReason, StreamChunk, Engine } from 'fascicle';
+import { z } from 'zod';
+
+/**
+ * Shared value and type contracts for volley.
+ *
+ * Type aliases are PascalCase; value-level identifiers are snake_case.
+ * Fascicle's usage/cost types are used verbatim so summaries carry the
+ * substrate's shapes, not a re-derivation.
+ */
+
+type Verdict = 'approved' | 'changes_requested';
+type CriticPreset = 'reviewer' | 'optimizer' | 'researcher';
+/** Transport for the critic role. The critic is read-only + schema-constrained,
+ * so it has always been able to run on a local model. */
+type CriticProvider = 'claude_cli' | 'ollama' | 'lmstudio';
+/** Transport for the builder role. `claude_cli` is a full agentic Claude Code
+ * session; the local providers run the builder as a volley-driven tool loop
+ * (write/exec tools supplied by the harness). The execution path for the local
+ * providers lands with the builder tool/termination work; this type and its
+ * plumbing exist so that work has somewhere to attach (spec v3). */
+type BuilderProvider = 'claude_cli' | 'ollama' | 'lmstudio';
+type BuilderPermissionMode = 'acceptEdits' | 'bypassPermissions';
+/** `auto`, `none`, or any shell command (the `string & {}` keeps the literal
+ * hints in editor completions without collapsing the union). */
+type CheckMode = 'auto' | 'none' | (string & {});
+type CheckRunnerKind = 'checkride' | 'command' | 'none';
+type CostSource = 'provider_reported' | 'engine_derived' | 'unknown';
+/** Fascicle's `provider_error.cause_kind` discriminant — why a provider call
+ * died. Recorded alongside a critic retry so a degraded run says
+ * *what* failed, not just that it retried. */
+type CauseKind = 'provider_5xx' | 'network' | 'unknown';
+type RunStatus = 'running' | 'success' | 'budget_exhausted' | 'cost_cap_reached'
+/** The builder edited the gate that judges it, under `--fail-on-gate-edit`:
+ * the run halts on the spot rather than iterating, because a check the builder
+ * can rewrite is not evidence the work is done. */
+ | 'gate_edit_blocked' | 'interrupted' | 'error';
+/** User-facing configuration, before resolution (config file / flags). */
+type VolleyConfig = {
+    prompt: string;
+    workspace: string;
+    criteria: string;
+    check?: CheckMode;
+    builder_model?: string;
+    builder_provider?: BuilderProvider;
+    builder_max_steps?: number;
+    allow_unsandboxed_builder?: boolean;
+    critic_model?: string;
+    critic_provider?: CriticProvider;
+    builder_permission_mode?: BuilderPermissionMode;
+    critic?: CriticPreset | (string & {});
+    max_iterations?: number;
+    max_cost_usd?: number | null;
+    git_checkpoints?: boolean;
+    worktree?: boolean;
+    discard_worktree?: boolean;
+    gate_paths?: string[];
+    fail_on_gate_edit?: boolean;
+    sandbox_image?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    show_thinking?: boolean;
+    dry_run?: boolean;
+};
+/** Fully resolved run configuration; `.volley/config.json` mirrors this. */
+type ResolvedConfig = {
+    version: 2;
+    run_id: string;
+    started_at: string;
+    prompt: string;
+    criteria: string;
+    check: CheckMode;
+    check_resolved: CheckRunnerKind;
+    builder_model: string;
+    builder_provider: BuilderProvider;
+    builder_max_steps: number;
+    /** Operator opt-out permitting a local (non-`claude_cli`) builder to run
+     * without a sandbox — it gets a real host bash. Refused by default. */
+    allow_unsandboxed_builder: boolean;
+    critic_model: string;
+    critic_provider: CriticProvider;
+    builder_permission_mode: BuilderPermissionMode;
+    critic_preset: CriticPreset | 'custom';
+    critic_prompt_path: string | null;
+    max_iterations: number;
+    max_cost_usd: number | null;
+    git_checkpoints: boolean;
+    /** Isolate the builder run's effects in a per-run git worktree: the
+     * builder/critic file tools' containment root moves to the worktree, while
+     * `.volley/` state stays under `workspace` (the control plane). Off by
+     * default; requires the workspace to be a git repository. */
+    worktree: boolean;
+    /** Throw a `--worktree` run's effects away at teardown even when it converged:
+     * the run branch is force-deleted rather than kept, because only the
+     * verdicts are wanted. This is what `volley matrix` sweeps with — one config,
+     * many builder×critic seats, no per-seat commits or branches left anywhere.
+     * Refused without `--worktree`; `--git` still wins, so a `--worktree --git`
+     * run integrates exactly as it always has. */
+    discard_worktree: boolean;
+    /** Glob patterns naming the *gate*: the tests, fixtures, and check
+     * configuration that decide whether the builder's work passes. An edit to one
+     * is reported to the critic and recorded in the summary — and refused outright
+     * under `fail_on_gate_edit`. Defaults to `DEFAULT_GATE_PATTERNS`; a config's
+     * own list replaces it, because what counts as the gate is the task's call
+     * (a test-writing task edits tests by design). */
+    gate_paths: string[];
+    /** Halt the run when the builder edits a `gate_paths` match, instead of
+     * reporting it and continuing. Off by default: a gate edit is legitimate often
+     * enough that refusing it by default would break honest tasks, and the mark on
+     * the summary already makes it impossible to miss. */
+    fail_on_gate_edit: boolean;
+    /** Container image the local-builder Docker sandbox runs. Defaults to
+     * volley's own `Dockerfile`-built image; `--sandbox-image <tag>` /
+     * `VOLLEY_SANDBOX_IMAGE` override it. Meaningful only for a local builder —
+     * the `claude_cli` path never uses Docker. */
+    sandbox_image: string;
+    workspace: string;
+    verbose: boolean;
+    quiet: boolean;
+    json: boolean;
+    show_thinking: boolean;
+};
+/** One failing check slot's raw artifact, for the critic prompt. */
+type CheckArtifact = {
+    slot: string;
+    path: string | null;
+    content: string;
+    truncated: boolean;
+};
+type CheckResult = {
+    ran: boolean;
+    runner: CheckRunnerKind;
+    ok: boolean;
+    exit_code: number | null;
+    duration_ms: number;
+    failing_slots: string[];
+    detail: CheckArtifact[];
+    /** Raw checkride summary JSON (when the runner is checkride). */
+    summary?: unknown;
+    /** Captured combined output (when the runner is a shell command). */
+    log?: string;
+};
+/** How one path changed between the run's baseline and the builder's output.
+ * `renamed` covers git's rename/copy detection (the destination path is the one
+ * recorded); `unknown` is any status git reports that none of these name. */
+type ChangeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'unknown';
+/** One path the builder changed, and whether that path is part of the *gate* —
+ * the tests, fixtures, and check configuration that decide whether the work
+ * passes. A gate edit is not misconduct by itself (some tasks are *about* the
+ * tests); it is the fact that makes a green check prove less. */
+type ChangedFile = {
+    path: string;
+    status: ChangeStatus;
+    gate: boolean;
+};
+/** What the builder changed since the run's baseline, as the harness sees it
+ * (`src/changes.ts`). Null in `LoopState` when the build root is not a git
+ * repository — change detection is evidence, never a precondition. */
+type ChangeSet = {
+    /** The commit the changes are measured against — the build root's HEAD before
+     * the first iteration. Null in a repository with no commits yet, where only
+     * untracked files can be reported. */
+    baseline: string | null;
+    /** The changed paths, sorted, capped at the collection limit. */
+    files: ChangedFile[];
+    /** Every gate-matching path — computed over the *full* list before the cap,
+     * so truncation can never hide a gate edit. */
+    gate_edits: string[];
+    /** How many paths changed in total, before the cap. */
+    total: number;
+    truncated: boolean;
+};
+/** Per-phase record for iteration summaries. */
+type PhaseRecord = {
+    provider: string;
+    model: string;
+    session_id: string | null;
+    duration_ms: number;
+    usage: UsageTotals;
+    cost_usd: number | null;
+    cost_source: CostSource;
+    /** How the phase's generate call ended. For a local builder,
+     * `'max_steps'` is a budget cutoff surfaced as a warning, not an error. */
+    finish_reason: FinishReason;
+    /** Tool calls fascicle executed in this phase, and how many were recovered
+     * from assistant text rather than returned structurally — the raw
+     * counts behind the salvage-rate health metric. */
+    tool_calls: number;
+    salvaged_tool_calls: number;
+    /** Provider-error retries that preceded this phase's successful call
+     * — the local-critic degradation ladder's first rung: a stochastic
+     * Ollama stream death is retried once before falling back. Set on the critic
+     * record (0 when the first call succeeded); absent on the builder, which is
+     * not retried this build. Additive — old summary consumers ignore it. */
+    retries?: number;
+    /** The `cause_kind` of the retried provider error, recorded with `retries`.
+     * Absent when no retry happened. */
+    retry_cause_kind?: CauseKind;
+    /** This local-critic verdict was rendered by the tool-less fallback rung:
+     * the tool-bearing critique kept dying on the provider's stream
+     * even after the bounded retry, so the critic judged with no read access —
+     * grounded only by the criteria, the raw check artifacts, and a workspace file
+     * inventory. Set (true) on a degraded critic record; absent on a full
+     * critique and on the builder. Additive, and a degraded verdict is *always*
+     * marked so it never passes silently as a full one. */
+    critic_degraded?: boolean;
+};
+type HaltReason = 'cost_cap' | 'gate_edit' | null;
+/** Carry-state threaded through the fascicle loop. */
+type LoopState = {
+    iteration: number;
+    iteration_started_at: string;
+    feedback: string | null;
+    verdict: Verdict | null;
+    unmet_criteria: string[];
+    check: CheckResult | null;
+    /** What the builder changed this iteration, measured against the run's
+     * baseline (`src/changes.ts`). Null when the build root is not a git
+     * repository, and before the first `build` step of a run. */
+    changes: ChangeSet | null;
+    builder: PhaseRecord | null;
+    critic: PhaseRecord | null;
+    total_usage: UsageTotals;
+    total_cost_usd: number;
+    builder_cost_usd: number;
+    critic_cost_usd: number;
+    check_duration_ms: number;
+    iteration_cost_usd: number;
+    halt: HaltReason;
+    cost_warned: boolean;
+};
+/** Projection of final loop state; `.volley/summary.json` mirrors this. */
+type RunResult = {
+    run_id: string;
+    status: RunStatus;
+    started_at: string;
+    completed_at: string | null;
+    iterations_completed: number;
+    total_usage: UsageTotals;
+    total_cost_usd: number;
+    builder_cost_usd: number;
+    critic_cost_usd: number;
+    check_duration_ms: number;
+    final_verdict: Verdict | null;
+    /** The run branch teardown left behind because this run's work was never
+     * integrated: under `--worktree` without `--git` a converged run has no
+     * other copy of its effects, so teardown commits them onto `volley/<run id>`
+     * and keeps the branch instead of force-deleting it. Null whenever nothing
+     * survived — every non-worktree run, every integrated run, every discarded
+     * one. `--json` consumers read it here; `.volley/summary.json` mirrors it. */
+    salvaged_branch: string | null;
+};
+
+/** `@path/to/file` reads the file; any other string passes through. */
+declare function expand_at_file(value: string, cwd: string): string;
+/** Load a `volley.config.ts` / `.js` file's default export. */
+declare function load_config_file(path: string): Promise<VolleyConfig>;
+type ResolveOptions = {
+    cwd?: string;
+    run_id?: string;
+    started_at?: string;
+    env?: Record<string, string | undefined>;
+};
+/** Merge, expand, and validate a raw `VolleyConfig` into a `ResolvedConfig`.
+ * `check_resolved` is filled in later by check detection (workspace-relative);
+ * it starts as `none` and `resolve_check_runner` overrides it. */
+declare function resolve_config(raw: VolleyConfig, options?: ResolveOptions): ResolvedConfig;
+
+type Role = 'builder' | 'critic' | 'check';
+
+/**
+ * Live output renderer: consumes `StreamChunk`s from each
+ * `generate` call plus volley's own phase/cost lines, and writes human
+ * progress to stderr. Streaming is a display concern only — the trajectory
+ * jsonl is the durable record.
+ */
+
+type RenderMode = 'default' | 'verbose' | 'quiet' | 'json';
+type RendererOptions = {
+    mode: RenderMode;
+    show_thinking: boolean;
+    color: boolean;
+    max_cost_usd: number | null;
+    write?: (text: string) => void;
+};
+type Renderer = {
+    builder_chunk: (chunk: StreamChunk) => void;
+    critic_chunk: (chunk: StreamChunk) => void;
+    phase_start: (iteration: number, phase: Role) => void;
+    phase_end: (iteration: number, phase: Role, ok: boolean, detail?: string) => void;
+    cost_line: (iteration: number, phase: Role, phase_cost: number | null, run_total: number) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+    final_summary: (result: RunResult) => void;
+};
+declare function create_renderer(options: RendererOptions): Renderer;
+
+declare function initial_state(): LoopState;
+/** All stopping conditions live here: acceptance, cost cap, the gate
+ * edit refusal, and — implicitly via `max_rounds` — the iteration budget.
+ * Success wins when it and the cap land on the same iteration.
+ *
+ * A gate edit is the one condition that *beats* success rather than losing to
+ * it: the run passed a check the builder had rewritten, so the pass is exactly
+ * what is in question. It stops the run instead of iterating, because a model
+ * that just edited the gate is not a promising candidate to be asked again. */
+declare function gate(config: ResolvedConfig, state: LoopState): {
+    stop: boolean;
+    state: LoopState;
+};
+declare function status_of(value: LoopState, converged: boolean): RunStatus;
+type OrchestratorDeps = {
+    renderer: Renderer;
+    engine?: Engine;
+    abort?: AbortSignal;
+    install_signal_handlers?: boolean;
+};
+declare function run_volley(config: ResolvedConfig, deps: OrchestratorDeps, resume_from?: LoopState | null): Promise<RunResult>;
+
+/**
+ * Critic invocation: a read-only `claude_cli` session returning a
+ * schema-validated structured verdict. The harness — not the critic — writes
+ * `.volley/feedback.md` and `.volley/verdict`.
+ */
+
+declare const verdict_schema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        approved: "approved";
+        changes_requested: "changes_requested";
+    }>;
+    feedback: z.ZodString;
+    unmet_criteria: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type VerdictOutput = z.infer<typeof verdict_schema>;
+
+declare const EXIT_SUCCESS = 0;
+declare const EXIT_BUDGET_EXHAUSTED = 2;
+declare const EXIT_BUILDER_ERROR = 3;
+declare const EXIT_CHECK_ERROR = 4;
+declare const EXIT_CONFIG_ERROR = 5;
+declare const EXIT_CRITIC_ERROR = 6;
+declare const EXIT_COST_CAP = 7;
+declare const EXIT_INTERRUPTED = 130;
+declare function exit_code_for_status(status: RunStatus): number;
+declare function exit_code_for_error(err: unknown): number;
+
+export { type BuilderPermissionMode, type CheckArtifact, type CheckMode, type CheckResult, type CheckRunnerKind, type CostSource, type CriticPreset, type CriticProvider, EXIT_BUDGET_EXHAUSTED, EXIT_BUILDER_ERROR, EXIT_CHECK_ERROR, EXIT_CONFIG_ERROR, EXIT_COST_CAP, EXIT_CRITIC_ERROR, EXIT_INTERRUPTED, EXIT_SUCCESS, type HaltReason, type LoopState, type PhaseRecord, type RenderMode, type Renderer, type RendererOptions, type ResolvedConfig, type RunResult, type RunStatus, type Verdict, type VerdictOutput, type VolleyConfig, create_renderer, exit_code_for_error, exit_code_for_status, expand_at_file, gate, initial_state, load_config_file, resolve_config, run_volley, status_of, verdict_schema };