@robmclarty/volley 0.5.2 → 0.5.4

package/dist/index.js

@@ -1506,6 +1506,7 @@ function make_builder_step(deps) {
   return model_call({
     engine: deps.engine,
     id: "builder",
+    description: "model call: one agentic session in the build root",
     provider: config.builder_provider,
     model: config.builder_model,
     system: resolve_builder_system(config),
@@ -1747,11 +1748,16 @@ function make_critic_tools_step(deps) {
   return model_call2({
     ...critic_call_config(deps),
     id: "critic_tools",
+    description: "model call with read-only workspace tools",
     ...critic_tool_options(deps.config)
   });
 }
 function make_critic_toolless_step(deps) {
-  return model_call2({ ...critic_call_config(deps), id: "critic_toolless" });
+  return model_call2({
+    ...critic_call_config(deps),
+    id: "critic_toolless",
+    description: "model call judging from the check output and a file list"
+  });
 }
 function critic_retryable(config) {
   return (err) => is_retryable_critic_error(config, err);
@@ -2342,14 +2348,18 @@ function build_critic(deps) {
   const retryable = critic_retryable(deps.config);
   return fallback(
     retry(make_critic_tools_step(deps), {
+      description: "one more try after a stream death, local providers only",
       max_attempts: MAX_CRITIC_RETRIES + 1,
       backoff_ms: 0,
       when: retryable,
       project: with_retries
     }),
-    pipe(make_critic_toolless_step(deps), as_degraded),
+    pipe(make_critic_toolless_step(deps), as_degraded, {
+      description: "mark the verdict degraded"
+    }),
     {
       name: "critic",
+      description: "judge without tools if a local critic's stream keeps dying",
       when: retryable,
       handoff: (prompt) => toolless_critic_prompt(deps.config, prompt),
       project: with_fallback_cause
@@ -2365,13 +2375,27 @@ function build_flow(deps, resume_from) {
     bash_executor: deps.bash_executor
   });
   const critic = build_critic({ engine: deps.engine, config, on_chunk: renderer.critic_chunk });
-  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx));
-  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s));
-  const check = step("check", (s, ctx) => check_phase(deps, s, ctx));
-  const critique = step("critique", (s, ctx) => critique_phase(deps, critic, s, ctx));
-  const record = step("record", (s) => record_phase(deps, s));
+  const build = step("build", (s, ctx) => build_phase(deps, builder, s, ctx), {
+    description: "open the iteration, run the builder, measure the change",
+    arm: builder
+  });
+  const skip_verify = step("skip_verify", (s) => skip_verify_phase(deps, s), {
+    description: "record the check as skipped and call no critic"
+  });
+  const check = step("check", (s, ctx) => check_phase(deps, s, ctx), {
+    description: "the deterministic gate: checkride, a command, or none"
+  });
+  const critique = step(
+    "critique",
+    (s, ctx) => critique_phase(deps, critic, s, ctx),
+    { description: "the read-only critic's verdict and feedback", arm: critic }
+  );
+  const record = step("record", (s) => record_phase(deps, s), {
+    description: "archive the iteration and rewrite the run summary"
+  });
   const verify = branch({
     name: "verify",
+    description: "did the build alone cross the cost cap?",
     when: (s) => cost_cap_hit(config, s),
     // fascicle names this arm `then`. It holds a Step object, never a function,
     // so nothing can mistake the config for a thenable.
@@ -2384,9 +2408,12 @@ function build_flow(deps, resume_from) {
   });
   return loop({
     name: "volley",
+    description: "one round per iteration, up to max_iterations",
     init: (input) => input.resume_from ?? initial_state(),
     body: iteration,
-    guard: step("gate", (s) => gate(config, s)),
+    guard: step("gate", (s) => gate(config, s), {
+      description: "stop on approval over a green check, the cost cap, or a gate edit"
+    }),
     finish: (s, { converged }) => ({ value: s, converged }),
     max_rounds: remaining_iterations(config, resume_from)
   });