@relayfile/sdk 0.10.51 → 0.10.53

package/dist/client.d.ts

@@ -178,6 +178,13 @@ export declare class RelayFileClient {
     private shouldRetryStatus;
     private shouldRetryError;
     private computeRetryDelayMs;
+    /**
+     * Extract a server-advertised retry delay from a parsed 429 error body.
+     * Relayfile advertises backpressure delays as `details.retryAfterSeconds`
+     * (in seconds) on `workspace_busy` / `queue_full` responses. Returns
+     * milliseconds, or null when absent/malformed.
+     */
+    private parseRetryAfterSecondsFromBody;
     private parseRetryAfterMs;
     private sleep;
     private readPayload;

package/dist/client.js

@@ -8,6 +8,15 @@ const DEFAULT_RETRY_OPTIONS = {
     maxDelayMs: 2000,
     jitterRatio: 0.2
 };
+/**
+ * Hard ceiling for a *server-advertised* retry delay (a 429 body's
+ * `details.retryAfterSeconds`). `maxDelayMs` bounds our OWN exponential
+ * backoff; an explicit server instruction ("retry after N seconds") is honored
+ * above that cap — truncating it just retries into the same overloaded resource
+ * and burns the retry budget — but is still bounded here so a pathological or
+ * hostile value cannot stall the client indefinitely.
+ */
+const RETRY_AFTER_MAX_MS = 30_000;
 const DEFAULT_CHANGE_COALESCE_MS = 200;
 const DEFAULT_CHANGE_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_CHANGE_LOG_MAX_ENTRIES = 10_000;
@@ -255,7 +264,9 @@ class RelayFileWebSocketConnection {
             }
         });
         socket.addEventListener("error", (event) => {
-            const errorEvent = event instanceof ErrorEvent && event.error instanceof Error ? event.error : event;
+            const errorEvent = typeof ErrorEvent !== "undefined" && event instanceof ErrorEvent && event.error instanceof Error
+                ? event.error
+                : event;
             for (const handler of this.handlers.error) {
                 handler(errorEvent);
             }
@@ -386,7 +397,13 @@ class RelayFileChangeSubscription {
         this.onChange = onChange;
         this.options = options;
         this.globPatterns = globs.map((pattern) => normalizeChangePattern(pattern));
-        this.pathScopes = options?.pathScope?.length ? options.pathScope.map((pattern) => normalizeChangePattern(pattern)) : null;
+        // A wildcard-free pathScope entry (e.g. "/ramp/transactions") is a DIRECTORY
+        // SUBTREE scope: expand it into the exact path plus its "/**" subtree filter
+        // so it matches the directory and everything under it. A bare path is never
+        // exact-file; use a glob for that. See expandDirectoryScope for the rule.
+        this.pathScopes = options?.pathScope?.length
+            ? options.pathScope.flatMap((pattern) => expandDirectoryScope(normalizeChangePattern(pattern)))
+            : null;
         this.shouldCoalesce = (options?.coalesce ?? "fire-once") !== "none";
         this.coalesceMs = Math.max(0, Math.floor(options?.coalesceMs ?? DEFAULT_CHANGE_COALESCE_MS));
     }
@@ -736,6 +753,45 @@ function normalizeChangePattern(pattern) {
     }
     return segments;
 }
+/**
+ * A wildcard-free `pathScope` entry is DEFINED as a DIRECTORY SUBTREE scope: it
+ * matches the path itself AND everything under it. To scope to an exact file,
+ * pass that exact path as a glob in the first `subscribe(globs, ...)` argument
+ * (the `globs` list is matched exactly unless an entry has a `*`/`**` wildcard);
+ * a bare `pathScope` path is never exact-file. This is a deliberate API-design
+ * choice (Option A), not an
+ * accident of the server matcher: it makes the common "watch this directory"
+ * intent Just Work and avoids a silent zero-event foot-gun.
+ *
+ * Why it MUST be subtree, and why "exact-file" is not a safe alternative:
+ * Relayfile creates descendants under file-looking paths (e.g.
+ * `/linear/issues/ENG-1.json/replies/draft.json`), so a bare path can never be
+ * assumed to name a leaf. Treating a wildcard-free entry as directory-scope is
+ * the only consistent rule.
+ *
+ * The data plane (see `webSocketPathMatches` in internal/httpapi/websocket.go)
+ * matches a `path=` filter against an event path with these semantics:
+ *   - exact match: `path` == the event path, OR
+ *   - trailing `**`: `/ramp/transactions/**` matches any STRICT descendant, OR
+ *   - per-segment `*` wildcards, requiring equal segment counts otherwise.
+ * A bare directory prefix like `/ramp/transactions` (no wildcard) would
+ * therefore match ONLY an event whose path is exactly `/ramp/transactions` —
+ * ZERO children — so a caller scoping to `["/ramp/transactions"]` opens a WS
+ * that silently receives no events (proven: `path=/ramp/transactions` -> 0
+ * events; `/**` -> 6). The same count-must-match rule in `matchChangeSegments`
+ * makes the client-side filter agree, so the miss would be doubly silent.
+ *
+ * Implementation: for a wildcard-free entry, emit BOTH the exact path AND the
+ * `.../**` subtree filter — the union matches the directory node itself plus its
+ * entire subtree. Entries that already contain a `*`/`**` wildcard are honored
+ * verbatim — an intentionally precise glob is never broadened.
+ */
+function expandDirectoryScope(segments) {
+    if (segments.some((segment) => segment === "*" || segment === "**")) {
+        return [segments];
+    }
+    return [segments, [...segments, "**"]];
+}
 function normalizeChangePath(path) {
     const normalized = path.startsWith("/") ? path : `/${path}`;
     const trimmed = normalized.replace(/\/+$/, "");
@@ -777,7 +833,14 @@ function getWorkspaceIdFromToken(token) {
     }
     try {
         const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
-        return typeof parsed.workspace_id === "string" && parsed.workspace_id.length > 0 ? parsed.workspace_id : undefined;
+        // Prefer the canonical `workspace_id` claim; fall back to the `wks` claim
+        // minted delegated tokens (relay_pa_*) actually carry, then `workspace`.
+        for (const candidate of [parsed.workspace_id, parsed.wks, parsed.workspace]) {
+            if (typeof candidate === "string" && candidate.length > 0) {
+                return candidate;
+            }
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -790,7 +853,15 @@ function getAgentIdFromToken(token) {
     }
     try {
         const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
-        return typeof parsed.agent_name === "string" && parsed.agent_name.length > 0 ? parsed.agent_name : undefined;
+        if (typeof parsed.agent_name === "string" && parsed.agent_name.length > 0) {
+            return parsed.agent_name;
+        }
+        // Minted delegated tokens omit `agent_name` and carry the agent as the JWT
+        // subject, e.g. sub: "agent_gil-ramp-bookkeeper".
+        if (typeof parsed.sub === "string" && parsed.sub.startsWith("agent_") && parsed.sub.length > "agent_".length) {
+            return parsed.sub.slice("agent_".length);
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -2177,7 +2248,11 @@ export class RelayFileClient {
             const payload = await this.readPayload(response);
             if (this.shouldRetryStatus(response.status, retries, params.signal)) {
                 retries += 1;
-                await this.sleep(this.computeRetryDelayMs(retries, response.headers.get("retry-after")), params.signal);
+                await this.sleep(this.computeRetryDelayMs(retries, response.headers.get("retry-after"), 
+                // `details.retryAfterSeconds` is a 429-only backpressure signal
+                // (`workspace_busy` / `queue_full`). Only consult the body on a 429
+                // so a 5xx body can never bypass `maxDelayMs` via this path.
+                response.status === 429 ? payload : undefined), params.signal);
                 continue;
             }
             this.throwForError(response.status, payload, response.headers);
@@ -2201,17 +2276,53 @@ export class RelayFileClient {
         }
         return retries < this.retryOptions.maxRetries;
     }
-    computeRetryDelayMs(retryAttempt, retryAfterHeader) {
+    computeRetryDelayMs(retryAttempt, retryAfterHeader, payload) {
+        // A server-advertised `Retry-After` HEADER is the standard, explicit
+        // signal and takes precedence: parse it first and leave its handling
+        // unchanged (bounded by our own `maxDelayMs`). Only when the header is
+        // absent or unparseable do we consult the body below, so a body hint never
+        // silently overrides a shorter, explicit header the server already sent.
         const retryAfterMs = this.parseRetryAfterMs(retryAfterHeader);
         if (retryAfterMs !== null) {
             return Math.min(this.retryOptions.maxDelayMs, retryAfterMs);
         }
+        // With no usable header, a 429 body can still advertise an explicit
+        // backpressure delay as `details.retryAfterSeconds` (e.g. `workspace_busy`
+        // when the workspace durable object is overloaded, or `queue_full`). Honor
+        // it as an instruction, bounded only by RETRY_AFTER_MAX_MS — NOT truncated
+        // to `maxDelayMs`, which governs our own exponential backoff. Truncating it
+        // (maxDelayMs defaults to 2s vs. a typical 5s advertised delay) retries
+        // into the still-busy resource and exhausts the retry budget.
+        const advertisedMs = this.parseRetryAfterSecondsFromBody(payload);
+        if (advertisedMs !== null) {
+            return Math.max(0, Math.min(RETRY_AFTER_MAX_MS, advertisedMs));
+        }
         const backoff = this.retryOptions.baseDelayMs * Math.pow(2, Math.max(0, retryAttempt - 1));
         const capped = Math.min(this.retryOptions.maxDelayMs, backoff);
         const jitter = this.retryOptions.jitterRatio;
         const factor = 1 + (Math.random() * 2 - 1) * jitter;
         return Math.max(0, Math.round(capped * factor));
     }
+    /**
+     * Extract a server-advertised retry delay from a parsed 429 error body.
+     * Relayfile advertises backpressure delays as `details.retryAfterSeconds`
+     * (in seconds) on `workspace_busy` / `queue_full` responses. Returns
+     * milliseconds, or null when absent/malformed.
+     */
+    parseRetryAfterSecondsFromBody(payload) {
+        if (!payload || typeof payload !== "object") {
+            return null;
+        }
+        const details = payload.details;
+        if (!details || typeof details !== "object") {
+            return null;
+        }
+        const seconds = details.retryAfterSeconds;
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0) {
+            return seconds * 1000;
+        }
+        return null;
+    }
     parseRetryAfterMs(retryAfterHeader) {
         if (!retryAfterHeader) {
             return null;

package/dist/types.d.ts

@@ -416,6 +416,22 @@ export interface LayoutManifest {
 export interface SubscribeOptions {
     coalesce?: "none" | "fire-once";
     coalesceMs?: number;
+    /**
+     * Narrow the server-side event stream to one or more path scopes.
+     *
+     * A **wildcard-free** entry is a DIRECTORY SUBTREE scope: `"/ramp/transactions"`
+     * matches that path AND everything under it. A bare path is NOT treated as an
+     * exact-file match — Relayfile creates descendants under file-looking paths
+     * (e.g. `/linear/issues/ENG-1.json/replies/draft.json`), so a wildcard-free
+     * scope always means "this directory and its subtree".
+     *
+     * To scope to something more precise, pass an explicit glob: a trailing `**`
+     * (`"/ramp/transactions/**"`) for a subtree, or per-segment `*` wildcards
+     * (`"/github/repos/acme/api/pulls/*"`); these are honored verbatim. For an
+     * exact single file, pass that exact path as a glob in the first `subscribe`
+     * argument (`subscribe(globs, ...)`, e.g. `["/linear/issues/ENG-1.json"]`) —
+     * the `globs` list is matched exactly unless it contains a `*`/`**` wildcard.
+     */
     pathScope?: string[];
     from?: "now" | "legacy";
     cursor?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.51",
+  "version": "0.10.53",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.51",
+    "@relayfile/core": "0.10.53",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.51",
-    "@relayfile/mount-darwin-x64": "0.10.51",
-    "@relayfile/mount-linux-arm64": "0.10.51",
-    "@relayfile/mount-linux-x64": "0.10.51"
+    "@relayfile/mount-darwin-arm64": "0.10.53",
+    "@relayfile/mount-darwin-x64": "0.10.53",
+    "@relayfile/mount-linux-arm64": "0.10.53",
+    "@relayfile/mount-linux-x64": "0.10.53"
   },
   "devDependencies": {
     "typescript": "^5.7.3",