@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/dist/src/pi-runtime-runner.js

@@ -0,0 +1,505 @@
+import { createPiRuntimeSessionAdapter, isEmptyAbortedAssistant, isTurnBoundaryStart, isTurnEnd, normalizePiMessage } from "./pi-runtime-adapter.js";
+import { RuntimeAgentProviderError } from "./runtime/agent-runner.js";
+import { errorText, jsonValue } from "./utils.js";
+import { WorkflowError } from "./types.js";
+const providerContinuationPrompt = "The provider error was transient. Continue the task from your current state.";
+const handoffContinuationPrompt = "Continue the task from the current session state.";
+export function runtimeToolFromPiDefinition(definition, context) {
+    const parameters = definition.parameters;
+    if (!jsonValue(parameters))
+        throw new WorkflowError("INVALID_METADATA", `Pi tool ${definition.name} has a non-JSON parameter schema`);
+    return {
+        name: definition.name,
+        description: definition.description,
+        parameters: parameters,
+        async execute(call) {
+            const result = await definition.execute(call.id, call.input, call.signal, undefined, context);
+            const isError = typeof result === "object" && result !== null && "isError" in result && result.isError === true;
+            if (!jsonValue(result))
+                throw new WorkflowError("RESULT_INVALID", `Pi tool ${definition.name} returned a non-JSON result`);
+            return { value: runtimeValue(result), ...(isError ? { isError: true } : {}) };
+        },
+    };
+}
+function hasToolCall(message) {
+    return typeof message === "object" && message !== null && Array.isArray(message.content) && message.content.some((part) => typeof part === "object" && part !== null && part.type === "toolCall");
+}
+function isHandoffAbort(message) { return message?.role === "assistant" && message.stopReason === "error" && Array.isArray(message.content) && message.content.length === 0 && typeof message.errorMessage === "string" && /abort/i.test(message.errorMessage); }
+function isTerminalAssistant(message) { return Boolean(message) && message?.stopReason !== "aborted" && !hasToolCall(message); }
+function runtimeUsage(session) {
+    const stats = session.getSessionStats();
+    const values = [stats.tokens.input, stats.tokens.output, stats.tokens.cacheRead, stats.tokens.cacheWrite, stats.cost];
+    if (values.some((value) => !Number.isFinite(value)))
+        return { availability: "unavailable" };
+    return { availability: "complete", input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, costUsd: stats.cost };
+}
+function providerFailure(session, message) {
+    if (message?.stopReason !== "error")
+        return undefined;
+    const state = session.getState();
+    return { provider: state.model.provider, model: state.model.model, error: message.errorMessage ?? "Workflow agent session ended with a terminal provider error" };
+}
+function runtimeValue(value) { return value; }
+function unstructuredResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.result !== "string")
+        return undefined;
+    return value.result;
+}
+function remaining(timeoutMs, started) { return timeoutMs === null || timeoutMs === undefined ? timeoutMs : Math.max(1, timeoutMs - (Date.now() - started)); }
+function providerLimited(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return candidate.status === 429 || candidate.code === 429 || candidate.code === "rate_limit_exceeded" || candidate.code === "RATE_LIMITED";
+}
+function isToolError(result) { return typeof result === "object" && result !== null && "isError" in result && result.isError === true; }
+function piToolFromRuntime(definition, signal) {
+    if (typeof definition.name !== "string" || !definition.name || typeof definition.description !== "string" || !jsonValue(definition.parameters) || typeof definition.execute !== "function")
+        throw new WorkflowError("INVALID_METADATA", `Runtime tool ${definition.name || "<unnamed>"} is not JSON-compatible`);
+    return {
+        name: definition.name,
+        label: definition.name,
+        description: definition.description,
+        parameters: definition.parameters,
+        async execute(toolCallId, input, toolSignal) {
+            if (!jsonValue(input))
+                throw new WorkflowError("INVALID_METADATA", `Runtime tool ${definition.name} received a non-JSON input`);
+            const result = await definition.execute({ id: toolCallId, input: runtimeValue(input), signal: toolSignal ?? signal });
+            if (!jsonValue(result.value))
+                throw new WorkflowError("RESULT_INVALID", `Runtime tool ${definition.name} returned a non-JSON result`);
+            return { content: [{ type: "text", text: JSON.stringify(result.value) }], details: result.value, ...(result.isError ? { isError: true } : {}) };
+        },
+    };
+}
+function preparedForRuntimeRequest(prepared, customTools, signal, captureResult, resultTool = prepared.resultTool) {
+    const names = new Set([...prepared.tools, ...(prepared.customTools ?? []).map(({ name }) => name), ...(resultTool ? [resultTool.name] : [])]);
+    const additions = customTools.map((tool) => {
+        if (names.has(tool.name))
+            throw new WorkflowError("INTERNAL_ERROR", `Runtime tool ${tool.name} conflicts with the prepared Pi tool policy`);
+        names.add(tool.name);
+        return piToolFromRuntime(tool, signal);
+    });
+    const nativeResultTool = resultTool;
+    const wrappedResultTool = nativeResultTool ? Object.freeze({
+        ...nativeResultTool,
+        async execute(toolCallId, input, toolSignal, onUpdate, context) {
+            const result = await nativeResultTool.execute(toolCallId, input, toolSignal, onUpdate, context);
+            if (!isToolError(result) && jsonValue(input))
+                captureResult(runtimeValue(structuredClone(input)));
+            return result;
+        },
+    }) : undefined;
+    if (additions.length === 0 && wrappedResultTool === undefined)
+        return prepared;
+    return Object.freeze({
+        ...prepared,
+        ...(additions.length === 0 ? {} : { customTools: Object.freeze([...(prepared.customTools ?? []), ...additions]) }),
+        ...(wrappedResultTool === undefined ? {} : { resultTool: wrappedResultTool }),
+    });
+}
+export function isRuntimeAgentProviderError(error) { return error instanceof RuntimeAgentProviderError; }
+export function normalizePiRuntimeError(error, signal, setupFailed = false) {
+    if (error instanceof WorkflowError)
+        return error;
+    if (error instanceof RuntimeAgentProviderError)
+        return new WorkflowError("AGENT_FAILED", error.failure.error);
+    return new WorkflowError(signal.aborted && setupFailed ? "CANCELLED" : "AGENT_FAILED", errorText(error));
+}
+async function withTimeout(work, timeoutMs, signal, session) {
+    if (signal.aborted)
+        throw new WorkflowError("CANCELLED", "Agent cancelled");
+    let timer;
+    let abort;
+    const state = { interrupted: false };
+    const timeout = timeoutMs === undefined || timeoutMs === null ? new Promise(() => undefined) : new Promise((_, reject) => {
+        timer = setTimeout(() => { state.interrupted = true; reject(new WorkflowError("AGENT_TIMEOUT", "Agent attempt timed out")); }, timeoutMs);
+    });
+    const cancelled = new Promise((_, reject) => {
+        abort = () => { state.interrupted = true; reject(new WorkflowError("CANCELLED", "Agent cancelled")); };
+        signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+        return await Promise.race([work, timeout, cancelled]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (abort)
+            signal.removeEventListener("abort", abort);
+        if (state.interrupted)
+            await session.abort();
+    }
+}
+async function promptWithProviderPause(session, textValue, timeoutMs, started, request) {
+    const promptTimeout = remaining(timeoutMs, started);
+    for (;;) {
+        try {
+            return await withTimeout(session.prompt(textValue), promptTimeout, request.signal, session);
+        }
+        catch (error) {
+            if (!request.onProviderLimit || !providerLimited(error))
+                throw error;
+            await request.onProviderLimit();
+        }
+    }
+}
+export class PiRuntimeAgentRunner {
+    id = "pi";
+    // Prepared Pi definitions remain native; request-neutral tools are adapted before session creation.
+    capabilities = { customTools: true, structuredResults: true, steering: true, handoff: true, usage: "complete" };
+    #options;
+    constructor(options) { this.#options = options; }
+    run(request) { return this.#runOnce(request); }
+    async #runOnce(request) {
+        if (request.signal.aborted)
+            throw new WorkflowError("CANCELLED", "Agent cancelled");
+        if (request.timeoutMs !== undefined && request.timeoutMs !== null && (!Number.isInteger(request.timeoutMs) || request.timeoutMs <= 0))
+            throw new WorkflowError("INVALID_METADATA", "timeoutMs must be null or a positive integer");
+        const started = Date.now();
+        const prepared = this.#options.prepared;
+        if (request.cwd !== prepared.cwd || request.model.provider !== prepared.model.provider || request.model.model !== prepared.model.model || request.model.thinking !== prepared.model.thinking || request.enabledTools.length !== prepared.tools.length || request.enabledTools.some((tool, index) => tool !== prepared.tools[index]))
+            throw new WorkflowError("INTERNAL_ERROR", "Pi runtime request does not match the prepared session");
+        let session;
+        let structuredResult;
+        const resultTool = prepared.resultTool;
+        if (!resultTool)
+            throw new WorkflowError("INTERNAL_ERROR", "Workflow agent session is missing its workflow_result tool");
+        const preparedForSession = preparedForRuntimeRequest(prepared, request.customTools, request.signal, (value) => { structuredResult = value; }, resultTool);
+        const callbacks = this.#options.callbacks;
+        const handoff = this.#options.handoff;
+        let adapter;
+        let unsubscribe;
+        let disposeStarted = false;
+        let sessionReady = false;
+        let successfulInvocation = false;
+        let progress = Promise.resolve();
+        const progressState = { failed: false, error: undefined };
+        const eventNotifications = new Set();
+        let systemPromptTurn = 0;
+        let systemPromptWrite = Promise.resolve();
+        let systemPromptWriteError;
+        let turnStarted = false;
+        let turnPolicyFailure;
+        let lastAssistant;
+        let handoffBoundaryAssistant;
+        let handoffAbortHandled = false;
+        const hasResult = () => structuredResult !== undefined;
+        // Session event observations are best effort, matching the legacy synchronous subscription.
+        const trackEvent = (notification) => {
+            eventNotifications.add(notification);
+            void notification.then(() => { eventNotifications.delete(notification); }, () => { eventNotifications.delete(notification); });
+        };
+        const flushEvents = async () => {
+            while (eventNotifications.size > 0) {
+                const pending = [...eventNotifications];
+                await Promise.allSettled(pending);
+                for (const notification of pending)
+                    eventNotifications.delete(notification);
+            }
+        };
+        const report = (value) => {
+            const progressHandler = request.onProgress;
+            if (!progressHandler || progressState.failed)
+                return;
+            const materialized = typeof value === "function" ? value() : value;
+            progress = progress.then(() => {
+                if (progressState.failed)
+                    return;
+                return progressHandler(materialized);
+            }).then(() => undefined).catch((error) => {
+                if (progressState.failed)
+                    return;
+                progressState.failed = true;
+                progressState.error = error;
+                if (session)
+                    void session.abort().catch(() => undefined);
+            });
+        };
+        const flushProgress = async () => {
+            await progress;
+            if (progressState.failed)
+                throw progressState.error;
+        };
+        const throwIfProgressFailed = () => { if (progressState.failed)
+            throw progressState.error; };
+        const recordSystemPrompt = (entry) => {
+            systemPromptWrite = systemPromptWrite.then(() => callbacks?.onSystemPrompt?.(entry)).catch((error) => { systemPromptWriteError ??= error; });
+        };
+        const flushSystemPrompts = async () => {
+            await systemPromptWrite;
+            if (systemPromptWriteError !== undefined)
+                throw new WorkflowError("INTERNAL_ERROR", `Failed to persist effective system prompt: ${errorText(systemPromptWriteError)}`);
+        };
+        const policy = request.turnPolicy;
+        const turnPolicyError = (error) => error instanceof WorkflowError ? error : new WorkflowError("BUDGET_EXHAUSTED", errorText(error));
+        const beginTurn = (abortOnFailure = true) => {
+            if (!policy || turnStarted)
+                return;
+            try {
+                policy.beforeTurn();
+                turnStarted = true;
+            }
+            catch (error) {
+                turnPolicyFailure ??= turnPolicyError(error);
+                if (abortOnFailure && session)
+                    void session.abort().catch(() => undefined);
+            }
+        };
+        const throwIfTurnPolicyFailed = () => { const failure = turnPolicyFailure; if (failure)
+            throw failure; };
+        const completeTurn = (final, steerInstruction, force = false) => {
+            if (!policy) {
+                turnStarted = false;
+                return;
+            }
+            if (turnPolicyFailure && !force) {
+                turnStarted = false;
+                return;
+            }
+            try {
+                const instruction = policy.afterTurn(runtimeUsage(session), final, steerInstruction);
+                if (steerInstruction && instruction && session)
+                    void session.steer(instruction).catch(() => undefined);
+            }
+            catch (error) {
+                turnPolicyFailure ??= turnPolicyError(error);
+                if (session)
+                    void session.abort().catch(() => undefined);
+            }
+            turnStarted = false;
+        };
+        const acceptAssistant = (candidate) => {
+            if (isEmptyAbortedAssistant(candidate)) {
+                const previous = session?.getLastAssistant();
+                if (previous && !isEmptyAbortedAssistant(previous))
+                    lastAssistant = previous;
+            }
+            else if (candidate)
+                lastAssistant = candidate;
+        };
+        const throwIfCancelled = () => { if (request.signal.aborted)
+            throw new WorkflowError("CANCELLED", "Agent cancelled"); };
+        try {
+            session = await this.#options.transport.createSession(preparedForSession, this.#options.context);
+            if (session.reference.transport !== this.#options.transport.id) {
+                const actualTransport = session.reference.transport;
+                disposeStarted = true;
+                await session.dispose();
+                session = undefined;
+                throw new WorkflowError("INTERNAL_ERROR", `Agent transport ${this.#options.transport.id} created a session for ${actualTransport}`);
+            }
+            sessionReady = true;
+            const createdAdapter = createPiRuntimeSessionAdapter(session, handoff);
+            adapter = createdAdapter;
+            await callbacks?.onSession?.(session, handoff, preparedForSession);
+            const activeSession = session;
+            const runtimeHandoff = request.handoff ?? adapter.handoff;
+            const preparedTools = new Set([...preparedForSession.tools, ...(preparedForSession.customTools ?? []).map(({ name }) => name), ...(preparedForSession.resultTool ? [preparedForSession.resultTool.name] : [])]);
+            if (session.getState().tools.some((tool) => !preparedTools.has(tool)))
+                throw new WorkflowError("INTERNAL_ERROR", `Agent transport ${this.#options.transport.id} widened the prepared tool policy`);
+            await callbacks?.onSessionReady?.();
+            const handleSessionEvent = async (event) => {
+                const observation = adapter?.observe(event);
+                if (!observation || !session)
+                    return;
+                const observedEvent = observation.event;
+                if (isTurnEnd(observedEvent.type))
+                    handoffBoundaryAssistant = observedEvent.message?.role === "assistant" ? observedEvent.message : session.getLastAssistant() ?? lastAssistant;
+                if (runtimeHandoff !== adapter?.handoff)
+                    runtimeHandoff.observe({ type: observedEvent.type });
+                if (isTurnEnd(observedEvent.type) && runtimeHandoff.state === "takeover-pending")
+                    void session.abort().catch(() => undefined);
+                if (observedEvent.type === "agent_start" && session.getState().systemPrompt !== undefined) {
+                    systemPromptTurn += 1;
+                    recordSystemPrompt({ sessionId: session.reference.sessionId, turn: systemPromptTurn, prompt: session.getState().systemPrompt ?? "" });
+                }
+                if (isTurnBoundaryStart(observedEvent.type) || (observedEvent.type === "message_start" && observedEvent.message?.role === "assistant"))
+                    beginTurn();
+                if (observedEvent.type === "message_end" && observedEvent.message?.role === "assistant") {
+                    acceptAssistant(observedEvent.message);
+                    const final = !hasToolCall(observedEvent.message) || hasResult();
+                    completeTurn(final, !final);
+                }
+                if (observation.report)
+                    report(() => observation.progress);
+            };
+            if (session.subscribeAsync)
+                unsubscribe = session.subscribeAsync((event) => { const notification = handleSessionEvent(event); trackEvent(notification); return notification; });
+            else
+                unsubscribe = session.subscribe((event) => { trackEvent(handleSessionEvent(event)); });
+            report(() => createdAdapter.snapshot(false));
+            await request.onControl?.({ handoff: runtimeHandoff, steer: (message) => activeSession.steer(message) });
+            const promptOnce = async (prompt, turnAlreadyStarted = false) => {
+                if (!turnAlreadyStarted)
+                    beginTurn();
+                throwIfTurnPolicyFailed();
+                const response = await promptWithProviderPause(session, prompt, request.timeoutMs, started, request);
+                acceptAssistant(normalizePiMessage(response.assistant));
+                await flushEvents();
+            };
+            const recoverTerminal = async () => {
+                let continued = false;
+                for (;;) {
+                    if (hasResult())
+                        return continued;
+                    const failure = providerFailure(session, lastAssistant);
+                    if (!failure)
+                        return continued;
+                    if (!request.onProviderError)
+                        throw new RuntimeAgentProviderError(failure, undefined, false);
+                    let recovery;
+                    try {
+                        recovery = await request.onProviderError(failure);
+                    }
+                    catch (error) {
+                        throw new RuntimeAgentProviderError({ ...failure, error: `${failure.error} (provider recovery failed: ${errorText(error)})` }, undefined, true);
+                    }
+                    if (recovery !== "retry")
+                        throw new RuntimeAgentProviderError(failure, recovery, true);
+                    continued = true;
+                    try {
+                        await promptOnce(providerContinuationPrompt);
+                    }
+                    catch (error) {
+                        acceptAssistant(session?.getLastAssistant() ?? lastAssistant);
+                        if (!hasResult())
+                            throw error;
+                    }
+                }
+            };
+            const promptAndRecover = async (prompt, turnAlreadyStarted = false) => {
+                let promptFailed = false;
+                let promptError;
+                try {
+                    await promptOnce(prompt, turnAlreadyStarted);
+                }
+                catch (error) {
+                    acceptAssistant(session?.getLastAssistant() ?? lastAssistant);
+                    promptFailed = true;
+                    promptError = error;
+                }
+                const handoffWasAttempted = runtimeHandoff.state !== "local-running";
+                throwIfCancelled();
+                throwIfProgressFailed();
+                const suppressHandoffAbort = handoffWasAttempted && !handoffAbortHandled && isHandoffAbort(lastAssistant);
+                if (suppressHandoffAbort)
+                    handoffAbortHandled = true;
+                const recovered = suppressHandoffAbort ? false : await recoverTerminal();
+                const preHandoffAssistant = handoffBoundaryAssistant;
+                handoffBoundaryAssistant = undefined;
+                throwIfCancelled();
+                await runtimeHandoff.waitForResume();
+                throwIfCancelled();
+                const resumed = session?.getLastAssistant();
+                const preservePreHandoffResult = runtimeHandoff.transferred && isTerminalAssistant(preHandoffAssistant);
+                if (preservePreHandoffResult)
+                    lastAssistant = preHandoffAssistant;
+                else
+                    acceptAssistant(resumed);
+                let handoffError;
+                let handoffRecovered = false;
+                if (runtimeHandoff.transferred && !preservePreHandoffResult && !hasResult() && (!resumed || resumed.stopReason === "aborted" || isHandoffAbort(resumed) || hasToolCall(resumed))) {
+                    try {
+                        await promptOnce(handoffContinuationPrompt);
+                    }
+                    catch (error) {
+                        handoffError = error;
+                    }
+                }
+                if (handoffWasAttempted && !runtimeHandoff.transferred && promptFailed && !hasResult()) {
+                    try {
+                        await promptOnce(handoffContinuationPrompt);
+                        handoffRecovered = true;
+                    }
+                    catch (error) {
+                        handoffError = error;
+                    }
+                }
+                if (handoffError && !hasResult())
+                    throw handoffError instanceof Error ? handoffError : new Error(errorText(handoffError));
+                if (promptFailed && !hasResult() && !recovered && !handoffRecovered && !runtimeHandoff.transferred)
+                    throw promptError instanceof Error ? promptError : new Error(errorText(promptError));
+            };
+            throwIfProgressFailed();
+            beginTurn(false);
+            throwIfTurnPolicyFailed();
+            await promptAndRecover(request.task, true);
+            completeTurn(hasResult() || !hasToolCall(lastAssistant), false, true);
+            if (turnPolicyFailure)
+                throw turnPolicyFailure;
+            if (!hasResult()) {
+                throwIfProgressFailed();
+                beginTurn(false);
+                throwIfTurnPolicyFailed();
+                await promptAndRecover("Submit the final result now by calling workflow_result exactly once. Do not return prose.", true);
+                completeTurn(true, false, true);
+            }
+            if (!hasResult()) {
+                throwIfProgressFailed();
+                beginTurn(false);
+                throwIfTurnPolicyFailed();
+                await promptAndRecover("Your result was missing or invalid. Repair it by calling workflow_result exactly once with a schema-valid value.", true);
+                completeTurn(true, false, true);
+            }
+            if (!hasResult())
+                throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
+            await callbacks?.onBeforeComplete?.();
+            report(() => createdAdapter.snapshot(true));
+            await flushProgress();
+            await flushEvents();
+            await flushSystemPrompts();
+            unsubscribe();
+            createdAdapter.dispose();
+            adapter = undefined;
+            const value = request.resultSchema === undefined ? unstructuredResult(structuredResult) : structuredResult;
+            if (value === undefined)
+                throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
+            const result = { value, usage: runtimeUsage(session), reference: { transport: session.reference.transport, ...(session.reference.locator === undefined ? {} : { locator: runtimeValue(session.reference.locator) }) } };
+            successfulInvocation = true;
+            await callbacks?.onComplete?.(result, session);
+            disposeStarted = true;
+            await session.dispose();
+            session = undefined;
+            return result;
+        }
+        catch (error) {
+            const typed = turnPolicyFailure ?? normalizePiRuntimeError(error, request.signal);
+            if (session && sessionReady) {
+                const activeSession = session;
+                const activeAdapter = adapter;
+                report(() => activeAdapter?.snapshot(true) ?? { usage: runtimeUsage(activeSession), toolCalls: [], state: activeSession.getState(), persist: true });
+                //NOTE: best-effort telemetry flush during teardown; the agent failure is rethrown after this block, so dropping the flush must not mask the primary error.
+                await flushProgress().catch(() => undefined);
+                await flushEvents().catch(() => undefined);
+                await flushSystemPrompts().catch(() => undefined);
+                unsubscribe?.();
+                activeAdapter?.dispose();
+                adapter = undefined;
+                if (!successfulInvocation && !turnPolicyFailure && typed.code !== "BUDGET_EXHAUSTED") {
+                    try {
+                        request.turnPolicy?.afterTurn(runtimeUsage(activeSession), true);
+                    }
+                    catch (budgetFailure) {
+                        turnPolicyFailure ??= turnPolicyError(budgetFailure);
+                    }
+                }
+                let callbackFailure;
+                if (!successfulInvocation) {
+                    try {
+                        await callbacks?.onFailure?.(turnPolicyFailure ?? typed, activeSession);
+                    }
+                    catch (failure) {
+                        callbackFailure = failure;
+                    }
+                }
+                if (!disposeStarted) {
+                    await activeSession.dispose().catch(() => undefined);
+                }
+                if (callbackFailure !== undefined)
+                    throw callbackFailure instanceof Error ? callbackFailure : new Error(errorText(callbackFailure));
+            }
+            throw turnPolicyFailure ?? (error instanceof Error ? error : new Error(errorText(error)));
+        }
+    }
+}
+export function createPiRuntimeAgentRunner(options) { return new PiRuntimeAgentRunner(options); }

package/dist/src/registry.d.ts

@@ -0,0 +1,48 @@
+import type { AgentAttemptAction, JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowExtension, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowFunction, WorkflowFunctionContext, WorkflowFunctionSource, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext, WorkflowRoleDirectoryRegistration } from "./types.js";
+import type { SubagentRunRequest, SubagentStatus } from "../subagents/src/contracts.js";
+export type SubagentStatusObserver = (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void;
+export declare class WorkflowRegistry {
+    #private;
+    get frozen(): boolean;
+    freeze(): void;
+    setSubagentStatusObserver(observer: SubagentStatusObserver | undefined): void;
+    observeSubagentStatus(status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>): void;
+    register(extension: WorkflowExtension): void;
+    function(name: string): WorkflowFunction;
+    functions(): Readonly<Record<string, WorkflowFunction>>;
+    functionSources(): Readonly<Record<string, WorkflowFunctionSource>>;
+    catalog(context?: WorkflowCatalogContext): WorkflowCatalog;
+    catalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex;
+    catalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError;
+    globals(): Readonly<Record<string, {
+        name: string;
+    }>>;
+    validateExtensionSettings(settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext): void;
+    invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
+    agentSetupHooks(): readonly RegisteredAgentSetupHook[];
+    agentAttemptActions(): Readonly<Record<string, AgentAttemptAction>>;
+    roleDirectories(): readonly string[];
+    roleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
+    modelAliases(): readonly {
+        name: string;
+        version: string;
+        headline: string;
+        resolve: WorkflowModelAlias["resolve"];
+    }[];
+    resolveModelAliases(context: Readonly<WorkflowModelAliasResolverContext>, shadowed?: ReadonlySet<string>): Promise<Readonly<Record<string, string>>>;
+}
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "functionSources" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "validateExtensionSettings" | "modelAliases" | "resolveModelAliases" | "agentSetupHooks" | "agentAttemptActions" | "roleDirectories" | "roleDirectoryRegistrations" | "setSubagentStatusObserver" | "observeSubagentStatus">;
+export declare function resetWorkflowRegistry(): void;
+export declare function resetWorkflowRegistryIfIdle(): void;
+export declare function beginWorkflowExtensionLoading(): void;
+export declare function retainWorkflowRegistry(): () => void;
+export declare function loadingRegistry(): WorkflowRegistryApi;
+export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
+export declare function workflowCatalog(context?: WorkflowCatalogContext): WorkflowCatalog;
+export declare function workflowCatalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex;
+export declare function workflowCatalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError;
+export declare function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>>;
+export declare function registeredWorkflowFunctionSources(): Readonly<Record<string, WorkflowFunctionSource>>;
+export declare function registeredWorkflowRoleDirectories(): readonly string[];
+export declare function registeredWorkflowRoleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
+export type { WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogModelAlias, WorkflowCatalogSettings, WorkflowRoleDirectoryRegistration } from "./types.js";