@botcord/daemon 0.2.5 → 0.2.8

package/dist/gateway/dispatcher.js

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { resolveRoute } from "./router.js";
 import { sessionKey } from "./session-store.js";
+import { truncateTextField, } from "./transcript.js";
 const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * Owner-chat room prefix. Reply-text gating: only rooms with this prefix get
@@ -16,6 +18,25 @@ const MAX_BATCH_BUFFER_ENTRIES = 40;
  * runtime prompt stays bounded even if the channel-side batch was huge.
  */
 const MAX_BATCH_BUFFER_CHARS = 16000;
+/**
+ * Reason carried on `AbortController.abort()` when a cancel-previous wave
+ * is taking over the slot. Distinguishing this from a timeout abort lets
+ * `runTurn`'s finalize know NOT to write a `turn_error` — the supersede
+ * path already wrote a `dropped` record for the old turnId before the abort.
+ */
+class TurnSupersededError extends Error {
+    supersededBy;
+    constructor(supersededBy) {
+        super("turn superseded");
+        this.supersededBy = supersededBy;
+        this.name = "TurnSupersededError";
+    }
+}
+const NOOP_TRANSCRIPT = {
+    enabled: false,
+    rootDir: "",
+    write: () => { },
+};
 /**
  * Gateway dispatcher: consumes `GatewayInboundEnvelope` and drives a runtime
  * turn per message, respecting queue mode, trust level, streaming, and
@@ -38,6 +59,9 @@ export class Dispatcher {
     onOutbound;
     composeUserTurn;
     managedRoutes;
+    attentionGate;
+    resolveHubUrl;
+    transcript;
     queues = new Map();
     constructor(opts) {
         this.config = opts.config;
@@ -51,18 +75,28 @@ export class Dispatcher {
         this.onOutbound = opts.onOutbound;
         this.composeUserTurn = opts.composeUserTurn;
         this.managedRoutes = opts.managedRoutes;
+        this.attentionGate = opts.attentionGate;
+        this.resolveHubUrl = opts.resolveHubUrl;
+        this.transcript = opts.transcript ?? NOOP_TRANSCRIPT;
     }
     /** Consume one inbound envelope, ack it once ownership is decided, then run its turn. */
     async handle(envelope) {
         const msg = envelope.message;
-        // Skip rule: empty/whitespace text.
-        const rawText = typeof msg.text === "string" ? msg.text.trim() : "";
-        if (!rawText) {
-            this.log.debug("dispatcher skip: empty text", { messageId: msg.id });
+        // ---- Pre-skip branches: NEVER write a transcript record (design §3.2).
+        // Order matters: unknown channel → own echo → empty text. Each ack's the
+        // envelope (when applicable) and returns silently with only a debug/warn
+        // line in the daemon log.
+        // Pre-skip: unknown channel — configuration error, not a conversation event.
+        const channel = this.channels.get(msg.channel);
+        if (!channel) {
+            this.log.warn("dispatcher: unknown channel for outbound reply", {
+                channel: msg.channel,
+                messageId: msg.id,
+            });
             await this.safeAck(envelope);
             return;
         }
-        // Skip rule: echo from the agent itself (own agent output looped back).
+        // Pre-skip: echo from the agent itself (own agent output looped back).
         // Owner/human messages in dashboard rooms share the agent's id as sender.id
         // but carry sender.kind === "user", so we only skip when kind === "agent".
         if (msg.sender.id === msg.accountId && msg.sender.kind === "agent") {
@@ -70,6 +104,16 @@ export class Dispatcher {
             await this.safeAck(envelope);
             return;
         }
+        // Pre-skip: empty/whitespace text.
+        const rawText = typeof msg.text === "string" ? msg.text.trim() : "";
+        if (!rawText) {
+            this.log.debug("dispatcher skip: empty text", { messageId: msg.id });
+            await this.safeAck(envelope);
+            return;
+        }
+        // From here on, the inbound is a real conversation event — generate a
+        // turnId and write the inbound transcript record.
+        const turnId = randomUUID();
         const managed = this.managedRoutes ? Array.from(this.managedRoutes.values()) : undefined;
         const route = resolveRoute(msg, this.config, managed);
         const mode = resolveQueueMode(route, msg.conversation.kind);
@@ -80,6 +124,7 @@ export class Dispatcher {
         // the full coalesced batch instead of any single arrival), so calling
         // the composer here would just be redundant work.
         let text = rawText;
+        let composeFailedError;
         if (mode === "cancel-previous" && this.composeUserTurn) {
             try {
                 const composed = this.composeUserTurn(msg);
@@ -88,14 +133,18 @@ export class Dispatcher {
                 }
             }
             catch (err) {
+                composeFailedError = err instanceof Error ? err.message : String(err);
                 this.log.warn("dispatcher: composeUserTurn threw — using raw text", {
                     messageId: msg.id,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: composeFailedError,
                 });
             }
         }
         // Ack immediately: once the dispatcher has a route + queue key, ownership is decided.
         await this.safeAck(envelope);
+        // Inbound transcript record — always before observers / gates so we have a
+        // grounded turnId for any downstream attention_skipped / dropped / etc.
+        this.emitInbound(turnId, msg);
         // Notify the optional observer (activity tracking, metrics, etc.) as soon
         // as the dispatcher owns the message. Errors must not abort the turn.
         if (this.onInbound) {
@@ -109,19 +158,58 @@ export class Dispatcher {
                 });
             }
         }
-        const channel = this.channels.get(msg.channel);
-        if (!channel) {
-            this.log.warn("dispatcher: unknown channel for outbound reply", {
-                channel: msg.channel,
-                messageId: msg.id,
+        // Attention gate (PR3, design §4.2). Inserted AFTER `onInbound` so the
+        // working-memory append + activity tracking still see the message — only
+        // the runtime turn is suppressed. Errors are treated as wake (fail-open)
+        // so a buggy gate cannot silence the agent.
+        if (this.attentionGate) {
+            let wake = true;
+            try {
+                const result = this.attentionGate(msg);
+                wake = result instanceof Promise ? await result : result;
+            }
+            catch (err) {
+                this.log.warn("dispatcher: attentionGate threw — waking", {
+                    messageId: msg.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                wake = true;
+            }
+            if (!wake) {
+                this.log.debug("dispatcher skip turn: attention policy", {
+                    messageId: msg.id,
+                    accountId: msg.accountId,
+                    conversationId: msg.conversation.id,
+                });
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "attention_skipped",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    reason: "attention_gate_false",
+                });
+                return;
+            }
+        }
+        if (composeFailedError) {
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "compose_failed",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                error: composeFailedError,
+                fallback: "raw_text",
             });
-            return;
         }
         if (mode === "cancel-previous") {
-            await this.runCancelPrevious(queueKey, route, text, msg, channel);
+            await this.runCancelPrevious(queueKey, route, text, msg, channel, turnId);
         }
         else {
-            await this.runSerial(queueKey, route, text, msg, channel);
+            await this.runSerial(queueKey, route, text, msg, channel, turnId);
         }
     }
     /** Snapshot of currently running turns keyed by queue key. */
@@ -163,7 +251,7 @@ export class Dispatcher {
         }
         return q;
     }
-    async runCancelPrevious(queueKey, route, text, msg, channel) {
+    async runCancelPrevious(queueKey, route, text, msg, channel, turnId) {
         const q = this.getQueue(queueKey);
         // Bump the generation on every arrival. Older arrivals still awaiting
         // the prior turn's teardown will observe `myGen !== q.cancelGen` when
@@ -173,7 +261,19 @@ export class Dispatcher {
         const prev = q.current;
         if (prev) {
             this.log.info("dispatcher: cancelling previous turn", { queueKey });
-            prev.controller.abort();
+            // Record the supersede BEFORE aborting so the prev turn's finalize sees
+            // the abort reason (TurnSupersededError) and skips writing turn_error.
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId: prev.turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                reason: "queue_cancel_previous",
+                supersededBy: turnId,
+            });
+            prev.controller.abort(new TurnSupersededError(turnId));
             // Wait for it to finish cleanup (it won't reply, won't persist).
             await prev.done.catch(() => undefined);
         }
@@ -182,9 +282,22 @@ export class Dispatcher {
         // drop out silently — the newest turn is the only one that should run.
         if (myGen !== q.cancelGen) {
             this.log.info("dispatcher: cancel-previous superseded", { queueKey });
+            // We didn't run the turn; emit dropped so the caller's inbound has a
+            // matching path record. supersededBy is unknown at this layer (newer
+            // arrival owns its own bump) — leave null.
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                reason: "queue_cancel_previous",
+                supersededBy: null,
+            });
             return;
         }
-        await this.runTurn(queueKey, route, text, msg, channel);
+        await this.runTurn(queueKey, route, text, msg, channel, turnId, []);
     }
     /**
      * Serial mode with coalesce-on-drain semantics:
@@ -204,9 +317,9 @@ export class Dispatcher {
      * merged message so the runtime sees a single coherent prompt covering all
      * coalesced messages.
      */
-    async runSerial(queueKey, route, _text, msg, channel) {
+    async runSerial(queueKey, route, _text, msg, channel, turnId) {
         const q = this.getQueue(queueKey);
-        q.serialBuffer.push({ route, msg, channel });
+        q.serialBuffer.push({ route, msg, channel, turnId });
         while (q.serialBuffer.length > MAX_BATCH_BUFFER_ENTRIES) {
             const dropped = q.serialBuffer.shift();
             this.log.warn("dispatcher: serial buffer overflow — dropped oldest entry", {
@@ -214,6 +327,16 @@ export class Dispatcher {
                 droppedMessageId: dropped.msg.id,
                 bufferCap: MAX_BATCH_BUFFER_ENTRIES,
             });
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId: dropped.turnId,
+                agentId: dropped.msg.accountId,
+                roomId: dropped.msg.conversation.id,
+                topicId: dropped.msg.conversation.threadId ?? null,
+                reason: "queue_overflow",
+                supersededBy: null,
+            });
         }
         if (q.serialWorkerActive)
             return;
@@ -224,7 +347,25 @@ export class Dispatcher {
                 const merged = this.mergeSerialBuffer(drained, queueKey);
                 if (!merged)
                     continue;
-                await this.runTurn(queueKey, merged.route, merged.text, merged.msg, merged.channel);
+                // Drained entries other than the winner get a `batch_merged` dropped
+                // record now (winner is always the last entry — see mergeSerialBuffer).
+                if (drained.length > 1) {
+                    for (let i = 0; i < drained.length - 1; i++) {
+                        const lost = drained[i];
+                        this.transcript.write({
+                            ts: nowIso(),
+                            kind: "dropped",
+                            turnId: lost.turnId,
+                            agentId: lost.msg.accountId,
+                            roomId: lost.msg.conversation.id,
+                            topicId: lost.msg.conversation.threadId ?? null,
+                            reason: "batch_merged",
+                            supersededBy: merged.turnId,
+                        });
+                    }
+                }
+                const mergedFromTurnIds = drained.length > 1 ? drained.slice(0, -1).map((e) => e.turnId) : [];
+                await this.runTurn(queueKey, merged.route, merged.text, merged.msg, merged.channel, merged.turnId, mergedFromTurnIds);
             }
         }
         finally {
@@ -250,6 +391,7 @@ export class Dispatcher {
                 text: this.recomposeUserTurn(only.msg),
                 msg: only.msg,
                 channel: only.channel,
+                turnId: only.turnId,
             };
         }
         // Flatten: each entry's raw may already be a BatchedInboxRaw with
@@ -301,6 +443,7 @@ export class Dispatcher {
             text: this.recomposeUserTurn(mergedMsg),
             msg: mergedMsg,
             channel: latest.channel,
+            turnId: latest.turnId,
         };
     }
     /**
@@ -326,7 +469,7 @@ export class Dispatcher {
         }
         return rawText;
     }
-    async runTurn(queueKey, route, text, msg, channel) {
+    async runTurn(queueKey, route, text, msg, channel, turnId, mergedFromTurnIds) {
         const q = this.getQueue(queueKey);
         const controller = new AbortController();
         const startedAt = Date.now();
@@ -343,8 +486,35 @@ export class Dispatcher {
         const done = new Promise((res) => {
             resolveDone = res;
         });
-        const slot = { controller, timedOut: false, snapshot, done };
+        const slot = {
+            turnId,
+            controller,
+            timedOut: false,
+            snapshot,
+            done,
+            dispatchedAt: startedAt,
+            blocks: [],
+        };
         q.current = slot;
+        // Dispatched record — marks "this turn entered runtime".
+        {
+            const composedField = truncateTextField(text);
+            const dispatched = {
+                ts: nowIso(),
+                kind: "dispatched",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                composedText: composedField.text,
+                runtime: route.runtime,
+            };
+            if (mergedFromTurnIds.length > 0)
+                dispatched.mergedFromTurnIds = mergedFromTurnIds;
+            if (composedField.truncated)
+                dispatched.truncated = { composedText: true };
+            this.transcript.write(dispatched);
+        }
         // Hard-cap turn with a timeout.
         const timer = setTimeout(() => {
             slot.timedOut = true;
@@ -370,8 +540,20 @@ export class Dispatcher {
         const streamable = msg.trace?.streamable === true;
         const traceId = msg.trace?.id;
         const canStream = streamable && typeof traceId === "string" && typeof channel.streamBlock === "function";
+        const recordBlock = (block) => {
+            const summary = { type: block.kind };
+            const raw = block.raw;
+            if (raw && typeof raw === "object") {
+                if (typeof raw.text === "string")
+                    summary.chars = raw.text.length;
+                if (typeof raw.name === "string")
+                    summary.name = raw.name;
+            }
+            slot.blocks.push(summary);
+        };
         const onBlock = canStream
             ? (block) => {
+                recordBlock(block);
                 // Fire-and-forget: stream errors must not break the turn.
                 channel
                     .streamBlock({
@@ -417,11 +599,13 @@ export class Dispatcher {
                     sessionId,
                     cwd: route.cwd,
                     accountId: msg.accountId,
+                    hubUrl: this.resolveHubUrl?.(msg.accountId),
                     extraArgs: route.extraArgs,
                     signal: controller.signal,
                     trustLevel,
                     systemContext,
                     onBlock,
+                    gateway: route.gateway,
                 });
             }
             catch (err) {
@@ -437,6 +621,11 @@ export class Dispatcher {
             // until after the reply lets the new arrival trip our abort signal, and
             // this check then drops us silently. Timed-out turns still fall through
             // to send their error reply.
+            //
+            // Note on transcript: the supersede path already wrote the `dropped`
+            // record from `runCancelPrevious` BEFORE aborting, so we MUST NOT also
+            // emit a `turn_error` here — that would violate the "exactly one
+            // terminal record per turnId" invariant.
             if (controller.signal.aborted && !slot.timedOut) {
                 return;
             }
@@ -458,6 +647,17 @@ export class Dispatcher {
             // own loop-risk accounting downstream.
             const isOwnerChat = isOwnerChatRoom(msg);
             if (slot.timedOut) {
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "turn_error",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    phase: "timeout",
+                    error: `runtime timeout after ${this.turnTimeoutMs}ms`,
+                    durationMs: Date.now() - slot.dispatchedAt,
+                });
                 if (isOwnerChat) {
                     await this.sendReply(channel, {
                         channel: msg.channel,
@@ -479,19 +679,30 @@ export class Dispatcher {
                 return;
             }
             if (threw) {
+                const errMsg = threw instanceof Error ? threw.message : String(threw);
                 this.log.error("dispatcher: runtime threw", {
                     queueKey,
                     runtime: route.runtime,
-                    error: threw instanceof Error ? threw.message : String(threw),
+                    error: errMsg,
+                });
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "turn_error",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    phase: "runtime",
+                    error: errMsg,
+                    durationMs: Date.now() - slot.dispatchedAt,
                 });
                 if (isOwnerChat) {
-                    const shortMsg = threw instanceof Error ? threw.message : String(threw);
                     await this.sendReply(channel, {
                         channel: msg.channel,
                         accountId: msg.accountId,
                         conversationId: msg.conversation.id,
                         threadId: msg.conversation.threadId ?? null,
-                        text: `⚠️ Runtime error: ${truncate(shortMsg, 500)}`,
+                        text: `⚠️ Runtime error: ${truncate(errMsg, 500)}`,
                         replyTo: msg.id,
                         traceId: msg.trace?.id ?? null,
                     });
@@ -561,8 +772,22 @@ export class Dispatcher {
                 }
             }
             const replyText = (result.text || "").trim();
-            if (!replyText)
+            const finalTextField = truncateTextField(result.text || "");
+            if (!replyText) {
+                this.emitOutbound({
+                    turnId,
+                    msg,
+                    runtime: route.runtime,
+                    runtimeSessionId: result.newSessionId || null,
+                    startedAt: slot.dispatchedAt,
+                    costUsd: result.costUsd,
+                    finalText: finalTextField,
+                    deliveryStatus: "empty_text",
+                    deliveryReason: null,
+                    blocks: slot.blocks,
+                });
                 return;
+            }
             if (!isOwnerChat) {
                 // Non-owner-chat rooms: result.text never goes out. The agent is
                 // expected to have used the `botcord_send` tool / `botcord send` CLI
@@ -573,6 +798,18 @@ export class Dispatcher {
                     conversationId: msg.conversation.id,
                     replyTextLen: replyText.length,
                 });
+                this.emitOutbound({
+                    turnId,
+                    msg,
+                    runtime: route.runtime,
+                    runtimeSessionId: result.newSessionId || null,
+                    startedAt: slot.dispatchedAt,
+                    costUsd: result.costUsd,
+                    finalText: finalTextField,
+                    deliveryStatus: "gated_non_owner_chat",
+                    deliveryReason: null,
+                    blocks: slot.blocks,
+                });
                 return;
             }
             // One last abort check immediately before the send. Narrows the window
@@ -581,7 +818,7 @@ export class Dispatcher {
             if (controller.signal.aborted && !slot.timedOut) {
                 return;
             }
-            await this.sendReply(channel, {
+            const sendResult = await this.sendReply(channel, {
                 channel: msg.channel,
                 accountId: msg.accountId,
                 conversationId: msg.conversation.id,
@@ -590,6 +827,18 @@ export class Dispatcher {
                 replyTo: msg.id,
                 traceId: msg.trace?.id ?? null,
             });
+            this.emitOutbound({
+                turnId,
+                msg,
+                runtime: route.runtime,
+                runtimeSessionId: result.newSessionId || null,
+                startedAt: slot.dispatchedAt,
+                costUsd: result.costUsd,
+                finalText: finalTextField,
+                deliveryStatus: sendResult.ok ? "delivered" : "send_failed",
+                deliveryReason: sendResult.ok ? null : sendResult.error,
+                blocks: slot.blocks,
+            });
         }
         finally {
             // Clear slot ownership AFTER the reply has been sent (or skipped).
@@ -607,12 +856,13 @@ export class Dispatcher {
             await channel.send({ message: outbound, log: this.log });
         }
         catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
             this.log.warn("dispatcher: channel.send failed", {
                 channel: outbound.channel,
                 conversationId: outbound.conversationId,
-                error: err instanceof Error ? err.message : String(err),
+                error,
             });
-            return;
+            return { ok: false, error };
         }
         if (this.onOutbound) {
             try {
@@ -625,7 +875,65 @@ export class Dispatcher {
                 });
             }
         }
+        return { ok: true };
     }
+    emitInbound(turnId, msg) {
+        if (!this.transcript.enabled)
+            return;
+        const rawText = typeof msg.text === "string" ? msg.text : "";
+        const tField = truncateTextField(rawText);
+        const raw = msg.raw;
+        const batch = raw && typeof raw === "object" && Array.isArray(raw.batch)
+            ? raw.batch.length
+            : undefined;
+        const rec = {
+            ts: nowIso(),
+            kind: "inbound",
+            turnId,
+            agentId: msg.accountId,
+            roomId: msg.conversation.id,
+            topicId: msg.conversation.threadId ?? null,
+            messageId: msg.id,
+            sender: { id: msg.sender.id, kind: msg.sender.kind, ...(msg.sender.name ? { name: msg.sender.name } : {}) },
+            text: tField.text,
+        };
+        if (batch !== undefined && batch > 1)
+            rec.rawBatchEntries = batch;
+        if (msg.trace?.id) {
+            rec.trace = { id: msg.trace.id, ...(msg.trace.streamable ? { streamable: true } : {}) };
+        }
+        if (tField.truncated)
+            rec.truncated = { text: true };
+        this.transcript.write(rec);
+    }
+    emitOutbound(args) {
+        if (!this.transcript.enabled)
+            return;
+        const rec = {
+            ts: nowIso(),
+            kind: "outbound",
+            turnId: args.turnId,
+            agentId: args.msg.accountId,
+            roomId: args.msg.conversation.id,
+            topicId: args.msg.conversation.threadId ?? null,
+            runtime: args.runtime,
+            runtimeSessionId: args.runtimeSessionId,
+            durationMs: Date.now() - args.startedAt,
+            finalText: args.finalText.text,
+            deliveryStatus: args.deliveryStatus,
+            deliveryReason: args.deliveryReason,
+        };
+        if (typeof args.costUsd === "number")
+            rec.costUsd = args.costUsd;
+        if (args.blocks.length > 0)
+            rec.blocks = args.blocks;
+        if (args.finalText.truncated)
+            rec.truncated = { finalText: true };
+        this.transcript.write(rec);
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
 }
 function buildQueueKey(msg) {
     const thread = msg.conversation.threadId ?? "";

package/dist/gateway/gateway.d.ts

@@ -1,7 +1,8 @@
 import { type ChannelBackoffOptions } from "./channel-manager.js";
 import { type RuntimeFactory } from "./dispatcher.js";
 import { type GatewayLogger } from "./log.js";
-import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
+import { type TranscriptWriter } from "./transcript.js";
+import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayInboundMessage, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
 /** Constructor options for `Gateway`. */
 export interface GatewayBootOptions {
     config: GatewayConfig;
@@ -35,6 +36,33 @@ export interface GatewayBootOptions {
      * bookkeeping like loop-risk tracking.
      */
     onOutbound?: OutboundObserver;
+    /**
+     * Optional attention gate (PR3, design §4.2). Forwarded to the dispatcher
+     * verbatim — see {@link Dispatcher} for semantics. Returning `false` skips
+     * the runtime turn while preserving ack + onInbound side effects.
+     */
+    attentionGate?: (message: GatewayInboundMessage) => Promise<boolean> | boolean;
+    /**
+     * Resolve the per-agent hub URL for an inbound message. Forwarded to the
+     * dispatcher as `RuntimeRunOptions.hubUrl` so spawned CLI subprocesses
+     * (`BOTCORD_HUB`) target the correct hub for the owning agent.
+     */
+    resolveHubUrl?: (accountId: string) => string | undefined;
+    /**
+     * Persistent NDJSON transcript writer (design §3 / §6). Optional — when
+     * omitted the dispatcher uses a noop writer. Pass `transcriptEnabled` plus
+     * `transcriptRootDir` to let the gateway construct one for you.
+     */
+    transcript?: TranscriptWriter;
+    /**
+     * Tri-state convenience: if `transcript` is not provided, the gateway
+     * constructs a writer using this flag plus `transcriptRootDir`. Use
+     * {@link resolveTranscriptEnabled} to combine `BOTCORD_TRANSCRIPT` env with
+     * the persistent daemon-config flag.
+     */
+    transcriptEnabled?: boolean;
+    /** Root directory for transcript files. Defaults to `~/.botcord/agents`. */
+    transcriptRootDir?: string;
 }
 /**
  * Top-level gateway bootstrap. Wires `ChannelManager` → `Dispatcher` →

package/dist/gateway/gateway.js

@@ -3,6 +3,7 @@ import { Dispatcher } from "./dispatcher.js";
 import { consoleLogger } from "./log.js";
 import { createRuntime } from "./runtimes/registry.js";
 import { DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS, SessionStore } from "./session-store.js";
+import { createTranscriptWriter, } from "./transcript.js";
 /** Default runtime factory: delegates to the built-in registry; ignores extraArgs at construction. */
 const defaultRuntimeFactory = (runtimeId) => createRuntime(runtimeId);
 /**
@@ -53,6 +54,12 @@ export class Gateway {
             maxEntryAgeMs: opts.sessionStoreMaxEntryAgeMs ?? DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS,
         });
         const runtimeFactory = opts.createRuntime ?? defaultRuntimeFactory;
+        const transcript = opts.transcript
+            ?? createTranscriptWriter({
+                log: this.log,
+                enabled: opts.transcriptEnabled === true,
+                rootDir: opts.transcriptRootDir,
+            });
         this.dispatcher = new Dispatcher({
             config: this.config,
             channels: this.channelMap,
@@ -65,6 +72,9 @@ export class Gateway {
             composeUserTurn: opts.composeUserTurn,
             onOutbound: opts.onOutbound,
             managedRoutes: this.managedRoutes,
+            attentionGate: opts.attentionGate,
+            resolveHubUrl: opts.resolveHubUrl,
+            transcript,
         });
         this.channelManager = new ChannelManager({
             config: this.config,