@zhin.js/client 1.1.3 → 1.1.5

package/client/websocket/manager.ts

@@ -1,17 +1,32 @@
-import type {
-  WebSocketMessage,
-  WebSocketConfig,
-  WebSocketCallbacks,
-} from "./types";
-import {
-  ConnectionState,
-  WebSocketError,
-  ConnectionError,
-  MessageError,
-  RequestTimeoutError,
-} from "./types";
+import { ConnectionState, WebSocketError, ConnectionError, MessageError, RequestTimeoutError, type WebSocketMessage, type WebSocketConfig, type WebSocketCallbacks } from './types';
+
 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;
@@ -26,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 = {}) {
@@ -44,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);
   }
@@ -60,25 +101,32 @@ export class WebSocketManager {
       this.attachEventHandlers();
     } catch (error) {
       this.handleConnectionError(new ConnectionError("Failed to create WebSocket", error as Error));
+      this.setState(ConnectionState.RECONNECTING);
+      this.notifyConnection(false);
+      this.scheduleReconnect();
     }
   }
 
   private async connectRestSse(): Promise<void> {
+    // Host without http.token allows unauthenticated SSE (authenticateHttp
+    // returns full when TokenRegistry is empty). Still open the stream so
+    // local dev Console receives hmr:reload / message.receive broadcasts.
     const token = getStoredToken();
-    if (!token) {
-      this.setState(ConnectionState.DISCONNECTED);
-      this.notifyConnection(false);
-      return;
-    }
     this.setState(ConnectionState.CONNECTING);
     this.sseAbort?.abort();
     this.sseAbort = new AbortController();
     try {
-      const res = await fetch(resolveApiUrl("/api/events"), {
-        headers: {
-          Authorization: `Bearer ${token}`,
-          Accept: "text/event-stream",
-        },
+      const headers: Record<string, string> = {
+        Accept: "text/event-stream",
+      };
+      if (token) headers.Authorization = `Bearer ${token}`;
+      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,
       });
       if (!res.ok || !res.body) {
@@ -91,9 +139,13 @@ export class WebSocketManager {
       void this.pumpSse(res.body);
     } catch (error) {
       if ((error as Error).name === "AbortError") return;
-      this.handleConnectionError(
-        error instanceof ConnectionError ? error : new ConnectionError("SSE connect failed", error as Error),
-      );
+      // Must set RECONNECTING (not ERROR) before scheduleReconnect — the timer
+      // only fires when state === RECONNECTING; handleConnectionError(ERROR)
+      // previously deadlocked reconnect after any transient SSE failure.
+      this.callbacks.onError?.(error as unknown as Event);
+      console.error("[Console transport] SSE connect error:", error);
+      this.setState(ConnectionState.RECONNECTING);
+      this.notifyConnection(false);
       this.scheduleReconnect();
     }
   }
@@ -107,20 +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 = JSON.parse(json) 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 {
@@ -134,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();
@@ -184,24 +330,23 @@ export class WebSocketManager {
   }
 
   private async sendRestRequest<T>(message: unknown): Promise<T> {
+    // Host may run without http.token (local smoke). Only require a token when
+    // one is configured client-side; otherwise POST without Authorization and
+    // let the Host accept (TokenRegistry empty → full scope).
     const token = getStoredToken();
-    if (!token) throw new WebSocketError("Not authenticated", "NOT_CONNECTED");
     const requestId = ++this.requestId;
     const body = { ...(message as Record<string, unknown>), requestId };
-    const timer = setTimeout(() => {
-      /* handled below */
-    }, this.config.requestTimeout);
     try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+      };
+      if (token) headers.Authorization = `Bearer ${token}`;
       const res = await fetch(resolveApiUrl("/api/console/request"), {
         method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
+        headers,
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(this.config.requestTimeout),
       });
-      clearTimeout(timer);
       const json = (await res.json()) as {
         success?: boolean;
         data?: T;
@@ -213,7 +358,6 @@ export class WebSocketManager {
       }
       return json.data as T;
     } catch (error) {
-      clearTimeout(timer);
       if (error instanceof WebSocketError) throw error;
       throw new MessageError("REST request failed", error as Error);
     }
@@ -335,7 +479,9 @@ export class WebSocketManager {
 
   private handleMessage(event: MessageEvent): void {
     try {
-      const message = JSON.parse(event.data) as WebSocketMessage;
+      const message = normalizeConsolePushMessage(
+        JSON.parse(event.data) as WebSocketMessage,
+      ) as WebSocketMessage;
       if (message.requestId && this.pendingRequests.has(message.requestId)) {
         this.handleRequestResponse(message);
         return;
@@ -350,18 +496,22 @@ export class WebSocketManager {
 
   private handleBroadcast(message: WebSocketMessage): void {
     const t = message.type;
-    if (t === "bot:request" || t === "bot:notice" || t === "bot:message") {
+    if (
+      t === SIDE_EVENT_PUSH.REQUEST_RECEIVE
+      || t === SIDE_EVENT_PUSH.NOTICE_RECEIVE
+      || t === SIDE_EVENT_PUSH.MESSAGE_RECEIVE
+    ) {
       if (typeof window !== "undefined") {
         window.dispatchEvent(new CustomEvent("zhin-console-bot-push", { detail: message }));
       }
       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;
@@ -391,8 +541,10 @@ export class WebSocketManager {
   }
 
   private handleConnectionError(error: Error): void {
-    this.clearReconnectTimer();
-    this.setState(ConnectionState.ERROR);
+    // Used by the legacy WS path. Do NOT clear the reconnect timer here —
+    // callers that still want to retry should set RECONNECTING then call
+    // scheduleReconnect(). Terminal failures go through scheduleReconnect's
+    // maxAttempts branch which sets ERROR.
     console.error("[Console transport] Connection error:", error);
     this.callbacks.onError?.(error as unknown as Event);
   }
@@ -400,12 +552,23 @@ export class WebSocketManager {
   private scheduleReconnect(): void {
     if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
       this.setState(ConnectionState.ERROR);
+      this.notifyConnection(false);
       return;
     }
     this.reconnectAttempts++;
+    // Keep / restore RECONNECTING so the timer callback's state guard passes.
+    if (this.state !== ConnectionState.RECONNECTING) {
+      this.setState(ConnectionState.RECONNECTING);
+    }
     const delay = this.config.reconnectInterval * this.reconnectAttempts;
+    this.clearReconnectTimer();
     this.reconnectTimer = setTimeout(() => {
-      if (this.state === ConnectionState.RECONNECTING) this.connect();
+      if (
+        this.state === ConnectionState.RECONNECTING
+        || this.state === ConnectionState.DISCONNECTED
+      ) {
+        this.connect();
+      }
     }, delay);
   }
 
@@ -424,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/remote-settings.ts

@@ -3,7 +3,7 @@ const TOKEN_KEY = "zhin_api_token";
 
 export function getApiBase(): string {
   const stored = localStorage.getItem(API_BASE_KEY)?.trim();
-  if (stored) return stored.replace(/\/$/, "");
+  if (stored) return trimTrailingSlash(stored);
   if (typeof window !== "undefined") {
     return window.location.origin;
   }
@@ -11,11 +11,23 @@ export function getApiBase(): string {
 }
 
 export function setApiBase(base: string): void {
-  localStorage.setItem(API_BASE_KEY, base.replace(/\/$/, ""));
+  localStorage.setItem(API_BASE_KEY, trimTrailingSlash(base));
 }
 
 export function getStoredToken(): string | null {
-  return localStorage.getItem(TOKEN_KEY);
+  const runtime = getRuntimeToken();
+  if (runtime) return runtime;
+  if (typeof localStorage !== "undefined") {
+    const local = localStorage.getItem(TOKEN_KEY)?.trim();
+    if (local) return local;
+  }
+  // Some login flows only persist to sessionStorage; keep transport in sync
+  // with sandbox page / agent-stream which already read both stores.
+  if (typeof sessionStorage !== "undefined") {
+    const session = sessionStorage.getItem(TOKEN_KEY)?.trim();
+    if (session) return session;
+  }
+  return null;
 }
 
 export function resolveApiUrl(path: string): string {
@@ -23,3 +35,13 @@ export function resolveApiUrl(path: string): string {
   const p = path.startsWith("/") ? path : `/${path}`;
   return `${base}${p}`;
 }
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+function getRuntimeToken(): string | null {
+  if (typeof window === "undefined") return null;
+  const token = (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN;
+  return token?.trim() || null;
+}

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;
 }