macro-agent 0.0.10 → 0.0.12

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,32 @@ 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) ─────────────────────────────
+
+  /**
+   * Set mail services for conversation tracking.
+   * Used for late binding when mailService is created after AgentManager.
+   */
+  setMailServices(
+    mailService: import("../mail/mail-service.js").MailService,
+    conversationMap: import("../mail/conversation-map.js").ConversationMap
+  ): void;
+
   // ── Cleanup ────────────────────────────────────────────────────
 
   /**
@@ -280,8 +323,32 @@ export interface AgentManagerConfig {
    * with coordinator agent lifecycle.
    */
   healthCheckService?: HealthCheckService;
+
+  /**
+   * Optional MailService for conversation tracking.
+   * When provided, spawn creates task conversations and terminate closes them.
+   */
+  mailService?: import("../mail/mail-service.js").MailService;
+
+  /**
+   * Optional ConversationMap for agent-to-conversation tracking.
+   * Required when mailService is provided.
+   */
+  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
 // ─────────────────────────────────────────────────────────────────
@@ -298,8 +365,17 @@ export function createAgentManager(
     workspaceManager,
     roleRegistry = new DefaultRoleRegistry(),
     healthCheckService,
+    mailService: initialMailService,
+    conversationMap: initialConversationMap,
   } = config;
 
+  // Mutable mail services (support late binding via setMailServices)
+  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>();
 
@@ -313,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,
@@ -324,6 +405,8 @@ export function createAgentManager(
       topics = [],
       config: agentConfig,
       agentType = defaultAgentType,
+      customPrompt,
+      interactionPatterns,
       // Workspace-related fields (Phase 2)
       role,
       streamId,
@@ -352,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}`,
@@ -388,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" },
@@ -488,6 +586,52 @@ export function createAgentManager(
         role: role ?? undefined,
       });
 
+      // ─────────────────────────────────────────────────────────────────
+      // Mail: Create task conversation for this agent
+      // ─────────────────────────────────────────────────────────────────
+      if (mailService && conversationMap) {
+        try {
+          const parentConversationId = parent
+            ? conversationMap.getAgentConversation(parent) ??
+              conversationMap.getSessionConversation(parent)
+            : undefined;
+
+          const { conversationId: taskConvId } =
+            mailService.createConversation({
+              type: "task",
+              subject: task?.slice(0, 80),
+              createdBy: parent ?? agentId,
+              parentConversationId: parentConversationId,
+            });
+
+          // Join parent and child as participants
+          if (parent) {
+            mailService.joinConversation({
+              conversationId: taskConvId,
+              participantId: parent,
+              participantType: "agent",
+              role: "initiator",
+              agentId: parent,
+            });
+          }
+          mailService.joinConversation({
+            conversationId: taskConvId,
+            participantId: agentId,
+            participantType: "agent",
+            role: "worker",
+            agentId,
+          });
+
+          conversationMap.setAgentConversation(agentId, taskConvId);
+        } catch (err) {
+          // Never fail spawn due to mail errors
+          console.warn(
+            `[AgentManager] Failed to create task conversation for ${agentId}:`,
+            err
+          );
+        }
+      }
+
       // Track active session
       const activeSession: ActiveSession = {
         agentId,
@@ -628,6 +772,38 @@ export function createAgentManager(
       }
     }
 
+    // ─────────────────────────────────────────────────────────────────
+    // Mail: Close task conversation on terminate
+    // ─────────────────────────────────────────────────────────────────
+    if (mailService && conversationMap) {
+      try {
+        const convId = conversationMap.getAgentConversation(agentId);
+        if (convId) {
+          mailService.closeConversation({
+            conversationId: convId,
+            closedBy: agentId,
+            reason: reason === "completed" ? "completed" : "failed",
+          });
+        }
+        // Close any peer conversations
+        const peerConvIds =
+          conversationMap.closePeerConversationsFor(agentId);
+        for (const peerConvId of peerConvIds) {
+          mailService.closeConversation({
+            conversationId: peerConvId,
+            closedBy: agentId,
+            reason: "participant_left",
+          });
+        }
+        conversationMap.removeAgent(agentId);
+      } catch (err) {
+        console.warn(
+          `[AgentManager] Failed to close conversation for ${agentId}:`,
+          err
+        );
+      }
+    }
+
     // Emit terminate event
     eventStore.emit({
       type: "terminate",
@@ -1160,6 +1336,18 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     }
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Mail Services (Late Binding)
+  // ─────────────────────────────────────────────────────────────────
+
+  function setMailServices(
+    ms: import("../mail/mail-service.js").MailService,
+    cm: import("../mail/conversation-map.js").ConversationMap
+  ): void {
+    mailService = ms;
+    conversationMap = cm;
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Cleanup
   // ─────────────────────────────────────────────────────────────────
@@ -1189,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,
@@ -1209,6 +1478,9 @@ 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/wake.ts

@@ -4,6 +4,21 @@
  * Implements progressive waking for agents based on activity and priority.
  * Supports inject/interrupt fallback chain.
  *
+ * ## Wake System Architecture
+ *
+ * This module provides **single-agent wake** functionality:
+ * - Immediately wake a single agent with an Activity
+ * - Priority-driven decision making (urgent/high/normal/low)
+ * - Inject → Interrupt → Queue fallback chain
+ * - Returns `WakeResult` from activity/types.ts
+ *
+ * For **batch wake cycles** (periodic delivery to multiple agents),
+ * see trigger/wake/wake-manager.ts which provides:
+ * - Heartbeat-based polling
+ * - Coalesced wake requests
+ * - Queue-based event delivery
+ * - Returns `WakeCycleStatus`
+ *
  * @module agent/wake
  * @see s-9rld In-Flight Steering spec section 3.4
  */