@relayfile/sdk 0.7.1 → 0.7.2

package/dist/client.d.ts

@@ -63,6 +63,14 @@ export declare class RelayFileClient {
      * sync-vs-async tokenProvider shapes.
      */
     getToken(): Promise<string>;
+    /**
+     * Return the normalized API base URL this client was constructed with.
+     *
+     * onWrite/sync consumers use this so an explicit RelayFileClient remains the
+     * source of truth for both HTTP and WebSocket traffic instead of letting a
+     * process-level env override silently redirect only the WS side.
+     */
+    getBaseUrl(): 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

@@ -185,6 +185,16 @@ export class RelayFileClient {
     async getToken() {
         return resolveToken(this.tokenProvider);
     }
+    /**
+     * Return the normalized API base URL this client was constructed with.
+     *
+     * onWrite/sync consumers use this so an explicit RelayFileClient remains the
+     * source of truth for both HTTP and WebSocket traffic instead of letting a
+     * process-level env override silently redirect only the WS side.
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
     async listTree(workspaceId, options = {}) {
         const query = buildQuery({
             path: options.path ?? "/",

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.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, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.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 { 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 RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
+export { createDefaultMountLauncher, defaultMountLauncher, readMountedWorkspaceStatus } from "./mount-launcher.js";
 export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";
 export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnWriteHandlerError, type OnWriteOptions } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";

package/dist/index.js

@@ -1,7 +1,8 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL } from "./client.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
-export { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
+export { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
 export { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
+export { createDefaultMountLauncher, defaultMountLauncher, readMountedWorkspaceStatus } from "./mount-launcher.js";
 export { RelayFileSync } from "./sync.js";
 export { onWrite, pathMatches } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";

package/dist/mount-launcher.d.ts

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import type { MountLauncher, MountMode, MountedWorkspaceStatus } from "./setup-types.js";
+interface DefaultMountLauncherOptions {
+    spawnImpl?: typeof spawn;
+    now?: () => number;
+    readyPollIntervalMs?: number;
+}
+interface ReadMountedWorkspaceStatusInput {
+    localDir: string;
+    workspaceId: string;
+    remotePath: string;
+    mode: MountMode;
+    relayfileBaseUrl: string;
+    relayfileToken: string;
+    expiresAt: string | null;
+    suggestedRefreshAt: string | null;
+    pid?: number;
+}
+export declare const defaultMountLauncher: MountLauncher;
+export declare function createDefaultMountLauncher(options?: DefaultMountLauncherOptions): MountLauncher;
+export declare function readMountedWorkspaceStatus(input: ReadMountedWorkspaceStatusInput): Promise<MountedWorkspaceStatus>;
+export {};

package/dist/mount-launcher.js

@@ -0,0 +1,371 @@
+import { spawn } from "node:child_process";
+import { constants as fsConstants, createWriteStream } from "node:fs";
+import { access, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { RelayFileClient } from "./client.js";
+import { CloudAbortError, MountModeUnavailableError, MountReadyTimeoutError, RelayfileSetupError } from "./setup-errors.js";
+const DEFAULT_READY_POLL_INTERVAL_MS = 250;
+const DEFAULT_STOP_TIMEOUT_MS = 10_000;
+const LOG_ROTATION_MAX_BYTES = 10 * 1024 * 1024;
+const LOG_ROTATION_FILES = 3;
+const FUSE_UNAVAILABLE_SIGNATURE = "fuse mode is not available in this build";
+export const defaultMountLauncher = createDefaultMountLauncher();
+export function createDefaultMountLauncher(options = {}) {
+    return {
+        async start(input) {
+            return startRelayfileMount(input, options);
+        }
+    };
+}
+export async function readMountedWorkspaceStatus(input) {
+    const state = await readMountStateFile(input.localDir);
+    if (state && !isMountStateStale(state)) {
+        return {
+            ready: isMountStateReady(state),
+            mode: normalizeMountMode(state.mode) ?? input.mode,
+            pid: state.daemon?.pid ?? input.pid,
+            lastHeartbeatAt: normalizeIsoString(state.lastHeartbeatAt),
+            lastReconcileAt: normalizeIsoString(state.lastReconcileAt),
+            lastEventAt: normalizeIsoString(state.lastEventAt),
+            expiresAt: input.expiresAt,
+            suggestedRefreshAt: input.suggestedRefreshAt,
+            pendingWriteback: normalizeInteger(state.pendingWriteback),
+            pendingConflicts: normalizeInteger(state.pendingConflicts)
+        };
+    }
+    const ready = await probeMountedWorkspace(input);
+    return {
+        ready,
+        mode: input.mode,
+        pid: input.pid,
+        expiresAt: input.expiresAt,
+        suggestedRefreshAt: input.suggestedRefreshAt
+    };
+}
+async function startRelayfileMount(input, options) {
+    const localDir = path.resolve(input.env.RELAYFILE_LOCAL_DIR ?? process.cwd());
+    const relayDir = path.join(localDir, ".relay");
+    const logPath = path.join(relayDir, "mount.log");
+    const pidPath = path.join(relayDir, "mount.pid");
+    await mkdir(relayDir, { recursive: true });
+    await rotateMountLogIfNeeded(logPath);
+    const command = await resolveRelayfileMountCommand();
+    const args = input.background === false ? ["--once"] : [];
+    const child = (options.spawnImpl ?? spawn)(command, args, {
+        cwd: input.cwd ?? localDir,
+        env: {
+            ...process.env,
+            ...input.env
+        },
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    const outputBuffer = [];
+    const logStream = createWriteStream(logPath, { flags: "a" });
+    pipeChildOutput(child, logStream, outputBuffer, input);
+    if (typeof child.pid === "number" && child.pid > 0) {
+        await writeAtomicFile(pidPath, `${child.pid}\n`);
+    }
+    return new RelayfileMountProcessInstance({
+        child,
+        logStream,
+        pidPath,
+        outputBuffer,
+        input,
+        localDir,
+        now: options.now ?? Date.now,
+        readyPollIntervalMs: options.readyPollIntervalMs ?? DEFAULT_READY_POLL_INTERVAL_MS
+    });
+}
+class RelayfileMountProcessInstance {
+    pid;
+    ready;
+    child;
+    logStream;
+    pidPath;
+    outputBuffer;
+    input;
+    localDir;
+    now;
+    readyPollIntervalMs;
+    exited = false;
+    stopping;
+    readyResolved = false;
+    constructor(input) {
+        this.child = input.child;
+        this.logStream = input.logStream;
+        this.pidPath = input.pidPath;
+        this.outputBuffer = input.outputBuffer;
+        this.input = input.input;
+        this.localDir = input.localDir;
+        this.pid = input.child.pid ?? undefined;
+        this.now = input.now;
+        this.readyPollIntervalMs = input.readyPollIntervalMs;
+        this.child.once("exit", () => {
+            this.exited = true;
+        });
+        this.ready = this.waitForReady();
+    }
+    async status() {
+        return readMountedWorkspaceStatus({
+            localDir: this.localDir,
+            workspaceId: this.input.env.RELAYFILE_WORKSPACE ?? "",
+            remotePath: this.input.env.RELAYFILE_REMOTE_PATH ?? "/",
+            mode: normalizeMountMode(this.input.env.RELAYFILE_MOUNT_MODE) ?? "poll",
+            relayfileBaseUrl: this.input.env.RELAYFILE_BASE_URL ?? "",
+            relayfileToken: this.input.env.RELAYFILE_TOKEN ?? "",
+            expiresAt: null,
+            suggestedRefreshAt: null,
+            pid: this.pid
+        });
+    }
+    async stop() {
+        if (!this.stopping) {
+            this.stopping = this.performStop();
+        }
+        await this.stopping;
+    }
+    async waitForReady() {
+        const startedAt = this.now();
+        const timeoutAt = startedAt + this.input.readyTimeoutMs;
+        for (;;) {
+            if (this.input.signal?.aborted) {
+                await this.stop();
+                throw new CloudAbortError("mountWorkspace");
+            }
+            const status = await this.status();
+            if (status.ready) {
+                this.readyResolved = true;
+                return;
+            }
+            if (this.isFuseUnavailable()) {
+                throw new MountModeUnavailableError("fuse");
+            }
+            if (this.exited) {
+                throw this.buildEarlyExitError();
+            }
+            if (this.now() >= timeoutAt) {
+                const error = new MountReadyTimeoutError(this.localDir, this.input.readyTimeoutMs);
+                await this.stop();
+                throw error;
+            }
+            await delay(this.readyPollIntervalMs);
+        }
+    }
+    buildEarlyExitError() {
+        if (this.isFuseUnavailable()) {
+            return new MountModeUnavailableError("fuse");
+        }
+        return new RelayfileSetupError("relayfile-mount exited before the workspace became ready.", "mount_launch_failed");
+    }
+    isFuseUnavailable() {
+        return (normalizeMountMode(this.input.env.RELAYFILE_MOUNT_MODE) === "fuse" &&
+            this.outputBuffer.join("").includes(FUSE_UNAVAILABLE_SIGNATURE));
+    }
+    async performStop() {
+        if (!this.exited && typeof this.child.pid === "number") {
+            this.child.kill("SIGTERM");
+            await waitForExit(this.child, DEFAULT_STOP_TIMEOUT_MS);
+        }
+        if (!this.exited && typeof this.child.pid === "number") {
+            this.child.kill("SIGKILL");
+            await waitForExit(this.child, 1_000);
+        }
+        if (!this.readyResolved) {
+            this.exited = true;
+        }
+        this.logStream.end();
+        await unlinkIfExists(this.pidPath);
+    }
+}
+function pipeChildOutput(child, logStream, outputBuffer, input) {
+    const appendChunk = (streamName, chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        logStream.write(text);
+        outputBuffer.push(text);
+        if (outputBuffer.length > 32) {
+            outputBuffer.splice(0, outputBuffer.length - 32);
+        }
+        input.onEvent?.({
+            type: streamName,
+            text
+        });
+    };
+    child.stdout?.on("data", (chunk) => {
+        appendChunk("stdout", chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+        appendChunk("stderr", chunk);
+    });
+}
+async function probeMountedWorkspace(input) {
+    const client = new RelayFileClient({
+        baseUrl: input.relayfileBaseUrl,
+        token: input.relayfileToken
+    });
+    try {
+        await client.listTree(input.workspaceId, {
+            path: input.remotePath,
+            depth: 1
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readMountStateFile(localDir) {
+    const statePath = path.join(localDir, ".relay", "state.json");
+    try {
+        const payload = await readFile(statePath, "utf8");
+        const parsed = JSON.parse(payload);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isMountStateReady(state) {
+    if (!normalizeIsoString(state.lastReconcileAt)) {
+        return false;
+    }
+    const providers = Array.isArray(state.providers) ? state.providers : [];
+    return providers.every((provider) => {
+        const status = normalizeNonEmptyString(provider?.status);
+        return status === undefined || status === "ready" || status === "syncing" || status === "unknown";
+    });
+}
+function isMountStateStale(state) {
+    const lastReconcileAt = normalizeIsoString(state.lastReconcileAt);
+    const intervalMs = normalizeInteger(state.intervalMs);
+    if (!lastReconcileAt || !intervalMs || intervalMs <= 0) {
+        return false;
+    }
+    const reconciledAt = Date.parse(lastReconcileAt);
+    return !Number.isNaN(reconciledAt) && Date.now() - reconciledAt > intervalMs * 2;
+}
+function normalizeMountMode(mode) {
+    return mode === "fuse" ? "fuse" : mode === "poll" ? "poll" : undefined;
+}
+function normalizeIsoString(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        return undefined;
+    }
+    return Number.isNaN(Date.parse(value)) ? undefined : value;
+}
+function normalizeInteger(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.trunc(value)
+        : undefined;
+}
+function normalizeNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+async function resolveRelayfileMountCommand() {
+    const executableFromPath = await findExecutableInPath("relayfile-mount");
+    if (executableFromPath) {
+        return executableFromPath;
+    }
+    const candidates = [
+        process.env.RELAYFILE_MOUNT_BIN,
+        fileURLToPath(new URL("../../../../bin/relayfile-mount", import.meta.url))
+    ];
+    for (const candidate of candidates) {
+        if (!candidate) {
+            continue;
+        }
+        if (await isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return "relayfile-mount";
+}
+async function findExecutableInPath(command) {
+    const pathValue = process.env.PATH ?? "";
+    const pathEntries = pathValue.split(path.delimiter).filter(Boolean);
+    for (const entry of pathEntries) {
+        const candidate = path.join(entry, command);
+        if (await isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function isExecutable(candidate) {
+    try {
+        await access(candidate, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function rotateMountLogIfNeeded(logPath) {
+    try {
+        const info = await stat(logPath);
+        if (info.size < LOG_ROTATION_MAX_BYTES) {
+            return;
+        }
+    }
+    catch {
+        return;
+    }
+    const oldest = `${logPath}.${LOG_ROTATION_FILES}`;
+    await unlinkIfExists(oldest);
+    for (let index = LOG_ROTATION_FILES - 1; index >= 1; index -= 1) {
+        const source = `${logPath}.${index}`;
+        const target = `${logPath}.${index + 1}`;
+        try {
+            await rename(source, target);
+        }
+        catch {
+            // ignore missing rotation slots
+        }
+    }
+    try {
+        await rename(logPath, `${logPath}.1`);
+    }
+    catch {
+        // ignore missing active log
+    }
+}
+async function writeAtomicFile(targetPath, content) {
+    const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(tempPath, content, "utf8");
+    await rename(tempPath, targetPath);
+}
+async function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null) {
+        return;
+    }
+    await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            child.removeListener("exit", onExit);
+            resolve();
+        }, timeoutMs);
+        const onExit = () => {
+            clearTimeout(timer);
+            child.removeListener("exit", onExit);
+            resolve();
+        };
+        child.once("exit", onExit);
+    });
+}
+async function unlinkIfExists(targetPath) {
+    try {
+        await unlink(targetPath);
+    }
+    catch {
+        // ignore
+    }
+}
+async function delay(delayMs) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}

package/dist/onWrite.js

@@ -38,6 +38,7 @@ export function onWrite(pattern, handler, options = {}) {
     if (!workspaceId) {
         throw new Error("onWrite requires options.workspaceId or RELAYFILE_WORKSPACE_ID.");
     }
+    const baseUrl = resolveOnWriteBaseUrl(options, client);
     const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
     for (const operation of operations) {
         if (operation !== "create" && operation !== "update" && operation !== "delete") {
@@ -65,7 +66,7 @@ export function onWrite(pattern, handler, options = {}) {
     dispatcher.register(registration, {
         workspaceId,
         signal: options.signal,
-        baseUrl: options.baseUrl,
+        baseUrl,
         token: options.token,
         webSocketFactory: options.webSocketFactory,
         pingIntervalMs: options.pingIntervalMs,
@@ -146,7 +147,7 @@ class OnWriteDispatcher {
         this.sync = RelayFileSync.connect({
             client: this.client,
             workspaceId: options.workspaceId,
-            baseUrl: options.baseUrl ?? readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL,
+            baseUrl: options.baseUrl ?? DEFAULT_RELAYFILE_BASE_URL,
             token,
             reconnect: {
                 minDelayMs: DEFAULT_RECONNECT_MIN_DELAY_MS,
@@ -330,6 +331,18 @@ function getDefaultClient() {
     }
     return defaultClient;
 }
+function resolveOnWriteBaseUrl(options, client) {
+    if (options.baseUrl) {
+        return options.baseUrl;
+    }
+    if (!options.client) {
+        return readEnv("RELAYFILE_BASE_URL") ?? DEFAULT_RELAYFILE_BASE_URL;
+    }
+    if (client instanceof RelayFileClient) {
+        return client.getBaseUrl();
+    }
+    return DEFAULT_RELAYFILE_BASE_URL;
+}
 function readEnv(name) {
     return globalThis.process?.env?.[name];
 }

package/dist/setup-errors.d.ts

@@ -42,3 +42,41 @@ export declare class MissingConnectionIdError extends RelayfileSetupError {
     readonly provider: WorkspaceIntegrationProvider;
     constructor(provider: WorkspaceIntegrationProvider);
 }
+export declare class MountSessionInputError extends RelayfileSetupError {
+    constructor(message: string);
+}
+export declare class InvalidMountModeError extends RelayfileSetupError {
+    readonly mode: string;
+    constructor(mode: string);
+}
+export declare class InvalidLocalDirError extends RelayfileSetupError {
+    readonly localDir: string;
+    constructor(localDir: string, message?: string);
+}
+export declare class InvalidRemotePathError extends RelayfileSetupError {
+    readonly remotePath: string;
+    constructor(remotePath: string, message?: string);
+}
+export declare class MountModeUnavailableError extends RelayfileSetupError {
+    readonly mode: string;
+    constructor(mode: string, message?: string);
+}
+export declare class MountReadyTimeoutError extends RelayfileSetupError {
+    readonly localDir: string;
+    readonly timeoutMs: number;
+    constructor(localDir: string, timeoutMs: number);
+}
+export declare class ProviderNotConnectedError extends RelayfileSetupError {
+    readonly provider: WorkspaceIntegrationProvider;
+    constructor(provider: WorkspaceIntegrationProvider);
+}
+export declare class ProviderNotReadyError extends RelayfileSetupError {
+    readonly provider: WorkspaceIntegrationProvider;
+    readonly state?: string;
+    readonly initialSyncState?: string;
+    constructor(input: {
+        provider: WorkspaceIntegrationProvider;
+        state?: string;
+        initialSyncState?: string;
+    });
+}

package/dist/setup-errors.js

@@ -69,6 +69,71 @@ export class MissingConnectionIdError extends RelayfileSetupError {
         this.provider = provider;
     }
 }
+export class MountSessionInputError extends RelayfileSetupError {
+    constructor(message) {
+        super(message, "mount_session_input_error");
+    }
+}
+export class InvalidMountModeError extends RelayfileSetupError {
+    mode;
+    constructor(mode) {
+        super(`Invalid mount mode "${mode}". Expected "poll" or "fuse".`, "invalid_mount_mode");
+        this.mode = mode;
+    }
+}
+export class InvalidLocalDirError extends RelayfileSetupError {
+    localDir;
+    constructor(localDir, message) {
+        super(message ?? `Invalid localDir "${localDir}" for mount session.`, "invalid_local_dir");
+        this.localDir = localDir;
+    }
+}
+export class InvalidRemotePathError extends RelayfileSetupError {
+    remotePath;
+    constructor(remotePath, message) {
+        super(message ?? `Invalid remotePath "${remotePath}" for mount session.`, "invalid_remote_path");
+        this.remotePath = remotePath;
+    }
+}
+export class MountModeUnavailableError extends RelayfileSetupError {
+    mode;
+    constructor(mode, message) {
+        super(message ?? `Mount mode "${mode}" is unavailable in this environment.`, "mount_mode_unavailable");
+        this.mode = mode;
+    }
+}
+export class MountReadyTimeoutError extends RelayfileSetupError {
+    localDir;
+    timeoutMs;
+    constructor(localDir, timeoutMs) {
+        super(`Timed out waiting for the mount at ${localDir} to become ready after ${timeoutMs}ms.`, "mount_ready_timeout");
+        this.localDir = localDir;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class ProviderNotConnectedError extends RelayfileSetupError {
+    provider;
+    constructor(provider) {
+        super(`Provider "${provider}" is not connected for this workspace.`, "provider_not_connected");
+        this.provider = provider;
+    }
+}
+export class ProviderNotReadyError extends RelayfileSetupError {
+    provider;
+    state;
+    initialSyncState;
+    constructor(input) {
+        const details = [input.state, input.initialSyncState]
+            .filter((value) => typeof value === "string" && value.trim() !== "")
+            .join(", ");
+        super(details
+            ? `Provider "${input.provider}" is connected but not ready (${details}).`
+            : `Provider "${input.provider}" is connected but not ready.`, "provider_not_ready");
+        this.provider = input.provider;
+        this.state = input.state;
+        this.initialSyncState = input.initialSyncState;
+    }
+}
 function readCloudErrorMessage(httpBody) {
     if (!httpBody || typeof httpBody !== "object" || Array.isArray(httpBody)) {
         return undefined;

package/dist/setup-types.d.ts

@@ -1,3 +1,4 @@
+import type { WorkspaceHandle } from "./setup.js";
 import type { AccessTokenProvider } from "./client.js";
 export declare const WORKSPACE_INTEGRATION_PROVIDERS: readonly ["github", "slack-sage", "slack-my-senior-dev", "slack-nightcto", "notion", "linear"];
 export type WorkspaceIntegrationProvider = (typeof WORKSPACE_INTEGRATION_PROVIDERS)[number];
@@ -65,6 +66,108 @@ export interface WorkspaceMountEnvOptions {
     relaycastBaseUrl?: string;
 }
 export type WorkspaceMountEnv = Record<string, string>;
+export type MountMode = "poll" | "fuse";
+export interface MountSessionRequest {
+    localDir: string;
+    remotePath?: string;
+    mode?: MountMode;
+    agentName?: string;
+    scopes?: string[];
+    provider?: WorkspaceIntegrationProvider;
+}
+export interface MountSessionResponse {
+    workspaceId: string;
+    relayfileBaseUrl: string;
+    relayfileToken: string;
+    wsUrl: string;
+    remotePath: string;
+    localDir: string;
+    mode: MountMode;
+    scopes: string[];
+    tokenIssuedAt: string | null;
+    expiresAt: string | null;
+    suggestedRefreshAt: string | null;
+    relaycastApiKey: string;
+    relaycastBaseUrl?: string;
+}
+export interface MountSessionResult {
+    workspaceId: string;
+    relayfileBaseUrl: string;
+    relayfileToken: string;
+    wsUrl: string;
+    remotePath: string;
+    localDir: string;
+    mode: MountMode;
+    scopes: string[];
+    tokenIssuedAt: string | null;
+    expiresAt: string | null;
+    suggestedRefreshAt: string | null;
+    relaycastApiKey: string;
+    relaycastBaseUrl?: string;
+}
+export interface MountedWorkspaceStatus {
+    ready: boolean;
+    mode: MountMode;
+    pid?: number;
+    lastHeartbeatAt?: string;
+    lastReconcileAt?: string;
+    lastEventAt?: string;
+    expiresAt: string | null;
+    suggestedRefreshAt: string | null;
+    pendingWriteback?: number;
+    pendingConflicts?: number;
+}
+export interface MountedWorkspaceHandle {
+    readonly workspaceId: string;
+    readonly localDir: string;
+    readonly remotePath: string;
+    readonly mode: MountMode;
+    readonly ready: boolean;
+    readonly expiresAt: string | null;
+    readonly suggestedRefreshAt: string | null;
+    env(): Record<string, string>;
+    status(): Promise<MountedWorkspaceStatus>;
+    stop(): Promise<void>;
+}
+export interface MountLauncherEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface MountLauncherStart {
+    env: Record<string, string>;
+    cwd?: string;
+    signal?: AbortSignal;
+    readyTimeoutMs: number;
+    onEvent?: (event: MountLauncherEvent) => void;
+    background?: boolean;
+}
+export interface MountLauncherInstance {
+    pid?: number;
+    ready: Promise<void>;
+    status(): Promise<MountedWorkspaceStatus>;
+    stop(): Promise<void>;
+}
+export interface MountLauncher {
+    start(input: MountLauncherStart): Promise<MountLauncherInstance>;
+}
+export interface MountWorkspaceInput {
+    workspace?: WorkspaceHandle;
+    workspaceId?: string;
+    localDir: string;
+    remotePath?: string;
+    mode?: MountMode;
+    background?: boolean;
+    agentName?: string;
+    scopes?: string[];
+    signal?: AbortSignal;
+    launcher?: MountLauncher;
+    readyTimeoutMs?: number;
+}
+export interface EnsureMountedWorkspaceInput extends MountWorkspaceInput {
+    provider?: WorkspaceIntegrationProvider;
+    verifyProvider?: boolean;
+    providerReadyTimeoutMs?: number;
+}
 export interface AgentWorkspaceInviteOptions {
     agentName?: string;
     relaycastBaseUrl?: string;

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 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";
+import { type EnsureMountedWorkspaceInput, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountedWorkspaceHandle, type MountWorkspaceInput, 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;
@@ -16,6 +16,11 @@ interface NormalizedJoinWorkspaceOptions {
     scopes: string[];
     permissions?: WorkspacePermissions;
 }
+interface ValidatedIntegrationStatusResponse {
+    ready: boolean;
+    state?: string;
+    initialSyncState?: string;
+}
 interface CloudRequestOptions {
     operation: string;
     method: string;
@@ -41,11 +46,15 @@ export declare class RelayfileSetup {
     constructor(options?: RelayfileSetupOptions);
     createWorkspace(options?: CreateWorkspaceOptions): Promise<WorkspaceHandle>;
     joinWorkspace(workspaceId: string, options?: JoinWorkspaceOptions): Promise<WorkspaceHandle>;
+    mountWorkspace(input: MountWorkspaceInput): Promise<MountedWorkspaceHandle>;
+    ensureMountedWorkspace(input: EnsureMountedWorkspaceInput): Promise<MountedWorkspaceHandle>;
     joinWorkspaceResponse(workspaceId: string, options: NormalizedJoinWorkspaceOptions, overrides?: {
         tokenProvider?: AccessTokenProvider;
     }): Promise<ValidatedJoinWorkspaceResponse>;
     requestJson(options: CloudRequestOptions): Promise<unknown>;
     getCloudApiUrl(): string;
+    private resolveWorkspaceForMount;
+    private createMountSession;
 }
 export declare class WorkspaceHandle {
     readonly info: WorkspaceInfo;
@@ -66,6 +75,7 @@ export declare class WorkspaceHandle {
     isConnected(provider: WorkspaceIntegrationProvider, connectionId: string): Promise<boolean>;
     disconnectIntegration(provider: WorkspaceIntegrationProvider, _connectionId?: string): Promise<void>;
     getToken(): string;
+    requestJson(options: Omit<CloudRequestOptions, "tokenProvider">): Promise<unknown>;
     mountEnv(options?: WorkspaceMountEnvOptions): WorkspaceMountEnv;
     /**
      * Build an invite that hands a peer agent the calling workspace's existing
@@ -99,6 +109,9 @@ export declare class WorkspaceHandle {
     private performRefreshToken;
     private getOrRefreshToken;
     private resolveConnectionId;
-    private getConnectionStatus;
+    getConnectionStatus(provider: WorkspaceIntegrationProvider, connectionId: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<ValidatedIntegrationStatusResponse>;
     private resolveRelaycastBaseUrl;
 }

package/dist/setup.js

@@ -1,8 +1,10 @@
+import path from "node:path";
 import { RelayFileClient } from "./client.js";
 import { createRelayfileCloudAccessTokenProvider, runRelayfileCloudLogin } from "./cloud-login.js";
-import { CloudAbortError, CloudApiError, CloudTimeoutError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, UnknownProviderError } from "./setup-errors.js";
+import { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, UnknownProviderError } from "./setup-errors.js";
 import { WORKSPACE_INTEGRATION_PROVIDERS } from "./setup-types.js";
 import { RELAYFILE_SDK_VERSION } from "./version.js";
+import { defaultMountLauncher, readMountedWorkspaceStatus } from "./mount-launcher.js";
 export { RELAYFILE_SDK_VERSION } from "./version.js";
 const DEFAULT_CLOUD_API_URL = "https://agentrelay.com/cloud";
 const DEFAULT_RELAYCAST_BASE_URL = "https://api.relaycast.dev";
@@ -14,6 +16,8 @@ const DEFAULT_AGENT_NAME = "sdk-agent";
 const DEFAULT_SCOPES = ["fs:read", "fs:write"];
 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 TOKEN_REFRESH_AGE_MS = 55 * 60 * 1000;
 export class RelayfileSetup {
     cloudApiUrl;
@@ -99,6 +103,57 @@ export class RelayfileSetup {
             joinOptions
         });
     }
+    async mountWorkspace(input) {
+        const normalized = normalizeMountWorkspaceInput(input);
+        const workspace = await this.resolveWorkspaceForMount(normalized);
+        const mountSession = await this.createMountSession(workspace, normalized);
+        const launcher = normalized.launcher;
+        const launcherInstance = await launcher.start({
+            env: buildMountLauncherEnv(mountSession),
+            signal: normalized.signal,
+            readyTimeoutMs: normalized.readyTimeoutMs,
+            background: normalized.background
+        });
+        try {
+            await waitForMountReady(launcherInstance.ready, normalized.signal);
+        }
+        catch (error) {
+            // If the abort signal fired before waitForMountReady got a chance to
+            // attach a Promise.race handler, ensureLauncher.ready will reject
+            // later. Attach a no-op rejection handler so Node 18+ does not surface
+            // an unhandledRejection (which terminates the process by default).
+            launcherInstance.ready.catch(() => { });
+            await safeStopLauncher(launcherInstance);
+            throw error;
+        }
+        return new MountedWorkspaceHandleImpl({
+            mountSession,
+            launcherInstance: normalized.background ? launcherInstance : undefined,
+            probeOnly: !normalized.background
+        });
+    }
+    async ensureMountedWorkspace(input) {
+        const normalized = normalizeEnsureMountedWorkspaceInput(input);
+        const workspace = await this.resolveWorkspaceForMount(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({
+            workspace,
+            localDir: normalized.localDir,
+            remotePath: normalized.remotePath,
+            mode: normalized.mode,
+            background: normalized.background,
+            agentName: normalized.agentName,
+            scopes: normalized.scopes,
+            signal: normalized.signal,
+            launcher: normalized.launcher,
+            readyTimeoutMs: normalized.readyTimeoutMs
+        });
+    }
     async joinWorkspaceResponse(workspaceId, options, overrides = {}) {
         return validateJoinWorkspaceResponse(await this.requestJson({
             operation: "joinWorkspace",
@@ -163,6 +218,38 @@ export class RelayfileSetup {
     getCloudApiUrl() {
         return this.cloudApiUrl;
     }
+    async resolveWorkspaceForMount(input) {
+        if (input.workspace) {
+            return input.workspace;
+        }
+        return this.joinWorkspace(input.workspaceId, {
+            agentName: input.agentName,
+            scopes: input.scopes
+        });
+    }
+    async createMountSession(workspace, input) {
+        const request = compactObject({
+            localDir: input.localDir,
+            remotePath: input.remotePath,
+            mode: input.mode,
+            agentName: normalizeNonEmptyString(input.agentName) ?? DEFAULT_MOUNT_AGENT_NAME,
+            scopes: input.scopes && input.scopes.length > 0
+                ? [...input.scopes]
+                : undefined
+        });
+        try {
+            return 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);
+        }
+        catch (error) {
+            throw mapMountSessionError(error, request);
+        }
+    }
 }
 export class WorkspaceHandle {
     info;
@@ -259,10 +346,11 @@ export class WorkspaceHandle {
             const remainingMs = timeoutMs - elapsedMs;
             let ready;
             try {
-                ready = await this.getConnectionStatus(provider, connectionId, {
+                const status = await this.getConnectionStatus(provider, connectionId, {
                     signal: options.signal,
                     timeoutMs: remainingMs
                 });
+                ready = status.ready;
             }
             catch (error) {
                 if (error instanceof CloudTimeoutError) {
@@ -287,7 +375,8 @@ export class WorkspaceHandle {
     }
     async isConnected(provider, connectionId) {
         assertProvider(provider);
-        return this.getConnectionStatus(provider, this.resolveConnectionId(provider, connectionId));
+        const status = await this.getConnectionStatus(provider, this.resolveConnectionId(provider, connectionId));
+        return status.ready;
     }
     async disconnectIntegration(provider, _connectionId) {
         assertProvider(provider);
@@ -302,6 +391,12 @@ export class WorkspaceHandle {
     getToken() {
         return this._token;
     }
+    async requestJson(options) {
+        return this._setup.requestJson({
+            ...options,
+            tokenProvider: async () => this.getOrRefreshToken()
+        });
+    }
     mountEnv(options = {}) {
         const relaycastBaseUrl = this.resolveRelaycastBaseUrl(options.relaycastBaseUrl);
         return compactStringRecord({
@@ -426,15 +521,13 @@ export class WorkspaceHandle {
     }
     async getConnectionStatus(provider, connectionId, options = {}) {
         const query = new URLSearchParams({ connectionId });
-        const response = validateIntegrationStatusResponse(await this._setup.requestJson({
+        return validateIntegrationStatusResponse(await this.requestJson({
             operation: "getIntegrationStatus",
             method: "GET",
             path: `api/v1/workspaces/${encodeURIComponent(this.workspaceId)}/integrations/${encodeURIComponent(provider)}/status?${query.toString()}`,
             signal: options.signal,
-            timeoutMs: options.timeoutMs,
-            tokenProvider: async () => this.getOrRefreshToken()
+            timeoutMs: options.timeoutMs
         }));
-        return response.ready;
     }
     resolveRelaycastBaseUrl(override) {
         return (normalizeNonEmptyString(override) ??
@@ -442,6 +535,63 @@ export class WorkspaceHandle {
             DEFAULT_RELAYCAST_BASE_URL);
     }
 }
+class MountedWorkspaceHandleImpl {
+    workspaceId;
+    localDir;
+    remotePath;
+    mode;
+    expiresAt;
+    suggestedRefreshAt;
+    mountSession;
+    launcherInstance;
+    probeOnly;
+    readySnapshot = true;
+    stopPromise;
+    constructor(input) {
+        this.mountSession = input.mountSession;
+        this.workspaceId = input.mountSession.workspaceId;
+        this.localDir = input.mountSession.localDir;
+        this.remotePath = input.mountSession.remotePath;
+        this.mode = input.mountSession.mode;
+        this.expiresAt = input.mountSession.expiresAt;
+        this.suggestedRefreshAt = input.mountSession.suggestedRefreshAt;
+        this.launcherInstance = input.launcherInstance;
+        this.probeOnly = input.probeOnly;
+    }
+    get ready() {
+        return this.readySnapshot;
+    }
+    env() {
+        return buildMountedWorkspaceEnv(this.mountSession);
+    }
+    async status() {
+        const status = await readMountedWorkspaceStatus({
+            localDir: this.localDir,
+            workspaceId: this.workspaceId,
+            remotePath: this.remotePath,
+            mode: this.mode,
+            relayfileBaseUrl: this.mountSession.relayfileBaseUrl,
+            relayfileToken: this.mountSession.relayfileToken,
+            expiresAt: this.expiresAt,
+            suggestedRefreshAt: this.suggestedRefreshAt,
+            pid: this.launcherInstance?.pid
+        });
+        this.readySnapshot = status.ready;
+        return status;
+    }
+    async stop() {
+        if (!this.stopPromise) {
+            this.stopPromise = this.performStop();
+        }
+        await this.stopPromise;
+    }
+    async performStop() {
+        if (this.probeOnly || !this.launcherInstance) {
+            return;
+        }
+        await safeStopLauncher(this.launcherInstance);
+    }
+}
 function assertProvider(provider) {
     if (!WORKSPACE_INTEGRATION_PROVIDERS.includes(provider)) {
         throw new UnknownProviderError(provider);
@@ -494,7 +644,26 @@ function validateConnectSessionResponse(payload) {
 }
 function validateIntegrationStatusResponse(payload) {
     return {
-        ready: requireBooleanField(payload, "ready")
+        ready: requireBooleanField(payload, "ready"),
+        state: readOptionalStringField(payload, "state"),
+        initialSyncState: readOptionalNestedStringField(payload, ["initialSync", "state"])
+    };
+}
+function validateMountSessionResponse(payload, localDir) {
+    return {
+        workspaceId: requireStringField(payload, "workspaceId"),
+        relayfileBaseUrl: stripTrailingSlash(requireStringField(payload, "relayfileBaseUrl")),
+        relayfileToken: requireStringField(payload, "relayfileToken"),
+        wsUrl: requireStringField(payload, "wsUrl"),
+        remotePath: requireStringField(payload, "remotePath"),
+        localDir,
+        mode: requireMountModeField(payload, "mode"),
+        scopes: requireStringArrayField(payload, "scopes"),
+        tokenIssuedAt: readNullableStringField(payload, "tokenIssuedAt"),
+        expiresAt: readNullableStringField(payload, "expiresAt"),
+        suggestedRefreshAt: readNullableStringField(payload, "suggestedRefreshAt"),
+        relaycastApiKey: requireStringField(payload, "relaycastApiKey"),
+        relaycastBaseUrl: readOptionalStringField(payload, "relaycastBaseUrl")
     };
 }
 function requireStringField(payload, field) {
@@ -514,6 +683,30 @@ function readOptionalStringField(payload, field) {
     }
     return value;
 }
+function readNullableStringField(payload, field) {
+    const value = readField(payload, field);
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function readOptionalNestedStringField(payload, pathSegments) {
+    const parent = readField(payload, pathSegments[0]);
+    if (!parent || typeof parent !== "object" || Array.isArray(parent)) {
+        return undefined;
+    }
+    const value = parent[pathSegments[1]];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new MalformedCloudResponseError(pathSegments.join("."), payload);
+    }
+    return value;
+}
 function requireBooleanField(payload, field) {
     const value = readField(payload, field);
     if (typeof value !== "boolean") {
@@ -521,6 +714,20 @@ function requireBooleanField(payload, field) {
     }
     return value;
 }
+function requireMountModeField(payload, field) {
+    const value = requireStringField(payload, field);
+    if (value !== "poll" && value !== "fuse") {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return value;
+}
+function requireStringArrayField(payload, field) {
+    const value = readField(payload, field);
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new MalformedCloudResponseError(field, payload);
+    }
+    return [...value];
+}
 function readField(payload, field) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
         return undefined;
@@ -530,6 +737,59 @@ function readField(payload, field) {
 function normalizeConnectionId(connectionId) {
     return normalizeNonEmptyString(connectionId);
 }
+function normalizeMountWorkspaceInput(input) {
+    if (!!input.workspace === !!input.workspaceId) {
+        throw new MountSessionInputError("Exactly one of workspace or workspaceId must be provided.");
+    }
+    const localDir = normalizeNonEmptyString(input.localDir);
+    if (!localDir) {
+        throw new InvalidLocalDirError(String(input.localDir ?? ""));
+    }
+    return {
+        workspace: input.workspace,
+        workspaceId: normalizeNonEmptyString(input.workspaceId),
+        localDir: path.resolve(localDir),
+        remotePath: normalizeMountRemotePath(input.remotePath),
+        mode: normalizeMountModeInput(input.mode),
+        background: input.background !== false,
+        agentName: normalizeNonEmptyString(input.agentName),
+        scopes: input.scopes && input.scopes.length > 0 ? [...input.scopes] : undefined,
+        signal: input.signal,
+        launcher: input.launcher ?? defaultMountLauncher,
+        readyTimeoutMs: Math.max(1, Math.floor(input.readyTimeoutMs ?? DEFAULT_MOUNT_READY_TIMEOUT_MS))
+    };
+}
+function normalizeEnsureMountedWorkspaceInput(input) {
+    const normalized = normalizeMountWorkspaceInput(input);
+    return {
+        ...normalized,
+        provider: input.provider,
+        verifyProvider: input.verifyProvider !== false,
+        providerReadyTimeoutMs: Math.max(0, Math.floor(input.providerReadyTimeoutMs ?? 0))
+    };
+}
+function normalizeMountModeInput(mode) {
+    const normalized = normalizeNonEmptyString(mode) ?? "poll";
+    if (normalized !== "poll" && normalized !== "fuse") {
+        throw new InvalidMountModeError(normalized);
+    }
+    return normalized;
+}
+function normalizeMountRemotePath(remotePath) {
+    const normalized = normalizeNonEmptyString(remotePath) ?? "/";
+    if (normalized.includes("\u0000")) {
+        throw new InvalidRemotePathError(normalized);
+    }
+    const segments = normalized.replace(/\\/g, "/").split("/");
+    if (segments.some((segment) => segment === "..")) {
+        throw new InvalidRemotePathError(normalized);
+    }
+    const resolved = path.posix.normalize(normalized.startsWith("/") ? normalized : `/${normalized}`);
+    if (!resolved.startsWith("/")) {
+        throw new InvalidRemotePathError(normalized);
+    }
+    return resolved === "/" ? "/" : resolved.replace(/\/+$/, "");
+}
 function normalizeNonEmptyString(value) {
     const normalized = value?.trim();
     return normalized ? normalized : undefined;
@@ -552,6 +812,31 @@ function compactStringRecord(value) {
         return entryValue !== undefined;
     }));
 }
+function buildMountedWorkspaceEnv(mountSession) {
+    const relaycastBaseUrl = normalizeNonEmptyString(mountSession.relaycastBaseUrl) ??
+        DEFAULT_RELAYCAST_BASE_URL;
+    return compactStringRecord({
+        RELAYFILE_BASE_URL: mountSession.relayfileBaseUrl,
+        RELAYFILE_TOKEN: mountSession.relayfileToken,
+        RELAYFILE_WORKSPACE: mountSession.workspaceId,
+        RELAYFILE_REMOTE_PATH: mountSession.remotePath,
+        RELAYFILE_LOCAL_DIR: mountSession.localDir,
+        RELAYFILE_MOUNT_MODE: mountSession.mode,
+        RELAYCAST_API_KEY: mountSession.relaycastApiKey,
+        RELAY_API_KEY: mountSession.relaycastApiKey,
+        RELAYCAST_BASE_URL: relaycastBaseUrl,
+        RELAY_BASE_URL: relaycastBaseUrl
+    });
+}
+function buildMountLauncherEnv(mountSession) {
+    return compactStringRecord({
+        ...buildMountedWorkspaceEnv(mountSession),
+        RELAYFILE_MOUNT_SCOPES: mountSession.scopes.join(" ")
+    });
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
 function buildCloudUrl(baseUrl, path) {
     const base = new URL(baseUrl);
     if (!base.pathname.endsWith("/")) {
@@ -672,3 +957,100 @@ function throwIfAborted(signal, operation) {
         throw new CloudAbortError(operation);
     }
 }
+async function waitForMountReady(ready, signal) {
+    if (!signal) {
+        await ready;
+        return;
+    }
+    if (signal.aborted) {
+        throw new CloudAbortError("mountWorkspace");
+    }
+    let onAbort;
+    try {
+        await Promise.race([
+            ready,
+            new Promise((_, reject) => {
+                onAbort = () => {
+                    signal.removeEventListener("abort", onAbort);
+                    reject(new CloudAbortError("mountWorkspace"));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            })
+        ]);
+    }
+    finally {
+        if (onAbort) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+}
+async function safeStopLauncher(launcherInstance) {
+    try {
+        await launcherInstance.stop();
+    }
+    catch {
+        // stop is best-effort during cleanup
+    }
+}
+async function verifyWorkspaceProviderReady(workspace, provider, providerReadyTimeoutMs, signal) {
+    const startedAt = Date.now();
+    const connectionId = workspace.workspaceId;
+    for (;;) {
+        throwIfAborted(signal, "ensureMountedWorkspace");
+        const elapsedMs = Date.now() - startedAt;
+        const remainingMs = providerReadyTimeoutMs <= 0
+            ? undefined
+            : Math.max(1, providerReadyTimeoutMs - elapsedMs);
+        const status = await workspace.getConnectionStatus(provider, connectionId, {
+            signal,
+            timeoutMs: remainingMs
+        });
+        if (status.ready) {
+            return;
+        }
+        // Integration status uses state="not_connected" to signal a provider that
+        // has never been connected. Other non-ready states still indicate a
+        // connected provider and map to ProviderNotReadyError.
+        if (status.state === "not_connected") {
+            throw new ProviderNotConnectedError(provider);
+        }
+        if (providerReadyTimeoutMs <= 0 || elapsedMs >= providerReadyTimeoutMs) {
+            throw new ProviderNotReadyError({
+                provider,
+                state: status.state,
+                initialSyncState: status.initialSyncState
+            });
+        }
+        const sleepMs = Math.min(DEFAULT_WAIT_INTERVAL_MS, Math.max(1, providerReadyTimeoutMs - elapsedMs));
+        await sleep(sleepMs, signal, "ensureMountedWorkspace");
+    }
+}
+function mapMountSessionError(error, request) {
+    if (!(error instanceof CloudApiError) || error.httpStatus !== 400) {
+        return error;
+    }
+    const code = readCloudErrorCode(error.httpBody);
+    switch (code) {
+        case "invalid_mode":
+            return new InvalidMountModeError(request.mode ?? "poll");
+        case "invalid_local_dir":
+            return new InvalidLocalDirError(request.localDir);
+        case "invalid_remote_path":
+            return new InvalidRemotePathError(request.remotePath ?? "/");
+        default:
+            return error;
+    }
+}
+function readCloudErrorCode(httpBody) {
+    if (!httpBody || typeof httpBody !== "object" || Array.isArray(httpBody)) {
+        return undefined;
+    }
+    const payload = httpBody;
+    for (const field of ["code", "error"]) {
+        const value = payload[field];
+        if (typeof value === "string" && value.trim() !== "") {
+            return value;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:e2e": "node scripts/setup-e2e.mjs",
+    "post-auth-mount:e2e": "node scripts/post-auth-mount-session-e2e.mjs",
+    "e2e:post-auth-mount-session": "node scripts/post-auth-mount-session-e2e.mjs",
     "agent-workspace:e2e": "node scripts/agent-workspace-golden-path-e2e.mjs",
     "test:e2e:golden-path": "node scripts/agent-workspace-golden-path-e2e.mjs",
     "demo:agent-workspace": "npm run build && node scripts/agent-workspace-demo.mjs",
@@ -20,7 +22,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.7.1"
+    "@relayfile/core": "0.7.2"
   },
   "devDependencies": {
     "typescript": "^5.7.3",