@ai-matrx/desktop-protocol 0.1.1 → 0.2.0

package/dist/client.d.cts

@@ -167,6 +167,18 @@ interface DesktopClient {
     on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
     /** Hand the relay a fresh token without dropping the socket. */
     reauth(token: string): void;
+    /**
+     * The app came back to the foreground or the network changed (`visibilitychange` → visible,
+     * `pageshow`, `online`). Reconnecting → dial now instead of waiting out the backoff. Open → probe:
+     * a ping must be answered within `probeMs` (default 4000) or the socket is treated as dead and
+     * redialed at once. A phone resumed from sleep often holds a socket the OS already killed, and two
+     * silent heartbeats would cost 50 s. Resource streams reattach with `since_seq` as usual.
+     */
+    wake(options?: WakeOptions): void;
+}
+interface WakeOptions {
+    /** How long an open socket has to answer the probe ping. Default 4000. */
+    probeMs?: number;
 }
 
 /**
@@ -178,4 +190,20 @@ interface DesktopClient {
 
 declare function createDesktopClient(options: DesktopClientOptions): DesktopClient;
 
-export { type ClientTimers, type DesktopClient, type DesktopClientDiagnostic, type DesktopClientOptions, type DesktopClientState, type DesktopClientStatus, DesktopProtocolError, type DesktopStream, type EventHandler, type EventName, type EventPayload, OpName, OpParams, OpResult, type RequestOptions, type StreamHandlers, type StreamOpName, type StreamOptions, type WebSocketFactory, type WebSocketLike, createDesktopClient };
+/**
+ * Wire a client's wake() to the browser events that mean "the person is back": the page becomes
+ * visible again (iOS Safari suspends a background tab's sockets), a back/forward-cache restore
+ * (`pageshow` with persisted), and the network returning (`online`). Framework-free; the React
+ * binding is `useDesktopWake` in `./react`.
+ */
+
+/** The subset of window/document the binding listens on — injectable for tests and non-DOM hosts. */
+interface WakeTargets {
+    window: Pick<Window, "addEventListener" | "removeEventListener">;
+    document: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
+}
+declare function bindDesktopWake(client: Pick<DesktopClient, "wake">, options?: WakeOptions & {
+    targets?: WakeTargets;
+}): () => void;
+
+export { type ClientTimers, type DesktopClient, type DesktopClientDiagnostic, type DesktopClientOptions, type DesktopClientState, type DesktopClientStatus, DesktopProtocolError, type DesktopStream, type EventHandler, type EventName, type EventPayload, OpName, OpParams, OpResult, type RequestOptions, type StreamHandlers, type StreamOpName, type StreamOptions, type WakeOptions, type WakeTargets, type WebSocketFactory, type WebSocketLike, bindDesktopWake, createDesktopClient };

package/dist/client.d.ts

@@ -167,6 +167,18 @@ interface DesktopClient {
     on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
     /** Hand the relay a fresh token without dropping the socket. */
     reauth(token: string): void;
+    /**
+     * The app came back to the foreground or the network changed (`visibilitychange` → visible,
+     * `pageshow`, `online`). Reconnecting → dial now instead of waiting out the backoff. Open → probe:
+     * a ping must be answered within `probeMs` (default 4000) or the socket is treated as dead and
+     * redialed at once. A phone resumed from sleep often holds a socket the OS already killed, and two
+     * silent heartbeats would cost 50 s. Resource streams reattach with `since_seq` as usual.
+     */
+    wake(options?: WakeOptions): void;
+}
+interface WakeOptions {
+    /** How long an open socket has to answer the probe ping. Default 4000. */
+    probeMs?: number;
 }
 
 /**
@@ -178,4 +190,20 @@ interface DesktopClient {
 
 declare function createDesktopClient(options: DesktopClientOptions): DesktopClient;
 
-export { type ClientTimers, type DesktopClient, type DesktopClientDiagnostic, type DesktopClientOptions, type DesktopClientState, type DesktopClientStatus, DesktopProtocolError, type DesktopStream, type EventHandler, type EventName, type EventPayload, OpName, OpParams, OpResult, type RequestOptions, type StreamHandlers, type StreamOpName, type StreamOptions, type WebSocketFactory, type WebSocketLike, createDesktopClient };
+/**
+ * Wire a client's wake() to the browser events that mean "the person is back": the page becomes
+ * visible again (iOS Safari suspends a background tab's sockets), a back/forward-cache restore
+ * (`pageshow` with persisted), and the network returning (`online`). Framework-free; the React
+ * binding is `useDesktopWake` in `./react`.
+ */
+
+/** The subset of window/document the binding listens on — injectable for tests and non-DOM hosts. */
+interface WakeTargets {
+    window: Pick<Window, "addEventListener" | "removeEventListener">;
+    document: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
+}
+declare function bindDesktopWake(client: Pick<DesktopClient, "wake">, options?: WakeOptions & {
+    targets?: WakeTargets;
+}): () => void;
+
+export { type ClientTimers, type DesktopClient, type DesktopClientDiagnostic, type DesktopClientOptions, type DesktopClientState, type DesktopClientStatus, DesktopProtocolError, type DesktopStream, type EventHandler, type EventName, type EventPayload, OpName, OpParams, OpResult, type RequestOptions, type StreamHandlers, type StreamOpName, type StreamOptions, type WakeOptions, type WakeTargets, type WebSocketFactory, type WebSocketLike, bindDesktopWake, createDesktopClient };

package/dist/client.js

@@ -732,7 +732,9 @@ function createDesktopClient(options) {
   let helloId = null;
   let reconnectTimer = null;
   let heartbeatTimer = null;
+  let probeTimer = null;
   let lastHeardAt = 0;
+  let heardCount = 0;
   let closedByUser = false;
   const newId = (prefix) => `${prefix}${(++nextId).toString(36)}`;
   function setState(patch) {
@@ -787,6 +789,7 @@ function createDesktopClient(options) {
     ws.onmessage = (event) => {
       if (generation !== socketGeneration) return;
       lastHeardAt = timers.now();
+      heardCount++;
       onMessage(event.data);
     };
     ws.onerror = () => {
@@ -828,6 +831,10 @@ function createDesktopClient(options) {
       timers.clearTimeout(heartbeatTimer);
       heartbeatTimer = null;
     }
+    if (probeTimer !== null) {
+      timers.clearTimeout(probeTimer);
+      probeTimer = null;
+    }
     const terminal = code === null ? void 0 : TERMINAL_CLOSE.get(code);
     const lost = error ?? (terminal ? new DesktopProtocolError(terminal[0], terminal[1]) : new DesktopProtocolError("DEVICE_OFFLINE", "Connection lost", { retryable: true }));
     for (const [id, p] of pending) {
@@ -1204,15 +1211,16 @@ function createDesktopClient(options) {
     });
     result.catch(() => void 0);
     done.catch(() => void 0);
+    const attach = op === "session.attach" ? params : null;
     const s = {
       op,
       handlers,
       options: opts,
       id: newId("s"),
       sid: null,
-      resourceId: null,
-      lastSeq: 0,
-      expectSeq: 1,
+      resourceId: attach ? attach.resource_id : null,
+      lastSeq: attach?.since_seq ?? 0,
+      expectSeq: attach ? attach.since_seq === void 0 ? null : attach.since_seq + 1 : 1,
       windowBytes: opts.windowBytes ?? DEFAULT_WINDOW_BYTES,
       consumedUncredited: 0,
       sendWindow: DEFAULT_WINDOW_BYTES,
@@ -1301,6 +1309,34 @@ function createDesktopClient(options) {
   function reauth(token) {
     sendJson({ type: "relay", op: "reauth", token });
   }
+  function wake(opts = {}) {
+    if (closedByUser || state.status === "closed") return;
+    if (state.status === "idle" || state.status === "reconnecting") {
+      connect();
+      return;
+    }
+    if (state.status === "connecting" || !socket || probeTimer !== null) return;
+    const generation = socketGeneration;
+    const heardBefore = heardCount;
+    try {
+      socket.send(PING_TEXT);
+    } catch {
+    }
+    probeTimer = timers.setTimeout(() => {
+      probeTimer = null;
+      if (generation !== socketGeneration || !socket) return;
+      if (heardCount > heardBefore) return;
+      const silentMs = timers.now() - lastHeardAt;
+      diagnose({ kind: "heartbeat_timeout", silentMs });
+      const dead = socket;
+      onSocketGone(generation, null, new DesktopProtocolError("TIMEOUT", "Connection went silent", { retryable: true }));
+      try {
+        dead.close(CloseCode.NORMAL, "wake probe timeout");
+      } catch {
+      }
+      if (state.status === "reconnecting") connect();
+    }, opts.probeMs ?? 4e3);
+  }
   return {
     connect,
     close,
@@ -1315,12 +1351,35 @@ function createDesktopClient(options) {
     request,
     stream,
     on,
-    reauth
+    reauth,
+    wake
+  };
+}
+
+// src/client/wake.ts
+function bindDesktopWake(client, options = {}) {
+  const targets = options.targets ?? (typeof window !== "undefined" && typeof document !== "undefined" ? { window, document } : null);
+  if (!targets) return () => void 0;
+  const wakeOptions = options.probeMs === void 0 ? {} : { probeMs: options.probeMs };
+  const onVisibility = () => {
+    if (targets.document.visibilityState === "visible") client.wake(wakeOptions);
+  };
+  const onWake = () => client.wake(wakeOptions);
+  targets.document.addEventListener("visibilitychange", onVisibility);
+  targets.window.addEventListener("pageshow", onWake);
+  targets.window.addEventListener("online", onWake);
+  targets.window.addEventListener("focus", onWake);
+  return () => {
+    targets.document.removeEventListener("visibilitychange", onVisibility);
+    targets.window.removeEventListener("pageshow", onWake);
+    targets.window.removeEventListener("online", onWake);
+    targets.window.removeEventListener("focus", onWake);
   };
 }
 export {
   DesktopProtocolError,
   RECONNECT_ALARM_ATTEMPTS,
+  bindDesktopWake,
   createDesktopClient,
   isDesktopProtocolError
 };