macro-agent 0.1.10 → 0.1.12

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

@@ -75,6 +75,48 @@ describe('landing strategies', () => {
         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', () => {

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

@@ -81,6 +81,7 @@ export class MergeToParentStrategy implements LandingStrategy {
         targetStreamId,
         agentId: ctx.agentId,
         worktree: mergeWorktree.path,
+        metadata: ctx.taskRef ? { task_ref: ctx.taskRef } : undefined,
       });
 
       // Cascade rebase on dependents if requested.

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

@@ -70,7 +70,8 @@ export class SpawnResolverStrategy implements ConflictRecoveryStrategy {
       };
     }
 
-    // Spawn the resolver
+    // 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 = {
@@ -78,6 +79,12 @@ export class SpawnResolverStrategy implements ConflictRecoveryStrategy {
         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;

package/src/workspace/types-v3.ts

@@ -124,6 +124,13 @@ export interface LandingContext {
   streamId: StreamId;
   sourceWorktree: string;
   targetStreamId?: StreamId;
+  /**
+   * Strategy selector. Accepts either an internal strategy name
+   * (`merge-to-parent`, `queue-to-branch`, …) or the YAML form
+   * (`merge_to_parent_stream`, `queue_to_branch`, …). `WorkspaceManager.land`
+   * normalizes. When undefined, `merge-to-parent` is used.
+   */
+  strategyName?: string;
   strategyConfig?: Record<string, unknown>;
   /** Reference to the manager; strategies call back for merge/cascade. */
   workspaceManager: unknown; // WorkspaceManager — circular; narrowed at callsite

package/src/workspace/types.ts

@@ -353,12 +353,17 @@ export interface WorkspaceManager {
 
   /**
    * Merge a source stream into a target stream.
+   *
+   * `metadata` is forwarded into the `x-cascade/stream.merged` emit so
+   * consumers (e.g., the OpenHive hub) can bind the merge to a task ref.
+   * Landing strategies pass `{ task_ref: ctx.taskRef }` through here.
    */
   mergeStream(opts: {
     sourceStreamId: StreamId;
     targetStreamId: StreamId;
     agentId: import('./types-v3.js').Principal;
     worktree: string;
+    metadata?: import('git-cascade/events').EventMetadata;
   }): import('./types-v3.js').MergeResult;
 
   /**
@@ -422,6 +427,21 @@ export interface WorkspaceManager {
    */
   registerLandingStrategy(strategy: import('./types-v3.js').LandingStrategy): void;
 
+  /**
+   * Dispatch a landing. Resolves the strategy by `ctx.strategyName`
+   * (defaulting to `merge-to-parent`), accepts both internal and YAML-style
+   * names, and invokes the strategy's `land(ctx)`. Strategies call back
+   * into this manager via `ctx.workspaceManager`, which is filled in here.
+   *
+   * Returns the strategy's `MergeResult`. Conflicts are reflected in the
+   * result (`success: false` + `conflicts: [...]`); thrown errors indicate
+   * unrecoverable failures (unknown strategy, strategy rejected context,
+   * transport-level issues).
+   */
+  land(
+    ctx: import('./types-v3.js').LandingContext,
+  ): Promise<import('./types-v3.js').MergeResult>;
+
   /**
    * Run macro-level reconciliation:
    * - Delegates to git-cascade's `reconcile()` for stream↔git sync.

package/src/workspace/workspace-manager.ts

@@ -1107,9 +1107,18 @@ export class DefaultWorkspaceManager implements WorkspaceManager {
     targetStreamId: StreamId;
     agentId: import('./types-v3.js').Principal;
     worktree: string;
+    /**
+     * Free-form metadata forwarded into the `x-cascade/stream.merged` emit.
+     * The canonical binding is `{ task_ref: { resource_id, node_id } }` —
+     * landing strategies thread `LandingContext.taskRef` through here so the
+     * hub's cascade_merges projection records which task drove the merge.
+     */
+    metadata?: import('git-cascade/events').EventMetadata;
   }): import('./types-v3.js').MergeResult {
-    // git-cascade's MergeStreamOptions uses `sourceStream`/`targetStream`.
-    // We adapt to v3's `sourceStreamId`/`targetStreamId` at the boundary.
+    // git-cascade's MergeStreamOptions uses `sourceStream`/`targetStream` and
+    // doesn't accept an opts.metadata field — the tagging is our concern, not
+    // the tracker's. Carry `opts.metadata` through on the emitted event
+    // instead, which is what the hub's cascade_merges projection reads.
     const result = this.adapter.mergeStream({
       sourceStream: opts.sourceStreamId,
       targetStream: opts.targetStreamId,
@@ -1121,6 +1130,7 @@ export class DefaultWorkspaceManager implements WorkspaceManager {
         sourceStreamId: opts.sourceStreamId,
         targetStreamId: opts.targetStreamId,
         mergeCommit: result.newHead,
+        ...(opts.metadata ? { metadata: opts.metadata } : {}),
       });
     } else {
       this.emit('stream:conflicted', {
@@ -1295,6 +1305,31 @@ export class DefaultWorkspaceManager implements WorkspaceManager {
     this.landingStrategies.set(strategy.name, strategy);
   }
 
+  async land(
+    ctx: import('./types-v3.js').LandingContext,
+  ): Promise<import('./types-v3.js').MergeResult> {
+    const internalName = resolveLandingStrategyName(ctx.strategyName);
+    if (internalName === 'none') {
+      return { success: true, alreadyMerged: true } as import('./types-v3.js').MergeResult;
+    }
+    const strategy = this.landingStrategies.get(internalName);
+    if (!strategy) {
+      throw new Error(
+        `No landing strategy registered for "${internalName}" (from ctx.strategyName="${ctx.strategyName ?? 'merge-to-parent'}"). Registered: ${Array.from(this.landingStrategies.keys()).join(', ') || '<none>'}.`,
+      );
+    }
+    const resolved: import('./types-v3.js').LandingContext = {
+      ...ctx,
+      workspaceManager: this,
+    };
+    if (strategy.canLand && !strategy.canLand(resolved)) {
+      throw new Error(
+        `Landing strategy "${internalName}" rejected context for agent ${ctx.agentId}, stream ${ctx.streamId}`,
+      );
+    }
+    return strategy.land(resolved);
+  }
+
   reconcileV3(): import('./types-v3.js').MacroReconcileResult {
     const result: import('./types-v3.js').MacroReconcileResult = {
       streamsChecked: 0,
@@ -1516,3 +1551,27 @@ export function createWorkspaceManagerWithAdapter(
 ): DefaultWorkspaceManager {
   return new DefaultWorkspaceManager(adapter, config);
 }
+
+// ═════════════════════════════════════════════════════════════════════════════
+// Landing strategy name resolution
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// YAML uses snake_case (`merge_to_parent_stream`, `queue_to_branch`, …) to
+// match the team-config naming convention. Strategy classes expose
+// kebab-case internal names (`merge-to-parent`, …). `WorkspaceManager.land()`
+// accepts either and normalizes before dispatch so AgentManagerV2 can pass
+// `roleConfig.landing` directly without another translation layer.
+
+const YAML_TO_INTERNAL_LANDING: Record<string, string> = {
+  merge_to_parent_stream: 'merge-to-parent',
+  queue_to_branch: 'queue-to-branch',
+  direct_push: 'direct-push',
+  optimistic_push: 'optimistic-push',
+  cherry_pick_stack: 'cherry-pick-stack',
+  none: 'none',
+};
+
+export function resolveLandingStrategyName(input?: string): string {
+  if (!input) return 'merge-to-parent';
+  return YAML_TO_INTERNAL_LANDING[input] ?? input;
+}

package/templates/teams/self-driving/team.yaml

@@ -0,0 +1,142 @@
+name: self-driving
+description: "Cursor-style autonomous codebase development: planners explore and create tasks, grinders claim and execute in their own streams, judges evaluate quality."
+version: 1
+
+# ─────────────────────────────────────────────────────────────
+# Roles
+# ─────────────────────────────────────────────────────────────
+roles:
+  - planner
+  - grinder
+  - judge
+
+# ─────────────────────────────────────────────────────────────
+# Topology
+# ─────────────────────────────────────────────────────────────
+topology:
+  root:
+    role: planner
+    prompt: prompts/planner.md
+    config:
+      model: sonnet
+  companions:
+    - role: judge
+      prompt: prompts/judge.md
+      config:
+        model: haiku
+  spawn_rules:
+    planner: [grinder, planner]
+    judge: []
+    grinder: []
+
+# ─────────────────────────────────────────────────────────────
+# Communication
+# ─────────────────────────────────────────────────────────────
+communication:
+  enforcement: permissive
+
+  channels:
+    task_updates:
+      description: "Task lifecycle events"
+      signals: [TASK_CREATED, TASK_COMPLETED, TASK_FAILED]
+    work_coordination:
+      description: "Work assignment and completion"
+      signals: [WORK_ASSIGNED, WORKER_DONE, MERGE_REQUEST]
+    health:
+      description: "System health monitoring"
+      signals: [HEALTH_CHECK, METRIC_SNAPSHOT, GREEN_SNAPSHOT, FIXUP_CREATED]
+
+  subscriptions:
+    planner:
+      - channel: task_updates
+      - channel: work_coordination
+        signals: [WORKER_DONE]
+      - channel: health
+        signals: [METRIC_SNAPSHOT, GREEN_SNAPSHOT, FIXUP_CREATED]
+    judge:
+      - channel: task_updates
+        signals: [TASK_FAILED]
+      - channel: work_coordination
+        signals: [WORKER_DONE]
+      - channel: health
+    grinder:
+      - channel: work_coordination
+        signals: [WORK_ASSIGNED]
+
+  emissions:
+    planner: [TASK_CREATED, WORK_ASSIGNED, PLANNING_COMPLETE]
+    judge: [HEALTH_CHECK, GREEN_SNAPSHOT, FIXUP_CREATED]
+    grinder: [WORKER_DONE]
+
+  routing:
+    peers:
+      - from: judge
+        to: planner
+        via: direct
+        signals: [FIXUP_CREATED, GREEN_SNAPSHOT]
+      - from: planner
+        to: judge
+        via: direct
+        signals: [CONVERGENCE_CHECK]
+
+# ─────────────────────────────────────────────────────────────
+# macro-agent specific extensions
+# ─────────────────────────────────────────────────────────────
+macro_agent:
+  # V3 stream-first workspace topology.
+  # Compiled by YamlDrivenTopology into per-spawn WorkspaceDecision values.
+  workspace:
+    default_stream:
+      fork_from: main
+      name_template: "{team}"
+      change_id_tracking: true
+
+    on_team_complete: keep
+
+    roles:
+      # Planner shares the team root stream — continuous exploration lives on the
+      # same branch as the team's accumulated work; no per-planner fork.
+      planner:
+        workspace: attach_to_team_root
+        capabilities:
+          - workspace.read
+          - agent.spawn
+
+      # Grinders fork their own stream off the team root, land via direct-push
+      # (trunk integration). A conflict during landing aborts and leaves the
+      # stream for human / judge review.
+      grinder:
+        workspace: new_stream
+        stream_lineage: fork_from_team_root
+        landing: direct_push
+        on_conflict: defer
+        capabilities:
+          - workspace.commit
+          - workspace.land
+
+      # Judge is read-only — it observes repo state but doesn't need a
+      # workspace of its own.
+      judge:
+        workspace: none
+        capabilities:
+          - workspace.read
+
+  # Declarative shorthand read by TeamRuntimeV2.getStrategyName(). `trunk`
+  # pairs with the grinder's direct_push landing above: every task lands
+  # straight onto the team-root stream rather than going through a merge
+  # queue. Kept here as a top-level scalar so runtimes that don't parse the
+  # full V3 workspace block (env-var consumers, logs, metrics labels) still
+  # see the integration strategy.
+  integration:
+    strategy: trunk
+
+  task_assignment:
+    mode: pull
+    pull:
+      idle_timeout_s: 300
+      claim_retry_delay_ms: 2000
+      max_concurrent_per_agent: 1
+
+  observability:
+    metrics_window_s: 3600
+    snapshot_interval_s: 300

package/tsconfig.json

@@ -13,7 +13,8 @@
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "types": ["node", "better-sqlite3", "express", "js-yaml", "supertest", "ws"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts"]