stageflow 0.35.0 → 0.36.0

package/dist/channels/health.js

@@ -0,0 +1,99 @@
+import { ChannelError } from "./errors.js";
+export const DEFAULT_HEALTH_INTERVAL_MS = 300000;
+function failed(code, retryable) {
+    return { state: "failed", checkedAt: new Date().toISOString(), error: { code, retryable } };
+}
+/**
+ * Host-only background check. It keeps the last result per connection in memory so the
+ * Connections page can show current status. It never sends a message and keeps no secrets.
+ * Failures back off up to `maxBackoffFactor` times the interval; successes return to it.
+ */
+export class ChannelHealthMonitor {
+    registry;
+    intervalMs;
+    jitter;
+    timeoutMs;
+    maxBackoffFactor;
+    random;
+    onResult;
+    results = new Map();
+    failures = new Map();
+    timers = new Map();
+    inflight = new Set();
+    controller = new AbortController();
+    running = false;
+    constructor(options) {
+        this.registry = options.registry;
+        this.intervalMs = options.intervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
+        this.jitter = options.jitter ?? 0.2;
+        this.timeoutMs = options.timeoutMs ?? 8000;
+        this.maxBackoffFactor = options.maxBackoffFactor ?? 8;
+        this.random = options.random ?? Math.random;
+        this.onResult = options.onResult;
+    }
+    snapshot() {
+        return Object.fromEntries([...this.results].map(([id, health]) => [id, structuredClone(health)]));
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.controller = new AbortController();
+        for (const connection of this.registry.list()) {
+            if (connection.enabled)
+                this.schedule(connection.id, Math.floor(this.random() * 2000));
+        }
+    }
+    async stop() {
+        this.running = false;
+        this.controller.abort();
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        await Promise.allSettled([...this.inflight]);
+    }
+    /** Runs one check now, outside the schedule. */
+    async checkNow(connectionId) {
+        const health = await this.runCheck(connectionId);
+        this.results.set(connectionId, health);
+        this.onResult?.(connectionId, structuredClone(health));
+        return structuredClone(health);
+    }
+    schedule(id, delay) {
+        if (!this.running)
+            return;
+        const timer = setTimeout(() => {
+            this.timers.delete(id);
+            const work = this.checkNow(id).then(health => {
+                const count = health.state === "ok" ? 0 : (this.failures.get(id) ?? 0) + 1;
+                this.failures.set(id, count);
+                this.schedule(id, this.nextDelay(count));
+            }).finally(() => { this.inflight.delete(work); });
+            this.inflight.add(work);
+        }, delay);
+        timer.unref?.();
+        this.timers.set(id, timer);
+    }
+    nextDelay(failureCount) {
+        const factor = Math.min(2 ** failureCount, this.maxBackoffFactor);
+        const base = this.intervalMs * (failureCount === 0 ? 1 : factor);
+        return Math.round(base * (1 + (this.random() * 2 - 1) * this.jitter));
+    }
+    async runCheck(id) {
+        let timer;
+        try {
+            const provider = this.registry.providerFor(id);
+            const connection = this.registry.resolve(id);
+            const timeout = new Promise(resolve => {
+                timer = setTimeout(() => resolve(failed("CHANNEL_TIMEOUT", true)), this.timeoutMs);
+            });
+            return await Promise.race([provider.check(connection, this.controller.signal), timeout]);
+        }
+        catch (error) {
+            return error instanceof ChannelError ? failed(error.code, error.retryable) : failed("CHANNEL_CONNECTION_FAILED", false);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/channels/host.d.ts

@@ -0,0 +1,55 @@
+import type { StageConfig } from "../types/stage.js";
+import { ChannelRegistry, type ChannelRegistryOptions } from "./registry.js";
+import { type ChannelErrorCode } from "./errors.js";
+import { ChannelSends } from "./ledger.js";
+export type ChannelSendInput = {
+    channel?: string;
+    text: string;
+    subject?: string;
+    operationKey: string;
+};
+export type ChannelSendResult = {
+    channel: string;
+    connection: string;
+    providerMessageId?: string;
+    submittedAt: string;
+    warnings?: string[];
+};
+export type StageChannels = {
+    send(input: ChannelSendInput): Promise<ChannelSendResult>;
+};
+export declare const MAX_MESSAGE_TEXT = 65536;
+export declare class ChannelHost {
+    private readonly cwd;
+    private readonly options;
+    registry: ChannelRegistry;
+    readonly sends: ChannelSends;
+    constructor(cwd: string, options?: Omit<ChannelRegistryOptions, "cwd">);
+    /** Re-reads connections.yaml after an edit. A file that no longer loads keeps the old registry. */
+    reload(): void;
+}
+export declare function channelHostFor(cwd: string): ChannelHost;
+/** Re-reads connections.yaml in every cached host, so an edit made once reaches every project. */
+export declare function reloadChannelHosts(): void;
+export declare function releaseChannelHost(cwd: string): Promise<void>;
+/** Fails with the first problem found. Static only: no network, no secret reads. */
+export declare function validateStageChannelConnections(host: ChannelHost, stage: Pick<StageConfig, "id" | "channels">): void;
+/**
+ * Removes every variable the loaded connections point at, and its `_FILE` form, from a worker
+ * environment. It reads the names from the same registry the host sends with, so the variables
+ * stripped always belong to the file the host actually loaded. A file that cannot be loaded
+ * leaves the environment unchanged.
+ */
+export declare function channelsWorkerEnvironment(env: NodeJS.ProcessEnv, cwd: string): NodeJS.ProcessEnv;
+/**
+ * Host-side authorization and delivery for one stage. The target comes from the stage's
+ * frozen `channels`, never from the caller. The caller's operation key is bound to the run,
+ * stage and channel before it reaches the ledger.
+ */
+export declare function stageChannels(host: ChannelHost, stage: StageConfig, runId: string): StageChannels;
+export declare function channelFault(error: unknown): {
+    code: ChannelErrorCode;
+    retryable: boolean;
+};
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export declare function workerStageChannels(): StageChannels;

package/dist/channels/host.js

@@ -0,0 +1,185 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+import { ChannelRegistry } from "./registry.js";
+import { ChannelError } from "./errors.js";
+import { ChannelSends } from "./ledger.js";
+import { channelKey, channelTarget, stageChannelLimit, validateStageChannels } from "./stageChannels.js";
+export const MAX_MESSAGE_TEXT = 65536;
+const WORKER_TIMEOUT_MS = 65000;
+const sendSchema = z.object({
+    channel: z.string().min(1).max(200).optional(),
+    text: z.string().min(1).max(MAX_MESSAGE_TEXT),
+    subject: z.string().min(1).max(998).regex(/^[^\r\n]*$/).optional(),
+    operationKey: z.string().min(1).max(120),
+}).strict();
+export class ChannelHost {
+    cwd;
+    options;
+    registry;
+    sends;
+    constructor(cwd, options = {}) {
+        this.cwd = cwd;
+        this.options = options;
+        this.registry = new ChannelRegistry({ cwd, ...options });
+        this.sends = new ChannelSends(this.registry.scope);
+    }
+    /** Re-reads connections.yaml after an edit. A file that no longer loads keeps the old registry. */
+    reload() {
+        this.registry = new ChannelRegistry({ cwd: this.cwd, ...this.options });
+    }
+}
+const hosts = new Map();
+export function channelHostFor(cwd) {
+    const key = path.resolve(cwd);
+    let entry = hosts.get(key);
+    if (entry?.releasing)
+        throw new ChannelError("CHANNEL_CONNECTION_FAILED", true);
+    if (!entry) {
+        entry = { host: new ChannelHost(key) };
+        hosts.set(key, entry);
+    }
+    return entry.host;
+}
+/** Re-reads connections.yaml in every cached host, so an edit made once reaches every project. */
+export function reloadChannelHosts() {
+    for (const entry of hosts.values()) {
+        try {
+            entry.host.reload();
+        }
+        catch {
+            /* a host whose file no longer loads keeps its previous registry until the file is fixed */
+        }
+    }
+}
+export async function releaseChannelHost(cwd) {
+    const key = path.resolve(cwd);
+    const entry = hosts.get(key);
+    if (!entry)
+        return;
+    entry.releasing ??= (async () => {
+        entry.host.sends.setAccepting(false);
+        await entry.host.sends.drain();
+    })();
+    await entry.releasing;
+    if (hosts.get(key) === entry)
+        hosts.delete(key);
+}
+/** Fails with the first problem found. Static only: no network, no secret reads. */
+export function validateStageChannelConnections(host, stage) {
+    const [first] = validateStageChannels(host.registry, stage);
+    if (first)
+        throw new ChannelError(first.code, false, { connectionId: stage.channels?.find(channel => channelKey(channel) === first.key)?.connection });
+}
+/**
+ * Removes every variable the loaded connections point at, and its `_FILE` form, from a worker
+ * environment. It reads the names from the same registry the host sends with, so the variables
+ * stripped always belong to the file the host actually loaded. A file that cannot be loaded
+ * leaves the environment unchanged.
+ */
+export function channelsWorkerEnvironment(env, cwd) {
+    const result = { ...env };
+    let names;
+    try {
+        names = channelHostFor(cwd).registry.envSecretNames();
+    }
+    catch {
+        return result;
+    }
+    for (const name of names) {
+        delete result[name];
+        delete result[`${name}_FILE`];
+    }
+    return result;
+}
+function pick(channels, requested) {
+    if (requested !== undefined) {
+        const found = channels.find(channel => channelKey(channel) === requested);
+        if (!found)
+            throw new ChannelError("CHANNEL_UNAUTHORIZED");
+        return found;
+    }
+    if (channels.length === 1)
+        return channels[0];
+    throw new ChannelError("CHANNEL_INVALID_INPUT", false, { field: "channel" });
+}
+function hashOf(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/**
+ * Host-side authorization and delivery for one stage. The target comes from the stage's
+ * frozen `channels`, never from the caller. The caller's operation key is bound to the run,
+ * stage and channel before it reaches the ledger.
+ */
+export function stageChannels(host, stage, runId) {
+    const declared = structuredClone(stage.channels ?? []);
+    const stageId = stage.id;
+    const tooMany = declared.length > stageChannelLimit();
+    return {
+        async send(raw) {
+            if (tooMany)
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            const parsed = sendSchema.safeParse(raw);
+            if (!parsed.success)
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            const input = parsed.data;
+            const channel = pick(declared, input.channel);
+            if (!channel.operations.includes("send"))
+                throw new ChannelError("CHANNEL_UNAUTHORIZED", false, { connectionId: channel.connection });
+            const key = channelKey(channel);
+            const target = host.registry.validateTarget(channel.connection, channelTarget(channel));
+            const provider = host.registry.providerFor(channel.connection);
+            const connection = host.registry.resolve(channel.connection);
+            const message = { text: input.text, ...(input.subject !== undefined ? { subject: input.subject } : {}) };
+            const operationKey = hashOf([runId, stageId, key, input.operationKey]);
+            const receipt = await host.sends.send({ connectionId: channel.connection, operationKey, hash: hashOf([key, channel.connection, channelTarget(channel), message]) }, () => provider.send(connection, target, message, { operationKey, runId, stageId }));
+            return {
+                channel: key,
+                connection: channel.connection,
+                ...(receipt.providerMessageId !== undefined ? { providerMessageId: receipt.providerMessageId } : {}),
+                submittedAt: receipt.submittedAt,
+                ...(receipt.warnings?.length ? { warnings: receipt.warnings } : {}),
+            };
+        },
+    };
+}
+export function channelFault(error) {
+    return error instanceof ChannelError
+        ? { code: error.code, retryable: error.retryable }
+        : { code: "CHANNEL_CONNECTION_FAILED", retryable: false };
+}
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export function workerStageChannels() {
+    return {
+        send(input) {
+            return new Promise((resolve, reject) => {
+                if (!process.connected || !process.send) {
+                    reject(new ChannelError("CHANNEL_UNAUTHORIZED"));
+                    return;
+                }
+                const requestId = randomUUID();
+                const finish = (error, result) => {
+                    clearTimeout(timer);
+                    process.off("message", receive);
+                    process.off("disconnect", disconnected);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(result);
+                };
+                const disconnected = () => finish(new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN"));
+                const receive = (message) => {
+                    const response = message;
+                    if (response?.type !== "channel.response" || response.requestId !== requestId)
+                        return;
+                    finish(response.error ? new ChannelError(response.error.code, response.error.retryable) : undefined, response.receipt);
+                };
+                const timer = setTimeout(disconnected, WORKER_TIMEOUT_MS);
+                process.on("message", receive);
+                process.once("disconnect", disconnected);
+                process.send({ type: "channel.send", requestId, input }, error => { if (error)
+                    disconnected(); });
+            });
+        },
+    };
+}

package/dist/channels/http.d.ts

@@ -0,0 +1,31 @@
+import { ChannelError } from "./errors.js";
+export type HttpMode = "check" | "send";
+export type HttpCall = {
+    fetch: typeof fetch;
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: unknown;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    mode: HttpMode;
+    connectionId?: string;
+};
+export type HttpResult = {
+    status: number;
+    text: string;
+};
+/**
+ * Maps a transport failure. For a send, only failures that happen before the request leaves
+ * the machine are definite; everything else may have reached the provider, so it is unknown.
+ */
+export declare function networkFailure(error: unknown, mode: HttpMode, timedOut: boolean, connectionId?: string): ChannelError;
+/** Maps an HTTP status to a channel error. `retryable` is true only for transient conditions. */
+export declare function statusFailure(status: number, mode: HttpMode, connectionId?: string): ChannelError;
+/**
+ * One bounded HTTP call. Redirects are refused so a credential header never follows a
+ * redirect to another host. Response bodies are returned to the provider but never put in
+ * an error, so provider messages cannot carry a secret into a log or a tool result.
+ */
+export declare function httpCall(call: HttpCall): Promise<HttpResult>;
+export declare function parseJson(text: string): unknown;

package/dist/channels/http.js

@@ -0,0 +1,79 @@
+import { ChannelError } from "./errors.js";
+const NOT_SENT_CODES = new Set(["ENOTFOUND", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "ERR_TLS_CERT_ALTNAME_INVALID", "CERT_HAS_EXPIRED", "DEPTH_ZERO_SELF_SIGNED_CERT", "UNABLE_TO_VERIFY_LEAF_SIGNATURE"]);
+function causeCode(error) {
+    const cause = error?.cause;
+    return typeof cause?.code === "string" ? cause.code : undefined;
+}
+/**
+ * Maps a transport failure. For a send, only failures that happen before the request leaves
+ * the machine are definite; everything else may have reached the provider, so it is unknown.
+ */
+export function networkFailure(error, mode, timedOut, connectionId) {
+    const detail = connectionId ? { connectionId } : undefined;
+    if (timedOut)
+        return new ChannelError(mode === "send" ? "CHANNEL_SEND_OUTCOME_UNKNOWN" : "CHANNEL_TIMEOUT", mode !== "send", detail);
+    if (mode === "check")
+        return new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    const code = causeCode(error);
+    if (code !== undefined && NOT_SENT_CODES.has(code))
+        return new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    return new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail);
+}
+/** Maps an HTTP status to a channel error. `retryable` is true only for transient conditions. */
+export function statusFailure(status, mode, connectionId) {
+    const detail = connectionId ? { connectionId } : undefined;
+    if (status === 401)
+        return new ChannelError("CHANNEL_AUTH_FAILED", false, detail);
+    if (status === 403)
+        return new ChannelError("CHANNEL_UNAUTHORIZED", false, detail);
+    if (status === 429)
+        return new ChannelError("CHANNEL_RATE_LIMIT", true, detail);
+    if (status >= 500) {
+        return mode === "send"
+            ? new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail)
+            : new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    }
+    if (status === 408)
+        return new ChannelError(mode === "send" ? "CHANNEL_SEND_OUTCOME_UNKNOWN" : "CHANNEL_TIMEOUT", mode !== "send", detail);
+    return new ChannelError("CHANNEL_INVALID_INPUT", false, detail);
+}
+/**
+ * One bounded HTTP call. Redirects are refused so a credential header never follows a
+ * redirect to another host. Response bodies are returned to the provider but never put in
+ * an error, so provider messages cannot carry a secret into a log or a tool result.
+ */
+export async function httpCall(call) {
+    const timeout = AbortSignal.timeout(call.timeoutMs);
+    const signal = call.signal ? AbortSignal.any([call.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await call.fetch(call.url, {
+            method: call.method,
+            headers: { ...call.headers, ...(call.body !== undefined ? { "content-type": "application/json" } : {}) },
+            ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+            redirect: "error",
+            signal,
+        });
+    }
+    catch (error) {
+        throw networkFailure(error, call.mode, timeout.aborted, call.connectionId);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        if (response.ok && call.mode === "send")
+            return { status: response.status, text: "" };
+        throw networkFailure(error, call.mode, timeout.aborted, call.connectionId);
+    }
+    return { status: response.status, text };
+}
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/channels/index.d.ts

@@ -0,0 +1,10 @@
+export { ChannelError, type ChannelErrorCode, type ChannelErrorDetail } from "./errors.js";
+export { CONNECTIONS_FILE_NAME, ChannelRegistry, type ChannelRegistryOptions } from "./registry.js";
+export { loadConnectionsFile, parseConnectionsYaml, type ConnectionsFile } from "./config.js";
+export { isSecretRef, redactSecrets, resolveSecretRef, resolveSecrets } from "./secrets.js";
+export type * from "./types.js";
+export { MAX_CHANNEL_TARGETS, MAX_CHANNELS_PER_STAGE, MAX_STAGE_CHANNELS, channelLimitMessage, setStageChannelLimitForTests, stageChannelLimit, channelKey, channelTarget, mergeChannelDefaults, parseChannels, validateStageChannels, type ParsedChannels, type StageChannelIssue, } from "./stageChannels.js";
+export { ChannelHost, MAX_MESSAGE_TEXT, channelFault, channelHostFor, channelsWorkerEnvironment, releaseChannelHost, stageChannels, validateStageChannelConnections, workerStageChannels, type ChannelSendInput, type ChannelSendResult, type StageChannels, } from "./host.js";
+export { ChannelSends, type ChannelSendRecord } from "./ledger.js";
+export { channelProviders, registerChannelProvider, unregisterChannelProvider } from "./providers.js";
+export { ChannelHealthMonitor, DEFAULT_HEALTH_INTERVAL_MS, type ChannelHealthOptions } from "./health.js";

package/dist/channels/index.js

@@ -0,0 +1,9 @@
+export { ChannelError } from "./errors.js";
+export { CONNECTIONS_FILE_NAME, ChannelRegistry } from "./registry.js";
+export { loadConnectionsFile, parseConnectionsYaml } from "./config.js";
+export { isSecretRef, redactSecrets, resolveSecretRef, resolveSecrets } from "./secrets.js";
+export { MAX_CHANNEL_TARGETS, MAX_CHANNELS_PER_STAGE, MAX_STAGE_CHANNELS, channelLimitMessage, setStageChannelLimitForTests, stageChannelLimit, channelKey, channelTarget, mergeChannelDefaults, parseChannels, validateStageChannels, } from "./stageChannels.js";
+export { ChannelHost, MAX_MESSAGE_TEXT, channelFault, channelHostFor, channelsWorkerEnvironment, releaseChannelHost, stageChannels, validateStageChannelConnections, workerStageChannels, } from "./host.js";
+export { ChannelSends } from "./ledger.js";
+export { channelProviders, registerChannelProvider, unregisterChannelProvider } from "./providers.js";
+export { ChannelHealthMonitor, DEFAULT_HEALTH_INTERVAL_MS } from "./health.js";

package/dist/channels/ledger.d.ts

@@ -0,0 +1,37 @@
+import { type ChannelErrorCode } from "./errors.js";
+import type { SendReceipt } from "./types.js";
+export type ChannelSendRecord = {
+    operationId: string;
+    connectionId: string;
+    operationKey: string;
+    hash: string;
+    state: "pending" | "submitted" | "failed" | "unknown";
+    createdAt: string;
+    receipt?: SendReceipt;
+    error?: {
+        code: ChannelErrorCode;
+        retryable: boolean;
+    };
+};
+export type ChannelSendIdentity = {
+    connectionId: string;
+    operationKey: string;
+    hash: string;
+};
+/**
+ * Durable record of send attempts, so a retried tool call or a resumed stage never sends twice.
+ * It stores a hash of the request, never the message text. The host is the single writer.
+ * A pending record that survives a crash becomes an uncertain outcome, never a resend.
+ */
+export declare class ChannelSends {
+    private readonly file;
+    private records;
+    private readonly active;
+    private accepting;
+    constructor(scope: string);
+    list(): ChannelSendRecord[];
+    drain(): Promise<void>;
+    setAccepting(accepting: boolean): void;
+    send(identity: ChannelSendIdentity, submit: () => Promise<SendReceipt>): Promise<SendReceipt>;
+    private persist;
+}

package/dist/channels/ledger.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { storeRootFor } from "../runstore/paths.js";
+import { ChannelError } from "./errors.js";
+const RETENTION_MS = 30 * 86400000;
+const MAX_RECORDS = 10000;
+/**
+ * Durable record of send attempts, so a retried tool call or a resumed stage never sends twice.
+ * It stores a hash of the request, never the message text. The host is the single writer.
+ * A pending record that survives a crash becomes an uncertain outcome, never a resend.
+ */
+export class ChannelSends {
+    file;
+    records;
+    active = new Map();
+    accepting = true;
+    constructor(scope) {
+        this.file = path.join(storeRootFor(scope), "channel-sends.json");
+        this.records = existsSync(this.file) ? JSON.parse(readFileSync(this.file, "utf8")) : [];
+        for (const record of this.records)
+            if (record.state === "pending")
+                record.state = "unknown";
+    }
+    list() {
+        return structuredClone(this.records);
+    }
+    async drain() {
+        await Promise.allSettled(this.active.values());
+    }
+    setAccepting(accepting) {
+        this.accepting = accepting;
+    }
+    async send(identity, submit) {
+        if (!this.accepting)
+            throw new ChannelError("CHANNEL_CONNECTION_FAILED", true, { connectionId: identity.connectionId });
+        const key = `${identity.connectionId}\0${identity.operationKey}`;
+        const found = this.records.find(record => record.connectionId === identity.connectionId && record.operationKey === identity.operationKey);
+        if (found) {
+            if (found.hash !== identity.hash)
+                throw new ChannelError("CHANNEL_OPERATION_CONFLICT", false, { connectionId: identity.connectionId });
+            const active = this.active.get(key);
+            if (active)
+                return active;
+            if (found.receipt)
+                return structuredClone(found.receipt);
+            if (found.state === "failed" && found.error)
+                throw new ChannelError(found.error.code, found.error.retryable, { connectionId: identity.connectionId });
+            throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+        }
+        const cutoff = Date.now() - RETENTION_MS;
+        this.records = this.records.filter(record => !["submitted", "failed"].includes(record.state) || Date.parse(record.createdAt) >= cutoff);
+        if (this.records.length >= MAX_RECORDS)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT", false, { connectionId: identity.connectionId });
+        const record = {
+            operationId: randomUUID(), connectionId: identity.connectionId, operationKey: identity.operationKey,
+            hash: identity.hash, state: "pending", createdAt: new Date().toISOString(),
+        };
+        this.records.push(record);
+        this.persist();
+        const work = Promise.resolve().then(submit).then(receipt => {
+            record.state = "submitted";
+            record.receipt = receipt;
+            try {
+                this.persist();
+            }
+            catch {
+                return { ...structuredClone(receipt), warnings: [...(receipt.warnings ?? []), "CHANNEL_STORAGE_FAILED"] };
+            }
+            return structuredClone(receipt);
+        }).catch(error => {
+            if (record.state === "submitted")
+                throw error;
+            const fault = error instanceof ChannelError ? error : new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+            record.state = fault.code === "CHANNEL_SEND_OUTCOME_UNKNOWN" ? "unknown" : "failed";
+            record.error = { code: fault.code, retryable: fault.retryable };
+            try {
+                this.persist();
+            }
+            catch {
+                record.state = "unknown";
+                throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: identity.connectionId });
+            }
+            throw new ChannelError(fault.code, fault.retryable, { connectionId: identity.connectionId });
+        }).finally(() => { this.active.delete(key); });
+        this.active.set(key, work);
+        return work;
+    }
+    persist() {
+        mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify(this.records), { mode: 0o600 });
+        renameSync(temporary, this.file);
+    }
+}

package/dist/channels/providers/agentmail.d.ts

@@ -0,0 +1,26 @@
+import type { ChannelProvider, ProviderMeta } from "../types.js";
+export type AgentMailConfig = {
+    inbox: string;
+    region: "us" | "eu";
+};
+export type AgentMailTarget = {
+    to: string[];
+    cc?: string[];
+};
+export declare const AGENTMAIL_BASE_URLS: {
+    readonly us: "https://api.agentmail.to";
+    readonly eu: "https://api.agentmail.eu";
+};
+export declare const AGENTMAIL_DEFAULT_SUBJECT = "Message from Stageflow";
+export declare const AGENTMAIL_META: ProviderMeta;
+export type AgentMailOptions = {
+    fetch?: typeof fetch;
+    baseUrls?: Partial<Record<"us" | "eu", string>>;
+    sendTimeoutMs?: number;
+    checkTimeoutMs?: number;
+};
+/**
+ * Sends mail from one existing AgentMail inbox through the REST API. Needs a key that can
+ * read the inbox and send messages. Receiving is not part of this phase.
+ */
+export declare function createAgentMailProvider(options?: AgentMailOptions): ChannelProvider<AgentMailConfig, AgentMailTarget>;