@robmclarty/volley 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -1,25 +1,18 @@
-import { UsageTotals, FinishReason, Throughput, 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.
- */
-
+import { Engine, FinishReason, StreamChunk, Throughput, Tool, ToolApprovalHandler, TrajectoryLogger, UsageTotals } from "fascicle";
+import { z } from "zod";
+//#region src/types.d.ts
 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';
+ * so it has always been able to run on a local model. `openrouter` reaches a
+ * hosted model over one API key and takes the local critic's tools and
+ * degradation ladder. */
+type CriticProvider = 'claude_cli' | 'ollama' | 'lmstudio' | 'openrouter';
 /** 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';
+ * session; every other provider runs the builder as a volley-driven tool loop
+ * (write/exec tools supplied by the harness), whether its model is local
+ * (`ollama`, `lmstudio`) or hosted (`openrouter`). */
+type BuilderProvider = 'claude_cli' | 'ollama' | 'lmstudio' | 'openrouter';
 type BuilderPermissionMode = 'acceptEdits' | 'bypassPermissions';
 /** `auto`, `none`, or any shell command (the `string & {}` keeps the literal
  * hints in editor completions without collapsing the union). */
@@ -30,116 +23,139 @@ type CostSource = 'provider_reported' | 'engine_derived' | 'unknown';
  * 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'
+/** Why a local critic's verdict came from the tool-less fallback:
+ * `stream_error`, the tool-bearing call kept dying on the provider's stream
+ * after the bounded retry; `step_exhaustion`, it spent its step budget (or
+ * stopped on a tool call) without producing a verdict. */
+type DegradeCause = 'stream_error' | 'step_exhaustion';
+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';
+'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;
+  prompt: string;
+  workspace: string;
+  criteria: string;
+  check?: CheckMode;
+  builder_model?: string;
+  builder_provider?: BuilderProvider;
+  builder_url?: string;
+  builder_max_steps?: number;
+  allow_unsandboxed_builder?: boolean;
+  critic_model?: string;
+  critic_provider?: CriticProvider;
+  critic_url?: string;
+  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;
+  state_dir?: string;
+  verbose?: boolean;
+  quiet?: boolean;
+  json?: boolean;
+  show_thinking?: boolean;
+  dry_run?: boolean;
 };
-/** Fully resolved run configuration; `.volley/config.json` mirrors this. */
+/** Fully resolved run configuration; the run's `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;
+  version: 2;
+  run_id: string;
+  started_at: string;
+  prompt: string;
+  criteria: string;
+  check: CheckMode;
+  check_resolved: CheckRunnerKind;
+  builder_model: string;
+  builder_provider: BuilderProvider;
+  /** The builder seat's own model server base URL (`--builder-url`), as given.
+   * It is normalized, and crossed to the host LLM endpoint when contained, only
+   * where it is used, because the crossing depends on where the run executes.
+   * Null falls back to the provider's env var (`VOLLEY_OLLAMA_URL` /
+   * `VOLLEY_LMSTUDIO_URL` / `VOLLEY_OPENROUTER_URL`), then its default, never to
+   * the critic's URL. Only a provider volley reaches at a base URL (ollama,
+   * lmstudio, openrouter) takes one. */
+  builder_url: string | null;
+  builder_max_steps: number;
+  /** Operator opt-out permitting a 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;
+  /** The critic seat's own model server base URL (`--critic-url`), as given;
+   * resolved like `builder_url`, and null never falls back to the builder's. */
+  critic_url: string | null;
+  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
+   * the run's state stays where `state_dir` puts it (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;
+  /** The root that holds each run's state at `<state_dir>/<run_id>/`
+   * (`--state-dir`), resolved to an absolute path. Null keeps it at
+   * `<workspace>/.volley/`, rotated aside by the next fresh run. */
+  state_dir: string | null;
+  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;
+  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;
+  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
@@ -150,175 +166,310 @@ type ChangeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'unknown';
  * 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;
+  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;
+  /** 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;
-    /** Wall-clock of the phase's model work, the same measure for every provider
-     * so an all-local run and an all-Claude run compare directly. The builder's is
-     * fascicle's `GenerateResult.timing`: the whole call, every turn and the tools
-     * between them. The critic's spans its whole degradation ladder, failed
-     * attempts included, since no one result's timing covers the attempts before
-     * it. Neither counts the Ollama prewarm. */
-    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;
-    /** Output tokens per second over the model's own turns (tool execution and
-     * retry backoff excluded), from fascicle's per-step timing. `basis` is
-     * `decode` when every turn streamed, `blended` when any round trip counted
-     * prefill and network too — always the case for `claude_cli`, whose rate
-     * fascicle derives from the CLI's reported API time. Absent when no turn
-     * carried timing. Additive. */
-    throughput?: Throughput;
+  provider: string;
+  model: string;
+  session_id: string | null;
+  /** Wall-clock of the phase's model work, the same measure for every provider
+   * so an all-local run and an all-Claude run compare directly. The builder's is
+   * fascicle's `GenerateResult.timing`: the whole call, every turn and the tools
+   * between them. The critic's spans its whole degradation ladder, failed
+   * attempts included, since no one result's timing covers the attempts before
+   * it. Neither counts the Ollama prewarm. */
+  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, or ran out of steps before its verdict, 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;
+  /** Why the verdict degraded, set with `critic_degraded`. Additive. */
+  degrade_cause?: DegradeCause;
+  /** Output tokens per second over the model's own turns (tool execution and
+   * retry backoff excluded), from fascicle's per-step timing. `basis` is
+   * `decode` when every turn streamed, `blended` when any round trip counted
+   * prefill and network too — always the case for `claude_cli`, whose rate
+   * fascicle derives from the CLI's reported API time. Absent when no turn
+   * carried timing. Additive.
+   *
+   * On Ollama, `decode` holds only while a turn's first chunk arrives as its
+   * first token is generated. Ollama sends a tool call whole, so a turn whose
+   * only output is a tool call dispatches nothing until generation ends, and
+   * its tokens are divided by the last few milliseconds: a non-thinking seat's
+   * rate reads far too high until robmclarty/fascicle#12 times those turns
+   * another way. A thinking seat needs ai-sdk-ollama 4.3.0 or later, which
+   * streams the reasoning even though volley never sets `think`. */
+  throughput?: Throughput;
 };
 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;
+  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;
+  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;
 };
-
+//#endregion
+//#region src/config.d.ts
 /** `@path/to/file` reads the file; any other string passes through. */
-declare function expand_at_file(value: string, cwd: string): string;
+export 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>;
+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>;
+  cwd?: string;
+  run_id?: string;
+  started_at?: string;
+  env?: Record<string, string | undefined>;
+  /** What happens to a tool-loop builder with nothing between its commands
+   * and the host (`unguarded_builder`): the CLI `refuse`s it, the default,
+   * while under `volley acp` each of its commands `ask`s a person first, which
+   * takes the container's place. */
+  uncontained_builder?: 'refuse' | 'ask';
 };
 /** Merge, expand, and validate a raw `VolleyConfig` into a `ResolvedConfig`.
  * `check_resolved` comes from check detection against the workspace, so the
  * SDK and the CLI resolve `auto` and a command check the same way. */
-declare function resolve_config(raw: VolleyConfig, options?: ResolveOptions): ResolvedConfig;
-
+export declare function resolve_config(raw: VolleyConfig, options?: ResolveOptions): ResolvedConfig;
+//#endregion
+//#region src/builder/tools.d.ts
+/** The raw outcome of running one bash command, before the model-facing
+ * truncation + timeout marker the `bash` tool applies. `status` is the exit code
+ * (null when the process was killed by a signal — e.g. the timeout SIGKILL);
+ * `timed_out` marks the timeout path. */
+type BashOutcome = {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  timed_out: boolean;
+};
+/** How the `bash` tool runs a command: the local `host_bash_executor`
+ * (`spawnSync`) — which under whole-process containment runs *inside*
+ * volley's own hardened container, no `docker exec` hop. The executor runs one
+ * command to completion and returns its raw outcome; the `bash` tool owns the
+ * truncation + timeout marker. Kept as an injectable seam so tests can supply a
+ * fake and a future shape could re-point it (the `docker exec` executor was
+ * retired). */
+type BashExecutor = (command: string, options: {
+  timeout_ms: number;
+  max_capture_bytes: number;
+}) => BashOutcome;
+//#endregion
+//#region src/workspace_tools.d.ts
+/** Which tool set a seat holds, so its prompt names the tools it has: volley's
+ * own (`'volley'`), or fascicle's workspace tools under `volley acp`
+ * (`'acp'`). */
+type ToolSet = 'volley' | 'acp';
+//#endregion
+//#region src/builder.d.ts
+type BuilderDeps = {
+  engine: Engine;
+  config: ResolvedConfig;
+  on_chunk: (chunk: StreamChunk) => void;
+  /** The `bash` executor for a sandboxed local builder (`docker exec` against
+   * the run's container), or null to use the host `spawnSync` default (the
+   * unsandboxed escape hatch, or `claude_cli` which supplies no volley tools). */
+  bash_executor?: BashExecutor | null;
+  /** Tools to hand the builder in place of volley's own set; absent, it gets
+   * that set. A `claude_cli` builder brings its own tools and never takes
+   * these. */
+  tools?: ReadonlyArray<Tool>;
+  /** Which set `tools` is, so the prompt names the tools the builder holds;
+   * absent, volley's own. */
+  tool_set?: ToolSet;
+  /** Answers each call to a tool that asks first (`needs_approval`). Like
+   * `tools`, it reaches every builder but `claude_cli`. Absent, such a call
+   * fails closed. */
+  on_tool_approval?: ToolApprovalHandler;
+};
+//#endregion
+//#region src/critic/run.d.ts
+export 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>;
+type CriticDeps = {
+  engine: Engine;
+  config: ResolvedConfig;
+  on_chunk: (chunk: StreamChunk) => void;
+  /** Tools to hand the critic's tool-bearing call in place of volley's reads;
+   * absent, it gets those. A `claude_cli` critic reads through the CLI's own
+   * tools and never takes these. The critic takes no approval handler, since
+   * nothing it reads with should ever ask. */
+  tools?: ReadonlyArray<Tool>;
+  /** Which set `tools` is, so the harness append names the reads the critic
+   * holds; absent, volley's own. */
+  tool_set?: ToolSet;
+};
+//#endregion
+//#region src/render/format.d.ts
 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.
- */
-
+//#endregion
+//#region src/render/renderer.d.ts
 type RenderMode = 'default' | 'verbose' | 'quiet' | 'json';
 type RendererOptions = {
-    mode: RenderMode;
-    show_thinking: boolean;
-    color: boolean;
-    max_cost_usd: number | null;
-    write?: (text: string) => void;
+  mode: RenderMode;
+  show_thinking: boolean;
+  color: boolean;
+  max_cost_usd: number | null;
+  /** Where the run's trajectory is written, named when verbose output is cut
+   * short (default: `.volley/trajectory.jsonl`). */
+  trajectory_path?: string;
+  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;
+  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;
-
+export declare function create_renderer(options: RendererOptions): Renderer;
+//#endregion
+//#region src/phases.d.ts
+/** How the check runs when the caller sets it, as `volley acp` does. Left
+ * out, the check inherits volley's environment and runs unasked, as on the
+ * CLI. */
+type CheckGate = {
+  /** The whole environment the check runs with, in place of volley's own. */
+  env?: Readonly<Record<string, string>>;
+  /** Asked on the check's card before each check, the way a model call asks
+   * before a gated tool runs. Anything short of an allow keeps the check from
+   * running, and it's recorded as failed. */
+  on_approval?: ToolApprovalHandler;
+};
+//#endregion
+//#region src/flow.d.ts
+/** The builder seat: the engine its calls go through, and, when the caller
+ * injects them, the tools that replace volley's own set, the name of that set
+ * (which its prompt names), and the handler that answers their approval
+ * requests. */
+type BuilderSeat = Pick<BuilderDeps, 'engine' | 'tools' | 'tool_set' | 'on_tool_approval'>;
+/** The critic seat: its engine and, when injected, the tools that replace its
+ * reads and the name of their set. It takes no approval handler, since its
+ * reads never ask. */
+type CriticSeat = Pick<CriticDeps, 'engine' | 'tools' | 'tool_set'>;
+//#endregion
+//#region src/orchestrator.d.ts
 type OrchestratorDeps = {
-    renderer: Renderer;
-    engine?: Engine;
-    abort?: AbortSignal;
-    install_signal_handlers?: boolean;
+  renderer: Renderer;
+  /** An engine to run both seats on in place of the ones built from the
+   * config. It serves both seats as-is, so the seat URLs then steer only
+   * volley's own requests (prewarm and the context probe), not model calls. */
+  engine?: Engine;
+  /** What to hand each seat in place of volley's own wiring: the builder's
+   * tools and the handler that answers their approval requests, and the
+   * critic's tools. A seat or a field left out keeps today's wiring, and a
+   * `claude_cli` seat, which brings its own tools, takes none of it. */
+  seats?: {
+    builder?: Omit<BuilderSeat, 'engine'>;
+    critic?: Omit<CriticSeat, 'engine'>;
+  };
+  /** A second sink for the run's trajectory, beside the run's
+   * `trajectory.jsonl`. With one, the flow runs through `run.stream`, so the
+   * sink also receives each model call's streamed chunks as `model_chunk`
+   * events, which the file never keeps. */
+  trajectory?: TrajectoryLogger;
+  /** The environment the check runs with and the approval it asks first, in
+   * place of inheriting volley's environment and running unasked. */
+  check?: CheckGate;
+  abort?: AbortSignal;
+  install_signal_handlers?: boolean;
 };
-declare function run_volley(config: ResolvedConfig, deps: OrchestratorDeps, resume_from?: LoopState | null): Promise<RunResult>;
-
-declare function initial_state(): LoopState;
+export declare function run_volley(config: ResolvedConfig, deps: OrchestratorDeps, resume_from?: LoopState | null): Promise<RunResult>;
+//#endregion
+//#region src/loop_state.d.ts
+export 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.
@@ -327,34 +478,19 @@ declare function initial_state(): LoopState;
  * 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;
+export declare function gate(config: ResolvedConfig, state: LoopState): {
+  stop: boolean;
+  state: LoopState;
 };
-declare function status_of(value: LoopState, converged: boolean): RunStatus;
-
-/**
- * Critic invocation: a read-only session (`claude_cli`, or a local model with
- * volley's read tools) 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>;
-
+export declare function status_of(value: LoopState, converged: boolean): RunStatus;
+//#endregion
+//#region src/sandbox.d.ts
 /** Canonical identity of the allowlist bridge the examples create (`docker
  * network create --subnet <SANDBOX_NETWORK_SUBNET> <SANDBOX_NETWORK_NAME>`) and
  * the host `DOCKER-USER` rules scope to. Exported so the blessed examples
  * share one spelling of the invocation spec. */
-declare const SANDBOX_NETWORK_NAME = "volley-sandbox-net";
-declare const SANDBOX_NETWORK_SUBNET = "172.31.99.0/24";
+export declare const SANDBOX_NETWORK_NAME = "volley-sandbox-net";
+export declare const SANDBOX_NETWORK_SUBNET = "172.31.99.0/24";
 /**
  * The container's egress posture. Under whole-process containment
  * the model client and the `fetch` tool run inside the container, so its
@@ -390,7 +526,7 @@ type SandboxNetwork = 'none' | 'allowlist';
  * collapses the allowlist targets onto the host gateway (`host.docker.internal`,
  * the Linux-portable spelling — harmless where Docker Desktop already provides it).
  */
-declare function network_run_args(network: SandboxNetwork, network_name: string): string[];
+export declare function network_run_args(network: SandboxNetwork, network_name: string): string[];
 /**
  * The hardened `docker run` argv that launches volley inside its container.
  * Pure and exported so the flag set is unit-testable without a
@@ -417,30 +553,32 @@ declare function network_run_args(network: SandboxNetwork, network_name: string)
  * `--read-only` rootfs is an explicit tmpfs or volume; the bind-mounted worktree
  * is the one host-visible write path.
  */
-declare function sandbox_run_args(options: {
-    image: string;
-    build_root: string;
-    uid: number | null;
-    gid: number | null;
-    store_volume?: string | null;
-    network: SandboxNetwork;
-    network_name: string;
-    name?: string | null;
-    env?: ReadonlyArray<readonly [string, string]>;
-    labels?: ReadonlyArray<readonly [string, string]>;
-    entrypoint?: string | null;
-    command?: ReadonlyArray<string>;
+export declare function sandbox_run_args(options: {
+  image: string;
+  build_root: string;
+  uid: number | null;
+  gid: number | null;
+  store_volume?: string | null;
+  network: SandboxNetwork;
+  network_name: string;
+  name?: string | null;
+  env?: ReadonlyArray<readonly [string, string]>;
+  labels?: ReadonlyArray<readonly [string, string]>;
+  entrypoint?: string | null;
+  command?: ReadonlyArray<string>;
 }): string[];
-
-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, SANDBOX_NETWORK_NAME, SANDBOX_NETWORK_SUBNET, type SandboxNetwork, 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, network_run_args, resolve_config, run_volley, sandbox_run_args, status_of, verdict_schema };
+//#endregion
+//#region src/exit_codes.d.ts
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_BUDGET_EXHAUSTED = 2;
+export declare const EXIT_BUILDER_ERROR = 3;
+export declare const EXIT_CHECK_ERROR = 4;
+export declare const EXIT_CONFIG_ERROR = 5;
+export declare const EXIT_CRITIC_ERROR = 6;
+export declare const EXIT_COST_CAP = 7;
+export declare const EXIT_INTERRUPTED = 130;
+export declare function exit_code_for_status(status: RunStatus): number;
+export declare function exit_code_for_error(err: unknown): number;
+//#endregion
+export type { BuilderPermissionMode, CheckArtifact, CheckMode, CheckResult, CheckRunnerKind, CostSource, CriticPreset, CriticProvider, HaltReason, LoopState, PhaseRecord, RenderMode, Renderer, RendererOptions, ResolvedConfig, RunResult, RunStatus, SandboxNetwork, Verdict, VerdictOutput, VolleyConfig };
+//# sourceMappingURL=index.d.ts.map