@agwab/pi-workflow 0.1.2 → 0.2.1

package/dist/subagent-backend.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
 import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { availableParallelism } from "node:os";
 import { fileURLToPath } from "node:url";
 import { fromProjectPath, isTerminalTaskStatus, nowIso, toProjectPath, writeRunRecord, } from "./store.js";
 import { applyTaskResultArtifact, isTaskTimedOut, markTaskTimedOut, } from "./result.js";
@@ -15,6 +16,10 @@ const FETCH_CONTENT_CACHE_ENV = "PI_WORKFLOW_FETCH_CONTENT_CACHE";
 const LEGACY_FETCH_CACHE_ENV = "PI_WORKFLOW_FETCH_CACHE";
 const DEFAULT_TRANSIENT_MODEL_FAILURE_RETRIES = 5;
 const DEFAULT_ARTIFACT_OUTPUT_RETRIES = 2;
+const MAX_CONCURRENT_LAUNCHES_ENV = "PI_WORKFLOW_MAX_CONCURRENT_LAUNCHES";
+const DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS = 3_000;
+const MIN_TRANSIENT_RETRY_JITTER_MS = 1_000;
+const MAX_TRANSIENT_RETRY_JITTER_MS = 5_000;
 const MODULE_PATH = fileURLToPath(import.meta.url);
 const MODULE_DIR = dirname(MODULE_PATH);
 const BUNDLED_PI_WEB_ACCESS_EXTENSION = bundledNodeModulePath("pi-web-access", "index.ts");
@@ -47,6 +52,81 @@ async function loadSubagentApi() {
     cachedSubagentApi ??= import(subagentApiSpecifier).then((mod) => mod);
     return cachedSubagentApi;
 }
+let launchSlotReleaseDelayMs = DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS;
+let transientRetryJitterForTests;
+const launchWaitQueue = [];
+let activeLaunchSlots = 0;
+function resolveMaxConcurrentLaunches() {
+    const override = Number.parseInt(process.env[MAX_CONCURRENT_LAUNCHES_ENV] ?? "", 10);
+    if (Number.isFinite(override))
+        return Math.max(1, Math.floor(override));
+    return Math.max(2, Math.floor(availableParallelism() / 2));
+}
+function isLaunchGateSaturated() {
+    return activeLaunchSlots >= resolveMaxConcurrentLaunches();
+}
+async function acquireLaunchSlot() {
+    if (!isLaunchGateSaturated()) {
+        activeLaunchSlots += 1;
+        return releaseLaunchSlot;
+    }
+    await new Promise((resolveWait) => launchWaitQueue.push(resolveWait));
+    return releaseLaunchSlot;
+}
+function releaseLaunchSlot() {
+    const next = launchWaitQueue.shift();
+    if (next) {
+        // Transfer the occupied slot directly to the queued launcher.
+        next();
+        return;
+    }
+    activeLaunchSlots = Math.max(0, activeLaunchSlots - 1);
+}
+function releaseLaunchSlotAfterDelay(delayMs, release) {
+    if (delayMs <= 0) {
+        release();
+        return;
+    }
+    const timer = setTimeout(release, delayMs);
+    timer.unref?.();
+}
+async function runWithLaunchSlot(action) {
+    const release = await acquireLaunchSlot();
+    let holdAfterReturn = false;
+    try {
+        const result = await action();
+        holdAfterReturn = true;
+        return result;
+    }
+    finally {
+        releaseLaunchSlotAfterDelay(holdAfterReturn ? launchSlotReleaseDelayMs : 0, release);
+    }
+}
+function transientRetryJitterMs() {
+    if (transientRetryJitterForTests)
+        return transientRetryJitterForTests();
+    return (MIN_TRANSIENT_RETRY_JITTER_MS +
+        Math.floor(Math.random() *
+            (MAX_TRANSIENT_RETRY_JITTER_MS - MIN_TRANSIENT_RETRY_JITTER_MS + 1)));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function setSubagentLaunchControlsForTests(options) {
+    launchSlotReleaseDelayMs =
+        options?.releaseDelayMs === undefined
+            ? DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS
+            : Math.max(0, Math.floor(options.releaseDelayMs));
+    transientRetryJitterForTests =
+        options?.retryJitterMs === undefined
+            ? undefined
+            : typeof options.retryJitterMs === "function"
+                ? options.retryJitterMs
+                : () => Math.max(0, Math.floor(options.retryJitterMs));
+    activeLaunchSlots = 0;
+    while (launchWaitQueue.length > 0)
+        launchWaitQueue.shift()?.();
+}
 export async function cleanupSubagentRun(_cwd, run) {
     for (const task of run.tasks) {
         if (isTerminalTaskStatus(task.status))
@@ -77,6 +157,14 @@ export async function launchSubagentTask(cwd, run, task, compiledTask) {
             message: "fast:on is not supported for pi-workflow execution.",
         };
     }
+    if ((task.launchRetry?.attempts ?? 0) > 0) {
+        const jitterMs = transientRetryJitterMs();
+        task.statusDetail = "retry_model_failure";
+        task.lastMessage = `waiting ${jitterMs}ms before retrying transient-model launch`;
+        await writeRunRecord(cwd, run);
+        if (jitterMs > 0)
+            await sleep(jitterMs);
+    }
     const systemPromptFile = fromProjectPath(cwd, task.files.systemPrompt);
     const taskPromptFile = fromProjectPath(cwd, task.files.taskPrompt);
     const outputFile = fromProjectPath(cwd, task.files.output);
@@ -126,7 +214,11 @@ export async function launchSubagentTask(cwd, run, task, compiledTask) {
         subagentOptions.extensions = extensions;
         if (captureToolCallsEnabled())
             subagentOptions.captureToolCalls = true;
-        launched = await api.runSubagent(subagentOptions);
+        if (isLaunchGateSaturated()) {
+            task.lastMessage = `waiting for pi-subagent launch slot (${resolveMaxConcurrentLaunches()} max)`;
+            await writeRunRecord(cwd, run).catch(() => undefined);
+        }
+        launched = await runWithLaunchSlot(() => api.runSubagent(subagentOptions));
     }
     catch (error) {
         task.status = "pending";
@@ -259,8 +351,23 @@ async function materializeTerminalSubagentResult(cwd, run, task, snapshot) {
         : undefined;
     const toolCalls = await readToolCallsSummary(snapshot, subagentResult, artifactRoot);
     const outputText = await readFile(outputFile, "utf8").catch(() => "");
+    const stderrText = await readFile(stderrFile, "utf8").catch(() => "");
     const outputBytes = Buffer.byteLength(outputText, "utf8");
-    const statusInfo = workflowStatusFromSubagent(snapshot, subagentResult, outputBytes);
+    let statusInfo = workflowStatusFromSubagent(snapshot, subagentResult, outputBytes);
+    const deterministicBootFailure = classifyDeterministicBootFailure({
+        statusInfo,
+        stderrText,
+        outputBytes,
+        contextLengthExceeded: Boolean(subagentResult?.metadata?.contextLengthExceeded ??
+            snapshot.metadata?.contextLengthExceeded),
+    });
+    if (deterministicBootFailure) {
+        statusInfo = {
+            status: "failed",
+            failureKind: "deterministic_boot",
+            errorMessage: deterministicBootFailure,
+        };
+    }
     const completedAt = typeof subagentResult?.completedAt === "string"
         ? subagentResult.completedAt
         : (snapshot.completedAt ?? nowIso());
@@ -685,6 +792,23 @@ function failArtifactGraphTask(task, options) {
     task.lastMessage = options.message;
     return true;
 }
+function classifyDeterministicBootFailure(options) {
+    if (options.statusInfo.status !== "failed" ||
+        options.statusInfo.failureKind !== "model" ||
+        options.outputBytes !== 0 ||
+        options.contextLengthExceeded) {
+        return undefined;
+    }
+    const text = options.stderrText;
+    const deterministicPattern = /(Failed to load extension|Cannot find module|(?:failed to load|invalid|missing) (?:workflow )?config(?:uration)?|config(?:uration)? (?:error|failed|invalid))/i;
+    if (!deterministicPattern.test(text))
+        return undefined;
+    const excerpt = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => deterministicPattern.test(line)) ?? text.trim();
+    return `deterministic-boot failure: ${excerpt.slice(0, 500)}`;
+}
 function shouldRetryTransientModelFailure(statusInfo, workflowResult, outputBytes) {
     return (statusInfo.status === "failed" &&
         statusInfo.failureKind === "model" &&
@@ -714,14 +838,14 @@ function retryOrFailTransientSubagentFailure(task, options) {
     if (!exhausted) {
         task.status = "pending";
         task.statusDetail = "retry_model_failure";
-        task.lastMessage = `${options.message}; retrying transient model failure (${attempt}/${maxAttempts})`;
+        task.lastMessage = `${options.message}; retrying transient-model failure (${attempt}/${maxAttempts})`;
         return true;
     }
     task.status = "failed";
     task.statusDetail = task.launchRetry.reason ?? "model_exhausted";
     task.exitCode = 1;
     task.completedAt = nowIso();
-    task.lastMessage = `${options.message}; transient model failure retries exhausted (${maxAttempts})`;
+    task.lastMessage = `${options.message}; transient-model failure retries exhausted (${maxAttempts})`;
     return true;
 }
 function retryOrFailArtifactGraphTask(task, options) {

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowModelInfo, WorkflowRuntimeDefaults, WorkflowRuntimeThinkingResolution } from "./workflow-runtime.js";
 export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
 export declare const FAST_MODES: readonly ["inherit", "off"];
 export declare const APPROVAL_MODES: readonly ["non-interactive", "on-request"];
@@ -249,6 +250,7 @@ export interface PermissionPreview {
 export interface CompiledTaskRuntime {
     model?: string;
     thinking?: ThinkingLevel;
+    thinkingResolution?: WorkflowRuntimeThinkingResolution;
     fast?: FastMode;
     approvalMode: ApprovalMode;
     tools?: string[];
@@ -418,6 +420,8 @@ export interface CompiledDynamicWorkflowTask {
     helpers: Record<string, CompiledDynamicWorkflowHelper>;
     workflows: Record<string, CompiledDynamicNestedWorkflow>;
     decisionLoop?: CompiledDynamicDecisionLoop;
+    runtimeOverrides?: WorkflowRuntimeDefaults;
+    availableModels?: WorkflowModelInfo[];
 }
 export interface CompiledArtifactGraphTask {
     enabled: true;
@@ -505,6 +509,7 @@ export interface WorkflowTaskRunRecord {
     runtime: {
         model?: string;
         thinking?: ThinkingLevel;
+        thinkingResolution?: WorkflowRuntimeThinkingResolution;
         fast?: FastMode;
         approvalMode: ApprovalMode;
         maxRuntimeMs?: number;

package/dist/workflow-progress-health.d.ts

@@ -0,0 +1,37 @@
+import type { TaskRunStatus, WorkflowRunRecord, WorkflowTaskRunRecord } from "./types.js";
+export type WorkflowHealthState = "completed" | "pending" | "active" | "long-tail" | "stalled" | "likely-stuck" | "needs-action";
+export type WorkflowHealthTone = "success" | "accent" | "warning" | "error" | "dim";
+export type WorkflowDurationClass = "short" | "medium" | "long";
+export type WorkflowHealthSuggestion = "wait" | "inspect" | "resume" | "review";
+export interface WorkflowHealthTaskSummary {
+    taskId?: string;
+    displayName?: string;
+    stageId?: string;
+    status?: TaskRunStatus;
+    elapsedMs?: number;
+}
+export interface WorkflowProgressHealth {
+    state: WorkflowHealthState;
+    label: string;
+    summary: string;
+    tone: WorkflowHealthTone;
+    suggestion: WorkflowHealthSuggestion;
+    reason: string;
+    durationClass?: WorkflowDurationClass;
+    currentTask?: WorkflowHealthTaskSummary;
+    lastActivityAt?: string;
+    lastActivityAgeMs?: number;
+    heartbeatAt?: string;
+    heartbeatAgeMs?: number;
+}
+type TaskHealthInput = Pick<WorkflowTaskRunRecord, "taskId" | "specId" | "displayName" | "status" | "statusDetail" | "stageId" | "kind" | "startedAt" | "lastMessage" | "runtime" | "backendHandle" | "pid">;
+type RunHealthInput = Pick<WorkflowRunRecord, "status" | "taskSummary" | "createdAt" | "updatedAt"> & {
+    tasks?: TaskHealthInput[];
+};
+export interface WorkflowHealthOptions {
+    nowMs?: number;
+}
+export declare function diagnoseWorkflowRunHealth(run: RunHealthInput, options?: WorkflowHealthOptions): WorkflowProgressHealth;
+export declare function diagnoseWorkflowTaskHealth(task: TaskHealthInput, run?: Pick<WorkflowRunRecord, "updatedAt">, options?: WorkflowHealthOptions): WorkflowProgressHealth;
+export declare function classifyWorkflowTaskDuration(task: Pick<WorkflowTaskRunRecord, "stageId" | "displayName" | "specId" | "kind" | "statusDetail" | "runtime">): WorkflowDurationClass;
+export {};

package/dist/workflow-progress-health.js

@@ -0,0 +1,296 @@
+const ACTIVE_ACTIVITY_MS = 2 * 60_000;
+const LONG_TAIL_ELAPSED_MS = 8 * 60_000;
+const STALL_BY_DURATION = {
+    short: 5 * 60_000,
+    medium: 10 * 60_000,
+    long: 20 * 60_000,
+};
+const STUCK_BY_DURATION = {
+    short: 15 * 60_000,
+    medium: 30 * 60_000,
+    long: 60 * 60_000,
+};
+export function diagnoseWorkflowRunHealth(run, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const runningTask = currentRunningTask(run.tasks ?? []);
+    if (runningTask)
+        return diagnoseWorkflowTaskHealth(runningTask, run, { nowMs });
+    const problem = (run.tasks ?? []).find((task) => isProblemStatus(task.status));
+    if (problem)
+        return problemRunHealth(problem, nowMs);
+    if (isProblemStatus(run.status))
+        return problemWorkflowHealth(run.status);
+    if (run.status === "completed")
+        return completedWorkflowHealth();
+    return waitingWorkflowHealth(run, nowMs);
+}
+export function diagnoseWorkflowTaskHealth(task, run, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    if (task.status !== "running")
+        return terminalTaskHealth(task, nowMs);
+    return runningTaskHealth(runningContext(task, run, nowMs));
+}
+export function classifyWorkflowTaskDuration(task) {
+    const text = [
+        task.stageId,
+        task.displayName,
+        task.specId,
+        task.kind,
+        task.statusDetail,
+    ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+    if (/\b(render|helper|support|schema|partition|gate)\b/.test(text))
+        return "short";
+    if (/\b(research|audit|synthesis|review|verify|verifier|normalize|plan|impact|spec)\b/.test(text))
+        return "long";
+    const maxRuntimeMs = task.runtime?.maxRuntimeMs;
+    if (maxRuntimeMs !== undefined && Number.isFinite(maxRuntimeMs)) {
+        if (maxRuntimeMs <= 5 * 60_000)
+            return "short";
+        if (maxRuntimeMs >= 60 * 60_000)
+            return "long";
+    }
+    return "medium";
+}
+function currentRunningTask(tasks) {
+    return tasks
+        .filter((task) => task.status === "running")
+        .sort((left, right) => (parseTime(left.startedAt) ?? Number.POSITIVE_INFINITY) -
+        (parseTime(right.startedAt) ?? Number.POSITIVE_INFINITY))[0];
+}
+function completedWorkflowHealth() {
+    return {
+        state: "completed",
+        label: "completed",
+        summary: "run completed",
+        tone: "success",
+        suggestion: "review",
+        reason: "all tasks reached a terminal successful state",
+    };
+}
+function problemWorkflowHealth(status) {
+    return {
+        state: "needs-action",
+        label: "needs action",
+        summary: `run ${status}`,
+        tone: "error",
+        suggestion: "inspect",
+        reason: `workflow status is ${status}`,
+    };
+}
+function problemRunHealth(task, nowMs) {
+    return {
+        state: "needs-action",
+        label: "needs action",
+        summary: `${task.displayName ?? task.taskId ?? "task"} needs attention`,
+        tone: "error",
+        suggestion: "inspect",
+        reason: task.lastMessage ?? task.statusDetail ?? "task did not complete",
+        currentTask: taskSummary(task, nowMs),
+    };
+}
+function waitingWorkflowHealth(run, nowMs) {
+    const hasPending = run.taskSummary.pending > 0;
+    return {
+        state: hasPending ? "pending" : "active",
+        label: hasPending ? "pending" : "active",
+        summary: hasPending
+            ? "waiting for the next schedulable task"
+            : "run is active",
+        tone: hasPending ? "dim" : "accent",
+        suggestion: "wait",
+        reason: hasPending
+            ? "no task is currently running"
+            : "workflow is still in progress",
+        lastActivityAt: run.updatedAt,
+        lastActivityAgeMs: ageMs(run.updatedAt, nowMs),
+    };
+}
+function runningTaskHealth(context) {
+    return (runtimeExceededHealth(context) ??
+        staleRunningHealth(context) ??
+        longTailHealth(context) ??
+        activeRunningHealth(context));
+}
+function runtimeExceededHealth(context) {
+    const maxRuntimeMs = context.task.runtime?.maxRuntimeMs;
+    const hasElapsed = context.elapsedMs !== undefined;
+    const hasBudget = maxRuntimeMs !== undefined && Number.isFinite(maxRuntimeMs);
+    if (!hasElapsed || !hasBudget)
+        return undefined;
+    if (maxRuntimeMs <= 0 || context.elapsedMs <= maxRuntimeMs)
+        return undefined;
+    return runningHealth(context, {
+        state: "likely-stuck",
+        label: "runtime exceeded",
+        summary: "task exceeded its runtime budget",
+        tone: "error",
+        suggestion: "resume",
+        reason: "elapsed time is past runtime.maxRuntimeMs",
+    });
+}
+function staleRunningHealth(context) {
+    if (context.staleMs >= STUCK_BY_DURATION[context.durationClass] &&
+        !context.hasBackendSignal) {
+        return runningHealth(context, {
+            state: "likely-stuck",
+            label: "likely stuck",
+            summary: "no fresh backend or activity signal",
+            tone: "error",
+            suggestion: "resume",
+            reason: "running task has no backend signal and activity is stale",
+        });
+    }
+    if (context.staleMs < STALL_BY_DURATION[context.durationClass])
+        return undefined;
+    return runningHealth(context, {
+        state: "stalled",
+        label: "possibly stalled",
+        summary: "no recent visible progress",
+        tone: "warning",
+        suggestion: "inspect",
+        reason: context.hasBackendSignal
+            ? "backend signal exists, but activity is stale"
+            : "activity is stale",
+    });
+}
+function longTailHealth(context) {
+    const isLongTail = context.durationClass === "long" &&
+        context.elapsedMs !== undefined &&
+        context.elapsedMs >= LONG_TAIL_ELAPSED_MS;
+    if (!isLongTail)
+        return undefined;
+    return runningHealth(context, {
+        state: "long-tail",
+        label: "long-tail active",
+        summary: "slow task with fresh liveness signals",
+        tone: "accent",
+        suggestion: "wait",
+        reason: context.staleMs <= ACTIVE_ACTIVITY_MS
+            ? "liveness signal is fresh"
+            : "long-running stage is still within the stale threshold",
+    });
+}
+function activeRunningHealth(context) {
+    return runningHealth(context, {
+        state: "active",
+        label: "active",
+        summary: "task is running",
+        tone: "accent",
+        suggestion: "wait",
+        reason: context.staleMs <= ACTIVE_ACTIVITY_MS
+            ? "liveness signal is fresh"
+            : "activity remains within the expected window",
+    });
+}
+function runningContext(task, run, nowMs) {
+    const durationClass = classifyWorkflowTaskDuration(task);
+    const startedAtMs = parseTime(task.startedAt);
+    const heartbeatAt = parseHeartbeatAt(task.lastMessage);
+    const activityAt = latestIso([heartbeatAt, run?.updatedAt, task.startedAt]);
+    const lastActivityAgeMs = ageMs(activityAt, nowMs);
+    return {
+        task,
+        nowMs,
+        durationClass,
+        elapsedMs: startedAtMs === undefined ? undefined : Math.max(0, nowMs - startedAtMs),
+        activityAt,
+        lastActivityAgeMs,
+        heartbeatAt,
+        heartbeatAgeMs: ageMs(heartbeatAt, nowMs),
+        hasBackendSignal: Boolean(task.backendHandle || task.pid || heartbeatAt),
+        staleMs: lastActivityAgeMs ?? Number.POSITIVE_INFINITY,
+    };
+}
+function terminalTaskHealth(task, nowMs) {
+    if (task.status === "completed" || task.status === "skipped") {
+        return {
+            state: "completed",
+            label: task.status === "skipped" ? "skipped" : "completed",
+            summary: task.status === "skipped" ? "task skipped" : "task completed",
+            tone: "success",
+            suggestion: "review",
+            reason: task.statusDetail,
+            currentTask: taskSummary(task, nowMs),
+        };
+    }
+    if (task.status === "pending") {
+        return {
+            state: "pending",
+            label: "pending",
+            summary: "waiting for dependencies or scheduler",
+            tone: "dim",
+            suggestion: "wait",
+            reason: task.statusDetail,
+            currentTask: taskSummary(task, nowMs),
+        };
+    }
+    return {
+        state: "needs-action",
+        label: "needs action",
+        summary: `${task.status} task needs attention`,
+        tone: "error",
+        suggestion: "inspect",
+        reason: task.lastMessage ?? task.statusDetail,
+        currentTask: taskSummary(task, nowMs),
+    };
+}
+function runningHealth(context, health) {
+    return {
+        ...health,
+        durationClass: context.durationClass,
+        currentTask: taskSummary(context.task, context.nowMs),
+        lastActivityAt: context.activityAt,
+        lastActivityAgeMs: context.lastActivityAgeMs,
+        heartbeatAt: context.heartbeatAt,
+        heartbeatAgeMs: context.heartbeatAgeMs,
+    };
+}
+function taskSummary(task, nowMs) {
+    const startedAtMs = parseTime(task.startedAt);
+    return {
+        taskId: task.taskId,
+        displayName: task.displayName,
+        stageId: task.stageId,
+        status: task.status,
+        ...(startedAtMs === undefined
+            ? {}
+            : { elapsedMs: Math.max(0, nowMs - startedAtMs) }),
+    };
+}
+function isProblemStatus(status) {
+    return (status === "failed" || status === "blocked" || status === "interrupted");
+}
+function parseHeartbeatAt(message) {
+    if (!message)
+        return undefined;
+    const match = /heartbeat\s+(\d{4}-\d{2}-\d{2}T\S+?Z)/i.exec(message);
+    if (!match)
+        return undefined;
+    const value = match[1];
+    return parseTime(value) === undefined ? undefined : value;
+}
+function latestIso(values) {
+    let latest;
+    let latestMs = Number.NEGATIVE_INFINITY;
+    for (const value of values) {
+        const time = parseTime(value);
+        if (time === undefined || time <= latestMs)
+            continue;
+        latest = value;
+        latestMs = time;
+    }
+    return latest;
+}
+function ageMs(value, nowMs) {
+    const time = parseTime(value);
+    return time === undefined ? undefined : Math.max(0, nowMs - time);
+}
+function parseTime(value) {
+    if (!value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}

package/dist/workflow-runtime.d.ts

@@ -11,9 +11,15 @@ export interface WorkflowRuntimeDefaults {
     model?: string;
     thinking?: ThinkingLevel;
 }
+export interface WorkflowRuntimeThinkingResolution {
+    requested?: ThinkingLevel;
+    resolved?: ThinkingLevel;
+    reason?: string;
+}
 export interface WorkflowRuntimeResolutionInput {
     model?: string;
     thinking?: ThinkingLevel;
+    thinkingResolution?: WorkflowRuntimeThinkingResolution;
 }
 export interface WorkflowRuntimeResolutionContext {
     taskKey: string;
@@ -29,6 +35,8 @@ export interface ResolveWorkflowRuntimeOptions {
     availableModels?: WorkflowModelInfo[];
     prompt?: WorkflowRuntimePrompt;
 }
+export type WorkflowRuntimeLayer = WorkflowRuntimeDefaults | undefined;
+export declare function selectWorkflowRuntime(...layers: WorkflowRuntimeLayer[]): WorkflowRuntimeResolutionInput;
 export declare function toWorkflowModelInfo(model: {
     provider: string;
     id: string;

package/dist/workflow-runtime.js

@@ -1,4 +1,34 @@
 import { THINKING_LEVELS } from "./types.js";
+export function selectWorkflowRuntime(...layers) {
+    const modelLayer = layers.find((layer) => modelOf(layer));
+    const model = modelOf(modelLayer);
+    let thinking;
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.thinking) {
+            thinking = layer.thinking;
+            break;
+        }
+        const layerModel = modelOf(layer);
+        const modelThinking = layerModel
+            ? splitKnownThinkingSuffix(layerModel).thinking
+            : undefined;
+        if (modelThinking) {
+            thinking = modelThinking;
+            break;
+        }
+    }
+    return {
+        ...(model ? { model } : {}),
+        ...(thinking ? { thinking } : {}),
+    };
+}
+function modelOf(layer) {
+    return typeof layer?.model === "string" && layer.model.trim()
+        ? layer.model.trim()
+        : undefined;
+}
 export function toWorkflowModelInfo(model) {
     return {
         provider: model.provider,
@@ -15,10 +45,13 @@ export async function resolveWorkflowRuntime(runtime, context, options) {
         : { baseModel: undefined, thinking: undefined };
     const model = await resolveModel(baseModel, context, options);
     const effectiveThinking = runtime.thinking ?? thinking ?? options.defaults?.thinking;
-    const resolvedThinking = await resolveThinking(model, effectiveThinking, context, options);
+    const thinkingResolution = await resolveThinking(model, effectiveThinking, context, options);
     return {
         ...(model ? { model } : {}),
-        ...(resolvedThinking ? { thinking: resolvedThinking } : {}),
+        ...(thinkingResolution?.resolved
+            ? { thinking: thinkingResolution.resolved }
+            : {}),
+        ...(thinkingResolution ? { thinkingResolution } : {}),
     };
 }
 export function splitKnownThinkingSuffix(model) {
@@ -101,21 +134,41 @@ async function resolveThinking(modelId, requested, context, options) {
         return undefined;
     const model = findModelInfo(modelId, options.availableModels ?? []);
     const supported = getSupportedThinkingLevels(model);
-    if (supported.includes(requested))
-        return requested;
-    if (!options.prompt) {
-        const modelLabel = modelId ?? "selected model";
-        throw new Error(`${modelLabel} does not support reasoning level "${requested}" for ${context.taskKey}. Supported: ${supported.join(", ") || "none"}`);
+    if (supported.includes(requested)) {
+        return { requested, resolved: requested };
     }
     if (supported.length === 0) {
         throw new Error(`${modelId ?? "selected model"} does not expose any supported reasoning levels for ${context.taskKey}`);
     }
-    const selected = await options.prompt.select(`${modelId ?? "Selected model"} does not support reasoning "${requested}" for ${context.taskKey}. Choose a supported level.`, supported);
+    const downgradeOptions = lowerOrEqualSupportedThinking(requested, supported);
+    if (downgradeOptions.length === 0) {
+        const modelLabel = modelId ?? "selected model";
+        throw new Error(`${modelLabel} does not support reasoning level "${requested}" for ${context.taskKey}, and no lower-or-equal fallback is available. Supported: ${supported.join(", ") || "none"}`);
+    }
+    if (!options.prompt) {
+        const resolved = downgradeOptions[downgradeOptions.length - 1];
+        return {
+            requested,
+            resolved,
+            reason: `requested ${requested} is unsupported by ${modelId ?? "selected model"}; using ${resolved}`,
+        };
+    }
+    const selected = await options.prompt.select(`${modelId ?? "Selected model"} does not support reasoning "${requested}" for ${context.taskKey}. Choose a supported lower-or-equal level.`, downgradeOptions);
     if (!selected)
         throw new Error(`Reasoning selection cancelled for ${context.taskKey}`);
-    if (!isThinkingLevel(selected))
+    if (!isThinkingLevel(selected) || !downgradeOptions.includes(selected))
         throw new Error(`Invalid reasoning selection "${selected}" for ${context.taskKey}`);
-    return selected;
+    return {
+        requested,
+        resolved: selected,
+        reason: `selected supported reasoning ${selected} for unsupported request ${requested}`,
+    };
+}
+function lowerOrEqualSupportedThinking(requested, supported) {
+    const requestedIndex = THINKING_LEVELS.indexOf(requested);
+    if (requestedIndex < 0)
+        return [];
+    return THINKING_LEVELS.slice(0, requestedIndex + 1).filter((level) => supported.includes(level));
 }
 function findModelInfo(modelId, available) {
     if (!modelId)