@botcord/daemon 0.2.5 → 0.2.6

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

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

@@ -37,7 +37,12 @@ export declare abstract class NdjsonStreamAdapter implements RuntimeAdapter {
     protected abstract resolveBinary(opts: RuntimeRunOptions): string;
     protected abstract buildArgs(opts: RuntimeRunOptions): string[];
     protected abstract handleEvent(obj: unknown, ctx: NdjsonEventCtx): void;
-    /** Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). */
-    protected spawnEnv(_opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    /**
+     * Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). Subclasses that
+     * override should compose with the bundled-CLI env helper so spawned
+     * `botcord` invocations stay scoped to the right hub/agent — see
+     * {@link buildCliEnv}.
+     */
+    protected spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv;
     run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
 }

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

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { buildCliEnv } from "../cli-resolver.js";
 import { consoleLogger } from "../log.js";
 const log = consoleLogger;
 /**
@@ -22,9 +23,21 @@ const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
 const KILL_GRACE_MS = 5_000;
 /** Base class for runtime adapters that drive a CLI emitting newline-delimited JSON. */
 export class NdjsonStreamAdapter {
-    /** Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). */
-    spawnEnv(_opts) {
-        return process.env;
+    /**
+     * Override to tweak env (FORCE_COLOR=0, NO_COLOR=1, etc). Subclasses that
+     * override should compose with the bundled-CLI env helper so spawned
+     * `botcord` invocations stay scoped to the right hub/agent — see
+     * {@link buildCliEnv}.
+     */
+    spawnEnv(opts) {
+        return {
+            ...process.env,
+            ...buildCliEnv({
+                hubUrl: opts.hubUrl,
+                accountId: opts.accountId,
+                basePath: process.env.PATH,
+            }),
+        };
     }
     async run(opts) {
         if (opts.signal.aborted) {

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

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+import { type ProbeDeps } from "./probe.js";
+import type { RuntimeAdapter, RuntimeProbeResult, RuntimeRunOptions, RuntimeRunResult } from "../types.js";
+/** Test-only: drop all cached child processes. */
+export declare function __resetOpenclawAcpPoolForTests(): void;
+export declare function probeOpenclaw(deps?: ProbeDeps): RuntimeProbeResult;
+interface SpawnDeps {
+    spawnFn?: typeof spawn;
+}
+/**
+ * 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 declare class OpenclawAcpAdapter implements RuntimeAdapter {
+    readonly id: "openclaw-acp";
+    private readonly spawnFn;
+    constructor(deps?: SpawnDeps);
+    probe(): RuntimeProbeResult;
+    run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+    private acquireHandle;
+    private spawnAcpProcess;
+    private newSession;
+    private prompt;
+}
+/**
+ * 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 declare function buildAcpSessionKey(args: {
+    openclawAgent: string;
+    accountId: string;
+    conversationKey: string;
+}): string;
+export {};