@ai-matrx/desktop-protocol 0.1.1 → 0.3.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-DJbrsZ4u.cjs';
-export { i as isDesktopProtocolError } from './registry-DJbrsZ4u.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-DQ5_mP_5.cjs';
+export { i as isDesktopProtocolError } from './registry-DQ5_mP_5.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-DJbrsZ4u.js';
-export { i as isDesktopProtocolError } from './registry-DJbrsZ4u.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-DQ5_mP_5.js';
+export { i as isDesktopProtocolError } from './registry-DQ5_mP_5.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

@@ -95,6 +95,7 @@ import { z as z2 } from "zod";
 import { z } from "zod";
 var PROTOCOL_MAJOR = 1;
 var PROTOCOL_MINOR = 0;
+var PROTOCOL_VERSION = `${PROTOCOL_MAJOR}.${PROTOCOL_MINOR}`;
 var ProtocolVersion = z.string().regex(/^[1-9][0-9]{0,2}\.[0-9]{1,3}$/);
 var RequestId = z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/);
 var ResourceId = z.string().regex(/^(pty|watch)_[A-Za-z0-9]{16,40}$/);
@@ -366,12 +367,9 @@ var FsEntry = z6.strictObject({
   kind: FsKind,
   size: nonNegInt,
   mtime: z6.number().min(0),
-  // seconds, float — daemon parity
-  mtime_ms: epochMs,
+  // seconds, float
   mode: z6.int().min(0).max(4095),
-  target: AbsPath.nullable(),
-  // symlink target, never followed
-  hidden: z6.boolean()
+  target: AbsPath.nullable()
 });
 var FsListParams = z6.strictObject({
   path: AbsPath,
@@ -379,10 +377,12 @@ var FsListParams = z6.strictObject({
   depth: z6.int().min(1).max(32).default(1),
   pattern: z6.string().max(256).optional(),
   // glob on name
-  limit: z6.int().min(1).max(5e3).default(500),
+  limit: z6.int().min(1).max(5e3).default(1e3),
   page_token: z6.string().max(256).optional(),
-  show_hidden: z6.boolean().default(false),
-  sort: z6.enum(["name", "mtime", "size", "kind"]).default("kind")
+  // Desktop additions; their defaults ARE the daemon's behaviour: dotfiles listed, siblings in
+  // binary (byte) order of name, depth-first.
+  show_hidden: z6.boolean().default(true),
+  sort: z6.enum(["name", "mtime", "size", "kind"]).default("name")
 });
 var FsListResult = z6.strictObject({
   entries: z6.array(FsEntry),
@@ -466,7 +466,7 @@ var FsSearchPathsParams = z6.strictObject({
   hidden: z6.boolean().default(false),
   max_results: z6.int().min(1).max(5e3).default(100)
 });
-var FsSearchPathsResult = z6.strictObject({ paths: z6.array(AbsPath), truncated: z6.boolean() });
+var FsSearchPathsResult = z6.strictObject({ paths: z6.array(z6.string().min(3).max(4096).regex(/^\.\/[^\\\u0000]+$/)) });
 var FsSearchContentParams = z6.strictObject({
   query: z6.string().min(1).max(1024),
   cwd: AbsPath,
@@ -479,13 +479,14 @@ var FsSearchContentParams = z6.strictObject({
 var FsSearchContentResult = z6.strictObject({
   results: z6.array(
     z6.strictObject({
-      path: AbsPath,
+      path: z6.string().min(1).max(4096).regex(/^[^/\\\u0000][^\\\u0000]*$/),
       lines: z6.string(),
       line_number: z6.int().min(1),
-      submatches: z6.array(z6.strictObject({ match: z6.string(), start: nonNegInt, end: nonNegInt }))
+      submatches: z6.array(
+        z6.strictObject({ match: z6.strictObject({ text: z6.string() }), start: nonNegInt, end: nonNegInt })
+      )
     })
-  ),
-  truncated: z6.boolean()
+  )
 });
 var FsChange = z6.strictObject({
   type: z6.enum(["created", "modified", "deleted", "moved"]),
@@ -732,7 +733,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 +790,7 @@ function createDesktopClient(options) {
     ws.onmessage = (event) => {
       if (generation !== socketGeneration) return;
       lastHeardAt = timers.now();
+      heardCount++;
       onMessage(event.data);
     };
     ws.onerror = () => {
@@ -828,6 +832,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 +1212,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 +1310,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 +1352,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
 };