@relayfile/sdk 0.6.11 → 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/client.d.ts

@@ -51,6 +51,18 @@ export declare class RelayFileClient {
     private readonly userAgent?;
     private readonly retryOptions;
     constructor(options: RelayFileClientOptions);
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    getToken(): Promise<string>;
     listTree(workspaceId: string, options?: ListTreeOptions): Promise<TreeResponse>;
     readFile(workspaceId: string, path: string, correlationId?: string, signal?: AbortSignal): Promise<FileReadResponse>;
     readFile(input: ReadFileInput): Promise<FileReadResponse>;

package/dist/client.js

@@ -171,6 +171,20 @@ export class RelayFileClient {
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);
     }
+    /**
+     * Resolve the current access token via the configured token provider.
+     *
+     * Components that need a fresh JWT for out-of-band auth (the WebSocket
+     * upgrade handshake, signed URLs, downstream services that proxy Relayfile
+     * tokens) should call this on every connection rather than caching the
+     * value, so token rotation/refresh propagates without restart.
+     *
+     * Always returns a Promise so callers don't need to special-case the
+     * sync-vs-async tokenProvider shapes.
+     */
+    async getToken() {
+        return resolveToken(this.tokenProvider);
+    }
     async listTree(workspaceId, options = {}) {
         const query = buildQuery({
             path: options.path ?? "/",

package/dist/index.d.ts

@@ -2,8 +2,8 @@ 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 { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState } from "./sync.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";
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";

package/dist/onWrite.d.ts

@@ -1,6 +1,6 @@
 import type { WriteEvent, WriteEventOperation } from "@relayfile/core";
 import { RelayFileClient } from "./client.js";
-import { type RelayFileSyncSocket } from "./sync.js";
+import { type RelayFileSyncSocket, type RelayFileSyncTokenProvider } from "./sync.js";
 export type OnWriteHandler = (event: WriteEvent) => void | Promise<void>;
 export interface OnWriteHandlerError {
     pattern: string;
@@ -17,10 +17,30 @@ export interface OnWriteOptions {
     operations?: WriteEventOperation[];
     signal?: AbortSignal;
     baseUrl?: string;
-    token?: string;
+    /**
+     * Optional WebSocket auth override. Accepts the same `string | () =>
+     * string | Promise<string>` shape as the underlying sync.
+     *
+     * If omitted, onWrite auto-derives WS auth from `client.getToken()` — the
+     * same JWT the REST API is using — and re-resolves it on every reconnect
+     * so token rotation propagates without restart. **Most callers should
+     * leave this unset.** Passing a literal string is back-compat for older
+     * code; passing a factory is the right shape for production.
+     */
+    token?: RelayFileSyncTokenProvider;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
     pingIntervalMs?: number;
     pongTimeoutMs?: number;
+    /**
+     * Notification hook fired when the underlying sync degrades to HTTP
+     * polling because the WebSocket failed to open. Useful for surfacing a
+     * "live updates paused" banner. The SDK also `console.warn`s and emits
+     * an `error` regardless.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export declare function pathMatches(pattern: string, path: string): boolean;
 export declare function onWrite(pattern: string, handler: OnWriteHandler, options?: OnWriteOptions): () => void;

package/dist/onWrite.js

@@ -69,7 +69,8 @@ export function onWrite(pattern, handler, options = {}) {
         token: options.token,
         webSocketFactory: options.webSocketFactory,
         pingIntervalMs: options.pingIntervalMs,
-        pongTimeoutMs: options.pongTimeoutMs
+        pongTimeoutMs: options.pongTimeoutMs,
+        onPollingFallback: options.onPollingFallback
     });
     debugLog("registered", { id: registration.id, pattern: normalizedPattern, workspaceId });
     return () => {
@@ -115,11 +116,38 @@ class OnWriteDispatcher {
         if (this.sync) {
             return;
         }
+        // Token resolution order:
+        //  1. options.token (literal or factory) — back-compat for callers that
+        //     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,
             baseUrl: options.baseUrl ?? readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL,
-            token: options.token ?? readEnv("RELAYFILE_TOKEN"),
+            token,
             reconnect: {
                 minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
                 maxDelayMs: DEFAULT_RECONNECT_MAX_DELAY_MS
@@ -127,6 +155,7 @@ class OnWriteDispatcher {
             webSocketFactory: options.webSocketFactory,
             pingIntervalMs: options.pingIntervalMs,
             pongTimeoutMs: options.pongTimeoutMs,
+            onPollingFallback: options.onPollingFallback,
             onEvent: (event) => {
                 void this.dispatch(event);
             }

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

@@ -1,5 +1,13 @@
 import type { RelayFileClient } from "./client.js";
 import type { FilesystemEvent } from "./types.js";
+/**
+ * WebSocket auth source for {@link RelayFileSyncOptions.token}.
+ *
+ * The function form is preferred for production: it is re-invoked on every
+ * (re)connect, so token rotation/refresh propagates without restarting the
+ * sync. The plain string form is kept for backward compatibility and tests.
+ */
+export type RelayFileSyncTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
 export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
 export interface RelayFileSyncPong {
     type: "pong";
@@ -14,7 +22,16 @@ export interface RelayFileSyncOptions {
     client: RelayFileClient;
     workspaceId: string;
     baseUrl?: string;
-    token?: string;
+    /**
+     * WebSocket auth token. Accepts either a literal string or a (sync/async)
+     * factory. The factory form is re-invoked on every (re)connect so token
+     * rotation propagates transparently.
+     *
+     * If omitted, sync resolves the token via `client.getToken()` on each
+     * connect — i.e. the same JWT the REST methods are using. Callers should
+     * normally NOT pass this and let it inherit from the client.
+     */
+    token?: RelayFileSyncTokenProvider;
     cursor?: string;
     preferPolling?: boolean;
     pollIntervalMs?: number;
@@ -24,6 +41,17 @@ export interface RelayFileSyncOptions {
     signal?: AbortSignal;
     webSocketFactory?: (url: string) => RelayFileSyncSocket;
     onEvent?: (event: FilesystemEvent) => void;
+    /**
+     * Notification hook invoked when the sync degrades to HTTP polling because
+     * the WebSocket failed to open or was rejected by the server. Live events
+     * will be delayed by `pollIntervalMs` while in this mode. Use this to
+     * surface a UI banner or alert; the SDK also emits `console.warn` and an
+     * `error` event regardless of whether this is wired.
+     */
+    onPollingFallback?: (info: {
+        reason: string;
+        cause?: unknown;
+    }) => void;
 }
 export interface RelayFileSyncSocket {
     addEventListener(type: "open", handler: (event: Event) => void): void;
@@ -42,11 +70,12 @@ 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;
     private readonly baseUrl?;
-    private readonly token?;
+    private readonly tokenProvider?;
     private readonly pollIntervalMs;
     private readonly pingIntervalMs;
     private readonly pongTimeoutMs;
@@ -54,15 +83,21 @@ export declare class RelayFileSync {
     private readonly preferPolling;
     private readonly signal?;
     private readonly webSocketFactory;
+    private readonly onPollingFallback?;
     private readonly handlers;
     private state;
     private cursor?;
+    private readonly polledEventIds;
+    private readonly polledEventOrder;
+    private firstPollComplete;
     private socket?;
     private started;
     private stopped;
     private pollingPromise?;
     private reconnectTimer?;
     private pingTimer?;
+    private errorRecoveryTimer?;
+    private currentSocketHasOpened;
     private lastFrameAt;
     private lastPingSentAt;
     private reconnectAttempts;
@@ -74,9 +109,12 @@ export declare class RelayFileSync {
     stop(): Promise<void>;
     on<TEventName extends RelayFileSyncEventName>(event: TEventName, handler: RelayFileSyncHandlerMap[TEventName]): () => void;
     private shouldUsePolling;
+    private resolveWsTokenMaybeSync;
     private openWebSocket;
+    private openWebSocketWithToken;
     private startPolling;
     private pollLoop;
+    private rememberPolledEvent;
     private handleSocketMessage;
     private startPingLoop;
     private forceReconnect;
@@ -87,6 +125,7 @@ export declare class RelayFileSync {
     private setState;
     private clearReconnectTimer;
     private clearPingTimer;
+    private clearErrorRecoveryTimer;
     private emit;
 }
 export {};

package/dist/sync.js

@@ -2,6 +2,28 @@ const DEFAULT_POLL_INTERVAL_MS = 5000;
 const DEFAULT_PING_INTERVAL_MS = 30000;
 const DEFAULT_RECONNECT_MIN_DELAY_MS = 250;
 const DEFAULT_RECONNECT_MAX_DELAY_MS = 5000;
+// Cap on the dedupe cache used in polling mode. Sized large enough that no
+// realistic workspace burst can churn through it within one poll interval
+// (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
+    // bugs for hours at a time. Customers running the SDK in a Node service
+    // see the warning in their normal logs without any opt-in.
+    if (typeof console === "undefined" || typeof console.warn !== "function") {
+        return;
+    }
+    const detail = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : "";
+    const suffix = detail ? ` (${reason}: ${detail})` : ` (${reason})`;
+    console.warn(`[relayfile-sdk] WebSocket connect failed; falling back to HTTP polling. Live events will be delayed.${suffix}`);
+}
 const debugEnabled = (() => {
     try {
         const value = globalThis.process?.env?.RELAYFILE_SDK_DEBUG;
@@ -68,14 +90,29 @@ 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;
     workspaceId;
     baseUrl;
-    token;
+    // Resolved on every connect attempt (string form is wrapped into a constant
+    // factory at construction time). `undefined` means "fall back to
+    // client.getToken()" — same JWT the REST methods use.
+    tokenProvider;
     pollIntervalMs;
     pingIntervalMs;
     pongTimeoutMs;
@@ -83,6 +120,7 @@ export class RelayFileSync {
     preferPolling;
     signal;
     webSocketFactory;
+    onPollingFallback;
     handlers = {
         event: new Set(),
         error: new Set(),
@@ -93,12 +131,25 @@ export class RelayFileSync {
     };
     state = "idle";
     cursor;
+    polledEventIds = new Set();
+    polledEventOrder = [];
+    firstPollComplete = false;
     socket;
     started = false;
     stopped = false;
     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;
@@ -112,8 +163,21 @@ export class RelayFileSync {
         this.client = options.client;
         this.workspaceId = options.workspaceId;
         this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
-        this.token = options.token;
+        // Normalize token into a factory. `undefined` is preserved so the open
+        // path knows to fall back to `client.getToken()` (the recommended path —
+        // the WebSocket then auto-uses the same JWT the REST API is using).
+        if (options.token === undefined) {
+            this.tokenProvider = undefined;
+        }
+        else if (typeof options.token === "function") {
+            this.tokenProvider = options.token;
+        }
+        else {
+            const literal = options.token;
+            this.tokenProvider = () => literal;
+        }
         this.cursor = options.cursor;
+        this.onPollingFallback = options.onPollingFallback;
         this.pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
         this.pingIntervalMs = Math.max(1, Math.floor(options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS));
         // Default the pong timeout to 2x ping interval so a single missed pong
@@ -161,7 +225,9 @@ export class RelayFileSync {
         }
         this.started = true;
         if (this.shouldUsePolling()) {
-            this.startPolling();
+            // Caller explicitly opted into polling, or there's no baseUrl to
+            // upgrade to wss. NOT a fallback — no warn here.
+            this.startPolling("explicit");
             return;
         }
         this.openWebSocket(false);
@@ -173,6 +239,7 @@ export class RelayFileSync {
         this.stopped = true;
         this.clearReconnectTimer();
         this.clearPingTimer();
+        this.clearErrorRecoveryTimer();
         const socket = this.socket;
         this.socket = undefined;
         if (socket) {
@@ -193,9 +260,63 @@ export class RelayFileSync {
         };
     }
     shouldUsePolling() {
-        return this.preferPolling || !this.baseUrl || !this.token;
+        // Token availability is no longer required up-front — the WS opener
+        // resolves it on demand from either `options.token` (a literal/factory)
+        // or `client.getToken()`. We only force polling when the caller asked
+        // for it or there is no baseUrl to derive a wss URL from.
+        return this.preferPolling || !this.baseUrl;
+    }
+    // Resolve a token for the WS upgrade. Returns either a string directly
+    // (sync fast-path; preserves the synchronous "start() → factory called"
+    // contract that pre-existed Bug 1's fix) or a Promise (async slow-path;
+    // factory is invoked on the next microtask). `undefined` means "no token
+    // available — the server may still accept the upgrade if it's configured
+    // for unauthenticated mode in tests/local-dev".
+    resolveWsTokenMaybeSync() {
+        if (this.tokenProvider) {
+            // Most production providers return synchronously (JWT pulled from a
+            // mutable cell that a refresh task updates in the background), so the
+            // sync path is the common case.
+            return this.tokenProvider();
+        }
+        // Auto-derive from the client's tokenProvider — the same JWT the REST
+        // surface is using. Bug 1 fix: callers no longer have to thread
+        // `token: await client.tokenProvider()` through every onWrite() call.
+        // client.getToken is always async (returns a Promise), so we land on
+        // the slow path here. That's fine: the WS open is async anyway.
+        return this.client.getToken();
     }
     openWebSocket(isReconnect) {
+        if (this.stopped) {
+            return;
+        }
+        this.setState(isReconnect ? "reconnecting" : "connecting");
+        // Resolve a fresh token on every (re)connect attempt. This is what
+        // makes mid-session token rotation transparent: the watchdog/close
+        // handler reconnects, we re-call the factory, and the new socket comes
+        // up with the new JWT. (Bug 4: pre-fix, the token was captured once at
+        // construction and a 4001/auth close on rotation triggered an infinite
+        // reconnect loop with the stale token.)
+        let resolved;
+        try {
+            resolved = this.resolveWsTokenMaybeSync();
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+            this.startPolling("token-resolution-failed", error);
+            return;
+        }
+        if (resolved && typeof resolved.then === "function") {
+            // Async path. The factory call gets deferred to the next microtask.
+            resolved.then((token) => this.openWebSocketWithToken(token), (error) => {
+                this.emit("error", error instanceof Error ? error : new Error("Failed to resolve WebSocket auth token."));
+                this.startPolling("token-resolution-failed", error);
+            });
+            return;
+        }
+        this.openWebSocketWithToken(resolved);
+    }
+    openWebSocketWithToken(token) {
         if (this.stopped) {
             return;
         }
@@ -203,24 +324,25 @@ export class RelayFileSync {
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         // Pass token in query string — the server authenticates during the HTTP
         // upgrade handshake via r.URL.Query().Get("token").
-        if (this.token) {
-            url.searchParams.set("token", this.token);
+        if (token) {
+            url.searchParams.set("token", token);
         }
-        this.setState(isReconnect ? "reconnecting" : "connecting");
         let socket;
         try {
             socket = this.webSocketFactory(url.toString());
         }
         catch (error) {
             this.emit("error", error instanceof Error ? error : new Error("Failed to create WebSocket connection."));
-            this.startPolling();
+            this.startPolling("ws-factory-threw", error);
             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
@@ -247,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
@@ -266,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) {
@@ -273,16 +436,29 @@ export class RelayFileSync {
                 return;
             }
             if (!this.reconnect.enabled) {
-                this.startPolling();
+                this.startPolling("ws-closed-no-reconnect", { code: event?.code, reason: event?.reason });
                 return;
             }
             this.scheduleReconnect();
         });
     }
-    startPolling() {
+    startPolling(reason = "fallback", cause) {
         if (this.pollingPromise || this.stopped) {
             return;
         }
+        // Always-on warning + structured callback whenever we drop into polling
+        // *involuntarily*. `explicit` means the caller asked for it (preferPolling
+        // or no baseUrl) and we stay quiet — anything else is a real degradation
+        // signal that previously took hours to detect.
+        if (reason !== "explicit") {
+            warnPollingFallback(reason, cause);
+            try {
+                this.onPollingFallback?.({ reason, cause });
+            }
+            catch (error) {
+                debugLog("onPollingFallback handler threw", error);
+            }
+        }
         this.setState("polling");
         this.pollingPromise = this.pollLoop().finally(() => {
             this.pollingPromise = undefined;
@@ -298,16 +474,58 @@ export class RelayFileSync {
                 throw createAbortError();
             }
             try {
-                const response = await this.client.getEvents(this.workspaceId, {
-                    cursor: this.cursor,
-                    signal: this.signal
-                });
+                // The current server implementation paginates events from oldest to
+                // newest. Empty cursor starts at index 0, and nextCursor advances
+                // forward through history. To avoid replaying the whole event log on
+                // startup while still preserving live forward progress, the first poll
+                // drains to the tip and seeds `this.cursor` without emitting. Later
+                // polls resume from that live cursor and emit only newly appended
+                // events.
+                let cursor = this.cursor;
+                let latestCursor = cursor;
+                const pending = [];
+                for (;;) {
+                    const response = await this.client.getEvents(this.workspaceId, {
+                        cursor,
+                        limit: 1000,
+                        signal: this.signal
+                    });
+                    const events = response.events ?? [];
+                    if (!this.firstPollComplete) {
+                        for (const event of events) {
+                            this.rememberPolledEvent(event.eventId);
+                        }
+                    }
+                    else {
+                        for (const event of events) {
+                            if (!event.eventId || this.polledEventIds.has(event.eventId)) {
+                                continue;
+                            }
+                            this.rememberPolledEvent(event.eventId);
+                            pending.push(event);
+                        }
+                    }
+                    const nextCursor = response.nextCursor || null;
+                    if (events.length > 0) {
+                        latestCursor = events[events.length - 1]?.eventId ?? latestCursor;
+                    }
+                    if (nextCursor) {
+                        latestCursor = nextCursor;
+                    }
+                    if (!nextCursor || nextCursor === cursor) {
+                        break;
+                    }
+                    cursor = nextCursor;
+                }
                 retryAttempt = 0;
-                for (const event of response.events) {
-                    this.emit("event", event);
+                this.cursor = latestCursor;
+                if (!this.firstPollComplete) {
+                    this.firstPollComplete = true;
                 }
-                if (response.nextCursor) {
-                    this.cursor = response.nextCursor;
+                else {
+                    for (const event of pending) {
+                        this.emit("event", event);
+                    }
                 }
                 await this.sleep(this.pollIntervalMs);
             }
@@ -322,6 +540,19 @@ export class RelayFileSync {
             }
         }
     }
+    rememberPolledEvent(eventId) {
+        if (!eventId || this.polledEventIds.has(eventId)) {
+            return;
+        }
+        this.polledEventIds.add(eventId);
+        this.polledEventOrder.push(eventId);
+        while (this.polledEventOrder.length > POLLING_DEDUPE_CACHE_LIMIT) {
+            const evicted = this.polledEventOrder.shift();
+            if (evicted) {
+                this.polledEventIds.delete(evicted);
+            }
+        }
+    }
     handleSocketMessage(event) {
         if (typeof event.data !== "string") {
             return;
@@ -428,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;
         }
@@ -443,8 +680,8 @@ export class RelayFileSync {
             this.setState("closed");
             return;
         }
-        if (!this.reconnect.enabled) {
-            this.startPolling();
+        if (!this.reconnect.enabled || options?.preferPolling) {
+            this.startPolling(options?.preferPolling ? "forced-polling-pre-open" : "forced-reconnect-no-retry", reason);
             return;
         }
         this.scheduleReconnect();
@@ -510,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.11",
+  "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.11"
+    "@relayfile/core": "0.6.13"
   },
   "devDependencies": {
     "typescript": "^5.7.3",