@botcord/daemon 0.2.5 → 0.2.8

package/dist/gateway/runtimes/openclaw-acp.js

@@ -0,0 +1,500 @@
+import { spawn } from "node:child_process";
+import { readCommandVersion, resolveCommandOnPath, } from "./probe.js";
+import { consoleLogger } from "../log.js";
+const log = consoleLogger;
+const ACP_PROTOCOL_VERSION = 1;
+/** How long an idle (no in-flight prompt) ACP child process is kept alive. */
+const ACP_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+/** Cap for streamed assistant text per turn. */
+const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
+const ACP_POOL = new Map();
+function poolKey(accountId, gatewayName) {
+    return `${accountId}::${gatewayName}`;
+}
+function resetIdle(h, key) {
+    if (h.idleTimer)
+        clearTimeout(h.idleTimer);
+    if (h.inFlight > 0)
+        return;
+    h.idleTimer = setTimeout(() => {
+        if (h.inFlight === 0 && !h.closed) {
+            log.info("openclaw-acp.idle-timeout", { key });
+            shutdownHandle(h, "idle-timeout");
+            ACP_POOL.delete(key);
+        }
+    }, ACP_IDLE_TIMEOUT_MS);
+    h.idleTimer.unref?.();
+}
+function shutdownHandle(h, reason) {
+    if (h.closed)
+        return;
+    h.closed = true;
+    h.exitReason = reason;
+    if (h.idleTimer)
+        clearTimeout(h.idleTimer);
+    for (const p of h.pending.values()) {
+        p.reject(new Error(`openclaw acp child closed: ${reason}`));
+    }
+    h.pending.clear();
+    h.subscribers.clear();
+    try {
+        h.child.kill("SIGTERM");
+    }
+    catch {
+        // already dead
+    }
+}
+/** Test-only: drop all cached child processes. */
+export function __resetOpenclawAcpPoolForTests() {
+    for (const [key, h] of ACP_POOL.entries()) {
+        shutdownHandle(h, "test-reset");
+        ACP_POOL.delete(key);
+    }
+}
+// ---------------------------------------------------------------------------
+// Probe
+// ---------------------------------------------------------------------------
+function resolveOpenclawCommand(deps = {}) {
+    const explicit = (deps.env ?? process.env).BOTCORD_OPENCLAW_BIN;
+    if (explicit && explicit.length > 0)
+        return explicit;
+    return resolveCommandOnPath("openclaw", deps);
+}
+export function probeOpenclaw(deps = {}) {
+    const command = resolveOpenclawCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * OpenClaw ACP runtime adapter.
+ *
+ * Spawns `openclaw acp --url <gateway> [--token <token>]` per
+ * `(accountId, gatewayName)` pair and reuses the process across turns. The
+ * child speaks JSON-RPC over stdio; we send `initialize` once, then
+ * `newSession` (with `_meta.sessionKey`) when the daemon has no persisted
+ * runtime session id, and `prompt` for each turn. Streaming `session/update`
+ * notifications are relayed to `onBlock`.
+ *
+ * Process-pool lifetime + abort/cancel semantics live at module scope; see
+ * `ACP_POOL` and `shutdownHandle` above.
+ */
+export class OpenclawAcpAdapter {
+    id = "openclaw-acp";
+    spawnFn;
+    constructor(deps = {}) {
+        this.spawnFn = deps.spawnFn ?? spawn;
+    }
+    probe() {
+        return probeOpenclaw();
+    }
+    async run(opts) {
+        const gateway = opts.gateway;
+        if (!gateway) {
+            return failResult(opts.sessionId ?? "", "openclaw-acp: missing gateway endpoint (route.gateway not resolved)");
+        }
+        if (!gateway.openclawAgent) {
+            return failResult(opts.sessionId ?? "", `openclaw-acp: gateway "${gateway.name}" did not resolve an openclawAgent (set defaultAgent on the profile or openclawAgent on the route)`);
+        }
+        const sessionKey = buildAcpSessionKey({
+            openclawAgent: gateway.openclawAgent,
+            accountId: opts.accountId,
+            // The dispatcher passes `context.conversationKey` in for routing;
+            // fall back to a stable per-accountId key when it's not present (e.g.
+            // synthetic test calls).
+            conversationKey: stringField(opts.context, "conversationKey") ?? "default",
+        });
+        const key = poolKey(opts.accountId, gateway.name);
+        let handle;
+        try {
+            handle = await this.acquireHandle(key, opts, gateway);
+        }
+        catch (err) {
+            return failResult(opts.sessionId ?? "", `openclaw-acp: ${err.message}`);
+        }
+        handle.inFlight += 1;
+        if (handle.idleTimer)
+            clearTimeout(handle.idleTimer);
+        let acpSessionId = opts.sessionId ?? "";
+        let seq = 0;
+        let assistantText = "";
+        let assistantBytes = 0;
+        let capped = false;
+        let finalText = "";
+        const emitBlock = (block) => {
+            try {
+                opts.onBlock?.(block);
+            }
+            catch (err) {
+                log.warn("openclaw-acp.onBlock-threw", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        };
+        const onNotification = (note) => {
+            seq += 1;
+            // Forward raw notification as a stream block for downstream visibility.
+            const kind = classifyAcpUpdate(note);
+            emitBlock({ raw: note, kind, seq });
+            const update = note.params?.update;
+            if (update?.sessionUpdate === "agent_message_chunk") {
+                const text = extractText(update.content);
+                if (text && !capped) {
+                    const bytes = Buffer.byteLength(text, "utf8");
+                    if (assistantBytes + bytes > ASSISTANT_TEXT_CAP) {
+                        capped = true;
+                    }
+                    else {
+                        assistantText += text;
+                        assistantBytes += bytes;
+                    }
+                }
+            }
+        };
+        let abortListener;
+        try {
+            // Ensure we have an ACP session id. When the dispatcher doesn't carry
+            // one, ask the child to create or rebind one for our sessionKey.
+            if (!acpSessionId) {
+                try {
+                    acpSessionId = await this.newSession(handle, {
+                        cwd: opts.cwd,
+                        sessionKey,
+                    });
+                }
+                catch (err) {
+                    throw new Error(`newSession failed: ${err.message}`);
+                }
+            }
+            handle.subscribers.set(acpSessionId, onNotification);
+            if (opts.signal?.aborted) {
+                return failResult(acpSessionId, "openclaw-acp: aborted before prompt");
+            }
+            abortListener = () => {
+                // Best-effort cancel; ACP `cancel` is a notification (fire-and-forget).
+                sendNotification(handle, "session/cancel", { sessionId: acpSessionId });
+            };
+            opts.signal?.addEventListener("abort", abortListener);
+            let promptResult;
+            try {
+                promptResult = await this.prompt(handle, {
+                    sessionId: acpSessionId,
+                    text: opts.text,
+                });
+            }
+            catch (err) {
+                const msg = err.message ?? "prompt failed";
+                // If the child says the session is gone (process restart, GC),
+                // recreate it so the next turn doesn't hard-fail.
+                if (/session not found|unknown session/i.test(msg)) {
+                    try {
+                        const fresh = await this.newSession(handle, {
+                            cwd: opts.cwd,
+                            sessionKey,
+                        });
+                        handle.subscribers.delete(acpSessionId);
+                        acpSessionId = fresh;
+                        handle.subscribers.set(acpSessionId, onNotification);
+                        promptResult = await this.prompt(handle, {
+                            sessionId: acpSessionId,
+                            text: opts.text,
+                        });
+                    }
+                    catch (err2) {
+                        throw new Error(`prompt failed after session reset: ${err2.message}`);
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+            // OpenClaw's prompt response shape isn't strictly fixed; pull a final
+            // text out of common locations and otherwise fall back to the streamed
+            // chunks accumulated above.
+            finalText = pickFinalText(promptResult) ?? assistantText;
+            if (capped) {
+                log.warn("openclaw-acp.assistant-text-capped", { sessionId: acpSessionId });
+            }
+            return {
+                text: finalText,
+                newSessionId: acpSessionId,
+            };
+        }
+        catch (err) {
+            return failResult(acpSessionId, `openclaw-acp: ${err.message}`);
+        }
+        finally {
+            if (abortListener && opts.signal) {
+                try {
+                    opts.signal.removeEventListener("abort", abortListener);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            handle.subscribers.delete(acpSessionId);
+            handle.inFlight = Math.max(0, handle.inFlight - 1);
+            resetIdle(handle, key);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Process management
+    // ---------------------------------------------------------------------
+    async acquireHandle(key, opts, gateway) {
+        let handle = ACP_POOL.get(key);
+        if (handle && handle.closed) {
+            ACP_POOL.delete(key);
+            handle = undefined;
+        }
+        // Invalidate the cached child if its spawn args drifted from the live
+        // gateway endpoint — config reload / token rotation under the same
+        // profile name must not keep talking to the old --url / --token.
+        if (handle &&
+            (handle.spawnedUrl !== gateway.url || handle.spawnedToken !== gateway.token)) {
+            log.info("openclaw-acp.gateway-args-changed", {
+                key,
+                oldUrl: handle.spawnedUrl,
+                newUrl: gateway.url,
+                tokenChanged: handle.spawnedToken !== gateway.token,
+            });
+            shutdownHandle(handle, "gateway-args-changed");
+            ACP_POOL.delete(key);
+            handle = undefined;
+        }
+        if (!handle) {
+            handle = this.spawnAcpProcess(key, gateway);
+            ACP_POOL.set(key, handle);
+        }
+        if (!handle.initialized) {
+            if (!handle.initializePromise) {
+                handle.initializePromise = sendRequest(handle, "initialize", {
+                    protocolVersion: ACP_PROTOCOL_VERSION,
+                    clientCapabilities: {},
+                }).then(() => {
+                    handle.initialized = true;
+                });
+            }
+            await handle.initializePromise;
+        }
+        return handle;
+    }
+    spawnAcpProcess(key, gateway) {
+        const command = resolveOpenclawCommand() ?? "openclaw";
+        const args = ["acp", "--url", gateway.url];
+        if (gateway.token)
+            args.push("--token", gateway.token);
+        const child = this.spawnFn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env },
+        });
+        const handle = {
+            child,
+            pending: new Map(),
+            subscribers: new Map(),
+            nextId: 1,
+            buffer: "",
+            initialized: false,
+            inFlight: 0,
+            closed: false,
+            spawnedUrl: gateway.url,
+            spawnedToken: gateway.token,
+        };
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => onStdoutChunk(handle, chunk));
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            log.debug("openclaw-acp.stderr", { key, chunk: chunk.slice(0, 500) });
+        });
+        child.on("exit", (code, signal) => {
+            shutdownHandle(handle, `exit code=${code ?? "null"} signal=${signal ?? "null"}`);
+            ACP_POOL.delete(key);
+        });
+        child.on("error", (err) => {
+            log.warn("openclaw-acp.child-error", {
+                key,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            shutdownHandle(handle, `error: ${err.message}`);
+            ACP_POOL.delete(key);
+        });
+        return handle;
+    }
+    async newSession(handle, args) {
+        const result = (await sendRequest(handle, "session/new", {
+            cwd: args.cwd,
+            mcpServers: [],
+            _meta: { sessionKey: args.sessionKey },
+        }));
+        if (!result?.sessionId || typeof result.sessionId !== "string") {
+            throw new Error("newSession returned no sessionId");
+        }
+        return result.sessionId;
+    }
+    async prompt(handle, args) {
+        return sendRequest(handle, "session/prompt", {
+            sessionId: args.sessionId,
+            prompt: [{ type: "text", text: args.text }],
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON-RPC stdio plumbing
+// ---------------------------------------------------------------------------
+function onStdoutChunk(handle, chunk) {
+    handle.buffer += chunk;
+    let idx;
+    while ((idx = handle.buffer.indexOf("\n")) !== -1) {
+        const line = handle.buffer.slice(0, idx).trim();
+        handle.buffer = handle.buffer.slice(idx + 1);
+        if (!line)
+            continue;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch (err) {
+            log.warn("openclaw-acp.parse-error", {
+                error: err instanceof Error ? err.message : String(err),
+                line: line.slice(0, 200),
+            });
+            continue;
+        }
+        routeMessage(handle, msg);
+    }
+}
+function routeMessage(handle, msg) {
+    if (msg && typeof msg === "object" && "id" in msg && ("result" in msg || "error" in msg)) {
+        const id = typeof msg.id === "number" ? msg.id : Number(msg.id);
+        const pending = handle.pending.get(id);
+        if (!pending)
+            return;
+        handle.pending.delete(id);
+        if (msg.error) {
+            const message = typeof msg.error?.message === "string" ? msg.error.message : "rpc error";
+            pending.reject(new Error(message));
+        }
+        else {
+            pending.resolve(msg.result);
+        }
+        return;
+    }
+    // Notification.
+    if (msg?.method && msg?.params) {
+        const sid = msg.params?.sessionId;
+        if (typeof sid === "string") {
+            const sub = handle.subscribers.get(sid);
+            if (sub) {
+                try {
+                    sub({ method: msg.method, params: msg.params });
+                }
+                catch (err) {
+                    log.warn("openclaw-acp.subscriber-threw", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+}
+function sendRequest(handle, method, params) {
+    if (handle.closed)
+        return Promise.reject(new Error("acp child closed"));
+    return new Promise((resolve, reject) => {
+        const id = handle.nextId++;
+        handle.pending.set(id, { resolve, reject, method });
+        const frame = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+        try {
+            handle.child.stdin.write(frame);
+        }
+        catch (err) {
+            handle.pending.delete(id);
+            reject(err);
+        }
+    });
+}
+function sendNotification(handle, method, params) {
+    if (handle.closed)
+        return;
+    const frame = JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n";
+    try {
+        handle.child.stdin.write(frame);
+    }
+    catch {
+        // best-effort fire-and-forget
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function failResult(sessionId, error) {
+    return {
+        text: "",
+        newSessionId: sessionId,
+        error,
+    };
+}
+function classifyAcpUpdate(note) {
+    const update = note.params?.update;
+    const kind = update?.sessionUpdate;
+    switch (kind) {
+        case "agent_message_chunk":
+            return "assistant_text";
+        case "tool_call":
+            return "tool_use";
+        case "tool_call_update":
+            return "tool_result";
+        case "session_info_update":
+        case "available_commands_update":
+        case "usage_update":
+            return "system";
+        default:
+            return "other";
+    }
+}
+function extractText(content) {
+    if (!content)
+        return "";
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content.map(extractText).join("");
+    }
+    if (typeof content === "object") {
+        const c = content;
+        if (typeof c.text === "string")
+            return c.text;
+        if (typeof c.content === "string")
+            return c.content;
+        if (Array.isArray(c.content))
+            return extractText(c.content);
+    }
+    return "";
+}
+function pickFinalText(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const r = result;
+    if (typeof r.text === "string" && r.text.length > 0)
+        return r.text;
+    if (typeof r.message === "string" && r.message.length > 0)
+        return r.message;
+    return undefined;
+}
+function stringField(bag, key) {
+    if (!bag)
+        return undefined;
+    const v = bag[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Build the OpenClaw ACP `sessionKey` for a daemon turn. `accountId` is
+ * always included to prevent two daemon agents from colliding on the same
+ * gateway-side key (RFC §3.5.2 串号 防御).
+ */
+export function buildAcpSessionKey(args) {
+    return `agent:${args.openclawAgent}:${args.accountId}:${args.conversationKey}`;
+}

package/dist/gateway/runtimes/registry.d.ts

@@ -28,8 +28,12 @@ export interface RuntimeModule {
 export declare const claudeCodeModule: RuntimeModule;
 /** Built-in runtime module entry for Codex. */
 export declare const codexModule: RuntimeModule;
+/** Built-in runtime module entry for Hermes Agent (ACP stdio). */
+export declare const hermesAgentModule: RuntimeModule;
 /** Built-in runtime module entry for Gemini (probe-only stub). */
 export declare const geminiModule: RuntimeModule;
+/** Built-in runtime module entry for OpenClaw (ACP). */
+export declare const openclawAcpModule: RuntimeModule;
 /**
  * Built-in runtime modules. To add a new runtime:
  *   1. Create `runtimes/<name>.ts` extending `NdjsonStreamAdapter` (or

package/dist/gateway/runtimes/registry.js

@@ -1,6 +1,8 @@
 import { ClaudeCodeAdapter, probeClaude } from "./claude-code.js";
 import { CodexAdapter, probeCodex } from "./codex.js";
 import { GeminiAdapter, probeGemini } from "./gemini.js";
+import { HermesAgentAdapter, probeHermesAgent } from "./hermes-agent.js";
+import { OpenclawAcpAdapter, probeOpenclaw } from "./openclaw-acp.js";
 /** Built-in runtime module entry for Claude Code. */
 export const claudeCodeModule = {
     id: "claude-code",
@@ -18,6 +20,15 @@ export const codexModule = {
     probe: () => probeCodex(),
     create: () => new CodexAdapter(),
 };
+/** Built-in runtime module entry for Hermes Agent (ACP stdio). */
+export const hermesAgentModule = {
+    id: "hermes-agent",
+    displayName: "Hermes Agent",
+    binary: "hermes-acp",
+    envVar: "BOTCORD_HERMES_AGENT_BIN",
+    probe: () => probeHermesAgent(),
+    create: () => new HermesAgentAdapter(),
+};
 /** Built-in runtime module entry for Gemini (probe-only stub). */
 export const geminiModule = {
     id: "gemini",
@@ -27,6 +38,15 @@ export const geminiModule = {
     create: () => new GeminiAdapter(),
     supportsRun: false,
 };
+/** Built-in runtime module entry for OpenClaw (ACP). */
+export const openclawAcpModule = {
+    id: "openclaw-acp",
+    displayName: "OpenClaw (ACP)",
+    binary: "openclaw",
+    envVar: "BOTCORD_OPENCLAW_BIN",
+    probe: () => probeOpenclaw(),
+    create: () => new OpenclawAcpAdapter(),
+};
 /**
  * Built-in runtime modules. To add a new runtime:
  *   1. Create `runtimes/<name>.ts` extending `NdjsonStreamAdapter` (or
@@ -36,7 +56,9 @@ export const geminiModule = {
 export const RUNTIME_MODULES = [
     claudeCodeModule,
     codexModule,
+    hermesAgentModule,
     geminiModule,
+    openclawAcpModule,
 ];
 const BY_ID = new Map(RUNTIME_MODULES.map((m) => [m.id, m]));
 /** Lookup a runtime module by id, or null when the id is unknown. */

package/dist/gateway/transcript-paths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function safePathSegment(raw: string): string;
+/**
+ * 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 declare function transcriptFilePath(rootDir: string, agentId: string, roomId: string, topicId: string | null): string;
+/** Directory holding a (agent, room) pair's transcript files. */
+export declare function transcriptRoomDir(rootDir: string, agentId: string, roomId: string): string;
+/** Directory holding all transcript rooms for a single agent. */
+export declare function transcriptAgentRoot(rootDir: string, agentId: string): string;