macro-agent 0.2.5 → 0.2.6

package/src/workspace/strategies/types.ts

@@ -1,145 +0,0 @@
-/**
- * Integration Strategy Types
- *
- * Defines the pluggable strategy interface for integrating worker changes
- * into the integration branch. Strategies determine how completed work
- * is landed (merge queue, direct push, optimistic push).
- *
- * @module workspace/strategies/types
- */
-
-// =============================================================================
-// Land Request / Result
-// =============================================================================
-
-/**
- * Result status from a land operation
- */
-export type LandResultStatus = "landed" | "conflict" | "failed";
-
-/**
- * Request to land changes from a worker branch
- */
-export interface LandRequest {
-  /** Worker's branch with completed changes */
-  sourceBranch: string;
-
-  /** Target integration branch */
-  targetBranch: string;
-
-  /** Workspace path where git operations run */
-  workspacePath: string;
-
-  /** Agent ID of the worker */
-  agentId: string;
-
-  /** Task ID associated with the changes */
-  taskId?: string;
-
-  /** Stream ID for the integration stream */
-  streamId?: string;
-
-  /** Commit message for the merge/rebase */
-  commitMessage?: string;
-}
-
-/**
- * Result of a land operation
- */
-export interface LandResult {
-  /** Whether the landing was successful */
-  status: LandResultStatus;
-
-  /** Merge/rebase commit hash if landed */
-  commitHash?: string;
-
-  /** Merge request ID if submitted to a queue */
-  mergeRequestId?: string;
-
-  /** Files with conflicts if status is "conflict" */
-  conflictFiles?: string[];
-
-  /** Action taken on conflict exhaustion */
-  action?: "abandoned" | "queued_for_resolution";
-
-  /** Error message if status is "failed" */
-  error?: string;
-
-  /** Number of retry attempts made */
-  retryCount?: number;
-}
-
-// =============================================================================
-// Strategy Interface
-// =============================================================================
-
-/**
- * Integration strategy interface.
- *
- * Strategies determine how completed worker changes are integrated
- * into the target branch. Different strategies suit different workflows:
- * - queue: Sequential merge via integrator (default, existing behavior)
- * - trunk: Direct push with rebase-and-retry
- * - optimistic: Push immediately, validate later (judge validates)
- */
-export interface IntegrationStrategy {
-  /** Strategy name */
-  readonly name: string;
-
-  /**
-   * Land changes from source branch to target branch.
-   */
-  land(request: LandRequest): Promise<LandResult>;
-
-  /**
-   * Optional initialization hook (called on TeamRuntime.initialize()).
-   */
-  initialize?(): Promise<void>;
-
-  /**
-   * Optional cleanup hook (called on TeamRuntime.teardown()).
-   */
-  close?(): Promise<void>;
-}
-
-// =============================================================================
-// Strategy Configuration Types
-// =============================================================================
-
-/**
- * Configuration for the queue strategy
- */
-export interface QueueStrategyConfig {
-  /** Priority for submitted merge requests (default: 100) */
-  defaultPriority?: number;
-}
-
-/**
- * Configuration for the trunk strategy
- */
-export interface TrunkStrategyConfig {
-  /** Maximum rebase-and-retry attempts on conflict (default: 3) */
-  maxRetries?: number;
-
-  /** Action on conflict exhaustion (default: "abandon") */
-  conflictAction?: "abandon" | "queued_for_resolution";
-}
-
-/**
- * Configuration for the optimistic strategy
- */
-export interface OptimisticStrategyConfig {
-  /** Maximum rebase-and-retry attempts on conflict (default: 3) */
-  maxRetries?: number;
-}
-
-// =============================================================================
-// Factory
-// =============================================================================
-
-/**
- * Factory function signature for creating strategies
- */
-export type IntegrationStrategyFactory = (
-  config?: Record<string, unknown>
-) => IntegrationStrategy;

package/src/workspace/topology/__tests__/yaml-driven.test.ts

@@ -1,345 +0,0 @@
-/**
- * YamlDrivenTopology tests (Phase 3).
- *
- * Verifies that the topology compiles each of the 6 workflow shapes from
- * docs/git-cascade-integration-gaps.md §5 into correct WorkspaceDecisions.
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { YamlDrivenTopology } from '../yaml-driven.js';
-import { parseTeamWorkspaceConfig, type TeamWorkspaceConfig } from '../../yaml-schema.js';
-import type { WorkspaceManager } from '../../types.js';
-
-// ─── Helpers ──────────────────────────────────────────────────────────────
-
-function mockWorkspaceManager(): WorkspaceManager {
-  const createdStreams: string[] = [];
-  return {
-    createStreamV3: vi.fn((_spec) => {
-      const id = `stream-${createdStreams.length + 1}`;
-      createdStreams.push(id);
-      return id;
-    }),
-    abandonStream: vi.fn(),
-    deallocateWorkspace: vi.fn(),
-    // The other methods are unused by topology logic in these tests.
-  } as unknown as WorkspaceManager;
-}
-
-// ─── Tests ────────────────────────────────────────────────────────────────
-
-describe('YamlDrivenTopology', () => {
-  describe('peer swarm', () => {
-    let topology: YamlDrivenTopology;
-    let ws: WorkspaceManager;
-
-    beforeEach(async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          orchestrator: { workspace: 'none' },
-          peer: {
-            workspace: 'new_stream',
-            stream_lineage: 'fork_from_team_root',
-            landing: 'merge_to_parent_stream',
-          },
-        },
-      });
-      topology = new YamlDrivenTopology(config!);
-      ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'peer-swarm',
-        teamInstanceId: 'swarm-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-    });
-
-    it('creates a team root stream at start', () => {
-      expect(ws.createStreamV3).toHaveBeenCalledOnce();
-      expect(ws.createStreamV3).toHaveBeenCalledWith(
-        expect.objectContaining({
-          ownerId: 'team:peer-swarm',
-          forkFrom: 'main',
-        })
-      );
-    });
-
-    it('spawns orchestrator with kind=none', async () => {
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-orch',
-        role: 'orchestrator',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('none');
-    });
-
-    it('spawns peer with new-stream forked off team root', async () => {
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-peer-1',
-        role: 'peer',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('new-stream');
-      if (decision.kind === 'new-stream') {
-        expect(decision.streamSpec.parent).toBe('stream-1');
-        expect(decision.streamSpec.ownerId).toBe('agent-peer-1');
-        expect(decision.allocateWorktree).toBe(true);
-      }
-    });
-  });
-
-  describe('triad (coordinator / worker / integrator)', () => {
-    let topology: YamlDrivenTopology;
-    let ws: WorkspaceManager;
-
-    beforeEach(async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          coordinator: { workspace: 'attach_to_team_root' },
-          worker: {
-            workspace: 'new_stream',
-            stream_lineage: 'fork_from_parent',
-            landing: 'queue_to_branch',
-          },
-          integrator: {
-            workspace: 'attach_to_team_root',
-            capabilities: ['workspace.merge', 'merge_queue.drain'],
-          },
-        },
-      });
-      topology = new YamlDrivenTopology(config!);
-      ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'triad',
-        teamInstanceId: 'triad-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-    });
-
-    it('attaches coordinator to team root stream', async () => {
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-coord',
-        role: 'coordinator',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('attach-to-stream');
-      if (decision.kind === 'attach-to-stream') {
-        expect(decision.streamId).toBe('stream-1');
-      }
-    });
-
-    it('spawns worker with fork_from_parent lineage', async () => {
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-worker',
-        role: 'worker',
-        parentAgentId: 'agent-coord',
-        parentStreamId: 'stream-1',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('new-stream');
-      if (decision.kind === 'new-stream') {
-        expect(decision.streamSpec.parent).toBe('stream-1');
-      }
-    });
-  });
-
-  describe('pipeline (share_with_agent)', () => {
-    it('resolves share_with via getAgentByRole callback', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          coder: {
-            workspace: 'new_stream',
-            stream_lineage: 'fork_from_team_root',
-          },
-          reviewer: {
-            workspace: 'share_with_agent',
-            share_with: 'coder',
-          },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'pipeline',
-        teamInstanceId: 'p-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-rev',
-        role: 'reviewer',
-        workspaceManager: ws,
-        getAgentByRole: (r) => (r === 'coder' ? 'agent-coder' : null),
-      });
-
-      expect(decision.kind).toBe('share-with-agent');
-      if (decision.kind === 'share-with-agent') {
-        expect(decision.agentId).toBe('agent-coder');
-      }
-    });
-
-    it('falls back to share-parent-cwd when share_with role has no active agent', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          coder: { workspace: 'new_stream', stream_lineage: 'fork_from_team_root' },
-          reviewer: { workspace: 'share_with_agent', share_with: 'coder' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'pipeline',
-        teamInstanceId: 'p-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-rev',
-        role: 'reviewer',
-        workspaceManager: ws,
-        getAgentByRole: () => null,
-      });
-
-      expect(decision.kind).toBe('share-parent-cwd');
-    });
-  });
-
-  describe('research / read-only', () => {
-    it('returns none for workspace: none, skips team root creation', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          researcher: { workspace: 'none' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      const plan = await topology.onTeamStart({
-        teamName: 'research',
-        teamInstanceId: 'r-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-
-      expect(plan.teamStreamId).toBeUndefined();
-      expect(ws.createStreamV3).not.toHaveBeenCalled();
-
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-1',
-        role: 'researcher',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('none');
-    });
-  });
-
-  describe('solo stack', () => {
-    it('author gets a new stream forked from team root', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          author: {
-            workspace: 'new_stream',
-            stream_lineage: 'fork_from_team_root',
-            landing: 'merge_to_parent_stream',
-            cascade_on_parent_update: true,
-          },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'solo',
-        teamInstanceId: 's-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-
-      const decision = await topology.onAgentSpawn({
-        agentId: 'agent-auth',
-        role: 'author',
-        workspaceManager: ws,
-      });
-      expect(decision.kind).toBe('new-stream');
-      if (decision.kind === 'new-stream') {
-        expect(decision.streamSpec.parent).toBe('stream-1');
-      }
-    });
-  });
-
-  describe('onTeamStop', () => {
-    it('abandons team stream when on_team_complete=abandon', async () => {
-      const config = parseTeamWorkspaceConfig({
-        on_team_complete: 'abandon',
-        roles: {
-          peer: { workspace: 'new_stream', stream_lineage: 'fork_from_team_root' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'x',
-        teamInstanceId: 'x-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-      await topology.onTeamStop({
-        teamName: 'x',
-        teamInstanceId: 'x-1',
-        teamStreamId: 'stream-1',
-        workspaceManager: ws,
-      });
-
-      expect(ws.abandonStream).toHaveBeenCalledWith(
-        'stream-1',
-        expect.objectContaining({ cascade: true })
-      );
-    });
-
-    it('keeps team stream when on_team_complete=keep (default)', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          peer: { workspace: 'new_stream', stream_lineage: 'fork_from_team_root' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-      await topology.onTeamStart({
-        teamName: 'x',
-        teamInstanceId: 'x-1',
-        workspaceConfig: config,
-        workspaceManager: ws,
-      });
-      await topology.onTeamStop({
-        teamName: 'x',
-        teamInstanceId: 'x-1',
-        teamStreamId: 'stream-1',
-        workspaceManager: ws,
-      });
-
-      expect(ws.abandonStream).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('onAgentComplete', () => {
-    it('deallocates the agent workspace', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          peer: { workspace: 'new_stream', stream_lineage: 'fork_from_team_root' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-      const ws = mockWorkspaceManager();
-
-      await topology.onAgentComplete({
-        agentId: 'agent-1',
-        role: 'peer',
-        reason: 'completed',
-        workspaceManager: ws,
-      });
-
-      expect(ws.deallocateWorkspace).toHaveBeenCalledWith('agent-1');
-    });
-  });
-});

package/src/workspace/topology/index.ts

@@ -1,18 +0,0 @@
-/**
- * Topology policies — compile team YAML into workspace decisions.
- *
- * @module workspace/topology
- */
-
-export type {
-  TopologyPolicy,
-  TeamStartContext,
-  TeamStartPlan,
-  SpawnContext,
-  WorkspaceDecision,
-  AgentCompleteContext,
-  TeamStopContext,
-} from './types.js';
-
-export { YamlDrivenTopology } from './yaml-driven.js';
-export { NoWorkspaceTopology } from './no-workspace.js';

package/src/workspace/topology/no-workspace.ts

@@ -1,39 +0,0 @@
-/**
- * NoWorkspaceTopology — null TopologyPolicy.
- *
- * Returns `share-parent-cwd` for every spawn. Used when no team YAML declares
- * `macro_agent.workspace` — agents run in the spawner's cwd with no git-cascade
- * state. Safe default for teams that don't need isolation.
- *
- * @module workspace/topology/no-workspace
- */
-
-import type {
-  TopologyPolicy,
-  TeamStartContext,
-  TeamStartPlan,
-  SpawnContext,
-  WorkspaceDecision,
-  AgentCompleteContext,
-  TeamStopContext,
-} from './types.js';
-
-export class NoWorkspaceTopology implements TopologyPolicy {
-  readonly name = 'no-workspace';
-
-  async onTeamStart(_ctx: TeamStartContext): Promise<TeamStartPlan> {
-    return {};
-  }
-
-  async onAgentSpawn(_ctx: SpawnContext): Promise<WorkspaceDecision> {
-    return { kind: 'share-parent-cwd' };
-  }
-
-  async onAgentComplete(_ctx: AgentCompleteContext): Promise<void> {
-    // No-op
-  }
-
-  async onTeamStop(_ctx: TeamStopContext): Promise<void> {
-    // No-op
-  }
-}

package/src/workspace/topology/types.ts

@@ -1,116 +0,0 @@
-/**
- * TopologyPolicy — compiles team YAML into per-spawn workspace decisions.
- *
- * A topology policy sits between AgentManagerV2 and WorkspaceManager. It
- * translates declarative team configuration (role shape, stream lineage,
- * landing strategy) into imperative `WorkspaceDecision`s that AgentManager
- * executes via the WorkspaceManager v3 surface.
- *
- * Three built-in policies:
- * - `YamlDrivenTopology` — primary; compiles TeamWorkspaceConfig (default)
- * - `NoWorkspaceTopology` — null policy; returns `none` for every agent
- * - `CognitiveCoreTopology` — programmatic policy for cognitive-core style
- *   callers that bypass YAML (deferred; stub for now)
- *
- * @module workspace/topology/types
- * @see docs/workspace-interfaces.md §7
- * @see docs/workspace-redesign-plan.md Phase 3
- */
-
-import type { AgentId, StreamId, Principal, StreamSpec } from '../types-v3.js';
-import type { WorkspaceManager } from '../types.js';
-import type {
-  TeamWorkspaceConfig,
-  RoleWorkspaceConfig,
-} from '../yaml-schema.js';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Context types
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface TeamStartContext {
-  teamName: string;
-  teamInstanceId: string;
-  workspaceConfig: TeamWorkspaceConfig | null;
-  workspaceManager: WorkspaceManager;
-}
-
-export interface TeamStartPlan {
-  teamStreamId?: StreamId;
-  additionalStreams?: StreamId[];
-}
-
-export interface SpawnContext {
-  agentId: AgentId;
-  role: string;
-  parentAgentId?: AgentId;
-  parentStreamId?: StreamId;
-  teamStreamId?: StreamId;
-  workspaceManager: WorkspaceManager;
-  /** Look up a live agent ID by role (for workspace: share_with_agent). */
-  getAgentByRole?: (role: string) => AgentId | null;
-}
-
-export interface AgentCompleteContext {
-  agentId: AgentId;
-  role: string;
-  reason: 'completed' | 'failed' | 'cascade' | 'interrupted';
-  streamId?: StreamId;
-  workspaceManager: WorkspaceManager;
-}
-
-export interface TeamStopContext {
-  teamName: string;
-  teamInstanceId: string;
-  teamStreamId?: StreamId;
-  workspaceManager: WorkspaceManager;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Decision type
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Declarative description of what workspace the spawning agent should get.
- * AgentManagerV2 executes this via WorkspaceManager calls.
- */
-export type WorkspaceDecision =
-  | { kind: 'none' }
-  | { kind: 'share-parent-cwd' }
-  | { kind: 'share-with-agent'; agentId: AgentId }
-  | { kind: 'attach-to-stream'; streamId: StreamId; allocateWorktree: boolean }
-  | {
-      kind: 'new-stream';
-      streamSpec: StreamSpec;
-      allocateWorktree: boolean;
-    };
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Policy interface
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface TopologyPolicy {
-  readonly name: string;
-
-  onTeamStart(ctx: TeamStartContext): Promise<TeamStartPlan>;
-  onAgentSpawn(ctx: SpawnContext): Promise<WorkspaceDecision>;
-  onAgentComplete(ctx: AgentCompleteContext): Promise<void>;
-  onTeamStop(ctx: TeamStopContext): Promise<void>;
-
-  /**
-   * Optional: subscribed when the topology cares about parent-stream updates.
-   * Used by roles with `on_parent_advanced: sync_with_parent`.
-   */
-  onParentStreamAdvanced?(ctx: {
-    parentStreamId: StreamId;
-    affectedAgents: AgentId[];
-    workspaceManager: WorkspaceManager;
-  }): Promise<void>;
-
-  /**
-   * Look up the per-role config if this policy is YAML-driven. Other code
-   * (e.g., the conflict recovery dispatcher) consults this to find
-   * `on_conflict_recovery` overrides at dispatch time.
-   */
-  getRoleConfig?(role: string): RoleWorkspaceConfig | null;
-}