pi-workflow-engine 0.11.0 → 0.12.0

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

@@ -1,14 +1,22 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
 import { bindParallel, bindPipeline, Semaphore } from "./concurrency.ts";
-import { linkAbortSignal, throwIfAborted } from "./cancellation.ts";
+import { WorkflowAgentLimiter } from "./agent-limits.ts";
+import { defaultAgentRetryScheduler, type AgentRetryScheduler } from "./agent-retry.ts";
+import { resolveWorkflowModelProfiles, type ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
+import { abortReason, isWorkflowPauseError, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
 import { createBudget } from "./budget.ts";
 import { runAgent, type AgentExecutionOptions, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSink, type PerfSnapshot } from "./perf.ts";
 import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.ts";
-import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
-import type { AgentOptions, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
+import {
+  resolveWorkflowRunOptions,
+  type ResolvedWorkflowRunOptions,
+} from "./options.ts";
+import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./ui/workflow-viewer-layout.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
 import { runFinalizers } from "./finalizers.ts";
@@ -17,6 +25,17 @@ import {
   captureWorkflowResumeContext,
   type AgentResumeBaseContext,
 } from "./resume-context.ts";
+import {
+  DurableWorkflowRun,
+  ProjectWorkflowRunStore,
+  workflowRunRecordPath,
+  type WorkflowRunStore,
+} from "./workflow-run-store.ts";
+import { createWorkflowRunRecord } from "./workflow-run-record.ts";
+import {
+  createProviderUsageLimitPauseRecord,
+  WorkflowProviderUsageLimitError,
+} from "./provider-usage-limit.ts";
 
 /** The workflow-facing slice of the progress tracker (satisfied by `ProgressTracker`). */
 export interface WorkflowProgress {
@@ -50,6 +69,8 @@ type Outcome<T> =
 
 export interface WorkflowEngineDependencies {
   readonly worktrees?: WorktreeRegistry;
+  readonly retryScheduler?: AgentRetryScheduler;
+  readonly modelProfiles?: ResolvedWorkflowModelProfiles;
 }
 
 /**
@@ -74,25 +95,44 @@ export async function runResolvedWorkflow(
   resolvedOptions: ResolvedWorkflowRunOptions,
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
-  const progress = new ProgressTracker(ctx, mod.meta.name);
+  const runId = resolvedOptions.runId ?? createWorkflowRunId();
+  let durableProgress: DurableWorkflowRun | undefined;
+  const progress = new ProgressTracker(ctx, mod.meta.name, runId, (snapshot) => durableProgress?.updateProgress(snapshot));
   const progressSource = { snapshot: () => progress.snapshot() };
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
-  const usage = createWorkflowUsageRecorder();
+  const usage = createWorkflowUsageRecorder((snapshot) => progress.updateUsage(snapshot));
   const budget = createBudget(resolvedOptions.budget, usage);
-  const runId = resolvedOptions.runId ?? createWorkflowRunId();
   const journalPath = workflowJournalPath(ctx.cwd, runId);
   const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
+  const runStore = new ProjectWorkflowRunStore(ctx.cwd);
+  let persistenceFailureReported = false;
+  const durableRun = new DurableWorkflowRun(
+    runStore,
+    createWorkflowRunRecord({
+      runId,
+      workflow: mod,
+      options: resolvedOptions,
+      progress: progress.snapshot(),
+      argumentsPresent: args.length > 0,
+    }),
+    (error) => {
+      if (persistenceFailureReported) return;
+      persistenceFailureReported = true;
+      process.stderr.write(`[${mod.meta.name}] run persistence failed: ${unknownErrorMessage(error)}\n`);
+    },
+  );
+  durableProgress = durableRun;
   const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
   const workflowOutcome = await captureOutcome(async () => {
     await notifyLifecycleObserver(progress, "progress source callback", () => resolvedOptions.onProgressSource?.(progressSource));
-    if (resolvedOptions.inspect && ctx.hasUI) {
+    if (resolvedOptions.inspect && ctx.hasUI && ctx.mode === "tui") {
       void ctx.ui
         .custom<void>(
           (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
-          { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+          WORKFLOW_VIEWER_OVERLAY_OPTIONS,
         )
         .catch((error: unknown) => {
           try {
@@ -104,15 +144,34 @@ export async function runResolvedWorkflow(
     }
 
     const journal = await createWorkflowJournal({ resumePath, writePath: journalPath });
+    durableRun.transition({ state: "running", progress: progress.snapshot() });
+    await durableRun.flush().catch(() => undefined);
     await notifyLifecycleObserver(progress, "run metadata callback", () =>
-      resolvedOptions.onRunMetadata?.({ runId, resumedFromRunId: resolvedOptions.resumeFromRunId, journalPath }),
+      resolvedOptions.onRunMetadata?.({
+        runId,
+        resumedFromRunId: resolvedOptions.resumeFromRunId,
+        journalPath,
+        recordPath: workflowRunRecordPath(ctx.cwd, runId),
+      }),
     );
     progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
+    const modelProfiles = dependencies.modelProfiles ?? resolveWorkflowModelProfiles({
+      cwd: ctx.cwd,
+      modelRegistry: ctx.modelRegistry,
+      hostModel: ctx.model,
+    });
     const rc: WorkflowRunContext = {
       cwd: ctx.cwd,
       hostModel: ctx.model,
       modelRegistry: ctx.modelRegistry,
       semaphore: new Semaphore(resolvedOptions.concurrency),
+      agentLimiter: new WorkflowAgentLimiter(resolvedOptions.maxAgents),
+      agentTimeoutMs: resolvedOptions.agentTimeoutMs,
+      agentRetries: resolvedOptions.agentRetries,
+      pauseOnProviderUsageLimit: resolvedOptions.background !== undefined,
+      resumeEditedWorkflow: resolvedOptions.resumeEditedWorkflow,
+      retryScheduler: dependencies.retryScheduler ?? defaultAgentRetryScheduler,
+      modelProfiles,
       progress,
       signal: runAbortController.signal,
       perf,
@@ -141,11 +200,69 @@ export async function runResolvedWorkflow(
       perf,
       usage,
       progress,
+      runStore,
       worktrees,
       unlinkSignals: [unlinkContextAbortSignal, unlinkOptionAbortSignal],
     }),
   );
 
+  if (workflowOutcome.ok && finalizationOutcome.ok) {
+    durableRun.transition({
+      state: "completed",
+      progress: progress.snapshot(),
+      usage: usage.snapshot(),
+      result: workflowOutcome.value,
+    });
+  } else if (!workflowOutcome.ok) {
+    const error = finalizationOutcome.ok
+      ? workflowOutcome.error
+      : combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
+    persistTerminalWorkflowError(error);
+  } else if (!finalizationOutcome.ok) {
+    persistTerminalWorkflowError(finalizationOutcome.error);
+  }
+  await durableRun.flush().catch(() => undefined);
+
+  function persistTerminalWorkflowError(error: unknown): void {
+    const pauseError = backgroundPauseError(error, ctx.signal, resolvedOptions.signal);
+    if (pauseError) {
+      if (pauseError instanceof WorkflowProviderUsageLimitError) {
+        if (resolvedOptions.background === undefined) {
+          durableRun.transition({
+            state: "failed",
+            progress: progress.snapshot(),
+            usage: usage.snapshot(),
+            error: pauseError,
+          });
+          return;
+        }
+        const providerPause = createProviderUsageLimitPauseRecord(
+          pauseError,
+          resolvedOptions,
+          mod.source.kind === "file" && args.length === 0,
+        );
+        durableRun.transition({
+          state: "paused",
+          progress: progress.snapshot(),
+          ...providerPause,
+        });
+        return;
+      }
+      durableRun.transition({
+        state: "paused",
+        progress: progress.snapshot(),
+        message: unknownErrorMessage(pauseError),
+      });
+      return;
+    }
+    durableRun.transition({
+      state: ctx.signal?.aborted || resolvedOptions.signal?.aborted ? "stopped" : "failed",
+      progress: progress.snapshot(),
+      usage: usage.snapshot(),
+      error,
+    });
+  }
+
   if (workflowOutcome.ok) {
     if (finalizationOutcome.ok) return workflowOutcome.value;
     throw finalizationOutcome.error;
@@ -154,6 +271,16 @@ export async function runResolvedWorkflow(
   throw combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
 }
 
+function backgroundPauseError(error: unknown, ...signals: Array<AbortSignal | undefined>): unknown {
+  if (isWorkflowPauseError(error)) return error;
+  for (const signal of signals) {
+    if (!signal?.aborted) continue;
+    const reason = abortReason(signal);
+    if (isWorkflowPauseError(reason)) return reason;
+  }
+  return undefined;
+}
+
 async function captureOutcome<T>(operation: () => Promise<T>): Promise<Outcome<T>> {
   try {
     return { ok: true, value: await operation() };
@@ -168,6 +295,7 @@ interface WorkflowFinalizationInput {
   readonly perf: PerfSink;
   readonly usage: WorkflowUsageSink;
   readonly progress: ProgressTracker;
+  readonly runStore: WorkflowRunStore;
   readonly worktrees: WorktreeRegistry;
   readonly unlinkSignals: readonly (() => void)[];
 }
@@ -201,6 +329,7 @@ async function finalizeWorkflowRun(input: WorkflowFinalizationInput): Promise<vo
         run: () => input.worktrees.removeAll(),
       },
       { name: "journal pruning", criticality: "best-effort", run: () => pruneWorkflowJournals(input.cwd) },
+      { name: "run record pruning", criticality: "best-effort", run: () => input.runStore.prune() },
       { name: "progress completion", criticality: "best-effort", run: () => input.progress.done() },
       {
         name: "progress snapshot callback",
@@ -232,6 +361,30 @@ function combinedWorkflowError(workflowError: unknown, finalizationError: unknow
   );
 }
 
+function createWorkflowAgent(
+  rc: WorkflowRunContext,
+  scope: WorkflowScope,
+  mod: LoadedWorkflow,
+  resumeContext: AgentResumeBaseContext,
+): WorkflowApi["agent"] {
+  function agent<S extends TSchema>(
+    prompt: string,
+    opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
+  ): Promise<IsolatedAgentResult<Static<S>>>;
+  function agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
+  function agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
+  function agent(prompt: string, opts?: AgentOptions): Promise<string>;
+  function agent(prompt: string, agentOpts?: AgentOptions): Promise<unknown> {
+    const scopedOptions = scope.agentOptions(agentOpts);
+    const executionOptions: AgentExecutionOptions =
+      scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
+        ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
+        : scopedOptions;
+    return runAgent(rc, prompt, executionOptions, resumeContext);
+  }
+  return agent;
+}
+
 /**
  * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
  * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
@@ -250,14 +403,7 @@ export async function runWorkflowWithContext(
     workflow: await captureWorkflowResumeContext(mod, rc.signal),
   };
 
-  const agent = ((prompt: string, agentOpts?: AgentOptions) => {
-    const scopedOptions = scope.agentOptions(agentOpts);
-    const executionOptions: AgentExecutionOptions =
-      scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
-        ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
-        : scopedOptions;
-    return runAgent(rc, prompt, executionOptions, resumeContext);
-  }) as WorkflowApi["agent"];
+  const agent = createWorkflowAgent(rc, scope, mod, resumeContext);
 
   const workflow: WorkflowApi["workflow"] =
     depth >= 1
@@ -305,7 +451,9 @@ export async function runWorkflowWithContext(
   };
 
   throwIfAborted(rc.signal);
-  return await mod.default(api);
+  const result = await mod.default(api);
+  throwIfAborted(rc.signal);
+  return result;
 }
 
 interface WorkflowScope {

package/.pi/extensions/pi-workflow-engine/src/filesystem-error.ts

@@ -0,0 +1,4 @@
+/** Identify a missing filesystem path reported by Node's filesystem APIs. */
+export function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

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

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { createHash } from "node:crypto";
 import type { LoadedWorkflow, WorkflowApi } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import { parseWorkflowMeta } from "./workflow-module.ts";
 
 /**
@@ -138,8 +139,7 @@ function compileExecutor(defaultExpression: string): InlineWorkflowExecutor {
   try {
     return new AsyncFunction("api", "Type", `"use strict";\nconst workflow = ${defaultExpression};\nreturn await workflow(api);`);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${message}`);
+    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${unknownErrorMessage(error)}`);
   }
 }
 

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

@@ -9,6 +9,7 @@ import {
   isAgentResumeContext,
   resumeContextMismatchReason,
   type AgentResumeContext,
+  type ResumeContextComparisonOptions,
 } from "./resume-context.ts";
 
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
@@ -47,7 +48,7 @@ export type AgentJournalKeyCapture =
   | { readonly kind: "unverifiable"; readonly reason: string };
 
 export interface WorkflowJournal {
-  lookup(key: string, identity: AgentResumeContext): JournalLookup;
+  lookup(key: string, identity: AgentResumeContext, options?: ResumeContextComparisonOptions): JournalLookup;
   record(key: string, result: unknown, identity: AgentResumeContext): Promise<JournalRecordResult>;
 }
 
@@ -60,7 +61,7 @@ export function createWorkflowRunId(): string {
 }
 
 export function workflowJournalPath(cwd: string, runId: string): string {
-  return join(cwd, WORKFLOW_RUNS_DIR, `${validateRunId(runId)}.jsonl`);
+  return join(cwd, WORKFLOW_RUNS_DIR, `${validateWorkflowRunId(runId)}.jsonl`);
 }
 
 export function agentJournalKey(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
@@ -110,6 +111,7 @@ function captureAgentCallHash(
         thinkingLevel: opts.thinkingLevel,
         tools: opts.tools,
         toolHints: opts.toolHints,
+        requireToolHints: opts.requireToolHints === true ? true : undefined,
         skills: opts.skills,
         schema: opts.schema,
         isolation: opts.isolation,
@@ -170,6 +172,8 @@ export async function createWorkflowJournal(options: {
   readonly writePath: string;
 }): Promise<WorkflowJournal> {
   const priorEntries = options.resumePath ? await loadJournalEntries(options.resumePath, { required: true }) : [];
+  await mkdir(dirname(options.writePath), { recursive: true });
+  await appendFile(options.writePath, "", "utf8");
   return createMemoryBackedJournal(priorEntries, options.writePath);
 }
 
@@ -182,7 +186,7 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
   }
 
   return {
-    lookup(key, identity) {
+    lookup(key, identity, options) {
       const entries = priorByKey.get(key);
       if (!entries || entries.length === 0) return { hit: false };
 
@@ -197,10 +201,12 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
             : "journal entry predates replay contract v2",
         };
       }
-      const matches = current.filter((entry) => resumeContextMismatchReason(entry.identity, identity) === undefined);
+      const matches = current.filter(
+        (entry) => resumeContextMismatchReason(entry.identity, identity, options) === undefined,
+      );
       if (matches.length === 1) return { hit: true, value: matches[0]!.result };
       if (matches.length > 1) return { hit: false, reason: "multiple cached entries match this agent call" };
-      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity) };
+      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity, options) };
     },
     async record(key, result, identity) {
       const entry: JournalEntryV2 = { version: 2, key, result, identity };
@@ -248,7 +254,7 @@ export async function pruneWorkflowJournals(cwd: string, keep = WORKFLOW_JOURNAL
   await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
 }
 
-function validateRunId(runId: string): string {
+export function validateWorkflowRunId(runId: string): string {
   const trimmed = runId.trim();
   if (!/^[A-Za-z0-9_.-]+$/.test(trimmed)) {
     throw new Error("Workflow run id must contain only letters, numbers, dots, underscores, or hyphens.");

package/.pi/extensions/pi-workflow-engine/src/model-profile-command.ts

@@ -0,0 +1,167 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+  clearWorkflowModelProfile,
+  isWorkflowModelProfileName,
+  isWorkflowThinkingLevel,
+  resolveWorkflowModelProfiles,
+  setWorkflowModelProfile,
+  workflowModelProfilePaths,
+  WORKFLOW_MODEL_PROFILE_NAMES,
+  WORKFLOW_THINKING_LEVELS,
+  type ResolvedWorkflowModelProfiles,
+  type WorkflowModelProfilePaths,
+  type WorkflowModelProfileName,
+} from "./model-profiles.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
+
+type ConfigScope = "user" | "project";
+
+type WorkflowModelsCommand =
+  | { readonly kind: "status" }
+  | {
+      readonly kind: "set";
+      readonly scope: ConfigScope;
+      readonly profile: WorkflowModelProfileName;
+      readonly model: string;
+      readonly thinkingLevel?: Parameters<typeof setWorkflowModelProfile>[0]["profile"]["thinkingLevel"];
+    }
+  | { readonly kind: "clear"; readonly scope: ConfigScope; readonly profile: WorkflowModelProfileName }
+  | { readonly kind: "error"; readonly message: string };
+
+const USAGE =
+  "Usage: /workflow:models [status | set <small|medium|big> <provider/model> [thinkingLevel] [--user|--project] | clear <small|medium|big> [--user|--project]]";
+const MODEL_COMMAND_ACTIONS = [
+  { value: "status", description: "Show resolved workflow model profiles" },
+  { value: "set", description: "Configure an exact model for a profile" },
+  { value: "clear", description: "Remove a configured profile" },
+] as const;
+const MODEL_COMMAND_SCOPES = [
+  { value: "--user", description: "Write the user-level workflow model config" },
+  { value: "--project", description: "Write the project-level workflow model config" },
+] as const;
+
+export function registerWorkflowModelProfileCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("workflow:models", {
+    description: "Inspect or configure exact small, medium, and big workflow model profiles",
+    getArgumentCompletions: workflowModelProfileArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const command = parseWorkflowModelsCommand(args);
+      if (command.kind === "error") {
+        ctx.ui.notify(`${command.message}\n${USAGE}`, "warning");
+        return;
+      }
+
+      try {
+        const paths = workflowModelProfilePaths(ctx.cwd);
+        if (command.kind === "set") {
+          setWorkflowModelProfile({
+            configPath: paths[command.scope],
+            name: command.profile,
+            profile: {
+              model: command.model,
+              ...(command.thinkingLevel === undefined ? {} : { thinkingLevel: command.thinkingLevel }),
+            },
+            modelRegistry: ctx.modelRegistry,
+          });
+        } else if (command.kind === "clear") {
+          clearWorkflowModelProfile(paths[command.scope], command.profile);
+        }
+
+        const profiles = resolveWorkflowModelProfiles({
+          cwd: ctx.cwd,
+          modelRegistry: ctx.modelRegistry,
+          hostModel: ctx.model,
+          paths,
+        });
+        const prefix = command.kind === "status"
+          ? "Workflow model profiles"
+          : `${command.profile} ${command.kind === "set" ? "updated" : "cleared"} in ${command.scope} config`;
+        ctx.ui.notify(`${prefix}\n${formatWorkflowModelProfiles(profiles, paths)}`, "info");
+      } catch (error) {
+        ctx.ui.notify(unknownErrorMessage(error), "error");
+      }
+    },
+  });
+}
+
+export function workflowModelProfileArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+  const parts = splitArgumentPrefix(argumentPrefix);
+  const completedWithoutScopes = parts.completed.filter((token) => token !== "--user" && token !== "--project");
+  const action = completedWithoutScopes[0];
+  const scopes = parts.completed.some((token) => token === "--user" || token === "--project")
+    ? []
+    : MODEL_COMMAND_SCOPES;
+
+  if (completedWithoutScopes.length === 0) {
+    return completeCurrentArgument(argumentPrefix, MODEL_COMMAND_ACTIONS);
+  }
+  if (action === "status") return null;
+  if (completedWithoutScopes.length === 1) {
+    return completeCurrentArgument(
+      argumentPrefix,
+      WORKFLOW_MODEL_PROFILE_NAMES.map((value) => ({ value, description: `${value} workflow model profile` })),
+    );
+  }
+  if (action === "clear") return completeCurrentArgument(argumentPrefix, scopes);
+  if (action !== "set") return null;
+
+  if (completedWithoutScopes.length === 2) {
+    return null;
+  }
+  if (completedWithoutScopes.length === 3) {
+    return completeCurrentArgument(argumentPrefix, [
+      ...WORKFLOW_THINKING_LEVELS.map((value) => ({ value, description: "Thinking level" })),
+      ...scopes,
+    ]);
+  }
+  return completeCurrentArgument(argumentPrefix, scopes);
+}
+
+export function parseWorkflowModelsCommand(args: string): WorkflowModelsCommand {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === "status")) return { kind: "status" };
+
+  const userScope = tokens.includes("--user");
+  const projectScope = tokens.includes("--project");
+  if (userScope && projectScope) return { kind: "error", message: "Choose either --user or --project, not both." };
+  const scope: ConfigScope = projectScope ? "project" : "user";
+  const positional = tokens.filter((token) => token !== "--user" && token !== "--project");
+  const [action, profile, model, thinkingLevel, ...extra] = positional;
+  if (extra.length > 0) return { kind: "error", message: "Too many /workflow:models arguments." };
+  if (!profile || !isWorkflowModelProfileName(profile)) {
+    return { kind: "error", message: "Profile must be small, medium, or big." };
+  }
+
+  if (action === "clear") {
+    if (model !== undefined) return { kind: "error", message: "The clear action accepts only a profile and optional scope." };
+    return { kind: "clear", scope, profile };
+  }
+  if (action !== "set") return { kind: "error", message: `Unknown /workflow:models action "${action ?? ""}".` };
+  if (!model) return { kind: "error", message: "The set action requires an exact provider/model identity." };
+  if (thinkingLevel !== undefined && !isWorkflowThinkingLevel(thinkingLevel)) {
+    return { kind: "error", message: "Thinking level must be off, minimal, low, medium, high, xhigh, or max." };
+  }
+  return {
+    kind: "set",
+    scope,
+    profile,
+    model,
+    ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+  };
+}
+
+function formatWorkflowModelProfiles(
+  profiles: ResolvedWorkflowModelProfiles,
+  paths: WorkflowModelProfilePaths,
+): string {
+  const lines = WORKFLOW_MODEL_PROFILE_NAMES.map((name) => {
+    const profile = profiles[name];
+    const model = profile.model ? `${profile.model.provider}/${profile.model.id}` : "(no host model)";
+    const thinking = profile.thinkingLevel ?? "host";
+    const source = profile.source === "host" ? "host fallback" : `${profile.source}: ${profile.configPath}`;
+    return `${name}: ${model} · thinking ${thinking} · ${source}`;
+  });
+  return [...lines, `user: ${paths.user}`, `project: ${paths.project} (overrides user)`].join("\n");
+}