@eddacraft/anvil-runtime 0.1.0

package/dist/concurrency/lock-manager.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Lock Manager
+ *
+ * Provides distributed locking for multi-agent coordination using file-based locks.
+ * Supports automatic stale lock detection and recovery.
+ */
+import { type LockRecord, type LockType, type LockAcquisitionResult, type LockReleaseResult, type AgentInfo, type ConcurrencyConfig } from './types.js';
+/**
+ * Options for LockManager
+ */
+export interface LockManagerOptions {
+    /** Workspace root directory */
+    workspaceRoot: string;
+    /** Concurrency configuration */
+    config?: Partial<ConcurrencyConfig>;
+    /** Agent info for this lock manager */
+    agentInfo?: AgentInfo;
+}
+/**
+ * Options for lock acquisition
+ */
+export interface AcquireLockOptions {
+    /** Lock type */
+    type: LockType;
+    /** Resource being locked */
+    resource: string;
+    /** Reason for lock */
+    reason?: string;
+    /** Custom timeout (overrides config) */
+    timeoutMs?: number;
+    /** Wait for lock (block until acquired or timeout) */
+    wait?: boolean;
+    /** Wait timeout in ms (default: 30s) */
+    waitTimeoutMs?: number;
+    /** Retry interval in ms (default: 100ms) */
+    retryIntervalMs?: number;
+    /** Allow acquiring from stale agents */
+    acquireFromStale?: boolean;
+}
+/**
+ * Lock Manager
+ *
+ * Manages distributed file-based locks for multi-agent coordination.
+ */
+export declare class LockManager {
+    private readonly workspaceRoot;
+    private readonly config;
+    private readonly agent;
+    private readonly lockDir;
+    private readonly heldLocks;
+    private readonly renewalTimers;
+    constructor(options: LockManagerOptions);
+    /**
+     * Get the agent ID
+     */
+    getAgentId(): string;
+    /**
+     * Acquire a lock
+     */
+    acquire(options: AcquireLockOptions): Promise<LockAcquisitionResult>;
+    /**
+     * Acquire lock with wait/retry
+     */
+    private acquireWithWait;
+    /**
+     * Release a lock
+     */
+    release(type: LockType, resource: string): Promise<LockReleaseResult>;
+    /**
+     * Release all locks held by this manager
+     */
+    releaseAll(): Promise<void>;
+    /**
+     * Check if a lock is held
+     */
+    isLocked(type: LockType, resource: string): Promise<boolean>;
+    /**
+     * Get lock info
+     */
+    getLockInfo(type: LockType, resource: string): Promise<LockRecord | null>;
+    /**
+     * Check if we hold a lock
+     */
+    holdsLock(type: LockType, resource: string): boolean;
+    /**
+     * Get all locks held by this manager
+     */
+    getHeldLocks(): LockRecord[];
+    /**
+     * Start auto-renewal for a lock
+     */
+    startAutoRenewal(type: LockType, resource: string, intervalMs?: number): void;
+    /**
+     * Stop auto-renewal for a lock
+     */
+    stopRenewal(lockKey: string): void;
+    /**
+     * Stop all auto-renewals
+     */
+    stopAllRenewals(): void;
+    /**
+     * Cleanup expired locks in the lock directory
+     */
+    cleanupExpiredLocks(): Promise<number>;
+    /**
+     * Create a new lock
+     */
+    private createLock;
+    /**
+     * Renew an existing lock
+     */
+    private renewLock;
+    /**
+     * Force acquire a lock (taking over from expired/stale holder)
+     */
+    private forceAcquire;
+    /**
+     * Check if lock holder is stale
+     */
+    private isHolderStale;
+    /**
+     * Read lock file
+     */
+    private readLock;
+    /**
+     * Get lock key from type and resource
+     */
+    private getLockKey;
+    /**
+     * Get lock file path
+     */
+    private getLockPath;
+    /**
+     * Ensure lock directory exists
+     */
+    private ensureLockDir;
+}
+/**
+ * Create a lock manager
+ */
+export declare function createLockManager(options: LockManagerOptions): LockManager;
+/**
+ * Execute a function while holding a lock
+ *
+ * @example
+ * ```typescript
+ * const result = await withLock(
+ *   lockManager,
+ *   { type: 'action', resource: 'gate' },
+ *   async () => {
+ *     // Perform work that requires exclusive access
+ *     return await runGates();
+ *   }
+ * );
+ * ```
+ */
+export declare function withLock<T>(manager: LockManager, options: Omit<AcquireLockOptions, 'wait'>, fn: () => Promise<T>): Promise<T>;
+/**
+ * Try to execute a function while holding a lock (non-blocking)
+ *
+ * Returns null if lock couldn't be acquired.
+ */
+export declare function tryWithLock<T>(manager: LockManager, options: Omit<AcquireLockOptions, 'wait'>, fn: () => Promise<T>): Promise<{
+    success: true;
+    result: T;
+} | {
+    success: false;
+    heldBy?: LockAcquisitionResult['heldBy'];
+}>;
+//# sourceMappingURL=lock-manager.d.ts.map

package/dist/concurrency/lock-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-manager.d.ts","sourceRoot":"","sources":["../../src/concurrency/lock-manager.ts"],"names":[],"mappings":"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"}

package/dist/concurrency/lock-manager.js

@@ -0,0 +1,525 @@
+/**
+ * Lock Manager
+ *
+ * Provides distributed locking for multi-agent coordination using file-based locks.
+ * Supports automatic stale lock detection and recovery.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { LockFileSchema, getDefaultConcurrencyConfig, } from './types.js';
+import { atomicWriteJson, readJsonSafe, unlinkSafe, sleepWithJitter, tryAcquireFileLock, } from './atomic.js';
+import { createAgentInfo } from './agent.js';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('lock');
+/**
+ * Lock Manager
+ *
+ * Manages distributed file-based locks for multi-agent coordination.
+ */
+export class LockManager {
+    workspaceRoot;
+    config;
+    agent;
+    lockDir;
+    // Track locks held by this manager instance
+    heldLocks = new Map();
+    // Renewal timers
+    renewalTimers = new Map();
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.config = {
+            ...getDefaultConcurrencyConfig(),
+            ...options.config,
+        };
+        this.agent = options.agentInfo ?? createAgentInfo();
+        this.lockDir = join(this.workspaceRoot, this.config.lockDir);
+    }
+    /**
+     * Get the agent ID
+     */
+    getAgentId() {
+        return this.agent.id;
+    }
+    /**
+     * Acquire a lock
+     */
+    async acquire(options) {
+        const { type, resource, reason, timeoutMs = this.config.lockTimeoutMs, wait = false, waitTimeoutMs = 30000, retryIntervalMs = 100, acquireFromStale = this.config.autoAcquireFromStale, } = options;
+        const lockKey = this.getLockKey(type, resource);
+        const lockPath = this.getLockPath(lockKey);
+        // If waiting, use retry loop
+        if (wait) {
+            return this.acquireWithWait(options, waitTimeoutMs, retryIntervalMs);
+        }
+        await this.ensureLockDir();
+        // Check for existing lock
+        const existingLock = await this.readLock(lockPath);
+        if (existingLock) {
+            // Check if it's our lock
+            if (existingLock.lock.agentId === this.agent.id) {
+                // Renew our existing lock
+                return this.renewLock(lockPath, existingLock, reason);
+            }
+            // Check if lock is expired
+            const now = Date.now();
+            const expiresAt = new Date(existingLock.lock.expiresAt).getTime();
+            if (now > expiresAt) {
+                debug(`Lock expired, taking over: ${lockKey}`);
+                return this.forceAcquire(lockPath, type, resource, reason, timeoutMs, existingLock);
+            }
+            // Check if holder is stale
+            if (acquireFromStale && (await this.isHolderStale(existingLock.lock))) {
+                debug(`Lock holder is stale, taking over: ${lockKey}`);
+                return this.forceAcquire(lockPath, type, resource, reason, timeoutMs, existingLock);
+            }
+            // Lock is held by another active agent
+            return {
+                acquired: false,
+                error: `Lock held by ${existingLock.lock.agentId}`,
+                heldBy: {
+                    agentId: existingLock.lock.agentId,
+                    agentType: existingLock.lock.agentType,
+                    acquiredAt: existingLock.lock.acquiredAt,
+                    expiresAt: existingLock.lock.expiresAt,
+                    pid: existingLock.lock.pid,
+                },
+            };
+        }
+        // No existing lock, acquire it
+        return this.createLock(lockPath, type, resource, reason, timeoutMs);
+    }
+    /**
+     * Acquire lock with wait/retry
+     */
+    async acquireWithWait(options, waitTimeoutMs, retryIntervalMs) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < waitTimeoutMs) {
+            const result = await this.acquire({ ...options, wait: false });
+            if (result.acquired) {
+                return result;
+            }
+            // Wait with jitter before retrying
+            await sleepWithJitter(retryIntervalMs);
+        }
+        // Timeout
+        const lockKey = this.getLockKey(options.type, options.resource);
+        const existingLock = await this.readLock(this.getLockPath(lockKey));
+        return {
+            acquired: false,
+            error: `Lock acquisition timed out after ${waitTimeoutMs}ms`,
+            heldBy: existingLock
+                ? {
+                    agentId: existingLock.lock.agentId,
+                    agentType: existingLock.lock.agentType,
+                    acquiredAt: existingLock.lock.acquiredAt,
+                    expiresAt: existingLock.lock.expiresAt,
+                    pid: existingLock.lock.pid,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Release a lock
+     */
+    async release(type, resource) {
+        const lockKey = this.getLockKey(type, resource);
+        const lockPath = this.getLockPath(lockKey);
+        // Stop renewal timer
+        this.stopRenewal(lockKey);
+        const existingLock = await this.readLock(lockPath);
+        if (!existingLock) {
+            this.heldLocks.delete(lockKey);
+            return { released: true };
+        }
+        // Check if we own the lock
+        if (existingLock.lock.agentId !== this.agent.id) {
+            return {
+                released: false,
+                error: `Lock held by different agent: ${existingLock.lock.agentId}`,
+                wasHeldByOther: true,
+            };
+        }
+        // Delete the lock file
+        await unlinkSafe(lockPath);
+        this.heldLocks.delete(lockKey);
+        debug(`Lock released: ${lockKey}`);
+        return { released: true };
+    }
+    /**
+     * Release all locks held by this manager
+     */
+    async releaseAll() {
+        for (const [, lock] of this.heldLocks) {
+            await this.release(lock.type, lock.resource);
+        }
+    }
+    /**
+     * Check if a lock is held
+     */
+    async isLocked(type, resource) {
+        const lockKey = this.getLockKey(type, resource);
+        const lockPath = this.getLockPath(lockKey);
+        const existingLock = await this.readLock(lockPath);
+        if (!existingLock) {
+            return false;
+        }
+        // Check expiration
+        const now = Date.now();
+        const expiresAt = new Date(existingLock.lock.expiresAt).getTime();
+        return now <= expiresAt;
+    }
+    /**
+     * Get lock info
+     */
+    async getLockInfo(type, resource) {
+        const lockKey = this.getLockKey(type, resource);
+        const lockPath = this.getLockPath(lockKey);
+        const existingLock = await this.readLock(lockPath);
+        return existingLock?.lock ?? null;
+    }
+    /**
+     * Check if we hold a lock
+     */
+    holdsLock(type, resource) {
+        const lockKey = this.getLockKey(type, resource);
+        return this.heldLocks.has(lockKey);
+    }
+    /**
+     * Get all locks held by this manager
+     */
+    getHeldLocks() {
+        return Array.from(this.heldLocks.values());
+    }
+    /**
+     * Start auto-renewal for a lock
+     */
+    startAutoRenewal(type, resource, intervalMs) {
+        const lockKey = this.getLockKey(type, resource);
+        const interval = intervalMs ?? Math.floor(this.config.lockTimeoutMs / 3);
+        if (this.renewalTimers.has(lockKey)) {
+            return;
+        }
+        const timer = setInterval(async () => {
+            try {
+                const lockPath = this.getLockPath(lockKey);
+                const existingLock = await this.readLock(lockPath);
+                if (existingLock && existingLock.lock.agentId === this.agent.id) {
+                    await this.renewLock(lockPath, existingLock);
+                    debug(`Lock auto-renewed: ${lockKey}`);
+                }
+                else {
+                    // We lost the lock
+                    this.stopRenewal(lockKey);
+                    this.heldLocks.delete(lockKey);
+                    debug(`Lost lock, stopping renewal: ${lockKey}`);
+                }
+            }
+            catch (error) {
+                debug(`Auto-renewal failed for ${lockKey}:`, error);
+            }
+        }, interval);
+        // Don't block process exit
+        timer.unref();
+        this.renewalTimers.set(lockKey, timer);
+        debug(`Auto-renewal started for ${lockKey} (interval=${interval}ms)`);
+    }
+    /**
+     * Stop auto-renewal for a lock
+     */
+    stopRenewal(lockKey) {
+        const timer = this.renewalTimers.get(lockKey);
+        if (timer) {
+            clearInterval(timer);
+            this.renewalTimers.delete(lockKey);
+            debug(`Auto-renewal stopped for ${lockKey}`);
+        }
+    }
+    /**
+     * Stop all auto-renewals
+     */
+    stopAllRenewals() {
+        for (const [lockKey, timer] of this.renewalTimers) {
+            clearInterval(timer);
+            debug(`Auto-renewal stopped for ${lockKey}`);
+        }
+        this.renewalTimers.clear();
+    }
+    /**
+     * Cleanup expired locks in the lock directory
+     */
+    async cleanupExpiredLocks() {
+        let cleaned = 0;
+        try {
+            const files = await fs.readdir(this.lockDir);
+            for (const file of files) {
+                if (!file.endsWith('.lock'))
+                    continue;
+                const lockPath = join(this.lockDir, file);
+                const lock = await this.readLock(lockPath);
+                if (!lock)
+                    continue;
+                const now = Date.now();
+                const expiresAt = new Date(lock.lock.expiresAt).getTime();
+                if (now > expiresAt) {
+                    await unlinkSafe(lockPath);
+                    cleaned++;
+                    debug(`Cleaned up expired lock: ${file}`);
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                debug('Cleanup failed:', error);
+            }
+        }
+        return cleaned;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Create a new lock
+     */
+    async createLock(lockPath, type, resource, reason, timeoutMs) {
+        // Use O_EXCL sentinel to prevent two agents both creating the lock
+        const sentinelPath = `${lockPath}.creating`;
+        const sentinel = await tryAcquireFileLock(sentinelPath, this.agent.id);
+        if (!sentinel) {
+            // Another agent is creating the lock right now — read what they wrote
+            const existingLock = await this.readLock(lockPath);
+            if (existingLock) {
+                return {
+                    acquired: false,
+                    error: `Lock acquired by another agent: ${existingLock.lock.agentId}`,
+                    heldBy: {
+                        agentId: existingLock.lock.agentId,
+                        agentType: existingLock.lock.agentType,
+                        acquiredAt: existingLock.lock.acquiredAt,
+                        expiresAt: existingLock.lock.expiresAt,
+                        pid: existingLock.lock.pid,
+                    },
+                };
+            }
+            return {
+                acquired: false,
+                error: 'Lock creation in progress by another agent',
+            };
+        }
+        try {
+            // Re-check after acquiring sentinel (another agent may have finished first)
+            const raceCheck = await this.readLock(lockPath);
+            if (raceCheck && raceCheck.lock.agentId !== this.agent.id) {
+                return {
+                    acquired: false,
+                    error: `Lock acquired by another agent: ${raceCheck.lock.agentId}`,
+                    heldBy: {
+                        agentId: raceCheck.lock.agentId,
+                        agentType: raceCheck.lock.agentType,
+                        acquiredAt: raceCheck.lock.acquiredAt,
+                        expiresAt: raceCheck.lock.expiresAt,
+                        pid: raceCheck.lock.pid,
+                    },
+                };
+            }
+            const now = new Date();
+            const expiresAt = new Date(now.getTime() + timeoutMs);
+            const lock = {
+                type,
+                resource,
+                agentId: this.agent.id,
+                agentType: this.agent.type,
+                pid: this.agent.pid,
+                acquiredAt: now.toISOString(),
+                expiresAt: expiresAt.toISOString(),
+                reason,
+                renewCount: 0,
+            };
+            const lockFile = {
+                version: '1.0.0',
+                lock,
+                history: [],
+            };
+            await atomicWriteJson(lockPath, lockFile);
+            const lockKey = this.getLockKey(type, resource);
+            this.heldLocks.set(lockKey, lock);
+            debug(`Lock acquired: ${lockKey}`);
+            return {
+                acquired: true,
+                lock,
+            };
+        }
+        finally {
+            await sentinel.release();
+        }
+    }
+    /**
+     * Renew an existing lock
+     */
+    async renewLock(lockPath, existingLock, reason) {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + this.config.lockTimeoutMs);
+        const lock = {
+            ...existingLock.lock,
+            expiresAt: expiresAt.toISOString(),
+            renewCount: existingLock.lock.renewCount + 1,
+            reason: reason ?? existingLock.lock.reason,
+        };
+        const lockFile = {
+            ...existingLock,
+            lock,
+        };
+        await atomicWriteJson(lockPath, lockFile);
+        const lockKey = this.getLockKey(lock.type, lock.resource);
+        this.heldLocks.set(lockKey, lock);
+        debug(`Lock renewed: ${lockKey} (count=${lock.renewCount})`);
+        return {
+            acquired: true,
+            lock,
+        };
+    }
+    /**
+     * Force acquire a lock (taking over from expired/stale holder)
+     */
+    async forceAcquire(lockPath, type, resource, reason, timeoutMs, existingLock) {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + timeoutMs);
+        const lock = {
+            type,
+            resource,
+            agentId: this.agent.id,
+            agentType: this.agent.type,
+            pid: this.agent.pid,
+            acquiredAt: now.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+            reason,
+            renewCount: 0,
+        };
+        const lockFile = {
+            version: '1.0.0',
+            lock,
+            history: [
+                ...existingLock.history,
+                {
+                    agentId: existingLock.lock.agentId,
+                    acquiredAt: existingLock.lock.acquiredAt,
+                    releasedAt: now.toISOString(),
+                    reason: 'Force-released (expired/stale)',
+                },
+            ],
+        };
+        await atomicWriteJson(lockPath, lockFile);
+        const lockKey = this.getLockKey(type, resource);
+        this.heldLocks.set(lockKey, lock);
+        debug(`Lock force-acquired: ${lockKey}`);
+        return {
+            acquired: true,
+            lock,
+        };
+    }
+    /**
+     * Check if lock holder is stale
+     */
+    async isHolderStale(lock) {
+        // Check if process is still running
+        if (lock.pid) {
+            try {
+                process.kill(lock.pid, 0);
+                return false; // Process exists
+            }
+            catch {
+                return true; // Process doesn't exist
+            }
+        }
+        // Can't determine - assume not stale
+        return false;
+    }
+    /**
+     * Read lock file
+     */
+    async readLock(lockPath) {
+        const data = await readJsonSafe(lockPath);
+        if (!data)
+            return null;
+        const result = LockFileSchema.safeParse(data);
+        if (!result.success) {
+            debug('Invalid lock file schema:', result.error);
+            return null;
+        }
+        return result.data;
+    }
+    /**
+     * Get lock key from type and resource
+     */
+    getLockKey(type, resource) {
+        return `${type}:${resource}`;
+    }
+    /**
+     * Get lock file path
+     */
+    getLockPath(lockKey) {
+        // Hash the key for safe filename
+        const hash = createHash('sha256').update(lockKey).digest('hex').slice(0, 16);
+        return join(this.lockDir, `${hash}.lock`);
+    }
+    /**
+     * Ensure lock directory exists
+     */
+    async ensureLockDir() {
+        await fs.mkdir(this.lockDir, { recursive: true });
+    }
+}
+/**
+ * Create a lock manager
+ */
+export function createLockManager(options) {
+    return new LockManager(options);
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * Execute a function while holding a lock
+ *
+ * @example
+ * ```typescript
+ * const result = await withLock(
+ *   lockManager,
+ *   { type: 'action', resource: 'gate' },
+ *   async () => {
+ *     // Perform work that requires exclusive access
+ *     return await runGates();
+ *   }
+ * );
+ * ```
+ */
+export async function withLock(manager, options, fn) {
+    const result = await manager.acquire({ ...options, wait: true });
+    if (!result.acquired) {
+        throw new Error(`Failed to acquire lock: ${result.error}`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await manager.release(options.type, options.resource);
+    }
+}
+/**
+ * Try to execute a function while holding a lock (non-blocking)
+ *
+ * Returns null if lock couldn't be acquired.
+ */
+export async function tryWithLock(manager, options, fn) {
+    const result = await manager.acquire({ ...options, wait: false });
+    if (!result.acquired) {
+        return { success: false, heldBy: result.heldBy };
+    }
+    try {
+        const fnResult = await fn();
+        return { success: true, result: fnResult };
+    }
+    finally {
+        await manager.release(options.type, options.resource);
+    }
+}