macro-agent 0.2.4 → 0.2.6

package/src/workspace/recovery/spawn-resolver.ts

@@ -1,152 +0,0 @@
-/**
- * `spawn-resolver` conflict recovery strategy.
- *
- * Async strategy that spawns a dedicated resolver agent on the conflicted
- * stream. The resolver reads conflict markers, resolves, commits, and calls
- * the `resolve_conflict` MCP tool — unblocking the original landing.
- *
- * Strategy config:
- * - `role`: string (default 'resolver') — role to spawn
- * - `max_concurrent`: number (default 2) — cap on simultaneous resolvers per stream
- * - `timeout_ms`: number (default 1,800,000 = 30 min) — fallback to escalate
- *
- * Unlike the other built-in strategies, this one requires an `AgentManager`
- * reference at construction time. Callers inject it via the factory. That's
- * why it's not in `buildBuiltinRecoveryRegistry()` — consumers register it
- * explicitly after constructing AgentManager.
- *
- * @module workspace/recovery/spawn-resolver
- * @see docs/conflict-recovery.md §4.3
- */
-
-import type { AgentManager } from '../../agent/agent-manager.js';
-import type { SpawnAgentOptions } from '../../agent/types.js';
-import type {
-  ConflictContext,
-  ConflictRecoveryStrategy,
-  ConflictResolution,
-} from './types.js';
-
-export interface SpawnResolverStrategyOptions {
-  agentManager: AgentManager;
-  /** Default role to spawn if not overridden in strategyConfig. */
-  defaultRole?: string;
-  /** Default timeout in ms. */
-  defaultTimeoutMs?: number;
-  /** Default concurrency cap per stream. */
-  defaultMaxConcurrent?: number;
-}
-
-export class SpawnResolverStrategy implements ConflictRecoveryStrategy {
-  readonly name = 'spawn-resolver';
-  readonly mode = 'async' as const;
-
-  // Tracks in-progress resolvers per stream to enforce max_concurrent.
-  private readonly activeByStream = new Map<string, Set<string>>();
-
-  constructor(private readonly opts: SpawnResolverStrategyOptions) {}
-
-  async recover(ctx: ConflictContext): Promise<ConflictResolution> {
-    const role =
-      (ctx.strategyConfig?.role as string | undefined) ??
-      this.opts.defaultRole ??
-      'resolver';
-    const timeoutMs =
-      (ctx.strategyConfig?.timeout_ms as number | undefined) ??
-      this.opts.defaultTimeoutMs ??
-      30 * 60 * 1000;
-    const maxConcurrent =
-      (ctx.strategyConfig?.max_concurrent as number | undefined) ??
-      this.opts.defaultMaxConcurrent ??
-      2;
-
-    // Concurrency cap
-    const active = this.activeByStream.get(ctx.streamId) ?? new Set();
-    if (active.size >= maxConcurrent) {
-      return {
-        kind: 'retry-after',
-        backoffMs: 30_000,
-        reason: `max concurrent resolvers (${maxConcurrent}) on stream ${ctx.streamId}`,
-      };
-    }
-
-    // Spawn the resolver. Injects MACRO_RECOVERY_STRATEGY + MACRO_CONFLICT_ID
-    // so the resolve_conflict MCP tool can tag the resolution correctly.
-    let resolverAgentId: string;
-    try {
-      const spawnOpts: SpawnAgentOptions = {
-        role,
-        task: `Resolve conflict ${ctx.conflictId} on stream ${ctx.streamId}`,
-        parent: ctx.landingAgentId,
-        capabilities: ['workspace.commit', 'workspace.resolve', 'workspace.read'],
-        config: {
-          env: {
-            MACRO_RECOVERY_STRATEGY: 'spawn-resolver',
-            MACRO_CONFLICT_ID: ctx.conflictId,
-          },
-        },
-      };
-      const spawned = await this.opts.agentManager.spawn(spawnOpts);
-      resolverAgentId = spawned.id;
-    } catch (err) {
-      return {
-        kind: 'failed',
-        error: `spawn-resolver: failed to spawn resolver — ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      };
-    }
-
-    active.add(resolverAgentId);
-    this.activeByStream.set(ctx.streamId, active);
-
-    // Wait for conflict.resolved event OR timeout. The resolver agent calls
-    // `resolve_conflict` MCP tool, which invokes workspaceManager.resolveConflict,
-    // which emits 'conflict:resolved' event.
-    try {
-      const resolution = await this.awaitResolution(ctx, timeoutMs);
-      return resolution;
-    } finally {
-      active.delete(resolverAgentId);
-      if (active.size === 0) this.activeByStream.delete(ctx.streamId);
-    }
-  }
-
-  private awaitResolution(
-    ctx: ConflictContext,
-    timeoutMs: number
-  ): Promise<ConflictResolution> {
-    return new Promise((resolve) => {
-      const unsubscribe = ctx.workspaceManager.onEvent((event) => {
-        if (
-          event.type === 'conflict:resolved' &&
-          event.data.conflictId === ctx.conflictId
-        ) {
-          clearTimeout(timer);
-          unsubscribe();
-          resolve({
-            kind: 'resolved',
-            resolutionCommit: (event.data.resolutionCommit as string) ?? 'unknown',
-          });
-        }
-      });
-
-      const timer = setTimeout(() => {
-        unsubscribe();
-        resolve({
-          kind: 'escalated',
-          escalatedTo: 'human',
-        });
-      }, timeoutMs);
-    });
-  }
-}
-
-/**
- * Factory for SpawnResolverStrategy — requires AgentManager.
- */
-export function createSpawnResolverStrategy(
-  opts: SpawnResolverStrategyOptions
-): SpawnResolverStrategy {
-  return new SpawnResolverStrategy(opts);
-}

package/src/workspace/recovery/types.ts

@@ -1,54 +0,0 @@
-/**
- * Conflict recovery types.
- *
- * Parallel to LandingStrategy. Dispatched from the agent's done() flow when
- * a landing returns a conflict. Registered globally; selected via per-role
- * YAML `on_conflict_recovery` or team default.
- *
- * @module workspace/recovery/types
- * @see docs/conflict-recovery.md
- */
-
-import type { AgentId, StreamId, Principal } from '../types-v3.js';
-import type { WorkspaceManager } from '../types.js';
-
-export interface ConflictContext {
-  conflictId: string;
-  streamId: StreamId;
-  sourceCommit?: string;
-  targetCommit?: string;
-  targetStreamId?: StreamId;
-  paths: string[];
-  operation: 'merge' | 'sync' | 'rebase' | 'cascade';
-  landingAgentId?: AgentId;
-  /**
-   * Worktree path where the conflict occurred. Required for
-   * `auto-resolve` and any other strategy that needs to replay git
-   * operations. Optional because some strategies (`defer`, `abandon`,
-   * `escalate`) don't need filesystem access.
-   */
-  worktree?: string;
-  recoveryDepth: number;
-  strategyConfig?: Record<string, unknown>;
-  workspaceManager: WorkspaceManager;
-}
-
-export type ConflictResolution =
-  | { kind: 'resolved'; resolutionCommit: string }
-  | { kind: 'deferred'; reason: string }
-  | { kind: 'abandoned'; streamId: StreamId; reason: string }
-  | { kind: 'escalated'; escalatedTo: Principal | 'human' }
-  | { kind: 'retry-after'; backoffMs: number; reason: string }
-  | { kind: 'failed'; error: string };
-
-export type ConflictResolutionMode = 'sync' | 'async';
-
-export interface ConflictRecoveryStrategy {
-  readonly name: string;
-  readonly mode: ConflictResolutionMode;
-
-  canHandle?(ctx: ConflictContext): boolean;
-  recover(ctx: ConflictContext): Promise<ConflictResolution>;
-  initialize?(): Promise<void>;
-  close?(): Promise<void>;
-}

package/src/workspace/strategies/index.ts

@@ -1,18 +0,0 @@
-export type {
-  IntegrationStrategy,
-  IntegrationStrategyFactory,
-  LandRequest,
-  LandResult,
-  LandResultStatus,
-  QueueStrategyConfig,
-  TrunkStrategyConfig,
-  OptimisticStrategyConfig,
-} from "./types.js";
-export { QueueIntegrationStrategy } from "./queue.js";
-export { TrunkIntegrationStrategy } from "./trunk.js";
-export { OptimisticIntegrationStrategy } from "./optimistic.js";
-export {
-  IntegrationStrategyRegistry,
-  createDefaultStrategyRegistry,
-  defaultStrategyRegistry,
-} from "./registry.js";

package/src/workspace/strategies/optimistic.ts

@@ -1,139 +0,0 @@
-/**
- * Optimistic Integration Strategy
- *
- * Push immediately and emit a validation event. Does NOT run build/test —
- * validation is the judge agent's responsibility (RD5).
- *
- * Uses the same rebase-and-retry logic as trunk for handling push conflicts.
- *
- * @module workspace/strategies/optimistic
- */
-
-import { execSync } from "child_process";
-import type {
-  IntegrationStrategy,
-  LandRequest,
-  LandResult,
-  OptimisticStrategyConfig,
-} from "./types.js";
-/** Minimal event store interface for emitting validation events */
-interface ValidationEventEmitter {
-  emit(event: { type: string; source: { agent_id: string }; payload: Record<string, unknown> }): void;
-}
-
-export class OptimisticIntegrationStrategy implements IntegrationStrategy {
-  readonly name = "optimistic";
-  private maxRetries: number;
-  private eventEmitter?: ValidationEventEmitter;
-
-  constructor(config?: Record<string, unknown>) {
-    const typedConfig = config as OptimisticStrategyConfig | undefined;
-    this.maxRetries = typedConfig?.maxRetries ?? 3;
-  }
-
-  /**
-   * Set the EventStore for emitting validation events.
-   * Called after construction since EventStore may not be available at strategy creation time.
-   */
-  setEventStore(store: ValidationEventEmitter): void {
-    this.eventEmitter = store;
-  }
-
-  async land(request: LandRequest): Promise<LandResult> {
-    const { workspacePath, targetBranch } = request;
-    let retryCount = 0;
-
-    while (retryCount <= this.maxRetries) {
-      try {
-        // Fetch latest
-        this.git(workspacePath, `fetch origin ${targetBranch}`);
-
-        // Rebase onto latest
-        try {
-          this.git(workspacePath, `rebase origin/${targetBranch}`);
-        } catch {
-          try {
-            this.git(workspacePath, "rebase --abort");
-          } catch {
-            /* already clean */
-          }
-
-          if (retryCount >= this.maxRetries) {
-            return {
-              status: "conflict",
-              retryCount,
-              error: `Rebase conflict after ${retryCount + 1} attempts`,
-            };
-          }
-          retryCount++;
-          continue;
-        }
-
-        // Push optimistically
-        try {
-          this.git(workspacePath, `push origin HEAD:${targetBranch}`);
-        } catch {
-          if (retryCount >= this.maxRetries) {
-            return {
-              status: "conflict",
-              retryCount,
-              error: `Push rejected after ${retryCount + 1} attempts`,
-            };
-          }
-          retryCount++;
-          continue;
-        }
-
-        const commitHash = this.git(workspacePath, "rev-parse HEAD").trim();
-
-        // Emit validation:requested event (RD5 — judge handles validation)
-        if (this.eventEmitter) {
-          try {
-            this.eventEmitter.emit({
-              type: "status",
-              source: { agent_id: request.agentId },
-              payload: {
-                status_type: "checkpoint",
-                summary: `Validation requested for ${commitHash.slice(0, 8)}`,
-                validation_requested: true,
-                commitHash,
-                sourceBranch: request.sourceBranch,
-                targetBranch,
-                taskId: request.taskId,
-                agentId: request.agentId,
-              },
-            });
-          } catch {
-            // Never fail land() due to event emission failure
-          }
-        }
-
-        return {
-          status: "landed",
-          commitHash,
-          retryCount,
-        };
-      } catch (error) {
-        return {
-          status: "failed",
-          retryCount,
-          error: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
-        };
-      }
-    }
-
-    return {
-      status: "failed",
-      retryCount,
-      error: "Exceeded maximum retries",
-    };
-  }
-
-  private git(cwd: string, args: string): string {
-    return execSync(`git ${args}`, {
-      cwd,
-      encoding: "utf-8",
-      timeout: 30000,
-    });
-  }
-}

package/src/workspace/strategies/queue.ts

@@ -1,81 +0,0 @@
-/**
- * Queue Integration Strategy
- *
- * Wraps the existing MergeQueueInterface — submits merge requests to
- * the queue for sequential processing by an integrator agent.
- *
- * This produces identical behavior to the current worker done() handler's
- * merge queue path.
- *
- * @module workspace/strategies/queue
- */
-
-import type {
-  IntegrationStrategy,
-  LandRequest,
-  LandResult,
-  QueueStrategyConfig,
-} from "./types.js";
-import type { MergeQueueInterface } from "../merge-queue/types.js";
-
-export class QueueIntegrationStrategy implements IntegrationStrategy {
-  readonly name = "queue";
-  private mergeQueue?: MergeQueueInterface;
-  private defaultPriority: number;
-
-  constructor(config?: Record<string, unknown>) {
-    const typedConfig = config as QueueStrategyConfig | undefined;
-    this.defaultPriority = typedConfig?.defaultPriority ?? 100;
-  }
-
-  /**
-   * Set the merge queue instance.
-   * Called after construction since merge queue may not be available at strategy creation time.
-   */
-  setMergeQueue(queue: MergeQueueInterface): void {
-    this.mergeQueue = queue;
-  }
-
-  async land(request: LandRequest): Promise<LandResult> {
-    if (!this.mergeQueue) {
-      return {
-        status: "failed",
-        error: "Merge queue not configured",
-      };
-    }
-
-    if (!request.streamId) {
-      return {
-        status: "failed",
-        error: "streamId required for queue strategy",
-      };
-    }
-
-    if (!request.taskId) {
-      return {
-        status: "failed",
-        error: "taskId required for queue strategy",
-      };
-    }
-
-    try {
-      const mrId = this.mergeQueue.submit({
-        streamId: request.streamId,
-        taskId: request.taskId,
-        workerBranch: request.sourceBranch,
-        workerAgentId: request.agentId,
-        priority: this.defaultPriority,
-      });
-
-      return {
-        status: "landed",
-        mergeRequestId: mrId,
-      };
-    } catch (error) {
-      return {
-        status: "failed",
-        error: `Failed to submit to merge queue: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  }
-}

package/src/workspace/strategies/registry.ts

@@ -1,89 +0,0 @@
-/**
- * Integration Strategy Registry
- *
- * Factory registry for creating named integration strategies.
- * Supports registration of custom strategies alongside built-in ones.
- *
- * @module workspace/strategies/registry
- */
-
-import type {
-  IntegrationStrategy,
-  IntegrationStrategyFactory,
-} from "./types.js";
-import { QueueIntegrationStrategy } from "./queue.js";
-import { TrunkIntegrationStrategy } from "./trunk.js";
-import { OptimisticIntegrationStrategy } from "./optimistic.js";
-
-// =============================================================================
-// Registry
-// =============================================================================
-
-export class IntegrationStrategyRegistry {
-  private factories = new Map<string, IntegrationStrategyFactory>();
-
-  /**
-   * Register a strategy factory under a name.
-   */
-  register(name: string, factory: IntegrationStrategyFactory): void {
-    this.factories.set(name, factory);
-  }
-
-  /**
-   * Create a strategy instance by name.
-   *
-   * @throws Error if the strategy name is not registered
-   */
-  get(name: string, config?: Record<string, unknown>): IntegrationStrategy {
-    const factory = this.factories.get(name);
-    if (!factory) {
-      throw new Error(
-        `Unknown integration strategy: '${name}'. Available: ${this.list().join(", ")}`
-      );
-    }
-    return factory(config);
-  }
-
-  /**
-   * Check if a strategy is registered.
-   */
-  has(name: string): boolean {
-    return this.factories.has(name);
-  }
-
-  /**
-   * List registered strategy names.
-   */
-  list(): string[] {
-    return Array.from(this.factories.keys());
-  }
-}
-
-// =============================================================================
-// Default Registry
-// =============================================================================
-
-/**
- * Create a registry with all built-in strategies registered.
- */
-export function createDefaultStrategyRegistry(): IntegrationStrategyRegistry {
-  const registry = new IntegrationStrategyRegistry();
-
-  registry.register(
-    "queue",
-    (config) => new QueueIntegrationStrategy(config)
-  );
-  registry.register(
-    "trunk",
-    (config) => new TrunkIntegrationStrategy(config)
-  );
-  registry.register(
-    "optimistic",
-    (config) => new OptimisticIntegrationStrategy(config)
-  );
-
-  return registry;
-}
-
-/** Singleton default registry */
-export const defaultStrategyRegistry = createDefaultStrategyRegistry();

package/src/workspace/strategies/trunk.ts

@@ -1,123 +0,0 @@
-/**
- * Trunk Integration Strategy
- *
- * Direct push to integration branch with rebase-and-retry on conflict.
- * Suited for trunk-based development workflows where changes are
- * integrated immediately.
- *
- * @module workspace/strategies/trunk
- */
-
-import { execSync } from "child_process";
-import type {
-  IntegrationStrategy,
-  LandRequest,
-  LandResult,
-  TrunkStrategyConfig,
-} from "./types.js";
-
-export class TrunkIntegrationStrategy implements IntegrationStrategy {
-  readonly name = "trunk";
-  private maxRetries: number;
-  private conflictAction: "abandon" | "queued_for_resolution";
-
-  constructor(config?: Record<string, unknown>) {
-    const typedConfig = config as TrunkStrategyConfig | undefined;
-    this.maxRetries = typedConfig?.maxRetries ?? 3;
-    this.conflictAction = typedConfig?.conflictAction ?? "abandon";
-  }
-
-  async land(request: LandRequest): Promise<LandResult> {
-    const { workspacePath, targetBranch } = request;
-    let retryCount = 0;
-
-    while (retryCount <= this.maxRetries) {
-      try {
-        // Fetch latest target branch
-        this.git(workspacePath, `fetch origin ${targetBranch}`);
-
-        // Rebase our changes onto latest target
-        try {
-          this.git(workspacePath, `rebase origin/${targetBranch}`);
-        } catch {
-          // Rebase conflict — abort and retry or give up
-          try {
-            this.git(workspacePath, "rebase --abort");
-          } catch {
-            /* already clean */
-          }
-
-          if (retryCount >= this.maxRetries) {
-            const conflictFiles = this.getConflictFiles(workspacePath);
-            return {
-              status: "conflict",
-              conflictFiles,
-              action: this.conflictAction === "abandon" ? "abandoned" : this.conflictAction,
-              retryCount,
-              error: `Rebase conflict after ${retryCount + 1} attempts`,
-            };
-          }
-
-          retryCount++;
-          continue;
-        }
-
-        // Push to target branch
-        try {
-          this.git(workspacePath, `push origin HEAD:${targetBranch}`);
-        } catch {
-          // Push rejected (concurrent update) — retry
-          if (retryCount >= this.maxRetries) {
-            return {
-              status: "conflict",
-              action: this.conflictAction === "abandon" ? "abandoned" : this.conflictAction,
-              retryCount,
-              error: `Push rejected after ${retryCount + 1} attempts`,
-            };
-          }
-
-          retryCount++;
-          continue;
-        }
-
-        // Get the HEAD commit hash
-        const commitHash = this.git(workspacePath, "rev-parse HEAD").trim();
-
-        return {
-          status: "landed",
-          commitHash,
-          retryCount,
-        };
-      } catch (error) {
-        return {
-          status: "failed",
-          retryCount,
-          error: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
-        };
-      }
-    }
-
-    return {
-      status: "failed",
-      retryCount,
-      error: "Exceeded maximum retries",
-    };
-  }
-
-  private git(cwd: string, args: string): string {
-    return execSync(`git ${args}`, {
-      cwd,
-      encoding: "utf-8",
-      timeout: 30000,
-    });
-  }
-
-  private getConflictFiles(cwd: string): string[] {
-    try {
-      const output = this.git(cwd, "diff --name-only --diff-filter=U");
-      return output.split("\n").filter(Boolean);
-    } catch {
-      return [];
-    }
-  }
-}