@relayfile/sdk 0.6.12 → 0.6.13

package/README.md

@@ -40,12 +40,17 @@ const mountEnv = workspace.mountEnv({
   remotePath: '/notion',
 })
 
-// Secret invite payload for a trusted co-worker agent
-const invite = workspace.agentInvite({
-  agentName: 'review-agent',
-  scopes: ['fs:read', 'relaycast:write'],
+// Secret invite payload for a trusted co-worker agent — same scopes as this
+// workspace's token (no per-invite downscoping).
+const invite = workspace.agentInvite({ agentName: 'review-agent' })
+
+// To grant a strictly narrower set of scopes, mint a fresh JWT via the cloud
+// API. The cloud rejects requests that exceed the calling token's grant.
+const scopedInvite = await workspace.agentInviteScoped({
+  agentName: 'notion-summarizer',
+  scopes: ['relayfile:fs:read:/notion/pages/*'],
 })
-// Never log invite — it contains credential material
+// Never log invites — they contain credential material
 ```
 
 For the full end-to-end journey, failure modes, and acceptance criteria see

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider,
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
-export { WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
+export { WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
 export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";
 export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnWriteHandlerError, type OnWriteOptions } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";

package/dist/onWrite.js

@@ -118,14 +118,31 @@ class OnWriteDispatcher {
         }
         // Token resolution order:
         //  1. options.token (literal or factory) — back-compat for callers that
-        //     mint their own auth.
-        //  2. RELAYFILE_TOKEN env var.
-        //  3. fall through to undefined → RelayFileSync auto-derives from
-        //     `client.getToken()` (the recommended path; same JWT as REST).
-        // (Bug 1 fix: previously, omitting `token` here passed `undefined` and
-        // the WS handshake silently failed with no auth, dropping us into
-        // backwards-walking polling forever.)
-        const token = options.token ?? readEnv("RELAYFILE_TOKEN") ?? undefined;
+        //     mint their own auth out-of-band.
+        //  2. fall through to undefined → RelayFileSync auto-derives from
+        //     `client.getToken()` on every (re)connect. This is the recommended
+        //     path: it is the same JWT the REST surface is using AND it is
+        //     re-resolved on every reconnect, so an expired/rotated token gets
+        //     refreshed automatically by whatever provider the client wraps
+        //     (e.g. WorkspaceHandle's getOrRefreshToken).
+        //
+        // Bug 5: previously this fell through to a `readEnv("RELAYFILE_TOKEN")`
+        // literal when the caller omitted `options.token`. That env value is
+        // captured once at workspace-join time (e.g. by
+        // `WorkspaceHandle.mountEnv()`) and never refreshed, so it expires
+        // ~1 hour later and the WS upgrade then fails with an auth error
+        // (visible only as a JS-layer "ws error" with no successor close,
+        // leaving the dispatcher stalled forever). The env literal also
+        // shadowed the auto-derive fix from PR #96 whenever a caller happened
+        // to have RELAYFILE_TOKEN set in their environment, which is the
+        // common case for any workspace started via mountEnv. Auto-derive must
+        // win over the env literal whenever a client is available.
+        //
+        // The default-client path (constructed by `getDefaultClient()` when
+        // `options.client` is omitted) already wires RELAYFILE_TOKEN into the
+        // client's tokenProvider, so callers that depend on the env-only flow
+        // continue to work — `client.getToken()` returns the env value.
+        const token = options.token;
         this.sync = RelayFileSync.connect({
             client: this.client,
             workspaceId: options.workspaceId,

package/dist/setup-types.d.ts

@@ -67,8 +67,25 @@ export interface WorkspaceMountEnvOptions {
 export type WorkspaceMountEnv = Record<string, string>;
 export interface AgentWorkspaceInviteOptions {
     agentName?: string;
+    relaycastBaseUrl?: string;
+    includeRelayfileToken?: boolean;
+}
+export interface AgentWorkspaceScopedInviteOptions {
+    /**
+     * Scopes to grant on the minted JWT. Must be a subset of the calling
+     * workspace token's grant; the cloud API rejects requests that exceed it.
+     * If omitted, falls back to the join-time scopes (effectively the same as
+     * the sync `agentInvite()`).
+     */
     scopes?: string[];
+    agentName?: string;
+    permissions?: WorkspacePermissions;
     relaycastBaseUrl?: string;
+    /**
+     * Set false to omit `relayfileToken` from the returned invite — useful
+     * when the receiving agent already has a token and only needs the
+     * connection metadata.
+     */
     includeRelayfileToken?: boolean;
 }
 export interface AgentWorkspaceInvite {

package/dist/setup.d.ts

@@ -1,6 +1,6 @@
 import { RelayFileClient, type AccessTokenProvider } from "./client.js";
 import { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
-import { type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type WaitForConnectionOptions, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspacePermissions } from "./setup-types.js";
+import { type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type RelayfileSetupOptions, type WaitForConnectionOptions, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspacePermissions } from "./setup-types.js";
 export { RELAYFILE_SDK_VERSION } from "./version.js";
 interface JoinWorkspaceResponse {
     workspaceId?: string;
@@ -41,7 +41,9 @@ export declare class RelayfileSetup {
     constructor(options?: RelayfileSetupOptions);
     createWorkspace(options?: CreateWorkspaceOptions): Promise<WorkspaceHandle>;
     joinWorkspace(workspaceId: string, options?: JoinWorkspaceOptions): Promise<WorkspaceHandle>;
-    joinWorkspaceResponse(workspaceId: string, options: NormalizedJoinWorkspaceOptions): Promise<ValidatedJoinWorkspaceResponse>;
+    joinWorkspaceResponse(workspaceId: string, options: NormalizedJoinWorkspaceOptions, overrides?: {
+        tokenProvider?: AccessTokenProvider;
+    }): Promise<ValidatedJoinWorkspaceResponse>;
     requestJson(options: CloudRequestOptions): Promise<unknown>;
     getCloudApiUrl(): string;
 }
@@ -65,7 +67,34 @@ export declare class WorkspaceHandle {
     disconnectIntegration(provider: WorkspaceIntegrationProvider, _connectionId?: string): Promise<void>;
     getToken(): string;
     mountEnv(options?: WorkspaceMountEnvOptions): WorkspaceMountEnv;
+    /**
+     * Build an invite that hands a peer agent the calling workspace's existing
+     * JWT and metadata. The invite carries the SAME token this handle holds,
+     * with the SAME scopes — there is no per-invite downscoping. Use
+     * {@link agentInviteScoped} when the receiver should have a strictly
+     * narrower set of scopes than this workspace.
+     */
     agentInvite(options?: AgentWorkspaceInviteOptions): AgentWorkspaceInvite;
+    /**
+     * Mint a fresh, downscoped relayfile JWT for a peer agent and return an
+     * invite carrying that token. Round-trips through the cloud join endpoint
+     * (`POST /api/v1/workspaces/{id}/join`), which signs a new JWT whose
+     * `scopes` claim is the requested subset of this workspace's grant. The
+     * cloud API rejects requests that exceed the calling workspace's scopes.
+     *
+     * Prefer this over {@link agentInvite} whenever the receiver should not
+     * inherit the full workspace token's reach (e.g. one agent that only needs
+     * `relayfile:fs:read:/notion/pages/*`). The caller's token is unaffected;
+     * a separate JWT is issued for the invitee.
+     *
+     * @example
+     * const invite = await workspace.agentInviteScoped({
+     *   agentName: 'notion-summarizer',
+     *   scopes: ['relayfile:fs:read:/notion/pages/*'],
+     * })
+     * // invite.relayfileToken is a JWT with scopes=['relayfile:fs:read:/notion/pages/*']
+     */
+    agentInviteScoped(options?: AgentWorkspaceScopedInviteOptions): Promise<AgentWorkspaceInvite>;
     refreshToken(): Promise<void>;
     private performRefreshToken;
     private getOrRefreshToken;

package/dist/setup.js

@@ -99,7 +99,7 @@ export class RelayfileSetup {
             joinOptions
         });
     }
-    async joinWorkspaceResponse(workspaceId, options) {
+    async joinWorkspaceResponse(workspaceId, options, overrides = {}) {
         return validateJoinWorkspaceResponse(await this.requestJson({
             operation: "joinWorkspace",
             method: "POST",
@@ -108,7 +108,8 @@ export class RelayfileSetup {
                 agentName: options.agentName,
                 scopes: [...options.scopes],
                 permissions: clonePermissions(options.permissions)
-            })
+            }),
+            tokenProvider: overrides.tokenProvider
         }));
     }
     async requestJson(options) {
@@ -316,6 +317,13 @@ export class WorkspaceHandle {
             RELAY_BASE_URL: relaycastBaseUrl
         });
     }
+    /**
+     * Build an invite that hands a peer agent the calling workspace's existing
+     * JWT and metadata. The invite carries the SAME token this handle holds,
+     * with the SAME scopes — there is no per-invite downscoping. Use
+     * {@link agentInviteScoped} when the receiver should have a strictly
+     * narrower set of scopes than this workspace.
+     */
     agentInvite(options = {}) {
         const relaycastBaseUrl = this.resolveRelaycastBaseUrl(options.relaycastBaseUrl);
         return compactObject({
@@ -325,14 +333,68 @@ export class WorkspaceHandle {
             relaycastApiKey: this.info.relaycastApiKey,
             relaycastBaseUrl,
             agentName: options.agentName ?? this._joinOptions.agentName,
-            scopes: options.scopes && options.scopes.length > 0
-                ? [...options.scopes]
-                : [...this._joinOptions.scopes],
+            scopes: [...this._joinOptions.scopes],
             relayfileToken: options.includeRelayfileToken === false ? undefined : this.getToken(),
             createdAt: this.info.createdAt,
             name: this.info.name
         });
     }
+    /**
+     * Mint a fresh, downscoped relayfile JWT for a peer agent and return an
+     * invite carrying that token. Round-trips through the cloud join endpoint
+     * (`POST /api/v1/workspaces/{id}/join`), which signs a new JWT whose
+     * `scopes` claim is the requested subset of this workspace's grant. The
+     * cloud API rejects requests that exceed the calling workspace's scopes.
+     *
+     * Prefer this over {@link agentInvite} whenever the receiver should not
+     * inherit the full workspace token's reach (e.g. one agent that only needs
+     * `relayfile:fs:read:/notion/pages/*`). The caller's token is unaffected;
+     * a separate JWT is issued for the invitee.
+     *
+     * @example
+     * const invite = await workspace.agentInviteScoped({
+     *   agentName: 'notion-summarizer',
+     *   scopes: ['relayfile:fs:read:/notion/pages/*'],
+     * })
+     * // invite.relayfileToken is a JWT with scopes=['relayfile:fs:read:/notion/pages/*']
+     */
+    async agentInviteScoped(options = {}) {
+        const requestedScopes = options.scopes && options.scopes.length > 0
+            ? [...options.scopes]
+            : [...this._joinOptions.scopes];
+        const agentName = options.agentName ?? this._joinOptions.agentName;
+        const permissions = options.permissions ?? this._joinOptions.permissions;
+        // Authenticate the join with this handle's workspace JWT. Without it,
+        // the cloud cannot verify that requestedScopes ⊆ caller's grant, and
+        // anonymous (or permissive) endpoints would silently mint a wide token —
+        // exactly the failure this method is designed to prevent. The setup-
+        // level accessToken (used for createWorkspace/joinWorkspace at the
+        // workspace-bootstrap layer) is the wrong identity here; we want the
+        // workspace JWT itself to be the parent the cloud downscopes from.
+        const joinResponse = await this._setup.joinWorkspaceResponse(this.workspaceId, {
+            agentName,
+            scopes: requestedScopes,
+            permissions
+        }, { tokenProvider: async () => this.getOrRefreshToken() });
+        // Prefer a relaycastBaseUrl returned by the cloud over the cached one —
+        // the cloud is authoritative if it shipped a fresher value with the
+        // join response.
+        const relaycastBaseUrl = this.resolveRelaycastBaseUrl(options.relaycastBaseUrl ?? joinResponse.relaycastBaseUrl);
+        return compactObject({
+            workspaceId: this.workspaceId,
+            cloudApiUrl: this._setup.getCloudApiUrl(),
+            relayfileUrl: joinResponse.relayfileUrl ?? this.info.relayfileUrl,
+            relaycastApiKey: joinResponse.relaycastApiKey ?? this.info.relaycastApiKey,
+            relaycastBaseUrl,
+            agentName,
+            scopes: requestedScopes,
+            relayfileToken: options.includeRelayfileToken === false
+                ? undefined
+                : joinResponse.token,
+            createdAt: this.info.createdAt,
+            name: this.info.name
+        });
+    }
     async refreshToken() {
         if (!this._refreshPromise) {
             this._refreshPromise = this.performRefreshToken();

package/dist/sync.d.ts

@@ -70,6 +70,7 @@ type RelayFileSyncHandlerMap = {
     close: (event: CloseEvent) => void;
     pong: (event: RelayFileSyncPong) => void;
 };
+export declare function normalizeError(event: unknown): unknown;
 export declare class RelayFileSync {
     private readonly client;
     private readonly workspaceId;
@@ -95,6 +96,8 @@ export declare class RelayFileSync {
     private pollingPromise?;
     private reconnectTimer?;
     private pingTimer?;
+    private errorRecoveryTimer?;
+    private currentSocketHasOpened;
     private lastFrameAt;
     private lastPingSentAt;
     private reconnectAttempts;
@@ -122,6 +125,7 @@ export declare class RelayFileSync {
     private setState;
     private clearReconnectTimer;
     private clearPingTimer;
+    private clearErrorRecoveryTimer;
     private emit;
 }
 export {};

package/dist/sync.js

@@ -7,6 +7,11 @@ const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
 // (the events API is itself capped at ~1000 per page), small enough to keep
 // memory bounded across long-lived processes.
 const POLLING_DEDUPE_CACHE_LIMIT = 2048;
+// How long we wait after a WS `error` for the matching `close` to arrive
+// before forcing a recovery. Some implementations (notably Node's built-in
+// WebSocket on auth-rejected upgrades) emit `error` with no successor
+// `close`; without this watchdog the dispatcher stalls indefinitely.
+const ERROR_TO_CLOSE_GRACE_MS = 250;
 function warnPollingFallback(reason, cause) {
     // Always-on warning (NOT gated by RELAYFILE_SDK_DEBUG) because silent
     // degradation to polling has historically masked real auth/connectivity
@@ -85,8 +90,20 @@ function normalizeFilesystemEvent(message) {
         timestamp: message.timestamp ?? message.ts ?? new Date().toISOString()
     };
 }
-function normalizeError(event) {
-    return event instanceof ErrorEvent && event.error instanceof Error ? event.error : event;
+// Exported for testing. `ErrorEvent` is a DOM/browser global that is not
+// available on every Node 22 runtime (for example Node 22.22.1), so we
+// duck-type the shape rather than referencing the global directly. Using
+// `instanceof ErrorEvent` here would throw
+// `ReferenceError: ErrorEvent is not defined` whenever the underlying
+// WebSocket emits an error event under Node.
+export function normalizeError(event) {
+    if (event !== null &&
+        typeof event === "object" &&
+        "error" in event &&
+        event.error instanceof Error) {
+        return event.error;
+    }
+    return event;
 }
 export class RelayFileSync {
     client;
@@ -123,6 +140,16 @@ export class RelayFileSync {
     pollingPromise;
     reconnectTimer;
     pingTimer;
+    // See ERROR_TO_CLOSE_GRACE_MS: armed in the WS `error` handler, cleared
+    // by the matching `close` (or by `stop()`); fires forceReconnect when
+    // the OS layer fails to deliver a close after the error.
+    errorRecoveryTimer;
+    // Tracks whether this.socket has reached the OPEN state. Reset every
+    // time we attach to a fresh socket; flipped true in the `open` handler.
+    // The error watchdog checks this so that a pre-open failure (auth reject,
+    // proxy RST during handshake, etc.) routes to polling rather than an
+    // infinite reconnect loop against a server that won't accept the WS.
+    currentSocketHasOpened = false;
     // Tracks the last time *any* WebSocket frame was received (event, pong, or
     // otherwise). The watchdog uses this to detect silent socket death.
     lastFrameAt = 0;
@@ -212,6 +239,7 @@ export class RelayFileSync {
         this.stopped = true;
         this.clearReconnectTimer();
         this.clearPingTimer();
+        this.clearErrorRecoveryTimer();
         const socket = this.socket;
         this.socket = undefined;
         if (socket) {
@@ -309,10 +337,12 @@ export class RelayFileSync {
             return;
         }
         this.socket = socket;
+        this.currentSocketHasOpened = false;
         socket.addEventListener("open", (event) => {
             if (this.socket !== socket || this.stopped) {
                 return;
             }
+            this.currentSocketHasOpened = true;
             this.reconnectAttempts = 0;
             // Reset frame/ping bookkeeping for the freshly opened socket so the
             // watchdog has a clean baseline. lastPingSentAt=0 disables the pong
@@ -339,6 +369,46 @@ export class RelayFileSync {
             }
             debugLog("ws error", event);
             this.emit("error", normalizeError(event));
+            // Per WHATWG, an `error` should be followed by a `close` and the
+            // close handler is the one that schedules reconnect / starts polling.
+            // In practice though, some WebSocket implementations (notably Node's
+            // built-in/undici WebSocket on auth-rejected upgrades, and some
+            // proxies that abruptly RST after the upgrade) deliver `error` with
+            // no successor `close`. The dispatcher would then sit silent forever
+            // — exactly the failure mode in the cortical-demo bug report (WS
+            // error fires, no close, no reconnect, no polling fallback).
+            //
+            // To recover, we arm a short grace timer here. If the close handler
+            // for THIS socket runs before it fires (the well-behaved path), it
+            // clears the timer. Otherwise the timer fires, sees the socket is
+            // still current, and forces the same recovery path the close handler
+            // would have taken (reconnect or polling). The grace window is
+            // intentionally short — by the time `error` has fired, the socket
+            // is already known-bad; we are only giving the OS layer a beat to
+            // deliver its close.
+            if (this.errorRecoveryTimer) {
+                return;
+            }
+            this.errorRecoveryTimer = setTimeout(() => {
+                this.errorRecoveryTimer = undefined;
+                if (this.stopped || this.socket !== socket) {
+                    return;
+                }
+                // If the socket never reached OPEN, this is a handshake-stage
+                // failure (auth rejection on upgrade, proxy RST, server cold
+                // start). Reconnecting in a tight loop just retries the same
+                // failing handshake. Drop straight into polling instead — that
+                // path tolerates 401/403/timeout and surfaces the error to the
+                // caller without burning the loop.
+                const preOpen = !this.currentSocketHasOpened;
+                debugLog("ws error with no successor close — forcing recovery", {
+                    workspaceId: this.workspaceId,
+                    preOpen
+                });
+                this.forceReconnect(socket, preOpen ? "ws-error-pre-open" : "ws-error-no-close", {
+                    preferPolling: preOpen
+                });
+            }, ERROR_TO_CLOSE_GRACE_MS);
         });
         socket.addEventListener("close", (event) => {
             // forceReconnect (called from the watchdog or a failed ping send) nulls
@@ -358,6 +428,7 @@ export class RelayFileSync {
             }
             this.socket = undefined;
             this.clearPingTimer();
+            this.clearErrorRecoveryTimer();
             debugLog("ws close", { code: event?.code, reason: event?.reason, stopped: this.stopped });
             this.emit("close", event);
             if (this.stopped) {
@@ -588,8 +659,14 @@ export class RelayFileSync {
     // no-ops via the `this.socket !== socket` guards) and trigger the standard
     // reconnect path. Catches errors from `close()` because some socket
     // implementations throw when closing an already-broken connection.
-    forceReconnect(socket, reason) {
+    //
+    // `options.preferPolling` lets the caller force the polling fallback even
+    // when reconnect is enabled. Used by the error watchdog when the failed
+    // socket never reached OPEN (handshake-stage failure) — retrying the WS
+    // upgrade in a loop won't help when the server is rejecting at the upgrade.
+    forceReconnect(socket, reason, options) {
         this.clearPingTimer();
+        this.clearErrorRecoveryTimer();
         if (this.socket === socket) {
             this.socket = undefined;
         }
@@ -603,8 +680,8 @@ export class RelayFileSync {
             this.setState("closed");
             return;
         }
-        if (!this.reconnect.enabled) {
-            this.startPolling("forced-reconnect-no-retry", reason);
+        if (!this.reconnect.enabled || options?.preferPolling) {
+            this.startPolling(options?.preferPolling ? "forced-polling-pre-open" : "forced-reconnect-no-retry", reason);
             return;
         }
         this.scheduleReconnect();
@@ -670,6 +747,12 @@ export class RelayFileSync {
             this.pingTimer = undefined;
         }
     }
+    clearErrorRecoveryTimer() {
+        if (this.errorRecoveryTimer) {
+            clearTimeout(this.errorRecoveryTimer);
+            this.errorRecoveryTimer = undefined;
+        }
+    }
     emit(event, payload) {
         const handlers = this.handlers[event];
         for (const handler of handlers) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.6.12"
+    "@relayfile/core": "0.6.13"
   },
   "devDependencies": {
     "typescript": "^5.7.3",