@botcord/daemon 0.1.1

package/dist/gateway/channels/botcord.js

@@ -0,0 +1,510 @@
+import WebSocket from "ws";
+import { BotCordClient, buildHubWebSocketUrl, defaultCredentialsFile, loadStoredCredentials, updateCredentialsToken, } from "@botcord/protocol-core";
+import { sanitizeUntrustedContent } from "./sanitize.js";
+const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
+const KEEPALIVE_INTERVAL = 20_000;
+const MAX_AUTH_FAILURES = 5;
+const SEEN_MESSAGES_CAP = 500;
+const OWNER_CHAT_PREFIX = "rm_oc_";
+const DM_ROOM_PREFIX = "rm_dm_";
+/** Default factory: wrap `loadStoredCredentials` + `new BotCordClient`. */
+function defaultClientFactory(input) {
+    const credFile = input.credentialsPath ?? defaultCredentialsFile(input.agentId);
+    const creds = loadStoredCredentials(credFile);
+    const client = new BotCordClient({
+        hubUrl: input.hubBaseUrl ?? creds.hubUrl,
+        agentId: creds.agentId,
+        keyId: creds.keyId,
+        privateKey: creds.privateKey,
+        token: creds.token,
+        tokenExpiresAt: creds.tokenExpiresAt,
+    });
+    client.onTokenRefresh = (token, expiresAt) => {
+        try {
+            updateCredentialsToken(credFile, token, expiresAt);
+        }
+        catch {
+            // persistence failures are non-fatal — next refresh will retry.
+        }
+    };
+    return client;
+}
+/**
+ * Classify inbound trust tier to decide whether to sanitize text.
+ *
+ * Mirrors `daemon/src/dispatcher.ts#classifyTrust`: owner-chat rooms
+ * (`rm_oc_` prefix) and `dashboard_user_chat` come from the operator and
+ * pass through verbatim; everything else gets sanitized before emit.
+ */
+function isOwnerTrust(msg) {
+    if (msg.room_id?.startsWith(OWNER_CHAT_PREFIX))
+        return true;
+    if (msg.source_type === "dashboard_user_chat")
+        return true;
+    return false;
+}
+/**
+ * Map `InboxMessage` → `GatewayInboundMessage`. Field origins:
+ *
+ *   id                       → msg.hub_msg_id (inbox id, what dispatcher currently keys on)
+ *   channel                  → options.channelId (the adapter's unique instance id)
+ *   accountId                → options.accountId
+ *   conversation.id          → msg.room_id (required; we skip upstream if missing)
+ *   conversation.kind        → "direct" for rm_dm_ and rm_oc_ rooms, else "group"
+ *   conversation.title       → msg.room_name (daemon uses the same field in logs)
+ *   conversation.threadId    → msg.topic_id ?? msg.topic ?? null
+ *   sender.id                → msg.envelope.from
+ *   sender.name              → msg.source_user_name || undefined
+ *   sender.kind              → "user" when trust==owner or source_type=="dashboard_human_room",
+ *                              else "agent". "system" is not produced by daemon today.
+ *   text                     → sanitized msg.text / envelope.payload.text (owner passes verbatim)
+ *   raw                      → the full InboxMessage
+ *   replyTo                  → msg.envelope.reply_to ?? null
+ *   mentioned                → msg.mentioned ?? false
+ *   receivedAt               → Date.now() (InboxMessage has no timestamp field today)
+ *   trace.id                 → msg.hub_msg_id
+ *   trace.streamable         → true only for owner-chat rooms (matches daemon's stream-block rule)
+ */
+function normalizeInbox(msg, options) {
+    const env = msg.envelope;
+    if (!env)
+        return null;
+    if (env.type !== "message")
+        return null;
+    if (!msg.room_id)
+        return null;
+    const rawText = msg.text ?? (typeof env.payload?.text === "string" ? env.payload.text : "");
+    if (typeof rawText !== "string")
+        return null;
+    const ownerTrust = isOwnerTrust(msg);
+    const text = ownerTrust ? rawText : sanitizeUntrustedContent(rawText);
+    const isDm = msg.room_id.startsWith(DM_ROOM_PREFIX);
+    const isOwnerChat = msg.room_id.startsWith(OWNER_CHAT_PREFIX);
+    const senderKind = ownerTrust || msg.source_type === "dashboard_human_room" ? "user" : "agent";
+    const senderName = msg.source_user_name ?? undefined;
+    const threadId = msg.topic_id ?? msg.topic ?? null;
+    const streamable = isOwnerChat;
+    return {
+        id: msg.hub_msg_id,
+        channel: options.channelId,
+        accountId: options.accountId,
+        conversation: {
+            id: msg.room_id,
+            kind: isDm || isOwnerChat ? "direct" : "group",
+            ...(msg.room_name ? { title: msg.room_name } : {}),
+            threadId,
+        },
+        sender: {
+            id: env.from,
+            ...(senderName ? { name: senderName } : {}),
+            kind: senderKind,
+        },
+        text,
+        raw: msg,
+        replyTo: env.reply_to ?? null,
+        mentioned: msg.mentioned ?? false,
+        receivedAt: Date.now(),
+        trace: { id: msg.hub_msg_id, streamable },
+    };
+}
+/**
+ * Construct a BotCord channel adapter.
+ *
+ * `start()` connects to Hub WS, drains `/hub/inbox` on every `inbox_update`,
+ * normalizes messages, and emits envelopes with a `accept()` ack that commits
+ * to Hub. The returned promise stays pending until `abortSignal` fires.
+ */
+export function createBotCordChannel(options) {
+    const channelType = "botcord";
+    const factory = options.clientFactory ?? defaultClientFactory;
+    let clientRef = options.client ?? null;
+    const seenMessages = new Set();
+    let stopCallback = null;
+    let statusSnapshot = {
+        channel: options.id,
+        accountId: options.accountId,
+        running: false,
+        connected: false,
+        reconnectAttempts: 0,
+        lastError: null,
+    };
+    function rememberSeen(hubMsgId) {
+        if (seenMessages.has(hubMsgId))
+            return false;
+        seenMessages.add(hubMsgId);
+        if (seenMessages.size > SEEN_MESSAGES_CAP) {
+            const first = seenMessages.values().next().value;
+            if (first)
+                seenMessages.delete(first);
+        }
+        return true;
+    }
+    function ensureClient() {
+        if (!clientRef) {
+            clientRef = factory({
+                agentId: options.agentId,
+                hubBaseUrl: options.hubBaseUrl,
+                credentialsPath: options.credentialsPath,
+            });
+        }
+        return clientRef;
+    }
+    async function drainInbox(client, emit, log) {
+        const resp = await client.pollInbox({ limit: 50, ack: false });
+        const msgs = resp.messages ?? [];
+        log.info("botcord inbox drained", { count: msgs.length });
+        if (msgs.length === 0)
+            return;
+        for (const msg of msgs) {
+            if (!rememberSeen(msg.hub_msg_id)) {
+                // Already emitted; ack again so Hub stops requeueing.
+                try {
+                    await client.ackMessages([msg.hub_msg_id]);
+                }
+                catch (err) {
+                    log.warn("botcord duplicate ack failed", { err: String(err) });
+                }
+                continue;
+            }
+            const normalized = normalizeInbox(msg, {
+                channelId: options.id,
+                accountId: options.accountId,
+            });
+            if (!normalized) {
+                // Not eligible (wrong type, missing room, etc.) — ack so it drops.
+                try {
+                    await client.ackMessages([msg.hub_msg_id]);
+                }
+                catch (err) {
+                    log.warn("botcord skip ack failed", { err: String(err) });
+                }
+                continue;
+            }
+            const envelope = {
+                message: normalized,
+                ack: {
+                    accept: async () => {
+                        try {
+                            await client.ackMessages([msg.hub_msg_id]);
+                        }
+                        catch (err) {
+                            log.warn("botcord ack failed — relying on seen-cache dedup", {
+                                hubMsgId: msg.hub_msg_id,
+                                err: String(err),
+                            });
+                        }
+                    },
+                },
+            };
+            try {
+                await emit(envelope);
+            }
+            catch (err) {
+                log.error("botcord emit threw", {
+                    hubMsgId: msg.hub_msg_id,
+                    err: String(err),
+                });
+            }
+        }
+    }
+    function startWsLoop(client, ctx) {
+        const { abortSignal, log, emit, setStatus } = ctx;
+        const hubUrl = options.hubBaseUrl ?? client.getHubUrl();
+        const wsCtor = options.webSocketCtor ?? WebSocket;
+        let ws = null;
+        let reconnectTimer = null;
+        let keepaliveTimer = null;
+        let reconnectAttempt = 0;
+        let consecutiveAuthFailures = 0;
+        let running = true;
+        let processing = false;
+        let pendingUpdate = false;
+        let pendingRefresh = null;
+        let resolveLoop = null;
+        const done = new Promise((resolve) => {
+            resolveLoop = resolve;
+        });
+        function clearTimers() {
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            if (keepaliveTimer) {
+                clearInterval(keepaliveTimer);
+                keepaliveTimer = null;
+            }
+        }
+        function markStatus(patch) {
+            statusSnapshot = { ...statusSnapshot, ...patch };
+            setStatus(patch);
+        }
+        async function fireInbox() {
+            if (processing) {
+                pendingUpdate = true;
+                return;
+            }
+            processing = true;
+            try {
+                do {
+                    pendingUpdate = false;
+                    await drainInbox(client, emit, log);
+                } while (pendingUpdate && running);
+            }
+            catch (err) {
+                log.error("botcord inbox drain failed", { err: String(err) });
+            }
+            finally {
+                processing = false;
+            }
+        }
+        function scheduleReconnect() {
+            if (!running)
+                return;
+            const delay = RECONNECT_BACKOFF[Math.min(reconnectAttempt, RECONNECT_BACKOFF.length - 1)];
+            reconnectAttempt += 1;
+            markStatus({
+                connected: false,
+                restartPending: true,
+                reconnectAttempts: reconnectAttempt,
+            });
+            log.info("botcord ws reconnect scheduled", { delayMs: delay, attempt: reconnectAttempt });
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                void connect();
+            }, delay);
+        }
+        async function connect() {
+            if (!running)
+                return;
+            markStatus({ connected: false, restartPending: false });
+            if (pendingRefresh) {
+                try {
+                    await pendingRefresh;
+                }
+                catch {
+                    // already logged by scheduler
+                }
+                finally {
+                    pendingRefresh = null;
+                }
+            }
+            let token;
+            try {
+                token = await client.ensureToken();
+            }
+            catch (err) {
+                log.error("botcord ws token refresh failed", { err: String(err) });
+                markStatus({ lastError: String(err) });
+                scheduleReconnect();
+                return;
+            }
+            const url = buildHubWebSocketUrl(hubUrl);
+            log.info("botcord ws connecting", { url, agentId: options.agentId });
+            try {
+                ws = new wsCtor(url);
+            }
+            catch (err) {
+                log.error("botcord ws construct failed", { err: String(err) });
+                markStatus({ lastError: String(err) });
+                scheduleReconnect();
+                return;
+            }
+            ws.on("open", () => {
+                ws.send(JSON.stringify({ type: "auth", token }));
+            });
+            ws.on("message", (data) => {
+                let msg = null;
+                try {
+                    msg = JSON.parse(String(data));
+                }
+                catch {
+                    return;
+                }
+                if (!msg || typeof msg.type !== "string")
+                    return;
+                if (msg.type === "auth_ok") {
+                    reconnectAttempt = 0;
+                    consecutiveAuthFailures = 0;
+                    markStatus({
+                        running: true,
+                        connected: true,
+                        reconnectAttempts: 0,
+                        lastStartAt: Date.now(),
+                        lastError: null,
+                    });
+                    log.info("botcord ws authenticated", { agentId: msg.agent_id });
+                    void fireInbox();
+                    keepaliveTimer = setInterval(() => {
+                        if (ws && ws.readyState === WebSocket.OPEN) {
+                            try {
+                                ws.send(JSON.stringify({ type: "ping" }));
+                            }
+                            catch {
+                                // ignore
+                            }
+                        }
+                    }, KEEPALIVE_INTERVAL);
+                }
+                else if (msg.type === "inbox_update") {
+                    log.info("botcord ws inbox_update received");
+                    void fireInbox();
+                }
+                else if (msg.type === "heartbeat" || msg.type === "pong") {
+                    // no-op
+                }
+                else if (msg.type === "error" || msg.type === "auth_failed") {
+                    log.warn("botcord ws server error", { msg });
+                }
+            });
+            ws.on("close", (code, reason) => {
+                const reasonStr = reason?.toString() || "";
+                log.info("botcord ws closed", { code, reason: reasonStr });
+                clearTimers();
+                markStatus({ connected: false });
+                if (!running) {
+                    if (resolveLoop) {
+                        const r = resolveLoop;
+                        resolveLoop = null;
+                        r();
+                    }
+                    return;
+                }
+                if (code === 4001) {
+                    consecutiveAuthFailures += 1;
+                    if (consecutiveAuthFailures >= MAX_AUTH_FAILURES) {
+                        log.error("botcord ws auth failing persistently — giving up reconnects", {
+                            failures: consecutiveAuthFailures,
+                        });
+                        running = false;
+                        markStatus({
+                            running: false,
+                            connected: false,
+                            lastStopAt: Date.now(),
+                            lastError: "auth failed repeatedly",
+                        });
+                        if (resolveLoop) {
+                            const r = resolveLoop;
+                            resolveLoop = null;
+                            r();
+                        }
+                        return;
+                    }
+                    pendingRefresh = client
+                        .refreshToken()
+                        .catch((err) => log.error("botcord ws forced refresh failed", { err: String(err) }));
+                }
+                scheduleReconnect();
+            });
+            ws.on("error", (err) => {
+                log.warn("botcord ws error", { err: String(err) });
+                markStatus({ lastError: String(err) });
+            });
+        }
+        function stopLoop() {
+            if (!running)
+                return;
+            running = false;
+            clearTimers();
+            markStatus({
+                running: false,
+                connected: false,
+                lastStopAt: Date.now(),
+            });
+            if (ws) {
+                try {
+                    ws.close();
+                }
+                catch {
+                    // ignore
+                }
+                ws = null;
+            }
+            if (resolveLoop) {
+                const r = resolveLoop;
+                resolveLoop = null;
+                r();
+            }
+        }
+        stopCallback = stopLoop;
+        abortSignal.addEventListener("abort", stopLoop, { once: true });
+        void connect();
+        return done;
+    }
+    const adapter = {
+        id: options.id,
+        type: channelType,
+        async start(ctx) {
+            const client = ensureClient();
+            // Only patch fields owned by the adapter; the manager is the single
+            // writer for `channel` (== adapter.id) and `accountId`.
+            const patch = {
+                running: true,
+                connected: false,
+                reconnectAttempts: 0,
+                lastStartAt: Date.now(),
+                lastError: null,
+            };
+            statusSnapshot = { ...statusSnapshot, ...patch };
+            ctx.setStatus(patch);
+            await startWsLoop(client, ctx);
+        },
+        async stop(_ctx) {
+            if (stopCallback) {
+                stopCallback();
+                stopCallback = null;
+            }
+        },
+        async send(ctx) {
+            const client = ensureClient();
+            const { message } = ctx;
+            const options = {};
+            if (message.replyTo)
+                options.replyTo = message.replyTo;
+            if (message.threadId)
+                options.topic = message.threadId;
+            const resp = await client.sendMessage(message.conversationId, message.text, options);
+            const providerMessageId = (resp && typeof resp.hub_msg_id === "string" && resp.hub_msg_id) ||
+                (resp && typeof resp.message_id === "string"
+                    ? resp.message_id
+                    : null);
+            return { providerMessageId: providerMessageId ?? null };
+        },
+        async streamBlock(ctx) {
+            const client = ensureClient();
+            const hubUrl = options.hubBaseUrl ?? client.getHubUrl();
+            try {
+                const token = await client.ensureToken();
+                const block = ctx.block;
+                const resp = await fetch(`${hubUrl}/hub/stream-block`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${token}`,
+                    },
+                    body: JSON.stringify({
+                        trace_id: ctx.traceId,
+                        seq: typeof block?.seq === "number" ? block.seq : 0,
+                        block: ctx.block,
+                    }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!resp.ok && resp.status !== 204) {
+                    const body = await resp.text().catch(() => "");
+                    ctx.log.warn("botcord stream-block non-ok", {
+                        status: resp.status,
+                        body: body.slice(0, 200),
+                    });
+                }
+            }
+            catch (err) {
+                ctx.log.warn("botcord stream-block failed", { err: String(err) });
+            }
+        },
+        status() {
+            return { ...statusSnapshot };
+        },
+    };
+    return adapter;
+}
+// Re-export the normalizer for tests that want to exercise it directly.
+export { normalizeInbox as __normalizeInboxForTests };

package/dist/gateway/channels/index.d.ts

@@ -0,0 +1,2 @@
+export { createBotCordChannel } from "./botcord.js";
+export type { BotCordChannelClient, BotCordChannelOptions, BotCordClientFactory, } from "./botcord.js";

package/dist/gateway/channels/index.js

@@ -0,0 +1 @@
+export { createBotCordChannel } from "./botcord.js";

package/dist/gateway/channels/sanitize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sanitize untrusted inbound content before handing it off to a local runtime.
+ *
+ * Copied from `packages/daemon/src/sanitize.ts` so the gateway channel adapter
+ * does not depend back on the daemon package. Keep these two files in sync —
+ * any new structural marker added in one place should be mirrored in the other.
+ *
+ * Neutralizes:
+ *   - BotCord structural markers the channel itself emits (so peers can't forge them).
+ *   - Common LLM prompt-injection patterns (<system>, [INST], <<SYS>>, <|im_start|>, etc.).
+ *   - Wrapper XML tags the channel uses to frame inbound content
+ *     (<agent-message>, <human-message>, <room-rule>).
+ */
+export declare function sanitizeUntrustedContent(text: string): string;
+/**
+ * Sanitize a sender label so it's safe to embed inside
+ * `<agent-message sender="...">`. Must not contain newlines, structural
+ * markers, or characters that could break the XML attribute boundary.
+ */
+export declare function sanitizeSenderName(name: string): string;

package/dist/gateway/channels/sanitize.js

@@ -0,0 +1,56 @@
+/**
+ * Sanitize untrusted inbound content before handing it off to a local runtime.
+ *
+ * Copied from `packages/daemon/src/sanitize.ts` so the gateway channel adapter
+ * does not depend back on the daemon package. Keep these two files in sync —
+ * any new structural marker added in one place should be mirrored in the other.
+ *
+ * Neutralizes:
+ *   - BotCord structural markers the channel itself emits (so peers can't forge them).
+ *   - Common LLM prompt-injection patterns (<system>, [INST], <<SYS>>, <|im_start|>, etc.).
+ *   - Wrapper XML tags the channel uses to frame inbound content
+ *     (<agent-message>, <human-message>, <room-rule>).
+ */
+export function sanitizeUntrustedContent(text) {
+    let s = text;
+    s = s.replace(/<\/?a[\s]*g[\s]*e[\s]*n[\s]*t[\s]*-[\s]*m[\s]*e[\s]*s[\s]*s[\s]*a[\s]*g[\s]*e[\s\S]*?>/gi, "[⚠ stripped: agent-message tag]");
+    s = s.replace(/<\/?h[\s]*u[\s]*m[\s]*a[\s]*n[\s]*-[\s]*m[\s]*e[\s]*s[\s]*s[\s]*a[\s]*g[\s]*e[\s\S]*?>/gi, "[⚠ stripped: human-message tag]");
+    s = s.replace(/<\/?r[\s]*o[\s]*o[\s]*m[\s]*-[\s]*r[\s]*u[\s]*l[\s]*e[\s\S]*?>/gi, "[⚠ stripped: room-rule tag]");
+    return s
+        .split(/\r?\n/)
+        .map((line) => {
+        let l = line;
+        l = l.replace(/^\[(BotCord (?:Message|Notification))\]/i, "[⚠ fake: $1]");
+        l = l.replace(/^\[Room Rule\]/i, "[⚠ fake: Room Rule]");
+        l = l.replace(/^\[房间规则\]/i, "[⚠ fake: 房间规则]");
+        l = l.replace(/^\[系统提示\]/i, "[⚠ fake: 系统提示]");
+        l = l.replace(/^\[BotCord\s+([^\]\r\n]+)\]/i, (_m, label) => {
+            const head = String(label).split(":")[0].trim() || String(label).trim();
+            return `[⚠ fake: BotCord ${head}]`;
+        });
+        l = l.replace(/^\[(System|SYSTEM|Assistant|ASSISTANT|User|USER)\]/, "[⚠ fake: $1]");
+        l = l.replace(/<\/?\s*system(?:-reminder)?\s*>/gi, "[⚠ stripped: system tag]");
+        l = l.replace(/<\|im_start\|>/gi, "[⚠ stripped: im_start]");
+        l = l.replace(/<\|im_end\|>/gi, "[⚠ stripped: im_end]");
+        l = l.replace(/\[\/?INST\]/gi, "[⚠ stripped: INST]");
+        l = l.replace(/<<\/?SYS>>/gi, "[⚠ stripped: SYS]");
+        l = l.replace(/<\s*\/?\|(?:system|user|assistant)\|?\s*>/gi, "[⚠ stripped: role tag]");
+        return l;
+    })
+        .join("\n");
+}
+/**
+ * Sanitize a sender label so it's safe to embed inside
+ * `<agent-message sender="...">`. Must not contain newlines, structural
+ * markers, or characters that could break the XML attribute boundary.
+ */
+export function sanitizeSenderName(name) {
+    return name
+        .replace(/[\n\r]/g, " ")
+        .replace(/\[/g, "⟦")
+        .replace(/\]/g, "⟧")
+        .replace(/"/g, "'")
+        .replace(/</g, "＜")
+        .replace(/>/g, "＞")
+        .slice(0, 100);
+}

package/dist/gateway/dispatcher.d.ts

@@ -0,0 +1,73 @@
+import type { GatewayLogger } from "./log.js";
+import { type SessionStore } from "./session-store.js";
+import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayRoute, InboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
+/** Factory signature for building a runtime adapter at turn dispatch time. */
+export type RuntimeFactory = (runtimeId: string, extraArgs?: string[]) => RuntimeAdapter;
+/** Constructor options for `Dispatcher`. */
+export interface DispatcherOptions {
+    config: GatewayConfig;
+    channels: Map<string, ChannelAdapter>;
+    runtime: RuntimeFactory;
+    sessionStore: SessionStore;
+    log: GatewayLogger;
+    turnTimeoutMs?: number;
+    /**
+     * Live reference to the Gateway's managed-route map. Dispatcher reads
+     * `values()` on every `resolveRoute` call so hot-add/remove take effect
+     * without restart.
+     */
+    managedRoutes?: Map<string, GatewayRoute>;
+    /**
+     * Optional hook producing a `systemContext` string for each turn. Result is
+     * forwarded to the runtime as `RuntimeRunOptions.systemContext`. Errors are
+     * swallowed and logged — they never abort the turn.
+     */
+    buildSystemContext?: SystemContextBuilder;
+    /**
+     * Optional side-effect hook invoked after ack, before the turn runs.
+     * Intended for bookkeeping (e.g. activity tracking). Errors are logged
+     * and suppressed so the turn is never cancelled by observer failure.
+     */
+    onInbound?: InboundObserver;
+    /**
+     * Optional composer that wraps `message.text` with channel-specific
+     * metadata (sender label, room header, reply hints…) before it is handed
+     * to the runtime. Skipped if it throws — the raw trimmed text is used as
+     * a fallback so a buggy composer cannot drop turns.
+     */
+    composeUserTurn?: UserTurnBuilder;
+}
+/**
+ * Gateway dispatcher: consumes `GatewayInboundEnvelope` and drives a runtime
+ * turn per message, respecting queue mode, trust level, streaming, and
+ * session persistence rules from the plan (§7/§9/§10/§11/§12/§13).
+ *
+ * Deliberate deviation from daemon: this core does NOT wrap inbound text in
+ * BotCord-style XML envelopes for untrusted content. The channel adapter is
+ * responsible for any channel-specific sanitization; the dispatcher passes
+ * `message.text` through to the runtime as-is (plan §15).
+ */
+export declare class Dispatcher {
+    private readonly config;
+    private readonly channels;
+    private readonly runtimeFactory;
+    private readonly sessionStore;
+    private readonly log;
+    private readonly turnTimeoutMs;
+    private readonly buildSystemContext?;
+    private readonly onInbound?;
+    private readonly composeUserTurn?;
+    private readonly managedRoutes?;
+    private readonly queues;
+    constructor(opts: DispatcherOptions);
+    /** Consume one inbound envelope, ack it once ownership is decided, then run its turn. */
+    handle(envelope: GatewayInboundEnvelope): Promise<void>;
+    /** Snapshot of currently running turns keyed by queue key. */
+    turns(): Record<string, TurnStatusSnapshot>;
+    private safeAck;
+    private getQueue;
+    private runCancelPrevious;
+    private runSerial;
+    private runTurn;
+    private sendReply;
+}