pi-workflow-engine 1.3.0 → 1.4.0

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -616,7 +616,7 @@ function registerWorkflowTool(
       parallelSubmissionLimit: Type.Optional(Type.Number({ description: "Optional limit for eagerly submitted parallel thunks" })),
       maxAgents: Type.Optional(
         Type.Integer({
-          description: `Maximum live model calls started across this run; replay hits are excluded; clamped to ${WORKFLOW_MAX_AGENTS_MIN}-${WORKFLOW_MAX_AGENTS_MAX}`,
+          description: `Maximum live model calls started across this run; replay hits are excluded; clamped to ${WORKFLOW_MAX_AGENTS_MIN}-${WORKFLOW_MAX_AGENTS_MAX}. Leave unset for a registered workflow unless the user asks for a cap: it sizes its own stages`,
         }),
       ),
       agentTimeoutMs: Type.Optional(

package/.pi/extensions/pi-workflow-engine/src/background-workflows.ts

@@ -1,8 +1,6 @@
-import { join } from "node:path";
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
 import { isRecord } from "./guards.ts";
-import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
   stopWorkflowRunRecord,
@@ -11,7 +9,7 @@ import {
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
 import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
-import { ProjectWorkflowRunStore, WORKFLOW_RUN_RECORD_SUFFIX, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { truncateText } from "./text.ts";
 import { formatWorkflowUsageLine } from "./usage.ts";
 import { workflowResultSummary } from "./workflow-execution.ts";
@@ -375,10 +373,7 @@ function wokenDeliveryBody(record: WorkflowRunRecord, summary: string): string {
 
 /** The retained record, script and journal, relative to the workflow cwd like the synchronous result's lines. */
 function backgroundRunFileLines(record: WorkflowRunRecord): string[] {
-  return [
-    `Record: ${join(WORKFLOW_RUNS_DIR, `${record.runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
-    ...formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined),
-  ];
+  return formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined);
 }
 
 function sessionHasBackgroundDelivery(ctx: ExtensionContext, runId: string): boolean {

package/.pi/extensions/pi-workflow-engine/src/workflow-result-context.ts

@@ -1,8 +1,17 @@
 import { join } from "node:path";
-import { formatAdvisoryLocation, isAdvisoryReport, type AdvisoryFinding, type AdvisoryReport } from "./advisory-schema.ts";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import {
+  AdvisoryVerifierVerdictSchema,
+  formatAdvisoryLocation,
+  isAdvisoryReport,
+  type AdvisoryFinding,
+  type AdvisoryReport,
+} from "./advisory-schema.ts";
 import { isRecord } from "./guards.ts";
 import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import { workflowRunScriptFile } from "./workflow-run-record.ts";
+import { WORKFLOW_RUN_RECORD_SUFFIX } from "./workflow-run-store.ts";
 import { toReviewIssues } from "./review/review-issues.ts";
 import { formatPerfSummary } from "./perf.ts";
 import { prettyJson } from "./text.ts";
@@ -35,21 +44,31 @@ export function formatWorkflowRunLine(run: { readonly runId: string; readonly re
 }
 
 /**
- * Where the host model can read what the run did, relative to the workflow cwd: the persisted script it
- * can edit and rerun with `scriptPath`, and the replay journal of completed agent results.
+ * Where the host model can read what the run did, relative to the workflow cwd: the record holding the full
+ * result, the persisted script it can edit and rerun with `scriptPath`, and the replay journal of completed
+ * agent results.
  */
 export function formatWorkflowRunFileLines(runId: string, scriptPersisted: boolean): string[] {
   return [
+    `Record: ${join(WORKFLOW_RUNS_DIR, `${runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
     ...(scriptPersisted ? [`Script: ${join(WORKFLOW_RUNS_DIR, workflowRunScriptFile(runId))}`] : []),
     `Journal: ${join(WORKFLOW_RUNS_DIR, `${runId}.jsonl`)}`,
     "If the result is empty or unexpected, read the journal before diagnosing.",
   ];
 }
 
+/** A verified candidate as lens reviews retain it beside their report, reduced to the fields the host listing reads. */
+const VerifiedCandidateSchema = Type.Object({
+  sourceCandidateIds: Type.Array(Type.String()),
+  summary: Type.String(),
+  verdict: AdvisoryVerifierVerdictSchema,
+});
+type VerifiedCandidate = Static<typeof VerifiedCandidateSchema>;
+
 /** A workflow result as the host model reads it: advisory reports as findings, other values as bounded JSON. */
 export function formatResultForContext(result: unknown): string {
   if (typeof result === "string") return result;
-  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result);
+  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result, unreportedCandidates(result));
   const summary = workflowResultSummary(result);
   if (summary !== undefined && isRecord(result) && Object.keys(result).length === 1) return summary;
   const json = formatResultJson(result);
@@ -57,7 +76,20 @@ export function formatResultForContext(result: unknown): string {
   return summary === undefined ? json : `${summary}\n\n${json}`;
 }
 
-function formatAdvisoryReportForContext(report: AdvisoryReport): string {
+/**
+ * Verified candidates that no finding draws on: ones synthesis left out under the reporting bar, and refuted
+ * ones. Listing them lets the host resolve the candidate IDs a synthesis summary cites when it explains an
+ * exclusion, without reading the run record.
+ */
+function unreportedCandidates(report: AdvisoryReport & { readonly verification?: unknown }): VerifiedCandidate[] {
+  const { verification } = report;
+  if (!Array.isArray(verification)) return [];
+  const reported = new Set(report.findings.flatMap((finding) => finding.sourceCandidateIds ?? []));
+  return verification.filter((entry): entry is VerifiedCandidate =>
+    Value.Check(VerifiedCandidateSchema, entry) && !entry.sourceCandidateIds.some((id) => reported.has(id)));
+}
+
+function formatAdvisoryReportForContext(report: AdvisoryReport, unreported: readonly VerifiedCandidate[]): string {
   const lines = [report.summary];
   const issues = toReviewIssues(report);
   if (issues.length > 0) {
@@ -75,6 +107,10 @@ function formatAdvisoryReportForContext(report: AdvisoryReport): string {
       );
     }
   }
+  if (unreported.length > 0) {
+    lines.push("", "Verified but not reported (verdict, candidate IDs):",
+      ...unreported.map((candidate) => `- ${candidate.verdict} ${candidate.sourceCandidateIds.join(", ")}: ${candidate.summary}`));
+  }
   if (report.gaps && report.gaps.length > 0) {
     lines.push("", "Coverage gaps:", ...report.gaps.map((gap) => `- ${gap}`));
   }

package/.pi/extensions/pi-workflow-engine/src/workflow-settings.ts

@@ -65,7 +65,7 @@ export function setWorkflowSize(configPath: string, size: WorkflowSizeGuideline)
 /** The catalog line for a size, or undefined when the guideline is off. */
 export function workflowSizeGuidelineLine(size: WorkflowSizeGuideline): string | undefined {
   if (size === "off") return undefined;
-  return `Workflow size guideline: ${size} — keep each workflow under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; the user changes this with /workflow:size.`;
+  return `Workflow size guideline: ${size} — keep each workflow script you author under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; registered workflows size their own stages, so run them without maxAgents unless the user sets a cap. The user changes this with /workflow:size.`;
 }
 
 type WorkflowSizeCommand =
@@ -76,7 +76,7 @@ type WorkflowSizeCommand =
 const USAGE = "Usage: /workflow:size [small|medium|large|off] [--user|--project]";
 const SIZE_COMPLETIONS = WORKFLOW_SIZE_GUIDELINES.map((value) => ({
   value,
-  description: value === "off" ? "No size guideline in the prompt" : `Keep each workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
+  description: value === "off" ? "No size guideline in the prompt" : `Keep each authored workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
 }));
 const SCOPE_COMPLETIONS = [
   { value: "--user", description: "Write the user-level workflow settings" },
@@ -110,7 +110,7 @@ export function formatWorkflowSize(resolved: ResolvedWorkflowSize): string {
   const source = resolved.source === "default" ? "default" : `${resolved.source} config ${resolved.configPath}`;
   const rule = resolved.size === "off"
     ? "no size guideline is added to the prompt"
-    : `keep each workflow under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more`;
+    : `keep each authored workflow script under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more; registered workflows are not capped by it`;
   return [
     `Workflow size guideline: ${resolved.size} (${source}) — ${rule}.`,
     `The maxAgents run limit (default ${DEFAULT_WORKFLOW_MAX_AGENTS}) stays the hard cap on live agents per run.`,

package/USAGE.md

@@ -207,13 +207,13 @@ The catalog ends with one line telling the host agent how large to make each wor
 
 ```text
 /workflow:size                    # show the current guideline and where it comes from
-/workflow:size small              # keep each workflow under 5 agents
+/workflow:size small              # keep each authored workflow under 5 agents
 /workflow:size medium             # under 10 agents (the default)
 /workflow:size large --project    # under 25 agents, for this project only
 /workflow:size off                # leave the line out
 ```
 
-The line reads, for example, `Workflow size guideline: medium — keep each workflow under 10 agents unless the user asks for more; the user changes this with /workflow:size.` The setting is stored like the model profiles: `~/.pi/agent/workflow-settings.json` for the user, overridden by `<project>/.pi/workflow-settings.json`; setting a size writes the user file unless `--project` is given. A minimal file is `{ "size": "small" }`. Changing it rebuilds the current session's catalog once.
+The line reads, for example, `Workflow size guideline: medium — keep each workflow script you author under 10 agents unless the user asks for more; registered workflows size their own stages, so run them without maxAgents unless the user sets a cap. The user changes this with /workflow:size.` The setting is stored like the model profiles: `~/.pi/agent/workflow-settings.json` for the user, overridden by `<project>/.pi/workflow-settings.json`; setting a size writes the user file unless `--project` is given. A minimal file is `{ "size": "small" }`. Changing it rebuilds the current session's catalog once.
 
 The guideline only shapes what the host agent writes. The `maxAgents` run limit (default `64`, see [Runtime knobs](#runtime-knobs)) stays the separate hard cap: once a run has started that many live agents, further `agent()` calls fail with `WorkflowAgentLimitError`, whatever the guideline says.
 
@@ -287,7 +287,7 @@ Persistence is intentionally bounded and private by default. Raw workflow args,
 
 An inline run (a tool `script` or `scriptPath`) also saves its script to `.pi/.workflow-runs/<run-id>.script.js`, a separate file the record only references, because the record never holds prompts. The script holds nothing new: pi's session transcript already contains it as the tool call's arguments. A pruned record takes its script with it. Whenever the engine creates `.pi/.workflow-runs/`, it adds a `.gitignore` containing `*` so run files stay out of the project's git history; an existing `.gitignore` there is never replaced.
 
-The result handed to the host agent names the run's files after the run ID: `Script:` for an inline run, and `Journal:` with a reminder to read the journal before diagnosing an empty or unexpected result. A failed inline run lists the same lines after its error, a background start names the script too, and a background delivery names the record, script, and journal (see [Background workflows](#background-workflows)). To iterate, edit the script and rerun it with `scriptPath` (see [Author an inline workflow](#author-an-inline-workflow)).
+The result handed to the host agent names the run's files after the run ID: `Record:` (which holds the full result when the text is truncated), `Script:` for an inline run, and `Journal:` with a reminder to read the journal before diagnosing an empty or unexpected result. A failed run lists the same lines after its error, a background start names the script too, and a background delivery names the same files (see [Background workflows](#background-workflows)). A review result also lists the verified candidates that no reported finding draws on, with their verdicts and candidate IDs, so the host can resolve the IDs a synthesis summary cites when it explains what it left out. To iterate, edit the script and rerun it with `scriptPath` (see [Author an inline workflow](#author-an-inline-workflow)).
 
 ### Background workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [