@botcord/daemon 0.1.1

package/dist/activity-tracker.d.ts

@@ -0,0 +1,43 @@
+export declare const ACTIVITY_PATH: string;
+/** Max preview length per entry — keeps the digest tight + cap bytes on disk. */
+export declare const ACTIVITY_PREVIEW_CHARS = 120;
+export interface ActivityEntry {
+    agentId: string;
+    roomId: string;
+    roomName?: string;
+    topic: string | null;
+    lastActivityAt: number;
+    /** Sanitized snippet of the last inbound message; may be empty. */
+    lastInboundPreview: string;
+    /** What kind of peer spoke last: "agent" | "human" | "owner". */
+    lastSenderKind: "agent" | "human" | "owner";
+    lastSender: string;
+}
+export declare class ActivityTracker {
+    private data;
+    private loaded;
+    private flushScheduled;
+    private readonly filePath;
+    constructor(opts?: {
+        filePath?: string;
+    });
+    private load;
+    record(entry: Omit<ActivityEntry, "lastActivityAt"> & {
+        lastActivityAt?: number;
+    }): void;
+    get(agentId: string, roomId: string, topic: string | null): ActivityEntry | null;
+    /**
+     * Return entries for a given agent, ordered most-recent first and filtered
+     * to activity within `windowMs`. When `excludeKey` is provided, the matching
+     * entry (the caller's current turn) is removed.
+     */
+    listActive(opts: {
+        agentId: string;
+        windowMs?: number;
+        excludeKey?: string;
+    }): ActivityEntry[];
+    keyFor(agentId: string, roomId: string, topic: string | null): string;
+    private scheduleFlush;
+    /** Synchronous atomic write. Safe from signal handlers. */
+    flushSync(): void;
+}

package/dist/activity-tracker.js

@@ -0,0 +1,110 @@
+/**
+ * Activity tracker — per-(agent, room, topic) record of the most recent
+ * inbound message, regardless of whether the subsequent turn succeeded.
+ *
+ * Why not reuse SessionStore? SessionStore is only written after the adapter
+ * returns `newSessionId`, which skips turns that errored, timed out, were
+ * cancelled, or ran on an adapter that doesn't do resume (Codex after 方案 A).
+ * The cross-room digest needs to reflect "which rooms am I actually talking
+ * in right now", so it reads from here instead.
+ *
+ * Stored at `<DAEMON_DIR>/activity.json`. Atomic write, 0o600.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { DAEMON_DIR_PATH } from "./config.js";
+export const ACTIVITY_PATH = path.join(DAEMON_DIR_PATH, "activity.json");
+/** Max preview length per entry — keeps the digest tight + cap bytes on disk. */
+export const ACTIVITY_PREVIEW_CHARS = 120;
+function keyOf(agentId, roomId, topic) {
+    return topic ? `${agentId}:${roomId}:${topic}` : `${agentId}:${roomId}`;
+}
+export class ActivityTracker {
+    data = { version: 1, entries: {} };
+    loaded = false;
+    flushScheduled = false;
+    filePath;
+    constructor(opts) {
+        this.filePath = opts?.filePath ?? ACTIVITY_PATH;
+    }
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(this.filePath, "utf-8"));
+            if (raw && raw.entries && typeof raw.entries === "object") {
+                this.data = { version: 1, entries: raw.entries };
+            }
+        }
+        catch {
+            // Corrupt file — start fresh rather than crashing.
+            this.data = { version: 1, entries: {} };
+        }
+    }
+    record(entry) {
+        this.load();
+        const key = keyOf(entry.agentId, entry.roomId, entry.topic);
+        const stored = {
+            ...entry,
+            lastInboundPreview: entry.lastInboundPreview.slice(0, ACTIVITY_PREVIEW_CHARS),
+            lastActivityAt: entry.lastActivityAt ?? Date.now(),
+        };
+        this.data.entries[key] = stored;
+        this.scheduleFlush();
+    }
+    get(agentId, roomId, topic) {
+        this.load();
+        return this.data.entries[keyOf(agentId, roomId, topic)] ?? null;
+    }
+    /**
+     * Return entries for a given agent, ordered most-recent first and filtered
+     * to activity within `windowMs`. When `excludeKey` is provided, the matching
+     * entry (the caller's current turn) is removed.
+     */
+    listActive(opts) {
+        this.load();
+        const window = opts.windowMs ?? 2 * 60 * 60 * 1000;
+        const cutoff = Date.now() - window;
+        const out = [];
+        for (const [k, e] of Object.entries(this.data.entries)) {
+            if (e.agentId !== opts.agentId)
+                continue;
+            if (e.lastActivityAt < cutoff)
+                continue;
+            if (opts.excludeKey && k === opts.excludeKey)
+                continue;
+            out.push(e);
+        }
+        out.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+        return out;
+    }
+    keyFor(agentId, roomId, topic) {
+        return keyOf(agentId, roomId, topic);
+    }
+    scheduleFlush() {
+        if (this.flushScheduled)
+            return;
+        this.flushScheduled = true;
+        setImmediate(() => {
+            this.flushScheduled = false;
+            this.flushSync();
+        });
+    }
+    /** Synchronous atomic write. Safe from signal handlers. */
+    flushSync() {
+        if (!this.loaded)
+            return;
+        try {
+            mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+        }
+        catch {
+            // best-effort
+        }
+        const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(this.data, null, 2), { mode: 0o600 });
+        renameSync(tmp, this.filePath);
+    }
+}

package/dist/adapters/runtimes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Thin pass-through to the local gateway module's runtime registry. The daemon CLI
+ * (`doctor`, `config`, `init`, `route`) uses these to probe, list, and
+ * validate adapter ids.
+ */
+import { type RuntimeModule, type RuntimeProbeEntry as GatewayRuntimeProbeEntry } from "../gateway/index.js";
+/** Lookup an adapter module by id, or null when the id is unknown. */
+export declare function getAdapterModule(id: string): RuntimeModule | null;
+/** All registered adapter ids in registration order. */
+export declare function listAdapterIds(): string[];
+/** One probe result per registered adapter, for `doctor`-style listings. */
+export type RuntimeProbeEntry = GatewayRuntimeProbeEntry;
+/** Probe every registered adapter and report installation status. */
+export declare function detectRuntimes(): RuntimeProbeEntry[];

package/dist/adapters/runtimes.js

@@ -0,0 +1,18 @@
+/**
+ * Thin pass-through to the local gateway module's runtime registry. The daemon CLI
+ * (`doctor`, `config`, `init`, `route`) uses these to probe, list, and
+ * validate adapter ids.
+ */
+import { detectRuntimes as gatewayDetectRuntimes, getRuntimeModule, listRuntimeIds, } from "../gateway/index.js";
+/** Lookup an adapter module by id, or null when the id is unknown. */
+export function getAdapterModule(id) {
+    return getRuntimeModule(id);
+}
+/** All registered adapter ids in registration order. */
+export function listAdapterIds() {
+    return listRuntimeIds();
+}
+/** Probe every registered adapter and report installation status. */
+export function detectRuntimes() {
+    return gatewayDetectRuntimes();
+}

package/dist/agent-discovery.d.ts

@@ -0,0 +1,81 @@
+import { type Stats } from "node:fs";
+import { type StoredBotCordCredentials } from "@botcord/protocol-core";
+import type { DaemonConfig } from "./config.js";
+/**
+ * Default location daemon looks at when discovering BotCord credentials at
+ * boot. Matches the path the `botcord` CLI and plugin write to.
+ */
+export declare const DEFAULT_CREDENTIALS_DIR: string;
+/**
+ * One local BotCord identity discovered at boot. The canonical id is the
+ * credential file's internal `agentId`, not the filename — a stale copy
+ * saved under a wrong name still binds to its true agent.
+ */
+export interface DiscoveredAgentCredential {
+    agentId: string;
+    credentialsFile: string;
+    hubUrl: string;
+    displayName?: string;
+    /**
+     * Runtime cached in the credentials file (docs/agent-runtime-property-plan.md).
+     * Null for legacy bind-code credentials without the field; the daemon
+     * falls back to `defaultRoute` in that case.
+     */
+    runtime?: string;
+    /** Working directory cached alongside `runtime`. */
+    cwd?: string;
+    /** Key id from the credentials file — surfaced so boot-time workspace
+     * seeding (see daemon-agent-workspace-plan.md §9) can render identity.md
+     * without re-reading the file. */
+    keyId?: string;
+    /** ISO timestamp of when the credentials file was written. */
+    savedAt?: string;
+}
+/** Result of one discovery pass — explicit about what was dropped and why. */
+export interface AgentDiscoveryResult {
+    agents: DiscoveredAgentCredential[];
+    warnings: string[];
+}
+/** Minimal surface the discovery module needs from `node:fs`. Injectable for tests. */
+export interface DiscoveryFs {
+    readDir?: (dir: string) => string[];
+    stat?: (p: string) => Stats;
+    loadCredentials?: (file: string) => StoredBotCordCredentials;
+}
+export interface DiscoveryOptions extends DiscoveryFs {
+    /** Directory to scan. Defaults to {@link DEFAULT_CREDENTIALS_DIR}. */
+    credentialsDir?: string;
+}
+/**
+ * Scan the credentials directory and return one entry per valid BotCord
+ * credential file. Tolerant by design: missing directory, non-JSON files,
+ * unparseable JSON, credentials missing required fields, and duplicate
+ * `agentId` entries are all skipped with a warning — never thrown.
+ *
+ * Duplicate policy is deterministic: prefer the file with the newer
+ * `mtimeMs`; if equal/unavailable, prefer lexical path order. This avoids
+ * surprising channel selection when stale copies sit alongside fresh ones.
+ */
+export declare function discoverAgentCredentials(opts?: DiscoveryOptions): AgentDiscoveryResult;
+/** Result of composing explicit config + discovery into the final boot list. */
+export interface BootAgentsResult {
+    /** Ordered list of agents the daemon should bind channels for. */
+    agents: DiscoveredAgentCredential[];
+    /** "config" — explicit `agents`/`agentId`; "credentials" — discovery. */
+    source: "config" | "credentials";
+    /** Resolved discovery directory (informational, for logs/status). */
+    credentialsDir: string;
+    /** Non-fatal issues surfaced by discovery, passed through for logging. */
+    warnings: string[];
+}
+/**
+ * Resolve the list of agents the daemon should bind at boot.
+ *
+ * Order of precedence:
+ *   1. `cfg.agents` / legacy `cfg.agentId` — channel credentials default to
+ *      `~/.botcord/credentials/<agentId>.json`.
+ *   2. If neither is set, discover credentials from disk (unless
+ *      `agentDiscovery.enabled === false`, in which case the caller should
+ *      already have errored in `loadConfig`).
+ */
+export declare function resolveBootAgents(cfg: DaemonConfig, opts?: DiscoveryOptions): BootAgentsResult;

package/dist/agent-discovery.js

@@ -0,0 +1,181 @@
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { defaultCredentialsFile, loadStoredCredentials, } from "@botcord/protocol-core";
+import { resolveConfiguredAgentIds } from "./config.js";
+import { log as daemonLog } from "./log.js";
+/**
+ * Default location daemon looks at when discovering BotCord credentials at
+ * boot. Matches the path the `botcord` CLI and plugin write to.
+ */
+export const DEFAULT_CREDENTIALS_DIR = path.join(homedir(), ".botcord", "credentials");
+/**
+ * Scan the credentials directory and return one entry per valid BotCord
+ * credential file. Tolerant by design: missing directory, non-JSON files,
+ * unparseable JSON, credentials missing required fields, and duplicate
+ * `agentId` entries are all skipped with a warning — never thrown.
+ *
+ * Duplicate policy is deterministic: prefer the file with the newer
+ * `mtimeMs`; if equal/unavailable, prefer lexical path order. This avoids
+ * surprising channel selection when stale copies sit alongside fresh ones.
+ */
+export function discoverAgentCredentials(opts = {}) {
+    const dir = opts.credentialsDir ?? DEFAULT_CREDENTIALS_DIR;
+    const readDir = opts.readDir ?? ((d) => readdirSync(d));
+    const stat = opts.stat ?? ((p) => statSync(p));
+    const loadCreds = opts.loadCredentials ?? loadStoredCredentials;
+    const warnings = [];
+    let entries;
+    try {
+        entries = readDir(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            daemonLog.debug("credentials dir missing", { dir });
+            return { agents: [], warnings };
+        }
+        warnings.push(`credentials dir unreadable (${dir}): ${errMsg(err)}`);
+        return { agents: [], warnings };
+    }
+    daemonLog.debug("credentials dir scan", { dir, entryCount: entries.length });
+    // Sort filenames lexically so the duplicate tie-breaker is deterministic
+    // regardless of filesystem ordering.
+    const files = entries
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => path.join(dir, name))
+        .sort();
+    const byAgent = new Map();
+    for (const file of files) {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = stat(file).mtimeMs;
+        }
+        catch {
+            // mtime is best-effort; fall back to 0 so lexical order wins ties.
+        }
+        let creds;
+        try {
+            creds = loadCreds(file);
+        }
+        catch (err) {
+            warnings.push(`invalid credentials at ${file}: ${errMsg(err)}`);
+            continue;
+        }
+        if (typeof creds.agentId !== "string" || creds.agentId.length === 0) {
+            warnings.push(`credentials at ${file} missing agentId; skipped`);
+            continue;
+        }
+        const existing = byAgent.get(creds.agentId);
+        if (!existing) {
+            byAgent.set(creds.agentId, { creds, credentialsFile: file, mtimeMs });
+            continue;
+        }
+        // Duplicate: pick newer mtime; ties fall through to the entry we saw
+        // first (lexically earlier thanks to the sort above).
+        if (mtimeMs > existing.mtimeMs) {
+            warnings.push(`duplicate agentId "${creds.agentId}": preferring ${file} over ${existing.credentialsFile} (newer mtime)`);
+            byAgent.set(creds.agentId, { creds, credentialsFile: file, mtimeMs });
+        }
+        else {
+            warnings.push(`duplicate agentId "${creds.agentId}": keeping ${existing.credentialsFile}, ignoring ${file}`);
+        }
+    }
+    const agents = [];
+    for (const { creds, credentialsFile } of byAgent.values()) {
+        const entry = {
+            agentId: creds.agentId,
+            credentialsFile,
+            hubUrl: creds.hubUrl,
+        };
+        if (creds.displayName)
+            entry.displayName = creds.displayName;
+        if (creds.runtime)
+            entry.runtime = creds.runtime;
+        if (creds.cwd)
+            entry.cwd = creds.cwd;
+        if (creds.keyId)
+            entry.keyId = creds.keyId;
+        if (creds.savedAt)
+            entry.savedAt = creds.savedAt;
+        agents.push(entry);
+    }
+    // Stable order for downstream channel creation / logs.
+    agents.sort((a, b) => a.agentId.localeCompare(b.agentId));
+    daemonLog.debug("credentials discovery done", {
+        dir,
+        agentCount: agents.length,
+        warningCount: warnings.length,
+    });
+    return { agents, warnings };
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Resolve the list of agents the daemon should bind at boot.
+ *
+ * Order of precedence:
+ *   1. `cfg.agents` / legacy `cfg.agentId` — channel credentials default to
+ *      `~/.botcord/credentials/<agentId>.json`.
+ *   2. If neither is set, discover credentials from disk (unless
+ *      `agentDiscovery.enabled === false`, in which case the caller should
+ *      already have errored in `loadConfig`).
+ */
+export function resolveBootAgents(cfg, opts = {}) {
+    const credentialsDir = opts.credentialsDir ?? cfg.agentDiscovery?.credentialsDir ?? DEFAULT_CREDENTIALS_DIR;
+    const explicit = resolveConfiguredAgentIds(cfg);
+    daemonLog.debug("resolveBootAgents", {
+        credentialsDir,
+        source: explicit ? "config" : "credentials",
+        explicitCount: explicit?.length ?? 0,
+    });
+    if (explicit) {
+        // Best-effort enrich with runtime/cwd cached in credentials. A missing
+        // or unreadable file is not fatal — the gateway channel will surface the
+        // real error at start. The fields we're after are purely for router
+        // fallback (docs/agent-runtime-property-plan.md §4.3).
+        const agents = explicit.map((agentId) => {
+            const credentialsFile = defaultCredentialsFile(agentId);
+            const entry = {
+                agentId,
+                credentialsFile,
+                hubUrl: "",
+            };
+            const load = opts.loadCredentials ?? loadStoredCredentials;
+            try {
+                const creds = load(credentialsFile);
+                if (creds.hubUrl)
+                    entry.hubUrl = creds.hubUrl;
+                if (creds.displayName)
+                    entry.displayName = creds.displayName;
+                if (creds.runtime)
+                    entry.runtime = creds.runtime;
+                if (creds.cwd)
+                    entry.cwd = creds.cwd;
+                if (creds.keyId)
+                    entry.keyId = creds.keyId;
+                if (creds.savedAt)
+                    entry.savedAt = creds.savedAt;
+            }
+            catch (err) {
+                // Silent on any read failure: the file may not exist yet (it gets
+                // written by provision flows or legacy CLI) and the gateway channel
+                // is the one that surfaces real errors at start. This enrichment
+                // is purely opportunistic — missing runtime/cwd just means the
+                // router falls back to `defaultRoute`, which is the pre-plan
+                // behavior.
+                void err;
+            }
+            return entry;
+        });
+        return { agents, source: "config", credentialsDir, warnings: [] };
+    }
+    const discovery = discoverAgentCredentials({ ...opts, credentialsDir });
+    return {
+        agents: discovery.agents,
+        source: "credentials",
+        credentialsDir,
+        warnings: discovery.warnings,
+    };
+}

package/dist/agent-workspace.d.ts

@@ -0,0 +1,31 @@
+export declare function agentHomeDir(agentId: string): string;
+export declare function agentWorkspaceDir(agentId: string): string;
+export declare function agentStateDir(agentId: string): string;
+/**
+ * Per-agent CODEX_HOME. The codex adapter sets the `CODEX_HOME` env var
+ * to this path so codex reads a daemon-managed `AGENTS.md` (written fresh
+ * each turn with the agent's systemContext) and stores its `sessions/`
+ * here — neither touching `~/.codex/` nor the agent's `workspace/` cwd.
+ */
+export declare function agentCodexHomeDir(agentId: string): string;
+export interface WorkspaceSeed {
+    displayName?: string;
+    bio?: string;
+    runtime?: string;
+    keyId?: string;
+    /** ISO timestamp. */
+    savedAt?: string;
+}
+/**
+ * Idempotently create the per-agent CODEX_HOME directory and link the
+ * user's codex `auth.json` into it. Does NOT write an initial `AGENTS.md`
+ * — the codex adapter writes it fresh per turn from `systemContext`.
+ */
+export declare function ensureAgentCodexHome(agentId: string): string;
+/**
+ * Idempotently create the agent's home / workspace / state directories and
+ * seed the workspace Markdown files. Existing files are never overwritten —
+ * users' edits to AGENTS.md, memory.md, etc. are preserved across calls.
+ * State files are not touched here; working-memory.ts owns `state/`.
+ */
+export declare function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void;