@botcord/daemon 0.1.1

package/src/agent-workspace.ts

@@ -0,0 +1,247 @@
+/**
+ * Per-agent on-disk workspace. Each provisioned agent gets a dedicated
+ * directory tree under `~/.botcord/agents/{agentId}/`:
+ *
+ *   workspace/   — runtime cwd; seed Markdown files live here (LLM-owned)
+ *   state/       — daemon-owned JSON (e.g. working-memory.json)
+ *   codex-home/  — per-agent CODEX_HOME used by the codex adapter so codex
+ *                  reads a daemon-written AGENTS.md (systemContext carrier)
+ *                  and stores its sessions/ without touching ~/.codex.
+ *
+ * See docs/daemon-agent-workspace-plan.md §4 for the full layout rationale.
+ */
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+// Accepted agent id pattern. Enforced at every path-builder entry so a
+// malicious / malformed agentId (e.g. "../../etc") cannot escape
+// ~/.botcord/agents/ and end up under `rmSync(..., { recursive: true })`
+// in revokeAgent(deleteWorkspace: true).
+const AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+function assertSafeAgentId(agentId: string): void {
+  if (!agentId) throw new Error("agentId is required");
+  if (!AGENT_ID_PATTERN.test(agentId)) {
+    throw new Error(`unsafe agentId: ${JSON.stringify(agentId)}`);
+  }
+}
+
+export function agentHomeDir(agentId: string): string {
+  assertSafeAgentId(agentId);
+  return path.join(homedir(), ".botcord", "agents", agentId);
+}
+
+export function agentWorkspaceDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "workspace");
+}
+
+export function agentStateDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "state");
+}
+
+/**
+ * Per-agent CODEX_HOME. The codex adapter sets the `CODEX_HOME` env var
+ * to this path so codex reads a daemon-managed `AGENTS.md` (written fresh
+ * each turn with the agent's systemContext) and stores its `sessions/`
+ * here — neither touching `~/.codex/` nor the agent's `workspace/` cwd.
+ */
+export function agentCodexHomeDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "codex-home");
+}
+
+export interface WorkspaceSeed {
+  displayName?: string;
+  bio?: string;
+  runtime?: string;
+  keyId?: string;
+  /** ISO timestamp. */
+  savedAt?: string;
+}
+
+const AGENTS_MD = `# Agent Workspace
+
+This directory is your persistent workspace. You run with \`cwd\` set here.
+
+## Files you own
+
+- \`identity.md\` — who you are, your role, your boundaries. Read before responding.
+- \`memory.md\` — long-lived facts, user preferences, past decisions. Update when
+  you learn something durable. Prune when it grows stale.
+- \`task.md\` — current task and plan. Update as you make progress. Clear when done.
+- \`notes/\` — free-form scratch space.
+
+## Boundaries
+
+- Do not modify files outside this workspace unless the user explicitly asks.
+- \`../state/\` (sibling directory, outside this workspace) is managed by the
+  daemon — do not read or edit it directly.
+
+## How to use this
+
+You are **instructed** to skim \`identity.md\`, \`memory.md\`, \`task.md\` before each
+response and to write back what changed after meaningful turns. Nothing in the
+runtime enforces this — the daemon does not auto-load these files into your
+context. Treat AGENTS.md as a convention, not a mechanism.
+`;
+
+const MEMORY_MD = `# Memory
+
+<!--
+Long-lived facts about the user, past decisions, and preferences that should
+survive across conversations. Organize by topic. Keep entries short. Prune
+regularly — AGENTS.md instructs the runtime to consult this file before each
+response, but nothing loads it automatically; keep it short enough to be
+worth re-reading.
+-->
+`;
+
+const TASK_MD = `# Current Task
+
+<!--
+What are you working on right now? What is the plan? What is blocked?
+Clear this file when the task is done.
+-->
+`;
+
+const BIO_PLACEHOLDER = "_(none provided at provision time — edit this section)_";
+const FIELD_PLACEHOLDER = "_(not set)_";
+
+function renderIdentity(agentId: string, seed: WorkspaceSeed): string {
+  const bio = seed.bio && seed.bio.trim().length > 0 ? seed.bio : BIO_PLACEHOLDER;
+  return `# Identity
+
+- **Agent ID**: ${agentId}
+- **Display name**: ${seed.displayName ?? FIELD_PLACEHOLDER}
+- **Runtime**: ${seed.runtime ?? FIELD_PLACEHOLDER}
+- **Key ID**: ${seed.keyId ?? FIELD_PLACEHOLDER}
+- **Created**: ${seed.savedAt ?? FIELD_PLACEHOLDER}
+
+## Bio
+
+${bio}
+
+## Role
+
+_(Describe what you do and for whom. Edit this section.)_
+
+## Boundaries
+
+_(What you will and will not do. Edit this section.)_
+`;
+}
+
+function mkdirTolerant(dir: string): void {
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+  }
+  // mkdirSync with `recursive: true` only applies `mode` to directories it
+  // creates. If the agent home / workspace / state already existed with
+  // looser perms (a very common case on upgrades), tighten them now.
+  // Best-effort: some filesystems (e.g. certain Windows / SMB mounts) reject
+  // chmod and that is acceptable.
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    /* best-effort */
+  }
+}
+
+function writeIfMissing(filePath: string, content: string): void {
+  if (existsSync(filePath)) return;
+  writeFileSync(filePath, content, { mode: 0o600 });
+}
+
+/**
+ * Best-effort link user's `~/.codex/auth.json` into the per-agent CODEX_HOME.
+ * Prefers a symlink (auto-follows `codex login` refreshes) and falls back to
+ * a copy on filesystems that reject symlinks. A no-op if the user has never
+ * run `codex login` — codex will then prompt on first use.
+ */
+function linkCodexAuth(codexHome: string): void {
+  const source = path.join(homedir(), ".codex", "auth.json");
+  if (!existsSync(source)) return;
+  const target = path.join(codexHome, "auth.json");
+  try {
+    if (existsSync(target) || isSymlink(target)) {
+      if (isSymlink(target) && readlinkSync(target) === source) return;
+      unlinkSync(target);
+    }
+  } catch {
+    // Unlink failure is rare but tolerable — symlink/copy below will fail
+    // loudly if the collision is real.
+  }
+  try {
+    symlinkSync(source, target);
+    return;
+  } catch {
+    // Fall through to copy on filesystems without symlink support.
+  }
+  try {
+    copyFileSync(source, target);
+    chmodSync(target, 0o600);
+  } catch {
+    /* best-effort */
+  }
+}
+
+function isSymlink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Idempotently create the per-agent CODEX_HOME directory and link the
+ * user's codex `auth.json` into it. Does NOT write an initial `AGENTS.md`
+ * — the codex adapter writes it fresh per turn from `systemContext`.
+ */
+export function ensureAgentCodexHome(agentId: string): string {
+  const dir = agentCodexHomeDir(agentId);
+  mkdirTolerant(dir);
+  linkCodexAuth(dir);
+  return dir;
+}
+
+/**
+ * Idempotently create the agent's home / workspace / state directories and
+ * seed the workspace Markdown files. Existing files are never overwritten —
+ * users' edits to AGENTS.md, memory.md, etc. are preserved across calls.
+ * State files are not touched here; working-memory.ts owns `state/`.
+ */
+export function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void {
+  if (!agentId) throw new Error("ensureAgentWorkspace: agentId is required");
+  const home = agentHomeDir(agentId);
+  const workspace = agentWorkspaceDir(agentId);
+  const notes = path.join(workspace, "notes");
+  const state = agentStateDir(agentId);
+
+  mkdirTolerant(home);
+  mkdirTolerant(workspace);
+  mkdirTolerant(notes);
+  mkdirTolerant(state);
+  ensureAgentCodexHome(agentId);
+
+  const agentsMdPath = path.join(workspace, "AGENTS.md");
+  const claudeMdPath = path.join(workspace, "CLAUDE.md");
+  writeIfMissing(agentsMdPath, AGENTS_MD);
+  writeIfMissing(claudeMdPath, AGENTS_MD);
+  writeIfMissing(path.join(workspace, "identity.md"), renderIdentity(agentId, seed));
+  writeIfMissing(path.join(workspace, "memory.md"), MEMORY_MD);
+  writeIfMissing(path.join(workspace, "task.md"), TASK_MD);
+  writeIfMissing(path.join(notes, ".gitkeep"), "");
+}

package/src/config.ts

@@ -0,0 +1,290 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { getAdapterModule, listAdapterIds } from "./adapters/runtimes.js";
+
+const DAEMON_DIR = path.join(homedir(), ".botcord", "daemon");
+const CONFIG_PATH = path.join(DAEMON_DIR, "config.json");
+export const PID_PATH = path.join(DAEMON_DIR, "daemon.pid");
+export const SESSIONS_PATH = path.join(DAEMON_DIR, "sessions.json");
+export const SNAPSHOT_PATH = path.join(DAEMON_DIR, "snapshot.json");
+
+/**
+ * Adapter ids. Built-in adapters are enumerated for editor hints; any string
+ * accepted by the registry is valid at runtime.
+ */
+export type AdapterName = "claude-code" | "codex" | "gemini" | (string & {});
+
+/**
+ * Predicates selecting messages for a route. `roomId` / `roomPrefix` are
+ * legacy aliases retained for backward compatibility with pre-P1 daemon
+ * configs; they map to `conversationId` / `conversationPrefix` at boot.
+ * First match wins.
+ */
+export interface RouteRuleMatch {
+  /** @deprecated alias for `conversationId`. */
+  roomId?: string;
+  /** @deprecated alias for `conversationPrefix`. */
+  roomPrefix?: string;
+  channel?: string;
+  accountId?: string;
+  conversationId?: string;
+  conversationPrefix?: string;
+  conversationKind?: "direct" | "group";
+  senderId?: string;
+  mentioned?: boolean;
+}
+
+export interface RouteRule {
+  match: RouteRuleMatch;
+  adapter: AdapterName;
+  cwd: string;
+  /** Extra CLI flags appended to the adapter invocation. */
+  extraArgs?: string[];
+}
+
+export interface DaemonRouteDefault {
+  adapter: AdapterName;
+  cwd: string;
+  extraArgs?: string[];
+}
+
+/**
+ * Daemon-layer hook controlling credential auto-discovery at boot. Kept
+ * optional so most users never need to touch it; absence means "use the
+ * default rule" (enabled unless an explicit `agents`/`agentId` list is
+ * already present).
+ */
+export interface AgentDiscoveryConfig {
+  enabled?: boolean;
+  credentialsDir?: string;
+}
+
+export interface DaemonConfig {
+  /**
+   * @deprecated Kept for backward compatibility with pre-multi-agent configs.
+   * Normalized in-memory to `agents: [agentId]` when present. New configs
+   * written by `init` use `agents` exclusively.
+   */
+  agentId?: string;
+
+  /**
+   * BotCord agent ids this daemon binds to. Each id maps to its own channel
+   * whose `id` equals the agentId. Credentials are loaded from
+   * `~/.botcord/credentials/{agentId}.json`. Canonical — prefer this over
+   * `agentId`.
+   *
+   * Optional: when both `agents` and `agentId` are absent, the daemon
+   * discovers identities from the credentials directory at boot.
+   */
+  agents?: string[];
+
+  /**
+   * Opt-in controls for credential discovery. When omitted, discovery runs
+   * iff no explicit `agents`/`agentId` list is present (P1 default).
+   */
+  agentDiscovery?: AgentDiscoveryConfig;
+
+  /** Default adapter + cwd used when no route matches. */
+  defaultRoute: DaemonRouteDefault;
+  routes: RouteRule[];
+  /** If true, stream blocks (only meaningful for rm_oc_* rooms). */
+  streamBlocks: boolean;
+}
+
+/**
+ * Return the explicit agent-id list written to disk, or `null` when the
+ * config has none. P1 gives discovery a chance at boot before failing,
+ * so the resolver no longer throws — callers that need a guaranteed list
+ * should fall back to `resolveAgentIds` (which still throws) or run the
+ * discovery layer first.
+ *
+ * - `agents` is present and non-empty → use it verbatim.
+ * - `agents` empty/missing + `agentId` present → synthesize `[agentId]`.
+ * - Both present: if `agentId` is not in `agents`, log a warn and let
+ *   `agents` win.
+ * - Neither present → return `null` (discovery-eligible).
+ *
+ * De-duplicates while preserving order.
+ */
+export function resolveConfiguredAgentIds(cfg: DaemonConfig): string[] | null {
+  const agents = Array.isArray(cfg.agents) ? cfg.agents.filter((s) => typeof s === "string" && s.length > 0) : [];
+  const legacy = typeof cfg.agentId === "string" && cfg.agentId.length > 0 ? cfg.agentId : null;
+
+  if (agents.length > 0) {
+    if (legacy && !agents.includes(legacy)) {
+      // Conflicting shapes on disk; `agents` wins per spec. Logged via
+      // stderr so users running `config` or `start` can spot the drift —
+      // the `log` module isn't imported here to avoid the side-effect of
+      // opening the log file from config validation.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `daemon config: legacy agentId "${legacy}" not listed in agents [${agents.join(", ")}]; preferring agents`,
+      );
+    }
+    return dedupe(agents);
+  }
+  if (legacy) return [legacy];
+  return null;
+}
+
+/**
+ * Legacy strict resolver — preserved for callers that still assume an
+ * explicit list on disk (e.g. internal tests, or codepaths that run
+ * before discovery). Throws when neither `agents` nor `agentId` is set.
+ */
+export function resolveAgentIds(cfg: DaemonConfig): string[] {
+  const configured = resolveConfiguredAgentIds(cfg);
+  if (configured) return configured;
+  throw new Error(
+    `daemon config missing agents (or legacy agentId) (${CONFIG_PATH})`,
+  );
+}
+
+function dedupe(xs: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const x of xs) {
+    if (seen.has(x)) continue;
+    seen.add(x);
+    out.push(x);
+  }
+  return out;
+}
+
+function ensureDir(): void {
+  try {
+    mkdirSync(DAEMON_DIR, { recursive: true, mode: 0o700 });
+  } catch {
+    // best-effort
+  }
+}
+
+export function loadConfig(): DaemonConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    throw new Error(
+      `daemon config not found at ${CONFIG_PATH}. Run \`botcord-daemon init\` first.`,
+    );
+  }
+  const raw = readFileSync(CONFIG_PATH, "utf8");
+  const parsed = JSON.parse(raw) as Partial<DaemonConfig>;
+
+  const hasAgents =
+    Array.isArray(parsed.agents) && parsed.agents.some((s) => typeof s === "string" && s.length > 0);
+  const hasLegacy = typeof parsed.agentId === "string" && parsed.agentId.length > 0;
+  const discovery = parsed.agentDiscovery;
+  const discoveryExplicitlyDisabled =
+    !!discovery && typeof discovery === "object" && discovery.enabled === false;
+  if (!hasAgents && !hasLegacy && discoveryExplicitlyDisabled) {
+    throw new Error(
+      `daemon config has no agents/agentId and agentDiscovery.enabled=false (${CONFIG_PATH})`,
+    );
+  }
+  if (hasAgents) {
+    for (const [i, a] of (parsed.agents as unknown[]).entries()) {
+      if (typeof a !== "string" || a.length === 0) {
+        throw new Error(`daemon config agents[${i}] must be a non-empty string (${CONFIG_PATH})`);
+      }
+    }
+  }
+  if (
+    !parsed.defaultRoute ||
+    typeof parsed.defaultRoute.adapter !== "string" ||
+    typeof parsed.defaultRoute.cwd !== "string"
+  ) {
+    throw new Error(`daemon config missing defaultRoute.adapter/cwd (${CONFIG_PATH})`);
+  }
+  validateAdapter(parsed.defaultRoute.adapter, "defaultRoute.adapter");
+
+  const routesRaw = parsed.routes ?? [];
+  if (!Array.isArray(routesRaw)) {
+    throw new Error(`daemon config "routes" must be an array (${CONFIG_PATH})`);
+  }
+  for (const [i, r] of routesRaw.entries()) {
+    if (!r || typeof r !== "object") {
+      throw new Error(`daemon config routes[${i}] is not an object (${CONFIG_PATH})`);
+    }
+    if (typeof r.adapter !== "string" || typeof r.cwd !== "string") {
+      throw new Error(
+        `daemon config routes[${i}] missing string adapter/cwd (${CONFIG_PATH})`,
+      );
+    }
+    validateAdapter(r.adapter, `routes[${i}].adapter`);
+  }
+  // Preserve the on-disk shape as-is so `config` prints what the user wrote.
+  // Resolution of agents vs agentId happens at the consumption boundary
+  // (`resolveAgentIds`, `toGatewayConfig`).
+  const out: DaemonConfig = {
+    defaultRoute: parsed.defaultRoute,
+    routes: routesRaw,
+    streamBlocks: parsed.streamBlocks ?? true,
+  };
+  if (hasAgents) out.agents = (parsed.agents as string[]).slice();
+  if (hasLegacy) out.agentId = parsed.agentId;
+  if (discovery && typeof discovery === "object") {
+    const copy: AgentDiscoveryConfig = {};
+    if (typeof discovery.enabled === "boolean") copy.enabled = discovery.enabled;
+    if (typeof discovery.credentialsDir === "string" && discovery.credentialsDir.length > 0) {
+      copy.credentialsDir = discovery.credentialsDir;
+    }
+    out.agentDiscovery = copy;
+  }
+  return out;
+}
+
+function validateAdapter(id: string, field: string): void {
+  const mod = getAdapterModule(id);
+  if (!mod) {
+    throw new Error(
+      `unknown ${field} "${id}". Registered: ${listAdapterIds().join(", ")}`,
+    );
+  }
+  if (mod.supportsRun === false) {
+    throw new Error(
+      `${field} "${id}" is a probe-only stub and cannot handle turns yet`,
+    );
+  }
+}
+
+export function saveConfig(cfg: DaemonConfig): void {
+  ensureDir();
+  const tmp = CONFIG_PATH + ".tmp";
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  renameSync(tmp, CONFIG_PATH);
+}
+
+/**
+ * Build a default config. Always writes the new `agents: [...]` shape when
+ * explicit ids are provided; the legacy scalar `agentId` field is never
+ * emitted by fresh `init` runs. When called with an empty list, `agents`
+ * is omitted entirely so the daemon auto-discovers identities at boot.
+ */
+export function initDefaultConfig(
+  agentIds: string | string[] | null | undefined,
+  cwd: string = homedir(),
+): DaemonConfig {
+  const list = Array.isArray(agentIds)
+    ? agentIds
+    : typeof agentIds === "string" && agentIds.length > 0
+      ? [agentIds]
+      : [];
+  const out: DaemonConfig = {
+    defaultRoute: { adapter: "claude-code", cwd },
+    routes: [],
+    streamBlocks: true,
+  };
+  if (list.length > 0) out.agents = dedupe(list);
+  return out;
+}
+
+export const CONFIG_FILE_PATH = CONFIG_PATH;
+export const DAEMON_DIR_PATH = DAEMON_DIR;
+
+/**
+ * Make the daemon directory (`~/.botcord/daemon`) exist with mode `0700`.
+ * Tolerant of the common case where it already exists. Exported so
+ * user-auth/snapshot code can stay independent of `saveConfig`.
+ */
+export function ensureDaemonDir(): void {
+  ensureDir();
+}