agent-relay 4.0.32 → 4.0.33

package/node_modules/@relayfile/local-mount/dist/auto-sync.js

@@ -0,0 +1,466 @@
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
+import path from 'node:path';
+import chokidar from 'chokidar';
+export function startAutoSync(ctx, opts = {}) {
+    const scanIntervalMs = opts.scanIntervalMs ?? 10_000;
+    const writeFinishMs = opts.writeFinishMs ?? 200;
+    const onError = opts.onError ?? (() => { });
+    const state = new Map();
+    primeState(state, ctx);
+    let syncing = false;
+    let pending = false;
+    let totalChanges = 0;
+    const runReconcile = async () => {
+        if (syncing) {
+            pending = true;
+            return 0;
+        }
+        syncing = true;
+        let count = 0;
+        try {
+            count = reconcile(state, ctx, onError);
+        }
+        catch (err) {
+            onError(err);
+        }
+        finally {
+            syncing = false;
+        }
+        if (pending) {
+            pending = false;
+            try {
+                count += reconcile(state, ctx, onError);
+            }
+            catch (err) {
+                onError(err);
+            }
+        }
+        totalChanges += count;
+        return count;
+    };
+    const syncPathFromRoot = (root, absPath) => {
+        const rel = path.relative(root, absPath);
+        if (rel === '' || rel.startsWith('..'))
+            return;
+        const relPosix = rel.split(path.sep).join('/');
+        if (!isSyncCandidate(relPosix, ctx))
+            return;
+        try {
+            const changed = syncOneFile(relPosix, state, ctx);
+            if (changed)
+                totalChanges += 1;
+        }
+        catch (err) {
+            onError(err);
+        }
+    };
+    const makeWatcher = (root) => {
+        const watcher = chokidar.watch(root, {
+            ignoreInitial: true,
+            persistent: true,
+            followSymlinks: false,
+            awaitWriteFinish: {
+                stabilityThreshold: writeFinishMs,
+                pollInterval: 50,
+            },
+            ignored: (candidate, stats) => shouldChokidarIgnore(candidate, root, ctx, stats),
+        });
+        const onEvent = (p) => syncPathFromRoot(root, p);
+        watcher.on('add', onEvent);
+        watcher.on('change', onEvent);
+        watcher.on('unlink', onEvent);
+        watcher.on('error', (err) => onError(err));
+        const ready = new Promise((resolve) => {
+            watcher.once('ready', () => resolve());
+        });
+        return { watcher, ready };
+    };
+    const mount = makeWatcher(ctx.realMountDir);
+    const project = makeWatcher(ctx.realProjectDir);
+    const mountWatcher = mount.watcher;
+    const projectWatcher = project.watcher;
+    const watchersReady = Promise.all([mount.ready, project.ready]);
+    const interval = setInterval(() => {
+        void runReconcile();
+    }, scanIntervalMs);
+    // Do not keep the event loop alive just because of our scan timer.
+    interval.unref?.();
+    return {
+        async stop() {
+            clearInterval(interval);
+            await Promise.all([mountWatcher.close(), projectWatcher.close()]);
+            // Drain any pending work so callers can rely on "stopped means quiesced".
+            await runReconcile();
+        },
+        reconcile: runReconcile,
+        totalChanges: () => totalChanges,
+        ready: async () => {
+            await watchersReady;
+        },
+    };
+}
+function primeState(state, ctx) {
+    // Record current mtimes for every file that exists in both trees with the
+    // same content. Files that differ are left out so the first reconcile sees
+    // no prev entry and picks a winner via the content-based resolution path.
+    walk(ctx.realMountDir, ctx, (abs) => {
+        const rel = toRelPosix(abs, ctx);
+        if (rel === null)
+            return;
+        if (!isSyncCandidate(rel, ctx))
+            return;
+        const mountStat = safeFileStat(abs);
+        if (!mountStat)
+            return;
+        const projectAbs = path.join(ctx.realProjectDir, rel);
+        const projectStat = safeFileStat(projectAbs);
+        if (!projectStat)
+            return;
+        if (!sameContent(abs, projectAbs))
+            return;
+        state.set(rel, {
+            mountMtimeMs: mountStat.mtimeMs,
+            projectMtimeMs: projectStat.mtimeMs,
+        });
+    });
+}
+function reconcile(state, ctx, onError) {
+    const seen = new Set();
+    let count = 0;
+    const visit = (relPosix) => {
+        if (seen.has(relPosix))
+            return;
+        seen.add(relPosix);
+        if (!isSyncCandidate(relPosix, ctx))
+            return;
+        try {
+            const changed = syncOneFile(relPosix, state, ctx);
+            if (changed)
+                count += 1;
+        }
+        catch (err) {
+            onError(err);
+        }
+    };
+    walk(ctx.realMountDir, ctx, (abs) => {
+        const rel = toRelPosix(abs, ctx);
+        if (rel !== null)
+            visit(rel);
+    });
+    walk(ctx.realProjectDir, ctx, (abs) => {
+        const rel = toRelPosixFromProject(abs, ctx);
+        if (rel !== null)
+            visit(rel);
+    });
+    // Tombstone sweep: any path in state we didn't visit had both sides absent,
+    // so it's fully gone.
+    for (const rel of Array.from(state.keys())) {
+        if (!seen.has(rel)) {
+            const mountAbs = path.join(ctx.realMountDir, rel);
+            const projectAbs = path.join(ctx.realProjectDir, rel);
+            if (!existsSync(mountAbs) && !existsSync(projectAbs)) {
+                state.delete(rel);
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Sync a single relPath and return true if a copy or delete actually happened.
+ *
+ * Resolution rules ("mount wins"):
+ * - If both sides changed since last sync → mount→project.
+ * - Only mount changed → mount→project (unless mount-side change is disallowed
+ *   for readonly files; then drop the mount change).
+ * - Only project changed → project→mount.
+ * - One side missing:
+ *   • Other side changed since last sync → recreate the missing side.
+ *   • Otherwise → propagate the delete.
+ */
+function syncOneFile(relPosix, state, ctx) {
+    const mountAbs = path.join(ctx.realMountDir, relPosix);
+    const projectAbs = path.join(ctx.realProjectDir, relPosix);
+    const mountStat = safeFileStat(mountAbs);
+    const projectStat = safeFileStat(projectAbs);
+    const prev = state.get(relPosix);
+    const readonly = ctx.isReadonly(relPosix);
+    if (!mountStat && !projectStat) {
+        state.delete(relPosix);
+        return false;
+    }
+    if (!prev) {
+        // First time we've seen this path.
+        if (mountStat && projectStat) {
+            if (sameContent(mountAbs, projectAbs)) {
+                state.set(relPosix, {
+                    mountMtimeMs: mountStat.mtimeMs,
+                    projectMtimeMs: projectStat.mtimeMs,
+                });
+                return false;
+            }
+            // Differ with no history: arbitrary tiebreak → mount wins.
+            if (readonly) {
+                // Readonly can't accept mount-side writes; fall back to project→mount.
+                return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+            }
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        if (mountStat && !projectStat) {
+            if (readonly) {
+                // New file in mount with a readonly pattern → cannot sync back.
+                return false;
+            }
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        if (!mountStat && projectStat) {
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+    }
+    // Use strict inequality rather than `>`: on filesystems with coarse mtime
+    // resolution, or after a backdated touch, a real content change can land
+    // with a non-greater mtime.
+    const mountChanged = mountStat
+        ? prev?.mountMtimeMs === undefined || mountStat.mtimeMs !== prev.mountMtimeMs
+        : false;
+    const projectChanged = projectStat
+        ? prev?.projectMtimeMs === undefined || projectStat.mtimeMs !== prev.projectMtimeMs
+        : false;
+    if (mountStat && projectStat) {
+        if (!mountChanged && !projectChanged)
+            return false;
+        if (mountChanged && !readonly) {
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        if (projectChanged) {
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+        return false;
+    }
+    if (mountStat && !projectStat) {
+        if (mountChanged && !readonly) {
+            return doMountToProject(relPosix, state, ctx, mountAbs, projectAbs);
+        }
+        // Project deleted externally and mount hasn't been touched since → mirror.
+        return doDeleteMount(relPosix, state, mountAbs);
+    }
+    if (!mountStat && projectStat) {
+        if (projectChanged) {
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+        // Mount deleted and project hasn't been touched since → mirror to project.
+        if (readonly) {
+            // Readonly deletes in mount don't sync back; recreate mount from project.
+            return doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly);
+        }
+        return doDeleteProject(relPosix, state, projectAbs);
+    }
+    return false;
+}
+function doMountToProject(relPosix, state, ctx, mountAbs, projectAbs) {
+    const target = resolveSafeWriteTarget(ctx.realProjectDir, projectAbs);
+    if (!target)
+        return false;
+    if (isSymlinkTarget(target))
+        return false;
+    if (existsSync(target) && sameContent(mountAbs, target)) {
+        updateState(state, relPosix, mountAbs, target);
+        return false;
+    }
+    copyFileSync(mountAbs, target);
+    updateState(state, relPosix, mountAbs, target);
+    return true;
+}
+function doProjectToMount(relPosix, state, ctx, projectAbs, mountAbs, readonly) {
+    const target = resolveSafeWriteTarget(ctx.realMountDir, mountAbs);
+    if (!target)
+        return false;
+    if (isSymlinkTarget(target))
+        return false;
+    if (existsSync(target) && sameContent(projectAbs, target)) {
+        updateState(state, relPosix, target, projectAbs);
+        return false;
+    }
+    // The mount copy of a readonly file has mode 0o444, which blocks
+    // copyFileSync from overwriting it. Temporarily restore write permission.
+    if (existsSync(target)) {
+        try {
+            chmodSync(target, 0o644);
+        }
+        catch { /* best effort */ }
+    }
+    copyFileSync(projectAbs, target);
+    if (readonly) {
+        try {
+            chmodSync(target, 0o444);
+        }
+        catch { /* best effort */ }
+    }
+    else {
+        const mode = safeFileStat(projectAbs)?.mode;
+        if (mode !== undefined) {
+            try {
+                chmodSync(target, mode & 0o777);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    updateState(state, relPosix, target, projectAbs);
+    return true;
+}
+function doDeleteMount(relPosix, state, mountAbs) {
+    try {
+        rmSync(mountAbs, { force: true });
+    }
+    catch {
+        return false;
+    }
+    state.delete(relPosix);
+    return true;
+}
+function doDeleteProject(relPosix, state, projectAbs) {
+    try {
+        rmSync(projectAbs, { force: true });
+    }
+    catch {
+        return false;
+    }
+    state.delete(relPosix);
+    return true;
+}
+function updateState(state, relPosix, mountAbs, projectAbs) {
+    const mountStat = safeFileStat(mountAbs);
+    const projectStat = safeFileStat(projectAbs);
+    state.set(relPosix, {
+        mountMtimeMs: mountStat?.mtimeMs,
+        projectMtimeMs: projectStat?.mtimeMs,
+    });
+}
+function isSyncCandidate(relPosix, ctx) {
+    if (!relPosix || relPosix.startsWith('..'))
+        return false;
+    if (ctx.isReservedFile(relPosix))
+        return false;
+    if (ctx.isExcluded(relPosix))
+        return false;
+    if (ctx.isIgnored(relPosix))
+        return false;
+    return true;
+}
+function toRelPosix(absPath, ctx) {
+    const rel = path.relative(ctx.realMountDir, absPath);
+    if (rel === '' || rel.startsWith('..'))
+        return null;
+    return rel.split(path.sep).join('/');
+}
+function toRelPosixFromProject(absPath, ctx) {
+    const rel = path.relative(ctx.realProjectDir, absPath);
+    if (rel === '' || rel.startsWith('..'))
+        return null;
+    return rel.split(path.sep).join('/');
+}
+function safeFileStat(p) {
+    try {
+        const s = lstatSync(p);
+        if (s.isSymbolicLink())
+            return null;
+        if (!s.isFile())
+            return null;
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+function isSymlinkTarget(target) {
+    // If the target already exists as a symlink, writing through it would
+    // follow the link and potentially escape the mount/project root. Refuse.
+    try {
+        return lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function sameContent(left, right) {
+    try {
+        const a = statSync(left);
+        const b = statSync(right);
+        if (a.size !== b.size)
+            return false;
+        return readFileSync(left).equals(readFileSync(right));
+    }
+    catch {
+        return false;
+    }
+}
+function resolveSafeWriteTarget(root, candidate) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedCandidate = path.resolve(candidate);
+    if (resolvedCandidate !== resolvedRoot &&
+        !resolvedCandidate.startsWith(`${resolvedRoot}${path.sep}`)) {
+        return null;
+    }
+    const parent = path.dirname(resolvedCandidate);
+    try {
+        mkdirSync(parent, { recursive: true });
+        const realParent = realpathSync(parent);
+        if (realParent !== resolvedRoot &&
+            !realParent.startsWith(`${resolvedRoot}${path.sep}`)) {
+            return null;
+        }
+        return path.join(realParent, path.basename(resolvedCandidate));
+    }
+    catch {
+        return null;
+    }
+}
+function walk(root, ctx, visit) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (!cur)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = path.join(cur, entry.name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel || rel.startsWith('..'))
+                continue;
+            if (ctx.isExcluded(rel) || ctx.isIgnored(rel, entry.isDirectory()))
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(abs);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                visit(abs);
+            }
+        }
+    }
+}
+function shouldChokidarIgnore(candidate, root, ctx, stats) {
+    if (candidate === root)
+        return false;
+    const rel = path.relative(root, candidate);
+    if (rel === '' || rel.startsWith('..'))
+        return false;
+    const relPosix = rel.split(path.sep).join('/');
+    if (ctx.isExcluded(relPosix))
+        return true;
+    if (ctx.isReservedFile(relPosix))
+        return true;
+    // chokidar calls this filter twice: first without stats (pre-stat prune),
+    // then again with stats once it knows the entry type. Only apply the
+    // directory-form match when we have stats confirming it's a directory,
+    // otherwise a directory-only pattern like `cache/` would wrongly prune a
+    // same-named file.
+    if (stats) {
+        return ctx.isIgnored(relPosix, stats.isDirectory());
+    }
+    return ctx.isIgnored(relPosix);
+}

package/node_modules/@relayfile/local-mount/dist/dotfiles.d.ts

@@ -0,0 +1,18 @@
+export interface ReadAgentDotfilesOptions {
+    /**
+     * If provided, also reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly`
+     * from the project directory and merges the resulting patterns.
+     */
+    agentName?: string;
+}
+export interface AgentDotfilePatterns {
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+}
+/**
+ * Read `.agentignore` and `.agentreadonly` dotfiles from a project directory
+ * and return the compiled pattern lists. If `agentName` is supplied, also
+ * reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly` and
+ * appends their patterns.
+ */
+export declare function readAgentDotfiles(projectDir: string, options?: ReadAgentDotfilesOptions): AgentDotfilePatterns;

package/node_modules/@relayfile/local-mount/dist/dotfiles.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+function cleanPatterns(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#'));
+}
+function loadPatternsFromFile(filePath) {
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    const content = readFileSync(filePath, 'utf8');
+    return cleanPatterns(content);
+}
+/**
+ * Read `.agentignore` and `.agentreadonly` dotfiles from a project directory
+ * and return the compiled pattern lists. If `agentName` is supplied, also
+ * reads `.{agentName}.agentignore` and `.{agentName}.agentreadonly` and
+ * appends their patterns.
+ */
+export function readAgentDotfiles(projectDir, options = {}) {
+    const resolvedProjectDir = path.resolve(projectDir);
+    const ignoredPatterns = [
+        ...loadPatternsFromFile(path.join(resolvedProjectDir, '.agentignore')),
+    ];
+    const readonlyPatterns = [
+        ...loadPatternsFromFile(path.join(resolvedProjectDir, '.agentreadonly')),
+    ];
+    if (options.agentName) {
+        const safeAgentName = sanitizeAgentName(options.agentName);
+        ignoredPatterns.push(...loadPatternsFromFile(path.join(resolvedProjectDir, `.${safeAgentName}.agentignore`)));
+        readonlyPatterns.push(...loadPatternsFromFile(path.join(resolvedProjectDir, `.${safeAgentName}.agentreadonly`)));
+    }
+    return { ignoredPatterns, readonlyPatterns };
+}
+const AGENT_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+function sanitizeAgentName(agentName) {
+    if (!AGENT_NAME_PATTERN.test(agentName) || path.basename(agentName) !== agentName) {
+        throw new Error(`Invalid agentName ${JSON.stringify(agentName)}: only [A-Za-z0-9_-] are allowed`);
+    }
+    return agentName;
+}

package/node_modules/@relayfile/local-mount/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createSymlinkMount, type SymlinkMountOptions, type SymlinkMountHandle, } from './symlink-mount.js';
+export { type AutoSyncOptions, type AutoSyncHandle, } from './auto-sync.js';
+export { readAgentDotfiles, type ReadAgentDotfilesOptions, type AgentDotfilePatterns, } from './dotfiles.js';
+export { launchOnMount, type LaunchOnMountOptions, type LaunchOnMountResult, } from './launch.js';

package/node_modules/@relayfile/local-mount/dist/index.js

@@ -0,0 +1,3 @@
+export { createSymlinkMount, } from './symlink-mount.js';
+export { readAgentDotfiles, } from './dotfiles.js';
+export { launchOnMount, } from './launch.js';

package/node_modules/@relayfile/local-mount/dist/launch.d.ts

@@ -0,0 +1,50 @@
+import type { AutoSyncOptions } from './auto-sync.js';
+export interface LaunchOnMountOptions {
+    /** Binary name or absolute path to the CLI to spawn, e.g. 'claude'. */
+    cli: string;
+    /** The real project directory to mirror. */
+    projectDir: string;
+    /** Where to create the mount. Must differ from projectDir. */
+    mountDir: string;
+    /** Argv to pass to the CLI after its binary name. */
+    args: string[];
+    /** Glob-style ignore patterns (files excluded entirely from the mount). */
+    ignoredPatterns?: string[];
+    /** Glob-style readonly patterns (files copied with mode 0o444). */
+    readonlyPatterns?: string[];
+    /** Extra directory names to exclude from the mount on top of defaults. */
+    excludeDirs?: string[];
+    /** Extra env vars merged on top of `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Optional agent name, used in the _MOUNT_README.md "Agent:" line. */
+    agentName?: string;
+    /**
+     * Invoked after the mount is created but before the CLI is spawned.
+     * Useful for writing additional files into the mount (overrides, extra docs).
+     */
+    onBeforeLaunch?: (mountDir: string) => void | Promise<void>;
+    /**
+     * Invoked after sync-back completes, before cleanup. Receives the total
+     * number of file changes propagated during the run — the sum of autosync
+     * activity in both directions (including deletes) and the final mount→
+     * project syncBack. Use this as an "anything changed?" signal rather than
+     * a strict mount→project count.
+     */
+    onAfterSync?: (syncedFileCount: number) => void | Promise<void>;
+    /**
+     * Auto-sync behavior. By default, bidirectional auto-sync runs during the
+     * lifetime of the spawned CLI. Pass `false` to disable, or an options object
+     * to tune the scan interval / write-finish debounce.
+     */
+    autoSync?: boolean | AutoSyncOptions;
+}
+export interface LaunchOnMountResult {
+    exitCode: number;
+}
+/**
+ * Create a mount of `projectDir` at `mountDir`, spawn `cli` with `args` using
+ * the mount as its cwd, forward SIGINT/SIGTERM to the child, sync writable
+ * changes back on exit, then clean up the mount. Resolves with the child's
+ * exit code.
+ */
+export declare function launchOnMount(opts: LaunchOnMountOptions): Promise<LaunchOnMountResult>;