macro-agent 0.1.0 → 0.1.1

package/src/map/adapter/connection-manager.ts

@@ -80,6 +80,7 @@ const DEFAULT_ANONYMOUS_CAPABILITIES: ParticipantCapabilities = {
   canManageScopes: false,
   canUpdatePermissions: false,
   canManageTasks: false,
+  canManageLifecycle: false,
 };
 
 /**
@@ -95,6 +96,7 @@ const DEFAULT_CLIENT_CAPABILITIES: ParticipantCapabilities = {
   canUpdatePermissions: false,
   canManageTasks: false,
   canManageFederation: false,
+  canManageLifecycle: false,
 };
 
 /**
@@ -110,6 +112,7 @@ const DEFAULT_AGENT_CAPABILITIES: ParticipantCapabilities = {
   canUpdatePermissions: false,
   canManageTasks: true,
   canManageFederation: true,
+  canManageLifecycle: true,
 };
 
 // =============================================================================

package/src/map/adapter/event-log.ts

@@ -0,0 +1,208 @@
+/**
+ * Event Log - In-memory ring buffer for MAP event replay
+ *
+ * Stores emitted MAP events for replay by newly connected clients.
+ * Events are stored in chronological order with ULID-based event IDs
+ * for keyset pagination.
+ *
+ * Event type normalization:
+ * - Server emits dot format: "agent.registered", "message.sent"
+ * - SDK sends underscore format: "agent_registered", "message_sent"
+ * - ACP-over-MAP emits underscore format: "message_delivered"
+ * - Both formats are normalized to dot format for filter comparison
+ * - Response events are converted to underscore format for the SDK
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Configuration for the event log */
+export interface EventLogConfig {
+  /** Maximum number of events to retain. Default: 10000 */
+  maxSize?: number;
+}
+
+/** A logged event entry */
+export interface LoggedEvent {
+  /** ULID event ID — stable, lexicographically sortable */
+  eventId: string;
+  /** Event timestamp (ms since epoch) */
+  timestamp: number;
+  /** Event type (dot or underscore format, as emitted) */
+  type: string;
+  /** Event-specific data payload */
+  data: unknown;
+  /** Parent event IDs for causal ordering */
+  causedBy?: string[];
+  /** Related agent ID (for filter matching) */
+  agentId?: string;
+  /** Related scope ID (for filter matching) */
+  scopeId?: string;
+}
+
+/** Filter for event log queries */
+export interface EventLogFilter {
+  /** Event types (can be underscore or dot format — normalized during comparison) */
+  eventTypes?: string[];
+  /** Agent IDs (OR within array) */
+  agents?: string[];
+  /** Scope IDs (OR within array) */
+  scopes?: string[];
+}
+
+/** Query parameters for replay */
+export interface EventLogQueryParams {
+  /** Keyset pagination cursor — start after this event ID */
+  afterEventId?: string;
+  /** Include events from this timestamp (inclusive) */
+  fromTimestamp?: number;
+  /** Include events up to this timestamp (inclusive) */
+  toTimestamp?: number;
+  /** Event filter */
+  filter?: EventLogFilter;
+  /** Maximum events to return (capped at 1000) */
+  limit?: number;
+}
+
+/** Result of an event log query */
+export interface EventLogQueryResult {
+  /** Matching events in chronological order */
+  events: LoggedEvent[];
+  /** Whether more events exist beyond this page */
+  hasMore: boolean;
+}
+
+// =============================================================================
+// Format Normalization
+// =============================================================================
+
+/** Convert underscore format to dot format: "agent_registered" → "agent.registered" */
+export function underscoreToDot(type: string): string {
+  return type.replace(/_/g, ".");
+}
+
+/** Convert dot format to underscore format: "agent.registered" → "agent_registered" */
+export function dotToUnderscore(type: string): string {
+  return type.replace(/\./g, "_");
+}
+
+// =============================================================================
+// EventLog
+// =============================================================================
+
+const DEFAULT_MAX_SIZE = 10_000;
+const MAX_QUERY_LIMIT = 1000;
+const DEFAULT_QUERY_LIMIT = 100;
+
+/**
+ * In-memory ring buffer for MAP event replay.
+ *
+ * Events are appended in emission order and oldest are evicted
+ * when the buffer exceeds maxSize.
+ */
+export class EventLog {
+  private readonly buffer: LoggedEvent[] = [];
+  private readonly maxSize: number;
+
+  constructor(config: EventLogConfig = {}) {
+    this.maxSize = config.maxSize ?? DEFAULT_MAX_SIZE;
+  }
+
+  /** Append an event to the log. O(1) amortized. */
+  append(event: LoggedEvent): void {
+    this.buffer.push(event);
+
+    // Evict oldest events if over capacity
+    if (this.buffer.length > this.maxSize) {
+      const overflow = this.buffer.length - this.maxSize;
+      this.buffer.splice(0, overflow);
+    }
+  }
+
+  /** Query events with filter and pagination. */
+  query(params: EventLogQueryParams = {}): EventLogQueryResult {
+    const limit = Math.min(params.limit ?? DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT);
+
+    // Normalize filter event types to dot format for comparison
+    const normalizedFilterTypes = params.filter?.eventTypes?.map(underscoreToDot);
+
+    let startIndex = 0;
+
+    // Handle afterEventId (keyset pagination)
+    if (params.afterEventId) {
+      const idx = this.buffer.findIndex(
+        (e) => e.eventId === params.afterEventId,
+      );
+      if (idx >= 0) {
+        startIndex = idx + 1;
+      }
+      // If not found (evicted), start from beginning
+    }
+
+    // Handle fromTimestamp (only if no afterEventId)
+    if (params.fromTimestamp != null && !params.afterEventId) {
+      const idx = this.buffer.findIndex(
+        (e) => e.timestamp >= params.fromTimestamp!,
+      );
+      if (idx >= 0) {
+        startIndex = idx;
+      } else {
+        // All events are before fromTimestamp
+        return { events: [], hasMore: false };
+      }
+    }
+
+    const results: LoggedEvent[] = [];
+
+    for (let i = startIndex; i < this.buffer.length && results.length < limit; i++) {
+      const event = this.buffer[i];
+
+      // Apply toTimestamp filter
+      if (params.toTimestamp != null && event.timestamp > params.toTimestamp) {
+        break;
+      }
+
+      // Apply event type filter (normalize stored type for comparison)
+      if (normalizedFilterTypes && normalizedFilterTypes.length > 0) {
+        const normalizedStoredType = underscoreToDot(event.type);
+        if (!normalizedFilterTypes.includes(normalizedStoredType)) {
+          continue;
+        }
+      }
+
+      // Apply agent filter (OR within array)
+      if (params.filter?.agents && params.filter.agents.length > 0) {
+        if (!event.agentId || !params.filter.agents.includes(event.agentId)) {
+          continue;
+        }
+      }
+
+      // Apply scope filter (OR within array)
+      if (params.filter?.scopes && params.filter.scopes.length > 0) {
+        if (!event.scopeId || !params.filter.scopes.includes(event.scopeId)) {
+          continue;
+        }
+      }
+
+      results.push(event);
+    }
+
+    // Determine hasMore: check if there are more matching events beyond our limit
+    let hasMore = false;
+    if (results.length === limit) {
+      // Check if there's at least one more event in the buffer after our results
+      const lastResultIndex = this.buffer.indexOf(results[results.length - 1]);
+      if (lastResultIndex >= 0 && lastResultIndex < this.buffer.length - 1) {
+        hasMore = true;
+      }
+    }
+
+    return { events: results, hasMore };
+  }
+
+  /** Number of events currently in the buffer. */
+  get size(): number {
+    return this.buffer.length;
+  }
+}

package/src/map/adapter/event-translator.ts

@@ -47,7 +47,7 @@ export interface TranslationContext {
  */
 const EVENT_TYPE_MAP: Record<EventType, MAPEventType | MAPEventType[] | null> = {
   spawn: "agent.registered",
-  terminate: "agent.unregistered",
+  stop: "agent.unregistered",
   status: "agent.state.changed",
   message: ["message.sent", "message.delivered"], // Two events for message
   task: null, // Handled specially based on payload
@@ -105,8 +105,8 @@ export function translateEvent(
     case "spawn":
       return translateSpawnEvent(event, generateEventId);
 
-    case "terminate":
-      return translateTerminateEvent(event, generateEventId);
+    case "stop":
+      return translateStopEvent(event, generateEventId);
 
     case "status":
       return translateStatusEvent(event, generateEventId);
@@ -157,15 +157,15 @@ function translateSpawnEvent(
 }
 
 /**
- * Translate terminate event to agent.unregistered.
+ * Translate stop event to agent.unregistered.
  */
-function translateTerminateEvent(
+function translateStopEvent(
   event: Event,
   generateEventId: () => string
 ): TranslationResult {
   const agentId = event.source.agent_id;
   if (!agentId) {
-    return { translated: false, reason: "Terminate event missing agent_id" };
+    return { translated: false, reason: "Stop event missing agent_id" };
   }
 
   const notification: EventNotification = {

package/src/map/adapter/extensions/agent-lifecycle.ts

@@ -0,0 +1,267 @@
+/**
+ * Agent Lifecycle Extension Methods (_macro/spawnAgent, _macro/forkAgent, etc.)
+ *
+ * Exposes agent lifecycle management to external MAP clients via direct
+ * JSON-RPC extension calls, replacing the need for ACP-over-MAP streams.
+ *
+ * Methods:
+ * - _macro/spawnAgent - Spawn a child agent
+ * - _macro/forkAgent - Fork an agent's session
+ * - _macro/setPermissionMode - Change an agent's permission mode
+ * - _macro/respondToPermission - Respond to a pending permission request
+ */
+
+import type { MAPAdapter, ExtensionHandler, ExtensionContext } from "../interface.js";
+import type { AgentId } from "../../../store/types/index.js";
+import { RPCError } from "../rpc-handler.js";
+
+// =============================================================================
+// Extension Services
+// =============================================================================
+
+/**
+ * Services required for agent lifecycle extensions
+ */
+export interface AgentLifecycleExtensionServices {
+  /** Get agent by ID */
+  getAgent: (id: AgentId) => { id: AgentId; state: string; session_id?: string; cwd?: string | null } | null;
+
+  /** Spawn a child agent under a parent */
+  spawn: (opts: {
+    parent: AgentId;
+    task: string;
+    cwd?: string;
+    role?: string;
+    topics?: string[];
+    config?: Record<string, unknown>;
+  }) => Promise<{ id: AgentId; session_id: string }>;
+
+  /** Fork an agent's session */
+  forkAgent: (agentId: AgentId, opts: {
+    name?: string;
+    prompt?: string;
+    cwd?: string;
+  }) => Promise<{ id: AgentId; session_id: string; session?: { id: string } }>;
+
+  /** Send a prompt to an agent (for fire-and-forget initial prompt on fork) */
+  prompt: (agentId: AgentId, message: string) => AsyncIterable<unknown>;
+
+  /** Set the permission mode for an agent's session */
+  setPermissionMode: (agentId: AgentId, mode: string) => boolean;
+
+  /** Get the current permission mode for an agent */
+  getPermissionMode: (agentId: AgentId) => string | null;
+
+  /** Respond to a pending permission request */
+  respondToPermission: (agentId: AgentId, requestId: string, optionId: string) => boolean;
+
+  /** Callback to notify subscribers that a new agent was registered */
+  onAgentRegistered?: (agent: { id: string; name?: string; role?: string; parent?: string }) => void;
+
+  /** List head manager agents (fallback parent for spawn) */
+  listHeadManagers: () => Array<{ id: AgentId }>;
+
+  /** Default working directory */
+  defaultCwd?: string;
+}
+
+// =============================================================================
+// Handler Implementations
+// =============================================================================
+
+function createSpawnHandler(services: AgentLifecycleExtensionServices): ExtensionHandler {
+  return async (_context: ExtensionContext, params: unknown) => {
+    const { task, cwd, topics, config, parentId } = (params ?? {}) as {
+      task: string;
+      cwd?: string;
+      topics?: string[];
+      config?: Record<string, unknown>;
+      parentId?: string;
+    };
+
+    if (!task) {
+      throw RPCError.invalidParams("task is required");
+    }
+
+    // Determine parent: explicit parentId, or fall back to head manager
+    let parent: AgentId | undefined;
+    if (parentId) {
+      parent = parentId as AgentId;
+    } else {
+      const headManagers = services.listHeadManagers();
+      if (headManagers.length > 0) {
+        parent = headManagers[0].id;
+      }
+    }
+
+    if (!parent) {
+      throw RPCError.invalidParams("No parent agent available for spawning");
+    }
+
+    const spawned = await services.spawn({
+      parent,
+      task,
+      cwd: cwd ?? services.defaultCwd,
+      role: "worker",
+      topics,
+      config,
+    });
+
+    // Notify subscribers that a new agent was registered
+    if (services.onAgentRegistered) {
+      const agent = services.getAgent(spawned.id);
+      services.onAgentRegistered({
+        id: spawned.id as string,
+        name: agent?.id as string,
+        role: "worker",
+        parent: parent as string,
+      });
+    }
+
+    return {
+      agentId: spawned.id,
+      sessionId: spawned.session_id,
+    };
+  };
+}
+
+function createForkHandler(services: AgentLifecycleExtensionServices): ExtensionHandler {
+  return async (_context: ExtensionContext, params: unknown) => {
+    const { agentId, name, prompt, cwd } = (params ?? {}) as {
+      agentId: string;
+      name?: string;
+      prompt?: string;
+      cwd?: string;
+    };
+
+    if (!agentId) {
+      throw RPCError.invalidParams("agentId is required");
+    }
+
+    const sourceAgent = services.getAgent(agentId as AgentId);
+    if (!sourceAgent) {
+      throw RPCError.notFound("agent", agentId);
+    }
+
+    const forked = await services.forkAgent(agentId as AgentId, {
+      name,
+      prompt,
+      cwd: cwd ?? sourceAgent.cwd ?? services.defaultCwd,
+    });
+
+    // Notify subscribers
+    if (services.onAgentRegistered) {
+      services.onAgentRegistered({
+        id: forked.id as string,
+        name,
+        parent: sourceAgent.id as string,
+      });
+    }
+
+    // Fire-and-forget initial prompt if provided
+    if (prompt && forked.id) {
+      (async () => {
+        try {
+          for await (const _chunk of services.prompt(forked.id, prompt)) {
+            // drain iterator
+          }
+        } catch {
+          // best-effort
+        }
+      })();
+    }
+
+    return {
+      newAgentId: forked.id,
+      newSessionId: forked.session_id,
+      originalAgentId: agentId,
+      providerSessionId: forked.session?.id,
+    };
+  };
+}
+
+function createSetPermissionModeHandler(services: AgentLifecycleExtensionServices): ExtensionHandler {
+  return async (_context: ExtensionContext, params: unknown) => {
+    const { agentId, permissionMode } = (params ?? {}) as {
+      agentId: string;
+      permissionMode: string;
+    };
+
+    if (!agentId || !permissionMode) {
+      throw RPCError.invalidParams("agentId and permissionMode are required");
+    }
+
+    const previousMode = services.getPermissionMode(agentId as AgentId);
+    const success = services.setPermissionMode(agentId as AgentId, permissionMode);
+
+    if (!success) {
+      return {
+        success: false,
+        error: `No active session found for agent ${agentId}`,
+      };
+    }
+
+    return {
+      success: true,
+      agentId,
+      previousMode,
+      newMode: permissionMode,
+    };
+  };
+}
+
+function createRespondToPermissionHandler(services: AgentLifecycleExtensionServices): ExtensionHandler {
+  return async (_context: ExtensionContext, params: unknown) => {
+    const { agentId, requestId, optionId } = (params ?? {}) as {
+      agentId: string;
+      requestId: string;
+      optionId: string;
+    };
+
+    if (!agentId || !requestId || !optionId) {
+      throw RPCError.invalidParams("agentId, requestId, and optionId are required");
+    }
+
+    const success = services.respondToPermission(
+      agentId as AgentId,
+      requestId,
+      optionId,
+    );
+
+    return { success };
+  };
+}
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/** All agent lifecycle extension method names */
+export const AGENT_LIFECYCLE_METHODS = [
+  "_macro/spawnAgent",
+  "_macro/forkAgent",
+  "_macro/setPermissionMode",
+  "_macro/respondToPermission",
+] as const;
+
+/**
+ * Register agent lifecycle extension methods with the MAPAdapter.
+ */
+export function registerAgentLifecycleExtensions(
+  adapter: MAPAdapter,
+  services: AgentLifecycleExtensionServices,
+): void {
+  adapter.registerExtension("_macro/spawnAgent", createSpawnHandler(services));
+  adapter.registerExtension("_macro/forkAgent", createForkHandler(services));
+  adapter.registerExtension("_macro/setPermissionMode", createSetPermissionModeHandler(services));
+  adapter.registerExtension("_macro/respondToPermission", createRespondToPermissionHandler(services));
+}
+
+/**
+ * Unregister agent lifecycle extension methods.
+ */
+export function unregisterAgentLifecycleExtensions(adapter: MAPAdapter): void {
+  for (const method of AGENT_LIFECYCLE_METHODS) {
+    adapter.unregisterExtension(method);
+  }
+}

package/src/map/adapter/extensions/index.ts

@@ -52,6 +52,29 @@ export {
   type AgentDetectionExtensionServices,
 } from "./agent-detection.js";
 
+// Update metadata extension
+export {
+  registerUpdateMetadataExtension,
+  unregisterUpdateMetadataExtension,
+  type UpdateMetadataExtensionServices,
+} from "./update-metadata.js";
+
+// MCP bridge extensions
+export {
+  registerMCPBridgeExtensions,
+  unregisterMCPBridgeExtensions,
+  MCP_BRIDGE_METHODS,
+  type MCPBridgeServices,
+} from "./mcp-bridge.js";
+
+// Agent lifecycle extensions
+export {
+  registerAgentLifecycleExtensions,
+  unregisterAgentLifecycleExtensions,
+  AGENT_LIFECYCLE_METHODS,
+  type AgentLifecycleExtensionServices,
+} from "./agent-lifecycle.js";
+
 import type { MAPAdapter } from "../interface.js";
 import type { TaskExtensionServices } from "./task.js";
 import type { WakeExtensionServices } from "./wake.js";
@@ -59,12 +82,18 @@ import type { WorkspaceExtensionServices } from "./workspace.js";
 import type { WorkspaceFileServices } from "./workspace-files.js";
 import type { ResumeExtensionServices } from "./resume.js";
 import type { AgentDetectionExtensionServices } from "./agent-detection.js";
+import type { UpdateMetadataExtensionServices } from "./update-metadata.js";
+import type { MCPBridgeServices } from "./mcp-bridge.js";
+import type { AgentLifecycleExtensionServices } from "./agent-lifecycle.js";
 import { registerTaskExtensions } from "./task.js";
 import { registerWakeExtension } from "./wake.js";
 import { registerWorkspaceExtension } from "./workspace.js";
 import { registerWorkspaceFileExtensions } from "./workspace-files.js";
 import { registerResumeExtension } from "./resume.js";
 import { registerAgentDetectionExtensions } from "./agent-detection.js";
+import { registerUpdateMetadataExtension } from "./update-metadata.js";
+import { registerMCPBridgeExtensions, unregisterMCPBridgeExtensions, MCP_BRIDGE_METHODS } from "./mcp-bridge.js";
+import { registerAgentLifecycleExtensions, unregisterAgentLifecycleExtensions, AGENT_LIFECYCLE_METHODS } from "./agent-lifecycle.js";
 
 // =============================================================================
 // Combined Registration
@@ -80,6 +109,9 @@ export interface MacroExtensionServices {
   workspaceFiles?: WorkspaceFileServices;
   resume?: ResumeExtensionServices;
   agentDetection?: AgentDetectionExtensionServices;
+  updateMetadata?: UpdateMetadataExtensionServices;
+  mcpBridge?: MCPBridgeServices;
+  agentLifecycle?: AgentLifecycleExtensionServices;
 }
 
 /**
@@ -140,6 +172,18 @@ export function registerMacroExtensions(
   if (services.agentDetection) {
     registerAgentDetectionExtensions(adapter, services.agentDetection);
   }
+
+  if (services.updateMetadata) {
+    registerUpdateMetadataExtension(adapter, services.updateMetadata);
+  }
+
+  if (services.mcpBridge) {
+    registerMCPBridgeExtensions(adapter, services.mcpBridge);
+  }
+
+  if (services.agentLifecycle) {
+    registerAgentLifecycleExtensions(adapter, services.agentLifecycle);
+  }
 }
 
 /**
@@ -164,9 +208,14 @@ export function unregisterMacroExtensions(adapter: MAPAdapter): void {
     adapter.unregisterExtension("_macro/resume");
     adapter.unregisterExtension("_macro/agents/available");
     adapter.unregisterExtension("_macro/agents/refresh");
+    adapter.unregisterExtension("_macro/agents/update");
   } catch {
     // Ignore errors from unregistering non-existent extensions
   }
+  // Also unregister MCP bridge extensions
+  unregisterMCPBridgeExtensions(adapter);
+  // Also unregister agent lifecycle extensions
+  unregisterAgentLifecycleExtensions(adapter);
 }
 
 // =============================================================================
@@ -197,6 +246,12 @@ export const MACRO_EXTENSION_METHODS = [
   // Agent detection extensions
   "_macro/agents/available",
   "_macro/agents/refresh",
+  // Update metadata extension
+  "_macro/agents/update",
+  // MCP bridge extensions
+  ...MCP_BRIDGE_METHODS,
+  // Agent lifecycle extensions
+  ...AGENT_LIFECYCLE_METHODS,
 ] as const;
 
 /**
@@ -217,4 +272,9 @@ export const EXTENSION_CAPABILITIES: Record<string, string> = {
   "_macro/resume": "canManageLifecycle",
   "_macro/agents/available": "canQuery",
   "_macro/agents/refresh": "canQuery",
+  "_macro/agents/update": "canQuery",
+  "_macro/spawnAgent": "canManageLifecycle",
+  "_macro/forkAgent": "canManageLifecycle",
+  "_macro/setPermissionMode": "canManageLifecycle",
+  "_macro/respondToPermission": "canManageLifecycle",
 };