@botcord/daemon 0.2.4 → 0.2.6

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);
+            });
+        });
+    }
+}

package/dist/gateway/runtimes/codex.js

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { agentCodexHomeDir, ensureAgentCodexHome } from "../../agent-workspace.js";
+import { buildCliEnv } from "../cli-resolver.js";
 import { NdjsonStreamAdapter } from "./ndjson-stream.js";
 import { firstExistingPath, readCommandVersion, resolveCommandOnPath, } from "./probe.js";
 const CODEX_DESKTOP_BUNDLE_PATH = "/Applications/Codex.app/Contents/Resources/codex";
@@ -188,8 +189,14 @@ export class CodexAdapter extends NdjsonStreamAdapter {
         return ["exec", ...tail, "--", prompt];
     }
     spawnEnv(opts) {
+        const cliEnv = buildCliEnv({
+            hubUrl: opts.hubUrl,
+            accountId: opts.accountId,
+            basePath: process.env.PATH,
+        });
         const env = {
             ...process.env,
+            ...cliEnv,
             // Keep JSONL free of ANSI codes regardless of user terminal settings.
             FORCE_COLOR: "0",
             NO_COLOR: "1",

package/dist/gateway/runtimes/hermes-agent.d.ts

@@ -0,0 +1,83 @@
+import { AcpRuntimeAdapter, type AcpPermissionRequest, type AcpPermissionResponse, type AcpUpdateCtx, type AcpUpdateParams } from "./acp-stream.js";
+import { type ProbeDeps } from "./probe.js";
+import type { RuntimeProbeResult, RuntimeRunOptions } from "../types.js";
+/** Resolve the `hermes-acp` executable on PATH. */
+export declare function resolveHermesAcpCommand(deps?: ProbeDeps): string | null;
+/** Probe whether `hermes-acp` is installed and report its version. */
+export declare function probeHermesAgent(deps?: ProbeDeps): RuntimeProbeResult;
+/**
+ * Hermes Agent adapter. Drives `hermes-acp` (the ACP stdio adapter shipped
+ * with `pip install "hermes-agent[acp]"`).
+ *
+ * ## systemContext injection
+ *
+ * Hermes discovers `AGENTS.md` from the spawn cwd upward. We point cwd at a
+ * runtime-private directory (`~/.botcord/agents/<id>/hermes-workspace/`) and
+ * write `<cwd>/AGENTS.md` from `opts.systemContext` before spawn. This is a
+ * **first-turn-only** injection: hermes persists the system prompt in the
+ * session DB and does not re-read AGENTS.md on continuation turns. The
+ * design doc tracks this as a known limitation; a follow-up PR to
+ * hermes-agent would expose a per-turn ephemeral prompt channel.
+ *
+ * ## Per-agent isolation
+ *
+ * - `HERMES_HOME` → `<agent-home>/hermes-home/` so `.env`, `state.db`,
+ *   `skills/` per-agent are isolated from `~/.hermes`.
+ * - cwd → `<agent-home>/hermes-workspace/` (NOT the user-editable
+ *   `<agent-home>/workspace/`) so each turn's daemon-rewritten AGENTS.md
+ *   does not clobber files the user/agent edited.
+ *
+ * ## Permission policy (trustLevel → ACP outcome)
+ *
+ * `HERMES_INTERACTIVE=1` makes hermes route dangerous tool calls through the
+ * ACP `session/request_permission` reverse-call. We answer per trustLevel:
+ *   - `owner`   → always select an `allow_*` option
+ *   - `trusted` → same; reasons go to the daemon log only
+ *   - `public`  → cancel (DeniedOutcome) for all writes/exec
+ */
+export declare class HermesAgentAdapter extends AcpRuntimeAdapter {
+    readonly id: "hermes-agent";
+    private readonly explicitBinary;
+    private resolvedBinary;
+    constructor(opts?: {
+        binary?: string;
+    });
+    probe(): RuntimeProbeResult;
+    protected resolveBinary(): string;
+    /**
+     * hermes-acp is invoked with no positional args — ACP is pure stdio
+     * JSON-RPC. We do not forward `opts.extraArgs` because hermes-acp does
+     * not accept CLI flags for runtime config; per-agent config goes in
+     * `<HERMES_HOME>/.env`.
+     */
+    protected buildArgs(_opts: RuntimeRunOptions): string[];
+    protected spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    protected sessionCwd(opts: RuntimeRunOptions): string;
+    /**
+     * Write systemContext to `<hermes-workspace>/AGENTS.md` atomically before
+     * spawn. NOTE: hermes only reads this file on the first turn of a session
+     * (see class-level docstring); subsequent turns keep the persisted
+     * system prompt and ignore filesystem changes.
+     */
+    protected prepareTurn(opts: RuntimeRunOptions): void;
+    /** Spawn with the runtime-private hermes-workspace as cwd. */
+    run(opts: RuntimeRunOptions): Promise<import("../types.js").RuntimeRunResult>;
+    /**
+     * Translate ACP `session/update` notifications into StreamBlocks +
+     * assistant text. We surface the common shapes that hermes emits:
+     *   - `agent_message_chunk` / `user_message_chunk` content blocks
+     *   - `tool_call` / `tool_call_update`
+     *   - `agent_thought_chunk`
+     *
+     * Anything else is forwarded as `kind: "other"` so subclasses /
+     * downstream channels can introspect.
+     */
+    protected onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /**
+     * trustLevel-driven policy. We pick the FIRST option whose `kind` matches
+     * our intent — `allow_*` for permit, otherwise cancel. ACP's
+     * DeniedOutcome carries no `optionId` / `reason` field; rationale lives
+     * in the daemon log.
+     */
+    protected onPermissionRequest(req: AcpPermissionRequest, opts: RuntimeRunOptions): Promise<AcpPermissionResponse>;
+}

package/dist/gateway/runtimes/hermes-agent.js

@@ -0,0 +1,180 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { agentHermesHomeDir, agentHermesWorkspaceDir, ensureAgentHermesWorkspace, } from "../../agent-workspace.js";
+import { buildCliEnv } from "../cli-resolver.js";
+import { AcpRuntimeAdapter, } from "./acp-stream.js";
+import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
+/** Resolve the `hermes-acp` executable on PATH. */
+export function resolveHermesAcpCommand(deps = {}) {
+    return resolveCommandOnPath("hermes-acp", deps);
+}
+/** Probe whether `hermes-acp` is installed and report its version. */
+export function probeHermesAgent(deps = {}) {
+    const command = resolveHermesAcpCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * Hermes Agent adapter. Drives `hermes-acp` (the ACP stdio adapter shipped
+ * with `pip install "hermes-agent[acp]"`).
+ *
+ * ## systemContext injection
+ *
+ * Hermes discovers `AGENTS.md` from the spawn cwd upward. We point cwd at a
+ * runtime-private directory (`~/.botcord/agents/<id>/hermes-workspace/`) and
+ * write `<cwd>/AGENTS.md` from `opts.systemContext` before spawn. This is a
+ * **first-turn-only** injection: hermes persists the system prompt in the
+ * session DB and does not re-read AGENTS.md on continuation turns. The
+ * design doc tracks this as a known limitation; a follow-up PR to
+ * hermes-agent would expose a per-turn ephemeral prompt channel.
+ *
+ * ## Per-agent isolation
+ *
+ * - `HERMES_HOME` → `<agent-home>/hermes-home/` so `.env`, `state.db`,
+ *   `skills/` per-agent are isolated from `~/.hermes`.
+ * - cwd → `<agent-home>/hermes-workspace/` (NOT the user-editable
+ *   `<agent-home>/workspace/`) so each turn's daemon-rewritten AGENTS.md
+ *   does not clobber files the user/agent edited.
+ *
+ * ## Permission policy (trustLevel → ACP outcome)
+ *
+ * `HERMES_INTERACTIVE=1` makes hermes route dangerous tool calls through the
+ * ACP `session/request_permission` reverse-call. We answer per trustLevel:
+ *   - `owner`   → always select an `allow_*` option
+ *   - `trusted` → same; reasons go to the daemon log only
+ *   - `public`  → cancel (DeniedOutcome) for all writes/exec
+ */
+export class HermesAgentAdapter extends AcpRuntimeAdapter {
+    id = "hermes-agent";
+    explicitBinary;
+    resolvedBinary = null;
+    constructor(opts) {
+        super();
+        this.explicitBinary = opts?.binary ?? process.env.BOTCORD_HERMES_AGENT_BIN;
+    }
+    probe() {
+        return probeHermesAgent();
+    }
+    resolveBinary() {
+        if (this.explicitBinary)
+            return this.explicitBinary;
+        if (this.resolvedBinary)
+            return this.resolvedBinary;
+        this.resolvedBinary = resolveHermesAcpCommand() ?? "hermes-acp";
+        return this.resolvedBinary;
+    }
+    /**
+     * hermes-acp is invoked with no positional args — ACP is pure stdio
+     * JSON-RPC. We do not forward `opts.extraArgs` because hermes-acp does
+     * not accept CLI flags for runtime config; per-agent config goes in
+     * `<HERMES_HOME>/.env`.
+     */
+    buildArgs(_opts) {
+        return [];
+    }
+    spawnEnv(opts) {
+        const cliEnv = buildCliEnv({
+            hubUrl: opts.hubUrl,
+            accountId: opts.accountId,
+            basePath: process.env.PATH,
+        });
+        const env = {
+            ...process.env,
+            ...cliEnv,
+            // Keep ACP stdout free of ANSI codes regardless of terminal settings.
+            NO_COLOR: "1",
+            // Route dangerous tool calls through ACP request_permission.
+            HERMES_INTERACTIVE: "1",
+        };
+        if (opts.accountId) {
+            env.HERMES_HOME = agentHermesHomeDir(opts.accountId);
+        }
+        return env;
+    }
+    sessionCwd(opts) {
+        if (opts.accountId)
+            return agentHermesWorkspaceDir(opts.accountId);
+        return opts.cwd;
+    }
+    /**
+     * Write systemContext to `<hermes-workspace>/AGENTS.md` atomically before
+     * spawn. NOTE: hermes only reads this file on the first turn of a session
+     * (see class-level docstring); subsequent turns keep the persisted
+     * system prompt and ignore filesystem changes.
+     */
+    prepareTurn(opts) {
+        if (!opts.accountId)
+            return;
+        const { hermesWorkspace } = ensureAgentHermesWorkspace(opts.accountId);
+        const target = path.join(hermesWorkspace, "AGENTS.md");
+        const tmp = path.join(hermesWorkspace, `.AGENTS.md.${process.pid}.tmp`);
+        mkdirSync(hermesWorkspace, { recursive: true, mode: 0o700 });
+        writeFileSync(tmp, opts.systemContext ?? "", { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    /** Spawn with the runtime-private hermes-workspace as cwd. */
+    async run(opts) {
+        const effective = opts.accountId
+            ? { ...opts, cwd: agentHermesWorkspaceDir(opts.accountId) }
+            : opts;
+        return super.run(effective);
+    }
+    /**
+     * Translate ACP `session/update` notifications into StreamBlocks +
+     * assistant text. We surface the common shapes that hermes emits:
+     *   - `agent_message_chunk` / `user_message_chunk` content blocks
+     *   - `tool_call` / `tool_call_update`
+     *   - `agent_thought_chunk`
+     *
+     * Anything else is forwarded as `kind: "other"` so subclasses /
+     * downstream channels can introspect.
+     */
+    onUpdate(params, ctx) {
+        const update = params.update ?? {};
+        const kind = typeof update.sessionUpdate === "string" ? update.sessionUpdate : "";
+        let blockKind = "other";
+        if (kind === "agent_message_chunk") {
+            const content = update
+                .content;
+            if (content && content.type === "text" && typeof content.text === "string") {
+                ctx.appendAssistantText(content.text);
+            }
+            blockKind = "assistant_text";
+        }
+        else if (kind === "agent_thought_chunk") {
+            blockKind = "system";
+        }
+        else if (kind === "tool_call" || kind === "tool_call_update") {
+            blockKind = "tool_use";
+        }
+        else if (kind === "user_message_chunk") {
+            blockKind = "other";
+        }
+        ctx.emitBlock({ raw: params, kind: blockKind, seq: ctx.seq });
+    }
+    /**
+     * trustLevel-driven policy. We pick the FIRST option whose `kind` matches
+     * our intent — `allow_*` for permit, otherwise cancel. ACP's
+     * DeniedOutcome carries no `optionId` / `reason` field; rationale lives
+     * in the daemon log.
+     */
+    async onPermissionRequest(req, opts) {
+        const options = Array.isArray(req.options) ? req.options : [];
+        const trust = opts.trustLevel;
+        if (trust === "owner" || trust === "trusted") {
+            const allow = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow_")) ??
+                options[0];
+            if (allow?.optionId) {
+                return { outcome: { outcome: "selected", optionId: allow.optionId } };
+            }
+            return { outcome: { outcome: "cancelled" } };
+        }
+        // public: deny everything that requires explicit approval
+        return { outcome: { outcome: "cancelled" } };
+    }
+}