stageflow 0.35.0 → 0.39.0

package/dist/agents/chatTurn.js

@@ -0,0 +1,77 @@
+import { AgentConversation } from "./sessions.js";
+/**
+ * Serializes turns per session (or per agent while a session is being
+ * opened) and keeps a handle on the running turn so it can be stopped.
+ */
+export class AgentChatController {
+    options;
+    turnChains = new Map();
+    activeBySession = new Map();
+    activeByAgent = new Map();
+    /** Sessions whose turn was stopped: their runtime session is released once the turn has wound down. */
+    stopped = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    runExclusive(key, work) {
+        const previous = this.turnChains.get(key) ?? Promise.resolve();
+        const run = previous.then(work, work);
+        this.turnChains.set(key, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    send(input) {
+        return this.runExclusive(input.sessionId ?? `agent:${input.agentId}`, async () => {
+            const chat = new AgentConversation(this.options);
+            if (input.sessionId)
+                this.activeBySession.set(input.sessionId, chat);
+            else
+                this.activeByAgent.set(input.agentId, chat);
+            let openedSessionId;
+            try {
+                return await chat.send({
+                    ...input,
+                    onSessionOpened: (sessionId) => {
+                        openedSessionId = sessionId;
+                        this.activeBySession.set(sessionId, chat);
+                        input.onSessionOpened?.(sessionId);
+                    },
+                });
+            }
+            finally {
+                const sessionId = input.sessionId ?? openedSessionId;
+                if (sessionId && this.stopped.delete(sessionId))
+                    await this.release(sessionId);
+                if (sessionId && this.activeBySession.get(sessionId) === chat)
+                    this.activeBySession.delete(sessionId);
+                if (this.activeByAgent.get(input.agentId) === chat)
+                    this.activeByAgent.delete(input.agentId);
+            }
+        });
+    }
+    /** Stop the running turn on a session. Returns false when nothing was running. */
+    stop(sessionId) {
+        const chat = this.activeBySession.get(sessionId);
+        if (!chat)
+            return false;
+        this.stopped.add(sessionId);
+        chat.stop();
+        return true;
+    }
+    /** Let the runtime drop what it holds for a session (model session, isolated MCP processes). Never throws. */
+    async release(sessionId) {
+        try {
+            await this.options.backend.release?.(sessionId);
+        }
+        catch (error) {
+            this.options.logError?.(`releasing agent session ${sessionId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Stop a turn that is still opening its session (client left before the session id arrived). */
+    stopOpening(agentId) {
+        const chat = this.activeByAgent.get(agentId);
+        if (!chat)
+            return false;
+        chat.stop();
+        return true;
+    }
+}

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