@botcord/daemon 0.2.77 → 0.2.79

package/src/gateway/types.ts

@@ -1,4 +1,20 @@
 import type { GatewayLogger } from "./log.js";
+import type {
+  GatewayInboundEnvelope as CanonicalGatewayInboundEnvelope,
+  GatewayInboundMessage as CanonicalGatewayInboundMessage,
+  GatewayOutboundAttachment as CanonicalGatewayOutboundAttachment,
+  GatewayOutboundMessage as CanonicalGatewayOutboundMessage,
+  RuntimeGatewayProvider,
+} from "@botcord/protocol-core";
+
+// Canonical gateway message shapes live in `@botcord/protocol-core` so the
+// `gateway-ingress` provider adapters can import the same types without
+// pulling the entire daemon. Daemon re-exports the canonical shapes here so
+// every existing import (`from "./gateway/index.js"`) keeps working.
+export type GatewayInboundMessage = CanonicalGatewayInboundMessage;
+export type GatewayInboundEnvelope = CanonicalGatewayInboundEnvelope;
+export type GatewayOutboundAttachment = CanonicalGatewayOutboundAttachment;
+export type GatewayOutboundMessage = CanonicalGatewayOutboundMessage;
 
 // ---------------------------------------------------------------------------
 // Routing (§9)
@@ -89,42 +105,9 @@ export interface GatewayConfig {
 // Inbound / outbound message shape (§7.3, §7.4, §7.5)
 // ---------------------------------------------------------------------------
 
-/** Normalized inbound message produced by a channel adapter for the dispatcher. */
-export interface GatewayInboundMessage {
-  id: string;
-  /** Channel adapter id (`ChannelAdapter.id`), not channel type. */
-  channel: string;
-  accountId: string;
-  conversation: {
-    id: string;
-    kind: "direct" | "group";
-    title?: string;
-    threadId?: string | null;
-  };
-  sender: {
-    id: string;
-    name?: string;
-    kind: "user" | "agent" | "system";
-  };
-  text?: string;
-  raw: unknown;
-  replyTo?: string | null;
-  mentioned?: boolean;
-  receivedAt: number;
-  trace?: {
-    id: string;
-    streamable?: boolean;
-  };
-}
-
-/** Inbound envelope wrapping a normalized message with optional upstream ack callbacks. */
-export interface GatewayInboundEnvelope {
-  message: GatewayInboundMessage;
-  ack?: {
-    accept(): Promise<void>;
-    reject?(reason: string): Promise<void>;
-  };
-}
+// `GatewayInboundMessage` and `GatewayInboundEnvelope` are re-exported from
+// `@botcord/protocol-core` at the top of this file. The wire-level subset is
+// `RuntimeGatewayInboundPayload` in protocol-core/runtime-frame.ts.
 
 /**
  * Channel-agnostic hook that produces a system-context string for a turn.
@@ -170,6 +153,15 @@ export type MemoryContextBuilder = (
   message: GatewayInboundMessage,
 ) => Promise<MemoryContextSnapshot | null | undefined> | MemoryContextSnapshot | null | undefined;
 
+/**
+ * Optional hook used after a runtime session is discarded and retried fresh.
+ * The daemon implementation can pull recent room messages from Hub; gateway
+ * core treats the returned string as opaque recovery context.
+ */
+export type RuntimeRecoveryContextBuilder = (
+  message: GatewayInboundMessage,
+) => Promise<string | null | undefined> | string | null | undefined;
+
 /**
  * Optional hook fired after the dispatcher dispatches a reply to a channel.
  * Intended for outbound bookkeeping (loop-risk tracking, metrics). Errors
@@ -179,28 +171,8 @@ export type OutboundObserver = (
   message: GatewayOutboundMessage,
 ) => Promise<void> | void;
 
-/** Outbound reply payload passed to `ChannelAdapter.send()`. */
-export interface GatewayOutboundAttachment {
-  /** Local daemon-readable file path. */
-  filePath?: string;
-  /** In-memory bytes, primarily for tests and in-process tool callers. */
-  data?: Uint8Array;
-  filename?: string;
-  contentType?: string;
-  kind?: "image" | "file" | "video";
-}
-
-export interface GatewayOutboundMessage {
-  channel: string;
-  accountId: string;
-  conversationId: string;
-  threadId?: string | null;
-  type?: "message" | "error";
-  text: string;
-  attachments?: GatewayOutboundAttachment[];
-  replyTo?: string | null;
-  traceId?: string | null;
-}
+// `GatewayOutboundAttachment` and `GatewayOutboundMessage` are re-exported from
+// `@botcord/protocol-core` at the top of this file.
 
 // ---------------------------------------------------------------------------
 // Status (§14)
@@ -218,7 +190,7 @@ export interface ChannelStatusSnapshot {
   lastStopAt?: number;
   lastError?: string | null;
   /** Third-party provider id when this channel is not the built-in BotCord. */
-  provider?: "wechat" | "telegram" | "feishu";
+  provider?: RuntimeGatewayProvider;
   /** Last time the adapter polled the upstream provider (ms epoch). */
   lastPollAt?: number;
   /** Last time the adapter accepted an inbound message (ms epoch). */

package/src/gateway-control.ts

@@ -313,13 +313,17 @@ export function createGatewayControl(ctx: GatewayControlContext) {
       if (!loginId) {
         return badParams("upsert_gateway: wechat requires loginId");
       }
-      const session = sessions.get(loginId);
-      if (!session) {
+      const resolved = sessions.resolve(loginId);
+      if (resolved.state !== "live") {
         return {
           ok: false,
-          error: { code: "login_expired", message: `wechat login session "${loginId}" not found or expired` },
+          error:
+            resolved.state === "missing"
+              ? { code: "login_missing", message: `wechat login session "${loginId}" not found` }
+              : { code: "login_expired", message: `wechat login session "${loginId}" expired` },
         };
       }
+      const session = resolved.session!;
       if (session.provider !== "wechat") {
         return badParams(`upsert_gateway: login session provider "${session.provider}" != "wechat"`);
       }
@@ -347,13 +351,17 @@ export function createGatewayControl(ctx: GatewayControlContext) {
       if (!loginId) {
         return badParams("upsert_gateway: feishu requires loginId");
       }
-      const session = sessions.get(loginId);
-      if (!session) {
+      const resolved = sessions.resolve(loginId);
+      if (resolved.state !== "live") {
         return {
           ok: false,
-          error: { code: "login_expired", message: `feishu login session "${loginId}" not found or expired` },
+          error:
+            resolved.state === "missing"
+              ? { code: "login_missing", message: `feishu login session "${loginId}" not found` }
+              : { code: "login_expired", message: `feishu login session "${loginId}" expired` },
         };
       }
+      const session = resolved.session!;
       if (session.provider !== "feishu") {
         return badParams(`upsert_gateway: login session provider "${session.provider}" != "feishu"`);
       }
@@ -869,13 +877,17 @@ export function createGatewayControl(ctx: GatewayControlContext) {
     if (!params.accountId || typeof params.accountId !== "string") {
       return badParams("gateway_recent_senders: accountId is required");
     }
-    const session = sessions.get(params.loginId);
-    if (!session) {
+    const resolved = sessions.resolve(params.loginId);
+    if (resolved.state !== "live") {
       return {
         ok: false,
-        error: { code: "login_expired", message: `wechat login session "${params.loginId}" not found or expired` },
+        error:
+          resolved.state === "missing"
+            ? { code: "login_missing", message: `wechat login session "${params.loginId}" not found` }
+            : { code: "login_expired", message: `wechat login session "${params.loginId}" expired` },
       };
     }
+    const session = resolved.session!;
     if (session.provider !== "wechat") {
       return badParams("gateway_recent_senders: provider does not match login session");
     }

package/src/provision.ts

@@ -26,6 +26,7 @@ import {
   type RuntimeProbeResult,
   type StoredBotCordCredentials,
   type UpdateAgentParams,
+  type GatewayInboundFrame,
 } from "@botcord/protocol-core";
 import type { Gateway } from "./gateway/index.js";
 import type { GatewayInboundMessage } from "./gateway/index.js";
@@ -72,6 +73,12 @@ import {
 import { log as daemonLog } from "./log.js";
 import { discoverAgentCredentials } from "./agent-discovery.js";
 import { resolveMemoryDir } from "./working-memory.js";
+import { discoverRuntimeModelCatalog } from "./runtime-models.js";
+import {
+  buildRuntimeSelectionExtraArgs,
+  mergeRuntimeExtraArgs,
+} from "./runtime-route-options.js";
+import { handleCloudGatewayRuntimeInbound } from "./cloud-gateway-runtime.js";
 
 /**
  * Information passed to {@link OnAgentInstalledHook} after a successful
@@ -159,7 +166,7 @@ export function createProvisioner(opts: ProvisionerOptions): (
 
       case CONTROL_FRAME_TYPES.HELLO: {
         const params = (frame.params ?? {}) as unknown as HelloParams;
-        const result = applyHelloIdentitySnapshot(params.agents);
+        const result = applyHelloIdentitySnapshot(params.agents, { gateway });
         daemonLog.debug("hello: identity snapshot applied", {
           frameId: frame.id,
           received: params.agents?.length ?? 0,
@@ -181,12 +188,19 @@ export function createProvisioner(opts: ProvisionerOptions): (
           displayName: params.displayName,
           bio: params.bio,
         });
+        const runtimeResult = applyAgentRuntimeSnapshot(params, { gateway });
+        const combined = {
+          changed: result.changed || runtimeResult.changed,
+          identity: result,
+          runtime: runtimeResult,
+        };
         daemonLog.info("update_agent applied", {
           agentId: params.agentId,
-          changed: result.changed,
-          skipped: result.skipped ?? null,
+          changed: combined.changed,
+          identitySkipped: result.skipped ?? null,
+          runtimeSkipped: runtimeResult.skipped ?? null,
         });
-        return { ok: true, result };
+        return { ok: true, result: combined };
       }
 
       case CONTROL_FRAME_TYPES.PROVISION_AGENT: {
@@ -414,6 +428,31 @@ export function createProvisioner(opts: ProvisionerOptions): (
         );
       }
 
+      case "cloud_gateway_runtime_inbound": {
+        const params = (frame.params ?? {}) as { frame?: unknown };
+        const runtimeFrame = params.frame as GatewayInboundFrame | undefined;
+        if (!runtimeFrame || typeof runtimeFrame !== "object") {
+          return {
+            ok: false,
+            error: {
+              code: "bad_params",
+              message: "cloud_gateway_runtime_inbound requires params.frame",
+            },
+          };
+        }
+        const result = await handleCloudGatewayRuntimeInbound(gateway, runtimeFrame);
+        return result.accepted
+          ? { ok: true, result }
+          : {
+              ok: false,
+              result,
+              error: result.error ?? {
+                code: "runtime_inbound_rejected",
+                message: "cloud gateway runtime inbound was rejected",
+              },
+            };
+      }
+
       case "list_agent_files": {
         const params = (frame.params ?? {}) as unknown as ListAgentFilesParams;
         if (!params.agentId) {
@@ -1057,6 +1096,11 @@ function upsertManagedRouteForCredentials(
     runtime: credentials.runtime ?? cfg.defaultRoute.adapter,
     cwd: credentials.cwd ?? agentWorkspaceDir(credentials.agentId),
   };
+  const extraArgs = mergeRuntimeExtraArgs(
+    cfg.defaultRoute.extraArgs,
+    buildRuntimeSelectionExtraArgs(synthRoute.runtime, credentials),
+  );
+  if (extraArgs) synthRoute.extraArgs = extraArgs;
   if (synthRoute.runtime === "openclaw-acp") {
     const profile = (cfg.openclawGateways ?? []).find(
       (g) => g.name === credentials.openclawGateway,
@@ -1169,6 +1213,10 @@ async function materializeCredentials(
     if (c.token) record.token = c.token;
     if (typeof c.tokenExpiresAt === "number") record.tokenExpiresAt = c.tokenExpiresAt;
     if (runtime) record.runtime = runtime;
+    const runtimeSelection = pickRuntimeSelection(params);
+    if (runtimeSelection.runtimeModel) record.runtimeModel = runtimeSelection.runtimeModel;
+    if (runtimeSelection.reasoningEffort) record.reasoningEffort = runtimeSelection.reasoningEffort;
+    if (typeof runtimeSelection.thinking === "boolean") record.thinking = runtimeSelection.thinking;
     record.cwd = cwd;
     const openclawSel = pickOpenclawSelection(params);
     if (openclawSel.gateway) record.openclawGateway = openclawSel.gateway;
@@ -1203,6 +1251,10 @@ async function materializeCredentials(
     tokenExpiresAt: reg.expiresAt,
   };
   if (runtime) record.runtime = runtime;
+  const runtimeSelection = pickRuntimeSelection(params);
+  if (runtimeSelection.runtimeModel) record.runtimeModel = runtimeSelection.runtimeModel;
+  if (runtimeSelection.reasoningEffort) record.reasoningEffort = runtimeSelection.reasoningEffort;
+  if (typeof runtimeSelection.thinking === "boolean") record.thinking = runtimeSelection.thinking;
   record.cwd = cwd;
   const openclawSel = pickOpenclawSelection(params);
   if (openclawSel.gateway) record.openclawGateway = openclawSel.gateway;
@@ -1784,6 +1836,10 @@ export function collectRuntimeSnapshot(opts: { force?: boolean } = {}): ListRunt
     // style used above.
     if (entry.result.version) record.version = entry.result.version;
     if (entry.result.path) record.path = entry.result.path;
+    const catalog = discoverRuntimeModelCatalog(entry);
+    const models = catalog.models;
+    if (models?.length) record.models = models.slice(0, RUNTIME_MODELS_CAP);
+    if (catalog.parameters?.length) record.parameters = catalog.parameters.slice(0, RUNTIME_PARAMETERS_CAP);
     // 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
@@ -1841,6 +1897,8 @@ export function attachRuntimeHealth(
 
 /** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
 export const RUNTIME_ENDPOINTS_CAP = 32;
+export const RUNTIME_MODELS_CAP = 128;
+export const RUNTIME_PARAMETERS_CAP = 64;
 
 /** Injection seam for L2 + L3 endpoint probes — kept testable + side-effect-free. */
 export type WsEndpointProbeFn = (args: {
@@ -2386,10 +2444,100 @@ interface HelloIdentityResult {
   skipped: number;
 }
 
+interface RuntimeSnapshotResult {
+  changed: boolean;
+  skipped?: string;
+  routeUpdated?: boolean;
+}
+
+interface RuntimeSnapshotCtx {
+  gateway?: Gateway;
+}
+
+function hasOwnField(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function cleanNullableString(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function applyAgentRuntimeSnapshot(
+  snapshot: AgentIdentitySnapshot,
+  ctx: RuntimeSnapshotCtx = {},
+): RuntimeSnapshotResult {
+  const hasRuntimeFields = (
+    hasOwnField(snapshot, "runtime") ||
+    hasOwnField(snapshot, "runtimeModel") ||
+    hasOwnField(snapshot, "reasoningEffort") ||
+    hasOwnField(snapshot, "thinking")
+  );
+  if (!hasRuntimeFields) return { changed: false, skipped: "no_runtime_fields" };
+
+  const credentialsFile = defaultCredentialsFile(snapshot.agentId);
+  if (!existsSync(credentialsFile)) {
+    return { changed: false, skipped: "credentials_missing" };
+  }
+
+  const credentials = loadStoredCredentials(credentialsFile);
+  let changed = false;
+
+  if (hasOwnField(snapshot, "runtime")) {
+    const runtime = cleanNullableString(snapshot.runtime);
+    if (runtime !== credentials.runtime) {
+      if (runtime) credentials.runtime = runtime;
+      else delete credentials.runtime;
+      changed = true;
+    }
+  }
+
+  if (hasOwnField(snapshot, "runtimeModel")) {
+    const runtimeModel = cleanNullableString(snapshot.runtimeModel);
+    if (runtimeModel !== credentials.runtimeModel) {
+      if (runtimeModel) credentials.runtimeModel = runtimeModel;
+      else delete credentials.runtimeModel;
+      changed = true;
+    }
+  }
+
+  if (hasOwnField(snapshot, "reasoningEffort")) {
+    const reasoningEffort = cleanNullableString(snapshot.reasoningEffort);
+    if (reasoningEffort !== credentials.reasoningEffort) {
+      if (reasoningEffort) credentials.reasoningEffort = reasoningEffort;
+      else delete credentials.reasoningEffort;
+      changed = true;
+    }
+  }
+
+  if (hasOwnField(snapshot, "thinking")) {
+    if (typeof snapshot.thinking === "boolean") {
+      if (credentials.thinking !== snapshot.thinking) {
+        credentials.thinking = snapshot.thinking;
+        changed = true;
+      }
+    } else if (typeof credentials.thinking === "boolean") {
+      delete credentials.thinking;
+      changed = true;
+    }
+  }
+
+  if (!changed) return { changed: false };
+
+  writeCredentialsFile(credentialsFile, credentials);
+  if (ctx.gateway) {
+    upsertManagedRouteForCredentials(credentials, loadConfig(), ctx.gateway);
+    return { changed: true, routeUpdated: true };
+  }
+  return { changed: true };
+}
+
 /**
  * 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.
+ * against the on-disk `identity.md` and credentials runtime selectors.
+ * 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
@@ -2399,6 +2547,7 @@ interface HelloIdentityResult {
  */
 export function applyHelloIdentitySnapshot(
   snapshot: AgentIdentitySnapshot[] | undefined,
+  ctx: RuntimeSnapshotCtx = {},
 ): HelloIdentityResult {
   const out: HelloIdentityResult = { updated: 0, skipped: 0 };
   if (!Array.isArray(snapshot)) return out;
@@ -2412,7 +2561,8 @@ export function applyHelloIdentitySnapshot(
         displayName: entry.displayName,
         bio: entry.bio,
       });
-      if (result.changed) out.updated += 1;
+      const runtimeResult = applyAgentRuntimeSnapshot(entry, ctx);
+      if (result.changed || runtimeResult.changed) out.updated += 1;
       else out.skipped += 1;
     } catch (err) {
       out.skipped += 1;
@@ -2511,20 +2661,34 @@ export async function reloadConfig(ctx: { gateway: Gateway }): Promise<ReloadRes
  */
 function readAgentRuntimesFromCredentials(
   agentIds: string[],
-): Record<string, { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string; hermesProfile?: string }> {
-  const out: Record<string, { runtime?: string; cwd?: string; openclawGateway?: string; openclawAgent?: string; hermesProfile?: string }> = {};
+): Record<string, { runtime?: string; runtimeModel?: string; reasoningEffort?: string; thinking?: boolean; cwd?: string; openclawGateway?: string; openclawAgent?: string; hermesProfile?: string }> {
+  const out: Record<string, { runtime?: string; runtimeModel?: string; reasoningEffort?: string; thinking?: boolean; cwd?: string; openclawGateway?: string; openclawAgent?: string; hermesProfile?: 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; openclawGateway?: string; openclawAgent?: string; hermesProfile?: string } = {};
+      const entry: { runtime?: string; runtimeModel?: string; reasoningEffort?: string; thinking?: boolean; cwd?: string; openclawGateway?: string; openclawAgent?: string; hermesProfile?: string } = {};
       if (creds.runtime) entry.runtime = creds.runtime;
+      if (creds.runtimeModel) entry.runtimeModel = creds.runtimeModel;
+      if (creds.reasoningEffort) entry.reasoningEffort = creds.reasoningEffort;
+      if (typeof creds.thinking === "boolean") entry.thinking = creds.thinking;
       if (creds.cwd) entry.cwd = creds.cwd;
       if (creds.openclawGateway) entry.openclawGateway = creds.openclawGateway;
       if (creds.openclawAgent) entry.openclawAgent = creds.openclawAgent;
       if (creds.hermesProfile) entry.hermesProfile = creds.hermesProfile;
-      if (entry.runtime || entry.cwd || entry.openclawGateway || entry.openclawAgent || entry.hermesProfile) out[id] = entry;
+      if (
+        entry.runtime ||
+        entry.runtimeModel ||
+        entry.reasoningEffort ||
+        typeof entry.thinking === "boolean" ||
+        entry.cwd ||
+        entry.openclawGateway ||
+        entry.openclawAgent ||
+        entry.hermesProfile
+      ) {
+        out[id] = entry;
+      }
     } catch {
       // best-effort — skip agents with unreadable credentials
     }
@@ -2769,6 +2933,33 @@ function pickRuntime(params: ProvisionAgentParams): string | undefined {
   return undefined;
 }
 
+function pickRuntimeSelection(
+  params: ProvisionAgentParams,
+): { runtimeModel?: string; reasoningEffort?: string; thinking?: boolean } {
+  const out: { runtimeModel?: string; reasoningEffort?: string; thinking?: boolean } = {};
+  const runtimeModel = pickString(params.runtimeModel, params.credentials?.runtimeModel);
+  const reasoningEffort = pickString(
+    params.reasoningEffort,
+    params.credentials?.reasoningEffort,
+  );
+  if (runtimeModel) out.runtimeModel = runtimeModel;
+  if (reasoningEffort) out.reasoningEffort = reasoningEffort;
+  if (typeof params.thinking === "boolean") {
+    out.thinking = params.thinking;
+  } else if (typeof params.credentials?.thinking === "boolean") {
+    out.thinking = params.credentials.thinking;
+  }
+  return out;
+}
+
+function pickString(...values: Array<string | undefined>): string | undefined {
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (trimmed) return trimmed;
+  }
+  return undefined;
+}
+
 function assertKnownRuntime(runtime: string): void {
   const mod = getAdapterModule(runtime);
   if (!mod) {

package/src/room-recovery-context.ts

@@ -0,0 +1,131 @@
+/**
+ * Build a compact, deterministic recovery block from recent Hub room messages.
+ * Used when a runtime-native session is discarded and the same turn is retried
+ * in a fresh session.
+ */
+import { BotCordClient, loadStoredCredentials } from "@botcord/protocol-core";
+import { sanitizeUntrustedContent } from "./gateway/index.js";
+import type { GatewayInboundMessage } from "./gateway/index.js";
+
+interface CachedClient {
+  client: BotCordClient;
+  credentialsPath: string;
+}
+
+export interface RecentRoomMessagesRecoveryOptions {
+  credentialPathByAgentId: Map<string, string>;
+  defaultCredentialsPath?: string;
+  hubBaseUrl?: string;
+  limit?: number;
+  log?: {
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+  };
+}
+
+interface RoomMessage {
+  from?: string;
+  from_name?: string;
+  text?: string;
+  type?: string;
+  ts?: string;
+  topic_id?: string | null;
+  topic_title?: string | null;
+}
+
+const DEFAULT_RECENT_LIMIT = 20;
+const MAX_MESSAGE_TEXT_CHARS = 1200;
+
+function stripNewlines(s: string): string {
+  return s.replace(/[\r\n]+/g, " ");
+}
+
+function messageLabel(m: RoomMessage): string {
+  const name = typeof m.from_name === "string" && m.from_name.trim()
+    ? m.from_name
+    : typeof m.from === "string" && m.from.trim()
+      ? m.from
+      : "unknown";
+  return sanitizeUntrustedContent(stripNewlines(name));
+}
+
+function formatRecentMessages(messages: RoomMessage[]): string {
+  if (messages.length === 0) return "[Recent Room Messages]\n(none)";
+  const chronological = [...messages].reverse();
+  const lines = ["[Recent Room Messages]"];
+  for (const m of chronological) {
+    const text = typeof m.text === "string" ? m.text.trim() : "";
+    if (!text) continue;
+    const ts = typeof m.ts === "string" ? m.ts : "";
+    const topic = typeof m.topic_title === "string" && m.topic_title.trim()
+      ? ` topic=${sanitizeUntrustedContent(stripNewlines(m.topic_title))}`
+      : typeof m.topic_id === "string" && m.topic_id
+        ? ` topic=${sanitizeUntrustedContent(stripNewlines(m.topic_id))}`
+        : "";
+    const safeText = sanitizeUntrustedContent(
+      text.length > MAX_MESSAGE_TEXT_CHARS
+        ? `${text.slice(0, MAX_MESSAGE_TEXT_CHARS)}...`
+        : text,
+    );
+    lines.push(`- ${ts ? `${ts} ` : ""}${messageLabel(m)}${topic}: ${safeText}`);
+  }
+  return lines.join("\n");
+}
+
+export function createRecentRoomMessagesRecoveryBuilder(
+  opts: RecentRoomMessagesRecoveryOptions,
+): (message: GatewayInboundMessage) => Promise<string | null> {
+  const clients = new Map<string, CachedClient>();
+  const limit = opts.limit ?? DEFAULT_RECENT_LIMIT;
+
+  function getClient(accountId: string): BotCordClient | null {
+    const existing = clients.get(accountId);
+    if (existing) return existing.client;
+
+    const credsPath =
+      opts.credentialPathByAgentId.get(accountId) ?? opts.defaultCredentialsPath;
+    if (!credsPath) {
+      opts.log?.warn("daemon.recovery-context.no-credentials", { accountId });
+      return null;
+    }
+
+    try {
+      const creds = loadStoredCredentials(credsPath);
+      const client = new BotCordClient({
+        hubUrl: opts.hubBaseUrl ?? creds.hubUrl,
+        agentId: creds.agentId,
+        keyId: creds.keyId,
+        privateKey: creds.privateKey,
+        ...(creds.token ? { token: creds.token } : {}),
+        ...(creds.tokenExpiresAt !== undefined
+          ? { tokenExpiresAt: creds.tokenExpiresAt }
+          : {}),
+      });
+      clients.set(accountId, { client, credentialsPath: credsPath });
+      return client;
+    } catch (err) {
+      opts.log?.warn("daemon.recovery-context.client-init-failed", {
+        accountId,
+        credsPath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  }
+
+  return async (message) => {
+    const client = getClient(message.accountId);
+    if (!client) return null;
+    try {
+      const body = await client.roomMessages(message.conversation.id, { limit });
+      const messages = Array.isArray(body?.messages) ? body.messages as RoomMessage[] : [];
+      return formatRecentMessages(messages);
+    } catch (err) {
+      opts.log?.warn("daemon.recovery-context.fetch-failed", {
+        accountId: message.accountId,
+        roomId: message.conversation.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  };
+}