@botcord/daemon 0.2.78 → 0.2.80

package/src/gateway/channels/text-split.ts

@@ -1,29 +1,7 @@
 /**
- * Split a long message into chunks <= `limit` characters each. Prefers to cut
- * on newline boundaries so multi-paragraph replies don't fragment mid-line.
- *
- * Shared by third-party channel adapters (Telegram, WeChat) which both have a
- * per-message size cap from upstream and no native streaming. WeChat caller
- * passes a smaller `limit` (~1800), Telegram a larger one (~4000, since the
- * raw Telegram limit is 4096).
- *
- * Empty input returns `[""]` so callers can iterate uniformly without a length
- * check.
+ * Thin re-export — `splitText` lives in `@botcord/protocol-core` so the
+ * daemon channel adapters and the `gateway-ingress` provider adapters use
+ * one canonical implementation. Existing imports of this module keep
+ * working unchanged.
  */
-export function splitText(text: string, limit: number): string[] {
-  if (limit <= 0) return [text];
-  if (text.length === 0) return [""];
-  if (text.length <= limit) return [text];
-
-  const out: string[] = [];
-  let remaining = text;
-  while (remaining.length > limit) {
-    let cut = remaining.lastIndexOf("\n", limit);
-    if (cut <= 0) cut = limit;
-    out.push(remaining.slice(0, cut));
-    // Drop the leading newline so the next chunk doesn't start with a blank line.
-    remaining = remaining.slice(cut).replace(/^\n/, "");
-  }
-  if (remaining.length > 0) out.push(remaining);
-  return out;
-}
+export { splitText } from "@botcord/protocol-core";

package/src/gateway/dispatcher.ts

@@ -23,6 +23,7 @@ import type {
   OutboundObserver,
   QueueMode,
   RuntimeAdapter,
+  RuntimeRecoveryContextBuilder,
   RuntimeRunResult,
   RuntimeCircuitBreakerSnapshot,
   RuntimeStatusEvent,
@@ -182,6 +183,31 @@ function extractCloudRunBudget(msg: GatewayInboundMessage): CloudRunBudgetCaps |
   return out.maxWallTimeMs !== undefined || out.maxToolCalls !== undefined ? out : undefined;
 }
 
+function looksLikeRecoverableSessionFailure(error: string): boolean {
+  return /compact|compaction|context|token limit|maximum context|too many tokens|conversation found|session .*not found|resume/i
+    .test(error);
+}
+
+function buildRuntimeRecoveryPrompt(args: {
+  userTurn: string;
+  error: string;
+  recoveryContext?: string | null;
+}): string {
+  return [
+    "[BotCord Runtime Recovery Notice]",
+    "The previous Codex runtime session for this room became unrecoverable while resuming or compacting context.",
+    `Previous runtime error: ${truncate(args.error, 1000)}`,
+    "You are now running in a fresh Codex session.",
+    "Use the recent room messages below, current filesystem state, and available BotCord memory/context tools to reconstruct the active task.",
+    "Continue the original user request without asking the user to repeat information unless it is missing from those sources.",
+    "",
+    args.recoveryContext?.trim() || "[Recent Room Messages]\n(unavailable)",
+    "",
+    "[Current User Turn]",
+    args.userTurn,
+  ].join("\n");
+}
+
 /** Factory signature for building a runtime adapter at turn dispatch time. */
 export type RuntimeFactory = (
   runtimeId: string,
@@ -217,6 +243,11 @@ export interface DispatcherOptions {
    * keep following stale memory.
    */
   buildMemoryContext?: MemoryContextBuilder;
+  /**
+   * Optional hook that returns recent room context for a fresh-session retry
+   * after a runtime resume session becomes unrecoverable.
+   */
+  buildRuntimeRecoveryContext?: RuntimeRecoveryContextBuilder;
   /**
    * Optional side-effect hook invoked after ack, before the turn runs.
    * Intended for bookkeeping (e.g. activity tracking). Errors are logged
@@ -381,6 +412,7 @@ export class Dispatcher {
   private readonly runtimeAuthFailureCooldownMs: number;
   private readonly buildSystemContext?: SystemContextBuilder;
   private readonly buildMemoryContext?: MemoryContextBuilder;
+  private readonly buildRuntimeRecoveryContext?: RuntimeRecoveryContextBuilder;
   private readonly onInbound?: InboundObserver;
   private readonly onOutbound?: OutboundObserver;
   private readonly onTurnComplete?: DispatcherOptions["onTurnComplete"];
@@ -415,6 +447,7 @@ export class Dispatcher {
       opts.runtimeAuthFailureCooldownMs ?? DEFAULT_RUNTIME_AUTH_FAILURE_COOLDOWN_MS;
     this.buildSystemContext = opts.buildSystemContext;
     this.buildMemoryContext = opts.buildMemoryContext;
+    this.buildRuntimeRecoveryContext = opts.buildRuntimeRecoveryContext;
     this.onInbound = opts.onInbound;
     this.onOutbound = opts.onOutbound;
     this.onTurnComplete = opts.onTurnComplete;
@@ -1604,33 +1637,96 @@ export class Dispatcher {
     const runtime = this.runtimeFactory(route.runtime, route.extraArgs);
     let result: RuntimeRunResult | undefined;
     let threw: unknown;
+    let activeSessionId: string | null = sessionId;
     const turnStartedAt = Date.now();
     try {
       try {
-        result = await runtime.run({
-          text: runtimeText,
-          sessionId,
-          cwd: route.cwd,
-          accountId: msg.accountId,
-          hubUrl: this.resolveHubUrl?.(msg.accountId),
-          extraArgs: route.extraArgs,
-          signal: controller.signal,
-          trustLevel,
-          systemContext,
-          onBlock,
-          onStatus,
-          context: {
-            turnId,
-            messageId: msg.id,
+        const runRuntime = (textForRun: string, sessionIdForRun: string | null) =>
+          runtime.run({
+            text: textForRun,
+            sessionId: sessionIdForRun,
+            cwd: route.cwd,
+            accountId: msg.accountId,
+            hubUrl: this.resolveHubUrl?.(msg.accountId),
+            extraArgs: route.extraArgs,
+            signal: controller.signal,
+            trustLevel,
+            systemContext,
+            onBlock,
+            onStatus,
+            context: {
+              turnId,
+              messageId: msg.id,
+              roomId: msg.conversation.id,
+              topicId: msg.conversation.threadId ?? null,
+              channel: msg.channel,
+              conversationKind: msg.conversation.kind,
+            },
+            ...(cloudRunBudget ? { budget: cloudRunBudget } : {}),
+            gateway: route.gateway,
+            ...(route.hermesProfile ? { hermesProfile: route.hermesProfile } : {}),
+          });
+
+        result = await runRuntime(runtimeText, sessionId);
+        const firstError = result.error ?? "";
+        const firstReply = (result.text || "").trim();
+        const shouldRetryFresh =
+          route.runtime === "codex" &&
+          !!sessionId &&
+          !!firstError &&
+          !firstReply &&
+          !looksLikeRuntimeAuthFailure(firstError) &&
+          looksLikeRecoverableSessionFailure(firstError) &&
+          !controller.signal.aborted &&
+          !slot.timedOut &&
+          !slot.budgetExceeded;
+
+        if (shouldRetryFresh) {
+          try {
+            await this.sessionStore.delete(key);
+            this.log.info("dispatcher: dropped unrecoverable runtime session before fresh retry", {
+              key,
+              prevRuntimeSessionId: sessionId,
+              runtime: route.runtime,
+              error: firstError,
+            });
+          } catch (err) {
+            this.log.warn("dispatcher: session-store.delete failed before fresh retry", {
+              key,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+
+          let recoveryContext: string | null | undefined;
+          if (this.buildRuntimeRecoveryContext) {
+            try {
+              recoveryContext = await this.buildRuntimeRecoveryContext(msg);
+            } catch (err) {
+              this.log.warn("dispatcher: buildRuntimeRecoveryContext threw — retrying without recent room context", {
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                turnId,
+                error: err instanceof Error ? err.message : String(err),
+              });
+            }
+          }
+
+          activeSessionId = null;
+          runtimeText = buildRuntimeRecoveryPrompt({
+            userTurn: text,
+            error: firstError,
+            recoveryContext,
+          });
+          this.log.info("dispatcher: retrying codex turn in a fresh session with recovery context", {
+            agentId: msg.accountId,
             roomId: msg.conversation.id,
             topicId: msg.conversation.threadId ?? null,
-            channel: msg.channel,
-            conversationKind: msg.conversation.kind,
-          },
-          ...(cloudRunBudget ? { budget: cloudRunBudget } : {}),
-          gateway: route.gateway,
-          ...(route.hermesProfile ? { hermesProfile: route.hermesProfile } : {}),
-        });
+            turnId,
+            queueKey,
+          });
+          result = await runRuntime(runtimeText, null);
+        }
       } catch (err) {
         threw = err;
       } finally {
@@ -1814,12 +1910,12 @@ export class Dispatcher {
       //                                 even when the adapter echoes that id back
       //   result.newSessionId truthy  → upsert the entry
       //   otherwise                   → no-op (e.g. codex intentionally never persists)
-      if (sessionId && effectiveError && !replyText) {
+      if (activeSessionId && effectiveError && !replyText) {
         try {
           await this.sessionStore.delete(key);
           this.log.info("dispatcher: dropped stale runtime session", {
             key,
-            prevRuntimeSessionId: sessionId,
+            prevRuntimeSessionId: activeSessionId,
             nextRuntimeSessionId: result.newSessionId || null,
             error: effectiveError,
           });
@@ -1844,7 +1940,7 @@ export class Dispatcher {
           updatedAt: Date.now(),
         };
         try {
-          const prevRuntimeSessionId = sessionId;
+          const prevRuntimeSessionId = activeSessionId;
           await this.sessionStore.set(session);
           this.log.debug("dispatcher: persisted runtime session", {
             key,
@@ -1857,12 +1953,12 @@ export class Dispatcher {
             error: err instanceof Error ? err.message : String(err),
           });
         }
-      } else if (sessionId && effectiveError) {
+      } else if (activeSessionId && effectiveError) {
         try {
           await this.sessionStore.delete(key);
           this.log.info("dispatcher: dropped stale runtime session", {
             key,
-            prevRuntimeSessionId: sessionId,
+            prevRuntimeSessionId: activeSessionId,
             error: effectiveError,
           });
         } catch (err) {

package/src/gateway/gateway.ts

@@ -23,6 +23,7 @@ import type {
   InboundObserver,
   MemoryContextBuilder,
   OutboundObserver,
+  RuntimeRecoveryContextBuilder,
   SystemContextBuilder,
   UserTurnBuilder,
 } from "./types.js";
@@ -49,6 +50,11 @@ export interface GatewayBootOptions {
    * resumed runtime sessions get an explicit prompt when memory changes.
    */
   buildMemoryContext?: MemoryContextBuilder;
+  /**
+   * Recent room context provider used by dispatcher when it must discard a
+   * broken runtime session and retry the same turn in a fresh session.
+   */
+  buildRuntimeRecoveryContext?: RuntimeRecoveryContextBuilder;
   /**
    * Observer called after the dispatcher acks each inbound message. Useful
    * for activity tracking or metrics. Errors are logged and swallowed.
@@ -178,6 +184,7 @@ export class Gateway {
       turnTimeoutMs: opts.turnTimeoutMs,
       buildSystemContext: opts.buildSystemContext,
       buildMemoryContext: opts.buildMemoryContext,
+      buildRuntimeRecoveryContext: opts.buildRuntimeRecoveryContext,
       onInbound: opts.onInbound,
       composeUserTurn: opts.composeUserTurn,
       onOutbound: opts.onOutbound,
@@ -295,6 +302,28 @@ export class Gateway {
     await this.dispatcher.handle({ message });
   }
 
+  /**
+   * Inject an inbound message while routing replies through a caller-owned
+   * channel adapter. Cloud gateway runtime sessions use this to execute a
+   * provider message without loading provider credentials inside the sandbox:
+   * the temporary adapter captures the runtime's final reply and the always-on
+   * ingress service performs the provider send.
+   */
+  async injectInboundThrough(
+    message: GatewayInboundMessage,
+    channel: ChannelAdapter,
+    ack?: { accept: () => Promise<void> },
+  ): Promise<void> {
+    const previous = this.channelMap.get(channel.id);
+    this.channelMap.set(channel.id, channel);
+    try {
+      await this.dispatcher.handle({ message, ...(ack ? { ack } : {}) });
+    } finally {
+      if (previous) this.channelMap.set(channel.id, previous);
+      else this.channelMap.delete(channel.id);
+    }
+  }
+
   /**
    * Send a daemon-control initiated outbound message through a registered
    * channel. Used by proactive third-party gateway sends where the runtime

package/src/gateway/policy-resolver.ts

@@ -65,20 +65,31 @@ const DEFAULT_TTL_MS = 5 * 60 * 1000;
 const FETCH_FAILED = Symbol("fetch_failed");
 
 /**
- * Force DM rooms (`rm_dm_*`) to `mode: "always"` per design §4.2 — UI never
+ * Force direct conversations to `mode: "always"` per design §4.2 — UI never
  * lets the user mute a DM, but a stale cache from before a UX bug is cheap
- * to defend against here.
+ * to defend against here. Third-party 1:1 gateway chats have the same
+ * expectation: they do not carry BotCord mention metadata, so applying a
+ * global mention-only policy would silently drop ordinary direct messages.
  */
-function maybeForceDm(
+function maybeForceDirectConversation(
   roomId: string | null,
   policy: DaemonAttentionPolicy,
 ): DaemonAttentionPolicy {
-  if (roomId && roomId.startsWith("rm_dm_") && policy.mode !== "always") {
+  if (roomId && isDirectConversation(roomId) && policy.mode !== "always") {
     return { ...policy, mode: "always" };
   }
   return policy;
 }
 
+function isDirectConversation(roomId: string): boolean {
+  return (
+    roomId.startsWith("rm_dm_") ||
+    roomId.startsWith("telegram:user:") ||
+    roomId.startsWith("wechat:user:") ||
+    roomId.startsWith("feishu:user:")
+  );
+}
+
 function defaultPolicy(): DaemonAttentionPolicy {
   return { mode: "always", keywords: [] };
 }
@@ -115,10 +126,10 @@ export class PolicyResolver implements PolicyResolverLike {
       if (fetched === FETCH_FAILED) return defaultPolicy();
       const policy = fetched ?? defaultPolicy();
       this.cache.set(cacheKey(agentId, roomId), {
-        policy: maybeForceDm(roomId, policy),
+        policy: maybeForceDirectConversation(roomId, policy),
         expiresAt: now + this.ttlMs,
       });
-      return maybeForceDm(roomId, policy);
+      return maybeForceDirectConversation(roomId, policy);
     }
 
     // 3. No room override known — inherit from the cached agent-wide global.
@@ -128,7 +139,7 @@ export class PolicyResolver implements PolicyResolverLike {
     const globalKey = cacheKey(agentId, null);
     const globalHit = this.cache.get(globalKey);
     if (globalHit && globalHit.expiresAt > now) {
-      return maybeForceDm(roomId, globalHit.policy);
+      return maybeForceDirectConversation(roomId, globalHit.policy);
     }
 
     // 4. Cold start for global.
@@ -136,7 +147,7 @@ export class PolicyResolver implements PolicyResolverLike {
     if (fetched === FETCH_FAILED) return defaultPolicy();
     const policy = fetched ?? defaultPolicy();
     this.cache.set(globalKey, { policy, expiresAt: now + this.ttlMs });
-    return maybeForceDm(roomId, policy);
+    return maybeForceDirectConversation(roomId, policy);
   }
 
   private async safeFetch(
@@ -168,7 +179,7 @@ export class PolicyResolver implements PolicyResolverLike {
   put(agentId: string, roomId: string | null, policy: DaemonAttentionPolicy): void {
     const key = cacheKey(agentId, roomId);
     this.cache.set(key, {
-      policy: maybeForceDm(roomId, policy),
+      policy: maybeForceDirectConversation(roomId, policy),
       expiresAt: Date.now() + this.ttlMs,
     });
   }

package/src/gateway/runtimes/deepseek-tui.ts

@@ -143,11 +143,14 @@ export class DeepseekTuiAdapter implements RuntimeAdapter {
         signal: turnAbort.signal,
       });
       const text = runResult.text;
+      const error =
+        runResult.error ??
+        (text === "" ? emptyCompletionError(handle.stderrTail) : undefined);
 
       return {
         text,
         newSessionId: threadId,
-        ...(runResult.error ? { error: runResult.error } : {}),
+        ...(error ? { error } : {}),
       };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -383,13 +386,18 @@ export class DeepseekTuiAdapter implements RuntimeAdapter {
         if (extractedError) errorText = extractedError;
         if (eventName === "message.delta") {
           append(stringField(payload, "content") ?? "");
-        } else if (eventName === "item.delta" && payload?.payload?.kind === "agent_message") {
-          append(stringField(payload.payload, "delta") ?? "");
+        } else if (eventName === "item.delta" && isAgentMessageDelta(payload)) {
+          append(extractDeepseekDelta(payload));
         }
         if (eventName === "turn.started" || embeddedDeepseekEvent(payload) === "turn.started") {
           opts.onStatus?.({ kind: "thinking", phase: "started", label: "Thinking" });
-        } else if (eventName === "tool.started" || isToolStarted(payload)) {
-          const label = stringField(payload, "name") ?? stringField(payload?.payload?.tool, "name") ?? "tool";
+        } else if (eventName === "tool.started" || isToolStarted(eventName, payload)) {
+          const label =
+            stringField(payload, "name") ??
+            stringField(payload?.tool, "name") ??
+            stringField(payload?.payload?.tool, "name") ??
+            inferDeepseekToolName(payload?.item ?? payload?.payload?.item) ??
+            "tool";
           opts.onStatus?.({ kind: "thinking", phase: "updated", label });
         } else if (isDeepseekTerminalEvent(eventName, payload)) {
           opts.onStatus?.({ kind: "thinking", phase: "stopped" });
@@ -449,15 +457,18 @@ function normalizeDeepseekEvent(eventName: string, payload: any, seq: number): S
   if (eventName === "message.delta") {
     return { raw: { event: eventName, payload }, kind: "assistant_text", seq };
   }
-  if (eventName === "tool.started" || isToolStarted(payload)) {
+  if (eventName === "tool.started" || isToolStarted(eventName, payload)) {
     return { raw: { event: eventName, payload }, kind: "tool_use", seq };
   }
-  if (eventName === "tool.completed" || isToolCompleted(payload)) {
+  if (eventName === "tool.completed" || isToolCompleted(eventName, payload)) {
     return { raw: { event: eventName, payload }, kind: "tool_result", seq };
   }
-  if (eventName === "item.delta" && payload?.payload?.kind === "agent_message") {
+  if (eventName === "item.delta" && isAgentMessageDelta(payload)) {
     return { raw: { event: eventName, payload }, kind: "assistant_text", seq };
   }
+  if (eventName === "item.completed" && isAgentReasoningItem(payload)) {
+    return { raw: { event: eventName, payload }, kind: "thinking", seq };
+  }
   if (eventName === "turn.started" || eventName === "status" || embeddedDeepseekEvent(payload) === "turn.started") {
     return { raw: { event: eventName, payload }, kind: "system", seq };
   }
@@ -485,18 +496,57 @@ function isDeepseekTerminalEvent(eventName: string, payload: any): boolean {
   );
 }
 
-function isToolStarted(payload: any): boolean {
-  return payload?.event === "item.started" && !!payload?.payload?.tool;
+function isToolStarted(eventName: string, payload: any): boolean {
+  return (
+    (eventName === "item.started" &&
+      (!!payload?.tool || payload?.item?.kind === "tool_call" || payload?.payload?.item?.kind === "tool_call")) ||
+    (payload?.event === "item.started" && !!payload?.payload?.tool)
+  );
 }
 
-function isToolCompleted(payload: any): boolean {
-  const kind = payload?.payload?.item?.kind;
+function isToolCompleted(eventName: string, payload: any): boolean {
+  const kind = payload?.payload?.item?.kind ?? payload?.item?.kind;
   return (
-    (payload?.event === "item.completed" || payload?.event === "item.failed") &&
+    (eventName === "item.completed" ||
+      eventName === "item.failed" ||
+      payload?.event === "item.completed" ||
+      payload?.event === "item.failed") &&
     (kind === "tool_call" || kind === "file_change" || kind === "command_execution")
   );
 }
 
+function isAgentMessageDelta(payload: any): boolean {
+  return payload?.kind === "agent_message" || payload?.payload?.kind === "agent_message";
+}
+
+function isAgentReasoningItem(payload: any): boolean {
+  return payload?.item?.kind === "agent_reasoning" || payload?.payload?.item?.kind === "agent_reasoning";
+}
+
+function extractDeepseekDelta(payload: any): string {
+  return stringField(payload, "delta") ?? stringField(payload?.payload, "delta") ?? "";
+}
+
+function inferDeepseekToolName(item: any): string | undefined {
+  const candidates = [stringField(item, "summary"), stringField(item, "detail")];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const match = candidate.match(/^([A-Za-z0-9_.:-]+)\s*(?:started|completed|failed|returned|:)/);
+    if (match?.[1] && match[1] !== "tool_call") return match[1];
+  }
+  return undefined;
+}
+
+function emptyCompletionError(stderrTail: string): string {
+  const tail = stderrTail.trim();
+  if (!tail) {
+    return "deepseek runtime completed with no assistant_message (check DEEPSEEK_API_KEY / model availability)";
+  }
+  const lines = tail.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  const lastLines = lines.slice(-5).join("\n").slice(-500);
+  return `deepseek runtime completed with no assistant_message; stderr tail: ${lastLines}`;
+}
+
 function extractDeepseekError(eventName: string, payload: any): string | undefined {
   if (eventName === "error") {
     return (

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). */