@botcord/daemon 0.2.27 → 0.2.28

package/dist/agent-discovery.d.ts

@@ -28,6 +28,8 @@ export interface DiscoveredAgentCredential {
     openclawGateway?: string;
     /** OpenClaw agent profile override from credentials. */
     openclawAgent?: string;
+    /** Hermes profile name from credentials (only meaningful for hermes-agent). */
+    hermesProfile?: string;
     /** Key id from the credentials file — surfaced so boot-time workspace
      * seeding (see daemon-agent-workspace-plan.md §9) can render identity.md
      * without re-reading the file. */

package/dist/agent-discovery.js

@@ -102,6 +102,8 @@ export function discoverAgentCredentials(opts = {}) {
             entry.openclawGateway = creds.openclawGateway;
         if (creds.openclawAgent)
             entry.openclawAgent = creds.openclawAgent;
+        if (creds.hermesProfile)
+            entry.hermesProfile = creds.hermesProfile;
         if (creds.keyId)
             entry.keyId = creds.keyId;
         if (creds.savedAt)

package/dist/agent-workspace.d.ts

@@ -48,7 +48,9 @@ export declare function ensureAgentCodexHome(agentId: string): string;
  * loader (which only sees this isolated HERMES_HOME, not `~/.hermes`)
  * can discover them.
  */
-export declare function ensureAgentHermesWorkspace(agentId: string): {
+export declare function ensureAgentHermesWorkspace(agentId: string, opts?: {
+    attached?: boolean;
+}): {
     hermesHome: string;
     hermesWorkspace: string;
 };

package/dist/agent-workspace.js

@@ -327,11 +327,19 @@ export function ensureAgentCodexHome(agentId) {
  * loader (which only sees this isolated HERMES_HOME, not `~/.hermes`)
  * can discover them.
  */
-export function ensureAgentHermesWorkspace(agentId) {
+export function ensureAgentHermesWorkspace(agentId, opts = {}) {
     const hermesHome = agentHermesHomeDir(agentId);
     const hermesWorkspace = agentHermesWorkspaceDir(agentId);
-    mkdirTolerant(hermesHome);
     mkdirTolerant(hermesWorkspace);
+    // Attach mode: HERMES_HOME points at the user's `~/.hermes/profiles/<n>/`
+    // so we MUST NOT touch the per-agent isolated home. The cwd
+    // (`hermesWorkspace`) is still ours and `prepareTurn` writes AGENTS.md
+    // there — that's the only thing the daemon is allowed to author when
+    // attached to a user-owned profile.
+    if (opts.attached) {
+        return { hermesHome, hermesWorkspace };
+    }
+    mkdirTolerant(hermesHome);
     writeIfMissing(path.join(hermesHome, ".env"), "# hermes-agent environment overrides for this BotCord agent.\n" +
         "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n");
     seedHermesConfig(hermesHome);

package/dist/daemon-config-map.d.ts

@@ -8,6 +8,8 @@ export interface AgentRuntimeMeta {
     openclawGateway?: string;
     /** Optional override of the OpenClaw agent profile within the gateway. */
     openclawAgent?: string;
+    /** Hermes profile name to attach to (`runtime === "hermes-agent"` only). */
+    hermesProfile?: string;
 }
 /** Profile + tokenFile-resolved bearer token. Exported so other module-boundary
  *  paths (runtime probing, post-provision hot-add) reuse the same resolver

package/dist/daemon-config-map.js

@@ -245,6 +245,9 @@ export function buildManagedRoutes(agentIds, agentRuntimes, defaultRoute, opencl
             }
             route.gateway = resolved;
         }
+        if (runtime === "hermes-agent" && meta.hermesProfile) {
+            route.hermesProfile = meta.hermesProfile;
+        }
         out.set(agentId, route);
     }
     return out;

package/dist/daemon.d.ts

@@ -110,6 +110,7 @@ export interface BootBackfillResult {
         cwd?: string;
         openclawGateway?: string;
         openclawAgent?: string;
+        hermesProfile?: string;
     }>;
 }
 /**

package/dist/daemon.js

@@ -425,12 +425,13 @@ export function backfillBootAgents(agents, opts) {
     for (const a of agents) {
         if (a.credentialsFile)
             credentialPathByAgentId.set(a.agentId, a.credentialsFile);
-        if (a.runtime || a.cwd || a.openclawGateway || a.openclawAgent) {
+        if (a.runtime || a.cwd || a.openclawGateway || a.openclawAgent || a.hermesProfile) {
             agentRuntimes[a.agentId] = {
                 ...(a.runtime ? { runtime: a.runtime } : {}),
                 ...(a.cwd ? { cwd: a.cwd } : {}),
                 ...(a.openclawGateway ? { openclawGateway: a.openclawGateway } : {}),
                 ...(a.openclawAgent ? { openclawAgent: a.openclawAgent } : {}),
+                ...(a.hermesProfile ? { hermesProfile: a.hermesProfile } : {}),
             };
         }
         // Seed files are written only when missing (see `ensureAgentWorkspace`),

package/dist/gateway/dispatcher.js

@@ -837,6 +837,7 @@ export class Dispatcher {
                     onBlock,
                     onStatus,
                     gateway: route.gateway,
+                    ...(route.hermesProfile ? { hermesProfile: route.hermesProfile } : {}),
                 });
             }
             catch (err) {

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

@@ -9,6 +9,41 @@ import type { RuntimeProbeResult, RuntimeRunOptions } from "../types.js";
 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;
+/**
+ * Discovered hermes profile entry (daemon-side shape; wire shape lives in
+ * protocol-core's `HermesProfileProbe`). Occupancy is filled in later by
+ * `provision.ts` from local credentials, not here.
+ */
+export interface HermesProfileInfo {
+    name: string;
+    home: string;
+    isDefault?: boolean;
+    isActive?: boolean;
+    modelName?: string;
+    sessionsCount?: number;
+    hasSoul?: boolean;
+}
+/**
+ * Resolve the hermes root (`~/.hermes`) — this is the location of the
+ * synthetic `default` profile per upstream's "default profile = HERMES_HOME
+ * itself" convention (`hermes_cli/profiles.py:8`).
+ */
+export declare function hermesRootDir(): string;
+export declare function isValidHermesProfileName(name: string): boolean;
+/**
+ * Resolve a hermes profile's HERMES_HOME directory. `default` maps to
+ * `~/.hermes`; all other names map to `~/.hermes/profiles/<name>`. Mirrors
+ * `hermes_cli/profiles.py:get_profile_dir`.
+ */
+export declare function hermesProfileHomeDir(name: string): string;
+/**
+ * Enumerate available hermes profiles on this device. Pure local filesystem
+ * scan — does not invoke any hermes binary. Returns the synthetic `default`
+ * entry first when `~/.hermes` exists (which it should, given that the probe
+ * already located `hermes-acp`); each `~/.hermes/profiles/<name>/` directory
+ * follows.
+ */
+export declare function listHermesProfiles(): HermesProfileInfo[];
 /**
  * Hermes Agent adapter. Drives `hermes-acp` (the ACP stdio adapter shipped
  * with `pip install "hermes-agent[acp]"`).

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

@@ -1,4 +1,5 @@
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
 import { agentHermesHomeDir, agentHermesWorkspaceDir, ensureAgentHermesWorkspace, } from "../../agent-workspace.js";
 import { buildCliEnv } from "../cli-resolver.js";
@@ -43,6 +44,122 @@ export function probeHermesAgent(deps = {}) {
         version: readCommandVersion(command, [], deps) ?? undefined,
     };
 }
+/**
+ * Resolve the hermes root (`~/.hermes`) — this is the location of the
+ * synthetic `default` profile per upstream's "default profile = HERMES_HOME
+ * itself" convention (`hermes_cli/profiles.py:8`).
+ */
+export function hermesRootDir() {
+    return path.join(homedir(), ".hermes");
+}
+/** Profile-name shape mirrors `hermes_cli/profiles.py:_PROFILE_ID_RE`. */
+const HERMES_PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export function isValidHermesProfileName(name) {
+    return name === "default" || HERMES_PROFILE_NAME_RE.test(name);
+}
+/**
+ * Resolve a hermes profile's HERMES_HOME directory. `default` maps to
+ * `~/.hermes`; all other names map to `~/.hermes/profiles/<name>`. Mirrors
+ * `hermes_cli/profiles.py:get_profile_dir`.
+ */
+export function hermesProfileHomeDir(name) {
+    if (!isValidHermesProfileName(name)) {
+        throw new Error(`Invalid hermes profile name: ${name}`);
+    }
+    if (name === "default")
+        return hermesRootDir();
+    return path.join(hermesRootDir(), "profiles", name);
+}
+function readActiveProfileName() {
+    try {
+        const raw = readFileSync(path.join(hermesRootDir(), "active_profile"), "utf8").trim();
+        return raw || "default";
+    }
+    catch {
+        return "default";
+    }
+}
+function readProfileModelName(profileHome) {
+    try {
+        const raw = readFileSync(path.join(profileHome, "config.yaml"), "utf8");
+        // Cheap surface-level YAML peek — config.yaml's first block is
+        // `model:\n  default: <name>`. Avoid pulling in a YAML dependency for
+        // a single optional field.
+        const match = raw.match(/^model:\s*\n(?:[ \t]+[^\n]*\n)*?[ \t]+default:\s*([^\n#]+)/m);
+        if (!match)
+            return undefined;
+        return match[1].trim().replace(/^['"]|['"]$/g, "") || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function countSessions(profileHome) {
+    try {
+        const dir = path.join(profileHome, "sessions");
+        if (!existsSync(dir))
+            return 0;
+        return readdirSync(dir).filter((f) => f.endsWith(".jsonl")).length;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasSoul(profileHome) {
+    return existsSync(path.join(profileHome, "SOUL.md"));
+}
+/**
+ * Enumerate available hermes profiles on this device. Pure local filesystem
+ * scan — does not invoke any hermes binary. Returns the synthetic `default`
+ * entry first when `~/.hermes` exists (which it should, given that the probe
+ * already located `hermes-acp`); each `~/.hermes/profiles/<name>/` directory
+ * follows.
+ */
+export function listHermesProfiles() {
+    const out = [];
+    const root = hermesRootDir();
+    const active = readActiveProfileName();
+    if (existsSync(root)) {
+        out.push({
+            name: "default",
+            home: root,
+            isDefault: true,
+            isActive: active === "default",
+            modelName: readProfileModelName(root),
+            sessionsCount: countSessions(root),
+            hasSoul: hasSoul(root),
+        });
+    }
+    const profilesDir = path.join(root, "profiles");
+    let entries = [];
+    try {
+        entries = readdirSync(profilesDir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (!HERMES_PROFILE_NAME_RE.test(name))
+            continue;
+        const home = path.join(profilesDir, name);
+        try {
+            if (!statSync(home).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        out.push({
+            name,
+            home,
+            isActive: active === name,
+            modelName: readProfileModelName(home),
+            sessionsCount: countSessions(home),
+            hasSoul: hasSoul(home),
+        });
+    }
+    return out;
+}
 /**
  * Hermes Agent adapter. Drives `hermes-acp` (the ACP stdio adapter shipped
  * with `pip install "hermes-agent[acp]"`).
@@ -115,7 +232,15 @@ export class HermesAgentAdapter extends AcpRuntimeAdapter {
             // Route dangerous tool calls through ACP request_permission.
             HERMES_INTERACTIVE: "1",
         };
-        if (opts.accountId) {
+        // Attach mode: BotCord agent shares a hermes profile (state.db /
+        // sessions / skills / .env) with the user's command-line `hermes`. In
+        // this mode we DO NOT seed a private home — the profile is wholly owned
+        // by the user, and AGENTS.md is written under the per-agent
+        // hermes-workspace cwd (NOT into the profile root) by `prepareTurn`.
+        if (opts.hermesProfile) {
+            env.HERMES_HOME = hermesProfileHomeDir(opts.hermesProfile);
+        }
+        else if (opts.accountId) {
             env.HERMES_HOME = agentHermesHomeDir(opts.accountId);
         }
         return env;
@@ -134,7 +259,9 @@ export class HermesAgentAdapter extends AcpRuntimeAdapter {
     prepareTurn(opts) {
         if (!opts.accountId)
             return;
-        const { hermesWorkspace } = ensureAgentHermesWorkspace(opts.accountId);
+        const { hermesWorkspace } = ensureAgentHermesWorkspace(opts.accountId, {
+            attached: !!opts.hermesProfile,
+        });
         const target = path.join(hermesWorkspace, "AGENTS.md");
         const tmp = path.join(hermesWorkspace, `.AGENTS.md.${process.pid}.tmp`);
         mkdirSync(hermesWorkspace, { recursive: true, mode: 0o700 });

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

@@ -12,9 +12,11 @@ interface SpawnDeps {
  *
  * 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`
+ * child speaks JSON-RPC over stdio; we send `initialize` once, then derive a
+ * stable OpenClaw `sessionKey` for the BotCord conversation. The persisted
+ * `runtimeSessionId` is only an ACP transport handle cached from a previous
+ * turn, so every resume first goes through `session/load` with
+ * `_meta.sessionKey` before `prompt`. Streaming `session/update`
  * notifications are relayed to `onBlock`.
  *
  * Process-pool lifetime + abort/cancel semantics live at module scope; see
@@ -29,6 +31,7 @@ export declare class OpenclawAcpAdapter implements RuntimeAdapter {
     private acquireHandle;
     private spawnAcpProcess;
     private newSession;
+    private loadSession;
     private prompt;
 }
 /**

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

@@ -75,9 +75,11 @@ export function probeOpenclaw(deps = {}) {
  *
  * 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`
+ * child speaks JSON-RPC over stdio; we send `initialize` once, then derive a
+ * stable OpenClaw `sessionKey` for the BotCord conversation. The persisted
+ * `runtimeSessionId` is only an ACP transport handle cached from a previous
+ * turn, so every resume first goes through `session/load` with
+ * `_meta.sessionKey` before `prompt`. Streaming `session/update`
  * notifications are relayed to `onBlock`.
  *
  * Process-pool lifetime + abort/cancel semantics live at module scope; see
@@ -117,6 +119,8 @@ export class OpenclawAcpAdapter {
         handle.inFlight += 1;
         if (handle.idleTimer)
             clearTimeout(handle.idleTimer);
+        // ACP session ids are process-local transport handles. They are useful as
+        // a cache, but the stable conversation identity is `sessionKey`.
         let acpSessionId = opts.sessionId ?? "";
         let seq = 0;
         let assistantText = "";
@@ -155,8 +159,28 @@ export class OpenclawAcpAdapter {
         };
         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.
+            // Ensure we have a live ACP transport session. If the dispatcher passes a
+            // cached session id, ask OpenClaw to load/rebind it with the stable
+            // sessionKey. If that handle is gone, discard it and create a fresh one.
+            if (acpSessionId) {
+                try {
+                    acpSessionId = await this.loadSession(handle, {
+                        sessionId: acpSessionId,
+                        cwd: opts.cwd,
+                        sessionKey,
+                    });
+                }
+                catch (err) {
+                    if (!isSessionNotFoundError(err))
+                        throw err;
+                    log.warn("openclaw-acp.session-load-not-found", {
+                        accountId: opts.accountId,
+                        oldSessionId: acpSessionId,
+                        sessionKey,
+                    });
+                    acpSessionId = "";
+                }
+            }
             if (!acpSessionId) {
                 try {
                     acpSessionId = await this.newSession(handle, {
@@ -185,11 +209,16 @@ export class OpenclawAcpAdapter {
                 });
             }
             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)) {
+                if (isSessionNotFoundError(err)) {
                     try {
+                        const oldSessionId = acpSessionId;
+                        log.warn("openclaw-acp.prompt-session-not-found-retry", {
+                            accountId: opts.accountId,
+                            oldSessionId,
+                            sessionKey,
+                        });
                         const fresh = await this.newSession(handle, {
                             cwd: opts.cwd,
                             sessionKey,
@@ -197,6 +226,12 @@ export class OpenclawAcpAdapter {
                         handle.subscribers.delete(acpSessionId);
                         acpSessionId = fresh;
                         handle.subscribers.set(acpSessionId, onNotification);
+                        log.info("openclaw-acp.session-recreated", {
+                            accountId: opts.accountId,
+                            oldSessionId,
+                            newSessionId: acpSessionId,
+                            sessionKey,
+                        });
                         promptResult = await this.prompt(handle, {
                             sessionId: acpSessionId,
                             text: opts.text,
@@ -223,7 +258,8 @@ export class OpenclawAcpAdapter {
             };
         }
         catch (err) {
-            return failResult(acpSessionId, `openclaw-acp: ${err.message}`);
+            const message = err instanceof Error ? err.message : String(err);
+            return failResult(isSessionNotFoundError(err) ? "" : acpSessionId, `openclaw-acp: ${message}`);
         }
         finally {
             if (abortListener && opts.signal) {
@@ -332,6 +368,18 @@ export class OpenclawAcpAdapter {
         }
         return result.sessionId;
     }
+    async loadSession(handle, args) {
+        const result = (await sendRequest(handle, "session/load", {
+            sessionId: args.sessionId,
+            cwd: args.cwd,
+            mcpServers: [],
+            _meta: { sessionKey: args.sessionKey },
+        }));
+        if (result?.sessionId && typeof result.sessionId === "string") {
+            return result.sessionId;
+        }
+        return args.sessionId;
+    }
     async prompt(handle, args) {
         return sendRequest(handle, "session/prompt", {
             sessionId: args.sessionId,
@@ -372,7 +420,7 @@ function routeMessage(handle, msg) {
             return;
         handle.pending.delete(id);
         if (msg.error) {
-            const message = typeof msg.error?.message === "string" ? msg.error.message : "rpc error";
+            const message = formatRpcError(msg.error);
             pending.reject(new Error(message));
         }
         else {
@@ -435,6 +483,24 @@ function failResult(sessionId, error) {
         error,
     };
 }
+function formatRpcError(error) {
+    if (!error || typeof error !== "object")
+        return "rpc error";
+    const e = error;
+    const message = typeof e.message === "string" ? e.message : "rpc error";
+    const data = e.data;
+    if (data && typeof data === "object") {
+        const details = data.details;
+        if (typeof details === "string" && details.length > 0) {
+            return `${message}: ${details}`;
+        }
+    }
+    return message;
+}
+function isSessionNotFoundError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /session(?:\s+[\w-]+)?\s+not\s+found|unknown\s+session/i.test(msg);
+}
 function classifyAcpUpdate(note) {
     const update = note.params?.update;
     const kind = update?.sessionUpdate;

package/dist/gateway/types.d.ts

@@ -36,6 +36,14 @@ export interface GatewayRoute {
     trustLevel?: TrustLevel;
     /** Required when `runtime === "openclaw-acp"`. Resolved at config-load time. */
     gateway?: ResolvedOpenclawGateway;
+    /**
+     * Hermes profile name to attach to. Set when `runtime === "hermes-agent"`
+     * and the agent is bound to a specific `~/.hermes/profiles/<name>/`. The
+     * dispatcher forwards this to the adapter as
+     * {@link RuntimeRunOptions.hermesProfile}, which is what the adapter uses
+     * to switch `HERMES_HOME` at spawn time.
+     */
+    hermesProfile?: string;
 }
 /**
  * Per-channel configuration entry. Channel-specific extras (e.g. BotCord
@@ -306,6 +314,15 @@ export interface RuntimeRunOptions {
      * lifting service URLs out of `extraArgs` into typed first-class fields.
      */
     gateway?: ResolvedOpenclawGateway;
+    /**
+     * Hermes profile to attach to. Only meaningful when `runtime ===
+     * "hermes-agent"`. When set, the adapter switches
+     * `HERMES_HOME=~/.hermes/profiles/<name>/` (or `~/.hermes` for `default`)
+     * so the BotCord agent shares state.db / sessions / skills with the
+     * user's command-line `hermes`. Mirrors how `gateway` is lifted out of
+     * `extraArgs` for the openclaw-acp runtime.
+     */
+    hermesProfile?: string;
 }
 /** Result returned by a runtime adapter after a turn completes. */
 export interface RuntimeRunResult {

package/dist/openclaw-discovery.d.ts

@@ -1,6 +1,6 @@
 import type { DaemonConfig, OpenclawGatewayProfile } from "./config.js";
 import { type WsEndpointProbeFn } from "./provision.js";
-export type DiscoveredOpenclawGatewaySource = "config-file" | "env" | "default-port";
+export type DiscoveredOpenclawGatewaySource = "config-file" | "env" | "systemd-unit" | "default-port";
 export interface DiscoveredOpenclawGateway {
     name: string;
     url: string;
@@ -14,6 +14,7 @@ export interface OpenclawGatewayDiscoveryOptions {
     probe?: WsEndpointProbeFn;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
+    systemdUnitPaths?: string[];
 }
 export interface MergeOpenclawGatewayResult {
     cfg: DaemonConfig;
@@ -25,5 +26,6 @@ export declare function mergeOpenclawGateways(cfg: DaemonConfig, found: Discover
 export declare function defaultOpenclawDiscoverySearchPaths(): string[];
 export declare function defaultOpenclawDiscoveryPorts(): number[];
 export declare function defaultOpenclawDiscoveryTokenFilePaths(): string[];
+export declare function defaultOpenclawDiscoverySystemdUnitPaths(): string[];
 export declare function openclawDiscoveryConfigEnabled(cfg: DaemonConfig): boolean;
 export declare function openclawAutoProvisionEnabled(cfg: DaemonConfig): boolean;