@eddacraft/anvil-runtime 0.1.0

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

@@ -0,0 +1,166 @@
+/**
+ * Queue Manager
+ *
+ * Provides fair queuing for resources when multiple agents are waiting
+ * for the same lock. Supports priority-based scheduling and timeout handling.
+ */
+import { type QueueJoinResult, type QueueStatusResult, type LockType, type AgentInfo, type ConcurrencyConfig, type LockAcquisitionResult } from './types.js';
+import { LockManager } from './lock-manager.js';
+/**
+ * Options for QueueManager
+ */
+export interface QueueManagerOptions {
+    /** Workspace root directory */
+    workspaceRoot: string;
+    /** Concurrency configuration */
+    config?: Partial<ConcurrencyConfig>;
+    /** Agent info */
+    agentInfo?: AgentInfo;
+    /** Lock manager (optional, created if not provided) */
+    lockManager?: LockManager;
+}
+/**
+ * Options for joining a queue
+ */
+export interface QueueJoinOptions {
+    /** Lock type */
+    type: LockType;
+    /** Resource identifier */
+    resource: string;
+    /** Priority (lower = higher priority, default: 100) */
+    priority?: number;
+    /** Reason for waiting */
+    reason?: string;
+    /** Custom timeout (overrides config) */
+    timeoutMs?: number;
+}
+/**
+ * Options for waiting in queue
+ */
+export interface QueueWaitOptions extends QueueJoinOptions {
+    /** Maximum time to wait in queue (ms) */
+    maxWaitMs?: number;
+    /** Polling interval (ms) */
+    pollIntervalMs?: number;
+    /** Callback when position changes */
+    onPositionChange?: (position: number, total: number) => void;
+    /** Callback when lock is acquired */
+    onLockAcquired?: () => void;
+}
+/**
+ * Queue Manager
+ *
+ * Manages fair queuing for resources across multiple agents.
+ */
+export declare class QueueManager {
+    private readonly workspaceRoot;
+    private readonly config;
+    private readonly agent;
+    private readonly queueDir;
+    private readonly lockManager;
+    constructor(options: QueueManagerOptions);
+    /**
+     * Get the agent ID
+     */
+    getAgentId(): string;
+    /**
+     * Join a queue for a resource
+     */
+    join(options: QueueJoinOptions): Promise<QueueJoinResult>;
+    /**
+     * Leave a queue
+     */
+    leave(type: LockType, resource: string): Promise<boolean>;
+    /**
+     * Get queue status
+     */
+    getStatus(type: LockType, resource: string): Promise<QueueStatusResult>;
+    /**
+     * Check if it's our turn (we're first in queue)
+     */
+    isOurTurn(type: LockType, resource: string): Promise<boolean>;
+    /**
+     * Wait in queue until lock is acquired
+     *
+     * This is the main coordination primitive - joins queue, waits for turn,
+     * then acquires lock.
+     */
+    waitForLock(options: QueueWaitOptions): Promise<LockAcquisitionResult>;
+    /**
+     * Get all queues in the workspace
+     */
+    getAllQueues(): Promise<Array<{
+        type: LockType;
+        resource: string;
+        entries: number;
+    }>>;
+    /**
+     * Cleanup all timed-out entries across all queues
+     */
+    cleanupAllTimedOut(): Promise<number>;
+    /**
+     * Load queue from file
+     */
+    private loadQueue;
+    /**
+     * Sort queue entries by priority then by queued time
+     */
+    private sortQueue;
+    /**
+     * Cleanup timed-out entries
+     */
+    private cleanupTimedOut;
+    /**
+     * Get queue file path
+     */
+    private getQueuePath;
+    /**
+     * Ensure queue directory exists
+     */
+    private ensureQueueDir;
+}
+/**
+ * Create a queue manager
+ */
+export declare function createQueueManager(options: QueueManagerOptions): QueueManager;
+/**
+ * Coordinated execution with fair queuing
+ *
+ * This is the primary way to execute code that requires exclusive access
+ * to a resource in a multi-agent environment.
+ *
+ * @example
+ * ```typescript
+ * const result = await coordinatedExecution(
+ *   queueManager,
+ *   { type: 'action', resource: 'gate', reason: 'Running quality gates' },
+ *   async () => {
+ *     return await runGates();
+ *   }
+ * );
+ * ```
+ */
+export declare function coordinatedExecution<T>(manager: QueueManager, options: QueueWaitOptions, fn: () => Promise<T>): Promise<T>;
+/**
+ * Result of a concurrent group execution
+ */
+export interface ConcurrentGroupResult<T> {
+    /** Results from each execution */
+    results: Array<{
+        agentId: string;
+        result?: T;
+        error?: Error;
+    }>;
+    /** Total execution time */
+    totalTimeMs: number;
+    /** Number of successful executions */
+    successCount: number;
+}
+/**
+ * Execute function with coordination, allowing limited concurrency
+ *
+ * Useful when you want to allow some parallel execution but limit the
+ * total number of concurrent agents.
+ */
+export declare function withConcurrencyLimit<T>(manager: QueueManager, type: LockType, resource: string, maxConcurrent: number, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=queue-manager.d.ts.map

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

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

package/dist/concurrency/queue-manager.js

@@ -0,0 +1,442 @@
+/**
+ * Queue Manager
+ *
+ * Provides fair queuing for resources when multiple agents are waiting
+ * for the same lock. Supports priority-based scheduling and timeout handling.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { QueueFileSchema, getDefaultConcurrencyConfig, } from './types.js';
+import { atomicWriteJson, readJsonSafe, unlinkSafe, sleepWithJitter, acquireFileLock, } from './atomic.js';
+import { createAgentInfo } from './agent.js';
+import { LockManager } from './lock-manager.js';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('queue');
+/**
+ * Queue Manager
+ *
+ * Manages fair queuing for resources across multiple agents.
+ */
+export class QueueManager {
+    workspaceRoot;
+    config;
+    agent;
+    queueDir;
+    lockManager;
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.config = {
+            ...getDefaultConcurrencyConfig(),
+            ...options.config,
+        };
+        this.agent = options.agentInfo ?? createAgentInfo();
+        this.queueDir = join(this.workspaceRoot, this.config.queueDir);
+        this.lockManager =
+            options.lockManager ??
+                new LockManager({
+                    workspaceRoot: options.workspaceRoot,
+                    config: options.config,
+                    agentInfo: this.agent,
+                });
+    }
+    /**
+     * Get the agent ID
+     */
+    getAgentId() {
+        return this.agent.id;
+    }
+    /**
+     * Join a queue for a resource
+     */
+    async join(options) {
+        const { type, resource, priority = 100, reason, timeoutMs = this.config.queueTimeoutMs, } = options;
+        await this.ensureQueueDir();
+        const queuePath = this.getQueuePath(type, resource);
+        // Serialise access to the queue file to prevent lost updates
+        const lockPath = `${queuePath}.lock`;
+        const fileLock = await acquireFileLock(lockPath, {
+            timeout: Math.min(timeoutMs, 30_000),
+            retryInterval: 50,
+        });
+        if (!fileLock) {
+            throw new Error(`Timed out waiting for queue lock: ${type}:${resource}`);
+        }
+        try {
+            const queue = await this.loadQueue(queuePath, type, resource);
+            // Check if already in queue
+            const existingIndex = queue.entries.findIndex((e) => e.agentId === this.agent.id);
+            if (existingIndex !== -1) {
+                // Update existing entry
+                queue.entries[existingIndex] = {
+                    ...queue.entries[existingIndex],
+                    priority,
+                    reason,
+                    timeoutAt: new Date(Date.now() + timeoutMs).toISOString(),
+                };
+                this.sortQueue(queue);
+                queue.updatedAt = new Date().toISOString();
+                await atomicWriteJson(queuePath, queue);
+                const newPosition = queue.entries.findIndex((e) => e.agentId === this.agent.id) + 1;
+                debug(`Queue entry updated: ${type}:${resource} position=${newPosition}`);
+                return {
+                    entryId: queue.entries[existingIndex].id,
+                    position: newPosition,
+                    alreadyQueued: true,
+                };
+            }
+            // Check queue size limit
+            if (queue.entries.length >= this.config.maxQueueSize) {
+                throw new Error(`Queue is full (max ${this.config.maxQueueSize} entries)`);
+            }
+            // Create new entry
+            const entry = {
+                id: randomUUID(),
+                agentId: this.agent.id,
+                agentType: this.agent.type,
+                lockType: type,
+                resource,
+                queuedAt: new Date().toISOString(),
+                priority,
+                timeoutAt: new Date(Date.now() + timeoutMs).toISOString(),
+                reason,
+            };
+            queue.entries.push(entry);
+            this.sortQueue(queue);
+            queue.updatedAt = new Date().toISOString();
+            await atomicWriteJson(queuePath, queue);
+            const position = queue.entries.findIndex((e) => e.id === entry.id) + 1;
+            debug(`Joined queue: ${type}:${resource} position=${position}`);
+            return {
+                entryId: entry.id,
+                position,
+                alreadyQueued: false,
+            };
+        }
+        finally {
+            await fileLock.release();
+        }
+    }
+    /**
+     * Leave a queue
+     */
+    async leave(type, resource) {
+        const queuePath = this.getQueuePath(type, resource);
+        const queue = await this.loadQueue(queuePath, type, resource);
+        const index = queue.entries.findIndex((e) => e.agentId === this.agent.id);
+        if (index === -1) {
+            return false;
+        }
+        queue.entries.splice(index, 1);
+        queue.updatedAt = new Date().toISOString();
+        if (queue.entries.length === 0) {
+            await unlinkSafe(queuePath);
+        }
+        else {
+            await atomicWriteJson(queuePath, queue);
+        }
+        debug(`Left queue: ${type}:${resource}`);
+        return true;
+    }
+    /**
+     * Get queue status
+     */
+    async getStatus(type, resource) {
+        const queuePath = this.getQueuePath(type, resource);
+        const queue = await this.loadQueue(queuePath, type, resource);
+        // Clean up timed-out entries
+        await this.cleanupTimedOut(queue, queuePath);
+        const yourEntry = queue.entries.find((e) => e.agentId === this.agent.id);
+        const yourPosition = yourEntry
+            ? queue.entries.findIndex((e) => e.agentId === this.agent.id) + 1
+            : undefined;
+        // Get current lock holder
+        const lockInfo = await this.lockManager.getLockInfo(type, resource);
+        return {
+            totalEntries: queue.entries.length,
+            yourPosition,
+            yourEntry,
+            currentHolder: lockInfo
+                ? {
+                    agentId: lockInfo.agentId,
+                    agentType: lockInfo.agentType,
+                    acquiredAt: lockInfo.acquiredAt,
+                    expiresAt: lockInfo.expiresAt,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Check if it's our turn (we're first in queue)
+     */
+    async isOurTurn(type, resource) {
+        const status = await this.getStatus(type, resource);
+        return status.yourPosition === 1;
+    }
+    /**
+     * Wait in queue until lock is acquired
+     *
+     * This is the main coordination primitive - joins queue, waits for turn,
+     * then acquires lock.
+     */
+    async waitForLock(options) {
+        const { type, resource, priority, reason, timeoutMs, maxWaitMs = this.config.queueTimeoutMs, pollIntervalMs = 500, onPositionChange, onLockAcquired, } = options;
+        const startTime = Date.now();
+        // First try to acquire lock directly (might be available)
+        const directResult = await this.lockManager.acquire({
+            type,
+            resource,
+            reason,
+            wait: false,
+        });
+        if (directResult.acquired) {
+            onLockAcquired?.();
+            return directResult;
+        }
+        // Join queue
+        const joinResult = await this.join({ type, resource, priority, reason, timeoutMs });
+        let lastPosition = joinResult.position;
+        debug(`Waiting in queue: ${type}:${resource} position=${lastPosition}`);
+        try {
+            while (Date.now() - startTime < maxWaitMs) {
+                // Check our position
+                const status = await this.getStatus(type, resource);
+                if (status.yourPosition !== lastPosition) {
+                    lastPosition = status.yourPosition ?? lastPosition;
+                    onPositionChange?.(lastPosition, status.totalEntries);
+                    debug(`Queue position changed: ${type}:${resource} position=${lastPosition}`);
+                }
+                // If we're first, try to acquire lock
+                if (status.yourPosition === 1) {
+                    const lockResult = await this.lockManager.acquire({
+                        type,
+                        resource,
+                        reason,
+                        wait: false,
+                    });
+                    if (lockResult.acquired) {
+                        // Leave queue and return
+                        await this.leave(type, resource);
+                        onLockAcquired?.();
+                        return lockResult;
+                    }
+                    // Lock still held, wait longer
+                }
+                // Wait before polling again
+                await sleepWithJitter(pollIntervalMs);
+            }
+            // Timeout
+            await this.leave(type, resource);
+            return {
+                acquired: false,
+                error: `Queue wait timed out after ${maxWaitMs}ms`,
+                queuePosition: lastPosition,
+            };
+        }
+        catch (error) {
+            // Cleanup on error
+            await this.leave(type, resource).catch(() => { });
+            throw error;
+        }
+    }
+    /**
+     * Get all queues in the workspace
+     */
+    async getAllQueues() {
+        const result = [];
+        try {
+            const files = await fs.readdir(this.queueDir);
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const queuePath = join(this.queueDir, file);
+                const data = await readJsonSafe(queuePath);
+                if (data) {
+                    const parseResult = QueueFileSchema.safeParse(data);
+                    if (parseResult.success) {
+                        result.push({
+                            type: parseResult.data.lockType,
+                            resource: parseResult.data.resource,
+                            entries: parseResult.data.entries.length,
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                debug('Failed to list queues:', error);
+            }
+        }
+        return result;
+    }
+    /**
+     * Cleanup all timed-out entries across all queues
+     */
+    async cleanupAllTimedOut() {
+        let cleaned = 0;
+        try {
+            const files = await fs.readdir(this.queueDir);
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const queuePath = join(this.queueDir, file);
+                const data = await readJsonSafe(queuePath);
+                if (data) {
+                    const parseResult = QueueFileSchema.safeParse(data);
+                    if (parseResult.success) {
+                        cleaned += await this.cleanupTimedOut(parseResult.data, queuePath);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                debug('Cleanup failed:', error);
+            }
+        }
+        return cleaned;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Load queue from file
+     */
+    async loadQueue(queuePath, type, resource) {
+        const data = await readJsonSafe(queuePath);
+        if (data) {
+            const result = QueueFileSchema.safeParse(data);
+            if (result.success) {
+                return result.data;
+            }
+            debug('Invalid queue file schema:', result.error);
+        }
+        return {
+            version: '1.0.0',
+            resource,
+            lockType: type,
+            updatedAt: new Date().toISOString(),
+            entries: [],
+        };
+    }
+    /**
+     * Sort queue entries by priority then by queued time
+     */
+    sortQueue(queue) {
+        queue.entries.sort((a, b) => {
+            // Lower priority number = higher priority
+            if (a.priority !== b.priority) {
+                return a.priority - b.priority;
+            }
+            // Earlier queued = higher priority
+            return new Date(a.queuedAt).getTime() - new Date(b.queuedAt).getTime();
+        });
+    }
+    /**
+     * Cleanup timed-out entries
+     */
+    async cleanupTimedOut(queue, queuePath) {
+        const now = Date.now();
+        const before = queue.entries.length;
+        queue.entries = queue.entries.filter((entry) => {
+            const timeoutAt = new Date(entry.timeoutAt).getTime();
+            return now < timeoutAt;
+        });
+        const removed = before - queue.entries.length;
+        if (removed > 0) {
+            if (queue.entries.length === 0) {
+                await unlinkSafe(queuePath);
+            }
+            else {
+                queue.updatedAt = new Date().toISOString();
+                await atomicWriteJson(queuePath, queue);
+            }
+            debug(`Cleaned up ${removed} timed-out queue entries`);
+        }
+        return removed;
+    }
+    /**
+     * Get queue file path
+     */
+    getQueuePath(type, resource) {
+        const key = `${type}:${resource}`;
+        const hash = createHash('sha256').update(key).digest('hex').slice(0, 16);
+        return join(this.queueDir, `${hash}.json`);
+    }
+    /**
+     * Ensure queue directory exists
+     */
+    async ensureQueueDir() {
+        await fs.mkdir(this.queueDir, { recursive: true });
+    }
+}
+/**
+ * Create a queue manager
+ */
+export function createQueueManager(options) {
+    return new QueueManager(options);
+}
+// ============================================================================
+// High-Level Coordination Primitives
+// ============================================================================
+/**
+ * Coordinated execution with fair queuing
+ *
+ * This is the primary way to execute code that requires exclusive access
+ * to a resource in a multi-agent environment.
+ *
+ * @example
+ * ```typescript
+ * const result = await coordinatedExecution(
+ *   queueManager,
+ *   { type: 'action', resource: 'gate', reason: 'Running quality gates' },
+ *   async () => {
+ *     return await runGates();
+ *   }
+ * );
+ * ```
+ */
+export async function coordinatedExecution(manager, options, fn) {
+    const lockResult = await manager.waitForLock(options);
+    if (!lockResult.acquired) {
+        throw new Error(`Failed to acquire lock: ${lockResult.error}`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await manager['lockManager'].release(options.type, options.resource);
+    }
+}
+/**
+ * Execute function with coordination, allowing limited concurrency
+ *
+ * Useful when you want to allow some parallel execution but limit the
+ * total number of concurrent agents.
+ */
+export async function withConcurrencyLimit(manager, type, resource, maxConcurrent, fn) {
+    // Use resource slots for concurrency limiting
+    for (let slot = 0; slot < maxConcurrent; slot++) {
+        const slotResource = `${resource}:slot-${slot}`;
+        const result = await manager.waitForLock({
+            type,
+            resource: slotResource,
+            maxWaitMs: 1000, // Quick check per slot
+        });
+        if (result.acquired) {
+            try {
+                return await fn();
+            }
+            finally {
+                await manager['lockManager'].release(type, slotResource);
+            }
+        }
+    }
+    // All slots taken, wait for any slot
+    return coordinatedExecution(manager, {
+        type,
+        resource: `${resource}:slot-0`, // Wait for first slot
+        maxWaitMs: manager['config'].queueTimeoutMs,
+    }, fn);
+}