@ai-matrx/desktop-protocol 0.1.0 → 0.2.0

package/dist/client.d.cts

@@ -1,8 +1,8 @@
 import { BackoffOptions } from '@ai-matrx/realtime';
 export { RECONNECT_ALARM_ATTEMPTS } from '@ai-matrx/realtime';
 import { z } from 'zod';
-import { W as Welcome, D as DesktopProtocolError, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, C as ClientType } from './registry-DTcTGycI.cjs';
-export { i as isDesktopProtocolError } from './registry-DTcTGycI.cjs';
+import { W as Welcome, D as DesktopProtocolError, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, C as ClientType } from './registry-DJbrsZ4u.cjs';
+export { i as isDesktopProtocolError } from './registry-DJbrsZ4u.cjs';
 import { FrameHeader } from './frame.cjs';
 
 /** The subset of the WHATWG WebSocket the client uses — browser, React Native, `ws` and Workers all fit. */
@@ -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

@@ -1,8 +1,8 @@
 import { BackoffOptions } from '@ai-matrx/realtime';
 export { RECONNECT_ALARM_ATTEMPTS } from '@ai-matrx/realtime';
 import { z } from 'zod';
-import { W as Welcome, D as DesktopProtocolError, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, C as ClientType } from './registry-DTcTGycI.js';
-export { i as isDesktopProtocolError } from './registry-DTcTGycI.js';
+import { W as Welcome, D as DesktopProtocolError, O as OpName, a as OpParams, b as OpResult, c as OPS, S as StreamMeta, E as EndReason, d as EVENTS, C as ClientType } from './registry-DJbrsZ4u.js';
+export { i as isDesktopProtocolError } from './registry-DJbrsZ4u.js';
 import { FrameHeader } from './frame.js';
 
 /** The subset of the WHATWG WebSocket the client uses — browser, React Native, `ws` and Workers all fit. */
@@ -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

@@ -254,7 +254,15 @@ var CoreToClientMsg = z3.discriminatedUnion("type", [ResponseMsg, ErrorMsg, Stre
 var CloseCode = {
   NORMAL: 1e3,
   GOING_AWAY: 1001,
-  // relay deploy / app quit — reconnect immediately
+  // app quit; relay: the device was silent for 75 s — reconnect
+  /** Never sent by anyone: what a socket reports when it drops without a close frame. A relay
+   *  deploy (every Durable Object restarts) arrives as this — reconnect immediately. */
+  ABNORMAL: 1006,
+  /** Relay → clients: the device (re)connected, so the core session they spoke to is gone —
+   *  reconnect, hello, and reattach with since_seq. */
+  DEVICE_RECONNECTED: 1012,
+  TRY_AGAIN_LATER: 1013,
+  // relay: signing keys or the device registry unreachable — retry
   AUTH_INVALID: 4001,
   AUTH_FORBIDDEN: 4003,
   DEVICE_NOT_FOUND: 4004,
@@ -267,6 +275,7 @@ var CloseCode = {
   PROTOCOL_ERROR: 4400,
   UPGRADE_REQUIRED: 4426
 };
+var CloseCodeValue = z3.literal([1e3, 1001, 1006, 1012, 1013, 4001, 4003, 4004, 4008, 4009, 4010, 4400, 4426]);
 
 // src/schema/frame.ts
 import { z as z4 } from "zod";
@@ -278,6 +287,22 @@ var FrameHeader = z4.strictObject({
   sid: u32,
   seq: u32
 });
+var RelayHopEnvelopeHeader = z4.strictObject({
+  version: z4.literal(FRAME_VERSION),
+  flags: z4.literal(0),
+  channel: z4.literal(255),
+  cid: u32,
+  sid: z4.literal(0),
+  seq: z4.literal(0)
+});
+var RelayHopConnectionEnd = z4.strictObject({
+  version: z4.literal(FRAME_VERSION),
+  flags: z4.literal(1),
+  channel: z4.literal(255),
+  cid: z4.int().min(1).max(4294967295),
+  sid: z4.literal(0),
+  seq: z4.literal(0)
+});
 var DEFAULT_WINDOW_BYTES = 262144;
 var DEFAULT_MAX_FRAME_PAYLOAD_BYTES = 65536;
 
@@ -587,6 +612,22 @@ var RelayCallResponse = z9.discriminatedUnion("ok", [
   z9.strictObject({ ok: z9.literal(true), result: z9.unknown() }),
   z9.strictObject({ ok: z9.literal(false), error: ProtocolErrorBody })
 ]);
+var RELAY_CALL_HELLO_ID = "hello";
+var RELAY_CALL_REQUEST_ID = "call";
+var RelayCallHello = z9.strictObject({
+  type: z9.literal("hello"),
+  id: z9.literal(RELAY_CALL_HELLO_ID),
+  protocolVersion: ProtocolVersion,
+  clientType: z9.literal("server"),
+  clientVersion: z9.string().min(1).max(32)
+});
+var RelayCallEnvelope = z9.strictObject({
+  id: z9.literal(RELAY_CALL_REQUEST_ID),
+  type: z9.literal("request"),
+  cap: z9.string().min(1).max(32),
+  op: z9.string().min(1).max(64),
+  params: z9.unknown()
+});
 
 // src/schema/registry.ts
 var FS_ERR = ["NOT_FOUND", "PERMISSION_DENIED_OS", "INVALID_PARAMS", "RESOURCE_BUSY", "INTERNAL"];
@@ -691,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) {
@@ -746,6 +789,7 @@ function createDesktopClient(options) {
     ws.onmessage = (event) => {
       if (generation !== socketGeneration) return;
       lastHeardAt = timers.now();
+      heardCount++;
       onMessage(event.data);
     };
     ws.onerror = () => {
@@ -787,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) {
@@ -1163,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,
@@ -1260,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,
@@ -1274,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
 };