macro-agent 0.1.7 → 0.1.10

package/src/boot-v2.ts

@@ -121,6 +121,52 @@ export interface BootV2Config {
     };
   };
 
+  /**
+   * Cascade event binding config. Controls how cascade events emitted by
+   * git-cascade-backed agents get tagged with external task references for
+   * hub projection (changelog, task↔stream binding). Independent of MAP
+   * transport: cascade events are data/identity, not transport.
+   */
+  cascade?: {
+    /**
+     * Default OpenTasks resource ID for this swarm. When set, the agent
+     * manager auto-builds `taskRef = { resource_id, node_id: task_id }`
+     * for spawned agents so cascade events carry the binding without
+     * callers constructing refs by hand.
+     *
+     * Leave undefined if:
+     *   - The swarm touches multiple opentasks graphs (use `resolveTaskRef`).
+     *   - Every caller sets `SpawnAgentOptions.taskRef` explicitly.
+     *   - You don't care about hub task↔stream binding.
+     */
+    taskResourceId?: string;
+
+    /**
+     * Custom resolver for multi-graph deployments. Called at every spawn;
+     * return a `TaskRef` to set the binding or `undefined` to skip.
+     * Precedence: explicit `SpawnAgentOptions.taskRef` > `resolveTaskRef` >
+     * `taskResourceId` fallback (combined with `spawnOptions.task_id`).
+     *
+     * Keep implementations cheap — this runs on every spawn.
+     *
+     * @example
+     *   resolveTaskRef: (opts) => {
+     *     const graph = graphForCwd(opts.cwd ?? process.cwd());
+     *     return graph ? { resource_id: graph.resourceId, node_id: String(opts.task_id) } : undefined;
+     *   }
+     */
+    resolveTaskRef?: (
+      spawnOptions: import("./agent/types.js").SpawnAgentOptions
+    ) => import("git-cascade/events").TaskRef | undefined;
+
+    /**
+     * Override the default `x-cascade` event prefix. Useful for branded
+     * deployments or isolating cascade namespaces in testing. Affects all
+     * events emitted by the tracker embedded in this swarm.
+     */
+    eventPrefix?: string;
+  };
+
   /** minimem (agent memory) — registers as MCP server for all agents */
   minimem?: {
     enabled?: boolean;
@@ -270,6 +316,8 @@ export async function bootV2(
       serverUrl: config.serverUrl,
       serverToken: config.serverToken,
       controlSocketPath,
+      taskResourceId: config.cascade?.taskResourceId,
+      resolveTaskRef: config.cascade?.resolveTaskRef,
     }
   );
 
@@ -344,23 +392,25 @@ export async function bootV2(
   }, HEALTH_CHECK_INTERVAL_MS);
   healthCheckTimer.unref(); // Don't prevent process exit
 
+  // Shared mutable system reference — passed to ACP server, MAP server, API server.
+  // Components created before the sidecar (steps 9-11) receive this object.
+  // When the sidecar is created (step 13), it's attached here so all components
+  // see it via the same reference (e.g., ACP handler accessing system.mapSidecar).
+  const systemRef = {
+    agentManager,
+    agentStore,
+    inboxAdapter,
+    tasksAdapter,
+    triggerSystem,
+    controlServer,
+    roleRegistry,
+    controlSocketPath,
+  } as any;
+
   // 9. REST API server (optional)
   let apiServer: ApiServer | null = null;
   if (config.api?.enabled) {
     const { createApiServer } = await import("./api/server.js");
-    // Build a partial system reference for the API server.
-    // The full system object is returned below; we create the API server
-    // first so it can be included in the return value and shut down cleanly.
-    const systemRef = {
-      agentManager,
-      agentStore,
-      inboxAdapter,
-      tasksAdapter,
-      triggerSystem,
-      controlServer,
-      roleRegistry,
-      controlSocketPath,
-    } as any;
     apiServer = createApiServer(systemRef, {
       port: config.api.port,
       host: config.api.host,
@@ -373,17 +423,7 @@ export async function bootV2(
   if (config.acp?.enabled) {
     const { createWebSocketACPServer } = await import("./acp/websocket-server.js");
     acpServer = createWebSocketACPServer(
-      // Pass a partial system ref (the full object is built below)
-      {
-        agentManager,
-        agentStore,
-        inboxAdapter,
-        tasksAdapter,
-        triggerSystem,
-        controlServer,
-        roleRegistry,
-        controlSocketPath,
-      } as any,
+      systemRef,
       {
         port: config.acp.port,
         host: config.acp.host,
@@ -404,17 +444,7 @@ export async function bootV2(
           agentStore,
           inboxAdapter,
           tasksAdapter,
-          // Pass partial system ref for ACP-over-MAP bridge
-          system: {
-            agentManager,
-            agentStore,
-            inboxAdapter,
-            tasksAdapter,
-            triggerSystem,
-            controlServer,
-            roleRegistry,
-            controlSocketPath,
-          } as any,
+          system: systemRef,
         },
         {
           port: config.mapServer.port,
@@ -468,8 +498,27 @@ export async function bootV2(
   if (config.map?.enabled && config.map.server) {
     try {
       const { createMAPSidecar } = await import("./map/sidecar.js");
+      // If a workspace manager is present, pull out its GitCascadeAdapter
+      // so the sidecar can forward cascade events to the hub.
+      const wsMgr = config.workspaceManager as
+        | {
+            getGitCascadeAdapter?: () =>
+              | import("./workspace/git-cascade-adapter.js").GitCascadeAdapter
+              | undefined;
+          }
+        | undefined;
+      const gitCascadeAdapter = wsMgr?.getGitCascadeAdapter?.();
       mapSidecar = createMAPSidecar(
-        { agentManager, agentStore, inboxAdapter, tasksAdapter },
+        {
+          agentManager,
+          agentStore,
+          inboxAdapter,
+          tasksAdapter,
+          getLocalMapId: mapServerInstance
+            ? (id: string) => mapServerInstance!.getLocalMapId(id)
+            : undefined,
+          gitCascadeAdapter,
+        },
         {
           server: config.map.server,
           token: config.map.token,
@@ -487,6 +536,8 @@ export async function bootV2(
       await mapSidecar.start();
       // Wire sidecar into agent manager for session-end checkpoints
       agentManager.setSidecar(mapSidecar);
+      // Attach to shared system ref so ACP/MAP handlers can access it
+      systemRef.mapSidecar = mapSidecar;
     } catch (err) {
       // Non-fatal — MAP hub connectivity is optional
       console.warn(

package/src/cli/index.ts

@@ -498,6 +498,67 @@ program
     }
   });
 
+// ─────────────────────────────────────────────────────────────────
+// Run Team Command (Phase 10)
+// ─────────────────────────────────────────────────────────────────
+
+program
+  .command("run <teamName>")
+  .description("Boot the system, start a team by name, and optionally prompt the root agent")
+  .option("--task <task>", "Task to prompt the root agent with")
+  .option("--cwd <path>", "Working directory for agents")
+  .option("--base-path <path>", "Base path for team YAML lookup (default: cwd)")
+  .action(async (teamName: string, options: { task?: string; cwd?: string; basePath?: string }) => {
+    const cwd = options.cwd ?? process.cwd();
+    console.log(chalk.blue(`Booting macro-agent and starting team: ${teamName}`));
+
+    let system: Awaited<ReturnType<typeof bootV2>> | null = null;
+    try {
+      system = await bootV2({ cwd });
+      console.log(chalk.green("System booted."));
+
+      // Construct & install a TeamManagerV2; start the requested team.
+      const { TeamManagerV2 } = await import("../teams/team-manager-v2.js");
+      const teamManager = new TeamManagerV2({
+        agentManager: system.agentManager,
+        inboxAdapter: system.inboxAdapter,
+        tasksAdapter: system.tasksAdapter,
+      });
+      teamManager.install();
+
+      const instanceId = await teamManager.startTeam(teamName, options.basePath ?? cwd);
+      console.log(chalk.green(`Team started: ${teamName} (instance ${instanceId})`));
+
+      // Find the root agent (first spawned agent in the instance)
+      const agents = system.agentStore.listAgents({ state: "running" });
+      const root = agents[0];
+
+      if (options.task && root) {
+        console.log(chalk.gray(`Prompting root agent (${root.id}) with task...`));
+        const iter = system.agentManager.prompt(root.id, options.task);
+        for await (const chunk of iter) {
+          process.stdout.write(typeof chunk === "string" ? chunk : JSON.stringify(chunk));
+        }
+        console.log();
+      } else if (!root) {
+        console.log(chalk.yellow("No root agent found to prompt."));
+      }
+
+      console.log(chalk.gray("Press Ctrl+C to shut down."));
+
+      // Graceful shutdown on SIGINT
+      process.on("SIGINT", async () => {
+        console.log(chalk.yellow("\nShutting down..."));
+        if (system) await system.shutdown();
+        process.exit(0);
+      });
+    } catch (error) {
+      console.error(chalk.red(`Failed to run team: ${error}`));
+      if (system) await system.shutdown();
+      process.exit(1);
+    }
+  });
+
 // ─────────────────────────────────────────────────────────────────
 // Parse and Run
 // ─────────────────────────────────────────────────────────────────

package/src/cognitive/__tests__/macro-agent-backend.test.ts

@@ -126,13 +126,31 @@ describe("MacroAgentBackend", () => {
 
   describe("spawn", () => {
     it("spawns analyst via agentManager", async () => {
-      const session = await backend.spawn({
+      // Use a deferred promise so promptUntilDone hangs, keeping session in "running"
+      let resolvePrompt!: () => void;
+      const hangingPrompt = new Promise<void>((r) => { resolvePrompt = r; });
+
+      const am = createMockAgentManager({
+        promptUntilDone: vi.fn().mockImplementation(async () => {
+          await hangingPrompt;
+          return {
+            doneCalled: true,
+            doneStatus: "completed",
+            exceededMax: false,
+            followUpCount: 0,
+            updates: [],
+          };
+        }),
+      });
+      const b = new MacroAgentBackend(am);
+
+      const session = await b.spawn({
         agentType: "claude-code",
         task: { description: "Analyze trajectory" },
         cwd: "/workspace",
       });
 
-      expect(agentManager.spawn).toHaveBeenCalledWith(
+      expect(am.spawn).toHaveBeenCalledWith(
         expect.objectContaining({
           task: "Analyze trajectory",
           role: "analyst",
@@ -143,6 +161,9 @@ describe("MacroAgentBackend", () => {
       expect(session.state).toBe("running");
       expect(session.agentType).toBe("claude-code");
       expect(session.task.description).toBe("Analyze trajectory");
+
+      // Let the hanging prompt resolve to avoid dangling promises
+      resolvePrompt();
     });
 
     it("returns session with unique ID", async () => {
@@ -382,17 +403,38 @@ describe("MacroAgentBackend", () => {
 
   describe("terminate", () => {
     it("terminates the macro-agent process", async () => {
-      const session = await backend.spawn({
+      // Use a deferred promise so promptUntilDone hangs until after terminate
+      let resolvePrompt!: () => void;
+      const hangingPrompt = new Promise<void>((r) => { resolvePrompt = r; });
+
+      const am = createMockAgentManager({
+        promptUntilDone: vi.fn().mockImplementation(async () => {
+          await hangingPrompt;
+          return {
+            doneCalled: true,
+            doneStatus: "completed",
+            exceededMax: false,
+            followUpCount: 0,
+            updates: [],
+          };
+        }),
+      });
+      const b = new MacroAgentBackend(am);
+
+      const session = await b.spawn({
         agentType: "claude-code",
         task: { description: "test" },
       });
 
-      await backend.terminate(session.id);
+      await b.terminate(session.id);
 
-      expect(agentManager.terminate).toHaveBeenCalledWith(
+      expect(am.terminate).toHaveBeenCalledWith(
         "agent_test123",
         "cancelled",
       );
+
+      // Let the hanging prompt resolve to avoid dangling promises
+      resolvePrompt();
     });
 
     it("sets session to failed", async () => {

package/src/cognitive/macro-agent-backend.ts

@@ -240,6 +240,46 @@ export class MacroAgentBackend {
     const timeout = config.timeout;
     let softTimer: ReturnType<typeof setTimeout> | undefined;
     let hardTimer: ReturnType<typeof setTimeout> | undefined;
+    let completionNotified = false;
+
+    // Helper: fire the completion callback + inbox notification exactly once.
+    // Called from both the hard-timer path and the finally block to avoid a
+    // race where waitForSession returns (state != "running") before finally
+    // runs and fires the callback.
+    const notifyCompletion = async (): Promise<void> => {
+      if (completionNotified) return;
+      if (session.state !== "completed" && session.state !== "failed") return;
+      completionNotified = true;
+
+      const completeEvent: SessionCompleteEvent = {
+        sessionId: session.id,
+        agentId: agentId as string,
+        state: session.state,
+        duration_ms: session.endTime
+          ? session.endTime.getTime() - session.startTime.getTime()
+          : 0,
+        message_count: session.messages.length,
+        tool_call_count: session.toolCalls.length,
+      };
+
+      this.onSessionComplete?.(completeEvent);
+
+      if (this.inboxAdapter) {
+        try {
+          await this.inboxAdapter.send(
+            agentId as string,
+            agentId as string,
+            {
+              type: "session.complete",
+              sessionId: session.id,
+              state: session.state,
+              duration_ms: completeEvent.duration_ms,
+              outcome: session.state === "completed" ? "success" : "failure",
+            },
+          );
+        } catch { /* best-effort */ }
+      }
+    };
 
     try {
       if (timeout && timeout > 0) {
@@ -263,6 +303,9 @@ export class MacroAgentBackend {
           session.state = "failed";
           session.error = "Timeout exceeded";
           session.endTime = new Date();
+          // Fire completion callback immediately — the finally block's
+          // deferred callback could race with waitForSession returning.
+          void notifyCompletion();
           this.agentManager.terminate(agentId, "timeout").catch(() => {});
         }, timeout);
       }
@@ -307,35 +350,8 @@ export class MacroAgentBackend {
       }
 
       // Notify completion (no trajectory extraction — OpenHive handles that via sessionlog)
-      if (session.state === "completed" || session.state === "failed") {
-        const completeEvent: SessionCompleteEvent = {
-          sessionId: session.id,
-          agentId: agentId as string,
-          state: session.state,
-          duration_ms: session.endTime
-            ? session.endTime.getTime() - session.startTime.getTime()
-            : 0,
-          message_count: session.messages.length,
-          tool_call_count: session.toolCalls.length,
-        };
-
-        this.onSessionComplete?.(completeEvent);
-
-        if (this.inboxAdapter) {
-          await this.inboxAdapter.send(
-            agentId as string,
-            agentId as string,
-            {
-              type: "session.complete",
-              sessionId: session.id,
-              state: session.state,
-              duration_ms: completeEvent.duration_ms,
-              outcome: session.state === "completed" ? "success" : "failure",
-            },
-            { subject: "session.complete" },
-          ).catch(() => {});
-        }
-      }
+      // This is a no-op if the hard-timer path already fired it.
+      await notifyCompletion();
 
       // Clean up agent process
       if (session.state !== "running") {

package/src/integrations/skilltree.ts

@@ -55,6 +55,7 @@ async function loadSkillTree(): Promise<any> {
   _loadAttempted = true;
 
   try {
+    // @ts-ignore - optional peer dependency, may not be installed
     _skillTreeModule = await import("skill-tree");
     return _skillTreeModule;
   } catch {

package/src/lifecycle/cleanup.ts

@@ -124,15 +124,45 @@ export function detectCleanupStatus(
 // =============================================================================
 
 /**
- * Commit all uncommitted changes in a workspace
+ * Optional handle for routing commits through git-cascade so the resulting
+ * commit gets a Change-Id trailer and emits an `x-cascade/stream.committed`
+ * event. When omitted, commits are made via raw git (no Change-Id, no
+ * cascade event) — used by legacy/null-workspace paths.
+ */
+export interface TrackedCommitHandle {
+  /** WorkspaceManager-style commitChanges signature */
+  commitChanges(opts: {
+    streamId: string;
+    agentId: string;
+    worktree: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+  }): { commit: string; changeId: string };
+  /** Stream this commit belongs to */
+  streamId: string;
+  /** Agent making the commit */
+  agentId: string;
+  /** Optional metadata threaded into the cascade event (e.g. `{ task_ref }`) */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Commit all uncommitted changes in a workspace.
+ *
+ * When a `TrackedCommitHandle` is supplied, the commit goes through
+ * git-cascade's tracker — gaining a stable Change-Id trailer and emitting
+ * `x-cascade/stream.committed` so OpenHive sees the work. Without a handle,
+ * falls back to raw git (legacy behavior).
  *
  * @param workspacePath - Path to the workspace
  * @param message - Commit message
+ * @param tracked - Optional handle to commit via the cascade tracker
  * @returns Commit hash if successful, undefined if nothing to commit
  */
 export function commitChanges(
   workspacePath: string,
-  message: string
+  message: string,
+  tracked?: TrackedCommitHandle
 ): string | undefined {
   try {
     // Check if there are changes to commit
@@ -140,7 +170,26 @@ export function commitChanges(
       return undefined;
     }
 
-    // Stage all changes
+    // Tracked path: stage + commit through git-cascade so Change-Id +
+    // x-cascade events fire.
+    if (tracked) {
+      try {
+        const { commit } = tracked.commitChanges({
+          streamId: tracked.streamId,
+          agentId: tracked.agentId,
+          worktree: workspacePath,
+          message,
+          metadata: tracked.metadata,
+        });
+        return commit;
+      } catch {
+        // Fall through to raw-git path on tracker failure (e.g., stream
+        // conflicted) so callers still get a commit. Caveat: no Change-Id
+        // and no cascade event in this fallback.
+      }
+    }
+
+    // Raw-git path: stage all changes
     execFileSync("git", ["add", "--all"], {
       cwd: workspacePath,
       encoding: "utf-8",

package/src/lifecycle/handlers-v2.ts

@@ -22,8 +22,9 @@ import type {
   CleanupStatus,
   DoneHandlerResult,
 } from "./types.js";
-import { commitChanges, attemptMerge, abortMerge } from "./cleanup.js";
+import { commitChanges, attemptMerge, abortMerge, type TrackedCommitHandle } from "./cleanup.js";
 import type { MergeQueueInterface } from "../workspace/merge-queue/types.js";
+import type { WorkspaceManager } from "../workspace/types.js";
 import {
   getAllDescendants,
   needsCascadeTermination,
@@ -40,6 +41,40 @@ export interface HandlerDepsV2 {
   agentManager: AgentManager;
   taskMode?: "push" | "pull";
   mergeQueue?: MergeQueueInterface;
+  /**
+   * Optional workspace manager. When provided AND `context.streamId` is set,
+   * commits route through the cascade tracker (Change-Id + x-cascade events).
+   * Without it, commits use raw git (legacy / null-workspace path).
+   */
+  workspaceManager?: WorkspaceManager;
+}
+
+// =============================================================================
+// Tracked Commit Helper
+// =============================================================================
+
+/**
+ * Build a TrackedCommitHandle when the agent has a streamId + workspaceManager.
+ * Returns undefined if either is missing — caller falls back to raw git.
+ */
+function buildTrackedHandle(
+  context: LifecycleContext,
+  deps: HandlerDepsV2
+): TrackedCommitHandle | undefined {
+  if (!context.streamId || !deps.workspaceManager) return undefined;
+  const ws = deps.workspaceManager;
+  // Build metadata with task_ref if known. Empty object is fine — the hub
+  // ignores unknown fields, and back-fill kicks in if task_ref appears later.
+  const metadata: Record<string, unknown> = {};
+  if (context.taskRef) {
+    metadata.task_ref = context.taskRef;
+  }
+  return {
+    streamId: context.streamId,
+    agentId: context.agentId,
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    commitChanges: (opts) => ws.commitChanges(opts),
+  };
 }
 
 // =============================================================================
@@ -110,10 +145,12 @@ async function handleWorkerDone(
         ? `WIP: ${args.summary}`
         : `WIP: Auto-commit from done() with ${uncommittedCount} uncommitted file(s)`;
 
-      const commitHash = commitChanges(context.workspacePath, commitMessage);
+      const tracked = buildTrackedHandle(context, deps);
+      const commitHash = commitChanges(context.workspacePath, commitMessage, tracked);
       if (commitHash) {
+        const via = tracked ? "tracker" : "raw-git";
         cleanupActions.push(
-          `Committed ${uncommittedCount} file(s): ${commitHash.slice(0, 8)}`
+          `Committed ${uncommittedCount} file(s) via ${via}: ${commitHash.slice(0, 8)}`
         );
       } else {
         warnings.push("Failed to auto-commit uncommitted changes");

package/src/lifecycle/types.ts

@@ -9,6 +9,7 @@
  */
 
 import type { AgentId, TaskId } from "../store/types/index.js";
+import type { TaskRef } from "git-cascade/events";
 
 // =============================================================================
 // Done Status Types
@@ -120,6 +121,17 @@ export interface LifecycleContext {
 
   /** Resolved capabilities for the agent's role (for capability-based handler dispatch) */
   capabilities?: string[];
+
+  /**
+   * Optional reference to an external task this agent is working on. When
+   * present, threaded into commit metadata so cascade events carry the
+   * binding (enabling task↔stream queries on the OpenHive hub).
+   *
+   * Sourced from `SpawnAgentOptions.taskRef` at spawn time and propagated
+   * via the agent manager. Late-binding (mid-session pull-mode claim) can
+   * mutate this on the live context.
+   */
+  taskRef?: TaskRef;
 }
 
 /**