stageflow 0.19.0 → 0.25.0

package/dist/a2a/server.js

@@ -0,0 +1,341 @@
+import { AgentCard, Role, TaskState, } from "@a2a-js/sdk";
+import { JsonRpcTransportHandler, ServerCallContext, validateVersion } from "@a2a-js/sdk/server";
+import { A2AError, RequestMalformedError, TaskNotCancelableError, TaskNotFoundError, UnsupportedOperationError, } from "@a2a-js/sdk/errors";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { A2aApplicationError } from "./contracts.js";
+import { loadPublicationRegistry } from "./registry.js";
+import { createA2aInvocations } from "./service.js";
+export const A2A_BODY_LIMIT = 1024 * 1024;
+/** Single source of truth for the two sub-routes so the URL builders below and the router in `createA2aHost` can never drift apart. */
+const CONTRACT_ROUTE_PREFIX = "/a2a/contracts/";
+const ARTIFACT_ROUTE_PREFIX = "/a2a/artifacts/";
+function contractUrl(publicUrl, publicationId) {
+    return publicUrl + CONTRACT_ROUTE_PREFIX + publicationId;
+}
+function artifactUrl(publicUrl, taskId, artifactId) {
+    return publicUrl + ARTIFACT_ROUTE_PREFIX + taskId + "/" + artifactId;
+}
+export function publicationCard(registry, caller) {
+    return AgentCard.fromJSON({
+        name: "Stageflow",
+        description: "Invoke published Stageflow pipelines as A2A capabilities.",
+        version: PACKAGE_VERSION,
+        supportedInterfaces: [{ url: registry.publicUrl + "/a2a", protocolBinding: "JSONRPC", protocolVersion: "1.0" }],
+        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: true },
+        securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: "bearer" } } },
+        securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+        defaultInputModes: ["application/json"],
+        defaultOutputModes: ["application/json"],
+        skills: registry.list(caller).map((publication) => ({
+            id: publication.id,
+            name: publication.name,
+            description: publication.description + " Contract: " + contractUrl(registry.publicUrl, publication.id),
+            tags: ["pipeline"],
+            inputModes: ["application/json"],
+            outputModes: ["application/json"],
+        })),
+    });
+}
+function mapState(state) {
+    switch (state) {
+        case "submitted":
+            return TaskState.TASK_STATE_SUBMITTED;
+        case "working":
+            return TaskState.TASK_STATE_WORKING;
+        case "input-required":
+            return TaskState.TASK_STATE_INPUT_REQUIRED;
+        case "completed":
+            return TaskState.TASK_STATE_COMPLETED;
+        case "failed":
+            return TaskState.TASK_STATE_FAILED;
+    }
+}
+function dataPart(value) {
+    return { content: { $case: "data", value }, metadata: undefined, filename: "", mediaType: "application/json" };
+}
+function urlPart(url, filename, mediaType) {
+    return { content: { $case: "url", value: url }, metadata: undefined, filename, mediaType };
+}
+function statusMessage(taskId, contextId, parts) {
+    return {
+        messageId: "status-" + taskId + "-" + Date.now().toString(36),
+        contextId,
+        taskId,
+        role: Role.ROLE_AGENT,
+        parts,
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: [],
+    };
+}
+function toWireTask(publicUrl, task) {
+    const parts = [];
+    if (task.state === "input-required" && task.questions) {
+        parts.push(dataPart({ questions: task.questions }));
+    }
+    const artifacts = [];
+    if (task.result) {
+        if (task.result.payload !== undefined) {
+            artifacts.push({
+                artifactId: "result",
+                name: "result",
+                description: task.result.summary,
+                parts: [dataPart(task.result.payload)],
+                metadata: undefined,
+                extensions: [],
+            });
+        }
+        for (const file of task.result.artifacts) {
+            artifacts.push({
+                artifactId: file.id,
+                name: file.name,
+                description: "",
+                parts: [urlPart(artifactUrl(publicUrl, task.id, file.id), file.name, file.mediaType ?? "application/octet-stream")],
+                metadata: undefined,
+                extensions: [],
+            });
+        }
+    }
+    return {
+        id: task.id,
+        contextId: task.contextId,
+        status: {
+            state: mapState(task.state),
+            message: parts.length > 0 ? statusMessage(task.id, task.contextId, parts) : undefined,
+            timestamp: task.updatedAt,
+        },
+        artifacts,
+        history: [],
+        // Only ever set for a "standalone" (ADR-0001 run_stage) task — see PublicTask.runId.
+        // This is how a caller learns the run id it needs to chain into its next
+        // run_stage call via envelope_ref (ADR-0002); invoke's published-capability
+        // tasks keep the run id opaque, unchanged from before this field existed.
+        metadata: task.runId ? { runId: task.runId } : undefined,
+    };
+}
+function mapApplicationError(err) {
+    if (err instanceof A2aApplicationError) {
+        if (err.category === "not-found") {
+            throw new TaskNotFoundError({ message: err.message });
+        }
+        if (err.category === "busy" || err.category === "export-failed") {
+            throw new A2AError({ message: err.message, metadata: { category: err.category } });
+        }
+        throw new RequestMalformedError({ message: err.message, metadata: { category: err.category } });
+    }
+    throw err;
+}
+function realHandler(card, invocations, publicUrl) {
+    const unsupportedStream = async function* () {
+        throw new UnsupportedOperationError("Streaming is not enabled");
+    };
+    const pushUnsupported = async () => {
+        throw new UnsupportedOperationError("Push notifications are not enabled");
+    };
+    return {
+        getAgentCard: async () => card,
+        getAuthenticatedExtendedAgentCard: async () => card,
+        async sendMessage(params, context) {
+            if (!params.message)
+                throw new RequestMalformedError({ message: "A message is required" });
+            try {
+                const task = await invocations.send({ id: context.user.userName }, params.message);
+                return toWireTask(publicUrl, task);
+            }
+            catch (err) {
+                return mapApplicationError(err);
+            }
+        },
+        async getTask(params, context) {
+            try {
+                const task = await invocations.get({ id: context.user.userName }, params.id);
+                return toWireTask(publicUrl, task);
+            }
+            catch (err) {
+                return mapApplicationError(err);
+            }
+        },
+        async listTasks(params, context) {
+            try {
+                const tasks = await invocations.list({ id: context.user.userName }, params.contextId || undefined);
+                const size = params.pageSize && params.pageSize > 0 ? Math.min(params.pageSize, 100) : 50;
+                const limited = tasks.slice(0, size);
+                return { tasks: limited.map((task) => toWireTask(publicUrl, task)), nextPageToken: "", pageSize: limited.length, totalSize: tasks.length };
+            }
+            catch (err) {
+                return mapApplicationError(err);
+            }
+        },
+        async cancelTask(params, context) {
+            try {
+                await invocations.get({ id: context.user.userName }, params.id);
+            }
+            catch (err) {
+                return mapApplicationError(err);
+            }
+            throw new TaskNotCancelableError({ message: "Active pipeline cancellation is not available yet" });
+        },
+        sendMessageStream: unsupportedStream,
+        resubscribe: unsupportedStream,
+        createTaskPushNotificationConfig: pushUnsupported,
+        getTaskPushNotificationConfig: pushUnsupported,
+        listTaskPushNotificationConfigs: pushUnsupported,
+        deleteTaskPushNotificationConfig: pushUnsupported,
+    };
+}
+function respond(res, status, value) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", "Vary": "Authorization" });
+    res.end(JSON.stringify(value));
+}
+async function readBody(req) {
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of req) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > A2A_BODY_LIMIT)
+            throw new Error("body_too_large");
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+const RETENTION_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+export async function createA2aHost(runtime, configPath, env = process.env) {
+    let registry;
+    let invocations;
+    const status = { state: "disabled" };
+    if (configPath) {
+        status.configPath = configPath;
+        try {
+            registry = await loadPublicationRegistry(configPath, env);
+            status.configPath = registry.configPath;
+            status.state = "enabled";
+            invocations = createA2aInvocations(registry, runtime.manager, runtime.runStore, runtime.rootDir, runtime.connection);
+        }
+        catch {
+            status.state = "configuration_error";
+        }
+    }
+    const sweep = invocations
+        ? setInterval(() => {
+            invocations.pruneExpired().catch(() => undefined);
+        }, RETENTION_SWEEP_INTERVAL_MS).unref()
+        : undefined;
+    return {
+        status,
+        async pruneExpired(now) {
+            return (await invocations?.pruneExpired(now)) ?? { removedTasks: 0, removedMessages: 0 };
+        },
+        close() {
+            if (sweep)
+                clearInterval(sweep);
+            invocations?.close();
+        },
+        async handle(req, res, pathname) {
+            const isRoute = pathname === "/a2a" ||
+                pathname === "/.well-known/agent-card.json" ||
+                pathname.startsWith(CONTRACT_ROUTE_PREFIX) ||
+                pathname.startsWith(ARTIFACT_ROUTE_PREFIX);
+            if (!isRoute)
+                return false;
+            if (!registry || !invocations) {
+                respond(res, status.state === "disabled" ? 404 : 503, { error: "A2A unavailable" });
+                return true;
+            }
+            const caller = registry.authenticate(req.headers.authorization);
+            if (!caller) {
+                res.setHeader("WWW-Authenticate", 'Bearer realm="stageflow-a2a"');
+                respond(res, 401, { error: "Authentication required" });
+                return true;
+            }
+            if (pathname.startsWith(ARTIFACT_ROUTE_PREFIX)) {
+                if (req.method !== "GET") {
+                    res.setHeader("Allow", "GET");
+                    respond(res, 405, { error: "Method not allowed" });
+                    return true;
+                }
+                const segments = pathname.slice(ARTIFACT_ROUTE_PREFIX.length).split("/");
+                if (segments.length !== 2) {
+                    respond(res, 404, { error: "Artifact not found" });
+                    return true;
+                }
+                try {
+                    const artifact = await invocations.readArtifact({ id: caller }, segments[0], segments[1]);
+                    res.writeHead(200, {
+                        "Content-Type": artifact.mediaType ?? "application/octet-stream",
+                        "Content-Length": artifact.bytes.length,
+                        "Cache-Control": "no-store",
+                        "Vary": "Authorization",
+                    });
+                    res.end(artifact.bytes);
+                }
+                catch {
+                    respond(res, 404, { error: "Artifact not found" });
+                }
+                return true;
+            }
+            const card = publicationCard(registry, caller);
+            if (pathname !== "/a2a") {
+                if (req.method !== "GET") {
+                    res.setHeader("Allow", "GET");
+                    respond(res, 405, { error: "Method not allowed" });
+                }
+                else if (pathname === "/.well-known/agent-card.json") {
+                    respond(res, 200, AgentCard.toJSON(card));
+                }
+                else {
+                    const publication = registry.get(caller, pathname.slice(CONTRACT_ROUTE_PREFIX.length));
+                    if (!publication)
+                        respond(res, 404, { error: "Contract not found" });
+                    else
+                        respond(res, 200, {
+                            contractVersion: 1,
+                            capability: publication.id,
+                            revision: publication.revision,
+                            executionEnabled: true,
+                            inputSchema: publication.inputSchema,
+                            outputSchema: publication.outputSchema,
+                            artifacts: publication.results.artifacts,
+                        });
+                }
+                return true;
+            }
+            if (req.method !== "POST") {
+                res.setHeader("Allow", "POST");
+                respond(res, 405, { error: "Method not allowed" });
+                return true;
+            }
+            if (req.headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") {
+                respond(res, 415, { error: "Expected application/json" });
+                return true;
+            }
+            if (Number(req.headers["content-length"]) > A2A_BODY_LIMIT) {
+                respond(res, 413, { error: "Request too large" });
+                return true;
+            }
+            const version = req.headers["a2a-version"];
+            try {
+                validateVersion(typeof version === "string" ? version : "0.3", card, "JSONRPC");
+            }
+            catch (error) {
+                respond(res, 400, { jsonrpc: "2.0", id: null, error: JsonRpcTransportHandler.mapToJSONRPCError(error) });
+                return true;
+            }
+            req.setTimeout(30_000, () => req.destroy());
+            try {
+                const body = await readBody(req);
+                const context = new ServerCallContext({ user: { isAuthenticated: true, userName: caller }, requestedVersion: "1.0" });
+                const result = await new JsonRpcTransportHandler(realHandler(card, invocations, registry.publicUrl)).handle(body, context);
+                respond(res, 200, result);
+            }
+            catch (error) {
+                if (!res.destroyed)
+                    respond(res, error instanceof Error && error.message === "body_too_large" ? 413 : 400, { error: "Invalid request body" });
+            }
+            finally {
+                req.setTimeout(0);
+            }
+            return true;
+        },
+    };
+}

package/dist/a2a/service.d.ts

@@ -0,0 +1,97 @@
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager } from "../runtime/runManager.js";
+import type { PublicationRegistry } from "./registry.js";
+import { type IncomingMessage } from "./contracts.js";
+import type Database from "better-sqlite3";
+import { A2aStore, type TaskState } from "./store.js";
+import { RateLimiter } from "./limits.js";
+export type Caller = {
+    id: string;
+};
+export type PublicQuestion = {
+    handle: string;
+    message: string;
+};
+export type PublicArtifact = {
+    id: string;
+    name: string;
+    mediaType?: string;
+    size: number;
+};
+export type PublicTask = {
+    id: string;
+    contextId: string;
+    state: TaskState;
+    publication: string;
+    createdAt: string;
+    updatedAt: string;
+    questions?: PublicQuestion[];
+    waitingForOperator?: boolean;
+    result?: {
+        summary: string;
+        payload?: Record<string, unknown>;
+        artifacts: PublicArtifact[];
+    };
+    /**
+     * The underlying run id — only ever populated for a "standalone" (ADR-0001
+     * run_stage) task. Published-capability (`invoke`) tasks keep the run id
+     * opaque, unchanged from before this field existed. Exposing it here is
+     * what makes ADR-0002's `envelope_ref` chaining ({runId, stageId}) usable
+     * from an A2A caller in the first place: run_stage's response is the only
+     * place a caller can learn the run id of a standalone call it just made,
+     * to hand to its *next* run_stage call.
+     */
+    runId?: string;
+};
+export type ArtifactRead = {
+    bytes: Buffer;
+    name: string;
+    mediaType?: string;
+};
+export declare class A2aInvocations {
+    private readonly registry;
+    private readonly manager;
+    private readonly runStore;
+    /** Base directory a `stage`/`pipeline` filesystem reference in a run_stage call resolves against. */
+    private readonly rootDir;
+    private readonly store;
+    private readonly rateLimiter;
+    constructor(registry: PublicationRegistry, manager: RunManager, runStore: RunStore, 
+    /** Base directory a `stage`/`pipeline` filesystem reference in a run_stage call resolves against. */
+    rootDir: string, store: A2aStore, rateLimiter?: RateLimiter);
+    close(): void;
+    /** Deletes terminal tasks and message tombstones past their retention window. Call periodically; the core logic takes an explicit clock so it stays deterministic to test. */
+    pruneExpired(now?: Date): Promise<{
+        removedTasks: number;
+        removedMessages: number;
+    }>;
+    private checkRate;
+    send(caller: Caller, raw: IncomingMessage): Promise<PublicTask>;
+    get(caller: Caller, taskId: string): Promise<PublicTask>;
+    list(caller: Caller, contextId: string | undefined): Promise<PublicTask[]>;
+    readArtifact(caller: Caller, taskId: string, artifactId: string): Promise<ArtifactRead>;
+    private requireOwnedTask;
+    /**
+     * (caller, messageId) dedup shared by invoke and answer: a resend of a message already recorded with
+     * the same content hash replays its prior outcome; a resend with different content is a conflict.
+     * Returns undefined only for a message this caller has not sent before.
+     */
+    private replayOrThrow;
+    private invoke;
+    /**
+     * ADR-0001's wildcard-access operation: run any catalog or inline
+     * stage/pipeline directly. Deliberately does NOT call `this.registry.get`/
+     * `.list` — that allowlist lookup is the entire mechanism `invoke` uses to
+     * restrict a caller to its published capabilities, and this operation's
+     * whole point is to bypass it. The caller is still authenticated (by the
+     * time `send` reaches here) and still rate-limited/admission-capped like
+     * any other task.
+     */
+    private runStandalone;
+    private answer;
+    private maybeFinalize;
+    /** The five PublicTask fields every projection shares; call sites layer in only what differs per state. */
+    private buildTask;
+    private projectTask;
+}
+export declare function createA2aInvocations(registry: PublicationRegistry, manager: RunManager, runStore: RunStore, rootDir: string, connection?: Database.Database, rateLimiter?: RateLimiter): A2aInvocations;