@botcord/daemon 0.1.1

package/src/system-context.ts

@@ -0,0 +1,162 @@
+/**
+ * Daemon-flavored `SystemContextBuilder` factory for the gateway dispatcher.
+ *
+ * The gateway dispatcher is channel-agnostic; it calls an optional
+ * `buildSystemContext` hook and forwards the result to the runtime via
+ * `RuntimeRunOptions.systemContext`. This module composes the daemon's
+ * system-context string from:
+ *
+ *   1. `[BotCord Scene: Owner Chat]` (owner-trust turns only)
+ *   2. `[BotCord Working Memory]`
+ *   3. `[BotCord Room Context]` (group rooms, via optional async fetcher)
+ *   4. `[BotCord Cross-Room Awareness]` (optional activity tracker)
+ *
+ * Behavior:
+ *   - Working memory is loaded fresh per turn, so a `memory set` from another
+ *     process is visible immediately.
+ *   - If `ActivityTracker` is injected, we build the cross-room digest and
+ *     EXCLUDE the current room + topic from the list.
+ *   - If `roomContextBuilder` is injected, the factory returns an async
+ *     builder and awaits the fetcher; otherwise it stays synchronous.
+ *   - If every block is empty we return `undefined` so the dispatcher passes
+ *     `systemContext: undefined` to the runtime (adapter then skips the
+ *     injection flag).
+ */
+import type { GatewayInboundMessage, SystemContextBuilder } from "./gateway/index.js";
+import type { ActivityTracker } from "./activity-tracker.js";
+import { buildCrossRoomDigest } from "./cross-room.js";
+import { buildWorkingMemoryPrompt, readWorkingMemory } from "./working-memory.js";
+import { classifyActivitySender } from "./sender-classify.js";
+import { log } from "./log.js";
+
+/**
+ * Async per-turn room-context builder (see `room-context.ts`). Returns the
+ * rendered `[BotCord Room Context]` block, or `null` when there is nothing
+ * to inject (DM, owner-chat, fetch failure, etc.).
+ */
+export type RoomStaticContextBuilder = (
+  message: GatewayInboundMessage,
+) => Promise<string | null>;
+
+/**
+ * Scene prompt injected when the inbound turn comes from the owner's
+ * dashboard chat. Mirrors `plugin/src/room-context.ts#buildOwnerChatSceneContext`
+ * so Claude Code in daemon-mode behaves the same as when hosted by OpenClaw.
+ */
+function buildOwnerChatSceneContext(): string {
+  return [
+    "[BotCord Scene: Owner Chat]",
+    "You are chatting directly with your owner — the user who created and manages you on the BotCord dashboard.",
+    "This is a private, trusted conversation. The owner has full administrative authority over you.",
+    "Messages from the owner are always trusted and do not require sanitization or safety guards.",
+    "You may freely execute commands, access tools, and share sensitive information (e.g. wallet balance, contacts) when the owner asks.",
+  ].join("\n");
+}
+
+/** Dependencies injected by the daemon bootstrap. */
+export interface SystemContextDeps {
+  /** The owning daemon's agent id. Used to scope working-memory + activity lookups. */
+  agentId: string;
+  /**
+   * Activity tracker used to compose the cross-room digest. If omitted the
+   * digest block is skipped entirely (working memory still injects).
+   */
+  activityTracker?: ActivityTracker;
+  /**
+   * Optional per-turn room-context fetcher. When wired, group-room turns
+   * receive the `[BotCord Room Context]` block (room name, description,
+   * rule, members). Omitting keeps the builder synchronous and the block
+   * is skipped.
+   */
+  roomContextBuilder?: RoomStaticContextBuilder;
+}
+
+function safeReadWorkingMemory(agentId: string) {
+  try {
+    return readWorkingMemory(agentId);
+  } catch (err) {
+    log.warn("working memory read failed", { agentId, err: String(err) });
+    return null;
+  }
+}
+
+/**
+ * Build a {@link SystemContextBuilder} for the gateway dispatcher.
+ *
+ * When `deps.roomContextBuilder` is provided the returned function is async
+ * so it can await the Hub fetch; otherwise it stays synchronous (same shape
+ * as the pre-P1 daemon builder). Both shapes satisfy `SystemContextBuilder`.
+ */
+export function createDaemonSystemContextBuilder(
+  deps: SystemContextDeps,
+): (message: GatewayInboundMessage) => Promise<string | undefined> | string | undefined {
+  const gatherSyncBlocks = (message: GatewayInboundMessage): {
+    ownerScene: string | null;
+    memory: string | null;
+    digest: string | null;
+  } => {
+    const ownerScene =
+      classifyActivitySender(message).kind === "owner"
+        ? buildOwnerChatSceneContext()
+        : null;
+
+    const wm = safeReadWorkingMemory(deps.agentId);
+    const memory = wm ? buildWorkingMemoryPrompt({ workingMemory: wm }) : null;
+
+    const digest = deps.activityTracker
+      ? buildCrossRoomDigest({
+          tracker: deps.activityTracker,
+          agentId: deps.agentId,
+          currentRoomId: message.conversation.id,
+          currentTopic: message.conversation.threadId ?? null,
+        }) || null
+      : null;
+
+    return { ownerScene, memory, digest };
+  };
+
+  const assemble = (parts: Array<string | null | undefined>): string | undefined => {
+    const filtered = parts.filter(
+      (p): p is string => typeof p === "string" && p.length > 0,
+    );
+    return filtered.length > 0 ? filtered.join("\n\n") : undefined;
+  };
+
+  if (!deps.roomContextBuilder) {
+    const syncBuilder = (message: GatewayInboundMessage): string | undefined => {
+      const { ownerScene, memory, digest } = gatherSyncBlocks(message);
+      return assemble([ownerScene, memory, digest]);
+    };
+    // Compile-time witness that the narrower sync signature still satisfies
+    // `SystemContextBuilder` (which allows async). Prevents the two contracts
+    // from silently drifting.
+    const _typecheck: SystemContextBuilder = syncBuilder;
+    void _typecheck;
+    return syncBuilder;
+  }
+
+  const roomBuilder = deps.roomContextBuilder;
+  const asyncBuilder = async (
+    message: GatewayInboundMessage,
+  ): Promise<string | undefined> => {
+    const { ownerScene, memory, digest } = gatherSyncBlocks(message);
+    // Room context landing order: after owner-scene / memory, before digest —
+    // "what room am I in" belongs with the session's own identity, while the
+    // cross-room digest deliberately describes OTHER rooms and should stay
+    // last so it doesn't get confused with the current room.
+    let roomBlock: string | null = null;
+    try {
+      roomBlock = await roomBuilder(message);
+    } catch (err) {
+      log.warn("system-context: roomContextBuilder threw — skipping room block", {
+        agentId: deps.agentId,
+        roomId: message.conversation.id,
+        err: err instanceof Error ? err.message : String(err),
+      });
+    }
+    return assemble([ownerScene, memory, roomBlock, digest]);
+  };
+  const _typecheck: SystemContextBuilder = asyncBuilder;
+  void _typecheck;
+  return asyncBuilder;
+}

package/src/turn-text.ts

@@ -0,0 +1,93 @@
+/**
+ * User-turn text composer for the gateway dispatcher.
+ *
+ * Wraps raw `msg.text` with channel-relevant metadata before handing it to
+ * the runtime. The wrapped text lands in the runtime transcript, so the
+ * model can recover "who sent this / what room / was I mentioned" on every
+ * later turn via `--resume`.
+ *
+ * Shape mirrors the plugin's `handleA2AGroup` output (see
+ * `plugin/src/inbound.ts`) so Claude Code behaves the same way in daemon as
+ * it does when hosted by OpenClaw:
+ *
+ *   [BotCord Message] | from: ag_alice | to: ag_me | room: Ouraca Team
+ *   <agent-message sender="ag_alice" sender_kind="agent">
+ *   hello
+ *   </agent-message>
+ *
+ *   [In group chats, do NOT reply unless you are explicitly mentioned or
+ *    addressed. If no response is needed, reply with exactly "NO_REPLY"
+ *    and nothing else.]
+ *
+ * Owner-chat messages bypass the wrapper entirely — they are trusted and
+ * the owner-chat scene prompt in `system-context.ts` already gives the
+ * model the context it needs.
+ */
+import type { GatewayInboundMessage } from "./gateway/index.js";
+import { sanitizeSenderName } from "./gateway/index.js";
+import { classifyActivitySender } from "./sender-classify.js";
+
+const GROUP_HINT =
+  '[In group chats, do NOT reply unless you are explicitly mentioned or addressed. ' +
+  'If no response is needed, reply with exactly "NO_REPLY" and nothing else.]';
+const DIRECT_HINT =
+  '[If the conversation has naturally concluded or no response is needed, ' +
+  'reply with exactly "NO_REPLY" and nothing else.]';
+
+/**
+ * Compose the user-turn text for a BotCord inbound message.
+ *
+ * Contract (from `UserTurnBuilder`):
+ *   - Must be synchronous + cheap (turn critical path).
+ *   - Caller guarantees `msg.text` is already trim-non-empty.
+ *   - Never throws on expected inputs. If something unforeseen happens the
+ *     dispatcher falls back to the raw trimmed text.
+ */
+export function composeBotCordUserTurn(msg: GatewayInboundMessage): string {
+  const rawText = typeof msg.text === "string" ? msg.text : "";
+  const trimmed = rawText.trim();
+  if (!trimmed) return trimmed;
+
+  const sender = classifyActivitySender(msg);
+
+  // Owner messages pass through verbatim. The scene prompt in
+  // system-context handles context; wrapping here would just add noise.
+  if (sender.kind === "owner") return trimmed;
+
+  const conversation = msg.conversation;
+  const isGroup = conversation.kind === "group";
+  const roomTitle =
+    typeof conversation.title === "string" ? conversation.title : undefined;
+
+  // Sanitize every field that could carry prompt-injection markers. The
+  // text itself is already sanitized by the channel when
+  // sender.kind !== "owner"; re-sanitizing is a no-op but keeps the
+  // contract local (the composer does not trust its inputs).
+  const sanitizedSenderLabel = sanitizeSenderName(sender.label);
+  const headerFields: string[] = [
+    "[BotCord Message]",
+    `from: ${sanitizedSenderLabel}`,
+    `to: ${msg.accountId}`,
+  ];
+  if (isGroup && roomTitle) {
+    const safeRoom = sanitizeSenderName(roomTitle.replace(/[\r\n]+/g, " "));
+    headerFields.push(`room: ${safeRoom}`);
+  }
+  if (msg.mentioned) {
+    headerFields.push("mentioned: true");
+  }
+
+  const tag = sender.kind === "human" ? "human-message" : "agent-message";
+  const senderKindAttr = sender.kind === "human" ? "human" : "agent";
+
+  const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
+
+  return [
+    headerFields.join(" | "),
+    `<${tag} sender="${sanitizedSenderLabel}" sender_kind="${senderKindAttr}">`,
+    trimmed,
+    `</${tag}>`,
+    "",
+    hint,
+  ].join("\n");
+}

package/src/user-auth.ts

@@ -0,0 +1,295 @@
+/**
+ * User-identity credentials for the daemon control plane.
+ *
+ * Unlike agent credentials (one file per agent under
+ * `~/.botcord/credentials/*.json`), the user-auth record is singular —
+ * the daemon only logs in as *one* user at a time. Stored at
+ * `~/.botcord/daemon/user-auth.json` with `0600` permissions.
+ *
+ * See `docs/daemon-control-plane-plan.md` §6–§7.
+ */
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import {
+  refreshDaemonToken,
+  type DaemonTokenResponse,
+} from "@botcord/protocol-core";
+import { DAEMON_DIR_PATH } from "./config.js";
+import { log as daemonLog } from "./log.js";
+
+export const USER_AUTH_PATH = path.join(DAEMON_DIR_PATH, "user-auth.json");
+export const AUTH_EXPIRED_FLAG_PATH = path.join(DAEMON_DIR_PATH, "auth-expired.flag");
+
+/** Persisted user-auth shape. Versioned so future fields can be added safely. */
+export interface UserAuthRecord {
+  version: 1;
+  userId: string;
+  daemonInstanceId: string;
+  hubUrl: string;
+  accessToken: string;
+  refreshToken: string;
+  /** Absolute unix millis when the access token expires. */
+  expiresAt: number;
+  /** ISO timestamp of initial token issuance — informational only. */
+  loggedInAt: string;
+  /** Optional human label (e.g. "MacBook Pro") set at login. */
+  label?: string;
+}
+
+function ensureDaemonDir(): void {
+  try {
+    mkdirSync(DAEMON_DIR_PATH, { recursive: true, mode: 0o700 });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Refuse to load user-auth if the file is group/world readable. This is a
+ * hard stop — a leaked refresh token gives an attacker permanent control
+ * over the daemon. Returns `true` when permissions are acceptable; throws
+ * otherwise so callers surface a clear remediation hint.
+ */
+function assertSecurePermissions(file: string): void {
+  const st = statSync(file);
+  // mode is packaged as unix bits — mask off everything except owner to
+  // detect any group/world bits.
+  if ((st.mode & 0o077) !== 0) {
+    throw new Error(
+      `daemon user-auth file ${file} has insecure permissions (mode ${(st.mode & 0o777).toString(8)}); run \`chmod 600 ${file}\``,
+    );
+  }
+}
+
+/**
+ * Read and return the on-disk user-auth record, or `null` if no login has
+ * happened yet. Throws on malformed content / insecure permissions.
+ */
+export function loadUserAuth(file: string = USER_AUTH_PATH): UserAuthRecord | null {
+  if (!existsSync(file)) return null;
+  assertSecurePermissions(file);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `daemon user-auth file ${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`daemon user-auth file ${file} must be a JSON object`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  const str = (k: string): string => {
+    const v = obj[k];
+    if (typeof v !== "string" || v.length === 0) {
+      throw new Error(`daemon user-auth file ${file} missing "${k}"`);
+    }
+    return v;
+  };
+  const num = (k: string): number => {
+    const v = obj[k];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      throw new Error(`daemon user-auth file ${file} missing numeric "${k}"`);
+    }
+    return v;
+  };
+  return {
+    version: 1,
+    userId: str("userId"),
+    daemonInstanceId: str("daemonInstanceId"),
+    hubUrl: str("hubUrl"),
+    accessToken: str("accessToken"),
+    refreshToken: str("refreshToken"),
+    expiresAt: num("expiresAt"),
+    loggedInAt: typeof obj.loggedInAt === "string" ? obj.loggedInAt : new Date().toISOString(),
+    ...(typeof obj.label === "string" ? { label: obj.label } : {}),
+  };
+}
+
+/** Atomically persist a user-auth record with mode 0600. */
+export function saveUserAuth(
+  record: UserAuthRecord,
+  file: string = USER_AUTH_PATH,
+): void {
+  ensureDaemonDir();
+  const tmp = file + ".tmp";
+  writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+  chmodSync(file, 0o600);
+  daemonLog.debug("user-auth saved", {
+    file,
+    userId: record.userId,
+    expiresAt: record.expiresAt,
+  });
+}
+
+/** Remove user-auth (e.g. after a hard revoke). Safe on missing file. */
+export function clearUserAuth(file: string = USER_AUTH_PATH): void {
+  try {
+    unlinkSync(file);
+    daemonLog.info("user-auth cleared", { file });
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Build a {@link UserAuthRecord} from a freshly issued daemon token
+ * envelope. Shared helper so login and refresh stay in sync about what
+ * fields the on-disk shape carries.
+ */
+export function userAuthFromTokenResponse(
+  tok: DaemonTokenResponse,
+  opts?: { label?: string; loggedInAt?: string },
+): UserAuthRecord {
+  return {
+    version: 1,
+    userId: tok.userId,
+    daemonInstanceId: tok.daemonInstanceId,
+    hubUrl: tok.hubUrl,
+    accessToken: tok.accessToken,
+    refreshToken: tok.refreshToken,
+    expiresAt: Date.now() + tok.expiresIn * 1000,
+    loggedInAt: opts?.loggedInAt ?? new Date().toISOString(),
+    ...(opts?.label ? { label: opts.label } : {}),
+  };
+}
+
+/** Write the `auth-expired.flag` stamp. Used by the control channel when a refresh 401s. */
+export function writeAuthExpiredFlag(file: string = AUTH_EXPIRED_FLAG_PATH): void {
+  ensureDaemonDir();
+  writeFileSync(file, JSON.stringify({ expiredAt: new Date().toISOString() }), {
+    mode: 0o600,
+  });
+  daemonLog.warn("user-auth expired flag written", { file });
+}
+
+/** Remove the auth-expired flag (e.g. after a successful re-login). */
+export function clearAuthExpiredFlag(file: string = AUTH_EXPIRED_FLAG_PATH): void {
+  try {
+    unlinkSync(file);
+    daemonLog.debug("user-auth expired flag cleared", { file });
+  } catch {
+    // ignore
+  }
+}
+
+/** Returns true if the stored access token is within `windowMs` of expiry. */
+export function isTokenNearExpiry(record: UserAuthRecord, windowMs = 60_000): boolean {
+  return record.expiresAt - Date.now() <= windowMs;
+}
+
+/**
+ * Stateful helper that owns the in-memory copy of user-auth and knows how
+ * to refresh it. Used by the control channel so reconnects always carry
+ * a fresh access token.
+ */
+export class UserAuthManager {
+  private record: UserAuthRecord | null;
+  private readonly file: string;
+  private refreshInflight: Promise<UserAuthRecord> | null = null;
+
+  constructor(opts: { record: UserAuthRecord | null; file?: string } = { record: null }) {
+    this.record = opts.record;
+    this.file = opts.file ?? USER_AUTH_PATH;
+  }
+
+  /** Load user-auth from disk; static convenience that wraps the ctor. */
+  static load(file: string = USER_AUTH_PATH): UserAuthManager {
+    return new UserAuthManager({ record: loadUserAuth(file), file });
+  }
+
+  /** The current (possibly stale) record, or `null` if not logged in. */
+  get current(): UserAuthRecord | null {
+    return this.record;
+  }
+
+  /**
+   * Return a valid access token, refreshing transparently if near expiry.
+   * Callers must treat the returned string as short-lived — re-invoke on
+   * 401 responses.
+   */
+  async ensureAccessToken(): Promise<string> {
+    if (!this.record) {
+      throw new Error("daemon not logged in (no user-auth)");
+    }
+    if (!isTokenNearExpiry(this.record)) {
+      return this.record.accessToken;
+    }
+    const refreshed = await this.refresh();
+    return refreshed.accessToken;
+  }
+
+  /**
+   * Force-refresh the access token. Deduplicates concurrent callers so
+   * a single network request settles them all.
+   */
+  async refresh(): Promise<UserAuthRecord> {
+    if (!this.record) {
+      throw new Error("daemon not logged in (no user-auth)");
+    }
+    if (this.refreshInflight) return this.refreshInflight;
+    const current = this.record;
+    daemonLog.info("user-auth refresh: start", {
+      userId: current.userId,
+      hubUrl: current.hubUrl,
+      expiresInMs: current.expiresAt - Date.now(),
+    });
+    this.refreshInflight = (async () => {
+      const tok = await refreshDaemonToken(current.hubUrl, current.refreshToken);
+      const next: UserAuthRecord = {
+        ...current,
+        accessToken: tok.accessToken,
+        refreshToken: tok.refreshToken,
+        expiresAt: Date.now() + tok.expiresIn * 1000,
+        hubUrl: tok.hubUrl || current.hubUrl,
+      };
+      saveUserAuth(next, this.file);
+      this.record = next;
+      daemonLog.info("user-auth refresh: ok", {
+        userId: next.userId,
+        expiresAt: next.expiresAt,
+      });
+      return next;
+    })().catch((err) => {
+      daemonLog.warn("user-auth refresh: failed", {
+        userId: current.userId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
+    }).finally(() => {
+      this.refreshInflight = null;
+    });
+    return this.refreshInflight;
+  }
+
+  /** Replace the record in memory and on disk (e.g. after device-code login). */
+  replace(record: UserAuthRecord): void {
+    saveUserAuth(record, this.file);
+    this.record = record;
+    clearAuthExpiredFlag();
+    daemonLog.info("user-auth replaced", {
+      userId: record.userId,
+      hubUrl: record.hubUrl,
+    });
+  }
+
+  /** Drop the record from memory + disk (e.g. after a hard revoke). */
+  clear(): void {
+    const prevUserId = this.record?.userId ?? null;
+    clearUserAuth(this.file);
+    this.record = null;
+    daemonLog.info("user-auth manager cleared", { userId: prevUserId });
+  }
+}