clinkx 0.1.10 → 0.2.1

package/clinkx-workflows/dist/workflow-tools.js

@@ -0,0 +1,1131 @@
+/**
+ * Reusable workflow tool registration for any MCP Server instance.
+ *
+ * Extracted from server.ts to allow both:
+ * - Standalone STDIO server (ClinkSession child process backend)
+ * - In-process integration (LocalClinkBackend via root ClinkX)
+ *
+ * The `registerWorkflowTools()` function registers three tools on a Server:
+ * - run_workflow: start a new workflow execution
+ * - resume_workflow: resume a failed/cancelled run
+ * - list_workflows: list available workflow definitions
+ *
+ * The caller provides a `createBackend` factory that determines how clink
+ * calls are dispatched — either via child process or in-process.
+ */
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { loadWorkflow, listWorkflowCatalog } from "./loader.js";
+import { WorkflowEngine } from "./engine.js";
+import { WorkflowStateStore } from "./state.js";
+import { validateRunId } from "./run-id.js";
+import { getTemplatesPath } from "./config.js";
+import { WorkflowCancellationError, } from "./errors.js";
+import { shutdownCoordinator } from "./shutdown.js";
+import { basename } from "node:path";
+import { logger } from "./logger.js";
+import { createValidatorRegistry } from "./validators/index.js";
+import { deriveDecisiveFailure } from "./run-summary-derived.js";
+import { buildRunSummaryOrUndefined, buildFailureRunSummary } from "./run-summary.js";
+import { extractCard } from "./run-summary/cards/index.js";
+import { renderWorkflowReceipt } from "./workflow-receipt.js";
+// ---------------------------------------------------------------------------
+// Admission control
+// ---------------------------------------------------------------------------
+let activeMutex = null;
+function acquireMutex(runId) {
+    if (activeMutex != null) {
+        throw new McpError(ErrorCode.InvalidRequest, `A workflow is already running (run_id: "${activeMutex.runId}", started: ${activeMutex.startedAt}). ` +
+            `Wait for it to complete or cancel it before starting another. ` +
+            `Only one workflow can run at a time per server instance.`);
+    }
+    activeMutex = { runId, startedAt: new Date().toISOString() };
+}
+function releaseMutex() {
+    activeMutex = null;
+}
+// ---------------------------------------------------------------------------
+// Variable validation (6-6)
+// ---------------------------------------------------------------------------
+function formatExpectedVariables(schema) {
+    const parts = [];
+    for (const [name, def] of Object.entries(schema)) {
+        const suffix = def.required && def.default === undefined ? ", required" : "";
+        parts.push(`${name} (${def.type}${suffix})`);
+    }
+    return parts.length > 0 ? `Expected variables: ${parts.join(", ")}` : "";
+}
+function validateVariables(supplied, schema) {
+    const resolved = {};
+    const errors = [];
+    for (const [name, def] of Object.entries(schema)) {
+        const value = supplied?.[name];
+        if (value === undefined) {
+            if (def.default !== undefined) {
+                resolved[name] = def.default;
+                continue;
+            }
+            if (def.required) {
+                errors.push(`Missing required variable "${name}"`);
+                continue;
+            }
+            continue;
+        }
+        const typeError = validateVariableType(name, value, def.type);
+        if (typeError != null) {
+            errors.push(typeError);
+            continue;
+        }
+        resolved[name] = value;
+    }
+    // Reject unknown variables
+    if (supplied != null) {
+        for (const key of Object.keys(supplied)) {
+            if (!(key in schema)) {
+                errors.push(`Unknown variable "${key}"`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        const expected = formatExpectedVariables(schema);
+        const suffix = expected !== "" ? `. ${expected}` : "";
+        throw new McpError(ErrorCode.InvalidParams, `Variable validation failed: ${errors.join("; ")}${suffix}`);
+    }
+    return resolved;
+}
+function validateVariableType(name, value, expectedType) {
+    switch (expectedType) {
+        case "string":
+            if (typeof value !== "string") {
+                return `Variable "${name}" must be a string, got ${typeof value}`;
+            }
+            return null;
+        case "number":
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                return `Variable "${name}" must be a finite number`;
+            }
+            return null;
+        case "boolean":
+            if (typeof value !== "boolean") {
+                return `Variable "${name}" must be a boolean, got ${typeof value}`;
+            }
+            return null;
+        case "string[]":
+            if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+                return `Variable "${name}" must be a string array`;
+            }
+            return null;
+        default:
+            return `Variable "${name}" has unknown type "${expectedType}"`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Progress (6-7) — WorkflowProgressReporter
+// ---------------------------------------------------------------------------
+/** Heartbeat interval matching root progress.ts pattern. */
+const HEARTBEAT_INTERVAL_MS = 5_000;
+/** Percentage reserved for startup notification. */
+const STARTUP_RESERVE = 5;
+/** Execution band spans [STARTUP_RESERVE, 100 - FINALIZATION_RESERVE]. */
+const FINALIZATION_RESERVE = 5;
+/** Width of the execution band. */
+const EXECUTION_BAND = 100 - STARTUP_RESERVE - FINALIZATION_RESERVE; // 90
+/** Decay constant for asymptotic heartbeat ramp. */
+const HEARTBEAT_DECAY_K = 0.05;
+/**
+ * Humanize a stage ID: replace underscores with spaces, capitalize first letter only.
+ * e.g. "cross_review" → "Cross review", "ranking_analysis" → "Ranking analysis"
+ */
+export function humanizeStageId(id) {
+    const spaced = id.replace(/_/g, " ");
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * Rich percentage-based progress reporter for workflow executions.
+ *
+ * Replaces the flat monotonic counter with real 0-100 percentages
+ * derived from the workflow definition's call count. Includes a
+ * heartbeat timer for liveness signals during long-running calls.
+ */
+class WorkflowProgressReporter {
+    server;
+    progressToken;
+    runId;
+    workflowName;
+    totalCalls;
+    totalStages;
+    bandWidth;
+    callBands = new Map();
+    /** Monotonic guard — highest progress value emitted. */
+    lastProgress = 0;
+    /** Heartbeat timer handle. */
+    heartbeatTimer;
+    /** Currently running calls, keyed by "stageId.callId". */
+    runningCalls = new Map();
+    constructor(server, progressToken, runId, definition) {
+        this.server = server;
+        this.progressToken = progressToken;
+        this.runId = runId;
+        this.workflowName = definition.name;
+        this.totalStages = definition.stages.length;
+        // Build per-call bands: each call gets a slice of [5..95]
+        let globalIndex = 0;
+        for (let si = 0; si < definition.stages.length; si++) {
+            const stage = definition.stages[si];
+            const stageLabel = stage.description ?? humanizeStageId(stage.id);
+            for (const call of stage.calls) {
+                const key = `${stage.id}.${call.id}`;
+                this.callBands.set(key, {
+                    globalIndex,
+                    stageIndex: si + 1,
+                    stageId: stage.id,
+                    stageLabel,
+                    floor: 0, // filled below
+                    ceiling: 0,
+                });
+                globalIndex++;
+            }
+        }
+        this.totalCalls = globalIndex;
+        this.bandWidth = this.totalCalls > 0 ? EXECUTION_BAND / this.totalCalls : EXECUTION_BAND;
+        // Compute floor/ceiling for each call band
+        for (const [key, band] of this.callBands) {
+            this.callBands.set(key, {
+                ...band,
+                floor: STARTUP_RESERVE + band.globalIndex * this.bandWidth,
+                ceiling: STARTUP_RESERVE + (band.globalIndex + 1) * this.bandWidth,
+            });
+        }
+    }
+    /**
+     * Seed progress offset for resumed workflows.
+     * Call before engine.execute() with the count of already-completed calls.
+     */
+    seedCompletedCalls(count) {
+        if (count > 0 && this.totalCalls > 0) {
+            this.lastProgress = Math.floor(STARTUP_RESERVE + Math.min(count, this.totalCalls) * this.bandWidth);
+        }
+    }
+    /** Engine onProgress hook handler. */
+    async onProgress(event) {
+        if (event.scope === "run") {
+            await this.handleRunProgress(event);
+        }
+        else if (event.scope === "call" && event.stageId != null && event.callId != null) {
+            await this.handleCallProgress(event);
+        }
+        // Stage-level events are covered by call-level granularity — no separate MCP emission.
+    }
+    /** Engine onRetryScheduled hook handler. */
+    async onRetryScheduled(event) {
+        const band = this.callBands.get(`${event.stageId}.${event.callId}`);
+        if (band == null)
+            return;
+        const delaySec = Math.round(event.delayMs / 1000);
+        const message = `[${String(band.stageIndex)}/${String(this.totalStages)}] ${band.stageLabel} | ` +
+            `${event.callId} retrying in ${String(delaySec)}s (attempt ${String(event.nextRetryCount + 1)}, ${event.failureClass})`;
+        // Informational only — do not advance progress percentage
+        await this.emit(this.lastProgress, message);
+    }
+    /** Stop heartbeat timer. Must be called in finally blocks. */
+    stop() {
+        this.stopHeartbeat();
+    }
+    // ── Internal ──────────────────────────────────────────────
+    async handleRunProgress(event) {
+        switch (event.state) {
+            case "running": {
+                const message = `[run_id: ${this.runId}] ${this.workflowName} starting ` +
+                    `(${String(this.totalStages)} stages, ${String(this.totalCalls)} calls)`;
+                await this.emit(2, message);
+                break;
+            }
+            case "succeeded":
+            case "failed":
+            case "cancelled": {
+                this.stopHeartbeat();
+                const suffix = event.state === "succeeded" ? "complete" : event.state;
+                await this.emit(100, `${this.workflowName} ${suffix}`);
+                break;
+            }
+        }
+    }
+    async handleCallProgress(event) {
+        const callKey = `${event.stageId}.${event.callId}`;
+        const band = this.callBands.get(callKey);
+        if (band == null)
+            return;
+        const prefix = `[${String(band.stageIndex)}/${String(this.totalStages)}] ${band.stageLabel}`;
+        switch (event.state) {
+            case "running": {
+                this.runningCalls.set(callKey, {
+                    stageId: event.stageId,
+                    callId: event.callId,
+                    startedAt: Date.now(),
+                    band,
+                });
+                this.startHeartbeatIfNeeded();
+                const progress = Math.floor(band.floor + 0.1 * this.bandWidth);
+                const retryInfo = (event.retryCount ?? 0) > 0
+                    ? ` (attempt ${String((event.retryCount ?? 0) + 1)})`
+                    : "";
+                await this.emit(progress, `${prefix} | ${event.callId} running${retryInfo}`);
+                break;
+            }
+            case "succeeded": {
+                this.runningCalls.delete(callKey);
+                this.stopHeartbeatIfIdle();
+                await this.emit(Math.floor(band.ceiling), `${prefix} | ${event.callId} succeeded`);
+                break;
+            }
+            case "failed": {
+                this.runningCalls.delete(callKey);
+                this.stopHeartbeatIfIdle();
+                await this.emit(Math.floor(band.ceiling), `${prefix} | ${event.callId} failed`);
+                break;
+            }
+            case "cancelled": {
+                this.runningCalls.delete(callKey);
+                this.stopHeartbeatIfIdle();
+                // Do not advance progress on cancellation
+                await this.emit(this.lastProgress, `${prefix} | ${event.callId} cancelled`);
+                break;
+            }
+        }
+    }
+    startHeartbeatIfNeeded() {
+        if (this.heartbeatTimer != null)
+            return;
+        const tick = () => {
+            const earliest = this.findEarliestRunningCall();
+            if (earliest == null) {
+                this.stopHeartbeat();
+                return;
+            }
+            const elapsedSec = Math.round((Date.now() - earliest.startedAt) / 1000);
+            const progress = this.computeHeartbeatProgress(earliest.band, earliest.startedAt);
+            const prefix = `[${String(earliest.band.stageIndex)}/${String(this.totalStages)}] ${earliest.band.stageLabel}`;
+            const message = `${prefix} | ${earliest.callId} running (${String(elapsedSec)}s)`;
+            // Self-scheduling: next tick fires after current send completes
+            void this.emit(progress, message).finally(() => {
+                if (this.heartbeatTimer != null) {
+                    this.heartbeatTimer = setTimeout(tick, HEARTBEAT_INTERVAL_MS);
+                    this.heartbeatTimer.unref();
+                }
+            });
+        };
+        this.heartbeatTimer = setTimeout(tick, HEARTBEAT_INTERVAL_MS);
+        this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer != null) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    stopHeartbeatIfIdle() {
+        if (this.runningCalls.size === 0) {
+            this.stopHeartbeat();
+        }
+    }
+    findEarliestRunningCall() {
+        let earliest;
+        for (const entry of this.runningCalls.values()) {
+            if (earliest == null || entry.startedAt < earliest.startedAt) {
+                earliest = entry;
+            }
+        }
+        return earliest;
+    }
+    /**
+     * Asymptotic ramp from floor+10% toward ceiling-10% within a call's band.
+     * Uses exponential decay so each heartbeat tick adds diminishing increments.
+     */
+    computeHeartbeatProgress(band, startedAt) {
+        const base = band.floor + 0.1 * this.bandWidth;
+        const target = band.ceiling - 0.1 * this.bandWidth;
+        const range = target - base;
+        if (range <= 0)
+            return Math.floor(base);
+        const elapsedTicks = (Date.now() - startedAt) / HEARTBEAT_INTERVAL_MS;
+        const raw = target - range * Math.exp(-HEARTBEAT_DECAY_K * elapsedTicks);
+        return Math.floor(Math.min(raw, target));
+    }
+    /**
+     * Send an MCP progress notification.
+     * Enforces monotonically increasing progress; best-effort delivery.
+     */
+    async emit(progress, message) {
+        const clamped = Math.min(Math.max(progress, this.lastProgress), 100);
+        try {
+            await this.server.notification({
+                method: "notifications/progress",
+                params: {
+                    progressToken: this.progressToken,
+                    progress: clamped,
+                    total: 100,
+                    message,
+                },
+            });
+            this.lastProgress = clamped;
+        }
+        catch {
+            // Best-effort — host may not support progress
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Debug metadata (6-8)
+// ---------------------------------------------------------------------------
+function buildDebugBlock(runId, result, store) {
+    const state = store?.runState;
+    const debug = {
+        run_id: runId,
+        stages: result.stages.map((stage) => ({
+            stage_id: stage.stageId,
+            ok: stage.ok,
+            calls: stage.calls.map((call) => {
+                const callState = state?.stages
+                    .find((s) => s.stageId === stage.stageId)
+                    ?.calls.find((c) => c.callId === call.callId);
+                return {
+                    call_id: call.callId,
+                    ok: call.ok,
+                    duration_ms: callState?.durationMs,
+                    retry_count: callState?.retryCount ?? 0,
+                    ...(call.error != null ? { error: call.error } : {}),
+                    ...(call.fidelity != null
+                        ? {
+                            truncation: {
+                                response: call.fidelity.responseTruncated,
+                                capture: call.fidelity.captureTruncated,
+                            },
+                        }
+                        : {}),
+                };
+            }),
+            ...(stage.aggregateArtifactPath != null
+                ? { aggregate_artifact: stage.aggregateArtifactPath }
+                : {}),
+        })),
+        artifacts_dir: result.artifactsDir,
+        ...(state?.fingerprint != null
+            ? {
+                fingerprint: {
+                    algorithm: state.fingerprint.algorithm,
+                    hash: state.fingerprint.hash.substring(0, 16) + "...",
+                },
+            }
+            : {}),
+    };
+    return JSON.stringify(debug, null, 2);
+}
+function buildErrorDebugBlock(runId, store) {
+    const state = store?.runState;
+    if (state == null) {
+        return JSON.stringify({ run_id: runId }, null, 2);
+    }
+    const debug = {
+        run_id: runId,
+        status: state.status,
+        stages: state.stages.map((stage) => ({
+            stage_id: stage.stageId,
+            state: stage.state,
+            calls: stage.calls.map((call) => ({
+                call_id: call.callId,
+                state: call.state,
+                retry_count: call.retryCount,
+                duration_ms: call.durationMs,
+                ...(call.errorMessage != null ? { error: call.errorMessage } : {}),
+                ...(call.failureClass != null
+                    ? { failure_class: call.failureClass }
+                    : {}),
+                ...(call.childDebugMetadata != null
+                    ? { child_debug: call.childDebugMetadata }
+                    : {}),
+            })),
+        })),
+        ...(state.fingerprint != null
+            ? {
+                fingerprint: {
+                    algorithm: state.fingerprint.algorithm,
+                    hash: state.fingerprint.hash.substring(0, 16) + "...",
+                },
+            }
+            : {}),
+    };
+    return JSON.stringify(debug, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Card extractor adapter
+// ---------------------------------------------------------------------------
+/**
+ * Adapt `extractCard()` from `./run-summary/cards/index.js` into the
+ * `RunSummaryCardExtractor` signature expected by `buildSuccessRunSummary()`.
+ */
+function createCardExtractor(definition) {
+    return (calls) => {
+        const stageCallArtifacts = new Map();
+        for (const call of calls) {
+            if (call.artifact?.parsed === undefined)
+                continue;
+            let callMap = stageCallArtifacts.get(call.stageId);
+            if (callMap == null) {
+                callMap = new Map();
+                stageCallArtifacts.set(call.stageId, callMap);
+            }
+            callMap.set(call.callId, call.artifact.parsed);
+        }
+        const input = {
+            definitionName: definition.name,
+            stageCallArtifacts,
+        };
+        return extractCard(input);
+    };
+}
+// ---------------------------------------------------------------------------
+// Receipt-aware content block assembly (2-7)
+// ---------------------------------------------------------------------------
+/**
+ * Shared content block assembly for both `executeRunWorkflow()` and
+ * `executeResumeWorkflow()`. Ordering contract:
+ *
+ *   content[0] — raw result (always present, byte-for-byte unchanged)
+ *   content[1] — receipt (when receipt=true and summary exists)
+ *   content[N]  — debug  (when debug=true)
+ *
+ * Receipt rendering is fail-open: errors are logged and silently omitted.
+ */
+function finalizeWorkflowPresentation(options) {
+    const content = [
+        { type: "text", text: options.outputText }, // content[0] — always raw result
+    ];
+    // content[1] — receipt (when receipt=true and summary exists)
+    if (options.receipt && options.summary !== undefined) {
+        try {
+            const receiptText = renderWorkflowReceipt(options.summary);
+            content.push({ type: "text", text: receiptText });
+        }
+        catch (err) {
+            logger.warn({ err }, "receipt rendering failed, omitting receipt");
+        }
+    }
+    // content[N] — debug (when debug=true)
+    if (options.debug && options.debugBlock !== undefined) {
+        content.push({ type: "text", text: options.debugBlock });
+    }
+    return content;
+}
+// ---------------------------------------------------------------------------
+// Actionable error formatting (5-6)
+// ---------------------------------------------------------------------------
+function formatWorkflowError(runId, error, store, workflowSource) {
+    const message = error instanceof Error ? error.message : String(error);
+    const state = store?.runState;
+    // Find the decisive failed call — prefer the call in the stage that has
+    // on_failure=abort (the one that caused the workflow to terminate), not
+    // just the first failed call found in state.
+    let location = "";
+    let retryCount = 0;
+    let childMeta;
+    let callErrorMessage;
+    if (state != null) {
+        const decisiveFailure = deriveDecisiveFailure(state.stages, store?.definition);
+        if (decisiveFailure != null) {
+            location = ` at ${decisiveFailure.location}`;
+            const decisiveCall = getCallEntryByLocation(state.stages, decisiveFailure.location);
+            retryCount = decisiveCall?.retryCount ?? 0;
+            childMeta = decisiveCall?.childDebugMetadata;
+            callErrorMessage = decisiveCall?.errorMessage;
+        }
+    }
+    // Build diagnostic details block
+    const metaLines = [];
+    // Always show the decisive call's error message when it differs from
+    // the top-level message — this carries validator failure details,
+    // child rejection reasons, etc. that the stage-abort message hides.
+    if (callErrorMessage != null && callErrorMessage !== message) {
+        metaLines.push(`  call_error: ${callErrorMessage}`);
+    }
+    if (childMeta != null) {
+        if (childMeta.rejection_reason != null) {
+            metaLines.push(`  rejection_reason: ${childMeta.rejection_reason}`);
+        }
+        if (childMeta.parse_status != null) {
+            metaLines.push(`  parse_status: ${childMeta.parse_status}`);
+        }
+        if (childMeta.parse_source != null) {
+            metaLines.push(`  parse_source: ${childMeta.parse_source}`);
+        }
+        if (childMeta.exit_code !== undefined) {
+            metaLines.push(`  exit_code: ${String(childMeta.exit_code)}`);
+        }
+        if (childMeta.codex_panic_class != null) {
+            metaLines.push(`  codex_panic_class: ${childMeta.codex_panic_class}`);
+        }
+    }
+    const metaBlock = metaLines.length > 0
+        ? `\n\nFailure details:\n${metaLines.join("\n")}`
+        : "";
+    // Workflow source annotation
+    const sourceLabel = workflowSource != null
+        ? ` (source: ${workflowSource.source}${workflowSource.sourcePath != null ? ` [${basename(workflowSource.sourcePath)}]` : ""})`
+        : "";
+    let nextAction = "";
+    if (store != null) {
+        const isResumable = state?.resumable === true;
+        nextAction = isResumable
+            ? `Use resume_workflow with run_id "${runId}" to retry from the last checkpoint.`
+            : `Start a new run with run_workflow (this run is not resumable — set CLINKX_WORKFLOWS_CHILD_CONFIG_PATH for resumable runs).`;
+    }
+    return (`Workflow failed [run_id: ${runId}]${sourceLabel}${location}` +
+        (retryCount > 0 ? ` (after ${String(retryCount)} retries)` : "") +
+        `: ${message}${metaBlock}` +
+        (nextAction !== "" ? `\n\n${nextAction}` : ""));
+}
+function getCallEntryByLocation(stages, location) {
+    const dotIndex = location.indexOf(".");
+    if (dotIndex === -1) {
+        return undefined;
+    }
+    const stageId = location.slice(0, dotIndex);
+    const callId = location.slice(dotIndex + 1);
+    const stage = stages.find((entry) => entry.stageId === stageId);
+    return stage?.calls.find((call) => call.callId === callId);
+}
+// ---------------------------------------------------------------------------
+// Tool execution helpers
+// ---------------------------------------------------------------------------
+async function executeRunWorkflow(server, options, args, signal, progressToken) {
+    const workflow = args["workflow"];
+    const runId = args["run_id"];
+    const variables = args["variables"];
+    const debug = args["debug"] === true;
+    const receipt = args["receipt"] === true;
+    if (typeof workflow !== "string" || workflow === "") {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid "workflow" parameter');
+    }
+    if (typeof runId !== "string" || runId === "") {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid "run_id" parameter');
+    }
+    try {
+        validateRunId(runId);
+    }
+    catch {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid run_id "${runId}". Must match [A-Za-z0-9_-]{1,64}.`);
+    }
+    const validatorRegistry = createValidatorRegistry();
+    const loaded = loadWorkflow(workflow, {
+        templatesRoot: options.templatesRoot ?? getTemplatesPath(),
+        validatorRegistry,
+    });
+    const resolvedVariables = validateVariables(variables, loaded.definition.variables);
+    acquireMutex(runId);
+    let store = null;
+    let backend = null;
+    let reporter;
+    try {
+        // Create state store (resumable if child config path is set)
+        store = await WorkflowStateStore.create({
+            runId,
+            definition: loaded.normalized,
+            variables: resolvedVariables,
+            debugKeepArtifacts: debug,
+        });
+        // Create backend via factory
+        backend = options.createBackend(runId);
+        await backend.connect();
+        // Wire up shutdown coordinator
+        const controller = new AbortController();
+        if (signal.aborted) {
+            controller.abort(new WorkflowCancellationError());
+        }
+        else {
+            signal.addEventListener("abort", () => {
+                controller.abort(new WorkflowCancellationError());
+            }, { once: true });
+        }
+        shutdownCoordinator.register(backend, controller, async () => {
+            if (store != null) {
+                await store.markCancelled();
+            }
+        });
+        // Build engine hooks — capture store in a const for closure narrowing
+        const storeRef = store;
+        reporter = progressToken != null
+            ? new WorkflowProgressReporter(server, progressToken, runId, loaded.normalized)
+            : undefined;
+        const rpt = reporter; // local const for closure narrowing
+        const hooks = {
+            ...storeRef.hooks,
+            ...(rpt != null
+                ? {
+                    onProgress: async (event) => {
+                        await storeRef.hooks.onProgress?.(event);
+                        await rpt.onProgress(event);
+                    },
+                    onRetryScheduled: async (event) => {
+                        await storeRef.hooks.onRetryScheduled?.(event);
+                        await rpt.onRetryScheduled(event);
+                    },
+                }
+                : {}),
+        };
+        const engine = new WorkflowEngine({
+            definition: loaded.normalized,
+            session: backend,
+            variables: resolvedVariables,
+            validatorRegistry,
+            runId,
+            runDir: storeRef.runDir,
+            signal: controller.signal,
+            hooks,
+        });
+        const result = await engine.execute();
+        shutdownCoordinator.unregister();
+        // Build summary (fail-open)
+        let summary;
+        if (receipt) {
+            try {
+                const cardExtractor = createCardExtractor(loaded.normalized);
+                summary = buildRunSummaryOrUndefined(result, store, cardExtractor);
+            }
+            catch (err) {
+                logger.warn({ err }, "run summary construction failed, omitting receipt");
+            }
+        }
+        const content = finalizeWorkflowPresentation({
+            outputText: result.outputText,
+            receipt,
+            debug,
+            summary,
+            debugBlock: debug ? buildDebugBlock(runId, result, store) : undefined,
+        });
+        return { content };
+    }
+    catch (error) {
+        shutdownCoordinator.unregister();
+        if (error instanceof WorkflowCancellationError) {
+            if (store != null) {
+                await store.markCancelled();
+            }
+            throw error;
+        }
+        const errorText = formatWorkflowError(runId, error, store, {
+            source: loaded.source,
+            sourcePath: loaded.sourcePath,
+        });
+        // Build failure summary (fail-open)
+        let failureSummary;
+        if (receipt && store != null) {
+            try {
+                failureSummary = buildFailureRunSummary(store);
+            }
+            catch (err) {
+                logger.warn({ err }, "failure summary construction failed, omitting receipt");
+            }
+        }
+        const content = finalizeWorkflowPresentation({
+            outputText: errorText,
+            receipt,
+            debug,
+            summary: failureSummary,
+            debugBlock: debug && store != null ? buildErrorDebugBlock(runId, store) : undefined,
+        });
+        return { content, isError: true };
+    }
+    finally {
+        reporter?.stop();
+        try {
+            if (backend != null && !backend.isTerminated) {
+                await backend.terminate();
+            }
+        }
+        catch (cleanupErr) {
+            logger.warn({ err: cleanupErr }, "backend.terminate() failed during cleanup");
+        }
+        try {
+            if (store != null) {
+                await store.close();
+            }
+        }
+        catch (cleanupErr) {
+            logger.warn({ err: cleanupErr }, "store.close() failed during cleanup");
+        }
+        releaseMutex();
+    }
+}
+async function executeResumeWorkflow(server, options, args, signal, progressToken) {
+    const runId = args["run_id"];
+    const debug = args["debug"] === true;
+    const receipt = args["receipt"] === true;
+    if (typeof runId !== "string" || runId === "") {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid "run_id" parameter');
+    }
+    try {
+        validateRunId(runId);
+    }
+    catch {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid run_id "${runId}". Must match [A-Za-z0-9_-]{1,64}.`);
+    }
+    acquireMutex(runId);
+    let store = null;
+    let backend = null;
+    let reporter;
+    try {
+        const resumeOptions = {
+            runId,
+            debugKeepArtifacts: debug,
+        };
+        store = await WorkflowStateStore.resume(resumeOptions);
+        const validatorRegistry = createValidatorRegistry();
+        // Create backend via factory
+        backend = options.createBackend(runId);
+        await backend.connect();
+        // Wire up shutdown coordinator
+        const controller = new AbortController();
+        if (signal.aborted) {
+            controller.abort(new WorkflowCancellationError());
+        }
+        else {
+            signal.addEventListener("abort", () => {
+                controller.abort(new WorkflowCancellationError());
+            }, { once: true });
+        }
+        shutdownCoordinator.register(backend, controller, async () => {
+            await store.markCancelled();
+        });
+        // Build engine hooks with progress reporter
+        reporter = progressToken != null
+            ? new WorkflowProgressReporter(server, progressToken, runId, store.definition)
+            : undefined;
+        if (reporter != null) {
+            // Seed progress from already-completed calls so resumed runs don't start at 0%
+            const completedCount = store.resume.completedCalls?.size ?? 0;
+            reporter.seedCompletedCalls(completedCount);
+        }
+        const rpt = reporter; // local const for closure narrowing
+        const hooks = {
+            ...store.hooks,
+            ...(rpt != null
+                ? {
+                    onProgress: async (event) => {
+                        await store.hooks.onProgress?.(event);
+                        await rpt.onProgress(event);
+                    },
+                    onRetryScheduled: async (event) => {
+                        await store.hooks.onRetryScheduled?.(event);
+                        await rpt.onRetryScheduled(event);
+                    },
+                }
+                : {}),
+        };
+        const engine = new WorkflowEngine({
+            definition: store.definition,
+            session: backend,
+            variables: store.variables,
+            validatorRegistry,
+            runId,
+            runDir: store.runDir,
+            signal: controller.signal,
+            hooks: rpt != null ? hooks : store.hooks,
+            resume: store.resume,
+        });
+        const result = await engine.execute();
+        shutdownCoordinator.unregister();
+        // Build summary (fail-open)
+        let summary;
+        if (receipt) {
+            try {
+                const cardExtractor = createCardExtractor(store.definition);
+                summary = buildRunSummaryOrUndefined(result, store, cardExtractor);
+            }
+            catch (err) {
+                logger.warn({ err }, "run summary construction failed, omitting receipt");
+            }
+        }
+        const content = finalizeWorkflowPresentation({
+            outputText: result.outputText,
+            receipt,
+            debug,
+            summary,
+            debugBlock: debug ? buildDebugBlock(runId, result, store) : undefined,
+        });
+        return { content };
+    }
+    catch (error) {
+        shutdownCoordinator.unregister();
+        if (error instanceof WorkflowCancellationError) {
+            if (store != null) {
+                await store.markCancelled();
+            }
+            throw error;
+        }
+        const errorText = formatWorkflowError(runId, error, store);
+        // Build failure summary (fail-open)
+        let failureSummary;
+        if (receipt && store != null) {
+            try {
+                failureSummary = buildFailureRunSummary(store);
+            }
+            catch (err) {
+                logger.warn({ err }, "failure summary construction failed, omitting receipt");
+            }
+        }
+        const content = finalizeWorkflowPresentation({
+            outputText: errorText,
+            receipt,
+            debug,
+            summary: failureSummary,
+            debugBlock: debug && store != null ? buildErrorDebugBlock(runId, store) : undefined,
+        });
+        return { content, isError: true };
+    }
+    finally {
+        reporter?.stop();
+        try {
+            if (backend != null && !backend.isTerminated) {
+                await backend.terminate();
+            }
+        }
+        catch (cleanupErr) {
+            logger.warn({ err: cleanupErr }, "backend.terminate() failed during cleanup");
+        }
+        try {
+            if (store != null) {
+                await store.close();
+            }
+        }
+        catch (cleanupErr) {
+            logger.warn({ err: cleanupErr }, "store.close() failed during cleanup");
+        }
+        releaseMutex();
+    }
+}
+function executeListWorkflows() {
+    const workflows = listWorkflowCatalog();
+    const entries = [];
+    for (const [name, entry] of workflows) {
+        const def = entry.definition;
+        entries.push({
+            name,
+            description: def.description,
+            version: def.version,
+            source: entry.source,
+            shadowed_yaml: entry.shadowedYaml,
+            ...(entry.path != null ? { path: basename(entry.path) } : {}),
+            variables: Object.fromEntries(Object.entries(def.variables).map(([varName, varDef]) => [
+                varName,
+                {
+                    type: varDef.type,
+                    required: varDef.required,
+                    ...(varDef.default !== undefined ? { default: varDef.default } : {}),
+                    ...(varDef.description != null ? { description: varDef.description } : {}),
+                },
+            ])),
+        });
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ workflows: entries }, null, 2),
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool input schemas (JSON Schema)
+// ---------------------------------------------------------------------------
+const MAX_INLINE_WORKFLOW_DETAILS = 8;
+const RUN_WORKFLOW_SCHEMA = {
+    type: "object",
+    properties: {
+        workflow: {
+            type: "string",
+            description: "Name of the workflow to run",
+        },
+        run_id: {
+            type: "string",
+            description: "Unique run identifier. Must match [A-Za-z0-9_-]{1,64}",
+            pattern: "^[A-Za-z0-9_-]{1,64}$",
+        },
+        variables: {
+            type: "object",
+            description: "Workflow input variables",
+            additionalProperties: true,
+        },
+        debug: {
+            type: "boolean",
+            description: "When true, append execution metadata as a second content block",
+            default: false,
+        },
+        receipt: {
+            type: "boolean",
+            description: "When true, append a structured receipt summarizing the workflow run as a content block",
+            default: false,
+        },
+    },
+    required: ["workflow", "run_id"],
+    additionalProperties: false,
+};
+const RESUME_WORKFLOW_SCHEMA = {
+    type: "object",
+    properties: {
+        run_id: {
+            type: "string",
+            description: "Run ID of a previously failed/cancelled workflow to resume",
+            pattern: "^[A-Za-z0-9_-]{1,64}$",
+        },
+        debug: {
+            type: "boolean",
+            description: "When true, append execution metadata as a second content block",
+            default: false,
+        },
+        receipt: {
+            type: "boolean",
+            description: "When true, append a structured receipt summarizing the workflow run as a content block",
+            default: false,
+        },
+    },
+    required: ["run_id"],
+    additionalProperties: false,
+};
+const LIST_WORKFLOWS_SCHEMA = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+/**
+ * Return the three workflow tool definitions for tools/list.
+ *
+ * Dynamically discovers available workflows to include in the
+ * run_workflow description. Safe to call repeatedly — no side effects.
+ */
+export function getWorkflowToolDefinitions() {
+    let catalogEntries;
+    try {
+        catalogEntries = listWorkflowCatalog();
+    }
+    catch {
+        // Non-fatal — list_workflows will report the error at call time
+    }
+    // C1: Clone schema and inject dynamic enum for workflow names
+    const runSchema = structuredClone(RUN_WORKFLOW_SCHEMA);
+    const names = catalogEntries != null && catalogEntries.size > 0
+        ? [...catalogEntries.keys()].sort()
+        : [];
+    if (names.length > 0) {
+        const props = runSchema["properties"];
+        props["workflow"] = { ...props["workflow"], enum: names };
+    }
+    // C2 + C3: Build rich description with per-workflow variables
+    let workflowSuffix = "";
+    if (names.length > MAX_INLINE_WORKFLOW_DETAILS) {
+        // C3: Cap at names-only for large catalogs
+        workflowSuffix = `\nAvailable workflows: ${names.join(", ")}. Use list_workflows for variable schemas.`;
+    }
+    else if (names.length > 0) {
+        const lines = [];
+        for (const name of names) {
+            const entry = catalogEntries.get(name);
+            const vars = entry.definition.variables;
+            const required = [];
+            const optional = [];
+            for (const [varName, varDef] of Object.entries(vars)) {
+                if (varDef.required && varDef.default === undefined) {
+                    required.push(varName);
+                }
+                else {
+                    optional.push(varName);
+                }
+            }
+            const parts = [];
+            if (required.length > 0)
+                parts.push(`required: ${required.join(", ")}`);
+            if (optional.length > 0)
+                parts.push(`optional: ${optional.join(", ")}`);
+            lines.push(`- ${name}${parts.length > 0 ? ` (${parts.join("; ")})` : ""}`);
+        }
+        workflowSuffix = `\nAvailable workflows:\n${lines.join("\n")}`;
+    }
+    return [
+        {
+            name: "run_workflow",
+            description: `Start a new multi-stage workflow execution.${workflowSuffix}`,
+            inputSchema: runSchema,
+        },
+        {
+            name: "resume_workflow",
+            description: "Resume a previously failed or cancelled workflow from its last checkpoint. " +
+                "Requires the original run_id and matching child config.",
+            inputSchema: RESUME_WORKFLOW_SCHEMA,
+        },
+        {
+            name: "list_workflows",
+            description: "List available workflow definitions with their name, description, version, and variable schema.",
+            inputSchema: LIST_WORKFLOWS_SCHEMA,
+            annotations: { readOnlyHint: true },
+        },
+    ];
+}
+/** Names of the workflow tools (for dispatch matching). */
+export const WORKFLOW_TOOL_NAMES = new Set([
+    "run_workflow",
+    "resume_workflow",
+    "list_workflows",
+]);
+/**
+ * Dispatch a workflow tool call.
+ *
+ * Returns the tool result, or null if the tool name is not recognized
+ * as a workflow tool (caller should handle it as an unknown tool).
+ */
+export async function handleWorkflowToolCall(server, options, name, args, signal, progressToken) {
+    switch (name) {
+        case "run_workflow":
+            return await executeRunWorkflow(server, options, args, signal, progressToken);
+        case "resume_workflow":
+            return await executeResumeWorkflow(server, options, args, signal, progressToken);
+        case "list_workflows":
+            return executeListWorkflows();
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public registration function
+// ---------------------------------------------------------------------------
+/**
+ * Register workflow tools on an MCP Server instance.
+ *
+ * This is the reusable core extracted from createWorkflowServer().
+ * It registers three tools: run_workflow, resume_workflow, list_workflows.
+ *
+ * The `options.createBackend` factory determines how clink calls are
+ * dispatched — callers provide either a child-process or in-process backend.
+ *
+ * NOTE: This calls setRequestHandler which REPLACES any existing handlers.
+ * For combined servers (root + workflows), use getWorkflowToolDefinitions()
+ * and handleWorkflowToolCall() instead and build a unified handler.
+ */
+export function registerWorkflowTools(server, options) {
+    // tools/list
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: getWorkflowToolDefinitions() };
+    });
+    // tools/call
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const { name, arguments: args } = request.params;
+        const progressToken = request.params._meta?.progressToken;
+        const result = await handleWorkflowToolCall(server, options, name, args ?? {}, extra.signal, progressToken);
+        if (result != null) {
+            return result;
+        }
+        logger.warn({ tool: name }, "unknown tool requested");
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${String(name)}` }],
+            isError: true,
+        };
+    });
+}
+//# sourceMappingURL=workflow-tools.js.map