@botcord/daemon 0.1.1

package/dist/provision.js

@@ -0,0 +1,749 @@
+/**
+ * Business logic triggered by control-plane frames. The channel dispatches
+ * to this module with the parsed {@link ControlFrame}; we execute the
+ * side effects (register agent, write credentials, load route, add/remove
+ * gateway channel) and return an ack payload.
+ *
+ * See `docs/daemon-control-plane-plan.md` §4.3, §5.3, §8.
+ */
+import { existsSync, rmSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { BotCordClient, CONTROL_FRAME_TYPES, defaultCredentialsFile, derivePublicKey, loadStoredCredentials, writeCredentialsFile, } from "@botcord/protocol-core";
+import { loadConfig, resolveConfiguredAgentIds, saveConfig, } from "./config.js";
+import { BOTCORD_CHANNEL_TYPE, buildManagedRoutes } from "./daemon-config-map.js";
+import { agentHomeDir, agentStateDir, agentWorkspaceDir, ensureAgentWorkspace, } from "./agent-workspace.js";
+import { detectRuntimes, getAdapterModule } from "./adapters/runtimes.js";
+import { log as daemonLog } from "./log.js";
+/**
+ * Build a dispatcher function that routes a `ControlFrame` to the right
+ * handler. Returned function signature matches
+ * `ControlChannelOptions.handle`.
+ */
+export function createProvisioner(opts) {
+    const gateway = opts.gateway;
+    const register = opts.register ?? BotCordClient.register;
+    return async (frame) => {
+        daemonLog.debug("provision.dispatch", { type: frame.type, id: frame.id });
+        switch (frame.type) {
+            case CONTROL_FRAME_TYPES.PING:
+                return { ok: true, result: { pong: true, ts: Date.now() } };
+            case CONTROL_FRAME_TYPES.PROVISION_AGENT: {
+                const params = (frame.params ?? {});
+                daemonLog.info("provision_agent: start", {
+                    frameId: frame.id,
+                    hasCredentials: !!params.credentials,
+                    runtime: pickRuntime(params) ?? null,
+                    name: params.name ?? null,
+                });
+                const agent = await provisionAgent(params, { gateway, register });
+                return {
+                    ok: true,
+                    result: {
+                        agentId: agent.agentId,
+                        hubUrl: agent.hubUrl,
+                        credentialsFile: agent.credentialsFile,
+                    },
+                };
+            }
+            case CONTROL_FRAME_TYPES.REVOKE_AGENT: {
+                const params = (frame.params ?? {});
+                daemonLog.info("revoke_agent: start", {
+                    frameId: frame.id,
+                    agentId: params.agentId,
+                    deleteCredentials: params.deleteCredentials !== false,
+                });
+                const res = await revokeAgent(params, { gateway });
+                return { ok: true, result: res };
+            }
+            case CONTROL_FRAME_TYPES.LIST_AGENTS: {
+                const agents = listAgentsFromGateway(gateway);
+                daemonLog.debug("list_agents", { count: agents.length });
+                return { ok: true, result: { agents } };
+            }
+            case CONTROL_FRAME_TYPES.RELOAD_CONFIG: {
+                daemonLog.info("reload_config: start", { frameId: frame.id });
+                const res = await reloadConfig({ gateway });
+                return { ok: true, result: res };
+            }
+            case CONTROL_FRAME_TYPES.SET_ROUTE: {
+                daemonLog.info("set_route: start", { frameId: frame.id });
+                const res = setRoute(frame.params ?? {});
+                return { ok: true, result: res };
+            }
+            case CONTROL_FRAME_TYPES.LIST_RUNTIMES: {
+                const snapshot = collectRuntimeSnapshot();
+                daemonLog.debug("list_runtimes", { count: snapshot.runtimes.length });
+                return { ok: true, result: snapshot };
+            }
+            default:
+                daemonLog.warn("provision.dispatch: unknown frame type", {
+                    type: frame.type,
+                    id: frame.id,
+                });
+                return {
+                    ok: false,
+                    error: { code: "unknown_type", message: `unknown control frame type "${frame.type}"` },
+                };
+        }
+    };
+}
+async function provisionAgent(params, ctx) {
+    // Validate both caller-supplied cwd sources up front. Previously only
+    // `params.cwd` was checked, so `params.credentials.cwd` could smuggle an
+    // arbitrary path (e.g. `/etc`) into the credentials file; plan §7 closes
+    // that hole by moving the check to the union of both.
+    const explicitCwd = params.credentials?.cwd ?? params.cwd;
+    assertSafeCwd(explicitCwd);
+    const cfg = loadConfig();
+    const credentials = await materializeCredentials(params, cfg, ctx, explicitCwd);
+    daemonLog.debug("provision: credentials materialized", {
+        agentId: credentials.agentId,
+        hubUrl: credentials.hubUrl,
+        runtime: credentials.runtime ?? null,
+        source: params.credentials ? "hub-supplied" : "registered",
+    });
+    const credentialsFile = writeCredentialsFile(defaultCredentialsFile(credentials.agentId), credentials);
+    // Seed the per-agent workspace directory. On failure, unlink the fresh
+    // credentials file but do NOT `rm -rf` the agent dir — partial contents
+    // may belong to a pre-existing workspace we must not touch.
+    try {
+        ensureAgentWorkspace(credentials.agentId, {
+            displayName: credentials.displayName,
+            bio: params.bio,
+            runtime: credentials.runtime,
+            keyId: credentials.keyId,
+            savedAt: credentials.savedAt,
+        });
+    }
+    catch (err) {
+        try {
+            unlinkSync(credentialsFile);
+        }
+        catch {
+            // best-effort
+        }
+        throw err;
+    }
+    try {
+        const updated = addAgentToConfig(cfg, credentials.agentId);
+        if (updated)
+            saveConfig(updated);
+    }
+    catch (err) {
+        // Rollback the credentials file if we can't persist config — the
+        // daemon should stay in sync or not at all. `addChannel` below would
+        // otherwise succeed against a config that doesn't list the agent.
+        try {
+            unlinkSync(credentialsFile);
+        }
+        catch {
+            // best-effort
+        }
+        throw err;
+    }
+    try {
+        await ctx.gateway.addChannel({
+            id: credentials.agentId,
+            type: BOTCORD_CHANNEL_TYPE,
+            accountId: credentials.agentId,
+            agentId: credentials.agentId,
+        });
+    }
+    catch (err) {
+        // Best-effort rollback: drop the new agent from config and remove the
+        // credentials file. Log loudly so operators notice the partial state.
+        daemonLog.error("provision.addChannel failed, rolling back", {
+            agentId: credentials.agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        try {
+            const revertCfg = removeAgentFromConfig(loadConfig(), credentials.agentId);
+            if (revertCfg)
+                saveConfig(revertCfg);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            unlinkSync(credentialsFile);
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+    // Hot-add the synthesized per-agent managed route so the next turn picks
+    // the agent's runtime + workspace cwd without waiting for reload_config.
+    try {
+        ctx.gateway.upsertManagedRoute(credentials.agentId, {
+            match: { accountId: credentials.agentId },
+            runtime: credentials.runtime ?? cfg.defaultRoute.adapter,
+            cwd: credentials.cwd ?? agentWorkspaceDir(credentials.agentId),
+        });
+    }
+    catch (err) {
+        // Rollback the channel + config + credentials on managed-route failure
+        // (shouldn't happen — pure map op — but keeps the invariant tight).
+        daemonLog.error("provision.upsertManagedRoute failed, rolling back", {
+            agentId: credentials.agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        try {
+            await ctx.gateway.removeChannel(credentials.agentId, "provision rollback");
+        }
+        catch {
+            // ignore
+        }
+        try {
+            const revertCfg = removeAgentFromConfig(loadConfig(), credentials.agentId);
+            if (revertCfg)
+                saveConfig(revertCfg);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            unlinkSync(credentialsFile);
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+    daemonLog.info("agent provisioned", {
+        agentId: credentials.agentId,
+        credentialsFile,
+    });
+    return {
+        agentId: credentials.agentId,
+        hubUrl: credentials.hubUrl,
+        credentialsFile,
+    };
+}
+async function materializeCredentials(params, cfg, ctx, explicitCwd) {
+    // Runtime is an agent property (docs/agent-runtime-property-plan.md §4.1).
+    // Hub is authoritative; top-level `runtime` wins, `adapter` is a one-release
+    // alias, and `credentials.runtime` is the per-agent cached copy.
+    const runtime = pickRuntime(params);
+    if (runtime)
+        assertKnownRuntime(runtime);
+    // Fast path: Hub handed us the credential envelope directly.
+    if (params.credentials) {
+        const c = params.credentials;
+        if (!c.agentId || !c.keyId || !c.privateKey) {
+            throw new Error("provision_agent.credentials missing required fields (agentId, keyId, privateKey)");
+        }
+        const derivedPub = derivePublicKey(c.privateKey);
+        if (c.publicKey && c.publicKey !== derivedPub) {
+            throw new Error("provision_agent.credentials publicKey does not match privateKey");
+        }
+        const hubUrl = c.hubUrl;
+        if (!hubUrl) {
+            throw new Error("provision_agent.credentials missing hubUrl");
+        }
+        const cwd = explicitCwd ?? agentWorkspaceDir(c.agentId);
+        const record = {
+            version: 1,
+            hubUrl,
+            agentId: c.agentId,
+            keyId: c.keyId,
+            privateKey: c.privateKey,
+            publicKey: c.publicKey ?? derivedPub,
+            savedAt: new Date().toISOString(),
+        };
+        if (c.displayName)
+            record.displayName = c.displayName;
+        if (c.token)
+            record.token = c.token;
+        if (typeof c.tokenExpiresAt === "number")
+            record.tokenExpiresAt = c.tokenExpiresAt;
+        if (runtime)
+            record.runtime = runtime;
+        record.cwd = cwd;
+        return record;
+    }
+    // Slow path: daemon registers a fresh identity against Hub. We need a
+    // hubUrl — but `DaemonConfig` doesn't persist one, so fall back to a
+    // sibling credentials file if any agent is already bound.
+    const hubUrl = inferHubUrl(cfg);
+    if (!hubUrl) {
+        throw new Error("provision_agent: cannot register without a known hubUrl — include `credentials.hubUrl` in the frame");
+    }
+    const name = params.name || `agent-${Date.now()}`;
+    const reg = await ctx.register(hubUrl, name, params.bio);
+    const cwd = explicitCwd ?? agentWorkspaceDir(reg.agentId);
+    const record = {
+        version: 1,
+        hubUrl: reg.hubUrl,
+        agentId: reg.agentId,
+        keyId: reg.keyId,
+        privateKey: reg.privateKey,
+        publicKey: reg.publicKey,
+        savedAt: new Date().toISOString(),
+        displayName: name,
+        token: reg.token,
+        tokenExpiresAt: reg.expiresAt,
+    };
+    if (runtime)
+        record.runtime = runtime;
+    record.cwd = cwd;
+    return record;
+}
+async function revokeAgent(params, ctx) {
+    if (!params.agentId) {
+        throw new Error("revoke_agent requires params.agentId");
+    }
+    const agentId = params.agentId;
+    const deleteCreds = params.deleteCredentials !== false;
+    // `deleteState` defaults to whatever `deleteCredentials` resolves to —
+    // vanilla revoke wipes runtime state, but explicit `deleteCredentials:false`
+    // (keep-creds) also implies keep-state unless the caller says otherwise.
+    const deleteState = params.deleteState ?? deleteCreds;
+    // Workspace is precious (user-authored memory/notes); require explicit opt-in.
+    const deleteWorkspace = params.deleteWorkspace === true;
+    // In-memory gateway ops run first so any in-flight turn is aborted before
+    // disk state changes. Both run unconditionally — the channel is revoked
+    // regardless of whether disk state survives, and the synthesized managed
+    // route is now dangling.
+    try {
+        await ctx.gateway.removeChannel(agentId, "revoked by hub");
+    }
+    catch (err) {
+        daemonLog.warn("revoke.removeChannel failed", {
+            agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    try {
+        ctx.gateway.removeManagedRoute(agentId);
+    }
+    catch (err) {
+        daemonLog.warn("revoke.removeManagedRoute failed", {
+            agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    let removed = false;
+    try {
+        const cfg = loadConfig();
+        const next = removeAgentFromConfig(cfg, agentId);
+        if (next) {
+            saveConfig(next);
+            removed = true;
+        }
+    }
+    catch (err) {
+        daemonLog.warn("revoke.saveConfig failed", {
+            agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    let credentialsDeleted = false;
+    if (deleteCreds) {
+        const file = defaultCredentialsFile(agentId);
+        try {
+            if (existsSync(file)) {
+                unlinkSync(file);
+                credentialsDeleted = true;
+            }
+        }
+        catch (err) {
+            daemonLog.warn("revoke.unlink failed", {
+                agentId,
+                file,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Disk steps are independent and best-effort: a failure at one step logs a
+    // warning but does not prevent the next (matches `deleteCredentials`).
+    let stateDeleted = false;
+    let workspaceDeleted = false;
+    if (deleteWorkspace) {
+        // Workspace deletion subsumes state — remove the whole agent home.
+        const home = agentHomeDir(agentId);
+        try {
+            if (existsSync(home)) {
+                rmSync(home, { recursive: true, force: true });
+                workspaceDeleted = true;
+                stateDeleted = true;
+            }
+        }
+        catch (err) {
+            daemonLog.warn("revoke.rmWorkspace failed", {
+                agentId,
+                path: home,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    else if (deleteState) {
+        const state = agentStateDir(agentId);
+        try {
+            if (existsSync(state)) {
+                rmSync(state, { recursive: true, force: true });
+                stateDeleted = true;
+            }
+        }
+        catch (err) {
+            daemonLog.warn("revoke.rmState failed", {
+                agentId,
+                path: state,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    daemonLog.info("agent revoked", {
+        agentId,
+        removed,
+        credentialsDeleted,
+        stateDeleted,
+        workspaceDeleted,
+    });
+    return { agentId, removed, credentialsDeleted, stateDeleted, workspaceDeleted };
+}
+/** Reject paths outside the operator's home directory (plan §8.3). */
+function assertSafeCwd(cwd) {
+    if (!cwd)
+        return;
+    const home = homedir();
+    const abs = path.resolve(cwd);
+    const rel = path.relative(home, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`provision_agent.cwd "${cwd}" is outside the user home directory`);
+    }
+}
+/**
+ * Append `agentId` to the daemon config if not already present. Returns a
+ * new config object or `null` if nothing changed (so callers can skip the
+ * disk write).
+ */
+export function addAgentToConfig(cfg, agentId) {
+    const list = Array.isArray(cfg.agents) ? cfg.agents.slice() : [];
+    if (cfg.agentId && !list.includes(cfg.agentId))
+        list.push(cfg.agentId);
+    if (list.includes(agentId))
+        return null;
+    list.push(agentId);
+    const next = { ...cfg, agents: list };
+    // Once `agents` exists explicitly, the legacy scalar becomes redundant.
+    delete next.agentId;
+    return next;
+}
+/** Inverse of {@link addAgentToConfig}. Returns `null` on no-op. */
+export function removeAgentFromConfig(cfg, agentId) {
+    const list = Array.isArray(cfg.agents) ? cfg.agents.slice() : [];
+    if (cfg.agentId && !list.includes(cfg.agentId))
+        list.push(cfg.agentId);
+    const before = list.length;
+    const filtered = list.filter((a) => a !== agentId);
+    const legacyMatched = cfg.agentId === agentId;
+    if (filtered.length === before && !legacyMatched)
+        return null;
+    const next = { ...cfg, agents: filtered };
+    if (legacyMatched)
+        delete next.agentId;
+    return next;
+}
+// ---------------------------------------------------------------------------
+// runtime-discovery snapshot (plan §8.5)
+// ---------------------------------------------------------------------------
+/**
+ * Probe every registered adapter and shape the result as the wire-level
+ * {@link ListRuntimesResult} — used by both the `list_runtimes` ack path and
+ * the daemon-side first-connect `runtime_snapshot` push in `daemon.ts`.
+ *
+ * Kept pure: the only side effects are `detectRuntimes()` itself (which the
+ * gateway already isolates from throwing) and reading the wall clock.
+ */
+export function collectRuntimeSnapshot() {
+    const entries = detectRuntimes();
+    const runtimes = entries.map((entry) => {
+        const record = {
+            id: entry.id,
+            available: entry.result.available,
+        };
+        // Only attach optional fields when present so the wire frame doesn't
+        // carry explicit `undefined`s — mirrors the credential-materialization
+        // style used above.
+        if (entry.result.version)
+            record.version = entry.result.version;
+        if (entry.result.path)
+            record.path = entry.result.path;
+        // Gateway's probe surface doesn't expose an `error` string today — it
+        // already swallows throws into `{available: false}`. We leave the wire
+        // field blank in that case and let callers treat `!available` as reason
+        // enough; filling a synthetic message would be misleading.
+        return record;
+    });
+    return { runtimes, probedAt: Date.now() };
+}
+/**
+ * Re-read `config.json` and reconcile the running gateway against it. New
+ * agents in config but not in gateway snapshot → `addChannel`; agents in
+ * gateway but no longer in config → `removeChannel`. The agent's
+ * credentials must already exist on disk; we don't re-register identities
+ * here (that's `provision_agent`'s job).
+ */
+export async function reloadConfig(ctx) {
+    const cfg = loadConfig();
+    const desired = new Set(resolveConfiguredAgentIds(cfg) ?? []);
+    const current = new Set(Object.keys(ctx.gateway.snapshot().channels));
+    const added = [];
+    const removed = [];
+    for (const id of desired) {
+        if (current.has(id))
+            continue;
+        const channelCfg = {
+            id,
+            type: BOTCORD_CHANNEL_TYPE,
+            accountId: id,
+            agentId: id,
+        };
+        try {
+            await ctx.gateway.addChannel(channelCfg);
+            added.push(id);
+        }
+        catch (err) {
+            daemonLog.warn("reload_config.addChannel failed", {
+                agentId: id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    for (const id of current) {
+        if (desired.has(id))
+            continue;
+        try {
+            await ctx.gateway.removeChannel(id, "reload_config");
+            removed.push(id);
+        }
+        catch (err) {
+            daemonLog.warn("reload_config.removeChannel failed", {
+                agentId: id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Re-synthesize managed routes so `set_route` + `reload_config` actually
+    // applies at runtime (plan §10.5). User-authored `cfg.routes[]` lives in a
+    // different bucket and is unaffected.
+    try {
+        const freshCfg = loadConfig();
+        const freshAgents = resolveConfiguredAgentIds(freshCfg) ?? [];
+        const agentRuntimes = readAgentRuntimesFromCredentials(freshAgents);
+        const freshDefault = {
+            runtime: freshCfg.defaultRoute.adapter,
+            cwd: freshCfg.defaultRoute.cwd,
+        };
+        const managed = buildManagedRoutes(freshAgents, agentRuntimes, freshDefault);
+        ctx.gateway.replaceManagedRoutes(managed);
+    }
+    catch (err) {
+        daemonLog.warn("reload_config.replaceManagedRoutes failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    daemonLog.info("config reloaded", { added, removed });
+    return { reloaded: true, added, removed };
+}
+/**
+ * Read cached `runtime`/`cwd` from each agent's credentials file. Missing
+ * files or malformed entries are skipped silently — callers fall back to
+ * the daemon's `defaultRoute` for those agents.
+ */
+function readAgentRuntimesFromCredentials(agentIds) {
+    const out = {};
+    for (const id of agentIds) {
+        const file = defaultCredentialsFile(id);
+        try {
+            if (!existsSync(file))
+                continue;
+            const creds = loadStoredCredentials(file);
+            const entry = {};
+            if (creds.runtime)
+                entry.runtime = creds.runtime;
+            if (creds.cwd)
+                entry.cwd = creds.cwd;
+            if (entry.runtime || entry.cwd)
+                out[id] = entry;
+        }
+        catch {
+            // best-effort — skip agents with unreadable credentials
+        }
+    }
+    return out;
+}
+function listAgentsFromGateway(gateway) {
+    const snap = gateway.snapshot();
+    // Include any configured agents that the gateway may not have a status for
+    // yet (e.g. initial boot before first reconcile).
+    let configuredIds = [];
+    try {
+        configuredIds = resolveConfiguredAgentIds(loadConfig()) ?? [];
+    }
+    catch {
+        configuredIds = [];
+    }
+    const ids = new Set([...Object.keys(snap.channels), ...configuredIds]);
+    const out = [];
+    for (const id of ids) {
+        const ch = snap.channels[id];
+        let name = id;
+        try {
+            const file = defaultCredentialsFile(id);
+            if (existsSync(file)) {
+                const c = loadStoredCredentials(file);
+                if (c.displayName)
+                    name = c.displayName;
+            }
+        }
+        catch {
+            // ignore — fall back to the id
+        }
+        const online = !!(ch && ch.running && ch.connected !== false);
+        const entry = {
+            id,
+            name,
+            online,
+            status: ch ? (ch.running ? "running" : "stopped") : "unknown",
+        };
+        if (ch?.lastStartAt)
+            entry.lastMessageAt = ch.lastStartAt;
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Persist a route in `config.json` for the given agent. If a route already
+ * matches `agentId` exactly (single-key match), it is replaced; otherwise a
+ * new entry is appended. `match.accountId` is forced to `agentId` so the
+ * route is always agent-scoped. The change is applied at next
+ * `reload_config` — it does not mutate the live router immediately.
+ *
+ * Accepts the contract's `{pattern, agentId}` shape (treats `pattern` as a
+ * conversation-id prefix) AND the richer `{agentId, route: {...}}` shape
+ * for daemon-side callers that need to set adapter/cwd explicitly.
+ */
+export function setRoute(params) {
+    const p = (params ?? {});
+    const agentId = p.agentId;
+    if (!agentId || typeof agentId !== "string") {
+        throw new Error("set_route requires params.agentId");
+    }
+    const route = p.route;
+    if (!route && (!p.pattern || typeof p.pattern !== "string")) {
+        throw new Error("set_route requires either params.route or params.pattern");
+    }
+    // Defaults used when only `pattern` is supplied.
+    const cfg = loadConfig();
+    const adapter = route?.adapter ?? cfg.defaultRoute.adapter;
+    if (!getAdapterModule(adapter)) {
+        throw new Error(`set_route: unknown adapter "${adapter}"`);
+    }
+    const cwd = route?.cwd ?? cfg.defaultRoute.cwd;
+    if (!cwd || typeof cwd !== "string") {
+        throw new Error("set_route: route.cwd is required");
+    }
+    assertSafeCwd(cwd);
+    // Build the canonical match — always pin accountId so the route can't
+    // accidentally bleed across agents.
+    const incomingMatch = (route?.match ?? {});
+    const match = { ...incomingMatch, accountId: agentId };
+    if (p.pattern && typeof p.pattern === "string" && !match.conversationPrefix) {
+        match.conversationPrefix = p.pattern;
+    }
+    const newRule = {
+        match,
+        adapter,
+        cwd,
+        ...(Array.isArray(route?.extraArgs) ? { extraArgs: route.extraArgs.slice() } : {}),
+    };
+    const routes = Array.isArray(cfg.routes) ? cfg.routes.slice() : [];
+    // Replace an existing matching rule. We use the canonical signature
+    // (accountId + conversationPrefix or accountId-only) so successive
+    // `set_route` calls for the same agent+pattern overwrite in place.
+    const sameSignature = (m) => {
+        if (!m)
+            return false;
+        if (m.accountId !== agentId)
+            return false;
+        const incomingPrefix = match.conversationPrefix ?? null;
+        const existingPrefix = m.conversationPrefix ?? m.roomPrefix ?? null;
+        if (incomingPrefix !== existingPrefix)
+            return false;
+        if (incomingPrefix === null && hasNonAccountSelector(m))
+            return false;
+        return true;
+    };
+    const existingIdx = routes.findIndex((r) => sameSignature(r.match));
+    let inserted = false;
+    let routeIndex;
+    if (existingIdx >= 0) {
+        routes[existingIdx] = newRule;
+        routeIndex = existingIdx;
+    }
+    else {
+        routes.push(newRule);
+        routeIndex = routes.length - 1;
+        inserted = true;
+    }
+    const next = { ...cfg, routes };
+    saveConfig(next);
+    daemonLog.info("route set", { agentId, routeIndex, inserted });
+    return { ok: true, agentId, routeIndex, inserted };
+}
+function hasNonAccountSelector(m) {
+    if (!m)
+        return false;
+    return !!(m.channel ||
+        m.conversationId ||
+        m.conversationPrefix ||
+        m.conversationKind ||
+        m.senderId ||
+        m.roomId ||
+        m.roomPrefix ||
+        typeof m.mentioned === "boolean");
+}
+/**
+ * Resolve the runtime id the frame asks for. Prefers the canonical
+ * `runtime` field; falls back to the deprecated `adapter` alias and finally
+ * to `credentials.runtime` for Hub builds that ship the envelope-only form.
+ */
+function pickRuntime(params) {
+    const candidates = [params.runtime, params.adapter, params.credentials?.runtime];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.length > 0)
+            return c;
+    }
+    return undefined;
+}
+function assertKnownRuntime(runtime) {
+    const mod = getAdapterModule(runtime);
+    if (!mod) {
+        throw new Error(`provision_agent: unknown runtime "${runtime}"`);
+    }
+}
+/**
+ * Pull a hubUrl out of an existing credentials file, if the daemon is
+ * already bound to at least one agent. Used as a fallback when
+ * `provision_agent` doesn't carry an explicit `credentials.hubUrl`.
+ */
+function inferHubUrl(cfg) {
+    const ids = resolveConfiguredAgentIds(cfg) ?? [];
+    for (const id of ids) {
+        const file = defaultCredentialsFile(id);
+        try {
+            if (!existsSync(file))
+                continue;
+            const creds = loadStoredCredentials(file);
+            if (creds.hubUrl)
+                return creds.hubUrl;
+        }
+        catch {
+            // skip
+        }
+    }
+    return null;
+}