@yycholla/pi-dynamic-workflows 3.3.0

package/dist/fs-persistence.js

@@ -0,0 +1,102 @@
+/**
+ * Shared filesystem primitives for JSON-backed persistence.
+ *
+ * Both run-persistence.ts (workflow runs) and workflow-saved.ts (saved
+ * workflow commands) persist plain-JSON records to per-record files under a
+ * project/user directory, and both need the same three guarantees:
+ *
+ *  1. Atomic writes with a recovery backup — a crash mid-write must never
+ *     corrupt the live file, and a later-discovered-truncated primary must
+ *     still be recoverable from the last good write.
+ *  2. Corrupt-file recovery on read — a truncated/corrupt primary falls back
+ *     to its `.bak` sidecar instead of losing the record.
+ *  3. A missing or unreadable directory degrades to "no files" rather than
+ *     throwing — a listing must never crash because one storage location is
+ *     temporarily inaccessible (not yet created, deleted mid-race, EACCES).
+ *
+ * This module is the single implementation of all three; run-persistence.ts
+ * and workflow-saved.ts both call into it rather than maintaining parallel
+ * copies.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+/** The real node:fs implementations. */
+export function defaultPersistenceFs() {
+    return { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync };
+}
+/** Merge a partial test override on top of the real node:fs implementations. */
+export function resolvePersistenceFs(overrides) {
+    const base = defaultPersistenceFs();
+    return overrides ? { ...base, ...overrides } : base;
+}
+/** Ensure `dir` exists (recursive mkdir), idempotent. */
+export function ensureDir(fs, dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/**
+ * Atomically write JSON to `path`: tmp-write + rename (atomic on the same
+ * filesystem, so a crash mid-write can't corrupt the live file), then
+ * best-effort refresh a `.bak` sidecar from the just-written good state —
+ * the recovery fallback readJsonWithBackupRecovery() uses if the primary is
+ * later found truncated (e.g. a rename that itself got interrupted by a
+ * power loss on a filesystem/OS combination where rename isn't fully atomic).
+ */
+export function writeJsonAtomicWithBackup(fs, path, data) {
+    const json = JSON.stringify(data, null, 2);
+    fs.writeFileSync(`${path}.tmp`, json);
+    fs.renameSync(`${path}.tmp`, path);
+    try {
+        fs.writeFileSync(`${path}.bak`, json);
+    }
+    catch {
+        // Backup is best-effort; the primary write already succeeded.
+    }
+}
+/**
+ * Read JSON from `path`, falling back to `path.bak` if the primary is
+ * missing or fails to parse. Returns null if neither candidate parses.
+ */
+export function readJsonWithBackupRecovery(fs, path) {
+    for (const candidate of [path, `${path}.bak`]) {
+        try {
+            if (!fs.existsSync(candidate))
+                continue;
+            return JSON.parse(fs.readFileSync(candidate, "utf-8"));
+        }
+        catch {
+            // Corrupt candidate -> fall through to the next candidate.
+        }
+    }
+    return null;
+}
+/**
+ * List `.json` record files in `dir`. A missing directory (never created
+ * yet) or an unreadable one (deleted between the existsSync check and
+ * readdirSync, permission-denied, etc.) both degrade to an empty list
+ * rather than throwing — callers (run listings, saved-workflow listings)
+ * must never crash a navigator/listing because one storage location is
+ * temporarily inaccessible.
+ */
+export function listJsonFilesSafe(fs, dir) {
+    try {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+}
+/** Best-effort unlink; ignores missing-file/permission errors, reports whether it deleted anything. */
+export function unlinkIfExistsSafe(fs, path) {
+    try {
+        if (fs.existsSync(path)) {
+            fs.unlinkSync(path);
+            return true;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+export type { AdversarialReviewConfig } from "./adversarial-review.js";
+export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
+export { listAvailableModelSpecs, listAvailableModels, WorkflowAgent } from "./agent.js";
+export type { AgentHistoryEntry, AgentHistoryKind, AgentHistoryRole } from "./agent-history.js";
+export { compactAgentHistory } from "./agent-history.js";
+export type { AgentDefinition, AgentRegistry } from "./agent-registry.js";
+export { applyToolPolicy, listAgentTypes, loadAgentRegistry, resolveAgentType } from "./agent-registry.js";
+export { registerBuiltinWorkflows } from "./builtin-commands.js";
+export { generateCodeReviewWorkflow, MAX_DIFF_CHARS } from "./code-review.js";
+export * from "./config.js";
+export type { DeepResearchConfig } from "./deep-research.js";
+export { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
+export type { WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowDisplay, WorkflowDisplayOptions, WorkflowSnapshot, } from "./display.js";
+export { createToolUpdateWorkflowDisplay, createWidgetWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
+export { createEffortState, type EffortLevel, type EffortState, effortDirective, isSubstantive, registerEffortCommand, } from "./effort-command.js";
+export { isAbortError, isTimeoutError, isWorkflowError, WorkflowError, WorkflowErrorCode, wrapError, } from "./errors.js";
+export type { WorkflowLogger, WorkflowLoggerOptions } from "./logger.js";
+export { createWorkflowLogger } from "./logger.js";
+export type { ModelRoute, ModelRoutingConfig } from "./model-routing.js";
+export { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+export type { ModelThinkingLevel, ResolvedModelSpec } from "./model-spec.js";
+export { canonicalModelSpec, formatModelSpecWithThinking, isThinkingLevel, resolveModelSpecWithThinking, splitModelSpecThinking, THINKING_LEVELS, } from "./model-spec.js";
+export type { ModelTierConfig, RankableModel } from "./model-tier-config.js";
+export { buildDefaultTierConfig, formatTierFallbackNotice, getModelTierConfigPath, loadModelTierConfig, resolveTierModel, saveModelTierConfig, sortedTierNames, } from "./model-tier-config.js";
+export type { PersistedRunState, RunPersistence, RunStatus } from "./run-persistence.js";
+export { createRunPersistence, generateRunId } from "./run-persistence.js";
+export { parseCommandArgs, registerAllSavedWorkflows, registerSavedWorkflow, } from "./saved-commands.js";
+export { SharedStore } from "./shared-store.js";
+export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export { deliverText, installResultDelivery, installTaskPanel, type TaskPanelOptions } from "./task-panel.js";
+export type { AutoResumeDelayParams, SchedulableWorkflowManager, TimerHandle, UsageLimitSchedulerOptions, } from "./usage-limit-scheduler.js";
+export { computeAutoResumeDelayMs, parseResetHintMs, UsageLimitScheduler } from "./usage-limit-scheduler.js";
+export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
+export type { AgentOptions, JournalEntry, SharedRuntime, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export type { AlignmentEvidence, CapabilityDescriptor, CapabilityDiagnostic, DynamicReferenceDescriptor, OptionDescriptor, OptionShape, PresentAtVersion, RuntimeBindingAssembly, StaticCapabilityFact, WorkflowCapabilityContract, WorkflowCapabilityDefinition, WorkflowRuntimeImplementations, } from "./workflow-capability-contract.js";
+export { CapabilityClassification, CapabilityOrigin, CapabilitySupport, DiagnosticSeverity, DiscoveryPlacement, defineWorkflowCapabilityContract, WORKFLOW_CAPABILITY_CONTRACT, WORKFLOW_CAPABILITY_DEFINITION, WorkflowCapabilityContractError, } from "./workflow-capability-contract.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
+export type { WorkflowControlInput, WorkflowControlRunDetails, WorkflowControlToolOptions, } from "./workflow-control-tool.js";
+export { createWorkflowControlTool } from "./workflow-control-tool.js";
+export { type ArmReason, buildArmedWorkflowPrompt, buildForcedWorkflowPrompt, endsWithTrigger, hasTrigger, type InstallWorkflowKeywordArmingOptions, installWorkflowKeywordArming, registerWorkflowProgressCommands, registerWorkflowTriggerCommand, type WorkflowModeState, } from "./workflow-editor.js";
+export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
+export { WorkflowManager } from "./workflow-manager.js";
+export type { WorkflowProjectPaths } from "./workflow-paths.js";
+export { WORKFLOW_HOME_RELATIVE_DIR, WORKFLOW_PROJECTS_SUBDIR, workflowHomeDir, workflowProjectKey, workflowProjectPaths, workflowUserSavedDir, } from "./workflow-paths.js";
+export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
+export { assertSafeSavedWorkflowName, createWorkflowStorage, isSafeSavedWorkflowName } from "./workflow-saved.js";
+export type { WorkflowSettings, WorkflowSettingsOptions, WorkflowSettingsStore } from "./workflow-settings.js";
+export { getWorkflowProjectSettingsPath, getWorkflowSettingsPath, loadWorkflowSettings, saveWorkflowSettings, saveWorkflowSettingsForCwd, } from "./workflow-settings.js";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
+export { backgroundStartedText, createWorkflowTool } from "./workflow-tool.js";
+export { keyToAction, type NavAction, NavigatorModel, NavigatorState, openWorkflowNavigator, renderNavigator, type ViewKind, } from "./workflow-ui.js";
+export { registerWorkflowModelsCommand } from "./workflows-models-command.js";
+export type { Worktree } from "./worktree.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/index.js

@@ -0,0 +1,35 @@
+export { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+export { listAvailableModelSpecs, listAvailableModels, WorkflowAgent } from "./agent.js";
+export { compactAgentHistory } from "./agent-history.js";
+export { applyToolPolicy, listAgentTypes, loadAgentRegistry, resolveAgentType } from "./agent-registry.js";
+export { registerBuiltinWorkflows } from "./builtin-commands.js";
+export { generateCodeReviewWorkflow, MAX_DIFF_CHARS } from "./code-review.js";
+export * from "./config.js";
+export { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
+export { createToolUpdateWorkflowDisplay, createWidgetWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
+export { createEffortState, effortDirective, isSubstantive, registerEffortCommand, } from "./effort-command.js";
+export { isAbortError, isTimeoutError, isWorkflowError, WorkflowError, WorkflowErrorCode, wrapError, } from "./errors.js";
+export { createWorkflowLogger } from "./logger.js";
+export { parseModelRoutingFromMeta, resolveModelForPhase } from "./model-routing.js";
+export { canonicalModelSpec, formatModelSpecWithThinking, isThinkingLevel, resolveModelSpecWithThinking, splitModelSpecThinking, THINKING_LEVELS, } from "./model-spec.js";
+export { buildDefaultTierConfig, formatTierFallbackNotice, getModelTierConfigPath, loadModelTierConfig, resolveTierModel, saveModelTierConfig, sortedTierNames, } from "./model-tier-config.js";
+export { createRunPersistence, generateRunId } from "./run-persistence.js";
+export { parseCommandArgs, registerAllSavedWorkflows, registerSavedWorkflow, } from "./saved-commands.js";
+export { SharedStore } from "./shared-store.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export { deliverText, installResultDelivery, installTaskPanel } from "./task-panel.js";
+export { computeAutoResumeDelayMs, parseResetHintMs, UsageLimitScheduler } from "./usage-limit-scheduler.js";
+export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { CapabilityClassification, CapabilityOrigin, CapabilitySupport, DiagnosticSeverity, DiscoveryPlacement, defineWorkflowCapabilityContract, WORKFLOW_CAPABILITY_CONTRACT, WORKFLOW_CAPABILITY_DEFINITION, WorkflowCapabilityContractError, } from "./workflow-capability-contract.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
+export { createWorkflowControlTool } from "./workflow-control-tool.js";
+export { buildArmedWorkflowPrompt, buildForcedWorkflowPrompt, endsWithTrigger, hasTrigger, installWorkflowKeywordArming, registerWorkflowProgressCommands, registerWorkflowTriggerCommand, } from "./workflow-editor.js";
+export { WorkflowManager } from "./workflow-manager.js";
+export { WORKFLOW_HOME_RELATIVE_DIR, WORKFLOW_PROJECTS_SUBDIR, workflowHomeDir, workflowProjectKey, workflowProjectPaths, workflowUserSavedDir, } from "./workflow-paths.js";
+export { assertSafeSavedWorkflowName, createWorkflowStorage, isSafeSavedWorkflowName } from "./workflow-saved.js";
+export { getWorkflowProjectSettingsPath, getWorkflowSettingsPath, loadWorkflowSettings, saveWorkflowSettings, saveWorkflowSettingsForCwd, } from "./workflow-settings.js";
+export { backgroundStartedText, createWorkflowTool } from "./workflow-tool.js";
+export { keyToAction, NavigatorModel, NavigatorState, openWorkflowNavigator, renderNavigator, } from "./workflow-ui.js";
+export { registerWorkflowModelsCommand } from "./workflows-models-command.js";
+export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/logger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workflow logger with file persistence.
+ */
+export interface WorkflowLogger {
+    log(message: string): void;
+    error(message: string): void;
+    warn(message: string): void;
+    getLogs(): string[];
+    persist(): string | null;
+}
+export interface WorkflowLoggerOptions {
+    /** Run ID for persistence. */
+    runId?: string;
+    /** Working directory for file paths. */
+    cwd?: string;
+    /** Whether to persist logs to disk. */
+    persist?: boolean;
+    /** Callback for each log entry. */
+    onLog?: (message: string) => void;
+}
+export declare function createWorkflowLogger(options?: WorkflowLoggerOptions): WorkflowLogger;

package/dist/logger.js

@@ -0,0 +1,66 @@
+/**
+ * Workflow logger with file persistence.
+ */
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { workflowProjectPaths } from "./workflow-paths.js";
+export function createWorkflowLogger(options = {}) {
+    const logs = [];
+    const persistLogs = options.persist ?? true;
+    const cwd = options.cwd ?? process.cwd();
+    const runId = options.runId ?? `run-${Date.now()}`;
+    const runsDir = workflowProjectPaths(cwd).runsDir;
+    let logFile = null;
+    const write = (level, message) => {
+        const timestamp = new Date().toISOString();
+        const entry = `[${timestamp}] [${level}] ${message}`;
+        logs.push(entry);
+        options.onLog?.(message);
+        if (persistLogs && logFile) {
+            try {
+                appendFileSync(logFile, `${entry}\n`);
+            }
+            catch {
+                // Silent fail for log persistence
+            }
+        }
+    };
+    const logger = {
+        log(message) {
+            write("INFO", message);
+        },
+        error(message) {
+            write("ERROR", message);
+        },
+        warn(message) {
+            write("WARN", message);
+        },
+        getLogs() {
+            return [...logs];
+        },
+        persist() {
+            if (!persistLogs)
+                return null;
+            try {
+                mkdirSync(runsDir, { recursive: true });
+                logFile = join(runsDir, `${runId}.log`);
+                writeFileSync(logFile, `${logs.join("\n")}\n`);
+                return logFile;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+    // Initialize log file if persisting
+    if (persistLogs) {
+        try {
+            mkdirSync(runsDir, { recursive: true });
+            logFile = join(runsDir, `${runId}.log`);
+        }
+        catch {
+            // Silent fail
+        }
+    }
+    return logger;
+}

package/dist/model-routing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Per-stage model routing for workflows.
+ * Allows different phases to use different models.
+ */
+export interface ModelRoute {
+    /** Phase name pattern (regex or exact match). */
+    phasePattern: string;
+    /** Model to use for this phase. */
+    model: string;
+    /** Whether to use regex matching. */
+    useRegex?: boolean;
+}
+export interface ModelRoutingConfig {
+    /** Default model for all phases. */
+    defaultModel?: string;
+    /** Per-phase model overrides. */
+    routes: ModelRoute[];
+}
+/**
+ * Resolve which model to use for a given phase.
+ */
+export declare function resolveModelForPhase(phase: string | undefined, config: ModelRoutingConfig): string | undefined;
+/**
+ * Parse model routing from workflow meta: per-phase models from meta.phases[].model
+ * and a top-level default from meta.model (used when no phase route matches).
+ */
+export declare function parseModelRoutingFromMeta(phases?: Array<{
+    title: string;
+    model?: string;
+}>, defaultModel?: string): ModelRoutingConfig;

package/dist/model-routing.js

@@ -0,0 +1,50 @@
+/**
+ * Per-stage model routing for workflows.
+ * Allows different phases to use different models.
+ */
+/**
+ * Resolve which model to use for a given phase.
+ */
+export function resolveModelForPhase(phase, config) {
+    if (!phase || !config.routes.length) {
+        return config.defaultModel;
+    }
+    for (const route of config.routes) {
+        if (route.useRegex) {
+            try {
+                const regex = new RegExp(route.phasePattern, "i");
+                if (regex.test(phase)) {
+                    return route.model;
+                }
+            }
+            catch {
+                // Invalid regex, skip
+            }
+        }
+        else if (phase === route.phasePattern) {
+            // Exact, case-sensitive match — phase titles are author-controlled literals,
+            // so fuzzy substring matching only caused mis-routes (e.g. "analyze" matching
+            // "analyze-deep" or vice-versa). Use the regex branch for fuzzy needs.
+            return route.model;
+        }
+    }
+    return config.defaultModel;
+}
+/**
+ * Parse model routing from workflow meta: per-phase models from meta.phases[].model
+ * and a top-level default from meta.model (used when no phase route matches).
+ */
+export function parseModelRoutingFromMeta(phases, defaultModel) {
+    const routes = [];
+    if (phases) {
+        for (const phase of phases) {
+            if (phase.model) {
+                routes.push({
+                    phasePattern: phase.title,
+                    model: phase.model,
+                });
+            }
+        }
+    }
+    return { defaultModel, routes };
+}

package/dist/model-spec.d.ts

@@ -0,0 +1,29 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ModelThinkingLevel = (typeof THINKING_LEVELS)[number];
+export interface ResolvedModelSpec {
+    requestedSpec: string;
+    model?: Model<Api>;
+    thinkingLevel?: ModelThinkingLevel;
+    resolvedSpec?: string;
+    warning?: string;
+    error?: string;
+}
+export declare function isThinkingLevel(value: string): value is ModelThinkingLevel;
+export declare function formatModelSpecWithThinking(modelSpec: string, thinkingLevel: ModelThinkingLevel | undefined): string;
+export declare function canonicalModelSpec(model: Model<Api>): string;
+/**
+ * Split a stored tier spec for display/editing. Exact known model specs win, so
+ * model ids that legitimately contain colons are not mistaken for thinking.
+ */
+export declare function splitModelSpecThinking(spec: string | undefined, knownModelSpecs?: readonly string[]): {
+    modelSpec: string;
+    thinkingLevel?: ModelThinkingLevel;
+};
+/**
+ * Resolve a workflow model-tier/agent model string with the same user-facing
+ * grammar as Pi CLI `--model`: `provider/modelId[:thinking]`, bare model ids,
+ * fuzzy patterns, and exact colon-containing model ids.
+ */
+export declare function resolveModelSpecWithThinking(spec: string, modelRegistry: Pick<ModelRegistry, "getAll">): ResolvedModelSpec;

package/dist/model-spec.js

@@ -0,0 +1,252 @@
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+const DEFAULT_MODEL_PER_PROVIDER = {
+    "amazon-bedrock": "us.anthropic.claude-opus-4-6-v1",
+    anthropic: "claude-opus-4-8",
+    openai: "gpt-5.4",
+    "azure-openai-responses": "gpt-5.4",
+    "openai-codex": "gpt-5.5",
+    deepseek: "deepseek-v4-pro",
+    google: "gemini-3.1-pro-preview",
+    "google-vertex": "gemini-3.1-pro-preview",
+    "github-copilot": "gpt-5.4",
+    openrouter: "moonshotai/kimi-k2.6",
+    "vercel-ai-gateway": "zai/glm-5.1",
+    zai: "glm-5.1",
+    mistral: "devstral-medium-latest",
+    minimax: "MiniMax-M2.7",
+    "minimax-cn": "MiniMax-M2.7",
+    moonshotai: "kimi-k2.6",
+    "moonshotai-cn": "kimi-k2.6",
+    huggingface: "moonshotai/Kimi-K2.6",
+    fireworks: "accounts/fireworks/models/kimi-k2p6",
+    together: "moonshotai/Kimi-K2.6",
+    opencode: "kimi-k2.6",
+    "opencode-go": "kimi-k2.6",
+    "kimi-coding": "kimi-for-coding",
+    "cloudflare-workers-ai": "@cf/moonshotai/kimi-k2.6",
+    "cloudflare-ai-gateway": "workers-ai/@cf/moonshotai/kimi-k2.6",
+    xiaomi: "mimo-v2.5-pro",
+    "xiaomi-token-plan-cn": "mimo-v2.5-pro",
+    "xiaomi-token-plan-ams": "mimo-v2.5-pro",
+    "xiaomi-token-plan-sgp": "mimo-v2.5-pro",
+};
+export function isThinkingLevel(value) {
+    return THINKING_LEVELS.includes(value);
+}
+export function formatModelSpecWithThinking(modelSpec, thinkingLevel) {
+    return thinkingLevel ? `${modelSpec}:${thinkingLevel}` : modelSpec;
+}
+export function canonicalModelSpec(model) {
+    return `${model.provider}/${model.id}`;
+}
+/**
+ * Split a stored tier spec for display/editing. Exact known model specs win, so
+ * model ids that legitimately contain colons are not mistaken for thinking.
+ */
+export function splitModelSpecThinking(spec, knownModelSpecs) {
+    const trimmed = spec?.trim() ?? "";
+    if (!trimmed)
+        return { modelSpec: "", thinkingLevel: undefined };
+    const known = knownModelSpecs ? new Set(knownModelSpecs) : undefined;
+    if (known?.has(trimmed))
+        return { modelSpec: trimmed, thinkingLevel: undefined };
+    const lastColon = trimmed.lastIndexOf(":");
+    if (lastColon === -1)
+        return { modelSpec: trimmed, thinkingLevel: undefined };
+    const prefix = trimmed.slice(0, lastColon);
+    const suffix = trimmed.slice(lastColon + 1);
+    if (!prefix || !isThinkingLevel(suffix))
+        return { modelSpec: trimmed, thinkingLevel: undefined };
+    if (known && !known.has(prefix))
+        return { modelSpec: trimmed, thinkingLevel: undefined };
+    return { modelSpec: prefix, thinkingLevel: suffix };
+}
+function isAlias(id) {
+    if (id.endsWith("-latest"))
+        return true;
+    return !/-\d{8}$/.test(id);
+}
+function findExactModelReferenceMatch(modelReference, availableModels) {
+    const trimmedReference = modelReference.trim();
+    if (!trimmedReference)
+        return undefined;
+    const normalizedReference = trimmedReference.toLowerCase();
+    const canonicalMatches = availableModels.filter((model) => canonicalModelSpec(model).toLowerCase() === normalizedReference);
+    if (canonicalMatches.length === 1)
+        return canonicalMatches[0];
+    if (canonicalMatches.length > 1)
+        return undefined;
+    const slashIndex = trimmedReference.indexOf("/");
+    if (slashIndex !== -1) {
+        const provider = trimmedReference.slice(0, slashIndex).trim();
+        const modelId = trimmedReference.slice(slashIndex + 1).trim();
+        if (provider && modelId) {
+            const providerMatches = availableModels.filter((model) => model.provider.toLowerCase() === provider.toLowerCase() && model.id.toLowerCase() === modelId.toLowerCase());
+            if (providerMatches.length === 1)
+                return providerMatches[0];
+            if (providerMatches.length > 1)
+                return undefined;
+        }
+    }
+    const idMatches = availableModels.filter((model) => model.id.toLowerCase() === normalizedReference);
+    return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+function tryMatchModel(modelPattern, availableModels) {
+    const exactMatch = findExactModelReferenceMatch(modelPattern, availableModels);
+    if (exactMatch)
+        return exactMatch;
+    const normalizedPattern = modelPattern.toLowerCase();
+    const matches = availableModels.filter((model) => model.id.toLowerCase().includes(normalizedPattern) || model.name?.toLowerCase().includes(normalizedPattern));
+    if (matches.length === 0)
+        return undefined;
+    const aliases = matches.filter((model) => isAlias(model.id));
+    if (aliases.length > 0) {
+        aliases.sort((a, b) => b.id.localeCompare(a.id));
+        return aliases[0];
+    }
+    const datedVersions = matches.filter((model) => !isAlias(model.id));
+    datedVersions.sort((a, b) => b.id.localeCompare(a.id));
+    return datedVersions[0];
+}
+function parseModelPattern(pattern, availableModels, options) {
+    const exactMatch = tryMatchModel(pattern, availableModels);
+    if (exactMatch)
+        return { model: exactMatch };
+    const lastColonIndex = pattern.lastIndexOf(":");
+    if (lastColonIndex === -1)
+        return {};
+    const prefix = pattern.slice(0, lastColonIndex);
+    const suffix = pattern.slice(lastColonIndex + 1);
+    if (isThinkingLevel(suffix)) {
+        const result = parseModelPattern(prefix, availableModels, options);
+        if (!result.model)
+            return result;
+        return {
+            model: result.model,
+            thinkingLevel: result.warning ? undefined : suffix,
+            warning: result.warning,
+        };
+    }
+    if (options?.allowInvalidThinkingLevelFallback === false)
+        return {};
+    const result = parseModelPattern(prefix, availableModels, options);
+    if (!result.model)
+        return result;
+    return {
+        model: result.model,
+        warning: `Invalid thinking level "${suffix}" in pattern "${pattern}". Using default instead.`,
+    };
+}
+function buildFallbackModel(provider, modelId, availableModels) {
+    const providerModels = availableModels.filter((model) => model.provider === provider);
+    if (providerModels.length === 0)
+        return undefined;
+    const defaultId = DEFAULT_MODEL_PER_PROVIDER[provider];
+    const baseModel = defaultId
+        ? (providerModels.find((model) => model.id === defaultId) ?? providerModels[0])
+        : providerModels[0];
+    return { ...baseModel, id: modelId, name: modelId };
+}
+/**
+ * Resolve a workflow model-tier/agent model string with the same user-facing
+ * grammar as Pi CLI `--model`: `provider/modelId[:thinking]`, bare model ids,
+ * fuzzy patterns, and exact colon-containing model ids.
+ */
+export function resolveModelSpecWithThinking(spec, modelRegistry) {
+    const requestedSpec = spec.trim();
+    if (!requestedSpec)
+        return { requestedSpec, error: "No model spec provided." };
+    const availableModels = modelRegistry.getAll();
+    if (availableModels.length === 0) {
+        return {
+            requestedSpec,
+            error: "No models available. Check your installation or add models to models.json.",
+        };
+    }
+    const providerMap = new Map();
+    for (const model of availableModels) {
+        providerMap.set(model.provider.toLowerCase(), model.provider);
+    }
+    let provider;
+    let pattern = requestedSpec;
+    let inferredProvider = false;
+    const slashIndex = requestedSpec.indexOf("/");
+    if (slashIndex !== -1) {
+        const maybeProvider = requestedSpec.slice(0, slashIndex);
+        const canonicalProvider = providerMap.get(maybeProvider.toLowerCase());
+        if (canonicalProvider) {
+            provider = canonicalProvider;
+            pattern = requestedSpec.slice(slashIndex + 1);
+            inferredProvider = true;
+        }
+    }
+    if (!provider) {
+        const exact = findExactModelReferenceMatch(requestedSpec, availableModels);
+        if (exact) {
+            return { requestedSpec, model: exact, resolvedSpec: canonicalModelSpec(exact) };
+        }
+    }
+    const candidates = provider ? availableModels.filter((model) => model.provider === provider) : availableModels;
+    const { model, thinkingLevel, warning } = parseModelPattern(pattern, candidates, {
+        allowInvalidThinkingLevelFallback: false,
+    });
+    if (model) {
+        return {
+            requestedSpec,
+            model,
+            thinkingLevel,
+            warning,
+            resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(model), thinkingLevel),
+        };
+    }
+    if (inferredProvider) {
+        const exact = findExactModelReferenceMatch(requestedSpec, availableModels);
+        if (exact) {
+            return { requestedSpec, model: exact, resolvedSpec: canonicalModelSpec(exact) };
+        }
+        const fallback = parseModelPattern(requestedSpec, availableModels, {
+            allowInvalidThinkingLevelFallback: false,
+        });
+        if (fallback.model) {
+            return {
+                requestedSpec,
+                model: fallback.model,
+                thinkingLevel: fallback.thinkingLevel,
+                warning: fallback.warning,
+                resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(fallback.model), fallback.thinkingLevel),
+            };
+        }
+    }
+    if (provider) {
+        let fallbackPattern = pattern;
+        let fallbackThinking;
+        const lastColon = pattern.lastIndexOf(":");
+        if (lastColon !== -1) {
+            const suffix = pattern.slice(lastColon + 1);
+            if (isThinkingLevel(suffix)) {
+                fallbackPattern = pattern.slice(0, lastColon);
+                fallbackThinking = suffix;
+            }
+        }
+        const fallbackModel = buildFallbackModel(provider, fallbackPattern, availableModels);
+        if (fallbackModel) {
+            const modelWithReasoning = fallbackThinking && fallbackThinking !== "off" ? { ...fallbackModel, reasoning: true } : fallbackModel;
+            const fallbackWarning = warning
+                ? `${warning} Model "${fallbackPattern}" not found for provider "${provider}". Using custom model id.`
+                : `Model "${fallbackPattern}" not found for provider "${provider}". Using custom model id.`;
+            return {
+                requestedSpec,
+                model: modelWithReasoning,
+                thinkingLevel: fallbackThinking,
+                warning: fallbackWarning,
+                resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(modelWithReasoning), fallbackThinking),
+            };
+        }
+    }
+    const display = provider ? `${provider}/${pattern}` : requestedSpec;
+    return {
+        requestedSpec,
+        warning,
+        error: `Model "${display}" not found. Use /workflows-models to choose an available model.`,
+    };
+}