@relayfile/sdk 0.10.31 → 0.10.32

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.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() {
@@ -139,7 +142,7 @@ export class RelayfileSetup {
             }
             await verifyWorkspaceProviderReady(workspace, normalized.provider, normalized.providerReadyTimeoutMs, normalized.signal);
         }
-        return this.mountWorkspace({
+        const mountInput = {
             workspace,
             localDir: normalized.localDir,
             remotePath: normalized.remotePath,
@@ -152,6 +155,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 +774,176 @@ class MountedWorkspaceHandleImpl {
         await this.stopPromise;
     }
     async performStop() {
+        this.readySnapshot = false;
         if (this.probeOnly || !this.launcherInstance) {
             return;
         }
         await safeStopLauncher(this.launcherInstance);
     }
 }
+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 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 +1139,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.32",
   "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.32",
     "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.32",
+    "@relayfile/mount-darwin-x64": "0.10.32",
+    "@relayfile/mount-linux-arm64": "0.10.32",
+    "@relayfile/mount-linux-x64": "0.10.32"
   },
   "devDependencies": {
     "typescript": "^5.7.3",