@botcord/daemon 0.1.1

package/dist/doctor.js

@@ -0,0 +1,191 @@
+import { resolveBootAgents } from "./agent-discovery.js";
+/**
+ * Build the implicit channel list for a daemon config. One channel per
+ * configured or discovered agent, keyed by agentId (matches
+ * `toGatewayConfig`). Mirrors the daemon's boot-agent resolution so
+ * `doctor` reports channels even when the config file omits `agents`.
+ */
+export function channelsFromDaemonConfig(cfg) {
+    let boot;
+    try {
+        boot = resolveBootAgents(cfg);
+    }
+    catch {
+        return [];
+    }
+    return boot.agents.map((a) => {
+        const entry = {
+            id: a.agentId,
+            type: "botcord",
+            accountId: a.agentId,
+        };
+        if (a.credentialsFile)
+            entry.credentialsFile = a.credentialsFile;
+        return entry;
+    });
+}
+/**
+ * Inspect credentials + Hub reachability for one channel. Pure modulo the
+ * injected file reader and fetcher.
+ */
+export async function probeChannel(ch, opts) {
+    const result = {
+        id: ch.id,
+        type: ch.type,
+        accountId: ch.accountId,
+        credentialsOk: false,
+        credentialsMessage: "",
+        hubUrl: null,
+        hubOk: false,
+        hubMessage: "",
+    };
+    if (ch.type !== "botcord") {
+        result.credentialsMessage = `unsupported channel type "${ch.type}" (no credentials check)`;
+        result.hubMessage = "skipped";
+        return result;
+    }
+    const credFile = ch.credentialsFile ?? opts.credentialsPath(ch.accountId);
+    const raw = opts.fileReader.readFile(credFile);
+    if (raw === null) {
+        result.credentialsMessage = `missing at ${credFile}`;
+    }
+    else {
+        try {
+            const parsed = JSON.parse(raw);
+            const token = parsed.token ?? parsed["token"];
+            const hubUrlRaw = parsed.hubUrl ?? parsed["hub_url"] ?? parsed["hub"];
+            if (typeof token !== "string" || token.length === 0) {
+                result.credentialsMessage = "token missing or empty";
+            }
+            else if (typeof hubUrlRaw !== "string" || hubUrlRaw.length === 0) {
+                result.credentialsMessage = "hubUrl missing";
+            }
+            else {
+                result.credentialsOk = true;
+                result.credentialsMessage = `loaded (${credFile})`;
+                result.hubUrl = hubUrlRaw;
+            }
+        }
+        catch (err) {
+            result.credentialsMessage = `invalid JSON: ${err.message}`;
+        }
+    }
+    if (!result.hubUrl) {
+        result.hubMessage = "skipped (no hub URL)";
+        return result;
+    }
+    // Probe `/` — the hub is ASGI and responds 2xx/3xx/404 which is fine for
+    // "reachable". We treat any response as reachable; network errors fall
+    // through to hubOk=false.
+    const probeUrl = `${result.hubUrl.replace(/\/+$/, "")}/`;
+    const http = await opts.fetcher(probeUrl, opts.timeoutMs);
+    if (http.ok) {
+        result.hubOk = true;
+        result.hubMessage = `reachable (HTTP ${http.status})`;
+    }
+    else if (http.status !== undefined) {
+        result.hubMessage = `HTTP ${http.status}`;
+    }
+    else {
+        result.hubMessage = http.error ?? "unreachable";
+    }
+    return result;
+}
+/** Probe a list of channels sequentially. Sequential keeps output stable. */
+export async function probeChannels(opts) {
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const out = [];
+    for (const ch of opts.channels) {
+        out.push(await probeChannel(ch, {
+            credentialsPath: opts.credentialsPath,
+            fileReader: opts.fileReader,
+            fetcher: opts.fetcher,
+            timeoutMs,
+        }));
+    }
+    return out;
+}
+/** Default HTTP fetcher using `fetch` + `AbortController` timeout. */
+export const defaultHttpFetcher = async (url, timeoutMs) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const resp = await fetch(url, {
+            method: "GET",
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        const ok = resp.status >= 200 && resp.status < 400;
+        return { ok, status: resp.status };
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === "AbortError")
+            return { ok: false, error: "timeout" };
+        return { ok: false, error: e.message };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+function pad(s, n) {
+    return s + " ".repeat(Math.max(0, n - s.length));
+}
+/**
+ * Render runtime + channel probe output. Pure — all IO happened already.
+ * Used by the CLI `doctor` command and by unit tests.
+ */
+export function renderDoctor(input) {
+    const lines = [];
+    // Runtimes table (matches existing doctor layout).
+    const rows = input.runtimes.map((e) => ({
+        runtime: e.id,
+        name: e.displayName,
+        status: e.result.available ? "ok" : "missing",
+        version: e.result.version ?? "—",
+        path: e.result.path ?? "—",
+    }));
+    const widths = {
+        runtime: Math.max(7, ...rows.map((r) => r.runtime.length)),
+        name: Math.max(4, ...rows.map((r) => r.name.length)),
+        status: Math.max(6, ...rows.map((r) => r.status.length)),
+        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) {
+        lines.push(`${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`);
+    }
+    const available = input.runtimes.filter((e) => e.result.available).length;
+    lines.push(`\n${available}/${input.runtimes.length} runtimes available`);
+    lines.push("");
+    lines.push("Channels:");
+    if (input.channels.length === 0) {
+        lines.push("  No channels configured.");
+        return lines.join("\n");
+    }
+    const cw = {
+        id: Math.max(2, ...input.channels.map((c) => c.id.length)),
+        type: Math.max(4, ...input.channels.map((c) => c.type.length)),
+    };
+    lines.push(`  ${pad("ID", cw.id)}  ${pad("TYPE", cw.type)}  CREDENTIALS        HUB`);
+    for (const c of input.channels) {
+        const credMark = c.credentialsOk ? "✓" : "✗";
+        const hubMark = c.hubOk ? "✓" : "✗";
+        lines.push(`  ${pad(c.id, cw.id)}  ${pad(c.type, cw.type)}  ${credMark} ${pad(c.credentialsMessage, 16)}  ${hubMark} ${c.hubMessage}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Thin orchestrator: runs runtime + channel probes and returns the rendered
+ * text. Keeps `index.ts` free of probe wiring.
+ */
+export async function runDoctor(runtimes, channels, opts) {
+    const channelResults = await probeChannels({
+        channels,
+        credentialsPath: opts.credentialsPath,
+        fileReader: opts.fileReader,
+        fetcher: opts.fetcher,
+        timeoutMs: opts.timeoutMs,
+    });
+    return { runtimes, channels: channelResults };
+}

package/dist/gateway/channel-manager.d.ts

@@ -0,0 +1,54 @@
+import type { ChannelAdapter, ChannelStatusSnapshot, GatewayConfig, GatewayInboundEnvelope } from "./types.js";
+import type { GatewayLogger } from "./log.js";
+/** Exponential backoff tuning for crashed-channel restarts. */
+export interface ChannelBackoffOptions {
+    initial?: number;
+    max?: number;
+    factor?: number;
+}
+/** Constructor options for `ChannelManager`. */
+export interface ChannelManagerOptions {
+    config: GatewayConfig;
+    channels: ChannelAdapter[];
+    log: GatewayLogger;
+    emit: (env: GatewayInboundEnvelope) => Promise<void>;
+    backoffMs?: ChannelBackoffOptions;
+}
+/** Supervises channel adapters: lifecycle, status tracking, and crash restart with backoff. */
+export declare class ChannelManager {
+    private readonly config;
+    private readonly log;
+    private readonly emit;
+    private readonly initialBackoff;
+    private readonly maxBackoff;
+    private readonly factor;
+    private readonly entries;
+    constructor(opts: ChannelManagerOptions);
+    private registerAdapter;
+    /** Start every configured channel; already-running channels are skipped. */
+    startAll(): Promise<void>;
+    /**
+     * Launch a single adapter that wasn't present at construction — used by
+     * `Gateway.addChannel()` to hot-plug a new agent without a full restart.
+     * Idempotent: if an entry with the same id is already running, this is a
+     * no-op (after logging a warning).
+     */
+    addOne(adapter: ChannelAdapter): void;
+    /**
+     * Stop and forget a single channel. Cancels any pending restart timer,
+     * aborts the running turn, awaits the adapter's `stop()`, and removes
+     * the entry from the status map. Safe to call on an unknown id.
+     */
+    removeOne(id: string, reason?: string): Promise<void>;
+    /** Abort every channel, cancel pending restarts, and await all run promises. */
+    stopAll(reason?: string): Promise<void>;
+    /** Return a shallow copy of per-channel status snapshots keyed by channel id. */
+    status(): Record<string, ChannelStatusSnapshot>;
+    /** Look up a registered channel adapter by id. */
+    getChannel(id: string): ChannelAdapter | undefined;
+    private findAccountId;
+    private launch;
+    private onExit;
+    private scheduleRestart;
+    private safeEmit;
+}

package/dist/gateway/channel-manager.js

@@ -0,0 +1,292 @@
+const DEFAULT_INITIAL_BACKOFF = 1000;
+const DEFAULT_MAX_BACKOFF = 60_000;
+const DEFAULT_FACTOR = 2;
+const LONG_RUN_THRESHOLD_MS = 30_000;
+/** Supervises channel adapters: lifecycle, status tracking, and crash restart with backoff. */
+export class ChannelManager {
+    config;
+    log;
+    emit;
+    initialBackoff;
+    maxBackoff;
+    factor;
+    entries = new Map();
+    constructor(opts) {
+        this.config = opts.config;
+        this.log = opts.log;
+        this.emit = opts.emit;
+        this.initialBackoff = opts.backoffMs?.initial ?? DEFAULT_INITIAL_BACKOFF;
+        this.maxBackoff = opts.backoffMs?.max ?? DEFAULT_MAX_BACKOFF;
+        this.factor = opts.backoffMs?.factor ?? DEFAULT_FACTOR;
+        for (const adapter of opts.channels) {
+            this.registerAdapter(adapter);
+        }
+    }
+    registerAdapter(adapter) {
+        const accountId = this.findAccountId(adapter.id);
+        const entry = {
+            adapter,
+            accountId,
+            state: "idle",
+            snapshot: {
+                channel: adapter.id,
+                accountId,
+                running: false,
+                reconnectAttempts: 0,
+                restartPending: false,
+                lastError: null,
+            },
+            controller: null,
+            runPromise: null,
+            restartTimer: null,
+            nextBackoff: this.initialBackoff,
+            currentStartAt: 0,
+            reconnectAttempts: 0,
+            stopRequested: false,
+        };
+        this.entries.set(adapter.id, entry);
+        return entry;
+    }
+    /** Start every configured channel; already-running channels are skipped. */
+    async startAll() {
+        for (const entry of this.entries.values()) {
+            if (entry.state === "idle" || entry.state === "crashed") {
+                this.launch(entry);
+            }
+        }
+    }
+    /**
+     * Launch a single adapter that wasn't present at construction — used by
+     * `Gateway.addChannel()` to hot-plug a new agent without a full restart.
+     * Idempotent: if an entry with the same id is already running, this is a
+     * no-op (after logging a warning).
+     */
+    addOne(adapter) {
+        const existing = this.entries.get(adapter.id);
+        if (existing) {
+            this.log.warn("channel.addOne: id already present", { channel: adapter.id });
+            return;
+        }
+        const entry = this.registerAdapter(adapter);
+        this.launch(entry);
+    }
+    /**
+     * Stop and forget a single channel. Cancels any pending restart timer,
+     * aborts the running turn, awaits the adapter's `stop()`, and removes
+     * the entry from the status map. Safe to call on an unknown id.
+     */
+    async removeOne(id, reason) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        entry.stopRequested = true;
+        if (entry.restartTimer) {
+            clearTimeout(entry.restartTimer);
+            entry.restartTimer = null;
+            entry.snapshot = { ...entry.snapshot, restartPending: false };
+        }
+        const pending = [];
+        if (entry.state === "running" || entry.state === "starting") {
+            entry.state = "stopping";
+            entry.controller?.abort();
+            const adapter = entry.adapter;
+            if (adapter.stop) {
+                try {
+                    const p = adapter.stop({ reason });
+                    pending.push(Promise.resolve(p).catch((err) => {
+                        this.log.warn("channel.stop failed", {
+                            channel: adapter.id,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }));
+                }
+                catch (err) {
+                    this.log.warn("channel.stop threw", {
+                        channel: adapter.id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+        if (entry.runPromise) {
+            pending.push(entry.runPromise.catch(() => undefined));
+        }
+        await Promise.all(pending);
+        this.entries.delete(id);
+    }
+    /** Abort every channel, cancel pending restarts, and await all run promises. */
+    async stopAll(reason) {
+        const pending = [];
+        for (const entry of this.entries.values()) {
+            entry.stopRequested = true;
+            if (entry.restartTimer) {
+                clearTimeout(entry.restartTimer);
+                entry.restartTimer = null;
+                entry.snapshot = { ...entry.snapshot, restartPending: false };
+            }
+            if (entry.state === "running" || entry.state === "starting") {
+                entry.state = "stopping";
+                entry.controller?.abort();
+                const adapter = entry.adapter;
+                if (adapter.stop) {
+                    try {
+                        const p = adapter.stop({ reason });
+                        pending.push(Promise.resolve(p).catch((err) => {
+                            this.log.warn("channel.stop failed", {
+                                channel: adapter.id,
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                        }));
+                    }
+                    catch (err) {
+                        this.log.warn("channel.stop threw", {
+                            channel: adapter.id,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+            }
+            if (entry.runPromise) {
+                pending.push(entry.runPromise.catch(() => undefined));
+            }
+        }
+        await Promise.all(pending);
+        // Reset stop flag so startAll can re-enter.
+        for (const entry of this.entries.values()) {
+            entry.stopRequested = false;
+        }
+    }
+    /** Return a shallow copy of per-channel status snapshots keyed by channel id. */
+    status() {
+        const out = {};
+        for (const [id, entry] of this.entries) {
+            out[id] = { ...entry.snapshot };
+        }
+        return out;
+    }
+    /** Look up a registered channel adapter by id. */
+    getChannel(id) {
+        return this.entries.get(id)?.adapter;
+    }
+    findAccountId(channelId) {
+        const cfg = this.config.channels.find((c) => c.id === channelId);
+        return cfg?.accountId ?? "";
+    }
+    launch(entry) {
+        if (entry.state === "starting" || entry.state === "running")
+            return;
+        entry.stopRequested = false;
+        entry.state = "starting";
+        entry.controller = new AbortController();
+        entry.currentStartAt = Date.now();
+        entry.snapshot = {
+            ...entry.snapshot,
+            running: true,
+            restartPending: false,
+            lastStartAt: entry.currentStartAt,
+            lastError: null,
+            reconnectAttempts: entry.reconnectAttempts,
+        };
+        const ctx = {
+            config: this.config,
+            accountId: entry.accountId,
+            abortSignal: entry.controller.signal,
+            log: this.log,
+            emit: (env) => this.safeEmit(entry.adapter.id, env),
+            setStatus: (patch) => {
+                entry.snapshot = { ...entry.snapshot, ...patch };
+            },
+        };
+        this.log.info("channel starting", { channel: entry.adapter.id });
+        const run = (async () => {
+            try {
+                await entry.adapter.start(ctx);
+                this.onExit(entry, null);
+            }
+            catch (err) {
+                this.onExit(entry, err);
+            }
+        })();
+        entry.runPromise = run;
+        entry.state = "running";
+    }
+    onExit(entry, err) {
+        const ranForMs = Date.now() - entry.currentStartAt;
+        const channelId = entry.adapter.id;
+        const crashed = err !== null && err !== undefined;
+        entry.snapshot = {
+            ...entry.snapshot,
+            running: false,
+            lastStopAt: Date.now(),
+            lastError: crashed
+                ? err instanceof Error
+                    ? err.message
+                    : String(err)
+                : entry.snapshot.lastError ?? null,
+        };
+        if (crashed) {
+            this.log.warn("channel crashed", {
+                channel: channelId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            entry.state = "crashed";
+        }
+        else {
+            this.log.info("channel exited", { channel: channelId });
+            entry.state = "idle";
+        }
+        if (entry.stopRequested) {
+            entry.runPromise = null;
+            return;
+        }
+        // Long-run resets backoff to initial.
+        if (ranForMs >= LONG_RUN_THRESHOLD_MS) {
+            entry.nextBackoff = this.initialBackoff;
+        }
+        this.scheduleRestart(entry);
+    }
+    scheduleRestart(entry) {
+        const delay = entry.nextBackoff;
+        entry.snapshot = { ...entry.snapshot, restartPending: true };
+        this.log.info("channel restart scheduled", {
+            channel: entry.adapter.id,
+            delayMs: delay,
+            attempts: entry.reconnectAttempts,
+        });
+        const timer = setTimeout(() => {
+            entry.restartTimer = null;
+            entry.runPromise = null;
+            if (entry.stopRequested)
+                return;
+            entry.reconnectAttempts += 1;
+            entry.snapshot = {
+                ...entry.snapshot,
+                restartPending: false,
+                reconnectAttempts: entry.reconnectAttempts,
+            };
+            entry.nextBackoff = Math.min(entry.nextBackoff * this.factor, this.maxBackoff);
+            this.launch(entry);
+        }, delay);
+        entry.restartTimer = timer;
+    }
+    async safeEmit(channelId, env) {
+        const msg = env?.message;
+        if (!msg || typeof msg.id !== "string" || !msg.id || typeof msg.channel !== "string" || !msg.channel) {
+            this.log.warn("dropping malformed inbound envelope", {
+                channel: channelId,
+                hasMessage: Boolean(msg),
+                messageId: msg && typeof msg === "object" ? msg.id : undefined,
+            });
+            return;
+        }
+        try {
+            await this.emit(env);
+        }
+        catch (err) {
+            this.log.error("emit failed", {
+                channel: channelId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}

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

@@ -0,0 +1,93 @@
+import WebSocket from "ws";
+import { type InboxMessage } from "@botcord/protocol-core";
+import type { ChannelAdapter, GatewayInboundMessage } from "../index.js";
+/** Minimal surface the adapter needs from `BotCordClient`. Matches the subset used at runtime. */
+export interface BotCordChannelClient {
+    ensureToken(): Promise<string>;
+    refreshToken(): Promise<string>;
+    pollInbox(options?: {
+        limit?: number;
+        ack?: boolean;
+        timeout?: number;
+        roomId?: string;
+    }): Promise<{
+        messages: InboxMessage[];
+        count: number;
+        has_more: boolean;
+    }>;
+    ackMessages(messageIds: string[]): Promise<void>;
+    sendMessage(to: string, text: string, options?: {
+        replyTo?: string;
+        topic?: string;
+    }): Promise<{
+        hub_msg_id?: string;
+        message_id?: string;
+    } & Record<string, unknown>>;
+    getHubUrl(): string;
+    onTokenRefresh?: (token: string, expiresAt: number) => void;
+}
+/** Factory that returns a ready-to-use BotCord client. Injection point for tests. */
+export type BotCordClientFactory = (input: {
+    agentId: string;
+    hubBaseUrl?: string;
+    credentialsPath?: string;
+}) => BotCordChannelClient;
+/** Options accepted by `createBotCordChannel()`. */
+export interface BotCordChannelOptions {
+    /** Channel instance id from config. */
+    id: string;
+    /** Gateway `accountId` — matches BotCord `agentId`. */
+    accountId: string;
+    /** BotCord `agentId` (usually identical to `accountId`). */
+    agentId: string;
+    /** Override for the credentials JSON path. Defaults to `~/.botcord/credentials/<agentId>.json`. */
+    credentialsPath?: string;
+    /** Override the Hub base URL. Defaults to the `hubUrl` stored in credentials. */
+    hubBaseUrl?: string;
+    /** Not used by the WS-only loop today; kept for future polling fallback. */
+    pollIntervalMs?: number;
+    /** Test hook: supply a pre-built client instead of loading credentials from disk. */
+    client?: BotCordChannelClient;
+    /** Test hook: supply a client factory. Ignored when `client` is provided. */
+    clientFactory?: BotCordClientFactory;
+    /**
+     * Test hook: override the raw WebSocket constructor. Useful for tests that
+     * can't spin up a real WS server.
+     */
+    webSocketCtor?: typeof WebSocket;
+}
+/**
+ * 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)
+ */
+declare function normalizeInbox(msg: InboxMessage, options: {
+    channelId: string;
+    accountId: string;
+}): GatewayInboundMessage | null;
+/**
+ * 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 declare function createBotCordChannel(options: BotCordChannelOptions): ChannelAdapter;
+export { normalizeInbox as __normalizeInboxForTests };