stageflow 0.36.0 → 0.40.0

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;

package/dist/agents/communications/photon.js

@@ -0,0 +1,38 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export function verifyPhotonSignature(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 parsePhotonInbound(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.conversation_id === "string"
+        ? record.conversation_id
+        : typeof record.sender === "string"
+            ? record.sender
+            : undefined;
+    const text = typeof record.text === "string" ? record.text.trim() : "";
+    if (eventId === undefined || threadId === undefined || text.length === 0) {
+        return { ok: false, code: "agent.invalid" };
+    }
+    return {
+        ok: true,
+        message: {
+            provider: "photon",
+            connectionId: config.connectionId,
+            eventId: `photon:${eventId}`,
+            threadId,
+            text,
+            ...(typeof record.sender === "string" ? { from: record.sender } : {}),
+        },
+    };
+}

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

@@ -0,0 +1,27 @@
+import type { AgentCommunicationProvider } from "../../config/loadAgent.js";
+export type { AgentCommunicationProvider };
+export type AgentInboundMessage = {
+    provider: AgentCommunicationProvider;
+    connectionId: string;
+    eventId: string;
+    threadId: string;
+    text: string;
+    from?: string;
+    /** Where a reply goes on the provider (channel id, chat id, or address). */
+    replyTo?: string;
+};
+/** The session a message belongs to. Failures (unbound, disabled) throw AgentError. */
+export type AgentInboundResult = {
+    agentId: string;
+    sessionId: string;
+    duplicate: boolean;
+};
+export type AgentInboundPort = {
+    receive(projectRoot: string, message: AgentInboundMessage): Promise<AgentInboundResult>;
+};
+export declare function agentThreadKey(input: {
+    provider: AgentCommunicationProvider;
+    connectionId: string;
+    threadId: string;
+}): string;
+export declare function inboundDedupeKey(message: Pick<AgentInboundMessage, "provider" | "eventId">): string;

package/dist/agents/communications/port.js

@@ -0,0 +1,6 @@
+export function agentThreadKey(input) {
+    return `${input.provider}\0${input.connectionId}\0${input.threadId}`;
+}
+export function inboundDedupeKey(message) {
+    return `${message.provider}\0${message.eventId}`;
+}

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

@@ -0,0 +1,28 @@
+import type { AgentInboundMessage } from "./port.js";
+export type SlackInboundConfig = {
+    connectionId: string;
+    signingSecret: string;
+};
+export type SlackInboundHeaders = {
+    signature?: string;
+    requestTimestamp?: string;
+};
+export type SlackParseResult = {
+    ok: true;
+    message: AgentInboundMessage;
+} | {
+    ok: true;
+    ignored: true;
+    reason: "bot_message";
+} | {
+    ok: false;
+    code: "agent.signature_invalid" | "agent.invalid";
+};
+export declare function verifySlackSignature(config: SlackInboundConfig, headers: SlackInboundHeaders, rawBody: string, nowMs?: number): {
+    ok: true;
+} | {
+    ok: false;
+    code: "agent.signature_invalid";
+};
+export declare function parseSlackInbound(config: SlackInboundConfig, payload: unknown): SlackParseResult;
+export declare function slackThreadKey(config: SlackInboundConfig, threadId: string): string;

package/dist/agents/communications/slack.js

@@ -0,0 +1,65 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { agentThreadKey } from "./port.js";
+export function verifySlackSignature(config, headers, rawBody, nowMs = Date.now()) {
+    const signature = headers.signature;
+    const timestamp = headers.requestTimestamp;
+    if (signature === undefined || timestamp === undefined) {
+        return { ok: false, code: "agent.signature_invalid" };
+    }
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts) || Math.abs(nowMs - ts * 1000) > 5 * 60_000) {
+        return { ok: false, code: "agent.signature_invalid" };
+    }
+    const base = `v0:${timestamp}:${rawBody}`;
+    const expected = `v0=${createHmac("sha256", config.signingSecret).update(base).digest("hex")}`;
+    const left = Buffer.from(expected);
+    const right = Buffer.from(signature);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        return { ok: false, code: "agent.signature_invalid" };
+    }
+    return { ok: true };
+}
+export function parseSlackInbound(config, payload) {
+    if (typeof payload !== "object" || payload === null)
+        return { ok: false, code: "agent.invalid" };
+    const event = payload.event;
+    if (typeof event !== "object" || event === null)
+        return { ok: false, code: "agent.invalid" };
+    const record = event;
+    if (record.bot_id !== undefined || record.subtype === "bot_message") {
+        return { ok: true, ignored: true, reason: "bot_message" };
+    }
+    const text = typeof record.text === "string" ? record.text.trim() : "";
+    if (text.length === 0)
+        return { ok: false, code: "agent.invalid" };
+    const channel = typeof record.channel === "string" ? record.channel : undefined;
+    const thread = typeof record.thread_ts === "string"
+        ? record.thread_ts
+        : typeof record.ts === "string"
+            ? record.ts
+            : undefined;
+    const eventId = typeof record.event_ts === "string"
+        ? record.event_ts
+        : typeof record.ts === "string"
+            ? record.ts
+            : undefined;
+    if (channel === undefined || thread === undefined || eventId === undefined) {
+        return { ok: false, code: "agent.invalid" };
+    }
+    const user = typeof record.user === "string" ? record.user : undefined;
+    return {
+        ok: true,
+        message: {
+            provider: "slack",
+            connectionId: config.connectionId,
+            eventId: `slack:${eventId}`,
+            threadId: thread,
+            text,
+            replyTo: channel,
+            ...(user !== undefined ? { from: user } : {}),
+        },
+    };
+}
+export function slackThreadKey(config, threadId) {
+    return agentThreadKey({ provider: "slack", connectionId: config.connectionId, threadId });
+}

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

@@ -0,0 +1,36 @@
+import type { AgentService } from "../service.js";
+import type { ListenerConnection } from "./inbound.js";
+import type { ChannelListener, ListenerDeps, ListenerState } from "./listener.js";
+import type { AgentInboundMessage } from "./port.js";
+export type ListenerFactory = (connection: ListenerConnection, deps: ListenerDeps) => ChannelListener | undefined;
+/** Listeners the Host can hold open itself. Other providers (Slack, Telegram) stay on webhooks. */
+export declare const DEFAULT_FACTORIES: Record<string, ListenerFactory>;
+/**
+ * Keeps one listener per connection that an enabled agent answers on: starts it when the agent is enabled or
+ * linked, restarts it when the connection's settings change, stops it when no enabled agent uses it.
+ * `reconcile` is cheap and idempotent, so it runs on every agent change and on a timer.
+ */
+export declare class ChannelSupervisor {
+    private readonly options;
+    private readonly running;
+    private chain;
+    private timer;
+    private stopped;
+    private readonly warned;
+    constructor(options: {
+        service: Pick<AgentService, "list" | "onChange">;
+        projectRoot: string;
+        resolve: (connectionId: string) => ListenerConnection | undefined;
+        deliver: (message: AgentInboundMessage) => Promise<unknown>;
+        log: (message: string) => void;
+        factories?: Record<string, ListenerFactory>;
+        intervalMs?: number;
+    });
+    /** Start following agents: listeners for what is linked now, and again after every change. */
+    start(): void;
+    reconcile(): Promise<void>;
+    private run;
+    /** The state of the listener on a connection, or undefined when none runs (webhook providers, no enabled agent). */
+    status(connectionId: string): ListenerState | undefined;
+    stop(): Promise<void>;
+}