@botcord/daemon 0.2.5 → 0.2.8

package/src/gateway/transcript-paths.ts

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+const FAST_PATH_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const WIN_RESERVED = new Set([
+  "CON", "PRN", "AUX", "NUL",
+  "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+  "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+]);
+const MAX_LEN = 200;
+const TRUNCATE_PREFIX = 191;
+
+function sha256_8(raw: string): string {
+  return createHash("sha256").update(raw).digest("hex").slice(0, 8);
+}
+
+function isControlOrNul(ch: number): boolean {
+  return ch === 0 || ch < 0x20 || ch === 0x7f;
+}
+
+function isAllControl(raw: string): boolean {
+  for (let i = 0; i < raw.length; i++) {
+    if (!isControlOrNul(raw.charCodeAt(i))) return false;
+  }
+  return true;
+}
+
+function percentEncodeByte(byte: number): string {
+  return "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+}
+
+function isWhitelistByte(byte: number): boolean {
+  // [A-Za-z0-9_-%] retained as literal
+  return (
+    (byte >= 0x30 && byte <= 0x39) || // 0-9
+    (byte >= 0x41 && byte <= 0x5a) || // A-Z
+    (byte >= 0x61 && byte <= 0x7a) || // a-z
+    byte === 0x5f || // _
+    byte === 0x2d || // -
+    byte === 0x25    // %  (kept literal — design §3.1)
+  );
+}
+
+function escapeRaw(raw: string): string {
+  const bytes = Buffer.from(raw, "utf8");
+  let out = "";
+  for (const b of bytes) {
+    out += isWhitelistByte(b) ? String.fromCharCode(b) : percentEncodeByte(b);
+  }
+  return out;
+}
+
+/**
+ * Truncate an escaped string to exactly MAX_LEN chars without splitting a `%XX`
+ * sequence. Keep first TRUNCATE_PREFIX chars (rolled back if mid-`%XX`), then
+ * `_` + sha256-8(raw) so the total is always ≤ MAX_LEN.
+ */
+function truncateEscaped(escaped: string, raw: string): string {
+  let cut = TRUNCATE_PREFIX;
+  // Roll back if cut sits inside a `%XX` sequence.
+  // A '%' at position cut-1 or cut-2 means the next 1 or 2 chars belong to it.
+  if (cut >= 1 && escaped[cut - 1] === "%") cut -= 1;
+  else if (cut >= 2 && escaped[cut - 2] === "%") cut -= 2;
+  const hash = sha256_8(raw);
+  return escaped.slice(0, cut) + "_" + hash;
+}
+
+/**
+ * Convert a raw ID into a filesystem-safe path segment.
+ *
+ * Order (must not be reordered — see design §3.1):
+ *   1. obviously invalid (empty / `.` / `..` / all control/NUL)
+ *      → `_invalid_<sha256-8>`
+ *   2. Windows reserved name (CON/PRN/AUX/NUL/COM1-9/LPT1-9, case-insensitive)
+ *      → `_win_<raw>`
+ *   3. fast path (`^[A-Za-z0-9_-]{1,128}$`) → return raw
+ *   4. percent-encode non-whitelist bytes; truncate at 200 chars without
+ *      splitting a `%XX` (191 prefix + `_` + sha256-8)
+ *
+ * The original ID is always written into the transcript record itself; this
+ * helper only sanitizes the on-disk filename.
+ */
+export function safePathSegment(raw: string): string {
+  // 1. obviously invalid
+  if (raw === "" || raw === "." || raw === ".." || isAllControl(raw)) {
+    return "_invalid_" + sha256_8(raw);
+  }
+
+  // 2. Windows reserved names — must run BEFORE fast path so `CON` is not
+  //    leaked unchanged on case-insensitive filesystems.
+  if (WIN_RESERVED.has(raw.toUpperCase())) {
+    return "_win_" + raw;
+  }
+
+  // 3. fast path
+  if (FAST_PATH_RE.test(raw)) return raw;
+
+  // 4. escape + maybe truncate
+  const escaped = escapeRaw(raw);
+  if (escaped.length <= MAX_LEN) return escaped;
+  return truncateEscaped(escaped, raw);
+}
+
+/**
+ * Resolve the on-disk transcript file for a given (agent, room, topic). Used
+ * by the writer AND the CLI subcommands so both look at the same file.
+ *
+ * Layout (design §3.1):
+ *   <rootDir>/<agentId>/transcripts/<roomId>/<topicId|_default>.jsonl
+ *
+ * Where <rootDir> is typically `~/.botcord/agents`.
+ */
+export function transcriptFilePath(
+  rootDir: string,
+  agentId: string,
+  roomId: string,
+  topicId: string | null,
+): string {
+  return path.join(
+    rootDir,
+    safePathSegment(agentId),
+    "transcripts",
+    safePathSegment(roomId),
+    (topicId === null ? "_default" : safePathSegment(topicId)) + ".jsonl",
+  );
+}
+
+/** Directory holding a (agent, room) pair's transcript files. */
+export function transcriptRoomDir(
+  rootDir: string,
+  agentId: string,
+  roomId: string,
+): string {
+  return path.join(
+    rootDir,
+    safePathSegment(agentId),
+    "transcripts",
+    safePathSegment(roomId),
+  );
+}
+
+/** Directory holding all transcript rooms for a single agent. */
+export function transcriptAgentRoot(rootDir: string, agentId: string): string {
+  return path.join(rootDir, safePathSegment(agentId), "transcripts");
+}

package/src/gateway/transcript.ts

@@ -0,0 +1,300 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { GatewayLogger } from "./log.js";
+import { transcriptFilePath } from "./transcript-paths.js";
+
+/**
+ * Soft cap on a single textual field (`text` / `composedText` / `finalText`).
+ * Anything longer is truncated and `truncated.<field>` set to `true`.
+ */
+export const TRANSCRIPT_TEXT_LIMIT = 32 * 1024;
+
+/** Soft cap on a single transcript file before rotation. */
+export const TRANSCRIPT_FILE_LIMIT = 8 * 1024 * 1024;
+
+/** Default root directory for per-agent transcript trees. */
+export function defaultTranscriptRoot(): string {
+  return path.join(homedir(), ".botcord", "agents");
+}
+
+// ---------------------------------------------------------------------------
+// Record types — see design §3.2
+// ---------------------------------------------------------------------------
+
+export type TranscriptRecordKind =
+  | "inbound"
+  | "dispatched"
+  | "compose_failed"
+  | "outbound"
+  | "turn_error"
+  | "attention_skipped"
+  | "dropped";
+
+export interface TranscriptRecordBase {
+  ts: string;
+  kind: TranscriptRecordKind;
+  turnId: string;
+  agentId: string;
+  roomId: string;
+  topicId: string | null;
+}
+
+export interface TranscriptSenderInfo {
+  id: string;
+  kind: "user" | "agent" | "system";
+  name?: string;
+}
+
+export interface InboundTranscriptRecord extends TranscriptRecordBase {
+  kind: "inbound";
+  messageId: string;
+  sender: TranscriptSenderInfo;
+  text: string;
+  rawBatchEntries?: number;
+  trace?: { id: string; streamable?: boolean };
+  truncated?: { text?: true };
+}
+
+export interface DispatchedTranscriptRecord extends TranscriptRecordBase {
+  kind: "dispatched";
+  composedText: string;
+  mergedFromTurnIds?: string[];
+  runtime: string;
+  truncated?: { composedText?: true };
+}
+
+export interface ComposeFailedTranscriptRecord extends TranscriptRecordBase {
+  kind: "compose_failed";
+  error: string;
+  fallback: "raw_text";
+}
+
+export type DeliveryStatus =
+  | "delivered"
+  | "gated_non_owner_chat"
+  | "empty_text"
+  | "send_failed";
+
+export interface TranscriptBlockSummary {
+  type: string;
+  chars?: number;
+  name?: string;
+}
+
+export interface OutboundTranscriptRecord extends TranscriptRecordBase {
+  kind: "outbound";
+  runtime: string;
+  runtimeSessionId?: string | null;
+  durationMs: number;
+  costUsd?: number;
+  finalText: string;
+  deliveryStatus: DeliveryStatus;
+  deliveryReason?: string | null;
+  blocks?: TranscriptBlockSummary[];
+  truncated?: { finalText?: true };
+}
+
+export interface TurnErrorTranscriptRecord extends TranscriptRecordBase {
+  kind: "turn_error";
+  phase: "runtime" | "timeout";
+  error: string;
+  durationMs: number;
+}
+
+export interface AttentionSkippedTranscriptRecord extends TranscriptRecordBase {
+  kind: "attention_skipped";
+  reason: string;
+}
+
+export type DroppedReason =
+  | "batch_merged"
+  | "queue_cancel_previous"
+  | "queue_overflow";
+
+export interface DroppedTranscriptRecord extends TranscriptRecordBase {
+  kind: "dropped";
+  reason: DroppedReason;
+  supersededBy?: string | null;
+}
+
+export type TranscriptRecord =
+  | InboundTranscriptRecord
+  | DispatchedTranscriptRecord
+  | ComposeFailedTranscriptRecord
+  | OutboundTranscriptRecord
+  | TurnErrorTranscriptRecord
+  | AttentionSkippedTranscriptRecord
+  | DroppedTranscriptRecord;
+
+// ---------------------------------------------------------------------------
+// Truncation helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Truncate `value` to TRANSCRIPT_TEXT_LIMIT chars. Returns the (possibly
+ * truncated) text and whether truncation occurred. Surrogate-pair aware: if
+ * the cut would split a pair, step back one char.
+ */
+export function truncateTextField(value: string): { text: string; truncated: boolean } {
+  if (value.length <= TRANSCRIPT_TEXT_LIMIT) return { text: value, truncated: false };
+  let cut = TRANSCRIPT_TEXT_LIMIT;
+  const code = value.charCodeAt(cut - 1);
+  if (code >= 0xd800 && code <= 0xdbff) cut -= 1; // mid-surrogate
+  return { text: value.slice(0, cut), truncated: true };
+}
+
+// ---------------------------------------------------------------------------
+// Writer
+// ---------------------------------------------------------------------------
+
+export interface TranscriptWriter {
+  /** Append a record. Failures are logged and swallowed. */
+  write(rec: TranscriptRecord): void;
+  /** Whether persistence is on. CLI / tests may read this. */
+  readonly enabled: boolean;
+  /** Root directory used for path resolution. */
+  readonly rootDir: string;
+}
+
+export interface CreateTranscriptWriterOptions {
+  /** Defaults to `~/.botcord/agents`. */
+  rootDir?: string;
+  log: GatewayLogger;
+  /** Defaults to `false` — see design §6 (default-off). */
+  enabled?: boolean;
+  /** Override file rotation threshold (bytes). Defaults to TRANSCRIPT_FILE_LIMIT. */
+  maxFileBytes?: number;
+}
+
+interface FileMeta {
+  size: number;
+}
+
+class NoopTranscriptWriter implements TranscriptWriter {
+  readonly enabled = false;
+  readonly rootDir: string;
+  constructor(rootDir: string) {
+    this.rootDir = rootDir;
+  }
+  write(_rec: TranscriptRecord): void {
+    // intentionally empty
+  }
+}
+
+class FsTranscriptWriter implements TranscriptWriter {
+  readonly enabled = true;
+  readonly rootDir: string;
+  private readonly log: GatewayLogger;
+  private readonly maxFileBytes: number;
+  private readonly fileMeta = new Map<string, FileMeta>();
+  private firstWriteAnnounced = false;
+
+  constructor(rootDir: string, log: GatewayLogger, maxFileBytes: number) {
+    this.rootDir = rootDir;
+    this.log = log;
+    this.maxFileBytes = maxFileBytes;
+  }
+
+  write(rec: TranscriptRecord): void {
+    try {
+      const file = transcriptFilePath(this.rootDir, rec.agentId, rec.roomId, rec.topicId);
+      const dir = path.dirname(file);
+      try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+      } catch {
+        // best-effort — appendFileSync below will surface a real error
+      }
+
+      const line = JSON.stringify(rec) + "\n";
+      const bytes = Buffer.byteLength(line, "utf8");
+
+      // Rotate before appending if the existing file would exceed the cap.
+      const meta = this.statFile(file);
+      if (meta.size > 0 && meta.size + bytes > this.maxFileBytes) {
+        this.rotate(file);
+        this.fileMeta.delete(file);
+      }
+
+      appendFileSync(file, line, { mode: 0o600 });
+      const cur = this.fileMeta.get(file) ?? { size: meta.size };
+      cur.size = (cur.size || 0) + bytes;
+      this.fileMeta.set(file, cur);
+
+      if (!this.firstWriteAnnounced) {
+        this.firstWriteAnnounced = true;
+        this.log.info("transcript enabled", { dir: this.rootDir });
+      }
+    } catch (err) {
+      this.log.warn("transcript: write failed", {
+        kind: rec.kind,
+        turnId: rec.turnId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  private statFile(file: string): FileMeta {
+    const cached = this.fileMeta.get(file);
+    if (cached) return cached;
+    try {
+      const st = statSync(file);
+      const meta = { size: st.size };
+      this.fileMeta.set(file, meta);
+      return meta;
+    } catch {
+      const meta = { size: 0 };
+      this.fileMeta.set(file, meta);
+      return meta;
+    }
+  }
+
+  private rotate(file: string): void {
+    const stamp = formatStamp(new Date());
+    const ext = ".jsonl";
+    const base = file.endsWith(ext) ? file.slice(0, -ext.length) : file;
+    const rotated = `${base}.${stamp}${ext}`;
+    try {
+      renameSync(file, rotated);
+    } catch (err) {
+      this.log.warn("transcript: rotate failed", {
+        file,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+export function createTranscriptWriter(
+  opts: CreateTranscriptWriterOptions,
+): TranscriptWriter {
+  const rootDir = opts.rootDir ?? defaultTranscriptRoot();
+  const enabled = opts.enabled ?? false;
+  if (!enabled) return new NoopTranscriptWriter(rootDir);
+  const maxBytes = opts.maxFileBytes ?? TRANSCRIPT_FILE_LIMIT;
+  return new FsTranscriptWriter(rootDir, opts.log, maxBytes);
+}
+
+/**
+ * Resolve the tri-state enable flag (env wins; otherwise config). See design §5.
+ *  - env === "1" → true (force on)
+ *  - env === "0" → false (force off)
+ *  - any other / unset → fall back to `configEnabled`
+ */
+export function resolveTranscriptEnabled(
+  envVal: string | undefined,
+  configEnabled: boolean,
+): boolean {
+  if (envVal === "1") return true;
+  if (envVal === "0") return false;
+  return configEnabled;
+}
+
+function formatStamp(d: Date): string {
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return (
+    `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
+    `-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}`
+  );
+}

package/src/gateway/types.ts

@@ -21,6 +21,20 @@ export type QueueMode = "serial" | "cancel-previous";
 /** Source-based trust tier used by runtimes to pick default permission flags. */
 export type TrustLevel = "owner" | "trusted" | "public";
 
+/**
+ * Resolved OpenClaw gateway endpoint for a route. Built eagerly in
+ * `toGatewayConfig` from the `DaemonConfig.openclawGateways` registry plus the
+ * `RouteRule.gateway` / `openclawAgent` choice — the dispatcher never needs
+ * to re-query the registry. `name` is preserved purely for logging/snapshot.
+ */
+export interface ResolvedOpenclawGateway {
+  name: string;
+  url: string;
+  token?: string;
+  /** OpenClaw agent profile, with the route override already applied. */
+  openclawAgent?: string;
+}
+
 /** Declarative route entry selecting the runtime and execution flags for matched messages. */
 export interface GatewayRoute {
   match?: RouteMatch;
@@ -29,6 +43,8 @@ export interface GatewayRoute {
   extraArgs?: string[];
   queueMode?: QueueMode;
   trustLevel?: TrustLevel;
+  /** Required when `runtime === "openclaw-acp"`. Resolved at config-load time. */
+  gateway?: ResolvedOpenclawGateway;
 }
 
 // ---------------------------------------------------------------------------
@@ -268,6 +284,15 @@ export interface RuntimeRunOptions {
    * per-agent `CODEX_HOME` carrying the AGENTS.md that injects systemContext.
    */
   accountId: string;
+  /**
+   * Hub URL the owning agent is registered against. Forwarded to runtimes
+   * so spawned CLI subprocesses can target the correct hub via
+   * `BOTCORD_HUB` (see `cli-resolver.buildCliEnv`). Optional because the
+   * dispatcher cannot always resolve a per-agent hub (e.g. for agents
+   * provisioned after boot); when unset, runtimes leave `BOTCORD_HUB`
+   * unspecified and the bundled CLI falls back to its own default.
+   */
+  hubUrl?: string;
   signal: AbortSignal;
   extraArgs?: string[];
   trustLevel: TrustLevel;
@@ -277,6 +302,13 @@ export interface RuntimeRunOptions {
   context?: Record<string, unknown>;
   /** Called for every parsed block while the turn is in progress. */
   onBlock?: (block: StreamBlock) => void;
+  /**
+   * External service endpoint required by some runtimes (first user:
+   * openclaw-acp). Resolved at config-load time and passed through here per
+   * call — runtime factories do not see it. Mirrors the `hubUrl` precedent of
+   * lifting service URLs out of `extraArgs` into typed first-class fields.
+   */
+  gateway?: ResolvedOpenclawGateway;
 }
 
 /** Result returned by a runtime adapter after a turn completes. */