@botcord/daemon 0.2.4 → 0.2.6

package/dist/index.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync, rmSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import path from "node:path";
-import { loadConfig, saveConfig, initDefaultConfig, resolveConfiguredAgentIds, PID_PATH, SNAPSHOT_PATH, CONFIG_FILE_PATH, } from "./config.js";
+import { loadConfig, saveConfig, initDefaultConfig, resolveConfiguredAgentIds, PID_PATH, SNAPSHOT_PATH, CONFIG_FILE_PATH, CONFIG_MISSING, } from "./config.js";
 import { resolveBootAgents } from "./agent-discovery.js";
+import { defaultTranscriptRoot, resolveTranscriptEnabled, transcriptAgentRoot, transcriptFilePath, } from "./gateway/index.js";
 import { startDaemon } from "./daemon.js";
 import { log, LOG_FILE_PATH } from "./log.js";
 import { detectRuntimes, getAdapterModule, listAdapterIds } from "./adapters/runtimes.js";
 import { pollDeviceToken, requestDeviceCode, } from "@botcord/protocol-core";
 import { AUTH_EXPIRED_FLAG_PATH, clearAuthExpiredFlag, loadUserAuth, saveUserAuth, userAuthFromTokenResponse, } from "./user-auth.js";
 import { renderStatus } from "./status-render.js";
+import { appendNextParam } from "./url-utils.js";
 import { channelsFromDaemonConfig, defaultHttpFetcher, renderDoctor, runDoctor, } from "./doctor.js";
 import { clearWorkingMemory, readWorkingMemory, resolveMemoryDir, updateWorkingMemory, DEFAULT_SECTION, } from "./working-memory.js";
 const ADAPTER_LIST = listAdapterIds().join("|");
@@ -29,12 +31,8 @@ const HELP = `botcord-daemon — BotCord local daemon
 Usage: botcord-daemon <command> [options]
 
 Commands:
-  init [--agent <ag_xxx> ...] [--cwd <path>]
-                                          Create ~/.botcord/daemon/config.json.
-                                          Without --agent, the daemon discovers
-                                          identities from ~/.botcord/credentials
-                                          at startup (repeat --agent to pin).
   start [--background|-d] [--relogin] [--hub <url>] [--label <name>]
+        [--agent <ag_xxx> ...] [--cwd <path>]
                                           Start the daemon in the foreground by
                                           default. Pass --background (alias -d)
                                           to detach and return to the shell.
@@ -48,9 +46,24 @@ Commands:
                                           (defaults to hostname). Non-TTY
                                           environments must mount a pre-existing
                                           user-auth.json (plan §6.4).
+                                          On first run, auto-creates
+                                          ~/.botcord/daemon/config.json with a
+                                          default route (claude-code, $HOME) and
+                                          credential auto-discovery. Pass
+                                          --agent/--cwd to seed the file
+                                          (ignored once config exists).
   stop                                    Stop the running daemon (SIGTERM)
   status                                  Print daemon status (pid, agent)
   logs [-f]                               Print log tail (use -f to follow)
+  transcript enable|disable|status        Toggle persistent transcript logging
+  transcript list --agent <ag_xxx>        List rooms with transcripts for an agent
+  transcript tail --agent <ag_xxx> --room <rm_xxx> [--topic <tp>] [-n 50] [-f]
+                                          Tail recent transcript records (NDJSON)
+  transcript dump --agent <ag_xxx> --room <rm_xxx> [--topic <tp>]
+                                          Print full transcript file to stdout
+  transcript prune --agent <ag_xxx> [--older-than 30d] [--all]
+                                          Remove rotated transcript files (or all
+                                          for the agent with --all --yes)
   route add [match flags] --adapter <${ADAPTER_LIST}> --cwd <path>
       match flags (first match wins; at least one conversation/sender selector required):
         --conversation-id <rm_xxx>        (alias: --room <rm_xxx>)
@@ -154,19 +167,32 @@ function pidAlive(pid) {
         return false;
     }
 }
-async function cmdInit(args) {
-    // `--agent` is optional as of P1: when omitted, the daemon discovers
-    // agent identities from `~/.botcord/credentials/*.json` at startup.
-    // Every repeated `--agent ag_xxx` still pins an explicit id (the
-    // canonical `agents: [...]` config shape).
-    const agents = args.lists.agent ?? [];
-    const cwd = typeof args.flags.cwd === "string" ? path.resolve(args.flags.cwd) : homedir();
-    log.info("cmd init", { agents, cwd });
-    const cfg = initDefaultConfig(agents, cwd);
-    saveConfig(cfg);
-    console.log(`wrote ${CONFIG_FILE_PATH}`);
-    if (agents.length === 0) {
-        console.log("no --agent provided; daemon will auto-discover identities from ~/.botcord/credentials at start");
+/**
+ * Load the daemon config, auto-creating `~/.botcord/daemon/config.json`
+ * with sensible defaults on first run. `--agent` (repeated) pins explicit
+ * agent ids; `--cwd` overrides the defaultRoute working directory. Both
+ * are seed-only — they are ignored once a config already exists, since
+ * `route` and direct edits to `config.json` are the canonical way to
+ * change a configured daemon.
+ */
+function loadOrInitConfig(args) {
+    try {
+        return loadConfig();
+    }
+    catch (err) {
+        const missing = err instanceof Error && err.code === CONFIG_MISSING;
+        if (!missing)
+            throw err;
+        const agents = args.lists.agent ?? [];
+        const cwd = typeof args.flags.cwd === "string" ? path.resolve(args.flags.cwd) : homedir();
+        const cfg = initDefaultConfig(agents, cwd);
+        saveConfig(cfg);
+        log.info("auto-initialized daemon config", { agents, cwd, path: CONFIG_FILE_PATH });
+        console.log(`wrote default config to ${CONFIG_FILE_PATH}`);
+        if (agents.length === 0) {
+            console.log("no --agent provided; daemon will auto-discover identities from ~/.botcord/credentials");
+        }
+        return cfg;
     }
 }
 /**
@@ -200,10 +226,15 @@ async function runDeviceCodeFlow(opts) {
         label: opts.label ?? null,
     });
     const dc = await requestDeviceCode(opts.hubUrl, opts.label ? { label: opts.label } : undefined);
-    const display = dc.verificationUriComplete ?? dc.verificationUri;
+    const base = dc.verificationUriComplete ?? dc.verificationUri;
+    const display = appendNextParam(base, "/settings/daemons");
+    console.log("");
+    console.log("Open this URL in a browser where you're signed in to BotCord");
+    console.log("(typically your laptop, NOT this machine):");
+    console.log("");
+    console.log(`  ${display}`);
     console.log("");
-    console.log(`Visit ${display}`);
-    console.log(`Code: ${dc.userCode}`);
+    console.log(`Or enter this code at ${dc.verificationUri}: ${dc.userCode}`);
     console.log("Waiting for authorization (Ctrl-C to abort)...");
     const expiresAt = Date.now() + dc.expiresIn * 1000;
     let intervalSec = dc.interval;
@@ -289,7 +320,7 @@ async function ensureUserAuthForStart(args) {
     return runDeviceCodeFlow({ hubUrl, label });
 }
 async function cmdStart(args) {
-    const cfg = loadConfig();
+    const cfg = loadOrInitConfig(args);
     // Foreground is now the default. --background (alias -d) detaches.
     // --foreground is still accepted (no-op) for backwards compatibility and
     // is also what the detached child re-execs itself with.
@@ -492,6 +523,222 @@ async function cmdLogs(args) {
     const lines = data.split("\n");
     console.log(lines.slice(-100).join("\n"));
 }
+// ---------------------------------------------------------------------------
+// transcript subcommands (design §5)
+// ---------------------------------------------------------------------------
+function transcriptStringFlag(args, name) {
+    const v = args.flags[name];
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+function parseDurationToMs(s) {
+    const m = /^(\d+)\s*([smhd])?$/.exec(s.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = m[2] ?? "d";
+    const mult = {
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return n * mult[unit];
+}
+async function cmdTranscript(args) {
+    switch (args.sub) {
+        case "enable":
+            return cmdTranscriptToggle(true);
+        case "disable":
+            return cmdTranscriptToggle(false);
+        case "status":
+            return cmdTranscriptStatus();
+        case "list":
+            return cmdTranscriptList(args);
+        case "tail":
+            return cmdTranscriptTail(args);
+        case "dump":
+            return cmdTranscriptDump(args);
+        case "prune":
+            return cmdTranscriptPrune(args);
+        default:
+            console.error("usage: botcord-daemon transcript <enable|disable|status|list|tail|dump|prune>");
+            process.exit(1);
+    }
+}
+function cmdTranscriptToggle(enable) {
+    let cfg;
+    try {
+        cfg = loadConfig();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === CONFIG_MISSING) {
+            console.error(`daemon config not found — run \`botcord-daemon start\` once to initialize, then retry`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    cfg.transcript = { ...(cfg.transcript ?? {}), enabled: enable };
+    saveConfig(cfg);
+    console.log(`transcript persistence ${enable ? "enabled" : "disabled"} (next daemon start)`);
+}
+function cmdTranscriptStatus() {
+    let cfg = null;
+    try {
+        cfg = loadConfig();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code !== CONFIG_MISSING)
+            throw err;
+    }
+    const configEnabled = cfg?.transcript?.enabled === true;
+    const env = process.env.BOTCORD_TRANSCRIPT;
+    const effective = resolveTranscriptEnabled(env, configEnabled);
+    let source;
+    if (env === "1" || env === "0")
+        source = `env BOTCORD_TRANSCRIPT=${env}`;
+    else if (configEnabled)
+        source = "config (transcript.enabled=true)";
+    else
+        source = "default-off";
+    console.log(`enabled: ${effective}`);
+    console.log(`source: ${source}`);
+    console.log(`root: ${defaultTranscriptRoot()}`);
+}
+function cmdTranscriptList(args) {
+    const agent = transcriptStringFlag(args, "agent");
+    if (!agent) {
+        console.error("transcript list requires --agent <ag_xxx>");
+        process.exit(1);
+    }
+    const root = transcriptAgentRoot(defaultTranscriptRoot(), agent);
+    if (!existsSync(root)) {
+        return; // no rooms → empty output
+    }
+    for (const entry of readdirSync(root)) {
+        const dir = path.join(root, entry);
+        let st;
+        try {
+            st = statSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue;
+        console.log(entry);
+    }
+}
+function cmdTranscriptTail(args) {
+    const agent = transcriptStringFlag(args, "agent");
+    const room = transcriptStringFlag(args, "room");
+    if (!agent || !room) {
+        console.error("transcript tail requires --agent <ag_xxx> --room <rm_xxx>");
+        process.exit(1);
+    }
+    const topic = transcriptStringFlag(args, "topic");
+    const file = transcriptFilePath(defaultTranscriptRoot(), agent, room, topic);
+    if (!existsSync(file)) {
+        console.error(`no transcript at ${file}`);
+        process.exit(1);
+    }
+    const follow = args.flags.f === true || args.flags.follow === true;
+    const nFlag = transcriptStringFlag(args, "n");
+    const n = nFlag && /^\d+$/.test(nFlag) ? Number(nFlag) : 50;
+    if (follow) {
+        const child = spawn("tail", ["-n", String(n), "-f", file], { stdio: "inherit" });
+        process.on("SIGINT", () => child.kill("SIGINT"));
+        return new Promise((resolve) => {
+            child.on("close", () => resolve());
+        });
+    }
+    const data = readFileSync(file, "utf8");
+    const lines = data.split("\n").filter((l) => l.length > 0);
+    console.log(lines.slice(-n).join("\n"));
+}
+function cmdTranscriptDump(args) {
+    const agent = transcriptStringFlag(args, "agent");
+    const room = transcriptStringFlag(args, "room");
+    if (!agent || !room) {
+        console.error("transcript dump requires --agent <ag_xxx> --room <rm_xxx>");
+        process.exit(1);
+    }
+    const topic = transcriptStringFlag(args, "topic");
+    const file = transcriptFilePath(defaultTranscriptRoot(), agent, room, topic);
+    if (!existsSync(file)) {
+        console.error(`no transcript at ${file}`);
+        process.exit(1);
+    }
+    process.stdout.write(readFileSync(file, "utf8"));
+}
+function cmdTranscriptPrune(args) {
+    const agent = transcriptStringFlag(args, "agent");
+    if (!agent) {
+        console.error("transcript prune requires --agent <ag_xxx>");
+        process.exit(1);
+    }
+    const all = args.flags.all === true;
+    const olderThanFlag = transcriptStringFlag(args, "older-than");
+    const yes = args.flags.yes === true;
+    const root = transcriptAgentRoot(defaultTranscriptRoot(), agent);
+    if (!existsSync(root))
+        return;
+    if (all) {
+        if (!yes) {
+            console.error(`transcript prune --all will delete every transcript under ${root}; rerun with --yes to confirm`);
+            process.exit(1);
+        }
+        rmSync(root, { recursive: true, force: true });
+        console.log(`removed ${root}`);
+        return;
+    }
+    // Default and --older-than: prune rotated files only (the "{topic}.STAMP.jsonl" form).
+    // Active files (`{topic}.jsonl` / `_default.jsonl`) are never touched.
+    const cutoffMs = olderThanFlag ? parseDurationToMs(olderThanFlag) : null;
+    if (olderThanFlag && cutoffMs === null) {
+        console.error(`transcript prune --older-than: invalid duration "${olderThanFlag}" (use 30d / 12h / 30m / 60s)`);
+        process.exit(1);
+    }
+    const cutoff = cutoffMs !== null ? Date.now() - cutoffMs : null;
+    let removed = 0;
+    for (const roomEntry of readdirSync(root)) {
+        const dir = path.join(root, roomEntry);
+        let st;
+        try {
+            st = statSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue;
+        for (const f of readdirSync(dir)) {
+            // rotated files: <topic>.<YYYYMMDD-HHMMSS>.jsonl — must contain a stamp segment
+            if (!/^.+\.\d{8}-\d{6}\.jsonl$/.test(f))
+                continue;
+            const full = path.join(dir, f);
+            if (cutoff !== null) {
+                try {
+                    const fst = statSync(full);
+                    if (fst.mtimeMs >= cutoff)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+            }
+            try {
+                unlinkSync(full);
+                removed += 1;
+            }
+            catch (err) {
+                console.error(`failed to remove ${full}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    console.log(`removed ${removed} rotated transcript file(s)`);
+}
 function formatRouteMatch(m) {
     const parts = [];
     if (m.channel)
@@ -793,13 +1040,25 @@ async function cmdDoctor(args) {
     // Doctor should not hard-fail when no config exists yet; channel probes
     // simply produce an empty list in that case.
     let channels = [];
+    let cfgForEndpoints = null;
     try {
         const cfg = loadConfig();
+        cfgForEndpoints = cfg;
         channels = channelsFromDaemonConfig(cfg);
     }
     catch {
         channels = [];
     }
+    if (cfgForEndpoints?.openclawGateways && cfgForEndpoints.openclawGateways.length > 0) {
+        const { collectRuntimeSnapshotAsync } = await import("./provision.js");
+        const snap = await collectRuntimeSnapshotAsync({ cfg: cfgForEndpoints });
+        const byId = new Map(snap.runtimes.map((r) => [r.id, r]));
+        for (const e of entries) {
+            const r = byId.get(e.id);
+            if (r?.endpoints)
+                e.endpoints = r.endpoints;
+        }
+    }
     const credentialsPath = (accountId) => path.join(homedir(), ".botcord", "credentials", `${accountId}.json`);
     const input = await runDoctor(entries, channels, {
         credentialsPath,
@@ -821,9 +1080,6 @@ async function main() {
     }
     try {
         switch (args.cmd) {
-            case "init":
-                await cmdInit(args);
-                break;
             case "start":
                 await cmdStart(args);
                 break;
@@ -836,6 +1092,9 @@ async function main() {
             case "logs":
                 await cmdLogs(args);
                 break;
+            case "transcript":
+                await cmdTranscript(args);
+                break;
             case "route":
                 await cmdRoute(args);
                 break;

package/dist/mention-scan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mention text-fallback (design §4.2). The Hub's `messages.mentioned` flag is
+ * sender-supplied and therefore not trustworthy on its own; we OR it with a
+ * local scan for `@<display_name>` or `@<agent_id>` so an agent that the
+ * sender forgot (or refused) to mark mentioned still wakes when addressed.
+ *
+ * Kept tiny and synchronous — runs on every inbound message. Both inputs are
+ * normalized to lowercase to keep the match case-insensitive.
+ */
+export interface MentionTargets {
+    /** Daemon-known agent id (e.g. `ag_xxx`). Always included when present. */
+    agentId?: string;
+    /** Display name from the agent's credentials. */
+    displayName?: string;
+}
+/**
+ * Return `true` when `text` contains an `@`-prefixed mention of `agentId`
+ * or `displayName`. Matches a literal `@` followed by the target — both the
+ * `@` and the target are required because plain occurrences of the
+ * displayName in conversation should NOT count as a mention.
+ */
+export declare function scanMention(text: string | undefined, targets: MentionTargets): boolean;

package/dist/mention-scan.js

@@ -0,0 +1,35 @@
+/**
+ * Mention text-fallback (design §4.2). The Hub's `messages.mentioned` flag is
+ * sender-supplied and therefore not trustworthy on its own; we OR it with a
+ * local scan for `@<display_name>` or `@<agent_id>` so an agent that the
+ * sender forgot (or refused) to mark mentioned still wakes when addressed.
+ *
+ * Kept tiny and synchronous — runs on every inbound message. Both inputs are
+ * normalized to lowercase to keep the match case-insensitive.
+ */
+/**
+ * Return `true` when `text` contains an `@`-prefixed mention of `agentId`
+ * or `displayName`. Matches a literal `@` followed by the target — both the
+ * `@` and the target are required because plain occurrences of the
+ * displayName in conversation should NOT count as a mention.
+ */
+export function scanMention(text, targets) {
+    if (!text)
+        return false;
+    const lower = text.toLowerCase();
+    const candidates = [];
+    if (targets.agentId)
+        candidates.push(targets.agentId.toLowerCase());
+    if (targets.displayName) {
+        const trimmed = targets.displayName.trim();
+        if (trimmed)
+            candidates.push(trimmed.toLowerCase());
+    }
+    for (const c of candidates) {
+        if (!c)
+            continue;
+        if (lower.includes("@" + c))
+            return true;
+    }
+    return false;
+}

package/dist/provision.d.ts

@@ -1,5 +1,6 @@
-import { BotCordClient, type ControlAck, type ControlFrame, type ListRuntimesResult } from "@botcord/protocol-core";
+import { BotCordClient, type AgentIdentitySnapshot, type ControlAck, type ControlFrame, type ListRuntimesResult } from "@botcord/protocol-core";
 import type { Gateway } from "./gateway/index.js";
+import type { PolicyResolverLike } from "./gateway/policy-resolver.js";
 import { type DaemonConfig } from "./config.js";
 /** Options accepted by {@link createProvisioner}. */
 export interface ProvisionerOptions {
@@ -10,6 +11,14 @@ export interface ProvisionerOptions {
      * run without a real Hub.
      */
     register?: typeof BotCordClient.register;
+    /**
+     * Optional policy-resolver handle (PR3). When present, the
+     * `policy_updated` control frame routes through it: cache is invalidated
+     * for the (agent, room?) pair, and any embedded `policy` payload is
+     * applied directly so the next inbound sees the fresh policy without an
+     * extra round-trip.
+     */
+    policyResolver?: PolicyResolverLike;
 }
 /** The value a frame handler returns (minus the `id` which the channel fills in). */
 type AckBody = Omit<ControlAck, "id">;
@@ -36,6 +45,68 @@ export declare function removeAgentFromConfig(cfg: DaemonConfig, agentId: string
  * gateway already isolates from throwing) and reading the wall clock.
  */
 export declare function collectRuntimeSnapshot(): ListRuntimesResult;
+/** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
+export declare const RUNTIME_ENDPOINTS_CAP = 32;
+/** Injection seam for L2 + L3 endpoint probes — kept testable + side-effect-free. */
+export type WsEndpointProbeFn = (args: {
+    url: string;
+    token?: string;
+    timeoutMs: number;
+}) => Promise<{
+    ok: boolean;
+    version?: string;
+    /**
+     * L3 — populated when `agents.list` succeeds. `id` is the stable key
+     * consumed by route lookups / `openclawAgent`; `name` is display-only.
+     */
+    agents?: Array<{
+        id: string;
+        name?: string;
+        workspace?: string;
+        model?: {
+            name?: string;
+            provider?: string;
+        };
+    }>;
+    error?: string;
+}>;
+/**
+ * Async variant that includes L2 (gateway reachability) and L3 (agent listing)
+ * probes for runtimes that talk to external services. Used by the production
+ * `list_runtimes` and first-connect snapshot paths.
+ *
+ * `cfg` is optional so existing callers without a loaded config (e.g. tests)
+ * can keep using the sync `collectRuntimeSnapshot()` — when absent, the result
+ * is identical to that function.
+ */
+export declare function collectRuntimeSnapshotAsync(opts?: {
+    cfg?: {
+        openclawGateways?: Array<{
+            name: string;
+            url: string;
+            token?: string;
+            tokenFile?: string;
+        }>;
+    };
+    wsProbe?: WsEndpointProbeFn;
+    timeoutMs?: number;
+}): Promise<ListRuntimesResult>;
+interface HelloIdentityResult {
+    updated: number;
+    skipped: number;
+}
+/**
+ * Reconcile every agent identity carried by the `hello.agents` snapshot
+ * against the on-disk `identity.md`. Best-effort: a malformed entry or a
+ * file-system error for one agent never aborts the rest.
+ *
+ * Identity-snapshot semantics intentionally only touch the metadata
+ * line + Bio body — Role/Boundaries paragraphs the user authored locally
+ * are preserved (see `applyAgentIdentity`). Missing identity.md files
+ * (agent provisioned on a different daemon, or workspace cleared) are
+ * silently skipped.
+ */
+export declare function applyHelloIdentitySnapshot(snapshot: AgentIdentitySnapshot[] | undefined): HelloIdentityResult;
 interface ReloadResult {
     reloaded: true;
     added: string[];
@@ -52,8 +123,7 @@ export declare function reloadConfig(ctx: {
     gateway: Gateway;
 }): Promise<ReloadResult>;
 /**
- * Per-agent entry returned by `list_agents`. Shape follows
- * `docs/daemon-control-plane-api-contract.md` §3.2 — `{id, name, online}`.
+ * Per-agent entry returned by `list_agents`. Wire shape: `{id, name, online}`.
  * `status` and `lastMessageAt` are extra daemon-only fields the dashboard
  * may ignore; kept so future contract revisions can promote them without
  * breaking the wire.