stageflow 0.35.0 → 0.39.0

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

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

@@ -0,0 +1,13 @@
+/**
+ * What a connection really talks to. Two connections can point at the same AgentMail inbox or the same Photon
+ * project; one stream and one agent may serve such a pair, so they share an identity. Other providers are
+ * identified by the connection itself.
+ */
+export declare function channelIdentity(connection: {
+    id: string;
+    provider: string;
+    config?: unknown;
+    credential?: {
+        secrets: Record<string, string>;
+    } | undefined;
+}): string;

package/dist/agents/communications/identity.js

@@ -0,0 +1,18 @@
+/**
+ * What a connection really talks to. Two connections can point at the same AgentMail inbox or the same Photon
+ * project; one stream and one agent may serve such a pair, so they share an identity. Other providers are
+ * identified by the connection itself.
+ */
+export function channelIdentity(connection) {
+    if (connection.provider === "agentmail") {
+        const config = (connection.config ?? {});
+        if (config.inbox)
+            return `agentmail:${config.region ?? "us"}:${config.inbox.trim().toLowerCase()}`;
+    }
+    if (connection.provider === "imessage") {
+        const project = connection.credential?.secrets.projectId;
+        if (project)
+            return `imessage:${project}`;
+    }
+    return `${connection.provider}:${connection.id}`;
+}

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

@@ -0,0 +1,41 @@
+import { type ChannelListener, type ListenerDeps } from "./listener.js";
+import type { AgentInboundMessage } from "./port.js";
+/** What this listener reads of a Spectrum message. */
+export type SpectrumInbound = {
+    id: string;
+    direction?: string;
+    content?: {
+        type?: string;
+        text?: string;
+    };
+    sender?: {
+        id?: string;
+    } | undefined;
+    space?: {
+        id?: string;
+        type?: string;
+    } | undefined;
+};
+export type SpectrumStream = {
+    messages: AsyncIterable<[unknown, SpectrumInbound]>;
+    stop(): Promise<void>;
+};
+export type IMessageTransport = {
+    open(): Promise<SpectrumStream>;
+};
+export type IMessageListenerConfig = {
+    connectionId: string;
+};
+/** The text and sender of a message the agent should answer, or undefined for everything else. */
+export declare function toInbound(connectionId: string, message: SpectrumInbound): AgentInboundMessage | undefined;
+/**
+ * Holds a Spectrum (Photon) stream open for an iMessage line. One conversation per sender, so with an
+ * always-on agent each person has one session that carries on after a failure. A dropped stream is
+ * reopened with backoff.
+ */
+export declare function createIMessageListener(config: IMessageListenerConfig, transport: IMessageTransport, deps: ListenerDeps): ChannelListener;
+/** The real transport over the Spectrum SDK; the packages load on first use. */
+export declare function sdkIMessageTransport(credentials: {
+    projectId: string;
+    projectSecret: string;
+}, importer?: (specifier: string) => Promise<any>): IMessageTransport;

package/dist/agents/communications/imessageListener.js

@@ -0,0 +1,92 @@
+import { normalizeSender } from "./allowlist.js";
+import { abortableSleep, reconnectDelay, StateTracker } from "./listener.js";
+/** The text and sender of a message the agent should answer, or undefined for everything else. */
+export function toInbound(connectionId, message) {
+    if (message.direction !== undefined && message.direction !== "inbound")
+        return undefined;
+    if (message.content?.type !== "text")
+        return undefined;
+    const text = message.content.text?.trim() ?? "";
+    const sender = message.sender?.id;
+    if (text.length === 0 || !sender)
+        return undefined;
+    // Group chats are out of scope: replying to one person's handle would answer the wrong audience.
+    if (message.space?.type === "group")
+        return undefined;
+    const from = normalizeSender(sender);
+    return { provider: "imessage", connectionId, eventId: `imessage:${message.id}`, threadId: from, text, from, replyTo: from };
+}
+/**
+ * Holds a Spectrum (Photon) stream open for an iMessage line. One conversation per sender, so with an
+ * always-on agent each person has one session that carries on after a failure. A dropped stream is
+ * reopened with backoff.
+ */
+export function createIMessageListener(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 stream;
+    async function session() {
+        stream = await transport.open();
+        tracker.set("connected");
+        for await (const [, message] of stream.messages) {
+            if (abort.signal.aborted)
+                return;
+            const inbound = toInbound(config.connectionId, message);
+            if (!inbound)
+                continue;
+            tracker.received();
+            await deps.onMessage(inbound).catch((error) => deps.log(`imessage ${config.connectionId}: delivery failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        if (!abort.signal.aborted)
+            throw new Error("stream ended");
+    }
+    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(`imessage ${config.connectionId}: ${message}; retrying`);
+                attempt += 1;
+                await sleep(reconnectDelay(attempt - 1), abort.signal);
+            }
+            finally {
+                await stream?.stop().catch(() => undefined);
+                stream = undefined;
+            }
+        }
+        tracker.set("stopped");
+    }
+    return {
+        async start() {
+            loop = run();
+            await Promise.resolve();
+        },
+        async stop() {
+            abort.abort();
+            await stream?.stop().catch(() => undefined);
+            await loop;
+        },
+        state: () => tracker.get(),
+    };
+}
+/** The real transport over the Spectrum SDK; the packages load on first use. */
+export function sdkIMessageTransport(credentials, importer = (s) => import(s)) {
+    return {
+        async open() {
+            const core = await importer("@spectrum-ts/core");
+            const module = await importer("@spectrum-ts/imessage");
+            const app = await core.Spectrum({ projectId: credentials.projectId, projectSecret: credentials.projectSecret, providers: [module.imessage.config()] });
+            return { messages: app.messages, stop: () => app.stop() };
+        },
+    };
+}

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

@@ -0,0 +1,63 @@
+import type { ContactInfo } from "../../channels/types.js";
+import { ReplyDelivery } from "./delivery.js";
+import type { AgentChatController } from "../chatTurn.js";
+import type { AgentService } from "../service.js";
+import type { AgentInboundMessage } from "./port.js";
+/** What the router needs from the Host's connections: who a connection is, and how to answer on it. */
+export type InboundConnections = {
+    find(connectionId: string): {
+        provider: string;
+        secret: string | undefined;
+    } | undefined;
+    reply(connectionId: string, to: string, text: string, operationKey: string): Promise<void>;
+    /** How people reach the connection (the number to text), when the provider can tell. */
+    contact?(connectionId: string): Promise<ContactInfo | undefined>;
+    /** The connection with its secrets, for providers the Host listens on itself (a stream instead of a webhook). */
+    resolve?(connectionId: string): ListenerConnection | undefined;
+};
+export type ListenerConnection = {
+    id: string;
+    provider: string;
+    config: unknown;
+    secrets: Record<string, string>;
+    credential?: {
+        secrets: Record<string, string>;
+    } | undefined;
+};
+export type InboundResponse = {
+    status: number;
+    body?: unknown;
+};
+type Headers = Record<string, string | undefined>;
+/**
+ * Receives provider webhooks for agents. A request is accepted only when the connection has an
+ * inbound secret and the provider's signature verifies; everything else is refused without
+ * saying why. Replies go back on the same connection to the sender, once per turn.
+ */
+export declare class AgentInboundRouter {
+    private readonly options;
+    private readonly limiter;
+    /** Sends each reply back and keeps track of whether it got through. */
+    readonly delivery: ReplyDelivery;
+    constructor(options: {
+        service: AgentService;
+        chat: Pick<AgentChatController, "send">;
+        connections: InboundConnections;
+        projectRoot: string;
+        logError?: (message: string) => void;
+        senderLimitPerMinute?: number;
+        delivery?: ReplyDelivery;
+    });
+    handle(connectionId: string, headers: Headers, rawBody: string): Promise<InboundResponse>;
+    /**
+     * A message from any source (a webhook or a stream the Host listens on): enforce the sender allow-list and
+     * rate limit, route it to its session and answer on the same connection.
+     */
+    deliver(message: AgentInboundMessage): Promise<InboundResponse>;
+    private verify;
+    private parse;
+    /** After a restart: retry the turns it cut off on always-on iMessage agents, answering the same sender once. */
+    resumeInterrupted(): Promise<number>;
+    private converse;
+}
+export {};

package/dist/agents/communications/inbound.js

@@ -0,0 +1,143 @@
+import { isAgentError } from "../errors.js";
+import { ReplyDelivery } from "./delivery.js";
+import { SlidingWindowLimiter } from "../webChat/rateLimit.js";
+import { parseAgentMailInbound, verifyAgentMailSignature } from "./agentmail.js";
+import { parseSlackInbound, verifySlackSignature } from "./slack.js";
+import { parseTelegramInbound, verifyTelegramSecret } from "./telegram.js";
+const MAX_REPLY_CHARS = 3500;
+/** Messages one sender may send an agent per minute before the rest are ignored. */
+const SENDER_LIMIT_PER_MINUTE = 20;
+/**
+ * Receives provider webhooks for agents. A request is accepted only when the connection has an
+ * inbound secret and the provider's signature verifies; everything else is refused without
+ * saying why. Replies go back on the same connection to the sender, once per turn.
+ */
+export class AgentInboundRouter {
+    options;
+    limiter = new SlidingWindowLimiter();
+    /** Sends each reply back and keeps track of whether it got through. */
+    delivery;
+    constructor(options) {
+        this.options = options;
+        this.delivery =
+            options.delivery ??
+                new ReplyDelivery({
+                    service: options.service,
+                    reply: (connectionId, to, text, key) => options.connections.reply(connectionId, to, text, key),
+                    ...(options.logError ? { log: options.logError } : {}),
+                });
+    }
+    async handle(connectionId, headers, rawBody) {
+        const connection = this.options.connections.find(connectionId);
+        if (!connection || connection.secret === undefined)
+            return { status: 404 };
+        const verified = this.verify(connection.provider, connection.secret, connectionId, headers, rawBody);
+        if (!verified)
+            return { status: 401 };
+        let payload;
+        try {
+            payload = JSON.parse(rawBody);
+        }
+        catch {
+            return { status: 400 };
+        }
+        if (connection.provider === "slack" && payload?.type === "url_verification") {
+            return { status: 200, body: { challenge: payload.challenge } };
+        }
+        const parsed = this.parse(connection.provider, connectionId, connection.secret, headers, payload);
+        if (!parsed)
+            return { status: 400 };
+        if ("ignored" in parsed)
+            return { status: 200, body: { ignored: true } };
+        return this.deliver(parsed.message);
+    }
+    /**
+     * A message from any source (a webhook or a stream the Host listens on): enforce the sender allow-list and
+     * rate limit, route it to its session and answer on the same connection.
+     */
+    async deliver(message) {
+        const limit = this.limiter.take(`${message.connectionId}\0${message.from ?? ""}`, this.options.senderLimitPerMinute ?? SENDER_LIMIT_PER_MINUTE, Date.now());
+        if (!limit.ok) {
+            this.options.logError?.(`agent inbound ${message.provider}: sender over the rate limit, message ignored`);
+            return { status: 200, body: { ignored: true } };
+        }
+        let routed;
+        try {
+            routed = await this.options.service.receive(this.options.projectRoot, message);
+        }
+        catch (error) {
+            // An unbound, disabled or not-allowed sender looks the same as success to the sender; nothing is retried.
+            if (isAgentError(error))
+                return { status: 200, body: { ignored: true } };
+            throw error;
+        }
+        if (routed.duplicate)
+            return { status: 200, body: { duplicate: true } };
+        void this.converse(routed, message);
+        return { status: 200, body: { ok: true } };
+    }
+    verify(provider, secret, connectionId, headers, rawBody) {
+        if (provider === "slack") {
+            return verifySlackSignature({ connectionId, signingSecret: secret }, { ...(headers["x-slack-signature"] ? { signature: headers["x-slack-signature"] } : {}), ...(headers["x-slack-request-timestamp"] ? { requestTimestamp: headers["x-slack-request-timestamp"] } : {}) }, rawBody).ok;
+        }
+        if (provider === "telegram")
+            return verifyTelegramSecret({ connectionId, secretToken: secret }, headers["x-telegram-bot-api-secret-token"]).ok;
+        if (provider === "agentmail")
+            return verifyAgentMailSignature({ connectionId, webhookSecret: secret }, headers["x-agentmail-signature"], rawBody).ok;
+        return false;
+    }
+    parse(provider, connectionId, secret, _headers, payload) {
+        const result = provider === "slack"
+            ? parseSlackInbound({ connectionId, signingSecret: secret }, payload)
+            : provider === "telegram"
+                ? parseTelegramInbound({ connectionId, secretToken: secret }, payload)
+                : parseAgentMailInbound({ connectionId, webhookSecret: secret }, payload);
+        if (!result.ok)
+            return undefined;
+        if ("ignored" in result)
+            return { ignored: true };
+        return { message: result.message };
+    }
+    /** After a restart: retry the turns it cut off on always-on iMessage agents, answering the same sender once. */
+    async resumeInterrupted() {
+        const turns = await this.options.service.resumableTurns(this.options.projectRoot);
+        for (const turn of turns) {
+            const message = { provider: turn.provider, connectionId: turn.connectionId, eventId: `resume:${turn.turnId}`, threadId: turn.threadId, text: turn.text, from: turn.from, replyTo: turn.from };
+            void this.converse({ agentId: turn.agentId, sessionId: turn.sessionId }, message, turn.turnId);
+        }
+        return turns.length;
+    }
+    async converse(routed, message, resumeTurnId) {
+        const { chat, connections, logError } = this.options;
+        try {
+            const detail = await chat.send({
+                projectRoot: this.options.projectRoot,
+                agentId: routed.agentId,
+                sessionId: routed.sessionId,
+                text: message.text,
+                author: message.from ?? null,
+                source: message.provider,
+                ...(resumeTurnId ? { resumeTurnId } : {}),
+            });
+            const turn = detail.turns.at(-1);
+            const reply = [...detail.messages].reverse().find((m) => m.role === "assistant" && m.turnId === turn?.id);
+            if (!turn || !reply || !message.replyTo)
+                return;
+            // The turn only counts as succeeded once this reaches the person; failures are retried or left for a person.
+            await this.delivery.deliver({
+                turnId: turn.id,
+                sessionId: routed.sessionId,
+                connectionId: message.connectionId,
+                provider: message.provider,
+                replyTo: message.replyTo,
+                text: reply.text.slice(0, MAX_REPLY_CHARS),
+            });
+        }
+        catch (error) {
+            if (isAgentError(error) && error.code === "agent.limit_reached" && message.replyTo) {
+                await connections.reply(message.connectionId, message.replyTo, error.message, `agent-limit:${routed.sessionId}:${message.eventId}`).catch(() => undefined);
+            }
+            logError?.(`agent inbound ${message.provider} turn failed: ${isAgentError(error) ? `${error.code}${error.message !== error.code ? ` (${error.message})` : ""}` : error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { AgentInboundMessage } from "./port.js";
+/** A stream the Host holds open to a provider so messages arrive without a public URL. */
+export type ChannelListener = {
+    /** Resolves once the first connection attempt has been made; it keeps itself connected until `stop`. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    state(): ListenerState;
+};
+export type ListenerState = {
+    status: "starting" | "connected" | "reconnecting" | "failed" | "stopped";
+    since: string;
+    /** Last failure, never a secret. */
+    error?: string;
+    /** Messages handed to the agents since the listener started. */
+    received: number;
+};
+export type ListenerDeps = {
+    onMessage(message: AgentInboundMessage): Promise<void>;
+    log(message: string): void;
+    now?: () => number;
+    /** Test seam: waits between reconnect attempts. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+};
+export declare const RECONNECT_MIN_MS = 2000;
+export declare const RECONNECT_MAX_MS = 60000;
+export declare function reconnectDelay(attempt: number): number;
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;
+/** Tracks a listener's state for the console. */
+export declare class StateTracker {
+    private readonly now;
+    private current;
+    constructor(now?: () => number);
+    set(status: ListenerState["status"], error?: string): void;
+    received(): void;
+    get(): ListenerState;
+}

package/dist/agents/communications/listener.js

@@ -0,0 +1,38 @@
+export const RECONNECT_MIN_MS = 2_000;
+export const RECONNECT_MAX_MS = 60_000;
+export function reconnectDelay(attempt) {
+    return Math.min(RECONNECT_MAX_MS, RECONNECT_MIN_MS * 2 ** Math.min(attempt, 10));
+}
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+/** Tracks a listener's state for the console. */
+export class StateTracker {
+    now;
+    current;
+    constructor(now = Date.now) {
+        this.now = now;
+        this.current = { status: "starting", since: new Date(now()).toISOString(), received: 0 };
+    }
+    set(status, error) {
+        this.current = { ...this.current, status, since: new Date(this.now()).toISOString(), ...(error !== undefined ? { error } : {}) };
+        if (error === undefined && status !== "failed" && status !== "reconnecting")
+            delete this.current.error;
+    }
+    received() {
+        this.current = { ...this.current, received: this.current.received + 1 };
+    }
+    get() {
+        return { ...this.current };
+    }
+}

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

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