macro-agent 0.1.8 → 0.1.10

package/src/agent/agent-manager.ts

@@ -131,6 +131,12 @@ export interface AgentManager {
    */
   listHeadManagers(): Agent[];
 
+  /**
+   * Look up the SpawnedAgent shape for any agent (any role) that's running
+   * AND has a live session in this process. Returns null otherwise.
+   */
+  getActiveAgentSession(agentId: AgentId): SpawnedAgent | null;
+
   // ── Session Interaction ────────────────────────────────────────
 
   /**
@@ -296,6 +302,14 @@ export interface AgentManager {
    */
   setSidecar(sidecar: { connected: boolean; reportCheckpoint(cp: any): Promise<any> } | null): void;
 
+  /**
+   * Set a TopologyPolicy for workspace allocation decisions.
+   * When set, AgentManagerV2 delegates `createWorkspaceForRole` to the policy
+   * before falling back to role-name dispatch. Set by boot-v2 when team YAML
+   * contains `macro_agent.workspace`.
+   */
+  setTopologyPolicy(policy: import('../workspace/topology/types.js').TopologyPolicy | null): void;
+
   // ── Cleanup ────────────────────────────────────────────────────
 
   /**

package/src/agent/types.ts

@@ -15,6 +15,7 @@ import type {
   StreamConfig,
   Workspace,
 } from "../workspace/types.js";
+import type { TaskRef } from "git-cascade/events";
 
 // ─────────────────────────────────────────────────────────────────
 // Spawn Options
@@ -90,16 +91,29 @@ export interface SpawnAgentOptions {
   streamConfig?: StreamConfig;
 
   /**
-   * Dataplane task ID to claim (for workers).
+   * git-cascade task ID to claim (for workers).
    * If provided, the worker will claim this task and work on it.
    */
-  dataplaneTaskId?: string;
+  gitCascadeTaskId?: string;
 
   /**
    * Resolved capabilities for this agent's role.
    * Injected by TeamRuntime spawn interceptor for capability-based workspace dispatch.
    */
   capabilities?: string[];
+
+  /**
+   * Optional reference to an external task this agent is working on. When
+   * set, the reference is woven into cascade event metadata so OpenHive (or
+   * any other observer) can bind the agent's commits, merges, and streams
+   * to the OpenTasks node. Propagates through:
+   *   - stream creation: `adapter.createStream({ metadata: { task_ref } })`
+   *   - commits: `adapter.commitChanges({ metadata: { task_ref } })` (pass
+   *     per-commit; each commit can carry a distinct sub-task binding)
+   * Can also arrive late via pull-mode `claim_task` — workers that claim a
+   * task mid-session should include the ref on subsequent commits.
+   */
+  taskRef?: TaskRef;
 }
 
 /**

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,
     }
   );
 
@@ -450,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,

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/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;
 }
 
 /**