@botcord/daemon 0.2.4 → 0.2.6

package/dist/daemon-config-map.js

@@ -1,6 +1,69 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import { resolveAgentIds } from "./config.js";
 import { agentWorkspaceDir } from "./agent-workspace.js";
 import { log as daemonLog } from "./log.js";
+function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return path.join(homedir(), p.slice(2));
+    return p;
+}
+/** Resolve one profile's token (inline > tokenFile). Failures are swallowed
+ *  into `tokenError`; `resolvedToken` is left undefined. Logs at warn for ops
+ *  visibility. */
+export function prepareGatewayProfile(p) {
+    const prepared = { ...p };
+    if (p.token && p.token.length > 0) {
+        prepared.resolvedToken = p.token;
+    }
+    else if (p.tokenFile && p.tokenFile.length > 0) {
+        try {
+            prepared.resolvedToken = readFileSync(expandHome(p.tokenFile), "utf8").trim();
+        }
+        catch (err) {
+            prepared.tokenError = err?.message ?? String(err);
+            daemonLog.warn("daemon.config.openclaw.tokenfile_failed", {
+                gateway: p.name,
+                tokenFile: p.tokenFile,
+                error: prepared.tokenError,
+            });
+        }
+    }
+    return prepared;
+}
+/** Build a name → prepared-profile map for a config's gateway registry. */
+export function prepareGatewayProfiles(profiles) {
+    const out = new Map();
+    if (!profiles)
+        return out;
+    for (const p of profiles)
+        out.set(p.name, prepareGatewayProfile(p));
+    return out;
+}
+function resolveGateway(profiles, gatewayName, agentOverride, where) {
+    if (!gatewayName) {
+        daemonLog.warn("daemon.config.openclaw.missing_gateway", { where });
+        return undefined;
+    }
+    const profile = profiles.get(gatewayName);
+    if (!profile) {
+        daemonLog.warn("daemon.config.openclaw.unknown_gateway", { where, gateway: gatewayName });
+        return undefined;
+    }
+    const resolved = {
+        name: profile.name,
+        url: profile.url,
+    };
+    if (profile.resolvedToken)
+        resolved.token = profile.resolvedToken;
+    const agent = agentOverride ?? profile.defaultAgent;
+    if (agent)
+        resolved.openclawAgent = agent;
+    return resolved;
+}
 /**
  * Historical channel id used when the daemon bound a single agent. Kept as a
  * named export for any downstream reader that still references it; no new
@@ -29,7 +92,7 @@ function mapTrustLevel(level) {
  * legacy alias and its canonical field are present, the canonical field
  * wins and a warning is logged.
  */
-function mapRoute(r) {
+function mapRoute(r, profiles, index) {
     const match = {};
     if (r.match.channel)
         match.channel = r.match.channel;
@@ -66,13 +129,17 @@ function mapRoute(r) {
     if (typeof r.match.mentioned === "boolean")
         match.mentioned = r.match.mentioned;
     const rawTrust = r.trustLevel;
-    return {
+    const out = {
         match,
         runtime: r.adapter,
         cwd: r.cwd,
         extraArgs: r.extraArgs,
         trustLevel: mapTrustLevel(rawTrust),
     };
+    if (r.adapter === "openclaw-acp") {
+        out.gateway = resolveGateway(profiles, r.gateway, r.openclawAgent, `routes[${index}]`);
+    }
+    return out;
 }
 /**
  * Convert the daemon's on-disk config into a gateway runtime config. Only
@@ -100,6 +167,7 @@ export function toGatewayConfig(cfg, opts = {}) {
     }));
     // DaemonConfig's typed surface doesn't carry `trustLevel`, but we read it
     // defensively so future config extensions can propagate without a shape bump.
+    const profiles = prepareGatewayProfiles(cfg.openclawGateways);
     const rawDefaultTrust = cfg.defaultRoute
         .trustLevel;
     const defaultRoute = {
@@ -110,14 +178,18 @@ export function toGatewayConfig(cfg, opts = {}) {
         // (direct → cancel-previous, group → serial).
         trustLevel: mapTrustLevel(rawDefaultTrust),
     };
-    const routes = (cfg.routes ?? []).map(mapRoute);
+    if (cfg.defaultRoute.adapter === "openclaw-acp") {
+        const dr = cfg.defaultRoute;
+        defaultRoute.gateway = resolveGateway(profiles, dr.gateway, dr.openclawAgent, "defaultRoute");
+    }
+    const routes = (cfg.routes ?? []).map((r, i) => mapRoute(r, profiles, i));
     // Synthesize a per-agent route for every bound agent and hand it to the
     // gateway via the managed-routes bucket (plan §10.1). User-authored
     // `cfg.routes[]` stay untouched. Match priority (see router.ts):
     // `routes[] with explicit accountId → managedRoutes → other routes[] →
     // defaultRoute`. Broad prefix/kind rules no longer clobber the agent's
     // chosen runtime — only routes that name the agent by `accountId` do.
-    const managedMap = buildManagedRoutes(agentIds, opts.agentRuntimes ?? {}, defaultRoute);
+    const managedMap = buildManagedRoutes(agentIds, opts.agentRuntimes ?? {}, defaultRoute, profiles);
     return {
         channels,
         defaultRoute,
@@ -140,15 +212,40 @@ export function toGatewayConfig(cfg, opts = {}) {
  * Exported so `reload_config` and `provisionAgent` hot-add can share the
  * same synthesis logic (plan §10.5).
  */
-export function buildManagedRoutes(agentIds, agentRuntimes, defaultRoute) {
+export function buildManagedRoutes(agentIds, agentRuntimes, defaultRoute, openclawProfiles) {
     const out = new Map();
+    // Lazy-build profile map when caller didn't pass one (legacy callers).
+    const profiles = openclawProfiles ?? new Map();
     for (const agentId of agentIds) {
         const meta = agentRuntimes[agentId] ?? {};
-        out.set(agentId, {
+        const runtime = meta.runtime ?? defaultRoute.runtime;
+        const route = {
             match: { accountId: agentId },
-            runtime: meta.runtime ?? defaultRoute.runtime,
+            runtime,
             cwd: meta.cwd || agentWorkspaceDir(agentId),
-        });
+            // Inherit defaultRoute's extraArgs so synthesized per-agent routes
+            // pick up operator-wide flags (e.g. `--permission-mode bypassPermissions`)
+            // that would otherwise apply only to agents listed in `cfg.routes[]`.
+            ...(defaultRoute.extraArgs ? { extraArgs: defaultRoute.extraArgs.slice() } : {}),
+        };
+        if (runtime === "openclaw-acp") {
+            // Per RFC §3.4: prefer credentials, fall back to defaultRoute.gateway.
+            const gatewayName = meta.openclawGateway ?? defaultRoute.gateway?.name;
+            const agentOverride = meta.openclawAgent;
+            const resolved = gatewayName
+                ? resolveGateway(profiles, gatewayName, agentOverride, `managedRoute[${agentId}]`)
+                : defaultRoute.gateway;
+            if (!resolved) {
+                // No usable gateway — skip the managed route so defaultRoute can take over.
+                daemonLog.warn("daemon.config.openclaw.managed_route_skipped", {
+                    agentId,
+                    gatewayName,
+                });
+                continue;
+            }
+            route.gateway = resolved;
+        }
+        out.set(agentId, route);
     }
     return out;
 }

package/dist/daemon.d.ts

@@ -108,6 +108,8 @@ export interface BootBackfillResult {
     agentRuntimes: Record<string, {
         runtime?: string;
         cwd?: string;
+        openclawGateway?: string;
+        openclawAgent?: string;
     }>;
 }
 /**

package/dist/daemon.js

@@ -1,5 +1,5 @@
-import { CONTROL_FRAME_TYPES } from "@botcord/protocol-core";
-import { Gateway, createBotCordChannel, sanitizeUntrustedContent, } from "./gateway/index.js";
+import { CONTROL_FRAME_TYPES, shouldWake, } from "@botcord/protocol-core";
+import { Gateway, createBotCordChannel, resolveTranscriptEnabled, sanitizeUntrustedContent, } from "./gateway/index.js";
 import { ActivityTracker } from "./activity-tracker.js";
 import { SESSIONS_PATH, SNAPSHOT_PATH } from "./config.js";
 import { resolveBootAgents } from "./agent-discovery.js";
@@ -15,6 +15,8 @@ import { createRoomContextFetcher } from "./room-context-fetcher.js";
 import { buildLoopRiskPrompt, loopRiskSessionKey, recordInboundText as recordLoopRiskInbound, recordOutboundText as recordLoopRiskOutbound, } from "./loop-risk.js";
 import { composeBotCordUserTurn } from "./turn-text.js";
 import { UserAuthManager } from "./user-auth.js";
+import { PolicyResolver } from "./gateway/policy-resolver.js";
+import { scanMention } from "./mention-scan.js";
 /**
  * Matches the 10-minute turn timeout the legacy daemon dispatcher used, so
  * long-running CLI turns behave the same way under the gateway core.
@@ -124,6 +126,17 @@ export async function startDaemon(opts) {
     const agentIds = boot.agents.map((a) => a.agentId);
     const { credentialPathByAgentId, agentRuntimes } = backfillBootAgents(boot.agents, { logger });
     const gwConfig = toGatewayConfig(opts.config, { agentIds, agentRuntimes });
+    // Per-agent hub URL — read from each credential file at boot. Used to
+    // populate `BOTCORD_HUB` for runtime CLI subprocesses so the bundled
+    // `botcord` CLI talks to the same hub the agent is registered against,
+    // even when a single daemon hosts agents from different hubs.
+    const hubUrlByAgentId = new Map();
+    for (const a of boot.agents) {
+        if (a.hubUrl)
+            hubUrlByAgentId.set(a.agentId, a.hubUrl);
+    }
+    const fallbackHubUrl = opts.hubBaseUrl;
+    const resolveHubUrl = (accountId) => hubUrlByAgentId.get(accountId) ?? fallbackHubUrl;
     // ActivityTracker lives at the daemon layer (not the gateway core). We
     // expose it to the gateway via (a) the `buildSystemContext` hook so the
     // cross-room digest reflects current activity, and (b) the `onInbound`
@@ -206,6 +219,35 @@ export async function startDaemon(opts) {
             text: out.text,
         });
     };
+    // Per-agent attention policy cache (PR3, design §4.2 / §5). Seeded from
+    // the optional `defaultAttention` / `attentionKeywords` carried by
+    // `provision_agent`, refreshed in-place by the `policy_updated` control
+    // frame. PR2 will plug per-room overrides into `fetchEffective`; PR3
+    // leaves it absent so the resolver collapses to per-agent state.
+    const policyResolver = new PolicyResolver({
+        fetchGlobal: async (_agentId) => undefined,
+    });
+    // Display-name lookup for the mention text-fallback. Populated from boot
+    // credentials; multi-agent daemons can reuse the same map via accountId.
+    const displayNameByAgent = new Map();
+    for (const a of boot.agents) {
+        if (a.displayName)
+            displayNameByAgent.set(a.agentId, a.displayName);
+    }
+    // Attention gate: compose `messages.mentioned` (sender-supplied — distrust)
+    // with a local `@<display_name>` / `@<agent_id>` text scan, resolve the
+    // effective policy, then defer to the protocol-core `shouldWake` decision.
+    const attentionGate = async (msg) => {
+        const policy = await policyResolver.resolve(msg.accountId, msg.conversation.id);
+        const localMention = scanMention(msg.text, {
+            agentId: msg.accountId,
+            displayName: displayNameByAgent.get(msg.accountId),
+        });
+        return shouldWake(policy, {
+            mentioned: msg.mentioned === true || localMention,
+            text: msg.text,
+        });
+    };
     const gateway = new Gateway({
         config: gwConfig,
         sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
@@ -225,6 +267,9 @@ export async function startDaemon(opts) {
         onInbound,
         onOutbound,
         composeUserTurn: composeBotCordUserTurn,
+        attentionGate,
+        resolveHubUrl,
+        transcriptEnabled: resolveTranscriptEnabled(process.env.BOTCORD_TRANSCRIPT, opts.config.transcript?.enabled === true),
     });
     logger.info("daemon starting", {
         agents: agentIds,
@@ -239,7 +284,7 @@ export async function startDaemon(opts) {
         logger.warn("daemon starting with no channels", {
             source: boot.source,
             credentialsDir: boot.credentialsDir,
-            hint: "drop a credentials JSON in the discovery dir and restart, or run `botcord-daemon init --agent <ag_xxx>`",
+            hint: "drop a credentials JSON in the discovery dir and restart, or run `botcord-daemon start --agent <ag_xxx>` (only seeds config on first run)",
         });
     }
     await gateway.start();
@@ -256,7 +301,7 @@ export async function startDaemon(opts) {
             userId: userAuth.current.userId,
             hubUrl: userAuth.current.hubUrl,
         });
-        const provisioner = createProvisioner({ gateway });
+        const provisioner = createProvisioner({ gateway, policyResolver });
         controlChannel = new ControlChannel({
             auth: userAuth,
             handle: provisioner,
@@ -329,10 +374,12 @@ export function backfillBootAgents(agents, opts) {
     for (const a of agents) {
         if (a.credentialsFile)
             credentialPathByAgentId.set(a.agentId, a.credentialsFile);
-        if (a.runtime || a.cwd) {
+        if (a.runtime || a.cwd || a.openclawGateway || a.openclawAgent) {
             agentRuntimes[a.agentId] = {
                 ...(a.runtime ? { runtime: a.runtime } : {}),
                 ...(a.cwd ? { cwd: a.cwd } : {}),
+                ...(a.openclawGateway ? { openclawGateway: a.openclawGateway } : {}),
+                ...(a.openclawAgent ? { openclawAgent: a.openclawAgent } : {}),
             };
         }
         // Seed files are written only when missing (see `ensureAgentWorkspace`),

package/dist/doctor.d.ts

@@ -25,9 +25,35 @@ export interface DoctorHttpResult {
     status?: number;
     error?: string;
 }
+/** One endpoint probe entry, mirrored from `RuntimeEndpointProbe`. */
+export interface DoctorRuntimeEndpoint {
+    name: string;
+    url: string;
+    reachable: boolean;
+    version?: string;
+    error?: string;
+    agents?: Array<{
+        id: string;
+        name?: string;
+        workspace?: string;
+        model?: {
+            name?: string;
+            provider?: string;
+        };
+    }>;
+    /**
+     * Optional warning surfaced by the doctor: e.g. botcord plugin loaded on
+     * the gateway (would form a daemon → openclaw → botcord → Hub loop).
+     */
+    warnings?: string[];
+}
+/** Augmented runtime entry that may carry endpoint probe results. */
+export interface DoctorRuntimeEntry extends RuntimeProbeEntry {
+    endpoints?: DoctorRuntimeEndpoint[];
+}
 /** Input for the rendered doctor output. */
 export interface DoctorInput {
-    runtimes: RuntimeProbeEntry[];
+    runtimes: DoctorRuntimeEntry[];
     channels: ChannelProbeResult[];
 }
 /** Per-channel config entry accepted by {@link probeChannel}. */

package/dist/doctor.js

@@ -152,8 +152,29 @@ export function renderDoctor(input) {
         version: Math.max(7, ...rows.map((r) => r.version.length)),
     };
     lines.push(`${pad("RUNTIME", widths.runtime)}  ${pad("NAME", widths.name)}  ${pad("STATUS", widths.status)}  ${pad("VERSION", widths.version)}  PATH`);
-    for (const r of rows) {
+    for (let i = 0; i < rows.length; i += 1) {
+        const r = rows[i];
+        const e = input.runtimes[i];
         lines.push(`${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`);
+        if (e.endpoints && e.endpoints.length > 0) {
+            for (const ep of e.endpoints) {
+                const mark = ep.reachable ? "✓" : "✗";
+                const detail = ep.reachable
+                    ? ep.version ?? "ok"
+                    : ep.error ?? "unreachable";
+                lines.push(`    gateway ${pad(`"${ep.name}"`, 16)} ${pad(ep.url, 40)} ${mark} ${detail}`);
+                if (ep.agents && ep.agents.length > 0) {
+                    // RFC §3.8.4: list by `id` (stable key); show display name when distinct.
+                    lines.push(`      agents (id): ${ep.agents
+                        .map((a) => (a.name && a.name !== a.id ? `${a.id} (${a.name})` : a.id))
+                        .join(", ")}`);
+                }
+                if (ep.warnings) {
+                    for (const w of ep.warnings)
+                        lines.push(`      WARN: ${w}`);
+                }
+            }
+        }
     }
     const available = input.runtimes.filter((e) => e.result.available).length;
     lines.push(`\n${available}/${input.runtimes.length} runtimes available`);

package/dist/gateway/cli-resolver.d.ts

@@ -0,0 +1,34 @@
+export interface BundledCliBin {
+    /** Directory containing the `botcord` symlink — safe to prepend to PATH. */
+    binDir: string;
+    /** Absolute path to the CLI's JS entry — for direct spawn (not via PATH). */
+    binPath: string;
+}
+/**
+ * Resolve the bundled `@botcord/cli` package and return both the
+ * `<install-root>/node_modules/.bin` directory (for PATH injection so
+ * `botcord` shows up to runtimes) and the absolute JS entry (for callers
+ * that want to spawn the CLI directly without depending on the symlink).
+ *
+ * Returns `null` when `@botcord/cli` is not installed alongside the daemon
+ * — callers should fall back to whatever `botcord` is on the user's PATH.
+ */
+export declare function resolveBundledCliBin(): BundledCliBin | null;
+/** Test-only: clear the cached resolution. */
+export declare function __resetBundledCliBinCache(): void;
+/**
+ * Return env additions that point a runtime CLI subprocess at the right
+ * BotCord identity:
+ *   - `BOTCORD_HUB`      — hub URL the agent is registered against
+ *   - `BOTCORD_AGENT_ID` — default `--agent` for `botcord ...` invocations
+ *   - `PATH`             — prepended with the bundled CLI's `.bin` dir so
+ *                          `botcord` resolves to the version daemon shipped
+ *                          with (avoiding protocol-core drift). Falls
+ *                          through to whatever the user already has on PATH
+ *                          when the bundled CLI can't be resolved.
+ */
+export declare function buildCliEnv(opts: {
+    hubUrl?: string;
+    accountId?: string;
+    basePath?: string | undefined;
+}): NodeJS.ProcessEnv;

package/dist/gateway/cli-resolver.js

@@ -0,0 +1,74 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import fs from "node:fs";
+import { consoleLogger } from "./log.js";
+const require = createRequire(import.meta.url);
+// Tri-state cache: `undefined` means "not yet attempted"; `null` means
+// "attempted and unavailable" (don't retry, don't re-log).
+let cached;
+/**
+ * Resolve the bundled `@botcord/cli` package and return both the
+ * `<install-root>/node_modules/.bin` directory (for PATH injection so
+ * `botcord` shows up to runtimes) and the absolute JS entry (for callers
+ * that want to spawn the CLI directly without depending on the symlink).
+ *
+ * Returns `null` when `@botcord/cli` is not installed alongside the daemon
+ * — callers should fall back to whatever `botcord` is on the user's PATH.
+ */
+export function resolveBundledCliBin() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        const pkgJsonPath = require.resolve("@botcord/cli/package.json");
+        const pkgRoot = path.dirname(pkgJsonPath);
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+        const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.botcord;
+        if (!binRel) {
+            consoleLogger.warn("cli-resolver: @botcord/cli has no bin.botcord entry");
+            cached = null;
+            return null;
+        }
+        const binPath = path.resolve(pkgRoot, binRel);
+        // PATH must point at `<install-root>/node_modules/.bin` (where npm puts
+        // the `botcord` shim), not the package's own `dist/` — there is no
+        // executable named `botcord` inside the package directory.
+        const binDir = path.resolve(pkgRoot, "..", "..", ".bin");
+        cached = { binDir, binPath };
+        return cached;
+    }
+    catch (err) {
+        consoleLogger.warn("cli-resolver: bundled @botcord/cli not resolvable; runtimes will fall back to PATH", { error: err instanceof Error ? err.message : String(err) });
+        cached = null;
+        return null;
+    }
+}
+/** Test-only: clear the cached resolution. */
+export function __resetBundledCliBinCache() {
+    cached = undefined;
+}
+/**
+ * Return env additions that point a runtime CLI subprocess at the right
+ * BotCord identity:
+ *   - `BOTCORD_HUB`      — hub URL the agent is registered against
+ *   - `BOTCORD_AGENT_ID` — default `--agent` for `botcord ...` invocations
+ *   - `PATH`             — prepended with the bundled CLI's `.bin` dir so
+ *                          `botcord` resolves to the version daemon shipped
+ *                          with (avoiding protocol-core drift). Falls
+ *                          through to whatever the user already has on PATH
+ *                          when the bundled CLI can't be resolved.
+ */
+export function buildCliEnv(opts) {
+    const env = {};
+    if (opts.hubUrl)
+        env.BOTCORD_HUB = opts.hubUrl;
+    if (opts.accountId)
+        env.BOTCORD_AGENT_ID = opts.accountId;
+    const cli = resolveBundledCliBin();
+    if (cli) {
+        const existing = opts.basePath ?? "";
+        env.PATH = existing
+            ? `${cli.binDir}${path.delimiter}${existing}`
+            : cli.binDir;
+    }
+    return env;
+}

package/dist/gateway/dispatcher.d.ts

@@ -1,6 +1,7 @@
 import type { GatewayLogger } from "./log.js";
 import { type SessionStore } from "./session-store.js";
-import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayRoute, InboundObserver, OutboundObserver, RuntimeAdapter, SystemContextBuilder, TurnStatusSnapshot, UserTurnBuilder } from "./types.js";
+import { type TranscriptWriter } from "./transcript.js";
+import type { ChannelAdapter, GatewayConfig, GatewayInboundEnvelope, GatewayInboundMessage, GatewayRoute, InboundObserver, OutboundObserver, 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`. */
@@ -42,6 +43,30 @@ export interface DispatcherOptions {
      * and suppressed so observer failures never break the turn.
      */
     onOutbound?: OutboundObserver;
+    /**
+     * Optional attention gate (PR3, design §4.2). Resolved AFTER `onInbound`
+     * runs and BEFORE the runtime turn enqueues, so working memory / activity
+     * tracking still observe the message even when the gate skips the wake.
+     *
+     * Return `true` to wake the runtime, `false` to skip the turn. Errors are
+     * logged and treated as `true` (fail-open) so a buggy gate cannot silence
+     * the agent.
+     */
+    attentionGate?: (message: GatewayInboundMessage) => Promise<boolean> | boolean;
+    /**
+     * Resolve the hub URL the inbound message's agent is registered against.
+     * Threaded into `RuntimeRunOptions.hubUrl` so spawned CLI subprocesses
+     * target the correct hub. If unset, runtimes leave `BOTCORD_HUB`
+     * unspecified and fall back to whatever the bundled CLI defaults to.
+     */
+    resolveHubUrl?: (accountId: string) => string | undefined;
+    /**
+     * Optional NDJSON transcript writer. When provided, dispatcher emits one
+     * inbound record + one path record + (for dispatched turns) one terminal
+     * record per `handle()` call. A noop writer is used by default so existing
+     * call sites keep working unchanged. See `docs/transcript-logging.md`.
+     */
+    transcript?: TranscriptWriter;
 }
 /**
  * Gateway dispatcher: consumes `GatewayInboundEnvelope` and drives a runtime
@@ -65,6 +90,9 @@ export declare class Dispatcher {
     private readonly onOutbound?;
     private readonly composeUserTurn?;
     private readonly managedRoutes?;
+    private readonly attentionGate?;
+    private readonly resolveHubUrl?;
+    private readonly transcript;
     private readonly queues;
     constructor(opts: DispatcherOptions);
     /** Consume one inbound envelope, ack it once ownership is decided, then run its turn. */
@@ -74,7 +102,44 @@ export declare class Dispatcher {
     private safeAck;
     private getQueue;
     private runCancelPrevious;
+    /**
+     * Serial mode with coalesce-on-drain semantics:
+     *
+     *   1. First arrival on an idle queue boots the worker, which dispatches a
+     *      single-message turn immediately (no batching delay).
+     *   2. Arrivals during an in-flight turn append to `serialBuffer`; when the
+     *      worker finishes the current turn it drains the entire buffer and
+     *      merges all pending entries into ONE next turn (folded into a single
+     *      `raw.batch` so the composer renders them as multi-block input).
+     *   3. Buffer caps: at most `MAX_BATCH_BUFFER_ENTRIES` entries are retained
+     *      (drop oldest) and merged turns are further trimmed to fit
+     *      `MAX_BATCH_BUFFER_CHARS` of total raw text.
+     *
+     * Note: the pre-composed `text` from `handle()` is intentionally discarded
+     * here — at drain time the worker re-invokes `composeUserTurn` on the
+     * merged message so the runtime sees a single coherent prompt covering all
+     * coalesced messages.
+     */
     private runSerial;
+    /**
+     * Merge buffered serial entries into a single dispatchable unit. With one
+     * entry the call is a near no-op (just recompose). With ≥2 entries this
+     * flattens any per-entry `raw.batch` (the BotCord channel already groups
+     * one inbox-poll's worth of same-room/topic messages into a `raw.batch`),
+     * applies the `MAX_BATCH_BUFFER_CHARS` cap by dropping oldest individual
+     * messages, and then synthesizes a merged inbound message anchored on the
+     * latest entry's metadata (mentioned = OR across all entries).
+     */
+    private mergeSerialBuffer;
+    /**
+     * Re-run the user-turn composer at drain time. Mirrors the logic in
+     * `handle()` but operates on the (possibly merged) message. Falls back to
+     * raw trimmed text on composer failure so a buggy composer never drops a
+     * turn.
+     */
+    private recomposeUserTurn;
     private runTurn;
     private sendReply;
+    private emitInbound;
+    private emitOutbound;
 }