@relayfile/sdk 0.10.31 → 0.10.33

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { RelayFileReadCacheOptions } from "./types.js";
 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 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 { 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 MountSupervisorEvent, 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";

package/dist/mount-launcher.js

@@ -109,7 +109,7 @@ class RelayfileMountProcessInstance {
         this.ready = this.waitForReady();
     }
     async status() {
-        return readMountedWorkspaceStatus({
+        const status = await readMountedWorkspaceStatus({
             localDir: this.localDir,
             workspaceId: this.input.env.RELAYFILE_WORKSPACE ?? "",
             remotePath: this.input.env.RELAYFILE_REMOTE_PATH ?? "/",
@@ -122,6 +122,7 @@ class RelayfileMountProcessInstance {
             suggestedRefreshAt: null,
             pid: this.pid
         });
+        return this.exited ? { ...status, ready: false } : status;
     }
     async stop() {
         if (!this.stopping) {

package/dist/setup-types.d.ts

@@ -146,6 +146,14 @@ export interface MountedWorkspaceHandle {
     status(): Promise<MountedWorkspaceStatus>;
     stop(): Promise<void>;
 }
+export interface MountSupervisorEvent {
+    type: "mount.refreshed" | "mount.refresh_failed";
+    workspaceId: string;
+    localDir: string;
+    attempt: number;
+    retryInMs?: number;
+    errorCode?: string;
+}
 export interface MountLauncherEvent {
     type: string;
     [key: string]: unknown;
@@ -186,6 +194,15 @@ export interface EnsureMountedWorkspaceInput extends MountWorkspaceInput {
     provider?: WorkspaceIntegrationProvider;
     verifyProvider?: boolean;
     providerReadyTimeoutMs?: number;
+    /** Keep a background mount healthy and renew its short-lived session. Defaults to true. */
+    supervise?: boolean;
+    /** Health-check cadence for supervised background mounts. */
+    healthCheckIntervalMs?: number;
+    /** Initial retry delay after a supervised refresh failure. */
+    refreshRetryBaseMs?: number;
+    /** Maximum retry delay after repeated supervised refresh failures. */
+    refreshRetryMaxMs?: number;
+    onSupervisorEvent?: (event: MountSupervisorEvent) => void | Promise<void>;
 }
 export interface AgentWorkspaceInviteOptions {
     agentName?: string;

package/dist/setup.d.ts

@@ -42,6 +42,7 @@ export declare class RelayfileSetup {
     private readonly accessToken?;
     private readonly requestTimeoutMs;
     private readonly retryOptions;
+    private readonly ensuredMounts;
     static login(options?: RelayfileCloudLoginOptions): Promise<RelayfileSetup>;
     static fromCloudTokens(tokens: RelayfileCloudTokenSet, options?: RelayfileCloudTokenSetupOptions): RelayfileSetup;
     constructor(options?: RelayfileSetupOptions);
@@ -49,6 +50,7 @@ export declare class RelayfileSetup {
     joinWorkspace(workspaceId: string, options?: JoinWorkspaceOptions): Promise<WorkspaceHandle>;
     mountWorkspace(input: MountWorkspaceInput): Promise<MountedWorkspaceHandle>;
     ensureMountedWorkspace(input: EnsureMountedWorkspaceInput): Promise<MountedWorkspaceHandle>;
+    private startEnsuredMount;
     joinWorkspaceResponse(workspaceId: string, options: NormalizedJoinWorkspaceOptions, overrides?: {
         tokenProvider?: AccessTokenProvider;
     }): Promise<ValidatedJoinWorkspaceResponse>;

package/dist/setup.js

@@ -18,6 +18,9 @@ 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 DEFAULT_MOUNT_HEALTH_INTERVAL_MS = 30_000;
+const DEFAULT_MOUNT_REFRESH_RETRY_BASE_MS = 1_000;
+const DEFAULT_MOUNT_REFRESH_RETRY_MAX_MS = 60_000;
 const TOKEN_REFRESH_AGE_MS = 55 * 60 * 1000;
 const nodeOnlyMountLauncher = {
     async start() {
@@ -29,6 +32,7 @@ export class RelayfileSetup {
     accessToken;
     requestTimeoutMs;
     retryOptions;
+    ensuredMounts = new Map();
     static async login(options = {}) {
         void options;
         throw new RelayfileSetupError("RelayfileSetup.login() starts a local HTTP callback server and is only available from @relayfile/sdk/cli. Import RelayfileSetup from @relayfile/sdk/cli for interactive Cloud login.", "node_only_sdk_feature");
@@ -133,13 +137,42 @@ export class RelayfileSetup {
     async ensureMountedWorkspace(input) {
         const normalized = normalizeEnsureMountedWorkspaceInput(input);
         const workspace = await this.resolveWorkspaceForMount(normalized);
+        throwIfAborted(normalized.signal, "ensureMountedWorkspace");
+        const mountKey = ensuredMountKey(workspace, normalized);
+        const existing = this.ensuredMounts.get(mountKey);
+        if (existing) {
+            return waitForEnsuredMount(existing, normalized.signal);
+        }
+        let shared;
+        // The physical mount belongs to the logical target, not the first caller.
+        // Individual abort signals only cancel that caller's wait below.
+        shared = this.startEnsuredMount(workspace, {
+            ...normalized,
+            signal: undefined
+        }).then((mounted) => new SharedMountedWorkspaceHandle({
+            mounted,
+            onStopped: () => {
+                if (this.ensuredMounts.get(mountKey) === shared) {
+                    this.ensuredMounts.delete(mountKey);
+                }
+            }
+        }));
+        this.ensuredMounts.set(mountKey, shared);
+        void shared.catch(() => {
+            if (this.ensuredMounts.get(mountKey) === shared) {
+                this.ensuredMounts.delete(mountKey);
+            }
+        });
+        return waitForEnsuredMount(shared, normalized.signal);
+    }
+    async startEnsuredMount(workspace, normalized) {
         if (normalized.verifyProvider) {
             if (!normalized.provider) {
                 throw new MountSessionInputError("provider required when verifyProvider=true");
             }
             await verifyWorkspaceProviderReady(workspace, normalized.provider, normalized.providerReadyTimeoutMs, normalized.signal);
         }
-        return this.mountWorkspace({
+        const mountInput = {
             workspace,
             localDir: normalized.localDir,
             remotePath: normalized.remotePath,
@@ -152,6 +185,19 @@ export class RelayfileSetup {
             signal: normalized.signal,
             launcher: normalized.launcher,
             readyTimeoutMs: normalized.readyTimeoutMs
+        };
+        const mounted = await this.mountWorkspace(mountInput);
+        if (!normalized.supervise || !normalized.background) {
+            return mounted;
+        }
+        return new SupervisedMountedWorkspaceHandle({
+            mounted,
+            launch: () => this.mountWorkspace(mountInput),
+            healthCheckIntervalMs: normalized.healthCheckIntervalMs,
+            refreshRetryBaseMs: normalized.refreshRetryBaseMs,
+            refreshRetryMaxMs: normalized.refreshRetryMaxMs,
+            onEvent: normalized.onSupervisorEvent,
+            signal: normalized.signal
         });
     }
     async joinWorkspaceResponse(workspaceId, options, overrides = {}) {
@@ -758,12 +804,256 @@ class MountedWorkspaceHandleImpl {
         await this.stopPromise;
     }
     async performStop() {
+        this.readySnapshot = false;
         if (this.probeOnly || !this.launcherInstance) {
             return;
         }
         await safeStopLauncher(this.launcherInstance);
     }
 }
+class SharedMountedWorkspaceHandle {
+    mounted;
+    onStopped;
+    stopPromise;
+    constructor(input) {
+        this.mounted = input.mounted;
+        this.onStopped = input.onStopped;
+    }
+    get workspaceId() {
+        return this.mounted.workspaceId;
+    }
+    get localDir() {
+        return this.mounted.localDir;
+    }
+    get remotePath() {
+        return this.mounted.remotePath;
+    }
+    get mode() {
+        return this.mounted.mode;
+    }
+    get ready() {
+        return this.mounted.ready;
+    }
+    get expiresAt() {
+        return this.mounted.expiresAt;
+    }
+    get suggestedRefreshAt() {
+        return this.mounted.suggestedRefreshAt;
+    }
+    env() {
+        return this.mounted.env();
+    }
+    status() {
+        return this.mounted.status();
+    }
+    async stop() {
+        if (!this.stopPromise)
+            this.stopPromise = this.performStop();
+        await this.stopPromise;
+    }
+    async performStop() {
+        try {
+            await this.mounted.stop();
+        }
+        finally {
+            this.onStopped();
+        }
+    }
+}
+class SupervisedMountedWorkspaceHandle {
+    mounted;
+    launch;
+    healthCheckIntervalMs;
+    refreshRetryBaseMs;
+    refreshRetryMaxMs;
+    onEvent;
+    signal;
+    timer;
+    refreshPromise;
+    stopPromise;
+    stopped = false;
+    supervisorReady = true;
+    refreshAttempts = 0;
+    constructor(input) {
+        this.mounted = input.mounted;
+        this.launch = input.launch;
+        this.healthCheckIntervalMs = input.healthCheckIntervalMs;
+        this.refreshRetryBaseMs = input.refreshRetryBaseMs;
+        this.refreshRetryMaxMs = input.refreshRetryMaxMs;
+        this.onEvent = input.onEvent;
+        this.signal = input.signal;
+        if (this.signal?.aborted) {
+            this.handleAbort();
+        }
+        else {
+            this.signal?.addEventListener("abort", this.handleAbort, { once: true });
+            this.schedule();
+        }
+    }
+    get workspaceId() {
+        return this.mounted.workspaceId;
+    }
+    get localDir() {
+        return this.mounted.localDir;
+    }
+    get remotePath() {
+        return this.mounted.remotePath;
+    }
+    get mode() {
+        return this.mounted.mode;
+    }
+    get ready() {
+        return !this.stopped && this.supervisorReady && this.mounted.ready;
+    }
+    get expiresAt() {
+        return this.mounted.expiresAt;
+    }
+    get suggestedRefreshAt() {
+        return this.mounted.suggestedRefreshAt;
+    }
+    env() {
+        return this.mounted.env();
+    }
+    async status() {
+        const status = await this.mounted.status();
+        return {
+            ...status,
+            ready: !this.stopped && this.supervisorReady && status.ready,
+            expiresAt: this.expiresAt,
+            suggestedRefreshAt: this.suggestedRefreshAt
+        };
+    }
+    async stop() {
+        if (!this.stopPromise)
+            this.stopPromise = this.performStop();
+        await this.stopPromise;
+    }
+    async performStop() {
+        this.stopped = true;
+        this.supervisorReady = false;
+        this.signal?.removeEventListener("abort", this.handleAbort);
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        await this.refreshPromise?.catch(() => { });
+        await this.mounted.stop();
+    }
+    handleAbort = () => {
+        void this.stop();
+    };
+    schedule(delayOverrideMs) {
+        if (this.stopped || this.timer)
+            return;
+        const suggestedRefreshAtMs = Date.parse(this.mounted.suggestedRefreshAt ?? "");
+        const untilRefresh = Number.isFinite(suggestedRefreshAtMs)
+            ? Math.max(0, suggestedRefreshAtMs - Date.now())
+            : this.healthCheckIntervalMs;
+        const delayMs = delayOverrideMs ?? Math.min(this.healthCheckIntervalMs, untilRefresh);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.refreshPromise = this.checkAndRefresh().finally(() => {
+                this.refreshPromise = undefined;
+            });
+        }, Math.max(1_000, delayMs));
+        this.timer.unref?.();
+    }
+    async checkAndRefresh() {
+        if (this.stopped)
+            return;
+        try {
+            const suggestedRefreshAtMs = Date.parse(this.mounted.suggestedRefreshAt ?? "");
+            const refreshDue = Number.isFinite(suggestedRefreshAtMs) && Date.now() >= suggestedRefreshAtMs;
+            if (!refreshDue) {
+                const status = await this.mounted.status();
+                if (status.ready) {
+                    this.supervisorReady = true;
+                    this.refreshAttempts = 0;
+                    this.schedule();
+                    return;
+                }
+            }
+            await this.replaceMount();
+            if (this.stopped)
+                return;
+            this.supervisorReady = true;
+            this.refreshAttempts = 0;
+            this.emit({
+                type: "mount.refreshed",
+                workspaceId: this.workspaceId,
+                localDir: this.localDir,
+                attempt: 0
+            });
+            this.schedule();
+        }
+        catch (error) {
+            if (this.stopped)
+                return;
+            this.supervisorReady = false;
+            this.refreshAttempts += 1;
+            const retryInMs = Math.min(this.refreshRetryMaxMs, this.refreshRetryBaseMs * 2 ** (this.refreshAttempts - 1));
+            this.emit({
+                type: "mount.refresh_failed",
+                workspaceId: this.workspaceId,
+                localDir: this.localDir,
+                attempt: this.refreshAttempts,
+                retryInMs,
+                errorCode: setupErrorCode(error)
+            });
+            this.schedule(retryInMs);
+        }
+    }
+    async replaceMount() {
+        const previous = this.mounted;
+        if (this.stopped)
+            return;
+        await previous.stop().catch(() => { });
+        if (this.stopped)
+            return;
+        const replacement = await this.launch();
+        if (this.stopped) {
+            await replacement.stop().catch(() => { });
+            return;
+        }
+        this.mounted = replacement;
+    }
+    emit(event) {
+        void Promise.resolve(this.onEvent?.(event)).catch(() => { });
+    }
+}
+function ensuredMountKey(workspace, input) {
+    return JSON.stringify([
+        workspace.workspaceId,
+        input.localDir,
+        input.remotePath,
+        input.mode,
+        input.localLayout,
+        input.syncMode,
+        input.background
+    ]);
+}
+async function waitForEnsuredMount(mounted, signal) {
+    if (!signal)
+        return mounted;
+    if (signal.aborted)
+        throw new CloudAbortError("ensureMountedWorkspace");
+    let onAbort;
+    try {
+        return await Promise.race([
+            mounted,
+            new Promise((_, reject) => {
+                onAbort = () => reject(new CloudAbortError("ensureMountedWorkspace"));
+                signal.addEventListener("abort", onAbort, { once: true });
+            })
+        ]);
+    }
+    finally {
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+function setupErrorCode(error) {
+    return error instanceof RelayfileSetupError ? error.code : "mount_refresh_failed";
+}
 // The metadata + accessible-resources verbs accept `WorkspaceIntegrationProvider | string`
 // so operators can target dynamically-discovered providers (Composio toolkit
 // slugs, future Atlassian-family additions) without an SDK release. We still
@@ -959,9 +1249,19 @@ function normalizeEnsureMountedWorkspaceInput(input) {
         ...normalized,
         provider: input.provider,
         verifyProvider: input.verifyProvider !== false,
-        providerReadyTimeoutMs: Math.max(0, Math.floor(input.providerReadyTimeoutMs ?? 0))
+        providerReadyTimeoutMs: Math.max(0, Math.floor(input.providerReadyTimeoutMs ?? 0)),
+        supervise: input.supervise !== false && normalized.background,
+        healthCheckIntervalMs: positiveInterval(input.healthCheckIntervalMs, DEFAULT_MOUNT_HEALTH_INTERVAL_MS),
+        refreshRetryBaseMs: positiveInterval(input.refreshRetryBaseMs, DEFAULT_MOUNT_REFRESH_RETRY_BASE_MS),
+        refreshRetryMaxMs: positiveInterval(input.refreshRetryMaxMs, DEFAULT_MOUNT_REFRESH_RETRY_MAX_MS),
+        onSupervisorEvent: input.onSupervisorEvent
     };
 }
+function positiveInterval(value, fallback) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.max(1_000, Math.floor(value));
+}
 function normalizeMountModeInput(mode) {
     const normalized = normalizeNonEmptyString(mode) ?? "poll";
     if (normalized !== "poll" && normalized !== "fuse") {

package/package.json

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