macro-agent 0.0.10 → 0.0.12

package/src/teams/types.ts

@@ -0,0 +1,377 @@
+/**
+ * Team Template Types
+ *
+ * TypeScript types for the team manifest schema. Generic multi-agent fields
+ * (name, roles, topology, communication) are separated from macro-agent
+ * specific extensions under the `macro_agent` namespace for interoperability.
+ *
+ * @module teams/types
+ */
+
+import type { RoleDefinition, Capability } from "../roles/types.js";
+
+// =============================================================================
+// Core Manifest
+// =============================================================================
+
+/**
+ * Fully resolved team manifest.
+ *
+ * Returned by TeamLoader.load() with all inheritance resolved,
+ * capabilities computed, and prompts loaded.
+ */
+export interface TeamManifest {
+  /** Team name (directory name) */
+  name: string;
+
+  /** Human-readable description */
+  description: string;
+
+  /** Schema version */
+  version: number;
+
+  /** Role names used by this team */
+  roles: string[];
+
+  /** Agent spawn topology */
+  topology: TeamTopology;
+
+  /** Communication topology */
+  communication: TeamCommunication;
+
+  /** macro-agent specific extensions */
+  macro_agent: MacroAgentExtensions;
+
+  // ─────────────────────────────────────────────────────────────
+  // Resolved state (populated by TeamLoader, not in YAML)
+  // ─────────────────────────────────────────────────────────────
+
+  /** Resolved role definitions keyed by role name */
+  _resolvedRoles: Map<string, ResolvedTeamRole>;
+
+  /** Loaded prompt contents keyed by file path */
+  _loadedPrompts: Map<string, string>;
+
+  /** Loaded MCP server configs keyed by role name */
+  _mcpServers: Map<string, McpServerEntry[]>;
+}
+
+// =============================================================================
+// Topology
+// =============================================================================
+
+/**
+ * Defines the agent spawn graph for the team.
+ */
+export interface TeamTopology {
+  /** The initial agent spawned when the team starts */
+  root: TopologyNode;
+
+  /** Agents spawned alongside root (peers, not children) */
+  companions?: TopologyNode[];
+
+  /**
+   * Which roles can spawn which other roles.
+   * Translated into capability additions by TeamLoader (RD3).
+   */
+  spawn_rules?: Record<string, string[]>;
+}
+
+/**
+ * A node in the team's spawn topology.
+ */
+export interface TopologyNode {
+  /** Role name (must be in manifest.roles) */
+  role: string;
+
+  /** Path to prompt file relative to team directory */
+  prompt?: string;
+
+  /** Agent configuration */
+  config?: TopologyNodeConfig;
+}
+
+export interface TopologyNodeConfig {
+  /** Model to use (e.g., "sonnet", "haiku", "opus") */
+  model?: string;
+
+  /** Additional key-value config passed to agent */
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Communication
+// =============================================================================
+
+/**
+ * Communication topology for the team.
+ *
+ * Declares channels (signal groups), per-role subscriptions,
+ * emission restrictions, and routing rules.
+ */
+export interface TeamCommunication {
+  /** Named signal channels */
+  channels?: Record<string, ChannelDefinition>;
+
+  /** Per-role subscription declarations */
+  subscriptions?: Record<string, ChannelSubscription[]>;
+
+  /** Per-role emission declarations (which signals a role can emit) */
+  emissions?: Record<string, string[]>;
+
+  /** Routing configuration */
+  routing?: CommunicationRouting;
+
+  /** Enforcement level for communication rules */
+  enforcement?: CommunicationEnforcement;
+}
+
+export type CommunicationEnforcement = "strict" | "permissive" | "audit";
+
+/**
+ * A named channel grouping related signals.
+ */
+export interface ChannelDefinition {
+  /** Human-readable description */
+  description?: string;
+
+  /** Signals in this channel */
+  signals: string[];
+}
+
+/**
+ * A role's subscription to a channel.
+ */
+export interface ChannelSubscription {
+  /** Channel name (must exist in communication.channels) */
+  channel: string;
+
+  /** Specific signals to receive. If omitted, receives all signals in the channel */
+  signals?: string[];
+}
+
+/**
+ * Communication routing configuration.
+ */
+export interface CommunicationRouting {
+  /** Status flow direction */
+  status?: "upstream";
+
+  /** Explicit peer connections (non-hierarchical) */
+  peers?: PeerConnection[];
+}
+
+/**
+ * A peer-to-peer connection between two roles.
+ */
+export interface PeerConnection {
+  /** Source role name */
+  from: string;
+
+  /** Target role name */
+  to: string;
+
+  /** Routing mechanism */
+  via: "direct" | "topic" | "scope";
+
+  /** Signals allowed on this connection */
+  signals?: string[];
+}
+
+// =============================================================================
+// macro-agent Extensions
+// =============================================================================
+
+/**
+ * macro-agent specific team configuration.
+ *
+ * Namespaced under `macro_agent` in team.yaml for interoperability.
+ */
+export interface MacroAgentExtensions {
+  /** Task assignment configuration */
+  task_assignment?: TaskAssignmentConfig;
+
+  /** Integration strategy configuration */
+  integration?: IntegrationConfig;
+
+  /** Agent lifecycle configuration */
+  lifecycle?: LifecycleConfig;
+
+  /** Observability configuration */
+  observability?: ObservabilityConfig;
+}
+
+export interface TaskAssignmentConfig {
+  /** Assignment mode */
+  mode: "push" | "pull";
+
+  /** Pull-mode specific settings */
+  pull?: {
+    /** Seconds before idle worker self-terminates */
+    idle_timeout_s?: number;
+    /** Milliseconds between claim retries */
+    claim_retry_delay_ms?: number;
+    /** Max concurrent task claims per agent */
+    max_concurrent_per_agent?: number;
+  };
+}
+
+export interface IntegrationConfig {
+  /** Strategy name: 'queue' | 'trunk' | 'optimistic' | custom name */
+  strategy: string;
+
+  /** Strategy-specific configuration passed to strategy.initialize() */
+  config?: Record<string, unknown>;
+}
+
+export interface LifecycleConfig {
+  /** Session continuation settings */
+  continuations?: {
+    enabled: boolean;
+    max_history_messages?: number;
+    checkpoint_interval?: "round_trip" | "none";
+  };
+
+  /** Worker scaling settings */
+  scaling?: {
+    min_workers?: number;
+    max_workers?: number;
+    scale_on?: "task_queue_depth" | "manual";
+    idle_drain?: boolean;
+  };
+}
+
+export interface ObservabilityConfig {
+  /** Sliding window for metric computation (seconds) */
+  metrics_window_s?: number;
+  /** Interval between metric snapshots (seconds) */
+  snapshot_interval_s?: number;
+}
+
+// =============================================================================
+// Team Role Definition
+// =============================================================================
+
+/**
+ * Role definition as declared in a team template's roles/*.yaml file.
+ *
+ * Supports both full replacement and additive/subtractive capability composition.
+ */
+export interface TeamRoleDefinition {
+  /** Role name */
+  name: string;
+
+  /** Built-in role to extend */
+  extends?: string;
+
+  /** Display name for UI/logs */
+  display_name?: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  /**
+   * Full replacement capability list.
+   * Mutually exclusive with add/remove.
+   */
+  capabilities?: string[];
+
+  /**
+   * Capabilities to add to the parent role's set.
+   * Only valid when `extends` is set.
+   */
+  capabilities_add?: string[];
+
+  /**
+   * Capabilities to remove from the parent role's set.
+   * Only valid when `extends` is set.
+   */
+  capabilities_remove?: string[];
+
+  /** Path to prompt file relative to team directory */
+  prompt?: string;
+
+  /** macro-agent specific role configuration */
+  macro_agent?: TeamRoleMacroAgent;
+}
+
+export interface TeamRoleMacroAgent {
+  /** Workspace configuration */
+  workspace?: {
+    type?: string;
+    branch_pattern?: string;
+    cleanup_on_terminate?: boolean;
+  };
+
+  /** Lifecycle configuration */
+  lifecycle?: {
+    type?: "ephemeral" | "persistent" | "daemon" | "event-driven";
+    cascade_terminate?: boolean;
+    self_cleanup?: boolean;
+    task_bound?: boolean;
+    parent_bound?: boolean;
+    max_duration_ms?: number;
+  };
+}
+
+// =============================================================================
+// Resolved Types
+// =============================================================================
+
+/**
+ * A team role with inheritance resolved and capabilities computed.
+ */
+export interface ResolvedTeamRole {
+  /** Role name */
+  name: string;
+
+  /** The built-in role this extends */
+  baseRole: string;
+
+  /** Final computed capability set */
+  capabilities: Capability[];
+
+  /** Loaded prompt content (if prompt file specified) */
+  prompt?: string;
+
+  /** Full RoleDefinition for RoleRegistry registration */
+  roleDefinition: RoleDefinition;
+}
+
+// =============================================================================
+// MCP Server Config
+// =============================================================================
+
+/**
+ * MCP server entry from tools/mcp-servers.json.
+ * Follows Claude Code's native format.
+ */
+export interface McpServerEntry {
+  name: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+// =============================================================================
+// Team Loading Errors
+// =============================================================================
+
+export type TeamLoadErrorCode =
+  | "MANIFEST_NOT_FOUND"
+  | "INVALID_MANIFEST"
+  | "ROLE_NOT_FOUND"
+  | "PROMPT_NOT_FOUND"
+  | "INVALID_COMMUNICATION"
+  | "INVALID_ROLE";
+
+export class TeamLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly code: TeamLoadErrorCode,
+    public readonly teamName?: string
+  ) {
+    super(message);
+    this.name = "TeamLoadError";
+  }
+}

package/src/trigger/router/trigger-router.ts

@@ -1,8 +1,35 @@
 /**
- * Trigger Router Implementation
+ * TriggerRouter - External Event Routing
  *
- * Routes trigger events to appropriate agents using pluggable
- * routing strategies. Manages strategy registration and selection.
+ * ## Routing Architecture Role
+ *
+ * TriggerRouter handles **external system events** (webhooks, cron, etc.)
+ * and routes them to appropriate agents using pluggable strategies.
+ *
+ * ```
+ * External Events → TriggerRouter → SystemEventQueue → WakeManager → Agent
+ * (webhooks, cron)   (this)         (queueing)         (delivery)
+ * ```
+ *
+ * **Responsibilities:**
+ * - Route external events to target agents via configurable strategies
+ * - Queue events for deferred delivery (SystemEventQueue)
+ * - Support multiple routing strategies (direct, head, role-based, etc.)
+ * - Trigger wake cycles for sleeping agents
+ *
+ * **Routing Strategies:**
+ * - direct: Route to specific agent ID
+ * - head: Route to coordinator/head of hierarchy
+ * - role: Route to agents by role
+ * - broadcast: Fan-out to multiple agents
+ *
+ * **Differs from MessageRouter:**
+ * - TriggerRouter: External events → agents (one-way, queued)
+ * - MessageRouter: Agent ↔ agent communication (bidirectional, immediate)
+ *
+ * **Differs from MAPAdapter:**
+ * - TriggerRouter: System events (webhooks, cron, internal signals)
+ * - MAPAdapter: MAP protocol clients (external agents, UIs)
  *
  * @module trigger/router/trigger-router
  */

package/src/trigger/wake/types.ts

@@ -4,6 +4,25 @@
  * Types for the wake manager that handles polling agents
  * with pending events and delivering them.
  *
+ * ## Wake System Architecture
+ *
+ * There are two wake mechanisms in macro-agent:
+ *
+ * 1. **Single-Agent Wake** (agent/wake.ts, activity/types.ts)
+ *    - For immediately waking a single agent with an Activity
+ *    - Priority-driven (urgent/high/normal/low)
+ *    - Uses inject/interrupt fallback chain
+ *    - Returns `WakeResult` (success: boolean, method: WakeMethod)
+ *
+ * 2. **Batch Wake Cycles** (trigger/wake/*)
+ *    - For periodic delivery of queued system events
+ *    - Heartbeat-based polling with coalescing
+ *    - Processes all agents with pending events
+ *    - Returns `WakeCycleStatus` (status: ran/skipped/failed)
+ *
+ * Use single-agent wake for: Immediate message delivery, activity notifications
+ * Use batch wake cycles for: Scheduled event delivery, system-wide polling
+ *
  * @module trigger/wake/types
  */
 
@@ -28,9 +47,12 @@ export interface WakeRequest {
 }
 
 /**
- * Result of a wake operation
+ * Status of a batch wake cycle.
+ *
+ * Note: This is different from `WakeResult` in activity/types.ts which
+ * represents the outcome of waking a single agent.
  */
-export interface WakeResult {
+export interface WakeCycleStatus {
   status: "ran" | "skipped" | "failed";
   /** Duration if ran */
   durationMs?: number;
@@ -40,10 +62,15 @@ export interface WakeResult {
   wokenAgents?: AgentId[];
 }
 
+/**
+ * @deprecated Use WakeCycleStatus instead. Renamed for clarity.
+ */
+export type WakeResult = WakeCycleStatus;
+
 /**
  * Wake handler function type
  */
-export type WakeHandler = (opts: { reason?: string }) => Promise<WakeResult>;
+export type WakeHandler = (opts: { reason?: string }) => Promise<WakeCycleStatus>;
 
 /**
  * Wake manager configuration
@@ -80,9 +107,9 @@ export interface TriggerWakeManager {
   /**
    * Run a single wake cycle immediately
    * @param opts - Optional reason for the cycle
-   * @returns Wake result
+   * @returns Wake cycle status
    */
-  runWakeCycle(opts?: { reason?: string }): Promise<WakeResult>;
+  runWakeCycle(opts?: { reason?: string }): Promise<WakeCycleStatus>;
 
   /**
    * Start the wake manager (enables heartbeat if configured)

package/src/trigger/wake/wake-manager.ts

@@ -18,7 +18,7 @@ import type {
   TriggerWakeManager,
   WakeManagerConfig,
   WakeRequest,
-  WakeResult,
+  WakeCycleStatus,
   WakeCycleResult,
   AgentDrainResult,
 } from "./types.js";
@@ -325,7 +325,7 @@ export function createWakeManager(
       return pendingReason !== null || Boolean(coalesceTimer) || scheduled;
     },
 
-    async runWakeCycle(opts?: { reason?: string }): Promise<WakeResult> {
+    async runWakeCycle(opts?: { reason?: string }): Promise<WakeCycleStatus> {
       if (wakingInProgress) {
         return { status: "skipped", reason: "wake-in-progress" };
       }

package/src/workspace/dataplane-adapter.ts

@@ -29,7 +29,7 @@ import {
   type Checkpoint,
   workerTasks,
   diffStacks,
-} from 'dataplane';
+} from 'git-cascade';
 import type { DataplaneConfig } from './config.js';
 import { DEFAULT_DATAPLANE_CONFIG } from './config.js';
 

package/src/workspace/index.ts

@@ -107,4 +107,4 @@ export type {
   ListTasksOptions,
   CleanupWorkerBranchesOptions,
   CleanupResult,
-} from 'dataplane';
+} from 'git-cascade';

package/src/workspace/strategies/index.ts

@@ -0,0 +1,18 @@
+export type {
+  IntegrationStrategy,
+  IntegrationStrategyFactory,
+  LandRequest,
+  LandResult,
+  LandResultStatus,
+  QueueStrategyConfig,
+  TrunkStrategyConfig,
+  OptimisticStrategyConfig,
+} from "./types.js";
+export { QueueIntegrationStrategy } from "./queue.js";
+export { TrunkIntegrationStrategy } from "./trunk.js";
+export { OptimisticIntegrationStrategy } from "./optimistic.js";
+export {
+  IntegrationStrategyRegistry,
+  createDefaultStrategyRegistry,
+  defaultStrategyRegistry,
+} from "./registry.js";

package/src/workspace/strategies/optimistic.ts

@@ -0,0 +1,136 @@
+/**
+ * Optimistic Integration Strategy
+ *
+ * Push immediately and emit a validation event. Does NOT run build/test —
+ * validation is the judge agent's responsibility (RD5).
+ *
+ * Uses the same rebase-and-retry logic as trunk for handling push conflicts.
+ *
+ * @module workspace/strategies/optimistic
+ */
+
+import { execSync } from "child_process";
+import type {
+  IntegrationStrategy,
+  LandRequest,
+  LandResult,
+  OptimisticStrategyConfig,
+} from "./types.js";
+import type { EventStore } from "../../store/event-store.js";
+
+export class OptimisticIntegrationStrategy implements IntegrationStrategy {
+  readonly name = "optimistic";
+  private maxRetries: number;
+  private eventStore?: EventStore;
+
+  constructor(config?: Record<string, unknown>) {
+    const typedConfig = config as OptimisticStrategyConfig | undefined;
+    this.maxRetries = typedConfig?.maxRetries ?? 3;
+  }
+
+  /**
+   * Set the EventStore for emitting validation events.
+   * Called after construction since EventStore may not be available at strategy creation time.
+   */
+  setEventStore(store: EventStore): void {
+    this.eventStore = store;
+  }
+
+  async land(request: LandRequest): Promise<LandResult> {
+    const { workspacePath, targetBranch } = request;
+    let retryCount = 0;
+
+    while (retryCount <= this.maxRetries) {
+      try {
+        // Fetch latest
+        this.git(workspacePath, `fetch origin ${targetBranch}`);
+
+        // Rebase onto latest
+        try {
+          this.git(workspacePath, `rebase origin/${targetBranch}`);
+        } catch {
+          try {
+            this.git(workspacePath, "rebase --abort");
+          } catch {
+            /* already clean */
+          }
+
+          if (retryCount >= this.maxRetries) {
+            return {
+              status: "conflict",
+              retryCount,
+              error: `Rebase conflict after ${retryCount + 1} attempts`,
+            };
+          }
+          retryCount++;
+          continue;
+        }
+
+        // Push optimistically
+        try {
+          this.git(workspacePath, `push origin HEAD:${targetBranch}`);
+        } catch {
+          if (retryCount >= this.maxRetries) {
+            return {
+              status: "conflict",
+              retryCount,
+              error: `Push rejected after ${retryCount + 1} attempts`,
+            };
+          }
+          retryCount++;
+          continue;
+        }
+
+        const commitHash = this.git(workspacePath, "rev-parse HEAD").trim();
+
+        // Emit validation:requested event (RD5 — judge handles validation)
+        if (this.eventStore) {
+          try {
+            this.eventStore.emit({
+              type: "status",
+              source: { agent_id: request.agentId },
+              payload: {
+                status_type: "checkpoint",
+                summary: `Validation requested for ${commitHash.slice(0, 8)}`,
+                validation_requested: true,
+                commitHash,
+                sourceBranch: request.sourceBranch,
+                targetBranch,
+                taskId: request.taskId,
+                agentId: request.agentId,
+              },
+            });
+          } catch {
+            // Never fail land() due to event emission failure
+          }
+        }
+
+        return {
+          status: "landed",
+          commitHash,
+          retryCount,
+        };
+      } catch (error) {
+        return {
+          status: "failed",
+          retryCount,
+          error: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    }
+
+    return {
+      status: "failed",
+      retryCount,
+      error: "Exceeded maximum retries",
+    };
+  }
+
+  private git(cwd: string, args: string): string {
+    return execSync(`git ${args}`, {
+      cwd,
+      encoding: "utf-8",
+      timeout: 30000,
+    });
+  }
+}