@botcord/daemon 0.2.5 → 0.2.8

package/src/provision.ts

@@ -14,16 +14,21 @@ import {
   derivePublicKey,
   loadStoredCredentials,
   writeCredentialsFile,
+  type AgentIdentitySnapshot,
   type ControlAck,
   type ControlFrame,
+  type HelloParams,
   type ListRuntimesResult,
   type ProvisionAgentParams,
   type RevokeAgentParams,
   type RevokeAgentResult,
   type RuntimeProbeResult,
   type StoredBotCordCredentials,
+  type UpdateAgentParams,
 } from "@botcord/protocol-core";
 import type { Gateway } from "./gateway/index.js";
+import type { PolicyResolverLike } from "./gateway/policy-resolver.js";
+import type { PolicyUpdatedParams } from "@botcord/protocol-core";
 import type {
   GatewayChannelConfig,
   GatewayRuntimeSnapshot,
@@ -36,15 +41,21 @@ import {
   type RouteRule,
   type RouteRuleMatch,
 } from "./config.js";
-import { BOTCORD_CHANNEL_TYPE, buildManagedRoutes } from "./daemon-config-map.js";
+import {
+  BOTCORD_CHANNEL_TYPE,
+  buildManagedRoutes,
+  prepareGatewayProfile,
+} from "./daemon-config-map.js";
 import {
   agentHomeDir,
   agentStateDir,
   agentWorkspaceDir,
+  applyAgentIdentity,
   ensureAgentWorkspace,
 } from "./agent-workspace.js";
 import { detectRuntimes, getAdapterModule } from "./adapters/runtimes.js";
 import { log as daemonLog } from "./log.js";
+import { discoverAgentCredentials } from "./agent-discovery.js";
 
 /** Options accepted by {@link createProvisioner}. */
 export interface ProvisionerOptions {
@@ -55,6 +66,14 @@ export interface ProvisionerOptions {
    * run without a real Hub.
    */
   register?: typeof BotCordClient.register;
+  /**
+   * Optional policy-resolver handle (PR3). When present, the
+   * `policy_updated` control frame routes through it: cache is invalidated
+   * for the (agent, room?) pair, and any embedded `policy` payload is
+   * applied directly so the next inbound sees the fresh policy without an
+   * extra round-trip.
+   */
+  policyResolver?: PolicyResolverLike;
 }
 
 /** The value a frame handler returns (minus the `id` which the channel fills in). */
@@ -70,6 +89,7 @@ export function createProvisioner(opts: ProvisionerOptions): (
 ) => Promise<AckBody> {
   const gateway = opts.gateway;
   const register = opts.register ?? BotCordClient.register;
+  const policyResolver = opts.policyResolver;
 
   return async (frame: ControlFrame): Promise<AckBody> => {
     daemonLog.debug("provision.dispatch", { type: frame.type, id: frame.id });
@@ -77,6 +97,38 @@ export function createProvisioner(opts: ProvisionerOptions): (
       case CONTROL_FRAME_TYPES.PING:
         return { ok: true, result: { pong: true, ts: Date.now() } };
 
+      case CONTROL_FRAME_TYPES.HELLO: {
+        const params = (frame.params ?? {}) as unknown as HelloParams;
+        const result = applyHelloIdentitySnapshot(params.agents);
+        daemonLog.debug("hello: identity snapshot applied", {
+          frameId: frame.id,
+          received: params.agents?.length ?? 0,
+          updated: result.updated,
+          skipped: result.skipped,
+        });
+        return { ok: true, result };
+      }
+
+      case CONTROL_FRAME_TYPES.UPDATE_AGENT: {
+        const params = (frame.params ?? {}) as unknown as UpdateAgentParams;
+        if (!params.agentId) {
+          return {
+            ok: false,
+            error: { code: "bad_params", message: "update_agent requires params.agentId" },
+          };
+        }
+        const result = applyAgentIdentity(params.agentId, {
+          displayName: params.displayName,
+          bio: params.bio,
+        });
+        daemonLog.info("update_agent applied", {
+          agentId: params.agentId,
+          changed: result.changed,
+          skipped: result.skipped ?? null,
+        });
+        return { ok: true, result };
+      }
+
       case CONTROL_FRAME_TYPES.PROVISION_AGENT: {
         const params = (frame.params ?? {}) as unknown as ProvisionAgentParams;
         daemonLog.info("provision_agent: start", {
@@ -86,6 +138,18 @@ export function createProvisioner(opts: ProvisionerOptions): (
           name: params.name ?? null,
         });
         const agent = await provisionAgent(params, { gateway, register });
+        // Seed the policy resolver from the optional `defaultAttention` /
+        // `attentionKeywords` fields (PR3, control-frame.ts). Hub builds that
+        // don't yet emit these stay backwards-compatible — the resolver just
+        // falls back to `mode=always` until a `policy_updated` frame arrives.
+        if (policyResolver && params.defaultAttention) {
+          policyResolver.put(agent.agentId, null, {
+            mode: params.defaultAttention,
+            keywords: Array.isArray(params.attentionKeywords)
+              ? params.attentionKeywords.slice()
+              : [],
+          });
+        }
         return {
           ok: true,
           result: {
@@ -125,8 +189,57 @@ export function createProvisioner(opts: ProvisionerOptions): (
         return { ok: true, result: res };
       }
 
+      case CONTROL_FRAME_TYPES.POLICY_UPDATED: {
+        const params = (frame.params ?? {}) as unknown as PolicyUpdatedParams;
+        const agentId = params.agent_id;
+        if (typeof agentId !== "string" || !agentId) {
+          return {
+            ok: false,
+            error: { code: "bad_params", message: "policy_updated requires agent_id" },
+          };
+        }
+        if (!policyResolver) {
+          // No resolver wired — quietly succeed; the daemon may be running
+          // without the gateway-level attention gate (e.g. legacy boot path).
+          daemonLog.debug("policy_updated: no resolver — noop", { agentId });
+          return { ok: true, result: { agent_id: agentId, applied: false } };
+        }
+        const roomId = typeof params.room_id === "string" ? params.room_id : undefined;
+        if (params.policy) {
+          // Embedded policy payload — install directly to avoid a refetch.
+          policyResolver.put(agentId, roomId ?? null, {
+            mode: params.policy.mode,
+            keywords: Array.isArray(params.policy.keywords)
+              ? params.policy.keywords.slice()
+              : [],
+            ...(typeof params.policy.muted_until === "number"
+              ? { muted_until: params.policy.muted_until }
+              : {}),
+          });
+        } else {
+          policyResolver.invalidate(agentId, roomId);
+        }
+        daemonLog.info("policy_updated: applied", {
+          agentId,
+          roomId: roomId ?? null,
+          embedded: !!params.policy,
+        });
+        return {
+          ok: true,
+          result: { agent_id: agentId, applied: true, embedded: !!params.policy },
+        };
+      }
+
       case CONTROL_FRAME_TYPES.LIST_RUNTIMES: {
-        const snapshot = collectRuntimeSnapshot();
+        // Async path so the openclaw-acp endpoints get probed inline; gateway
+        // / WS errors are swallowed inside `collectRuntimeSnapshotAsync`.
+        let cfgForProbe: { openclawGateways?: any[] } | undefined;
+        try {
+          cfgForProbe = loadConfig();
+        } catch {
+          cfgForProbe = undefined;
+        }
+        const snapshot = await collectRuntimeSnapshotAsync({ cfg: cfgForProbe });
         daemonLog.debug("list_runtimes", { count: snapshot.runtimes.length });
         return { ok: true, result: snapshot };
       }
@@ -155,6 +268,8 @@ interface ProvisionCtx {
   register: typeof BotCordClient.register;
 }
 
+const openclawProvisionLocks = new Map<string, Promise<unknown>>();
+
 async function provisionAgent(
   params: ProvisionAgentParams,
   ctx: ProvisionCtx,
@@ -166,13 +281,53 @@ async function provisionAgent(
   const explicitCwd = params.credentials?.cwd ?? params.cwd;
   assertSafeCwd(explicitCwd);
 
+  const openclawSel = pickOpenclawSelection(params);
+  if (openclawSel.gateway && openclawSel.agent) {
+    return withOpenclawProvisionLock(openclawSel.gateway, openclawSel.agent, async () => {
+      const existing = findCredentialsByOpenclaw(openclawSel.gateway!, openclawSel.agent!);
+      if (existing) {
+        daemonLog.info("provision_agent: openclaw binding already exists", {
+          gateway: openclawSel.gateway,
+          openclawAgent: openclawSel.agent,
+          agentId: existing.agentId,
+        });
+        return installExistingOpenclawBinding(existing.agentId, ctx);
+      }
+      const cfg = loadConfig();
+      const credentials = await materializeCredentials(params, cfg, ctx, explicitCwd);
+      return installLocalAgent(credentials, {
+        ...ctx,
+        cfg,
+        bio: params.bio,
+        source: params.credentials ? "hub-supplied" : "registered",
+      });
+    });
+  }
+
   const cfg = loadConfig();
   const credentials = await materializeCredentials(params, cfg, ctx, explicitCwd);
+  return installLocalAgent(credentials, {
+    ...ctx,
+    cfg,
+    bio: params.bio,
+    source: params.credentials ? "hub-supplied" : "registered",
+  });
+}
+
+async function installLocalAgent(
+  credentials: StoredBotCordCredentials,
+  ctx: ProvisionCtx & {
+    cfg: DaemonConfig;
+    bio?: string;
+    source: "hub-supplied" | "registered" | "adopted-openclaw";
+  },
+): Promise<ProvisionedAgent> {
+  const cfg = ctx.cfg;
   daemonLog.debug("provision: credentials materialized", {
     agentId: credentials.agentId,
     hubUrl: credentials.hubUrl,
     runtime: credentials.runtime ?? null,
-    source: params.credentials ? "hub-supplied" : "registered",
+    source: ctx.source,
   });
 
   const credentialsFile = writeCredentialsFile(
@@ -186,7 +341,7 @@ async function provisionAgent(
   try {
     ensureAgentWorkspace(credentials.agentId, {
       displayName: credentials.displayName,
-      bio: params.bio,
+      bio: ctx.bio,
       runtime: credentials.runtime,
       keyId: credentials.keyId,
       savedAt: credentials.savedAt,
@@ -246,11 +401,7 @@ async function provisionAgent(
   // 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),
-    });
+    upsertManagedRouteForCredentials(credentials, cfg, ctx.gateway);
   } catch (err) {
     // Rollback the channel + config + credentials on managed-route failure
     // (shouldn't happen — pure map op — but keeps the invariant tight).
@@ -289,6 +440,63 @@ async function provisionAgent(
   };
 }
 
+function upsertManagedRouteForCredentials(
+  credentials: StoredBotCordCredentials,
+  cfg: DaemonConfig,
+  gateway: Gateway,
+): void {
+  const synthRoute: import("./gateway/index.js").GatewayRoute = {
+    match: { accountId: credentials.agentId },
+    runtime: credentials.runtime ?? cfg.defaultRoute.adapter,
+    cwd: credentials.cwd ?? agentWorkspaceDir(credentials.agentId),
+  };
+  if (synthRoute.runtime === "openclaw-acp") {
+    const profile = (cfg.openclawGateways ?? []).find(
+      (g) => g.name === credentials.openclawGateway,
+    );
+    if (profile) {
+      const prepared = prepareGatewayProfile(profile);
+      synthRoute.gateway = {
+        name: prepared.name,
+        url: prepared.url,
+        ...(prepared.resolvedToken ? { token: prepared.resolvedToken } : {}),
+        ...(credentials.openclawAgent
+          ? { openclawAgent: credentials.openclawAgent }
+          : prepared.defaultAgent
+            ? { openclawAgent: prepared.defaultAgent }
+            : {}),
+      };
+    }
+  }
+  gateway.upsertManagedRoute(credentials.agentId, synthRoute);
+}
+
+async function installExistingOpenclawBinding(
+  agentId: string,
+  ctx: ProvisionCtx,
+): Promise<ProvisionedAgent> {
+  const credentialsFile = defaultCredentialsFile(agentId);
+  const credentials = loadStoredCredentials(credentialsFile);
+  const cfg = loadConfig();
+  const updated = addAgentToConfig(cfg, credentials.agentId);
+  if (updated) saveConfig(updated);
+  const snap = ctx.gateway.snapshot();
+  if (!snap.channels[credentials.agentId]) {
+    await ctx.gateway.addChannel({
+      id: credentials.agentId,
+      type: BOTCORD_CHANNEL_TYPE,
+      accountId: credentials.agentId,
+      agentId: credentials.agentId,
+    });
+  }
+  upsertManagedRouteForCredentials(credentials, cfg, ctx.gateway);
+  return {
+    agentId: credentials.agentId,
+    hubUrl: credentials.hubUrl,
+    credentialsFile,
+  };
+}
+
 async function materializeCredentials(
   params: ProvisionAgentParams,
   cfg: DaemonConfig,
@@ -332,6 +540,9 @@ async function materializeCredentials(
     if (typeof c.tokenExpiresAt === "number") record.tokenExpiresAt = c.tokenExpiresAt;
     if (runtime) record.runtime = runtime;
     record.cwd = cwd;
+    const openclawSel = pickOpenclawSelection(params);
+    if (openclawSel.gateway) record.openclawGateway = openclawSel.gateway;
+    if (openclawSel.agent) record.openclawAgent = openclawSel.agent;
     return record;
   }
 
@@ -361,9 +572,175 @@ async function materializeCredentials(
   };
   if (runtime) record.runtime = runtime;
   record.cwd = cwd;
+  const openclawSel = pickOpenclawSelection(params);
+  if (openclawSel.gateway) record.openclawGateway = openclawSel.gateway;
+  if (openclawSel.agent) record.openclawAgent = openclawSel.agent;
   return record;
 }
 
+/**
+ * Resolve OpenClaw routing selection from a `provision_agent` frame. Top-level
+ * `params.openclaw` (nested) wins over the flat `credentials.openclaw*` mirror.
+ * Returning `{}` is fine — only meaningful when the agent's runtime is
+ * `openclaw-acp`, and `buildManagedRoutes` falls back to defaultRoute.gateway
+ * when both are missing.
+ */
+function pickOpenclawSelection(
+  params: ProvisionAgentParams,
+): { gateway?: string; agent?: string } {
+  const out: { gateway?: string; agent?: string } = {};
+  const top = params.openclaw;
+  if (top && typeof top.gateway === "string" && top.gateway.length > 0) {
+    out.gateway = top.gateway;
+    if (typeof top.agent === "string" && top.agent.length > 0) out.agent = top.agent;
+    return out;
+  }
+  const flat = params.credentials;
+  if (flat) {
+    if (typeof flat.openclawGateway === "string" && flat.openclawGateway.length > 0) {
+      out.gateway = flat.openclawGateway;
+    }
+    if (typeof flat.openclawAgent === "string" && flat.openclawAgent.length > 0) {
+      out.agent = flat.openclawAgent;
+    }
+  }
+  return out;
+}
+
+async function withOpenclawProvisionLock<T>(
+  gateway: string,
+  agent: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const key = `${gateway}\0${agent}`;
+  const prev = openclawProvisionLocks.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const chain = prev.then(() => current);
+  openclawProvisionLocks.set(key, chain);
+  await prev.catch(() => undefined);
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (openclawProvisionLocks.get(key) === chain) {
+      openclawProvisionLocks.delete(key);
+    }
+  }
+}
+
+function findCredentialsByOpenclaw(
+  gateway: string,
+  openclawAgent: string,
+): { agentId: string; credentialsFile: string } | null {
+  const discovered = discoverAgentCredentials({
+    credentialsDir: path.join(homedir(), ".botcord", "credentials"),
+  });
+  for (const a of discovered.agents) {
+    if (a.openclawGateway === gateway && a.openclawAgent === openclawAgent) {
+      return { agentId: a.agentId, credentialsFile: a.credentialsFile };
+    }
+  }
+  return null;
+}
+
+export interface AdoptDiscoveredOpenclawAgentsResult {
+  adopted: string[];
+  skipped: Array<{ gateway: string; openclawAgent?: string; reason: string }>;
+  failed: Array<{ gateway: string; openclawAgent?: string; error: string }>;
+}
+
+export async function adoptDiscoveredOpenclawAgents(ctx: {
+  gateway: Gateway;
+  register?: typeof BotCordClient.register;
+  cfg?: DaemonConfig;
+  timeoutMs?: number;
+  probe?: WsEndpointProbeFn;
+}): Promise<AdoptDiscoveredOpenclawAgentsResult> {
+  const register = ctx.register ?? BotCordClient.register;
+  const cfg = ctx.cfg ?? loadConfig();
+  const result: AdoptDiscoveredOpenclawAgentsResult = {
+    adopted: [],
+    skipped: [],
+    failed: [],
+  };
+  for (const gw of cfg.openclawGateways ?? []) {
+    let probeResult: Awaited<ReturnType<typeof probeOpenclawAgents>>;
+    try {
+      probeResult = await probeOpenclawAgents(gw, {
+        timeoutMs: ctx.timeoutMs,
+        probe: ctx.probe,
+      });
+    } catch (err) {
+      result.failed.push({
+        gateway: gw.name,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    if (!probeResult.ok) {
+      result.skipped.push({
+        gateway: gw.name,
+        reason: probeResult.error ?? "gateway_unreachable",
+      });
+      continue;
+    }
+    for (const oc of probeResult.agents ?? []) {
+      await withOpenclawProvisionLock(gw.name, oc.id, async () => {
+        const existing = findCredentialsByOpenclaw(gw.name, oc.id);
+        if (existing) {
+          result.skipped.push({
+            gateway: gw.name,
+            openclawAgent: oc.id,
+            reason: "already_bound",
+          });
+          return;
+        }
+        const freshCfg = loadConfig();
+        if (!inferHubUrl(freshCfg)) {
+          result.skipped.push({
+            gateway: gw.name,
+            openclawAgent: oc.id,
+            reason: "missing_hub_url",
+          });
+          daemonLog.warn("openclaw adopt skipped: no known hubUrl", {
+            gateway: gw.name,
+            openclawAgent: oc.id,
+          });
+          return;
+        }
+        try {
+          const params: ProvisionAgentParams = {
+            runtime: "openclaw-acp",
+            name: oc.name ?? `openclaw-${oc.id}`,
+            openclaw: { gateway: gw.name, agent: oc.id },
+          };
+          const credentials = await materializeCredentials(params, freshCfg, {
+            gateway: ctx.gateway,
+            register,
+          }, undefined);
+          const installed = await installLocalAgent(credentials, {
+            gateway: ctx.gateway,
+            register,
+            cfg: freshCfg,
+            source: "adopted-openclaw",
+          });
+          result.adopted.push(installed.agentId);
+        } catch (err) {
+          result.failed.push({
+            gateway: gw.name,
+            openclawAgent: oc.id,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      });
+    }
+  }
+  return result;
+}
+
 async function revokeAgent(
   params: RevokeAgentParams,
   ctx: { gateway: Gateway },
@@ -555,6 +932,277 @@ export function collectRuntimeSnapshot(): ListRuntimesResult {
   return { runtimes, probedAt: Date.now() };
 }
 
+/** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
+export const RUNTIME_ENDPOINTS_CAP = 32;
+
+/** Injection seam for L2 + L3 endpoint probes — kept testable + side-effect-free. */
+export type WsEndpointProbeFn = (args: {
+  url: string;
+  token?: string;
+  timeoutMs: number;
+}) => Promise<{
+  ok: boolean;
+  version?: string;
+  /**
+   * L3 — populated when `agents.list` succeeds. `id` is the stable key
+   * consumed by route lookups / `openclawAgent`; `name` is display-only.
+   */
+  agents?: Array<{
+    id: string;
+    name?: string;
+    workspace?: string;
+    model?: { name?: string; provider?: string };
+  }>;
+  error?: string;
+}>;
+
+/**
+ * Default L2 + L3 probe — opens a WS handshake against the OpenClaw gateway
+ * and, when the connection is up, issues a JSON-RPC `agents.list` request to
+ * enumerate configured agent profiles. Best-effort: a successful WS open with
+ * a failed `agents.list` still reports `ok: true` (just without `agents`),
+ * matching the RFC's "agents populated only when listing succeeded" rule.
+ *
+ * Method name and result shape follow OpenClaw:
+ *   `~/claws/openclaw/src/gateway/server-methods/agents.ts:416` and
+ *   `~/claws/openclaw/src/gateway/session-utils.ts:783` —
+ *   `{ defaultId, mainKey, scope, agents: [{ id, name?, identity?, workspace, model? }] }`.
+ */
+async function defaultWsProbe(args: {
+  url: string;
+  token?: string;
+  timeoutMs: number;
+}): Promise<{
+  ok: boolean;
+  version?: string;
+  agents?: Array<{
+    id: string;
+    name?: string;
+    workspace?: string;
+    model?: { name?: string; provider?: string };
+  }>;
+  error?: string;
+}> {
+  type AgentRow = {
+    id: string;
+    name?: string;
+    workspace?: string;
+    model?: { name?: string; provider?: string };
+  };
+  type ProbeResult = {
+    ok: boolean;
+    version?: string;
+    agents?: AgentRow[];
+    error?: string;
+  };
+  const { default: WebSocket } = await import("ws");
+  return new Promise<ProbeResult>((resolve) => {
+    let settled = false;
+    let ws: any;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (v: ProbeResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      try {
+        ws?.terminate();
+      } catch {
+        // ignore
+      }
+      resolve(v);
+    };
+    try {
+      const headers: Record<string, string> = {};
+      if (args.token) headers["Authorization"] = `Bearer ${args.token}`;
+      ws = new WebSocket(args.url, { headers });
+    } catch (err) {
+      resolve({ ok: false, error: (err as Error).message });
+      return;
+    }
+    timer = setTimeout(() => settle({ ok: false, error: "timeout" }), args.timeoutMs);
+    const requestId = "probe-agents-list";
+    ws.on("open", () => {
+      // L3: enumerate agent profiles. We don't fail the L2 result if this
+      // call fails — the gateway is reachable either way.
+      try {
+        ws.send(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: requestId,
+            method: "agents.list",
+            params: {},
+          }),
+        );
+      } catch (err) {
+        settle({ ok: true, error: `agents.list send failed: ${(err as Error).message}` });
+      }
+    });
+    ws.on("message", (raw: Buffer | string) => {
+      try {
+        const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
+        if (msg?.id !== requestId) return; // ignore unrelated frames
+        if (msg.error) {
+          settle({ ok: true, error: String(msg.error?.message ?? "agents.list error") });
+          return;
+        }
+        const list = Array.isArray(msg.result?.agents) ? msg.result.agents : [];
+        const agents: AgentRow[] = [];
+        for (const a of list) {
+          if (!a || typeof a.id !== "string" || a.id.length === 0) continue;
+          const row: AgentRow = { id: a.id };
+          if (typeof a.name === "string") row.name = a.name;
+          if (typeof a.workspace === "string") row.workspace = a.workspace;
+          if (a.model && typeof a.model === "object") {
+            const model: { name?: string; provider?: string } = {};
+            if (typeof a.model.name === "string") model.name = a.model.name;
+            if (typeof a.model.provider === "string") model.provider = a.model.provider;
+            if (model.name || model.provider) row.model = model;
+          }
+          agents.push(row);
+        }
+        settle({ ok: true, agents });
+      } catch (err) {
+        settle({ ok: true, error: `agents.list parse failed: ${(err as Error).message}` });
+      }
+    });
+    ws.on("error", (err: Error) => {
+      settle({ ok: false, error: err.message });
+    });
+    ws.on("close", () => {
+      // If the socket closes before `agents.list` resolved we still treat
+      // L2 as ok (open fired) and emit no agents.
+      settle({ ok: true });
+    });
+  });
+}
+
+export async function probeOpenclawAgents(
+  profile: { url: string; token?: string; tokenFile?: string },
+  opts: { timeoutMs?: number; probe?: WsEndpointProbeFn } = {},
+): Promise<{
+  ok: boolean;
+  version?: string;
+  agents?: Array<{
+    id: string;
+    name?: string;
+    workspace?: string;
+    model?: { name?: string; provider?: string };
+  }>;
+  error?: string;
+}> {
+  const probe = opts.probe ?? defaultWsProbe;
+  const prepared = prepareGatewayProfile({
+    name: "probe",
+    url: profile.url,
+    ...(profile.token ? { token: profile.token } : {}),
+    ...(profile.tokenFile ? { tokenFile: profile.tokenFile } : {}),
+  });
+  return probe({
+    url: profile.url,
+    token: prepared.resolvedToken,
+    timeoutMs: opts.timeoutMs ?? 3000,
+  });
+}
+
+/**
+ * Async variant that includes L2 (gateway reachability) and L3 (agent listing)
+ * probes for runtimes that talk to external services. Used by the production
+ * `list_runtimes` and first-connect snapshot paths.
+ *
+ * `cfg` is optional so existing callers without a loaded config (e.g. tests)
+ * can keep using the sync `collectRuntimeSnapshot()` — when absent, the result
+ * is identical to that function.
+ */
+export async function collectRuntimeSnapshotAsync(opts: {
+  cfg?: { openclawGateways?: Array<{ name: string; url: string; token?: string; tokenFile?: string }> };
+  wsProbe?: WsEndpointProbeFn;
+  timeoutMs?: number;
+} = {}): Promise<ListRuntimesResult> {
+  const base = collectRuntimeSnapshot();
+  const gateways = opts.cfg?.openclawGateways ?? [];
+  if (gateways.length === 0) return base;
+  // Default daemon-side budget is 3s — it must stay below the Hub's
+  // `list_runtimes` ack wait (5s, see backend/hub/routers/daemon_control.py)
+  // so a single slow gateway can't blow the whole snapshot to a 504.
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  const capped = gateways.slice(0, RUNTIME_ENDPOINTS_CAP);
+  const endpoints = await Promise.all(
+    capped.map(async (g) => {
+      try {
+        const res = await probeOpenclawAgents(g, {
+          probe: opts.wsProbe,
+          timeoutMs,
+        });
+        const entry: any = { name: g.name, url: g.url, reachable: res.ok };
+        if (res.version) entry.version = res.version;
+        if (res.error) entry.error = res.error;
+        if (res.agents) entry.agents = res.agents;
+        return entry;
+      } catch (err) {
+        return {
+          name: g.name,
+          url: g.url,
+          reachable: false,
+          error: (err as Error).message,
+        };
+      }
+    }),
+  );
+  const out: ListRuntimesResult = { ...base };
+  out.runtimes = base.runtimes.map((r) =>
+    r.id === "openclaw-acp" ? { ...r, endpoints } : r,
+  );
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// hello agents snapshot (lightweight identity sync)
+// ---------------------------------------------------------------------------
+
+interface HelloIdentityResult {
+  updated: number;
+  skipped: number;
+}
+
+/**
+ * Reconcile every agent identity carried by the `hello.agents` snapshot
+ * against the on-disk `identity.md`. Best-effort: a malformed entry or a
+ * file-system error for one agent never aborts the rest.
+ *
+ * Identity-snapshot semantics intentionally only touch the metadata
+ * line + Bio body — Role/Boundaries paragraphs the user authored locally
+ * are preserved (see `applyAgentIdentity`). Missing identity.md files
+ * (agent provisioned on a different daemon, or workspace cleared) are
+ * silently skipped.
+ */
+export function applyHelloIdentitySnapshot(
+  snapshot: AgentIdentitySnapshot[] | undefined,
+): HelloIdentityResult {
+  const out: HelloIdentityResult = { updated: 0, skipped: 0 };
+  if (!Array.isArray(snapshot)) return out;
+  for (const entry of snapshot) {
+    if (!entry || typeof entry.agentId !== "string") {
+      out.skipped += 1;
+      continue;
+    }
+    try {
+      const result = applyAgentIdentity(entry.agentId, {
+        displayName: entry.displayName,
+        bio: entry.bio,
+      });
+      if (result.changed) out.updated += 1;
+      else out.skipped += 1;
+    } catch (err) {
+      out.skipped += 1;
+      daemonLog.warn("hello.identity apply failed", {
+        agentId: entry.agentId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // reload_config / list_agents / set_route handlers (P3)
 // ---------------------------------------------------------------------------
@@ -641,17 +1289,19 @@ export async function reloadConfig(ctx: { gateway: Gateway }): Promise<ReloadRes
  */
 function readAgentRuntimesFromCredentials(
   agentIds: string[],
-): Record<string, { runtime?: string; cwd?: string }> {
-  const out: Record<string, { runtime?: string; cwd?: string }> = {};
+): Record<string, { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string }> {
+  const out: Record<string, { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string }> = {};
   for (const id of agentIds) {
     const file = defaultCredentialsFile(id);
     try {
       if (!existsSync(file)) continue;
       const creds = loadStoredCredentials(file);
-      const entry: { runtime?: string; cwd?: string } = {};
+      const entry: { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string } = {};
       if (creds.runtime) entry.runtime = creds.runtime;
       if (creds.cwd) entry.cwd = creds.cwd;
-      if (entry.runtime || entry.cwd) out[id] = entry;
+      if (creds.openclawGateway) entry.openclawGateway = creds.openclawGateway;
+      if (creds.openclawAgent) entry.openclawAgent = creds.openclawAgent;
+      if (entry.runtime || entry.cwd || entry.openclawGateway || entry.openclawAgent) out[id] = entry;
     } catch {
       // best-effort — skip agents with unreadable credentials
     }
@@ -782,11 +1432,21 @@ export function setRoute(params: unknown): SetRouteResult {
     match.conversationPrefix = p.pattern;
   }
 
+  // Fall back to defaultRoute.extraArgs (mirrors adapter/cwd inheritance
+  // above) so dashboard-driven `set_route` calls that only carry agentId +
+  // pattern still pick up operator-wide flags like `--permission-mode
+  // bypassPermissions`. Without this, every newly provisioned agent lost
+  // those flags and Bash/MCP tool calls would deadlock on permission prompts.
+  const extraArgs = Array.isArray(route?.extraArgs)
+    ? route!.extraArgs!.slice()
+    : Array.isArray(cfg.defaultRoute.extraArgs)
+      ? cfg.defaultRoute.extraArgs.slice()
+      : undefined;
   const newRule: RouteRule = {
     match,
     adapter,
     cwd,
-    ...(Array.isArray(route?.extraArgs) ? { extraArgs: route!.extraArgs!.slice() } : {}),
+    ...(extraArgs ? { extraArgs } : {}),
   };
 
   const routes = Array.isArray(cfg.routes) ? cfg.routes.slice() : [];
@@ -872,5 +1532,13 @@ function inferHubUrl(cfg: DaemonConfig): string | null {
       // skip
     }
   }
+  if (ids.length === 0) {
+    const discovered = discoverAgentCredentials({
+      credentialsDir: path.join(homedir(), ".botcord", "credentials"),
+    });
+    for (const a of discovered.agents) {
+      if (a.hubUrl) return a.hubUrl;
+    }
+  }
   return null;
 }