@botcord/daemon 0.2.5 → 0.2.8

package/dist/gateway/index.d.ts

@@ -8,6 +8,8 @@ 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 { createTranscriptWriter, resolveTranscriptEnabled, defaultTranscriptRoot, truncateTextField, TRANSCRIPT_TEXT_LIMIT, TRANSCRIPT_FILE_LIMIT, type TranscriptWriter, type TranscriptRecord, type InboundTranscriptRecord, type DispatchedTranscriptRecord, type ComposeFailedTranscriptRecord, type OutboundTranscriptRecord, type TurnErrorTranscriptRecord, type AttentionSkippedTranscriptRecord, type DroppedTranscriptRecord, type DeliveryStatus, type DroppedReason, } from "./transcript.js";
+export { safePathSegment, transcriptFilePath, transcriptRoomDir, transcriptAgentRoot, } from "./transcript-paths.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";

package/dist/gateway/index.js

@@ -8,6 +8,8 @@ export { resolveRoute, matchesRoute } from "./router.js";
 export { ChannelManager } from "./channel-manager.js";
 export { Dispatcher } from "./dispatcher.js";
 export { Gateway } from "./gateway.js";
+export { createTranscriptWriter, resolveTranscriptEnabled, defaultTranscriptRoot, truncateTextField, TRANSCRIPT_TEXT_LIMIT, TRANSCRIPT_FILE_LIMIT, } from "./transcript.js";
+export { safePathSegment, transcriptFilePath, transcriptRoomDir, transcriptAgentRoot, } from "./transcript-paths.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";

package/dist/gateway/policy-resolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Daemon-side per-agent attention-policy cache (PR3, design §5).
+ *
+ * The dispatcher consults this resolver after `onInbound` fires and before
+ * the runtime turn enqueues. Cache layout:
+ *
+ *   - `agent_id`              → global default policy (seeded by
+ *                                `provision_agent` + `policy_updated{agent}`).
+ *   - `agent_id:room_id`      → genuine per-room override only — installed
+ *                                exclusively via `put` from a per-room
+ *                                `policy_updated` frame. Inheritance reads
+ *                                never write here.
+ *
+ * `resolve(agent, room)` checks the room key first, then falls back to the
+ * global key. This means a per-room override always wins, and the global
+ * propagates to every room without explicit fan-out (a global update only
+ * needs to refresh the agent_id entry).
+ *
+ * `invalidate(agent_id, room_id)` drops the matching room entry; the next
+ * resolve falls through to the global. `invalidate(agent_id)` drops every
+ * entry for that agent — both global and any room overrides — used when
+ * the agent is revoked or the cache must rebuild from scratch.
+ */
+import type { AttentionPolicy } from "@botcord/protocol-core";
+/** Public surface — kept narrow so the dispatcher can mock easily in tests. */
+export interface PolicyResolverLike {
+    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    invalidate(agentId: string, roomId?: string): void;
+    /**
+     * Install (or replace) the cached policy entry for an agent / room. Used
+     * by the `policy_updated` control-frame handler to apply embedded policy
+     * payloads without forcing a refetch.
+     */
+    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+}
+export interface PolicyResolverOptions {
+    /** Fetcher for the per-agent default. Returning `undefined` means "no policy known"; the resolver falls back to `mode=always`. */
+    fetchGlobal: (agentId: string) => Promise<AttentionPolicy | undefined>;
+    /**
+     * Optional per-room fetcher. PR2 supplies this; PR3 leaves it
+     * unimplemented and the resolver collapses to the global policy.
+     */
+    fetchEffective?: (agentId: string, roomId: string) => Promise<AttentionPolicy | undefined>;
+    /** Cache TTL in milliseconds. Defaults to 5 minutes. */
+    ttlMs?: number;
+}
+export declare class PolicyResolver implements PolicyResolverLike {
+    private readonly fetchGlobal;
+    private readonly fetchEffective?;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(opts: PolicyResolverOptions);
+    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    private safeFetch;
+    invalidate(agentId: string, roomId?: string): void;
+    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+}

package/dist/gateway/policy-resolver.js

@@ -0,0 +1,123 @@
+/**
+ * Daemon-side per-agent attention-policy cache (PR3, design §5).
+ *
+ * The dispatcher consults this resolver after `onInbound` fires and before
+ * the runtime turn enqueues. Cache layout:
+ *
+ *   - `agent_id`              → global default policy (seeded by
+ *                                `provision_agent` + `policy_updated{agent}`).
+ *   - `agent_id:room_id`      → genuine per-room override only — installed
+ *                                exclusively via `put` from a per-room
+ *                                `policy_updated` frame. Inheritance reads
+ *                                never write here.
+ *
+ * `resolve(agent, room)` checks the room key first, then falls back to the
+ * global key. This means a per-room override always wins, and the global
+ * propagates to every room without explicit fan-out (a global update only
+ * needs to refresh the agent_id entry).
+ *
+ * `invalidate(agent_id, room_id)` drops the matching room entry; the next
+ * resolve falls through to the global. `invalidate(agent_id)` drops every
+ * entry for that agent — both global and any room overrides — used when
+ * the agent is revoked or the cache must rebuild from scratch.
+ */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const FETCH_FAILED = Symbol("fetch_failed");
+/**
+ * Force DM rooms (`rm_dm_*`) to `mode: "always"` per design §4.2 — UI never
+ * lets the user mute a DM, but a stale cache from before a UX bug is cheap
+ * to defend against here.
+ */
+function maybeForceDm(roomId, policy) {
+    if (roomId && roomId.startsWith("rm_dm_") && policy.mode !== "always") {
+        return { ...policy, mode: "always" };
+    }
+    return policy;
+}
+function defaultPolicy() {
+    return { mode: "always", keywords: [] };
+}
+export class PolicyResolver {
+    fetchGlobal;
+    fetchEffective;
+    ttlMs;
+    cache = new Map();
+    constructor(opts) {
+        this.fetchGlobal = opts.fetchGlobal;
+        this.fetchEffective = opts.fetchEffective;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    }
+    async resolve(agentId, roomId) {
+        const now = Date.now();
+        // 1. Per-room cache — populated either by a `policy_updated{room_id}`
+        //    push (genuine override) or by a prior `fetchEffective` cold-start.
+        if (roomId) {
+            const roomHit = this.cache.get(cacheKey(agentId, roomId));
+            if (roomHit && roomHit.expiresAt > now)
+                return roomHit.policy;
+        }
+        // 2. If a per-room fetcher is wired, treat it as authoritative for cold
+        //    rooms — it returns the override-merged effective policy and so must
+        //    not be skipped just because the global cache is warm.
+        if (roomId && this.fetchEffective) {
+            const fetched = await this.safeFetch(() => this.fetchEffective(agentId, roomId));
+            if (fetched === FETCH_FAILED)
+                return defaultPolicy();
+            const policy = fetched ?? defaultPolicy();
+            this.cache.set(cacheKey(agentId, roomId), {
+                policy: maybeForceDm(roomId, policy),
+                expiresAt: now + this.ttlMs,
+            });
+            return maybeForceDm(roomId, policy);
+        }
+        // 3. No room override known — inherit from the cached agent-wide global.
+        //    Without this layer, group messages collapsed to mode=always whenever
+        //    the daemon ran without a per-room fetcher (the current production
+        //    state), silently breaking global mention_only/muted.
+        const globalKey = cacheKey(agentId, null);
+        const globalHit = this.cache.get(globalKey);
+        if (globalHit && globalHit.expiresAt > now) {
+            return maybeForceDm(roomId, globalHit.policy);
+        }
+        // 4. Cold start for global.
+        const fetched = await this.safeFetch(() => this.fetchGlobal(agentId));
+        if (fetched === FETCH_FAILED)
+            return defaultPolicy();
+        const policy = fetched ?? defaultPolicy();
+        this.cache.set(globalKey, { policy, expiresAt: now + this.ttlMs });
+        return maybeForceDm(roomId, policy);
+    }
+    async safeFetch(fn) {
+        try {
+            return await fn();
+        }
+        catch {
+            // Fail-open: a fetch error must not silence the agent. The caller
+            // returns the default policy without caching so the next resolve retries.
+            return FETCH_FAILED;
+        }
+    }
+    invalidate(agentId, roomId) {
+        if (roomId !== undefined) {
+            this.cache.delete(cacheKey(agentId, roomId));
+            return;
+        }
+        // Drop every entry for this agent.
+        const prefix = agentId + ":";
+        for (const key of Array.from(this.cache.keys())) {
+            if (key === agentId || key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    put(agentId, roomId, policy) {
+        const key = cacheKey(agentId, roomId);
+        this.cache.set(key, {
+            policy: maybeForceDm(roomId, policy),
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+}
+function cacheKey(agentId, roomId) {
+    return roomId ? `${agentId}:${roomId}` : agentId;
+}

package/dist/gateway/runtimes/acp-stream.d.ts

@@ -0,0 +1,99 @@
+import type { RuntimeAdapter, RuntimeProbeResult, RuntimeRunOptions, RuntimeRunResult, StreamBlock } from "../types.js";
+/** ACP protocol version this client targets. */
+export declare const ACP_PROTOCOL_VERSION = 1;
+export interface AcpInitializeResult {
+    protocolVersion?: number;
+    agentInfo?: {
+        name?: string;
+        version?: string;
+    };
+    agentCapabilities?: Record<string, unknown>;
+    authMethods?: Array<{
+        id?: string;
+        name?: string;
+        description?: string;
+    }>;
+    [k: string]: unknown;
+}
+export interface AcpPermissionOption {
+    optionId: string;
+    name?: string;
+    /**
+     * ACP option kind. Common values: `allow_once`, `allow_always`,
+     * `reject_once`, `reject_always`. Treated as opaque by the base class —
+     * subclasses inspect `.kind` to pick the right outcome.
+     */
+    kind?: string;
+    [k: string]: unknown;
+}
+export interface AcpPermissionRequest {
+    sessionId: string;
+    toolCall?: {
+        name?: string;
+        rawInput?: unknown;
+        [k: string]: unknown;
+    };
+    options: AcpPermissionOption[];
+    [k: string]: unknown;
+}
+export type AcpPermissionResponse = {
+    outcome: {
+        outcome: "selected";
+        optionId: string;
+    };
+} | {
+    outcome: {
+        outcome: "cancelled";
+    };
+};
+export interface AcpUpdateParams {
+    sessionId: string;
+    update: {
+        sessionUpdate?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Hooks exposed to subclasses to react to inbound traffic during a turn. */
+export interface AcpTurnHooks {
+    /** Called for each `session/update` notification. */
+    onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /** Called for `session/request_permission` requests. Must resolve to an outcome. */
+    onPermissionRequest(req: AcpPermissionRequest): Promise<AcpPermissionResponse>;
+}
+export interface AcpUpdateCtx {
+    /** Append to the turn's running assistant text. */
+    appendAssistantText(text: string): void;
+    /** Forward a normalized StreamBlock to `opts.onBlock`. */
+    emitBlock(block: StreamBlock): void;
+    /** 1-based sequence within this turn. */
+    seq: number;
+}
+export declare abstract class AcpRuntimeAdapter implements RuntimeAdapter {
+    abstract readonly id: string;
+    probe?(): RuntimeProbeResult;
+    protected abstract resolveBinary(opts: RuntimeRunOptions): string;
+    /** Argv tail (excluding the binary). ACP servers usually take none. */
+    protected buildArgs(_opts: RuntimeRunOptions): string[];
+    protected abstract spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    /** Subclass hook: react to one `session/update` notification. */
+    protected abstract onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /** Subclass hook: respond to a `session/request_permission` request. */
+    protected abstract onPermissionRequest(req: AcpPermissionRequest, opts: RuntimeRunOptions): Promise<AcpPermissionResponse>;
+    /** Runtime-specific clientCapabilities sent on initialize. */
+    protected clientCapabilities(): Record<string, unknown>;
+    /** Runtime-specific clientInfo sent on initialize. */
+    protected clientInfo(): {
+        name: string;
+        version: string;
+    };
+    /**
+     * Hook invoked synchronously before spawn. Subclasses use this to write
+     * systemContext to disk (e.g. `<cwd>/AGENTS.md`).
+     */
+    protected prepareTurn(_opts: RuntimeRunOptions): void;
+    /** cwd passed to ACP `session/new` / `session/load`. Typically `opts.cwd`. */
+    protected sessionCwd(opts: RuntimeRunOptions): string;
+    run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+    private withTimeout;
+}

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

@@ -0,0 +1,394 @@
+import { spawn } from "node:child_process";
+import { consoleLogger } from "../log.js";
+/**
+ * Minimal bidirectional ACP (Agent Client Protocol) client used by runtime
+ * adapters whose backing CLI speaks ACP over stdio (JSON-RPC 2.0,
+ * newline-delimited).
+ *
+ * Why a base class instead of `NdjsonStreamAdapter`: ACP is a bidirectional
+ * RPC protocol — the agent sends notifications (`session/update`) AND
+ * server-initiated requests (`session/request_permission`) that the daemon
+ * MUST reply to or the agent stalls. The ndjson base only models a one-way
+ * event stream, so it cannot drive ACP correctly.
+ */
+const log = consoleLogger;
+/** How much stderr we keep for error reporting. */
+const STDERR_TAIL_CAP = 8 * 1024;
+/** How much of the retained stderr is included in synthesized errors. */
+const STDERR_ERROR_SNIPPET = 500;
+/** Cap on streamed assistant text per turn — guards a runaway runtime. */
+const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
+/** Grace period between SIGTERM and SIGKILL on abort. */
+const KILL_GRACE_MS = 5_000;
+/** Deadline for the initial `initialize` handshake. */
+const INITIALIZE_TIMEOUT_MS = 30_000;
+/** ACP protocol version this client targets. */
+export const ACP_PROTOCOL_VERSION = 1;
+/** Minimal newline-JSON-RPC framing on top of a child process's stdio. */
+class AcpConnection {
+    child;
+    handlers;
+    logId;
+    nextId = 1;
+    pending = new Map();
+    stdoutBuf = "";
+    closed = false;
+    closeReason = null;
+    constructor(child, handlers, logId) {
+        this.child = child;
+        this.handlers = handlers;
+        this.logId = logId;
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => this.onStdout(chunk));
+        child.stdout.on("end", () => this.fail(new Error("stdout closed")));
+        child.on("close", (code) => this.fail(new Error(`process exited with code ${code ?? 0}`)));
+        child.on("error", (err) => this.fail(err));
+    }
+    onStdout(chunk) {
+        this.stdoutBuf += chunk;
+        let idx;
+        while ((idx = this.stdoutBuf.indexOf("\n")) !== -1) {
+            const line = this.stdoutBuf.slice(0, idx).trim();
+            this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+            if (!line)
+                continue;
+            this.dispatchLine(line);
+        }
+    }
+    dispatchLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            log.warn(`${this.logId} non-json acp line`, { line: line.slice(0, 200) });
+            return;
+        }
+        if (typeof msg !== "object" || msg === null)
+            return;
+        // Response to a client→server request
+        if (typeof msg.id === "number" && (msg.result !== undefined || msg.error !== undefined)) {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error) {
+                const err = new Error(`acp error ${msg.error.code ?? "?"}: ${msg.error.message ?? "(no message)"}`);
+                pending.reject(err);
+            }
+            else {
+                pending.resolve(msg.result ?? null);
+            }
+            return;
+        }
+        if (typeof msg.method === "string") {
+            // Server→client request (has `id`) or notification (no `id`)
+            if (msg.id !== undefined) {
+                void this.handleServerRequest(msg.id, msg.method, msg.params);
+            }
+            else {
+                try {
+                    this.handlers.onNotification(msg.method, msg.params);
+                }
+                catch (err) {
+                    log.warn(`${this.logId} notification handler threw`, {
+                        method: msg.method,
+                        err: String(err),
+                    });
+                }
+            }
+        }
+    }
+    async handleServerRequest(id, method, params) {
+        let result;
+        let error = null;
+        try {
+            result = await this.handlers.onRequest(method, params);
+        }
+        catch (err) {
+            error = {
+                code: -32603,
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+        const reply = error
+            ? { jsonrpc: "2.0", id, error }
+            : { jsonrpc: "2.0", id, result: result ?? null };
+        this.writeMessage(reply);
+    }
+    writeMessage(obj) {
+        if (this.closed)
+            return;
+        try {
+            this.child.stdin.write(JSON.stringify(obj) + "\n");
+        }
+        catch (err) {
+            this.fail(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    request(method, params) {
+        if (this.closed) {
+            return Promise.reject(this.closeReason ?? new Error("acp closed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+            });
+            this.writeMessage({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    notify(method, params) {
+        this.writeMessage({ jsonrpc: "2.0", method, params });
+    }
+    fail(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeReason = err;
+        for (const [, p] of this.pending)
+            p.reject(err);
+        this.pending.clear();
+    }
+    isClosed() {
+        return this.closed;
+    }
+}
+export class AcpRuntimeAdapter {
+    /** Argv tail (excluding the binary). ACP servers usually take none. */
+    buildArgs(_opts) {
+        return [];
+    }
+    /** Runtime-specific clientCapabilities sent on initialize. */
+    clientCapabilities() {
+        return { fs: { readTextFile: false, writeTextFile: false } };
+    }
+    /** Runtime-specific clientInfo sent on initialize. */
+    clientInfo() {
+        return { name: "botcord-daemon", version: "0.1" };
+    }
+    /**
+     * Hook invoked synchronously before spawn. Subclasses use this to write
+     * systemContext to disk (e.g. `<cwd>/AGENTS.md`).
+     */
+    prepareTurn(_opts) {
+        /* default: noop */
+    }
+    /** cwd passed to ACP `session/new` / `session/load`. Typically `opts.cwd`. */
+    sessionCwd(opts) {
+        return opts.cwd;
+    }
+    async run(opts) {
+        if (opts.signal.aborted) {
+            return {
+                text: "",
+                newSessionId: opts.sessionId ?? "",
+                error: `${this.id} aborted before spawn`,
+            };
+        }
+        try {
+            this.prepareTurn(opts);
+        }
+        catch (err) {
+            log.warn(`${this.id} prepareTurn threw`, { err: String(err) });
+        }
+        const binary = this.resolveBinary(opts);
+        const args = this.buildArgs(opts);
+        log.debug(`${this.id} spawn`, {
+            cwd: opts.cwd,
+            sessionId: opts.sessionId,
+            argv: args,
+        });
+        const child = spawn(binary, args, {
+            cwd: opts.cwd,
+            env: this.spawnEnv(opts),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let killTimer = null;
+        const onAbort = () => {
+            if (child.killed)
+                return;
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => {
+                if (!child.killed) {
+                    log.warn(`${this.id} did not exit after SIGTERM; sending SIGKILL`);
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }, KILL_GRACE_MS);
+            if (typeof killTimer.unref === "function")
+                killTimer.unref();
+        };
+        opts.signal.addEventListener("abort", onAbort, { once: true });
+        let stderrTail = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CAP);
+        });
+        const state = {
+            finalText: "",
+            assistantTextChunks: [],
+            assistantTextBytes: 0,
+            assistantTextCapped: false,
+        };
+        const appendAssistantText = (text) => {
+            if (!text || state.assistantTextCapped)
+                return;
+            const budget = ASSISTANT_TEXT_CAP - state.assistantTextBytes;
+            if (budget <= 0) {
+                state.assistantTextCapped = true;
+                return;
+            }
+            if (text.length > budget) {
+                state.assistantTextChunks.push(text.slice(0, budget));
+                state.assistantTextBytes += budget;
+                state.assistantTextCapped = true;
+                return;
+            }
+            state.assistantTextChunks.push(text);
+            state.assistantTextBytes += text.length;
+        };
+        let seq = 0;
+        const conn = new AcpConnection(child, {
+            onNotification: (method, params) => {
+                if (method === "session/update") {
+                    seq += 1;
+                    this.onUpdate(params, {
+                        appendAssistantText,
+                        emitBlock: (b) => opts.onBlock?.(b),
+                        seq,
+                    });
+                }
+            },
+            onRequest: async (method, params) => {
+                if (method === "session/request_permission") {
+                    return this.onPermissionRequest(params, opts);
+                }
+                // Unknown server→client request: signal "method not found" so the
+                // server can decide what to do. Throwing here surfaces as a JSON-RPC
+                // error reply via AcpConnection.
+                const err = new Error(`unknown server request: ${method}`);
+                throw err;
+            },
+        }, this.id);
+        const childExit = new Promise((resolve) => {
+            child.on("close", (code) => resolve(code ?? 0));
+        });
+        let newSessionId = opts.sessionId ?? "";
+        try {
+            // 1) initialize
+            await this.withTimeout(conn.request("initialize", {
+                protocolVersion: ACP_PROTOCOL_VERSION,
+                clientCapabilities: this.clientCapabilities(),
+                clientInfo: this.clientInfo(),
+            }), INITIALIZE_TIMEOUT_MS, "initialize");
+            // 2) session/load (if resuming) → fallback to session/new
+            const cwd = this.sessionCwd(opts);
+            let sessionId = "";
+            if (opts.sessionId) {
+                try {
+                    const loaded = (await conn.request("session/load", {
+                        sessionId: opts.sessionId,
+                        cwd,
+                        mcpServers: [],
+                    }));
+                    if (loaded !== null && loaded !== undefined) {
+                        // Hermes' load_session does NOT return a session_id — reuse the
+                        // requested one. If a future server returns one, prefer it.
+                        sessionId =
+                            (loaded && typeof loaded.sessionId === "string"
+                                ? loaded.sessionId
+                                : "") || opts.sessionId;
+                    }
+                }
+                catch (err) {
+                    log.warn(`${this.id} session/load failed; falling back to new`, {
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            if (!sessionId) {
+                const created = await conn.request("session/new", { cwd, mcpServers: [] });
+                sessionId = created?.sessionId ?? "";
+            }
+            if (!sessionId) {
+                throw new Error("acp server did not return a sessionId");
+            }
+            newSessionId = sessionId;
+            // 3) session/prompt
+            const promptResult = (await conn.request("session/prompt", {
+                sessionId,
+                prompt: [{ type: "text", text: opts.text }],
+            }));
+            const stopReason = promptResult?.stopReason ?? "end_turn";
+            if (stopReason === "refusal" || stopReason === "error") {
+                state.errorText = state.errorText ?? `prompt stopped: ${stopReason}`;
+            }
+            // Politely close stdin so the server can exit. Some ACP servers shut
+            // down on EOF; if not, abort signal will SIGTERM.
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        catch (err) {
+            state.errorText =
+                state.errorText ??
+                    (err instanceof Error ? err.message : String(err));
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        let code = 0;
+        try {
+            code = await childExit;
+        }
+        finally {
+            opts.signal.removeEventListener("abort", onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+        }
+        if (code !== 0 && !state.errorText) {
+            state.errorText = `${this.id} exited with code ${code}: ${stderrTail.slice(-STDERR_ERROR_SNIPPET)}`;
+        }
+        const rawText = state.finalText || state.assistantTextChunks.join("").trim();
+        const text = rawText.length > ASSISTANT_TEXT_CAP
+            ? rawText.slice(0, ASSISTANT_TEXT_CAP)
+            : rawText;
+        return {
+            text,
+            newSessionId,
+            ...(state.errorText ? { error: state.errorText } : {}),
+        };
+    }
+    withTimeout(p, ms, label) {
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => reject(new Error(`${this.id} ${label} timed out after ${ms}ms`)), ms);
+            if (typeof t.unref === "function")
+                t.unref();
+            p.then((v) => {
+                clearTimeout(t);
+                resolve(v);
+            }, (e) => {
+                clearTimeout(t);
+                reject(e);
+            });
+        });
+    }
+}