@botcord/daemon 0.1.1

package/src/room-context-fetcher.ts

@@ -0,0 +1,124 @@
+/**
+ * Hub-backed implementation of `RoomContextFetcher`.
+ *
+ * Maintains a per-`accountId` `BotCordClient` (so token refreshes amortize
+ * across turns) and translates the shared `/hub/rooms/:id` response into the
+ * `{ room, members }` shape the builder expects. A single GET is enough —
+ * Hub returns both the room record and its member list in one payload.
+ */
+import { BotCordClient, loadStoredCredentials } from "@botcord/protocol-core";
+import type { RoomContextFetcher } from "./room-context.js";
+
+interface CachedClient {
+  client: BotCordClient;
+  credentialsPath: string;
+}
+
+export interface RoomContextFetcherOptions {
+  /** agentId → credentials JSON path. Populated by `resolveBootAgents`. */
+  credentialPathByAgentId: Map<string, string>;
+  /** Default creds path when an agent isn't in the map (rare). */
+  defaultCredentialsPath?: string;
+  /** Hub base URL override; when set, wins over the URL stored in credentials. */
+  hubBaseUrl?: string;
+  log?: {
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+  };
+}
+
+/**
+ * Build a {@link RoomContextFetcher} that resolves against Hub. Returns
+ * `null` on any error (missing creds, network, non-JSON, etc.) so the
+ * system-context builder can skip the block without blocking the turn.
+ */
+export function createRoomContextFetcher(
+  opts: RoomContextFetcherOptions,
+): RoomContextFetcher {
+  const clients = new Map<string, CachedClient>();
+
+  function getClient(accountId: string): BotCordClient | null {
+    const existing = clients.get(accountId);
+    if (existing) return existing.client;
+
+    const credsPath =
+      opts.credentialPathByAgentId.get(accountId) ?? opts.defaultCredentialsPath;
+    if (!credsPath) {
+      opts.log?.warn("daemon.room-context.no-credentials", { accountId });
+      return null;
+    }
+
+    try {
+      const creds = loadStoredCredentials(credsPath);
+      const client = new BotCordClient({
+        hubUrl: opts.hubBaseUrl ?? creds.hubUrl,
+        agentId: creds.agentId,
+        keyId: creds.keyId,
+        privateKey: creds.privateKey,
+        ...(creds.token ? { token: creds.token } : {}),
+        ...(creds.tokenExpiresAt !== undefined
+          ? { tokenExpiresAt: creds.tokenExpiresAt }
+          : {}),
+      });
+      clients.set(accountId, { client, credentialsPath: credsPath });
+      return client;
+    } catch (err) {
+      opts.log?.warn("daemon.room-context.client-init-failed", {
+        accountId,
+        credsPath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  }
+
+  return async ({ accountId, roomId }) => {
+    const client = getClient(accountId);
+    if (!client) return null;
+    try {
+      // Hub returns `{ room_id, name, description, rule, visibility,
+      // join_policy, member_count, members: [...], ... }` in a single
+      // `/hub/rooms/:id` response. Use the raw value so we don't pay for
+      // the typed cast that drops `members`.
+      const room = (await client.getRoomInfo(roomId)) as Record<string, unknown>;
+      const members = Array.isArray((room as { members?: unknown[] }).members)
+        ? ((room as { members: unknown[] }).members as Array<Record<string, unknown>>)
+        : [];
+      return {
+        room: {
+          room_id:
+            typeof room.room_id === "string" ? room.room_id : roomId,
+          ...(typeof room.name === "string" ? { name: room.name } : {}),
+          ...(typeof room.description === "string"
+            ? { description: room.description }
+            : {}),
+          ...(typeof room.rule === "string" || room.rule === null
+            ? { rule: (room.rule as string | null) ?? null }
+            : {}),
+          ...(typeof room.visibility === "string"
+            ? { visibility: room.visibility }
+            : {}),
+          ...(typeof room.join_policy === "string"
+            ? { join_policy: room.join_policy }
+            : {}),
+          ...(typeof room.member_count === "number"
+            ? { member_count: room.member_count }
+            : {}),
+        },
+        members: members.map((m) => ({
+          agent_id: typeof m.agent_id === "string" ? m.agent_id : "unknown",
+          ...(typeof m.display_name === "string"
+            ? { display_name: m.display_name }
+            : {}),
+          ...(typeof m.role === "string" ? { role: m.role } : {}),
+        })),
+      };
+    } catch (err) {
+      opts.log?.warn("daemon.room-context.fetch-failed", {
+        accountId,
+        roomId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  };
+}

package/src/room-context.ts

@@ -0,0 +1,167 @@
+/**
+ * Room static context builder — injects room name, description, rule, and
+ * member list into the system prompt for group conversations. Mirrors
+ * `plugin/src/room-context.ts#buildRoomStaticContext` so Claude Code in
+ * daemon-mode carries the same awareness as when hosted by OpenClaw.
+ *
+ * Scope:
+ *   - Group rooms only. DMs (`rm_dm_`) and owner-chat (`rm_oc_`) rooms skip
+ *     the block — DMs don't need it and owner-chat already has a scene
+ *     prompt from system-context.ts.
+ *   - Cached per `accountId:roomId` with a 5-minute TTL to keep Hub load
+ *     bounded. Fetch failures are NOT cached so the next turn retries.
+ *   - Concurrent fetches are de-duplicated via an in-flight promise slot.
+ */
+import { sanitizeUntrustedContent } from "./gateway/index.js";
+import type { GatewayInboundMessage } from "./gateway/index.js";
+
+/** Subset of Hub `/hub/rooms/:id` needed to render the block. */
+export interface RoomInfoSnapshot {
+  room_id: string;
+  name?: string;
+  description?: string;
+  rule?: string | null;
+  visibility?: string;
+  join_policy?: string;
+  member_count?: number;
+}
+
+/** Subset of a room-member record needed to render the block. */
+export interface RoomMemberSnapshot {
+  agent_id: string;
+  display_name?: string;
+  role?: string;
+}
+
+/** Combined result returned by the injected fetcher. */
+export interface RoomContextFetchResult {
+  room: RoomInfoSnapshot;
+  members: RoomMemberSnapshot[];
+}
+
+/** Injected fetcher — daemon wraps a `BotCordClient` behind this contract. */
+export type RoomContextFetcher = (params: {
+  accountId: string;
+  roomId: string;
+}) => Promise<RoomContextFetchResult | null>;
+
+/** Minimal logger surface — matches the daemon/gateway logger shape. */
+interface CtxLogger {
+  warn: (msg: string, meta?: Record<string, unknown>) => void;
+}
+
+export interface RoomContextBuilderOptions {
+  fetchRoomInfo: RoomContextFetcher;
+  /** Cache TTL in ms. Defaults to 5 minutes to match the plugin. */
+  ttlMs?: number;
+  /** Clock override for tests. */
+  now?: () => number;
+  log?: CtxLogger;
+}
+
+interface CacheEntry {
+  blockText: string | null;
+  fetchedAt: number;
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+/** Strip CR/LF so tenant-controlled values can't reshape the prompt header. */
+function stripNewlines(s: string): string {
+  return s.replace(/[\r\n]+/g, " ");
+}
+
+/** Render the block. Exported for tests; production callers go through the builder. */
+export function renderRoomContextBlock(
+  room: RoomInfoSnapshot,
+  members: RoomMemberSnapshot[],
+): string {
+  const safeName = sanitizeUntrustedContent(stripNewlines(room.name ?? ""));
+  const lines: string[] = [
+    "[BotCord Room Context]",
+    `Room: ${safeName || "(unnamed)"} (${room.room_id})`,
+  ];
+  if (room.description) {
+    lines.push(`Description: ${sanitizeUntrustedContent(room.description)}`);
+  }
+  if (room.rule) {
+    lines.push(`Rule: ${sanitizeUntrustedContent(room.rule)}`);
+  }
+  if (room.visibility || room.join_policy) {
+    const visibility = room.visibility ?? "unknown";
+    const joinPolicy = room.join_policy ?? "unknown";
+    lines.push(`Visibility: ${visibility}, Join: ${joinPolicy}`);
+  }
+  if (members.length > 0) {
+    const list = members
+      .map((m) => {
+        const raw = m.display_name || m.agent_id;
+        const safe = sanitizeUntrustedContent(stripNewlines(raw));
+        return m.role && m.role !== "member" ? `${safe} (${m.role})` : safe;
+      })
+      .join(", ");
+    lines.push(`Members (${members.length}): ${list}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Return `true` if the inbound message is eligible for a room-context block.
+ * Exported for tests + reuse by the system-context builder.
+ */
+export function shouldInjectRoomContext(message: GatewayInboundMessage): boolean {
+  if (message.conversation.kind !== "group") return false;
+  const id = message.conversation.id;
+  if (id.startsWith("rm_dm_")) return false;
+  if (id.startsWith("rm_oc_")) return false;
+  return true;
+}
+
+/**
+ * Create a per-turn builder: `(msg) => Promise<string | null>`. The returned
+ * function honors TTL, dedupes concurrent fetches, and tolerates fetcher
+ * failures (logs + returns null so the turn is never blocked).
+ */
+export function createRoomStaticContextBuilder(
+  opts: RoomContextBuilderOptions,
+): (message: GatewayInboundMessage) => Promise<string | null> {
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const now = opts.now ?? Date.now;
+  const cache = new Map<string, CacheEntry>();
+  const inflight = new Map<string, Promise<string | null>>();
+
+  return async function getBlock(message) {
+    if (!shouldInjectRoomContext(message)) return null;
+    const accountId = message.accountId;
+    const roomId = message.conversation.id;
+    const key = `${accountId}:${roomId}`;
+
+    const hit = cache.get(key);
+    if (hit && now() - hit.fetchedAt < ttl) return hit.blockText;
+
+    const existing = inflight.get(key);
+    if (existing) return existing;
+
+    const p = (async () => {
+      try {
+        const result = await opts.fetchRoomInfo({ accountId, roomId });
+        if (!result) return null;
+        const blockText = renderRoomContextBlock(result.room, result.members);
+        cache.set(key, { blockText, fetchedAt: now() });
+        return blockText;
+      } catch (err) {
+        opts.log?.warn("daemon.room-context.fetch-failed", {
+          accountId,
+          roomId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        // Don't poison the cache — next turn will retry.
+        return null;
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+    inflight.set(key, p);
+    return p;
+  };
+}

package/src/sender-classify.ts

@@ -0,0 +1,46 @@
+/**
+ * Sender classification helper — shared between the daemon's activity
+ * recorder (daemon.ts) and the user-turn composer (turn-text.ts).
+ *
+ * Lives in its own module so both callers can import it without forming a
+ * dependency cycle through daemon.ts.
+ */
+import type { GatewayInboundMessage } from "./gateway/index.js";
+
+/**
+ * BotCord owner-chat room prefix. Rooms with this prefix are direct-message
+ * rooms between an operator and their own agent; turns here are treated as
+ * owner-trust by the daemon's trust classifier.
+ */
+export const OWNER_CHAT_PREFIX = "rm_oc_";
+
+/**
+ * Map a gateway inbound message to a sender label + kind.
+ *
+ * The gateway BotCord channel collapses two distinct owner-trust cases
+ * (`rm_oc_` rooms AND `source_type === "dashboard_user_chat"`) into a single
+ * `sender.kind === "user"` marker — which also covers `dashboard_human_room`
+ * humans. We need them separated here so callers can distinguish "owner"
+ * (admin, fully trusted) from "human Alice" (a regular human in a normal
+ * room). Falling back to just the `rm_oc_` prefix when `raw` is an
+ * unexpected shape keeps the classifier working even if a non-BotCord
+ * channel is later plugged in.
+ */
+export function classifyActivitySender(
+  msg: GatewayInboundMessage,
+): { kind: "agent" | "human" | "owner"; label: string } {
+  const sourceType =
+    msg.raw && typeof msg.raw === "object" && "source_type" in msg.raw
+      ? (msg.raw as { source_type?: unknown }).source_type
+      : undefined;
+  const isOwner =
+    msg.conversation.id.startsWith(OWNER_CHAT_PREFIX) ||
+    sourceType === "dashboard_user_chat";
+  if (isOwner) {
+    return { kind: "owner", label: msg.sender.name || msg.sender.id || "owner" };
+  }
+  if (msg.sender.kind === "user") {
+    return { kind: "human", label: msg.sender.name || msg.sender.id || "user" };
+  }
+  return { kind: "agent", label: msg.sender.id || "unknown" };
+}

package/src/snapshot-writer.ts

@@ -0,0 +1,103 @@
+import { mkdirSync, renameSync, writeFileSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import type { GatewayLogger, GatewayRuntimeSnapshot } from "./gateway/index.js";
+
+/** Envelope written to the snapshot file; `version` lets readers guard shape. */
+export interface SnapshotFile {
+  version: 1;
+  writtenAt: number;
+  snapshot: GatewayRuntimeSnapshot;
+}
+
+/** Options for {@link SnapshotWriter}. */
+export interface SnapshotWriterOptions {
+  path: string;
+  intervalMs: number;
+  snapshot: () => GatewayRuntimeSnapshot;
+  log?: GatewayLogger;
+  /** Injection point for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+/**
+ * Periodically writes `gateway.snapshot()` to a file so out-of-process CLI
+ * commands can read daemon state. Writes are atomic (tmp + rename) and
+ * failures are logged, never thrown.
+ */
+export class SnapshotWriter {
+  private readonly opts: SnapshotWriterOptions;
+  private timer: NodeJS.Timeout | null = null;
+  private stopped = false;
+
+  constructor(opts: SnapshotWriterOptions) {
+    this.opts = opts;
+  }
+
+  /** Begin periodic writes; performs one write immediately. */
+  start(): void {
+    if (this.timer || this.stopped) return;
+    this.writeOnce();
+    this.timer = setInterval(() => this.writeOnce(), this.opts.intervalMs);
+    // Don't keep the event loop alive just for status writes.
+    if (typeof this.timer.unref === "function") this.timer.unref();
+  }
+
+  /** Stop the interval. Does not delete the file — call {@link writeFinal} / {@link remove} as needed. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Write one synchronous snapshot immediately; swallows errors. */
+  writeOnce(): void {
+    let snap: GatewayRuntimeSnapshot;
+    try {
+      snap = this.opts.snapshot();
+    } catch (err) {
+      this.opts.log?.warn("daemon.snapshot-writer.snapshot-fn-threw", {
+        error: (err as Error).message,
+      });
+      return;
+    }
+    const now = (this.opts.now ?? Date.now)();
+    const payload: SnapshotFile = {
+      version: 1,
+      writtenAt: now,
+      snapshot: snap,
+    };
+    try {
+      const dir = path.dirname(this.opts.path);
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      const tmp = `${this.opts.path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(payload, null, 2), { mode: 0o600 });
+      renameSync(tmp, this.opts.path);
+    } catch (err) {
+      this.opts.log?.warn("daemon.snapshot-writer.write-failed", {
+        path: this.opts.path,
+        error: (err as Error).message,
+      });
+    }
+  }
+
+  /** Write one last snapshot — used right before {@link remove}. */
+  writeFinal(): void {
+    this.writeOnce();
+  }
+
+  /** Best-effort delete of the snapshot file; swallows + logs on failure. */
+  remove(): void {
+    try {
+      unlinkSync(this.opts.path);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") return;
+      this.opts.log?.warn("daemon.snapshot-writer.remove-failed", {
+        path: this.opts.path,
+        error: (err as Error).message,
+      });
+    }
+  }
+}

package/src/status-render.ts

@@ -0,0 +1,132 @@
+import type { GatewayRuntimeSnapshot } from "./gateway/index.js";
+
+/** Threshold after which a snapshot is flagged `⚠ stale` in rendered output. */
+export const STALE_THRESHOLD_MS = 30_000;
+
+/** Input bundle for {@link renderStatus}. */
+export interface StatusRenderInput {
+  pid: number | null;
+  alive: boolean;
+  /**
+   * Effective list of agent ids the daemon is bound to. Single-agent installs
+   * show one entry; multi-agent configs show all. `agentId` (scalar) is kept
+   * for backward-compat callers and, when provided alone, rendered the same
+   * way.
+   */
+  agents?: string[] | null;
+  /** @deprecated prefer `agents`. */
+  agentId?: string | null;
+  /** "config" — explicit list; "credentials" — auto-discovered. */
+  agentsSource?: "config" | "credentials" | null;
+  configPath?: string | null;
+  snapshot?: GatewayRuntimeSnapshot | null;
+  /** `writtenAt` age in ms. Undefined when no snapshot is available. */
+  snapshotAgeMs?: number | null;
+}
+
+function pad(s: string, n: number): string {
+  return s + " ".repeat(Math.max(0, n - s.length));
+}
+
+function relTime(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return `${h}h ago`;
+}
+
+function renderChannels(snap: GatewayRuntimeSnapshot): string[] {
+  const entries = Object.values(snap.channels);
+  if (entries.length === 0) return ["Channels:", "  (none)"];
+  const idW = Math.max(2, ...entries.map((c) => c.channel.length));
+  const accW = Math.max(7, ...entries.map((c) => c.accountId.length));
+  const out: string[] = ["Channels:"];
+  out.push(
+    `  ${pad("ID", idW)}  ${pad("ACCOUNT", accW)}  RUNNING  CONNECTED  RETRIES  RESTART  LAST ERROR`,
+  );
+  for (const c of entries) {
+    const running = c.running ? "yes" : "no";
+    const connected =
+      c.connected === undefined ? "—" : c.connected ? "yes" : "no";
+    const retries =
+      c.reconnectAttempts === undefined ? "—" : String(c.reconnectAttempts);
+    const restart = c.restartPending ? "yes" : "no";
+    const err = c.lastError ?? "—";
+    out.push(
+      `  ${pad(c.channel, idW)}  ${pad(c.accountId, accW)}  ${pad(running, 7)}  ${pad(connected, 9)}  ${pad(retries, 7)}  ${pad(restart, 7)}  ${err}`,
+    );
+  }
+  return out;
+}
+
+function renderTurns(
+  snap: GatewayRuntimeSnapshot,
+  now: number,
+): string[] {
+  const entries = Object.values(snap.turns);
+  if (entries.length === 0) return ["In-flight turns:", "  (none)"];
+  const out: string[] = ["In-flight turns:"];
+  const keyW = Math.max(3, ...entries.map((t) => t.key.length));
+  const chW = Math.max(7, ...entries.map((t) => t.channel.length));
+  const convW = Math.max(14, ...entries.map((t) => t.conversationId.length));
+  const rtW = Math.max(7, ...entries.map((t) => t.runtime.length));
+  out.push(
+    `  ${pad("KEY", keyW)}  ${pad("CHANNEL", chW)}  ${pad("CONVERSATION", convW)}  ${pad("RUNTIME", rtW)}  STARTED          CWD`,
+  );
+  for (const t of entries) {
+    const started = relTime(now - t.startedAt);
+    out.push(
+      `  ${pad(t.key, keyW)}  ${pad(t.channel, chW)}  ${pad(t.conversationId, convW)}  ${pad(t.runtime, rtW)}  ${pad(started, 16)}  ${t.cwd}`,
+    );
+  }
+  return out;
+}
+
+/**
+ * Format a human-readable status block. Kept pure so it can be unit-tested
+ * without touching disk or spawning a daemon.
+ */
+export function renderStatus(input: StatusRenderInput, now: number = Date.now()): string {
+  const lines: string[] = [];
+  if (input.pid === null) {
+    lines.push("daemon: stopped");
+    return lines.join("\n");
+  }
+  lines.push(`daemon: pid ${input.pid} (${input.alive ? "alive" : "not alive"})`);
+  const agents =
+    input.agents && input.agents.length > 0
+      ? input.agents
+      : input.agentId
+        ? [input.agentId]
+        : [];
+  const sourceTag =
+    input.agentsSource === "credentials"
+      ? " (discovered)"
+      : input.agentsSource === "config"
+        ? ""
+        : "";
+  if (agents.length === 1) {
+    lines.push(`agent:  ${agents[0]}${sourceTag}`);
+  } else if (agents.length > 1) {
+    lines.push(`agents: ${agents.join(", ")}${sourceTag}`);
+  } else if (input.agentsSource === "credentials") {
+    lines.push(`agents: (none discovered; drop credentials in ~/.botcord/credentials)`);
+  }
+  if (input.configPath) lines.push(`config: ${input.configPath}`);
+
+  if (input.snapshot) {
+    const age = input.snapshotAgeMs ?? 0;
+    const stale = age > STALE_THRESHOLD_MS ? " ⚠ stale" : "";
+    lines.push(`snapshot: ${relTime(age)}${stale}`);
+    lines.push("");
+    lines.push(...renderChannels(input.snapshot));
+    lines.push("");
+    lines.push(...renderTurns(input.snapshot, now));
+  } else if (input.alive) {
+    lines.push("snapshot: unavailable (daemon running but no snapshot file found)");
+  }
+  return lines.join("\n");
+}