@botcord/daemon 0.2.4 → 0.2.6

package/dist/gateway/transcript-paths.js

@@ -0,0 +1,114 @@
+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) {
+    return createHash("sha256").update(raw).digest("hex").slice(0, 8);
+}
+function isControlOrNul(ch) {
+    return ch === 0 || ch < 0x20 || ch === 0x7f;
+}
+function isAllControl(raw) {
+    for (let i = 0; i < raw.length; i++) {
+        if (!isControlOrNul(raw.charCodeAt(i)))
+            return false;
+    }
+    return true;
+}
+function percentEncodeByte(byte) {
+    return "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+}
+function isWhitelistByte(byte) {
+    // [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) {
+    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, raw) {
+    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) {
+    // 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, agentId, roomId, topicId) {
+    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, agentId, roomId) {
+    return path.join(rootDir, safePathSegment(agentId), "transcripts", safePathSegment(roomId));
+}
+/** Directory holding all transcript rooms for a single agent. */
+export function transcriptAgentRoot(rootDir, agentId) {
+    return path.join(rootDir, safePathSegment(agentId), "transcripts");
+}

package/dist/gateway/transcript.d.ts

@@ -0,0 +1,123 @@
+import type { GatewayLogger } from "./log.js";
+/**
+ * Soft cap on a single textual field (`text` / `composedText` / `finalText`).
+ * Anything longer is truncated and `truncated.<field>` set to `true`.
+ */
+export declare const TRANSCRIPT_TEXT_LIMIT: number;
+/** Soft cap on a single transcript file before rotation. */
+export declare const TRANSCRIPT_FILE_LIMIT: number;
+/** Default root directory for per-agent transcript trees. */
+export declare function defaultTranscriptRoot(): string;
+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;
+/**
+ * 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 declare function truncateTextField(value: string): {
+    text: string;
+    truncated: boolean;
+};
+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;
+}
+export declare function createTranscriptWriter(opts: CreateTranscriptWriterOptions): TranscriptWriter;
+/**
+ * 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 declare function resolveTranscriptEnabled(envVal: string | undefined, configEnabled: boolean): boolean;

package/dist/gateway/transcript.js

@@ -0,0 +1,147 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+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() {
+    return path.join(homedir(), ".botcord", "agents");
+}
+// ---------------------------------------------------------------------------
+// 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) {
+    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 };
+}
+class NoopTranscriptWriter {
+    enabled = false;
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    write(_rec) {
+        // intentionally empty
+    }
+}
+class FsTranscriptWriter {
+    enabled = true;
+    rootDir;
+    log;
+    maxFileBytes;
+    fileMeta = new Map();
+    firstWriteAnnounced = false;
+    constructor(rootDir, log, maxFileBytes) {
+        this.rootDir = rootDir;
+        this.log = log;
+        this.maxFileBytes = maxFileBytes;
+    }
+    write(rec) {
+        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),
+            });
+        }
+    }
+    statFile(file) {
+        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;
+        }
+    }
+    rotate(file) {
+        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) {
+    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, configEnabled) {
+    if (envVal === "1")
+        return true;
+    if (envVal === "0")
+        return false;
+    return configEnabled;
+}
+function formatStamp(d) {
+    const pad = (n) => 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/dist/gateway/types.d.ts

@@ -13,6 +13,19 @@ export interface RouteMatch {
 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;
@@ -21,6 +34,8 @@ export interface GatewayRoute {
     extraArgs?: string[];
     queueMode?: QueueMode;
     trustLevel?: TrustLevel;
+    /** Required when `runtime === "openclaw-acp"`. Resolved at config-load time. */
+    gateway?: ResolvedOpenclawGateway;
 }
 /**
  * Per-channel configuration entry. Channel-specific extras (e.g. BotCord
@@ -214,6 +229,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;
@@ -223,6 +247,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. */
 export interface RuntimeRunResult {