@signalridge/pi-workflows 1.3.2 → 1.5.0

package/src/builtins.ts

@@ -55,7 +55,7 @@ const plan = await agent(
   'You are planning web research for this question:\\n' + question +
   '\\n\\nProduce ' + angles + ' diverse, specific search queries that together cover the question from different angles. ' +
   'Use your web search tools when helpful to refine them.',
-  { label: 'plan queries', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
+  { label: 'plan queries', tier: 'medium', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
 )
 const planned = plan && Array.isArray(plan.queries) ? plan.queries.filter((q) => typeof q === 'string' && q.trim().length > 0) : []
 const queries = (planned.length > 0 ? planned : [question]).slice(0, angles)
@@ -67,7 +67,7 @@ const gathered = await parallel(queries.map((q, i) => () =>
     '\\n\\nSteps: (1) run a web search for the query; (2) fetch the most relevant result URLs; ' +
     '(3) extract concrete, verifiable factual claims, each tagged with the exact source URL it came from. ' +
     'Do NOT invent sources or claims — report only what the fetched pages actually say.',
-    { label: 'research ' + (i + 1), schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
+    { label: 'research ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
   )
 ))
 const allSources = gathered.filter(Boolean).flatMap((g) => (g && g.sources) || [])
@@ -77,7 +77,7 @@ const verdict = await agent(
   'Cross-check these research sources. Group claims that assert the same fact across different source URLs. ' +
   'Keep a claim only if it is supported by at least ' + minSupport + ' distinct source URLs OR by one clearly authoritative source. ' +
   'Discard claims found in a single weak source or that conflict with others.\\n\\nSOURCES JSON:\\n' + JSON.stringify(allSources),
-  { label: 'cross-check', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
+  { label: 'cross-check', tier: 'medium', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
 )
 
 phase('Report')
@@ -85,7 +85,7 @@ const report = await agent(
   'Write a concise, well-structured research report that answers the question using ONLY the supported claims below. ' +
   'Cite source URLs inline next to each claim. If the evidence is thin, say so explicitly.\\n\\n' +
   'QUESTION: ' + question + '\\n\\nSUPPORTED CLAIMS JSON:\\n' + JSON.stringify((verdict && verdict.supported) || []),
-  { label: 'write report' }
+  { label: 'write report', tier: 'medium' }
 )
 
 return { question, queries, supported: (verdict && verdict.supported) || [], report }`;
@@ -107,7 +107,7 @@ const threshold = (args && args.threshold) || 0.5
 phase('Investigate')
 const investigation = await agent(
   'Investigate the following and list concrete, individually-checkable findings:\\n' + task,
-  { label: 'investigate', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
+  { label: 'investigate', tier: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
 )
 const findings = (investigation && Array.isArray(investigation.findings) ? investigation.findings : [])
 
@@ -118,7 +118,7 @@ const judged = await parallel(findings.map((f, i) => () =>
       'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
       'Default to real=false when uncertain. Investigate with the available tools if needed.\\n\\n' +
       'TASK: ' + task + '\\nFINDING: ' + f,
-      { label: 'refute ' + (i + 1) + '.' + (r + 1), schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
+      { label: 'refute ' + (i + 1) + '.' + (r + 1), tier: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
     )
   )).then((votes) => {
     const valid = votes.filter(Boolean)
@@ -134,7 +134,7 @@ const report = await agent(
   'Synthesize the surviving findings into a concise review. For each finding, note the skeptic agreement ' +
   '(realVotes/totalVotes). Do not include findings that failed the refutation pass.\\n\\n' +
   'TASK: ' + task + '\\n\\nSURVIVING FINDINGS JSON:\\n' + JSON.stringify(survivors),
-  { label: 'consensus report' }
+  { label: 'consensus report', tier: 'medium' }
 )
 
 return { findings, judged: judged.filter(Boolean), survivors, report }`;
@@ -154,13 +154,13 @@ const diffSource = (args && args.diffSource) || 'provided diff'
 
 phase('Scan')
 const finders = await parallel([
-  () => agent('You are a correctness reviewer. Find bugs, race conditions, error-handling gaps, and edge-case failures in this diff.\\n\\n' + diff, { label: 'correctness', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a reuse reviewer. Find duplicated logic, reinvented wheels, and missed opportunities to reuse existing code or libraries.\\n\\n' + diff, { label: 'reuse', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a simplification reviewer. Find over-engineering, unnecessary complexity, and simpler alternatives.\\n\\n' + diff, { label: 'simplification', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are an efficiency reviewer. Find performance problems, avoidable allocations, and scaling risks.\\n\\n' + diff, { label: 'efficiency', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are an architecture reviewer. Assess the change at the right altitude: design fit, layering, boundaries, and future maintenance.\\n\\n' + diff, { label: 'altitude', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a security reviewer. Find trust-boundary, injection, secret-leak, permission, and unsafe-input risks in this diff.\\n\\n' + diff, { label: 'security', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
-  () => agent('You are a testability reviewer. Find missing regression tests, observability gaps, and rollout/recovery risks in this diff.\\n\\n' + diff, { label: 'testability', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a correctness reviewer. Find bugs, race conditions, error-handling gaps, and edge-case failures in this diff.\\n\\n' + diff, { label: 'correctness', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a reuse reviewer. Find duplicated logic, reinvented wheels, and missed opportunities to reuse existing code or libraries.\\n\\n' + diff, { label: 'reuse', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a simplification reviewer. Find over-engineering, unnecessary complexity, and simpler alternatives.\\n\\n' + diff, { label: 'simplification', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are an efficiency reviewer. Find performance problems, avoidable allocations, and scaling risks.\\n\\n' + diff, { label: 'efficiency', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are an architecture reviewer. Assess the change at the right altitude: design fit, layering, boundaries, and future maintenance.\\n\\n' + diff, { label: 'altitude', tier: 'medium', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a security reviewer. Find trust-boundary, injection, secret-leak, permission, and unsafe-input risks in this diff.\\n\\n' + diff, { label: 'security', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
+  () => agent('You are a testability reviewer. Find missing regression tests, observability gaps, and rollout/recovery risks in this diff.\\n\\n' + diff, { label: 'testability', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }),
 ])
 const candidates = finders.filter(Boolean).flatMap((f) => (f && f.findings) || [])
 
@@ -168,7 +168,7 @@ phase('Verify')
 const verified = await parallel(candidates.map((finding, i) => () =>
   agent('You are a skeptical verifier. For this candidate finding, check whether it is a REAL issue in the diff. ' +
     'Default to real=false when uncertain.\\n\\nCANDIDATE: ' + finding + '\\n\\nDIFF:\\n' + diff,
-    { label: 'verify ' + (i + 1), schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } })
+    { label: 'verify ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } })
 ))
 
 phase('Report')
@@ -179,7 +179,7 @@ const report = await agent(
   'Write a ranked code review report for this diff (' + diffSource + '). ' +
   'Include only verified findings, ordered by severity, each with a concrete location and fix suggestion.\\n\\n' +
   'VERIFIED FINDINGS JSON:\\n' + JSON.stringify(ranked),
-  { label: 'final report' }
+  { label: 'final report', tier: 'medium' }
 )
 
 return { candidates, ranked, report }`;
@@ -199,13 +199,13 @@ const perspectives = (args && Array.isArray(args.perspectives) && args.perspecti
 phase('Perspectives')
 const views = await parallel(perspectives.map((p, i) => () =>
   agent('Evaluate this topic from the perspective of: ' + p + '. Be concrete and specific; note risks, trade-offs, and what matters most from this angle.\\n\\nTOPIC: ' + topic,
-    { label: 'perspective ' + (i + 1), schema: { type: 'object', properties: { angle: { type: 'string' }, points: { type: 'array', items: { type: 'string' } }, risks: { type: 'array', items: { type: 'string' } } }, required: ['angle', 'points', 'risks'] } })
+    { label: 'perspective ' + (i + 1), tier: 'low', schema: { type: 'object', properties: { angle: { type: 'string' }, points: { type: 'array', items: { type: 'string' } }, risks: { type: 'array', items: { type: 'string' } } }, required: ['angle', 'points', 'risks'] } })
 ))
 
 phase('Synthesis')
 const synthesis = await agent(
   'Synthesize these perspectives into a balanced assessment. Identify where perspectives agree, where they conflict, and give a bottom-line recommendation with the key trade-offs.\\n\\nTOPIC: ' + topic + '\\n\\nPERSPECTIVES JSON:\\n' + JSON.stringify(views.filter(Boolean)),
-  { label: 'synthesis' }
+  { label: 'synthesis', tier: 'medium' }
 )
 
 return { views: views.filter(Boolean), synthesis }`;
@@ -229,21 +229,21 @@ const map = await agent(
   'Explore the codebase at ' + root + ' and produce a structural map: top-level modules, entry points, ' +
   'data flow, and where complexity concentrates. Use the available file tools.\\n' +
   (focus ? 'Focus/checks requested: ' + focus + '\\n' : ''),
-  { label: 'map', schema: { type: 'object', properties: { modules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, purpose: { type: 'string' }, risk: { type: 'string' } }, required: ['name', 'purpose'] } }, entryPoints: { type: 'array', items: { type: 'string' } }, complexityHotspots: { type: 'array', items: { type: 'string' } } }, required: ['modules'] } }
+  { label: 'map', tier: 'medium', schema: { type: 'object', properties: { modules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, purpose: { type: 'string' }, risk: { type: 'string' } }, required: ['name', 'purpose'] } }, entryPoints: { type: 'array', items: { type: 'string' } }, complexityHotspots: { type: 'array', items: { type: 'string' } } }, required: ['modules'] } }
 )
 
 phase('Audit')
 const audits = await parallel([
-  () => agent('Audit this codebase for correctness risks: error handling, boundary conditions, concurrency, security. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'correctness', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
-  () => agent('Audit this codebase for maintainability: coupling, duplication, naming, test coverage, documentation. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'maintainability', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
-  () => agent('Audit this codebase for operational health: dependencies, build, deployment, observability, secrets handling. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'operations', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for correctness risks: error handling, boundary conditions, concurrency, security. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'correctness', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for maintainability: coupling, duplication, naming, test coverage, documentation. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'maintainability', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
+  () => agent('Audit this codebase for operational health: dependencies, build, deployment, observability, secrets handling. Use file tools.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map), { label: 'operations', tier: 'low', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } }, severity: { type: 'string' } }, required: ['findings'] } }),
 ])
 
 phase('Report')
 const report = await agent(
   'Write a codebase health audit report: overall health score, ranked findings across dimensions with concrete locations, ' +
   'and a prioritized remediation roadmap.\\n\\nSTRUCTURE:\\n' + JSON.stringify(map) + '\\n\\nAUDITS JSON:\\n' + JSON.stringify(audits.filter(Boolean)),
-  { label: 'audit report' }
+  { label: 'audit report', tier: 'medium' }
 )
 
 return { map, audits: audits.filter(Boolean), report }`;

package/src/capabilities.ts

@@ -29,7 +29,7 @@ export interface CapabilityEntry {
 }
 
 /** The contract format version. Bump on any breaking surface change. */
-export const WORKFLOW_CAPABILITY_CONTRACT_VERSION = "1.0.0";
+export const WORKFLOW_CAPABILITY_CONTRACT_VERSION = "2.0.0";
 
 /**
  * The runtime globals a script can rely on. `options` documents each helper's
@@ -44,8 +44,12 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "label", kind: "string", optional: true, default: "derived from phase and call count" },
       { name: "phase", kind: "string", optional: true, default: "current phase" },
       { name: "schema", kind: "plain JSON Schema", optional: true, default: "none" },
-      { name: "model", kind: "string", optional: true, default: "pi-subagents model resolver" },
-      { name: "tier", kind: "small|medium|large", optional: true, default: "pi-subagents workflow tier" },
+      {
+        name: "tier",
+        kind: "agent tier key",
+        optional: true,
+        default: "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" },
@@ -58,8 +62,11 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "recoverable failures return null after retries; nonrecoverable failures throw",
       "schema noncompliance after bounded repair attempts is nonrecoverable",
       "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",
-      "explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed",
+      "tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch",
+      "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",
       "same-thread calls must be sequential and preserve a stable workflow thread name",
       "threads cannot be combined with worktree isolation",
     ],
@@ -72,8 +79,9 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     constraints: [
       "requires functions rather than promises",
       "result order matches input order",
-      "recoverable thunk failures become null; nonrecoverable failures throw",
+      "recoverable thunk failures become null; nonrecoverable failures throw after the batch barrier settles",
       "a breached agent cap cancels only its own batch",
+      "accepts at most 4096 thunks per call",
     ],
   },
   {
@@ -85,6 +93,28 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "items run concurrently while stages per item run sequentially",
       "each stage receives previousValue, originalItem, and zero-based index",
       "a null stage result is passed to the next stage",
+      "accepts at most 4096 items per call and awaits the whole batch before surfacing fatal errors",
+    ],
+  },
+  {
+    name: "orchestrate",
+    classification: "runtime-global",
+    signature: "orchestrate(tasks, options?) => Promise<{ results, tasks }>",
+    options: [
+      {
+        name: "onError",
+        kind: '"skip-dependents"|"continue"|"fail-fast"',
+        optional: true,
+        default: '"skip-dependents"',
+      },
+    ],
+    constraints: [
+      "task ids and dependencies are validated before any callback runs",
+      "ready tasks run in declaration-order layers with a barrier between layers",
+      "task context carries detached named results and statuses",
+      "ordinary task failures can retry up to three times; fatal workflow errors propagate",
+      "failed or skipped dependencies skip descendants by default; continue runs them with null values",
+      "the graph accepts at most 128 tasks and emits task start/retry/end/skip runtime events",
     ],
   },
   {
@@ -93,9 +123,9 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     signature: "workflow(savedName, childArgs?) => Promise<unknown>",
     options: [],
     constraints: [
-      "one nested level",
+      "one nested level; concurrent sibling nested calls are allowed",
       "shares limiter, counters, token accounting, and store",
-      "nested runs get unique runIds via nestedCallSeq",
+      "nested calls use call-index/generation namespaces and replay as one parent result",
     ],
   },
   {
@@ -271,6 +301,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     options: [],
     constraints: [
       "resumes a prior incomplete run with an edited script",
+      "original args and execution limits are reused on resume",
       "unchanged positional calls replay from cache until the first changed call",
       "always runs in the background",
     ],
@@ -283,6 +314,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     constraints: [
       "must be the first statement",
       "name and description must be nonblank literals",
+      "workflow meta and phase metadata cannot contain model or thinking fields",
       "spread, computed keys, methods, template interpolation, and __proto__/constructor/prototype are rejected",
     ],
   },