@signalridge/pi-workflows 1.5.0 → 1.7.0

package/src/capabilities.ts

@@ -34,6 +34,14 @@ export const WORKFLOW_CAPABILITY_CONTRACT_VERSION = "2.0.0";
 /**
  * The runtime globals a script can rely on. `options` documents each helper's
  * accepted inputs with defaults; `constraints` states the behavioral contract.
+ *
+ * The strength option's type is spelled out on each of the four helpers that
+ * take it, rather than derived from `WORKFLOW_STRENGTHS`, because this array
+ * must stay literal-only: `check:capabilities` evaluates it in an empty VM
+ * realm so the published contract can be read without executing this package.
+ * `strengths.test.ts` pins the four copies against the vocabulary the runtime
+ * enforces, which is the drift protection a shared constant would otherwise
+ * have provided.
  */
 export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
@@ -45,17 +53,17 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "phase", kind: "string", optional: true, default: "current phase" },
       { name: "schema", kind: "plain JSON Schema", optional: true, default: "none" },
       {
-        name: "tier",
-        kind: "agent tier key",
+        name: "strength",
+        kind: '"low" | "medium" | "high"',
         optional: true,
-        default: "the agent's own tier, else agentTiers.defaultTier",
+        default: "no tier is sent; the agent's own tier, else agentTiers.defaultTier",
       },
       { name: "isolation", kind: '"worktree"', optional: true, default: "pi-subagents worktree policy" },
       { name: "thread", kind: "string", optional: true, default: "fresh session per call" },
       { name: "toolset", kind: "string", optional: true, default: "configured host/agent toolset hint" },
       { name: "excludeTools", kind: "string[]", optional: true, default: "none" },
       { name: "agentType", kind: "string", optional: true, default: "general-purpose" },
-      { name: "timeoutMs", kind: "number | null", optional: true, default: "300000 (5min); null disables" },
+      { name: "timeoutMs", kind: "number | null", optional: true, default: "1800000 (30min); null disables" },
       { name: "retries", kind: "number", optional: true, default: "run retry count" },
     ],
     constraints: [
@@ -64,11 +72,15 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "resume replays only the longest unchanged prefix; the first miss and every later call execute live",
       "replayed calls do not consume the real-dispatch maxAgents or token/phase budgets",
       "spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict",
-      "tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch",
+      "strength is this package's own vocabulary, not an agentTiers key; a word outside low/medium/high is rejected before dispatch",
+      "a strengths table alone binds a strength to an agent tier; an unmapped strength dispatches with no tier and takes the agent's own default",
+      "a call that names no strength also dispatches with no tier; there is no default strength, so an unlabelled call never outranks the agent type's own tier",
+      "an unconfigured host uses a shipped default table: each strength on the catalogue tier of the same name, where the host defines one",
       "resolveAgentTier in pi-subagents owns model, thinking, clamping, availability, and the resolution snapshot",
-      "there is no per-call model or thinking: a tier is the only model policy a workflow can express",
+      "there is no per-call model, thinking, or tier: a strength is the only model policy a workflow can express",
       "same-thread calls must be sequential and preserve a stable workflow thread name",
       "threads cannot be combined with worktree isolation",
+      "an option name outside this list is rejected before dispatch, not ignored; tier, model, and thinking name their replacement",
     ],
   },
   {
@@ -136,6 +148,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "reviewers", kind: "number", optional: true, default: "2" },
       { name: "threshold", kind: "number", optional: true, default: "0.5" },
       { name: "lens", kind: "string | string[]", optional: true, default: "none" },
+      { name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"low"' },
     ],
     constraints: ["threshold comparison is inclusive; real is false when no reviewer succeeds"],
   },
@@ -146,6 +159,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     options: [
       { name: "judges", kind: "number", optional: true, default: "3" },
       { name: "rubric", kind: "string", optional: true, default: "overall quality and correctness" },
+      { name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"low"' },
     ],
     constraints: ["highest mean score wins with stable input index as the tie-break; empty input returns undefined"],
   },
@@ -164,8 +178,8 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "completenessCheck",
     classification: "runtime-global",
-    signature: "completenessCheck(taskArgs, results) => Promise<{ complete, missing? } | null>",
-    options: [],
+    signature: "completenessCheck(taskArgs, results, options?) => Promise<{ complete, missing? } | null>",
+    options: [{ name: "strength", kind: '"low" | "medium" | "high"', optional: true, default: '"medium"' }],
     constraints: ["only the first 4,000 characters of serialized result evidence are sent to the critic"],
   },
   {
@@ -199,6 +213,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     constraints: [
       "consumes one agent slot and no tokens",
       "journaled answers replay only within an unchanged resume prefix",
+      "an option name outside this list is rejected rather than ignored, since a dropped headless silently auto-approves",
     ],
   },
   { name: "log", classification: "runtime-global", signature: "log(message) => void", options: [], constraints: [] },
@@ -269,9 +284,15 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "concurrency",
     classification: "workflow-tool-input",
-    signature: "concurrency?: number",
+    signature: "concurrency?: number = the host's pi-subagents maxConcurrent",
     options: [],
-    constraints: ["runtime clamps to 1..16"],
+    constraints: [
+      "runtime clamps to 1..64",
+      "read live from the peer at each start and resume, and also the ceiling: a request above the pool is clamped to it, and the run log records the clamp",
+      "16 is only the fallback for a peer that publishes no pool size",
+      "pi-subagents maxConcurrent stays the authoritative throttle; one setting governs the whole fleet",
+      "that pool is typically small (4 slots by default), so a wide fan-out runs in waves rather than all at once",
+    ],
   },
   {
     name: "agentRetries",
@@ -283,9 +304,13 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "agentTimeoutMs",
     classification: "workflow-tool-input",
-    signature: "agentTimeoutMs?: number = 300000",
+    signature: "agentTimeoutMs?: number = 1800000",
     options: [],
-    constraints: ["null disables the hard timeout; default 300000ms (5min)"],
+    constraints: [
+      "null disables the hard timeout; default 1800000ms (30min)",
+      "it bounds a hang only; an agent's real budget is the host's turn, tool and token ceiling",
+      "the clock restarts when the host reports the agent left its queue, so waiting for a slot is not charged as work",
+    ],
   },
   {
     name: "tokenBudget",

package/src/engine.ts

@@ -61,6 +61,7 @@ import {
   type WorkflowRunResult,
   type WorkflowRuntimeEvent,
 } from "./runtime.js";
+import type { WorkflowStrengthTable } from "./strengths.js";
 
 export const MAX_ATTEMPTS_PER_NODE = 3;
 
@@ -88,8 +89,19 @@ export interface ScriptStartOptions {
   concurrency?: number;
   agentRetries?: number;
   tokenBudget?: number | null;
-  /** True for a script this package ships; see WorkflowRunOptions.shippedScript. */
-  shippedScript?: boolean;
+  /**
+   * The user's strength → Agent tier table; see WorkflowRunOptions.strengths.
+   *
+   * Deliberately absent from `frozenOptions`. The frozen set is the run's
+   * inputs — budget, scale, toolset — which a resume must not silently
+   * renegotiate. Routing is not an input: a resume already re-reads the host's
+   * tier catalogue, and a table frozen against a catalogue that has since moved
+   * would be the one thing in the run still pointing at the old world.
+   *
+   * Being unfrozen makes supplying it every resume's job, including the resumes
+   * the engine starts itself — see {@link WorkflowEngine.strengths}.
+   */
+  strengths?: WorkflowStrengthTable;
   agentTimeoutMs?: number | null;
   toolset?: string;
   excludeTools?: string[];
@@ -105,13 +117,8 @@ export interface ScriptStartOptions {
       timeoutMs?: number;
     },
   ) => Promise<unknown>;
-  /**
-   * Resolve a nested `workflow(name)` reference. The result reports whether the
-   * script it returned ships with this package, because that decides how the
-   * child frame treats a tier name the host does not define — see
-   * `WorkflowRunOptions.shippedScript`.
-   */
-  loadSavedWorkflow?: (name: string) => { script: string; shippedScript?: boolean } | undefined;
+  /** Resolve a nested `workflow(name)` reference to the script it names. */
+  loadSavedWorkflow?: (name: string) => string | undefined;
   mainModel?: string;
 }
 
@@ -129,12 +136,32 @@ interface AgentLifecycleWaiter {
   generation: number;
   onUsage?: (usage: AgentUsage) => void;
   onHistory?: (history: unknown[]) => void;
+  /** Told once when the host reports this agent left the queue and started. */
+  onRunning?: () => void;
+  startedNotified: boolean;
   executionGeneration: number;
   resolve: (response: ManagedSpawnResponse) => void;
   reject: (error: unknown) => void;
   settled: boolean;
 }
 
+/**
+ * Tell a waiter once that its agent started.
+ *
+ * Once, because the wall clock is restarted from this point: a repeated report
+ * — a duplicate event, or a reply that raced its own lifecycle event — would
+ * keep pushing the deadline out and quietly turn the timeout off.
+ */
+function notifyAgentRunning(waiter: AgentLifecycleWaiter): void {
+  if (waiter.startedNotified || waiter.settled) return;
+  waiter.startedNotified = true;
+  try {
+    waiter.onRunning?.();
+  } catch {
+    /* the clock is best effort; never fail a live agent over it */
+  }
+}
+
 interface AgentTerminalDelivery {
   response: ManagedSpawnResponse;
   usage?: AgentUsage;
@@ -151,14 +178,7 @@ export interface ScriptRunState {
   /** Frozen run parameters — resume reuses the original values, ignoring new budget/toolset overrides. */
   frozenOptions: Pick<
     ScriptStartOptions,
-    | "tokenBudget"
-    | "maxAgents"
-    | "concurrency"
-    | "agentRetries"
-    | "agentTimeoutMs"
-    | "toolset"
-    | "shippedScript"
-    | "excludeTools"
+    "tokenBudget" | "maxAgents" | "concurrency" | "agentRetries" | "agentTimeoutMs" | "toolset" | "excludeTools"
   >;
   /** Abort controller for this run's script execution. */
   controller: AbortController;
@@ -289,6 +309,18 @@ export class WorkflowEngine {
   onRunSettled: (() => void) | undefined;
   /** Optional in-process observer for phase/task/quality runtime events. */
   onRuntimeEvent: ((runId: string, event: WorkflowRuntimeEvent) => void) | undefined;
+  /**
+   * The user's current strength → Agent tier table, read fresh per execution.
+   *
+   * A callback rather than a value because the table is deliberately unfrozen:
+   * "read fresh at each start and resume" has to hold for the resumes the
+   * engine starts on its own — `control("resume")` and the provider-limit
+   * retry — which have no caller to pass options for them. Without it those
+   * resume with no table at all, and since a call's identity keys on the tier
+   * it requested, every already-finished call would miss its journal entry and
+   * re-run untabled: the exact re-spend this table exists to prevent.
+   */
+  strengths: (() => WorkflowStrengthTable | undefined) | undefined;
   private readonly waiters = new Map<
     string,
     Set<{ resolve: (run: ScriptRun) => void; reject: (e: unknown) => void; settled: boolean; cleanup: () => void }>
@@ -420,6 +452,10 @@ export class WorkflowEngine {
     if (updateCallTierIdentity(state, callNodeId, data.tier)) {
       this.persistCallTierIdentity(state, callNodeId);
     }
+    // A start is the moment the host admitted this agent from its queue. It is
+    // the only signal that separates waiting for a slot from doing the work, so
+    // the call's wall clock is restarted here rather than at dispatch.
+    if (eventName === "subagents:started" && waiterMatches && waiter) notifyAgentRunning(waiter);
     // Created/started lifecycle facts carry managed identity before the RPC
     // reply is necessarily available. They are observation-only here; terminal
     // ownership is handled below once a completion/failure fact arrives.
@@ -628,7 +664,6 @@ export class WorkflowEngine {
     const runId = randomUUID();
     const scriptHash = hashScript(script);
     const toolset = options.toolset;
-    const shippedScript = options.shippedScript === true ? true : undefined;
     const durableArgs = cloneWorkflowArgs(options.args);
     const runtimeArgs = cloneWorkflowArgs(durableArgs);
     const journalArgs = cloneWorkflowArgs(durableArgs);
@@ -657,7 +692,6 @@ export class WorkflowEngine {
       meta,
       ...(durableArgs === undefined ? {} : { args: durableArgs }),
       frozenArgsPresent,
-      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
       ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
       ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
@@ -686,7 +720,6 @@ export class WorkflowEngine {
       meta,
       ...(journalArgs === undefined ? {} : { args: journalArgs }),
       frozenArgsPresent,
-      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
       ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
       ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
@@ -705,7 +738,6 @@ export class WorkflowEngine {
         ...(frozenAgentRetries !== undefined ? { agentRetries: frozenAgentRetries } : {}),
         ...(frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: frozenAgentTimeoutMs } : {}),
         ...(options.toolset ? { toolset: options.toolset } : {}),
-        ...(shippedScript === undefined ? {} : { shippedScript }),
         ...(options.excludeTools ? { excludeTools: [...options.excludeTools] } : {}),
       },
       controller: new AbortController(),
@@ -802,11 +834,15 @@ export class WorkflowEngine {
     this.setWorkflowStatus(run, "running");
     state.controller = new AbortController();
     // Freeze semantics: original run parameters and args win over new options.
-    // Only signal/confirm/background/loadSavedWorkflow/mainModel are per-resume context;
-    // input/budget/scale/toolset are frozen from the original start.
+    // Only signal/confirm/background/loadSavedWorkflow/mainModel/strengths are
+    // per-resume context; input/budget/scale/toolset are frozen from the
+    // original start.
     const frozen = state.frozenOptions;
     const resumeOptions: ScriptStartOptions = {
       ...options,
+      // `??`, not an overwrite: a caller that passed a table meant it, and only
+      // a caller that passed none is asking the engine to read the current one.
+      strengths: options.strengths ?? this.strengths?.(),
       args: resumeArgs,
       tokenBudget: frozen.tokenBudget,
       maxAgents: frozen.maxAgents,
@@ -814,7 +850,6 @@ export class WorkflowEngine {
       agentRetries: frozen.agentRetries,
       agentTimeoutMs: frozen.agentTimeoutMs,
       toolset: frozen.toolset,
-      shippedScript: frozen.shippedScript,
       excludeTools: frozen.excludeTools ? [...frozen.excludeTools] : undefined,
     };
     state.bufferedTerminals.clear();
@@ -999,6 +1034,10 @@ export class WorkflowEngine {
           : {
               routingPolicy: protocol.routingPolicy,
               routingPolicyFingerprint: protocol.routingPolicyFingerprint,
+              // Read live at each start and resume, never frozen onto the run:
+              // the pool is a host setting the user can change between them, and
+              // a run that outlived a narrowing would dispatch into a queue.
+              ...(protocol.maxConcurrent === undefined ? {} : { hostMaxConcurrent: protocol.maxConcurrent }),
             }),
         concurrency: options.concurrency,
         agentRetries: options.agentRetries,
@@ -1010,7 +1049,7 @@ export class WorkflowEngine {
         executionNonce: `${generation}-${randomUUID()}`,
         resumeJournal,
         toolset: options.toolset,
-        shippedScript: options.shippedScript,
+        strengths: options.strengths,
         excludeTools: options.excludeTools,
         confirm: options.confirm,
         loadSavedWorkflow: options.loadSavedWorkflow,
@@ -1276,11 +1315,17 @@ export class WorkflowEngine {
         executionGeneration,
         onUsage: runOptions.onUsage,
         onHistory: runOptions.onHistory,
+        onRunning: runOptions.onRunning,
+        startedNotified: false,
         settled: false,
         resolve,
         reject,
       };
       state.agentWaiters.set(pendingId, waiter);
+      // A spawn that was admitted straight away is already running, and its
+      // `subagents:started` event fired before this waiter existed. Only a
+      // reply that says "queued" still has a start to wait for.
+      if (typeof response !== "string" && response.state !== "queued") notifyAgentRunning(waiter);
       externalSignal.addEventListener("abort", waitAbort, { once: true });
       if (externalSignal.aborted) {
         waitAbort();
@@ -1750,7 +1795,6 @@ export class WorkflowEngine {
           ...(run.frozenAgentRetries !== undefined ? { agentRetries: run.frozenAgentRetries } : {}),
           ...(run.frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: run.frozenAgentTimeoutMs } : {}),
           ...(run.toolset ? { toolset: run.toolset } : {}),
-          ...(run.shippedScript === undefined ? {} : { shippedScript: run.shippedScript }),
           ...(run.frozenExcludeTools ? { excludeTools: [...run.frozenExcludeTools] } : {}),
         },
         controller: new AbortController(),