macro-agent 0.1.8 → 0.1.11

package/src/workspace/recovery/abandon.ts

@@ -0,0 +1,51 @@
+/**
+ * `abandon` conflict recovery strategy.
+ *
+ * Abandons the conflicted stream. Throwaway-exploration teams; CI-driven
+ * flows where broken work is discarded rather than resolved.
+ *
+ * @module workspace/recovery/abandon
+ */
+
+import type {
+  ConflictContext,
+  ConflictRecoveryStrategy,
+  ConflictResolution,
+} from './types.js';
+
+export class AbandonStrategy implements ConflictRecoveryStrategy {
+  readonly name = 'abandon';
+  readonly mode = 'sync' as const;
+
+  async recover(ctx: ConflictContext): Promise<ConflictResolution> {
+    try {
+      // Mark the conflict resolved (method='abandoned') so the OpenHive hub
+      // moves cascade_conflicts.status from pending → resolved instead of
+      // showing it stuck pending forever.
+      try {
+        ctx.workspaceManager.resolveConflict({
+          conflictId: ctx.conflictId,
+          resolvedBy: 'system:abandon',
+          method: 'abandoned',
+          summary: `stream abandoned: ${ctx.streamId}`,
+        });
+      } catch {
+        // Non-fatal — abandonStream below still runs
+      }
+
+      ctx.workspaceManager.abandonStream(ctx.streamId, {
+        reason: `abandon strategy: conflict ${ctx.conflictId}`,
+      });
+      return {
+        kind: 'abandoned',
+        streamId: ctx.streamId,
+        reason: `conflict ${ctx.conflictId}`,
+      };
+    } catch (err) {
+      return {
+        kind: 'failed',
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+}

package/src/workspace/recovery/auto-resolve.ts

@@ -0,0 +1,119 @@
+/**
+ * `auto-resolve` conflict recovery strategy.
+ *
+ * Replays the failed merge in the agent's worktree with a git strategy
+ * option (`-X ours` / `-X theirs` / `-s union` via `-X`), commits the
+ * resolution, and returns the resulting commit hash.
+ *
+ * Strategy config:
+ * - `strategy`: 'ours' | 'theirs' | 'union' (default: 'ours')
+ * - `commit_message`: string (default: `resolve: ${conflictId} via <strategy>`)
+ *
+ * Scope limits:
+ * - Only handles `operation: 'merge'`. Rebase conflicts need different tooling.
+ * - Requires `ctx.worktree` to be set. If absent, returns `failed`.
+ * - Requires `ctx.sourceCommit` to identify what to replay. If absent,
+ *   tries `HEAD^2` (the merge commit's incoming side).
+ *
+ * @module workspace/recovery/auto-resolve
+ */
+
+import { execSync } from 'child_process';
+import type {
+  ConflictContext,
+  ConflictRecoveryStrategy,
+  ConflictResolution,
+} from './types.js';
+
+export class AutoResolveStrategy implements ConflictRecoveryStrategy {
+  readonly name = 'auto-resolve';
+  readonly mode = 'sync' as const;
+
+  canHandle(ctx: ConflictContext): boolean {
+    return ctx.operation === 'merge' && !!ctx.worktree;
+  }
+
+  async recover(ctx: ConflictContext): Promise<ConflictResolution> {
+    if (ctx.operation !== 'merge') {
+      return {
+        kind: 'failed',
+        error: `auto-resolve only handles merge conflicts, not ${ctx.operation}`,
+      };
+    }
+
+    if (!ctx.worktree) {
+      return {
+        kind: 'failed',
+        error: 'auto-resolve requires ctx.worktree',
+      };
+    }
+
+    const strategy = (ctx.strategyConfig?.strategy as string | undefined) ?? 'ours';
+    if (strategy !== 'ours' && strategy !== 'theirs' && strategy !== 'union') {
+      return {
+        kind: 'failed',
+        error: `auto-resolve: unsupported strategy "${strategy}" (use ours | theirs | union)`,
+      };
+    }
+
+    const sourceRef = ctx.sourceCommit ?? 'MERGE_HEAD';
+    const commitMessage =
+      (ctx.strategyConfig?.commit_message as string | undefined) ??
+      `resolve: ${ctx.conflictId} via ${strategy}`;
+
+    try {
+      // Abort any in-progress merge state first (safety — merge may have
+      // left the index in a partial state)
+      try {
+        execSync('git merge --abort', {
+          cwd: ctx.worktree,
+          stdio: 'pipe',
+        });
+      } catch {
+        // No merge in progress — that's fine
+      }
+
+      // Replay the merge with the chosen strategy
+      execSync(
+        `git merge -X ${strategy} --no-edit -m ${quote(commitMessage)} ${quote(sourceRef)}`,
+        {
+          cwd: ctx.worktree,
+          stdio: 'pipe',
+        }
+      );
+
+      // Capture the new HEAD as the resolution commit
+      const resolutionCommit = execSync('git rev-parse HEAD', {
+        cwd: ctx.worktree,
+        encoding: 'utf-8',
+      }).trim();
+
+      // Notify the WorkspaceManager so downstream consumers see the resolution
+      try {
+        ctx.workspaceManager.resolveConflict({
+          conflictId: ctx.conflictId,
+          resolvedBy: ctx.landingAgentId ?? 'system:auto-resolve',
+          resolutionCommit,
+          method: 'auto-resolve',
+          summary: `merged with -X ${strategy}`,
+        });
+      } catch {
+        // Non-fatal — resolution is recorded via return value regardless
+      }
+
+      return { kind: 'resolved', resolutionCommit };
+    } catch (err) {
+      return {
+        kind: 'failed',
+        error: `auto-resolve (strategy=${strategy}): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      };
+    }
+  }
+}
+
+/** Minimal shell-safe single-quoting for commit messages / refs. */
+function quote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/workspace/recovery/defer.ts

@@ -0,0 +1,23 @@
+/**
+ * `defer` conflict recovery strategy — no-op.
+ *
+ * Leaves the conflict record in place; stream stays `conflicted`. Something
+ * else (human, external process, scheduled recovery) resolves later.
+ *
+ * @module workspace/recovery/defer
+ */
+
+import type {
+  ConflictContext,
+  ConflictRecoveryStrategy,
+  ConflictResolution,
+} from './types.js';
+
+export class DeferStrategy implements ConflictRecoveryStrategy {
+  readonly name = 'defer';
+  readonly mode = 'sync' as const;
+
+  async recover(_ctx: ConflictContext): Promise<ConflictResolution> {
+    return { kind: 'deferred', reason: 'no recovery strategy configured' };
+  }
+}

package/src/workspace/recovery/escalate.ts

@@ -0,0 +1,30 @@
+/**
+ * `escalate` conflict recovery strategy — human-in-the-loop.
+ *
+ * Pauses the stream and emits an escalation marker. External systems (UI,
+ * on-call agent, operator) resolve the conflict manually, then call
+ * `resolve_conflict` MCP tool to unblock.
+ *
+ * @module workspace/recovery/escalate
+ */
+
+import type {
+  ConflictContext,
+  ConflictRecoveryStrategy,
+  ConflictResolution,
+} from './types.js';
+
+export class EscalateStrategy implements ConflictRecoveryStrategy {
+  readonly name = 'escalate';
+  readonly mode = 'async' as const;
+
+  async recover(ctx: ConflictContext): Promise<ConflictResolution> {
+    try {
+      ctx.workspaceManager.pauseStream(ctx.streamId, 'awaiting human resolution');
+    } catch {
+      // Non-fatal — stream may already be in a paused/conflicted state
+    }
+    const target = (ctx.strategyConfig?.notify as string | undefined) ?? 'human';
+    return { kind: 'escalated', escalatedTo: target as 'human' };
+  }
+}

package/src/workspace/recovery/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Conflict recovery strategies.
+ *
+ * Register via `WorkspaceManager.registerConflictRecoveryStrategy` (Phase 7b).
+ * Selected via per-role YAML `on_conflict_recovery` or team default.
+ *
+ * Built-ins:
+ * - `defer`        — no-op; leave conflict record for external resolution
+ * - `abandon`      — abandon the conflicted stream
+ * - `escalate`     — pause stream; notify human
+ * - `auto-resolve` — git strategies (ours/theirs/union) — scaffold only
+ * - `spawn-resolver` — LLM resolver agent (Phase 7b; requires AgentManager)
+ *
+ * @module workspace/recovery
+ * @see docs/conflict-recovery.md
+ */
+
+export type {
+  ConflictContext,
+  ConflictRecoveryStrategy,
+  ConflictResolution,
+  ConflictResolutionMode,
+} from './types.js';
+
+export { DeferStrategy } from './defer.js';
+export { AbandonStrategy } from './abandon.js';
+export { EscalateStrategy } from './escalate.js';
+export { AutoResolveStrategy } from './auto-resolve.js';
+export {
+  SpawnResolverStrategy,
+  createSpawnResolverStrategy,
+  type SpawnResolverStrategyOptions,
+} from './spawn-resolver.js';
+
+import { DeferStrategy } from './defer.js';
+import { AbandonStrategy } from './abandon.js';
+import { EscalateStrategy } from './escalate.js';
+import { AutoResolveStrategy } from './auto-resolve.js';
+import type { ConflictRecoveryStrategy } from './types.js';
+
+/**
+ * Build a registry of built-in conflict recovery strategies.
+ *
+ * Returns a Map keyed by strategy name. Callers plug this into their dispatch
+ * layer (Phase 7b). `spawn-resolver` is not included — it requires
+ * AgentManager injection and is added by the consumer.
+ */
+export function buildBuiltinRecoveryRegistry(): Map<string, ConflictRecoveryStrategy> {
+  const map = new Map<string, ConflictRecoveryStrategy>();
+  const strategies: ConflictRecoveryStrategy[] = [
+    new DeferStrategy(),
+    new AbandonStrategy(),
+    new EscalateStrategy(),
+    new AutoResolveStrategy(),
+  ];
+  for (const s of strategies) map.set(s.name, s);
+  return map;
+}

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

@@ -0,0 +1,152 @@
+/**
+ * `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

@@ -0,0 +1,54 @@
+/**
+ * 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>;
+}