@relayfile/sdk 0.8.9 → 0.8.11

package/dist/client.d.ts

@@ -55,6 +55,9 @@ export interface WebSocketConnection {
 }
 export interface ConnectWebSocketOptions {
     token?: string;
+    from?: "now" | "legacy";
+    cursor?: string;
+    paths?: string[];
     onEvent?: (event: FilesystemEvent) => void;
 }
 interface ProactiveRequestContext {

package/dist/client.js

@@ -318,6 +318,14 @@ class RelayFileChangeSubscription {
         }
         await drain;
     }
+    serverPathFilters() {
+        const filters = new Set();
+        const patterns = this.pathScopes ?? this.globPatterns;
+        for (const pattern of patterns) {
+            filters.add(`/${pattern.join("/")}`);
+        }
+        return Array.from(filters);
+    }
     matches(path) {
         const pathSegments = normalizeChangePath(path);
         const matchesGlob = this.globPatterns.some((pattern) => matchChangeSegments(pattern, pathSegments));
@@ -353,18 +361,21 @@ class RelayFileChangeStreamManager {
     workspaceId;
     token;
     baseUrl;
+    startOptions;
     subscriptions = new Set();
     openHandleCount = 0;
     sync;
+    activePathFilterKey;
     readyResolved = false;
     readyInternal;
     resolveReady;
     rejectReady;
-    constructor(client, workspaceId, token, baseUrl) {
+    constructor(client, workspaceId, token, baseUrl, startOptions) {
         this.client = client;
         this.workspaceId = workspaceId;
         this.token = token;
         this.baseUrl = baseUrl;
+        this.startOptions = startOptions;
         this.readyInternal = new Promise((resolve, reject) => {
             this.resolveReady = resolve;
             this.rejectReady = reject;
@@ -376,22 +387,26 @@ class RelayFileChangeStreamManager {
     addSubscription(globs, onChange, options) {
         const subscription = new RelayFileChangeSubscription(this, globs, onChange, options);
         this.subscriptions.add(subscription);
+        this.restartIfPathScopeChanged();
         this.ensureStarted();
         return {
             unsubscribe: async () => {
                 this.subscriptions.delete(subscription);
                 await subscription.close();
+                this.restartIfPathScopeChanged();
                 await this.maybeStop();
             }
         };
     }
     open() {
         this.openHandleCount += 1;
+        this.restartIfPathScopeChanged();
         this.ensureStarted();
         return {
             ready: this.ready,
             unsubscribe: async () => {
                 this.openHandleCount = Math.max(0, this.openHandleCount - 1);
+                this.restartIfPathScopeChanged();
                 await this.maybeStop();
             }
         };
@@ -429,11 +444,16 @@ class RelayFileChangeStreamManager {
         if (this.sync) {
             return;
         }
+        const paths = this.serverPathFilters();
+        this.activePathFilterKey = paths.join("\n");
         const sync = new RelayFileSync({
             client: this.client,
             workspaceId: this.workspaceId,
             baseUrl: this.baseUrl,
             token: this.token,
+            from: this.startOptions.from,
+            cursor: this.startOptions.cursor,
+            paths,
             onPollingFallback: () => {
                 this.resolveReadyOnce();
             }
@@ -462,6 +482,34 @@ class RelayFileChangeStreamManager {
             this.resolveReadyOnce();
         }
     }
+    restartIfPathScopeChanged() {
+        if (!this.sync) {
+            return;
+        }
+        const nextKey = this.serverPathFilters().join("\n");
+        const currentKey = this.activePathFilterKey;
+        if (nextKey === currentKey) {
+            return;
+        }
+        const sync = this.sync;
+        this.sync = undefined;
+        void sync.stop();
+        if (this.openHandleCount > 0 || this.subscriptions.size > 0) {
+            this.ensureStarted();
+        }
+    }
+    serverPathFilters() {
+        if (this.openHandleCount > 0) {
+            return [];
+        }
+        const filters = new Set();
+        for (const subscription of this.subscriptions) {
+            for (const path of subscription.serverPathFilters()) {
+                filters.add(path);
+            }
+        }
+        return Array.from(filters).sort();
+    }
     resolveReadyOnce() {
         if (this.readyResolved) {
             return;
@@ -476,6 +524,7 @@ class RelayFileChangeStreamManager {
         if (this.sync) {
             const sync = this.sync;
             this.sync = undefined;
+            this.activePathFilterKey = undefined;
             await sync.stop();
         }
         const managers = changeStreamManagers.get(this.client);
@@ -489,18 +538,21 @@ class RelayFileChangeStreamManager {
         }
     }
 }
-function getStreamManager(client, workspaceId, token, baseUrl) {
+function getStreamManager(client, workspaceId, token, baseUrl, startOptions = {}) {
     let managers = changeStreamManagers.get(client);
     if (!managers) {
         managers = new Map();
         changeStreamManagers.set(client, managers);
     }
-    const key = `${workspaceId}:${token ?? CLIENT_TOKEN_STREAM_KEY}`;
+    const key = `${workspaceId}:${token ?? CLIENT_TOKEN_STREAM_KEY}:${startOptions.from ?? "now"}:${startOptions.cursor ?? ""}`;
     const existing = managers.get(key);
     if (existing) {
         return existing;
     }
-    const manager = new RelayFileChangeStreamManager(client, workspaceId, token, baseUrl);
+    const manager = new RelayFileChangeStreamManager(client, workspaceId, token, baseUrl, {
+        from: startOptions.from,
+        cursor: startOptions.cursor
+    });
     managers.set(key, manager);
     return manager;
 }
@@ -1125,7 +1177,7 @@ export class RelayFileClient {
     subscribe(globs, onChange, options) {
         const setup = this.resolveWorkspaceId(options?.aclToken)
             .then((workspaceId) => {
-            const manager = getStreamManager(this, workspaceId, options?.aclToken, this.baseUrl);
+            const manager = getStreamManager(this, workspaceId, options?.aclToken, this.baseUrl, options);
             return manager.addSubscription(globs, onChange, options);
         });
         return {
@@ -1136,7 +1188,7 @@ export class RelayFileClient {
         };
     }
     open(options) {
-        const manager = getStreamManager(this, options.workspaceId, options.aclToken, this.baseUrl);
+        const manager = getStreamManager(this, options.workspaceId, options.aclToken, this.baseUrl, options);
         const connection = manager.open();
         const replay = this.primeReplayCache(options).catch((error) => {
             if (typeof console !== "undefined" && typeof console.error === "function") {
@@ -1252,6 +1304,15 @@ export class RelayFileClient {
         const url = new URL(`${this.baseUrl}/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/ws`);
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         url.searchParams.set("token", token);
+        if (options.cursor) {
+            url.searchParams.set("cursor", options.cursor);
+        }
+        else if ((options.from ?? "now") === "now") {
+            url.searchParams.set("from", "now");
+        }
+        for (const path of options.paths ?? []) {
+            url.searchParams.append("path", path);
+        }
         const socket = new WebSocket(url.toString());
         return new RelayFileWebSocketConnection(socket, options.onEvent);
     }

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, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
-export { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, 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 { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountLocalLayout, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountSyncMode, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, 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 RelayFileSyncStart, 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/mount-launcher.js

@@ -20,7 +20,7 @@ export function createDefaultMountLauncher(options = {}) {
     };
 }
 export async function readMountedWorkspaceStatus(input) {
-    const state = await readMountStateFile(input.localDir);
+    const state = await readMountStateFile(resolveMountLocalDir(input.localDir, input.remotePath, input.localLayout));
     if (state && !isMountStateStale(state)) {
         return {
             ready: isMountStateReady(state),
@@ -46,7 +46,8 @@ export async function readMountedWorkspaceStatus(input) {
 }
 async function startRelayfileMount(input, options) {
     const localDir = path.resolve(input.env.RELAYFILE_LOCAL_DIR ?? process.cwd());
-    const relayDir = path.join(localDir, ".relay");
+    const mountLocalDir = resolveMountLocalDir(localDir, input.env.RELAYFILE_REMOTE_PATH, input.env.RELAYFILE_MOUNT_LOCAL_LAYOUT);
+    const relayDir = path.join(mountLocalDir, ".relay");
     const logPath = path.join(relayDir, "mount.log");
     const pidPath = path.join(relayDir, "mount.pid");
     await mkdir(relayDir, { recursive: true });
@@ -54,7 +55,7 @@ async function startRelayfileMount(input, options) {
     const command = await resolveRelayfileMountCommand();
     const args = input.background === false ? ["--once"] : [];
     const child = (options.spawnImpl ?? spawn)(command, args, {
-        cwd: input.cwd ?? localDir,
+        cwd: input.cwd ?? mountLocalDir,
         env: {
             ...process.env,
             ...input.env
@@ -73,7 +74,7 @@ async function startRelayfileMount(input, options) {
         pidPath,
         outputBuffer,
         input,
-        localDir,
+        localDir: mountLocalDir,
         now: options.now ?? Date.now,
         readyPollIntervalMs: options.readyPollIntervalMs ?? DEFAULT_READY_POLL_INTERVAL_MS
     });
@@ -113,6 +114,8 @@ class RelayfileMountProcessInstance {
             workspaceId: this.input.env.RELAYFILE_WORKSPACE ?? "",
             remotePath: this.input.env.RELAYFILE_REMOTE_PATH ?? "/",
             mode: normalizeMountMode(this.input.env.RELAYFILE_MOUNT_MODE) ?? "poll",
+            localLayout: normalizeMountLocalLayout(this.input.env.RELAYFILE_MOUNT_LOCAL_LAYOUT),
+            syncMode: normalizeMountSyncMode(this.input.env.RELAYFILE_MOUNT_SYNC_MODE),
             relayfileBaseUrl: this.input.env.RELAYFILE_BASE_URL ?? "",
             relayfileToken: this.input.env.RELAYFILE_TOKEN ?? "",
             expiresAt: null,
@@ -251,6 +254,32 @@ function isMountStateStale(state) {
 function normalizeMountMode(mode) {
     return mode === "fuse" ? "fuse" : mode === "poll" ? "poll" : undefined;
 }
+function normalizeMountLocalLayout(layout) {
+    return layout === "scoped" ? "scoped" : "exact";
+}
+function normalizeMountSyncMode(mode) {
+    return mode === "write-only" ? "write-only" : "mirror";
+}
+function resolveMountLocalDir(localDir, remotePath, localLayout) {
+    const root = path.resolve(localDir);
+    if (normalizeMountLocalLayout(localLayout) !== "scoped") {
+        return root;
+    }
+    const normalizedRemote = normalizeRemotePath(remotePath);
+    if (normalizedRemote === "/") {
+        return root;
+    }
+    return path.join(root, ...normalizedRemote.split("/").filter(Boolean));
+}
+function normalizeRemotePath(remotePath) {
+    const trimmed = typeof remotePath === "string" ? remotePath.trim() : "";
+    if (!trimmed || trimmed === "/") {
+        return "/";
+    }
+    const slashNormalized = trimmed.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(slashNormalized.startsWith("/") ? slashNormalized : `/${slashNormalized}`);
+    return normalized === "/" ? "/" : normalized.replace(/\/+$/, "");
+}
 function normalizeIsoString(value) {
     if (typeof value !== "string" || value.trim() === "") {
         return undefined;

package/dist/setup-types.d.ts

@@ -67,6 +67,8 @@ export interface WorkspaceMountEnvOptions {
 }
 export type WorkspaceMountEnv = Record<string, string>;
 export type MountMode = "poll" | "fuse";
+export type MountLocalLayout = "exact" | "scoped";
+export type MountSyncMode = "mirror" | "write-only";
 export interface MountSessionRequest {
     localDir: string;
     remotePath?: string;
@@ -98,6 +100,8 @@ export interface MountSessionResult {
     remotePath: string;
     localDir: string;
     mode: MountMode;
+    localLayout: MountLocalLayout;
+    syncMode: MountSyncMode;
     scopes: string[];
     tokenIssuedAt: string | null;
     expiresAt: string | null;
@@ -122,6 +126,8 @@ export interface ReadMountedWorkspaceStatusInput {
     workspaceId: string;
     remotePath: string;
     mode: MountMode;
+    localLayout?: MountLocalLayout;
+    syncMode?: MountSyncMode;
     relayfileBaseUrl: string;
     relayfileToken: string;
     expiresAt: string | null;
@@ -167,6 +173,8 @@ export interface MountWorkspaceInput {
     localDir: string;
     remotePath?: string;
     mode?: MountMode;
+    localLayout?: MountLocalLayout;
+    syncMode?: MountSyncMode;
     background?: boolean;
     agentName?: string;
     scopes?: string[];

package/dist/setup.js

@@ -16,6 +16,8 @@ const DEFAULT_WAIT_INTERVAL_MS = 2_000;
 const DEFAULT_WAIT_TIMEOUT_MS = 300_000;
 const DEFAULT_MOUNT_READY_TIMEOUT_MS = 60_000;
 const DEFAULT_MOUNT_AGENT_NAME = "relayfile-mount";
+const DEFAULT_MOUNT_LOCAL_LAYOUT = "exact";
+const DEFAULT_MOUNT_SYNC_MODE = "mirror";
 const TOKEN_REFRESH_AGE_MS = 55 * 60 * 1000;
 const nodeOnlyMountLauncher = {
     async start() {
@@ -142,6 +144,8 @@ export class RelayfileSetup {
             localDir: normalized.localDir,
             remotePath: normalized.remotePath,
             mode: normalized.mode,
+            localLayout: normalized.localLayout,
+            syncMode: normalized.syncMode,
             background: normalized.background,
             agentName: normalized.agentName,
             scopes: normalized.scopes,
@@ -246,13 +250,18 @@ export class RelayfileSetup {
                 : undefined
         });
         try {
-            return validateMountSessionResponse(await workspace.requestJson({
+            const session = validateMountSessionResponse(await workspace.requestJson({
                 operation: "mountWorkspace",
                 method: "POST",
                 path: `api/v1/workspaces/${encodeURIComponent(workspace.workspaceId)}/relayfile/mount-session`,
                 body: request,
                 signal: input.signal
             }), input.localDir);
+            return {
+                ...session,
+                localLayout: input.localLayout,
+                syncMode: input.syncMode
+            };
         }
         catch (error) {
             throw mapMountSessionError(error, request);
@@ -731,6 +740,8 @@ class MountedWorkspaceHandleImpl {
             workspaceId: this.workspaceId,
             remotePath: this.remotePath,
             mode: this.mode,
+            localLayout: this.mountSession.localLayout,
+            syncMode: this.mountSession.syncMode,
             relayfileBaseUrl: this.mountSession.relayfileBaseUrl,
             relayfileToken: this.mountSession.relayfileToken,
             expiresAt: this.expiresAt,
@@ -837,6 +848,8 @@ function validateMountSessionResponse(payload, localDir) {
         remotePath: requireStringField(payload, "remotePath"),
         localDir,
         mode: requireMountModeField(payload, "mode"),
+        localLayout: DEFAULT_MOUNT_LOCAL_LAYOUT,
+        syncMode: DEFAULT_MOUNT_SYNC_MODE,
         scopes: requireStringArrayField(payload, "scopes"),
         tokenIssuedAt: readNullableStringField(payload, "tokenIssuedAt"),
         expiresAt: readNullableStringField(payload, "expiresAt"),
@@ -930,6 +943,8 @@ function normalizeMountWorkspaceInput(input) {
         localDir: resolveLocalDir(localDir),
         remotePath: normalizeMountRemotePath(input.remotePath),
         mode: normalizeMountModeInput(input.mode),
+        localLayout: normalizeMountLocalLayoutInput(input.localLayout),
+        syncMode: normalizeMountSyncModeInput(input.syncMode),
         background: input.background !== false,
         agentName: normalizeNonEmptyString(input.agentName),
         scopes: input.scopes && input.scopes.length > 0 ? [...input.scopes] : undefined,
@@ -954,6 +969,20 @@ function normalizeMountModeInput(mode) {
     }
     return normalized;
 }
+function normalizeMountLocalLayoutInput(layout) {
+    const normalized = normalizeNonEmptyString(layout) ?? DEFAULT_MOUNT_LOCAL_LAYOUT;
+    if (normalized !== "exact" && normalized !== "scoped") {
+        throw new MountSessionInputError(`Invalid localLayout "${normalized}" for mount session.`);
+    }
+    return normalized;
+}
+function normalizeMountSyncModeInput(mode) {
+    const normalized = normalizeNonEmptyString(mode) ?? DEFAULT_MOUNT_SYNC_MODE;
+    if (normalized !== "mirror" && normalized !== "write-only") {
+        throw new MountSessionInputError(`Invalid syncMode "${normalized}" for mount session.`);
+    }
+    return normalized;
+}
 function normalizeMountRemotePath(remotePath) {
     const normalized = normalizeNonEmptyString(remotePath) ?? "/";
     if (normalized.includes("\u0000")) {
@@ -1052,6 +1081,8 @@ function buildMountedWorkspaceEnv(mountSession) {
         RELAYFILE_REMOTE_PATH: mountSession.remotePath,
         RELAYFILE_LOCAL_DIR: mountSession.localDir,
         RELAYFILE_MOUNT_MODE: mountSession.mode,
+        RELAYFILE_MOUNT_LOCAL_LAYOUT: mountSession.localLayout,
+        RELAYFILE_MOUNT_SYNC_MODE: mountSession.syncMode,
         RELAYCAST_API_KEY: mountSession.relaycastApiKey,
         RELAY_API_KEY: mountSession.relaycastApiKey,
         RELAYCAST_BASE_URL: relaycastBaseUrl,

package/dist/sync.d.ts

@@ -9,6 +9,7 @@ import type { FilesystemEvent } from "./types.js";
  */
 export type RelayFileSyncTokenProvider = string | (() => string | undefined | Promise<string | undefined>);
 export type RelayFileSyncState = "idle" | "connecting" | "open" | "polling" | "reconnecting" | "closed";
+export type RelayFileSyncStart = "now" | "legacy";
 export interface RelayFileSyncPong {
     type: "pong";
     timestamp?: string;
@@ -32,7 +33,9 @@ export interface RelayFileSyncOptions {
      * normally NOT pass this and let it inherit from the client.
      */
     token?: RelayFileSyncTokenProvider;
+    from?: RelayFileSyncStart;
     cursor?: string;
+    paths?: string[];
     preferPolling?: boolean;
     pollIntervalMs?: number;
     pingIntervalMs?: number;
@@ -87,6 +90,8 @@ export declare class RelayFileSync {
     private readonly handlers;
     private state;
     private cursor?;
+    private readonly from;
+    private readonly paths;
     private readonly polledEventIds;
     private readonly polledEventOrder;
     private firstPollComplete;
@@ -116,6 +121,7 @@ export declare class RelayFileSync {
     private pollLoop;
     private rememberPolledEvent;
     private handleSocketMessage;
+    private emitFilesystemEvent;
     private startPingLoop;
     private forceReconnect;
     private scheduleReconnect;

package/dist/sync.js

@@ -1,3 +1,45 @@
+function normalizeWebSocketPathFilters(paths) {
+    const seen = new Set();
+    const normalized = [];
+    for (const value of paths ?? []) {
+        const path = typeof value === "string" ? value.trim() : "";
+        if (!path) {
+            continue;
+        }
+        const absolute = path.startsWith("/") ? path : `/${path}`;
+        if (seen.has(absolute)) {
+            continue;
+        }
+        seen.add(absolute);
+        normalized.push(absolute);
+    }
+    return normalized;
+}
+function pathMatchesAnyFilter(filters, path) {
+    if (filters.length === 0) {
+        return true;
+    }
+    const pathSegments = normalizePathSegments(path);
+    return filters.some((filter) => matchPathSegments(normalizePathSegments(filter), pathSegments));
+}
+function normalizePathSegments(path) {
+    const absolute = path.startsWith("/") ? path : `/${path}`;
+    const trimmed = absolute.replace(/\/+$/, "");
+    if (!trimmed) {
+        return [];
+    }
+    return trimmed.split("/").filter(Boolean);
+}
+function matchPathSegments(pattern, path) {
+    if (pattern.length > 0 && pattern[pattern.length - 1] === "**") {
+        const prefix = pattern.slice(0, -1);
+        return path.length >= prefix.length && prefix.every((segment, index) => segment === "*" || segment === path[index]);
+    }
+    if (pattern.length !== path.length) {
+        return false;
+    }
+    return pattern.every((segment, index) => segment === "*" || segment === path[index]);
+}
 const DEFAULT_POLL_INTERVAL_MS = 5000;
 const DEFAULT_PING_INTERVAL_MS = 30000;
 const DEFAULT_RECONNECT_MIN_DELAY_MS = 250;
@@ -131,6 +173,8 @@ export class RelayFileSync {
     };
     state = "idle";
     cursor;
+    from;
+    paths;
     polledEventIds = new Set();
     polledEventOrder = [];
     firstPollComplete = false;
@@ -176,7 +220,9 @@ export class RelayFileSync {
             const literal = options.token;
             this.tokenProvider = () => literal;
         }
+        this.from = options.from ?? "now";
         this.cursor = options.cursor;
+        this.paths = normalizeWebSocketPathFilters(options.paths);
         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));
@@ -327,6 +373,15 @@ export class RelayFileSync {
         if (token) {
             url.searchParams.set("token", token);
         }
+        if (this.cursor) {
+            url.searchParams.set("cursor", this.cursor);
+        }
+        else if (this.from === "now") {
+            url.searchParams.set("from", "now");
+        }
+        for (const path of this.paths) {
+            url.searchParams.append("path", path);
+        }
         let socket;
         try {
             socket = this.webSocketFactory(url.toString());
@@ -524,7 +579,7 @@ export class RelayFileSync {
                 }
                 else {
                     for (const event of pending) {
-                        this.emit("event", event);
+                        this.emitFilesystemEvent(event);
                     }
                 }
                 await this.sleep(this.pollIntervalMs);
@@ -594,8 +649,17 @@ export class RelayFileSync {
             return;
         }
         const normalized = normalizeFilesystemEvent(parsed);
+        if (parsed.eventId) {
+            this.cursor = parsed.eventId;
+        }
         debugLog("event", { type: normalized.type, path: normalized.path, revision: normalized.revision });
-        this.emit("event", normalized);
+        this.emitFilesystemEvent(normalized);
+    }
+    emitFilesystemEvent(event) {
+        if (!pathMatchesAnyFilter(this.paths, event.path)) {
+            return;
+        }
+        this.emit("event", event);
     }
     startPingLoop(socket) {
         this.clearPingTimer();

package/dist/types.d.ts

@@ -257,6 +257,8 @@ export interface SubscribeOptions {
     coalesce?: "none" | "fire-once";
     coalesceMs?: number;
     pathScope?: string[];
+    from?: "now" | "legacy";
+    cursor?: string;
     aclToken?: string;
     drainMs?: number;
 }
@@ -273,6 +275,8 @@ export type ReplayOptions = {
 export type ChangeStreamConnectionOptions = ReplayOptions & {
     workspaceId: string;
     aclToken?: string;
+    from?: "now" | "legacy";
+    cursor?: string;
 };
 export interface ChangeStreamConnection extends Subscription {
     readonly ready: Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,7 +55,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.8.9",
+    "@relayfile/core": "0.8.11",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },