@botcord/daemon 0.1.1

package/dist/system-context.js

@@ -0,0 +1,91 @@
+import { buildCrossRoomDigest } from "./cross-room.js";
+import { buildWorkingMemoryPrompt, readWorkingMemory } from "./working-memory.js";
+import { classifyActivitySender } from "./sender-classify.js";
+import { log } from "./log.js";
+/**
+ * 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() {
+    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");
+}
+function safeReadWorkingMemory(agentId) {
+    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) {
+    const gatherSyncBlocks = (message) => {
+        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) => {
+        const filtered = parts.filter((p) => typeof p === "string" && p.length > 0);
+        return filtered.length > 0 ? filtered.join("\n\n") : undefined;
+    };
+    if (!deps.roomContextBuilder) {
+        const syncBuilder = (message) => {
+            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 = syncBuilder;
+        void _typecheck;
+        return syncBuilder;
+    }
+    const roomBuilder = deps.roomContextBuilder;
+    const asyncBuilder = async (message) => {
+        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 = 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 = asyncBuilder;
+    void _typecheck;
+    return asyncBuilder;
+}

package/dist/turn-text.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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";
+/**
+ * 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 declare function composeBotCordUserTurn(msg: GatewayInboundMessage): string;

package/dist/turn-text.js

@@ -0,0 +1,57 @@
+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) {
+    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 = [
+        "[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/dist/user-auth.d.ts

@@ -0,0 +1,75 @@
+import { type DaemonTokenResponse } from "@botcord/protocol-core";
+export declare const USER_AUTH_PATH: string;
+export declare const AUTH_EXPIRED_FLAG_PATH: string;
+/** 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;
+}
+/**
+ * Read and return the on-disk user-auth record, or `null` if no login has
+ * happened yet. Throws on malformed content / insecure permissions.
+ */
+export declare function loadUserAuth(file?: string): UserAuthRecord | null;
+/** Atomically persist a user-auth record with mode 0600. */
+export declare function saveUserAuth(record: UserAuthRecord, file?: string): void;
+/** Remove user-auth (e.g. after a hard revoke). Safe on missing file. */
+export declare function clearUserAuth(file?: string): void;
+/**
+ * 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 declare function userAuthFromTokenResponse(tok: DaemonTokenResponse, opts?: {
+    label?: string;
+    loggedInAt?: string;
+}): UserAuthRecord;
+/** Write the `auth-expired.flag` stamp. Used by the control channel when a refresh 401s. */
+export declare function writeAuthExpiredFlag(file?: string): void;
+/** Remove the auth-expired flag (e.g. after a successful re-login). */
+export declare function clearAuthExpiredFlag(file?: string): void;
+/** Returns true if the stored access token is within `windowMs` of expiry. */
+export declare function isTokenNearExpiry(record: UserAuthRecord, windowMs?: number): boolean;
+/**
+ * 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 declare class UserAuthManager {
+    private record;
+    private readonly file;
+    private refreshInflight;
+    constructor(opts?: {
+        record: UserAuthRecord | null;
+        file?: string;
+    });
+    /** Load user-auth from disk; static convenience that wraps the ctor. */
+    static load(file?: string): UserAuthManager;
+    /** The current (possibly stale) record, or `null` if not logged in. */
+    get current(): UserAuthRecord | null;
+    /**
+     * Return a valid access token, refreshing transparently if near expiry.
+     * Callers must treat the returned string as short-lived — re-invoke on
+     * 401 responses.
+     */
+    ensureAccessToken(): Promise<string>;
+    /**
+     * Force-refresh the access token. Deduplicates concurrent callers so
+     * a single network request settles them all.
+     */
+    refresh(): Promise<UserAuthRecord>;
+    /** Replace the record in memory and on disk (e.g. after device-code login). */
+    replace(record: UserAuthRecord): void;
+    /** Drop the record from memory + disk (e.g. after a hard revoke). */
+    clear(): void;
+}

package/dist/user-auth.js

@@ -0,0 +1,245 @@
+/**
+ * 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, } 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");
+function ensureDaemonDir() {
+    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) {
+    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 = USER_AUTH_PATH) {
+    if (!existsSync(file))
+        return null;
+    assertSecurePermissions(file);
+    let parsed;
+    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;
+    const str = (k) => {
+        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) => {
+        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, file = USER_AUTH_PATH) {
+    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 = USER_AUTH_PATH) {
+    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, opts) {
+    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 = AUTH_EXPIRED_FLAG_PATH) {
+    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 = AUTH_EXPIRED_FLAG_PATH) {
+    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, windowMs = 60_000) {
+    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 {
+    record;
+    file;
+    refreshInflight = null;
+    constructor(opts = { 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 = USER_AUTH_PATH) {
+        return new UserAuthManager({ record: loadUserAuth(file), file });
+    }
+    /** The current (possibly stale) record, or `null` if not logged in. */
+    get current() {
+        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() {
+        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() {
+        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 = {
+                ...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) {
+        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() {
+        const prevUserId = this.record?.userId ?? null;
+        clearUserAuth(this.file);
+        this.record = null;
+        daemonLog.info("user-auth manager cleared", { userId: prevUserId });
+    }
+}

package/dist/working-memory.d.ts

@@ -0,0 +1,46 @@
+export interface WorkingMemory {
+    version: 2;
+    goal?: string;
+    sections: Record<string, string>;
+    updatedAt: string;
+}
+/** Characters per section; matches the plugin-side limit. */
+export declare const MAX_SECTION_CHARS = 10000;
+export declare const MAX_GOAL_CHARS = 500;
+export declare const MAX_TOTAL_CHARS = 20000;
+export declare const DEFAULT_SECTION = "notes";
+/**
+ * Canonical per-agent state directory. Returns the new location
+ * (`~/.botcord/agents/{agentId}/state`). The legacy location under
+ * `~/.botcord/daemon/memory/{agentId}` is migrated lazily on first read —
+ * see §8 of the daemon-agent-workspace plan.
+ */
+export declare function resolveMemoryDir(agentId: string): string;
+export declare function readWorkingMemory(agentId: string): WorkingMemory | null;
+export declare function writeWorkingMemory(agentId: string, data: WorkingMemory): void;
+export interface SetSectionResult {
+    memory: WorkingMemory;
+    totalChars: number;
+    /** Whether the targeted section ended up present after the write. */
+    sectionPresent: boolean;
+}
+/**
+ * Upsert a section (or goal). Passing empty `content` with a `section`
+ * deletes that section. `goal === ""` clears the goal.
+ */
+export declare function updateWorkingMemory(agentId: string, update: {
+    goal?: string;
+    section?: string;
+    content?: string;
+}): SetSectionResult;
+/** Wipe the agent's working memory entirely (goal + all sections). */
+export declare function clearWorkingMemory(agentId: string): void;
+/**
+ * Render a system-prompt block describing the agent's working memory. The
+ * format intentionally mirrors the plugin's so a CLI-side agent sees the
+ * same shape as an OpenClaw-hosted one.
+ */
+export declare function buildWorkingMemoryPrompt(opts: {
+    workingMemory: WorkingMemory | null;
+    warnLarge?: boolean;
+}): string;