@botcord/daemon 0.1.1

package/src/gateway/gateway.ts

@@ -0,0 +1,211 @@
+import { ChannelManager, type ChannelBackoffOptions } from "./channel-manager.js";
+import { Dispatcher, type RuntimeFactory } from "./dispatcher.js";
+import { consoleLogger, type GatewayLogger } from "./log.js";
+import { createRuntime } from "./runtimes/registry.js";
+import { DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS, SessionStore } from "./session-store.js";
+import type {
+  ChannelAdapter,
+  GatewayChannelConfig,
+  GatewayConfig,
+  GatewayRoute,
+  GatewayRuntimeSnapshot,
+  InboundObserver,
+  SystemContextBuilder,
+  UserTurnBuilder,
+} from "./types.js";
+
+/** Constructor options for `Gateway`. */
+export interface GatewayBootOptions {
+  config: GatewayConfig;
+  sessionStorePath: string;
+  /** Max age for persisted runtime session entries. Defaults to 30 days. */
+  sessionStoreMaxEntryAgeMs?: number;
+  createChannel: (cfg: GatewayChannelConfig) => ChannelAdapter;
+  createRuntime?: RuntimeFactory;
+  log?: GatewayLogger;
+  turnTimeoutMs?: number;
+  backoffMs?: ChannelBackoffOptions;
+  /**
+   * Hook that composes per-turn system context (working memory, cross-room
+   * digest, etc.). Forwarded to the dispatcher; errors are logged and do not
+   * abort the turn.
+   */
+  buildSystemContext?: SystemContextBuilder;
+  /**
+   * Observer called after the dispatcher acks each inbound message. Useful
+   * for activity tracking or metrics. Errors are logged and swallowed.
+   */
+  onInbound?: InboundObserver;
+  /**
+   * Optional composer that wraps the user-turn text with channel-specific
+   * metadata (sender label, room header, NO_REPLY hint…) before it is handed
+   * to the runtime. Forwarded to the dispatcher; see {@link UserTurnBuilder}.
+   */
+  composeUserTurn?: UserTurnBuilder;
+}
+
+/** Default runtime factory: delegates to the built-in registry; ignores extraArgs at construction. */
+const defaultRuntimeFactory: RuntimeFactory = (runtimeId) => createRuntime(runtimeId);
+
+/**
+ * Top-level gateway bootstrap. Wires `ChannelManager` → `Dispatcher` →
+ * `SessionStore` + runtime factory. Channel adapters are constructed from
+ * `opts.createChannel` per `config.channels[]` entry and keyed by adapter id.
+ */
+export class Gateway {
+  private readonly config: GatewayConfig;
+  private readonly log: GatewayLogger;
+  private readonly sessionStore: SessionStore;
+  private readonly dispatcher: Dispatcher;
+  private readonly channelManager: ChannelManager;
+  private readonly channelMap: Map<string, ChannelAdapter>;
+  private readonly createChannelFn: (cfg: GatewayChannelConfig) => ChannelAdapter;
+  private readonly managedRoutes: Map<string, GatewayRoute> = new Map();
+  private started = false;
+  private stopped = false;
+
+  constructor(opts: GatewayBootOptions) {
+    this.config = opts.config;
+    this.log = opts.log ?? consoleLogger;
+    this.createChannelFn = opts.createChannel;
+
+    this.channelMap = new Map();
+    const channelList: ChannelAdapter[] = [];
+    for (const cfg of opts.config.channels) {
+      const adapter = opts.createChannel(cfg);
+      this.channelMap.set(adapter.id, adapter);
+      channelList.push(adapter);
+    }
+
+    for (const route of opts.config.managedRoutes ?? []) {
+      const id = route.match?.accountId;
+      if (typeof id === "string") {
+        this.managedRoutes.set(id, route);
+      } else {
+        // Defensive: buildManagedRoutes always sets match.accountId, so
+        // reaching here means a caller constructed GatewayConfig directly
+        // with a malformed entry. Log so it's not silently dropped.
+        this.log.warn("gateway: dropping seed managed route with no accountId", {
+          runtime: route.runtime,
+          cwd: route.cwd,
+        });
+      }
+    }
+
+    this.sessionStore = new SessionStore({
+      path: opts.sessionStorePath,
+      log: this.log,
+      maxEntryAgeMs: opts.sessionStoreMaxEntryAgeMs ?? DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS,
+    });
+
+    const runtimeFactory = opts.createRuntime ?? defaultRuntimeFactory;
+
+    this.dispatcher = new Dispatcher({
+      config: this.config,
+      channels: this.channelMap,
+      runtime: runtimeFactory,
+      sessionStore: this.sessionStore,
+      log: this.log,
+      turnTimeoutMs: opts.turnTimeoutMs,
+      buildSystemContext: opts.buildSystemContext,
+      onInbound: opts.onInbound,
+      composeUserTurn: opts.composeUserTurn,
+      managedRoutes: this.managedRoutes,
+    });
+
+    this.channelManager = new ChannelManager({
+      config: this.config,
+      channels: channelList,
+      log: this.log,
+      emit: (env) => this.dispatcher.handle(env),
+      backoffMs: opts.backoffMs,
+    });
+  }
+
+  /** Load persisted sessions and start every configured channel. */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    await this.sessionStore.load();
+    await this.channelManager.startAll();
+  }
+
+  /** Tear down every channel; idempotent. */
+  async stop(reason?: string): Promise<void> {
+    if (this.stopped) return;
+    this.stopped = true;
+    await this.channelManager.stopAll(reason);
+  }
+
+  /** Aggregate status snapshot combining channel and turn state. */
+  snapshot(): GatewayRuntimeSnapshot {
+    return {
+      channels: this.channelManager.status(),
+      turns: this.dispatcher.turns(),
+    };
+  }
+
+  /**
+   * Read-only view of the synthesized per-agent routes. Exposed for
+   * snapshot/debug callers and tests; matching reads the live internal map.
+   */
+  listManagedRoutes(): GatewayRoute[] {
+    return Array.from(this.managedRoutes.values());
+  }
+
+  /** Replace all managed routes atomically. Used by `reload_config`. */
+  replaceManagedRoutes(routes: Map<string, GatewayRoute>): void {
+    this.managedRoutes.clear();
+    for (const [id, route] of routes) {
+      this.managedRoutes.set(id, route);
+    }
+  }
+
+  /** Add or update one managed route. Used by provision hot-add. */
+  upsertManagedRoute(accountId: string, route: GatewayRoute): void {
+    this.managedRoutes.set(accountId, route);
+  }
+
+  /** Drop one managed route. Used by revoke / removeChannel. */
+  removeManagedRoute(accountId: string): void {
+    this.managedRoutes.delete(accountId);
+  }
+
+  /**
+   * Hot-plug a new channel without restarting the gateway. The daemon's
+   * control plane calls this after a `provision_agent` frame: it has already
+   * written the new agent's credentials to disk and updated `config.json`,
+   * and now needs the channel to come online without tearing down peers.
+   *
+   * The caller supplies a fully-constructed `GatewayChannelConfig` entry;
+   * `createChannel` (from the original `GatewayBootOptions`) is invoked to
+   * build the adapter. The config entry is appended to `config.channels`
+   * so status/router lookups see it; it is otherwise a pure in-memory op.
+   */
+  async addChannel(cfg: GatewayChannelConfig): Promise<void> {
+    if (this.stopped) {
+      throw new Error("gateway already stopped");
+    }
+    if (this.channelMap.has(cfg.id)) {
+      throw new Error(`channel "${cfg.id}" already registered`);
+    }
+    this.config.channels.push(cfg);
+    const adapter = this.createChannelFn(cfg);
+    this.channelMap.set(adapter.id, adapter);
+    this.channelManager.addOne(adapter);
+  }
+
+  /**
+   * Remove a channel registered earlier (either at boot or via
+   * `addChannel`). Aborts the running turn loop, awaits the adapter's
+   * `stop()`, drops the entry from the channel map and config.channels.
+   * No-op on unknown id.
+   */
+  async removeChannel(id: string, reason?: string): Promise<void> {
+    if (!this.channelMap.has(id)) return;
+    await this.channelManager.removeOne(id, reason);
+    this.channelMap.delete(id);
+    const idx = this.config.channels.findIndex((c) => c.id === id);
+    if (idx >= 0) this.config.channels.splice(idx, 1);
+  }
+}

package/src/gateway/index.ts

@@ -0,0 +1,29 @@
+export * from "./types.js";
+export * from "./log.js";
+export * from "./runtimes/registry.js";
+export * from "./channels/index.js";
+export { sanitizeUntrustedContent, sanitizeSenderName } from "./channels/sanitize.js";
+export { sessionKey, SessionStore, type SessionStoreOptions } from "./session-store.js";
+export { resolveRoute, matchesRoute } from "./router.js";
+export { ChannelManager, type ChannelManagerOptions, type ChannelBackoffOptions } from "./channel-manager.js";
+export { Dispatcher, type DispatcherOptions, type RuntimeFactory } from "./dispatcher.js";
+export { Gateway, type GatewayBootOptions } from "./gateway.js";
+export {
+  ClaudeCodeAdapter,
+  probeClaude,
+  resolveClaudeCommand,
+} from "./runtimes/claude-code.js";
+export { CodexAdapter, probeCodex, resolveCodexCommand } from "./runtimes/codex.js";
+export { GeminiAdapter, probeGemini, resolveGeminiCommand } from "./runtimes/gemini.js";
+export {
+  NdjsonStreamAdapter,
+  type NdjsonEventCtx,
+  type NdjsonRunState,
+} from "./runtimes/ndjson-stream.js";
+export {
+  firstExistingPath,
+  readCommandVersion,
+  resolveCommandOnPath,
+  resolveHomePath,
+  type ProbeDeps,
+} from "./runtimes/probe.js";

package/src/gateway/log.ts

@@ -0,0 +1,30 @@
+/** Structured logger interface used across the gateway core and adapters. */
+export interface GatewayLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  debug(msg: string, meta?: Record<string, unknown>): void;
+}
+
+type Level = "info" | "warn" | "error" | "debug";
+
+function write(level: Level, msg: string, meta?: Record<string, unknown>): void {
+  const line = JSON.stringify({
+    ts: new Date().toISOString(),
+    level,
+    msg,
+    ...(meta ?? {}),
+  });
+  // Always write to stderr so stdout stays clean for NDJSON-style channel output.
+  process.stderr.write(line + "\n");
+}
+
+/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+export const consoleLogger: GatewayLogger = {
+  info: (msg, meta) => write("info", msg, meta),
+  warn: (msg, meta) => write("warn", msg, meta),
+  error: (msg, meta) => write("error", msg, meta),
+  debug: (msg, meta) => {
+    if (process.env.BOTCORD_GATEWAY_DEBUG) write("debug", msg, meta);
+  },
+};

package/src/gateway/router.ts

@@ -0,0 +1,60 @@
+import type {
+  GatewayConfig,
+  GatewayInboundMessage,
+  GatewayRoute,
+  RouteMatch,
+} from "./types.js";
+
+/** Returns true if every provided field of `match` matches `message`; undefined match matches all. */
+export function matchesRoute(
+  message: GatewayInboundMessage,
+  match: RouteMatch | undefined,
+): boolean {
+  if (!match) return true;
+  if (match.channel !== undefined && match.channel !== message.channel) return false;
+  if (match.accountId !== undefined && match.accountId !== message.accountId) return false;
+  if (match.conversationId !== undefined && match.conversationId !== message.conversation.id) {
+    return false;
+  }
+  if (
+    match.conversationPrefix !== undefined &&
+    !message.conversation.id.startsWith(match.conversationPrefix)
+  ) {
+    return false;
+  }
+  if (
+    match.conversationKind !== undefined &&
+    match.conversationKind !== message.conversation.kind
+  ) {
+    return false;
+  }
+  if (match.senderId !== undefined && match.senderId !== message.sender.id) return false;
+  if (match.mentioned !== undefined) {
+    const actual = message.mentioned ?? false;
+    if (match.mentioned !== actual) return false;
+  }
+  return true;
+}
+
+/**
+ * Picks the first matching route in priority order:
+ *   1. `config.routes[]` (user-authored)
+ *   2. `managedRoutes` (daemon-synthesized per-agent)
+ *   3. `config.defaultRoute`
+ */
+export function resolveRoute(
+  message: GatewayInboundMessage,
+  config: Pick<GatewayConfig, "defaultRoute" | "routes">,
+  managedRoutes?: readonly GatewayRoute[],
+): GatewayRoute {
+  const routes = config.routes ?? [];
+  for (const route of routes) {
+    if (matchesRoute(message, route.match)) return route;
+  }
+  if (managedRoutes) {
+    for (const route of managedRoutes) {
+      if (matchesRoute(message, route.match)) return route;
+    }
+  }
+  return config.defaultRoute;
+}

package/src/gateway/runtimes/claude-code.ts

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import {
+  firstExistingPath,
+  readCommandVersion,
+  resolveCommandOnPath,
+  resolveHomePath,
+  type ProbeDeps,
+} from "./probe.js";
+import type { RuntimeProbeResult, RuntimeRunOptions, StreamBlock } from "../types.js";
+
+const CLAUDE_DESKTOP_CLI_RELATIVE_PATH = path.join(
+  "Applications",
+  "Claude Code URL Handler.app",
+  "Contents",
+  "MacOS",
+  "claude",
+);
+const CLAUDE_DESKTOP_CLI_SYSTEM_PATH =
+  "/Applications/Claude Code URL Handler.app/Contents/MacOS/claude";
+function isValidClaudeSessionId(sessionId: string): boolean {
+  if (sessionId.length === 0 || sessionId.length > 512) return false;
+  if (sessionId.startsWith("-")) return false;
+  for (const ch of sessionId) {
+    const code = ch.codePointAt(0);
+    if (code === undefined || code < 0x20 || code === 0x7f) return false;
+  }
+  return true;
+}
+
+function invalidClaudeSessionIdError(): string {
+  return "claude-code: invalid sessionId (expected non-control text not starting with '-')";
+}
+
+/** Resolve the Claude Code CLI path on PATH or the macOS desktop bundle fallback. */
+export function resolveClaudeCommand(deps: ProbeDeps = {}): string | null {
+  const onPath = resolveCommandOnPath("claude", deps);
+  if (onPath) return onPath;
+  if ((deps.platform ?? process.platform) !== "darwin") return null;
+  return firstExistingPath(
+    [resolveHomePath(CLAUDE_DESKTOP_CLI_RELATIVE_PATH, deps), CLAUDE_DESKTOP_CLI_SYSTEM_PATH],
+    deps,
+  );
+}
+
+/** Probe whether the Claude Code CLI is installed and report its version. */
+export function probeClaude(deps: ProbeDeps = {}): RuntimeProbeResult {
+  const command = resolveClaudeCommand(deps);
+  if (!command) return { available: false };
+  return {
+    available: true,
+    path: command,
+    version: readCommandVersion(command, [], deps) ?? undefined,
+  };
+}
+
+/**
+ * Claude Code adapter — spawns `claude -p "<text>" --output-format stream-json`
+ * (with `--resume <sid>` when available) and parses the ndjson stream.
+ *
+ * stream-json shape (abridged):
+ *   {type:"system", subtype:"init", session_id:"...", ...}
+ *   {type:"assistant", message:{content:[{type:"text", text:"..."} | {type:"tool_use", ...}]}}
+ *   {type:"user", message:{content:[{type:"tool_result", ...}]}}
+ *   {type:"result", subtype:"success", session_id:"...", total_cost_usd: 0.01, result:"final text"}
+ */
+export class ClaudeCodeAdapter extends NdjsonStreamAdapter {
+  readonly id = "claude-code" as const;
+
+  private readonly explicitBinary: string | undefined;
+  private resolvedBinary: string | null = null;
+
+  constructor(opts?: { binary?: string }) {
+    super();
+    this.explicitBinary = opts?.binary ?? process.env.BOTCORD_CLAUDE_BIN;
+  }
+
+  probe(): RuntimeProbeResult {
+    return probeClaude();
+  }
+
+  override async run(opts: RuntimeRunOptions) {
+    if (opts.sessionId && !isValidClaudeSessionId(opts.sessionId)) {
+      return { text: "", newSessionId: "", error: invalidClaudeSessionIdError() };
+    }
+    return super.run(opts);
+  }
+
+  protected resolveBinary(): string {
+    if (this.explicitBinary) return this.explicitBinary;
+    if (this.resolvedBinary) return this.resolvedBinary;
+    // Falls back to the macOS Claude Code URL Handler bundle when not on PATH.
+    this.resolvedBinary = resolveClaudeCommand() ?? "claude";
+    return this.resolvedBinary;
+  }
+
+  protected buildArgs(opts: RuntimeRunOptions): string[] {
+    const args = ["-p", opts.text, "--output-format", "stream-json", "--verbose"];
+    if (opts.sessionId) {
+      if (!isValidClaudeSessionId(opts.sessionId)) throw new Error(invalidClaudeSessionIdError());
+      args.push("--resume", opts.sessionId);
+    }
+    // Permission-mode policy:
+    //  - owner: acceptEdits (owner trusts their own agent).
+    //  - non-owner (trusted/public): default (let Claude Code prompt / reject edits per its own rules).
+    // `extraArgs` still wins — operators who know what they're doing can override either.
+    if (!opts.extraArgs?.some((a) => a.startsWith("--permission-mode"))) {
+      if (opts.trustLevel === "owner") {
+        args.push("--permission-mode", "acceptEdits");
+      } else {
+        args.push("--permission-mode", "default");
+      }
+    }
+    // Claude Code's `--append-system-prompt` is applied per invocation and NOT
+    // persisted in the resumed session transcript — ideal for memory / digest
+    // content that should re-evaluate every turn.
+    if (opts.systemContext && !opts.extraArgs?.includes("--append-system-prompt")) {
+      args.push("--append-system-prompt", opts.systemContext);
+    }
+    if (opts.extraArgs?.length) args.push(...opts.extraArgs);
+    return args;
+  }
+
+  protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void {
+    const obj = raw as {
+      type?: string;
+      subtype?: string;
+      session_id?: string;
+      total_cost_usd?: number;
+      result?: string;
+      message?: { content?: Array<{ type?: string; text?: string }> };
+    };
+
+    ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+
+    if (obj.type === "system" && obj.session_id) {
+      ctx.state.newSessionId = String(obj.session_id);
+      return;
+    }
+    if (obj.type === "assistant" && Array.isArray(obj.message?.content)) {
+      for (const c of obj.message.content) {
+        if (c?.type === "text" && typeof c.text === "string") {
+          ctx.appendAssistantText(c.text);
+        }
+      }
+      return;
+    }
+    if (obj.type === "result") {
+      if (typeof obj.total_cost_usd === "number") ctx.state.costUsd = obj.total_cost_usd;
+      if (obj.subtype === "success") {
+        if (typeof obj.session_id === "string") ctx.state.newSessionId = obj.session_id;
+        if (typeof obj.result === "string") ctx.state.finalText = obj.result;
+      } else {
+        // Non-success result (e.g. resume targeted a missing UUID). Claude Code
+        // still emits a fresh `session_id` for the just-spawned empty session —
+        // persisting it would trap us into resuming a useless UUID forever.
+        // Wipe newSessionId so the dispatcher deletes the stale entry instead.
+        // The CLI also exits non-zero, so the base adapter synthesizes errorText
+        // from stderr if `obj.result` is missing.
+        ctx.state.newSessionId = "";
+        if (typeof obj.result === "string") ctx.state.errorText = obj.result;
+      }
+    }
+  }
+}
+
+function normalizeBlock(obj: any, seq: number): StreamBlock {
+  let kind: StreamBlock["kind"] = "other";
+  if (obj?.type === "assistant") {
+    const contents = Array.isArray(obj.message?.content) ? obj.message.content : [];
+    if (contents.some((c: any) => c?.type === "tool_use")) kind = "tool_use";
+    else if (contents.some((c: any) => c?.type === "text")) kind = "assistant_text";
+  } else if (obj?.type === "user") {
+    const contents = Array.isArray(obj.message?.content) ? obj.message.content : [];
+    if (contents.some((c: any) => c?.type === "tool_result")) kind = "tool_result";
+  } else if (obj?.type === "system") {
+    kind = "system";
+  }
+  return { raw: obj, kind, seq };
+}