@zoebuildsai/trace 1.5.0

package/src/async-queue.ts

@@ -0,0 +1,203 @@
+/**
+ * Async Queue for Trace
+ * Enables batch commits without blocking agent execution
+ */
+
+export interface QueuedOperation {
+  id: string;
+  type: 'commit' | 'push' | 'pull';
+  payload: Record<string, unknown>;
+  timestamp: number;
+  status: 'pending' | 'executing' | 'completed' | 'failed';
+  error?: string;
+  result?: unknown;
+  webhooks?: string[]; // URLs to notify on completion
+}
+
+export class AsyncQueue {
+  private queue: QueuedOperation[] = [];
+  private executing = false;
+  private concurrency = 3; // Run up to 3 operations in parallel
+
+  /**
+   * Enqueue an operation
+   */
+  enqueue(operation: Omit<QueuedOperation, 'id' | 'timestamp' | 'status'>): string {
+    const id = `op-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const queued: QueuedOperation = {
+      ...operation,
+      id,
+      timestamp: Date.now(),
+      status: 'pending',
+    };
+    this.queue.push(queued);
+    this.process(); // Start processing if not already running
+    return id;
+  }
+
+  /**
+   * Get operation status
+   */
+  getStatus(id: string): QueuedOperation | undefined {
+    return this.queue.find(op => op.id === id);
+  }
+
+  /**
+   * Process queue (async, non-blocking)
+   */
+  private async process(): Promise<void> {
+    if (this.executing) return;
+    this.executing = true;
+
+    while (this.queue.length > 0) {
+      const batch = this.queue
+        .filter(op => op.status === 'pending')
+        .slice(0, this.concurrency);
+
+      if (batch.length === 0) break;
+
+      // Mark as executing
+      batch.forEach(op => { op.status = 'executing'; });
+
+      // Execute in parallel
+      const results = await Promise.allSettled(
+        batch.map(op => this.executeOperation(op))
+      );
+
+      // Update statuses
+      batch.forEach((op, index) => {
+        const result = results[index];
+        if (result.status === 'fulfilled') {
+          op.status = 'completed';
+          op.result = result.value;
+          this.notifyWebhooks(op);
+        } else {
+          op.status = 'failed';
+          op.error = String(result.reason);
+          this.notifyWebhooks(op);
+        }
+      });
+    }
+
+    this.executing = false;
+  }
+
+  /**
+   * Execute a single operation (stub - to be implemented)
+   */
+  private async executeOperation(op: QueuedOperation): Promise<unknown> {
+    // Implementation would go here
+    return { success: true };
+  }
+
+  /**
+   * Notify webhooks safely
+   */
+  private async notifyWebhooks(op: QueuedOperation): Promise<void> {
+    if (!op.webhooks || op.webhooks.length === 0) return;
+
+    for (const url of op.webhooks) {
+      try {
+        // Validate URL
+        if (!this.isValidUrl(url)) {
+          console.warn(`Invalid webhook URL: ${url}`);
+          continue;
+        }
+
+        // Sanitize payload (remove secrets)
+        const payload = this.sanitizePayload({
+          operationId: op.id,
+          type: op.type,
+          status: op.status,
+          timestamp: op.timestamp,
+          error: op.error,
+          // result is intentionally excluded to avoid leaking data
+        });
+
+        // Send webhook with retries
+        await this.sendWebhookWithRetry(url, payload, 3);
+      } catch (err) {
+        console.error(`Failed to notify webhook ${url}:`, err);
+      }
+    }
+  }
+
+  /**
+   * Send webhook with retry logic
+   */
+  private async sendWebhookWithRetry(
+    url: string,
+    payload: unknown,
+    maxRetries: number
+  ): Promise<void> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        // Note: In real implementation, would use fetch or similar
+        // For now, this is a stub that would call the webhook
+        await this.postWebhook(url, payload);
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+
+    throw lastError || new Error('Failed to send webhook after retries');
+  }
+
+  /**
+   * Post to webhook (stub)
+   */
+  private async postWebhook(url: string, payload: unknown): Promise<void> {
+    // Stub - would use fetch in real implementation
+  }
+
+  /**
+   * Validate webhook URL
+   */
+  private isValidUrl(url: string): boolean {
+    try {
+      const parsed = new URL(url);
+      // Only allow https for security
+      if (parsed.protocol !== 'https:') return false;
+      // Reject localhost in production
+      if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Sanitize payload to remove secrets
+   */
+  private sanitizePayload(payload: Record<string, unknown>): Record<string, unknown> {
+    const sanitized = { ...payload };
+    // Remove any fields that might contain secrets
+    const secretFields = ['password', 'token', 'secret', 'key', 'apiKey'];
+    for (const field of secretFields) {
+      delete sanitized[field];
+    }
+    return sanitized;
+  }
+
+  /**
+   * Get queue stats
+   */
+  getStats() {
+    return {
+      total: this.queue.length,
+      pending: this.queue.filter(op => op.status === 'pending').length,
+      executing: this.queue.filter(op => op.status === 'executing').length,
+      completed: this.queue.filter(op => op.status === 'completed').length,
+      failed: this.queue.filter(op => op.status === 'failed').length,
+    };
+  }
+}
+
+export default AsyncQueue;

package/src/auto-branching.ts

@@ -0,0 +1,279 @@
+/**
+ * Auto-Branching for Trace
+ * Automatically create & manage agent-per-task branches
+ */
+
+export interface BranchInfo {
+  name: string;
+  agent: string;
+  task: string;
+  created: number;
+  lastModified: number;
+  headCommit: string;
+  parentBranch: string;
+  isActive: boolean;
+}
+
+export interface BranchStats {
+  totalBranches: number;
+  activeBranches: number;
+  commitsByBranch: Map<string, number>;
+  oldestBranch: BranchInfo | undefined;
+  newestBranch: BranchInfo | undefined;
+}
+
+export class AutoBranching {
+  private branches: Map<string, BranchInfo> = new Map();
+  private taskAgentMap: Map<string, string> = new Map(); // task -> agent
+  private agentBranches: Map<string, string[]> = new Map(); // agent -> [branches]
+  private commitCounts: Map<string, number> = new Map(); // branch -> commit count
+
+  /**
+   * Create branch for agent task
+   */
+  createBranchForTask(
+    agent: string,
+    task: string,
+    parentBranch: string = 'main',
+    headCommit: string = ''
+  ): BranchInfo {
+    // Normalize branch name: agent-task format
+    const branchName = `${agent}/${task}`.toLowerCase().replace(/\s+/g, '-');
+
+    if (this.branches.has(branchName)) {
+      throw new Error(`Branch ${branchName} already exists`);
+    }
+
+    const branch: BranchInfo = {
+      name: branchName,
+      agent,
+      task,
+      created: Date.now(),
+      lastModified: Date.now(),
+      headCommit,
+      parentBranch,
+      isActive: true,
+    };
+
+    this.branches.set(branchName, branch);
+    this.taskAgentMap.set(task, agent);
+
+    if (!this.agentBranches.has(agent)) {
+      this.agentBranches.set(agent, []);
+    }
+    this.agentBranches.get(agent)!.push(branchName);
+    this.commitCounts.set(branchName, 0);
+
+    return branch;
+  }
+
+  /**
+   * Get or create branch for agent (auto-detect from context)
+   */
+  getOrCreateBranch(agent: string, task: string): BranchInfo {
+    const branchName = `${agent}/${task}`.toLowerCase().replace(/\s+/g, '-');
+    
+    if (this.branches.has(branchName)) {
+      return this.branches.get(branchName)!;
+    }
+
+    return this.createBranchForTask(agent, task);
+  }
+
+  /**
+   * Get branch by name
+   */
+  getBranch(name: string): BranchInfo | undefined {
+    return this.branches.get(name);
+  }
+
+  /**
+   * Get all branches for agent
+   */
+  getAgentBranches(agent: string): BranchInfo[] {
+    const branchNames = this.agentBranches.get(agent) || [];
+    return branchNames
+      .map(name => this.branches.get(name))
+      .filter((b): b is BranchInfo => b !== undefined);
+  }
+
+  /**
+   * List all branches
+   */
+  listBranches(activeOnly: boolean = false): BranchInfo[] {
+    const all = Array.from(this.branches.values());
+    if (activeOnly) {
+      return all.filter(b => b.isActive);
+    }
+    return all;
+  }
+
+  /**
+   * Record commit on branch
+   */
+  recordCommit(branchName: string, commitHash: string): void {
+    const branch = this.branches.get(branchName);
+    if (!branch) {
+      throw new Error(`Branch ${branchName} not found`);
+    }
+
+    branch.lastModified = Date.now();
+    branch.headCommit = commitHash;
+    const count = (this.commitCounts.get(branchName) || 0) + 1;
+    this.commitCounts.set(branchName, count);
+  }
+
+  /**
+   * Merge branch (mark complete, deactivate)
+   */
+  mergeBranch(branchName: string): BranchInfo {
+    const branch = this.branches.get(branchName);
+    if (!branch) {
+      throw new Error(`Branch ${branchName} not found`);
+    }
+
+    branch.isActive = false;
+    branch.lastModified = Date.now();
+
+    return branch;
+  }
+
+  /**
+   * Merge and delete branch
+   */
+  mergeBranchAndDelete(branchName: string): BranchInfo {
+    const branch = this.mergeBranch(branchName);
+    
+    // Remove from agent branches list
+    const agentBranches = this.agentBranches.get(branch.agent) || [];
+    this.agentBranches.set(
+      branch.agent,
+      agentBranches.filter(b => b !== branchName)
+    );
+
+    // Could optionally keep archived, or delete
+    // For now, keep for history
+    return branch;
+  }
+
+  /**
+   * Checkout branch (for agent)
+   */
+  checkoutBranch(branchName: string): BranchInfo {
+    const branch = this.branches.get(branchName);
+    if (!branch) {
+      throw new Error(`Branch ${branchName} not found`);
+    }
+
+    // In real implementation, would restore working directory
+    // to branch's head commit
+    return branch;
+  }
+
+  /**
+   * Get stats
+   */
+  getStats(): BranchStats {
+    const branches = Array.from(this.branches.values());
+    const activeBranches = branches.filter(b => b.isActive);
+    
+    const commitsByBranch = new Map<string, number>();
+    for (const [branchName, count] of this.commitCounts) {
+      commitsByBranch.set(branchName, count);
+    }
+
+    let oldest = branches[0];
+    let newest = branches[0];
+    for (const branch of branches) {
+      if (branch.created < (oldest?.created || Infinity)) oldest = branch;
+      if (branch.created > (newest?.created || 0)) newest = branch;
+    }
+
+    return {
+      totalBranches: branches.length,
+      activeBranches: activeBranches.length,
+      commitsByBranch,
+      oldestBranch: oldest,
+      newestBranch: newest,
+    };
+  }
+
+  /**
+   * Detect stale branches (no commits in N days)
+   */
+  detectStaleBranches(daysOld: number = 7): BranchInfo[] {
+    const threshold = Date.now() - daysOld * 24 * 60 * 60 * 1000;
+    return Array.from(this.branches.values()).filter(
+      b => b.isActive && b.lastModified < threshold
+    );
+  }
+
+  /**
+   * Get branch tree (parent-child relationships)
+   */
+  getBranchTree(): Map<string, BranchInfo[]> {
+    const tree = new Map<string, BranchInfo[]>();
+    
+    for (const branch of this.branches.values()) {
+      if (!tree.has(branch.parentBranch)) {
+        tree.set(branch.parentBranch, []);
+      }
+      tree.get(branch.parentBranch)!.push(branch);
+    }
+
+    return tree;
+  }
+
+  /**
+   * Format branch list for display
+   */
+  static formatBranchList(branches: BranchInfo[]): string {
+    if (branches.length === 0) {
+      return 'No branches found.';
+    }
+
+    let output = `\n📦 BRANCHES (${branches.length} total):\n`;
+    
+    for (const branch of branches.sort((a, b) => b.created - a.created)) {
+      const status = branch.isActive ? '✓' : '✗';
+      output += `${status} ${branch.name}\n`;
+      output += `   Agent: ${branch.agent} | Task: ${branch.task}\n`;
+      output += `   Head: ${branch.headCommit.substring(0, 7)} | Parent: ${branch.parentBranch}\n`;
+      output += `   Created: ${new Date(branch.created).toISOString()}\n`;
+    }
+
+    return output;
+  }
+
+  /**
+   * Rebase branch (move to new parent)
+   */
+  rebaseBranch(branchName: string, newParent: string): BranchInfo {
+    const branch = this.branches.get(branchName);
+    if (!branch) {
+      throw new Error(`Branch ${branchName} not found`);
+    }
+
+    const parentBranch = this.branches.get(newParent);
+    if (!parentBranch) {
+      throw new Error(`Parent branch ${newParent} not found`);
+    }
+
+    branch.parentBranch = newParent;
+    branch.lastModified = Date.now();
+
+    return branch;
+  }
+
+  /**
+   * Clear branch (for testing)
+   */
+  clearBranches(): void {
+    this.branches.clear();
+    this.taskAgentMap.clear();
+    this.agentBranches.clear();
+    this.commitCounts.clear();
+  }
+}
+
+export default AutoBranching;

package/src/auto-commit.ts

@@ -0,0 +1,166 @@
+/**
+ * Auto-Commit Feature
+ * 
+ * Watches memory directory for changes and auto-commits on a timer.
+ * - Polling-based change detection
+ * - Configurable interval (default 60s)
+ * - Skips if no changes detected
+ * - Batches rapid changes
+ * - Marks commits with [auto] prefix
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { TraceCommands } from './commands';
+
+export interface AutoCommitterOptions {
+  interval?: number; // milliseconds, default 60000
+  ignorePatterns?: string[];
+  workdir?: string;
+}
+
+export class AutoCommitter {
+  private commands: TraceCommands;
+  private interval: number = 60000; // default 60s
+  private isRunningFlag: boolean = false;
+  private watcher: fs.FSWatcher | null = null;
+  private lastCommitHash: string | null = null;
+  private changeQueue: Set<string> = new Set();
+  private ignorePatterns: string[] = ['node_modules', '.git', '.memory-git'];
+  private workdir: string;
+  private commitTimer: NodeJS.Timeout | null = null;
+  private lastSeenState: Map<string, number> = new Map();
+
+  constructor(commands: TraceCommands, workdir?: string) {
+    this.commands = commands;
+    this.workdir = workdir || process.cwd();
+  }
+
+  /**
+   * Start auto-commit watch
+   */
+  start(options: AutoCommitterOptions = {}): void {
+    if (this.isRunningFlag) return;
+
+    this.interval = options.interval || 60000;
+    if (options.ignorePatterns) {
+      this.ignorePatterns = options.ignorePatterns;
+    }
+
+    this.isRunningFlag = true;
+    this.setupWatcher();
+    this.scheduleCommit();
+  }
+
+  /**
+   * Stop auto-commit watch
+   */
+  stop(): void {
+    if (this.watcher) {
+      try {
+        this.watcher.close();
+      } catch (e) {
+        // Already closed
+      }
+      this.watcher = null;
+    }
+    if (this.commitTimer) {
+      clearTimeout(this.commitTimer);
+      this.commitTimer = null;
+    }
+    this.isRunningFlag = false;
+    this.changeQueue.clear();
+  }
+
+  /**
+   * Check if auto-committer is running
+   */
+  isRunning_(): boolean {
+    return this.isRunningFlag;
+  }
+
+  /**
+   * Get current interval in milliseconds
+   */
+  getInterval(): number {
+    return this.interval;
+  }
+
+  /**
+   * Set new interval
+   */
+  setInterval(ms: number): void {
+    this.interval = ms;
+    if (this.isRunningFlag) {
+      this.stop();
+      this.start({ interval: ms, ignorePatterns: this.ignorePatterns });
+    }
+  }
+
+  /**
+   * Private: Setup file system watcher
+   */
+  private setupWatcher(): void {
+    try {
+      this.watcher = fs.watch(this.workdir, { recursive: true }, (eventType, filename) => {
+        if (filename && !this.shouldIgnore(filename)) {
+          this.changeQueue.add(filename);
+        }
+      });
+    } catch (err) {
+      // fs.watch may fail on some systems; continue with polling only
+    }
+  }
+
+  /**
+   * Private: Schedule periodic commit check
+   */
+  private scheduleCommit(): void {
+    if (!this.isRunningFlag) return;
+
+    this.commitTimer = setTimeout(() => {
+      this.checkAndCommit();
+      this.scheduleCommit();
+    }, this.interval);
+  }
+
+  /**
+   * Private: Check for changes and commit if any
+   */
+  private checkAndCommit(): void {
+    try {
+      const status = this.commands.status();
+
+      // Skip if clean
+      if (status.clean) {
+        return;
+      }
+
+      // Count changed files
+      const totalChanges = (status.modified?.length || 0) +
+                          (status.added?.length || 0) +
+                          (status.deleted?.length || 0);
+
+      const message = `[auto] Memory snapshot (files: ${totalChanges})`;
+      const metadata = {
+        auto: true,
+        filesChanged: totalChanges,
+        timestamp: Date.now(),
+      };
+
+      this.lastCommitHash = this.commands.commit(message, 'agent', metadata);
+      this.changeQueue.clear();
+    } catch (err) {
+      // Log but don't throw
+    }
+  }
+
+  /**
+   * Private: Check if file should be ignored
+   */
+  private shouldIgnore(filename: string): boolean {
+    return this.ignorePatterns.some(pattern => {
+      return filename.includes(pattern);
+    });
+  }
+}