stageflow 0.23.0 → 0.25.0

package/dist/cli/runStageCommand.js

@@ -0,0 +1,407 @@
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
+import { resolveAbsolute } from "./hostClient.js";
+export const RUN_STAGE_USAGE = `Usage:
+  sf run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>] [--envelope-ref ...]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
+
+Run a single stage directly against the shared Stageflow service, without authoring a pipeline file. Distinct from the internal-only, worker-process-only \`sf internal run-stage\`.
+  --stage <path>          Filesystem path to a catalog stage YAML file
+  --stage-inline <json>   Inline stage body object ({ id, system_prompt, io, ... } — no uses:/route/pipeline wrapper)
+  --task <path>           Filesystem path to a catalog task YAML file
+  --task-inline <json>    Inline task object ({ id, goal, ... })
+  --envelope-ref <ref>    Resolve a previously stored StageEnvelope as this stage's input instead of a task: <runId>:<stageId>[:<attempt>]. Repeat to pass more than one — each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal.
+  --checkout <path>       Optional checkout to use with --envelope-ref (--task/--task-inline carry their own checkout)
+  --model <id>            Override the model/backend for this call only, ahead of the stage's own declared model
+  --blocking              Wait for the run to reach a terminal or waiting state and print the result in this same call, instead of returning immediately with just the run id
+  --timeout-ms <n>        Wait budget in ms when --blocking is set
+  --json                  Machine-readable JSON output`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseRunStageCliArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false, blocking: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false, blocking: false };
+    }
+    let stage;
+    let stageInline;
+    let task;
+    let taskInline;
+    let envelopeRef;
+    let checkout;
+    let model;
+    let timeoutMs;
+    let json = false;
+    let blocking = false;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--stage") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --stage");
+            }
+            stage = value;
+        }
+        else if (arg === "--stage-inline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --stage-inline");
+            }
+            stageInline = value;
+        }
+        else if (arg === "--task") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --task");
+            }
+            task = value;
+        }
+        else if (arg === "--task-inline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --task-inline");
+            }
+            taskInline = value;
+        }
+        else if (arg === "--envelope-ref") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --envelope-ref");
+            }
+            envelopeRef = [...(envelopeRef ?? []), value];
+        }
+        else if (arg === "--checkout") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --checkout");
+            }
+            checkout = value;
+        }
+        else if (arg === "--model") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --model");
+            }
+            model = value;
+        }
+        else if (arg === "--timeout-ms") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --timeout-ms");
+            }
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`Invalid --timeout-ms: ${value}`);
+            }
+            timeoutMs = parsed;
+        }
+        else if (arg === "--blocking") {
+            blocking = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return {
+        help,
+        json,
+        blocking,
+        stage,
+        stageInline,
+        task,
+        taskInline,
+        envelopeRef,
+        checkout,
+        model,
+        timeoutMs,
+    };
+}
+function parseEnvelopeRefFlag(raw) {
+    const parts = raw.split(":");
+    if (parts.length < 2 || parts.length > 3) {
+        throw new Error("--envelope-ref must be <runId>:<stageId>[:<attempt>]");
+    }
+    const [runId, stageId, attemptRaw] = parts;
+    if (!runId || !stageId) {
+        throw new Error("--envelope-ref must be <runId>:<stageId>[:<attempt>]");
+    }
+    const ref = { runId, stageId };
+    if (attemptRaw !== undefined) {
+        const attempt = Number.parseInt(attemptRaw, 10);
+        if (!Number.isFinite(attempt) || attempt < 1) {
+            throw new Error("--envelope-ref attempt must be a positive integer");
+        }
+        ref.attempt = attempt;
+    }
+    return ref;
+}
+function parseJsonFlag(raw, flagName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${flagName} must be valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${flagName} must be a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * Streamable HTTP MCP is stateful by default (see docs/mcp.md): a bare
+ * tools/call POST with no session id is rejected with "Session ID
+ * required". Do the same initialize -> notifications/initialized ->
+ * tools/call handshake a real MCP client would, against the shared global
+ * service (started/ensured by the caller), then close the session.
+ */
+async function mcpInitializeSession(base) {
+    const res = await fetch(`${base}/mcp`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 0,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-03-26",
+                capabilities: {},
+                clientInfo: { name: "sf-cli", version: PACKAGE_VERSION },
+            },
+        }),
+    });
+    const sessionId = res.headers.get("mcp-session-id");
+    await res.text().catch(() => undefined);
+    if (!sessionId) {
+        throw new Error(`Failed to initialize MCP session against ${base}/mcp (status ${res.status})`);
+    }
+    await fetch(`${base}/mcp`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "mcp-session-id": sessionId,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "notifications/initialized",
+        }),
+    }).catch(() => undefined);
+    return sessionId;
+}
+async function mcpCloseSession(base, sessionId) {
+    await fetch(`${base}/mcp`, {
+        method: "DELETE",
+        headers: { "mcp-session-id": sessionId },
+    }).catch(() => undefined);
+}
+async function mcpToolCall(base, sessionId, name, args) {
+    const res = await fetch(`${base}/mcp`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "mcp-session-id": sessionId,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: { name, arguments: args },
+        }),
+    });
+    const text = await res.text();
+    const dataLine = text.split("\n").find((line) => line.startsWith("data: "));
+    if (!dataLine) {
+        throw new Error(`Unexpected MCP response from ${base}/mcp (status ${res.status}): ${text.slice(0, 200)}`);
+    }
+    const message = JSON.parse(dataLine.slice("data: ".length));
+    if (message.error) {
+        throw new Error(message.error.message ?? "MCP tool call failed");
+    }
+    const contentText = message.result?.content?.[0]?.text ?? "";
+    return {
+        isError: Boolean(message.result?.isError),
+        payload: contentText ? JSON.parse(contentText) : null,
+    };
+}
+function defaultCallTool(base, ensureService) {
+    return async (args) => {
+        const ensured = await ensureService();
+        if (!ensured.ok) {
+            throw new Error(ensured.message);
+        }
+        const sessionId = await mcpInitializeSession(base);
+        try {
+            return await mcpToolCall(base, sessionId, "run_stage", args);
+        }
+        finally {
+            await mcpCloseSession(base, sessionId);
+        }
+    };
+}
+function reportRunStageResult(result, options) {
+    const { io, json } = options;
+    const payload = result.payload ?? {};
+    if (result.isError) {
+        if (json) {
+            io.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            const message = typeof payload.error === "string" ? payload.error : "run_stage failed";
+            io.error(message);
+        }
+        return 1;
+    }
+    const status = payload.status;
+    if (status === undefined) {
+        // Async mode: { runId, stageId }.
+        if (json) {
+            io.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            io.log(`Stage run started: ${payload.runId} (stage: ${payload.stageId})`);
+        }
+        return 0;
+    }
+    // Blocking mode: { runId, stageId, status, envelope? | pending_prompt? }.
+    if (json) {
+        io.log(JSON.stringify(payload, null, 2));
+    }
+    else if (status === "completed") {
+        const envelope = payload.envelope;
+        if (envelope?.status === "failure") {
+            io.error(`Stage failed: ${envelope.summary ?? ""}`);
+        }
+        else {
+            io.log(`Stage completed: ${envelope?.summary ?? ""}`);
+        }
+    }
+    else if (status === "needs_input") {
+        io.error(`Stage waiting for input (run ${payload.runId}, stage ${payload.stageId}).`);
+    }
+    else if (status === "timeout") {
+        io.error(`Timed out waiting for stage to finish (run ${payload.runId}).`);
+    }
+    if (status === "completed") {
+        const envelope = payload.envelope;
+        return envelope?.status === "failure" ? 1 : 0;
+    }
+    if (status === "needs_input" || status === "timeout") {
+        return 2;
+    }
+    return 0;
+}
+export async function runRunStageCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    const base = options.hostBaseUrl ?? hostBaseUrl();
+    let parsed;
+    try {
+        parsed = parseRunStageCliArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(RUN_STAGE_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(RUN_STAGE_USAGE);
+        return 0;
+    }
+    if (Boolean(parsed.stage) === Boolean(parsed.stageInline)) {
+        out.error("Exactly one of --stage or --stage-inline is required");
+        out.error(RUN_STAGE_USAGE);
+        return 1;
+    }
+    const inputFlagCount = [parsed.task, parsed.taskInline, parsed.envelopeRef].filter((v) => v !== undefined).length;
+    if (inputFlagCount !== 1) {
+        out.error("Exactly one of --task, --task-inline, or --envelope-ref is required");
+        out.error(RUN_STAGE_USAGE);
+        return 1;
+    }
+    let stage;
+    if (parsed.stage !== undefined) {
+        stage = resolveAbsolute(cwd, parsed.stage);
+    }
+    else {
+        try {
+            stage = parseJsonFlag(parsed.stageInline, "--stage-inline");
+        }
+        catch (err) {
+            out.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    let taskPath;
+    let task;
+    let envelopeRef;
+    if (parsed.task !== undefined) {
+        taskPath = resolveAbsolute(cwd, parsed.task);
+    }
+    else if (parsed.taskInline !== undefined) {
+        try {
+            task = parseJsonFlag(parsed.taskInline, "--task-inline");
+        }
+        catch (err) {
+            out.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    else {
+        try {
+            const refs = parsed.envelopeRef.map(parseEnvelopeRefFlag);
+            envelopeRef = refs.length === 1 ? refs[0] : refs;
+        }
+        catch (err) {
+            out.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    const toolArgs = {
+        stage,
+        ...(taskPath !== undefined ? { task_path: taskPath } : {}),
+        ...(task !== undefined ? { task } : {}),
+        ...(envelopeRef !== undefined ? { envelope_ref: envelopeRef } : {}),
+        ...(parsed.checkout !== undefined
+            ? { checkout: resolveAbsolute(cwd, parsed.checkout) }
+            : {}),
+        ...(parsed.model !== undefined ? { model: parsed.model } : {}),
+        ...(parsed.blocking ? { blocking: true } : {}),
+        ...(parsed.timeoutMs !== undefined ? { timeout_ms: parsed.timeoutMs } : {}),
+    };
+    const callTool = options.callTool ??
+        defaultCallTool(base, options.ensureService ?? (() => ensureGlobalService()));
+    let result;
+    try {
+        result = await callTool(toolArgs);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (parsed.json) {
+            out.log(JSON.stringify({ error: message }));
+        }
+        else {
+            out.error(message);
+        }
+        return 1;
+    }
+    return reportRunStageResult(result, { json: parsed.json, io: out });
+}

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { A2A_USAGE, runA2aCommand } from "./cli/a2aCommand.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +11,7 @@ import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.j
 import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
+import { RUN_STAGE_USAGE, runRunStageCommand } from "./cli/runStageCommand.js";
 import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
@@ -27,6 +29,7 @@ import { PACKAGE_VERSION } from "./package-meta.js";
 const USAGE = `Usage:
   sf init
   sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
+  sf run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
   sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
   sf graph --pipeline <path> [--json]
   sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
@@ -58,6 +61,8 @@ const USAGE = `Usage:
   sf --version
   sf -V
   sf --help
+  sf a2a validate|list [--config <path>]
+  sf a2a add-caller <id> [--config <path>] [--token-env <NAME>]
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
 
@@ -67,10 +72,14 @@ ${INIT_USAGE}
 
 ${RUN_USAGE}
 
+${RUN_STAGE_USAGE}
+
 ${VALIDATE_USAGE}
 
 ${GRAPH_USAGE}
 
+${A2A_USAGE}
+
 ${MIGRATE_YAML_USAGE}
 
 ${ARTIFACT_USAGE}
@@ -103,8 +112,10 @@ function parseArgs(argv) {
     if (command === "providers" ||
         command === "validate" ||
         command === "graph" ||
+        command === "a2a" ||
         command === "migrate-yaml" ||
         command === "run" ||
+        command === "run-stage" ||
         command === "init" ||
         command === "artifact" ||
         command === "envelope" ||
@@ -282,6 +293,9 @@ async function main(argv) {
             return 0;
         }
         const ctx = await resolveStageflowContext(process.cwd());
+        if (parsed.command === "a2a") {
+            return runA2aCommand(argv.slice(3), { cwd: ctx.invocationCwd, projectRoot: ctx.projectRoot });
+        }
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
         }
@@ -308,6 +322,11 @@ async function main(argv) {
                 cwd: ctx.invocationCwd,
             });
         }
+        if (parsed.command === "run-stage") {
+            return runRunStageCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+            });
+        }
         if (parsed.command === "artifact") {
             return runArtifactCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,

package/dist/mcp/catalogTools.js

@@ -3,10 +3,13 @@ import { z } from "zod";
 import { browseCatalog, } from "../config/browseCatalog.js";
 import { describePipeline } from "../config/describePipeline.js";
 import { loadPipeline } from "../config/loadPipeline.js";
+import { readYamlObject } from "../config/readYamlObject.js";
 import { validateCatalog } from "../config/validateCatalog.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
 import { findProjectRoot } from "../project/findProjectRoot.js";
 import { PipelineValidationError } from "../runtime/pipelineValidationError.js";
+import { EnvelopeRefError, resolveEnvelopeRefsToTask, } from "../runtime/resolveEnvelopeRef.js";
+import { isTerminalProjection, isWaitingProjection, waitRun } from "./waitRun.js";
 import { mapStoreLookupError } from "../server/operatorResults.js";
 import { projectRunForMcp } from "./projectRun.js";
 import { classifyArtifactContent, readRunArtifactBytes } from "./readArtifact.js";
@@ -60,6 +63,45 @@ const startRunSchema = z
     .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
     message: "Exactly one of task_path or task is required",
 });
+/**
+ * Deliberately thin, same reasoning as inlinePipelineSchema above: real
+ * structural validation of the stage body happens downstream through the
+ * same stage loader a pipeline's inline stage goes through.
+ */
+const envelopeRefSchema = z.object({
+    runId: z.string(),
+    stageId: z.string(),
+    attempt: z.number().int().positive().optional(),
+});
+const runStageSchema = z
+    .object({
+    stage: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Filesystem path to a stage YAML file, or a bare inline stage body object ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper) authored directly in this call"),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+    envelope_ref: z
+        .union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)])
+        .optional()
+        .describe("Resolve one or more previously stored StageEnvelopes (from another run_stage call or from any stage inside a full pipeline run) and use them as this stage's input, instead of an inline task/task_path. A single ref: its payload becomes input, its summary becomes goal. Multiple refs (an array): each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal."),
+    checkout: z
+        .string()
+        .optional()
+        .describe("Optional checkout to use with envelope_ref (ignored with task/task_path, which carry their own checkout). Resolving envelope_ref never implies a checkout on its own."),
+    model: z
+        .string()
+        .optional()
+        .describe("Override the model/backend for this call only, taking precedence over the stage's own declared model and the global default. Omit to use the stage's own model (or the global default)."),
+    blocking: z
+        .boolean()
+        .optional()
+        .describe("When true, wait for the run to reach a terminal or waiting state and return the result in this same call, instead of returning immediately with just { runId }"),
+    timeout_ms: z
+        .number()
+        .optional()
+        .describe("Wait budget in ms when blocking is true (same bounds as wait_run)"),
+})
+    .refine((data) => [data.task_path, data.task, data.envelope_ref].filter(Boolean).length === 1, { message: "Exactly one of task_path, task, or envelope_ref is required" });
 const runStatusSchema = z.enum(["created", "running", "succeeded", "failed"]);
 export function registerCatalogTools(server, deps) {
     const { manager, store, cwd } = deps;
@@ -161,6 +203,103 @@ export function registerCatalogTools(server, deps) {
         }
         return textResult({ runId: result.runId });
     });
+    server.registerTool("run_stage", {
+        description: "Run a single stage directly, without authoring a pipeline. `stage` is a filesystem path to a stage YAML file, or a bare inline stage body ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper), and exactly one of task_path, an inline task, or envelope_ref ({ runId, stageId, attempt? }) to resolve a previously stored envelope — from another run_stage call or any stage in a full pipeline run — as this stage's input. Internally this synthesizes a one-stage pipeline and executes it through the normal run path, so it shows up in list_runs/get_run and is polled with wait_run / get_envelope exactly like any other run. By default returns { runId, stageId } immediately (async); pass blocking:true to wait in this same call and get back { runId, stageId, status: \"completed\"|\"needs_input\"|\"timeout\", envelope? , pending_prompt? }.",
+        inputSchema: runStageSchema,
+    }, async ({ stage, task_path, task, envelope_ref, checkout, model, blocking, timeout_ms }) => {
+        let taskInput = task_path ?? task;
+        if (envelope_ref) {
+            try {
+                taskInput = await resolveEnvelopeRefsToTask(store, envelope_ref, checkout);
+            }
+            catch (err) {
+                if (err instanceof EnvelopeRefError) {
+                    return textResult({ error: err.message, status: err.status }, true);
+                }
+                throw err;
+            }
+        }
+        if (taskInput === undefined) {
+            return textResult({ error: "Exactly one of task_path, task, or envelope_ref is required" }, true);
+        }
+        let stageBody;
+        if (typeof stage === "string") {
+            if (!stage.trim()) {
+                return textResult({ error: "stage is required" }, true);
+            }
+            const absPath = path.resolve(cwd, stage);
+            try {
+                stageBody = await readYamlObject(absPath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return textResult({ error: `Failed to read stage file: ${message}` }, true);
+            }
+        }
+        else {
+            stageBody = stage;
+        }
+        if (typeof stageBody.id !== "string" || !stageBody.id.trim()) {
+            return textResult({ error: "stage.id is required" }, true);
+        }
+        const stageId = stageBody.id;
+        // A call-level model override wins over both the stage's own declared
+        // model and the global default: it replaces the field the stage body
+        // itself would otherwise resolve through, rather than adding a new
+        // tier to resolveModel's stage > pipeline > global chain.
+        const effectiveStageBody = model !== undefined ? { ...stageBody, model } : stageBody;
+        const pipeline = {
+            id: `standalone-${stageId}`,
+            stages: [effectiveStageBody],
+        };
+        let result;
+        try {
+            result = await manager.startRun({ pipeline, task: taskInput });
+        }
+        catch (err) {
+            if (err instanceof PipelineValidationError) {
+                return textResult({ error: "Stage validation failed", validation: err.result }, true);
+            }
+            throw err;
+        }
+        if (!result.ok) {
+            const { ok: _ok, reason, ...rest } = result;
+            return textResult({ error: reason, ...rest }, true);
+        }
+        const runId = result.runId;
+        if (!blocking) {
+            return textResult({ runId, stageId });
+        }
+        const waited = await waitRun({ store, runId, timeoutMs: timeout_ms, until: "any" });
+        if (!waited.ok) {
+            return textResult({
+                error: waited.error,
+                ...(waited.status !== undefined ? { status: waited.status } : {}),
+                ...(waited.code !== undefined ? { code: waited.code } : {}),
+            }, true);
+        }
+        const stageProjection = waited.run.stages.find((s) => s.stage_id === stageId);
+        if (isTerminalProjection(waited.run)) {
+            return textResult({
+                runId,
+                stageId,
+                status: "completed",
+                envelope: stageProjection?.envelope ?? null,
+            });
+        }
+        if (isWaitingProjection(waited.run)) {
+            return textResult({
+                runId,
+                stageId,
+                status: "needs_input",
+                pending_prompt: stageProjection?.pending_prompt,
+                waiting_kind: waited.run.waiting_kind,
+                waiting_prompt_id: waited.run.waiting_prompt_id,
+                waiting_summary: waited.run.waiting_summary,
+            });
+        }
+        return textResult({ runId, stageId, status: "timeout" });
+    });
     server.registerTool("get_run", {
         description: "Poll a run: status, stage statuses, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events, get_envelope, or get_stage_verification for stage detail.",
         inputSchema: z.object({

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.23.0";
+export declare const PACKAGE_VERSION = "0.25.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.23.0";
+export const PACKAGE_VERSION = "0.25.0";

package/dist/runstore/createStore.d.ts

@@ -1,3 +1,4 @@
+import type Database from "better-sqlite3";
 import type { RunStore } from "./port.js";
 export type RunStoreKind = "sqlite";
 export type RunStoreConfig = {
@@ -7,6 +8,15 @@ export type RunStoreConfig = {
     kind?: RunStoreKind | "disk";
 };
 export declare const DISK_STORE_REJECTED = "SF_STORE=disk is no longer a live RunStore. SQLite is the only adapter. Disk-era .stageflow/runs trees import automatically when the SQLite store is empty.";
+/**
+ * Composition-root factory: hands back the concrete SQLite connection alongside the `RunStore`,
+ * for the one caller wiring a second, colocated store (A2A's tables) into the same `state.db`
+ * file. Ordinary call sites use `createRunStore` below and never see this.
+ */
+export declare function createRunStoreWithConnection(config: RunStoreConfig): {
+    store: RunStore;
+    connection: Database.Database;
+};
 /**
  * Factory at the application edge. Call sites should receive the returned `RunStore`
  * and must not branch on backend kind.