@robmclarty/volley 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,17 +1,18 @@
-import { Engine, FinishReason, StreamChunk, Throughput, UsageTotals } from "fascicle";
+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). */
@@ -22,6 +23,11 @@ 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';
+/** 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
@@ -51,13 +57,14 @@ type VolleyConfig = {
   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;
@@ -72,12 +79,13 @@ type ResolvedConfig = {
    * 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`), then its default, never to the critic's URL. Only
-   * a provider volley reaches at a base URL (ollama, lmstudio) takes one. */
+   * `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 local (non-`claude_cli`) builder to run
-   * without a sandbox — it gets a real host bash. Refused by default. */
+  /** 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;
@@ -92,7 +100,7 @@ type ResolvedConfig = {
   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
+   * 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:
@@ -119,6 +127,10 @@ type ResolvedConfig = {
    * `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;
@@ -209,12 +221,15 @@ type PhaseRecord = {
   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. */
+   * 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
@@ -287,12 +302,92 @@ type ResolveOptions = {
   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. */
 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';
 //#endregion
@@ -303,6 +398,9 @@ type RendererOptions = {
   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 = {
@@ -318,6 +416,30 @@ type 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;
@@ -325,6 +447,22 @@ type OrchestratorDeps = {
    * 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;
 };
@@ -346,17 +484,6 @@ export declare function gate(config: ResolvedConfig, state: LoopState): {
 };
 export declare function status_of(value: LoopState, converged: boolean): RunStatus;
 //#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>;
-//#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