macro-agent 0.0.11 → 0.0.13

package/src/agent/agent-manager.ts

@@ -36,6 +36,7 @@ import type {
   SystemPromptContext,
   AgentLifecycleCallback,
   AgentConfig,
+  ContinueAgentOptions,
 } from "./types.js";
 import { AgentManagerError } from "./types.js";
 import type { RoleRegistry, Capability } from "../roles/types.js";
@@ -74,8 +75,10 @@ function getSpawnCapability(childRole: string): Capability {
       // or system-level agents can spawn coordinators
       return AGENT_CAPABILITIES.SPAWN_CUSTOM;
     default:
-      // For custom roles, check against the custom spawn capability
-      return AGENT_CAPABILITIES.SPAWN_CUSTOM;
+      // For team-defined roles (e.g., "grinder"), return the specific capability
+      // (e.g., "agent.spawn.grinder"). The spawn check also accepts
+      // "agent.spawn.custom" as a generic fallback.
+      return `agent.spawn.${childRole}` as Capability;
   }
 }
 
@@ -103,6 +106,20 @@ export interface AgentManager {
    */
   resume(agentId: AgentId): Promise<SpawnedAgent>;
 
+  /**
+   * Continue a terminated agent by spawning a new agent with the same
+   * role and task, injecting the prior conversation context as a
+   * resume prefix in the system prompt.
+   *
+   * @param agentId - ID of the agent to continue
+   * @param options - Continuation options
+   * @returns The newly spawned continuation agent
+   */
+  continueAgent(
+    agentId: AgentId,
+    options?: ContinueAgentOptions
+  ): Promise<SpawnedAgent>;
+
   // ── Queries ────────────────────────────────────────────────────
 
   /**
@@ -237,6 +254,21 @@ export interface AgentManager {
    */
   onLifecycleEvent(callback: AgentLifecycleCallback): () => void;
 
+  // ── Team Integration ─────────────────────────────────────────
+
+  /**
+   * Set a spawn interceptor that transforms SpawnAgentOptions before spawning.
+   * Used by TeamRuntime to inject team topics, prompts, MCP servers, and env vars.
+   */
+  setSpawnInterceptor(
+    interceptor: SpawnInterceptor | null
+  ): void;
+
+  /**
+   * Get the RoleRegistry used by this AgentManager.
+   */
+  getRoleRegistry(): RoleRegistry;
+
   // ── Mail Services (Late Binding) ─────────────────────────────
 
   /**
@@ -305,6 +337,18 @@ export interface AgentManagerConfig {
   conversationMap?: import("../mail/conversation-map.js").ConversationMap;
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Spawn Interceptor
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Function that transforms SpawnAgentOptions before an agent is spawned.
+ * Used by TeamRuntime to inject team-specific configuration.
+ */
+export type SpawnInterceptor = (
+  options: SpawnAgentOptions
+) => SpawnAgentOptions | Promise<SpawnAgentOptions>;
+
 // ─────────────────────────────────────────────────────────────────
 // AgentManager Implementation
 // ─────────────────────────────────────────────────────────────────
@@ -329,6 +373,9 @@ export function createAgentManager(
   let mailService = initialMailService;
   let conversationMap = initialConversationMap;
 
+  // Mutable spawn interceptor (set by TeamRuntime)
+  let spawnInterceptor: SpawnInterceptor | null = null;
+
   // Active sessions tracked in memory
   const activeSessions = new Map<AgentId, ActiveSession>();
 
@@ -342,7 +389,12 @@ export function createAgentManager(
   // Lifecycle
   // ─────────────────────────────────────────────────────────────────
 
-  async function spawn(options: SpawnAgentOptions): Promise<SpawnedAgent> {
+  async function spawn(rawOptions: SpawnAgentOptions): Promise<SpawnedAgent> {
+    // Apply spawn interceptor if set (used by TeamRuntime for team context injection)
+    const options = spawnInterceptor
+      ? await spawnInterceptor(rawOptions)
+      : rawOptions;
+
     const {
       task,
       task_id,
@@ -353,6 +405,8 @@ export function createAgentManager(
       topics = [],
       config: agentConfig,
       agentType = defaultAgentType,
+      customPrompt,
+      interactionPatterns,
       // Workspace-related fields (Phase 2)
       role,
       streamId,
@@ -381,7 +435,13 @@ export function createAgentManager(
       const requiredCapability = getSpawnCapability(childRole);
       const parentRole = parentAgent.role ?? "worker";
 
-      if (!roleRegistry.hasCapability(parentRole, requiredCapability)) {
+      // Accept either the specific capability (e.g., agent.spawn.grinder)
+      // or the generic agent.spawn.custom as a fallback for non-built-in roles
+      const hasSpecific = roleRegistry.hasCapability(parentRole, requiredCapability);
+      const hasGeneric = requiredCapability !== AGENT_CAPABILITIES.SPAWN_CUSTOM &&
+        roleRegistry.hasCapability(parentRole, AGENT_CAPABILITIES.SPAWN_CUSTOM);
+
+      if (!hasSpecific && !hasGeneric) {
         throw new AgentManagerError(
           `Parent agent with role '${parentRole}' does not have capability to spawn '${childRole}' agents. ` +
             `Required capability: ${requiredCapability}`,
@@ -417,12 +477,21 @@ export function createAgentManager(
 
     let systemPrompt = generateSystemPrompt(promptContext);
 
-    // Append role-specific system prompt if defined
+    // Append role prompt: team customPrompt takes precedence over resolvedRole.systemPrompt
     const resolvedRole = roleRegistry.resolveRole(role ?? "worker");
-    if (resolvedRole.systemPrompt) {
+    if (customPrompt) {
+      systemPrompt += `\n\n# Role Instructions\n\n${customPrompt}`;
+    } else if (resolvedRole.systemPrompt) {
       systemPrompt += `\n\n# Role-Specific Instructions\n\n${resolvedRole.systemPrompt}`;
     }
 
+    // Append team interaction pattern sections (pull mode, trunk integration, etc.)
+    if (interactionPatterns && interactionPatterns.length > 0) {
+      for (const pattern of interactionPatterns) {
+        systemPrompt += `\n\n${pattern}`;
+      }
+    }
+
     eventStore.emit({
       type: "spawn",
       source: { agent_id: parent ?? "system" },
@@ -1308,10 +1377,91 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     lifecycleListeners.clear();
   }
 
+  function setSpawnInterceptor(interceptor: SpawnInterceptor | null): void {
+    spawnInterceptor = interceptor;
+  }
+
+  function getRoleRegistry(): RoleRegistry {
+    return roleRegistry;
+  }
+
+  /**
+   * Continue a terminated agent by spawning a new agent with the same
+   * role and task, injecting prior conversation context as a resume prefix.
+   */
+  async function continueAgent(
+    agentId: AgentId,
+    options?: ContinueAgentOptions
+  ): Promise<SpawnedAgent> {
+    const agent = eventStore.getAgent(agentId);
+    if (!agent) {
+      throw new AgentManagerError(
+        `Agent not found: ${agentId}`,
+        "AGENT_NOT_FOUND",
+        agentId
+      );
+    }
+
+    // Build resume context from EventStore events
+    const maxMessages = options?.maxMessages ?? 50;
+    const events = eventStore.query({
+      type: "status",
+      source_agent_id: agentId,
+      limit: maxMessages,
+    });
+
+    // Format conversation turns as resume context
+    const contextLines: string[] = [];
+    if (options?.additionalContext) {
+      contextLines.push(options.additionalContext);
+    }
+
+    if (events.length > 0) {
+      contextLines.push("## Prior Session Context");
+      contextLines.push(`Continuing from agent ${agentId} (${events.length} events).`);
+      for (const event of events.slice(-20)) {
+        const summary = event.payload?.summary;
+        if (summary && typeof summary === "string") {
+          contextLines.push(`- ${summary}`);
+        }
+      }
+    }
+
+    const resumeContext = contextLines.join("\n");
+
+    // Spawn a continuation agent with same role, task, and context
+    const taskDescription =
+      options?.task ??
+      agent.task ??
+      `Continue work from ${agentId}`;
+
+    const newAgent = await spawn({
+      task: taskDescription,
+      role: agent.role,
+      parent: agent.parent ?? undefined,
+      cwd: agent.cwd ?? defaultCwd,
+      customPrompt: resumeContext || undefined,
+    });
+
+    // Emit continuation event
+    eventStore.emit({
+      type: "status",
+      source: { agent_id: newAgent.id },
+      payload: {
+        status_type: "started",
+        summary: `Continuation of agent ${agentId}`,
+        continuation_of: agentId,
+      },
+    });
+
+    return newAgent;
+  }
+
   return {
     spawn,
     terminate,
     resume,
+    continueAgent,
     get,
     list,
     getChildren,
@@ -1328,6 +1478,8 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     respondToPermission,
     cancelPermission,
     onLifecycleEvent,
+    setSpawnInterceptor,
+    getRoleRegistry,
     setMailServices,
     close,
   };

package/src/agent/types.ts

@@ -51,6 +51,19 @@ export interface SpawnAgentOptions {
   /** Optional agent type (defaults to "claude-code") */
   agentType?: string;
 
+  /**
+   * Custom prompt content injected as the role instructions section.
+   * When set, replaces resolvedRole.systemPrompt in prompt assembly.
+   * Used by team templates to provide static role prompts.
+   */
+  customPrompt?: string;
+
+  /**
+   * Interaction pattern sections to append after the role prompt.
+   * Auto-generated by TeamRuntime based on team config (pull mode, etc.).
+   */
+  interactionPatterns?: string[];
+
   // ─────────────────────────────────────────────────────────────────
   // Workspace-related fields (Phase 2)
   // ─────────────────────────────────────────────────────────────────
@@ -80,6 +93,20 @@ export interface SpawnAgentOptions {
   dataplaneTaskId?: string;
 }
 
+/**
+ * Options for continuing a terminated agent
+ */
+export interface ContinueAgentOptions {
+  /** Maximum number of conversation turns to include in context (default: 50) */
+  maxMessages?: number;
+
+  /** Override the task description for the continuation */
+  task?: string;
+
+  /** Additional context to prepend to the continuation prompt */
+  additionalContext?: string;
+}
+
 /**
  * Custom agent configuration
  */

package/src/agent-detection/__tests__/command-builder.test.ts

@@ -0,0 +1,336 @@
+/**
+ * Command Builder Tests
+ */
+
+import { describe, it, expect } from "vitest";
+
+import { buildSpawnCommand, formatSpawnCommand } from "../command-builder.js";
+import { BUILTIN_AGENTS } from "../registry.js";
+import type { CLIAgentDefinition } from "../types.js";
+
+// Helper to get a built-in agent definition by ID
+function getAgent(id: string): CLIAgentDefinition {
+  const agent = BUILTIN_AGENTS.find((a) => a.id === id);
+  if (!agent) throw new Error(`Unknown agent: ${id}`);
+  return agent;
+}
+
+describe("buildSpawnCommand()", () => {
+  // ===========================================================================
+  // Claude Code
+  // ===========================================================================
+
+  describe("claude-code", () => {
+    const def = getAgent("claude-code");
+
+    it("builds basic command", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("claude");
+      expect(cmd.args).toEqual([
+        "--output-format",
+        "stream-json",
+        "-p",
+        "Fix the auth bug",
+      ]);
+    });
+
+    it("builds command with model", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "claude-sonnet-4-5",
+      });
+      expect(cmd.command).toBe("claude");
+      expect(cmd.args).toEqual([
+        "--output-format",
+        "stream-json",
+        "--model",
+        "claude-sonnet-4-5",
+        "-p",
+        "Fix the auth bug",
+      ]);
+    });
+
+    it("builds command with cwd", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        cwd: "/home/user/project",
+      });
+      expect(cmd.args).toContain("--cwd");
+      expect(cmd.args).toContain("/home/user/project");
+    });
+
+    it("builds command with model and cwd", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "claude-sonnet-4-5",
+        cwd: "/home/user/project",
+      });
+      expect(cmd.command).toBe("claude");
+      expect(cmd.args).toEqual([
+        "--output-format",
+        "stream-json",
+        "--model",
+        "claude-sonnet-4-5",
+        "--cwd",
+        "/home/user/project",
+        "-p",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // Codex
+  // ===========================================================================
+
+  describe("codex", () => {
+    const def = getAgent("codex");
+
+    it("builds basic command with positional prompt", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("codex");
+      expect(cmd.args).toEqual([
+        "exec",
+        "--full-auto",
+        "Fix the auth bug",
+      ]);
+    });
+
+    it("builds command with model and path", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "o3",
+        cwd: "/home/user/project",
+      });
+      expect(cmd.command).toBe("codex");
+      expect(cmd.args).toEqual([
+        "exec",
+        "--full-auto",
+        "--model",
+        "o3",
+        "--path",
+        "/home/user/project",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // Gemini CLI
+  // ===========================================================================
+
+  describe("gemini-cli", () => {
+    const def = getAgent("gemini-cli");
+
+    it("builds basic command", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("gemini");
+      expect(cmd.args).toEqual(["-p", "Fix the auth bug"]);
+    });
+
+    it("builds command with model (no cwd flag)", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "gemini-2.5-pro",
+        cwd: "/home/user/project",
+      });
+      expect(cmd.command).toBe("gemini");
+      // Gemini has no cwdFlag, so cwd is ignored
+      expect(cmd.args).toEqual([
+        "--model",
+        "gemini-2.5-pro",
+        "-p",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // OpenCode
+  // ===========================================================================
+
+  describe("opencode", () => {
+    const def = getAgent("opencode");
+
+    it("builds basic command with positional prompt", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("opencode");
+      expect(cmd.args).toEqual(["run", "Fix the auth bug"]);
+    });
+
+    it("builds command with model", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "gpt-4",
+      });
+      expect(cmd.args).toEqual([
+        "run",
+        "--model",
+        "gpt-4",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // Aider
+  // ===========================================================================
+
+  describe("aider", () => {
+    const def = getAgent("aider");
+
+    it("builds basic command", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("aider");
+      expect(cmd.args).toEqual([
+        "--yes",
+        "--message",
+        "Fix the auth bug",
+      ]);
+    });
+
+    it("builds command with model", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "claude-3-opus",
+      });
+      expect(cmd.args).toEqual([
+        "--yes",
+        "--model",
+        "claude-3-opus",
+        "--message",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // Goose
+  // ===========================================================================
+
+  describe("goose", () => {
+    const def = getAgent("goose");
+
+    it("builds basic command", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug");
+      expect(cmd.command).toBe("goose");
+      expect(cmd.args).toEqual([
+        "run",
+        "--no-session",
+        "-t",
+        "Fix the auth bug",
+      ]);
+    });
+
+    it("builds command with model", () => {
+      const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+        model: "claude-4-sonnet",
+      });
+      expect(cmd.args).toEqual([
+        "run",
+        "--no-session",
+        "--model",
+        "claude-4-sonnet",
+        "-t",
+        "Fix the auth bug",
+      ]);
+    });
+  });
+
+  // ===========================================================================
+  // Edge Cases
+  // ===========================================================================
+
+  describe("edge cases", () => {
+    it("throws when task is empty", () => {
+      const def = getAgent("claude-code");
+      expect(() => buildSpawnCommand(def, "")).toThrow("Task prompt is required");
+    });
+
+    it("does not add model flag when modelFlag is undefined", () => {
+      const def: CLIAgentDefinition = {
+        id: "no-model",
+        name: "No Model",
+        description: "Agent without model flag",
+        binary: "no-model",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "Test",
+        // modelFlag intentionally omitted
+      };
+      const cmd = buildSpawnCommand(def, "Do something", { model: "gpt-4" });
+      expect(cmd.args).not.toContain("--model");
+      expect(cmd.args).not.toContain("gpt-4");
+    });
+
+    it("does not add cwd flag when cwdFlag is undefined", () => {
+      const def: CLIAgentDefinition = {
+        id: "no-cwd",
+        name: "No CWD",
+        description: "Agent without cwd flag",
+        binary: "no-cwd",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "Test",
+        // cwdFlag intentionally omitted
+      };
+      const cmd = buildSpawnCommand(def, "Do something", {
+        cwd: "/tmp",
+      });
+      expect(cmd.args).not.toContain("--cwd");
+      expect(cmd.args).not.toContain("/tmp");
+    });
+
+    it("handles definition with no subcommand or default flags", () => {
+      const def: CLIAgentDefinition = {
+        id: "minimal",
+        name: "Minimal",
+        description: "Minimal agent",
+        binary: "minimal",
+        versionArgs: ["--version"],
+        headless: { promptFlag: "--prompt" },
+        vendor: "Test",
+      };
+      const cmd = buildSpawnCommand(def, "Do something");
+      expect(cmd.command).toBe("minimal");
+      expect(cmd.args).toEqual(["--prompt", "Do something"]);
+    });
+  });
+});
+
+// =============================================================================
+// formatSpawnCommand()
+// =============================================================================
+
+describe("formatSpawnCommand()", () => {
+  it("formats a command with no arguments", () => {
+    const formatted = formatSpawnCommand({
+      command: "my-agent",
+      args: [],
+    });
+    expect(formatted).toBe("my-agent");
+  });
+
+  it("formats a simple command", () => {
+    const formatted = formatSpawnCommand({
+      command: "claude",
+      args: ["-p", "hello"],
+    });
+    expect(formatted).toBe('claude -p hello');
+  });
+
+  it("quotes arguments with spaces", () => {
+    const formatted = formatSpawnCommand({
+      command: "claude",
+      args: ["-p", "Fix the auth bug", "--cwd", "/home/user/my project"],
+    });
+    expect(formatted).toBe(
+      'claude -p "Fix the auth bug" --cwd "/home/user/my project"'
+    );
+  });
+
+  it("formats a full claude-code command", () => {
+    const def = getAgent("claude-code");
+    const cmd = buildSpawnCommand(def, "Fix the auth bug", {
+      model: "claude-sonnet-4-5",
+      cwd: "/home/user/project",
+    });
+    const formatted = formatSpawnCommand(cmd);
+    expect(formatted).toBe(
+      'claude --output-format stream-json --model claude-sonnet-4-5 --cwd /home/user/project -p "Fix the auth bug"'
+    );
+  });
+});