macro-agent 0.2.4 → 0.2.6

package/src/workspace/yaml-schema.ts

@@ -1,216 +0,0 @@
-/**
- * YAML Zod schema for `macro_agent.workspace`.
- *
- * Teams declare workspace topology via `macro_agent.workspace` in their
- * `team.yaml`. This module validates that section and exposes typed config
- * objects that the TopologyPolicy compiler (Phase 3) consumes.
- *
- * @module workspace/yaml-schema
- * @see docs/workspace-interfaces.md §8
- * @see docs/workspace-redesign-plan.md Phase 2
- */
-
-import { z } from 'zod';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Enums
-// ─────────────────────────────────────────────────────────────────────────────
-
-export const StreamLineageSchema = z.enum([
-  'from_team_root',         // attach to the team's root stream (no new stream)
-  'fork_from_team_root',    // fork a new stream off the team root
-  'fork_from_parent',       // fork a new stream off the spawner's stream
-  'independent',            // fork a new stream off a branch (no parent stream)
-  'track_existing_branch',  // track an existing branch (no new stream/<id>)
-]);
-
-export const LandingStrategyNameSchema = z.enum([
-  'merge_to_parent_stream',
-  'queue_to_branch',
-  'cherry_pick_stack',
-  'direct_push',
-  'optimistic_push',
-  'none',
-]);
-
-export const ConflictStrategyNameSchema = z.enum([
-  'abort',
-  'ours',
-  'theirs',
-  'defer',
-  'agent',
-]);
-
-/**
- * Recovery strategies for landing conflicts.
- * See docs/conflict-recovery.md §4.
- */
-export const ConflictRecoveryStrategyNameSchema = z.enum([
-  'auto-resolve',
-  'defer',
-  'spawn-resolver',
-  'abandon',
-  'escalate',
-]);
-
-export const WorkspaceKindSchema = z.enum([
-  'new_stream',           // agent gets its own stream
-  'attach_to_team_root',  // agent works on team root stream
-  'share_with_agent',     // agent shares another agent's worktree (ref-counted)
-  'share_parent_cwd',     // agent inherits spawner's cwd (no isolation)
-  'none',                 // no workspace; agent has no streaming concerns
-]);
-
-export const AllocationSchema = z.enum([
-  'new_worktree',
-  'inherit_parent_cwd',
-  'pooled_worktree',
-]);
-
-export const OnParentAdvancedSchema = z.enum([
-  'sync_with_parent',
-  'none',
-]);
-
-export const OnTeamCompleteSchema = z.enum([
-  'keep',
-  'merge_to_main',
-  'abandon',
-]);
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Schemas
-// ─────────────────────────────────────────────────────────────────────────────
-
-export const RoleWorkspaceConfigSchema = z.object({
-  workspace: WorkspaceKindSchema,
-  stream_lineage: StreamLineageSchema.optional(),
-  allocation: AllocationSchema.optional(),
-
-  // Landing
-  landing: LandingStrategyNameSchema.optional(),
-  landing_config: z.record(z.string(), z.unknown()).optional(),
-
-  // Conflict handling at landing time
-  on_conflict: ConflictStrategyNameSchema.optional(),
-  on_conflict_recovery: ConflictRecoveryStrategyNameSchema.optional(),
-  conflict_recovery_config: z.record(z.string(), z.unknown()).optional(),
-
-  // Cascade behavior
-  cascade_on_parent_update: z.boolean().optional(),
-  on_parent_advanced: OnParentAdvancedSchema.optional(),
-
-  // Cross-role references
-  share_with: z.string().optional(),   // role name (for workspace: share_with_agent)
-  track_branch: z.string().optional(), // branch name (for stream_lineage: track_existing_branch)
-
-  // Capabilities granted to this role for MCP tool gating
-  capabilities: z.array(z.string()).optional(),
-}).superRefine((val, ctx) => {
-  if (val.workspace === 'share_with_agent' && !val.share_with) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['share_with'],
-      message: 'share_with is required when workspace = share_with_agent',
-    });
-  }
-  if (val.stream_lineage === 'track_existing_branch' && !val.track_branch) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['track_branch'],
-      message: 'track_branch is required when stream_lineage = track_existing_branch',
-    });
-  }
-  if (val.workspace === 'new_stream' && !val.stream_lineage) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['stream_lineage'],
-      message: 'stream_lineage is required when workspace = new_stream',
-    });
-  }
-});
-
-export const PoolConfigSchema = z.object({
-  enabled: z.boolean().default(true),
-  max_size: z.number().int().positive().default(10),
-  reuse_across_streams: z.boolean().default(false),
-});
-
-export const DefaultStreamConfigSchema = z.object({
-  fork_from: z.string().default('main'),
-  name_template: z.string().default('{team}'),
-  change_id_tracking: z.boolean().default(true),
-});
-
-export const ConflictRecoveryTeamConfigSchema = z.object({
-  default_strategy: ConflictRecoveryStrategyNameSchema.default('defer'),
-  default_config: z.record(z.string(), z.unknown()).optional(),
-  escalation_target: z.string().optional(),
-  max_recovery_depth: z.number().int().positive().default(3),
-});
-
-export const TeamWorkspaceConfigSchema = z.object({
-  default_stream: DefaultStreamConfigSchema.optional(),
-  on_team_complete: OnTeamCompleteSchema.default('keep'),
-  pool: PoolConfigSchema.optional(),
-  roles: z.record(z.string(), RoleWorkspaceConfigSchema),
-  conflict_recovery: ConflictRecoveryTeamConfigSchema.optional(),
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Types (inferred)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type StreamLineage = z.infer<typeof StreamLineageSchema>;
-export type LandingStrategyName = z.infer<typeof LandingStrategyNameSchema>;
-export type ConflictStrategyName = z.infer<typeof ConflictStrategyNameSchema>;
-export type ConflictRecoveryStrategyName = z.infer<typeof ConflictRecoveryStrategyNameSchema>;
-export type WorkspaceKind = z.infer<typeof WorkspaceKindSchema>;
-export type Allocation = z.infer<typeof AllocationSchema>;
-export type OnParentAdvanced = z.infer<typeof OnParentAdvancedSchema>;
-export type OnTeamComplete = z.infer<typeof OnTeamCompleteSchema>;
-export type RoleWorkspaceConfig = z.infer<typeof RoleWorkspaceConfigSchema>;
-export type PoolConfig = z.infer<typeof PoolConfigSchema>;
-export type DefaultStreamConfig = z.infer<typeof DefaultStreamConfigSchema>;
-export type ConflictRecoveryTeamConfig = z.infer<typeof ConflictRecoveryTeamConfigSchema>;
-export type TeamWorkspaceConfig = z.infer<typeof TeamWorkspaceConfigSchema>;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Parsing helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse and validate a `macro_agent.workspace` block from a team manifest.
- *
- * Returns `null` when the block is absent (indicating no workspace isolation
- * is configured for the team). Throws on validation failure with a helpful
- * error message.
- */
-export function parseTeamWorkspaceConfig(
-  raw: unknown
-): TeamWorkspaceConfig | null {
-  if (raw === undefined || raw === null) return null;
-  const result = TeamWorkspaceConfigSchema.safeParse(raw);
-  if (!result.success) {
-    const issues = result.error.issues
-      .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
-      .join('\n');
-    throw new Error(
-      `Invalid macro_agent.workspace configuration:\n${issues}`
-    );
-  }
-  return result.data;
-}
-
-/**
- * Extract the workspace block from a loaded openteams `TeamManifest`.
- *
- * openteams treats `macro_agent` as `Record<string, unknown>` — macro-agent
- * owns the schema inside.
- */
-export function extractWorkspaceConfig(
-  manifest: { macro_agent?: Record<string, unknown> }
-): TeamWorkspaceConfig | null {
-  const workspaceRaw = manifest.macro_agent?.workspace;
-  return parseTeamWorkspaceConfig(workspaceRaw);
-}

package/test_fixtures/README.md

@@ -1,425 +0,0 @@
-# Test Fixtures
-
-Testing infrastructure for multi-agent orchestration scenarios.
-
-> Multi-Agent Orchestration Testing Strategy
-
-## Overview
-
-This directory provides a complete testing framework for:
-- **Simulated agents** that execute behavior scripts without real LLM calls
-- **Temporary repositories** for isolated git operations
-- **Event-driven stepping** for deterministic test execution
-- **Built-in assertions** for common test scenarios
-
-## Directory Structure
-
-```
-test_fixtures/
-├── fixtures/           # Reusable test data and configurations
-│   ├── behaviors/      # Agent behavior scripts
-│   │   ├── workers.ts      # Worker behaviors (successful, failing, stuck, etc.)
-│   │   ├── coordinators.ts # Coordinator behaviors
-│   │   ├── integrators.ts  # Integrator behaviors
-│   │   └── monitors.ts     # Monitor behaviors
-│   ├── projects/       # Project templates
-│   │   └── typescript-project.ts
-│   ├── repos/          # Repository utilities
-│   │   └── temp-repo-factory.ts
-│   └── opentasks/      # OpenTasks fixtures
-│       └── issues.ts
-│
-├── harness/            # Test harness implementation
-│   ├── test-harness.ts # Main TestHarness class
-│   ├── simulator/      # Agent simulation
-│   │   ├── agent-simulator.ts   # Simulated agent
-│   │   ├── behavior-executor.ts # Step execution
-│   │   └── types.ts             # Type definitions
-│   ├── timing/         # Execution control
-│   │   └── event-stepper.ts     # Deterministic stepping
-│   ├── assertions/     # Test assertions
-│   │   └── harness-assertions.ts
-│   └── __tests__/      # Self-tests for harness
-│
-└── README.md           # This file
-```
-
-## Quick Start
-
-### Basic Test Setup
-
-```typescript
-import { describe, it, expect, afterEach } from "vitest";
-import { createTestHarness, SUCCESSFUL_WORKER } from "../test_fixtures";
-
-describe("my test", () => {
-  let harness: TestHarness;
-
-  afterEach(async () => {
-    await harness?.cleanup();
-  });
-
-  it("should run a worker", async () => {
-    harness = await createTestHarness();
-    await harness.createTempRepo();
-
-    const worker = await harness.spawnSimulator({
-      role: "worker",
-      behavior: SUCCESSFUL_WORKER,
-    });
-
-    await harness.waitForSimulator(worker.agentId);
-
-    harness.assertSimulatorComplete(worker.agentId);
-    harness.assertAgentTerminated(worker.agentId);
-  });
-});
-```
-
-## TestHarness
-
-The `TestHarness` is the main orchestrator for multi-agent tests. It manages:
-- Services (EventStore, MessageRouter, TaskManager)
-- Repositories (temporary git repos, worktrees)
-- Simulators (spawning, stepping, waiting)
-- Assertions (agent state, task status, git state)
-
-### Creating a Harness
-
-```typescript
-// Basic harness
-const harness = await createTestHarness();
-
-// With merge queue support
-const harness = await createTestHarness({ withMergeQueue: true });
-
-// With workspace/worktree support
-const harness = await createTestHarness({ withWorkspaces: true });
-```
-
-### Harness Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `inMemory` | `boolean` | `true` | Use in-memory EventStore |
-| `withMergeQueue` | `boolean` | `false` | Enable merge queue support |
-| `withWorkspaces` | `boolean` | `false` | Enable worktree management |
-
-## Agent Simulator
-
-Simulates agent behavior without LLM calls. Executes a behavior script step-by-step.
-
-### SimulatedBehavior
-
-```typescript
-interface SimulatedBehavior {
-  /** Steps to execute when agent starts */
-  onStart: BehaviorStep[];
-
-  /** Event handlers (keyed by event name) */
-  onEvent?: Record<string, BehaviorStep[]>;
-
-  /** Conditional behaviors evaluated continuously */
-  conditions?: ConditionalBehavior[];
-
-  /** Fail after N steps (for testing error handling) */
-  failAfter?: number;
-  failWith?: Error | string;
-
-  /** Delay between steps */
-  stepDelayMs?: number;
-
-  /** Maximum execution time */
-  timeoutMs?: number;
-}
-```
-
-### Behavior Steps
-
-| Step Type | Description | Example |
-|-----------|-------------|---------|
-| `log` | Log a message | `{ type: "log", message: "Starting" }` |
-| `write_file` | Write content to file | `{ type: "write_file", path: "foo.txt", content: "bar" }` |
-| `read_file` | Read file into variable | `{ type: "read_file", path: "foo.txt", into: "content" }` |
-| `commit` | Git commit | `{ type: "commit", message: "Add feature" }` |
-| `done` | Complete with status | `{ type: "done", status: "completed", summary: "Done" }` |
-| `emit_signal` | Emit a signal | `{ type: "emit_signal", signal: "progress", payload: { pct: 50 } }` |
-| `wait_for_event` | Wait for event | `{ type: "wait_for_event", event: "ASSIGNED" }` |
-| `wait_for_condition` | Wait for condition | `{ type: "wait_for_condition", condition: (ctx) => ctx.stepCount > 5 }` |
-| `call_tool` | Call MCP tool | `{ type: "call_tool", tool: "done", params: { status: "completed" } }` |
-| `spawn_child` | Spawn child agent | `{ type: "spawn_child", role: "worker", behavior: WORKER }` |
-| `sleep` | Sleep for duration | `{ type: "sleep", ms: 100 }` |
-| `conditional` | Conditional branching | `{ type: "conditional", if: fn, then: [...], else: [...] }` |
-| `assert` | Runtime assertion | `{ type: "assert", condition: fn, message: "failed" }` |
-
-### Done Status Values
-
-| Status | Description |
-|--------|-------------|
-| `completed` | Work finished successfully |
-| `failed` | Work failed with error |
-| `blocked` | Waiting on external dependency |
-| `deferred` | Work postponed for later |
-
-## Pre-built Behaviors
-
-### Workers
-
-```typescript
-import {
-  SUCCESSFUL_WORKER,      // Writes file, commits, completes
-  FAILING_WORKER,         // Starts then fails
-  STUCK_WORKER,           // Waits forever (timeout testing)
-  BLOCKED_WORKER,         // Completes with blocked status
-  DEFERRED_WORKER,        // Defers work
-  SIGNALING_WORKER,       // Emits progress signals
-  MULTI_COMMIT_WORKER,    // Creates multiple commits
-  HELP_EMITTING_WORKER,   // Emits HELP signal
-  RESOLVER_WORKER,        // Resolves conflicts
-} from "../test_fixtures";
-
-// Factory functions
-createWorker(steps, options)
-createConflictingWorker(filePath, content, commitMessage)
-createUniqueFileWorker(workerId, content)
-createResolverWorker(filePath, resolvedContent, commitMessage)
-```
-
-### Coordinators
-
-```typescript
-import {
-  PLANNING_COORDINATOR,       // Plans and spawns workers
-  WAITING_COORDINATOR,        // Waits for workers
-  CONDITIONAL_COORDINATOR,    // Conditional logic
-  EVENT_HANDLING_COORDINATOR, // Handles events
-  TASK_CREATING_COORDINATOR,  // Creates tasks
-  SIMPLE_COORDINATOR,         // Minimal coordinator
-} from "../test_fixtures";
-
-createMultiWorkerCoordinator(workerCount)
-```
-
-### Integrators
-
-```typescript
-import {
-  BASIC_INTEGRATOR,       // Simple merge processing
-  CONFLICT_RESOLVER,      // Handles conflicts
-  BATCH_INTEGRATOR,       // Batch merge processing
-  VALIDATING_INTEGRATOR,  // Validates before merge
-  CONTINUOUS_INTEGRATOR,  // Continuous processing
-  FAILING_INTEGRATOR,     // Fails during merge
-} from "../test_fixtures";
-```
-
-### Monitors
-
-```typescript
-import {
-  HEALTH_CHECK_MONITOR,  // Health checking
-  GUPP_MONITOR,          // Global Update Progress Protocol
-  PROGRESS_MONITOR,      // Progress tracking
-  TIMEOUT_MONITOR,       // Timeout detection
-  RESOURCE_MONITOR,      // Resource monitoring
-  PERSISTENT_MONITOR,    // Long-running monitor
-} from "../test_fixtures";
-```
-
-## Execution Control
-
-### Stepping
-
-The harness uses deterministic stepping for reliable tests:
-
-```typescript
-// Step all simulators once
-await harness.stepAll();
-
-// Run until all simulators are idle
-await harness.runUntilIdle();
-
-// Wait for specific simulator
-await harness.waitForSimulator(agentId);
-
-// Wait for all simulators
-await harness.waitForAll();
-
-// Wait for custom condition
-await harness.waitForCondition(() => harness.getSimulatorCount() >= 3);
-```
-
-### Options
-
-```typescript
-await harness.waitForSimulator(agentId, {
-  timeoutMs: 5000,     // Max wait time
-  maxIterations: 100,  // Max step iterations
-});
-```
-
-## Assertions
-
-### Agent Assertions
-
-```typescript
-harness.assertAgentTerminated(agentId);
-harness.assertAgentState(agentId, "running" | "stopped" | "paused");
-harness.assertSimulatorComplete(agentId);
-harness.assertExecutedStep(agentId, "commit");
-```
-
-### Task Assertions
-
-```typescript
-harness.assertTaskStatus(taskId, "pending" | "assigned" | "in_progress" | "completed" | "failed");
-```
-
-### Message Assertions
-
-```typescript
-harness.assertMessagesReceived(agentId, minCount);
-harness.assertMessageReceived(agentId, "pattern" | /regex/);
-```
-
-### Git Assertions
-
-```typescript
-harness.assertBranchExists("feature/foo");
-harness.assertBranchMerged("feature/foo", "main");
-harness.assertCleanWorkingTree();
-harness.assertCommitCount("main", 5);
-harness.assertFileExists("src/index.ts");
-harness.assertFileContains("src/index.ts", "export");
-```
-
-### Merge Queue Assertions (requires `withMergeQueue: true`)
-
-```typescript
-harness.assertMergeRequestStatus(mrId, "pending" | "processing" | "merged" | "conflict");
-harness.assertTaskMergeRequestStatus(taskId, status);
-harness.assertMergeQueueDepth(streamId, expectedDepth);
-harness.assertMergeRequestMerged(mrId);
-harness.assertMergeRequestConflict(mrId, expectedFiles);
-```
-
-### Worktree Assertions (requires `withWorkspaces: true`)
-
-```typescript
-harness.assertWorktreeExists(worktreePath);
-harness.assertAgentHasWorktree(agentId);
-harness.assertWorktreeBranch(worktreePath, "feature/foo");
-harness.assertWorktreeClean(worktreePath);
-harness.assertWorktreeFileExists(worktreePath, "src/index.ts");
-harness.assertWorktreeFileContains(worktreePath, "src/index.ts", "export");
-```
-
-## Repository Management
-
-### Temporary Repositories
-
-```typescript
-const repo = await harness.createTempRepo();
-
-// With initial files
-const repo = await harness.createTempRepo({
-  files: {
-    "src/index.ts": "export const x = 1;",
-    "package.json": '{ "name": "test" }',
-  },
-});
-
-// Access repo
-const repo = harness.getRepo();
-repo.git("status");
-repo.writeFile("foo.txt", "content");
-repo.path; // Absolute path to repo
-```
-
-### Worktrees (requires `withWorkspaces: true`)
-
-```typescript
-const worktreePath = harness.createWorktreeForAgent(agentId, "feature/foo", {
-  baseBranch: "main",
-  streamId: "stream-1",
-});
-
-harness.getWorktreePath(agentId);
-harness.removeWorktree(agentId);
-```
-
-## Merge Queue (requires `withMergeQueue: true`)
-
-```typescript
-// Submit merge request
-const mrId = harness.submitMergeRequest({
-  streamId: "stream-1",
-  taskId: "task-1",
-  agentId: "agent-1",
-  branch: "feature/foo",
-  targetBranch: "main",
-});
-
-// Process next request
-harness.processNextMergeRequest("stream-1");
-
-// Process with simulated conflict
-harness.processNextMergeRequest("stream-1", {
-  simulateConflict: true,
-  conflictFiles: ["shared.ts"],
-});
-
-// Process all requests
-harness.processAllMergeRequests("stream-1");
-
-// Check queue depth
-harness.getMergeQueueDepth("stream-1");
-```
-
-## Example: Multi-Worker Test
-
-```typescript
-it("should coordinate multiple workers", async () => {
-  harness = await createTestHarness({ withMergeQueue: true });
-  await harness.createTempRepo();
-
-  // Spawn coordinator
-  const coordinator = await harness.spawnSimulator({
-    role: "coordinator",
-    behavior: createMultiWorkerCoordinator(3),
-  });
-
-  // Run until all complete
-  await harness.waitForAll({ maxIterations: 500 });
-
-  // Verify all workers completed
-  const workers = harness.getAllSimulators()
-    .filter(s => s.role === "worker");
-
-  expect(workers).toHaveLength(3);
-  workers.forEach(w => {
-    harness.assertSimulatorComplete(w.agentId);
-  });
-
-  // Verify all merge requests processed
-  harness.assertMergeQueueDepth("default", 0);
-});
-```
-
-## Running Harness Tests
-
-```bash
-# Run harness self-tests
-npm test -- test_fixtures/harness/__tests__
-
-# Run specific test file
-npm test -- test_fixtures/harness/__tests__/test-harness-and-assertions.test.ts
-```
-
-## Best Practices
-
-1. **Always call `cleanup()`** in `afterEach` to avoid resource leaks
-2. **Use pre-built behaviors** when possible for consistency
-3. **Use deterministic stepping** instead of timers for reliable tests
-4. **Create custom behaviors** with factory functions for parameterization
-5. **Check assertions in order** - agent state before task state before git state