@botcord/daemon 0.2.5 → 0.2.6

package/src/config.ts

@@ -13,7 +13,24 @@ export const SNAPSHOT_PATH = path.join(DAEMON_DIR, "snapshot.json");
  * Adapter ids. Built-in adapters are enumerated for editor hints; any string
  * accepted by the registry is valid at runtime.
  */
-export type AdapterName = "claude-code" | "codex" | "gemini" | (string & {});
+export type AdapterName = "claude-code" | "codex" | "gemini" | "openclaw-acp" | (string & {});
+
+/**
+ * One OpenClaw gateway profile. Referenced by `RouteRule.gateway` and
+ * `DaemonRouteDefault.gateway` (and `StoredBotCordCredentials.openclawGateway`)
+ * via `name`. `tokenFile` is `~`-expanded and read at `toGatewayConfig` time;
+ * read failures do not block boot — the gateway becomes unusable but other
+ * gateways still work.
+ */
+export interface OpenclawGatewayProfile {
+  name: string;
+  url: string;
+  /** Bearer token; mutually-exclusive priority is `token > tokenFile`. */
+  token?: string;
+  tokenFile?: string;
+  /** Default OpenClaw agent profile name when a route does not pin one. */
+  defaultAgent?: string;
+}
 
 /**
  * Predicates selecting messages for a route. `roomId` / `roomPrefix` are
@@ -41,12 +58,23 @@ export interface RouteRule {
   cwd: string;
   /** Extra CLI flags appended to the adapter invocation. */
   extraArgs?: string[];
+  /**
+   * Required when `adapter === "openclaw-acp"`: name of an entry in
+   * `DaemonConfig.openclawGateways[]`.
+   */
+  gateway?: string;
+  /** Overrides `OpenclawGatewayProfile.defaultAgent` when set. */
+  openclawAgent?: string;
 }
 
 export interface DaemonRouteDefault {
   adapter: AdapterName;
   cwd: string;
   extraArgs?: string[];
+  /** Same semantics as `RouteRule.gateway`. */
+  gateway?: string;
+  /** Same semantics as `RouteRule.openclawAgent`. */
+  openclawAgent?: string;
 }
 
 /**
@@ -90,6 +118,28 @@ export interface DaemonConfig {
   routes: RouteRule[];
   /** If true, stream blocks (only meaningful for rm_oc_* rooms). */
   streamBlocks: boolean;
+  /**
+   * Persistent transcript-logging settings (design §3 / §6). Defaults to
+   * disabled — see `BOTCORD_TRANSCRIPT` for env-driven temporary overrides.
+   */
+  transcript?: TranscriptConfig;
+
+  /**
+   * Optional registry of OpenClaw gateway endpoints. Routes / managed routes
+   * with `adapter === "openclaw-acp"` reference these by `name`. Resolution
+   * to {@link ResolvedOpenclawGateway} happens eagerly in `toGatewayConfig`
+   * so the dispatcher never re-queries this list.
+   */
+  openclawGateways?: OpenclawGatewayProfile[];
+}
+
+/**
+ * Persistent transcript settings (design §6). Default-off — `botcord-daemon
+ * transcript enable` flips `enabled` and `transcript disable` flips it back.
+ * The env var `BOTCORD_TRANSCRIPT` can override at boot.
+ */
+export interface TranscriptConfig {
+  enabled?: boolean;
 }
 
 /**
@@ -160,11 +210,15 @@ function ensureDir(): void {
   }
 }
 
+export const CONFIG_MISSING = "CONFIG_MISSING";
+
 export function loadConfig(): DaemonConfig {
   if (!existsSync(CONFIG_PATH)) {
-    throw new Error(
-      `daemon config not found at ${CONFIG_PATH}. Run \`botcord-daemon init\` first.`,
-    );
+    const err = new Error(`daemon config not found at ${CONFIG_PATH}`) as Error & {
+      code?: string;
+    };
+    err.code = CONFIG_MISSING;
+    throw err;
   }
   const raw = readFileSync(CONFIG_PATH, "utf8");
   const parsed = JSON.parse(raw) as Partial<DaemonConfig>;
@@ -196,6 +250,65 @@ export function loadConfig(): DaemonConfig {
   }
   validateAdapter(parsed.defaultRoute.adapter, "defaultRoute.adapter");
 
+  const gatewaysRaw = (parsed as Partial<DaemonConfig>).openclawGateways;
+  const gatewayNames = new Set<string>();
+  if (gatewaysRaw !== undefined) {
+    if (!Array.isArray(gatewaysRaw)) {
+      throw new Error(
+        `daemon config "openclawGateways" must be an array (${CONFIG_PATH})`,
+      );
+    }
+    for (const [i, g] of gatewaysRaw.entries()) {
+      if (!g || typeof g !== "object") {
+        throw new Error(
+          `daemon config openclawGateways[${i}] is not an object (${CONFIG_PATH})`,
+        );
+      }
+      const gg = g as Partial<OpenclawGatewayProfile>;
+      if (typeof gg.name !== "string" || gg.name.length === 0) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].name must be a non-empty string (${CONFIG_PATH})`,
+        );
+      }
+      if (typeof gg.url !== "string" || gg.url.length === 0) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].url must be a non-empty string (${CONFIG_PATH})`,
+        );
+      }
+      if (gatewayNames.has(gg.name)) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].name "${gg.name}" duplicated (${CONFIG_PATH})`,
+        );
+      }
+      gatewayNames.add(gg.name);
+    }
+  }
+
+  const validateGatewayRef = (
+    adapter: string,
+    gateway: unknown,
+    where: string,
+  ): void => {
+    if (adapter === "openclaw-acp") {
+      if (typeof gateway !== "string" || gateway.length === 0) {
+        throw new Error(
+          `daemon config ${where} adapter "openclaw-acp" requires a "gateway" name (${CONFIG_PATH})`,
+        );
+      }
+      if (!gatewayNames.has(gateway)) {
+        throw new Error(
+          `daemon config ${where}.gateway "${gateway}" not in openclawGateways (${CONFIG_PATH})`,
+        );
+      }
+    }
+  };
+
+  validateGatewayRef(
+    parsed.defaultRoute.adapter,
+    (parsed.defaultRoute as DaemonRouteDefault).gateway,
+    "defaultRoute",
+  );
+
   const routesRaw = parsed.routes ?? [];
   if (!Array.isArray(routesRaw)) {
     throw new Error(`daemon config "routes" must be an array (${CONFIG_PATH})`);
@@ -210,6 +323,7 @@ export function loadConfig(): DaemonConfig {
       );
     }
     validateAdapter(r.adapter, `routes[${i}].adapter`);
+    validateGatewayRef(r.adapter, (r as RouteRule).gateway, `routes[${i}]`);
   }
   // Preserve the on-disk shape as-is so `config` prints what the user wrote.
   // Resolution of agents vs agentId happens at the consumption boundary
@@ -219,6 +333,20 @@ export function loadConfig(): DaemonConfig {
     routes: routesRaw,
     streamBlocks: parsed.streamBlocks ?? true,
   };
+  if (parsed.transcript && typeof parsed.transcript === "object") {
+    const t: TranscriptConfig = {};
+    if (typeof parsed.transcript.enabled === "boolean") t.enabled = parsed.transcript.enabled;
+    out.transcript = t;
+  }
+  if (gatewaysRaw && Array.isArray(gatewaysRaw)) {
+    out.openclawGateways = (gatewaysRaw as OpenclawGatewayProfile[]).map((g) => {
+      const copy: OpenclawGatewayProfile = { name: g.name, url: g.url };
+      if (typeof g.token === "string") copy.token = g.token;
+      if (typeof g.tokenFile === "string") copy.tokenFile = g.tokenFile;
+      if (typeof g.defaultAgent === "string") copy.defaultAgent = g.defaultAgent;
+      return copy;
+    });
+  }
   if (hasAgents) out.agents = (parsed.agents as string[]).slice();
   if (hasLegacy) out.agentId = parsed.agentId;
   if (discovery && typeof discovery === "object") {

package/src/daemon-config-map.ts

@@ -1,15 +1,109 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import type {
   GatewayChannelConfig,
   GatewayConfig,
   GatewayRoute,
+  ResolvedOpenclawGateway,
   RouteMatch,
   TrustLevel as GatewayTrustLevel,
 } from "./gateway/index.js";
-import type { DaemonConfig, RouteRule } from "./config.js";
+import type {
+  DaemonConfig,
+  DaemonRouteDefault,
+  OpenclawGatewayProfile,
+  RouteRule,
+} from "./config.js";
 import { resolveAgentIds } from "./config.js";
 import { agentWorkspaceDir } from "./agent-workspace.js";
 import { log as daemonLog } from "./log.js";
 
+/** Per-agent metadata cached from credentials, used by `buildManagedRoutes`. */
+export interface AgentRuntimeMeta {
+  runtime?: string;
+  cwd?: string;
+  /** OpenClaw gateway profile name to lookup in the registry. */
+  openclawGateway?: string;
+  /** Optional override of the OpenClaw agent profile within the gateway. */
+  openclawAgent?: string;
+}
+
+/** Profile + tokenFile-resolved bearer token. Exported so other module-boundary
+ *  paths (runtime probing, post-provision hot-add) reuse the same resolver
+ *  instead of duplicating tokenFile semantics. */
+export interface PreparedGatewayProfile extends OpenclawGatewayProfile {
+  /** Token actually usable at dispatch time; empty when load failed. */
+  resolvedToken?: string;
+  /** Reason `resolvedToken` is empty, for logs. */
+  tokenError?: string;
+}
+
+function expandHome(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return path.join(homedir(), p.slice(2));
+  return p;
+}
+
+/** Resolve one profile's token (inline > tokenFile). Failures are swallowed
+ *  into `tokenError`; `resolvedToken` is left undefined. Logs at warn for ops
+ *  visibility. */
+export function prepareGatewayProfile(
+  p: OpenclawGatewayProfile,
+): PreparedGatewayProfile {
+  const prepared: PreparedGatewayProfile = { ...p };
+  if (p.token && p.token.length > 0) {
+    prepared.resolvedToken = p.token;
+  } else if (p.tokenFile && p.tokenFile.length > 0) {
+    try {
+      prepared.resolvedToken = readFileSync(expandHome(p.tokenFile), "utf8").trim();
+    } catch (err: any) {
+      prepared.tokenError = err?.message ?? String(err);
+      daemonLog.warn("daemon.config.openclaw.tokenfile_failed", {
+        gateway: p.name,
+        tokenFile: p.tokenFile,
+        error: prepared.tokenError,
+      });
+    }
+  }
+  return prepared;
+}
+
+/** Build a name → prepared-profile map for a config's gateway registry. */
+export function prepareGatewayProfiles(
+  profiles: OpenclawGatewayProfile[] | undefined,
+): Map<string, PreparedGatewayProfile> {
+  const out = new Map<string, PreparedGatewayProfile>();
+  if (!profiles) return out;
+  for (const p of profiles) out.set(p.name, prepareGatewayProfile(p));
+  return out;
+}
+
+function resolveGateway(
+  profiles: Map<string, PreparedGatewayProfile>,
+  gatewayName: string | undefined,
+  agentOverride: string | undefined,
+  where: string,
+): ResolvedOpenclawGateway | undefined {
+  if (!gatewayName) {
+    daemonLog.warn("daemon.config.openclaw.missing_gateway", { where });
+    return undefined;
+  }
+  const profile = profiles.get(gatewayName);
+  if (!profile) {
+    daemonLog.warn("daemon.config.openclaw.unknown_gateway", { where, gateway: gatewayName });
+    return undefined;
+  }
+  const resolved: ResolvedOpenclawGateway = {
+    name: profile.name,
+    url: profile.url,
+  };
+  if (profile.resolvedToken) resolved.token = profile.resolvedToken;
+  const agent = agentOverride ?? profile.defaultAgent;
+  if (agent) resolved.openclawAgent = agent;
+  return resolved;
+}
+
 /** Options accepted by {@link toGatewayConfig}. */
 export interface ToGatewayConfigOptions {
   /**
@@ -24,7 +118,7 @@ export interface ToGatewayConfigOptions {
    * turns to its runtime. Explicit `cfg.routes` entries still win because
    * synthesized routes are appended after them.
    */
-  agentRuntimes?: Record<string, { runtime?: string; cwd?: string }>;
+  agentRuntimes?: Record<string, AgentRuntimeMeta>;
 }
 
 /**
@@ -59,7 +153,11 @@ function mapTrustLevel(
  * legacy alias and its canonical field are present, the canonical field
  * wins and a warning is logged.
  */
-function mapRoute(r: RouteRule): GatewayRoute {
+function mapRoute(
+  r: RouteRule,
+  profiles: Map<string, PreparedGatewayProfile>,
+  index: number,
+): GatewayRoute {
   const match: RouteMatch = {};
   if (r.match.channel) match.channel = r.match.channel;
   if (r.match.accountId) match.accountId = r.match.accountId;
@@ -95,13 +193,22 @@ function mapRoute(r: RouteRule): GatewayRoute {
   if (typeof r.match.mentioned === "boolean") match.mentioned = r.match.mentioned;
 
   const rawTrust = (r as { trustLevel?: "owner" | "untrusted" }).trustLevel;
-  return {
+  const out: GatewayRoute = {
     match,
     runtime: r.adapter,
     cwd: r.cwd,
     extraArgs: r.extraArgs,
     trustLevel: mapTrustLevel(rawTrust),
   };
+  if (r.adapter === "openclaw-acp") {
+    out.gateway = resolveGateway(
+      profiles,
+      r.gateway,
+      r.openclawAgent,
+      `routes[${index}]`,
+    );
+  }
+  return out;
 }
 
 /**
@@ -134,6 +241,8 @@ export function toGatewayConfig(
 
   // DaemonConfig's typed surface doesn't carry `trustLevel`, but we read it
   // defensively so future config extensions can propagate without a shape bump.
+  const profiles = prepareGatewayProfiles(cfg.openclawGateways);
+
   const rawDefaultTrust = (cfg.defaultRoute as { trustLevel?: "owner" | "untrusted" })
     .trustLevel;
   const defaultRoute: GatewayRoute = {
@@ -144,8 +253,17 @@ export function toGatewayConfig(
     // (direct → cancel-previous, group → serial).
     trustLevel: mapTrustLevel(rawDefaultTrust),
   };
+  if (cfg.defaultRoute.adapter === "openclaw-acp") {
+    const dr = cfg.defaultRoute as DaemonRouteDefault;
+    defaultRoute.gateway = resolveGateway(
+      profiles,
+      dr.gateway,
+      dr.openclawAgent,
+      "defaultRoute",
+    );
+  }
 
-  const routes: GatewayRoute[] = (cfg.routes ?? []).map(mapRoute);
+  const routes: GatewayRoute[] = (cfg.routes ?? []).map((r, i) => mapRoute(r, profiles, i));
 
   // Synthesize a per-agent route for every bound agent and hand it to the
   // gateway via the managed-routes bucket (plan §10.1). User-authored
@@ -157,6 +275,7 @@ export function toGatewayConfig(
     agentIds,
     opts.agentRuntimes ?? {},
     defaultRoute,
+    profiles,
   );
 
   return {
@@ -184,17 +303,43 @@ export function toGatewayConfig(
  */
 export function buildManagedRoutes(
   agentIds: string[],
-  agentRuntimes: Record<string, { runtime?: string; cwd?: string }>,
+  agentRuntimes: Record<string, AgentRuntimeMeta>,
   defaultRoute: GatewayRoute,
+  openclawProfiles?: Map<string, PreparedGatewayProfile>,
 ): Map<string, GatewayRoute> {
   const out = new Map<string, GatewayRoute>();
+  // Lazy-build profile map when caller didn't pass one (legacy callers).
+  const profiles = openclawProfiles ?? new Map<string, PreparedGatewayProfile>();
   for (const agentId of agentIds) {
     const meta = agentRuntimes[agentId] ?? {};
-    out.set(agentId, {
+    const runtime = meta.runtime ?? defaultRoute.runtime;
+    const route: GatewayRoute = {
       match: { accountId: agentId },
-      runtime: meta.runtime ?? defaultRoute.runtime,
+      runtime,
       cwd: meta.cwd || agentWorkspaceDir(agentId),
-    });
+      // Inherit defaultRoute's extraArgs so synthesized per-agent routes
+      // pick up operator-wide flags (e.g. `--permission-mode bypassPermissions`)
+      // that would otherwise apply only to agents listed in `cfg.routes[]`.
+      ...(defaultRoute.extraArgs ? { extraArgs: defaultRoute.extraArgs.slice() } : {}),
+    };
+    if (runtime === "openclaw-acp") {
+      // Per RFC §3.4: prefer credentials, fall back to defaultRoute.gateway.
+      const gatewayName = meta.openclawGateway ?? defaultRoute.gateway?.name;
+      const agentOverride = meta.openclawAgent;
+      const resolved = gatewayName
+        ? resolveGateway(profiles, gatewayName, agentOverride, `managedRoute[${agentId}]`)
+        : defaultRoute.gateway;
+      if (!resolved) {
+        // No usable gateway — skip the managed route so defaultRoute can take over.
+        daemonLog.warn("daemon.config.openclaw.managed_route_skipped", {
+          agentId,
+          gatewayName,
+        });
+        continue;
+      }
+      route.gateway = resolved;
+    }
+    out.set(agentId, route);
   }
   return out;
 }

package/src/daemon.ts

@@ -1,7 +1,12 @@
-import { CONTROL_FRAME_TYPES } from "@botcord/protocol-core";
+import {
+  CONTROL_FRAME_TYPES,
+  shouldWake,
+  type AttentionPolicy,
+} from "@botcord/protocol-core";
 import {
   Gateway,
   createBotCordChannel,
+  resolveTranscriptEnabled,
   sanitizeUntrustedContent,
   type ChannelAdapter,
   type GatewayChannelConfig,
@@ -31,6 +36,8 @@ import {
 } from "./loop-risk.js";
 import { composeBotCordUserTurn } from "./turn-text.js";
 import { UserAuthManager } from "./user-auth.js";
+import { PolicyResolver } from "./gateway/policy-resolver.js";
+import { scanMention } from "./mention-scan.js";
 
 /**
  * Matches the 10-minute turn timeout the legacy daemon dispatcher used, so
@@ -222,6 +229,18 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
 
   const gwConfig = toGatewayConfig(opts.config, { agentIds, agentRuntimes });
 
+  // Per-agent hub URL — read from each credential file at boot. Used to
+  // populate `BOTCORD_HUB` for runtime CLI subprocesses so the bundled
+  // `botcord` CLI talks to the same hub the agent is registered against,
+  // even when a single daemon hosts agents from different hubs.
+  const hubUrlByAgentId = new Map<string, string>();
+  for (const a of boot.agents) {
+    if (a.hubUrl) hubUrlByAgentId.set(a.agentId, a.hubUrl);
+  }
+  const fallbackHubUrl = opts.hubBaseUrl;
+  const resolveHubUrl = (accountId: string): string | undefined =>
+    hubUrlByAgentId.get(accountId) ?? fallbackHubUrl;
+
   // ActivityTracker lives at the daemon layer (not the gateway core). We
   // expose it to the gateway via (a) the `buildSystemContext` hook so the
   // cross-room digest reflects current activity, and (b) the `onInbound`
@@ -319,6 +338,40 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     });
   };
 
+  // Per-agent attention policy cache (PR3, design §4.2 / §5). Seeded from
+  // the optional `defaultAttention` / `attentionKeywords` carried by
+  // `provision_agent`, refreshed in-place by the `policy_updated` control
+  // frame. PR2 will plug per-room overrides into `fetchEffective`; PR3
+  // leaves it absent so the resolver collapses to per-agent state.
+  const policyResolver = new PolicyResolver({
+    fetchGlobal: async (_agentId: string) => undefined,
+  });
+
+  // Display-name lookup for the mention text-fallback. Populated from boot
+  // credentials; multi-agent daemons can reuse the same map via accountId.
+  const displayNameByAgent = new Map<string, string>();
+  for (const a of boot.agents) {
+    if (a.displayName) displayNameByAgent.set(a.agentId, a.displayName);
+  }
+
+  // Attention gate: compose `messages.mentioned` (sender-supplied — distrust)
+  // with a local `@<display_name>` / `@<agent_id>` text scan, resolve the
+  // effective policy, then defer to the protocol-core `shouldWake` decision.
+  const attentionGate = async (msg: GatewayInboundMessage): Promise<boolean> => {
+    const policy: AttentionPolicy = await policyResolver.resolve(
+      msg.accountId,
+      msg.conversation.id,
+    );
+    const localMention = scanMention(msg.text, {
+      agentId: msg.accountId,
+      displayName: displayNameByAgent.get(msg.accountId),
+    });
+    return shouldWake(policy, {
+      mentioned: msg.mentioned === true || localMention,
+      text: msg.text,
+    });
+  };
+
   const gateway = new Gateway({
     config: gwConfig,
     sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
@@ -340,6 +393,12 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     onInbound,
     onOutbound,
     composeUserTurn: composeBotCordUserTurn,
+    attentionGate,
+    resolveHubUrl,
+    transcriptEnabled: resolveTranscriptEnabled(
+      process.env.BOTCORD_TRANSCRIPT,
+      opts.config.transcript?.enabled === true,
+    ),
   });
 
   logger.info("daemon starting", {
@@ -356,7 +415,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     logger.warn("daemon starting with no channels", {
       source: boot.source,
       credentialsDir: boot.credentialsDir,
-      hint: "drop a credentials JSON in the discovery dir and restart, or run `botcord-daemon init --agent <ag_xxx>`",
+      hint: "drop a credentials JSON in the discovery dir and restart, or run `botcord-daemon start --agent <ag_xxx>` (only seeds config on first run)",
     });
   }
 
@@ -376,7 +435,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
       userId: userAuth.current.userId,
       hubUrl: userAuth.current.hubUrl,
     });
-    const provisioner = createProvisioner({ gateway });
+    const provisioner = createProvisioner({ gateway, policyResolver });
     controlChannel = new ControlChannel({
       auth: userAuth,
       handle: provisioner,
@@ -443,7 +502,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
  */
 export interface BootBackfillResult {
   credentialPathByAgentId: Map<string, string>;
-  agentRuntimes: Record<string, { runtime?: string; cwd?: string }>;
+  agentRuntimes: Record<string, { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string }>;
 }
 
 /**
@@ -466,10 +525,12 @@ export function backfillBootAgents(
   const failed: string[] = [];
   for (const a of agents) {
     if (a.credentialsFile) credentialPathByAgentId.set(a.agentId, a.credentialsFile);
-    if (a.runtime || a.cwd) {
+    if (a.runtime || a.cwd || a.openclawGateway || a.openclawAgent) {
       agentRuntimes[a.agentId] = {
         ...(a.runtime ? { runtime: a.runtime } : {}),
         ...(a.cwd ? { cwd: a.cwd } : {}),
+        ...(a.openclawGateway ? { openclawGateway: a.openclawGateway } : {}),
+        ...(a.openclawAgent ? { openclawAgent: a.openclawAgent } : {}),
       };
     }
     // Seed files are written only when missing (see `ensureAgentWorkspace`),

package/src/doctor.ts

@@ -31,9 +31,34 @@ export interface DoctorHttpResult {
   error?: string;
 }
 
+/** One endpoint probe entry, mirrored from `RuntimeEndpointProbe`. */
+export interface DoctorRuntimeEndpoint {
+  name: string;
+  url: string;
+  reachable: boolean;
+  version?: string;
+  error?: string;
+  agents?: Array<{
+    id: string;
+    name?: string;
+    workspace?: string;
+    model?: { name?: string; provider?: string };
+  }>;
+  /**
+   * Optional warning surfaced by the doctor: e.g. botcord plugin loaded on
+   * the gateway (would form a daemon → openclaw → botcord → Hub loop).
+   */
+  warnings?: string[];
+}
+
+/** Augmented runtime entry that may carry endpoint probe results. */
+export interface DoctorRuntimeEntry extends RuntimeProbeEntry {
+  endpoints?: DoctorRuntimeEndpoint[];
+}
+
 /** Input for the rendered doctor output. */
 export interface DoctorInput {
-  runtimes: RuntimeProbeEntry[];
+  runtimes: DoctorRuntimeEntry[];
   channels: ChannelProbeResult[];
 }
 
@@ -226,10 +251,32 @@ export function renderDoctor(input: DoctorInput): string {
   lines.push(
     `${pad("RUNTIME", widths.runtime)}  ${pad("NAME", widths.name)}  ${pad("STATUS", widths.status)}  ${pad("VERSION", widths.version)}  PATH`,
   );
-  for (const r of rows) {
+  for (let i = 0; i < rows.length; i += 1) {
+    const r = rows[i];
+    const e = input.runtimes[i];
     lines.push(
       `${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`,
     );
+    if (e.endpoints && e.endpoints.length > 0) {
+      for (const ep of e.endpoints) {
+        const mark = ep.reachable ? "✓" : "✗";
+        const detail = ep.reachable
+          ? ep.version ?? "ok"
+          : ep.error ?? "unreachable";
+        lines.push(`    gateway ${pad(`"${ep.name}"`, 16)} ${pad(ep.url, 40)} ${mark} ${detail}`);
+        if (ep.agents && ep.agents.length > 0) {
+          // RFC §3.8.4: list by `id` (stable key); show display name when distinct.
+          lines.push(
+            `      agents (id): ${ep.agents
+              .map((a) => (a.name && a.name !== a.id ? `${a.id} (${a.name})` : a.id))
+              .join(", ")}`,
+          );
+        }
+        if (ep.warnings) {
+          for (const w of ep.warnings) lines.push(`      WARN: ${w}`);
+        }
+      }
+    }
   }
   const available = input.runtimes.filter((e) => e.result.available).length;
   lines.push(`\n${available}/${input.runtimes.length} runtimes available`);