@relayfile/sdk 0.7.38 → 0.8.0

package/dist/index.js

@@ -9,3 +9,10 @@ export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiEr
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
 export { WritebackConsumer } from "./writeback-consumer.js";
 export * from "./integration-adapter.js";
+// Agent workspace provisioning helpers (`seedWorkspace`, `seedAclRules`,
+// `ensureRelayfileMount`, …) live in CLI-only modules that statically pull in
+// `node:child_process`, `node:fs`, and `node:path`. They are intentionally
+// excluded from the default entry so browser/edge consumers stay node-free.
+// Import them from the explicit subpaths instead:
+//   `@relayfile/sdk/workspace-seeder`
+//   `@relayfile/sdk/workspace-mount`

package/dist/workspace-mount.d.ts

@@ -0,0 +1,13 @@
+export interface MountConfig {
+    binaryPath?: string;
+    relayfileUrl: string;
+    workspace: string;
+    token: string;
+    mountPoint?: string;
+}
+export interface MountHandle {
+    pid: number;
+    mountPoint: string;
+    stop(): Promise<void>;
+}
+export declare function ensureRelayfileMount(config: MountConfig): Promise<MountHandle>;

package/dist/workspace-mount.js

@@ -0,0 +1,373 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { accessSync, chmodSync, constants, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+const RELAYFILE_VERSION = '0.1.6';
+const RELEASE_BASE_URL = 'https://github.com/AgentWorkforce/relayfile/releases/download';
+const CHECKSUMS_FILE = 'checksums.txt';
+const CACHE_DIR = path.join(os.homedir(), '.agent-relay', 'bin');
+const CACHE_PATH = path.join(CACHE_DIR, 'relayfile-mount');
+const VERSION_PATH = path.join(CACHE_DIR, 'relayfile-mount.version');
+const SUPPORTED_TARGETS = ['darwin-arm64', 'darwin-amd64', 'linux-arm64', 'linux-amd64'].join(', ');
+const PLATFORM_ARCH_MAP = {
+    'darwin:arm64': 'darwin-arm64',
+    'darwin:x64': 'darwin-amd64',
+    'linux:arm64': 'linux-arm64',
+    'linux:x64': 'linux-amd64',
+};
+function ensureCacheDir() {
+    mkdirSync(CACHE_DIR, { recursive: true });
+}
+function getRelayfileTarget() {
+    const target = PLATFORM_ARCH_MAP[`${os.platform()}:${os.arch()}`];
+    if (!target) {
+        throw new Error(`Unsupported platform for relayfile-mount: ${os.platform()}-${os.arch()}. Supported targets: ${SUPPORTED_TARGETS}.`);
+    }
+    return target;
+}
+function getReleaseAssetUrl(assetName) {
+    return `${RELEASE_BASE_URL}/v${RELAYFILE_VERSION}/${assetName}`;
+}
+function readCachedVersion() {
+    try {
+        return readFileSync(VERSION_PATH, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function isExecutable(filePath) {
+    try {
+        accessSync(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function downloadErrorMessage(url, status) {
+    return `Download failed with status ${status} for ${url}`;
+}
+function downloadBinary(url, destPath, maxRedirects = 5) {
+    ensureCacheDir();
+    const attemptDownload = (currentUrl, redirectsRemaining, resolve, reject) => {
+        const request = https.get(currentUrl, (res) => {
+            const status = res.statusCode ?? 0;
+            const location = res.headers.location;
+            const isRedirect = status >= 300 && status < 400 && location;
+            if (isRedirect) {
+                if (redirectsRemaining <= 0) {
+                    res.resume();
+                    reject(new Error('Too many redirects while downloading relayfile-mount'));
+                    return;
+                }
+                const nextUrl = new URL(location, currentUrl).toString();
+                res.resume();
+                attemptDownload(nextUrl, redirectsRemaining - 1, resolve, reject);
+                return;
+            }
+            if (status !== 200) {
+                res.resume();
+                reject(new Error(downloadErrorMessage(currentUrl, status)));
+                return;
+            }
+            const fileStream = createWriteStream(destPath, { mode: 0o755 });
+            res.pipe(fileStream);
+            fileStream.on('finish', () => {
+                fileStream.close(() => resolve());
+            });
+            fileStream.on('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+            res.on('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        });
+        request.on('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+    };
+    return new Promise((resolve, reject) => {
+        attemptDownload(url, maxRedirects, resolve, reject);
+    }).catch((error) => {
+        try {
+            rmSync(destPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup failures.
+        }
+        throw error;
+    });
+}
+function downloadText(url, maxRedirects = 5) {
+    const fetchWithRedirects = (currentUrl, redirectsRemaining, resolve, reject) => {
+        const request = https.get(currentUrl, (res) => {
+            const status = res.statusCode ?? 0;
+            const location = res.headers.location;
+            const isRedirect = status >= 300 && status < 400 && location;
+            if (isRedirect) {
+                if (redirectsRemaining <= 0) {
+                    res.resume();
+                    reject(new Error('Too many redirects while downloading relayfile checksums'));
+                    return;
+                }
+                const nextUrl = new URL(location, currentUrl).toString();
+                res.resume();
+                fetchWithRedirects(nextUrl, redirectsRemaining - 1, resolve, reject);
+                return;
+            }
+            if (status !== 200) {
+                res.resume();
+                reject(new Error(downloadErrorMessage(currentUrl, status)));
+                return;
+            }
+            const chunks = [];
+            res.on('data', (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            res.on('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        });
+        request.on('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+    };
+    return new Promise((resolve, reject) => {
+        fetchWithRedirects(url, maxRedirects, resolve, reject);
+    });
+}
+function getExpectedChecksum(checksumContent, binaryName) {
+    for (const line of checksumContent.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const match = trimmed.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+        if (!match) {
+            continue;
+        }
+        const entryName = path.basename(match[2].trim());
+        if (entryName === binaryName) {
+            return match[1].toLowerCase();
+        }
+    }
+    throw new Error(`No checksum entry found for ${binaryName}`);
+}
+async function verifyChecksum(filePath, binaryName) {
+    const checksumUrl = getReleaseAssetUrl(CHECKSUMS_FILE);
+    const checksumContent = await downloadText(checksumUrl);
+    const expectedHash = getExpectedChecksum(checksumContent, binaryName);
+    const actualHash = createHash('sha256').update(readFileSync(filePath)).digest('hex');
+    if (actualHash !== expectedHash) {
+        throw new Error(`Checksum mismatch for ${binaryName}: expected ${expectedHash}, got ${actualHash}`);
+    }
+}
+function resignBinaryForMacOS(binaryPath) {
+    if (os.platform() !== 'darwin') {
+        return;
+    }
+    try {
+        // Pass the binary path as a separate argv entry so shell metacharacters
+        // in the cache path cannot break or hijack the codesign invocation.
+        execFileSync('codesign', ['--force', '--sign', '-', binaryPath], { stdio: 'pipe' });
+    }
+    catch {
+        // Ignore best-effort re-sign failures.
+    }
+}
+async function ensureRelayfileMountBinary(binaryPath) {
+    if (binaryPath) {
+        return binaryPath;
+    }
+    if (process.env.RELAYFILE_ROOT) {
+        return path.join(process.env.RELAYFILE_ROOT, 'bin', 'relayfile-mount');
+    }
+    const target = getRelayfileTarget();
+    const binaryName = `relayfile-mount-${target}`;
+    const downloadUrl = getReleaseAssetUrl(binaryName);
+    ensureCacheDir();
+    if (existsSync(CACHE_PATH) && readCachedVersion() === RELAYFILE_VERSION) {
+        if (!isExecutable(CACHE_PATH)) {
+            chmodSync(CACHE_PATH, 0o755);
+        }
+        return CACHE_PATH;
+    }
+    const tempPath = path.join(CACHE_DIR, `relayfile-mount.${process.pid}.${Date.now()}.download`);
+    try {
+        await downloadBinary(downloadUrl, tempPath);
+        await verifyChecksum(tempPath, binaryName);
+        chmodSync(tempPath, 0o755);
+        renameSync(tempPath, CACHE_PATH);
+        chmodSync(CACHE_PATH, 0o755);
+        resignBinaryForMacOS(CACHE_PATH);
+        writeFileSync(VERSION_PATH, `${RELAYFILE_VERSION}\n`, 'utf8');
+        return CACHE_PATH;
+    }
+    catch (error) {
+        try {
+            rmSync(tempPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup failures.
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to install relayfile-mount from ${downloadUrl}: ${message}`);
+    }
+}
+const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+async function runCommandCapture(command, args, env, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+    return await new Promise((resolve, reject) => {
+        const proc = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+        let output = '';
+        let settled = false;
+        const settle = (fn) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            // Best-effort terminate the stalled child so we don't leak the process.
+            try {
+                proc.kill('SIGTERM');
+            }
+            catch {
+                // Ignore kill failures; the timeout error below is what matters.
+            }
+            settle(() => reject(new Error(`command timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        proc.stdout.setEncoding('utf8');
+        proc.stderr.setEncoding('utf8');
+        proc.stdout.on('data', (chunk) => {
+            output += chunk;
+        });
+        proc.stderr.on('data', (chunk) => {
+            output += chunk;
+        });
+        proc.on('error', (error) => {
+            settle(() => reject(error));
+        });
+        proc.on('close', (code, signal) => {
+            if (code === 0) {
+                settle(() => resolve(output));
+                return;
+            }
+            const reason = signal ? `signal ${signal}` : `exit code ${typeof code === 'number' ? code : 'unknown'}`;
+            const detail = output.trim();
+            settle(() => reject(new Error(detail || `command failed with ${reason}`)));
+        });
+    });
+}
+function ensureProcessRunning(processRef) {
+    return processRef.exitCode === null && !processRef.killed;
+}
+async function stopMountProcess(processRef) {
+    if (processRef.exitCode !== null || !processRef.pid) {
+        return;
+    }
+    processRef.kill('SIGTERM');
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (processRef.exitCode === null && processRef.pid) {
+                processRef.kill('SIGKILL');
+            }
+            resolve();
+        }, 1200);
+        processRef.once('exit', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+export async function ensureRelayfileMount(config) {
+    const binaryPath = await ensureRelayfileMountBinary(config.binaryPath);
+    if (!existsSync(binaryPath)) {
+        throw new Error(`missing relayfile mount binary: ${binaryPath}`);
+    }
+    // Track whether we created the mountPoint ourselves. We must only `rm` the
+    // directory on shutdown/failure when this function owns it — never when a
+    // caller passed their own path, since that could destroy unrelated user data.
+    let mountPoint;
+    let ownsMountPoint;
+    if (config.mountPoint) {
+        mountPoint = config.mountPoint;
+        ownsMountPoint = false;
+        mkdirSync(mountPoint, { recursive: true });
+    }
+    else {
+        mountPoint = await mkdtemp(path.join(os.tmpdir(), `relayfile-mount-${config.workspace}-`));
+        ownsMountPoint = true;
+    }
+    const cleanupMountPoint = async () => {
+        if (!ownsMountPoint) {
+            return;
+        }
+        await rm(mountPoint, { recursive: true, force: true }).catch(() => undefined);
+    };
+    const mountBaseArgs = [
+        '--base-url',
+        config.relayfileUrl,
+        '--workspace',
+        config.workspace,
+        '--local-dir',
+        mountPoint,
+    ];
+    const onceArgs = [...mountBaseArgs, '--once'];
+    const mountEnv = {
+        ...process.env,
+        RELAYFILE_TOKEN: config.token,
+    };
+    let mountProc;
+    let startupPhase = 'initial workspace sync';
+    try {
+        await runCommandCapture(binaryPath, onceArgs, mountEnv);
+        startupPhase = 'mount process startup';
+        const startedMountProc = spawn(binaryPath, mountBaseArgs, {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            env: mountEnv,
+        });
+        mountProc = startedMountProc;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => resolve(), 600);
+            startedMountProc.on('error', (spawnError) => {
+                clearTimeout(timer);
+                reject(spawnError);
+            });
+            startedMountProc.on('spawn', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        if (!ensureProcessRunning(startedMountProc) || typeof startedMountProc.pid !== 'number') {
+            await stopMountProcess(startedMountProc).catch(() => undefined);
+            throw new Error(`mount process for workspace ${config.workspace} exited before continuing`);
+        }
+    }
+    catch (error) {
+        if (mountProc) {
+            await stopMountProcess(mountProc).catch(() => undefined);
+        }
+        await cleanupMountPoint();
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${startupPhase} failed for ${config.workspace}: ${message}`);
+    }
+    if (!mountProc || typeof mountProc.pid !== 'number') {
+        await cleanupMountPoint();
+        throw new Error(`mount process startup failed for ${config.workspace}: missing process id`);
+    }
+    let stopPromise;
+    const startedMountProc = mountProc;
+    return {
+        pid: mountProc.pid,
+        mountPoint,
+        async stop() {
+            if (!stopPromise) {
+                // Memoize the in-flight shutdown so concurrent callers all await the
+                // same termination + cleanup sequence instead of returning early
+                // before stopMountProcess and cleanupMountPoint have settled.
+                stopPromise = (async () => {
+                    await stopMountProcess(startedMountProc).catch(() => undefined);
+                    await cleanupMountPoint();
+                })();
+            }
+            await stopPromise;
+        },
+    };
+}

package/dist/workspace-seeder.d.ts

@@ -0,0 +1,16 @@
+interface WorkflowAclAgent {
+    name: string;
+    acl: Record<string, string[]>;
+}
+interface SeedWorkflowAclsOptions {
+    relayfileUrl: string;
+    adminToken: string;
+    workspace: string;
+    agents: WorkflowAclAgent[];
+}
+export declare function createWorkspaceIfNeeded(baseUrl: string, token: string, workspaceId: string): Promise<void>;
+export declare function seedAclRules(baseUrl: string, token: string, workspaceId: string, aclRules: Record<string, string[]>): Promise<void>;
+export declare function seedWorkspace(baseUrl: string, token: string, workspaceId: string, projectDir: string, excludeDirs: string[]): Promise<number>;
+export declare function seedWorkflowAcls({ relayfileUrl, adminToken, workspace, agents, }: SeedWorkflowAclsOptions): Promise<void>;
+export declare function seedWorkspaceTar(baseUrl: string, token: string, workspaceId: string, projectDir: string, excludeDirs: string[]): Promise<number>;
+export {};

package/dist/workspace-seeder.js

@@ -0,0 +1,480 @@
+import { RelayFileClient } from './client.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as tar from 'tar';
+const DEFAULT_EXCLUDED_DIRS = ['.relay', '.git', 'node_modules'];
+const DEFAULT_EXCLUDED_FILES = new Set(['.relayfile-mount-state.json']);
+const BATCH_SIZE = 50;
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+function normalizeBaseUrl(baseUrl) {
+    const url = String(baseUrl ?? '').trim();
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 0x2f) {
+        end--;
+    }
+    return end === url.length ? url : url.slice(0, end);
+}
+function normalizeWorkspaceId(workspaceId) {
+    const value = String(workspaceId ?? '').trim();
+    if (!value) {
+        throw new Error('workspaceId is required');
+    }
+    return value;
+}
+function normalizeExcludeDirs(excludeDirs) {
+    const result = new Set();
+    for (const dir of excludeDirs) {
+        const normalized = String(dir ?? '')
+            .trim()
+            .replace(/^[/\\]+|[/\\]+$/g, '');
+        if (!normalized) {
+            continue;
+        }
+        result.add(normalized);
+    }
+    return result;
+}
+function normalizeAclDirectory(dirPath) {
+    const normalized = String(dirPath ?? '')
+        .trim()
+        .replace(/\\/gu, '/')
+        .replace(/\/+$/u, '');
+    if (!normalized || normalized === '/') {
+        return '/';
+    }
+    return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+function isReviewerAgent(agentName) {
+    return /reviewer/iu.test(String(agentName ?? '').trim());
+}
+function createClient(baseUrl, token) {
+    return new RelayFileClient({
+        baseUrl: normalizeBaseUrl(baseUrl),
+        token,
+        retry: { maxRetries: 0 },
+    });
+}
+function isUtf8(raw) {
+    try {
+        utf8Decoder.decode(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function buildSeedFilePayload(filePath, rootDir) {
+    const relative = path.relative(rootDir, filePath).split(path.sep).join('/');
+    const raw = fs.readFileSync(filePath);
+    if (isUtf8(raw)) {
+        return { path: `/${relative}`, content: raw.toString('utf8'), encoding: 'utf-8' };
+    }
+    return { path: `/${relative}`, content: raw.toString('base64'), encoding: 'base64' };
+}
+function collectSeedPaths(rootDir, currentRelative, excludeDirs, output, visited = new Set()) {
+    const absoluteDir = path.join(rootDir, currentRelative);
+    let realDir;
+    try {
+        realDir = fs.realpathSync(absoluteDir);
+    }
+    catch {
+        return;
+    }
+    if (visited.has(realDir)) {
+        // Cycle guard: a symlinked directory pointed back to an ancestor.
+        return;
+    }
+    visited.add(realDir);
+    const entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (excludeDirs.has(entry.name)) {
+            continue;
+        }
+        if (DEFAULT_EXCLUDED_FILES.has(entry.name)) {
+            continue;
+        }
+        const nextRelative = currentRelative ? `${currentRelative}/${entry.name}` : entry.name;
+        const absolutePath = path.join(rootDir, nextRelative);
+        if (excludeDirs.has(nextRelative)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            collectSeedPaths(rootDir, nextRelative, excludeDirs, output, visited);
+            continue;
+        }
+        if (entry.isFile()) {
+            output.push(absolutePath);
+            continue;
+        }
+        if (entry.isSymbolicLink()) {
+            try {
+                const resolved = fs.realpathSync(absolutePath);
+                if (!resolved.startsWith(rootDir + path.sep) && resolved !== rootDir) {
+                    continue;
+                }
+                const stat = fs.statSync(resolved);
+                if (stat.isDirectory()) {
+                    collectSeedPaths(rootDir, nextRelative, excludeDirs, output, visited);
+                    continue;
+                }
+                if (stat.isFile()) {
+                    output.push(absolutePath);
+                }
+            }
+            catch {
+                // Ignore symlinks that cannot be resolved.
+            }
+        }
+    }
+}
+function parseBulkWriteResponse(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { written: 0, errorCount: 0, errors: [] };
+    }
+    const parsed = payload;
+    return {
+        written: typeof parsed.written === 'number' ? parsed.written : 0,
+        errorCount: typeof parsed.errorCount === 'number' ? parsed.errorCount : 0,
+        errors: parsed.errors ?? [],
+    };
+}
+async function postBulkWrite(baseUrl, token, workspaceId, files, correlationId) {
+    const response = await fetch(`${normalizeBaseUrl(baseUrl)}/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/bulk`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'X-Correlation-Id': correlationId,
+        },
+        body: JSON.stringify({ files }),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new Error(`failed to seed workspace ${workspaceId}: HTTP ${response.status} ${body}`.trim());
+    }
+    if (!body) {
+        return { written: files.length, errorCount: 0, errors: [] };
+    }
+    try {
+        return parseBulkWriteResponse(JSON.parse(body));
+    }
+    catch {
+        return { written: files.length, errorCount: 0, errors: [] };
+    }
+}
+async function writeBulkWrite(baseUrl, token, workspaceId, files, correlationId) {
+    const client = createClient(baseUrl, token);
+    try {
+        const response = await client.bulkWrite({
+            workspaceId,
+            files,
+            correlationId,
+        });
+        return parseBulkWriteResponse(response);
+    }
+    catch (error) {
+        if (typeof error.status === 'number') {
+            throw error;
+        }
+    }
+    return postBulkWrite(baseUrl, token, workspaceId, files, correlationId);
+}
+export async function createWorkspaceIfNeeded(baseUrl, token, workspaceId) {
+    const workspace = normalizeWorkspaceId(workspaceId);
+    const client = createClient(baseUrl, token);
+    const maybeCreateWorkspace = client;
+    if (typeof maybeCreateWorkspace.createWorkspace === 'function') {
+        for (const arg of [workspace, { id: workspace }, { workspaceId: workspace }, { name: workspace }]) {
+            try {
+                await maybeCreateWorkspace.createWorkspace(arg);
+                return;
+            }
+            catch {
+                // Continue to the next overload candidate, then fallback to HTTP.
+            }
+        }
+    }
+    const endpoint = `${normalizeBaseUrl(baseUrl)}/v1/workspaces`;
+    const bodyCandidates = [
+        { name: workspace },
+        { workspace: workspace },
+        { workspaceId: workspace },
+        { id: workspace },
+    ];
+    let lastFailure = null;
+    for (const body of bodyCandidates) {
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                    'X-Correlation-Id': `create-workspace-${Date.now()}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (response.status === 200 ||
+                response.status === 201 ||
+                response.status === 204 ||
+                response.status === 409) {
+                return;
+            }
+            const responseBody = await response.text().catch(() => '');
+            lastFailure = `HTTP ${response.status} ${responseBody}`.trim();
+            if (response.status < 500 && response.status !== 409) {
+                continue;
+            }
+        }
+        catch (error) {
+            lastFailure = String(error);
+        }
+    }
+    if (lastFailure) {
+        throw new Error(`Failed to create workspace ${workspace}: ${lastFailure}`);
+    }
+}
+export async function seedAclRules(baseUrl, token, workspaceId, aclRules) {
+    const workspace = normalizeWorkspaceId(workspaceId);
+    const files = Object.entries(aclRules).map(([dirPath, rules]) => {
+        const normalizedDir = String(dirPath ?? '')
+            .trim()
+            .replace(/\/+$/, '');
+        const aclPath = normalizedDir === '' || normalizedDir === '/' ? '/.relayfile.acl' : `${normalizedDir}/.relayfile.acl`;
+        return {
+            path: aclPath,
+            content: JSON.stringify({ semantics: { permissions: rules } }),
+            encoding: 'utf-8',
+        };
+    });
+    if (files.length === 0) {
+        return;
+    }
+    const result = await writeBulkWrite(baseUrl, token, workspace, files, `seed-acl-${workspace}-${Date.now()}`);
+    if (result.errorCount > 0) {
+        const details = result.errors ? JSON.stringify(result.errors) : '[]';
+        throw new Error(`ACL seeding had ${result.errorCount} error(s) for workspace ${workspace}: ${details}`);
+    }
+}
+export async function seedWorkspace(baseUrl, token, workspaceId, projectDir, excludeDirs) {
+    const workspace = normalizeWorkspaceId(workspaceId);
+    const rootDir = path.resolve(projectDir);
+    const excludes = normalizeExcludeDirs([...DEFAULT_EXCLUDED_DIRS, ...excludeDirs]);
+    const seedPaths = [];
+    collectSeedPaths(rootDir, '', excludes, seedPaths);
+    const allFiles = seedPaths
+        .sort((left, right) => left.localeCompare(right))
+        .map((filePath) => buildSeedFilePayload(filePath, rootDir));
+    let seededCount = 0;
+    let totalErrorCount = 0;
+    const collectedErrors = [];
+    for (let index = 0; index < allFiles.length; index += BATCH_SIZE) {
+        const batch = allFiles.slice(index, index + BATCH_SIZE);
+        const batchIndex = Math.floor(index / BATCH_SIZE);
+        const result = await writeBulkWrite(baseUrl, token, workspace, batch, `seed-workspace-${workspace}-${Date.now()}-${batchIndex}`);
+        seededCount += result.written;
+        totalErrorCount += result.errorCount;
+        if (Array.isArray(result.errors)) {
+            collectedErrors.push(...result.errors);
+        }
+        else if (result.errors && result.errorCount > 0) {
+            collectedErrors.push(result.errors);
+        }
+    }
+    if (totalErrorCount > 0) {
+        const details = collectedErrors.length > 0 ? JSON.stringify(collectedErrors) : '[]';
+        throw new Error(`seedWorkspace had ${totalErrorCount} error(s) for workspace ${workspace}: ${details}`);
+    }
+    return seededCount;
+}
+function buildWorkflowAclRules(agents) {
+    const directories = new Set();
+    const normalizedAgents = agents.map((agent) => ({
+        name: String(agent.name ?? '').trim(),
+        acl: Object.fromEntries(Object.entries(agent.acl ?? {}).map(([dirPath, rules]) => [
+            normalizeAclDirectory(dirPath),
+            Array.isArray(rules) ? rules : [],
+        ])),
+    }));
+    const reviewerNames = normalizedAgents
+        .map((agent) => agent.name)
+        .filter((name) => name !== '' && isReviewerAgent(name));
+    for (const agent of normalizedAgents) {
+        for (const dirPath of Object.keys(agent.acl)) {
+            directories.add(dirPath);
+        }
+    }
+    const merged = new Map();
+    for (const dirPath of [...directories].sort((left, right) => left.localeCompare(right))) {
+        const rules = new Set();
+        for (const reviewerName of reviewerNames) {
+            rules.add(`allow:agent:${reviewerName}:read`);
+        }
+        for (const agent of normalizedAgents) {
+            if (!agent.name) {
+                continue;
+            }
+            const agentRules = agent.acl[dirPath] ?? [];
+            const hasRead = agentRules.includes('read') || agentRules.includes('write');
+            const hasWrite = agentRules.includes('write');
+            if (hasRead) {
+                rules.add(`allow:agent:${agent.name}:read`);
+            }
+            else if (!isReviewerAgent(agent.name)) {
+                rules.add(`deny:agent:${agent.name}`);
+            }
+            if (hasWrite) {
+                rules.add(`allow:agent:${agent.name}:write`);
+            }
+        }
+        if (rules.size > 0) {
+            merged.set(dirPath, rules);
+        }
+    }
+    return Object.fromEntries([...merged.entries()].map(([dirPath, rules]) => [dirPath, [...rules].sort()]));
+}
+export async function seedWorkflowAcls({ relayfileUrl, adminToken, workspace, agents, }) {
+    const aclRules = buildWorkflowAclRules(agents);
+    if (Object.keys(aclRules).length === 0) {
+        return;
+    }
+    await seedAclRules(relayfileUrl, adminToken, workspace, aclRules);
+}
+/**
+ * Test whether a workspace-relative file path is covered by an exclude entry.
+ *
+ * Exclude entries can be either a single directory/file name (matched against
+ * any path segment) or a nested relative path like `build/output` (matched
+ * against any contiguous run of segments at any depth). Both single-name and
+ * nested matches must align on segment boundaries.
+ */
+function isExcludedRelativePath(relativePath, excludes) {
+    const segments = relativePath.split('/');
+    if (DEFAULT_EXCLUDED_FILES.has(segments[segments.length - 1] ?? '')) {
+        return true;
+    }
+    for (const exclude of excludes) {
+        if (!exclude)
+            continue;
+        if (!exclude.includes('/')) {
+            if (segments.some((seg) => seg === exclude)) {
+                return true;
+            }
+            continue;
+        }
+        const excludeSegments = exclude.split('/').filter(Boolean);
+        if (excludeSegments.length === 0)
+            continue;
+        const limit = segments.length - excludeSegments.length;
+        for (let start = 0; start <= limit; start++) {
+            let matched = true;
+            for (let i = 0; i < excludeSegments.length; i++) {
+                if (segments[start + i] !== excludeSegments[i]) {
+                    matched = false;
+                    break;
+                }
+            }
+            if (matched) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function getGitTrackedFiles(rootDir) {
+    try {
+        const output = execSync('git ls-files -z --cached --others --exclude-standard', {
+            cwd: rootDir,
+            encoding: 'utf-8',
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        const files = output.split('\0').filter(Boolean);
+        return files;
+    }
+    catch {
+        return null;
+    }
+}
+function collectAllFiles(rootDir, excludeDirs) {
+    const files = [];
+    const stack = [''];
+    while (stack.length > 0) {
+        const currentRelative = stack.pop();
+        const absoluteDir = path.join(rootDir, currentRelative);
+        let entries;
+        try {
+            entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (excludeDirs.has(entry.name))
+                continue;
+            if (DEFAULT_EXCLUDED_FILES.has(entry.name))
+                continue;
+            const nextRelative = currentRelative ? `${currentRelative}/${entry.name}` : entry.name;
+            if (excludeDirs.has(nextRelative))
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(nextRelative);
+            }
+            else if (entry.isFile()) {
+                files.push(nextRelative);
+            }
+        }
+    }
+    return files;
+}
+async function createTarBuffer(rootDir, files) {
+    const tarStream = tar.create({ gzip: true, cwd: rootDir, portable: true, follow: true }, files);
+    const chunks = [];
+    for await (const chunk of tarStream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+export async function seedWorkspaceTar(baseUrl, token, workspaceId, projectDir, excludeDirs) {
+    const workspace = normalizeWorkspaceId(workspaceId);
+    const rootDir = path.resolve(projectDir);
+    const excludes = normalizeExcludeDirs([...DEFAULT_EXCLUDED_DIRS, ...excludeDirs]);
+    const gitFiles = getGitTrackedFiles(rootDir);
+    const rawFiles = gitFiles ?? collectAllFiles(rootDir, excludes);
+    const files = gitFiles ? rawFiles.filter((f) => !isExcludedRelativePath(f, excludes)) : rawFiles;
+    if (files.length === 0) {
+        return 0;
+    }
+    const tarball = await createTarBuffer(rootDir, files);
+    // Detach into a plain Uint8Array view so we don't expose the underlying
+    // Node Buffer pool through the request body.
+    const body = new Uint8Array(tarball.buffer, tarball.byteOffset, tarball.byteLength).slice();
+    const url = `${normalizeBaseUrl(baseUrl)}/v1/workspaces/${encodeURIComponent(workspace)}/fs/import`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/gzip',
+            'X-Correlation-Id': `seed-tar-${workspace}-${Date.now()}`,
+        },
+        body,
+    });
+    if (response.status === 404) {
+        // Tar import not supported — fall back to batch upload
+        return seedWorkspace(baseUrl, token, workspaceId, projectDir, excludeDirs);
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`tar import failed for workspace ${workspace}: HTTP ${response.status} ${body}`.trim());
+    }
+    const raw = await response.text();
+    if (!raw.trim()) {
+        return files.length;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.imported === 'number' ? parsed.imported : files.length;
+    }
+    catch {
+        return files.length;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.7.38",
+  "version": "0.8.0",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,14 @@
       "types": "./dist/mount-harness.d.ts",
       "default": "./dist/mount-harness.js"
     },
+    "./workspace-seeder": {
+      "types": "./dist/workspace-seeder.d.ts",
+      "default": "./dist/workspace-seeder.js"
+    },
+    "./workspace-mount": {
+      "types": "./dist/workspace-mount.d.ts",
+      "default": "./dist/workspace-mount.js"
+    },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
@@ -47,8 +55,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.7.38"
+    "@relayfile/core": "0.8.0",
+    "ignore": "^7.0.5",
+    "tar": "^7.5.10"
   },
+  "peerDependencies": {},
   "devDependencies": {
     "typescript": "^5.7.3",
     "vitest": "^3.0.0"