@botcord/daemon 0.1.1

package/src/gateway/runtimes/registry.ts

@@ -0,0 +1,143 @@
+import { ClaudeCodeAdapter, probeClaude } from "./claude-code.js";
+import { CodexAdapter, probeCodex } from "./codex.js";
+import { GeminiAdapter, probeGemini } from "./gemini.js";
+import type { RuntimeAdapter, RuntimeProbeResult } from "../types.js";
+
+/**
+ * Metadata + factory for a single runtime adapter, used by the registry.
+ * Add a new runtime by exporting one of these from the adapter file and
+ * registering it in `REGISTRY` below.
+ */
+export interface RuntimeModule {
+  id: string;
+  displayName: string;
+  /** Canonical PATH binary name — shown in `doctor` output. */
+  binary: string;
+  /**
+   * Env var that overrides the resolved CLI path for this adapter.
+   * Defaults to `BOTCORD_<ID>_BIN` with dashes → underscores, uppercased.
+   */
+  envVar?: string;
+  /** Module-level probe so callers don't have to instantiate the adapter. */
+  probe(): RuntimeProbeResult;
+  create(): RuntimeAdapter;
+  /**
+   * Whether `create().run()` is implemented. Defaults to true. Stubs
+   * (e.g. gemini until we wire its driver) should set `false` so the
+   * config loader rejects routing turns to this adapter.
+   */
+  supportsRun?: boolean;
+}
+
+/** Built-in runtime module entry for Claude Code. */
+export const claudeCodeModule: RuntimeModule = {
+  id: "claude-code",
+  displayName: "Claude Code",
+  binary: "claude",
+  envVar: "BOTCORD_CLAUDE_BIN",
+  probe: () => probeClaude(),
+  create: () => new ClaudeCodeAdapter(),
+};
+
+/** Built-in runtime module entry for Codex. */
+export const codexModule: RuntimeModule = {
+  id: "codex",
+  displayName: "Codex CLI",
+  binary: "codex",
+  probe: () => probeCodex(),
+  create: () => new CodexAdapter(),
+};
+
+/** Built-in runtime module entry for Gemini (probe-only stub). */
+export const geminiModule: RuntimeModule = {
+  id: "gemini",
+  displayName: "Gemini CLI",
+  binary: "gemini",
+  probe: () => probeGemini(),
+  create: () => new GeminiAdapter(),
+  supportsRun: false,
+};
+
+/**
+ * Built-in runtime modules. To add a new runtime:
+ *   1. Create `runtimes/<name>.ts` extending `NdjsonStreamAdapter` (or
+ *      implementing `RuntimeAdapter` directly).
+ *   2. Add a `RuntimeModule` entry + register it here.
+ */
+export const RUNTIME_MODULES: readonly RuntimeModule[] = [
+  claudeCodeModule,
+  codexModule,
+  geminiModule,
+];
+
+const BY_ID = new Map<string, RuntimeModule>(
+  RUNTIME_MODULES.map((m) => [m.id, m]),
+);
+
+/** Lookup a runtime module by id, or null when the id is unknown. */
+export function getRuntimeModule(id: string): RuntimeModule | null {
+  return BY_ID.get(id) ?? null;
+}
+
+/** All registered runtime ids in registration order. */
+export function listRuntimeIds(): string[] {
+  return RUNTIME_MODULES.map((m) => m.id);
+}
+
+/** Env var name used to override the binary path for a given runtime id. */
+export function envVarForRuntime(id: string): string {
+  const mod = getRuntimeModule(id);
+  if (mod?.envVar) return mod.envVar;
+  const token = id.replace(/-/g, "_").toUpperCase();
+  return `BOTCORD_${token}_BIN`;
+}
+
+/** Instantiate a single runtime adapter by id; throws if unknown. */
+export function createRuntime(id: string): RuntimeAdapter {
+  const mod = getRuntimeModule(id);
+  if (!mod) {
+    throw new Error(
+      `Unknown runtime "${id}". Registered runtimes: ${listRuntimeIds().join(", ")}`,
+    );
+  }
+  return mod.create();
+}
+
+/** Instantiate every registered runtime — used as the dispatcher default. */
+export function createAllRuntimes(): Record<string, RuntimeAdapter> {
+  const map: Record<string, RuntimeAdapter> = {};
+  for (const m of RUNTIME_MODULES) {
+    map[m.id] = m.create();
+  }
+  return map;
+}
+
+/** One probe result per registered runtime, for `doctor`-style listings. */
+export interface RuntimeProbeEntry {
+  id: string;
+  displayName: string;
+  binary: string;
+  supportsRun: boolean;
+  result: RuntimeProbeResult;
+}
+
+/** Probe every registered runtime and report installation status. */
+export function detectRuntimes(): RuntimeProbeEntry[] {
+  const out: RuntimeProbeEntry[] = [];
+  for (const m of RUNTIME_MODULES) {
+    let result: RuntimeProbeResult = { available: false };
+    try {
+      result = m.probe();
+    } catch {
+      result = { available: false };
+    }
+    out.push({
+      id: m.id,
+      displayName: m.displayName,
+      binary: m.binary,
+      supportsRun: m.supportsRun !== false,
+      result,
+    });
+  }
+  return out;
+}

package/src/gateway/session-store.ts

@@ -0,0 +1,157 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { GatewayLogger } from "./log.js";
+import type { GatewaySessionEntry, SessionKeyInput } from "./types.js";
+
+export const DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Derive the canonical session-store key for a runtime + channel + conversation. */
+export function sessionKey(input: SessionKeyInput): string {
+  const base = `${input.runtime}:${input.channel}:${input.accountId}:${input.conversationKind}:${input.conversationId}`;
+  const thread = input.threadId;
+  if (typeof thread === "string" && thread.length > 0) {
+    return `${base}:${thread}`;
+  }
+  return base;
+}
+
+/** Options for constructing a `SessionStore`. */
+export interface SessionStoreOptions {
+  path: string;
+  log?: GatewayLogger;
+  /** Optional TTL for persisted entries. Omit to disable automatic pruning. */
+  maxEntryAgeMs?: number;
+}
+
+interface StoreFile {
+  version: 1;
+  entries: Record<string, GatewaySessionEntry>;
+}
+
+function emptyFile(): StoreFile {
+  return { version: 1, entries: {} };
+}
+
+function isValidShape(x: unknown): x is StoreFile {
+  if (!x || typeof x !== "object") return false;
+  const o = x as Record<string, unknown>;
+  return o.version === 1 && !!o.entries && typeof o.entries === "object";
+}
+
+/** JSON-backed session store for runtime resume ids, keyed by `sessionKey()`. */
+export class SessionStore {
+  private readonly filePath: string;
+  private readonly log?: GatewayLogger;
+  private readonly maxEntryAgeMs?: number;
+  private data: StoreFile = emptyFile();
+  private loaded = false;
+  private writeQueue: Promise<void> = Promise.resolve();
+
+  constructor(opts: SessionStoreOptions) {
+    this.filePath = opts.path;
+    this.log = opts.log;
+    if (Number.isFinite(opts.maxEntryAgeMs) && opts.maxEntryAgeMs! > 0) {
+      this.maxEntryAgeMs = opts.maxEntryAgeMs;
+    }
+  }
+
+  /** Load entries from disk. Tolerates missing or corrupt files. */
+  async load(): Promise<void> {
+    let raw: string;
+    try {
+      raw = await readFile(this.filePath, "utf8");
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") {
+        this.data = emptyFile();
+        this.loaded = true;
+        return;
+      }
+      throw err;
+    }
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (isValidShape(parsed)) {
+        this.data = { version: 1, entries: parsed.entries };
+      } else {
+        this.log?.warn("gateway.session-store.invalid-shape", { path: this.filePath });
+        this.data = emptyFile();
+      }
+    } catch (err) {
+      this.log?.warn("gateway.session-store.parse-error", {
+        path: this.filePath,
+        error: (err as Error).message,
+      });
+      this.data = emptyFile();
+    }
+    this.loaded = true;
+    if (this.maxEntryAgeMs !== undefined) {
+      await this.pruneExpired({ maxAgeMs: this.maxEntryAgeMs });
+    }
+  }
+
+  /** Look up an entry by its full session key. */
+  get(key: string): GatewaySessionEntry | undefined {
+    return this.data.entries[key];
+  }
+
+  /** Upsert an entry and persist the store atomically. */
+  async set(entry: GatewaySessionEntry): Promise<void> {
+    const callerTs = entry.updatedAt;
+    const updatedAt = Number.isFinite(callerTs) && callerTs > 0 ? callerTs : Date.now();
+    this.data.entries[entry.key] = { ...entry, updatedAt };
+    await this.persist();
+  }
+
+  /** Remove an entry and persist the store atomically. */
+  async delete(key: string): Promise<void> {
+    if (this.data.entries[key] !== undefined) {
+      delete this.data.entries[key];
+    }
+    await this.persist();
+  }
+
+  /** Snapshot of all entries (for status/debugging). */
+  all(): GatewaySessionEntry[] {
+    return Object.values(this.data.entries);
+  }
+
+  /** Remove entries whose `updatedAt` is older than `maxAgeMs`; returns count removed. */
+  async pruneExpired(opts: { maxAgeMs: number; now?: number }): Promise<number> {
+    const maxAgeMs = opts.maxAgeMs;
+    if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0) return 0;
+    const now = Number.isFinite(opts.now) ? opts.now! : Date.now();
+    const cutoff = now - maxAgeMs;
+    let removed = 0;
+    for (const [key, entry] of Object.entries(this.data.entries)) {
+      if (!Number.isFinite(entry.updatedAt) || entry.updatedAt < cutoff) {
+        delete this.data.entries[key];
+        removed += 1;
+      }
+    }
+    if (removed > 0) {
+      this.log?.info("gateway.session-store.pruned-expired", {
+        path: this.filePath,
+        removed,
+        maxAgeMs,
+      });
+      await this.persist();
+    }
+    return removed;
+  }
+
+  private persist(): Promise<void> {
+    const next = this.writeQueue.then(() => this.flushOnce());
+    this.writeQueue = next.catch(() => undefined);
+    return next;
+  }
+
+  private async flushOnce(): Promise<void> {
+    const dir = path.dirname(this.filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    const payload = JSON.stringify(this.data, null, 2);
+    await writeFile(tmp, payload, { mode: 0o600 });
+    await rename(tmp, this.filePath);
+  }
+}

package/src/gateway/types.ts

@@ -0,0 +1,325 @@
+import type { GatewayLogger } from "./log.js";
+
+// ---------------------------------------------------------------------------
+// Routing (§9)
+// ---------------------------------------------------------------------------
+
+/** Set of predicates matched against a normalized inbound message to pick a route. */
+export interface RouteMatch {
+  channel?: string;
+  accountId?: string;
+  conversationId?: string;
+  conversationPrefix?: string;
+  conversationKind?: "direct" | "group";
+  senderId?: string;
+  mentioned?: boolean;
+}
+
+/** Concurrency model for turns sharing the same queue key. */
+export type QueueMode = "serial" | "cancel-previous";
+
+/** Source-based trust tier used by runtimes to pick default permission flags. */
+export type TrustLevel = "owner" | "trusted" | "public";
+
+/** Declarative route entry selecting the runtime and execution flags for matched messages. */
+export interface GatewayRoute {
+  match?: RouteMatch;
+  runtime: string;
+  cwd: string;
+  extraArgs?: string[];
+  queueMode?: QueueMode;
+  trustLevel?: TrustLevel;
+}
+
+// ---------------------------------------------------------------------------
+// Config (§8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-channel configuration entry. Channel-specific extras (e.g. BotCord
+ * `agentId`) are accepted via the index signature so adapters can read them
+ * without introducing a tagged-union everywhere.
+ */
+export interface GatewayChannelConfig {
+  id: string;
+  type: string;
+  accountId: string;
+  [key: string]: unknown;
+}
+
+/** Root gateway configuration document loaded from disk or assembled in memory. */
+export interface GatewayConfig {
+  channels: GatewayChannelConfig[];
+  defaultRoute: GatewayRoute;
+  routes?: GatewayRoute[];
+  /**
+   * Daemon-synthesized per-agent routes. Snapshot/debug-only surface —
+   * `resolveRoute` reads the live map on the Gateway, not this array.
+   * Matched after `routes[]` and before `defaultRoute`.
+   */
+  managedRoutes?: GatewayRoute[];
+  streamBlocks?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Inbound / outbound message shape (§7.3, §7.4, §7.5)
+// ---------------------------------------------------------------------------
+
+/** Normalized inbound message produced by a channel adapter for the dispatcher. */
+export interface GatewayInboundMessage {
+  id: string;
+  /** Channel adapter id (`ChannelAdapter.id`), not channel type. */
+  channel: string;
+  accountId: string;
+  conversation: {
+    id: string;
+    kind: "direct" | "group";
+    title?: string;
+    threadId?: string | null;
+  };
+  sender: {
+    id: string;
+    name?: string;
+    kind: "user" | "agent" | "system";
+  };
+  text?: string;
+  raw: unknown;
+  replyTo?: string | null;
+  mentioned?: boolean;
+  receivedAt: number;
+  trace?: {
+    id: string;
+    streamable?: boolean;
+  };
+}
+
+/** Inbound envelope wrapping a normalized message with optional upstream ack callbacks. */
+export interface GatewayInboundEnvelope {
+  message: GatewayInboundMessage;
+  ack?: {
+    accept(): Promise<void>;
+    reject?(reason: string): Promise<void>;
+  };
+}
+
+/**
+ * Channel-agnostic hook that produces a system-context string for a turn.
+ * Called before every `runtime.run(...)`; returned value is passed through
+ * as `RuntimeRunOptions.systemContext`. Runtimes surface it via
+ * `--append-system-prompt` (Claude Code) or an equivalent prefix.
+ *
+ * Returning `undefined` or an empty string means "no context for this turn".
+ * Builders must be resilient — if this throws, the dispatcher logs a warning
+ * and continues the turn without systemContext rather than dropping the turn.
+ */
+export type SystemContextBuilder = (
+  message: GatewayInboundMessage,
+) => Promise<string | undefined> | string | undefined;
+
+/**
+ * Optional side-effect hook invoked right after the dispatcher acks an
+ * envelope, before the turn executes. Intended for bookkeeping such as
+ * activity tracking; errors are caught and logged so they do not break the
+ * turn. Kept synchronous-or-async to match `SystemContextBuilder` ergonomics.
+ */
+export type InboundObserver = (
+  message: GatewayInboundMessage,
+) => Promise<void> | void;
+
+/**
+ * Channel-agnostic hook that composes the user-turn text passed to the
+ * runtime. When omitted, the dispatcher passes `message.text.trim()` through
+ * as-is. Builders can wrap the content with sender metadata, room headers,
+ * reply hints, etc. — anything that should land in the session transcript.
+ *
+ * Must be synchronous + cheap (runs on the turn's critical path). Throws are
+ * caught by the dispatcher and the raw trimmed text is used as a fallback so
+ * a buggy composer never drops turns.
+ */
+export type UserTurnBuilder = (message: GatewayInboundMessage) => string;
+
+/** Outbound reply payload passed to `ChannelAdapter.send()`. */
+export interface GatewayOutboundMessage {
+  channel: string;
+  accountId: string;
+  conversationId: string;
+  threadId?: string | null;
+  text: string;
+  replyTo?: string | null;
+  traceId?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Status (§14)
+// ---------------------------------------------------------------------------
+
+/** Per-channel status snapshot exposed for `status`/`doctor` style output. */
+export interface ChannelStatusSnapshot {
+  channel: string;
+  accountId: string;
+  running: boolean;
+  connected?: boolean;
+  restartPending?: boolean;
+  reconnectAttempts?: number;
+  lastStartAt?: number;
+  lastStopAt?: number;
+  lastError?: string | null;
+}
+
+/** Per-turn status snapshot describing a currently-executing runtime invocation. */
+export interface TurnStatusSnapshot {
+  key: string;
+  channel: string;
+  accountId: string;
+  conversationId: string;
+  runtime: string;
+  cwd: string;
+  startedAt: number;
+}
+
+/** Aggregate gateway state combining channel and turn snapshots. */
+export interface GatewayRuntimeSnapshot {
+  channels: Record<string, ChannelStatusSnapshot>;
+  turns: Record<string, TurnStatusSnapshot>;
+}
+
+// ---------------------------------------------------------------------------
+// Channel adapter (§7.1–7.3, §13, §14)
+// ---------------------------------------------------------------------------
+
+/** Context passed to `ChannelAdapter.start()` for its lifetime. */
+export interface ChannelStartContext {
+  config: GatewayConfig;
+  accountId: string;
+  abortSignal: AbortSignal;
+  log: GatewayLogger;
+  emit: (event: GatewayInboundEnvelope) => Promise<void>;
+  setStatus: (patch: Partial<ChannelStatusSnapshot>) => void;
+}
+
+/** Context passed to `ChannelAdapter.stop()` when the manager is tearing the channel down. */
+export interface ChannelStopContext {
+  reason?: string;
+}
+
+/** Context passed to `ChannelAdapter.send()` when delivering a reply. */
+export interface ChannelSendContext {
+  message: GatewayOutboundMessage;
+  log: GatewayLogger;
+}
+
+/** Result returned by `ChannelAdapter.send()` — the upstream message id if known. */
+export interface ChannelSendResult {
+  providerMessageId?: string | null;
+}
+
+/** Context passed to `ChannelAdapter.streamBlock()` for progressive output forwarding. */
+export interface ChannelStreamBlockContext {
+  traceId: string;
+  accountId: string;
+  conversationId: string;
+  block: unknown;
+  log: GatewayLogger;
+}
+
+/** Upstream messaging surface such as BotCord, Telegram, or WeChat. */
+export interface ChannelAdapter {
+  readonly id: string;
+  readonly type: string;
+  start(ctx: ChannelStartContext): Promise<unknown>;
+  stop?(ctx: ChannelStopContext): Promise<void>;
+  send(ctx: ChannelSendContext): Promise<ChannelSendResult>;
+  status?(): ChannelStatusSnapshot;
+  streamBlock?(ctx: ChannelStreamBlockContext): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime adapter (§7.6)
+// ---------------------------------------------------------------------------
+
+/** One parsed block from a runtime's streaming output, forwarded via `onBlock`. */
+export interface StreamBlock {
+  /** Raw JSON object as emitted by the underlying CLI (e.g. claude-code stream-json). */
+  raw: unknown;
+  /** Normalized kind, used by channels to decide whether to forward progressive output. */
+  kind: "assistant_text" | "tool_use" | "tool_result" | "system" | "other";
+  /** 1-based sequence number within this turn. */
+  seq: number;
+}
+
+/** Options passed to a runtime adapter for a single turn. */
+export interface RuntimeRunOptions {
+  text: string;
+  /** Runtime-native session id for resume; null/empty for a new session. */
+  sessionId: string | null;
+  cwd: string;
+  /**
+   * Owning agent id (the daemon's `accountId` for this route). Lets adapters
+   * resolve per-agent state — e.g. the codex adapter uses it to locate the
+   * per-agent `CODEX_HOME` carrying the AGENTS.md that injects systemContext.
+   */
+  accountId: string;
+  signal: AbortSignal;
+  extraArgs?: string[];
+  trustLevel: TrustLevel;
+  /** System-level context injected alongside the user turn (memory, digest, room info). */
+  systemContext?: string;
+  /** Channel-agnostic bag for dispatch-time data (traceId, channel, conversation, etc.). */
+  context?: Record<string, unknown>;
+  /** Called for every parsed block while the turn is in progress. */
+  onBlock?: (block: StreamBlock) => void;
+}
+
+/** Result returned by a runtime adapter after a turn completes. */
+export interface RuntimeRunResult {
+  /** Final assistant text for this turn (concatenated if streamed). */
+  text: string;
+  /** New runtime session id to persist so the next turn can resume. */
+  newSessionId: string;
+  /** Optional cost in USD, if the runtime reports it. */
+  costUsd?: number;
+  /** Populated when the runtime reported a hard error. */
+  error?: string;
+}
+
+/** Detection result for whether a runtime binary/SDK is usable on this machine. */
+export interface RuntimeProbeResult {
+  available: boolean;
+  path?: string;
+  version?: string;
+}
+
+/** Downstream agent executor such as Claude Code, Codex, Gemini, or OpenClaw. */
+export interface RuntimeAdapter {
+  readonly id: string;
+  run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+  probe?(): RuntimeProbeResult;
+}
+
+// ---------------------------------------------------------------------------
+// Session store (§10)
+// ---------------------------------------------------------------------------
+
+/** Minimal fields needed to derive a session key for the JSON session store. */
+export interface SessionKeyInput {
+  runtime: string;
+  channel: string;
+  accountId: string;
+  conversationKind: "direct" | "group";
+  conversationId: string;
+  threadId?: string | null;
+}
+
+/** Persisted runtime-session record keyed by the derived session key. */
+export interface GatewaySessionEntry {
+  key: string;
+  runtime: string;
+  runtimeSessionId: string;
+  channel: string;
+  accountId: string;
+  conversationKind: "direct" | "group";
+  conversationId: string;
+  threadId?: string | null;
+  cwd: string;
+  updatedAt: number;
+}