@robmclarty/volley 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -32,7 +32,13 @@ 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' |
+/** 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';
+/** What a run does: the builder/critic loop (`run`), or one check and one
+ * critique of a change already made, with no builder at all (`critique`). */
+type RunMode = 'run' | 'critique';
 /** User-facing configuration, before resolution (config file / flags). */
 type VolleyConfig = {
   prompt: string;
@@ -43,6 +49,8 @@ type VolleyConfig = {
   builder_provider?: BuilderProvider;
   builder_url?: string;
   builder_max_steps?: number;
+  builder_max_tool_calls?: number;
+  builder_max_output_tokens?: number;
   allow_unsandboxed_builder?: boolean;
   critic_model?: string;
   critic_provider?: CriticProvider;
@@ -69,6 +77,13 @@ type ResolvedConfig = {
   version: 2;
   run_id: string;
   started_at: string;
+  /** A run, or a critique (`volley critique`). A critique's builder fields
+   * hold the defaults, untouched by flags and the environment, since no
+   * builder is ever constructed, and its loop settings are one round with
+   * nothing isolated or committed. */
+  mode: RunMode;
+  /** The task. A critique needs none, since a critic judges against the
+   * criteria alone, so it's empty unless one was given to record. */
   prompt: string;
   criteria: string;
   check: CheckMode;
@@ -84,6 +99,21 @@ type ResolvedConfig = {
    * lmstudio, openrouter) takes one. */
   builder_url: string | null;
   builder_max_steps: number;
+  /** How many tool calls a tool-loop builder may make in one turn, reads
+   * aside (`read_file`, `search_files`, `list_files` are `read_only` and
+   * don't count); fascicle runs a turn's calls in order up to the first one
+   * past the cap, drops the rest, and tells the model which it dropped. 1 by
+   * default, since some model and runtime pairs return parallel calls badly;
+   * raise it for a pair that handles them. Ignored by the `claude_cli`
+   * builder. */
+  builder_max_tool_calls: number;
+  /** The most output tokens a tool-loop builder may generate in one turn,
+   * reasoning included, or null to leave each turn to the provider's own
+   * limit. 16384 by default on a local builder (ollama, lmstudio), null on
+   * openrouter. A turn cut off at it before it made a tool call costs that
+   * one step, not the session: fascicle feeds back that it hit the limit and
+   * the loop goes on. Ignored by the `claude_cli` builder. */
+  builder_max_output_tokens: number | 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;
@@ -127,9 +157,12 @@ 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. */
+  /** The root that holds each run's state at `<state_dir>/<run_id>/`, as an
+   * absolute path: `--state-dir`, else the default root,
+   * `$XDG_STATE_HOME/volley` or `~/.local/state/volley`. `resolve_config`
+   * always sets one. Null is the layout older runs used, `<workspace>/.volley/`,
+   * rotated aside by the next fresh run: a run an older volley started
+   * resumes in it, and a hand-built config can still ask for it. */
   state_dir: string | null;
   workspace: string;
   verbose: boolean;
@@ -154,6 +187,9 @@ type CheckResult = {
   detail: CheckArtifact[];
   /** Raw checkride summary JSON (when the runner is checkride). */
   summary?: unknown;
+  /** checkride's capped excerpt of the failing slots (`.check/digest.md`),
+   * when the check failed and checkride wrote one. */
+  digest?: string;
   /** Captured combined output (when the runner is a shell command). */
   log?: string;
 };
@@ -210,6 +246,10 @@ type PhaseRecord = {
    * counts behind the salvage-rate health metric. */
   tool_calls: number;
   salvaged_tool_calls: number;
+  /** Turns the provider cut off at the output cap before they made a tool
+   * call (`--builder-max-output-tokens`), each of which cost a step and went
+   * on. Set on a builder record when any was; absent otherwise. Additive. */
+  truncated_turns?: 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
@@ -266,11 +306,14 @@ type LoopState = {
   builder_cost_usd: number;
   critic_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;
   iteration_cost_usd: number;
   halt: HaltReason;
   cost_warned: boolean;
 };
-/** Projection of final loop state; `.volley/summary.json` mirrors this. */
+/** Projection of final loop state; the run's `summary.json` mirrors this. */
 type RunResult = {
   run_id: string;
   status: RunStatus;
@@ -282,14 +325,27 @@ type RunResult = {
   builder_cost_usd: number;
   critic_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
+   * warning a run prints for each goes to stderr, which `--json` silences, so
+   * a harness reads it here. Always 0 for a `claude_cli` builder, which has
+   * no step limit, and for a critique. */
+  builder_max_steps_hits: 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. */
+   * one. `--json` consumers read it here; the run's `summary.json` mirrors it. */
   salvaged_branch: string | null;
+  /** A run, or a critique, which runs no builder. */
+  mode: RunMode;
+  /** Where this run keeps its config, summary, trajectory, feedback, verdict,
+   * and iterations: `<state_dir>/<run_id>/` under a state root, else the
+   * workspace's `.volley/`. Inside the sandbox container it is the container's
+   * path, which a harness maps back to the directory it mounted. */
+  run_state_dir: string;
 };
 //#endregion
 //#region src/config.d.ts
@@ -307,6 +363,12 @@ type ResolveOptions = {
    * while under `volley acp` each of its commands `ask`s a person first, which
    * takes the container's place. */
   uncontained_builder?: 'refuse' | 'ask';
+  /** Where the run's state goes, in place of what the config says: `volley
+   * resume` passes the root it found the run under, or null for a run an older
+   * volley kept in the workspace's `.volley/`, which resumes there. */
+  state_dir?: string | null;
+  /** A run (the default), or a critique, which has no builder or loop. */
+  mode?: RunMode;
 };
 /** Merge, expand, and validate a raw `VolleyConfig` into a `ResolvedConfig`.
  * `check_resolved` comes from check detection against the workspace, so the
@@ -365,13 +427,19 @@ type BuilderDeps = {
 };
 //#endregion
 //#region src/critic/run.d.ts
+/** A critic that holds tools isn't constrain-decoded, so nothing stops it
+ * answering null for the feedback or the unmet list, as GLM did on approving.
+ * Both fields allow null and read it as empty, so that answer is a verdict
+ * rather than a schema failure that ends the run. fascicle sends the schema's
+ * input side, so the model sees each field as its type or null, still
+ * required; `.describe()` comes last so the description stays on the field. */
 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>;
+  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>>;
 }, z.core.$strip>;
 type VerdictOutput = z.infer<typeof verdict_schema>;
 type CriticDeps = {
@@ -399,7 +467,7 @@ type RendererOptions = {
   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`). */
+   * short (default: "the run's trajectory.jsonl"). */
   trajectory_path?: string;
   write?: (text: string) => void;
 };
@@ -467,6 +535,25 @@ type OrchestratorDeps = {
   install_signal_handlers?: boolean;
 };
 export declare function run_volley(config: ResolvedConfig, deps: OrchestratorDeps, resume_from?: LoopState | null): Promise<RunResult>;
+/** What a critique runs with: what a run does, less the builder's seat, plus
+ * the revision its change is measured from. */
+type CritiqueDeps = Omit<OrchestratorDeps, 'seats'> & {
+  /** The revision the change under review is measured from (`--baseline`):
+   * everything that differs from it, committed or not, untracked files
+   * included. HEAD when absent, so the uncommitted edits are the change. */
+  baseline?: string;
+  /** The critic's tools in place of volley's reads, as for a run's critic. */
+  critic?: Omit<CriticSeat, 'engine'>;
+};
+/**
+ * `volley critique`: the check and the critic, once, over a change already
+ * made. No builder is constructed, and the engine serves the critic's seat
+ * alone, so a critic can be measured on fixed, labeled changes without paying
+ * for builder turns. It writes the state a one-round run does, with the mode
+ * recorded, and ends `success` on approval over a green check, else
+ * `rejected`.
+ */
+export declare function run_critique(config: ResolvedConfig, deps: CritiqueDeps): Promise<RunResult>;
 //#endregion
 //#region src/loop_state.d.ts
 export declare function initial_state(): LoopState;
@@ -485,6 +572,13 @@ export declare function gate(config: ResolvedConfig, state: LoopState): {
 export declare function status_of(value: LoopState, converged: boolean): RunStatus;
 //#endregion
 //#region src/sandbox.d.ts
+/** Where volley inside the container keeps each run's state when no
+ * `--state-dir` names a root: the default root under the pinned `HOME`, since
+ * the image sets no `XDG_STATE_HOME`. `sandbox_run_args`'s `run_state` binds one
+ * run's host directory at that run's directory under it, so the state outlives
+ * the `--rm` container. Exported so a harness can map a contained run's
+ * `run_state_dir` back to the directory it mounted. */
+export declare const SANDBOX_STATE_ROOT: string;
 /** 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
@@ -530,7 +624,7 @@ export declare function network_run_args(network: SandboxNetwork, network_name:
 /**
  * The hardened `docker run` argv that launches volley inside its container.
  * Pure and exported so the flag set is unit-testable without a
- * daemon and the blessed examples / `--dry-run` preflight can render it.
+ * daemon and the blessed examples and a parent harness can render it.
  *
  * A one-shot, foreground `--rm` container — the whole run *is* this
  * container (an earlier design ran a detached `-d … sleep infinity` daemon volley
@@ -542,6 +636,25 @@ export declare function network_run_args(network: SandboxNetwork, network_name:
  * the image entrypoint (the opt-in real-docker isolation test runs a raw `sh`
  * this way).
  *
+ * `run_state` binds the run's own state directory on the host,
+ * `<root>/<run_id>/`, at `<SANDBOX_STATE_ROOT>/<run_id>/`, where volley inside
+ * keeps that run's state when no `--state-dir` names a root, so it outlives the
+ * container at the path a run on the host would use. Only the one directory
+ * is mounted, never the root: the builder inside runs arbitrary commands, so
+ * it can rewrite its own run's state but can't read another run's trajectory
+ * or plant a check in another run's config. Its own run's state is still the
+ * builder's to rewrite, config.json included, so a host-side resume refuses
+ * that config, which volley signs only outside the sandbox (`./trust.ts`), and
+ * a directory holding a symlink: resume a contained run inside the container,
+ * with the same mount. Create the
+ * directory on the host first, empty (Docker on Linux makes a missing bind
+ * source owned by root, which the container's user can't write), and pass the
+ * same id to volley as `--run-id`. Keep it outside `build_root`, so the check
+ * never reads it, and pass no `XDG_STATE_HOME` in `env`, which would move the
+ * root off the mount. Omit it and no state is mounted: a contained run keeping
+ * its state under the default root then stops before spending (exit 5),
+ * since the read-only root filesystem leaves it nowhere to write.
+ *
  * `store_volume` mounts the named volume as the pnpm store; omit it and no store
  * is mounted. A store is shared by every run that mounts it, so a caller that
  * installs dependencies in a separate container first can keep the builder's
@@ -551,13 +664,17 @@ export declare function network_run_args(network: SandboxNetwork, network_name:
  * Never emits `--privileged` and refuses `--user 0`: volley must not hand
  * the sandbox root or full capabilities. Everything writable under the
  * `--read-only` rootfs is an explicit tmpfs or volume; the bind-mounted worktree
- * is the one host-visible write path.
+ * and, when one is named, the state root are the host-visible write paths.
  */
 export declare function sandbox_run_args(options: {
   image: string;
   build_root: string;
   uid: number | null;
   gid: number | null;
+  run_state?: {
+    root: string;
+    run_id: string;
+  } | null;
   store_volume?: string | null;
   network: SandboxNetwork;
   network_name: string;
@@ -568,6 +685,13 @@ export declare function sandbox_run_args(options: {
   command?: ReadonlyArray<string>;
 }): string[];
 //#endregion
+//#region src/workspace.d.ts
+/** The root each run's state sits under when `--state-dir` names none:
+ * `$XDG_STATE_HOME/volley`, else `<home>/.local/state/volley`. A relative
+ * `XDG_STATE_HOME` is ignored, as the XDG spec says. `home` is the host's by
+ * default; the sandbox passes its container's to spell the same root inside. */
+export declare function default_state_root(env: Readonly<Record<string, string | undefined>>, home?: string): string;
+//#endregion
 //#region src/exit_codes.d.ts
 export declare const EXIT_SUCCESS = 0;
 export declare const EXIT_BUDGET_EXHAUSTED = 2;
@@ -580,5 +704,5 @@ 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 };
+export type { BuilderPermissionMode, CheckArtifact, CheckMode, CheckResult, CheckRunnerKind, CostSource, CriticPreset, CriticProvider, CritiqueDeps, HaltReason, LoopState, PhaseRecord, RenderMode, Renderer, RendererOptions, ResolvedConfig, RunMode, RunResult, RunStatus, SandboxNetwork, Verdict, VerdictOutput, VolleyConfig };
 //# sourceMappingURL=index.d.ts.map