@relayfile/sdk 0.8.10 → 0.8.11

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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 { 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";

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.8.10",
+  "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.10",
+    "@relayfile/core": "0.8.11",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },