@eddacraft/anvil-runtime 0.1.0

package/dist/concurrency/agent.js

@@ -0,0 +1,440 @@
+/**
+ * Agent Manager
+ *
+ * Handles agent identification, registration, and heartbeat management
+ * for multi-agent coordination in Anvil.
+ */
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { AgentRegistrySchema, AgentInfoSchema, getDefaultConcurrencyConfig, } from './types.js';
+import { atomicWriteJson, readJsonSafe } from './atomic.js';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('agent');
+// ============================================================================
+// Agent ID Detection
+// ============================================================================
+/**
+ * Environment variables for agent identification
+ */
+const AGENT_ENV_VARS = {
+    // Explicit Anvil agent ID
+    ANVIL_AGENT_ID: 'ANVIL_AGENT_ID',
+    ANVIL_AGENT_TYPE: 'ANVIL_AGENT_TYPE',
+    ANVIL_AGENT_NAME: 'ANVIL_AGENT_NAME',
+    ANVIL_SESSION_ID: 'ANVIL_SESSION_ID',
+    // Claude Code specific
+    CLAUDE_SESSION_ID: 'CLAUDE_SESSION_ID',
+    CLAUDE_CODE_SESSION: 'CLAUDE_CODE_SESSION',
+    // Cursor specific
+    CURSOR_SESSION_ID: 'CURSOR_SESSION_ID',
+    // General AI tool indicators
+    AI_TOOL: 'AI_TOOL',
+    EDITOR_PID: 'EDITOR_PID',
+    // CI indicators
+    CI: 'CI',
+    GITHUB_ACTIONS: 'GITHUB_ACTIONS',
+    GITLAB_CI: 'GITLAB_CI',
+    CIRCLECI: 'CIRCLECI',
+    JENKINS_URL: 'JENKINS_URL',
+};
+/**
+ * Detect agent type from environment
+ */
+export function detectAgentType() {
+    const env = process.env;
+    // Explicit type setting
+    if (env[AGENT_ENV_VARS.ANVIL_AGENT_TYPE]) {
+        const type = env[AGENT_ENV_VARS.ANVIL_AGENT_TYPE]?.toLowerCase();
+        if (type &&
+            ['claude', 'cursor', 'copilot', 'aider', 'continue', 'codeium', 'human', 'ci'].includes(type)) {
+            return type;
+        }
+    }
+    // CI detection
+    if (env[AGENT_ENV_VARS.CI] ||
+        env[AGENT_ENV_VARS.GITHUB_ACTIONS] ||
+        env[AGENT_ENV_VARS.GITLAB_CI] ||
+        env[AGENT_ENV_VARS.CIRCLECI] ||
+        env[AGENT_ENV_VARS.JENKINS_URL]) {
+        return 'ci';
+    }
+    // Claude Code detection
+    if (env[AGENT_ENV_VARS.CLAUDE_SESSION_ID] || env[AGENT_ENV_VARS.CLAUDE_CODE_SESSION]) {
+        return 'claude';
+    }
+    // Cursor detection
+    if (env[AGENT_ENV_VARS.CURSOR_SESSION_ID]) {
+        return 'cursor';
+    }
+    // Explicit AI tool setting
+    if (env[AGENT_ENV_VARS.AI_TOOL]) {
+        const tool = env[AGENT_ENV_VARS.AI_TOOL]?.toLowerCase();
+        if (tool === 'aider')
+            return 'aider';
+        if (tool === 'continue')
+            return 'continue';
+        if (tool === 'codeium')
+            return 'codeium';
+        if (tool === 'copilot')
+            return 'copilot';
+    }
+    // Check if running interactively (likely human)
+    if (process.stdin.isTTY && !env[AGENT_ENV_VARS.AI_TOOL]) {
+        return 'human';
+    }
+    return 'unknown';
+}
+/**
+ * Get or generate agent ID
+ */
+export function getAgentId() {
+    // Check explicit agent ID
+    const explicitId = process.env[AGENT_ENV_VARS.ANVIL_AGENT_ID];
+    if (explicitId) {
+        return explicitId;
+    }
+    // Use session IDs if available
+    if (process.env[AGENT_ENV_VARS.ANVIL_SESSION_ID]) {
+        return `session-${process.env[AGENT_ENV_VARS.ANVIL_SESSION_ID]}`;
+    }
+    if (process.env[AGENT_ENV_VARS.CLAUDE_SESSION_ID]) {
+        return `claude-${process.env[AGENT_ENV_VARS.CLAUDE_SESSION_ID]}`;
+    }
+    if (process.env[AGENT_ENV_VARS.CURSOR_SESSION_ID]) {
+        return `cursor-${process.env[AGENT_ENV_VARS.CURSOR_SESSION_ID]}`;
+    }
+    // CI-specific IDs
+    if (process.env['GITHUB_RUN_ID']) {
+        return `gh-${process.env['GITHUB_RUN_ID']}-${process.env['GITHUB_RUN_ATTEMPT'] || '1'}`;
+    }
+    if (process.env['CI_JOB_ID']) {
+        return `ci-${process.env['CI_JOB_ID']}`;
+    }
+    // Generate based on process
+    return `proc-${process.pid}-${Date.now().toString(36)}`;
+}
+/**
+ * Get session ID if available
+ */
+export function getSessionId() {
+    return (process.env[AGENT_ENV_VARS.ANVIL_SESSION_ID] ||
+        process.env[AGENT_ENV_VARS.CLAUDE_SESSION_ID] ||
+        process.env[AGENT_ENV_VARS.CURSOR_SESSION_ID] ||
+        undefined);
+}
+/**
+ * Get agent name from environment or generate one
+ */
+export function getAgentName() {
+    const explicitName = process.env[AGENT_ENV_VARS.ANVIL_AGENT_NAME];
+    if (explicitName) {
+        return explicitName;
+    }
+    const type = detectAgentType();
+    const pid = process.pid;
+    switch (type) {
+        case 'claude':
+            return `Claude Code (${pid})`;
+        case 'cursor':
+            return `Cursor AI (${pid})`;
+        case 'copilot':
+            return `GitHub Copilot (${pid})`;
+        case 'aider':
+            return `Aider (${pid})`;
+        case 'continue':
+            return `Continue (${pid})`;
+        case 'codeium':
+            return `Codeium (${pid})`;
+        case 'human':
+            return `Human Developer (${pid})`;
+        case 'ci':
+            return `CI Runner (${pid})`;
+        default:
+            return `Agent (${pid})`;
+    }
+}
+/**
+ * Create agent info from environment
+ */
+export function createAgentInfo(overrides) {
+    return AgentInfoSchema.parse({
+        id: getAgentId(),
+        type: detectAgentType(),
+        pid: process.pid,
+        name: getAgentName(),
+        sessionId: getSessionId(),
+        ...overrides,
+    });
+}
+/**
+ * Agent Manager
+ *
+ * Manages agent registration, heartbeat, and lifecycle in a multi-agent environment.
+ */
+export class AgentManager {
+    workspaceRoot;
+    config;
+    agent;
+    registryPath;
+    heartbeatTimer = null;
+    isRegistered = false;
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.config = {
+            ...getDefaultConcurrencyConfig(),
+            ...options.config,
+        };
+        this.agent = options.agentInfo ?? createAgentInfo();
+        this.registryPath = join(this.workspaceRoot, this.config.registryPath);
+    }
+    /**
+     * Check if agent is registered
+     */
+    get registered() {
+        return this.isRegistered;
+    }
+    /**
+     * Get the current agent info
+     */
+    getAgent() {
+        return { ...this.agent };
+    }
+    /**
+     * Get the agent ID
+     */
+    getAgentId() {
+        return this.agent.id;
+    }
+    /**
+     * Register this agent
+     */
+    async register(operation) {
+        await this.ensureDir();
+        const registry = await this.loadRegistry();
+        const now = new Date().toISOString();
+        const registration = {
+            agent: this.agent,
+            registeredAt: now,
+            lastHeartbeat: now,
+            heartbeatCount: 0,
+            state: 'active',
+            currentOperation: operation,
+            workspaceRoot: this.workspaceRoot,
+        };
+        registry.agents[this.agent.id] = registration;
+        registry.updatedAt = now;
+        await this.saveRegistry(registry);
+        this.isRegistered = true;
+        debug(`Agent registered: ${this.agent.id} (${this.agent.type})`);
+    }
+    /**
+     * Start heartbeat timer
+     */
+    startHeartbeat() {
+        if (this.heartbeatTimer) {
+            return;
+        }
+        this.heartbeatTimer = setInterval(async () => {
+            try {
+                await this.heartbeat();
+            }
+            catch (error) {
+                debug('Heartbeat failed:', error);
+            }
+        }, this.config.heartbeatIntervalMs);
+        // Don't block process exit for heartbeat
+        this.heartbeatTimer.unref();
+        debug(`Heartbeat started: interval=${this.config.heartbeatIntervalMs}ms`);
+    }
+    /**
+     * Stop heartbeat timer
+     */
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+            debug('Heartbeat stopped');
+        }
+    }
+    /**
+     * Send a heartbeat
+     */
+    async heartbeat(operation) {
+        const registry = await this.loadRegistry();
+        const registration = registry.agents[this.agent.id];
+        if (!registration) {
+            // Re-register if not in registry
+            await this.register(operation);
+            return;
+        }
+        const now = new Date().toISOString();
+        registration.lastHeartbeat = now;
+        registration.heartbeatCount++;
+        registration.state = 'active';
+        if (operation !== undefined) {
+            registration.currentOperation = operation;
+        }
+        registry.updatedAt = now;
+        await this.saveRegistry(registry);
+        debug(`Heartbeat sent: ${this.agent.id} (count=${registration.heartbeatCount})`);
+    }
+    /**
+     * Update current operation
+     */
+    async setOperation(operation) {
+        const registry = await this.loadRegistry();
+        const registration = registry.agents[this.agent.id];
+        if (registration) {
+            registration.currentOperation = operation;
+            registration.lastHeartbeat = new Date().toISOString();
+            registry.updatedAt = new Date().toISOString();
+            await this.saveRegistry(registry);
+        }
+    }
+    /**
+     * Unregister this agent
+     */
+    async unregister() {
+        this.stopHeartbeat();
+        const registry = await this.loadRegistry();
+        if (registry.agents[this.agent.id]) {
+            registry.agents[this.agent.id].state = 'terminated';
+            registry.updatedAt = new Date().toISOString();
+            await this.saveRegistry(registry);
+        }
+        this.isRegistered = false;
+        debug(`Agent unregistered: ${this.agent.id}`);
+    }
+    /**
+     * Get all registered agents
+     */
+    async getAllAgents() {
+        const registry = await this.loadRegistry();
+        return Object.values(registry.agents);
+    }
+    /**
+     * Get active agents
+     */
+    async getActiveAgents() {
+        const registry = await this.loadRegistry();
+        const now = Date.now();
+        const staleThreshold = this.config.staleThresholdMs;
+        return Object.values(registry.agents).filter((reg) => {
+            const lastHeartbeat = new Date(reg.lastHeartbeat).getTime();
+            const isStale = now - lastHeartbeat > staleThreshold;
+            return reg.state === 'active' && !isStale;
+        });
+    }
+    /**
+     * Cleanup stale agents
+     */
+    async cleanupStaleAgents() {
+        const registry = await this.loadRegistry();
+        const now = Date.now();
+        const staleThreshold = this.config.staleThresholdMs;
+        const staleAgents = [];
+        for (const [id, reg] of Object.entries(registry.agents)) {
+            const lastHeartbeat = new Date(reg.lastHeartbeat).getTime();
+            const isStale = now - lastHeartbeat > staleThreshold;
+            if (isStale && reg.state === 'active') {
+                reg.state = 'stale';
+                staleAgents.push(id);
+                debug(`Agent marked stale: ${id}`);
+            }
+        }
+        if (staleAgents.length > 0) {
+            registry.updatedAt = new Date().toISOString();
+            await this.saveRegistry(registry);
+        }
+        return staleAgents;
+    }
+    /**
+     * Check if an agent is stale
+     */
+    async isAgentStale(agentId) {
+        const registry = await this.loadRegistry();
+        const registration = registry.agents[agentId];
+        if (!registration) {
+            return true;
+        }
+        if (registration.state === 'stale' || registration.state === 'terminated') {
+            return true;
+        }
+        const now = Date.now();
+        const lastHeartbeat = new Date(registration.lastHeartbeat).getTime();
+        return now - lastHeartbeat > this.config.staleThresholdMs;
+    }
+    /**
+     * Check if a process is still running
+     */
+    isProcessRunning(pid) {
+        try {
+            // Sending signal 0 doesn't actually send a signal but checks if process exists
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get git user for commit trailers
+     */
+    getGitAgentTrailer() {
+        return `Anvil-Agent: ${this.agent.id} (${this.agent.type})`;
+    }
+    /**
+     * Load registry from file
+     */
+    async loadRegistry() {
+        const data = await readJsonSafe(this.registryPath);
+        if (data) {
+            const result = AgentRegistrySchema.safeParse(data);
+            if (result.success) {
+                return result.data;
+            }
+            debug('Invalid registry schema, creating new:', result.error);
+        }
+        return {
+            version: '1.0.0',
+            updatedAt: new Date().toISOString(),
+            agents: {},
+        };
+    }
+    /**
+     * Save registry to file
+     */
+    async saveRegistry(registry) {
+        await atomicWriteJson(this.registryPath, registry);
+    }
+    /**
+     * Ensure registry directory exists
+     */
+    async ensureDir() {
+        const dir = dirname(this.registryPath);
+        await fs.mkdir(dir, { recursive: true });
+    }
+}
+/**
+ * Create an agent manager
+ */
+export function createAgentManager(options) {
+    return new AgentManager(options);
+}
+/**
+ * Global agent manager singleton (optional usage pattern)
+ */
+let globalAgentManager = null;
+/**
+ * Initialize global agent manager
+ */
+export function initializeGlobalAgent(options) {
+    globalAgentManager = createAgentManager(options);
+    return globalAgentManager;
+}
+/**
+ * Get global agent manager
+ */
+export function getGlobalAgent() {
+    return globalAgentManager;
+}

package/dist/concurrency/atomic.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Atomic File Operations
+ *
+ * Provides atomic read/write operations for JSON files to prevent
+ * corruption in multi-agent/multi-process scenarios.
+ *
+ * Uses the atomic write pattern: write to temp file, then rename.
+ * This ensures that either the old or new content is visible, never partial.
+ */
+/**
+ * Atomic write options
+ */
+export interface AtomicWriteOptions {
+    /** File mode (default: 0o644) */
+    mode?: number;
+    /** Retry count for rename conflicts (default: 3) */
+    retries?: number;
+    /** Create parent directories if needed (default: true) */
+    createDirs?: boolean;
+}
+/**
+ * Write JSON atomically
+ *
+ * 1. Write content to a temp file in the same directory
+ * 2. Rename temp file to target (atomic on most filesystems)
+ * 3. Clean up temp file on error
+ */
+export declare function atomicWriteJson(filePath: string, data: unknown, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Write text atomically
+ */
+export declare function atomicWriteText(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Read JSON safely (returns null if file doesn't exist or is invalid)
+ */
+export declare function readJsonSafe<T = unknown>(filePath: string): Promise<T | null>;
+/**
+ * Read JSON with retries (for handling transient lock conflicts)
+ */
+export declare function readJsonWithRetry<T = unknown>(filePath: string, retries?: number, delayMs?: number): Promise<T | null>;
+/**
+ * Atomic file lock using a lock file
+ *
+ * Uses O_EXCL flag for atomic creation - only succeeds if file doesn't exist.
+ * This provides a simple but robust mutual exclusion mechanism.
+ */
+export interface FileLockOptions {
+    /** Maximum time to wait for lock (ms) */
+    timeout?: number;
+    /** Retry interval (ms) */
+    retryInterval?: number;
+    /** Lock file content */
+    content?: string;
+}
+export interface FileLockHandle {
+    /** Path to the lock file */
+    path: string;
+    /** Release the lock */
+    release: () => Promise<void>;
+}
+/**
+ * Acquire a file lock (blocks until acquired or timeout)
+ */
+export declare function acquireFileLock(lockPath: string, options?: FileLockOptions): Promise<FileLockHandle | null>;
+/**
+ * Try to acquire a file lock (non-blocking)
+ */
+export declare function tryAcquireFileLock(lockPath: string, content?: string): Promise<FileLockHandle | null>;
+/**
+ * Check if a lock file exists
+ */
+export declare function isLocked(lockPath: string): Promise<boolean>;
+/**
+ * Force release a lock (use with caution)
+ */
+export declare function forceReleaseLock(lockPath: string): Promise<boolean>;
+/**
+ * Delete file if it exists (no error if missing)
+ */
+export declare function unlinkSafe(filePath: string): Promise<boolean>;
+/**
+ * Check if file exists
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Get file modification time
+ */
+export declare function getFileMtime(filePath: string): Promise<Date | null>;
+/**
+ * Sleep with jitter (to prevent thundering herd)
+ */
+export declare function sleepWithJitter(baseMs: number, jitterPercent?: number): Promise<void>;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/concurrency/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../src/concurrency/atomic.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAWnF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EACjD,QAAQ,EAAE,MAAM,EAChB,OAAO,SAAI,EACX,OAAO,SAAK,GACX,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAsChC;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,SAAK,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA4BhC;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOjE;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWzE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUnE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAOzE;AASD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlF"}