@robmclarty/volley 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -1,8 +1,16 @@
-import { Engine, FinishReason, StreamChunk, Throughput, Tool, ToolApprovalHandler, TrajectoryLogger, UsageTotals } from "fascicle";
+import { EffortLevel, Engine, FinishReason, StreamChunk, Throughput, Tool, ToolApprovalHandler, TrajectoryLogger, UsageTotals } from "fascicle";
 import { z } from "zod";
 //#region src/types.d.ts
 type Verdict = 'approved' | 'changes_requested';
+/** One rung of the effort ladder, and the critic's effort: fascicle's
+ * per-call `effort` levels less `none`, which on `claude_cli` sets nothing and
+ * leaves Claude Code at its own default, possibly above `low`, so it can't
+ * stand on a ladder that climbs. */
+type EffortRung = Exclude<EffortLevel, 'none'>;
 type CriticPreset = 'reviewer' | 'optimizer' | 'researcher';
+/** `--tester`: whether a tester writes a failing test from the criteria
+ * before the first build. */
+type TesterSetting = 'on' | 'off';
 /** Transport for the critic role. The critic is read-only + schema-constrained,
  * 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
@@ -33,6 +41,10 @@ type RunStatus = 'running' | 'success' | 'budget_exhausted' | 'cost_cap_reached'
  * 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' |
+/** The check passed right after the tester wrote its test, before any
+ * build: the test is vacuous or the work is already done, and either way no
+ * builder is paid to find out (move 1's D6, D17). */
+'tester_passed_early' |
 /** A critique's other outcome: the critic requested changes, or the check
  * failed, on the one change it reviewed. A run never ends this way. */
 'rejected' | 'interrupted' | 'error';
@@ -52,10 +64,14 @@ type VolleyConfig = {
   builder_max_tool_calls?: number;
   builder_max_output_tokens?: number;
   builder_trim_history?: number;
+  effort_ladder?: EffortRung[];
   allow_unsandboxed_builder?: boolean;
   critic_model?: string;
   critic_provider?: CriticProvider;
   critic_url?: string;
+  critic_effort?: EffortRung;
+  tester?: TesterSetting;
+  tester_model?: string;
   builder_permission_mode?: BuilderPermissionMode;
   critic?: CriticPreset | (string & {});
   max_iterations?: number;
@@ -120,6 +136,12 @@ type ResolvedConfig = {
    * every turn whole. Null by default, until a long local session is shown
    * to run faster with it on. Ignored by the `claude_cli` builder. */
   builder_trim_history: number | null;
+  /** The efforts the builder climbs (`--effort-ladder`): each build runs one
+   * rung further up than the last, and the top rung repeats. Null, the
+   * default, passes no effort at all, so the builder's call is today's. On
+   * `ollama` and `lmstudio`, whose transports drop effort, every rung is the
+   * same and the ladder is flat. */
+  effort_ladder: EffortRung[] | null;
   /** 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;
@@ -128,6 +150,18 @@ type ResolvedConfig = {
   /** 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;
+  /** The critic's effort on every call (`--critic-effort`), apart from the
+   * builder's ladder: `high` when a ladder is set and nothing names one, since
+   * the critic is what makes a cheap build safe, else null, which passes no
+   * effort, as before there was a ladder. */
+  critic_effort: EffortRung | null;
+  /** Whether a tester runs before the first build (`--tester on`), writing a
+   * failing test from the criteria under the test and fixture gate paths. Off
+   * by default. It takes the critic's provider, URL and effort. */
+  tester: boolean;
+  /** The tester's model: `--tester-model`, else the critic's. Null with the
+   * tester off. */
+  tester_model: string | null;
   builder_permission_mode: BuilderPermissionMode;
   critic_preset: CriticPreset | 'custom';
   critic_prompt_path: string | null;
@@ -231,6 +265,9 @@ type ChangeSet = {
 };
 /** Per-phase record for iteration summaries. */
 type PhaseRecord = {
+  /** What the critic found wrong with the tester's test, when it found
+   * anything. Critic-only. Additive. */
+  test_findings?: string[];
   provider: string;
   model: string;
   session_id: string | null;
@@ -276,6 +313,11 @@ type PhaseRecord = {
   critic_degraded?: boolean;
   /** Why the verdict degraded, set with `critic_degraded`. Additive. */
   degrade_cause?: DegradeCause;
+  /** The seat asked for an effort its provider drops (ollama, lmstudio), so
+   * the call ran at the provider's own and a ladder there is flat. Set on a
+   * builder record that ran at a rung and a critic record that ran at
+   * `critic_effort`, when either was ignored; absent otherwise. Additive. */
+  effort_ignored?: true;
   /** 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
@@ -326,7 +368,10 @@ type BuilderStepRecord = {
     output_chars: number;
   }>;
 };
-type HaltReason = 'cost_cap' | 'gate_edit' | null;
+type HaltReason = 'cost_cap' | 'gate_edit' | 'tester_passed_early' | null;
+/** Why a build ran one rung up the ladder from the build before it: that
+ * build's check failed, or its check passed and the critic sent it back. */
+type ClimbReason = 'check_failed' | 'critic_rejected';
 /** Carry-state threaded through the fascicle loop. */
 type LoopState = {
   iteration: number;
@@ -341,14 +386,39 @@ type LoopState = {
   changes: ChangeSet | null;
   builder: PhaseRecord | null;
   critic: PhaseRecord | null;
+  /** This iteration's tester session, or null: the tester runs in iteration 1
+   * only, before its build. */
+  tester: PhaseRecord | null;
+  /** The check run right after the tester, which must fail; null in an
+   * iteration the tester didn't open. Apart from `check`, which is the check
+   * after the build. */
+  tester_check: CheckResult | null;
+  /** What the tester wrote, measured as the builder's changes are; null in an
+   * iteration the tester didn't open, or outside a git repository. */
+  tester_changes: ChangeSet | null;
+  /** Each file the tester wrote, by its hash right after the test phase. A
+   * build that leaves one at that hash didn't edit the gate there (move 1's
+   * D22). Kept for the whole run, and read back on resume. */
+  tester_hashes: Record<string, string>;
   total_usage: UsageTotals;
   total_cost_usd: number;
   builder_cost_usd: number;
   critic_cost_usd: number;
+  /** The tester's spend, apart from the other two seats' (D21). */
+  tester_cost_usd: number;
   check_duration_ms: number;
   /** How many of the run's builder sessions ended on the step limit
    * (`max_steps`) rather than calling finish. */
   builder_max_steps_hits: number;
+  /** Builder sessions the run has started, this iteration's included: build
+   * *k* runs at `effort_ladder[min(k, len) - 1]`. A resumed run reads it back
+   * from the last archived iteration. */
+  builds: number;
+  /** The effort this iteration's build ran at, or null with no ladder. */
+  rung: EffortRung | null;
+  /** Why this iteration's build ran a rung above the last one's, or null when
+   * it didn't: the first build, the top rung repeating, or no ladder. */
+  climbed: ClimbReason | null;
   iteration_cost_usd: number;
   halt: HaltReason;
   cost_warned: boolean;
@@ -364,6 +434,8 @@ type RunResult = {
   total_cost_usd: number;
   builder_cost_usd: number;
   critic_cost_usd: number;
+  /** The tester's spend; 0 with the tester off. Additive. */
+  tester_cost_usd: number;
   check_duration_ms: number;
   /** How many of the run's builder sessions hit the step limit before they
    * called finish: work handed to the check and critic unverified. The
@@ -415,6 +487,12 @@ type ResolveOptions = {
  * 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/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/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
@@ -438,12 +516,6 @@ type BashExecutor = (command: string, options: {
   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;
@@ -480,6 +552,7 @@ export declare const verdict_schema: z.ZodObject<{
   }>;
   feedback: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string, string | null>>;
   unmet_criteria: z.ZodPipe<z.ZodNullable<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[] | null>>;
+  test_findings: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 type VerdictOutput = z.infer<typeof verdict_schema>;
 type CriticDeps = {
@@ -497,15 +570,22 @@ type CriticDeps = {
 };
 //#endregion
 //#region src/render/format.d.ts
-type Role = 'builder' | 'critic' | 'check';
+type Role = 'builder' | 'critic' | 'tester' | 'check';
 //#endregion
 //#region src/render/renderer.d.ts
-type RenderMode = 'default' | 'verbose' | 'quiet' | 'json';
+/** `protocol` is `volley run --protocol runciter.run/1`: the quiet mode's
+ * human lines, with runciter's typed lines (`runciter.progress` for each
+ * phase, `runciter.usage` for each iteration) in place of the phase and cost
+ * lines. */
+type RenderMode = 'default' | 'verbose' | 'quiet' | 'json' | 'protocol';
 type RendererOptions = {
   mode: RenderMode;
   show_thinking: boolean;
   color: boolean;
   max_cost_usd: number | null;
+  /** The run's iteration cap, the `total` of each `runciter.progress` line in
+   * protocol mode. */
+  max_iterations?: number;
   /** Where the run's trajectory is written, named when verbose output is cut
    * short (default: "the run's trajectory.jsonl"). */
   trajectory_path?: string;
@@ -514,8 +594,12 @@ type RendererOptions = {
 type Renderer = {
   builder_chunk: (chunk: StreamChunk) => void;
   critic_chunk: (chunk: StreamChunk) => void;
+  tester_chunk: (chunk: StreamChunk) => void;
   phase_start: (iteration: number, phase: Role) => void;
   phase_end: (iteration: number, phase: Role, ok: boolean, detail?: string) => void;
+  /** The effort this iteration's build runs at, one line per build when a
+   * ladder is set. */
+  rung: (iteration: number, rung: EffortRung, climbed: ClimbReason | null) => void;
   cost_line: (iteration: number, phase: Role, phase_cost: number | null, run_total: number) => void;
   info: (message: string) => void;
   warn: (message: string) => void;
@@ -524,6 +608,23 @@ type Renderer = {
 };
 export declare function create_renderer(options: RendererOptions): Renderer;
 //#endregion
+//#region src/tester/run.d.ts
+type TesterDeps = {
+  engine: Engine;
+  config: ResolvedConfig;
+  on_chunk: (chunk: StreamChunk) => void;
+  /** Tools in place of `tester_tools`, as the critic takes them. A
+   * `claude_cli` tester uses the CLI's own and never takes these. */
+  tools?: ReadonlyArray<Tool>;
+  /** Which set `tools` is, so the system prompt names what the tester holds;
+   * absent, volley's own. */
+  tool_set?: ToolSet;
+  /** Answers each call to a tool that asks first, as under `volley acp`,
+   * where the tester's writes ask as the builder's do. Absent, such a call
+   * fails closed. */
+  on_tool_approval?: ToolApprovalHandler;
+};
+//#endregion
 //#region src/phases.d.ts
 /** How the check runs when the caller sets it, as `volley acp` does. Left
  * out, the check runs unasked with volley's environment less the seats' keys,
@@ -548,6 +649,11 @@ type BuilderSeat = Pick<BuilderDeps, 'engine' | 'tools' | 'tool_set' | 'on_tool_
  * 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'>;
+/** The tester seat: its engine and, when injected, the tools that replace
+ * volley's tester tools, the name of their set, and the handler that answers
+ * their approval requests. Absent, it rides the critic's engine, whose
+ * provider and URL it takes. */
+type TesterSeat = Pick<TesterDeps, 'engine' | 'tools' | 'tool_set' | 'on_tool_approval'>;
 //#endregion
 //#region src/orchestrator.d.ts
 type OrchestratorDeps = {
@@ -563,6 +669,8 @@ type OrchestratorDeps = {
   seats?: {
     builder?: Omit<BuilderSeat, 'engine'>;
     critic?: Omit<CriticSeat, 'engine'>;
+    /** The tester's, which rides the critic's engine. */
+    tester?: Omit<TesterSeat, '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
@@ -599,7 +707,8 @@ export declare function run_critique(config: ResolvedConfig, deps: CritiqueDeps)
 //#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.
+ * edit refusal, a tester's test passing before any build, 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