stageflow 0.23.0 → 0.27.0

package/dist/a2a/store.js

@@ -0,0 +1,202 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveStoreRoot } from "../runstore/paths.js";
+import { MESSAGE_TOMBSTONE_RETENTION_MS, TERMINAL_RETENTION_MS } from "./limits.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+export class A2aStore {
+    db;
+    artifactsRoot;
+    ownsConnection;
+    /**
+     * Uses the SqliteRunStore connection to the same `state.db` file so the two stores share one
+     * transaction domain. The Host must open the run store in migrate mode before constructing
+     * A2aStore. Additive `kind` / `result_stage_id` columns for run_stage are applied here.
+     */
+    constructor(rootDir, connection) {
+        this.db = connection;
+        this.ownsConnection = false;
+        this.migrateAddStandaloneColumns();
+        this.artifactsRoot = path.join(resolveStoreRoot(rootDir), "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 };
+    }
+    /** Deletes every A2A task (and frozen artifact files) bound to a Stageflow run. */
+    async deleteByRunId(runId) {
+        const tasks = this.db
+            .prepare("SELECT task_id FROM a2a_tasks WHERE run_id = ?")
+            .all(runId);
+        for (const { task_id: taskId } of tasks) {
+            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);
+            })();
+        }
+        return { removedTasks: tasks.length };
+    }
+}

package/dist/agent/activity.d.ts

@@ -71,6 +71,9 @@ export type StageLifecycleEvent = {
     event: "failed";
     reason: string;
     usage?: StageUsage;
+} | {
+    event: "interrupted";
+    reason: string;
 } | {
     event: "skipped";
 }

package/dist/agent/bootProviderConfig.d.ts

@@ -0,0 +1,21 @@
+import { type ProviderAuthContext } from "./providerAuth.js";
+export type BootProviderResult = {
+    configured: string[];
+    failures: Array<{
+        providerId: string;
+        code: string;
+        message: string;
+    }>;
+};
+export type BootProviderOptions = {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    requireProviders?: string[];
+    authContext?: ProviderAuthContext;
+    logError?: (message: string) => void;
+};
+/**
+ * Configure providers from STAGEFLOW_PROVIDER_<ID>_API_KEY / _FILE at Host boot.
+ * Soft-fails unreadable/rejected keys by default; requireProviders makes missing ids fatal.
+ */
+export declare function bootProviderConfig(options: BootProviderOptions): Promise<BootProviderResult>;

package/dist/agent/bootProviderConfig.js

@@ -0,0 +1,74 @@
+import { loginWithApiKey, } from "./providerAuth.js";
+import { readSecretFromEnvOrFile, SecretFromEnvError, } from "../config/secretFromEnvOrFile.js";
+const PROVIDER_KEY_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY$/;
+const PROVIDER_FILE_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY_FILE$/;
+function discoverProviders(env) {
+    const byLower = new Map();
+    for (const key of Object.keys(env)) {
+        let envId;
+        const plain = key.match(PROVIDER_KEY_RE);
+        if (plain)
+            envId = plain[1];
+        else {
+            const file = key.match(PROVIDER_FILE_RE);
+            if (file)
+                envId = file[1];
+        }
+        if (envId === undefined)
+            continue;
+        const providerId = envId.toLowerCase().replace(/_/g, "-");
+        if (!byLower.has(providerId)) {
+            byLower.set(providerId, { envId, providerId });
+        }
+    }
+    return [...byLower.values()].sort((a, b) => a.providerId.localeCompare(b.providerId));
+}
+/**
+ * Configure providers from STAGEFLOW_PROVIDER_<ID>_API_KEY / _FILE at Host boot.
+ * Soft-fails unreadable/rejected keys by default; requireProviders makes missing ids fatal.
+ */
+export async function bootProviderConfig(options) {
+    const env = options.env ?? process.env;
+    const logError = options.logError ?? ((message) => console.error(message));
+    const configured = [];
+    const failures = [];
+    for (const { envId, providerId } of discoverProviders(env)) {
+        const envName = `STAGEFLOW_PROVIDER_${envId}_API_KEY`;
+        let secret;
+        try {
+            secret = readSecretFromEnvOrFile(env, envName);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (err instanceof SecretFromEnvError &&
+                message.includes("not both")) {
+                throw err;
+            }
+            const code = err instanceof SecretFromEnvError ? err.code : "config_invalid";
+            failures.push({ providerId, code, message });
+            logError(`stageflow: provider ${providerId} boot failed: ${message}`);
+            continue;
+        }
+        if (secret === undefined)
+            continue;
+        try {
+            await loginWithApiKey(options.cwd, providerId, secret, options.authContext);
+            configured.push(providerId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            failures.push({
+                providerId,
+                code: "provider_not_configured",
+                message,
+            });
+            logError(`stageflow: provider ${providerId} boot failed: ${message}`);
+        }
+    }
+    const required = (options.requireProviders ?? []).map((id) => id.toLowerCase());
+    const missing = required.filter((id) => !configured.includes(id));
+    if (missing.length > 0) {
+        throw new Error(`STAGEFLOW_REQUIRE_PROVIDERS: missing configured providers: ${missing.join(", ")}`);
+    }
+    return { configured, failures };
+}

package/dist/agent/piAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type EventBus, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type EventBus, type ExtensionFactory, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -6,6 +6,14 @@ import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 import type { StageGateKind } from "../types/stage.js";
 import { type StageUsage } from "../types/usage.js";
+import { STAGEFLOW_PATH_DENIED } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export declare const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+export declare function createDurableRootPathDenyExtension(options: {
+    runWorkspaceDir: string;
+    durableRoot: string;
+    checkoutRoot?: string;
+}): ExtensionFactory;
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).

package/dist/agent/piAdapter.js

@@ -49,6 +49,36 @@ import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { durableRootFileToolDenial, STAGEFLOW_PATH_DENIED, } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+const PATH_DENY_FILE_TOOLS = new Set(["read", "write", "edit"]);
+export function createDurableRootPathDenyExtension(options) {
+    const { runWorkspaceDir, durableRoot, checkoutRoot } = options;
+    const allowlistedRoots = checkoutRoot !== undefined && checkoutRoot !== ""
+        ? [checkoutRoot]
+        : undefined;
+    return (pi) => {
+        pi.on("tool_call", async (event, ctx) => {
+            if (!PATH_DENY_FILE_TOOLS.has(event.toolName)) {
+                return undefined;
+            }
+            const rawPath = event.input.path;
+            if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+                return undefined;
+            }
+            const candidate = path.isAbsolute(rawPath)
+                ? rawPath
+                : path.resolve(ctx.cwd, rawPath);
+            const reason = await durableRootFileToolDenial(candidate, runWorkspaceDir, durableRoot, allowlistedRoots);
+            if (reason !== undefined) {
+                return { block: true, reason };
+            }
+            return undefined;
+        });
+    };
+}
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -825,6 +855,19 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             restoreProvider?.();
             return { ok: false, reason };
         };
+        const extensionFactories = [
+            {
+                name: STAGEFLOW_PATH_DENY_EXTENSION_NAME,
+                factory: createDurableRootPathDenyExtension({
+                    runWorkspaceDir: roots.runWorkspaceDir,
+                    durableRoot: globalStageflowHome(),
+                    ...(roots.checkoutRoot !== undefined
+                        ? { checkoutRoot: roots.checkoutRoot }
+                        : {}),
+                }),
+            },
+            ...(attached.extensionFactories ?? []),
+        ];
         const loader = createSealedResourceLoader({
             cwd: roots.cwd,
             agentDir: roots.agentDir,
@@ -834,9 +877,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             ...(input.skillFilePath !== undefined
                 ? { additionalSkillPaths: [input.skillFilePath] }
                 : {}),
-            ...(attached.extensionFactories !== undefined
-                ? { extensionFactories: attached.extensionFactories }
-                : {}),
+            extensionFactories,
             ...(attached.eventBus !== undefined ? { eventBus: attached.eventBus } : {}),
         });
         await loader.reload();
@@ -943,6 +984,13 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
         const liveSession = session;
         return {
             session: liveSession,
@@ -1011,6 +1059,13 @@ async function bindStageSession(input, sessionManager, wiring) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
     }
     catch (err) {
         await shutdownSession(session);

package/dist/agent/piIsolatedMcp.d.ts

@@ -1,6 +1,8 @@
 import { type EventBus, type InlineExtension } from "@earendil-works/pi-coding-agent";
 import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 export declare const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
+export declare function jitiFsCacheDir(): string;
+export declare function resetCreateMcpAdapterCacheForTests(): void;
 type IsolatedMcpServerEntry = Record<string, unknown> & {
     lifecycle: "lazy" | "eager";
     directTools: true;

package/dist/agent/piIsolatedMcp.js

@@ -1,10 +1,18 @@
+import path from "node:path";
 import { createEventBus, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError, } from "../config/resolveStageMcpServers.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 export const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
 const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
-const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 5_000;
+const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 30_000;
 const STATUS_POLL_MS = 50;
 const PI_MCP_ADAPTER_SPEC = "pi-mcp-adapter";
+export function jitiFsCacheDir() {
+    return path.join(globalStageflowHome(), "cache", "jiti");
+}
+export function resetCreateMcpAdapterCacheForTests() {
+    cachedCreateMcpAdapter = undefined;
+}
 const ISOLATED_MCP_SETTINGS = {
     directTools: true,
     elicitation: false,
@@ -58,7 +66,7 @@ async function loadCreateMcpAdapter() {
         // Node does not type-strip .ts under node_modules.
     }
     const { createJiti } = await import("jiti/static");
-    const jiti = createJiti(import.meta.url);
+    const jiti = createJiti(import.meta.url, { fsCache: jitiFsCacheDir() });
     const mod = (await jiti.import(PI_MCP_ADAPTER_SPEC));
     cachedCreateMcpAdapter = mod.createMcpAdapter;
     return cachedCreateMcpAdapter;

package/dist/agent/port.d.ts

@@ -75,6 +75,12 @@ export type StageRunInput = {
     repairContext?: StageRepairContext;
     /** Live attempt-scoped QA trail; read at emit execute time, not bootstrap time. */
     readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
+    /** Optional: record the provider-resolved model after resolveCliModel. */
+    onResolvedModel?: (info: {
+        stageId: string;
+        model: string;
+        thinkingLevel?: string;
+    }) => void | Promise<void>;
 };
 export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "stageId">): string;
 export type StageRunResult = {

package/dist/agent/streamLogRedact.d.ts

@@ -1,2 +1,2 @@
-/** Scrub common secret-shaped substrings before text is persisted or returned. */
+/** Scrub secret-shaped substrings and registered values before text is persisted. */
 export declare function redactSecrets(text: string): string;

package/dist/agent/streamLogRedact.js

@@ -1,13 +1,6 @@
-const SECRET_PATTERNS = [
-    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
-    /\bghp_[A-Za-z0-9]{20,}\b/g,
-    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
-];
-/** Scrub common secret-shaped substrings before text is persisted or returned. */
+import { redactString } from "../logging/redact.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+/** Scrub secret-shaped substrings and registered values before text is persisted. */
 export function redactSecrets(text) {
-    let out = text;
-    for (const pattern of SECRET_PATTERNS) {
-        out = out.replace(pattern, "[redacted]");
-    }
-    return out;
+    return redactString(text, { namedSecrets: getNamedSecrets() });
 }

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;
+    }
+}