@jameslovespancakes/pi-plus 1.0.10 → 1.0.12

package/src/domains/workflows/runtime/workflow-execution.ts

@@ -0,0 +1,121 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedWorkflowRunOptions } from "./options.ts";
+import type { PerfAggregate, PerfSink, PerfSnapshot } from "./perf.ts";
+import type { WorkflowProgressSnapshot } from "./progress-types.ts";
+import type {
+  LoadedWorkflow,
+  WorkflowProgressSource,
+  WorkflowRef,
+  WorkflowRunMetadata,
+} from "./types.ts";
+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;
+  readonly completedAt: number;
+  readonly usage?: WorkflowUsageSnapshot;
+  readonly perf?: WorkflowPerfDetails;
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export type ResolvedWorkflowRunner = (
+  ctx: ExtensionContext,
+  mod: LoadedWorkflow,
+  args: string,
+  options: ResolvedWorkflowRunOptions,
+) => Promise<unknown>;
+
+export interface WorkflowExecutionInput {
+  readonly ctx: ExtensionContext;
+  readonly name: string;
+  readonly mod: LoadedWorkflow;
+  readonly args: string;
+  readonly options: ResolvedWorkflowRunOptions;
+  readonly perfRecorder?: PerfSink;
+  readonly runResolvedWorkflow: ResolvedWorkflowRunner;
+  readonly resolveWorkflow: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
+  readonly onProgressSource?: (source: WorkflowProgressSource | undefined) => void | Promise<void>;
+  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> {
+  let perfSnapshot: PerfSnapshot | undefined;
+  let usageSnapshot: WorkflowUsageSnapshot | undefined;
+  let runMetadata: WorkflowRunMetadata | undefined;
+  const { options } = input;
+  const runOptions: ResolvedWorkflowRunOptions = {
+    ...options,
+    perfRecorder: input.perfRecorder,
+    resolveWorkflow: input.resolveWorkflow,
+    onProgressSource(source) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSource?.(source),
+        () => options.onProgressSource?.(source),
+      );
+    },
+    onPerfSnapshot(snapshot) {
+      perfSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onPerfSnapshot?.(snapshot));
+    },
+    onUsageSnapshot(snapshot) {
+      usageSnapshot = snapshot;
+      return notifyLifecycleObservers(() => options.onUsageSnapshot?.(snapshot));
+    },
+    onRunMetadata(metadata) {
+      runMetadata = metadata;
+      return notifyLifecycleObservers(() => options.onRunMetadata?.(metadata));
+    },
+    onProgressSnapshot(snapshot) {
+      return notifyLifecycleObservers(
+        () => input.onProgressSnapshot?.(snapshot),
+        () => options.onProgressSnapshot?.(snapshot),
+      );
+    },
+  };
+  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,
+    },
+  };
+}
+
+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) {
+    try {
+      await observer();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) throw new AggregateError(failures, "Workflow lifecycle observers failed");
+}

package/src/domains/workflows/runtime/workflow-module.ts

@@ -0,0 +1,75 @@
+import type {
+  LoadedWorkflow,
+  WorkflowMeta,
+  WorkflowModule,
+  WorkflowSourceIdentity,
+} from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+
+type WorkflowMetaCandidate = {
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly phases?: unknown;
+};
+
+type WorkflowModuleCandidate = {
+  readonly meta?: unknown;
+  readonly default?: unknown;
+};
+
+/** 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);
+}
+
+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" };
+
+  const parsedMeta = parseWorkflowMetaObject(meta);
+  if ("reason" in parsedMeta) return parsedMeta;
+  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+
+  return { module: { meta: parsedMeta.meta, default: candidate.default } };
+}
+
+/** Attach engine-owned source provenance after an authored module has been validated. */
+export function loadWorkflow(
+  module: WorkflowModule,
+  source: WorkflowSourceIdentity,
+  isolatedWorktreeBaseline?: WorktreeBaseline,
+): LoadedWorkflow {
+  const loaded = { meta: module.meta, default: module.default, source };
+  return isolatedWorktreeBaseline === undefined
+    ? loaded
+    : { ...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";
+}
+
+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/src/domains/workflows/runtime/workflow-run-background.ts

@@ -0,0 +1,72 @@
+import type { WorkflowBackgroundOrigin } from "./types.ts";
+import type { WorkflowRunRecord } from "./workflow-run-record.ts";
+
+const MAX_BACKGROUND_TEXT = 2_048;
+
+export type WorkflowRunDelivery =
+  | { readonly state: "pending" }
+  | { readonly state: "delivered"; readonly deliveredAt: number }
+  | { readonly state: "unavailable"; readonly attemptedAt: number; readonly message: string };
+
+export interface PersistedWorkflowBackground {
+  readonly origin: WorkflowBackgroundOrigin;
+  readonly delivery: WorkflowRunDelivery;
+}
+
+export function createPersistedWorkflowBackground(
+  origin: WorkflowBackgroundOrigin | undefined,
+): PersistedWorkflowBackground | undefined {
+  if (!origin) return undefined;
+  return {
+    origin: {
+      sessionId: boundedText(origin.sessionId),
+      requestedAt: origin.requestedAt,
+    },
+    delivery: { state: "pending" },
+  };
+}
+
+export function updateWorkflowRunDelivery(
+  record: WorkflowRunRecord,
+  delivery: WorkflowRunDelivery,
+  at = Date.now(),
+): WorkflowRunRecord {
+  if (!record.background) throw new Error(`Workflow run ${record.runId} is not a background run.`);
+  return {
+    ...record,
+    updatedAt: at,
+    background: {
+      origin: record.background.origin,
+      delivery: delivery.state === "unavailable"
+        ? { ...delivery, message: boundedText(delivery.message) }
+        : delivery,
+    },
+  };
+}
+
+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;
+  switch (value.delivery.state) {
+    case "pending":
+      return true;
+    case "delivered":
+      return isFiniteNumber(value.delivery.deliveredAt);
+    case "unavailable":
+      return isFiniteNumber(value.delivery.attemptedAt) && typeof value.delivery.message === "string";
+    default:
+      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);
+}

package/src/domains/workflows/runtime/workflow-run-controller.ts

@@ -0,0 +1,342 @@
+import type {
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { BackgroundWorkflowCoordinator } from "./background-workflows.ts";
+import { backgroundUnavailableResult, startBackgroundWorkflowTool } from "./background-workflow-tool.ts";
+import { validateWorkflowRunId } from "./journal.ts";
+import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
+import type { LoadedWorkflow } from "./types.ts";
+import {
+  availableWorkflowRunActions,
+  canRelaunchWorkflowRun,
+  formatWorkflowRunDetails,
+  formatWorkflowRunHistory,
+  formatWorkflowRunSummary,
+  isWorkflowRunLifecycleAction,
+  parseWorkflowRunsCommand,
+  retainedWorkflowRunOutcome,
+  WORKFLOW_RUN_ACTIONS,
+  WORKFLOW_RUN_HISTORY_LIMIT,
+  type WorkflowRunLifecycleAction,
+} from "./workflow-run-history.ts";
+import { transitionWorkflowRun, type WorkflowRunRecord } from "./workflow-run-record.ts";
+import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { emptyWorkflowUsageTotals } from "./usage.ts";
+import {
+  WorkflowUsageLimitScheduler,
+  type WorkflowUsageLimitSchedulerClock,
+} from "./workflow-usage-limit-scheduler.ts";
+import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./ui/workflow-viewer-layout.ts";
+import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
+
+type WorkflowRunCompletionContext = Pick<ExtensionContext, "cwd" | "sessionManager">;
+
+interface WorkflowRunControllerDependencies {
+  readonly resolveWorkflow: (name: string) => Promise<LoadedWorkflow | undefined>;
+  readonly execute: (
+    ctx: ExtensionContext,
+    name: string,
+    workflow: LoadedWorkflow,
+    options: ResolvedWorkflowRunOptions,
+  ) => Promise<void>;
+  readonly storeForCwd?: (cwd: string) => WorkflowRunStore;
+  readonly schedulerClock?: WorkflowUsageLimitSchedulerClock;
+  readonly log?: (message: string) => void;
+}
+
+export class WorkflowRunController {
+  private readonly storeForCwd: (cwd: string) => WorkflowRunStore;
+  private readonly usageLimitScheduler: WorkflowUsageLimitScheduler;
+  private readonly log: (message: string) => void;
+  private completionContext: WorkflowRunCompletionContext | undefined;
+
+  constructor(
+    private readonly background: BackgroundWorkflowCoordinator,
+    private readonly dependencies: WorkflowRunControllerDependencies,
+  ) {
+    this.storeForCwd = dependencies.storeForCwd ?? ((cwd) => new ProjectWorkflowRunStore(cwd));
+    this.log = dependencies.log ?? ((message) => process.stderr.write(`${message}\n`));
+    this.usageLimitScheduler = new WorkflowUsageLimitScheduler(
+      (ctx, runId, attempt) => this.autoResume(ctx, runId, attempt),
+      dependencies.schedulerClock,
+      dependencies.log,
+    );
+  }
+
+  async runSettled(ctx: ExtensionContext, runId: string): Promise<void> {
+    const record = await this.loadRecord(ctx.cwd, runId);
+    if (record && canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
+  }
+
+  async sessionStarted(ctx: ExtensionContext): Promise<void> {
+    this.completionContext = { cwd: ctx.cwd, sessionManager: ctx.sessionManager };
+    this.usageLimitScheduler.activateSession(ctx);
+    try {
+      for (const record of await this.storeForCwd(ctx.cwd).list()) {
+        if (canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
+      }
+    } catch (error) {
+      this.log(`[workflow] provider-limit recovery could not load run history: ${unknownErrorMessage(error)}`);
+    }
+  }
+
+  sessionShutdown(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    this.usageLimitScheduler.cancelSession(ctx);
+    this.completionContext = undefined;
+  }
+
+  async handleCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+    const command = parseWorkflowRunsCommand(args);
+    if (command.kind === "error") {
+      ctx.ui.notify(command.message, "warning");
+      return;
+    }
+    if (command.kind === "action") {
+      await this.perform(command.action, command.runId, ctx);
+      return;
+    }
+    if (!ctx.hasUI) {
+      const records = await this.listRecent(ctx.cwd);
+      ctx.ui.notify(formatWorkflowRunHistory(records, this.background.activeRunIds(ctx)), "info");
+      return;
+    }
+    await this.openRunSelector(ctx);
+  }
+
+  async inspectStoredRun(ctx: ExtensionContext, runId: string): Promise<boolean> {
+    const record = await this.loadRecord(ctx.cwd, runId);
+    if (!record) return false;
+    await this.inspect(record, ctx);
+    return true;
+  }
+
+  private async openRunSelector(ctx: ExtensionCommandContext): Promise<void> {
+    while (true) {
+      const records = await this.listRecent(ctx.cwd);
+      const active = this.background.activeRunIds(ctx);
+      if (records.length === 0) {
+        ctx.ui.notify(formatWorkflowRunHistory(records, active), "info");
+        return;
+      }
+      const options = records.map((record) =>
+        formatWorkflowRunSummary(record, active.has(record.runId))
+      );
+      const selected = await ctx.ui.select("Workflow Runs", options);
+      if (!selected) return;
+      const selectedIndex = options.indexOf(selected);
+      const selectedRecord = records[selectedIndex];
+      const record = selectedRecord && await this.loadRecord(ctx.cwd, selectedRecord.runId);
+      if (!record) {
+        ctx.ui.notify("The selected workflow run is no longer available.", "warning");
+        continue;
+      }
+      const actions = availableWorkflowRunActions(record, active.has(record.runId));
+      const selectedAction = await ctx.ui.select(
+        `${record.workflow.name} · ${record.runId}`,
+        [...actions],
+      );
+      const action = actions.find((candidate) => candidate === selectedAction);
+      if (!action) continue;
+      if (action === "inspect") await this.inspect(record, ctx);
+      else await this.perform(action, record.runId, ctx);
+    }
+  }
+
+  private async inspect(record: WorkflowRunRecord, ctx: ExtensionContext): Promise<void> {
+    if (!ctx.hasUI || ctx.mode !== "tui") {
+      ctx.ui.notify(
+        formatWorkflowRunDetails(record, this.background.activeRunIds(ctx).has(record.runId)),
+        "info",
+      );
+      return;
+    }
+    await ctx.ui.custom<void>(
+      (tui, theme, _keybindings, done) => new WorkflowInspector(
+        () => record.progress,
+        tui,
+        theme,
+        () => done(undefined),
+        { label: `${record.state.toUpperCase()} outcome`, text: retainedWorkflowRunOutcome(record) },
+      ),
+      WORKFLOW_VIEWER_OVERLAY_OPTIONS,
+    );
+  }
+
+  private async perform(
+    action: WorkflowRunLifecycleAction,
+    runId: string,
+    ctx: ExtensionContext,
+  ): Promise<void> {
+    const record = await this.loadRecord(ctx.cwd, runId);
+    if (!record) {
+      ctx.ui.notify(`Workflow run ${runId} was not found.`, "warning");
+      return;
+    }
+    if (action === "inspect") {
+      await this.inspect(record, ctx);
+      return;
+    }
+    const available = availableWorkflowRunActions(
+      record,
+      this.background.activeRunIds(ctx).has(record.runId),
+    );
+    if (!available.includes(action)) {
+      ctx.ui.notify(`Action ${action} is not available for ${record.state} run ${runId}.`, "warning");
+      return;
+    }
+
+    try {
+      if (action === "stop") {
+        if (record.state === "paused") {
+          this.usageLimitScheduler.cancel(runId);
+          const stopped = transitionWorkflowRun(record, {
+            state: "stopped",
+            progress: record.progress,
+            usage: record.usage ?? record.progress.usage ?? {
+              agents: [],
+              totals: emptyWorkflowUsageTotals(),
+              assistantMessages: 0,
+            },
+            error: new Error("Workflow stopped by user."),
+          });
+          await this.storeForCwd(ctx.cwd).save(stopped);
+          await this.background.durableRunSettled(ctx, runId);
+          ctx.ui.notify(`Workflow run ${runId} is now stopped.`, "info");
+          return;
+        }
+        const stopped = await this.background.stop(ctx, runId);
+        ctx.ui.notify(`Workflow run ${runId} is now ${stopped.state}.`, "info");
+        return;
+      }
+      this.usageLimitScheduler.cancel(runId);
+      const message = await this.relaunch(ctx, record, action);
+      ctx.ui.notify(message, "info");
+    } catch (error) {
+      ctx.ui.notify(`Workflow ${action} failed: ${unknownErrorMessage(error)}`, "error");
+    }
+  }
+
+  private async relaunch(
+    ctx: ExtensionContext,
+    record: WorkflowRunRecord,
+    action: "resume" | "restart",
+  ): Promise<string> {
+    const unavailable = backgroundUnavailableResult(ctx.mode);
+    if (unavailable) {
+      const first = unavailable.content[0];
+      throw new Error(first?.type === "text" ? first.text : "background workflows are unavailable");
+    }
+    const workflow = await this.dependencies.resolveWorkflow(record.workflow.name);
+    if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
+    if (workflow.source.kind !== "file") {
+      throw new Error(`registered workflow ${record.workflow.name} no longer has verifiable file provenance`);
+    }
+    if (
+      action === "resume"
+      && workflow.source.fingerprint !== record.workflow.sourceFingerprint
+    ) {
+      throw new Error("workflow source changed, so journal replay cannot resume safely");
+    }
+    const options = resolveWorkflowRunOptions({
+      inspect: false,
+      perf: record.options.perf,
+      concurrency: record.options.concurrency ?? undefined,
+      parallelSubmissionLimit: record.options.parallelSubmissionLimit ?? undefined,
+      maxAgents: record.options.maxAgents ?? undefined,
+      agentTimeoutMs: record.options.agentTimeoutMs ?? undefined,
+      agentRetries: record.options.agentRetries,
+      autoResumeOnUsageLimit: record.options.autoResumeOnUsageLimit,
+      usageLimitMaxAttempts: record.options.usageLimitMaxAttempts,
+      usageLimitMaxDelayMs: record.options.usageLimitMaxDelayMs,
+      usageLimitAttempt: action === "resume"
+        ? (record.state === "paused" ? record.pause?.attempt : undefined) ?? record.options.usageLimitAttempt
+        : 0,
+      budget: record.options.budget ?? undefined,
+      resultViewer: "skip",
+      resumeFromRunId: action === "resume" ? record.runId : undefined,
+    });
+    const result = await startBackgroundWorkflowTool({
+      coordinator: this.background,
+      ctx,
+      name: workflow.meta.name,
+      options,
+      execute: (backgroundCtx, backgroundOptions) =>
+        this.dependencies.execute(backgroundCtx, workflow.meta.name, workflow, backgroundOptions),
+    });
+    const first = result.content[0];
+    const message = first?.type === "text" ? first.text : `Workflow ${action} started.`;
+    if (typeof result.details.error === "string") throw new Error(message);
+    return message;
+  }
+
+  private async autoResume(ctx: ExtensionContext, runId: string, attempt: number): Promise<void> {
+    const record = await this.loadRecord(ctx.cwd, runId);
+    if (
+      record?.state !== "paused"
+      || record.pause?.kind !== "provider_usage_limit"
+      || !record.pause.autoResume
+      || record.pause.attempt !== attempt
+      || !canRelaunchWorkflowRun(record)
+    ) {
+      return;
+    }
+    const message = await this.relaunch(ctx, record, "resume");
+    ctx.ui.notify(message, "info");
+  }
+
+  private async loadRecord(cwd: string, runId: string): Promise<WorkflowRunRecord | undefined> {
+    try {
+      validateWorkflowRunId(runId);
+    } catch {
+      return undefined;
+    }
+    return await this.storeForCwd(cwd).load(runId);
+  }
+
+  private async listRecent(cwd: string): Promise<WorkflowRunRecord[]> {
+    const records = await this.storeForCwd(cwd).list();
+    return records
+      .sort((left, right) => right.createdAt - left.createdAt)
+      .slice(0, WORKFLOW_RUN_HISTORY_LIMIT);
+  }
+
+  async argumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+    const ctx = this.completionContext;
+    const parts = splitArgumentPrefix(argumentPrefix);
+    if (parts.completed.length === 0) {
+      return completeCurrentArgument(argumentPrefix, WORKFLOW_RUN_ACTIONS);
+    }
+    if (parts.completed.length !== 1 || !ctx) return null;
+    const action = parts.completed[0];
+    if (!action || !isWorkflowRunLifecycleAction(action)) return null;
+    const records = await this.listRecent(ctx.cwd);
+    const active = this.background.activeRunIds(ctx);
+    return completeCurrentArgument(
+      argumentPrefix,
+      records
+        .filter((record) => availableWorkflowRunActions(record, active.has(record.runId)).includes(action))
+        .map((record) => ({
+          value: record.runId,
+          description: `${record.state} · ${record.workflow.name}`,
+        })),
+    );
+  }
+
+  async inspectorArgumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+    const ctx = this.completionContext;
+    const parts = splitArgumentPrefix(argumentPrefix);
+    if (parts.completed.length > 0) return null;
+    const records = ctx ? await this.listRecent(ctx.cwd) : [];
+    return completeCurrentArgument(argumentPrefix, [
+      { value: "last", description: "Inspect the current or most recent in-session workflow" },
+      ...records.map((record) => ({
+        value: record.runId,
+        description: `${record.state} · ${record.workflow.name}`,
+      })),
+    ]);
+  }
+}