pi-workflow-engine 0.10.3 → 0.12.0

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

@@ -0,0 +1,138 @@
+export type IdentityCanonicalization =
+  | { readonly kind: "verified"; readonly value: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface IdentityCanonicalizationOptions {
+  readonly maxBytes?: number;
+  readonly maxDepth?: number;
+  readonly maxNodes?: number;
+}
+
+const DEFAULT_MAX_BYTES = 1 << 20;
+const DEFAULT_MAX_DEPTH = 64;
+const DEFAULT_MAX_NODES = 16_384;
+
+/**
+ * Produce a deterministic, bounded identity for JSON-like data.
+ *
+ * Replay inputs are not trusted: schemas and tool metadata can contain cycles,
+ * accessors, proxies, or values JSON cannot represent. Those inputs disable
+ * replay instead of throwing or being silently collapsed to the same key.
+ */
+export function canonicalizeIdentity(
+  value: unknown,
+  options: IdentityCanonicalizationOptions = {},
+): IdentityCanonicalization {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+  const active = new WeakSet<object>();
+  const chunks: string[] = [];
+  let bytes = 0;
+  let nodes = 0;
+
+  const append = (chunk: string): void => {
+    bytes += Buffer.byteLength(chunk);
+    if (bytes > maxBytes) throw new IdentityCanonicalizationError(`identity exceeded ${maxBytes} bytes`);
+    chunks.push(chunk);
+  };
+
+  const visit = (current: unknown, depth: number): void => {
+    nodes += 1;
+    if (nodes > maxNodes) throw new IdentityCanonicalizationError(`identity exceeded ${maxNodes} values`);
+    if (depth > maxDepth) throw new IdentityCanonicalizationError(`identity exceeded ${maxDepth} levels`);
+
+    if (current === null) {
+      append("n;");
+      return;
+    }
+    switch (typeof current) {
+      case "undefined":
+        append("u;");
+        return;
+      case "boolean":
+        append(current ? "b1;" : "b0;");
+        return;
+      case "number":
+        if (!Number.isFinite(current)) throw new IdentityCanonicalizationError("identity contains a non-finite number");
+        append(`d${Object.is(current, -0) ? "-0" : String(current)};`);
+        return;
+      case "string":
+        append(`s${Buffer.byteLength(current)}:${current};`);
+        return;
+      case "bigint":
+      case "function":
+      case "symbol":
+        throw new IdentityCanonicalizationError(`identity contains unsupported ${typeof current} data`);
+      case "object":
+        break;
+    }
+
+    if (active.has(current)) throw new IdentityCanonicalizationError("identity contains a cycle");
+    active.add(current);
+    try {
+      const prototype = Object.getPrototypeOf(current);
+      if (Array.isArray(current)) {
+        if (prototype !== Array.prototype) throw new IdentityCanonicalizationError("identity contains an array with a custom prototype");
+        const descriptors = Object.getOwnPropertyDescriptors(current);
+        const ownKeys = Reflect.ownKeys(current);
+        if (ownKeys.some((key) => typeof key === "symbol")) {
+          throw new IdentityCanonicalizationError("identity contains symbol keys");
+        }
+        if (ownKeys.some((key) => typeof key === "string" && key !== "length" && !isArrayIndex(key, current.length))) {
+          throw new IdentityCanonicalizationError("identity array contains custom properties");
+        }
+        append(`a${current.length}[`);
+        for (let index = 0; index < current.length; index++) {
+          const descriptor = descriptors[String(index)];
+          if (!descriptor) {
+            append("h;");
+            continue;
+          }
+          if (!("value" in descriptor)) throw new IdentityCanonicalizationError("identity contains an array accessor");
+          visit(descriptor.value, depth + 1);
+        }
+        append("];");
+        return;
+      }
+
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new IdentityCanonicalizationError("identity contains an object with a custom prototype");
+      }
+      const descriptors = Object.getOwnPropertyDescriptors(current);
+      const ownKeys = Reflect.ownKeys(current);
+      if (ownKeys.some((key) => typeof key === "symbol")) {
+        throw new IdentityCanonicalizationError("identity contains symbol keys");
+      }
+      const keys = Object.keys(descriptors).sort();
+      append(`o${keys.length}{`);
+      for (const key of keys) {
+        const descriptor = descriptors[key]!;
+        if (!("value" in descriptor)) throw new IdentityCanonicalizationError(`identity property ${key} is an accessor`);
+        append(`k${Buffer.byteLength(key)}:${key};`);
+        append(`p${descriptor.enumerable ? 1 : 0}${descriptor.configurable ? 1 : 0}${descriptor.writable ? 1 : 0};`);
+        visit(descriptor.value, depth + 1);
+      }
+      append("};");
+    } finally {
+      active.delete(current);
+    }
+  };
+
+  try {
+    visit(value, 0);
+    return { kind: "verified", value: chunks.join("") };
+  } catch (error) {
+    return {
+      kind: "unverifiable",
+      reason: error instanceof IdentityCanonicalizationError ? error.message : "identity inspection failed",
+    };
+  }
+}
+
+class IdentityCanonicalizationError extends Error {}
+
+function isArrayIndex(key: string, length: number): boolean {
+  const index = Number(key);
+  return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+}

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

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+
+export function hashIdentity(value: unknown): string {
+  const canonical = canonicalizeIdentity(value);
+  if (canonical.kind === "unverifiable") throw new Error(canonical.reason);
+  return `sha256:${createHash("sha256").update(canonical.value).digest("hex")}`;
+}
+
+export function inspectableFunctionSource(value: unknown, label: string): string {
+  if (typeof value !== "function") throw new Error(`${label} is not a function`);
+  const source = Function.prototype.toString.call(value);
+  if (source.length === 0 || source.includes("[native code]")) throw new Error(`${label} has no inspectable source`);
+  return source;
+}

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

@@ -1,5 +1,7 @@
 import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta, WorkflowModule } from "./types.ts";
+import { createHash } from "node:crypto";
+import type { LoadedWorkflow, WorkflowApi } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import { parseWorkflowMeta } from "./workflow-module.ts";
 
 /**
@@ -28,7 +30,7 @@ type AsyncFunctionConstructor = new (...args: string[]) => InlineWorkflowExecuto
 
 const AsyncFunction = Object.getPrototypeOf(async function inlineWorkflowCompilerSentinel() {}).constructor as AsyncFunctionConstructor;
 
-export function compileInlineWorkflow(source: string): WorkflowModule {
+export function compileInlineWorkflow(source: string): LoadedWorkflow {
   rejectForbiddenModuleSyntax(source);
   const metaLiteral = extractMetaLiteral(source);
   const parsedMeta = parseWorkflowMeta(metaLiteral.value);
@@ -36,7 +38,11 @@ export function compileInlineWorkflow(source: string): WorkflowModule {
 
   const defaultExpression = extractDefaultWorkflowExpression(source, metaLiteral.endOffset);
   const executor = compileExecutor(defaultExpression);
-  return { meta: parsedMeta.meta, default: (api) => executor(api, Type) };
+  return {
+    meta: parsedMeta.meta,
+    default: (api) => executor(api, Type),
+    source: { kind: "fingerprint", fingerprint: createHash("sha256").update(source).digest("hex") },
+  };
 }
 
 export function extractMetaLiteral(source: string): InlineMetaLiteral {
@@ -133,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

@@ -2,21 +2,54 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentOptions } from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  isAgentResumeContext,
+  resumeContextMismatchReason,
+  type AgentResumeContext,
+  type ResumeContextComparisonOptions,
+} from "./resume-context.ts";
 
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
 export const WORKFLOW_JOURNAL_KEEP = 50;
 
-export interface JournalEntry {
+export interface JournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: AgentResumeContext;
+}
+
+/** Parsed so journals written before effective-session identity can fail closed without aborting resume. */
+export interface LegacyJournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: unknown;
+}
+
+/** Parsed only so resume can explain why an older entry is not replayed. */
+export interface LegacyJournalEntryV1 {
+  readonly version?: 1;
   readonly key: string;
   readonly value: unknown;
+  readonly context?: unknown;
 }
 
-export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false };
+export type JournalEntry = LegacyJournalEntryV2 | LegacyJournalEntryV1;
+
+export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false; readonly reason?: string };
 export type JournalRecordResult = { readonly ok: true } | { readonly ok: false; readonly error: string };
 
+export type AgentJournalKeyCapture =
+  | { readonly kind: "verified"; readonly key: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
 export interface WorkflowJournal {
-  lookup(key: string): JournalLookup;
-  record(key: string, value: unknown): Promise<JournalRecordResult>;
+  lookup(key: string, identity: AgentResumeContext, options?: ResumeContextComparisonOptions): JournalLookup;
+  record(key: string, result: unknown, identity: AgentResumeContext): Promise<JournalRecordResult>;
 }
 
 export class WorkflowJournalLoadError extends Error {
@@ -28,31 +61,75 @@ 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 {
+  const capture = captureAgentJournalKey(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified" ? capture.key : `agent:unverifiable:${randomUUID()}`;
 }
 
-export function agentJournalKey(prompt: string, opts: AgentOptions = {}): string {
-  const behaviorHash = hashAgentCall(prompt, opts);
-  const cacheKey = opts.cacheKey?.trim();
-  if (!cacheKey) return `agent:${behaviorHash}`;
+export function hashAgentCall(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
+  const capture = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified"
+    ? capture.hash
+    : createHash("sha256").update(`unverifiable:${randomUUID()}`).digest("hex");
+}
+
+/** Capture a replay key without allowing hostile or oversized schemas to escape as exceptions. */
+export function captureAgentJournalKey(
+  prompt: string,
+  opts: AgentOptions = {},
+  worktreeBaseline?: WorktreeBaseline,
+): AgentJournalKeyCapture {
+  const behavior = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  if (behavior.kind === "unverifiable") return behavior;
+  let cacheKey: string | undefined;
+  try {
+    cacheKey = opts.cacheKey?.trim();
+  } catch {
+    return { kind: "unverifiable", reason: "agent cache key could not be inspected" };
+  }
+  if (!cacheKey) return { kind: "verified", key: `agent:${behavior.hash}` };
   const cacheKeyHash = createHash("sha256").update(cacheKey).digest("hex");
-  return `agent:${cacheKeyHash}:${behaviorHash}`;
-}
-
-export function hashAgentCall(prompt: string, opts: AgentOptions = {}): string {
-  const behavior = {
-    prompt,
-    opts: {
-      model: opts.model,
-      thinkingLevel: opts.thinkingLevel,
-      tools: sortedArray(opts.tools),
-      toolHints: sortedArray(opts.toolHints),
-      skills: sortedArray(opts.skills),
-      schema: opts.schema,
-      isolation: opts.isolation,
-    },
-  };
-  return createHash("sha256").update(stableStringify(behavior)).digest("hex");
+  return { kind: "verified", key: `agent:${cacheKeyHash}:${behavior.hash}` };
+}
+
+type AgentCallHashCapture =
+  | { readonly kind: "verified"; readonly hash: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+function captureAgentCallHash(
+  prompt: string,
+  opts: AgentOptions,
+  worktreeBaseline: WorktreeBaseline | undefined,
+): AgentCallHashCapture {
+  try {
+    const behavior = {
+      prompt,
+      opts: {
+        thinkingLevel: opts.thinkingLevel,
+        tools: opts.tools,
+        toolHints: opts.toolHints,
+        requireToolHints: opts.requireToolHints === true ? true : undefined,
+        skills: opts.skills,
+        schema: opts.schema,
+        isolation: opts.isolation,
+        worktreeBaseline: worktreeBaseline
+          ? {
+              ref: worktreeBaseline.ref,
+              patchFingerprint: createHash("sha256").update(worktreeBaseline.patch ?? "").digest("hex"),
+            }
+          : undefined,
+      },
+    };
+    const canonical = canonicalizeIdentity(behavior);
+    return canonical.kind === "verified"
+      ? { kind: "verified", hash: createHash("sha256").update(canonical.value).digest("hex") }
+      : canonical;
+  } catch {
+    return { kind: "unverifiable", reason: "agent replay inputs could not be inspected" };
+  }
 }
 
 export async function loadJournalEntries(path: string, options: { readonly required?: boolean } = {}): Promise<JournalEntry[]> {
@@ -61,7 +138,7 @@ export async function loadJournalEntries(path: string, options: { readonly requi
     content = await readFile(path, "utf8");
   } catch (error) {
     if (options.required) {
-      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${formatError(error)}`);
+      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${unknownErrorMessage(error)}`);
     }
     return [];
   }
@@ -95,29 +172,50 @@ 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);
 }
 
 export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[] = [], writePath?: string): WorkflowJournal {
-  const priorByKey = new Map<string, JournalEntry | "ambiguous">();
+  const priorByKey = new Map<string, JournalEntry[]>();
   for (const entry of priorEntries) {
-    priorByKey.set(entry.key, priorByKey.has(entry.key) ? "ambiguous" : entry);
+    const entries = priorByKey.get(entry.key) ?? [];
+    entries.push(entry);
+    priorByKey.set(entry.key, entries);
   }
 
   return {
-    lookup(key) {
-      const entry = priorByKey.get(key);
-      if (!entry || entry === "ambiguous") return { hit: false };
-      return { hit: true, value: entry.value };
+    lookup(key, identity, options) {
+      const entries = priorByKey.get(key);
+      if (!entries || entries.length === 0) return { hit: false };
+
+      const current = entries.filter(
+        (entry): entry is JournalEntryV2 => entry.version === 2 && isAgentResumeContext(entry.identity),
+      );
+      if (current.length === 0) {
+        return {
+          hit: false,
+          reason: entries.some((entry) => entry.version === 2)
+            ? "journal entry predates effective replay identity"
+            : "journal entry predates replay contract v2",
+        };
+      }
+      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, options) };
     },
-    async record(key, value) {
-      const entry = { key, value };
+    async record(key, result, identity) {
+      const entry: JournalEntryV2 = { version: 2, key, result, identity };
       if (writePath) {
         try {
           await mkdir(dirname(writePath), { recursive: true });
           await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
         } catch (error) {
-          return { ok: false, error: formatError(error) };
+      return { ok: false, error: unknownErrorMessage(error) };
         }
       }
       return { ok: true };
@@ -156,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.");
@@ -164,37 +262,29 @@ function validateRunId(runId: string): string {
   return trimmed;
 }
 
-function sortedArray(values: readonly string[] | undefined): readonly string[] | undefined {
-  return values ? [...values].sort() : undefined;
-}
-
-function stableStringify(value: unknown): string {
-  return JSON.stringify(normalizeStable(value));
-}
-
-function normalizeStable(value: unknown): unknown {
-  if (value === undefined) return undefined;
-  if (value === null) return null;
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
-  if (Array.isArray(value)) return value.map(normalizeStable);
-  if (typeof value === "object") {
-    const record = value as Record<string, unknown>;
-    const out: Record<string, unknown> = {};
-    for (const key of Object.keys(record).sort()) {
-      const normalized = normalizeStable(record[key]);
-      if (normalized !== undefined) out[key] = normalized;
-    }
-    return out;
-  }
-  return String(value);
-}
-
 function isJournalEntry(value: unknown): value is JournalEntry {
   if (typeof value !== "object" || value === null) return false;
-  const entry = value as { readonly key?: unknown; readonly value?: unknown };
-  return typeof entry.key === "string" && "value" in entry;
+  const entry = value as {
+    readonly version?: unknown;
+    readonly key?: unknown;
+    readonly result?: unknown;
+    readonly identity?: unknown;
+    readonly value?: unknown;
+    readonly context?: unknown;
+  };
+  if (entry.version === 2) {
+    return typeof entry.key === "string" && "result" in entry && "identity" in entry;
+  }
+  return (
+    (entry.version === undefined || entry.version === 1) &&
+    typeof entry.key === "string" &&
+    "value" in entry &&
+    (entry.context === undefined || isLegacyAgentResumeContext(entry.context))
+  );
 }
 
-function formatError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function isLegacyAgentResumeContext(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const context = value as { readonly repository?: unknown; readonly workflow?: unknown; readonly model?: unknown };
+  return "repository" in context && "workflow" in context && "model" in context;
 }

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");
+}