@eddacraft/anvil-runtime 0.1.0

package/dist/concurrency/git-agent.js

@@ -0,0 +1,313 @@
+/**
+ * Git Agent Identification
+ *
+ * Utilities for identifying agents via git commit metadata.
+ * Supports reading and writing agent identification through commit trailers.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createAgentInfo } from './agent.js';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('git-agent');
+// ============================================================================
+// Trailer Constants
+// ============================================================================
+/**
+ * Git trailer keys used for agent identification
+ */
+export const GIT_TRAILERS = {
+    /** Agent ID trailer */
+    AGENT_ID: 'Anvil-Agent-ID',
+    /** Agent type trailer */
+    AGENT_TYPE: 'Anvil-Agent-Type',
+    /** Session ID trailer */
+    SESSION_ID: 'Anvil-Session-ID',
+    /** Agent name trailer */
+    AGENT_NAME: 'Anvil-Agent-Name',
+    /** Co-authored-by for agent attribution */
+    CO_AUTHORED_BY: 'Co-authored-by',
+};
+/**
+ * Parse trailers from commit message
+ */
+export function parseCommitTrailers(commitMessage) {
+    const trailers = {};
+    const lines = commitMessage.split('\n');
+    // Trailers are at the end, after a blank line
+    let inTrailers = false;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (line === '') {
+            if (inTrailers)
+                break;
+            inTrailers = true;
+            continue;
+        }
+        if (inTrailers) {
+            const match = line.match(/^([A-Za-z][A-Za-z0-9-]*)\s*:\s*(.+)$/);
+            if (match) {
+                trailers[match[1]] = match[2];
+            }
+        }
+    }
+    return trailers;
+}
+/**
+ * Extract agent info from commit trailers
+ */
+export function extractAgentInfo(trailers) {
+    const agentId = trailers[GIT_TRAILERS.AGENT_ID];
+    const agentTypeStr = trailers[GIT_TRAILERS.AGENT_TYPE];
+    const sessionId = trailers[GIT_TRAILERS.SESSION_ID];
+    const agentName = trailers[GIT_TRAILERS.AGENT_NAME];
+    // Check for AI indicators
+    const isAiGenerated = !!agentId ||
+        !!agentTypeStr ||
+        Object.values(trailers).some((v) => v.toLowerCase().includes('ai') ||
+            v.toLowerCase().includes('claude') ||
+            v.toLowerCase().includes('copilot') ||
+            v.toLowerCase().includes('cursor'));
+    // Extract co-authors
+    const coAuthors = [];
+    for (const [key, value] of Object.entries(trailers)) {
+        if (key.toLowerCase() === 'co-authored-by') {
+            coAuthors.push(value);
+        }
+    }
+    return {
+        agentId,
+        agentType: agentTypeStr,
+        sessionId,
+        agentName,
+        isAiGenerated,
+        coAuthors,
+        trailers,
+    };
+}
+/**
+ * Get agent info from a specific commit
+ */
+export function getCommitAgentInfo(commitRef, cwd) {
+    try {
+        const message = execFileSync('git', ['log', '-1', '--format=%B', commitRef], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const trailers = parseCommitTrailers(message);
+        return extractAgentInfo(trailers);
+    }
+    catch (error) {
+        debug(`Failed to get commit agent info for ${commitRef}:`, error);
+        return null;
+    }
+}
+/**
+ * Get agent info from recent commits
+ */
+export function getRecentCommitsAgentInfo(count = 10, cwd) {
+    const results = [];
+    try {
+        const hashes = execFileSync('git', ['log', `-${count}`, '--format=%H'], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        })
+            .trim()
+            .split('\n');
+        for (const hash of hashes) {
+            const info = getCommitAgentInfo(hash, cwd);
+            if (info) {
+                results.push({ hash, info });
+            }
+        }
+    }
+    catch (error) {
+        debug('Failed to get recent commits:', error);
+    }
+    return results;
+}
+/**
+ * Format a commit message with agent identification trailers
+ */
+export function formatCommitWithAgent(options) {
+    const { message, agent = createAgentInfo(), includeCoAuthor = true, additionalTrailers = {}, } = options;
+    const trailers = [];
+    // Add agent trailers
+    trailers.push(`${GIT_TRAILERS.AGENT_ID}: ${agent.id}`);
+    trailers.push(`${GIT_TRAILERS.AGENT_TYPE}: ${agent.type}`);
+    if (agent.sessionId) {
+        trailers.push(`${GIT_TRAILERS.SESSION_ID}: ${agent.sessionId}`);
+    }
+    if (agent.name) {
+        trailers.push(`${GIT_TRAILERS.AGENT_NAME}: ${agent.name}`);
+    }
+    // Add co-authored-by for AI agents
+    if (includeCoAuthor && agent.type !== 'human') {
+        const coAuthorName = getAgentCoAuthorName(agent);
+        trailers.push(`${GIT_TRAILERS.CO_AUTHORED_BY}: ${coAuthorName}`);
+    }
+    // Add additional trailers
+    for (const [key, value] of Object.entries(additionalTrailers)) {
+        trailers.push(`${key}: ${value}`);
+    }
+    // Ensure message has proper spacing before trailers
+    const trimmedMessage = message.trimEnd();
+    const trailersBlock = trailers.join('\n');
+    // Check if message already has trailers
+    const existingTrailers = parseCommitTrailers(trimmedMessage);
+    const hasExistingTrailers = Object.keys(existingTrailers).length > 0;
+    if (hasExistingTrailers) {
+        // Append to existing trailers
+        return `${trimmedMessage}\n${trailersBlock}`;
+    }
+    // Add blank line before trailers
+    return `${trimmedMessage}\n\n${trailersBlock}`;
+}
+/**
+ * Get co-author name for an agent
+ */
+function getAgentCoAuthorName(agent) {
+    switch (agent.type) {
+        case 'claude':
+            return 'Claude <claude@anthropic.com>';
+        case 'cursor':
+            return 'Cursor AI <ai@cursor.sh>';
+        case 'copilot':
+            return 'GitHub Copilot <copilot@github.com>';
+        case 'aider':
+            return 'Aider <aider@aider.chat>';
+        case 'continue':
+            return 'Continue <ai@continue.dev>';
+        case 'codeium':
+            return 'Codeium <ai@codeium.com>';
+        default:
+            return `AI Agent (${agent.id}) <noreply@example.com>`;
+    }
+}
+// ============================================================================
+// Git Hook Helpers
+// ============================================================================
+/**
+ * Prepare commit message hook helper
+ *
+ * Automatically adds agent trailers to commit messages.
+ * Can be used in a prepare-commit-msg hook.
+ */
+export function prepareCommitMsgHook(commitMsgFile, commitSource, _sha1) {
+    // Only modify non-merge, non-squash commits
+    if (commitSource === 'merge' || commitSource === 'squash') {
+        return;
+    }
+    // Read original message
+    const originalMessage = readFileSync(commitMsgFile, 'utf-8');
+    // Check if already has agent trailers
+    const trailers = parseCommitTrailers(originalMessage);
+    if (trailers[GIT_TRAILERS.AGENT_ID]) {
+        return; // Already has agent info
+    }
+    // Add agent info
+    const agent = createAgentInfo();
+    // Only add for AI agents
+    if (agent.type === 'human' || agent.type === 'unknown') {
+        return;
+    }
+    const modifiedMessage = formatCommitWithAgent({
+        message: originalMessage,
+        agent,
+    });
+    writeFileSync(commitMsgFile, modifiedMessage);
+}
+/**
+ * Generate a git config command to set up the prepare-commit-msg hook
+ */
+export function getHookSetupCommand() {
+    return `
+# Add to .git/hooks/prepare-commit-msg:
+#!/bin/sh
+COMMIT_MSG_FILE=$1
+COMMIT_SOURCE=$2
+SHA1=$3
+
+# Run the prepare-commit-msg hook via the runtime module
+if command -v node &> /dev/null; then
+  node -e "
+    import('${`@eddacraft/anvil-runtime/concurrency`}')
+      .then(m => m.prepareCommitMsgHook('$COMMIT_MSG_FILE', '$COMMIT_SOURCE', '$SHA1'))
+      .catch(() => {});
+  "
+fi
+`.trim();
+}
+/**
+ * Get contribution summary by agent
+ */
+export function getAgentContributions(sinceRef, cwd) {
+    const contributions = new Map();
+    try {
+        const args = ['log'];
+        if (sinceRef)
+            args.push(`${sinceRef}..HEAD`);
+        args.push('--format=%H|%aI');
+        const output = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!output)
+            return contributions;
+        const lines = output.split('\n');
+        for (const line of lines) {
+            const [hash, timestamp] = line.split('|');
+            const info = getCommitAgentInfo(hash, cwd);
+            if (!info?.agentId)
+                continue;
+            const existing = contributions.get(info.agentId);
+            if (existing) {
+                existing.commitCount++;
+                if (timestamp < existing.firstCommit) {
+                    existing.firstCommit = timestamp;
+                }
+                if (timestamp > existing.lastCommit) {
+                    existing.lastCommit = timestamp;
+                }
+            }
+            else {
+                contributions.set(info.agentId, {
+                    agentId: info.agentId,
+                    agentType: info.agentType ?? 'unknown',
+                    commitCount: 1,
+                    firstCommit: timestamp,
+                    lastCommit: timestamp,
+                });
+            }
+        }
+    }
+    catch (error) {
+        debug('Failed to get agent contributions:', error);
+    }
+    return contributions;
+}
+/**
+ * Get percentage of AI-generated commits in a range
+ */
+export function getAiCommitPercentage(sinceRef, cwd) {
+    try {
+        const revListArgs = ['rev-list', '--count'];
+        revListArgs.push(sinceRef ? `${sinceRef}..HEAD` : 'HEAD');
+        const totalCount = parseInt(execFileSync('git', revListArgs, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim(), 10);
+        if (totalCount === 0)
+            return 0;
+        const commits = getRecentCommitsAgentInfo(totalCount, cwd);
+        const aiCount = commits.filter((c) => c.info.isAiGenerated).length;
+        return (aiCount / totalCount) * 100;
+    }
+    catch (error) {
+        debug('Failed to calculate AI commit percentage:', error);
+        return 0;
+    }
+}

package/dist/concurrency/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Multi-Agent Concurrency Module
+ *
+ * Provides coordination primitives for multi-agent development scenarios:
+ * - Agent identification and registration
+ * - File-based distributed locking
+ * - Fair request queuing
+ * - Git agent attribution
+ * - Atomic file operations
+ *
+ * @module @eddacraft/anvil-runtime/concurrency
+ */
+export * from './types.js';
+export { atomicWriteJson, atomicWriteText, readJsonSafe, readJsonWithRetry, acquireFileLock, tryAcquireFileLock, isLocked, forceReleaseLock, unlinkSafe, fileExists, getFileMtime, sleepWithJitter, type AtomicWriteOptions, type FileLockOptions, type FileLockHandle, } from './atomic.js';
+export { AgentManager, createAgentManager, initializeGlobalAgent, getGlobalAgent, detectAgentType, getAgentId, getSessionId, getAgentName, createAgentInfo, type AgentManagerOptions, } from './agent.js';
+export { LockManager, createLockManager, withLock, tryWithLock, type LockManagerOptions, type AcquireLockOptions, } from './lock-manager.js';
+export { QueueManager, createQueueManager, coordinatedExecution, withConcurrencyLimit, type QueueManagerOptions, type QueueJoinOptions, type QueueWaitOptions, type ConcurrentGroupResult, } from './queue-manager.js';
+export { GIT_TRAILERS, parseCommitTrailers, extractAgentInfo, getCommitAgentInfo, getRecentCommitsAgentInfo, formatCommitWithAgent, prepareCommitMsgHook, getHookSetupCommand, getAgentContributions, getAiCommitPercentage, type CommitAgentInfo, type FormatCommitOptions, type AgentContributionSummary, } from './git-agent.js';
+import { AgentManager } from './agent.js';
+import { LockManager, type LockManagerOptions } from './lock-manager.js';
+import { QueueManager } from './queue-manager.js';
+import type { ConcurrencyConfig, AgentInfo } from './types.js';
+/**
+ * Options for creating a full concurrency context
+ */
+export interface ConcurrencyContextOptions {
+    /** Workspace root directory */
+    workspaceRoot: string;
+    /** Concurrency configuration */
+    config?: Partial<ConcurrencyConfig>;
+    /** Agent info (auto-detected if not provided) */
+    agentInfo?: AgentInfo;
+    /** Whether to auto-register agent */
+    autoRegister?: boolean;
+    /** Whether to auto-start heartbeat */
+    autoHeartbeat?: boolean;
+}
+/**
+ * Full concurrency context with all managers
+ */
+export interface ConcurrencyContext {
+    /** Agent manager */
+    agent: AgentManager;
+    /** Lock manager */
+    locks: LockManager;
+    /** Queue manager */
+    queue: QueueManager;
+    /** Configuration */
+    config: ConcurrencyConfig;
+    /** Cleanup function */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a full concurrency context
+ *
+ * This is the main entry point for multi-agent coordination.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createConcurrencyContext({
+ *   workspaceRoot: process.cwd(),
+ *   autoRegister: true,
+ *   autoHeartbeat: true,
+ * });
+ *
+ * try {
+ *   // Wait for lock with fair queuing
+ *   const result = await ctx.queue.waitForLock({
+ *     type: 'action',
+ *     resource: 'gate',
+ *     reason: 'Running quality gates',
+ *   });
+ *
+ *   if (result.acquired) {
+ *     // Perform work
+ *     await runGates();
+ *
+ *     // Lock is automatically released when leaving queue
+ *   }
+ * } finally {
+ *   await ctx.cleanup();
+ * }
+ * ```
+ */
+export declare function createConcurrencyContext(options: ConcurrencyContextOptions): Promise<ConcurrencyContext>;
+/**
+ * Create a simple lock-only context (without queuing)
+ *
+ * Use when you just need basic locking without fair queuing.
+ */
+export declare function createSimpleLockContext(options: LockManagerOptions): {
+    locks: LockManager;
+    cleanup: () => Promise<void>;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/concurrency/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,eAAe,EACf,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAqB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IAEtB,gCAAgC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEpC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,sCAAsC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,KAAK,EAAE,YAAY,CAAC;IAEpB,mBAAmB;IACnB,KAAK,EAAE,WAAW,CAAC;IAEnB,oBAAoB;IACpB,KAAK,EAAE,YAAY,CAAC;IAEpB,oBAAoB;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAE1B,uBAAuB;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CA8D7B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG;IACpE,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAUA"}

package/dist/concurrency/index.js

@@ -0,0 +1,127 @@
+/**
+ * Multi-Agent Concurrency Module
+ *
+ * Provides coordination primitives for multi-agent development scenarios:
+ * - Agent identification and registration
+ * - File-based distributed locking
+ * - Fair request queuing
+ * - Git agent attribution
+ * - Atomic file operations
+ *
+ * @module @eddacraft/anvil-runtime/concurrency
+ */
+// Types
+export * from './types.js';
+// Atomic file operations
+export { atomicWriteJson, atomicWriteText, readJsonSafe, readJsonWithRetry, acquireFileLock, tryAcquireFileLock, isLocked, forceReleaseLock, unlinkSafe, fileExists, getFileMtime, sleepWithJitter, } from './atomic.js';
+// Agent management
+export { AgentManager, createAgentManager, initializeGlobalAgent, getGlobalAgent, detectAgentType, getAgentId, getSessionId, getAgentName, createAgentInfo, } from './agent.js';
+// Lock management
+export { LockManager, createLockManager, withLock, tryWithLock, } from './lock-manager.js';
+// Queue management
+export { QueueManager, createQueueManager, coordinatedExecution, withConcurrencyLimit, } from './queue-manager.js';
+// Git agent identification
+export { GIT_TRAILERS, parseCommitTrailers, extractAgentInfo, getCommitAgentInfo, getRecentCommitsAgentInfo, formatCommitWithAgent, prepareCommitMsgHook, getHookSetupCommand, getAgentContributions, getAiCommitPercentage, } from './git-agent.js';
+// ============================================================================
+// High-Level Convenience Functions
+// ============================================================================
+import { createAgentManager } from './agent.js';
+import { createLockManager } from './lock-manager.js';
+import { createQueueManager } from './queue-manager.js';
+import { getDefaultConcurrencyConfig } from './types.js';
+/**
+ * Create a full concurrency context
+ *
+ * This is the main entry point for multi-agent coordination.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createConcurrencyContext({
+ *   workspaceRoot: process.cwd(),
+ *   autoRegister: true,
+ *   autoHeartbeat: true,
+ * });
+ *
+ * try {
+ *   // Wait for lock with fair queuing
+ *   const result = await ctx.queue.waitForLock({
+ *     type: 'action',
+ *     resource: 'gate',
+ *     reason: 'Running quality gates',
+ *   });
+ *
+ *   if (result.acquired) {
+ *     // Perform work
+ *     await runGates();
+ *
+ *     // Lock is automatically released when leaving queue
+ *   }
+ * } finally {
+ *   await ctx.cleanup();
+ * }
+ * ```
+ */
+export async function createConcurrencyContext(options) {
+    const { workspaceRoot, config: configOverrides, agentInfo, autoRegister = true, autoHeartbeat = true, } = options;
+    const config = {
+        ...getDefaultConcurrencyConfig(),
+        ...configOverrides,
+    };
+    // Create agent manager
+    const agent = createAgentManager({
+        workspaceRoot,
+        config,
+        agentInfo,
+    });
+    // Create lock manager with same agent
+    const locks = createLockManager({
+        workspaceRoot,
+        config,
+        agentInfo: agent.getAgent(),
+    });
+    // Create queue manager with same lock manager
+    const queue = createQueueManager({
+        workspaceRoot,
+        config,
+        agentInfo: agent.getAgent(),
+        lockManager: locks,
+    });
+    // Auto-register and start heartbeat
+    if (autoRegister) {
+        await agent.register('initializing');
+    }
+    if (autoHeartbeat) {
+        agent.startHeartbeat();
+    }
+    // Cleanup function
+    const cleanup = async () => {
+        agent.stopHeartbeat();
+        locks.stopAllRenewals();
+        await locks.releaseAll();
+        if (autoRegister) {
+            await agent.unregister();
+        }
+    };
+    return {
+        agent,
+        locks,
+        queue,
+        config,
+        cleanup,
+    };
+}
+/**
+ * Create a simple lock-only context (without queuing)
+ *
+ * Use when you just need basic locking without fair queuing.
+ */
+export function createSimpleLockContext(options) {
+    const locks = createLockManager(options);
+    return {
+        locks,
+        cleanup: async () => {
+            locks.stopAllRenewals();
+            await locks.releaseAll();
+        },
+    };
+}