@agent-relay/factory 0.0.0 → 0.1.1

package/dist/linear/state-resolver.js

@@ -0,0 +1,221 @@
+import { FACTORY_STATE_ROLES } from '../config/schema';
+// Roles the factory cannot operate without; humanReview is optional (the
+// terminalState falls back to `done` when it is unset).
+const REQUIRED_ROLES = [
+    'readyForAgent',
+    'agentImplementing',
+    'inPlanning',
+    'done',
+];
+const STATES_INDEX_PATH = '/linear/states/_index.json';
+const stateCanonicalPath = (id) => `/linear/states/${id}.json`;
+// Cap concurrent canonical-record reads so a large states catalog can't flood a
+// remote/cloud mount (rate limits, timeouts, fd exhaustion).
+const CATALOG_READ_CONCURRENCY = 10;
+// Build a resolution from explicit, already-known UUIDs (no mount reads). Used
+// as the back-compat / test path when names aren't configured: the global ids
+// apply to every team. Lenient — unresolved roles only throw when used.
+export function stateResolutionFromIds(stateIds) {
+    const roleById = new Map();
+    for (const role of FACTORY_STATE_ROLES) {
+        const id = stateIds[role];
+        if (id)
+            roleById.set(id, role);
+    }
+    return {
+        idFor(_teamToken, role) {
+            const id = stateIds[role];
+            if (!id)
+                throw new Error(`No resolved Linear state for role "${role}".`);
+            return id;
+        },
+        optionalIdFor(_teamToken, role) {
+            return stateIds[role];
+        },
+        roleOf(stateId) {
+            return stateId ? roleById.get(stateId) : undefined;
+        },
+        isRole(stateId, role) {
+            return Boolean(stateId) && roleById.get(stateId) === role;
+        },
+        hasHumanReview() {
+            return Boolean(stateIds.humanReview);
+        },
+    };
+}
+const norm = (value) => (value ?? '').trim().toLowerCase();
+const asArray = (value) => {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object') {
+        const record = value;
+        for (const key of ['entries', 'rows', 'items', 'payload']) {
+            if (Array.isArray(record[key]))
+                return record[key];
+        }
+    }
+    return [];
+};
+const unwrap = (value) => {
+    if (!value || typeof value !== 'object')
+        return {};
+    const record = value;
+    return record.payload && typeof record.payload === 'object'
+        ? record.payload
+        : record;
+};
+const str = (value) => (typeof value === 'string' && value ? value : undefined);
+// Lazily load and cache the /linear/states catalog. Only invoked when at least
+// one role is configured by name, so explicit-UUID setups never read it.
+class StateCatalog {
+    reader;
+    #records;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    async records() {
+        if (this.#records)
+            return this.#records;
+        let index;
+        try {
+            index = (await this.reader.readFile(STATES_INDEX_PATH)).content;
+        }
+        catch (error) {
+            throw new Error(`Cannot resolve Linear state names: ${STATES_INDEX_PATH} is unavailable ` +
+                `(${error instanceof Error ? error.message : String(error)}). ` +
+                `Deploy the workflow-states resource or pin stateIds (UUIDs) in config.`);
+        }
+        const ids = asArray(index)
+            .map((row) => str(row?.id))
+            .filter((id) => Boolean(id));
+        // Read canonical records in bounded batches — a workspace can have many
+        // states, and an unbounded Promise.all would flood a remote/cloud mount.
+        const records = [];
+        for (let i = 0; i < ids.length; i += CATALOG_READ_CONCURRENCY) {
+            const batch = await Promise.all(ids.slice(i, i + CATALOG_READ_CONCURRENCY).map(async (id) => {
+                try {
+                    const rec = unwrap((await this.reader.readFile(stateCanonicalPath(id))).content);
+                    return { id, name: str(rec.name), teamKey: str(rec.team_key), teamName: str(rec.team_name) };
+                }
+                catch {
+                    return { id };
+                }
+            }));
+            records.push(...batch);
+        }
+        this.#records = records;
+        return records;
+    }
+    // Resolve a state NAME to a UUID, optionally scoped to a team token (matched
+    // against team_key or team_name). Throws on no match or ambiguity.
+    async resolve(name, teamToken) {
+        const records = await this.records();
+        let matches = records.filter((rec) => norm(rec.name) === norm(name));
+        if (teamToken) {
+            // Restrict to states that belong to this team (or are team-less). Never
+            // fall back to another team's state of the same name — that would silently
+            // mis-route issues across teams. If nothing remains, it's a hard no-match.
+            const teamless = (rec) => !rec.teamKey && !rec.teamName;
+            const inTeam = (rec) => norm(rec.teamKey) === norm(teamToken) || norm(rec.teamName) === norm(teamToken);
+            matches = matches.filter((rec) => inTeam(rec) || teamless(rec));
+            const scoped = matches.filter(inTeam);
+            if (scoped.length > 0)
+                matches = scoped;
+        }
+        if (matches.length === 0) {
+            throw new Error(`No Linear workflow state named "${name}"${teamToken ? ` for team "${teamToken}"` : ''}.`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`Linear workflow state "${name}" is ambiguous (${matches.length} matches)` +
+                `${teamToken ? ` for team "${teamToken}"` : ''}; scope it with linear.statesByTeam.`);
+        }
+        return matches[0].id;
+    }
+}
+// Resolve every configured role for every known team to concrete UUIDs, building
+// the forward (team,role)->id map and the reverse id->role map. Throws if a
+// required role cannot be resolved for any team.
+export async function resolveFactoryStates(reader, input) {
+    const catalog = new StateCatalog(reader);
+    const globalNames = input.states ?? {};
+    const explicitIds = input.stateIds ?? {};
+    // Normalize statesByTeam keys up front so per-team lookups are case-insensitive
+    // and consistent with how byTeam/teamTokens are keyed (avoids a lowercase
+    // team token silently missing an uppercase override, then overwriting it).
+    const byTeamNames = {};
+    for (const [team, names] of Object.entries(input.statesByTeam ?? {})) {
+        byTeamNames[norm(team)] = names;
+    }
+    // Resolve one role for one team token, applying precedence:
+    // per-team name > global name > explicit UUID.
+    const resolveRole = async (teamToken, role) => {
+        const perTeamName = teamToken ? byTeamNames[norm(teamToken)]?.[role] : undefined;
+        const name = perTeamName ?? globalNames[role];
+        if (name)
+            return catalog.resolve(name, teamToken);
+        return explicitIds[role];
+    };
+    // Dedupe team tokens by normalized form while keeping the first original
+    // casing for resolution + error messages.
+    const teamTokenByNorm = new Map();
+    for (const team of [...Object.keys(input.statesByTeam ?? {}), ...(input.teams ?? [])]) {
+        const key = norm(team);
+        if (key && !teamTokenByNorm.has(key))
+            teamTokenByNorm.set(key, team);
+    }
+    const byTeam = new Map();
+    const resolveAllRoles = async (teamToken, enforce) => {
+        const resolved = {};
+        for (const role of FACTORY_STATE_ROLES) {
+            const id = await resolveRole(teamToken, role);
+            if (id)
+                resolved[role] = id;
+        }
+        const missing = REQUIRED_ROLES.filter((role) => !resolved[role]);
+        if (enforce && missing.length > 0) {
+            throw new Error(`Linear state resolution incomplete${teamToken ? ` for team "${teamToken}"` : ''}: ` +
+                `missing [${missing.join(', ')}]. Set linear.states / linear.statesByTeam (by name) or stateIds (UUIDs).`);
+        }
+        return resolved;
+    };
+    // The team-less default only needs to satisfy required roles when there's
+    // global config meant to fill it; a per-team-only setup leaves it best-effort
+    // (each subscribed team is enforced below, and idFor() throws at use if an
+    // unconfigured team's issue ever appears).
+    const hasGlobalConfig = Object.keys(globalNames).length > 0 || Object.keys(explicitIds).length > 0;
+    const defaultIds = await resolveAllRoles(undefined, hasGlobalConfig);
+    for (const [key, team] of teamTokenByNorm) {
+        byTeam.set(key, await resolveAllRoles(team, true));
+    }
+    const idsFor = (teamToken) => (teamToken ? byTeam.get(norm(teamToken)) : undefined) ?? defaultIds;
+    // Reverse map across the default + every team mapping.
+    const roleById = new Map();
+    for (const ids of [defaultIds, ...byTeam.values()]) {
+        for (const role of FACTORY_STATE_ROLES) {
+            const id = ids[role];
+            if (id)
+                roleById.set(id, role);
+        }
+    }
+    return {
+        idFor(teamToken, role) {
+            const id = idsFor(teamToken)[role];
+            if (!id)
+                throw new Error(`No resolved Linear state for role "${role}"${teamToken ? ` (team "${teamToken}")` : ''}.`);
+            return id;
+        },
+        optionalIdFor(teamToken, role) {
+            return idsFor(teamToken)[role];
+        },
+        roleOf(stateId) {
+            return stateId ? roleById.get(stateId) : undefined;
+        },
+        isRole(stateId, role) {
+            return Boolean(stateId) && roleById.get(stateId) === role;
+        },
+        hasHumanReview(teamToken) {
+            return Boolean(idsFor(teamToken).humanReview);
+        },
+    };
+}
+//# sourceMappingURL=state-resolver.js.map

package/dist/linear/state-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-resolver.js","sourceRoot":"","sources":["../../src/linear/state-resolver.ts"],"names":[],"mappings":"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"}

package/dist/mount/local-mount-preflight.d.ts

@@ -0,0 +1,8 @@
+interface EnsureLocalMountOptions {
+    stateWaitTimeoutMs?: number;
+    stateWaitPollMs?: number;
+    acceptableWorkspaceIds?: readonly string[];
+}
+export declare function ensureLocalMount(workspaceId: string, startDir: string, options?: EnsureLocalMountOptions): Promise<void>;
+export {};
+//# sourceMappingURL=local-mount-preflight.d.ts.map

package/dist/mount/local-mount-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-mount-preflight.d.ts","sourceRoot":"","sources":["../../src/mount/local-mount-preflight.ts"],"names":[],"mappings":"AAQA,UAAU,uBAAuB;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAA;IAIxB,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/mount/local-mount-preflight.js

@@ -0,0 +1,97 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { checkMountStaleness, resolveRelayfileMountBinary } from './relayfile-binary';
+const STATE_FILE = '.integrations/.relay/state.json';
+export async function ensureLocalMount(workspaceId, startDir, options = {}) {
+    const stateFilePath = join(startDir, STATE_FILE);
+    if (!(await isMountStatePresent(stateFilePath))) {
+        await spawnMount(workspaceId, startDir);
+        await waitForStateFile(stateFilePath, workspaceId, options.stateWaitTimeoutMs, options.stateWaitPollMs, options.acceptableWorkspaceIds);
+        return;
+    }
+    const staleness = checkMountStaleness(stateFilePath, workspaceId, options.acceptableWorkspaceIds);
+    if (staleness.stale) {
+        const suffix = staleness.reason !== undefined ? ` (${staleness.reason})` : '';
+        process.stderr.write(`[factory] local mount is stale${suffix}; writeback may not propagate. Run: relayfile stop && relayfile start ${workspaceId} .integrations --background\n`);
+    }
+}
+async function isMountStatePresent(stateFilePath) {
+    try {
+        const raw = await readFile(stateFilePath, 'utf8');
+        JSON.parse(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function spawnMount(workspaceId, startDir) {
+    const binaryPath = resolveRelayfileMountBinary();
+    return new Promise((resolve, reject) => {
+        const child = spawn(binaryPath, ['start', workspaceId, '.integrations', '--background', '--rehome'], {
+            cwd: startDir,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        const stderrChunks = [];
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        }
+        child.on('close', (code) => {
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            if (isAuthError(stderr)) {
+                reject(new Error(`[factory] relayfile mount not authorized — run: relayfile workspace join ${workspaceId} --write`));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`[factory] relayfile mount start failed (exit ${code ?? 'null'}): ${stderr.trim()}`));
+                return;
+            }
+            resolve();
+        });
+        child.on('error', (err) => {
+            reject(new Error(`[factory] relayfile mount start error: ${err.message}`));
+        });
+    });
+}
+async function waitForStateFile(stateFilePath, workspaceId, timeoutMs = 10_000, pollMs = 200, acceptableWorkspaceIds = []) {
+    const deadline = Date.now() + timeoutMs;
+    let lastInvalidReason = 'state file was not created';
+    while (Date.now() < deadline) {
+        try {
+            const raw = await readFile(stateFilePath, 'utf8');
+            const state = JSON.parse(raw);
+            if (isValidMountState(state, workspaceId, acceptableWorkspaceIds))
+                return;
+            lastInvalidReason = `state file is malformed or for another workspace: ${stateFilePath}`;
+        }
+        catch (error) {
+            if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+                lastInvalidReason = 'state file was not created';
+            }
+            else {
+                lastInvalidReason = error instanceof Error ? error.message : String(error);
+            }
+            // not yet present
+        }
+        await sleep(pollMs);
+    }
+    throw new Error(`[factory] relayfile mount did not become ready within ${timeoutMs}ms (${lastInvalidReason})`);
+}
+function isValidMountState(value, workspaceId, acceptableWorkspaceIds = []) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const state = value;
+    const accepted = new Set([workspaceId, ...acceptableWorkspaceIds]);
+    return typeof state.workspaceId === 'string' && accepted.has(state.workspaceId) &&
+        typeof state.lastReconcileAt === 'string' &&
+        Number.isFinite(Date.parse(state.lastReconcileAt)) &&
+        typeof state.pid === 'number' &&
+        Number.isInteger(state.pid) &&
+        state.pid > 0;
+}
+const isAuthError = (stderr) => stderr.includes('workspace join') ||
+    stderr.includes('unauthorized') ||
+    stderr.includes('no credentials');
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+//# sourceMappingURL=local-mount-preflight.js.map

package/dist/mount/local-mount-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-mount-preflight.js","sourceRoot":"","sources":["../../src/mount/local-mount-preflight.ts"],"names":[],"mappings":"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"}

package/dist/mount/relayfile-binary.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveRelayfileMountBinary(startDir?: string): string;
+export declare function checkMountStaleness(stateFilePath: string, workspaceId: string, acceptableWorkspaceIds?: readonly string[]): {
+    stale: boolean;
+    reason?: string;
+    pid?: number;
+};
+//# sourceMappingURL=relayfile-binary.d.ts.map

package/dist/mount/relayfile-binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayfile-binary.d.ts","sourceRoot":"","sources":["../../src/mount/relayfile-binary.ts"],"names":[],"mappings":"AA0EA,wBAAgB,2BAA2B,CAAC,QAAQ,SAAY,GAAG,MAAM,CAqBxE;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EAKnB,sBAAsB,GAAE,SAAS,MAAM,EAAO,GAC7C;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CA0DnD"}

package/dist/mount/relayfile-binary.js

@@ -0,0 +1,143 @@
+import { accessSync, constants, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const STALE_RECONCILE_MS = 15 * 60 * 1000;
+const NOT_FOUND_ERROR = '[factory] relayfile-mount binary not found. Install dependencies or run: npm run relayfile-mount:install';
+function canExecute(filePath) {
+    if (!filePath)
+        return false;
+    try {
+        accessSync(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function devArchSuffix() {
+    if (process.platform === 'darwin') {
+        return process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-amd64';
+    }
+    if (process.platform === 'linux') {
+        return process.arch === 'arm64' ? 'linux-arm64' : 'linux-amd64';
+    }
+    return `${process.platform}-${process.arch}`;
+}
+function binaryName() {
+    return process.platform === 'win32' ? 'relayfile-mount.exe' : 'relayfile-mount';
+}
+function optionalPackageArchSuffix() {
+    return `${process.platform}-${process.arch}`;
+}
+function findPearRoot(startDir) {
+    let current = resolve(startDir);
+    for (;;) {
+        try {
+            accessSync(join(current, 'factory.config.json'), constants.R_OK);
+            return current;
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return null;
+            current = parent;
+        }
+    }
+}
+function devRelayfileCandidates(pearRoot) {
+    const distRoot = resolve(process.env.RELAYFILE_DIST_DIR ?? join(pearRoot, '..', 'relayfile', 'dist'));
+    const suffix = devArchSuffix();
+    return [
+        join(distRoot, `relayfile-mount-${suffix}`),
+        join(distRoot, suffix, binaryName()),
+    ];
+}
+// @relayfile/sdk carries relayfile-mount through per-platform optional
+// dependencies. Prefer that bundled binary so factory start does not depend on
+// a global relayfile install or a manually populated repo bin/ directory.
+function optionalPackageCandidates(pearRoot) {
+    const suffix = optionalPackageArchSuffix();
+    return [
+        join(pearRoot, 'node_modules', '@relayfile', `mount-${suffix}`, 'bin', binaryName()),
+        join(pearRoot, 'node_modules', '@relayfile', 'sdk', 'node_modules', '@relayfile', `mount-${suffix}`, 'bin', binaryName()),
+    ];
+}
+export function resolveRelayfileMountBinary(startDir = __dirname) {
+    if (process.env.RELAYFILE_MOUNT_BIN) {
+        const explicitBinary = resolve(process.env.RELAYFILE_MOUNT_BIN);
+        if (canExecute(explicitBinary))
+            return explicitBinary;
+        throw new Error(NOT_FOUND_ERROR);
+    }
+    const pearRoot = findPearRoot(startDir);
+    const candidates = pearRoot
+        ? [
+            ...optionalPackageCandidates(pearRoot),
+            join(pearRoot, 'bin', binaryName()),
+            ...devRelayfileCandidates(pearRoot),
+        ]
+        : [];
+    for (const candidate of candidates) {
+        if (canExecute(candidate))
+            return resolve(candidate);
+    }
+    throw new Error(NOT_FOUND_ERROR);
+}
+export function checkMountStaleness(stateFilePath, workspaceId, 
+// Alternate identifiers that name the SAME workspace (e.g. the cloud-side
+// UUID for a `rw_` handle). The local mount records the cloud UUID in its
+// state.json, so without these aliases a handle-vs-UUID comparison would
+// report a false "workspace mismatch".
+acceptableWorkspaceIds = []) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(stateFilePath, 'utf8'));
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            return { stale: false };
+        }
+        return { stale: true, reason: `mount state is unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { stale: true, reason: 'mount state is unreadable: expected object' };
+    }
+    const registeredWorkspaceId = typeof parsed.workspaceId === 'string' ? parsed.workspaceId : undefined;
+    const accepted = new Set([workspaceId, ...acceptableWorkspaceIds]);
+    if (registeredWorkspaceId === undefined || !accepted.has(registeredWorkspaceId)) {
+        return {
+            stale: true,
+            reason: `workspace mismatch: registered=${registeredWorkspaceId ?? 'unknown'} expected=${[...accepted].join('|')}`,
+        };
+    }
+    const pid = typeof parsed.pid === 'number' && Number.isInteger(parsed.pid) && parsed.pid > 0
+        ? parsed.pid
+        : undefined;
+    const lastReconcileAt = typeof parsed.lastReconcileAt === 'string'
+        ? Date.parse(parsed.lastReconcileAt)
+        : NaN;
+    if (!Number.isFinite(lastReconcileAt)) {
+        return { stale: true, reason: 'last reconcile timestamp is missing', pid };
+    }
+    const ageMs = Date.now() - lastReconcileAt;
+    if (ageMs > STALE_RECONCILE_MS) {
+        return {
+            stale: true,
+            reason: `last reconcile ${Math.floor(ageMs / 60000)}m ago`,
+            pid,
+        };
+    }
+    if (pid === undefined) {
+        return { stale: true, reason: 'mount process pid is missing' };
+    }
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EPERM') {
+            return { stale: false, pid };
+        }
+        return { stale: true, reason: `mount process (pid ${pid}) is not running`, pid };
+    }
+    return { stale: false, pid };
+}
+//# sourceMappingURL=relayfile-binary.js.map

package/dist/mount/relayfile-binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayfile-binary.js","sourceRoot":"","sources":["../../src/mount/relayfile-binary.ts"],"names":[],"mappings":"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"}

package/dist/mount/relayfile-cloud-mount-client.d.ts

@@ -0,0 +1,123 @@
+import { type ActiveWorkspaceDescriptor, type CloudSession, type CloudSessionOptions } from '@agent-relay/cloud';
+import { type ChangeEvent, type DeleteFileInput, type EventFeedResponse, type FileReadResponse, type GetEventsOptions, type ListTreeOptions, type ResourceAtEventResult, type OperationStatusResponse, type Subscription, type TreeResponse, type WriteFileInput, type WriteQueuedResponse } from '@relayfile/sdk';
+import type { EventPage, MountClient, ProviderSyncStatus, SubscribeOptions } from '../ports';
+import { type RelayfileEventClient, type TokenProvider } from '../subscriptions';
+export declare const FACTORY_RELAYFILE_SCOPES: readonly ["relayfile:fs:read:/linear/issues/**", "relayfile:fs:write:/linear/issues/**", "relayfile:fs:read:/github/repos/**", "relayfile:fs:read:/slack/channels/**", "relayfile:fs:write:/slack/channels/**", "relayfile:fs:read:/slack/users/**"];
+export type CloudSessionProvider = (options?: CloudSessionOptions) => Promise<CloudSession>;
+export type ActiveWorkspaceResolver = (options?: {
+    interactive?: boolean;
+}) => Promise<ActiveWorkspaceDescriptor>;
+export interface ResolvedFactoryWorkspace {
+    /** Relayfile workspace handle (e.g. `rw_7ccfea89`) — what the mount/config use. */
+    workspaceId: string;
+    /**
+     * Cloud-side UUID for the same workspace (e.g. `50587328-…`). The local
+     * relayfile mount records this form in its state.json, so it is passed to the
+     * staleness check as an accepted alias to avoid a spurious "workspace
+     * mismatch" warning when handle and UUID refer to the same workspace.
+     */
+    cloudWorkspaceId?: string;
+}
+/**
+ * Derive the factory's workspace from the active cloud session rather than a
+ * hardcoded config value. `resolveActiveWorkspace()` resolves the locally
+ * pinned workspace against the cloud API and returns both identifier forms.
+ * Falls back to the built-in default when resolution fails (offline / no
+ * session), so callers always get a usable handle.
+ */
+export declare function resolveFactoryWorkspace(resolver?: ActiveWorkspaceResolver): Promise<ResolvedFactoryWorkspace>;
+export interface RelayfileWorkspaceHandleLike {
+    info: {
+        relayfileUrl: string;
+    };
+    client(): RelayFileClientLike;
+    getToken(): Promise<string> | string;
+}
+export type RelayfileSetupFactory = (options: {
+    cloudApiUrl: string;
+    tokenProvider: () => Promise<string>;
+}) => {
+    joinWorkspace(workspaceId: string, options?: {
+        agentName?: string;
+        scopes?: string[];
+    }): Promise<RelayfileWorkspaceHandleLike>;
+};
+export interface RelayfileCloudMountClientConfig {
+    backend?: 'relayfile-cloud';
+    workspaceId?: string;
+    cloudApiUrl?: string;
+    cloudSessionProvider?: CloudSessionProvider;
+    cloudSessionRefreshTimeoutMs?: number;
+    cloudSessionEnv?: NodeJS.ProcessEnv;
+    relayfileSetupFactory?: RelayfileSetupFactory;
+    agentName?: string;
+    scopes?: string[];
+    client?: RelayFileClientLike;
+    tokenProvider?: TokenProvider;
+    baseUrl?: string;
+    eventClient?: RelayfileEventClient;
+    isAllowedDraft?: (path: string, content: unknown, opts?: {
+        guarded?: boolean;
+    }) => boolean | Promise<boolean>;
+    isAllowedDelete?: (path: string, currentContent: unknown) => boolean | Promise<boolean>;
+}
+export type RelayFileClientLike = {
+    readFile(workspaceId: string, path: string): Promise<FileReadResponse>;
+    writeFile(input: WriteFileInput): Promise<WriteQueuedResponse>;
+    deleteFile(input: DeleteFileInput): Promise<WriteQueuedResponse>;
+    listTree(workspaceId: string, options?: ListTreeOptions): Promise<TreeResponse>;
+    getEvents(workspaceId: string, options?: GetEventsOptions): Promise<EventFeedResponse>;
+    listLastNChanges?(limit: number, context?: {
+        workspaceId: string;
+        token?: string;
+    }): Promise<{
+        events: ChangeEvent[];
+    }>;
+    getResourceAtEvent(eventId: string, context?: {
+        workspaceId: string;
+        token?: string;
+    }): Promise<ResourceAtEventResult>;
+    getOp?(workspaceId: string, opId: string): Promise<OperationStatusResponse>;
+    getSyncStatus?(workspaceId: string, options?: {
+        provider?: string;
+    }): Promise<unknown>;
+    getToken?(): Promise<string> | string;
+    getBaseUrl?(): string;
+};
+export declare class RelayfileCloudMountClient implements MountClient {
+    #private;
+    readonly workspaceId: string;
+    readonly writebackTransport = "relayfile-cloud";
+    constructor(config?: RelayfileCloudMountClientConfig);
+    setDefaultAllowedDraftPredicate(predicate: (path: string, content: unknown, opts?: {
+        guarded?: boolean;
+    }) => boolean | Promise<boolean>): void;
+    static fromConfig(config?: RelayfileCloudMountClientConfig): Promise<RelayfileCloudMountClient>;
+    readFile(path: string): Promise<{
+        content: unknown;
+        revision?: string;
+    }>;
+    writeFile(path: string, content: unknown, opts?: {
+        guarded?: boolean;
+    }): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    listTree(prefix: string): Promise<string[]>;
+    subscribe(globs: string[], onChange: (event: ChangeEvent) => void, opts?: SubscribeOptions): Subscription;
+    getEvents(opts: {
+        cursor?: string;
+        limit?: number;
+        provider?: string;
+        last?: number;
+    }): Promise<EventPage>;
+    getEventHighWatermark(opts?: {
+        provider?: string;
+    }): Promise<string | undefined>;
+    getSyncStatus(provider: string): Promise<ProviderSyncStatus | undefined>;
+    confirmWrite(path: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<'acked' | 'pending' | 'failed' | 'timeout'>;
+    ensureSubRoot(prefix: string, _opts?: {
+        timeoutMs?: number;
+    }): Promise<'ready' | 'absent'>;
+}
+//# sourceMappingURL=relayfile-cloud-mount-client.d.ts.map