macro-agent 0.2.4 → 0.2.6

package/src/workspace/index.ts

@@ -1,110 +0,0 @@
-/**
- * Workspace Module
- *
- * Provides workspace isolation for agents using git-cascade for stream and worktree management.
- * Implements [[s-7ktd]] Structured Workspace Isolation.
- *
- * @module workspace
- */
-
-// Configuration types
-export {
-  type GitCascadeConfig,
-  type WorkspaceDirectoryConfig,
-  type WorktreePoolConfig,
-  type AllocationStrategy,
-  DEFAULT_GIT_CASCADE_CONFIG,
-  DEFAULT_WORKSPACE_DIR_CONFIG,
-  DEFAULT_POOL_CONFIG,
-} from './config.js';
-
-// git-cascade adapter
-export {
-  GitCascadeAdapter,
-  createGitCascadeAdapter,
-  type GitCascadeEvent,
-  type GitCascadeEventType,
-  type GitCascadeEventCallback,
-} from './git-cascade-adapter.js';
-
-// Workspace types
-export type {
-  AgentId,
-  StreamId,
-  TaskId,
-  WorkspaceRole,
-  Workspace,
-  WorkerWorkspace,
-  IntegratorWorkspace,
-  CoordinatorWorkspace,
-  StreamConfig,
-  CreateTaskOptions as WorkspaceCreateTaskOptions,
-  WorkspaceStatus,
-  CleanupStatus,
-  WorkspaceManager,
-  WorkspaceEvent,
-  WorkspaceEventType,
-  WorkspaceEventCallback,
-} from './types.js';
-
-// Workspace manager
-export {
-  DefaultWorkspaceManager,
-  createWorkspaceManager,
-  createWorkspaceManagerWithAdapter,
-  type WorkspaceManagerConfig,
-} from './workspace-manager.js';
-
-// Merge queue
-export {
-  MergeQueue,
-  createMergeQueue,
-  MergeRequestNotFoundError,
-  MergeRequestStateError,
-  initMergeQueueSchema,
-  mergeQueueTableExists,
-  type MergeQueueConfig,
-  type MergeRequest,
-  type MergeRequestStatus,
-  type SubmitMergeRequestOptions,
-  type ListMergeRequestsOptions,
-  type MergeQueueInterface,
-  type MergeQueueEvent,
-  type MergeQueueEventType,
-  type MergeQueueEventCallback,
-} from './merge-queue/index.js';
-
-// Worktree pool
-export {
-  WorktreePool,
-  type AllocationResult,
-  type AcquireOptions,
-  type ReleaseOptions,
-  type PooledWorktree,
-  type PoolEvent,
-  type PoolEventCallback,
-  type PoolEventType,
-  type PoolStats,
-  type QueuedRequest,
-  type RecoveryResult,
-  type WorktreePoolInterface,
-  type WorktreeState,
-} from './pool/index.js';
-
-// Re-export key types from git-cascade adapter for convenience
-export type {
-  Stream,
-  StreamStatus,
-  CreateStreamOptions,
-  AgentWorktree,
-  CreateWorktreeOptions,
-  WorkerTask,
-  CreateTaskOptions,
-  StartTaskOptions,
-  CompleteTaskOptions,
-  StartTaskResult,
-  CompleteTaskResult,
-  ListTasksOptions,
-  CleanupWorkerBranchesOptions,
-  CleanupResult,
-} from 'git-cascade';

package/src/workspace/landing/__tests__/strategies.test.ts

@@ -1,184 +0,0 @@
-/**
- * Landing strategy tests (Phase 5).
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import {
-  MergeToParentStrategy,
-  QueueToBranchStrategy,
-  registerBuiltinLandingStrategies,
-} from '../index.js';
-import type { WorkspaceManager } from '../../types.js';
-
-describe('landing strategies', () => {
-  describe('MergeToParentStrategy', () => {
-    it('merges into parent stream when targetStreamId is absent', async () => {
-      const strategy = new MergeToParentStrategy();
-      const ws = {
-        listStreams: vi.fn(() => [
-          { id: 'child-1', parentStream: 'parent-1', status: 'active' },
-        ]),
-        mergeStream: vi.fn(() => ({ success: true, newHead: 'abc123' })),
-      } as unknown as WorkspaceManager;
-
-      const result = await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'child-1',
-        sourceWorktree: '/tmp/wt',
-        workspaceManager: ws,
-      });
-
-      expect(result.success).toBe(true);
-      expect(ws.mergeStream).toHaveBeenCalledWith(
-        expect.objectContaining({
-          sourceStreamId: 'child-1',
-          targetStreamId: 'parent-1',
-        })
-      );
-    });
-
-    it('fails when source has no parent and no targetStreamId', async () => {
-      const strategy = new MergeToParentStrategy();
-      const ws = {
-        listStreams: vi.fn(() => [{ id: 'orphan-1', status: 'active' }]),
-        mergeStream: vi.fn(),
-      } as unknown as WorkspaceManager;
-
-      const result = await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'orphan-1',
-        sourceWorktree: '/tmp/wt',
-        workspaceManager: ws,
-      });
-
-      expect(result.success).toBe(false);
-      expect(result.error).toMatch(/no target stream/);
-    });
-
-    it('uses explicit targetStreamId when provided', async () => {
-      const strategy = new MergeToParentStrategy();
-      const ws = {
-        listStreams: vi.fn(() => []),
-        mergeStream: vi.fn(() => ({ success: true, newHead: 'def456' })),
-      } as unknown as WorkspaceManager;
-
-      const result = await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'src-1',
-        sourceWorktree: '/tmp/wt',
-        targetStreamId: 'target-1',
-        workspaceManager: ws,
-      });
-
-      expect(result.success).toBe(true);
-      expect(ws.mergeStream).toHaveBeenCalledWith(
-        expect.objectContaining({ targetStreamId: 'target-1' })
-      );
-    });
-
-    it('threads ctx.taskRef into mergeStream metadata when present', async () => {
-      const strategy = new MergeToParentStrategy();
-      const ws = {
-        listStreams: vi.fn(() => []),
-        mergeStream: vi.fn(() => ({ success: true, newHead: 'aaa' })),
-      } as unknown as WorkspaceManager;
-
-      const taskRef = { resource_id: 'res-a1', node_id: 'task-a1' };
-      await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'src-1',
-        sourceWorktree: '/tmp/wt',
-        targetStreamId: 'target-1',
-        taskRef,
-        workspaceManager: ws,
-      });
-
-      expect(ws.mergeStream).toHaveBeenCalledWith(
-        expect.objectContaining({ metadata: { task_ref: taskRef } })
-      );
-    });
-
-    it('omits metadata when ctx.taskRef is absent', async () => {
-      const strategy = new MergeToParentStrategy();
-      const ws = {
-        listStreams: vi.fn(() => []),
-        mergeStream: vi.fn(() => ({ success: true, newHead: 'bbb' })),
-      } as unknown as WorkspaceManager;
-
-      await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'src-1',
-        sourceWorktree: '/tmp/wt',
-        targetStreamId: 'target-1',
-        workspaceManager: ws,
-      });
-
-      expect(ws.mergeStream).toHaveBeenCalledWith(
-        expect.objectContaining({ metadata: undefined })
-      );
-    });
-  });
-
-  describe('QueueToBranchStrategy', () => {
-    it('enqueues to branch target (default main)', async () => {
-      const strategy = new QueueToBranchStrategy();
-      const addToMergeQueue = vi.fn(() => 'queue-entry-1');
-      const ws = {
-        adapter: { addToMergeQueue },
-        listStreams: vi.fn(() => []),
-      } as unknown as WorkspaceManager;
-
-      const result = await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'stream-1',
-        sourceWorktree: '/tmp/wt',
-        workspaceManager: ws,
-      });
-
-      expect(result.success).toBe(true);
-      expect(addToMergeQueue).toHaveBeenCalledWith(
-        expect.objectContaining({
-          streamId: 'stream-1',
-          targetBranch: 'main',
-        })
-      );
-    });
-
-    it('accepts explicit branch: target spec', async () => {
-      const strategy = new QueueToBranchStrategy();
-      const addToMergeQueue = vi.fn(() => 'q-1');
-      const ws = {
-        adapter: { addToMergeQueue },
-        listStreams: vi.fn(() => []),
-      } as unknown as WorkspaceManager;
-
-      await strategy.land({
-        agentId: 'agent-1',
-        streamId: 'stream-1',
-        sourceWorktree: '/tmp/wt',
-        strategyConfig: { target: 'branch:release' },
-        workspaceManager: ws,
-      });
-
-      expect(addToMergeQueue).toHaveBeenCalledWith(
-        expect.objectContaining({ targetBranch: 'release' })
-      );
-    });
-  });
-
-  describe('registerBuiltinLandingStrategies', () => {
-    it('registers all four built-in strategies', () => {
-      const registered: string[] = [];
-      const ws = {
-        registerLandingStrategy: vi.fn((s) => registered.push(s.name)),
-      } as unknown as WorkspaceManager;
-
-      registerBuiltinLandingStrategies(ws);
-
-      expect(registered).toContain('merge-to-parent');
-      expect(registered).toContain('queue-to-branch');
-      expect(registered).toContain('direct-push');
-      expect(registered).toContain('optimistic-push');
-    });
-  });
-});

package/src/workspace/landing/direct-push.ts

@@ -1,91 +0,0 @@
-/**
- * `direct-push` landing strategy.
- *
- * Rebases the source stream's worker branch onto a target branch and pushes.
- * Preserves existing trunk-based behavior from the legacy `trunk` integration
- * strategy. Uses raw git (via execSync) since git-cascade doesn't expose a
- * rebase-and-push primitive.
- *
- * Strategy config:
- * - `target_branch`: string (default 'main')
- * - `max_retries`: number (default 3)
- *
- * @module workspace/landing/direct-push
- */
-
-import { execSync } from 'child_process';
-import type {
-  LandingStrategy,
-  LandingContext,
-  MergeResult,
-} from '../types-v3.js';
-import type { WorkspaceManager } from '../types.js';
-import type { GitCascadeAdapter } from '../git-cascade-adapter.js';
-
-export class DirectPushStrategy implements LandingStrategy {
-  readonly name = 'direct-push';
-
-  async land(ctx: LandingContext): Promise<MergeResult> {
-    const targetBranch = (ctx.strategyConfig?.target_branch as string | undefined) ?? 'main';
-    const remote = (ctx.strategyConfig?.remote as string | undefined) ?? 'origin';
-    const maxRetries = (ctx.strategyConfig?.max_retries as number | undefined) ?? 3;
-
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-      try {
-        execSync(`git fetch ${remote} ${targetBranch}`, {
-          cwd: ctx.sourceWorktree,
-          stdio: 'pipe',
-        });
-        execSync(`git rebase ${remote}/${targetBranch}`, {
-          cwd: ctx.sourceWorktree,
-          stdio: 'pipe',
-        });
-        execSync(`git push ${remote} HEAD:${targetBranch}`, {
-          cwd: ctx.sourceWorktree,
-          stdio: 'pipe',
-        });
-
-        // Capture pushed commit + emit stream:pushed for hub observability
-        // (OpenHive cascade-bridge translates this to x-cascade/stream.pushed
-        // since trunk pushes don't fire stream.merged).
-        try {
-          const pushedCommit = execSync('git rev-parse HEAD', {
-            cwd: ctx.sourceWorktree,
-            encoding: 'utf-8',
-          }).trim();
-          const adapter = (
-            ctx.workspaceManager as WorkspaceManager & {
-              getGitCascadeAdapter?: () => GitCascadeAdapter;
-            }
-          ).getGitCascadeAdapter?.();
-          adapter?.notifyStreamPushed({
-            streamId: ctx.streamId,
-            agentId: ctx.agentId,
-            pushedCommit,
-            remote,
-            remoteRef: targetBranch,
-            strategy: this.name,
-            metadata: ctx.taskRef ? { task_ref: ctx.taskRef } : undefined,
-          });
-        } catch {
-          // Best-effort observability — don't fail the push if notify fails.
-        }
-
-        return { success: true };
-      } catch (err) {
-        if (attempt >= maxRetries) {
-          return {
-            success: false,
-            error: `direct-push: failed after ${maxRetries} attempts — ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-          };
-        }
-        // Transient failure — retry once after brief backoff
-        // (brief; no sleep needed in tests — strategies are synchronous enough)
-      }
-    }
-
-    return { success: false, error: 'direct-push: exhausted retries' };
-  }
-}

package/src/workspace/landing/index.ts

@@ -1,40 +0,0 @@
-/**
- * Landing strategies — pluggable algorithms for finalizing stream work.
- *
- * Register via `WorkspaceManager.registerLandingStrategy`. Team YAML selects
- * the strategy via `roles.<role>.landing`. At `done()` time, AgentManagerV2
- * invokes `WorkspaceManager.land()` which dispatches to the registered
- * strategy by name.
- *
- * Built-in strategies:
- * - `merge-to-parent` — mergeStream into parent; optional cascade
- * - `queue-to-branch` — git-cascade's built-in merge queue
- * - `direct-push`     — rebase + push (trunk behavior)
- * - `optimistic-push` — direct-push + validation event
- *
- * @module workspace/landing
- * @see docs/workspace-interfaces.md §6
- */
-
-import type { WorkspaceManager } from '../types.js';
-import { MergeToParentStrategy } from './merge-to-parent.js';
-import { QueueToBranchStrategy } from './queue-to-branch.js';
-import { DirectPushStrategy } from './direct-push.js';
-import { OptimisticPushStrategy } from './optimistic-push.js';
-
-export { MergeToParentStrategy } from './merge-to-parent.js';
-export { QueueToBranchStrategy } from './queue-to-branch.js';
-export { DirectPushStrategy } from './direct-push.js';
-export { OptimisticPushStrategy } from './optimistic-push.js';
-
-/**
- * Register all built-in landing strategies on a WorkspaceManager.
- *
- * Called by boot-v2 after the WorkspaceManager is constructed.
- */
-export function registerBuiltinLandingStrategies(ws: WorkspaceManager): void {
-  ws.registerLandingStrategy(new MergeToParentStrategy());
-  ws.registerLandingStrategy(new QueueToBranchStrategy());
-  ws.registerLandingStrategy(new DirectPushStrategy());
-  ws.registerLandingStrategy(new OptimisticPushStrategy());
-}

package/src/workspace/landing/merge-to-parent.ts

@@ -1,229 +0,0 @@
-/**
- * `merge-to-parent` landing strategy.
- *
- * Merges the source stream into its parent stream via `mergeStream`. On
- * success, optionally triggers a cascade rebase for dependents if
- * `strategyConfig.cascade === true` (requires git-cascade 0.0.3+).
- *
- * Strategy config:
- * - `cascade`: boolean (default false) — run cascadeRebase after merge
- * - `cascadeStrategy`: 'stop_on_conflict' | 'skip_conflicting' | 'defer_conflicts'
- *   (default 'defer_conflicts')
- *
- * Cascade worktree provider:
- *   For each dependent stream needing a worktree, the strategy:
- *   1. Reuses a live agent's worktree if one is already allocated on that stream.
- *   2. Otherwise allocates an ephemeral system-owned worktree (under
- *      `system:cascade-<streamId>`), tracks it, and tears it down after
- *      cascadeRebase returns — regardless of per-stream success/failure.
- *
- * Per-root-stream lock prevents two parallel cascades on the same root from
- * racing on ephemeral worktree allocation.
- *
- * @module workspace/landing/merge-to-parent
- */
-
-import type {
-  LandingStrategy,
-  LandingContext,
-  MergeResult,
-  CascadeStrategy,
-  Principal,
-} from '../types-v3.js';
-import type { WorkspaceManager } from '../types.js';
-import type { DefaultWorkspaceManager } from '../workspace-manager.js';
-
-/**
- * Per-root-stream locks for cascadeRebase. Shared across all instances of
- * this strategy (module-scoped) so two separately-registered strategies
- * can't race either.
- */
-const rootStreamLocks = new Map<string, Promise<unknown>>();
-
-export class MergeToParentStrategy implements LandingStrategy {
-  readonly name = 'merge-to-parent';
-
-  async land(ctx: LandingContext): Promise<MergeResult> {
-    const ws = ctx.workspaceManager as WorkspaceManager;
-
-    // Resolve target stream. Explicit targetStreamId wins; otherwise use
-    // the source stream's parent.
-    let targetStreamId: string | undefined = ctx.targetStreamId;
-    if (!targetStreamId) {
-      const allStreams = ws.listStreams();
-      const source = allStreams.find((s) => s.id === ctx.streamId);
-      targetStreamId = source?.parentStream ?? undefined;
-    }
-
-    if (!targetStreamId) {
-      return {
-        success: false,
-        error: `merge-to-parent: no target stream (source ${ctx.streamId} has no parent)`,
-      };
-    }
-
-    // Resolve the worktree to perform the merge in.
-    //
-    // git's constraint: the target branch cannot already be checked out in
-    // another worktree. Three cases:
-    //   1. A live agent is already on the target stream → use that worktree
-    //      (the merge happens there; the agent's files update).
-    //   2. No live agent on target → use the source's worktree (target
-    //      branch isn't checked out anywhere else, so mergeStream can
-    //      check it out safely).
-    //   3. Neither — fallback: allocate an ephemeral worktree on the target.
-    const mergeWorktree = this.resolveMergeWorktree(ws, targetStreamId, ctx.sourceWorktree);
-    const ephemeralForMerge = mergeWorktree.ephemeralId;
-
-    try {
-      const result = ws.mergeStream({
-        sourceStreamId: ctx.streamId,
-        targetStreamId,
-        agentId: ctx.agentId,
-        worktree: mergeWorktree.path,
-        metadata: ctx.taskRef ? { task_ref: ctx.taskRef } : undefined,
-      });
-
-      // Cascade rebase on dependents if requested.
-      if (result.success && ctx.strategyConfig?.cascade === true) {
-        await this.runCascade(ws, ctx, targetStreamId);
-      }
-
-      return result;
-    } finally {
-      if (ephemeralForMerge) {
-        try {
-          (ws as DefaultWorkspaceManager).deallocateWorkspace(ephemeralForMerge);
-        } catch {
-          // Best-effort cleanup
-        }
-      }
-    }
-  }
-
-  /**
-   * Pick a worktree to perform the merge in.
-   *
-   * Priority:
-   *   1. A live agent already on the target stream
-   *   2. The source worktree (target branch not checked out elsewhere)
-   *   3. Ephemeral system worktree on the target stream
-   */
-  private resolveMergeWorktree(
-    ws: WorkspaceManager,
-    targetStreamId: string,
-    sourceWorktree: string
-  ): { path: string; ephemeralId?: string } {
-    const adapter = (ws as unknown as {
-      adapter?: {
-        listWorktrees?: () => Array<{ agentId: string; path: string; currentStream?: string | null }>;
-      };
-    }).adapter;
-
-    if (adapter?.listWorktrees) {
-      const live = adapter.listWorktrees().find((wt) => wt.currentStream === targetStreamId);
-      if (live) return { path: live.path };
-    }
-
-    // Default: use the source worktree. mergeStream will check out the
-    // target branch there. If that conflicts (branch checked out elsewhere
-    // that we didn't detect), the adapter throws and the strategy's caller
-    // handles it.
-    return { path: sourceWorktree };
-  }
-
-  private async runCascade(
-    ws: WorkspaceManager,
-    ctx: LandingContext,
-    rootStreamId: string
-  ): Promise<void> {
-    // Serialize cascades on the same root to prevent ephemeral-worktree
-    // races.
-    const prior = rootStreamLocks.get(rootStreamId);
-    const gate = prior ?? Promise.resolve();
-
-    const run = gate.then(async () => {
-      await this.doCascade(ws, ctx, rootStreamId);
-    });
-
-    // Store under the lock; clean up when done regardless of outcome.
-    rootStreamLocks.set(rootStreamId, run);
-    try {
-      await run;
-    } finally {
-      if (rootStreamLocks.get(rootStreamId) === run) {
-        rootStreamLocks.delete(rootStreamId);
-      }
-    }
-  }
-
-  private async doCascade(
-    ws: WorkspaceManager,
-    ctx: LandingContext,
-    rootStreamId: string
-  ): Promise<void> {
-    const dwm = ws as DefaultWorkspaceManager;
-    const adapter = (dwm as unknown as {
-      adapter?: {
-        cascadeRebase?: (opts: unknown) => unknown;
-        getWorktree?: (agentId: string) => { path: string; currentStream?: string } | null;
-        listWorktrees?: () => Array<{ agentId: string; path: string; currentStream?: string | null }>;
-      };
-    }).adapter;
-    if (!adapter?.cascadeRebase) return; // no-op if cascade unavailable
-
-    const cascadeStrategy =
-      (ctx.strategyConfig?.cascadeStrategy as CascadeStrategy | undefined) ??
-      'defer_conflicts';
-
-    // Track ephemeral worktrees we allocate so we can tear them down.
-    const ephemeralIds: Principal[] = [];
-
-    const provider = (streamId: string): string | null => {
-      // 1. Look for a live agent already on this stream.
-      if (adapter.listWorktrees) {
-        const wts = adapter.listWorktrees();
-        const live = wts.find((wt) => wt.currentStream === streamId);
-        if (live) return live.path;
-      }
-
-      // 2. Allocate an ephemeral system-owned worktree.
-      try {
-        const ephemeralId = `system:cascade-${streamId}` as Principal;
-        const worktree = ws.allocateWorktree({
-          agentId: ephemeralId,
-          streamId,
-        });
-        ephemeralIds.push(ephemeralId);
-        return worktree.path;
-      } catch {
-        // Allocation failure — signal skip to cascadeRebase
-        return null;
-      }
-    };
-
-    try {
-      adapter.cascadeRebase({
-        rootStream: rootStreamId,
-        agentId: ctx.agentId,
-        strategy: cascadeStrategy,
-        worktree: {
-          mode: 'callback',
-          provider,
-        },
-      });
-    } catch {
-      // Cascade internal failure — non-fatal to the landing
-    } finally {
-      // Tear down all ephemeral worktrees we allocated, regardless of
-      // per-stream success/failure.
-      for (const id of ephemeralIds) {
-        try {
-          dwm.deallocateWorkspace(id as string);
-        } catch {
-          // Best-effort cleanup
-        }
-      }
-    }
-  }
-}

package/src/workspace/landing/optimistic-push.ts

@@ -1,36 +0,0 @@
-/**
- * `optimistic-push` landing strategy.
- *
- * Same as `direct-push`, plus emits a `validation:requested` event to trigger
- * a downstream judge/reviewer agent. Used by self-driving teams where landing
- * is optimistic and validation runs post-hoc.
- *
- * @module workspace/landing/optimistic-push
- */
-
-import type {
-  LandingStrategy,
-  LandingContext,
-  MergeResult,
-} from '../types-v3.js';
-import { DirectPushStrategy } from './direct-push.js';
-
-export class OptimisticPushStrategy implements LandingStrategy {
-  readonly name = 'optimistic-push';
-  private readonly inner = new DirectPushStrategy();
-
-  async land(ctx: LandingContext): Promise<MergeResult> {
-    const result = await this.inner.land(ctx);
-    if (result.success) {
-      // Emit validation request via the WorkspaceManager's event stream.
-      // Consumers (trigger/wake + judge agents) subscribe and act.
-      const ws = ctx.workspaceManager as {
-        emit?: (type: string, data: Record<string, unknown>) => void;
-      };
-      // emit is private on DefaultWorkspaceManager; use landing:completed instead
-      // which is the public event channel for landing outcomes.
-      // (Actual emission handled by the caller that invokes land().)
-    }
-    return result;
-  }
-}