@ai-matrx/desktop-protocol 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.3.0
+
+SPEC 6.1 sandbox parity: every search and list op now answers exactly what the cloud sandbox
+daemon answers (fd 8.3.1 / ripgrep 13 run in `cwd`), verified against answers recorded from a live
+sandbox (matrx-desktop `test/fixtures/sandbox-daemon/observed.json`).
+
+- `fs.search_content`: `results[].path` is RELATIVE to `cwd` (no `./`), `submatches[].match` is
+  ripgrep's `{ text }`, and there is no `truncated` (`max_results` caps matching lines per file,
+  as `rg -m`).
+- `fs.search_paths`: `paths` are RELATIVE to `cwd` and prefixed `./` (fd), sorted, cut to
+  `max_results`; no `truncated`.
+- `FsEntry` (`fs.stat`, `fs.list` entries) is the daemon's `get_stat_dict` field for field:
+  `mtime_ms` and `hidden` are gone (take a write guard from `fs.read`'s `mtime_ms`).
+- `fs.list` defaults are the daemon's behaviour: `limit` 1000, dotfiles listed (`show_hidden`
+  true), siblings in byte order of name (`sort` "name"). Page tokens are single-use.
+
+Consumer action: join a search path to `cwd` yourself when you need an absolute one; read
+`match.text` instead of `match`; drop any use of `truncated` on search results and of `mtime_ms` /
+`hidden` on entries.
+
+## 0.2.0
+
+The phone console (lane E) needs a client that comes back the instant the person does.
+
+- `client.wake({ probeMs })` — reconnecting: dial now instead of waiting out the backoff; open:
+  send a ping and, if nothing is heard within `probeMs` (default 4000), treat the socket as dead
+  and redial at once. A phone resumed from sleep often holds a socket the OS already killed.
+- `bindDesktopWake(client)` (`./client`) and `useDesktopWake()` (`./react`) call `wake()` on
+  `visibilitychange` → visible, `pageshow`, `online` and `focus`.
+- A caller-started `session.attach` (a page reload reattaching by the resource id it kept in the
+  URL) is now a resource stream from its first byte: `resourceId` is set from the params,
+  `lastSeq` starts at `since_seq` (no false `seq_gap` on the first replayed frame), and the stream
+  reattaches after a later drop like the stream that created the resource.
+
+Consumer action: none required. Phone and browser consoles should call `useDesktopWake()` (or
+`bindDesktopWake`) once per client.
+
 ## 0.1.1
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -14,7 +14,7 @@ pnpm add @ai-matrx/desktop-protocol
 | `@ai-matrx/desktop-protocol` | Schemas for the envelope and every `cap.op`, `OPS` / `EVENTS` registries, `ErrorCode`, close codes, `DesktopProtocolError`. Every schema name is also its inferred type. |
 | `@ai-matrx/desktop-protocol/frame` | The 16-byte binary frame codec. Zod-free (the relay Worker's hot path). |
 | `@ai-matrx/desktop-protocol/client` | `createDesktopClient` — reconnecting client with typed requests, credit-gated streams, transparent terminal reattach, heartbeat and relay reauth. |
-| `@ai-matrx/desktop-protocol/react` | `DesktopClientProvider`, `useDesktopConnection`, `useDesktopRequest`, `useDesktopEvent`. |
+| `@ai-matrx/desktop-protocol/react` | `DesktopClientProvider`, `useDesktopConnection`, `useDesktopRequest`, `useDesktopEvent`, `useDesktopWake`. |
 
 ## Client
 
@@ -54,6 +54,12 @@ term.write("ls\n");
   `@ai-matrx/realtime` backoff (stability reset + jitter) — including `1006` (a relay deploy drops
   every socket without a close frame) and `1012` (the relay's "the device reconnected": hello and
   reattach against the new core session).
+- **Coming back:** `client.wake()` (or `bindDesktopWake(client)` / `useDesktopWake()`, which call it
+  on `visibilitychange`, `pageshow`, `online` and `focus`) dials at once while reconnecting and
+  probes an open socket with a ping, redialing if nothing answers within 4 s.
+- **Reload reattach:** keep `stream.resourceId` and `stream.lastSeq` (e.g. in the URL); after a reload
+  `client.stream("session.attach", { resource_id, since_seq })` replays the gap and then behaves
+  exactly like the original stream, including surviving later drops.
 - Background problems (malformed messages, sequence gaps, heartbeat death, reconnect alarm) go to
   `onDiagnostic` — loud by default (`console.warn`).
 

package/dist/client.cjs

@@ -22,6 +22,7 @@ var client_exports = {};
 __export(client_exports, {
   DesktopProtocolError: () => DesktopProtocolError,
   RECONNECT_ALARM_ATTEMPTS: () => import_realtime.RECONNECT_ALARM_ATTEMPTS,
+  bindDesktopWake: () => bindDesktopWake,
   createDesktopClient: () => createDesktopClient,
   isDesktopProtocolError: () => isDesktopProtocolError
 });
@@ -124,6 +125,7 @@ var import_zod2 = require("zod");
 var import_zod = require("zod");
 var PROTOCOL_MAJOR = 1;
 var PROTOCOL_MINOR = 0;
+var PROTOCOL_VERSION = `${PROTOCOL_MAJOR}.${PROTOCOL_MINOR}`;
 var ProtocolVersion = import_zod.z.string().regex(/^[1-9][0-9]{0,2}\.[0-9]{1,3}$/);
 var RequestId = import_zod.z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/);
 var ResourceId = import_zod.z.string().regex(/^(pty|watch)_[A-Za-z0-9]{16,40}$/);
@@ -395,12 +397,9 @@ var FsEntry = import_zod6.z.strictObject({
   kind: FsKind,
   size: nonNegInt,
   mtime: import_zod6.z.number().min(0),
-  // seconds, float — daemon parity
-  mtime_ms: epochMs,
+  // seconds, float
   mode: import_zod6.z.int().min(0).max(4095),
-  target: AbsPath.nullable(),
-  // symlink target, never followed
-  hidden: import_zod6.z.boolean()
+  target: AbsPath.nullable()
 });
 var FsListParams = import_zod6.z.strictObject({
   path: AbsPath,
@@ -408,10 +407,12 @@ var FsListParams = import_zod6.z.strictObject({
   depth: import_zod6.z.int().min(1).max(32).default(1),
   pattern: import_zod6.z.string().max(256).optional(),
   // glob on name
-  limit: import_zod6.z.int().min(1).max(5e3).default(500),
+  limit: import_zod6.z.int().min(1).max(5e3).default(1e3),
   page_token: import_zod6.z.string().max(256).optional(),
-  show_hidden: import_zod6.z.boolean().default(false),
-  sort: import_zod6.z.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: import_zod6.z.boolean().default(true),
+  sort: import_zod6.z.enum(["name", "mtime", "size", "kind"]).default("name")
 });
 var FsListResult = import_zod6.z.strictObject({
   entries: import_zod6.z.array(FsEntry),
@@ -495,7 +496,7 @@ var FsSearchPathsParams = import_zod6.z.strictObject({
   hidden: import_zod6.z.boolean().default(false),
   max_results: import_zod6.z.int().min(1).max(5e3).default(100)
 });
-var FsSearchPathsResult = import_zod6.z.strictObject({ paths: import_zod6.z.array(AbsPath), truncated: import_zod6.z.boolean() });
+var FsSearchPathsResult = import_zod6.z.strictObject({ paths: import_zod6.z.array(import_zod6.z.string().min(3).max(4096).regex(/^\.\/[^\\\u0000]+$/)) });
 var FsSearchContentParams = import_zod6.z.strictObject({
   query: import_zod6.z.string().min(1).max(1024),
   cwd: AbsPath,
@@ -508,13 +509,14 @@ var FsSearchContentParams = import_zod6.z.strictObject({
 var FsSearchContentResult = import_zod6.z.strictObject({
   results: import_zod6.z.array(
     import_zod6.z.strictObject({
-      path: AbsPath,
+      path: import_zod6.z.string().min(1).max(4096).regex(/^[^/\\\u0000][^\\\u0000]*$/),
       lines: import_zod6.z.string(),
       line_number: import_zod6.z.int().min(1),
-      submatches: import_zod6.z.array(import_zod6.z.strictObject({ match: import_zod6.z.string(), start: nonNegInt, end: nonNegInt }))
+      submatches: import_zod6.z.array(
+        import_zod6.z.strictObject({ match: import_zod6.z.strictObject({ text: import_zod6.z.string() }), start: nonNegInt, end: nonNegInt })
+      )
     })
-  ),
-  truncated: import_zod6.z.boolean()
+  )
 });
 var FsChange = import_zod6.z.strictObject({
   type: import_zod6.z.enum(["created", "modified", "deleted", "moved"]),
@@ -761,7 +763,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) {
@@ -816,6 +820,7 @@ function createDesktopClient(options) {
     ws.onmessage = (event) => {
       if (generation !== socketGeneration) return;
       lastHeardAt = timers.now();
+      heardCount++;
       onMessage(event.data);
     };
     ws.onerror = () => {
@@ -857,6 +862,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) {
@@ -1233,15 +1242,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,
@@ -1330,6 +1340,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,
@@ -1344,7 +1382,29 @@ 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);
   };
 }
 //# sourceMappingURL=client.cjs.map