stageflow 0.19.0 → 0.25.0

package/dist/runtime/runManager.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
+import { RunSubmissionExistsError } from "../runstore/submission.js";
 import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
+import { findProjectRoot } from "../project/findProjectRoot.js";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
 import { loadRunContext } from "./resumeReconstruct.js";
 import { assertTimedOutStageEligible, reconstructTimedOutAndContinue, } from "./resumeTimedOut.js";
@@ -12,7 +14,7 @@ import { resolveFeedbackLoopDecision, } from "./feedbackLoopDecision.js";
 import { RunRetryCoordinator, readRetryRootWaitTimeoutMs, } from "./runRetryCoordinator.js";
 import { readMaxActiveStageProcesses, readMaxActiveStagesPerRun, readStageExecutionMode, } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
-import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, projectSettingsContext, readMaxConcurrentFromContext, writeMaxConcurrentToContext, } from "./settingsFile.js";
+import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, readMaxConcurrentFromGlobal, writeMaxConcurrentToGlobal, } from "./settingsFile.js";
 import { StageHitlController, waitKey, } from "./stageHitl.js";
 import { resolveAndValidateCheckout, } from "./stageRoots.js";
 import { orchestrateAnswerResume } from "./answerResume.js";
@@ -21,6 +23,12 @@ import { resumeSessionFilePath } from "./stageAttemptContext.js";
 import { resolveStartTaskInput } from "./taskInput.js";
 import { failStageAsInterrupted, syncRunStatusFromStages, } from "./stageRecovery.js";
 import { blocksGenericRetry, manualRecoveryEligibility, readManualRecoveryState, } from "./manualRecoveryState.js";
+function existingSubmissionResult(existing, request) {
+    if (existing.requestHash !== request.requestHash) {
+        return { ok: false, status: 409, reason: "Submission key was already used for different input" };
+    }
+    return { ok: true, runId: existing.runId, reused: true };
+}
 const DEFAULT_MAX_CONCURRENT = 3;
 const STARTUP_RECONCILE_REASON = "process_interrupted: no active worker (server restart)";
 const OPERATOR_ABANDON_REASON = "process_interrupted: operator abandoned stage";
@@ -44,6 +52,7 @@ async function toCheckoutLeaseKey(absPath) {
 }
 export class RunManager {
     options;
+    submissionsInFlight = new Map();
     active = new Map();
     checkoutLeases = new Map();
     provisionalIds = new Set();
@@ -94,10 +103,9 @@ export class RunManager {
         this.cwd = options.cwd ?? process.cwd();
         this.projectRoot = options.projectRoot ?? this.cwd;
         this.isGitProject = options.isGitProject ?? false;
-        const settingsCtx = projectSettingsContext(this.cwd, this.projectRoot, this.isGitProject);
         this.maxConcurrent =
             options.maxConcurrent ??
-                readMaxConcurrentFromContext(settingsCtx) ??
+                readMaxConcurrentFromGlobal() ??
                 parseMaxConcurrent(process.env.STAGEFLOW_MAX_CONCURRENT_RUNS);
         this.maxActiveStagesPerRun = readMaxActiveStagesPerRun(process.env, options.maxActiveStagesPerRun);
         this.executionMode = readStageExecutionMode(process.env, options.executionMode);
@@ -119,7 +127,7 @@ export class RunManager {
             throw new Error(INVALID_SLOT_COUNT_MESSAGE);
         }
         this.maxConcurrent = parsed;
-        writeMaxConcurrentToContext(projectSettingsContext(this.cwd, this.projectRoot, this.isGitProject), parsed);
+        writeMaxConcurrentToGlobal(parsed);
         return this.getHealth();
     }
     getActiveCount() {
@@ -348,8 +356,48 @@ export class RunManager {
         }
         return { ok: true, runId, stageId };
     }
-    async startRun(input) {
+    async startRunOnce(input, submission) {
+        if (!submission.key.trim() || submission.key.length > 256 || !/^[a-f0-9]{64}$/.test(submission.requestHash)) {
+            return { ok: false, status: 400, reason: "Submission requires a key and SHA-256 request hash" };
+        }
+        const pending = this.submissionsInFlight.get(submission.key);
+        if (pending) {
+            if (pending.requestHash !== submission.requestHash) {
+                return { ok: false, status: 409, reason: "Submission key was already used for different input" };
+            }
+            const result = await pending.result;
+            return result.ok ? { ...result, reused: true } : result;
+        }
+        const result = this.startSubmittedRun(input, submission);
+        this.submissionsInFlight.set(submission.key, { requestHash: submission.requestHash, result });
+        try {
+            return await result;
+        }
+        finally {
+            this.submissionsInFlight.delete(submission.key);
+        }
+    }
+    async startSubmittedRun(input, submission) {
+        const existing = await this.options.store.getRunBySubmission(submission.key);
+        if (existing)
+            return existingSubmissionResult(existing, submission);
+        try {
+            const result = await this.startRun(input, submission);
+            return result.ok ? { ok: true, runId: result.runId, reused: false, done: result.done } : result;
+        }
+        catch (error) {
+            if (error instanceof RunSubmissionExistsError)
+                return existingSubmissionResult(error.submission, submission);
+            throw error;
+        }
+    }
+    async startRun(input, submission) {
         const cwd = this.options.cwd ?? process.cwd();
+        // An inline pipeline has no filesystem anchor to derive a project root from.
+        const derivedProjectRoot = typeof input.pipeline === "string"
+            ? (findProjectRoot(path.dirname(path.resolve(cwd, input.pipeline))) ??
+                this.projectRoot)
+            : this.projectRoot;
         let resolved;
         try {
             resolved = resolveStartTaskInput(input, cwd);
@@ -384,7 +432,7 @@ export class RunManager {
             gitSha: input.gitSha,
             ciPrUrl: input.ciPrUrl,
             ciJobUrl: input.ciJobUrl,
-        }, undefined, resolved.kind === "path" ? resolved.taskPath : undefined);
+        }, derivedProjectRoot, resolved.kind === "path" ? resolved.taskPath : undefined, submission);
     }
     async rerun(runId) {
         const cwd = this.options.cwd ?? process.cwd();
@@ -456,6 +504,7 @@ export class RunManager {
         }
         const insertedForResume = !wasActive;
         try {
+            const runProjectRoot = detail.project_root ?? this.projectRoot;
             const done = reconstructTimedOutAndContinue({
                 runId,
                 stageId,
@@ -463,9 +512,9 @@ export class RunManager {
                 store: this.options.store,
                 hitl: this.hitl,
                 executionMode: this.executionMode,
-                cwd: this.cwd,
+                cwd: runProjectRoot,
                 maxActiveStagesPerRun: this.maxActiveStagesPerRun,
-                factoryCwd: this.projectRoot,
+                factoryCwd: runProjectRoot,
                 ...(this.stageProcessLauncher !== undefined
                     ? { stageProcessLauncher: this.stageProcessLauncher }
                     : {}),
@@ -585,6 +634,7 @@ export class RunManager {
             };
         }
         try {
+            let meta;
             let orchestrationConflict = this.active.has(runId) &&
                 !this.attachedWaiting.has(waitKey(runId, stageId));
             if (!this.retryCoordinator.isActive(runId)) {
@@ -607,7 +657,7 @@ export class RunManager {
                 let detail;
                 try {
                     detail = await this.options.store.readRun(runId);
-                    await this.options.store.readRunMeta(runId);
+                    meta = await this.options.store.readRunMeta(runId);
                 }
                 catch {
                     this.retryInFlight.delete(retryKey);
@@ -626,12 +676,21 @@ export class RunManager {
                     }
                 }
             }
+            if (meta === undefined) {
+                try {
+                    meta = await this.options.store.readRunMeta(runId);
+                }
+                catch {
+                    this.retryInFlight.delete(retryKey);
+                    return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
+                }
+            }
             const result = await this.retryCoordinator.retryStage({
                 runId,
                 stageId,
                 store: this.options.store,
                 agent: this.options.agent,
-                cwd: this.cwd,
+                cwd: meta.project_root ?? this.projectRoot,
                 operatorCatalog: this.options.operatorCatalog,
                 maxActiveStagesPerRun: this.maxActiveStagesPerRun,
                 executionMode: this.executionMode,
@@ -980,6 +1039,7 @@ export class RunManager {
                 };
             }
             const { meta, task, loaded } = await loadRunContext(this.options.store, runId, this.cwd);
+            const runProjectRoot = meta.project_root ?? this.projectRoot;
             const done = runPipelineDag({
                 prepared: {
                     task,
@@ -990,8 +1050,8 @@ export class RunManager {
                     },
                     agent: this.options.agent,
                     store: this.options.store,
-                    cwd: this.cwd,
-                    projectRoot: this.projectRoot,
+                    cwd: runProjectRoot,
+                    projectRoot: runProjectRoot,
                     checkoutRoot: meta.checkout_root,
                     hitl: this.hitl,
                     operatorCatalog: this.options.operatorCatalog,
@@ -1041,10 +1101,12 @@ export class RunManager {
         const sessionFilePath = resumeSessionFilePath(workspaceDir, stageId, attempt);
         const eventOptions = { attempt };
         try {
+            const runMeta = await store.readRunMeta(runId);
+            const runProjectRoot = runMeta.project_root ?? this.projectRoot;
             const launchResult = await launcher.launch({
                 runId,
                 stageId,
-                rootDir: this.projectRoot,
+                rootDir: runProjectRoot,
                 mode: "resume",
                 resumeAnswer: opaqueAnswer,
                 attempt,
@@ -1079,8 +1141,8 @@ export class RunManager {
                     run: { runId, workspaceDir: store.getWorkspaceDir(runId) },
                     agent: this.options.agent,
                     store,
-                    cwd: this.cwd,
-                    projectRoot: this.projectRoot,
+                    cwd: meta.project_root ?? this.projectRoot,
+                    projectRoot: meta.project_root ?? this.projectRoot,
                     checkoutRoot: meta.checkout_root,
                     hitl: this.hitl,
                     operatorCatalog: this.options.operatorCatalog,
@@ -1137,7 +1199,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath, submission) {
         let checkoutKey;
         try {
             const task = loadTaskFromYaml(taskYaml, taskLabel);
@@ -1159,6 +1221,7 @@ export class RunManager {
             return reserved.failure;
         try {
             const started = await startPipeline({
+                submission,
                 agent: this.options.agent,
                 store: this.options.store,
                 taskYaml,
@@ -1182,7 +1245,7 @@ export class RunManager {
         }
         catch (err) {
             this.clearReservation(reserved.provisionalId);
-            if (err instanceof PipelineValidationError) {
+            if (err instanceof PipelineValidationError || err instanceof RunSubmissionExistsError) {
                 throw err;
             }
             return {
@@ -1277,6 +1340,7 @@ export class RunManager {
             return false;
         }
         try {
+            const runProjectRoot = meta.project_root ?? this.projectRoot;
             const { meta: loadedMeta, task, loaded, workspaceDir } = await loadRunContext(this.options.store, runId, this.cwd);
             const promise = runPipelineDag({
                 prepared: {
@@ -1285,8 +1349,8 @@ export class RunManager {
                     run: { runId, workspaceDir },
                     agent: this.options.agent,
                     store: this.options.store,
-                    cwd: this.cwd,
-                    projectRoot: this.projectRoot,
+                    cwd: runProjectRoot,
+                    projectRoot: runProjectRoot,
                     checkoutRoot: loadedMeta.checkout_root,
                     hitl: this.hitl,
                     operatorCatalog: this.options.operatorCatalog,

package/dist/runtime/settingsFile.d.ts

@@ -23,6 +23,8 @@ export declare function readMaxConcurrentFromContext(ctx: ProjectContext): numbe
 export declare function readMaxConcurrentFromFile(cwd: string): number | undefined;
 export declare function writeMaxConcurrentToContext(ctx: ProjectContext, maxConcurrent: number): void;
 export declare function writeMaxConcurrentToFile(cwd: string, maxConcurrent: number): void;
+export declare function readMaxConcurrentFromGlobal(): number | undefined;
+export declare function writeMaxConcurrentToGlobal(maxConcurrent: number): void;
 export declare function readCredentialSourceFromFile(cwd: string): CredentialSource | undefined;
 export declare function writeCredentialSourceToContext(ctx: ProjectContext, credentialSource: CredentialSource): void;
 export declare function writeCredentialSourceToFile(cwd: string, credentialSource: CredentialSource): void;

package/dist/runtime/settingsFile.js

@@ -150,6 +150,25 @@ export function writeMaxConcurrentToContext(ctx, maxConcurrent) {
 export function writeMaxConcurrentToFile(cwd, maxConcurrent) {
     writeFactorySettings(cwd, { maxConcurrent });
 }
+export function readMaxConcurrentFromGlobal() {
+    return parseFactorySettingsFromRaw(readRawSettingsFromFile(globalSettingsFilePath())).maxConcurrent;
+}
+export function writeMaxConcurrentToGlobal(maxConcurrent) {
+    if (parseSlotCount(maxConcurrent) === undefined) {
+        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
+    }
+    const current = parseFactorySettingsFromRaw(readRawSettingsFromFile(globalSettingsFilePath()));
+    const next = { ...current, maxConcurrent };
+    const out = {};
+    if (next.maxConcurrent !== undefined) {
+        out.maxConcurrent = next.maxConcurrent;
+    }
+    if (next.credentialSource !== undefined) {
+        out.credentialSource = next.credentialSource;
+    }
+    mkdirSync(path.dirname(globalSettingsFilePath()), { recursive: true });
+    writeFileSync(globalSettingsFilePath(), `${JSON.stringify(out, null, 2)}\n`, "utf8");
+}
 export function readCredentialSourceFromFile(cwd) {
     return readFactorySettings(cwd).credentialSource;
 }

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -1,4 +1,5 @@
 import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunInput, StageSessionMode } from "../agent/port.js";
+import { type StageStreamLogWriter } from "./stageStreamLog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
@@ -23,6 +24,8 @@ export type StageAttemptOpenInput = {
     attemptCtx?: StageAttemptContext;
     operatorCatalog?: OperatorCatalog;
     onActivity?: StageRunInput["onActivity"];
+    /** Test seam; defaults to the real createStageStreamLogWriter. */
+    streamLogWriterFactory?: (streamLogPath: string) => StageStreamLogWriter;
     roots?: StageRoots;
     resumeToken?: string;
     sessionMode?: StageSessionMode;

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,7 +1,8 @@
 import { resolveSkillByName } from "../config/listSkills.js";
 import { mkdir } from "node:fs/promises";
 import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
-import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
+import { attemptArtifactsDir, attemptStreamLogPath } from "../runstore/workspaceLayout.js";
+import { createStageStreamLogWriter, } from "./stageStreamLog.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
 import { assertPriorInputPayload, payloadInstanceMismatch, } from "../envelope/payloadSchema.js";
@@ -199,6 +200,7 @@ export async function openStageAttempt(input) {
         return priorInput;
     const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
+    const streamWriter = (input.streamLogWriterFactory ?? createStageStreamLogWriter)(attemptStreamLogPath(input.workspaceDir, stageId, attempt));
     const resumeToken = input.resumeToken ??
         resumeSessionFilePath(input.workspaceDir, stageId, attempt);
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
@@ -231,7 +233,11 @@ export async function openStageAttempt(input) {
             : {}),
         resumeToken,
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
-        onActivity: input.onActivity,
+        onActivity: (event) => {
+            input.onActivity?.(event);
+            void streamWriter.flush();
+        },
+        onAssistantTextDelta: streamWriter.onDelta,
         forkEmitContext,
         cloneEmitContext,
         ...(feedbackLoopEmitContext !== undefined ? { feedbackLoopEmitContext } : {}),

package/dist/runtime/stageStreamLog.d.ts

@@ -0,0 +1,17 @@
+/** First line of every stream.log: the logical byte offset of the content that follows. */
+export declare const STREAM_LOG_HEADER_PREFIX = "BASE:";
+export declare function encodeStreamLogHeader(base: number): string;
+/** Split a stream.log buffer into its logical base offset and content bytes. */
+export declare function parseStreamLogHeader(raw: Buffer): {
+    base: number;
+    headerLength: number;
+};
+export type StageStreamLogWriter = {
+    onDelta(delta: string): void;
+    /** Idempotent; resolves once any pending buffered text has been written to disk. */
+    flush(): Promise<void>;
+};
+export declare function createStageStreamLogWriter(streamLogPath: string, options?: {
+    flushThrottleMs?: number;
+    capBytes?: number;
+}): StageStreamLogWriter;

package/dist/runtime/stageStreamLog.js

@@ -0,0 +1,89 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { STREAM_FLUSH_THROTTLE_MS } from "../agent/activityObserver.js";
+import { redactSecrets } from "../agent/streamLogRedact.js";
+const DEFAULT_CAP_BYTES = 256 * 1024;
+/** First line of every stream.log: the logical byte offset of the content that follows. */
+export const STREAM_LOG_HEADER_PREFIX = "BASE:";
+export function encodeStreamLogHeader(base) {
+    return `${STREAM_LOG_HEADER_PREFIX}${base}\n`;
+}
+/** Split a stream.log buffer into its logical base offset and content bytes. */
+export function parseStreamLogHeader(raw) {
+    const prefix = Buffer.from(STREAM_LOG_HEADER_PREFIX, "utf8");
+    if (raw.subarray(0, prefix.length).equals(prefix)) {
+        const newlineIdx = raw.indexOf(0x0a);
+        if (newlineIdx !== -1) {
+            const baseStr = raw.subarray(prefix.length, newlineIdx).toString("utf8");
+            const base = Number(baseStr);
+            if (Number.isFinite(base) && base >= 0) {
+                return { base, headerLength: newlineIdx + 1 };
+            }
+        }
+    }
+    return { base: 0, headerLength: 0 };
+}
+async function appendChunk(streamLogPath, chunk, capBytes) {
+    await mkdir(path.dirname(streamLogPath), { recursive: true });
+    let base = 0;
+    let contentBytes;
+    try {
+        const raw = await readFile(streamLogPath);
+        const parsed = parseStreamLogHeader(raw);
+        base = parsed.base;
+        contentBytes = raw.subarray(parsed.headerLength);
+    }
+    catch {
+        contentBytes = Buffer.alloc(0);
+    }
+    contentBytes = Buffer.concat([contentBytes, Buffer.from(chunk, "utf8")]);
+    const headerBytes = Buffer.from(encodeStreamLogHeader(base), "utf8");
+    if (headerBytes.length + contentBytes.length > capBytes) {
+        let dropBytes = Math.floor(contentBytes.length / 2);
+        // Never split a multi-byte UTF-8 codepoint: skip past continuation bytes.
+        while (dropBytes < contentBytes.length &&
+            (contentBytes[dropBytes] & 0xc0) === 0x80) {
+            dropBytes++;
+        }
+        base += dropBytes;
+        contentBytes = contentBytes.subarray(dropBytes);
+    }
+    const finalHeader = Buffer.from(encodeStreamLogHeader(base), "utf8");
+    await writeFile(streamLogPath, Buffer.concat([finalHeader, contentBytes]));
+}
+export function createStageStreamLogWriter(streamLogPath, options = {}) {
+    const flushThrottleMs = options.flushThrottleMs ?? STREAM_FLUSH_THROTTLE_MS;
+    const capBytes = options.capBytes ?? DEFAULT_CAP_BYTES;
+    let buffer = "";
+    let timer = null;
+    // Serializes disk writes so the throttle timer and an eager flush() never race.
+    let writeChain = Promise.resolve();
+    function flushNow() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (!buffer)
+            return writeChain;
+        const chunk = redactSecrets(buffer);
+        buffer = "";
+        writeChain = writeChain.then(() => appendChunk(streamLogPath, chunk, capBytes));
+        return writeChain;
+    }
+    return {
+        onDelta(delta) {
+            if (!delta)
+                return;
+            buffer += delta;
+            if (timer === null) {
+                timer = setTimeout(() => {
+                    timer = null;
+                    void flushNow();
+                }, flushThrottleMs);
+            }
+        },
+        flush() {
+            return flushNow();
+        },
+    };
+}

package/dist/runtime/stageWorker.js

@@ -3,6 +3,7 @@ import { asAgentBackendId } from "../agent/agentBackend.js";
 import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
 import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
 import { createRunStore } from "../runstore/createStore.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { loadRunContext } from "./resumeReconstruct.js";
 import { bindPiAgentDirEnv, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
 import { runStage, isRunStageWaiting, } from "./stageRunner.js";
@@ -11,7 +12,7 @@ import { attemptContext } from "./stageAttemptContext.js";
 import { loadActiveFeedbackLoopContext } from "./feedbackLoopCoordinator.js";
 import { outcomeToWorkerResult, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 export async function runStageWorker(input) {
-    const store = createRunStore({ rootDir: input.rootDir });
+    const store = createRunStore({ rootDir: globalStageflowHome() });
     const { meta, task, loaded } = await loadRunContext(store, input.runId, input.rootDir);
     const definitionId = definitionIdForInstance(meta.pipeline_dag, input.stageId);
     const stage = loaded.stages.find((s) => s.id === definitionId);

package/dist/server/bootstrap.d.ts

@@ -1,3 +1,4 @@
+import { type A2aHost } from "../a2a/server.js";
 import type { AgentPort } from "../agent/port.js";
 import type { ProviderAuthContext } from "../agent/providerAuth.js";
 import { type RunStoreKind } from "../runstore/createStore.js";
@@ -18,6 +19,7 @@ export type StageflowHostOptions = {
     runChangeBus?: RunChangeBus;
 };
 export type StageflowHostBootstrap = {
+    a2a?: A2aHost;
     cwd: string;
     agentDir: string;
     rootDir: string;

package/dist/server/bootstrap.js

@@ -1,5 +1,7 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { createRunStore } from "../runstore/createStore.js";
+import { createA2aHost } from "../a2a/server.js";
+import { createRunStoreWithConnection } from "../runstore/createStore.js";
+import { resolveA2aConfigPath } from "../a2a/configDiscovery.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { findProjectRoot } from "../project/findProjectRoot.js";
 import { RunManager } from "../runtime/runManager.js";
@@ -14,8 +16,16 @@ export async function bootstrapStageflowHost(options) {
     const isGitProject = options.rootDir !== undefined
         ? findProjectRoot(rootDir) !== null
         : ctx.isGitProject;
-    const rawStore = options.store ??
-        createRunStore({ rootDir, kind: options.storeKind });
+    let rawStore;
+    let sqliteConnection;
+    if (options.store) {
+        rawStore = options.store;
+    }
+    else {
+        const created = createRunStoreWithConnection({ rootDir: ctx.globalHome, kind: options.storeKind });
+        rawStore = created.store;
+        sqliteConnection = created.connection;
+    }
     const boundBus = isRunStoreWrapped(rawStore)
         ? getRunChangeBusFromWrappedStore(rawStore)
         : undefined;
@@ -41,8 +51,16 @@ export async function bootstrapStageflowHost(options) {
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
     });
-    const mcpHandler = createMcpHttpHandler({ manager, store, cwd, runChangeBus }, { mcpStateless });
+    const mcpHandler = createMcpHttpHandler({
+        manager,
+        store,
+        cwd,
+        runChangeBus,
+        providerAuthContext: options.providerAuthContext,
+        projectRoot: rootDir,
+    }, { mcpStateless });
     return {
+        a2a: await createA2aHost({ manager, runStore: store, rootDir, connection: sqliteConnection }, resolveA2aConfigPath(rootDir)),
         cwd,
         agentDir,
         rootDir,

package/dist/server/createHttpHost.js

@@ -17,6 +17,12 @@ export async function createHttpHost(options) {
         const method = req.method ?? "GET";
         const url = new URL(req.url ?? "/", `http://${host}:${port}`);
         const pathname = url.pathname;
+        if (pathname === "/api/a2a/status" && method === "GET") {
+            json(res, 200, boot.a2a?.status ?? { state: "disabled" });
+            return;
+        }
+        if (await boot.a2a?.handle(req, res, pathname))
+            return;
         if (pathname === "/mcp") {
             if (!validateMcpHost(req, res) || !validateMcpOrigin(req, res)) {
                 return;

package/dist/server/ensureGlobalService.d.ts

@@ -0,0 +1,35 @@
+import { type ChildProcess, spawn as spawnDefault } from "node:child_process";
+/** Coarse up/down probe result, used by CLI code that only needs "is it safe to talk to the host." */
+export type HostProbeResult = "up" | "down";
+/**
+ * Finer-grained probe result used to auto-start: "unreachable" (nothing
+ * listening, safe to spawn) is distinct from "unhealthy" (something is
+ * listening on the port but didn't answer with valid health JSON, so it's
+ * almost certainly not our service and spawning would just collide).
+ */
+export type ServiceProbeResult = "up" | "unreachable" | "unhealthy";
+export declare function hostBaseUrl(): string;
+export declare function probeGlobalServiceDetailed(): Promise<ServiceProbeResult>;
+export declare function defaultProbeHost(): Promise<HostProbeResult>;
+export type EnsureGlobalServiceResult = {
+    ok: true;
+    alreadyRunning: boolean;
+} | {
+    ok: false;
+    reason: "port_occupied" | "spawn_failed" | "timed_out";
+    message: string;
+};
+export interface EnsureGlobalServiceOptions {
+    /** Path to the CLI entry script to spawn `<entry> mcp` against. Defaults to the running process's own entry (process.argv[1]). */
+    cliEntry?: string;
+    probeHost?: () => Promise<ServiceProbeResult>;
+    spawnFn?: (command: string, args: string[], options: Parameters<typeof spawnDefault>[2]) => ChildProcess;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * Health-probe-then-spawn: makes sure a global Stageflow service is
+ * reachable at the well-known port, starting one headlessly (`<cliEntry>
+ * mcp`, detached) if nothing answers yet. No-ops if one is already up.
+ */
+export declare function ensureGlobalService(options?: EnsureGlobalServiceOptions): Promise<EnsureGlobalServiceResult>;