pi-workflow-engine 1.0.0 → 1.2.0

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-widget.ts

@@ -3,7 +3,7 @@ import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/p
 import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
 import { formatCount } from "../text.ts";
 import { compactUsage, dot, fit, GLYPH, joinParts, keyHints, progressBar, spread, type ThemeColor } from "./kit.ts";
-import { countAgents, formatDuration, formatElapsed, type WorkflowStatusCounts } from "./workflow-format.ts";
+import { countAgents, finishedAgents, formatDuration, formatElapsed, type WorkflowStatusCounts } from "./workflow-format.ts";
 
 /** pi caps string widgets at this many rows; the component keeps to the same budget. */
 const MAX_WIDGET_LINES = 10;
@@ -64,7 +64,7 @@ export class WidthAwareWidget implements Component {
 /** `◆ background · code-review 56b57550 · Find 6/10 · 12s`: one line for a run the user sent to the background. */
 export function renderBackgroundWorkflowLine(snapshot: WorkflowProgressSnapshot, width: number, theme: Theme): string[] {
   const counts = countAgents(snapshot.phases);
-  const progress = counts.total > 0 ? `${snapshot.currentPhase} ${counts.done + counts.failed}/${counts.total}` : snapshot.currentPhase;
+  const progress = counts.total > 0 ? `${snapshot.currentPhase} ${finishedAgents(counts)}/${counts.total}` : snapshot.currentPhase;
   const line = joinParts([
     `${theme.fg("accent", GLYPH.workflow)} ${theme.fg("muted", "background")}`,
     `${theme.bold(snapshot.title)} ${theme.fg("dim", snapshot.runId.slice(0, 8))}`,
@@ -92,7 +92,7 @@ function classifyPhases(snapshot: WorkflowProgressSnapshot): ClassifiedPhases {
 
 function headerLine(snapshot: WorkflowProgressSnapshot, counts: WorkflowStatusCounts, width: number, now: number, theme: Theme): string {
   const name = `${theme.fg("accent", GLYPH.workflow)} ${theme.bold(snapshot.title)}`;
-  const finished = counts.done + counts.failed;
+  const finished = finishedAgents(counts);
   const stats = joinParts([
     counts.total > 0 ? theme.fg("text", `${finished}/${counts.total}`) : undefined,
     theme.fg("muted", formatElapsed(now - snapshot.startedAt)),
@@ -156,8 +156,8 @@ function phaseBody(
 
 /**
  * Spread the row budget over active phases by importance — a reserved share for failures so they always
- * show, then running, remaining failures, done, queued — while each phase lists its chosen rows as
- * running, failed, done, queued.
+ * show, then running, remaining failures, skipped, done, queued — while each phase lists its chosen rows
+ * in that same status order.
  */
 function planAgentRows(active: readonly PhaseSnapshot[], budget: number): Map<PhaseSnapshot, AgentRowPlan> {
   const byStatus = (status: AgentRowSnapshot["status"]) =>
@@ -177,10 +177,11 @@ function planAgentRows(active: readonly PhaseSnapshot[], budget: number): Map<Ph
   take(failed, failed.length > 0 ? Math.max(1, Math.floor(budget / 3)) : 0);
   take(byStatus("running"));
   take(failed);
+  take(byStatus("skipped"));
   take(byStatus("done"));
   take(byStatus("queued"));
 
-  const rank = { running: 0, failed: 1, done: 2, queued: 3 } as const;
+  const rank = { running: 0, failed: 1, skipped: 2, done: 3, queued: 4 } as const;
   const plans = new Map<PhaseSnapshot, AgentRowPlan>();
   for (const phase of active) {
     const shown = phase.agents.filter((agent) => chosen.has(agent)).sort((a, b) => rank[a.status] - rank[b.status]);
@@ -196,7 +197,7 @@ function agentLabelWidth(plans: ReadonlyMap<PhaseSnapshot, AgentRowPlan>, width:
 
 function finishedPhaseLine(phase: PhaseSnapshot, titleWidth: number, theme: Theme): string {
   const counts = countAgents([phase]);
-  const glyph = counts.failed === 0
+  const glyph = counts.failed === 0 && counts.skipped === 0
     ? theme.fg("success", GLYPH.done)
     : counts.failed === counts.total ? theme.fg("error", GLYPH.failed) : theme.fg("warning", GLYPH.warning);
   const span = phaseSpan(phase.agents);
@@ -204,17 +205,19 @@ function finishedPhaseLine(phase: PhaseSnapshot, titleWidth: number, theme: Them
     counts.total > 0 ? theme.fg("muted", plural(counts.total, "agent")) : undefined,
     span === undefined ? undefined : theme.fg("muted", shortDuration(span)),
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
   ], theme);
   return `  ${glyph} ${theme.fg("muted", fit(phase.title, titleWidth))}  ${detail}`.trimEnd();
 }
 
 function foldedPhasesLine(phases: readonly PhaseSnapshot[], theme: Theme): string {
   const counts = countAgents(phases);
-  const glyph = counts.failed > 0 ? theme.fg("warning", GLYPH.warning) : theme.fg("success", GLYPH.done);
+  const glyph = counts.failed > 0 || counts.skipped > 0 ? theme.fg("warning", GLYPH.warning) : theme.fg("success", GLYPH.done);
   const titles = phases.map((phase) => phase.title).join(" · ");
   const detail = joinParts([
     theme.fg("muted", plural(counts.total, "agent")),
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
   ], theme);
   return `  ${glyph} ${theme.fg("muted", titles)}  ${detail}`;
 }
@@ -226,6 +229,7 @@ function activePhaseLine(plan: AgentRowPlan, titleWidth: number, theme: Theme):
     counts.queued > 0 ? theme.fg("muted", `${counts.queued} queued`) : undefined,
     counts.done > 0 ? theme.fg("muted", `${counts.done} done`) : undefined,
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
     plan.hidden > 0 ? theme.fg("dim", `+${plan.hidden} more`) : undefined,
   ], theme);
   return `  ${theme.fg("accent", GLYPH.running)} ${theme.bold(fit(plan.phase.title, titleWidth))}  ${detail}`.trimEnd();
@@ -246,6 +250,8 @@ function agentGlyph(agent: AgentRowSnapshot, theme: Theme): string {
       return theme.fg("error", GLYPH.failed);
     case "done":
       return theme.fg("success", GLYPH.done);
+    case "skipped":
+      return theme.fg("warning", GLYPH.skipped);
     case "queued":
       return theme.fg("dim", GLYPH.queued);
   }
@@ -264,6 +270,8 @@ function agentDetail(agent: AgentRowSnapshot, now: number, theme: Theme): string
       ], theme);
     case "failed":
       return theme.fg("error", oneLine(agent.error ?? "failed"));
+    case "skipped":
+      return theme.fg("warning", "skipped");
     case "queued":
       return theme.fg("dim", "queued");
   }

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

@@ -1,3 +1,4 @@
+import type { Usage } from "@earendil-works/pi-ai";
 import { isFiniteNumber, isRecord } from "./guards.ts";
 import { formatCount } from "./text.ts";
 
@@ -81,9 +82,14 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
       const parsed = parseAssistantUsageMessage(message);
       return parsed ? [parsed] : [];
     });
-    if (assistantMessages.length === 0) return;
+    // Tools that call models themselves, such as codemode running a classifier, report it on their result.
+    const toolUsage = input.messages.flatMap((message) => {
+      const parsed = parseToolResultUsage(message);
+      return parsed ? [parsed] : [];
+    });
+    if (assistantMessages.length === 0 && toolUsage.length === 0) return;
 
-    const usage = sumTotals(assistantMessages.map((message) => message.usage));
+    const usage = sumTotals([...assistantMessages.map((message) => message.usage), ...toolUsage]);
     const latestMetadata = assistantMessages.findLast((message) => message.provider !== undefined || message.model !== undefined);
     this.agents.push({
       label: input.label,
@@ -127,6 +133,13 @@ export function hasWorkflowUsage(snapshot: unknown): snapshot is WorkflowUsageSn
   return snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
 }
 
+/** The run's subagent totals as pi's `Usage`, so a tool result adds them to the session's cost. */
+export function workflowUsageForPi(snapshot: unknown): Usage | undefined {
+  if (!hasWorkflowUsage(snapshot)) return undefined;
+  const { input, output, cacheRead, cacheWrite, totalTokens, cost } = snapshot.totals;
+  return { input, output, cacheRead, cacheWrite, totalTokens, cost: { ...cost } };
+}
+
 export function formatWorkflowUsageLine(snapshot: unknown): string | undefined {
   if (!hasWorkflowUsage(snapshot)) return undefined;
   const parts = formatWorkflowUsageComponents(snapshot.totals);
@@ -217,6 +230,11 @@ function parseAssistantUsageMessage(message: unknown): AssistantUsageMessage | u
   };
 }
 
+function parseToolResultUsage(message: unknown): WorkflowUsageTotals | undefined {
+  if (!isRecord(message) || message.role !== "toolResult") return undefined;
+  return parseUsageTotals(message.usage);
+}
+
 function parseUsageTotals(value: unknown): WorkflowUsageTotals | undefined {
   if (!isRecord(value)) return undefined;
   const input = finiteNumber(value.input);

package/.pi/extensions/pi-workflow-engine/src/workflow-advisory-utils.ts

@@ -1,5 +1,8 @@
 import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
-import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
+import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, mergeCandidateInto, repoPathCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
+import { isFatalWorkflowError } from "./cancellation.ts";
+import { WorkflowClassifierUnavailableError } from "./classify.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
 
 
@@ -17,7 +20,9 @@ export type AdvisoryVerified = IdentifiedAdvisoryCandidate & {
 
 export interface LensVerificationPipelineResult {
   verified: AdvisoryVerified[];
+  /** Every candidate the finders returned, including those over the per-lens cap. */
   rawCandidates: number;
+  /** Candidates never verified: over the per-lens cap, duplicates, or out of scope. */
   dropped: number;
   coverage: AdvisoryStageCoverage[];
 }
@@ -49,7 +54,7 @@ export function publishVerifiedKeptProgress(
 }
 
 export interface LensVerificationPipelineOptions {
-  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">;
+  api: Pick<WorkflowApi, "agent" | "classify" | "parallel" | "phase" | "progress" | "log">;
   lenses: readonly AdvisoryLens[];
   perLens: number;
   finderPhase?: "Find" | "Hypothesize";
@@ -70,6 +75,7 @@ export async function runLensVerificationPipeline(
   const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
   const coverage: AdvisoryStageCoverage[] = [];
   let rawCandidates = 0;
+  let overCap = 0;
   api.phase(finderPhase);
   const found = await collectAdvisoryStage(api, "Find", lenses.map((lens) => ({ id: lens.label, run: async () => {
     const result = await api.agent(finderPrompt(lens), {
@@ -77,9 +83,16 @@ export async function runLensVerificationPipeline(
       tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
       profile: "small", schema: AdvisoryCandidatesSchema,
     });
+    rawCandidates += result.candidates.length;
+    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: result.candidates.length });
+    // A finder can return more than the cap its prompt states; keep the first perLens and report the rest.
+    const cut = Math.max(0, result.candidates.length - perLens);
+    if (cut > 0) {
+      overCap += cut;
+      api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: cut });
+      api.log(`Dropped ${cut} ${lens.label} candidate(s) over the per-lens cap of ${perLens}`);
+    }
     const raw = identifyCandidates(result.candidates.slice(0, perLens), lens.label);
-    rawCandidates += raw.length;
-    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
     const candidates = boundCandidate ? raw.flatMap((candidate) => {
       const bounded = boundCandidate(candidate, lens);
       return bounded ? [bounded] : [];
@@ -90,12 +103,13 @@ export async function runLensVerificationPipeline(
     }
     return candidates;
   } })), coverage);
-  const candidates = dedupeCandidates(found.flat());
-  const dropped = rawCandidates - candidates.length;
-  if (dropped > 0) {
-    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-    api.log(`Dropped ${dropped} duplicate or out-of-scope candidate(s)`);
+  const candidates = await mergeEquivalentCandidates(api, dedupeCandidates(found.flat()));
+  const duplicateOrOutOfScope = rawCandidates - overCap - candidates.length;
+  if (duplicateOrOutOfScope > 0) {
+    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: duplicateOrOutOfScope });
+    api.log(`Dropped ${duplicateOrOutOfScope} duplicate or out-of-scope candidate(s)`);
   }
+  const dropped = overCap + duplicateOrOutOfScope;
   api.phase("Verify");
   const verified = await collectAdvisoryStage(api, "Verify", candidates.map((candidate) => ({
     id: candidate.candidateId, candidate, run: async (): Promise<AdvisoryVerified> => {
@@ -112,6 +126,106 @@ export async function runLensVerificationPipeline(
   return { verified, rawCandidates, dropped, coverage };
 }
 
+/** TypeSafe Jev routes in preference order. Jev is the classifier the duplicate merge was measured with. */
+export const DUPLICATE_CANDIDATE_CLASSIFIERS = [
+  "typesafe/jev-latest",
+  "openrouter/~typesafe/jev-latest",
+  "openrouter/typesafe/jev-1.13",
+  "cloudflare-workers-ai/typesafe/jev",
+  "vercel-ai-gateway/typesafe-ai/jev",
+  "opencode/jev-1.13",
+  "opencode/jev-1.13-free",
+] as const;
+
+/** Probability above which two candidates count as one defect. */
+const SAME_DEFECT_PROBABILITY = 0.8;
+
+/**
+ * Merge same-file candidates that a classifier judges to be one defect, so each defect gets one verifier.
+ * Lenses often report the same bug in different words; on GPT-6.1 Sol code reviews this cut verifier
+ * agents and cost by about 40% without losing a finding. Runs without a reachable Jev classifier skip it.
+ */
+export async function mergeEquivalentCandidates<T extends IdentifiedAdvisoryCandidate>(
+  api: Pick<WorkflowApi, "classify" | "parallel" | "log">,
+  candidates: readonly T[],
+): Promise<T[]> {
+  const files = candidates.map(candidateFile);
+  const pairs: Array<readonly [number, number]> = [];
+  for (let first = 0; first < candidates.length; first++) {
+    for (let second = first + 1; second < candidates.length; second++) {
+      if (files[first] === files[second]) pairs.push([first, second]);
+    }
+  }
+  if (pairs.length === 0) return [...candidates];
+  const sameDefect = async ([first, second]: readonly [number, number]): Promise<number> => {
+    const answers = await api.classify({
+      state: { first: candidateForClassifier(candidates[first]!), second: candidateForClassifier(candidates[second]!) },
+      questions: {
+        same: {
+          type: "bool",
+          instructions: "Two code-review candidates were raised against the same file. Do they describe the same underlying defect (same root cause and same fix), even if worded differently?",
+          criteria: { true: "Same underlying defect", false: "Different defects" },
+        },
+      },
+    }, { model: DUPLICATE_CANDIDATE_CLASSIFIERS, label: "dedup" });
+    return answers.same?.type === "bool" ? answers.same.probability : 0;
+  };
+  // The first call probes the classifier: if it fails for any reason (no Jev route, bad credentials, a rate
+  // limit), skip the merge rather than send every other pair into the same failure.
+  let firstProbability: number;
+  try {
+    firstProbability = await sameDefect(pairs[0]!);
+  } catch (error) {
+    if (isFatalWorkflowError(error, undefined)) throw error;
+    if (!(error instanceof WorkflowClassifierUnavailableError)) api.log(`Skipped merging duplicate candidates: ${unknownErrorMessage(error)}`);
+    return [...candidates];
+  }
+  if (pairs.length > 1) api.log(`Comparing ${pairs.length} same-file candidate pairs for duplicates`);
+  const rest = await api.parallel(pairs.slice(1).map((pair) => () => sameDefect(pair)));
+  const probability = new Map<string, number>();
+  pairs.forEach(([first, second], index) => probability.set(`${first}:${second}`, index === 0 ? firstProbability : rest[index - 1] ?? 0));
+
+  // Complete linkage: a candidate joins a group only when it matches every member, so one vague candidate
+  // that resembles two different defects cannot chain them together.
+  const groups: number[][] = [];
+  candidates.forEach((_, index) => {
+    const group = groups.find((members) =>
+      members.every((member) => (probability.get(`${member}:${index}`) ?? 0) >= SAME_DEFECT_PROBABILITY));
+    if (group) group.push(index);
+    else groups.push([index]);
+  });
+  const merged = groups.map(([keep, ...folded]) => {
+    const kept = { ...candidates[keep!]! };
+    for (const index of folded) {
+      const duplicate = candidates[index]!;
+      mergeCandidateInto(kept, duplicate);
+      // The kept summary leads; keep folded wording visible to the verifier in case the classifier was wrong.
+      if (duplicate.summary !== kept.summary) {
+        kept.discoveryEvidence = [...new Set([...(kept.discoveryEvidence ?? []), `Also reported as: ${duplicate.summary}`])];
+      }
+    }
+    return kept;
+  });
+  const folded = candidates.length - merged.length;
+  if (folded > 0) api.log(`Merged ${folded} candidate(s) describing the same defect before verification`);
+  return merged;
+}
+
+/** Pair by the changed line when there is one, with the repository-relative path exact dedup uses. */
+function candidateFile(candidate: IdentifiedAdvisoryCandidate): string {
+  return repoPathCandidates((candidate.reviewAnchor ?? primaryLocation(candidate)).file)[1];
+}
+
+function candidateForClassifier(candidate: IdentifiedAdvisoryCandidate) {
+  return {
+    category: candidate.category,
+    summary: candidate.summary,
+    impact: candidate.impact,
+    location: formatLocation(candidate),
+    evidence: (candidate.discoveryEvidence ?? []).slice(0, 4),
+  };
+}
+
 /** Stats for a lens review that stopped before discovery. */
 export const EMPTY_LENS_REVIEW_STATS: Readonly<WorkflowRunStats> = Object.freeze({ files: 0, candidates: 0, verified: 0, kept: 0, dropped: 0, refuted: 0 });
 

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

@@ -0,0 +1,79 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionKey } from "./session-identity.ts";
+import type { WorkflowMeta } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { DEFAULT_WORKFLOW_SIZE_GUIDELINE, workflowSizeGuidelineLine, type WorkflowSizeGuideline } from "./workflow-settings.ts";
+
+/** System prompt section pi wraps as `<workflows>`: the registered workflows the host may run by name. */
+export const WORKFLOWS_SECTION = "workflows";
+
+/**
+ * One line per workflow, sorted by name, then the size guideline, so the section text depends only on
+ * what is registered and configured.
+ */
+export function formatWorkflowCatalog(workflows: Iterable<WorkflowMeta>, sizeLine?: string): string | undefined {
+  const lines = [...workflows]
+    // Code-unit order rather than localeCompare, whose result depends on the host locale.
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+    .map((meta) => {
+      const description = meta.description.trim();
+      const whenToUse = meta.whenToUse?.trim();
+      return `- ${meta.name}${description ? `: ${description}` : ""}${whenToUse ? ` ${whenToUse}` : ""}`;
+    });
+  const blocks: string[] = [];
+  if (lines.length > 0) {
+    blocks.push(["Registered workflows the workflow tool runs by `name`, passing the target or instructions as `args` (only once the user opted into workflow orchestration):", ...lines].join("\n"));
+  }
+  if (sizeLine) blocks.push(sizeLine);
+  return blocks.length > 0 ? blocks.join("\n\n") : undefined;
+}
+
+export interface WorkflowCatalogSources {
+  readonly discover: (ctx: ExtensionContext) => Promise<Iterable<WorkflowMeta>>;
+  readonly size: (ctx: ExtensionContext) => WorkflowSizeGuideline;
+  readonly log?: (message: string) => void;
+}
+
+/**
+ * The catalog section for each session, built once from discovery and settings and then reused, so every
+ * run in the session sends identical text and keeps the provider's prompt cache. A new session start or a
+ * size change rebuilds it.
+ */
+export class WorkflowCatalogPrompt {
+  private readonly sessions = new Map<string, Promise<string | undefined>>();
+  private readonly log: (message: string) => void;
+
+  constructor(private readonly sources: WorkflowCatalogSources) {
+    this.log = sources.log ?? ((message) => process.stderr.write(`${message}\n`));
+  }
+
+  section(ctx: ExtensionContext): Promise<string | undefined> {
+    const key = sessionKey(ctx);
+    const cached = this.sessions.get(key);
+    if (cached) return cached;
+    const built = this.build(ctx);
+    this.sessions.set(key, built);
+    return built;
+  }
+
+  forget(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    this.sessions.delete(sessionKey(ctx));
+  }
+
+  // The catalog only advertises workflows and a guideline; neither failure may block the prompt.
+  private async build(ctx: ExtensionContext): Promise<string | undefined> {
+    let size = DEFAULT_WORKFLOW_SIZE_GUIDELINE;
+    try {
+      size = this.sources.size(ctx);
+    } catch (error) {
+      this.log(`[workflow] workflow size guideline unavailable, using ${size}: ${unknownErrorMessage(error)}`);
+    }
+    let workflows: Iterable<WorkflowMeta> = [];
+    try {
+      workflows = await this.sources.discover(ctx);
+    } catch (error) {
+      this.log(`[workflow] workflow catalog unavailable: ${unknownErrorMessage(error)}`);
+    }
+    return formatWorkflowCatalog(workflows, workflowSizeGuidelineLine(size));
+  }
+}

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

@@ -25,6 +25,8 @@ export interface WorkflowResultEnvelope {
   readonly perf?: WorkflowPerfDetails;
   readonly runId?: string;
   readonly resumedFromRunId?: string;
+  /** Whether an inline run's script was persisted beside its journal. */
+  readonly scriptPersisted?: boolean;
 }
 
 /** A workflow result's own summary: the result itself when it is a string, else its string `summary` field. */
@@ -36,7 +38,7 @@ export function workflowResultSummary(result: unknown): string | undefined {
 export type ResolvedWorkflowRunner = (
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  args: unknown,
   options: ResolvedWorkflowRunOptions,
 ) => Promise<unknown>;
 
@@ -44,7 +46,8 @@ export interface WorkflowExecutionInput {
   readonly ctx: ExtensionContext;
   readonly name: string;
   readonly mod: LoadedWorkflow;
-  readonly args: string;
+  /** A slash command's argument string, or a tool call's string or JSON value. */
+  readonly args: unknown;
   readonly options: ResolvedWorkflowRunOptions;
   readonly perfRecorder?: PerfSink;
   readonly runResolvedWorkflow: ResolvedWorkflowRunner;
@@ -99,6 +102,7 @@ export async function executeWorkflowInvocation(input: WorkflowExecutionInput):
     perf: perfSnapshot?.enabled ? { aggregates: perfSnapshot.aggregates } : undefined,
     runId: runMetadata?.runId,
     resumedFromRunId: runMetadata?.resumedFromRunId,
+    scriptPersisted: runMetadata?.scriptPath !== undefined,
   };
 }
 

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

@@ -0,0 +1,13 @@
+// A workflow's input is the string a slash command passes, or any JSON value from a tool call or
+// `api.workflow()`. Workflows read it verbatim as `api.input` and as text as `api.args`.
+
+/** `api.args`: a string verbatim, any other JSON value as JSON text, and "" when nothing was passed. */
+export function workflowArgsText(input: unknown): string {
+  if (typeof input === "string") return input;
+  return JSON.stringify(input) ?? "";
+}
+
+/** Whether a run had arguments. Run records never keep them, so such a run cannot be relaunched. */
+export function workflowInputPresent(input: unknown): boolean {
+  return input !== undefined && input !== "";
+}

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

@@ -2,10 +2,14 @@ import type {
   LoadedWorkflow,
   WorkflowMeta,
   WorkflowModule,
+  WorkflowPhaseMeta,
   WorkflowSourceIdentity,
 } from "./types.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
 import { isRecord } from "./guards.ts";
+import { isWorkflowModelProfileName } from "./model-profiles.ts";
+
+const PHASES_SHAPE = 'meta.phases must be an array of { title: string, profile?: "small" | "medium" | "big" }';
 
 /** Validate and normalize workflow metadata without executing workflow code. */
 export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { reason: string } {
@@ -15,10 +19,14 @@ export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { rea
   const description = meta.description;
   if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
 
-  const phases = meta.phases;
-  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+  const whenToUse = meta.whenToUse;
+  if (whenToUse !== undefined && typeof whenToUse !== "string") return { reason: "meta.whenToUse must be a string when provided" };
+
+  const phases = meta.phases === undefined ? undefined : parseWorkflowPhases(meta.phases);
+  if (phases === null) return { reason: PHASES_SHAPE };
 
   const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (whenToUse !== undefined) workflowMeta.whenToUse = whenToUse;
   if (phases !== undefined) workflowMeta.phases = phases;
   return { meta: workflowMeta };
 }
@@ -50,6 +58,15 @@ function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
   return typeof value === "function";
 }
 
-function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
-  return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
+/** The declared phases keeping only known fields, or null when any entry is malformed. */
+function parseWorkflowPhases(value: unknown): WorkflowPhaseMeta[] | null {
+  if (!Array.isArray(value)) return null;
+  const phases: WorkflowPhaseMeta[] = [];
+  for (const phase of value) {
+    if (!isRecord(phase) || typeof phase.title !== "string") return null;
+    const { profile } = phase;
+    if (profile !== undefined && (typeof profile !== "string" || !isWorkflowModelProfileName(profile))) return null;
+    phases.push({ title: phase.title, ...(profile === undefined ? {} : { profile }) });
+  }
+  return phases;
 }

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

@@ -1,5 +1,8 @@
+import { join } from "node:path";
 import { 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 { toReviewIssues } from "./review/review-issues.ts";
 import { formatPerfSummary } from "./perf.ts";
 import { prettyJson } from "./text.ts";
@@ -15,19 +18,36 @@ export function formatWorkflowResultForContext(envelope: WorkflowResultEnvelope)
   return `## Workflow: ${envelope.name}\n\n${formatResultForContext(envelope.result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
 }
 
-/** Run id, usage and perf lines appended for the host model. */
+/** Run id, run files, usage and perf lines appended for the host model. */
 function formatWorkflowDetailLines(envelope: WorkflowResultEnvelope): string[] {
-  const run = envelope.runId
-    ? envelope.resumedFromRunId ? `Run: ${envelope.runId} (resumed from ${envelope.resumedFromRunId})` : `Run: ${envelope.runId}`
-    : undefined;
   return [
-    run,
+    ...(envelope.runId
+      ? [formatWorkflowRunLine({ runId: envelope.runId, resumedFromRunId: envelope.resumedFromRunId }), ...formatWorkflowRunFileLines(envelope.runId, envelope.scriptPersisted === true)]
+      : []),
     formatWorkflowUsageLine(envelope.usage),
     envelope.perf ? formatPerfSummary(envelope.perf.aggregates) : undefined,
   ].filter((line): line is string => line !== undefined);
 }
 
-function formatResultForContext(result: unknown): string {
+/** The run id, naming the run a resume continues. */
+export function formatWorkflowRunLine(run: { readonly runId: string; readonly resumedFromRunId?: string }): string {
+  return run.resumedFromRunId ? `Run: ${run.runId} (resumed from ${run.resumedFromRunId})` : `Run: ${run.runId}`;
+}
+
+/**
+ * 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.
+ */
+export function formatWorkflowRunFileLines(runId: string, scriptPersisted: boolean): string[] {
+  return [
+    ...(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 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);
   const summary = workflowResultSummary(result);

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

@@ -23,6 +23,7 @@ export function createPersistedWorkflowBackground(
     origin: {
       sessionId: truncateText(origin.sessionId, MAX_BACKGROUND_TEXT),
       requestedAt: origin.requestedAt,
+      ...(origin.wakeOnComplete ? { wakeOnComplete: true } : {}),
     },
     delivery: { state: "pending" },
   };
@@ -49,6 +50,7 @@ export function updateWorkflowRunDelivery(
 export function isPersistedWorkflowBackground(value: unknown): value is PersistedWorkflowBackground {
   if (!isRecord(value) || !isRecord(value.origin) || !isRecord(value.delivery)) return false;
   if (typeof value.origin.sessionId !== "string" || !isFiniteNumber(value.origin.requestedAt)) return false;
+  if (value.origin.wakeOnComplete !== undefined && typeof value.origin.wakeOnComplete !== "boolean") return false;
   switch (value.delivery.state) {
     case "pending":
       return true;