pi-workflow-engine 0.10.2 → 0.11.0

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

@@ -2,22 +2,28 @@ import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { SelectList, Text, truncateToWidth, type Component, type SelectItem, type SelectListTheme, type TUI } from "@earendil-works/pi-tui";
+import { isAdvisoryReport } from "./src/advisory-schema.ts";
 import type { WorkflowProgressSnapshot } from "./src/progress.ts";
-import type { WorkflowModule, WorkflowProgressSource, WorkflowRef, WorkflowRunMetadata, WorkflowRunOptions } from "./src/types.ts";
+import type { LoadedWorkflow, WorkflowModule, WorkflowProgressSource, WorkflowRef, WorkflowRunMetadata, WorkflowRunOptions } from "./src/types.ts";
 import { WorkflowInspector } from "./src/ui/workflow-inspector.ts";
-import type { PerfSink, PerfSnapshot } from "./src/perf.ts";
+import type { PerfSink } from "./src/perf.ts";
 import type { WorkflowUsageSnapshot } from "./src/usage.ts";
-import { registerDynamax } from "./src/dynamax.ts";
-import { handleReviewViewerAction } from "./src/review/review-actions.ts";
-import { decideReviewResultsPresentation, extensionContextMode, maybeShowReviewResultsViewer } from "./src/review/review-results-flow.ts";
+import { ADAPTIVE_WORKFLOW_GUIDANCE, dynamaxSessionKey, registerDynamax } from "./src/dynamax.ts";
+import { resolveDynamaxShortcuts, type DynamaxShortcuts } from "./src/dynamax-shortcuts.ts";
+import { ReviewSessionCoordinator } from "./src/review/review-session-coordinator.ts";
 import {
   formatWorkflowDetailLines,
   isWorkflowResult,
   renderWorkflowResult,
-  type WorkflowPerfDetails,
-  type WorkflowResultEnvelope,
 } from "./src/ui/workflow-result-renderer.ts";
-import { parseWorkflowBudgetString, WORKFLOW_BUDGET_MAX, WORKFLOW_BUDGET_MIN } from "./src/options.ts";
+import {
+  parseWorkflowBudgetString,
+  resolveWorkflowRunOptions,
+  type ResolvedWorkflowRunOptions,
+  WORKFLOW_BUDGET_MAX,
+  WORKFLOW_BUDGET_MIN,
+} from "./src/options.ts";
+import { executeWorkflowInvocation, type WorkflowExecution, type WorkflowPerfDetails } from "./src/workflow-execution.ts";
 
 /** Extension root (this file lives in <repo>/.pi/extensions/pi-workflow-engine/index.ts). */
 const EXTENSION_DIR = fileURLToPath(new URL(".", import.meta.url));
@@ -37,22 +43,39 @@ function formatMessageContent(
   metadata?: WorkflowRunMetadata,
 ): string {
   const details = formatWorkflowDetailLines({ usage, perf, metadata });
-  return `## Workflow: ${name}\n\n${summarize(result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
-}
-
-function workflowEnvelope(
-  name: string,
-  result: unknown,
-  usage?: WorkflowUsageSnapshot,
-  perf?: WorkflowPerfDetails,
-  metadata?: WorkflowRunMetadata,
-): WorkflowResultEnvelope {
-  return { name, result, completedAt: Date.now(), usage, perf, runId: metadata?.runId, resumedFromRunId: metadata?.resumedFromRunId };
+  return `## Workflow: ${name}\n\n${formatResultForContext(result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
+}
+
+function formatResultForContext(result: unknown): string {
+  if (!isAdvisoryReport(result)) return summarize(result);
+
+  const lines = [result.summary];
+  if (result.findings.length > 0) {
+    lines.push("", "Findings:");
+    result.findings.forEach((finding, index) => {
+      const id = `R${String(index + 1).padStart(3, "0")}`;
+      lines.push(
+        `\n### ${id}: ${finding.summary}`,
+        `- Severity: ${finding.severity}`,
+        `- Confidence: ${finding.confidence}`,
+        `- Category: ${finding.category}`,
+        `- Location: ${finding.locations.map(formatFindingLocation).join(", ")}`,
+        `- Impact: ${finding.impact}`,
+        `- Evidence: ${finding.evidence.length > 0 ? finding.evidence.join("; ") : "(none cited)"}`,
+        `- Recommendation: ${finding.recommendation}`,
+      );
+    });
+  }
+  if (result.nextSteps.length > 0) {
+    lines.push("", "Next steps:", ...result.nextSteps.map((step) => `- ${step}`));
+  }
+  return lines.join("\n");
 }
 
-function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
-  if (!snapshot?.enabled) return undefined;
-  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
+function formatFindingLocation(location: { readonly file: string; readonly line?: number; readonly symbol?: string }): string {
+  const line = location.line === undefined ? "" : `:${location.line}`;
+  const symbol = location.symbol === undefined ? "" : ` (${location.symbol})`;
+  return `${location.file}${line}${symbol}`;
 }
 
 type DiscoveryModule = typeof import("./src/discovery.ts");
@@ -71,9 +94,8 @@ async function loadInlineWorkflow(): Promise<InlineWorkflowModule> {
   return await import("./src/inline-workflow.ts");
 }
 
-async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSink | undefined> {
-  const enabled = options.perf ?? process.env.PI_WORKFLOW_PERF === "1";
-  if (!enabled) return undefined;
+async function createInvocationPerf(options: ResolvedWorkflowRunOptions): Promise<PerfSink | undefined> {
+  if (!options.perf) return undefined;
   const { createPerfRecorder } = await import("./src/perf.ts");
   return createPerfRecorder(true);
 }
@@ -81,7 +103,7 @@ async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSi
 /**
  * Resolve an `api.workflow()` reference to a registered workflow module. Throws on an unknown name.
  */
-export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<WorkflowModule> {
+export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<LoadedWorkflow> {
   const { discoverWorkflows } = await loadDiscovery();
   const workflows = await discoverWorkflows(EXTENSION_DIR, { perf });
   const mod = workflows.get(ref);
@@ -182,15 +204,21 @@ export interface ActiveWorkflowInspection {
   readonly snapshot: () => WorkflowProgressSnapshot;
 }
 
-let lastWorkflowInspection: LastWorkflowInspection | undefined;
-let activeWorkflowInspection: ActiveWorkflowInspection | undefined;
+interface SessionWorkflowInspections {
+  last?: LastWorkflowInspection;
+  active?: ActiveWorkflowInspection;
+}
+
+const workflowInspections = new WeakMap<ExtensionAPI, Map<string, SessionWorkflowInspections>>();
+let latestWorkflowInspection: LastWorkflowInspection | undefined;
+let latestActiveWorkflowInspection: ActiveWorkflowInspection | undefined;
 
 export function getLastWorkflowInspection(): LastWorkflowInspection | undefined {
-  return lastWorkflowInspection;
+  return latestWorkflowInspection;
 }
 
 export function getActiveWorkflowInspection(): ActiveWorkflowInspection | undefined {
-  return activeWorkflowInspection;
+  return latestActiveWorkflowInspection;
 }
 
 export async function openWorkflowInspector(ctx: ExtensionContext, inspection: LastWorkflowInspection | ActiveWorkflowInspection): Promise<void> {
@@ -200,12 +228,22 @@ export async function openWorkflowInspector(ctx: ExtensionContext, inspection: L
   );
 }
 
-async function openAvailableWorkflowInspector(ctx: ExtensionContext): Promise<void> {
+function workflowInspectionState(pi: ExtensionAPI, ctx: ExtensionContext): SessionWorkflowInspections {
+  const sessions = workflowInspections.get(pi) ?? new Map<string, SessionWorkflowInspections>();
+  const key = dynamaxSessionKey(ctx);
+  const state = sessions.get(key) ?? {};
+  sessions.set(key, state);
+  workflowInspections.set(pi, sessions);
+  return state;
+}
+
+async function openAvailableWorkflowInspector(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) {
     ctx.ui.notify("Workflow inspector requires the TUI", "warning");
     return;
   }
-  const inspection = activeWorkflowInspection ?? lastWorkflowInspection;
+  const state = workflowInspectionState(pi, ctx);
+  const inspection = state.active ?? state.last;
   if (!inspection) {
     ctx.ui.notify("No workflow inspector is available yet", "warning");
     return;
@@ -362,6 +400,7 @@ Always pass a plain string as the first api.agent() argument; build prompts with
 If using \`isolation: "worktree"\`, remember api.agent() returns \`{ result, patch, changed }\`; read \`.result\` for the agent answer and \`.patch\` for the diff.
 When the run is budgeted, guard expensive loops with \`while (api.budget.total && api.budget.remaining() > N) { ... }\`; api.agent() throws once the budget is spent.
 Subagents receive no skills by default. When the brief asks for a skill or a stage clearly benefits from one, pass \`skills: ["skill-name"]\` on that agent call only.
+${ADAPTIVE_WORKFLOW_GUIDANCE}
 Do not edit files unless the user explicitly requested edits.`;
 }
 
@@ -425,76 +464,127 @@ export async function pickWorkflow(
 
 export async function sendWorkflowResult(
   pi: ExtensionAPI,
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
   name: string,
-  mod: WorkflowModule,
+  mod: LoadedWorkflow,
   args: string,
   options: WorkflowRunOptions,
   perfRecorder?: PerfSink,
+  reviewSessions: ReviewSessionCoordinator = createReviewSessionCoordinator(pi),
 ): Promise<void> {
-  const { runWorkflow } = await loadEngine();
-  let perfSnapshot: PerfSnapshot | undefined;
-  let usageSnapshot: WorkflowUsageSnapshot | undefined;
-  let runMetadata: WorkflowRunMetadata | undefined;
+  await sendResolvedWorkflowResult(
+    pi,
+    ctx,
+    name,
+    mod,
+    args,
+    resolveWorkflowRunOptions(options),
+    perfRecorder,
+    reviewSessions,
+  );
+}
+
+async function sendResolvedWorkflowResult(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  name: string,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+  perfRecorder: PerfSink | undefined,
+  reviewSessions: ReviewSessionCoordinator,
+): Promise<void> {
+  const execution = await executeResolvedWorkflow(pi, ctx, name, mod, args, options, perfRecorder);
+  reviewSessions.remember(ctx, execution, options);
+  sendWorkflowExecution(pi, execution);
+  await reviewSessions.present(ctx, execution, options);
+}
+
+async function executeResolvedWorkflow(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  name: string,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+  perfRecorder?: PerfSink,
+): Promise<WorkflowExecution> {
+  const { runResolvedWorkflow } = await loadEngine();
   let liveInspection: ActiveWorkflowInspection | undefined;
-  const result = await runWorkflow(ctx, mod, args, {
-    ...options,
-    perf: options.perf ?? perfRecorder !== undefined,
+  const inspections = workflowInspectionState(pi, ctx);
+  return await executeWorkflowInvocation({
+    ctx,
+    name,
+    mod,
+    args,
+    options,
     perfRecorder,
+    runResolvedWorkflow,
     resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
     onProgressSource(source) {
       if (source) {
         liveInspection = bindActiveWorkflowInspection(name, args, source);
-        activeWorkflowInspection = liveInspection;
-      } else if (activeWorkflowInspection === liveInspection) {
-        activeWorkflowInspection = undefined;
+        inspections.active = liveInspection;
+        latestActiveWorkflowInspection = liveInspection;
+      } else if (inspections.active === liveInspection) {
+        inspections.active = undefined;
+        if (latestActiveWorkflowInspection === liveInspection) latestActiveWorkflowInspection = undefined;
         liveInspection = undefined;
       }
-      options.onProgressSource?.(source);
-    },
-    onPerfSnapshot(snapshot) {
-      perfSnapshot = snapshot;
-      options.onPerfSnapshot?.(snapshot);
-    },
-    onUsageSnapshot(snapshot) {
-      usageSnapshot = snapshot;
-      options.onUsageSnapshot?.(snapshot);
-    },
-    onRunMetadata(metadata) {
-      runMetadata = metadata;
-      options.onRunMetadata?.(metadata);
     },
     onProgressSnapshot(snapshot) {
-      lastWorkflowInspection = { name, args, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
-      options.onProgressSnapshot?.(snapshot);
+      const completed = { name, args, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
+      inspections.last = completed;
+      latestWorkflowInspection = completed;
     },
   });
-  const perf = compactPerfSnapshot(perfSnapshot);
-  const reviewDecision = decideReviewResultsPresentation({
-    workflowName: name,
-    result,
-    mode: extensionContextMode(ctx),
-    hasUI: ctx.hasUI,
-    resultViewer: options.resultViewer,
-    invocationKind: "command",
-  });
-  const reviewAction = await maybeShowReviewResultsViewer(ctx, reviewDecision);
-  if (reviewDecision.kind !== "send") {
-    await handleReviewViewerAction(pi, ctx, reviewAction, reviewDecision.issues, reviewDecision.report.reviewContext);
-  }
+}
+
+function sendWorkflowExecution(pi: ExtensionAPI, execution: WorkflowExecution): void {
+  const { name } = execution.envelope;
   pi.sendMessage(
     {
       customType: "workflow-result",
-      content: formatMessageContent(name, result, usageSnapshot, perf, runMetadata),
+      content: formatMessageContent(
+        name,
+        execution.envelope.result,
+        execution.envelope.usage,
+        execution.envelope.perf,
+        execution.metadata,
+      ),
       display: true,
-      details: workflowEnvelope(name, result, usageSnapshot, perf, runMetadata),
+      details: execution.envelope,
     },
     { triggerTurn: false },
   );
 }
 
-export default function workflowEngine(pi: ExtensionAPI): void {
-  registerDynamax(pi, undefined, { openInspector: openAvailableWorkflowInspector });
+function createReviewSessionCoordinator(pi: ExtensionAPI): ReviewSessionCoordinator {
+  return new ReviewSessionCoordinator(pi, {
+    async runFollowUp(ctx, workflow, options) {
+      const perfRecorder = await createInvocationPerf(options);
+      return await executeResolvedWorkflow(pi, ctx, workflow.meta.name, workflow, "", options, perfRecorder);
+    },
+    publish: (execution) => sendWorkflowExecution(pi, execution),
+  });
+}
+
+export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShortcuts = resolveDynamaxShortcuts()): void {
+  const reviewSessions = createReviewSessionCoordinator(pi);
+  registerDynamax(pi, shortcuts, { openInspector: (ctx) => openAvailableWorkflowInspector(pi, ctx) });
+  pi.on("session_shutdown", (_event, ctx) => {
+    const key = dynamaxSessionKey(ctx);
+    workflowInspections.get(pi)?.delete(key);
+    reviewSessions.dispose(ctx);
+  });
+  if (shortcuts.results) {
+    pi.registerShortcut(shortcuts.results, {
+      description: "Open last code-review results",
+      handler: async (ctx) => {
+        await reviewSessions.reopen(ctx);
+      },
+    });
+  }
 
   pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
     const details = message.details;
@@ -515,7 +605,18 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         ctx.ui.notify("Usage: /workflow:inspector [last]", "warning");
         return;
       }
-      await openAvailableWorkflowInspector(ctx);
+      await openAvailableWorkflowInspector(pi, ctx);
+    },
+  });
+
+  pi.registerCommand("workflow:results", {
+    description: "Reopen the last code-review findings viewer",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      if (args.trim()) {
+        ctx.ui.notify("Usage: /workflow:results", "warning");
+        return;
+      }
+      await reviewSessions.reopen(ctx);
     },
   });
 
@@ -528,7 +629,8 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         ctx.ui.notify(`Invalid workflow option: ${direct.optionErrors.join("; ")}`, "warning");
         return;
       }
-      const perfRecorder = await createInvocationPerf(direct.options);
+      const directOptions = resolveWorkflowRunOptions(direct.options);
+      const perfRecorder = await createInvocationPerf(directOptions);
       const { discoverWorkflows } = await loadDiscovery();
       const workflows = await discoverWorkflows(EXTENSION_DIR, { refresh: direct.refreshDiscovery, perf: perfRecorder });
       const available = [...workflows.keys()].join(", ") || "(none)";
@@ -550,7 +652,8 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         return;
       }
 
-      await sendWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, invocation.options, perfRecorder);
+      const effectiveOptions = invocation === direct ? directOptions : resolveWorkflowRunOptions(invocation.options);
+      await sendResolvedWorkflowResult(pi, ctx, invocation.name, mod, invocation.args, effectiveOptions, perfRecorder, reviewSessions);
     },
   });
 
@@ -572,6 +675,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       "When using `isolation: \"worktree\"`, `api.agent()` returns `{ result, patch, changed }`; use `.result` for the answer and `.patch` for the isolated diff.",
       "If an inline subagent needs grep/find/code-search helpers, use `tools: [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]` plus `toolHints: [\"search\"]` so installed tools such as ast-grep, mgrep, ffgrep, or fffind are discovered dynamically.",
       "`api.budget` exposes `{ total, spent(), remaining() }` (output tokens). When the run is budgeted, scale fleets from `budget.total` and guard loops with `while (budget.total && budget.remaining() > N) { await api.agent(...) }`; `api.agent()` throws once the ceiling is reached.",
+      ADAPTIVE_WORKFLOW_GUIDANCE,
       "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
     ],
     parameters: Type.Object({
@@ -623,7 +727,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         };
       }
 
-      const runOptions: WorkflowRunOptions = {
+      const runOptions = resolveWorkflowRunOptions({
         inspect: ctx.hasUI,
         concurrency: params.concurrency,
         parallelSubmissionLimit: params.parallelSubmissionLimit,
@@ -631,9 +735,9 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         perf: params.perf,
         resumeFromRunId,
         signal,
-      };
+      });
       const perfRecorder = await createInvocationPerf(runOptions);
-      let mod: WorkflowModule;
+      let mod: LoadedWorkflow;
       let resultName: string;
 
       if (request.kind === "named") {
@@ -660,46 +764,21 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         resultName = mod.meta.name;
       }
 
-      const { runWorkflow } = await loadEngine();
-      let perfSnapshot: PerfSnapshot | undefined;
-      let usageSnapshot: WorkflowUsageSnapshot | undefined;
-      let runMetadata: WorkflowRunMetadata | undefined;
-      let liveInspection: ActiveWorkflowInspection | undefined;
       const resultArgs = params.args ?? "";
-      const result = await runWorkflow(ctx, mod, resultArgs, {
-        ...runOptions,
-        perf: runOptions.perf ?? perfRecorder !== undefined,
-        perfRecorder,
-        resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
-        onProgressSource(source) {
-          if (source) {
-            liveInspection = bindActiveWorkflowInspection(resultName, resultArgs, source);
-            activeWorkflowInspection = liveInspection;
-          } else if (activeWorkflowInspection === liveInspection) {
-            activeWorkflowInspection = undefined;
-            liveInspection = undefined;
-          }
-        },
-        onPerfSnapshot: (snapshot) => {
-          perfSnapshot = snapshot;
-        },
-        onUsageSnapshot: (snapshot) => {
-          usageSnapshot = snapshot;
-        },
-        onRunMetadata: (metadata) => {
-          runMetadata = metadata;
-        },
-        onProgressSnapshot: (snapshot) => {
-          // Record the run so /workflow:inspector can reopen it — tool-invoked (dynamax) runs were
-          // previously uninspectable, unlike the /workflow command path.
-          lastWorkflowInspection = { name: resultName, args: resultArgs, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
-        },
-      });
-      const perf = compactPerfSnapshot(perfSnapshot);
-      const detailLines = formatWorkflowDetailLines({ usage: usageSnapshot, perf, metadata: runMetadata });
+      const execution = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, runOptions, perfRecorder);
+      reviewSessions.remember(ctx, execution, runOptions);
       return {
-        content: [{ type: "text", text: `${summarize(result)}${detailLines.length > 0 ? `\n\n${detailLines.join("\n")}` : ""}` }],
-        details: workflowEnvelope(resultName, result, usageSnapshot, perf, runMetadata),
+        content: [{
+          type: "text",
+          text: formatMessageContent(
+            resultName,
+            execution.envelope.result,
+            execution.envelope.usage,
+            execution.envelope.perf,
+            execution.metadata,
+          ),
+        }],
+        details: execution.envelope,
       };
     },
   });

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

@@ -1,4 +1,5 @@
 import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
 
 export const AdvisorySeveritySchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
   description: "Impact level of an advisory finding.",
@@ -53,6 +54,11 @@ export const AdvisoryReportSchema = Type.Object({
   nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
 });
 
+export const AdvisoryReportWithStatsSchema = Type.Object({
+  ...AdvisoryReportSchema.properties,
+  stats: Type.Optional(Type.Record(Type.String(), Type.Union([Type.String(), Type.Number()]))),
+});
+
 export type AdvisorySeverity = Static<typeof AdvisorySeveritySchema>;
 export type AdvisoryConfidence = Static<typeof AdvisoryConfidenceSchema>;
 export type AdvisoryVerifierVerdict = Static<typeof AdvisoryVerifierVerdictSchema>;
@@ -62,3 +68,8 @@ export type AdvisoryCandidates = Static<typeof AdvisoryCandidatesSchema>;
 export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
 export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
 export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;
+export type AdvisoryReportWithStats = Static<typeof AdvisoryReportWithStatsSchema>;
+
+export function isAdvisoryReport(value: unknown): value is AdvisoryReportWithStats {
+  return Value.Check(AdvisoryReportWithStatsSchema, value);
+}

package/.pi/extensions/pi-workflow-engine/src/agent-attempt.ts

@@ -0,0 +1,145 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import {
+  type AgentExecutionOptions,
+  type AgentRunTags,
+  type RunContext,
+} from "./agent-runner-types.ts";
+import {
+  captureReplayIdentity,
+  captureIsolatedRepositoryAfterSetup,
+  captureSharedRepositoryBeforeSetup,
+  isReplayEnabled,
+  lookupReplayResult,
+  validateReplayEvidence,
+  validateReplayIdentity,
+  type AgentAttemptResult,
+  type AgentReplayEvidence,
+  type AgentReplayPlan,
+} from "./agent-replay.ts";
+import { openAgentSession, promptAgentSession, type AgentSessionHandle } from "./agent-session.ts";
+import {
+  createAgentWorkspace,
+  disposeAgentWorkspace,
+  type AgentWorkspace,
+} from "./agent-workspace.ts";
+import type { AgentResumeBaseContext, AgentResumeContext, RepositoryResumeContext } from "./resume-context.ts";
+import { captureRepositoryMutationGuard } from "./resume-context.ts";
+
+/** Execute one fully bracketed workspace/session attempt. Cleanup always precedes settlement. */
+export async function executeAgentAttempt(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly resumeBaseContext: AgentResumeBaseContext;
+  readonly model: Model<Api> | undefined;
+  readonly replay: AgentReplayPlan;
+  readonly label: string;
+  readonly rowId: number;
+  readonly tags: AgentRunTags;
+}): Promise<AgentAttemptResult> {
+  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, tags } = input;
+  let repositoryBefore: RepositoryResumeContext | undefined;
+  let evidence: AgentReplayEvidence | undefined;
+  if (isReplayEnabled(replay)) {
+    if (replay.kind === "isolated") {
+      const mutationGuard = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
+      if (mutationGuard.kind === "unverifiable") {
+        repositoryBefore = mutationGuard;
+      } else {
+        evidence = { kind: "isolated", mutationGuard: mutationGuard.fingerprint };
+      }
+    } else {
+      repositoryBefore = await captureSharedRepositoryBeforeSetup(rc, prompt, opts, replay);
+      evidence = { kind: "shared" };
+    }
+  }
+  let workspace: AgentWorkspace | undefined;
+  let handle: AgentSessionHandle | undefined;
+
+  try {
+    workspace = await createAgentWorkspace(rc, opts, label);
+    if (replay.kind === "isolated" && evidence?.kind === "isolated") {
+      if (workspace.kind !== "isolated") throw new Error("Isolated replay created a shared workspace.");
+      repositoryBefore = await captureIsolatedRepositoryAfterSetup(rc, prompt, opts, workspace);
+    }
+    handle = await openAgentSession({ rc, prompt, opts, cwd: workspace.cwd, model, label, tags });
+
+    let identity: AgentResumeContext | undefined;
+    if (isReplayEnabled(replay) && repositoryBefore && evidence) {
+      const capture = await captureReplayIdentity({
+        rc,
+        base: resumeBaseContext,
+        repository: repositoryBefore,
+        selectedSkills: handle.selectedSkills,
+        session: handle.session,
+        sessionCwd: workspace.cwd,
+      });
+      if (capture.kind === "unverifiable") {
+        rc.progress.log(`${label}: resume disabled for this call (${capture.reason})`);
+      } else {
+        identity = capture.identity;
+        const cached = await lookupReplayResult({ rc, key: replay.key, identity, opts, workspace });
+        if (cached.hit) {
+          const contract = await validateReplayIdentity({
+            rc,
+            identity,
+            selectedSkills: handle.selectedSkills,
+            session: handle.session,
+            sessionCwd: workspace.cwd,
+            replay,
+            workspace,
+          });
+          const validation = contract.ok
+            ? await validateReplayEvidence(rc, evidence)
+            : contract;
+          if (validation.ok) {
+            return { kind: "cache-hit", result: cached.result, identity, evidence };
+          }
+          rc.progress.log(`${label}: cached result invalidated (${validation.reason})`);
+        } else if (cached.reason) {
+          rc.progress.log(`${label}: cached result invalidated (${cached.reason})`);
+        }
+      }
+    }
+
+    assertWorkflowBudgetAvailable(rc.budget);
+    const rawResult = await promptAgentSession({
+      rc,
+      handle,
+      prompt,
+      opts,
+      label,
+      rowId,
+      tags,
+    });
+    const result = await workspace.wrapResult(rawResult);
+    if (!identity) return { kind: "live-unrecordable", result };
+    if (!isReplayEnabled(replay) || !evidence) throw new Error("Replay identity produced without complete replay evidence.");
+
+    const contract = await validateReplayIdentity({
+      rc,
+      identity,
+      selectedSkills: handle.selectedSkills,
+      session: handle.session,
+      sessionCwd: workspace.cwd,
+      replay,
+      workspace,
+    });
+    const validation = contract.ok
+      ? await validateReplayEvidence(rc, evidence)
+      : contract;
+    if (validation.ok) {
+      return { kind: "live-recordable", result, identity, evidence };
+    }
+    rc.progress.log(`${label}: read-only resume contract was not recorded (${validation.reason})`);
+    return { kind: "live-unrecordable", result };
+  } finally {
+    try {
+      const session = handle?.session;
+      if (session) rc.perf.timeSync("agent.dispose_ms", () => session.dispose(), tags);
+    } finally {
+      await disposeAgentWorkspace(rc, label, workspace);
+    }
+  }
+}