@botcord/daemon 0.1.1

package/dist/daemon.d.ts

@@ -0,0 +1,123 @@
+import { type GatewayInboundMessage, type GatewayLogger, type GatewayRuntimeSnapshot } from "./gateway/index.js";
+import type { DaemonConfig } from "./config.js";
+import { type BootAgentsResult } from "./agent-discovery.js";
+import { ensureAgentWorkspace } from "./agent-workspace.js";
+import { UserAuthManager } from "./user-auth.js";
+import { classifyActivitySender } from "./sender-classify.js";
+export { classifyActivitySender };
+/** Minimal activity-tracker surface the inbound observer uses. */
+interface ActivityRecorderTarget {
+    record: (entry: {
+        agentId: string;
+        roomId: string;
+        roomName?: string;
+        topic: string | null;
+        lastInboundPreview: string;
+        lastSenderKind: "agent" | "human" | "owner";
+        lastSender: string;
+    }) => void;
+}
+/**
+ * Build the `onInbound` observer wired to the given activity tracker.
+ * Exported for tests.
+ *
+ * The recorded `agentId` is taken from the inbound message's `accountId`
+ * — so a multi-agent daemon files activity under whichever configured
+ * agent actually received the message. An optional `fallbackAgentId`
+ * covers pathological inputs where `accountId` is empty (should never
+ * happen from the gateway, but defensive).
+ */
+export declare function createActivityRecorder(opts: {
+    activityTracker: ActivityRecorderTarget;
+    fallbackAgentId?: string;
+}): (msg: GatewayInboundMessage) => void;
+/**
+ * Minimal send-capable surface used by {@link pushRuntimeSnapshot}.
+ * Exists so the helper is trivially mockable from unit tests without needing
+ * a full `ControlChannel` + user-auth harness.
+ */
+export interface RuntimeSnapshotSink {
+    send: (frame: {
+        id: string;
+        type: string;
+        params?: Record<string, unknown>;
+        ts?: number;
+    }) => boolean;
+}
+/**
+ * Emit one `runtime_snapshot` event frame on the control channel. Plan §8.5
+ * P0: first-connect push only — reconnect-push and diffing are P1. A send
+ * failure is non-fatal (the Hub will re-query via `list_runtimes` on demand
+ * or wait for the next daemon restart). Exported for unit tests.
+ */
+export declare function pushRuntimeSnapshot(sink: RuntimeSnapshotSink): boolean;
+/** Options accepted by {@link startDaemon} — the P0.5 compatibility shim. */
+export interface DaemonRuntimeOptions {
+    config: DaemonConfig;
+    /** Informational only; surfaced in startup logs. */
+    configPath: string;
+    /** Override the JSON session store location; defaults to `~/.botcord/daemon/sessions.json`. */
+    sessionStorePath?: string;
+    /** Override the snapshot file path; defaults to `~/.botcord/daemon/snapshot.json`. */
+    snapshotPath?: string;
+    /** Override snapshot write cadence in ms; defaults to 5s or `BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS`. */
+    snapshotIntervalMs?: number;
+    log?: GatewayLogger;
+    /** Override Hub base URL; defaults to the one stored in credentials. */
+    hubBaseUrl?: string;
+    /** Override credentials JSON path; defaults to `~/.botcord/credentials/<agentId>.json`. */
+    credentialsPath?: string;
+    /**
+     * Inject a pre-resolved boot-agent list (e.g. from tests). When omitted,
+     * `startDaemon` resolves boot agents from `config.agents`/`config.agentId`
+     * or falls back to credential discovery.
+     */
+    bootAgents?: BootAgentsResult;
+    /**
+     * Inject a pre-built user-auth manager. Typically only set by tests; in
+     * production the daemon calls `UserAuthManager.load()` internally, and
+     * only starts the control channel when a user-auth record exists.
+     */
+    userAuth?: UserAuthManager | null;
+    /** Skip the control channel even when user-auth is available. Test hook. */
+    disableControlChannel?: boolean;
+}
+/** Handle returned by {@link startDaemon}. */
+export interface DaemonHandle {
+    /** Graceful shutdown — idempotent. */
+    stop: (reason?: string) => Promise<void>;
+    /** Channel + turn status snapshot, straight from `Gateway.snapshot()`. */
+    snapshot: () => GatewayRuntimeSnapshot;
+}
+/**
+ * Boot the gateway using a daemon-shaped config. This is the P0.5 compat
+ * entry point: the on-disk config at `~/.botcord/daemon/config.json` keeps
+ * its existing shape, and `Gateway` handles channels/dispatch/sessions
+ * under the hood.
+ *
+ * Only the BotCord channel is supported today; `channels[]` in the
+ * translated gateway config has exactly one entry (`botcord-main`).
+ */
+export declare function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHandle>;
+/**
+ * Result of {@link backfillBootAgents}: the maps the boot flow needs to
+ * plumb into `toGatewayConfig` + the channel factory.
+ */
+export interface BootBackfillResult {
+    credentialPathByAgentId: Map<string, string>;
+    agentRuntimes: Record<string, {
+        runtime?: string;
+        cwd?: string;
+    }>;
+}
+/**
+ * Walk the boot-agent list and (a) populate the credential-path + runtime
+ * caches used downstream, and (b) idempotently create each agent's on-disk
+ * workspace tree (plan §9). One agent's failing workspace must not block
+ * the others — errors are warned and swallowed per agent. Exported for
+ * unit tests; `startDaemon` calls this inline.
+ */
+export declare function backfillBootAgents(agents: BootAgentsResult["agents"], opts: {
+    logger: GatewayLogger;
+    ensure?: typeof ensureAgentWorkspace;
+}): BootBackfillResult;

package/dist/daemon.js

@@ -0,0 +1,349 @@
+import { CONTROL_FRAME_TYPES } from "@botcord/protocol-core";
+import { Gateway, createBotCordChannel, 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";
+import { ensureAgentWorkspace } from "./agent-workspace.js";
+import { ControlChannel } from "./control-channel.js";
+import { toGatewayConfig } from "./daemon-config-map.js";
+import { log as daemonLog } from "./log.js";
+import { collectRuntimeSnapshot, createProvisioner } from "./provision.js";
+import { SnapshotWriter } from "./snapshot-writer.js";
+import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { createRoomStaticContextBuilder } from "./room-context.js";
+import { createRoomContextFetcher } from "./room-context-fetcher.js";
+import { composeBotCordUserTurn } from "./turn-text.js";
+import { UserAuthManager } from "./user-auth.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.
+ */
+const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Default cadence for writing `gateway.snapshot()` to disk. Override via
+ * `BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS`.
+ */
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 5_000;
+function resolveSnapshotIntervalMs() {
+    const raw = process.env.BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS;
+    if (!raw)
+        return DEFAULT_SNAPSHOT_INTERVAL_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_SNAPSHOT_INTERVAL_MS;
+    return n;
+}
+// Sender classification lives in `./sender-classify.ts` so it can be shared
+// with the user-turn composer without a daemon.ts ↔ turn-text.ts cycle.
+import { classifyActivitySender } from "./sender-classify.js";
+export { classifyActivitySender };
+/**
+ * Build the `onInbound` observer wired to the given activity tracker.
+ * Exported for tests.
+ *
+ * The recorded `agentId` is taken from the inbound message's `accountId`
+ * — so a multi-agent daemon files activity under whichever configured
+ * agent actually received the message. An optional `fallbackAgentId`
+ * covers pathological inputs where `accountId` is empty (should never
+ * happen from the gateway, but defensive).
+ */
+export function createActivityRecorder(opts) {
+    return (msg) => {
+        const { kind, label } = classifyActivitySender(msg);
+        const rawText = typeof msg.text === "string" ? msg.text : "";
+        // Owner text passes through verbatim; everything else gets the same
+        // sanitization the legacy dispatcher applied before recording a preview.
+        const preview = kind === "owner" ? rawText : sanitizeUntrustedContent(rawText);
+        const agentId = msg.accountId || opts.fallbackAgentId || "";
+        opts.activityTracker.record({
+            agentId,
+            roomId: msg.conversation.id,
+            roomName: msg.conversation.title,
+            topic: msg.conversation.threadId ?? null,
+            lastInboundPreview: preview,
+            lastSenderKind: kind,
+            lastSender: label,
+        });
+    };
+}
+/**
+ * Emit one `runtime_snapshot` event frame on the control channel. Plan §8.5
+ * P0: first-connect push only — reconnect-push and diffing are P1. A send
+ * failure is non-fatal (the Hub will re-query via `list_runtimes` on demand
+ * or wait for the next daemon restart). Exported for unit tests.
+ */
+export function pushRuntimeSnapshot(sink) {
+    const snap = collectRuntimeSnapshot();
+    const ok = sink.send({
+        id: `rt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        type: CONTROL_FRAME_TYPES.RUNTIME_SNAPSHOT,
+        params: snap,
+        ts: Date.now(),
+    });
+    if (!ok) {
+        daemonLog.warn("runtime-snapshot: control-channel send returned false", {
+            runtimes: snap.runtimes.length,
+        });
+    }
+    return ok;
+}
+/**
+ * Adapt daemon's file-based `log` module into the gateway logger contract.
+ * Writes go to `~/.botcord/logs/daemon.log` + stderr, preserving the format
+ * existing `logs -f` watchers rely on. Debug lines stay gated by
+ * `BOTCORD_DAEMON_DEBUG`, mirroring pre-migration behavior.
+ */
+function buildDaemonLogger() {
+    return {
+        info: (msg, meta) => daemonLog.info(msg, meta),
+        warn: (msg, meta) => daemonLog.warn(msg, meta),
+        error: (msg, meta) => daemonLog.error(msg, meta),
+        debug: (msg, meta) => daemonLog.debug(msg, meta),
+    };
+}
+/**
+ * Boot the gateway using a daemon-shaped config. This is the P0.5 compat
+ * entry point: the on-disk config at `~/.botcord/daemon/config.json` keeps
+ * its existing shape, and `Gateway` handles channels/dispatch/sessions
+ * under the hood.
+ *
+ * Only the BotCord channel is supported today; `channels[]` in the
+ * translated gateway config has exactly one entry (`botcord-main`).
+ */
+export async function startDaemon(opts) {
+    const logger = opts.log ?? buildDaemonLogger();
+    // Resolve boot agents: explicit `agents` config wins; otherwise scan the
+    // credentials directory. A zero-agent result is valid in P1 — the daemon
+    // still starts with zero channels so operators can drop credentials in
+    // and restart without re-running `init`.
+    const boot = opts.bootAgents ?? resolveBootAgents(opts.config);
+    for (const w of boot.warnings) {
+        logger.warn("daemon.discovery.warning", { message: w });
+    }
+    const agentIds = boot.agents.map((a) => a.agentId);
+    const { credentialPathByAgentId, agentRuntimes } = backfillBootAgents(boot.agents, { logger });
+    const gwConfig = toGatewayConfig(opts.config, { agentIds, agentRuntimes });
+    // 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`
+    // observer so incoming messages get recorded before the turn runs —
+    // mirroring the pre-P0.5 dispatcher's "record-before-adapter-run" ordering.
+    const activityTracker = new ActivityTracker();
+    // Shared room-context fetcher — one BotCordClient per accountId, created
+    // lazily and reused across turns so JWT refreshes amortize. The builder
+    // wrapping it adds a TTL cache on top so group rooms don't hit Hub every
+    // turn.
+    const roomContextFetcher = createRoomContextFetcher({
+        credentialPathByAgentId,
+        ...(opts.credentialsPath ? { defaultCredentialsPath: opts.credentialsPath } : {}),
+        ...(opts.hubBaseUrl ? { hubBaseUrl: opts.hubBaseUrl } : {}),
+        log: logger,
+    });
+    const roomContextBuilder = createRoomStaticContextBuilder({
+        fetchRoomInfo: roomContextFetcher,
+        log: logger,
+    });
+    const scBuilders = new Map();
+    for (const aid of agentIds) {
+        scBuilders.set(aid, createDaemonSystemContextBuilder({
+            agentId: aid,
+            activityTracker,
+            roomContextBuilder,
+        }));
+    }
+    const buildSystemContext = (message) => {
+        const b = scBuilders.get(message.accountId);
+        if (b)
+            return b(message);
+        // Unknown accountId (shouldn't happen in practice): fall back to the
+        // first configured agent so we still emit *something* rather than
+        // silently dropping the context block. When no agents are bound the
+        // daemon has no context to surface — return undefined.
+        const first = agentIds[0];
+        if (!first)
+            return undefined;
+        const fallback = scBuilders.get(first);
+        return fallback ? fallback(message) : undefined;
+    };
+    // Observer runs after ack + before runtime.run. Keeping the side effect
+    // outside the system-context builder (option A) means the builder stays
+    // pure — a cleaner contract the gateway can also expose to non-daemon
+    // callers in the future.
+    const onInbound = createActivityRecorder({
+        activityTracker,
+        ...(agentIds[0] ? { fallbackAgentId: agentIds[0] } : {}),
+    });
+    const gateway = new Gateway({
+        config: gwConfig,
+        sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
+        createChannel: (chCfg) => {
+            const agentId = typeof chCfg.agentId === "string" ? chCfg.agentId : chCfg.accountId;
+            return createBotCordChannel({
+                id: chCfg.id,
+                accountId: chCfg.accountId,
+                agentId,
+                credentialsPath: credentialPathByAgentId.get(agentId) ?? opts.credentialsPath,
+                hubBaseUrl: opts.hubBaseUrl,
+            });
+        },
+        log: logger,
+        turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
+        buildSystemContext,
+        onInbound,
+        composeUserTurn: composeBotCordUserTurn,
+    });
+    logger.info("daemon starting", {
+        agents: agentIds,
+        source: boot.source,
+        credentialsDir: boot.credentialsDir,
+        configPath: opts.configPath,
+        sessionsPath: opts.sessionStorePath ?? SESSIONS_PATH,
+        channels: gwConfig.channels.map((c) => c.id),
+        routeCount: gwConfig.routes?.length ?? 0,
+    });
+    if (agentIds.length === 0) {
+        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>`",
+        });
+    }
+    await gateway.start();
+    logger.info("daemon started", { agents: agentIds });
+    // Control channel is optional — daemon still runs (data-plane only)
+    // when user-auth hasn't been set up yet. Operators can `login` later
+    // without restarting, but for P0 we require a restart to pick it up.
+    let controlChannel = null;
+    const userAuth = opts.userAuth === undefined
+        ? tryLoadUserAuth(logger)
+        : opts.userAuth;
+    if (userAuth?.current && !opts.disableControlChannel) {
+        logger.info("control-channel: enabling", {
+            userId: userAuth.current.userId,
+            hubUrl: userAuth.current.hubUrl,
+        });
+        const provisioner = createProvisioner({ gateway });
+        controlChannel = new ControlChannel({
+            auth: userAuth,
+            handle: provisioner,
+        });
+        try {
+            await controlChannel.start();
+            // Plan §8.5 P0 — push one runtime snapshot immediately after connect
+            // so Hub's `daemon_instances.runtimes_json` is populated for the
+            // dashboard even before any user action. No periodic refresh in P0.
+            const pushed = pushRuntimeSnapshot(controlChannel);
+            logger.info("control-channel: initial runtime_snapshot push", {
+                ok: pushed,
+            });
+        }
+        catch (err) {
+            logger.warn("control-channel failed to start; continuing without it", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // start() schedules its own reconnect; we swallow the initial
+            // failure so the daemon boots either way.
+        }
+    }
+    else if (!userAuth?.current) {
+        logger.info("control-channel skipped: no user-auth record", {
+            hint: "run `botcord-daemon start` to enable Hub control plane (device-code login)",
+        });
+    }
+    const snapshotWriter = new SnapshotWriter({
+        path: opts.snapshotPath ?? SNAPSHOT_PATH,
+        intervalMs: opts.snapshotIntervalMs ?? resolveSnapshotIntervalMs(),
+        snapshot: () => gateway.snapshot(),
+        log: logger,
+    });
+    snapshotWriter.start();
+    let stopping = null;
+    const stop = (reason) => {
+        if (stopping)
+            return stopping;
+        logger.info("daemon stopping", { reason: reason ?? null });
+        snapshotWriter.stop();
+        // Write one final snapshot so `status` doesn't briefly see stale data,
+        // then delete the file on the way out.
+        snapshotWriter.writeFinal();
+        const controlStopP = controlChannel
+            ? controlChannel.stop().catch(() => undefined)
+            : Promise.resolve();
+        stopping = Promise.all([controlStopP, gateway.stop(reason)]).then(() => undefined).finally(() => {
+            snapshotWriter.remove();
+            logger.info("daemon stopped", { reason: reason ?? null });
+        });
+        return stopping;
+    };
+    return {
+        stop,
+        snapshot: () => gateway.snapshot(),
+    };
+}
+/**
+ * Walk the boot-agent list and (a) populate the credential-path + runtime
+ * caches used downstream, and (b) idempotently create each agent's on-disk
+ * workspace tree (plan §9). One agent's failing workspace must not block
+ * the others — errors are warned and swallowed per agent. Exported for
+ * unit tests; `startDaemon` calls this inline.
+ */
+export function backfillBootAgents(agents, opts) {
+    const ensure = opts.ensure ?? ensureAgentWorkspace;
+    const credentialPathByAgentId = new Map();
+    const agentRuntimes = {};
+    const failed = [];
+    for (const a of agents) {
+        if (a.credentialsFile)
+            credentialPathByAgentId.set(a.agentId, a.credentialsFile);
+        if (a.runtime || a.cwd) {
+            agentRuntimes[a.agentId] = {
+                ...(a.runtime ? { runtime: a.runtime } : {}),
+                ...(a.cwd ? { cwd: a.cwd } : {}),
+            };
+        }
+        // Seed files are written only when missing (see `ensureAgentWorkspace`),
+        // so a legacy agent whose workspace dir doesn't exist yet gets one on
+        // the next boot — with zero risk of overwriting the user's edits.
+        try {
+            ensure(a.agentId, {
+                ...(a.displayName ? { displayName: a.displayName } : {}),
+                ...(a.runtime ? { runtime: a.runtime } : {}),
+                ...(a.keyId ? { keyId: a.keyId } : {}),
+                ...(a.savedAt ? { savedAt: a.savedAt } : {}),
+                // `bio` is not surfaced on BootAgent — identity.md renders a
+                // placeholder the user can fill in.
+            });
+        }
+        catch (err) {
+            failed.push(a.agentId);
+            opts.logger.warn("ensureAgentWorkspace failed at boot; continuing", {
+                agentId: a.agentId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (failed.length > 0) {
+        opts.logger.warn("ensureAgentWorkspace: boot backfill incomplete", {
+            count: failed.length,
+            agentIds: failed,
+        });
+    }
+    return { credentialPathByAgentId, agentRuntimes };
+}
+/**
+ * Load the user-auth record if present, swallowing "file missing" as the
+ * expected not-logged-in state. A parse / permission error is logged and
+ * treated as "no record" so a broken user-auth.json can't block the
+ * data-plane from coming up.
+ */
+function tryLoadUserAuth(logger) {
+    try {
+        return UserAuthManager.load();
+    }
+    catch (err) {
+        logger.warn("failed to load user-auth", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,89 @@
+import type { RuntimeProbeEntry } from "./adapters/runtimes.js";
+import type { DaemonConfig } from "./config.js";
+/** Summary of a single channel's readiness, printable by the doctor command. */
+export interface ChannelProbeResult {
+    id: string;
+    type: string;
+    accountId: string;
+    credentialsOk: boolean;
+    credentialsMessage: string;
+    hubUrl: string | null;
+    hubOk: boolean;
+    hubMessage: string;
+}
+/** Minimal filesystem surface needed by {@link probeChannel}; injectable for tests. */
+export interface DoctorFileReader {
+    readFile(path: string): string | null;
+}
+/** HTTP GET surface needed by {@link probeChannel}; injectable for tests. */
+export interface DoctorHttpFetcher {
+    (url: string, timeoutMs: number): Promise<DoctorHttpResult>;
+}
+/** Response shape returned by {@link DoctorHttpFetcher}. */
+export interface DoctorHttpResult {
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+/** Input for the rendered doctor output. */
+export interface DoctorInput {
+    runtimes: RuntimeProbeEntry[];
+    channels: ChannelProbeResult[];
+}
+/** Per-channel config entry accepted by {@link probeChannel}. */
+export interface ChannelProbeConfig {
+    id: string;
+    type: string;
+    accountId: string;
+    /**
+     * Optional explicit credential file path. When set, wins over the
+     * default `~/.botcord/credentials/<accountId>.json` used by
+     * `probeChannel`'s fallback. Populated by discovery to surface the
+     * exact file that would be loaded at start.
+     */
+    credentialsFile?: string;
+}
+/** Top-level options for {@link probeChannels}. */
+export interface ProbeChannelsOptions {
+    channels: ChannelProbeConfig[];
+    credentialsPath: (accountId: string) => string;
+    fileReader: DoctorFileReader;
+    fetcher: DoctorHttpFetcher;
+    timeoutMs?: number;
+}
+/**
+ * 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 declare function channelsFromDaemonConfig(cfg: DaemonConfig): ChannelProbeConfig[];
+/**
+ * Inspect credentials + Hub reachability for one channel. Pure modulo the
+ * injected file reader and fetcher.
+ */
+export declare function probeChannel(ch: ChannelProbeConfig, opts: {
+    credentialsPath: (accountId: string) => string;
+    fileReader: DoctorFileReader;
+    fetcher: DoctorHttpFetcher;
+    timeoutMs: number;
+}): Promise<ChannelProbeResult>;
+/** Probe a list of channels sequentially. Sequential keeps output stable. */
+export declare function probeChannels(opts: ProbeChannelsOptions): Promise<ChannelProbeResult[]>;
+/** Default HTTP fetcher using `fetch` + `AbortController` timeout. */
+export declare const defaultHttpFetcher: DoctorHttpFetcher;
+/**
+ * Render runtime + channel probe output. Pure — all IO happened already.
+ * Used by the CLI `doctor` command and by unit tests.
+ */
+export declare function renderDoctor(input: DoctorInput): string;
+/**
+ * Thin orchestrator: runs runtime + channel probes and returns the rendered
+ * text. Keeps `index.ts` free of probe wiring.
+ */
+export declare function runDoctor(runtimes: RuntimeProbeEntry[], channels: ChannelProbeConfig[], opts: {
+    credentialsPath: (accountId: string) => string;
+    fileReader: DoctorFileReader;
+    fetcher: DoctorHttpFetcher;
+    timeoutMs?: number;
+}): Promise<DoctorInput>;