stageflow 0.23.0 → 0.27.0

package/README.md

@@ -35,9 +35,11 @@ The same pipeline runs three ways without rewriting anything:
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
+- **Standalone stage execution** — run a single stage directly with `run_stage` (MCP tool, `sf run-stage` CLI, or the A2A `run_stage` operation), no pipeline file required; chain calls with `envelope_ref` (one or many prior results) instead of a pipeline DAG
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
-- **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
+- **Definition-time graph view** — `sf graph --pipeline <path>` prints how a pipeline is wired before any run (terminal diagram or `--json`)
+- **SQLite run store** — global `~/.stageflow/.stageflow/` state plus per-run workspaces, shared across every project since Stageflow became a single auto-starting service
 
 ## Architecture at a glance
 
@@ -96,6 +98,8 @@ sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
 
 Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
+**Docker Compose** (UI + MCP in one Host): copy [`.env.example`](.env.example) → `.env`, set `STAGEFLOW_CONTROL_TOKEN`, then `docker compose up --build -d`. Checklist: [docs/docker.md](docs/docker.md#local-try-compose).
+
 ## Connect a model provider
 
 Each stage sets a **`model`** id in YAML (e.g. `anthropic/claude-sonnet-4-5`). The matching provider must be authenticated before runs succeed — `sf validate` does not check auth.
@@ -184,16 +188,28 @@ See [docs/ci.md](docs/ci.md) for the full CI recipe and [`.github/actions/sf-run
 
 ## State
 
-Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository (SQLite + per-run workspaces under `.stageflow/runs/`). Global config and `sf_owned` auth live under **`~/.stageflow/`**. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
+Runtime state (SQLite run store + per-run workspaces) is **global** — `~/.stageflow/.stageflow/` — shared across every project on the machine, since Stageflow became a single auto-starting service. Global config and `sf_owned` auth live directly under **`~/.stageflow/`**; per-project settings (`maxConcurrent`, `credentialSource`) still live at `<git-root>/.stageflow/settings.json`. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
 
 ## MCP
 
 Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.
 
-HITL-aware tools include `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Inspect tools (`list_providers`, `list_models`, `describe_pipeline`, …) are read-only. Full tool list: [docs/mcp.md](docs/mcp.md).
+Stageflow runs as **one global auto-starting service per machine** (not one process per project): `sf run`, `sf run-stage`, and `sf runs *` health-probe the well-known port and spawn the service headlessly if nothing answers, so you do not have to start `sf ui`/`sf mcp` by hand before using the CLI.
+
+HITL-aware tools include `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Inspect tools (`list_providers`, `list_models`, `describe_pipeline`, …) are read-only. `run_stage` runs a single stage directly, no pipeline file required — see [Standalone stages](#standalone-stages) below. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).
 
+## Standalone stages
+
+Run a single stage directly, without authoring a pipeline: the MCP `run_stage` tool, the `sf run-stage` CLI command, and (over A2A, wildcard-access — see below) the `run_stage` operation all give a calling agent (Claude Code, Cursor, Codex, Pi, ...) the same capability, so it can decide what to run next itself rather than following a pre-authored DAG. Chain calls with `envelope_ref` — a reference to a previous call's stored envelope, one or many at once — instead of copying results around by hand. Full reference: [docs/mcp.md#run_stage](docs/mcp.md#run_stage), [docs/cli-reference.md#sf-run-stage](docs/cli-reference.md#sf-run-stage).
+
+## A2A
+
+MCP is for your own trusted, local tools. A2A's `invoke` operation is a second, gated door for other agents on the network: publish specific pipelines in a separate `a2a.yaml`, and outside callers invoke them over JSON-RPC with a bearer token, poll for results, and download frozen artifacts -- never touching your internal run IDs or unpublished pipelines. A2A also exposes `run_stage` (above) with deliberately no gate: any caller with a valid bearer token can run any catalog or inline stage/pipeline, the same wildcard-access default MCP and the CLI give a local harness -- a temporary trade-off, not a hardened access boundary; keep that in mind before exposing a host with real callers.
+
+Drop `a2a.yaml` next to `stageflow.yaml` and it's auto-discovered when `sf ui` starts -- no extra flag needed. `sf a2a add-caller <id>` registers a caller and generates its token. Full reference: [docs/a2a.md](docs/a2a.md).
+
 ## Stageflow vs Conductor
 
 Both projects address multi-step agent workflows. They differ in orchestration model and runtime.
@@ -237,12 +253,15 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
-| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
+| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf run-stage`, `sf graph`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
 | [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
+| [docs/verified-stage-execution.md](docs/verified-stage-execution.md) | After-phase `verify`, evidence, and `on_verify_fail` repair / manual recovery |
 | [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
 | [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
-| [docs/mcp.md](docs/mcp.md) | MCP tool reference |
+| [docs/mcp.md](docs/mcp.md) | MCP tool reference, including standalone `run_stage` |
+| [docs/a2a.md](docs/a2a.md) | Publish pipelines for other agents to call over JSON-RPC (A2A), plus the wildcard-access `run_stage` operation |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
+| [docs/docker.md](docs/docker.md) | Docker Compose local try, image pull/run, backup, self-hosting |
 | [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
 | [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 

package/dist/a2a/configDiscovery.d.ts

@@ -0,0 +1,9 @@
+/** Where `a2a.yaml` lives when nothing else says otherwise: next to `stageflow.yaml`, at the project root. */
+export declare function a2aConfigPathFor(projectRoot: string): string;
+/**
+ * `STAGEFLOW_A2A_CONFIG` always wins when set (an explicit override, e.g. a config file living
+ * outside the project). Otherwise, `<projectRoot>/a2a.yaml` is used if it exists -- the same
+ * auto-discovery convention `stageflow.yaml` already follows for the pipeline catalog. Returns
+ * undefined (A2A disabled) when neither is present.
+ */
+export declare function resolveA2aConfigPath(projectRoot: string, env?: NodeJS.ProcessEnv): string | undefined;

package/dist/a2a/configDiscovery.js

@@ -0,0 +1,18 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+/** Where `a2a.yaml` lives when nothing else says otherwise: next to `stageflow.yaml`, at the project root. */
+export function a2aConfigPathFor(projectRoot) {
+    return path.join(projectRoot, "a2a.yaml");
+}
+/**
+ * `STAGEFLOW_A2A_CONFIG` always wins when set (an explicit override, e.g. a config file living
+ * outside the project). Otherwise, `<projectRoot>/a2a.yaml` is used if it exists -- the same
+ * auto-discovery convention `stageflow.yaml` already follows for the pipeline catalog. Returns
+ * undefined (A2A disabled) when neither is present.
+ */
+export function resolveA2aConfigPath(projectRoot, env = process.env) {
+    if (env.STAGEFLOW_A2A_CONFIG)
+        return env.STAGEFLOW_A2A_CONFIG;
+    const candidate = a2aConfigPathFor(projectRoot);
+    return existsSync(candidate) ? candidate : undefined;
+}

package/dist/a2a/contracts.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+export type ApplicationErrorCategory = "invalid-input" | "unknown-capability" | "busy" | "message-conflict" | "stale-question" | "export-failed" | "not-found";
+export declare class A2aApplicationError extends Error {
+    readonly category: ApplicationErrorCategory;
+    readonly details?: Record<string, string> | undefined;
+    constructor(category: ApplicationErrorCategory, message: string, details?: Record<string, string> | undefined);
+}
+/**
+ * Same shape as TaskFile (src/types/task.ts), duplicated locally the same way
+ * src/mcp/catalogTools.ts's own taskFileSchema is: deliberately not shared
+ * across module boundaries for a schema this small.
+ */
+declare const taskFileSchema: z.ZodObject<{
+    id: z.ZodString;
+    goal: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodString>;
+    checkout: z.ZodOptional<z.ZodString>;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const envelopeRefSchema: z.ZodObject<{
+    runId: z.ZodString;
+    stageId: z.ZodString;
+    attempt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type InvokeCommand = {
+    kind: "invoke";
+    messageId: string;
+    contextId?: string;
+    capability: string;
+    input: unknown;
+};
+export type AnswerCommand = {
+    kind: "answer";
+    messageId: string;
+    contextId?: string;
+    taskId: string;
+    handle: string;
+    answer: {
+        kind: "free_text";
+        text: string;
+    };
+};
+export type TaskFileInput = z.infer<typeof taskFileSchema>;
+export type EnvelopeRefInput = z.infer<typeof envelopeRefSchema>;
+/**
+ * ADR-0001's wildcard-access operation. Unlike InvokeCommand, `stage`/`pipeline`
+ * name the target directly (a catalog path or an inline body) instead of a
+ * published capability id, so no publication/allowlist lookup is possible or
+ * required to route it.
+ */
+export type RunStageCommand = {
+    kind: "run_stage";
+    messageId: string;
+    contextId?: string;
+    stage?: string | Record<string, unknown>;
+    pipeline?: string | Record<string, unknown>;
+    project_root?: string;
+    task_path?: string;
+    task?: TaskFileInput;
+    envelope_ref?: EnvelopeRefInput | EnvelopeRefInput[];
+    checkout?: string;
+    model?: string;
+    blocking?: boolean;
+    timeout_ms?: number;
+};
+export type ValidatedMessage = InvokeCommand | AnswerCommand | RunStageCommand;
+export type IncomingMessage = {
+    messageId: string;
+    contextId?: string;
+    taskId?: string;
+    parts: Array<{
+        content?: {
+            $case: "data";
+            value: unknown;
+        } | {
+            $case: string;
+            value: unknown;
+        };
+    }>;
+};
+export declare function parseIncomingMessage(message: IncomingMessage): ValidatedMessage;
+export declare function contentHash(value: unknown): string;
+export declare function submissionKeyFor(callerId: string, capability: string, hash: string): string;
+export declare function encodePromptHandle(taskId: string, stageId: string, promptId: string): string;
+export declare function decodePromptHandle(handle: string): {
+    taskId: string;
+    stageId: string;
+    promptId: string;
+} | undefined;
+export declare function newTaskId(): string;
+export declare function newContextId(): string;
+export declare function newArtifactId(): string;
+export {};

package/dist/a2a/contracts.js

@@ -0,0 +1,164 @@
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+export class A2aApplicationError extends Error {
+    category;
+    details;
+    constructor(category, message, details) {
+        super(message);
+        this.category = category;
+        this.details = details;
+        this.name = "A2aApplicationError";
+    }
+}
+const invokeDataPart = z.object({
+    contractVersion: z.literal(1),
+    operation: z.literal("invoke"),
+    capability: z.string().min(1),
+    input: z.unknown(),
+});
+const freeTextAnswerPayload = z.object({
+    kind: z.literal("free_text"),
+    text: z.string(),
+});
+const answerDataPart = z.object({
+    contractVersion: z.literal(1),
+    operation: z.literal("answer"),
+    prompt: z.string().min(1),
+    answer: freeTextAnswerPayload,
+});
+/**
+ * Same shape as TaskFile (src/types/task.ts), duplicated locally the same way
+ * src/mcp/catalogTools.ts's own taskFileSchema is: deliberately not shared
+ * across module boundaries for a schema this small.
+ */
+const taskFileSchema = z.object({
+    id: z.string(),
+    goal: z.string(),
+    context: z.string().optional(),
+    constraints: z.string().optional(),
+    checkout: z.string().optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
+});
+const envelopeRefSchema = z.object({
+    runId: z.string().min(1),
+    stageId: z.string().min(1),
+    attempt: z.number().int().positive().optional(),
+});
+/**
+ * ADR-0001's wildcard-access operation: invokes any catalog or inline
+ * stage/pipeline directly, bypassing the `publications`/`allowed_callers`
+ * allowlist that `invoke` enforces. Mirrors run_stage's MCP call shape
+ * (src/mcp/catalogTools.ts) closely on purpose so a harness gets the same
+ * capability over A2A that it gets over MCP/CLI.
+ */
+const runStageDataPart = z
+    .object({
+    contractVersion: z.literal(1),
+    operation: z.literal("run_stage"),
+    stage: z.union([z.string().min(1), z.record(z.string(), z.unknown())]).optional(),
+    pipeline: z.union([z.string().min(1), z.record(z.string(), z.unknown())]).optional(),
+    project_root: z.string().optional(),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+    envelope_ref: z.union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)]).optional(),
+    checkout: z.string().optional(),
+    model: z.string().optional(),
+    blocking: z.boolean().optional(),
+    timeout_ms: z.number().optional(),
+})
+    .refine((data) => [data.stage, data.pipeline].filter((v) => v !== undefined).length === 1, {
+    message: "Exactly one of stage or pipeline is required",
+})
+    .refine((data) => [data.task_path, data.task, data.envelope_ref].filter((v) => v !== undefined).length === 1, { message: "Exactly one of task_path, task, or envelope_ref is required" });
+const dataPart = z.union([invokeDataPart, answerDataPart, runStageDataPart]);
+export function parseIncomingMessage(message) {
+    const dataParts = message.parts.filter((part) => part.content?.$case === "data");
+    if (dataParts.length !== 1) {
+        throw new A2aApplicationError("invalid-input", "Message must carry exactly one structured data part with the invoke/answer contract");
+    }
+    const parsed = dataPart.safeParse(dataParts[0].content.value);
+    if (!parsed.success) {
+        throw new A2aApplicationError("invalid-input", "Message data part does not match the invoke/answer contract: " + parsed.error.message);
+    }
+    if (parsed.data.operation === "invoke") {
+        return {
+            kind: "invoke",
+            messageId: message.messageId,
+            contextId: message.contextId || undefined,
+            capability: parsed.data.capability,
+            input: parsed.data.input,
+        };
+    }
+    if (parsed.data.operation === "run_stage") {
+        return {
+            kind: "run_stage",
+            messageId: message.messageId,
+            contextId: message.contextId || undefined,
+            stage: parsed.data.stage,
+            pipeline: parsed.data.pipeline,
+            task_path: parsed.data.task_path,
+            task: parsed.data.task,
+            envelope_ref: parsed.data.envelope_ref,
+            checkout: parsed.data.checkout,
+            model: parsed.data.model,
+            blocking: parsed.data.blocking,
+            timeout_ms: parsed.data.timeout_ms,
+        };
+    }
+    if (!message.taskId) {
+        throw new A2aApplicationError("invalid-input", "An answer message must reference its task");
+    }
+    return {
+        kind: "answer",
+        messageId: message.messageId,
+        contextId: message.contextId || undefined,
+        taskId: message.taskId,
+        handle: parsed.data.prompt,
+        answer: parsed.data.answer,
+    };
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, canonicalize(value[key])]));
+    }
+    return value;
+}
+export function contentHash(value) {
+    return createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex");
+}
+export function submissionKeyFor(callerId, capability, hash) {
+    return "a2a:" + callerId + ":" + capability + ":" + hash;
+}
+const HANDLE_SEPARATOR = ":";
+export function encodePromptHandle(taskId, stageId, promptId) {
+    return Buffer.from([taskId, stageId, promptId].join(HANDLE_SEPARATOR), "utf8").toString("base64url");
+}
+export function decodePromptHandle(handle) {
+    let decoded;
+    try {
+        decoded = Buffer.from(handle, "base64url").toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const parts = decoded.split(HANDLE_SEPARATOR);
+    if (parts.length !== 3 || parts.some((part) => part.length === 0))
+        return undefined;
+    const taskId = parts[0];
+    const stageId = parts[1];
+    const promptId = parts[2];
+    return { taskId, stageId, promptId };
+}
+export function newTaskId() {
+    return randomUUID();
+}
+export function newContextId() {
+    return randomUUID();
+}
+export function newArtifactId() {
+    return randomUUID();
+}

package/dist/a2a/limits.d.ts

@@ -0,0 +1,14 @@
+export declare const RATE_LIMIT_PER_MINUTE = 60;
+export declare const RATE_LIMIT_BURST = 20;
+export declare const MAX_NONTERMINAL_TASKS_PER_CALLER = 2;
+export declare const TERMINAL_RETENTION_MS: number;
+export declare const MESSAGE_TOMBSTONE_RETENTION_MS: number;
+/** Token-bucket per caller: `capacity` burst, refilling at `perMinute` tokens/minute. Clock is injectable for deterministic tests. */
+export declare class RateLimiter {
+    private readonly capacity;
+    private readonly now;
+    private readonly buckets;
+    private readonly refillPerMs;
+    constructor(capacity?: number, perMinute?: number, now?: () => number);
+    tryConsume(key: string): boolean;
+}

package/dist/a2a/limits.js

@@ -0,0 +1,29 @@
+export const RATE_LIMIT_PER_MINUTE = 60;
+export const RATE_LIMIT_BURST = 20;
+export const MAX_NONTERMINAL_TASKS_PER_CALLER = 2;
+export const TERMINAL_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+export const MESSAGE_TOMBSTONE_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+/** Token-bucket per caller: `capacity` burst, refilling at `perMinute` tokens/minute. Clock is injectable for deterministic tests. */
+export class RateLimiter {
+    capacity;
+    now;
+    buckets = new Map();
+    refillPerMs;
+    constructor(capacity = RATE_LIMIT_BURST, perMinute = RATE_LIMIT_PER_MINUTE, now = Date.now) {
+        this.capacity = capacity;
+        this.now = now;
+        this.refillPerMs = perMinute / 60000;
+    }
+    tryConsume(key) {
+        const at = this.now();
+        const existing = this.buckets.get(key);
+        const elapsed = existing ? Math.max(0, at - existing.updatedAt) : 0;
+        const tokens = existing ? Math.min(this.capacity, existing.tokens + elapsed * this.refillPerMs) : this.capacity;
+        if (tokens < 1) {
+            this.buckets.set(key, { tokens, updatedAt: at });
+            return false;
+        }
+        this.buckets.set(key, { tokens: tokens - 1, updatedAt: at });
+        return true;
+    }
+}

package/dist/a2a/registry.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+declare const publicationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    project_root: z.ZodString;
+    pipeline: z.ZodString;
+    goal: z.ZodString;
+    repository: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    allowed_callers: z.ZodArray<z.ZodString>;
+    input_schema: z.ZodString;
+    results: z.ZodObject<{
+        stage: z.ZodString;
+        include_payload: z.ZodDefault<z.ZodBoolean>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    caller_answerable_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type PublicationConfig = z.infer<typeof publicationSchema>;
+export type Publication = PublicationConfig & {
+    revision: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: unknown;
+};
+export declare class PublicationRegistry {
+    readonly publicUrl: string;
+    readonly configPath: string;
+    private readonly publications;
+    private readonly credentials;
+    constructor(publicUrl: string, configPath: string, publications: readonly Publication[], credentials: readonly {
+        id: string;
+        hash: Buffer;
+    }[]);
+    authenticate(authorization: string | undefined): string | undefined;
+    list(caller: string): Publication[];
+    get(caller: string, id: string): Publication | undefined;
+    summaries(): Array<{
+        id: string;
+        name: string;
+        revision: string;
+    }>;
+    assertUnchanged(caller: string, id: string): Promise<void>;
+}
+export declare function loadPublicationRegistry(configPath: string, env?: NodeJS.ProcessEnv): Promise<PublicationRegistry>;
+export {};

package/dist/a2a/registry.js

@@ -0,0 +1,178 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+import { loadPipeline } from "../config/loadPipeline.js";
+import { compilePayloadSchema, isPayloadSchemaSubset } from "../envelope/payloadSchema.js";
+const identifier = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/);
+const publicationSchema = z.object({
+    id: identifier,
+    name: z.string().trim().min(1),
+    description: z.string().trim().min(1),
+    project_root: z.string().min(1),
+    pipeline: z.string().min(1),
+    goal: z.string().trim().min(1),
+    repository: z.string().trim().min(1).optional(),
+    ref: z.string().trim().min(1).optional(),
+    allowed_callers: z.array(identifier).min(1),
+    input_schema: z.string().min(1),
+    results: z.object({
+        stage: identifier,
+        include_payload: z.boolean().default(true),
+        artifacts: z.array(z.string().regex(/^[^/\\.][^/\\]*$/)).default([]),
+    }).strict(),
+    caller_answerable_stages: z.array(identifier).default([]),
+}).strict().superRefine((data, ctx) => {
+    const hasRepo = data.repository !== undefined;
+    const hasRef = data.ref !== undefined;
+    if (hasRepo && !hasRef) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "repository requires ref",
+            path: ["ref"],
+        });
+    }
+    if (hasRef && !hasRepo) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "ref requires repository",
+            path: ["repository"],
+        });
+    }
+});
+const configSchema = z.object({
+    version: z.literal(1),
+    public_url: z.string().url(),
+    callers: z.array(z.object({
+        id: identifier,
+        token_env: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
+    }).strict()).min(1),
+    publications: z.array(publicationSchema).min(1),
+}).strict();
+function digest(value) {
+    return createHash("sha256").update(value).digest();
+}
+function requireUnique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`Duplicate ${label}`);
+}
+function publicUrl(value) {
+    const url = new URL(value);
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) ||
+        url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+        throw new Error("public_url must be an HTTPS origin (HTTP allowed on loopback)");
+    }
+    return url.origin;
+}
+function validatePublication(config, loaded, input) {
+    const result = loaded.stages.find((stage) => stage.id === config.results.stage);
+    if (!result || loaded.dag.childrenOf[result.id]?.length ||
+        loaded.dag.nodes.some((node) => node.clone_cap !== undefined)) {
+        throw new Error(`Publication ${config.id} requires a fixed terminal result stage without cloning`);
+    }
+    for (const root of loaded.dag.roots) {
+        const stage = loaded.stages.find((candidate) => candidate.id === root);
+        if (!isPayloadSchemaSubset(stage.clone_input_schema, input)) {
+            throw new Error(`Publication ${config.id} input is incompatible with entry stage ${root}`);
+        }
+    }
+    for (const id of config.caller_answerable_stages) {
+        const stage = loaded.stages.find((candidate) => candidate.id === id);
+        if (!stage || stage.gate_kinds?.length !== 1 || stage.gate_kinds[0] !== "free_text") {
+            throw new Error(`Publication ${config.id} caller-answerable stage ${id} must allow only free_text`);
+        }
+    }
+    const declared = new Set(result.pre_emit_checks?.flatMap((check) => check.type === "artifact_declared" ? check.basename : []) ?? []);
+    for (const name of config.results.artifacts) {
+        if (!declared.has(name))
+            throw new Error(`Publication ${config.id} artifact ${name} needs an emit artifact check`);
+    }
+}
+async function readPublication(config) {
+    const loaded = await loadPipeline(config.pipeline, { cwd: config.project_root, projectRoot: config.project_root });
+    const input = JSON.parse(await readFile(config.input_schema, "utf8"));
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error(`Publication ${config.id} needs an object schema`);
+    compilePayloadSchema(input);
+    validatePublication(config, loaded, input);
+    const files = [...new Set([loaded.pipelinePath, ...Object.values(loaded.stageSources ?? {})
+                .flatMap((source) => source.kind === "file" ? [source.path] : [])])].sort();
+    const bodies = await Promise.all(files.map(async (file) => [file, await readFile(file, "utf8")]));
+    const revision = digest(JSON.stringify({ config, loaded, input, bodies })).toString("hex");
+    return {
+        ...config,
+        revision,
+        inputSchema: input,
+        outputSchema: loaded.stages.find((stage) => stage.id === config.results.stage).payload_schema,
+    };
+}
+export class PublicationRegistry {
+    publicUrl;
+    configPath;
+    publications;
+    credentials;
+    constructor(publicUrl, configPath, publications, credentials) {
+        this.publicUrl = publicUrl;
+        this.configPath = configPath;
+        this.publications = publications;
+        this.credentials = credentials;
+    }
+    authenticate(authorization) {
+        const match = authorization?.match(/^Bearer ([^\s]+)$/i);
+        if (!match)
+            return undefined;
+        const hash = digest(match[1]);
+        return this.credentials.find((credential) => timingSafeEqual(credential.hash, hash))?.id;
+    }
+    list(caller) {
+        return this.publications.filter((publication) => publication.allowed_callers.includes(caller))
+            .map((publication) => structuredClone(publication));
+    }
+    get(caller, id) {
+        return this.list(caller).find((publication) => publication.id === id);
+    }
+    summaries() {
+        return this.publications.map(({ id, name, revision }) => ({ id, name, revision }));
+    }
+    async assertUnchanged(caller, id) {
+        const publication = this.get(caller, id);
+        if (!publication)
+            throw new Error("Publication not found");
+        const { revision: _revision, inputSchema: _input, outputSchema: _output, ...config } = publication;
+        const current = await readPublication(config);
+        if (current.revision !== publication.revision)
+            throw new Error("Publication changed; reload the deployed configuration");
+    }
+}
+export async function loadPublicationRegistry(configPath, env = process.env) {
+    const absolute = await realpath(configPath);
+    const config = configSchema.parse(parse(await readFile(absolute, "utf8")));
+    const origin = publicUrl(config.public_url);
+    requireUnique(config.callers.map((caller) => caller.id), "caller ID");
+    requireUnique(config.publications.map((publication) => publication.id), "publication ID");
+    const credentials = config.callers.map((caller) => {
+        const token = env[caller.token_env];
+        if (!token || /\s/.test(token) || token.length < 32)
+            throw new Error(`Caller ${caller.id} requires a token of at least 32 characters in ${caller.token_env}`);
+        return { id: caller.id, hash: digest(token) };
+    });
+    requireUnique(credentials.map((credential) => credential.hash.toString("hex")), "caller credential");
+    const publications = [];
+    for (const entry of config.publications) {
+        requireUnique(entry.allowed_callers, `caller in publication ${entry.id}`);
+        requireUnique(entry.results.artifacts, `artifact in publication ${entry.id}`);
+        requireUnique(entry.caller_answerable_stages, `answerable stage in publication ${entry.id}`);
+        if (entry.allowed_callers.some((id) => !credentials.some((caller) => caller.id === id))) {
+            throw new Error(`Publication ${entry.id} refers to an unknown caller`);
+        }
+        const root = await realpath(path.resolve(path.dirname(absolute), entry.project_root));
+        publications.push(await readPublication({
+            ...entry, project_root: root,
+            pipeline: await realpath(path.resolve(root, entry.pipeline)),
+            input_schema: await realpath(path.resolve(root, entry.input_schema)),
+        }));
+    }
+    return new PublicationRegistry(origin, absolute, publications, credentials);
+}

package/dist/a2a/server.d.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage as HttpIncomingMessage, ServerResponse } from "node:http";
+import type Database from "better-sqlite3";
+import { AgentCard } from "@a2a-js/sdk";
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager } from "../runtime/runManager.js";
+import { type PublicationRegistry } from "./registry.js";
+import type { A2aStore } from "./store.js";
+export declare const A2A_BODY_LIMIT: number;
+export declare function publicationCard(registry: PublicationRegistry, caller: string): AgentCard;
+export type A2aRuntime = {
+    manager: RunManager;
+    runStore: RunStore;
+    rootDir: string;
+    /** The SqliteRunStore's own connection to `state.db`, when the caller constructed one via `createRunStoreWithConnection`. */
+    connection?: Database.Database;
+    /** Shared A2A store when the Host composition root already opened one for delete_run. */
+    a2aStore?: A2aStore;
+};
+export type A2aHost = {
+    status: {
+        state: "disabled" | "enabled" | "configuration_error";
+        configPath?: string;
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+    handle(req: HttpIncomingMessage, res: ServerResponse, pathname: string): Promise<boolean>;
+    /** Deletes expired terminal tasks/artifacts and message tombstones. A no-op when A2A is not enabled. */
+    pruneExpired(now?: Date): Promise<{
+        removedTasks: number;
+        removedMessages: number;
+    }>;
+    close(): void;
+};
+export declare function createA2aHost(runtime: A2aRuntime, configPath?: string, env?: NodeJS.ProcessEnv): Promise<A2aHost>;