pi-workflow-engine 0.13.0 → 1.1.0

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

@@ -62,12 +62,13 @@ export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown
 }
 
 export function extractSkillSelectorsFromText(text: string): string[] {
-  const selectors: string[] = [];
-  collectPatternMatches(text, SLASH_SKILL_PATTERN, selectors, 1);
-  collectListPatternMatches(text, SKILLS_FIELD_PATTERN, selectors);
-  collectListPatternMatches(text, VERB_SKILL_LIST_PATTERN, selectors);
-  collectPatternMatches(text, VERB_NAMED_SKILL_PATTERN, selectors, 2);
-  return uniqueSelectors(selectors);
+  const selectors = [
+    ...Array.from(text.matchAll(SLASH_SKILL_PATTERN), (match) => match[1] ?? ""),
+    ...[...text.matchAll(SKILLS_FIELD_PATTERN), ...text.matchAll(VERB_SKILL_LIST_PATTERN)]
+      .flatMap((match) => parseSkillList(match[1] ?? "")),
+    ...Array.from(text.matchAll(VERB_NAMED_SKILL_PATTERN), (match) => match[2] ?? ""),
+  ].map(normalizeSkillSelector);
+  return [...new Set(selectors.filter((value) => value && !isGenericSkillWord(value)))];
 }
 
 export function normalizeSkillSelector(value: string): string {
@@ -179,23 +180,6 @@ export async function captureAgentSkillIdentities(
   return { kind: "verified", skills: identities };
 }
 
-function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {
-  pattern.lastIndex = 0;
-  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
-    const value = match[captureIndex];
-    if (value !== undefined) selectors.push(value);
-  }
-}
-
-function collectListPatternMatches(text: string, pattern: RegExp, selectors: string[]): void {
-  pattern.lastIndex = 0;
-  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
-    const value = match[1];
-    if (value === undefined) continue;
-    selectors.push(...parseSkillList(value));
-  }
-}
-
 function parseSkillList(fragment: string): string[] {
   const scoped = fragment.replace(PURPOSE_BOUNDARY_PATTERN, "");
   return scoped
@@ -208,9 +192,7 @@ function normalizeExplicitSkillSelectors(value: unknown): string[] {
   if (!Array.isArray(value)) {
     throw new Error("Invalid subagent skills option: expected an array of skill names.");
   }
-  const seen = new Set<string>();
-  const result: string[] = [];
-  for (const item of value) {
+  const selectors = value.map((item: unknown) => {
     if (typeof item !== "string") {
       throw new Error("Invalid subagent skills option: every skill name must be a string.");
     }
@@ -218,11 +200,9 @@ function normalizeExplicitSkillSelectors(value: unknown): string[] {
     if (!normalized || isGenericSkillWord(normalized)) {
       throw new Error(`Invalid subagent skills option: \"${item}\" is not a valid skill name.`);
     }
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    result.push(normalized);
-  }
-  return result;
+    return normalized;
+  });
+  return [...new Set(selectors)];
 }
 
 function logSkillDiagnostics(log: ((message: string) => void) | undefined, diagnostics: readonly ResourceDiagnostic[], requested: boolean): void {
@@ -233,18 +213,6 @@ function logSkillDiagnostics(log: ((message: string) => void) | undefined, diagn
   }
 }
 
-function uniqueSelectors(values: Iterable<string>): string[] {
-  const seen = new Set<string>();
-  const result: string[] = [];
-  for (const value of values) {
-    const normalized = normalizeSkillSelector(value);
-    if (!normalized || isGenericSkillWord(normalized) || seen.has(normalized)) continue;
-    seen.add(normalized);
-    result.push(normalized);
-  }
-  return result;
-}
-
 function isGenericSkillWord(value: string): boolean {
   return value === "skill" || value === "skills" || value === "the" || value === "this" || value === "these" || value === "that";
 }

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

@@ -1,5 +1,4 @@
 import type { AgentExecutionOptions, AgentProgress } from "./agent-runner-types.ts";
-import { unknownErrorMessage } from "./unknown-error.ts";
 import type { WorktreeRegistry } from "./worktree.ts";
 
 interface AgentWorkspaceBase {
@@ -45,7 +44,7 @@ export async function createAgentWorkspace(
 
   const probe = await rc.worktrees.probe(rc.signal);
   if (!probe.ok) {
-    throw new Error(`Failed to check git worktree availability for isolated agent: ${probe.error ?? "unknown git error"}`);
+    throw new Error(`Failed to check git worktree availability for isolated agent: ${probe.error}`);
   }
   if (!probe.inside) {
     throw new Error("Agent requested worktree isolation, but the workflow cwd is not inside a git work tree.");
@@ -59,11 +58,11 @@ export async function createAgentWorkspace(
       if (opts.candidatePatch.baselineOid !== added.baselineOid) throw new Error("Candidate baseline differs from evaluator baseline");
       if (opts.candidatePatch.patch.trim()) {
         const applied = await rc.worktrees.applyPatch(worktreePath, opts.candidatePatch.patch, rc.signal);
-        if (!applied.ok) throw new Error(`Candidate patch could not be applied: ${applied.error ?? applied.stderr}`);
+        if (!applied.ok) throw new Error(`Candidate patch could not be applied: ${applied.error}`);
       }
     } catch (error) {
       const removed = await rc.worktrees.remove(worktreePath);
-      if (!removed.ok) rc.progress.log(`${label}: evaluator setup cleanup failed: ${removed.error ?? removed.stderr}`);
+      if (!removed.ok) rc.progress.log(`${label}: evaluator setup cleanup failed: ${removed.error}`);
       throw error;
     }
   }
@@ -82,22 +81,9 @@ export async function createAgentWorkspace(
       const removed = await rc.worktrees.remove(worktreePath);
       if (!removed.ok) {
         rc.progress.log(
-          `${label}: failed to remove isolated worktree (${removed.error ?? (removed.stderr.trim() || "unknown error")})`,
+          `${label}: failed to remove isolated worktree (${removed.error})`,
         );
       }
     },
   };
 }
-
-export async function disposeAgentWorkspace(
-  rc: Pick<AgentWorkspaceContext, "progress">,
-  label: string,
-  workspace: AgentWorkspace | undefined,
-): Promise<void> {
-  if (!workspace) return;
-  try {
-    await workspace.dispose();
-  } catch (error) {
-    rc.progress.log(`${label}: failed to dispose isolated workspace (${unknownErrorMessage(error)})`);
-  }
-}

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

@@ -7,6 +7,7 @@ import { unknownErrorMessage } from "./unknown-error.ts";
 export interface BackgroundWorkflowToolResult {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
   readonly details: Readonly<Record<string, unknown>>;
+  readonly isError?: true;
 }
 
 export interface BackgroundWorkflowToolStartInput {
@@ -25,6 +26,7 @@ export function backgroundUnavailableResult(mode: ExtensionContext["mode"]): Bac
       text: `Background workflows are unavailable in ${mode} mode because pi exits after the prompt. Run synchronously or use TUI/RPC mode.`,
     }],
     details: { error: "background_unavailable", mode },
+    isError: true,
   };
 }
 
@@ -63,6 +65,7 @@ export async function startBackgroundWorkflowTool(
     return {
       content: [{ type: "text", text: `Background workflow did not start: ${message}` }],
       details: { error: "background_start_failed", message, runId },
+      isError: true,
     };
   }
   return {

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

@@ -1,18 +1,20 @@
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
+import { isRecord } from "./guards.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
+  stopWorkflowRunRecord,
   transitionWorkflowRun,
   type WorkflowRunRecord,
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
-import { updateWorkflowRunDelivery } from "./workflow-run-background.ts";
+import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
 import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { truncateText } from "./text.ts";
+import { workflowResultSummary } from "./workflow-execution.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
-import { emptyWorkflowUsageTotals } from "./usage.ts";
 
 const BACKGROUND_DELIVERY_CUSTOM_TYPE = "workflow-result";
-const BACKGROUND_WIDGET_KEY = "workflow-background";
 const SHUTDOWN_WAIT_MS = 5_000;
 const SUMMARY_LIMIT = 500;
 
@@ -25,7 +27,10 @@ export interface BackgroundWorkflowStartInput {
 
 export interface BackgroundWorkflowResultDetails {
   readonly name: string;
-  readonly result: { readonly summary: string };
+  /** The retained result of a completed run, so the delivery renders like a foreground result; else `{ summary }`. */
+  readonly result: unknown;
+  readonly summary: string;
+  readonly startedAt?: number;
   readonly completedAt: number;
   readonly usage: WorkflowRunRecord["usage"];
   readonly runId: string;
@@ -56,7 +61,7 @@ type BackgroundWorkflowSettledListener = (ctx: ExtensionContext, runId: string)
 /** Owns background runs for one extension instance and routes their durable completion delivery. */
 export class BackgroundWorkflowCoordinator {
   private readonly active = new Map<string, ActiveBackgroundRun>();
-  private readonly settledListeners = new Set<BackgroundWorkflowSettledListener>();
+  private settledListener: BackgroundWorkflowSettledListener | undefined;
   private readonly pendingDelivery = new Map<string, Set<string>>();
   private readonly shuttingDown = new Set<string>();
   private readonly storeForCwd: (cwd: string) => WorkflowRunStore;
@@ -82,13 +87,8 @@ export class BackgroundWorkflowCoordinator {
     let accepted = false;
     let deliveryScheduled = false;
     let settled = false;
-    let startedSignalled = false;
-    let resolveStarted: (() => void) | undefined;
-    let rejectStarted: ((error: unknown) => void) | undefined;
-    const started = new Promise<void>((resolve, reject) => {
-      resolveStarted = resolve;
-      rejectStarted = reject;
-    });
+    // Settles once: a rejection after the run published its metadata is ignored.
+    const started = Promise.withResolvers<void>();
 
     const scheduleDelivery = (): void => {
       if (deliveryScheduled || !accepted || !settled || this.shuttingDown.has(sessionId)) return;
@@ -100,18 +100,13 @@ export class BackgroundWorkflowCoordinator {
 
     const settledPromise = (async () => {
       try {
-        await input.run(controller.signal, () => {
-          if (startedSignalled) return;
-          startedSignalled = true;
-          resolveStarted?.();
-        });
-        if (!startedSignalled) rejectStarted?.(new Error("Background workflow ended before publishing run metadata."));
+        await input.run(controller.signal, () => started.resolve());
+        started.reject(new Error("Background workflow ended before publishing run metadata."));
       } catch (error) {
-        if (!startedSignalled) rejectStarted?.(error);
+        started.reject(error);
       } finally {
         settled = true;
         this.active.delete(input.runId);
-        this.updateBackgroundSurface(input.ctx);
         await this.notifyRunSettled(input.ctx, input.runId);
         scheduleDelivery();
       }
@@ -124,7 +119,7 @@ export class BackgroundWorkflowCoordinator {
       isSettled: () => settled,
     });
 
-    await started;
+    await started.promise;
     const record = await this.storeForCwd(input.ctx.cwd).load(input.runId);
     if (record?.state !== "running" || !record.background || record.background.origin.sessionId !== sessionId) {
       controller.abort(new WorkflowAbortError("Background workflow could not persist its origin metadata."));
@@ -132,7 +127,6 @@ export class BackgroundWorkflowCoordinator {
     }
 
     accepted = true;
-    this.updateBackgroundSurface(input.ctx);
     scheduleDelivery();
   }
 
@@ -145,9 +139,8 @@ export class BackgroundWorkflowCoordinator {
     );
   }
 
-  onRunSettled(listener: BackgroundWorkflowSettledListener): () => void {
-    this.settledListeners.add(listener);
-    return () => this.settledListeners.delete(listener);
+  onRunSettled(listener: BackgroundWorkflowSettledListener): void {
+    this.settledListener = listener;
   }
 
   async stop(ctx: ExtensionContext, runId: string): Promise<WorkflowRunRecord> {
@@ -243,7 +236,6 @@ export class BackgroundWorkflowCoordinator {
         this.log(`[workflow:${runId}] failed to force paused state during shutdown: ${unknownErrorMessage(error)}`);
       }
     }
-    if (ctx.hasUI) ctx.ui.setWidget(BACKGROUND_WIDGET_KEY, undefined);
   }
 
   private async queueOrDeliver(ctx: ExtensionContext, runId: string): Promise<void> {
@@ -262,12 +254,10 @@ export class BackgroundWorkflowCoordinator {
   }
 
   private async notifyRunSettled(ctx: ExtensionContext, runId: string): Promise<void> {
-    for (const listener of this.settledListeners) {
-      try {
-        await listener(ctx, runId);
-      } catch (error) {
-        this.log(`[workflow:${runId}] background settlement listener failed: ${unknownErrorMessage(error)}`);
-      }
+    try {
+      await this.settledListener?.(ctx, runId);
+    } catch (error) {
+      this.log(`[workflow:${runId}] background settlement listener failed: ${unknownErrorMessage(error)}`);
     }
   }
 
@@ -292,23 +282,6 @@ export class BackgroundWorkflowCoordinator {
     this.pendingDelivery.set(sessionId, pending);
   }
 
-  private updateBackgroundSurface(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    const sessionId = ctx.sessionManager.getSessionId();
-    const runs = [...this.active.entries()]
-      .filter(([, run]) => run.sessionId === sessionId)
-      .map(([runId, run]) => ({ runId, name: run.name }));
-    if (runs.length === 0) {
-      ctx.ui.setWidget(BACKGROUND_WIDGET_KEY, undefined);
-      return;
-    }
-    ctx.ui.setWidget(
-      BACKGROUND_WIDGET_KEY,
-      [formatBackgroundActivity(runs, ctx.ui.theme)],
-      { placement: "aboveEditor" },
-    );
-  }
-
   private async deliver(ctx: ExtensionContext, runId: string): Promise<boolean> {
     const store = this.storeForCwd(ctx.cwd);
     const record = await store.load(runId);
@@ -333,25 +306,18 @@ export class BackgroundWorkflowCoordinator {
   }
 }
 
-function formatBackgroundActivity(
-  runs: readonly { readonly runId: string; readonly name: string }[],
-  theme: ExtensionContext["ui"]["theme"],
-): string {
-  const visible = runs.slice(0, 2).map((run) => `${run.name} ${run.runId.slice(0, 8)}`);
-  const hidden = runs.length - visible.length;
-  const suffix = hidden > 0 ? ` · +${hidden} more` : "";
-  return `${theme.fg("accent", "●")} ${theme.bold("Background workflows")} ${theme.fg("dim", `· ${visible.join(" · ")}${suffix}`)}`;
-}
-
 export function backgroundOrigin(ctx: Pick<ExtensionContext, "sessionManager">, requestedAt = Date.now()): WorkflowBackgroundOrigin {
   return { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
 }
 
 export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWorkflowResultDetails {
   if (!isDeliverableState(record.state)) throw new Error(`Workflow run ${record.runId} has not finished or paused.`);
+  const summary = backgroundSummary(record);
   return {
     name: record.workflow.name,
-    result: { summary: backgroundSummary(record) },
+    result: record.state === "completed" && record.result.kind === "value" ? record.result.value : { summary },
+    summary,
+    startedAt: record.startedAt,
     completedAt: record.endedAt ?? record.updatedAt,
     usage: record.usage,
     runId: record.runId,
@@ -362,14 +328,12 @@ export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWo
 }
 
 function backgroundSummary(record: WorkflowRunRecord): string {
-  if (record.state !== "completed") return boundedSummary(`Workflow ${record.state}: ${record.message}`);
+  if (record.state !== "completed") return truncateText(`Workflow ${record.state}: ${record.message}`, SUMMARY_LIMIT);
   if (record.result.kind === "unavailable") {
-    return boundedSummary(`Workflow completed; retained result is unavailable: ${record.result.reason}`);
+    return truncateText(`Workflow completed; retained result is unavailable: ${record.result.reason}`, SUMMARY_LIMIT);
   }
-  const value = record.result.value;
-  if (typeof value === "string") return boundedSummary(value);
-  if (isRecord(value) && typeof value.summary === "string") return boundedSummary(value.summary);
-  return "Workflow completed. Open run history for the retained result.";
+  const summary = workflowResultSummary(record.result.value);
+  return summary === undefined ? "Workflow completed. Open run history for the retained result." : truncateText(summary, SUMMARY_LIMIT);
 }
 
 function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): string {
@@ -379,7 +343,7 @@ function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): str
     `Run ID: ${details.runId}`,
     `State: ${details.status}`,
     "",
-    details.result.summary,
+    details.summary,
   ].join("\n");
 }
 
@@ -404,7 +368,7 @@ function isDeliverableState(state: WorkflowRunState): state is "completed" | "fa
 async function markDelivery(
   store: WorkflowRunStore,
   runId: string,
-  delivery: Parameters<typeof updateWorkflowRunDelivery>[1],
+  delivery: WorkflowRunDelivery,
 ): Promise<void> {
   const latest = await store.load(runId);
   if (!latest?.background || latest.background.delivery.state !== "pending") return;
@@ -424,16 +388,7 @@ async function forcePausedRecord(store: WorkflowRunStore, runId: string): Promis
 async function forceStoppedRecord(store: WorkflowRunStore, runId: string): Promise<void> {
   const record = await store.load(runId);
   if (!record || (record.state !== "queued" && record.state !== "running")) return;
-  await store.save(transitionWorkflowRun(record, {
-    state: "stopped",
-    progress: record.progress,
-    usage: record.usage ?? record.progress.usage ?? {
-      agents: [],
-      totals: emptyWorkflowUsageTotals(),
-      assistantMessages: 0,
-    },
-    error: new WorkflowAbortError("Workflow stopped by user."),
-  }));
+  await store.save(stopWorkflowRunRecord(record));
 }
 
 async function reconcileInterruptedRun(
@@ -482,11 +437,3 @@ async function waitForRuns(runs: readonly Promise<void>[], timeoutMs: number): P
     if (timer) clearTimeout(timer);
   }
 }
-
-function boundedSummary(value: string): string {
-  return value.length <= SUMMARY_LIMIT ? value : `${value.slice(0, SUMMARY_LIMIT - 1)}…`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -27,7 +27,7 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
 export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undefined): boolean {
   if (signal?.aborted) return true;
   if (safeInstanceOf(error, WorkflowAbortError)) return true;
-  if (typeof DOMException !== "undefined" && safeInstanceOf(error, DOMException)) {
+  if (safeInstanceOf(error, DOMException)) {
     try {
       return error.name === "AbortError";
     } catch {
@@ -67,10 +67,6 @@ export async function raceWithAbort<T>(operation: () => Promise<T>, signal: Abor
     };
     const onAbort = () => finish(() => reject(abortReason(signal)));
     signal.addEventListener("abort", onAbort, { once: true });
-    if (signal.aborted) {
-      onAbort();
-      return;
-    }
     void operation().then(
       (value) => finish(() => resolve(value)),
       (error: unknown) => finish(() => reject(error)),

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

@@ -0,0 +1,107 @@
+import type { ClassifierAnswer, ClassifierApi, ClassifierContext, ClassifierModel } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { RunContext } from "./agent-runner-types.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import { throwIfAborted } from "./cancellation.ts";
+import type { ClassifyOptions } from "./types.ts";
+
+type ClassifierRegistry = Pick<ModelRegistry, "classify" | "getAvailableOfType" | "getModelOfType">;
+
+/** No classifier model is configured, or the requested one is unknown. Recoverable inside `parallel`. */
+export class WorkflowClassifierUnavailableError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_UNAVAILABLE";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierUnavailableError";
+  }
+}
+
+/** The classifier answered with an error or no answer. Recoverable inside `parallel`. */
+export class WorkflowClassifierError extends Error {
+  readonly code = "WORKFLOW_CLASSIFIER_FAILED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowClassifierError";
+  }
+}
+
+/**
+ * `api.classify()`: answer typed questions about JSON state with a classifier model through the host's
+ * credentials, without a chat session. It shares the run's concurrency cap, budget, and per-agent timeout,
+ * records usage like an agent, and is not journaled, so a resumed run asks again.
+ */
+export async function runClassifier(
+  rc: RunContext,
+  context: ClassifierContext,
+  opts: ClassifyOptions = {},
+): Promise<Record<string, ClassifierAnswer>> {
+  const registry = rc.modelRegistry;
+  return await rc.semaphore.run(async () => {
+    assertWorkflowBudgetAvailable(rc.budget);
+    const model = await cachedClassifierModel(rc, registry, opts.model);
+    const label = opts.label ?? `classify:${model.provider}/${model.id}`;
+    // A stalled classifier must not hold a concurrency slot past the limit agents get.
+    const timeout = AbortSignal.timeout(rc.agentTimeoutMs);
+    const result = await registry.classify(model, context, { signal: rc.signal ? AbortSignal.any([rc.signal, timeout]) : timeout });
+    // One classifier response is one model response: recording it like one keeps per-model usage and the budget
+    // whole. Record before the abort check, since the provider charged for a call that returned as the run stopped.
+    rc.usage.recordAgentSession({
+      label,
+      phase: opts.phase,
+      messages: [{ role: "assistant", provider: result.provider, model: result.model, usage: result.usage }],
+    });
+    throwIfAborted(rc.signal);
+    if (result.stopReason !== "stop" && timeout.aborted) {
+      throw new WorkflowClassifierError(`${label}: classifier timed out after ${rc.agentTimeoutMs}ms`);
+    }
+    if (result.stopReason !== "stop") {
+      throw new WorkflowClassifierError(`${label}: classifier ${result.stopReason}${result.errorMessage ? `: ${result.errorMessage}` : ""}`);
+    }
+    return result.answers;
+  }, { signal: rc.signal });
+}
+
+/** One credential lookup per route and run; a route that failed to resolve keeps failing for the run. */
+function cachedClassifierModel(
+  rc: RunContext,
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  const key = JSON.stringify(ref ?? null);
+  const cached = rc.classifierRoutes?.get(key);
+  if (cached) return cached;
+  const resolved = resolveClassifierModel(registry, ref);
+  rc.classifierRoutes?.set(key, resolved);
+  return resolved;
+}
+
+async function resolveClassifierModel(
+  registry: ClassifierRegistry,
+  ref: string | readonly string[] | undefined,
+): Promise<ClassifierModel<ClassifierApi>> {
+  if (ref !== undefined && typeof ref !== "string") {
+    const available = await registry.getAvailableOfType("classifier");
+    const preferred = ref.map((candidate) => parseAgentModelRef(candidate))
+      .map(({ provider, id }) => available.find((model) => model.provider === provider && model.id === id))
+      .find((model) => model !== undefined);
+    if (!preferred) throw new WorkflowClassifierUnavailableError(`None of the classifier models ${ref.join(", ")} has working credentials.`);
+    return preferred;
+  }
+  if (ref === undefined) {
+    const [available] = await registry.getAvailableOfType("classifier");
+    if (!available) {
+      throw new WorkflowClassifierUnavailableError(
+        "No classifier model has working credentials. Configure one (for example TypeSafe Jev via OpenRouter) or pass { model: \"provider/id\" }.",
+      );
+    }
+    return available;
+  }
+  // Same ref rules as agent({ model }): malformed refs throw, bare ids mean Anthropic.
+  const { provider, id } = parseAgentModelRef(ref);
+  const model = registry.getModelOfType("classifier", provider, id);
+  if (!model) throw new WorkflowClassifierUnavailableError(`Classifier model "${ref}" not found (resolved as ${provider}/${id}).`);
+  return model;
+}