@botcord/daemon 0.1.1

package/dist/working-memory.js

@@ -0,0 +1,274 @@
+/**
+ * Working memory — persistent, account-scoped notes injected into every turn.
+ *
+ * Stored at `~/.botcord/agents/{agentId}/state/working-memory.json` (the
+ * per-agent state dir owned by the daemon; see docs/daemon-agent-workspace-plan.md §8).
+ *
+ * Ported from plugin/src/memory.ts (dropping workspace + OpenClaw runtime
+ * branches) and plugin/src/memory-protocol.ts (prompt builder).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { agentStateDir } from "./agent-workspace.js";
+import { DAEMON_DIR_PATH } from "./config.js";
+import { log as daemonLog } from "./log.js";
+const VALID_SECTION_KEY_RE = /^[a-zA-Z0-9_]+$/;
+/** Characters per section; matches the plugin-side limit. */
+export const MAX_SECTION_CHARS = 10_000;
+export const MAX_GOAL_CHARS = 500;
+export const MAX_TOTAL_CHARS = 20_000;
+export const DEFAULT_SECTION = "notes";
+const MEMORY_SIZE_WARN_CHARS = 2_000;
+/** Tags that must not appear verbatim in injected memory content. */
+const RESERVED_TAGS_RE = /<\/?(?:current_memory|section_\w+)\b[^>]*>/gi;
+// ── Path resolution ────────────────────────────────────────────────
+/**
+ * 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 function resolveMemoryDir(agentId) {
+    if (!agentId)
+        throw new Error("resolveMemoryDir: agentId is required");
+    return agentStateDir(agentId);
+}
+/** Legacy location retained for one-shot migration on read. */
+function legacyMemoryDir(agentId) {
+    return path.join(DAEMON_DIR_PATH, "memory", agentId);
+}
+function workingMemoryPath(agentId) {
+    return path.join(resolveMemoryDir(agentId), "working-memory.json");
+}
+function legacyWorkingMemoryPath(agentId) {
+    return path.join(legacyMemoryDir(agentId), "working-memory.json");
+}
+// Migration conflict warnings are emitted at most once per agent per
+// process. Reset only by daemon restart — good enough for a one-release
+// transitional branch that gets removed later.
+const warnedMigrationConflict = new Set();
+/**
+ * Resolve the path to read from, migrating from the legacy location if
+ * necessary. Returns the path the caller should read, or `null` when no
+ * memory file exists anywhere.
+ *
+ * Migration branch (the `else if` on `legacyExists` below) is meant to be
+ * deleted one release after this change ships; see plan §8 step 6.
+ */
+function resolveReadPath(agentId) {
+    const newPath = workingMemoryPath(agentId);
+    const oldPath = legacyWorkingMemoryPath(agentId);
+    const newExists = existsSync(newPath);
+    const oldExists = existsSync(oldPath);
+    if (newExists) {
+        if (oldExists && !warnedMigrationConflict.has(agentId)) {
+            warnedMigrationConflict.add(agentId);
+            daemonLog.warn("working-memory: both new and legacy paths exist; using new", {
+                agentId,
+                oldPath,
+                newPath,
+            });
+        }
+        return newPath;
+    }
+    if (oldExists) {
+        try {
+            mkdirSync(path.dirname(newPath), { recursive: true, mode: 0o700 });
+            try {
+                renameSync(oldPath, newPath);
+            }
+            catch (err) {
+                // EXDEV = legacy and new paths live on different filesystems
+                // (bind mounts, tmpfs overlays). `renameSync` cannot cross fs
+                // boundaries, so fall back to copy + unlink. Without this, the
+                // next write would go to newPath while legacy still has the old
+                // payload — silent divergence the reviewer of §8 flagged.
+                if (err.code === "EXDEV") {
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+                else {
+                    throw err;
+                }
+            }
+            return newPath;
+        }
+        catch (err) {
+            const e = err;
+            daemonLog.warn("working-memory: migration rename failed; reading legacy path", {
+                agentId,
+                oldPath,
+                newPath,
+                code: e.code,
+                error: e.message ?? String(err),
+            });
+            return oldPath;
+        }
+    }
+    return null;
+}
+// ── File I/O ───────────────────────────────────────────────────────
+function readJson(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic write: tmp file + rename so a crash never leaves a half-file. */
+function writeJsonAtomic(filePath, data) {
+    mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    renameSync(tmp, filePath);
+}
+function sanitizeSections(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (VALID_SECTION_KEY_RE.test(k) && typeof v === "string")
+            out[k] = v;
+    }
+    return out;
+}
+function normalize(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    if (r.version === 2 && r.sections && typeof r.sections === "object") {
+        return {
+            version: 2,
+            goal: typeof r.goal === "string" ? r.goal : undefined,
+            sections: sanitizeSections(r.sections),
+            updatedAt: typeof r.updatedAt === "string" ? r.updatedAt : "",
+        };
+    }
+    if (r.version === 1 && typeof r.content === "string") {
+        const v1 = r;
+        return {
+            version: 2,
+            sections: v1.content ? { [DEFAULT_SECTION]: v1.content } : {},
+            updatedAt: typeof v1.updatedAt === "string" ? v1.updatedAt : "",
+        };
+    }
+    return null;
+}
+export function readWorkingMemory(agentId) {
+    const p = resolveReadPath(agentId);
+    if (!p)
+        return null;
+    return normalize(readJson(p));
+}
+export function writeWorkingMemory(agentId, data) {
+    writeJsonAtomic(workingMemoryPath(agentId), data);
+}
+/**
+ * Upsert a section (or goal). Passing empty `content` with a `section`
+ * deletes that section. `goal === ""` clears the goal.
+ */
+export function updateWorkingMemory(agentId, update) {
+    if (update.goal === undefined && update.content === undefined) {
+        throw new Error("updateWorkingMemory: must provide 'goal' or 'content'");
+    }
+    if (update.goal !== undefined && update.goal.length > MAX_GOAL_CHARS) {
+        throw new Error(`goal exceeds ${MAX_GOAL_CHARS} characters`);
+    }
+    const sectionName = (update.section ?? DEFAULT_SECTION).trim();
+    if (update.content !== undefined && !VALID_SECTION_KEY_RE.test(sectionName)) {
+        throw new Error("section name must contain only letters, digits, and underscores");
+    }
+    if (update.content !== undefined &&
+        update.content.length > MAX_SECTION_CHARS) {
+        throw new Error(`content exceeds ${MAX_SECTION_CHARS} characters for section '${sectionName}'`);
+    }
+    const existing = readWorkingMemory(agentId) ?? {
+        version: 2,
+        sections: {},
+        updatedAt: "",
+    };
+    if (update.goal !== undefined) {
+        existing.goal = update.goal === "" ? undefined : update.goal;
+    }
+    if (update.content !== undefined) {
+        if (update.content === "")
+            delete existing.sections[sectionName];
+        else
+            existing.sections[sectionName] = update.content;
+    }
+    const totalChars = (existing.goal?.length ?? 0) +
+        Object.values(existing.sections).reduce((s, v) => s + v.length, 0);
+    if (totalChars > MAX_TOTAL_CHARS) {
+        throw new Error(`total working memory exceeds ${MAX_TOTAL_CHARS} characters (current: ${totalChars})`);
+    }
+    existing.updatedAt = new Date().toISOString();
+    writeWorkingMemory(agentId, existing);
+    return {
+        memory: existing,
+        totalChars,
+        sectionPresent: update.content !== undefined ? update.content !== "" : sectionName in existing.sections,
+    };
+}
+/** Wipe the agent's working memory entirely (goal + all sections). */
+export function clearWorkingMemory(agentId) {
+    const empty = {
+        version: 2,
+        sections: {},
+        updatedAt: new Date().toISOString(),
+    };
+    writeWorkingMemory(agentId, empty);
+}
+// ── Prompt builder ─────────────────────────────────────────────────
+function sanitizeMemoryContent(content) {
+    return content.replace(RESERVED_TAGS_RE, (tag) => tag.replace(/</g, "‹").replace(/>/g, "›"));
+}
+/**
+ * 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 function buildWorkingMemoryPrompt(opts) {
+    const { workingMemory, warnLarge = true } = opts;
+    const lines = [
+        "[BotCord Working Memory]",
+        "You have a persistent working memory that survives across turns and rooms.",
+        "Use it to track your goal, important facts, pending commitments, and context worth remembering.",
+        "",
+        "Update via the daemon's `memory` CLI (or whatever tool the operator wires):",
+        "- goal: a short pinned statement of what you're working on.",
+        "- sections: named buckets (contacts, pending_tasks, preferences, etc.).",
+        "- Updating one section never touches others. Empty content deletes a section.",
+        "",
+        "Only update when something meaningful changes. Keep each section tight.",
+    ];
+    if (!workingMemory) {
+        lines.push("", "Your working memory is currently empty.");
+        return lines.join("\n");
+    }
+    const entries = Object.entries(workingMemory.sections ?? {});
+    const hasGoal = !!workingMemory.goal;
+    const hasSections = entries.length > 0;
+    if (!hasGoal && !hasSections) {
+        lines.push("", "Your working memory is currently empty.");
+        return lines.join("\n");
+    }
+    lines.push("", `Current working memory (last updated: ${workingMemory.updatedAt}):`);
+    let totalChars = 0;
+    if (hasGoal) {
+        const goal = sanitizeMemoryContent(workingMemory.goal.replace(/[\r\n]+/g, " ").trim());
+        lines.push("", `Goal: ${goal}`);
+        totalChars += goal.length;
+    }
+    for (const [name, content] of entries) {
+        if (!content)
+            continue;
+        const body = sanitizeMemoryContent(content);
+        lines.push("", `<section_${name}>`, body, `</section_${name}>`);
+        totalChars += body.length;
+    }
+    if (warnLarge && totalChars > MEMORY_SIZE_WARN_CHARS) {
+        lines.push("", `⚠ Your working memory is ${totalChars} characters. Consider condensing sections to keep token usage low.`);
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@botcord/daemon",
+  "version": "0.1.1",
+  "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
+  "type": "module",
+  "bin": {
+    "botcord-daemon": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@botcord/protocol-core": "^0.1.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/__tests__/activity-tracker.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ActivityTracker } from "../activity-tracker.js";
+
+let tmpDir = "";
+let filePath = "";
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(path.join(os.tmpdir(), "daemon-act-"));
+  filePath = path.join(tmpDir, "activity.json");
+});
+afterEach(() => {
+  if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("ActivityTracker", () => {
+  it("records + reads by (agent, room, topic)", () => {
+    const t = new ActivityTracker({ filePath });
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_1",
+      topic: "tp_plan",
+      lastInboundPreview: "hi there",
+      lastSenderKind: "agent",
+      lastSender: "ag_peer",
+    });
+    const got = t.get("ag_a", "rm_1", "tp_plan");
+    expect(got?.lastSender).toBe("ag_peer");
+    expect(got?.lastActivityAt).toBeGreaterThan(Date.now() - 1000);
+    // Different topic → distinct entry
+    expect(t.get("ag_a", "rm_1", null)).toBeNull();
+  });
+
+  it("caps preview length at ACTIVITY_PREVIEW_CHARS", () => {
+    const t = new ActivityTracker({ filePath });
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_1",
+      topic: null,
+      lastInboundPreview: "x".repeat(500),
+      lastSenderKind: "agent",
+      lastSender: "ag_peer",
+    });
+    const got = t.get("ag_a", "rm_1", null);
+    expect(got?.lastInboundPreview.length).toBe(120);
+  });
+
+  it("listActive filters by agent + window, excludes current key, sorts newest first", () => {
+    const t = new ActivityTracker({ filePath });
+    const now = Date.now();
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_old",
+      topic: null,
+      lastInboundPreview: "old",
+      lastSenderKind: "agent",
+      lastSender: "p",
+      lastActivityAt: now - 3 * 60 * 60 * 1000, // 3h ago
+    });
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_new",
+      topic: null,
+      lastInboundPreview: "new",
+      lastSenderKind: "agent",
+      lastSender: "p",
+      lastActivityAt: now - 10 * 60 * 1000, // 10m ago
+    });
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_cur",
+      topic: null,
+      lastInboundPreview: "cur",
+      lastSenderKind: "agent",
+      lastSender: "p",
+      lastActivityAt: now - 1 * 60 * 1000,
+    });
+    // Different agent entry — must be ignored.
+    t.record({
+      agentId: "ag_b",
+      roomId: "rm_other",
+      topic: null,
+      lastInboundPreview: "nope",
+      lastSenderKind: "agent",
+      lastSender: "p",
+    });
+
+    const list = t.listActive({
+      agentId: "ag_a",
+      windowMs: 2 * 60 * 60 * 1000,
+      excludeKey: t.keyFor("ag_a", "rm_cur", null),
+    });
+    expect(list.map((e) => e.roomId)).toEqual(["rm_new"]);
+  });
+
+  it("flushes atomically to disk", () => {
+    const t = new ActivityTracker({ filePath });
+    t.record({
+      agentId: "ag_a",
+      roomId: "rm_1",
+      topic: null,
+      lastInboundPreview: "hi",
+      lastSenderKind: "agent",
+      lastSender: "p",
+    });
+    t.flushSync();
+    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    expect(raw.version).toBe(1);
+    const entry = Object.values(raw.entries)[0] as Record<string, unknown>;
+    expect(entry.roomId).toBe("rm_1");
+  });
+
+  it("survives reopen — previous records reload from disk", () => {
+    const t1 = new ActivityTracker({ filePath });
+    t1.record({
+      agentId: "ag_a",
+      roomId: "rm_1",
+      topic: null,
+      lastInboundPreview: "x",
+      lastSenderKind: "agent",
+      lastSender: "p",
+    });
+    t1.flushSync();
+
+    const t2 = new ActivityTracker({ filePath });
+    expect(t2.get("ag_a", "rm_1", null)?.lastSender).toBe("p");
+  });
+});

package/src/__tests__/agent-discovery.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import type { Stats } from "node:fs";
+import { discoverAgentCredentials, resolveBootAgents } from "../agent-discovery.js";
+import type { DaemonConfig } from "../config.js";
+
+function fakeStat(mtimeMs: number): Stats {
+  return { mtimeMs } as unknown as Stats;
+}
+
+function fakeCreds(agentId: string, extra: Record<string, unknown> = {}) {
+  return {
+    version: 1 as const,
+    hubUrl: "https://hub.example.com",
+    agentId,
+    keyId: "k_1",
+    privateKey: "priv",
+    publicKey: "pub",
+    savedAt: new Date().toISOString(),
+    ...extra,
+  };
+}
+
+describe("discoverAgentCredentials", () => {
+  it("returns an empty result when the credentials directory is missing", () => {
+    const res = discoverAgentCredentials({
+      credentialsDir: "/no/such/dir",
+      readDir: () => {
+        const err = new Error("ENOENT") as NodeJS.ErrnoException;
+        err.code = "ENOENT";
+        throw err;
+      },
+      stat: () => fakeStat(0),
+      loadCredentials: () => {
+        throw new Error("should not be called");
+      },
+    });
+    expect(res.agents).toEqual([]);
+    expect(res.warnings).toEqual([]);
+  });
+
+  it("loads valid credential files and returns the internal agentId (not the filename)", () => {
+    const savedAt = "2025-01-01T00:00:00.000Z";
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["wrong-name.json"],
+      stat: () => fakeStat(100),
+      loadCredentials: () =>
+        fakeCreds("ag_internal", { displayName: "Alice", savedAt }),
+    });
+    expect(res.agents).toEqual([
+      {
+        agentId: "ag_internal",
+        credentialsFile: "/creds/wrong-name.json",
+        hubUrl: "https://hub.example.com",
+        displayName: "Alice",
+        keyId: "k_1",
+        savedAt,
+      },
+    ]);
+    expect(res.warnings).toEqual([]);
+  });
+
+  it("surfaces keyId and savedAt from the credentials file (plan §9 BootAgent shape)", () => {
+    const savedAt = "2026-04-23T12:00:00.000Z";
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["ag.json"],
+      stat: () => fakeStat(1),
+      loadCredentials: () =>
+        fakeCreds("ag_one", { keyId: "k_42", savedAt }),
+    });
+    expect(res.agents).toHaveLength(1);
+    expect(res.agents[0].keyId).toBe("k_42");
+    expect(res.agents[0].savedAt).toBe(savedAt);
+  });
+
+  it("ignores non-JSON files silently", () => {
+    const loaded: string[] = [];
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["ignore.txt", "README", "ag.json"],
+      stat: () => fakeStat(1),
+      loadCredentials: (f) => {
+        loaded.push(f);
+        return fakeCreds("ag_one");
+      },
+    });
+    expect(loaded).toEqual(["/creds/ag.json"]);
+    expect(res.agents.map((a) => a.agentId)).toEqual(["ag_one"]);
+  });
+
+  it("skips invalid credentials and records a warning", () => {
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["bad.json", "good.json"],
+      stat: () => fakeStat(1),
+      loadCredentials: (f) => {
+        if (f.endsWith("bad.json")) throw new Error("missing hubUrl");
+        return fakeCreds("ag_good");
+      },
+    });
+    expect(res.agents.map((a) => a.agentId)).toEqual(["ag_good"]);
+    expect(res.warnings.some((w) => w.includes("invalid credentials") && w.includes("bad.json"))).toBe(true);
+  });
+
+  it("prefers the newer mtime on duplicate agentIds", () => {
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["a.json", "b.json"],
+      stat: (p) => (p.endsWith("b.json") ? fakeStat(200) : fakeStat(100)),
+      loadCredentials: () => fakeCreds("ag_dup"),
+    });
+    expect(res.agents).toHaveLength(1);
+    expect(res.agents[0].credentialsFile).toBe("/creds/b.json");
+    expect(res.warnings.some((w) => w.includes("duplicate agentId"))).toBe(true);
+  });
+
+  it("falls back to lexical order when mtimes tie", () => {
+    const res = discoverAgentCredentials({
+      credentialsDir: "/creds",
+      readDir: () => ["z.json", "a.json"],
+      stat: () => fakeStat(42),
+      loadCredentials: () => fakeCreds("ag_dup"),
+    });
+    expect(res.agents).toHaveLength(1);
+    // Sorted lexically first wins when mtimes are equal.
+    expect(res.agents[0].credentialsFile).toBe("/creds/a.json");
+  });
+});
+
+describe("resolveBootAgents", () => {
+  function cfg(overrides: Partial<DaemonConfig> = {}): DaemonConfig {
+    return {
+      defaultRoute: { adapter: "claude-code", cwd: "/home/a" },
+      routes: [],
+      streamBlocks: true,
+      ...overrides,
+    };
+  }
+
+  it("uses explicit `agents` list and derives default credential paths", () => {
+    const res = resolveBootAgents(cfg({ agents: ["ag_one", "ag_two"] }));
+    expect(res.source).toBe("config");
+    expect(res.agents).toHaveLength(2);
+    expect(res.agents[0].agentId).toBe("ag_one");
+    expect(res.agents[0].credentialsFile).toContain("ag_one.json");
+    expect(res.warnings).toEqual([]);
+  });
+
+  it("falls back to discovery when no explicit list is present", () => {
+    const res = resolveBootAgents(cfg(), {
+      credentialsDir: "/creds",
+      readDir: () => ["x.json"],
+      stat: () => fakeStat(1),
+      loadCredentials: () => fakeCreds("ag_discovered"),
+    });
+    expect(res.source).toBe("credentials");
+    expect(res.agents.map((a) => a.agentId)).toEqual(["ag_discovered"]);
+    expect(res.agents[0].credentialsFile).toBe("/creds/x.json");
+  });
+
+  it("returns an empty agent list (not a throw) when discovery finds nothing", () => {
+    const res = resolveBootAgents(cfg(), {
+      credentialsDir: "/creds",
+      readDir: () => [],
+      stat: () => fakeStat(0),
+      loadCredentials: () => {
+        throw new Error("should not be called");
+      },
+    });
+    expect(res.source).toBe("credentials");
+    expect(res.agents).toEqual([]);
+  });
+
+  it("honors cfg.agentDiscovery.credentialsDir when discovery runs", () => {
+    const calls: string[] = [];
+    const res = resolveBootAgents(
+      cfg({ agentDiscovery: { credentialsDir: "/custom" } }),
+      {
+        readDir: (d) => {
+          calls.push(d);
+          return ["a.json"];
+        },
+        stat: () => fakeStat(1),
+        loadCredentials: () => fakeCreds("ag_c"),
+      },
+    );
+    expect(calls).toEqual(["/custom"]);
+    expect(res.credentialsDir).toBe("/custom");
+  });
+});