stageflow 0.23.0 → 0.25.0

package/dist/a2a/store.js

@@ -0,0 +1,245 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { storeRootFor } from "../runstore/paths.js";
+import { MESSAGE_TOMBSTONE_RETENTION_MS, TERMINAL_RETENTION_MS } from "./limits.js";
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS a2a_contexts (
+  context_id TEXT PRIMARY KEY,
+  caller_id TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS a2a_tasks (
+  task_id TEXT PRIMARY KEY,
+  context_id TEXT NOT NULL,
+  caller_id TEXT NOT NULL,
+  publication_id TEXT NOT NULL,
+  publication_revision TEXT NOT NULL,
+  submission_key TEXT NOT NULL UNIQUE,
+  run_id TEXT,
+  state TEXT NOT NULL,
+  result_json TEXT,
+  kind TEXT NOT NULL DEFAULT 'invoke',
+  result_stage_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS a2a_tasks_context ON a2a_tasks(context_id);
+CREATE INDEX IF NOT EXISTS a2a_tasks_caller ON a2a_tasks(caller_id);
+
+CREATE TABLE IF NOT EXISTS a2a_messages (
+  caller_id TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  request_hash TEXT NOT NULL,
+  outcome_json TEXT,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (caller_id, message_id)
+);
+
+CREATE TABLE IF NOT EXISTS a2a_artifacts (
+  artifact_id TEXT PRIMARY KEY,
+  task_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  media_type TEXT,
+  size INTEGER NOT NULL,
+  content_path TEXT NOT NULL,
+  hash TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS a2a_artifacts_task ON a2a_artifacts(task_id);
+`;
+function nowIso() {
+    return new Date().toISOString();
+}
+export class A2aStore {
+    db;
+    artifactsRoot;
+    ownsConnection;
+    /**
+     * `connection`, when passed, is the SqliteRunStore's own connection to the same `state.db` file
+     * (see `createRunStoreWithConnection`) so the two stores share one transaction domain. Falls
+     * back to opening its own connection when no shared one is available (e.g. a caller-supplied
+     * non-SQLite `RunStore` in bootstrap).
+     */
+    constructor(rootDir, connection) {
+        const storeRoot = storeRootFor(rootDir);
+        if (connection) {
+            this.db = connection;
+            this.ownsConnection = false;
+        }
+        else {
+            this.db = new Database(path.join(storeRoot, "state.db"));
+            this.db.pragma("journal_mode = WAL");
+            this.db.pragma("busy_timeout = 5000");
+            this.ownsConnection = true;
+        }
+        this.db.exec(SCHEMA_SQL);
+        this.migrateAddStandaloneColumns();
+        this.artifactsRoot = path.join(storeRoot, "a2a-artifacts");
+    }
+    /**
+     * Additive migration for a `state.db` created before the run_stage A2A
+     * operation existed: `CREATE TABLE IF NOT EXISTS` above never alters an
+     * already-existing a2a_tasks table, so a pre-existing one is missing these
+     * two columns. Same PRAGMA table_info-guarded ADD COLUMN pattern as
+     * src/runstore/sqlite/SqliteRunStore.ts.
+     */
+    migrateAddStandaloneColumns() {
+        const cols = this.db.prepare(`PRAGMA table_info(a2a_tasks)`).all();
+        if (!cols.some((c) => c.name === "kind")) {
+            this.db.exec(`ALTER TABLE a2a_tasks ADD COLUMN kind TEXT NOT NULL DEFAULT 'invoke'`);
+        }
+        if (!cols.some((c) => c.name === "result_stage_id")) {
+            this.db.exec(`ALTER TABLE a2a_tasks ADD COLUMN result_stage_id TEXT`);
+        }
+    }
+    close() {
+        if (this.ownsConnection)
+            this.db.close();
+    }
+    ensureContext(callerId, contextId) {
+        if (contextId) {
+            const row = this.db
+                .prepare("SELECT caller_id FROM a2a_contexts WHERE context_id = ?")
+                .get(contextId);
+            if (row && row.caller_id !== callerId) {
+                throw new Error("Context belongs to a different caller");
+            }
+            if (row)
+                return contextId;
+            this.db
+                .prepare("INSERT INTO a2a_contexts (context_id, caller_id, created_at) VALUES (?, ?, ?)")
+                .run(contextId, callerId, nowIso());
+            return contextId;
+        }
+        const generated = randomUUID();
+        this.db
+            .prepare("INSERT INTO a2a_contexts (context_id, caller_id, created_at) VALUES (?, ?, ?)")
+            .run(generated, callerId, nowIso());
+        return generated;
+    }
+    getMessage(callerId, messageId) {
+        const row = this.db
+            .prepare("SELECT task_id AS taskId, request_hash AS requestHash, outcome_json AS outcomeJson FROM a2a_messages WHERE caller_id = ? AND message_id = ?")
+            .get(callerId, messageId);
+        if (!row)
+            return undefined;
+        return { taskId: row.taskId, requestHash: row.requestHash, outcome: row.outcomeJson ? JSON.parse(row.outcomeJson) : undefined };
+    }
+    recordMessage(params) {
+        this.db
+            .prepare("INSERT INTO a2a_messages (caller_id, message_id, task_id, operation, request_hash, outcome_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)")
+            .run(params.callerId, params.messageId, params.taskId, params.operation, params.requestHash, JSON.stringify(params.outcome), nowIso());
+    }
+    getTaskBySubmissionKey(key) {
+        return this.db.prepare("SELECT * FROM a2a_tasks WHERE submission_key = ?").get(key);
+    }
+    createTask(params) {
+        const at = nowIso();
+        this.db
+            .prepare(`INSERT INTO a2a_tasks
+          (task_id, context_id, caller_id, publication_id, publication_revision, submission_key, run_id, state, result_json, kind, result_stage_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 'submitted', NULL, ?, ?, ?, ?)`)
+            .run(params.taskId, params.contextId, params.callerId, params.publicationId, params.publicationRevision, params.submissionKey, params.runId, params.kind ?? "invoke", params.resultStageId ?? null, at, at);
+        return this.getTask(params.taskId);
+    }
+    getTask(taskId) {
+        return this.db.prepare("SELECT * FROM a2a_tasks WHERE task_id = ?").get(taskId);
+    }
+    listTasksForCaller(callerId, contextId) {
+        if (contextId) {
+            return this.db
+                .prepare("SELECT * FROM a2a_tasks WHERE caller_id = ? AND context_id = ? ORDER BY created_at ASC")
+                .all(callerId, contextId);
+        }
+        return this.db
+            .prepare("SELECT * FROM a2a_tasks WHERE caller_id = ? ORDER BY created_at ASC")
+            .all(callerId);
+    }
+    getArtifact(taskId, artifactId) {
+        return this.db
+            .prepare("SELECT * FROM a2a_artifacts WHERE task_id = ? AND artifact_id = ?")
+            .get(taskId, artifactId);
+    }
+    listArtifacts(taskId) {
+        return this.db.prepare("SELECT * FROM a2a_artifacts WHERE task_id = ?").all(taskId);
+    }
+    /** Freezes a successful outcome exactly once; a second call for an already-terminal task is a no-op. */
+    async freezeCompleted(taskId, result) {
+        return this.freeze(taskId, "completed", result);
+    }
+    /** Freezes a failure exactly once; a second call for an already-terminal task is a no-op. */
+    async freezeFailed(taskId) {
+        return this.freeze(taskId, "failed", undefined);
+    }
+    async freeze(taskId, state, result) {
+        const current = this.getTask(taskId);
+        if (!current || current.state === "completed" || current.state === "failed")
+            return;
+        const artifactRows = [];
+        if (result) {
+            for (const artifact of result.artifacts) {
+                const artifactId = randomUUID();
+                const hash = createHash("sha256").update(artifact.bytes).digest("hex");
+                const dir = path.join(this.artifactsRoot, taskId);
+                await mkdir(dir, { recursive: true });
+                const contentPath = path.join(dir, artifactId);
+                await writeFile(contentPath, artifact.bytes);
+                artifactRows.push({
+                    artifact_id: artifactId,
+                    task_id: taskId,
+                    name: artifact.name,
+                    media_type: artifact.mediaType ?? null,
+                    size: artifact.bytes.length,
+                    content_path: contentPath,
+                    hash,
+                    created_at: nowIso(),
+                });
+            }
+        }
+        const resultJson = result ? JSON.stringify({ summary: result.summary, payload: result.payload }) : null;
+        const transact = this.db.transaction(() => {
+            const outcome = this.db
+                .prepare("UPDATE a2a_tasks SET state = ?, result_json = ?, updated_at = ? WHERE task_id = ? AND state NOT IN ('completed', 'failed')")
+                .run(state, resultJson, nowIso(), taskId);
+            if (outcome.changes === 0)
+                return;
+            for (const row of artifactRows) {
+                this.db
+                    .prepare("INSERT INTO a2a_artifacts (artifact_id, task_id, name, media_type, size, content_path, hash, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+                    .run(row.artifact_id, row.task_id, row.name, row.media_type, row.size, row.content_path, row.hash, row.created_at);
+            }
+        });
+        transact();
+    }
+    countNonterminal(callerId) {
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS n FROM a2a_tasks WHERE caller_id = ? AND state NOT IN ('completed', 'failed')")
+            .get(callerId);
+        return row.n;
+    }
+    /** Deletes terminal tasks (and their frozen artifact files) and message tombstones older than the retention window. */
+    async pruneExpired(now, terminalRetentionMs = TERMINAL_RETENTION_MS, messageRetentionMs = MESSAGE_TOMBSTONE_RETENTION_MS) {
+        const terminalCutoff = new Date(now.getTime() - terminalRetentionMs).toISOString();
+        const messageCutoff = new Date(now.getTime() - messageRetentionMs).toISOString();
+        const expiredTasks = this.db
+            .prepare("SELECT task_id FROM a2a_tasks WHERE state IN ('completed', 'failed') AND updated_at < ?")
+            .all(terminalCutoff);
+        for (const { task_id: taskId } of expiredTasks) {
+            for (const artifact of this.listArtifacts(taskId)) {
+                await unlink(artifact.content_path).catch(() => undefined);
+            }
+            this.db.transaction(() => {
+                this.db.prepare("DELETE FROM a2a_artifacts WHERE task_id = ?").run(taskId);
+                this.db.prepare("DELETE FROM a2a_messages WHERE task_id = ?").run(taskId);
+                this.db.prepare("DELETE FROM a2a_tasks WHERE task_id = ?").run(taskId);
+            })();
+        }
+        const removedMessages = this.db.prepare("DELETE FROM a2a_messages WHERE created_at < ?").run(messageCutoff).changes;
+        return { removedTasks: expiredTasks.length, removedMessages };
+    }
+}

package/dist/cli/a2aCommand.d.ts

@@ -0,0 +1,8 @@
+export declare const A2A_USAGE = "sf a2a validate [--config <path>]\nsf a2a list [--config <path>]\nsf a2a add-caller <id> [--config <path>] [--token-env <NAME>]\n\nValidate or inspect an A2A publication configuration, or register a new caller.\n--config defaults to <project-root>/a2a.yaml when omitted -- the same file\nSTAGEFLOW_A2A_CONFIG would point at if set. Caller credentials are read from\nthe environment variables named in the configuration; add-caller only writes\nthe caller's id and its token_env name to the file, never a secret value.";
+export declare function runA2aCommand(args: string[], options: {
+    cwd: string;
+    projectRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+}): Promise<number>;

package/dist/cli/a2aCommand.js

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
+import { loadPublicationRegistry } from "../a2a/registry.js";
+import { a2aConfigPathFor, resolveA2aConfigPath } from "../a2a/configDiscovery.js";
+export const A2A_USAGE = `sf a2a validate [--config <path>]
+sf a2a list [--config <path>]
+sf a2a add-caller <id> [--config <path>] [--token-env <NAME>]
+
+Validate or inspect an A2A publication configuration, or register a new caller.
+--config defaults to <project-root>/a2a.yaml when omitted -- the same file
+STAGEFLOW_A2A_CONFIG would point at if set. Caller credentials are read from
+the environment variables named in the configuration; add-caller only writes
+the caller's id and its token_env name to the file, never a secret value.`;
+const SCAFFOLD = { version: 1, callers: [], publications: [] };
+function deriveTokenEnvName(callerId) {
+    const normalized = callerId
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return (normalized || "CALLER") + "_TOKEN";
+}
+function parseFlags(args) {
+    let config;
+    let tokenEnv;
+    const positionals = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === "--config") {
+            config = args[(i += 1)];
+        }
+        else if (args[i] === "--token-env") {
+            tokenEnv = args[(i += 1)];
+        }
+        else {
+            positionals.push(args[i]);
+        }
+    }
+    return { config, tokenEnv, positionals };
+}
+async function addCaller(configPath, callerId, tokenEnvOverride) {
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch {
+        raw = undefined;
+    }
+    const config = raw ? (parse(raw) ?? {}) : { ...SCAFFOLD };
+    if (typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(configPath + " does not contain a YAML mapping");
+    }
+    if (config.version === undefined)
+        config.version = 1;
+    if (config.callers === undefined)
+        config.callers = [];
+    if (config.publications === undefined)
+        config.publications = [];
+    const callers = config.callers;
+    if (!Array.isArray(callers)) {
+        throw new Error('"callers" in ' + configPath + " is not a list");
+    }
+    if (callers.some((entry) => entry && typeof entry === "object" && entry.id === callerId)) {
+        throw new Error('Caller "' + callerId + '" already exists in ' + configPath);
+    }
+    const tokenEnv = tokenEnvOverride ?? deriveTokenEnvName(callerId);
+    callers.push({ id: callerId, token_env: tokenEnv });
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, stringify(config));
+    const token = randomBytes(24).toString("hex");
+    return { tokenEnv, token, created: raw === undefined };
+}
+export async function runA2aCommand(args, options) {
+    const log = options.log ?? console.log;
+    const error = options.error ?? console.error;
+    const env = options.env ?? process.env;
+    const projectRoot = options.projectRoot ?? options.cwd;
+    if (args[0] === "--help" || args[0] === "-h") {
+        log(A2A_USAGE);
+        return 0;
+    }
+    const sub = args[0];
+    if (sub !== "validate" && sub !== "list" && sub !== "add-caller") {
+        error(A2A_USAGE);
+        return 1;
+    }
+    const { config, tokenEnv, positionals } = parseFlags(args.slice(1));
+    if (sub === "add-caller") {
+        if (positionals.length !== 1 || !positionals[0]) {
+            error(A2A_USAGE);
+            return 1;
+        }
+        const configPath = config ? path.resolve(options.cwd, config) : a2aConfigPathFor(projectRoot);
+        try {
+            const result = await addCaller(configPath, positionals[0], tokenEnv);
+            log(JSON.stringify({ ok: true, configPath, callerId: positionals[0], tokenEnv: result.tokenEnv, created: result.created }));
+            log('Generated a token for caller "' + positionals[0] + '". Export it before starting the host (or store it in your secrets manager):');
+            log("  export " + result.tokenEnv + "=" + result.token);
+            if (result.created) {
+                log("Created " + configPath + " with no publications yet -- add at least one under `publications:` before this config can be loaded.");
+            }
+            return 0;
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    if (positionals.length !== 0) {
+        error(A2A_USAGE);
+        return 1;
+    }
+    const configPath = config ? path.resolve(options.cwd, config) : resolveA2aConfigPath(projectRoot, env);
+    if (!configPath) {
+        error("No A2A configuration found. Pass --config <path>, or create " + a2aConfigPathFor(projectRoot) + ".");
+        return 1;
+    }
+    try {
+        const registry = await loadPublicationRegistry(configPath, env);
+        log(JSON.stringify({ ok: true, configPath: registry.configPath, publicUrl: registry.publicUrl, mode: "discovery", publications: registry.summaries() }));
+        if (sub === "list") {
+            log("Configuration validated locally. An already-running host must be restarted explicitly to pick up changes.");
+        }
+        return 0;
+    }
+    catch (err) {
+        error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}

package/dist/cli/runStageCommand.d.ts

@@ -0,0 +1,33 @@
+import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
+export declare const RUN_STAGE_USAGE = "Usage:\n  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]\n\nRun 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`.\n  --stage <path>          Filesystem path to a catalog stage YAML file\n  --stage-inline <json>   Inline stage body object ({ id, system_prompt, io, ... } \u2014 no uses:/route/pipeline wrapper)\n  --task <path>           Filesystem path to a catalog task YAML file\n  --task-inline <json>    Inline task object ({ id, goal, ... })\n  --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 \u2014 each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal.\n  --checkout <path>       Optional checkout to use with --envelope-ref (--task/--task-inline carry their own checkout)\n  --model <id>            Override the model/backend for this call only, ahead of the stage's own declared model\n  --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\n  --timeout-ms <n>        Wait budget in ms when --blocking is set\n  --json                  Machine-readable JSON output";
+export type RunStageEnvelopeRef = {
+    runId: string;
+    stageId: string;
+    attempt?: number;
+};
+export type RunStageToolArgs = {
+    stage: string | Record<string, unknown>;
+    task_path?: string;
+    task?: Record<string, unknown>;
+    envelope_ref?: RunStageEnvelopeRef | RunStageEnvelopeRef[];
+    checkout?: string;
+    model?: string;
+    blocking?: boolean;
+    timeout_ms?: number;
+};
+export type RunStageToolResult = {
+    isError: boolean;
+    payload: Record<string, unknown> | null;
+};
+export type RunStageCallFn = (args: RunStageToolArgs) => Promise<RunStageToolResult>;
+export type RunStageCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runRunStageCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<RunStageCommandIo>;
+    callTool?: RunStageCallFn;
+    hostBaseUrl?: string;
+    ensureService?: () => Promise<EnsureGlobalServiceResult>;
+}): Promise<number>;