@zhin.js/client 2.1.10 → 2.1.11

package/README.md

@@ -27,6 +27,10 @@ Peer：`react >= 18`（`createPluginRegisterHostApi` 需要 React 引用）。
 | `normalizeConsolePushType` / `normalizeConsolePushMessage` | 在 SDK 边界兼容旧 `endpoint:*` 推送并输出规范事件与 payload |
 | `parseConsoleInboxEvent` | 一次完成 Inbox 推送名称、身份别名和 message/request/notice 分类 |
 | `ConsoleEndpointSummary` / `EndpointManagementCapability` | Host 与 Remote Console 共享的 Endpoint wire 类型 |
+| `fetchConsoleEventHistory` | 按 `(runtimeId, eventId)` 拉取有界事件历史 |
+| `WebSocketManager.onConsoleEvent` | 订阅带 `live/history` 投递来源的强类型事件 |
+| `WebSocketManager.onConsoleEventRecoveryGap` | 观察不可续接游标并触发领域全量重同步 |
+| `ConsoleInboxNoticesQuery` / `ConsoleInboxNoticesResult` | 以 `unreadOnly` 从持久 Inbox 重建未读通知 |
 
 类型与 Entry 契约来自 `@zhin.js/contract`。
 
@@ -97,6 +101,8 @@ const res = await apiFetch("/api/console/request", {
 
 辅助：`resolveApiUrl`、`resolveWebSocketUrl`（SSE `/api/events` 等）。
 
+Client 在连接 `/api/events` 前先补拉 `/api/events/history`，再携带最新游标进入 SSE；Host 会原子重放 HTTP 与订阅之间产生的事件。游标只在 Inbox 持久化成功后推进，重复的 history/live 投递按 `(runtimeId, eventId)` 幂等写入 IndexedDB。`gap` 不会被吞掉，页面可订阅恢复缺口并改走领域 HTTP 全量投影。
+
 ## `createPluginRegisterHostApi`
 
 将壳层已有的 React 与路由/工具注册函数适配为契约中的 `PluginRegisterHostApi`（含 `addPage` 别名 → `addRoute`）：

package/client/console-events.ts

@@ -0,0 +1,37 @@
+import type {
+  ConsoleEventHistoryPage,
+  ConsoleEventHistoryQuery,
+} from '@zhin.js/console-protocol';
+import { getStoredToken, resolveApiUrl } from './websocket/remote-settings.js';
+
+export interface FetchConsoleEventHistoryOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Read a typed page from the Host's bounded Console event journal. */
+export async function fetchConsoleEventHistory(
+  query: ConsoleEventHistoryQuery = {},
+  options: FetchConsoleEventHistoryOptions = {},
+): Promise<ConsoleEventHistoryPage> {
+  const params = new URLSearchParams();
+  if (query.runtimeId) params.set('runtimeId', query.runtimeId);
+  if (query.after !== undefined) params.set('after', String(query.after));
+  if (query.limit !== undefined) params.set('limit', String(query.limit));
+  const token = getStoredToken();
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const suffix = params.size ? `?${params}` : '';
+  const response = await fetch(resolveApiUrl(`/api/events/history${suffix}`), {
+    headers,
+    signal: options.signal,
+  });
+  const body = await response.json() as {
+    success?: boolean;
+    data?: ConsoleEventHistoryPage;
+    error?: string;
+  };
+  if (!response.ok || body.success !== true || !body.data) {
+    throw new Error(body.error ?? `Console event history failed: HTTP ${response.status}`);
+  }
+  return body.data;
+}

package/client/index.ts

@@ -2,6 +2,7 @@
 export * from "./types";
 export {
   ENDPOINT_RPC,
+  CONSOLE_EVENT_RECOVERY_GAP_EVENT,
   ENDPOINT_MANAGEMENT_CAPABILITIES,
   INBOX_RPC,
   SIDE_EVENT_PUSH,
@@ -11,11 +12,35 @@ export {
   parseConsoleInboxEvent,
   type ConsoleInboxEvent,
   type ConsoleInboxEventKind,
+  type ConsoleInboxNoticeRow,
+  type ConsoleInboxNoticesQuery,
+  type ConsoleInboxNoticesResult,
   type ConsoleEndpointPhase,
   type ConsoleEndpointSummary,
+  type ConsoleEventActor,
+  type ConsoleEventChannel,
   type EndpointManagementCapability,
+  parseConsoleSseFrame,
+  type ConsoleEventDelivery,
+  type ConsoleEventData,
+  type ConsoleEndpointEventData,
+  type ConsoleEventEnvelope,
+  type ConsoleEventHistoryPage,
+  type ConsoleEventHistoryQuery,
+  type ConsoleEventPayloadMap,
+  type ConsoleMessageEventData,
+  type ConsoleNoticeEventData,
+  type ConsoleRequestEventData,
+  type KnownConsoleEventType,
+  type KnownConsoleEventEnvelope,
+  type ParsedConsoleSseFrame,
 } from "@zhin.js/console-protocol";
 
+export {
+  fetchConsoleEventHistory,
+  type FetchConsoleEventHistoryOptions,
+} from './console-events.js';
+
 // Media URL resolution
 export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from "./mediaSrc";
 

package/client/persistence/idb-store.test.ts

@@ -108,6 +108,17 @@ describe("applyConsoleEvent inbox record ids", () => {
     expect(new Set(rows.map((r) => r.id)).size).toBe(2);
   });
 
+  it('deduplicates the same resumable event across history and live delivery', async () => {
+    const event = { ...PUSH, runtimeId: 'runtime-a', eventId: 7, timestamp: 1700000000000 };
+    await applyConsoleEvent(event);
+    await applyConsoleEvent(event);
+
+    const rows = await idbListInbox('icqq', 'bot-1', 'message');
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.id).toBe('runtime-a:7');
+    expect(rows[0]?.updatedAt).toBe(1700000000000);
+  });
+
   it("reads legacy records that only carry endpointKey (camelCase)", async () => {
     // 旧版（DB v1 时代）记录只有 endpointKey 字段，升级后仍需能被列出
     const { idbPutInbox } = await import("./idb-store.js");

package/client/persistence/idb-store.ts

@@ -66,13 +66,29 @@ export async function idbListInbox(
   );
 }
 
-export async function applyConsoleEvent(event: { type: string; data?: unknown }): Promise<void> {
+export async function applyConsoleEvent(event: {
+  type: string;
+  data?: unknown;
+  runtimeId?: string;
+  eventId?: number;
+  timestamp?: number;
+}): Promise<void> {
   const parsed = parseConsoleInboxEvent(event);
   if (!parsed) return;
-  const updatedAt = Date.now();
+  const updatedAt = typeof event.timestamp === 'number' && Number.isFinite(event.timestamp)
+    ? event.timestamp
+    : Date.now();
+  const resumableId = typeof event.runtimeId === 'string'
+    && event.runtimeId
+    && Number.isSafeInteger(event.eventId)
+    && (event.eventId ?? 0) > 0
+    ? `${event.runtimeId}:${event.eventId}`
+    : null;
   await idbPutInbox({
-    // 追加自增+随机后缀：同毫秒同会话的两条事件不会因主键相同而互相覆盖
-    id: `${parsed.adapter}:${parsed.endpointKey}:${parsed.type}:${updatedAt}:${inboxEventSeq++}:${Math.random().toString(36).slice(2, 8)}`,
+    // Resumable Host events are idempotent across history/live redelivery.
+    // Legacy/unsequenced sources retain collision-safe append ids.
+    id: resumableId
+      ?? `${parsed.adapter}:${parsed.endpointKey}:${parsed.type}:${updatedAt}:${inboxEventSeq++}:${Math.random().toString(36).slice(2, 8)}`,
     adapter: parsed.adapter,
     endpoint_id: parsed.endpointKey,
     kind: parsed.kind,

package/client/websocket/index.ts

@@ -1,5 +1,10 @@
 export * from "./types";
-export { WebSocketManager } from "./manager";
+export {
+  WebSocketManager,
+  type ConsoleEventListener,
+  type ConsoleEventRecoveryGap,
+  type ConsoleEventRecoveryGapListener,
+} from "./manager";
 export { getWebSocketManager, destroyWebSocketManager, resetWebSocketManager } from "./instance";
 export { useWebSocket, useConfig, useConfigYaml, useFiles, useEnvFiles, useDatabase } from "./hooks";
 import { getWebSocketManager } from "./instance";

package/client/websocket/manager.test.ts

@@ -54,6 +54,32 @@ function sseResponse(status = 200, body?: ReadableStream<Uint8Array> | null) {
   } as Response;
 }
 
+function eventHistoryResponse(items: unknown[] = [], runtimeId = 'runtime-test', latestEventId?: number) {
+  const inferredLatest = (items.at(-1) as { eventId?: number } | undefined)?.eventId ?? 0;
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({
+      success: true,
+      data: {
+        runtimeId,
+        items,
+        oldestAvailableEventId: items.length ? 1 : null,
+        latestEventId: latestEventId ?? inferredLatest,
+        nextAfter: inferredLatest,
+        hasMore: false,
+        gap: false,
+      },
+    }),
+  } as Response;
+}
+
+function mockConsoleTransport(sse: () => Response | Promise<Response>) {
+  return vi.fn(async (input: RequestInfo | URL, _init?: RequestInit) => {
+    return String(input).includes('/api/events/history') ? eventHistoryResponse() : await sse();
+  });
+}
+
 describe("WebSocketManager REST/SSE transport", () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -68,7 +94,7 @@ describe("WebSocketManager REST/SSE transport", () => {
 
   it("connects SSE without a token (local Host with empty TokenRegistry)", async () => {
     installBrowserGlobals();
-    const fetchMock = vi.fn(async () => sseResponse(200));
+    const fetchMock = mockConsoleTransport(() => sseResponse(200));
     vi.stubGlobal("fetch", fetchMock);
 
     const manager = new WebSocketManager({ reconnectInterval: 100, maxReconnectAttempts: 3 });
@@ -81,7 +107,8 @@ describe("WebSocketManager REST/SSE transport", () => {
     await Promise.resolve();
 
     expect(fetchMock).toHaveBeenCalled();
-    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    const sseCall = fetchMock.mock.calls.find(([input]) => !String(input).includes('/history'))!;
+    const init = sseCall[1] as RequestInit;
     const headers = init.headers as Record<string, string>;
     expect(headers.Accept).toBe("text/event-stream");
     expect(headers.Authorization).toBeUndefined();
@@ -92,7 +119,7 @@ describe("WebSocketManager REST/SSE transport", () => {
 
   it("sends Authorization when a token is stored", async () => {
     installBrowserGlobals(mockStorage({ zhin_api_token: "secret" }));
-    const fetchMock = vi.fn(async () => sseResponse(200));
+    const fetchMock = mockConsoleTransport(() => sseResponse(200));
     vi.stubGlobal("fetch", fetchMock);
 
     const manager = new WebSocketManager();
@@ -101,17 +128,18 @@ describe("WebSocketManager REST/SSE transport", () => {
     await Promise.resolve();
     await Promise.resolve();
 
-    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    const sseCall = fetchMock.mock.calls.find(([input]) => !String(input).includes('/history'))!;
+    const init = sseCall[1] as RequestInit;
     expect((init.headers as Record<string, string>).Authorization).toBe("Bearer secret");
     manager.disconnect();
   });
 
   it("reconnects after a transient SSE failure (no ERROR deadlock)", async () => {
     installBrowserGlobals();
-    let calls = 0;
-    const fetchMock = vi.fn(async () => {
-      calls += 1;
-      if (calls === 1) return sseResponse(503, null);
+    let sseCalls = 0;
+    const fetchMock = mockConsoleTransport(() => {
+      sseCalls += 1;
+      if (sseCalls === 1) return sseResponse(503, null);
       return sseResponse(200);
     });
     vi.stubGlobal("fetch", fetchMock);
@@ -127,14 +155,14 @@ describe("WebSocketManager REST/SSE transport", () => {
     await Promise.resolve();
     await Promise.resolve();
     expect(manager.getState()).toBe(ConnectionState.RECONNECTING);
-    expect(calls).toBe(1);
+    expect(sseCalls).toBe(1);
 
     // scheduleReconnect delay = 100 * attempt(1) = 100ms
     await vi.advanceTimersByTimeAsync(100);
     await Promise.resolve();
     await Promise.resolve();
 
-    expect(calls).toBeGreaterThanOrEqual(2);
+    expect(sseCalls).toBeGreaterThanOrEqual(2);
     expect(manager.getState()).toBe(ConnectionState.CONNECTED);
     manager.disconnect();
   });
@@ -194,7 +222,7 @@ describe("WebSocketManager REST/SSE transport", () => {
 
   it("stops reconnecting after maxReconnectAttempts", async () => {
     installBrowserGlobals();
-    const fetchMock = vi.fn(async () => sseResponse(500, null));
+    const fetchMock = mockConsoleTransport(() => sseResponse(500, null));
     vi.stubGlobal("fetch", fetchMock);
 
     const manager = new WebSocketManager({
@@ -210,7 +238,112 @@ describe("WebSocketManager REST/SSE transport", () => {
     }
 
     expect(manager.getState()).toBe(ConnectionState.ERROR);
-    expect(fetchMock.mock.calls.length).toBeLessThanOrEqual(3);
+    const sseCalls = fetchMock.mock.calls.filter(([input]) => !String(input).includes('/history'));
+    expect(sseCalls.length).toBeLessThanOrEqual(3);
     manager.disconnect();
   });
+
+  it('recovers typed history before live SSE and preserves event metadata', async () => {
+    installBrowserGlobals();
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoder.encode([
+          'id: 2',
+          'event: message.receive',
+          'runtime: runtime-a',
+          'timestamp: 200',
+          'data: {"adapter":"sandbox","endpointKey":"bot","content":"live"}',
+          '',
+          '',
+        ].join('\n')));
+      },
+    });
+    const historyEvent = {
+      runtimeId: 'runtime-a', eventId: 1, type: 'message.receive', timestamp: 100,
+      data: { adapter: 'sandbox', endpointKey: 'bot', content: 'history' },
+    };
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => (
+      String(input).includes('/history')
+        ? eventHistoryResponse([historyEvent], 'runtime-a')
+        : sseResponse(200, stream)
+    ));
+    vi.stubGlobal('fetch', fetchMock);
+    const received: Array<{ eventId: number; delivery?: string }> = [];
+    const manager = new WebSocketManager();
+    manager.onConsoleEvent('message.receive', (event) => received.push({ eventId: event.eventId, delivery: event.delivery }));
+    manager.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(received).toEqual([
+      { eventId: 1, delivery: 'history' },
+      { eventId: 2, delivery: 'live' },
+    ]);
+    expect(mockApplyConsoleEvent).toHaveBeenCalledTimes(2);
+    manager.disconnect();
+  });
+
+  it('keeps an in-memory cursor when localStorage is unavailable', async () => {
+    const storage = mockStorage();
+    storage.setItem = () => { throw new Error('storage disabled'); };
+    installBrowserGlobals(storage);
+    const historyEvent = {
+      runtimeId: 'runtime-a', eventId: 1, type: 'message.receive', timestamp: 100,
+      data: { adapter: 'sandbox', endpointKey: 'bot', content: 'history' },
+    };
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const after = new URL(String(input)).searchParams.get('after');
+      return after === '1'
+        ? eventHistoryResponse([], 'runtime-a', 1)
+        : eventHistoryResponse([historyEvent], 'runtime-a', 1);
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const received: number[] = [];
+    const manager = new WebSocketManager();
+    manager.onConsoleEvent('message.receive', (event) => received.push(event.eventId));
+    const recover = manager as unknown as { recoverEventHistory(signal: AbortSignal): Promise<void> };
+    await recover.recoverEventHistory(new AbortController().signal);
+    await recover.recoverEventHistory(new AbortController().signal);
+
+    expect(received).toEqual([1]);
+    expect(fetchMock.mock.calls[1]?.[0]).toContain('after=1');
+  });
+
+  it('exposes a typed recovery gap instead of silently treating it as complete', async () => {
+    installBrowserGlobals();
+    const response = eventHistoryResponse([], 'runtime-new', 9);
+    const originalJson = response.json;
+    response.json = async () => {
+      const body = await originalJson() as { data: Record<string, unknown> };
+      return { ...body, data: { ...body.data, gap: true, oldestAvailableEventId: 8 } };
+    };
+    vi.stubGlobal('fetch', vi.fn(async () => response));
+    const manager = new WebSocketManager();
+    const gaps: unknown[] = [];
+    manager.onConsoleEventRecoveryGap((gap) => gaps.push(gap));
+    const recover = manager as unknown as { recoverEventHistory(signal: AbortSignal): Promise<void> };
+    await recover.recoverEventHistory(new AbortController().signal);
+
+    expect(gaps).toEqual([expect.objectContaining({
+      page: expect.objectContaining({ runtimeId: 'runtime-new', gap: true }),
+    })]);
+  });
+
+  it('does not persist a cursor past an inbox event that failed durable storage', async () => {
+    const stored: Record<string, string> = {};
+    installBrowserGlobals(mockStorage(stored));
+    mockApplyConsoleEvent.mockRejectedValueOnce(new Error('IndexedDB unavailable'));
+    const historyEvent = {
+      runtimeId: 'runtime-a', eventId: 1, type: 'message.receive', timestamp: 100,
+      data: { adapter: 'sandbox', endpointKey: 'bot', content: 'history' },
+    };
+    vi.stubGlobal('fetch', vi.fn(async () => eventHistoryResponse([historyEvent], 'runtime-a', 1)));
+    const manager = new WebSocketManager();
+    const recover = manager as unknown as { recoverEventHistory(signal: AbortSignal): Promise<void> };
+    await recover.recoverEventHistory(new AbortController().signal);
+
+    expect(Object.keys(stored).filter((key) => key.includes('event-cursor'))).toEqual([]);
+  });
 });

package/client/websocket/manager.ts

@@ -2,11 +2,32 @@ import { ConnectionState, WebSocketError, ConnectionError, MessageError, Request
 
 import { getApiBase, getStoredToken, resolveApiUrl } from "./remote-settings.js";
 import { applyConsoleEvent } from "../persistence/idb-store.js";
+import { fetchConsoleEventHistory } from '../console-events.js';
 import {
+  CONSOLE_EVENT_RECOVERY_GAP_EVENT,
   SIDE_EVENT_PUSH,
   normalizeConsolePushMessage,
+  parseConsoleSseFrame,
+  type ConsoleEventData,
+  type ConsoleEventEnvelope,
+  type ConsoleEventHistoryPage,
+  type ConsoleEventHistoryQuery,
 } from "@zhin.js/console-protocol";
 
+interface ConsoleEventCursor {
+  readonly runtimeId: string;
+  readonly eventId: number;
+}
+
+export type ConsoleEventListener<Type extends string> = (
+  event: ConsoleEventEnvelope<Type, ConsoleEventData<Type>>,
+) => void;
+export interface ConsoleEventRecoveryGap {
+  readonly query: ConsoleEventHistoryQuery;
+  readonly page: ConsoleEventHistoryPage;
+}
+export type ConsoleEventRecoveryGapListener = (gap: ConsoleEventRecoveryGap) => void;
+
 export class WebSocketManager {
   private ws: WebSocket | null = null;
   private config: Required<WebSocketConfig>;
@@ -20,7 +41,12 @@ export class WebSocketManager {
     { resolve: (value: unknown) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }
   >();
   private connectedListeners = new Set<(connected: boolean) => void>();
+  private eventListeners = new Map<string, Set<ConsoleEventListener<string>>>();
+  private recoveryGapListeners = new Set<ConsoleEventRecoveryGapListener>();
   private sseAbort: AbortController | null = null;
+  private eventRuntimeId = '';
+  private lastEventId = 0;
+  private durableCursorBlocked = false;
   private useRestTransport = true;
 
   constructor(config: WebSocketConfig = {}, callbacks: WebSocketCallbacks = {}) {
@@ -38,6 +64,27 @@ export class WebSocketManager {
     return () => this.connectedListeners.delete(listener);
   }
 
+  /** Subscribe by event name; known names infer their exact payload type. */
+  onConsoleEvent<Type extends string>(type: Type, listener: ConsoleEventListener<Type>): () => void {
+    let listeners = this.eventListeners.get(type);
+    if (!listeners) {
+      listeners = new Set();
+      this.eventListeners.set(type, listeners);
+    }
+    const stored = listener as ConsoleEventListener<string>;
+    listeners.add(stored);
+    return () => {
+      listeners?.delete(stored);
+      if (listeners?.size === 0) this.eventListeners.delete(type);
+    };
+  }
+
+  /** Observe a non-resumable cursor so domain views can perform a full resync. */
+  onConsoleEventRecoveryGap(listener: ConsoleEventRecoveryGapListener): () => void {
+    this.recoveryGapListeners.add(listener);
+    return () => this.recoveryGapListeners.delete(listener);
+  }
+
   private notifyConnection(connected: boolean) {
     for (const l of this.connectedListeners) l(connected);
   }
@@ -73,7 +120,12 @@ export class WebSocketManager {
         Accept: "text/event-stream",
       };
       if (token) headers.Authorization = `Bearer ${token}`;
-      const res = await fetch(resolveApiUrl("/api/events"), {
+      await this.recoverEventHistory(this.sseAbort.signal);
+      const params = new URLSearchParams();
+      if (this.eventRuntimeId) params.set('runtimeId', this.eventRuntimeId);
+      if (this.lastEventId > 0) params.set('after', String(this.lastEventId));
+      const suffix = params.size ? `?${params}` : '';
+      const res = await fetch(resolveApiUrl(`/api/events${suffix}`), {
         headers,
         signal: this.sseAbort.signal,
       });
@@ -107,22 +159,21 @@ export class WebSocketManager {
         const { done, value } = await reader.read();
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
-        const parts = buffer.split("\n\n");
+        const parts = buffer.split(/\r?\n\r?\n/u);
         buffer = parts.pop() ?? "";
         for (const part of parts) {
-          const line = part.split("\n").find((l) => l.startsWith("data: "));
-          if (!line) continue;
-          const json = line.slice(6);
-          try {
-            const message = normalizeConsolePushMessage(
-              JSON.parse(json) as WebSocketMessage,
-            ) as WebSocketMessage;
-            void applyConsoleEvent(message);
-            this.handleBroadcast(message);
-            this.callbacks.onMessage?.(message);
-          } catch {
-            /* skip */
-          }
+          const parsed = parseConsoleSseFrame(part);
+          if (!parsed) continue;
+          const runtimeId = parsed.runtimeId ?? this.eventRuntimeId;
+          const event: ConsoleEventEnvelope = Object.freeze({
+            runtimeId,
+            eventId: parsed.eventId ?? 0,
+            type: parsed.type,
+            data: parsed.data,
+            timestamp: parsed.timestamp ?? Date.now(),
+            delivery: 'live',
+          });
+          await this.deliverConsoleEvent(event);
         }
       }
     } catch {
@@ -136,6 +187,99 @@ export class WebSocketManager {
     }
   }
 
+  private async recoverEventHistory(signal: AbortSignal): Promise<void> {
+    const stored = this.eventRuntimeId
+      ? { runtimeId: this.eventRuntimeId, eventId: this.lastEventId }
+      : readEventCursor();
+    let runtimeId = stored?.runtimeId;
+    let after = stored?.eventId ?? 0;
+    if (runtimeId) {
+      this.eventRuntimeId = runtimeId;
+      this.lastEventId = after;
+    }
+    for (;;) {
+      const query = { runtimeId, after, limit: 500 } satisfies ConsoleEventHistoryQuery;
+      const page = await fetchConsoleEventHistory(query, { signal });
+      if (page.runtimeId !== runtimeId) {
+        runtimeId = page.runtimeId;
+        after = 0;
+        this.lastEventId = 0;
+        this.durableCursorBlocked = false;
+      }
+      this.eventRuntimeId = page.runtimeId;
+      if (page.gap) this.notifyRecoveryGap({ query, page });
+      for (const item of page.items) {
+        await this.deliverConsoleEvent(Object.freeze({ ...item, delivery: 'history' }));
+        after = item.eventId;
+      }
+      if (!page.hasMore) {
+        this.lastEventId = Math.max(after, page.latestEventId);
+        if (!this.durableCursorBlocked) {
+          writeEventCursor({ runtimeId: page.runtimeId, eventId: this.lastEventId });
+        }
+        return;
+      }
+      after = page.nextAfter;
+    }
+  }
+
+  private async deliverConsoleEvent(event: ConsoleEventEnvelope): Promise<void> {
+    if (event.runtimeId && event.runtimeId !== this.eventRuntimeId) {
+      this.eventRuntimeId = event.runtimeId;
+      this.lastEventId = 0;
+      this.durableCursorBlocked = false;
+    }
+    if (event.eventId > 0
+      && event.runtimeId === this.eventRuntimeId
+      && event.eventId <= this.lastEventId) return;
+    const message = normalizeConsolePushMessage({
+      type: event.type,
+      data: event.data,
+      runtimeId: event.runtimeId,
+      eventId: event.eventId || undefined,
+      timestamp: event.timestamp,
+      delivery: event.delivery,
+    }) as WebSocketMessage;
+    try {
+      await applyConsoleEvent(message);
+    } catch (error) {
+      this.durableCursorBlocked = true;
+      console.error('[Console transport] Failed to persist event:', error);
+    }
+    this.handleBroadcast(message);
+    try {
+      this.callbacks.onMessage?.(message);
+    } catch (error) {
+      console.error('[Console transport] onMessage listener failed:', error);
+    }
+    for (const listener of this.eventListeners.get(event.type) ?? []) {
+      try {
+        listener(event as ConsoleEventEnvelope<string, unknown>);
+      } catch (error) {
+        console.error('[Console transport] event listener failed:', error);
+      }
+    }
+    if (event.eventId > 0 && event.runtimeId) {
+      this.lastEventId = Math.max(this.lastEventId, event.eventId);
+      if (!this.durableCursorBlocked) {
+        writeEventCursor({ runtimeId: event.runtimeId, eventId: this.lastEventId });
+      }
+    }
+  }
+
+  private notifyRecoveryGap(gap: ConsoleEventRecoveryGap): void {
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(CONSOLE_EVENT_RECOVERY_GAP_EVENT, { detail: gap }));
+    }
+    for (const listener of this.recoveryGapListeners) {
+      try {
+        listener(gap);
+      } catch (error) {
+        console.error('[Console transport] recovery gap listener failed:', error);
+      }
+    }
+  }
+
   disconnect(): void {
     this.clearReconnectTimer();
     this.clearPendingRequests();
@@ -362,12 +506,12 @@ export class WebSocketManager {
       }
       return;
     }
-    if (t === "hmr:reload") {
+    if (t === "hmr:reload" && message.delivery !== 'history') {
       console.info(`[HMR] File changed, reloading...`);
       window.location.reload();
       return;
     }
-    if (t === "system:restarting") {
+    if (t === "system:restarting" && message.delivery !== 'history') {
       console.info("[System] Server restarting, will reload shortly...");
       setTimeout(() => window.location.reload(), 3000);
       return;
@@ -443,3 +587,31 @@ export class WebSocketManager {
     this.pendingRequests.clear();
   }
 }
+
+function eventCursorStorageKey(): string {
+  return `zhin.console.event-cursor:${getApiBase()}`;
+}
+
+function readEventCursor(): ConsoleEventCursor | null {
+  if (typeof localStorage === 'undefined') return null;
+  try {
+    const parsed = JSON.parse(localStorage.getItem(eventCursorStorageKey()) ?? 'null') as Partial<ConsoleEventCursor> | null;
+    return parsed
+      && typeof parsed.runtimeId === 'string'
+      && Number.isSafeInteger(parsed.eventId)
+      && (parsed.eventId ?? -1) >= 0
+      ? { runtimeId: parsed.runtimeId, eventId: parsed.eventId as number }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeEventCursor(cursor: ConsoleEventCursor): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    localStorage.setItem(eventCursorStorageKey(), JSON.stringify(cursor));
+  } catch {
+    // HTTP history remains available when browser storage is unavailable.
+  }
+}

package/client/websocket/types.ts

@@ -1,6 +1,11 @@
+import type { ConsoleEventDelivery } from '@zhin.js/console-protocol';
+
 export interface BaseMessage {
   type: string;
   timestamp?: number;
+  runtimeId?: string;
+  eventId?: number;
+  delivery?: ConsoleEventDelivery;
   requestId?: number;
   error?: string;
 }

package/dist/console-events.d.ts

@@ -0,0 +1,7 @@
+import type { ConsoleEventHistoryPage, ConsoleEventHistoryQuery } from '@zhin.js/console-protocol';
+export interface FetchConsoleEventHistoryOptions {
+    readonly signal?: AbortSignal;
+}
+/** Read a typed page from the Host's bounded Console event journal. */
+export declare function fetchConsoleEventHistory(query?: ConsoleEventHistoryQuery, options?: FetchConsoleEventHistoryOptions): Promise<ConsoleEventHistoryPage>;
+//# sourceMappingURL=console-events.d.ts.map