stageflow 0.36.0 → 0.39.0

package/dist/agents/communications/agentmail.d.ts

@@ -0,0 +1,19 @@
+import type { AgentInboundMessage } from "./port.js";
+export type AgentMailInboundConfig = {
+    connectionId: string;
+    webhookSecret: string;
+};
+export type AgentMailParseResult = {
+    ok: true;
+    message: AgentInboundMessage;
+} | {
+    ok: false;
+    code: "agent.signature_invalid" | "agent.invalid";
+};
+export declare function verifyAgentMailSignature(config: AgentMailInboundConfig, signatureHeader: string | undefined, rawBody: string): {
+    ok: true;
+} | {
+    ok: false;
+    code: "agent.signature_invalid";
+};
+export declare function parseAgentMailInbound(config: AgentMailInboundConfig, payload: unknown): AgentMailParseResult;

package/dist/agents/communications/agentmail.js

@@ -0,0 +1,46 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export function verifyAgentMailSignature(config, signatureHeader, rawBody) {
+    if (signatureHeader === undefined)
+        return { ok: false, code: "agent.signature_invalid" };
+    const expected = createHmac("sha256", config.webhookSecret).update(rawBody).digest("hex");
+    const left = Buffer.from(expected);
+    const right = Buffer.from(signatureHeader);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        return { ok: false, code: "agent.signature_invalid" };
+    }
+    return { ok: true };
+}
+export function parseAgentMailInbound(config, payload) {
+    if (typeof payload !== "object" || payload === null)
+        return { ok: false, code: "agent.invalid" };
+    const record = payload;
+    const eventId = typeof record.id === "string" ? record.id : undefined;
+    const threadId = typeof record.thread_id === "string"
+        ? record.thread_id
+        : typeof record.inbox_id === "string"
+            ? record.inbox_id
+            : undefined;
+    const text = typeof record.text === "string"
+        ? record.text.trim()
+        : typeof record.body === "string"
+            ? record.body.trim()
+            : "";
+    if (eventId === undefined || threadId === undefined || text.length === 0) {
+        return { ok: false, code: "agent.invalid" };
+    }
+    const from = typeof record.from === "string" ? record.from : undefined;
+    // Replies go to a message id (AgentMail's reply endpoint), never to the sender's address.
+    const replyTo = typeof record.message_id === "string" ? record.message_id : eventId;
+    return {
+        ok: true,
+        message: {
+            provider: "agentmail",
+            connectionId: config.connectionId,
+            eventId: `agentmail:${eventId}`,
+            threadId,
+            text,
+            replyTo,
+            ...(from !== undefined ? { from } : {}),
+        },
+    };
+}

package/dist/agents/communications/agentmailListener.d.ts

@@ -0,0 +1,59 @@
+import type { AgentInboundMessage } from "./port.js";
+import { type ChannelListener, type ListenerDeps } from "./listener.js";
+/** The slice of the AgentMail SDK socket this listener uses; tests supply a fake. */
+export type AgentMailSocket = {
+    on(event: "open" | "message" | "close" | "error", callback: (payload?: any) => void): void;
+    sendSubscribe(message: {
+        type: "subscribe";
+        inboxIds: string[];
+        eventTypes: string[];
+    }): void;
+    waitForOpen(): Promise<unknown>;
+    close(): void;
+};
+export type AgentMailMessage = {
+    inboxId: string;
+    threadId: string;
+    messageId: string;
+    labels?: string[];
+    timestamp?: string | Date;
+    from: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+    extractedText?: string;
+    headers?: Record<string, string>;
+};
+export type AgentMailTransport = {
+    connect(): Promise<AgentMailSocket>;
+    /** Mail that arrived while the Host was not listening. */
+    recent(inbox: string, since: Date): Promise<AgentMailMessage[]>;
+};
+export type AgentMailListenerConfig = {
+    connectionId: string;
+    inbox: string;
+};
+/** The bare address of "Name <a@b.com>", lowercased. */
+export declare function addressOf(from: string): string;
+/**
+ * Why an email must not get an answer, or undefined when it should. Keeps the agent out of mail loops:
+ * its own mail, bounces, automatic replies and no-reply senders.
+ */
+export declare function ignoreReason(message: AgentMailMessage, inbox: string): string | undefined;
+/** What the agent reads: the new text of the email (no quoted history), led by the subject on a first message. */
+export declare function bodyOf(message: AgentMailMessage): string;
+export declare function toInbound(connectionId: string, message: AgentMailMessage): AgentInboundMessage | undefined;
+/** Minutes of missed mail answered after a reconnect or restart. */
+export declare const CATCHUP_MINUTES = 15;
+/**
+ * Holds an AgentMail WebSocket open for one inbox. A dropped connection is retried with backoff and, once back,
+ * mail that arrived meanwhile is answered too (deduped by message id). Only `message.received` events count:
+ * spam, blocked and unauthenticated (spoofed sender) mail uses other event types and never reaches an agent.
+ */
+export declare function createAgentMailListener(config: AgentMailListenerConfig, transport: AgentMailTransport, deps: ListenerDeps): ChannelListener;
+/** The real transport over the AgentMail SDK. The SDK loads on first use, so a Host without AgentMail never needs it. */
+export declare function sdkAgentMailTransport(options: {
+    apiKey: string;
+    region: "us" | "eu";
+    inbox: string;
+}): AgentMailTransport;

package/dist/agents/communications/agentmailListener.js

@@ -0,0 +1,183 @@
+import { abortableSleep, reconnectDelay, StateTracker } from "./listener.js";
+const NOREPLY_LOCALPART = /^(mailer-daemon|postmaster|no-?reply|do-?not-?reply|bounce[sd]?|notifications?)([+._-].*)?$/i;
+/** The bare address of "Name <a@b.com>", lowercased. */
+export function addressOf(from) {
+    const angle = /<([^<>]+)>/.exec(from);
+    return (angle ? angle[1] : from).trim().toLowerCase();
+}
+function stripHtml(html) {
+    return html
+        .replace(/<(script|style)[\s\S]*?<\/\1>/gi, "")
+        .replace(/<br\s*\/?>|<\/p>|<\/div>/gi, "\n")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Why an email must not get an answer, or undefined when it should. Keeps the agent out of mail loops:
+ * its own mail, bounces, automatic replies and no-reply senders.
+ */
+export function ignoreReason(message, inbox) {
+    const labels = message.labels ?? [];
+    if (labels.includes("sent") || (labels.length > 0 && !labels.includes("received")))
+        return "not received mail";
+    const sender = addressOf(message.from);
+    if (sender === inbox.toLowerCase())
+        return "from the agent's own inbox";
+    const local = sender.split("@")[0] ?? "";
+    if (NOREPLY_LOCALPART.test(local))
+        return "from a no-reply or system sender";
+    const headers = Object.fromEntries(Object.entries(message.headers ?? {}).map(([key, value]) => [key.toLowerCase(), String(value).toLowerCase()]));
+    if (headers["auto-submitted"] !== undefined && headers["auto-submitted"] !== "no")
+        return "automatic reply";
+    if (headers["x-auto-response-suppress"] !== undefined)
+        return "automatic reply";
+    if (["bulk", "list", "junk"].includes(headers.precedence ?? ""))
+        return "bulk mail";
+    return undefined;
+}
+/** What the agent reads: the new text of the email (no quoted history), led by the subject on a first message. */
+export function bodyOf(message) {
+    const body = (message.extractedText ?? message.text ?? (message.html ? stripHtml(message.html) : "")).trim();
+    const subject = message.subject?.trim();
+    if (body.length === 0)
+        return "";
+    return subject && !/^(re|fwd?):/i.test(subject) ? `Subject: ${subject}\n\n${body}` : body;
+}
+export function toInbound(connectionId, message) {
+    const text = bodyOf(message);
+    if (text.length === 0)
+        return undefined;
+    return {
+        provider: "agentmail",
+        connectionId,
+        // The message id (not the event id) so the live stream and the catch-up list dedupe against each other.
+        eventId: `agentmail:${message.messageId}`,
+        threadId: message.threadId,
+        text,
+        from: message.from,
+        replyTo: message.messageId,
+    };
+}
+/** Minutes of missed mail answered after a reconnect or restart. */
+export const CATCHUP_MINUTES = 15;
+/**
+ * Holds an AgentMail WebSocket open for one inbox. A dropped connection is retried with backoff and, once back,
+ * mail that arrived meanwhile is answered too (deduped by message id). Only `message.received` events count:
+ * spam, blocked and unauthenticated (spoofed sender) mail uses other event types and never reaches an agent.
+ */
+export function createAgentMailListener(config, transport, deps) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? abortableSleep;
+    const tracker = new StateTracker(now);
+    const abort = new AbortController();
+    let loop;
+    let socket;
+    async function handle(message) {
+        const reason = ignoreReason(message, config.inbox);
+        if (reason) {
+            deps.log(`agentmail ${config.connectionId}: ignored a message (${reason})`);
+            return;
+        }
+        const inbound = toInbound(config.connectionId, message);
+        if (!inbound)
+            return;
+        tracker.received();
+        await deps.onMessage(inbound).catch((error) => deps.log(`agentmail ${config.connectionId}: delivery failed: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    async function session() {
+        const opened = await transport.connect();
+        socket = opened;
+        const closed = new Promise((resolve) => {
+            opened.on("close", () => resolve(undefined));
+            opened.on("error", (error) => resolve(error instanceof Error ? error.message : "connection error"));
+        });
+        opened.on("message", (payload) => {
+            if (payload?.type === "event" && payload.eventType === "message.received" && payload.message && payload.message.inboxId === config.inbox)
+                void handle(payload.message);
+        });
+        await opened.waitForOpen();
+        opened.sendSubscribe({ type: "subscribe", inboxIds: [config.inbox], eventTypes: ["message.received"] });
+        tracker.set("connected");
+        const missed = await transport.recent(config.inbox, new Date(now() - CATCHUP_MINUTES * 60_000)).catch(() => []);
+        for (const message of missed)
+            await handle(message);
+        const reason = await Promise.race([closed, new Promise((resolve) => abort.signal.addEventListener("abort", () => resolve(undefined), { once: true }))]);
+        if (!abort.signal.aborted)
+            throw new Error(reason ?? "connection closed");
+    }
+    async function run() {
+        let attempt = 0;
+        while (!abort.signal.aborted) {
+            try {
+                await session();
+                attempt = 0;
+            }
+            catch (error) {
+                if (abort.signal.aborted)
+                    break;
+                const message = error instanceof Error ? error.message : String(error);
+                tracker.set(attempt === 0 ? "reconnecting" : "failed", message);
+                deps.log(`agentmail ${config.connectionId}: ${message}; retrying`);
+                attempt += 1;
+                await sleep(reconnectDelay(attempt - 1), abort.signal);
+            }
+            finally {
+                try {
+                    socket?.close();
+                }
+                catch {
+                    // already closed
+                }
+                socket = undefined;
+            }
+        }
+        tracker.set("stopped");
+    }
+    return {
+        async start() {
+            loop = run();
+            await Promise.resolve();
+        },
+        async stop() {
+            abort.abort();
+            try {
+                socket?.close();
+            }
+            catch {
+                // already closed
+            }
+            await loop;
+        },
+        state: () => tracker.get(),
+    };
+}
+/** The real transport over the AgentMail SDK. The SDK loads on first use, so a Host without AgentMail never needs it. */
+export function sdkAgentMailTransport(options) {
+    let client;
+    const load = async () => {
+        if (client)
+            return client;
+        const sdk = await import("agentmail");
+        client = new sdk.AgentMailClient({ apiKey: options.apiKey, environment: options.region === "eu" ? sdk.AgentMailEnvironment.EuProd : sdk.AgentMailEnvironment.Prod });
+        return client;
+    };
+    return {
+        async connect() {
+            const sdkClient = await load();
+            const socket = await sdkClient.websockets.connect({ reconnectAttempts: 0 });
+            return socket;
+        },
+        async recent(inbox, since) {
+            const sdkClient = await load();
+            const page = await sdkClient.inboxes.messages.list(inbox, { after: since, labels: ["received"], limit: 50, ascending: true });
+            // The list carries previews only; the agent needs the body.
+            const full = await Promise.all((page.messages ?? []).map((item) => sdkClient.inboxes.messages.get(inbox, item.messageId)));
+            return full;
+        },
+    };
+}

package/dist/agents/communications/allowlist.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Who may message an agent over its channel. Entries are an email address, a phone number
+ * (E.164), `@domain` for everyone at a domain, a Slack user id (`U02ABC123`), a Telegram `@username`,
+ * or `*` for anyone. An empty list lets nobody in.
+ */
+export declare const SENDER_ENTRY: RegExp;
+/** "Jane Doe <Jane@X.com>" -> "jane@x.com"; phone numbers lose spaces, dashes and brackets. */
+export declare function normalizeSender(raw: string): string;
+export declare function normalizeEntry(entry: string): string;
+export declare function senderAllowed(allowFrom: readonly string[], sender: string | undefined): boolean;

package/dist/agents/communications/allowlist.js

@@ -0,0 +1,36 @@
+/**
+ * Who may message an agent over its channel. Entries are an email address, a phone number
+ * (E.164), `@domain` for everyone at a domain, a Slack user id (`U02ABC123`), a Telegram `@username`,
+ * or `*` for anyone. An empty list lets nobody in.
+ */
+export const SENDER_ENTRY = /^(\*|@[^\s@]+\.[^\s@]+|[^\s@]+@[^\s@]+\.[^\s@]+|\+[1-9]\d{6,14}|[UW][A-Z0-9]{7,}|@[A-Za-z][A-Za-z0-9_]{4,31})$/;
+/** "Jane Doe <Jane@X.com>" -> "jane@x.com"; phone numbers lose spaces, dashes and brackets. */
+export function normalizeSender(raw) {
+    const angle = /<([^<>]+)>/.exec(raw);
+    const value = (angle ? angle[1] : raw).trim();
+    if (/^[+\d][\d\s().-]*$/.test(value))
+        return value.replace(/[\s().-]/g, "");
+    return value.toLowerCase();
+}
+export function normalizeEntry(entry) {
+    return entry === "*" ? entry : normalizeSender(entry);
+}
+export function senderAllowed(allowFrom, sender) {
+    if (allowFrom.length === 0)
+        return false;
+    if (allowFrom.includes("*"))
+        return true;
+    if (sender === undefined)
+        return false;
+    const who = normalizeSender(sender);
+    const domain = who.includes("@") ? who.slice(who.lastIndexOf("@")) : undefined;
+    return allowFrom.some((entry) => {
+        const allowed = normalizeEntry(entry);
+        if (allowed === who)
+            return true;
+        if (!allowed.startsWith("@"))
+            return false;
+        // `@domain` matches everyone at it; a dotless `@name` is a Telegram username (senders arrive without the `@`).
+        return allowed.includes(".") ? domain === allowed : who === allowed.slice(1);
+    });
+}

package/dist/agents/communications/channelConnections.d.ts

@@ -0,0 +1,3 @@
+import type { InboundConnections } from "./inbound.js";
+/** Inbound lookups and replies over the Host's connections (`connections.yaml`). */
+export declare function channelInboundConnections(cwd: string): InboundConnections;

package/dist/agents/communications/channelConnections.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { channelHostFor } from "../../channels/host.js";
+const hashOf = (parts) => createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+/** Inbound lookups and replies over the Host's connections (`connections.yaml`). */
+export function channelInboundConnections(cwd) {
+    return {
+        find(connectionId) {
+            try {
+                const host = channelHostFor(cwd);
+                const connection = host.registry.resolve(connectionId);
+                return { provider: connection.provider, secret: connection.secrets.inboundSecret };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async reply(connectionId, to, text, operationKey) {
+            const host = channelHostFor(cwd);
+            const provider = host.registry.providerFor(connectionId);
+            const connection = host.registry.resolve(connectionId);
+            const message = { text };
+            // A provider that can answer inside the conversation does; otherwise the reply is a new message to the sender.
+            const submit = provider.reply
+                ? () => provider.reply(connection, to, message, { operationKey })
+                : () => provider.send(connection, host.registry.validateTarget(connectionId, { to }), message, { operationKey });
+            await host.sends.send({ connectionId, operationKey, hash: hashOf([connectionId, to, message]) }, submit);
+        },
+        async contact(connectionId) {
+            try {
+                const host = channelHostFor(cwd);
+                const provider = host.registry.providerFor(connectionId);
+                if (!provider.contact)
+                    return undefined;
+                return await provider.contact(host.registry.resolve(connectionId, false));
+            }
+            catch {
+                return undefined;
+            }
+        },
+        resolve(connectionId) {
+            try {
+                const host = channelHostFor(cwd);
+                const connection = host.registry.resolve(connectionId);
+                return { id: connection.id, provider: connection.provider, config: connection.config, secrets: connection.secrets, credential: connection.credential ? { secrets: connection.credential.secrets } : undefined };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/agents/communications/delivery.d.ts

@@ -0,0 +1,53 @@
+import type { DeliveryInput } from "../ledgers.js";
+import type { AgentService } from "../service.js";
+import type { AgentDelivery } from "../store.js";
+/** Waits before each automatic retry of a reply that definitely did not go out. */
+export declare const RETRY_BACKOFF_MS: number[];
+export type { DeliveryInput };
+type Reply = (connectionId: string, to: string, text: string, operationKey: string) => Promise<void>;
+type Outcome = {
+    kind: "failed" | "unknown";
+    retryable: boolean;
+    code: string;
+    message: string;
+};
+/** Sorts a send failure into "never left" (safe to retry when transient) and "may have arrived" (never resent on its own). */
+export declare function classifySendFailure(error: unknown): Outcome;
+/**
+ * Gets an agent's reply to the person on the channel they wrote from. The turn only counts as succeeded once the
+ * reply is delivered: a definite failure is retried with backoff when it may be transient; an unknown outcome is never
+ * resent automatically (it could arrive twice); anything left over is a failed turn a person can resend or mark delivered.
+ */
+export declare class ReplyDelivery {
+    private readonly options;
+    private readonly timers;
+    private sweeping;
+    constructor(options: {
+        service: Pick<AgentService, "deliveries" | "settleInterruptedDeliveries" | "setReplyDelivered" | "clockMs">;
+        reply: Reply;
+        log?: (message: string) => void;
+        backoffMs?: number[];
+    });
+    private get backoff();
+    /** Record the reply and make the first attempt. Resolves with the delivery's state after that attempt. */
+    deliver(input: DeliveryInput): Promise<AgentDelivery>;
+    /**
+     * One send attempt. The right to send is claimed first, atomically (`pending`/`failed`/`unknown` -> `sending`), and
+     * the row is what is trusted, not any list the caller read earlier: an attempt that finds the delivery already
+     * claimed, sent or no longer due does nothing and returns it as it is. Overlapping sweeps and timers therefore
+     * cannot send the same reply twice.
+     */
+    private attempt;
+    private later;
+    /** A timer-driven sweep has no caller to report to; a failure (a store closing mid-sweep) must not escape as an unhandled rejection. */
+    private sweepInBackground;
+    /** Retry what is due. Also run on a timer, so retries survive a restart. */
+    sweep(): Promise<number>;
+    /** On start: sends a restart cut off are now unknown; retries that were waiting are picked up by the sweep. */
+    start(intervalMs?: number): void;
+    stop(): void;
+    /** A person resends a reply that failed or whose outcome was unknown. One attempt; no automatic retries after it. */
+    resend(turnId: string): Promise<AgentDelivery>;
+    /** A person confirms the reply did arrive (for example after an unknown outcome). */
+    markDelivered(turnId: string): AgentDelivery;
+}

package/dist/agents/communications/delivery.js

@@ -0,0 +1,142 @@
+import { CHANNEL_ERROR_INFO } from "../../channels/errorInfo.js";
+import { ChannelError } from "../../channels/errors.js";
+import { AgentError } from "../errors.js";
+/** Waits before each automatic retry of a reply that definitely did not go out. */
+export const RETRY_BACKOFF_MS = [5_000, 30_000, 120_000];
+/** Sorts a send failure into "never left" (safe to retry when transient) and "may have arrived" (never resent on its own). */
+export function classifySendFailure(error) {
+    if (error instanceof ChannelError) {
+        const info = CHANNEL_ERROR_INFO[error.code];
+        const unknown = error.code === "CHANNEL_SEND_OUTCOME_UNKNOWN";
+        return { kind: unknown ? "unknown" : "failed", retryable: !unknown && error.retryable, code: error.code, message: `${info.reason}${info.hint ? `. ${info.hint}` : ""}` };
+    }
+    const code = String(error?.code ?? "SEND_FAILED");
+    const message = (error instanceof Error ? error.message : String(error)).slice(0, 300);
+    // Something broke on this side before the send: nothing left, but retrying the same call will not fix it.
+    return { kind: "failed", retryable: false, code, message };
+}
+/**
+ * Gets an agent's reply to the person on the channel they wrote from. The turn only counts as succeeded once the
+ * reply is delivered: a definite failure is retried with backoff when it may be transient; an unknown outcome is never
+ * resent automatically (it could arrive twice); anything left over is a failed turn a person can resend or mark delivered.
+ */
+export class ReplyDelivery {
+    options;
+    timers = new Set();
+    sweeping;
+    constructor(options) {
+        this.options = options;
+    }
+    get backoff() {
+        return this.options.backoffMs ?? RETRY_BACKOFF_MS;
+    }
+    /** Record the reply and make the first attempt. Resolves with the delivery's state after that attempt. */
+    async deliver(input) {
+        const { deliveries } = this.options.service;
+        const existing = deliveries.get(input.turnId);
+        if (existing)
+            return existing;
+        deliveries.create(input);
+        return this.attempt(input.turnId, "first");
+    }
+    /**
+     * One send attempt. The right to send is claimed first, atomically (`pending`/`failed`/`unknown` -> `sending`), and
+     * the row is what is trusted, not any list the caller read earlier: an attempt that finds the delivery already
+     * claimed, sent or no longer due does nothing and returns it as it is. Overlapping sweeps and timers therefore
+     * cannot send the same reply twice.
+     */
+    async attempt(turnId, kind) {
+        const { service } = this.options;
+        const automatic = kind !== "manual";
+        // Written before sending: a crash mid-send leaves "sending", which a restart turns into "unknown".
+        const current = service.deliveries.claim(turnId, kind);
+        if (!current)
+            return service.deliveries.get(turnId);
+        const attempts = current.attempts;
+        try {
+            await this.options.reply(current.connectionId, current.replyTo, current.text, `agent-reply:${current.sessionId}:${turnId}:${attempts}`);
+        }
+        catch (error) {
+            const outcome = classifySendFailure(error);
+            const retry = automatic && outcome.kind === "failed" && outcome.retryable && attempts <= this.backoff.length;
+            const delay = this.backoff[attempts - 1];
+            const next = retry && delay !== undefined ? new Date(service.clockMs() + delay).toISOString() : null;
+            const saved = service.deliveries.patch(turnId, { state: outcome.kind, errorCode: outcome.code, errorMessage: outcome.message, retryable: next !== null, nextAttemptAt: next });
+            // While a retry is coming the turn stays as it was; when none is, the turn failed.
+            if (next === null)
+                service.setReplyDelivered(turnId, false);
+            else if (delay !== undefined)
+                this.later(delay);
+            this.options.log?.(`agent reply ${turnId} ${outcome.kind} (${outcome.code}) after attempt ${attempts}${next ? `, retrying at ${next}` : ""}`);
+            return saved;
+        }
+        const saved = service.deliveries.patch(turnId, { state: "delivered", errorCode: null, errorMessage: null, retryable: false, nextAttemptAt: null });
+        service.setReplyDelivered(turnId, true);
+        return saved;
+    }
+    later(delayMs) {
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            this.sweepInBackground();
+        }, delayMs + 50);
+        timer.unref?.();
+        this.timers.add(timer);
+    }
+    /** A timer-driven sweep has no caller to report to; a failure (a store closing mid-sweep) must not escape as an unhandled rejection. */
+    sweepInBackground() {
+        this.sweep().catch((error) => {
+            this.options.log?.(`agent reply sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /** Retry what is due. Also run on a timer, so retries survive a restart. */
+    async sweep() {
+        const due = this.options.service.deliveries.due();
+        let attempted = 0;
+        for (const delivery of due) {
+            const before = this.options.service.deliveries.get(delivery.turnId);
+            // The list may be stale: another sweep or timer may have taken this one since it was read.
+            if (!before || before.state !== "failed")
+                continue;
+            const after = await this.attempt(delivery.turnId, "retry");
+            if (after.attempts > before.attempts)
+                attempted += 1;
+        }
+        return attempted;
+    }
+    /** On start: sends a restart cut off are now unknown; retries that were waiting are picked up by the sweep. */
+    start(intervalMs = 15_000) {
+        const settled = this.options.service.settleInterruptedDeliveries();
+        if (settled.length > 0)
+            this.options.log?.(`agent replies: ${settled.length} send(s) were cut off by a restart and need a person to resend or mark delivered`);
+        this.sweepInBackground();
+        this.sweeping = setInterval(() => this.sweepInBackground(), intervalMs);
+        this.sweeping.unref?.();
+    }
+    stop() {
+        if (this.sweeping)
+            clearInterval(this.sweeping);
+        for (const timer of this.timers)
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+    /** A person resends a reply that failed or whose outcome was unknown. One attempt; no automatic retries after it. */
+    async resend(turnId) {
+        const current = this.options.service.deliveries.get(turnId);
+        if (!current)
+            throw new AgentError("agent.not_found", "This turn has no reply to send");
+        if (current.state !== "failed" && current.state !== "unknown")
+            throw new AgentError("agent.invalid", `The reply is ${current.state}; only a failed or unconfirmed reply can be resent`);
+        return this.attempt(turnId, "manual");
+    }
+    /** A person confirms the reply did arrive (for example after an unknown outcome). */
+    markDelivered(turnId) {
+        const current = this.options.service.deliveries.get(turnId);
+        if (!current)
+            throw new AgentError("agent.not_found", "This turn has no reply to send");
+        if (current.state === "delivered")
+            return current;
+        const saved = this.options.service.deliveries.patch(turnId, { state: "delivered", errorCode: null, errorMessage: null, retryable: false, nextAttemptAt: null });
+        this.options.service.setReplyDelivered(turnId, true);
+        return saved;
+    }
+}

package/dist/agents/communications/email.d.ts

@@ -0,0 +1,26 @@
+import type { AgentInboundMessage } from "./port.js";
+import type { AgentInboundPort } from "./port.js";
+export type NormalizedAgentEmail = {
+    connectionId: string;
+    messageId: string;
+    threadId: string;
+    from: string;
+    subject: string;
+    text: string;
+};
+export declare function normalizeAgentEmail(input: NormalizedAgentEmail): AgentInboundMessage;
+export type EmailDispatchInput = {
+    email: NormalizedAgentEmail;
+    isBound: boolean;
+    port: AgentInboundPort;
+    projectRoot: string;
+    onTrigger?: (email: NormalizedAgentEmail) => Promise<void>;
+};
+export declare function dispatchAgentEmail(input: EmailDispatchInput): Promise<{
+    routed: "agent";
+    result: Awaited<ReturnType<AgentInboundPort["receive"]>>;
+} | {
+    routed: "trigger";
+} | {
+    routed: "none";
+}>;

package/dist/agents/communications/email.js

@@ -0,0 +1,20 @@
+export function normalizeAgentEmail(input) {
+    return {
+        provider: "email",
+        connectionId: input.connectionId,
+        eventId: `email:${input.messageId}`,
+        threadId: input.threadId,
+        text: input.subject.trim().length > 0 ? `${input.subject}\n\n${input.text}` : input.text,
+        from: input.from,
+    };
+}
+export async function dispatchAgentEmail(input) {
+    if (input.onTrigger) {
+        await input.onTrigger(input.email);
+    }
+    if (!input.isBound) {
+        return { routed: input.onTrigger ? "trigger" : "none" };
+    }
+    const result = await input.port.receive(input.projectRoot, normalizeAgentEmail(input.email));
+    return { routed: "agent", result };
+}