@signalridge/pi-workflows 1.6.0 → 1.7.1

package/src/rpc-client.ts

@@ -172,6 +172,16 @@ export interface ManagedProtocolCheck {
   routingPolicy: ManagedRoutingPolicy;
   /** Whole-catalogue identity; used only where a per-tier identity cannot be. */
   routingPolicyFingerprint: string;
+  /**
+   * The host's background-agent pool size, when the peer published one.
+   *
+   * A workflow agent occupies one of those slots like any other background
+   * agent, so this is the width the run can actually achieve; dispatching past
+   * it only fills the host's queue. Undefined means the peer predates the
+   * field or answered through the readiness broadcast, which carries no
+   * requested fields — the caller then falls back to its own default.
+   */
+  maxConcurrent?: number;
 }
 
 export async function checkManagedSpawnProtocol(
@@ -213,7 +223,9 @@ export async function checkManagedSpawnProtocol(
     });
     const sendPing = () => {
       try {
-        events.emit("subagents:rpc:ping", { requestId: id });
+        // Additive reply fields are requested by name: the reply envelope is
+        // strictly parsed, so a peer may not volunteer one.
+        events.emit("subagents:rpc:ping", { requestId: id, include: ["maxConcurrent"] });
       } catch (error: unknown) {
         finish(undefined, error instanceof Error ? error : new Error(String(error)));
       }
@@ -254,6 +266,7 @@ export async function checkManagedSpawnProtocol(
   return {
     routingPolicy: ping.routingPolicy.policy,
     routingPolicyFingerprint: ping.routingPolicy.fingerprint,
+    ...(ping.maxConcurrent === undefined ? {} : { maxConcurrent: ping.maxConcurrent }),
   };
 }
 
@@ -367,7 +380,7 @@ export function createManagedSpawnClient(
           agentId,
           owner,
         },
-        sessionSignal,
+        undefined,
       );
     },
     async reconcileManaged(spawnKey, owner) {
@@ -390,10 +403,15 @@ export function createManagedSpawnClient(
           ...(owners ? { owners } : {}),
           timeoutMs,
         },
-        sessionSignal,
+        undefined,
         timeoutMs + 1_000,
       );
-      if (!isRecord(data) || typeof data.settled !== "boolean" || !Array.isArray(data.pending)) {
+      if (
+        !isRecord(data) ||
+        typeof data.settled !== "boolean" ||
+        !Array.isArray(data.pending) ||
+        !data.pending.every((id) => typeof id === "string" && id.length > 0)
+      ) {
         throw new Error("subagents quiescence returned an invalid response");
       }
       const pending = data.pending.filter((id): id is string => typeof id === "string");

package/src/runtime.ts

@@ -116,6 +116,8 @@ export type Limiter = <T>(fn: () => Promise<T>) => Promise<T>;
 /** The dispatch boundary the engine implements over spawn-managed RPC. */
 export interface WorkflowAgentRunner {
   run(prompt: string, options?: AgentRunOptions): Promise<unknown>;
+  /** Managed runners bound and confirm cleanup of aborted dispatches. */
+  waitForCleanup?(): Promise<void>;
 }
 
 export interface AgentRunOptions {
@@ -155,6 +157,16 @@ export interface AgentRunOptions {
   onTierResolved?: (tier: string) => void;
   onUsage?: (usage: AgentUsage) => void;
   onHistory?: (history: unknown[]) => void;
+  /**
+   * The agent left the host's queue and is now running.
+   *
+   * A dispatched agent does not necessarily start: it takes a background slot
+   * from pi-subagents, and a fan-out wider than that pool waits. The wall clock
+   * is restarted from this point so queue time is not charged against the work,
+   * which is what let a batch dispatched behind a busy pool fail as timeouts
+   * without any of it having run.
+   */
+  onRunning?: () => void;
 }
 
 export interface AgentOptions {
@@ -260,6 +272,17 @@ export interface WorkflowRunOptions {
   workflowDepth?: number;
   cwd?: string;
   concurrency?: number;
+  /**
+   * The host's background-agent pool size, read live from the peer at each
+   * start and resume.
+   *
+   * It is both the default width and the ceiling: a workflow agent occupies one
+   * of those slots like any other background agent, so dispatching past the pool
+   * does not run wider — it fills the host's single queue ahead of the host's own
+   * spawns. One setting therefore governs the fleet, and a run neither has to
+   * guess it nor can exceed it.
+   */
+  hostMaxConcurrent?: number;
   agentRetries?: number;
   tokenBudget?: number | null;
   signal?: AbortSignal;
@@ -279,7 +302,7 @@ export interface WorkflowRunOptions {
   sharedStore?: SharedStore;
   /** Resolve a nested `workflow(name)` reference to the script it names. */
   loadSavedWorkflow?: (name: string) => string | undefined;
-  confirm?: (promptText: string, options: CheckpointOptions) => Promise<unknown>;
+  confirm?: (promptText: string, options: CheckpointOptions, signal?: AbortSignal) => Promise<unknown>;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onRuntimeEvent?: (event: WorkflowRuntimeEvent) => void;
@@ -337,9 +360,36 @@ export const MAX_AGENTS_PER_RUN = 1000;
 export const MAX_CALLS_PER_WORKFLOW = 1_000;
 /** Per-call item cap, matching the bounded batch contract used by reference engines. */
 export const MAX_FANOUT_ITEMS = 4_096;
-export const MAX_CONCURRENCY = 16;
+/**
+ * Upper bound on agents in flight at once.
+ *
+ * A dispatched agent is a remote call this process waits on, not work it
+ * performs, so the ceiling guards against a runaway script rather than against
+ * machine capacity. The real throttle belongs to pi-subagents: every managed
+ * spawn takes one of its `maxConcurrent` background slots, so a host that wants
+ * a narrower fleet narrows it there, once, for every agent it runs.
+ */
+export const MAX_CONCURRENCY = 64;
+/**
+ * In-flight agents when neither the run nor the caller names a number.
+ *
+ * Deliberately a constant rather than a function of `hardwareConcurrency`. Core
+ * count measures what this process can compute, and dispatching an agent
+ * computes nothing here; deriving the default from it fanned a 14-core host out
+ * 12 ways and a 4-core host 2 ways for identical, entirely remote work.
+ */
+export const DEFAULT_CONCURRENCY = 16;
 export const MAX_AGENT_RETRIES = 3;
-export const DEFAULT_AGENT_TIMEOUT_MS: number | null = 300_000;
+/**
+ * Wall clock for one agent when neither the call nor the run names one.
+ *
+ * It bounds a hang and nothing else. An agent's real budget is the turn, tool
+ * and token ceiling pi-subagents applies to it, which a deep call legitimately
+ * spends over many minutes; a default an order of magnitude shorter than that
+ * budget turned every wide fan-out of real work into a batch of timeouts. Pass
+ * `null` to remove the wall clock and leave the host's budgets in sole charge.
+ */
+export const DEFAULT_AGENT_TIMEOUT_MS: number | null = 1_800_000;
 export const MAX_SCRIPT_SYNC_MS = 1_000;
 
 // ── Determinism guardrail ────────────────────────────────────────────────────
@@ -865,13 +915,33 @@ async function withTimeout<T>(
   ms: number | null,
   label: string,
   onTimeout?: () => void,
+  /**
+   * Receives a `restart()` that re-arms the clock from now.
+   *
+   * The clock is armed at dispatch and restarted when the agent reports that it
+   * started, rather than only armed on that report: a report that never arrives
+   * must degrade to the old behaviour, not to an agent that can hang forever.
+   */
+  onArm?: (restart: () => void) => void,
+  waitForCleanup?: () => Promise<void>,
 ): Promise<T> {
-  if (ms === null) return promise;
+  if (ms === null) {
+    onArm?.(() => {});
+    return promise;
+  }
 
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  // The `restart` handed out below outlives this call: the holder keeps it in a
+  // closure that the caller may still reach after the race settles. Re-arming
+  // then would leave a live timer nothing clears, firing `onTimeout` on a
+  // finished agent long after the fact, so settlement makes it inert here
+  // rather than relying on every holder to guard its own call.
+  let settled = false;
+  let timedOut = false;
 
   const timeoutPromise = new Promise<never>((_, reject) => {
-    timeoutId = setTimeout(() => {
+    const fire = () => {
+      timedOut = true;
       try {
         onTimeout?.();
       } catch {
@@ -884,13 +954,23 @@ async function withTimeout<T>(
           { recoverable: true },
         ),
       );
-    }, ms);
+    };
+    timeoutId = setTimeout(fire, ms);
+    onArm?.(() => {
+      if (settled) return;
+      if (timeoutId) clearTimeout(timeoutId);
+      timeoutId = setTimeout(fire, ms);
+    });
   });
 
   try {
     return await Promise.race([promise, timeoutPromise]);
   } finally {
+    settled = true;
     if (timeoutId) clearTimeout(timeoutId);
+    // The timeout wins the race immediately, but managed cleanup must settle
+    // (or durably fence the run) before script continuation and journal output.
+    if (timedOut) await waitForCleanup?.();
   }
 }
 
@@ -1185,19 +1265,38 @@ export async function runWorkflow<T = unknown>(
   };
 
   const agentRunner = options.agent;
+  // The host's pool is the width that can actually be achieved, so it is the
+  // default when it is known and the ceiling when it is not the default.
+  // DEFAULT_CONCURRENCY only covers a peer that published no pool size.
+  const requestedConcurrency = options.concurrency ?? options.hostMaxConcurrent ?? DEFAULT_CONCURRENCY;
   const concurrency = normalizeConcurrency(
-    options.concurrency ??
-      Math.max(
-        1,
-        (globalThis as { navigator?: { hardwareConcurrency?: number } }).navigator?.hardwareConcurrency ?? 8,
-      ) - 2,
+    options.hostMaxConcurrent === undefined
+      ? requestedConcurrency
+      : Math.min(requestedConcurrency, options.hostMaxConcurrent),
   );
+  // Only a caller who asked for a specific width can be surprised by the clamp,
+  // and the guidance now tells everything else to omit the field — so the one
+  // caller that set it is exactly the one owed an explanation for the number it
+  // did not get.
+  // Floored, not raw: normalizeConcurrency floors, and reporting 12.5 -> 12 as a
+  // clamp would blame a bound that did not bite.
+  const askedConcurrency = options.concurrency === undefined ? undefined : Math.floor(options.concurrency);
+  const concurrencyClampNotice =
+    askedConcurrency !== undefined && askedConcurrency > concurrency
+      ? `concurrency ${askedConcurrency} clamped to ${concurrency}` +
+        // Name the bound that actually bit. A pool above MAX_CONCURRENCY is not
+        // the reason for the clamp even though it is below what was requested.
+        (concurrency === options.hostMaxConcurrent
+          ? `: the host's subagent pool is ${concurrency}, and dispatching past it only queues`
+          : `: the runtime ceiling is ${MAX_CONCURRENCY}`)
+      : undefined;
 
   const log = (message: unknown) => {
     const text = String(message);
     state.logs.push(text);
     options.onLog?.(text);
   };
+  if (concurrencyClampNotice !== undefined) log(concurrencyClampNotice);
 
   /**
    * The strength table this run will honor, target-checked once at start.
@@ -1584,6 +1683,10 @@ export async function runWorkflow<T = unknown>(
               );
             }
 
+            // Set by withTimeout below, and called by the dispatcher when the
+            // agent leaves the host queue. Undefined until then: a start that
+            // beats the arming simply leaves the full clock ahead of it.
+            let restartTimeout: (() => void) | undefined;
             const runPromise = agentRunner.run(promptText + schemaInstruction + repairFeedback, {
               label,
               sessionName: agentOptions.thread
@@ -1614,9 +1717,21 @@ export async function runWorkflow<T = unknown>(
               onHistory: (history: unknown[]) => {
                 options.onAgentHistory?.({ id: deltaKey, label, phase: assignedPhase, history });
               },
+              onRunning: () => {
+                restartTimeout?.();
+              },
             });
             runPromise.catch(() => {});
-            let result = await withTimeout(runPromise, timeout, label, () => agentController.abort());
+            let result = await withTimeout(
+              runPromise,
+              timeout,
+              label,
+              () => agentController.abort(),
+              (restart) => {
+                restartTimeout = restart;
+              },
+              options.agent?.waitForCleanup,
+            );
 
             throwIfAborted();
             if (isEmptyTextAgentResult(result, schema)) {
@@ -1683,6 +1798,18 @@ export async function runWorkflow<T = unknown>(
             });
             return result;
           } catch (error) {
+            // A timeout waits for managed cleanup before reaching this catch.
+            // Explicit cancellation may arrive during that await; it wins only
+            // over this recoverable timeout, never over a fatal cleanup fence.
+            if (
+              options.signal?.aborted &&
+              !shared.runFatalController.signal.aborted &&
+              error instanceof WorkflowError &&
+              error.recoverable &&
+              error.code === WorkflowErrorCode.AGENT_TIMEOUT
+            ) {
+              throwIfAborted();
+            }
             if (isAborted()) throw error;
 
             const workflowError = wrapError(error, { agentLabel: label });
@@ -2179,7 +2306,34 @@ export async function runWorkflow<T = unknown>(
 
     let reply: unknown;
     if (options.confirm) {
-      reply = await options.confirm(promptText, checkpointOptions);
+      // Host-only cancellation must not affect author options or replay hashes.
+      const signal = options.signal
+        ? AbortSignal.any([options.signal, shared.runFatalController.signal])
+        : shared.runFatalController.signal;
+      const confirm = options.confirm;
+      let onAbort: (() => void) | undefined;
+      try {
+        const cancelled = new Promise<never>((_resolve, reject) => {
+          onAbort = () => {
+            try {
+              throwIfAborted();
+            } catch (error) {
+              reject(error);
+            }
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        });
+        // Older host callbacks may ignore the optional signal. Still release
+        // the runtime wait, and observe any eventual callback rejection.
+        const answer = Promise.resolve().then(() => {
+          throwIfAborted();
+          return confirm(promptText, checkpointOptions, signal);
+        });
+        reply = await Promise.race([answer, cancelled]);
+      } finally {
+        if (onAbort) signal.removeEventListener("abort", onAbort);
+      }
     } else if (checkpointOptions.headless === "abort") {
       throw new WorkflowError(
         `checkpoint "${promptText}" needs human input but none is available (headless run)`,