pi-workflow-engine 0.13.0 → 1.0.0

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

@@ -1,7 +1,8 @@
-import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+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 type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
 
+
 export interface AdvisoryLens {
   label: string;
   category: string;
@@ -11,7 +12,6 @@ export interface AdvisoryLens {
 export type AdvisoryVerified = IdentifiedAdvisoryCandidate & {
   verdict: AdvisoryVerdict["verdict"];
   evidence: string[];
-  confidence?: AdvisoryVerdict["confidence"];
   challenge?: import("./advisory-challenge.ts").ChallengeRecord;
 };
 
@@ -19,7 +19,6 @@ export interface LensVerificationPipelineResult {
   verified: AdvisoryVerified[];
   rawCandidates: number;
   dropped: number;
-  refuted: number;
   coverage: AdvisoryStageCoverage[];
 }
 
@@ -71,7 +70,6 @@ export async function runLensVerificationPipeline(
   const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
   const coverage: AdvisoryStageCoverage[] = [];
   let rawCandidates = 0;
-  let refuted = 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), {
@@ -107,11 +105,59 @@ export async function runLensVerificationPipeline(
         tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
         profile: "small", schema: AdvisoryVerdictSchema,
       });
-      recordVerdictProgress(api.progress, candidate, judged, () => { refuted += 1; });
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence };
+      recordVerdictProgress(api.progress, candidate, judged);
+      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence };
     },
   })), coverage);
-  return { verified, rawCandidates, dropped, refuted, coverage };
+  return { verified, rawCandidates, dropped, coverage };
+}
+
+/** 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 });
+
+export interface LensReviewConclusion {
+  /** Scoped file count reported in stats. */
+  files: number;
+  rank(finding: AdvisoryVerified): number;
+  /** One ranked finding's synthesis-prompt block, headed by the IDs synthesis selects; defaults to {@link formatRankedFinding}. */
+  formatFinding?(finding: AdvisoryVerified, index: number): string;
+  /** Report used when no finding survives verification and challenge. */
+  empty: { summary: string; nextSteps: string[] };
+  synthesisPrompt(block: string, ranked: readonly AdvisoryVerified[], refuted: readonly AdvisoryVerified[]): string;
+}
+
+export function formatRankedFinding(finding: AdvisoryVerified, index: number, recommendationLabel = "Recommendation"): string {
+  return `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
+    `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\n${recommendationLabel}: ${finding.recommendation ?? "(none supplied)"}`;
+}
+
+/** Rank and synthesize the findings that survived verification and challenge into the final report. */
+export async function concludeLensReview(
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">,
+  pipeline: LensVerificationPipelineResult,
+  verified: AdvisoryVerified[],
+  conclusion: LensReviewConclusion,
+) {
+  const { coverage } = pipeline;
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const stats: WorkflowRunStats = {
+    files: conclusion.files,
+    candidates: pipeline.rawCandidates,
+    verified: verified.length,
+    kept: surviving.length,
+    dropped: pipeline.dropped,
+    refuted: verified.length - surviving.length,
+  };
+  publishVerifiedKeptProgress(api, verified.length, surviving.length);
+  if (surviving.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(conclusion.empty.summary, conclusion.empty.nextSteps, stats), coverage, verified);
+  }
+
+  const ranked = [...surviving].sort((a, b) => conclusion.rank(a) - conclusion.rank(b));
+  const block = ranked.map((finding, index) => (conclusion.formatFinding ?? formatRankedFinding)(finding, index)).join("\n\n");
+  const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
+  const resolved = await synthesizeAdvisoryReport(api, conclusion.synthesisPrompt(block, ranked, refuted), ranked, coverage);
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
 }
 
 export async function synthesizeAdvisoryReport(
@@ -123,7 +169,7 @@ export async function synthesizeAdvisoryReport(
   api.phase("Synthesize");
   const [report] = await collectAdvisoryStage(api, "Synthesize", [{ id: "synthesize", run: () => api.agent(
     SYNTHESIS_ID_INSTRUCTIONS + prompt,
-    { phase: "Synthesize", label: "synthesize", tools: [], profile: "medium", resume: "read-only", schema: AdvisorySynthesisSchema },
+    { phase: "Synthesize", label: "synthesize", tools: [], skills: [], profile: "medium", resume: "read-only", schema: AdvisorySynthesisSchema },
   ) }], coverage);
   return resolveAdvisorySynthesis(report, ranked, {
     impact: "Impact not restated by verification.",
@@ -142,27 +188,20 @@ export function primaryLocation(candidate: Pick<AdvisoryCandidate, "locations">)
 }
 
 export function formatLocation(candidate: Pick<AdvisoryCandidate, "locations">): string {
-  const location = primaryLocation(candidate);
-  const line = location.line != null ? `:${location.line}` : "";
-  const symbol = location.symbol ? ` (${location.symbol})` : "";
-  return `${location.file}${line}${symbol}`;
+  return formatAdvisoryLocation(primaryLocation(candidate));
 }
 
 export function formatEvidence(evidence: readonly string[]): string {
   return evidence.join("; ");
 }
 
-export function normalizePath(path: string): string {
-  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
-}
-
 const VERDICT_PRESENTATION = {
   CONFIRMED: { lane: "Confirmed", status: "success", confidence: "high" },
   PLAUSIBLE: { lane: "Plausible", status: "warning", confidence: "medium" },
   NOT_SUBSTANTIATED: { lane: "Unresolved", status: "warning", confidence: "medium" },
   REFUTED: { lane: "Refuted", status: "error", confidence: "low" },
 } satisfies Record<AdvisoryVerdict["verdict"], {
-  lane: string; status: "success" | "warning" | "error"; confidence: NonNullable<AdvisoryVerdict["confidence"]>;
+  lane: string; status: "success" | "warning" | "error"; confidence: AdvisoryFinding["confidence"];
 }>;
 
 export function verdictConfidence(verdict: AdvisoryVerdict["verdict"]): "high" | "medium" | "low" {
@@ -173,11 +212,9 @@ export function recordVerdictProgress(
   progress: (event: WorkflowProgressEvent) => void,
   candidate: Pick<AdvisoryCandidate, "locations" | "summary">,
   verdict: Pick<AdvisoryVerdict, "verdict" | "evidence">,
-  onRefuted?: () => void,
 ): void {
   progress({ type: "counter_delta", key: `verdict.${verdict.verdict.toLowerCase()}`, label: verdict.verdict, delta: 1 });
   if (verdict.verdict === "REFUTED") {
-    onRefuted?.();
     progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
   }
   progress({

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

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "./guards.ts";
 import type { ResolvedWorkflowRunOptions } from "./options.ts";
 import type { PerfAggregate, PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
@@ -11,14 +12,14 @@ import type {
 import type { WorkflowUsageSnapshot } from "./usage.ts";
 
 export interface WorkflowPerfDetails {
-  readonly enabled: boolean;
-  readonly startedAt: number;
   readonly aggregates: readonly PerfAggregate[];
 }
 
 export interface WorkflowResultEnvelope {
   readonly name: string;
   readonly result: unknown;
+  /** Optional so envelopes persisted before it existed still render. */
+  readonly startedAt?: number;
   readonly completedAt: number;
   readonly usage?: WorkflowUsageSnapshot;
   readonly perf?: WorkflowPerfDetails;
@@ -26,6 +27,12 @@ export interface WorkflowResultEnvelope {
   readonly resumedFromRunId?: string;
 }
 
+/** A workflow result's own summary: the result itself when it is a string, else its string `summary` field. */
+export function workflowResultSummary(result: unknown): string | undefined {
+  if (typeof result === "string") return result;
+  return isRecord(result) && typeof result.summary === "string" ? result.summary : undefined;
+}
+
 export type ResolvedWorkflowRunner = (
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
@@ -46,13 +53,8 @@ export interface WorkflowExecutionInput {
   readonly onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
 }
 
-export interface WorkflowExecution {
-  readonly metadata?: WorkflowRunMetadata;
-  readonly envelope: WorkflowResultEnvelope;
-}
-
 /** Shared command/tool execution path. The engine remains lazy-loaded by the caller. */
-export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowResultEnvelope> {
   let perfSnapshot: PerfSnapshot | undefined;
   let usageSnapshot: WorkflowUsageSnapshot | undefined;
   let runMetadata: WorkflowRunMetadata | undefined;
@@ -86,27 +88,20 @@ export async function executeWorkflowInvocation(input: WorkflowExecutionInput):
       );
     },
   };
+  const startedAt = Date.now();
   const result = await input.runResolvedWorkflow(input.ctx, input.mod, input.args, runOptions);
-  const perf = compactPerfSnapshot(perfSnapshot);
   return {
-    metadata: runMetadata,
-    envelope: {
-      name: input.name,
-      result,
-      completedAt: Date.now(),
-      usage: usageSnapshot,
-      perf,
-      runId: runMetadata?.runId,
-      resumedFromRunId: runMetadata?.resumedFromRunId,
-    },
+    name: input.name,
+    result,
+    startedAt,
+    completedAt: Date.now(),
+    usage: usageSnapshot,
+    perf: perfSnapshot?.enabled ? { aggregates: perfSnapshot.aggregates } : undefined,
+    runId: runMetadata?.runId,
+    resumedFromRunId: runMetadata?.resumedFromRunId,
   };
 }
 
-function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
-  if (!snapshot?.enabled) return undefined;
-  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
-}
-
 async function notifyLifecycleObservers(...observers: ReadonlyArray<() => void | Promise<void>>): Promise<void> {
   const failures: unknown[] = [];
   for (const observer of observers) {

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

@@ -5,35 +5,33 @@ import type {
   WorkflowSourceIdentity,
 } from "./types.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
+import { isRecord } from "./guards.ts";
 
-type WorkflowMetaCandidate = {
-  readonly name?: unknown;
-  readonly description?: unknown;
-  readonly phases?: unknown;
-};
+/** Validate and normalize workflow metadata without executing workflow code. */
+export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { reason: string } {
+  if (!isRecord(meta)) return { reason: "meta export must be an object" };
+  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
 
-type WorkflowModuleCandidate = {
-  readonly meta?: unknown;
-  readonly default?: unknown;
-};
+  const description = meta.description;
+  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
 
-/** Validate and normalize workflow metadata without executing workflow code. */
-export function parseWorkflowMeta(value: unknown): { meta: WorkflowMeta } | { reason: string } {
-  if (!isRecord(value)) return { reason: "meta export must be an object" };
-  return parseWorkflowMetaObject(value);
+  const phases = meta.phases;
+  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+
+  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (phases !== undefined) workflowMeta.phases = phases;
+  return { meta: workflowMeta };
 }
 
 export function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
   if (!isRecord(value)) return { reason: "module export is not an object" };
-  const candidate = value as WorkflowModuleCandidate;
-  const meta = candidate.meta;
-  if (!isRecord(meta)) return { reason: "missing meta export" };
+  if (value.meta === undefined) return { reason: "missing meta export" };
 
-  const parsedMeta = parseWorkflowMetaObject(meta);
+  const parsedMeta = parseWorkflowMeta(value.meta);
   if ("reason" in parsedMeta) return parsedMeta;
-  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+  if (!isWorkflowRun(value.default)) return { reason: "default export must be a function" };
 
-  return { module: { meta: parsedMeta.meta, default: candidate.default } };
+  return { module: { meta: parsedMeta.meta, default: value.default } };
 }
 
 /** Attach engine-owned source provenance after an authored module has been validated. */
@@ -48,20 +46,6 @@ export function loadWorkflow(
     : { ...loaded, isolatedWorktreeBaseline };
 }
 
-function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
-  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
-
-  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 workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
-  if (phases !== undefined) workflowMeta.phases = phases;
-  return { meta: workflowMeta };
-}
-
 function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
   return typeof value === "function";
 }
@@ -69,7 +53,3 @@ function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
 function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
   return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}

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

@@ -0,0 +1,79 @@
+import { formatAdvisoryLocation, isAdvisoryReport, type AdvisoryFinding, type AdvisoryReport } from "./advisory-schema.ts";
+import { isRecord } from "./guards.ts";
+import { toReviewIssues } from "./review/review-issues.ts";
+import { formatPerfSummary } from "./perf.ts";
+import { prettyJson } from "./text.ts";
+import { formatWorkflowUsageLine } from "./usage.ts";
+import { workflowResultSummary, type WorkflowResultEnvelope } from "./workflow-execution.ts";
+
+/** Cap on the result JSON copied into the host agent's context; the run record keeps the full value. */
+const MAX_CONTEXT_RESULT_JSON_CHARS = 20_000;
+
+/** The host model only sees this text, never the envelope `details`, so it carries every result field. */
+export function formatWorkflowResultForContext(envelope: WorkflowResultEnvelope): string {
+  const details = formatWorkflowDetailLines(envelope);
+  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. */
+function formatWorkflowDetailLines(envelope: WorkflowResultEnvelope): string[] {
+  const run = envelope.runId
+    ? envelope.resumedFromRunId ? `Run: ${envelope.runId} (resumed from ${envelope.resumedFromRunId})` : `Run: ${envelope.runId}`
+    : undefined;
+  return [
+    run,
+    formatWorkflowUsageLine(envelope.usage),
+    envelope.perf ? formatPerfSummary(envelope.perf.aggregates) : undefined,
+  ].filter((line): line is string => line !== undefined);
+}
+
+function formatResultForContext(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result);
+  const summary = workflowResultSummary(result);
+  if (summary !== undefined && isRecord(result) && Object.keys(result).length === 1) return summary;
+  const json = formatResultJson(result);
+  if (json === undefined) return summary ?? "Workflow finished.";
+  return summary === undefined ? json : `${summary}\n\n${json}`;
+}
+
+function formatAdvisoryReportForContext(report: AdvisoryReport): string {
+  const lines = [report.summary];
+  const issues = toReviewIssues(report);
+  if (issues.length > 0) {
+    lines.push("", "Findings:");
+    for (const { id, finding } of issues) {
+      lines.push(
+        `\n### ${id}: ${finding.summary}`,
+        `- Severity: ${finding.severity}`,
+        `- Confidence: ${finding.confidence}`,
+        `- Category: ${finding.category}`,
+        `- Location: ${formatFindingLocations(finding)}`,
+        `- Impact: ${finding.impact}`,
+        `- Evidence: ${finding.evidence.length > 0 ? finding.evidence.join("; ") : "(none cited)"}`,
+        `- Recommendation: ${finding.recommendation}`,
+      );
+    }
+  }
+  if (report.gaps && report.gaps.length > 0) {
+    lines.push("", "Coverage gaps:", ...report.gaps.map((gap) => `- ${gap}`));
+  }
+  if (report.nextSteps.length > 0) {
+    lines.push("", "Next steps:", ...report.nextSteps.map((step) => `- ${step}`));
+  }
+  return lines.join("\n");
+}
+
+function formatResultJson(result: unknown): string | undefined {
+  if (result === null || result === undefined) return undefined;
+  const json = prettyJson(result);
+  if (json === undefined) return undefined;
+  if (json.length <= MAX_CONTEXT_RESULT_JSON_CHARS) return `Result:\n\`\`\`json\n${json}\n\`\`\``;
+  return `Result (first ${MAX_CONTEXT_RESULT_JSON_CHARS} of ${json.length} characters; truncated, the run record holds the full value):\n\`\`\`json\n${json.slice(0, MAX_CONTEXT_RESULT_JSON_CHARS)}\n\`\`\``;
+}
+
+/** The review anchor that the findings viewer and PR comments cite comes first, then every other cited location. */
+function formatFindingLocations(finding: AdvisoryFinding): string {
+  const locations = finding.reviewAnchor ? [finding.reviewAnchor, ...finding.locations] : finding.locations;
+  return [...new Set(locations.map(formatAdvisoryLocation))].join(", ");
+}

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

@@ -1,3 +1,5 @@
+import { isFiniteNumber, isRecord } from "./guards.ts";
+import { truncateText } from "./text.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import type { WorkflowRunRecord } from "./workflow-run-record.ts";
 
@@ -19,7 +21,7 @@ export function createPersistedWorkflowBackground(
   if (!origin) return undefined;
   return {
     origin: {
-      sessionId: boundedText(origin.sessionId),
+      sessionId: truncateText(origin.sessionId, MAX_BACKGROUND_TEXT),
       requestedAt: origin.requestedAt,
     },
     delivery: { state: "pending" },
@@ -38,7 +40,7 @@ export function updateWorkflowRunDelivery(
     background: {
       origin: record.background.origin,
       delivery: delivery.state === "unavailable"
-        ? { ...delivery, message: boundedText(delivery.message) }
+        ? { ...delivery, message: truncateText(delivery.message, MAX_BACKGROUND_TEXT) }
         : delivery,
     },
   };
@@ -58,15 +60,3 @@ export function isPersistedWorkflowBackground(value: unknown): value is Persiste
       return false;
   }
 }
-
-function boundedText(value: string): string {
-  return value.length <= MAX_BACKGROUND_TEXT ? value : `${value.slice(0, MAX_BACKGROUND_TEXT - 1)}…`;
-}
-
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}