@zoebuildsai/trace 1.5.0

package/src/agent-checkout.ts

@@ -0,0 +1,227 @@
+/**
+ * Agent Checkout System for Trace
+ * Restore working directory to specific commit (like git checkout)
+ */
+
+import { Commit } from './commit-hash-system';
+
+export interface CheckoutResult {
+  success: boolean;
+  hash: string;
+  filesRestored: string[];
+  filesRemoved: string[];
+  message: string;
+  timestamp: number;
+}
+
+export interface WorkingDirectory {
+  currentHash: string;
+  currentCommit?: Commit;
+  files: Map<string, string>;
+  dirty: boolean;
+  timestamp: number;
+}
+
+export class AgentCheckout {
+  private workingDirectory: WorkingDirectory;
+  private checkoutHistory: CheckoutResult[] = [];
+
+  constructor() {
+    this.workingDirectory = {
+      currentHash: '',
+      files: new Map(),
+      dirty: false,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Checkout commit (restore working directory)
+   */
+  checkout(commit: Commit, force: boolean = false): CheckoutResult {
+    // Check for uncommitted changes
+    if (this.workingDirectory.dirty && !force) {
+      throw new Error(
+        `Working directory has uncommitted changes. Use force=true to discard.`
+      );
+    }
+
+    const filesRestored: string[] = [];
+    const filesRemoved: string[] = [];
+    const oldFiles = new Map(this.workingDirectory.files);
+
+    // Apply new files
+    this.workingDirectory.files.clear();
+    for (const [path, content] of commit.files) {
+      this.workingDirectory.files.set(path, content);
+      if (!oldFiles.has(path)) {
+        filesRestored.push(path);
+      }
+    }
+
+    // Identify removed files
+    for (const path of oldFiles.keys()) {
+      if (!this.workingDirectory.files.has(path)) {
+        filesRemoved.push(path);
+      }
+    }
+
+    this.workingDirectory.currentHash = commit.hash.full;
+    this.workingDirectory.currentCommit = commit;
+    this.workingDirectory.dirty = false;
+    this.workingDirectory.timestamp = Date.now();
+
+    const result: CheckoutResult = {
+      success: true,
+      hash: commit.hash.full,
+      filesRestored,
+      filesRemoved,
+      message: `Checked out ${commit.hash.short}: ${commit.message}`,
+      timestamp: this.workingDirectory.timestamp,
+    };
+
+    this.checkoutHistory.push(result);
+    return result;
+  }
+
+  /**
+   * Checkout by hash (full or short)
+   */
+  checkoutByHash(
+    commits: Map<string, Commit>,
+    hash: string,
+    force: boolean = false
+  ): CheckoutResult {
+    let commit = commits.get(hash);
+
+    // Try short hash
+    if (!commit) {
+      for (const [fullHash, c] of commits) {
+        if (fullHash.startsWith(hash)) {
+          commit = c;
+          break;
+        }
+      }
+    }
+
+    if (!commit) {
+      throw new Error(`Commit ${hash} not found`);
+    }
+
+    return this.checkout(commit, force);
+  }
+
+  /**
+   * Get current working directory state
+   */
+  getWorkingDirectory(): WorkingDirectory {
+    return {
+      ...this.workingDirectory,
+      files: new Map(this.workingDirectory.files),
+    };
+  }
+
+  /**
+   * Get file at current commit
+   */
+  getFile(path: string): string | undefined {
+    return this.workingDirectory.files.get(path);
+  }
+
+  /**
+   * List all files in working directory
+   */
+  listFiles(): string[] {
+    return Array.from(this.workingDirectory.files.keys()).sort();
+  }
+
+  /**
+   * Check if working directory is clean
+   */
+  isClean(): boolean {
+    return !this.workingDirectory.dirty;
+  }
+
+  /**
+   * Mark working directory as dirty (files changed)
+   */
+  markDirty(): void {
+    this.workingDirectory.dirty = true;
+  }
+
+  /**
+   * Get checkout history
+   */
+  getCheckoutHistory(): CheckoutResult[] {
+    return [...this.checkoutHistory];
+  }
+
+  /**
+   * Get current commit
+   */
+  getCurrentCommit(): Commit | undefined {
+    return this.workingDirectory.currentCommit;
+  }
+
+  /**
+   * Get current hash
+   */
+  getCurrentHash(): string {
+    return this.workingDirectory.currentHash;
+  }
+
+  /**
+   * Diff between current and another commit
+   */
+  diffWithCommit(otherCommit: Commit): {
+    added: string[];
+    removed: string[];
+    modified: string[];
+  } {
+    const added: string[] = [];
+    const removed: string[] = [];
+    const modified: string[] = [];
+
+    // Find added/modified files
+    for (const [path, content] of otherCommit.files) {
+      if (!this.workingDirectory.files.has(path)) {
+        added.push(path);
+      } else if (this.workingDirectory.files.get(path) !== content) {
+        modified.push(path);
+      }
+    }
+
+    // Find removed files
+    for (const path of this.workingDirectory.files.keys()) {
+      if (!otherCommit.files.has(path)) {
+        removed.push(path);
+      }
+    }
+
+    return { added, removed, modified };
+  }
+
+  /**
+   * Reset to specific file version from commit
+   */
+  restoreFile(path: string, commit: Commit): boolean {
+    if (!commit.files.has(path)) {
+      return false;
+    }
+
+    this.workingDirectory.files.set(path, commit.files.get(path)!);
+    return true;
+  }
+
+  /**
+   * Restore all files from commit
+   */
+  restoreAll(commit: Commit): void {
+    this.workingDirectory.files.clear();
+    for (const [path, content] of commit.files) {
+      this.workingDirectory.files.set(path, content);
+    }
+  }
+}
+
+export default AgentCheckout;

package/src/agent-coordination.ts

@@ -0,0 +1,318 @@
+/**
+ * Agent Coordination Layer
+ * The REAL value proposition: prevent agents from stepping on each other
+ * This is what git doesn't solve
+ */
+
+export interface AgentTask {
+  taskId: string;
+  agent: string;
+  files: string[]; // Files this task will modify
+  priority: number; // Higher = goes first
+  status: 'pending' | 'assigned' | 'executing' | 'completed' | 'blocked';
+  assignedAt?: number;
+  completedAt?: number;
+  blockedBy?: string[]; // Other task IDs blocking this
+}
+
+export interface CoordinationPolicy {
+  allowParallel: boolean; // Can tasks run in parallel?
+  maxConcurrent: number; // How many tasks at once?
+  lockTimeout: number; // How long to hold lock before auto-release?
+  conflictStrategy: 'block' | 'queue' | 'merge';
+}
+
+export class AgentCoordination {
+  private tasks: Map<string, AgentTask> = new Map();
+  private fileLocks: Map<string, string> = new Map(); // file -> agentId
+  private policy: CoordinationPolicy;
+
+  constructor(policy: Partial<CoordinationPolicy> = {}) {
+    this.policy = {
+      allowParallel: true,
+      maxConcurrent: 10,
+      lockTimeout: 5 * 60 * 1000, // 5 minutes
+      conflictStrategy: 'block',
+      ...policy,
+    };
+  }
+
+  /**
+   * Register a task from an agent
+   * Returns whether task can start immediately or is blocked
+   */
+  registerTask(agent: string, files: string[], priority: number = 0): {
+    taskId: string;
+    canStart: boolean;
+    blockedBy?: string[];
+  } {
+    const taskId = `task-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+    const task: AgentTask = {
+      taskId,
+      agent,
+      files,
+      priority,
+      status: 'pending',
+      assignedAt: Date.now(),
+    };
+
+    // Check for conflicts
+    const conflicts = this.detectConflicts(agent, files);
+
+    if (conflicts.length > 0) {
+      if (this.policy.conflictStrategy === 'block') {
+        task.status = 'blocked';
+        task.blockedBy = conflicts;
+        this.tasks.set(taskId, task);
+        return { taskId, canStart: false, blockedBy: conflicts };
+      }
+    }
+
+    task.status = 'executing';
+    this.tasks.set(taskId, task);
+    return { taskId, canStart: true };
+  }
+
+  /**
+   * Detect if agent's files conflict with existing tasks
+   */
+  private detectConflicts(agent: string, files: string[]): string[] {
+    const conflicts: string[] = [];
+
+    for (const task of this.tasks.values()) {
+      if (task.agent === agent || task.status === 'completed') {
+        continue; // Same agent or finished task
+      }
+
+      // Check if any files overlap
+      const overlap = task.files.some(f => files.includes(f));
+      if (overlap) {
+        conflicts.push(task.taskId);
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * Request lock on a file for exclusive access
+   */
+  requestLock(file: string, agent: string): {
+    locked: boolean;
+    owner?: string;
+    waitTime?: number;
+  } {
+    // Check if already locked by someone else
+    const owner = this.fileLocks.get(file);
+
+    if (owner && owner !== agent) {
+      return { locked: false, owner };
+    }
+
+    // Lock it
+    this.fileLocks.set(file, agent);
+    return { locked: true };
+  }
+
+  /**
+   * Release lock
+   */
+  releaseLock(file: string, agent: string): boolean {
+    const owner = this.fileLocks.get(file);
+    if (owner !== agent) {
+      return false; // Not the owner
+    }
+
+    this.fileLocks.delete(file);
+    return true;
+  }
+
+  /**
+   * Check what tasks are blocked and why
+   */
+  getBlockedTasks(): Array<{ taskId: string; agent: string; blockedBy: string[] }> {
+    const blocked: Array<{ taskId: string; agent: string; blockedBy: string[] }> = [];
+
+    for (const task of this.tasks.values()) {
+      if (task.status === 'blocked' && task.blockedBy) {
+        blocked.push({
+          taskId: task.taskId,
+          agent: task.agent,
+          blockedBy: task.blockedBy,
+        });
+      }
+    }
+
+    return blocked;
+  }
+
+  /**
+   * Get current lock holder for file
+   */
+  getLockHolder(file: string): string | undefined {
+    return this.fileLocks.get(file);
+  }
+
+  /**
+   * Complete task and auto-unblock dependent tasks
+   */
+  completeTask(taskId: string): {
+    success: boolean;
+    unblocked: string[];
+  } {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      return { success: false, unblocked: [] };
+    }
+
+    task.status = 'completed';
+    task.completedAt = Date.now();
+
+    // Release locks
+    for (const file of task.files) {
+      this.releaseLock(file, task.agent);
+    }
+
+    // Find blocked tasks and try to unblock
+    const unblocked: string[] = [];
+    for (const otherTask of this.tasks.values()) {
+      if (otherTask.status === 'blocked' && otherTask.blockedBy?.includes(taskId)) {
+        const newBlockers = (otherTask.blockedBy || []).filter(b => b !== taskId);
+
+        if (newBlockers.length === 0) {
+          otherTask.status = 'executing';
+          unblocked.push(otherTask.taskId);
+        } else {
+          otherTask.blockedBy = newBlockers;
+        }
+      }
+    }
+
+    return { success: true, unblocked };
+  }
+
+  /**
+   * Get task status
+   */
+  getTaskStatus(taskId: string): AgentTask | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  /**
+   * Get all active tasks for agent
+   */
+  getAgentTasks(agent: string): AgentTask[] {
+    return Array.from(this.tasks.values()).filter(t => t.agent === agent);
+  }
+
+  /**
+   * Get coordination statistics
+   */
+  getStats(): {
+    totalTasks: number;
+    executing: number;
+    blocked: number;
+    completed: number;
+    currentLocks: number;
+    avgWaitTime: number;
+  } {
+    let executing = 0;
+    let blocked = 0;
+    let completed = 0;
+    let totalWait = 0;
+
+    for (const task of this.tasks.values()) {
+      switch (task.status) {
+        case 'executing':
+          executing++;
+          break;
+        case 'blocked':
+          blocked++;
+          if (task.assignedAt) {
+            totalWait += Date.now() - task.assignedAt;
+          }
+          break;
+        case 'completed':
+          completed++;
+          break;
+      }
+    }
+
+    return {
+      totalTasks: this.tasks.size,
+      executing,
+      blocked,
+      completed,
+      currentLocks: this.fileLocks.size,
+      avgWaitTime: blocked > 0 ? Math.round(totalWait / blocked) : 0,
+    };
+  }
+
+  /**
+   * Suggest optimal task ordering
+   */
+  suggestOrder(): string[] {
+    // Sort by priority, then by dependencies
+    return Array.from(this.tasks.values())
+      .filter(t => t.status !== 'completed')
+      .sort((a, b) => {
+        // Higher priority first
+        if (b.priority !== a.priority) {
+          return b.priority - a.priority;
+        }
+        // Blocked tasks last
+        if ((a.blockedBy?.length || 0) !== (b.blockedBy?.length || 0)) {
+          return (a.blockedBy?.length || 0) - (b.blockedBy?.length || 0);
+        }
+        // Older first
+        return (a.assignedAt || 0) - (b.assignedAt || 0);
+      })
+      .map(t => t.taskId);
+  }
+
+  /**
+   * Set coordination policy
+   */
+  setPolicy(policy: Partial<CoordinationPolicy>): void {
+    this.policy = { ...this.policy, ...policy };
+  }
+
+  /**
+   * Get coordination policy
+   */
+  getPolicy(): CoordinationPolicy {
+    return { ...this.policy };
+  }
+
+  /**
+   * Format coordination state for display
+   */
+  formatState(): string {
+    const stats = this.getStats();
+    let output = `\n🔀 AGENT COORDINATION STATE\n`;
+    output += `Tasks: ${stats.totalTasks} total (executing: ${stats.executing}, blocked: ${stats.blocked}, done: ${stats.completed})\n`;
+    output += `File Locks: ${stats.currentLocks}\n`;
+    output += `Avg Block Time: ${stats.avgWaitTime}ms\n\n`;
+
+    const blocked = this.getBlockedTasks();
+    if (blocked.length > 0) {
+      output += `BLOCKED TASKS:\n`;
+      for (const task of blocked) {
+        output += `  ${task.taskId} (agent: ${task.agent}) blocked by ${task.blockedBy.join(', ')}\n`;
+      }
+    }
+
+    return output;
+  }
+
+  /**
+   * Clear all state (for testing)
+   */
+  clear(): void {
+    this.tasks.clear();
+    this.fileLocks.clear();
+  }
+}
+
+export default AgentCoordination;