@multi-agent-protocol/sdk 0.0.2

package/dist/testing.js

@@ -0,0 +1,4000 @@
+import { ulid } from 'ulid';
+
+// src/jsonrpc/index.ts
+function isRequest(message) {
+  return typeof message === "object" && message !== null && "jsonrpc" in message && message.jsonrpc === "2.0" && "id" in message && "method" in message;
+}
+function isNotification(message) {
+  return typeof message === "object" && message !== null && "jsonrpc" in message && message.jsonrpc === "2.0" && "method" in message && !("id" in message);
+}
+function isResponse(message) {
+  return typeof message === "object" && message !== null && "jsonrpc" in message && message.jsonrpc === "2.0" && "id" in message && !("method" in message);
+}
+function isErrorResponse(response) {
+  return "error" in response;
+}
+function createRequest(id, method, params) {
+  const request = {
+    jsonrpc: "2.0",
+    id,
+    method
+  };
+  if (params !== void 0) {
+    request.params = params;
+  }
+  return request;
+}
+function createNotification(method, params) {
+  const notification = {
+    jsonrpc: "2.0",
+    method
+  };
+  if (params !== void 0) {
+    notification.params = params;
+  }
+  return notification;
+}
+function createSuccessResponse(id, result) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result
+  };
+}
+function createErrorResponse(id, error) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error
+  };
+}
+
+// src/types/index.ts
+var EVENT_TYPES = {
+  // Agent lifecycle events
+  AGENT_REGISTERED: "agent_registered",
+  AGENT_UNREGISTERED: "agent_unregistered",
+  AGENT_STATE_CHANGED: "agent_state_changed",
+  AGENT_ORPHANED: "agent_orphaned",
+  // Participant lifecycle events
+  PARTICIPANT_CONNECTED: "participant_connected",
+  PARTICIPANT_DISCONNECTED: "participant_disconnected",
+  // Message events
+  MESSAGE_SENT: "message_sent",
+  // Scope events
+  SCOPE_CREATED: "scope_created",
+  SCOPE_MEMBER_JOINED: "scope_member_joined",
+  SCOPE_MEMBER_LEFT: "scope_member_left",
+  // Permission events
+  PERMISSIONS_CLIENT_UPDATED: "permissions_client_updated",
+  PERMISSIONS_AGENT_UPDATED: "permissions_agent_updated"};
+var CORE_METHODS = {
+  CONNECT: "map/connect",
+  DISCONNECT: "map/disconnect",
+  SEND: "map/send",
+  SUBSCRIBE: "map/subscribe",
+  UNSUBSCRIBE: "map/unsubscribe",
+  REPLAY: "map/replay"
+};
+var OBSERVATION_METHODS = {
+  AGENTS_LIST: "map/agents/list",
+  AGENTS_GET: "map/agents/get",
+  SCOPES_LIST: "map/scopes/list",
+  SCOPES_GET: "map/scopes/get",
+  SCOPES_MEMBERS: "map/scopes/members",
+  STRUCTURE_GRAPH: "map/structure/graph"
+};
+var LIFECYCLE_METHODS = {
+  AGENTS_REGISTER: "map/agents/register",
+  AGENTS_UNREGISTER: "map/agents/unregister",
+  AGENTS_SPAWN: "map/agents/spawn"
+};
+var STATE_METHODS = {
+  AGENTS_UPDATE: "map/agents/update",
+  AGENTS_SUSPEND: "map/agents/suspend",
+  AGENTS_RESUME: "map/agents/resume",
+  AGENTS_STOP: "map/agents/stop"
+};
+var STEERING_METHODS = {
+  INJECT: "map/inject"
+};
+var SCOPE_METHODS = {
+  SCOPES_CREATE: "map/scopes/create",
+  SCOPES_JOIN: "map/scopes/join",
+  SCOPES_LEAVE: "map/scopes/leave"
+};
+var SESSION_METHODS = {
+  SESSION_LIST: "map/session/list",
+  SESSION_LOAD: "map/session/load",
+  SESSION_CLOSE: "map/session/close"
+};
+var PERMISSION_METHODS = {
+  PERMISSIONS_UPDATE: "map/permissions/update"
+};
+var FEDERATION_METHODS = {
+  FEDERATION_ROUTE: "map/federation/route"
+};
+var NOTIFICATION_METHODS = {
+  EVENT: "map/event",
+  MESSAGE: "map/message",
+  /** Client acknowledges received events (for backpressure) */
+  SUBSCRIBE_ACK: "map/subscribe.ack"
+};
+var PROTOCOL_ERROR_CODES = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603
+};
+var AUTH_ERROR_CODES = {
+  AUTH_REQUIRED: 1e3,
+  AUTH_FAILED: 1001,
+  TOKEN_EXPIRED: 1002,
+  PERMISSION_DENIED: 1003
+};
+var ROUTING_ERROR_CODES = {
+  ADDRESS_NOT_FOUND: 2e3,
+  AGENT_NOT_FOUND: 2001,
+  SCOPE_NOT_FOUND: 2002,
+  DELIVERY_FAILED: 2003,
+  ADDRESS_AMBIGUOUS: 2004
+};
+var AGENT_ERROR_CODES = {
+  AGENT_EXISTS: 3e3,
+  STATE_INVALID: 3001,
+  NOT_RESPONDING: 3002,
+  TERMINATED: 3003,
+  SPAWN_FAILED: 3004
+};
+var RESOURCE_ERROR_CODES = {
+  EXHAUSTED: 4e3,
+  RATE_LIMITED: 4001,
+  QUOTA_EXCEEDED: 4002
+};
+var FEDERATION_ERROR_CODES = {
+  FEDERATION_UNAVAILABLE: 5e3,
+  FEDERATION_SYSTEM_NOT_FOUND: 5001,
+  FEDERATION_AUTH_FAILED: 5002,
+  FEDERATION_ROUTE_REJECTED: 5003,
+  /** Message has already visited this system (loop detected) */
+  FEDERATION_LOOP_DETECTED: 5010,
+  /** Message exceeded maximum hop count */
+  FEDERATION_MAX_HOPS_EXCEEDED: 5011
+};
+var ERROR_CODES = {
+  ...PROTOCOL_ERROR_CODES,
+  ...AUTH_ERROR_CODES,
+  ...ROUTING_ERROR_CODES,
+  ...AGENT_ERROR_CODES,
+  ...RESOURCE_ERROR_CODES,
+  ...FEDERATION_ERROR_CODES
+};
+var PROTOCOL_VERSION = 1;
+
+// src/errors/index.ts
+var MAPRequestError = class _MAPRequestError extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "MAPRequestError";
+    this.code = code;
+    this.data = data;
+  }
+  /**
+   * Convert to MAP error object
+   */
+  toError() {
+    const error = {
+      code: this.code,
+      message: this.message
+    };
+    if (this.data) {
+      error.data = this.data;
+    }
+    return error;
+  }
+  /**
+   * Convert to JSON-RPC error response
+   */
+  toResponse(id) {
+    return createErrorResponse(id, this.toError());
+  }
+  // ==========================================================================
+  // Protocol Errors (-32xxx)
+  // ==========================================================================
+  static parseError(details) {
+    return new _MAPRequestError(
+      PROTOCOL_ERROR_CODES.PARSE_ERROR,
+      details ?? "Parse error",
+      { category: "protocol" }
+    );
+  }
+  static invalidRequest(details) {
+    return new _MAPRequestError(
+      PROTOCOL_ERROR_CODES.INVALID_REQUEST,
+      details ?? "Invalid request",
+      { category: "protocol" }
+    );
+  }
+  static methodNotFound(method) {
+    return new _MAPRequestError(
+      PROTOCOL_ERROR_CODES.METHOD_NOT_FOUND,
+      `Method not found: ${method}`,
+      { category: "protocol" }
+    );
+  }
+  static invalidParams(details) {
+    return new _MAPRequestError(
+      PROTOCOL_ERROR_CODES.INVALID_PARAMS,
+      "Invalid params",
+      { category: "protocol", details }
+    );
+  }
+  static internalError(details) {
+    return new _MAPRequestError(
+      PROTOCOL_ERROR_CODES.INTERNAL_ERROR,
+      details ?? "Internal error",
+      { category: "internal" }
+    );
+  }
+  // ==========================================================================
+  // Auth Errors (1xxx)
+  // ==========================================================================
+  static authRequired() {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.AUTH_REQUIRED,
+      "Authentication required",
+      { category: "auth" }
+    );
+  }
+  static authFailed(details) {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.AUTH_FAILED,
+      details ?? "Authentication failed",
+      { category: "auth" }
+    );
+  }
+  static tokenExpired() {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.TOKEN_EXPIRED,
+      "Token expired",
+      { category: "auth", retryable: true }
+    );
+  }
+  static permissionDenied(required) {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.PERMISSION_DENIED,
+      required ? `Permission denied: ${required}` : "Permission denied",
+      { category: "auth" }
+    );
+  }
+  // ==========================================================================
+  // Routing Errors (2xxx)
+  // ==========================================================================
+  static addressNotFound(address) {
+    return new _MAPRequestError(
+      ROUTING_ERROR_CODES.ADDRESS_NOT_FOUND,
+      `Address not found: ${address}`,
+      { category: "routing" }
+    );
+  }
+  static agentNotFound(agentId) {
+    return new _MAPRequestError(
+      ROUTING_ERROR_CODES.AGENT_NOT_FOUND,
+      `Agent not found: ${agentId}`,
+      { category: "routing" }
+    );
+  }
+  static scopeNotFound(scopeId) {
+    return new _MAPRequestError(
+      ROUTING_ERROR_CODES.SCOPE_NOT_FOUND,
+      `Scope not found: ${scopeId}`,
+      { category: "routing" }
+    );
+  }
+  static deliveryFailed(details) {
+    return new _MAPRequestError(
+      ROUTING_ERROR_CODES.DELIVERY_FAILED,
+      details ?? "Message delivery failed",
+      { category: "routing", retryable: true }
+    );
+  }
+  static addressAmbiguous(address) {
+    return new _MAPRequestError(
+      ROUTING_ERROR_CODES.ADDRESS_AMBIGUOUS,
+      `Address is ambiguous: ${address}`,
+      { category: "routing" }
+    );
+  }
+  // ==========================================================================
+  // Agent Errors (3xxx)
+  // ==========================================================================
+  static agentExists(agentId) {
+    return new _MAPRequestError(
+      AGENT_ERROR_CODES.AGENT_EXISTS,
+      `Agent already exists: ${agentId}`,
+      { category: "agent" }
+    );
+  }
+  static stateInvalid(currentState, requestedAction) {
+    return new _MAPRequestError(
+      AGENT_ERROR_CODES.STATE_INVALID,
+      `Cannot ${requestedAction} agent in state: ${currentState}`,
+      { category: "agent" }
+    );
+  }
+  static agentNotResponding(agentId) {
+    return new _MAPRequestError(
+      AGENT_ERROR_CODES.NOT_RESPONDING,
+      `Agent not responding: ${agentId}`,
+      { category: "agent", retryable: true }
+    );
+  }
+  static agentTerminated(agentId) {
+    return new _MAPRequestError(
+      AGENT_ERROR_CODES.TERMINATED,
+      `Agent terminated: ${agentId}`,
+      { category: "agent" }
+    );
+  }
+  static spawnFailed(details) {
+    return new _MAPRequestError(
+      AGENT_ERROR_CODES.SPAWN_FAILED,
+      details ?? "Failed to spawn agent",
+      { category: "agent" }
+    );
+  }
+  // ==========================================================================
+  // Resource Errors (4xxx)
+  // ==========================================================================
+  static resourceExhausted(resource) {
+    return new _MAPRequestError(
+      RESOURCE_ERROR_CODES.EXHAUSTED,
+      resource ? `Resource exhausted: ${resource}` : "Resource exhausted",
+      { category: "resource", retryable: true }
+    );
+  }
+  static rateLimited(retryAfterMs) {
+    return new _MAPRequestError(
+      RESOURCE_ERROR_CODES.RATE_LIMITED,
+      "Rate limited",
+      { category: "resource", retryable: true, retryAfterMs }
+    );
+  }
+  static quotaExceeded(quota) {
+    return new _MAPRequestError(
+      RESOURCE_ERROR_CODES.QUOTA_EXCEEDED,
+      quota ? `Quota exceeded: ${quota}` : "Quota exceeded",
+      { category: "resource" }
+    );
+  }
+  // ==========================================================================
+  // Federation Errors (5xxx)
+  // ==========================================================================
+  static federationUnavailable(systemId) {
+    return new _MAPRequestError(
+      FEDERATION_ERROR_CODES.FEDERATION_UNAVAILABLE,
+      systemId ? `Federation unavailable: ${systemId}` : "Federation unavailable",
+      { category: "federation", retryable: true }
+    );
+  }
+  static federationSystemNotFound(systemId) {
+    return new _MAPRequestError(
+      FEDERATION_ERROR_CODES.FEDERATION_SYSTEM_NOT_FOUND,
+      `System not found: ${systemId}`,
+      { category: "federation" }
+    );
+  }
+  static federationAuthFailed(systemId) {
+    return new _MAPRequestError(
+      FEDERATION_ERROR_CODES.FEDERATION_AUTH_FAILED,
+      `Federation authentication failed: ${systemId}`,
+      { category: "federation" }
+    );
+  }
+  static federationRouteRejected(systemId, reason) {
+    return new _MAPRequestError(
+      FEDERATION_ERROR_CODES.FEDERATION_ROUTE_REJECTED,
+      reason ? `Route rejected by ${systemId}: ${reason}` : `Route rejected by ${systemId}`,
+      { category: "federation" }
+    );
+  }
+  // ==========================================================================
+  // Utility
+  // ==========================================================================
+  /**
+   * Create from a MAP error object
+   */
+  static fromError(error) {
+    return new _MAPRequestError(error.code, error.message, error.data);
+  }
+  /**
+   * Check if this error is retryable
+   */
+  get retryable() {
+    return this.data?.retryable ?? false;
+  }
+  /**
+   * Get retry delay in milliseconds, if specified
+   */
+  get retryAfterMs() {
+    return this.data?.retryAfterMs;
+  }
+  /**
+   * Get error category
+   */
+  get category() {
+    return this.data?.category;
+  }
+};
+var MAPConnectionError = class _MAPConnectionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MAPConnectionError";
+  }
+  static closed() {
+    return new _MAPConnectionError("Connection closed");
+  }
+  static timeout() {
+    return new _MAPConnectionError("Connection timeout");
+  }
+};
+var MAPTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(operation, timeoutMs) {
+    super(`Operation timed out after ${timeoutMs}ms: ${operation}`);
+    this.name = "MAPTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// src/connection/base.ts
+var BaseConnection = class {
+  #stream;
+  #pendingResponses = /* @__PURE__ */ new Map();
+  #abortController = new AbortController();
+  #closedPromise;
+  #defaultTimeout;
+  #stateChangeHandlers = /* @__PURE__ */ new Set();
+  #nextRequestId = 1;
+  #writeQueue = Promise.resolve();
+  #requestHandler = null;
+  #notificationHandler = null;
+  #closed = false;
+  #closeResolver;
+  #state = "initial";
+  constructor(stream, options = {}) {
+    this.#stream = stream;
+    this.#defaultTimeout = options.defaultTimeout ?? 3e4;
+    this.#closedPromise = new Promise((resolve) => {
+      this.#closeResolver = resolve;
+    });
+    void this.#startReceiving();
+  }
+  /**
+   * AbortSignal that triggers when the connection closes.
+   * Useful for cancelling operations tied to this connection.
+   */
+  get signal() {
+    return this.#abortController.signal;
+  }
+  /**
+   * Promise that resolves when the connection is closed.
+   */
+  get closed() {
+    return this.#closedPromise;
+  }
+  /**
+   * Whether the connection is closed
+   */
+  get isClosed() {
+    return this.#closed;
+  }
+  /**
+   * Set the handler for incoming requests
+   */
+  setRequestHandler(handler) {
+    this.#requestHandler = handler;
+  }
+  /**
+   * Set the handler for incoming notifications
+   */
+  setNotificationHandler(handler) {
+    this.#notificationHandler = handler;
+  }
+  /**
+   * Current connection state
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * Register a handler for state changes.
+   *
+   * @param handler - Function called when state changes
+   * @returns Unsubscribe function to remove the handler
+   */
+  onStateChange(handler) {
+    this.#stateChangeHandlers.add(handler);
+    return () => this.#stateChangeHandlers.delete(handler);
+  }
+  /**
+   * Transition to a new state and notify handlers.
+   * @internal
+   */
+  _transitionTo(newState) {
+    if (this.#state === newState) return;
+    const oldState = this.#state;
+    this.#state = newState;
+    for (const handler of this.#stateChangeHandlers) {
+      try {
+        handler(newState, oldState);
+      } catch (error) {
+        console.error("MAP: State change handler error:", error);
+      }
+    }
+  }
+  /**
+   * Reconnect with a new stream.
+   *
+   * This method is used by role-specific connections to replace the
+   * underlying transport after a disconnect.
+   *
+   * @param newStream - The new stream to use
+   * @throws If the connection is permanently closed
+   */
+  async reconnect(newStream) {
+    if (this.#state === "closed") {
+      throw new Error("Cannot reconnect a permanently closed connection");
+    }
+    this.#stream = newStream;
+    this.#closed = false;
+    this.#writeQueue = Promise.resolve();
+    void this.#startReceiving();
+    this._transitionTo("connected");
+  }
+  /**
+   * Send a request and wait for response
+   */
+  async sendRequest(method, params, options) {
+    if (this.#closed) {
+      throw MAPConnectionError.closed();
+    }
+    const id = this.#nextRequestId++;
+    const request = createRequest(id, method, params);
+    const responsePromise = new Promise((resolve, reject) => {
+      const pending = { resolve, reject };
+      const timeout = options?.timeout ?? this.#defaultTimeout;
+      if (timeout > 0) {
+        pending.timeoutId = setTimeout(() => {
+          this.#pendingResponses.delete(id);
+          reject(new MAPTimeoutError(method, timeout));
+        }, timeout);
+      }
+      this.#pendingResponses.set(id, pending);
+    });
+    await this.#sendMessage(request);
+    return responsePromise;
+  }
+  /**
+   * Send a notification (no response expected)
+   */
+  async sendNotification(method, params) {
+    if (this.#closed) {
+      throw MAPConnectionError.closed();
+    }
+    const notification = createNotification(method, params);
+    await this.#sendMessage(notification);
+  }
+  /**
+   * Send a response to a request
+   */
+  async sendResponse(id, result) {
+    if (this.#closed) {
+      throw MAPConnectionError.closed();
+    }
+    const response = createSuccessResponse(id, result);
+    await this.#sendMessage(response);
+  }
+  /**
+   * Send an error response to a request
+   */
+  async sendErrorResponse(id, error) {
+    if (this.#closed) {
+      throw MAPConnectionError.closed();
+    }
+    const response = createErrorResponse(id, error);
+    await this.#sendMessage(response);
+  }
+  /**
+   * Close the connection
+   */
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this._transitionTo("closed");
+    this.#abortController.abort();
+    for (const [, pending] of this.#pendingResponses) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId);
+      }
+      pending.reject(MAPConnectionError.closed());
+    }
+    this.#pendingResponses.clear();
+    try {
+      const writer = this.#stream.writable.getWriter();
+      await writer.close();
+      writer.releaseLock();
+    } catch {
+    }
+    this.#closeResolver();
+  }
+  /**
+   * Start receiving messages from the stream
+   */
+  async #startReceiving() {
+    const reader = this.#stream.readable.getReader();
+    try {
+      while (!this.#closed) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        await this.#handleMessage(value);
+      }
+    } catch (error) {
+      if (!this.#closed) {
+        console.error("MAP: Error receiving message:", error);
+      }
+    } finally {
+      reader.releaseLock();
+      await this.close();
+    }
+  }
+  /**
+   * Handle an incoming message
+   */
+  async #handleMessage(message) {
+    try {
+      if (isRequest(message)) {
+        await this.#handleRequest(message);
+      } else if (isNotification(message)) {
+        await this.#handleNotification(message);
+      } else if (isResponse(message)) {
+        this.#handleResponse(message);
+      } else {
+        console.error("MAP: Unknown message type:", message);
+      }
+    } catch (error) {
+      console.error("MAP: Error handling message:", error);
+    }
+  }
+  /**
+   * Handle an incoming request
+   */
+  async #handleRequest(request) {
+    const { id, method, params } = request;
+    if (!this.#requestHandler) {
+      await this.sendErrorResponse(
+        id,
+        MAPRequestError.methodNotFound(method).toError()
+      );
+      return;
+    }
+    try {
+      const result = await this.#requestHandler(method, params);
+      await this.sendResponse(id, result ?? null);
+    } catch (error) {
+      if (error instanceof MAPRequestError) {
+        await this.sendErrorResponse(id, error.toError());
+      } else {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        await this.sendErrorResponse(
+          id,
+          MAPRequestError.internalError(message).toError()
+        );
+      }
+    }
+  }
+  /**
+   * Handle an incoming notification
+   */
+  async #handleNotification(notification) {
+    const { method, params } = notification;
+    if (!this.#notificationHandler) {
+      console.warn("MAP: No notification handler for:", method);
+      return;
+    }
+    try {
+      await this.#notificationHandler(method, params);
+    } catch (error) {
+      console.error("MAP: Error handling notification:", method, error);
+    }
+  }
+  /**
+   * Handle an incoming response
+   */
+  #handleResponse(response) {
+    const { id } = response;
+    const pending = this.#pendingResponses.get(id);
+    if (!pending) {
+      console.warn("MAP: Received response for unknown request:", id);
+      return;
+    }
+    this.#pendingResponses.delete(id);
+    if (pending.timeoutId) {
+      clearTimeout(pending.timeoutId);
+    }
+    if (isErrorResponse(response)) {
+      pending.reject(MAPRequestError.fromError(response.error));
+    } else {
+      pending.resolve(response.result);
+    }
+  }
+  /**
+   * Send a message through the stream with write queue serialization
+   */
+  async #sendMessage(message) {
+    this.#writeQueue = this.#writeQueue.then(async () => {
+      if (this.#closed) return;
+      const writer = this.#stream.writable.getWriter();
+      try {
+        await writer.write(message);
+      } finally {
+        writer.releaseLock();
+      }
+    }).catch((error) => {
+      console.error("MAP: Write error:", error);
+    });
+    return this.#writeQueue;
+  }
+};
+
+// src/federation/envelope.ts
+function processFederationEnvelope(envelope, config) {
+  const { federation } = envelope;
+  const maxHops = federation.maxHops ?? config.maxHops ?? 10;
+  if (federation.hopCount >= maxHops) {
+    return {
+      success: false,
+      errorCode: ERROR_CODES.FEDERATION_MAX_HOPS_EXCEEDED,
+      errorMessage: `Message exceeded maximum hop count of ${maxHops}`
+    };
+  }
+  if (federation.path?.includes(config.systemId)) {
+    return {
+      success: false,
+      errorCode: ERROR_CODES.FEDERATION_LOOP_DETECTED,
+      errorMessage: `Loop detected: message already visited ${config.systemId}`
+    };
+  }
+  if (config.allowedSources && !config.allowedSources.includes(federation.sourceSystem)) {
+    return {
+      success: false,
+      errorCode: ERROR_CODES.FEDERATION_ROUTE_REJECTED,
+      errorMessage: `Source system ${federation.sourceSystem} not in allowed sources`
+    };
+  }
+  if (config.allowedTargets && !config.allowedTargets.includes(federation.targetSystem)) {
+    return {
+      success: false,
+      errorCode: ERROR_CODES.FEDERATION_ROUTE_REJECTED,
+      errorMessage: `Target system ${federation.targetSystem} not in allowed targets`
+    };
+  }
+  return {
+    success: true,
+    envelope: {
+      payload: envelope.payload,
+      federation: {
+        ...federation,
+        hopCount: federation.hopCount + 1,
+        path: config.trackPath ? [...federation.path ?? [], config.systemId] : federation.path
+      }
+    }
+  };
+}
+function unwrapEnvelope(envelope) {
+  return envelope.payload;
+}
+function isValidEnvelope(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const envelope = obj;
+  if (!("payload" in envelope) || !("federation" in envelope)) return false;
+  const federation = envelope.federation;
+  if (!federation || typeof federation !== "object") return false;
+  return typeof federation.sourceSystem === "string" && typeof federation.targetSystem === "string" && typeof federation.hopCount === "number" && typeof federation.originTimestamp === "number";
+}
+
+// src/protocol/index.ts
+function buildConnectResponse(params) {
+  return {
+    protocolVersion: params.protocolVersion,
+    sessionId: params.sessionId,
+    participantId: params.participantId,
+    capabilities: params.capabilities,
+    systemInfo: params.systemInfo,
+    reconnected: params.reconnected,
+    reclaimedAgents: params.reclaimedAgents,
+    ownedAgents: params.ownedAgents
+  };
+}
+function buildSendResponse(messageId, delivered) {
+  return { messageId, delivered };
+}
+function buildAgentsRegisterResponse(agent) {
+  return { agent };
+}
+function buildAgentsUnregisterResponse(agent) {
+  return { agent };
+}
+function buildAgentsListResponse(agents) {
+  return { agents };
+}
+function buildAgentsGetResponse(agent, children, descendants) {
+  const result = { agent };
+  if (children) result.children = children;
+  if (descendants) result.descendants = descendants;
+  return result;
+}
+function buildAgentsUpdateResponse(agent) {
+  return { agent };
+}
+function buildScopesCreateResponse(scope) {
+  return { scope };
+}
+function buildScopesListResponse(scopes) {
+  return { scopes };
+}
+function buildScopesJoinResponse(scope, agent) {
+  return { scope, agent };
+}
+function buildScopesLeaveResponse(scope, agent) {
+  return { scope, agent };
+}
+function buildSubscribeResponse(subscriptionId) {
+  return { subscriptionId };
+}
+function buildUnsubscribeResponse(subscriptionId, closedAt = Date.now()) {
+  return {
+    subscription: {
+      id: subscriptionId,
+      closedAt
+    }
+  };
+}
+
+// src/permissions/index.ts
+function isAgentExposed(exposure, agentId) {
+  if (!exposure?.agents) return true;
+  const {
+    publicByDefault = true,
+    publicAgents = [],
+    hiddenAgents = []
+  } = exposure.agents;
+  if (matchesPatterns(agentId, hiddenAgents)) return false;
+  if (matchesPatterns(agentId, publicAgents)) return true;
+  return publicByDefault;
+}
+function isEventTypeExposed(exposure, eventType) {
+  if (!exposure?.events) return true;
+  const { exposedTypes, hiddenTypes = [] } = exposure.events;
+  if (hiddenTypes.includes(eventType)) return false;
+  if (exposedTypes && !exposedTypes.includes(eventType)) return false;
+  return true;
+}
+function isScopeExposed(exposure, scopeId) {
+  if (!exposure?.scopes) return true;
+  const {
+    publicByDefault = true,
+    publicScopes = [],
+    hiddenScopes = []
+  } = exposure.scopes;
+  if (matchesPatterns(scopeId, hiddenScopes)) return false;
+  if (matchesPatterns(scopeId, publicScopes)) return true;
+  return publicByDefault;
+}
+function canSeeScope(scope, participant, memberAgentIds = []) {
+  const visibility = scope.visibility ?? "public";
+  switch (visibility) {
+    case "public":
+      return true;
+    case "members":
+      return memberAgentIds.length > 0;
+    case "system":
+      return participant.type === "system";
+    default:
+      return false;
+  }
+}
+function canSeeAgent(agent, participant, ownedAgentIds = []) {
+  const visibility = agent.visibility ?? "public";
+  switch (visibility) {
+    case "public":
+      return true;
+    case "parent-only":
+      if (ownedAgentIds.includes(agent.id)) return true;
+      return agent.parent ? ownedAgentIds.includes(agent.parent) : false;
+    case "scope":
+      return true;
+    case "system":
+      return participant.type === "system";
+    default:
+      return false;
+  }
+}
+function filterVisibleAgents(agents, context) {
+  const ownedAgentIds = context.ownedAgentIds ?? [];
+  return agents.filter((agent) => {
+    if (!isAgentExposed(context.system.exposure, agent.id)) {
+      return false;
+    }
+    if (!canSeeAgent(agent, context.participant, ownedAgentIds)) {
+      return false;
+    }
+    return true;
+  });
+}
+function filterVisibleScopes(scopes, context) {
+  const scopeMembership = context.scopeMembership ?? /* @__PURE__ */ new Map();
+  return scopes.filter((scope) => {
+    if (!isScopeExposed(context.system.exposure, scope.id)) {
+      return false;
+    }
+    const memberAgentIds = scopeMembership.get(scope.id) ?? [];
+    if (!canSeeScope(scope, context.participant, memberAgentIds)) {
+      return false;
+    }
+    return true;
+  });
+}
+function matchesPatterns(value, patterns) {
+  return patterns.some((pattern) => matchGlob(value, pattern));
+}
+function matchGlob(value, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  const regex = new RegExp(`^${escaped}$`);
+  return regex.test(value);
+}
+
+// src/utils/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxRetries: 10,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  jitter: true
+};
+function calculateDelay(attempt, policy) {
+  let delay = Math.min(
+    policy.baseDelayMs * Math.pow(2, attempt - 1),
+    policy.maxDelayMs
+  );
+  if (policy.jitter) {
+    delay = delay * (0.5 + Math.random());
+  }
+  return Math.floor(delay);
+}
+async function withRetry(operation, policy = DEFAULT_RETRY_POLICY, callbacks) {
+  let lastError;
+  for (let attempt = 1; attempt <= policy.maxRetries + 1; attempt++) {
+    try {
+      const result = await operation();
+      callbacks?.onSuccess?.(result, attempt);
+      return result;
+    } catch (error) {
+      lastError = error;
+      const isRetryable = policy.isRetryable?.(lastError) ?? true;
+      const hasMoreAttempts = attempt <= policy.maxRetries;
+      if (!isRetryable || !hasMoreAttempts) {
+        break;
+      }
+      const delay = calculateDelay(attempt, policy);
+      callbacks?.onRetry?.({
+        attempt,
+        nextDelayMs: delay,
+        lastError
+      });
+      await sleep(delay);
+    }
+  }
+  callbacks?.onFailure?.(lastError, policy.maxRetries + 1);
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/testing/server.ts
+var TestServer = class {
+  #options;
+  #participants = /* @__PURE__ */ new Map();
+  #agents = /* @__PURE__ */ new Map();
+  #scopes = /* @__PURE__ */ new Map();
+  #subscriptions = /* @__PURE__ */ new Map();
+  #messages = [];
+  #eventHistory = [];
+  #maxEventHistory;
+  /**
+   * Tracks recent event IDs for causal linking.
+   * Key format: "type:source" or "type:messageId" for message events
+   */
+  #recentEventIds = /* @__PURE__ */ new Map();
+  #sessionId;
+  #nextParticipantId = 1;
+  #nextAgentId = 1;
+  #nextScopeId = 1;
+  #nextSubscriptionId = 1;
+  #nextMessageId = 1;
+  constructor(options = {}) {
+    this.#options = options;
+    this.#sessionId = `session-${Date.now()}`;
+    this.#maxEventHistory = options.maxEventHistory ?? 1e4;
+  }
+  /**
+   * Accept a new connection
+   */
+  acceptConnection(stream) {
+    const connection = new BaseConnection(stream);
+    connection.setRequestHandler(this.#handleRequest.bind(this, connection));
+    return connection;
+  }
+  /**
+   * Get current session ID
+   */
+  get sessionId() {
+    return this.#sessionId;
+  }
+  /**
+   * Get all registered agents
+   */
+  get agents() {
+    return this.#agents;
+  }
+  /**
+   * Get all scopes
+   */
+  get scopes() {
+    return this.#scopes;
+  }
+  /**
+   * Get all messages sent through the server
+   */
+  get messages() {
+    return this.#messages;
+  }
+  /**
+   * Get connected participant count
+   */
+  get participantCount() {
+    return this.#participants.size;
+  }
+  /**
+   * Get event history for replay testing
+   */
+  get eventHistory() {
+    return this.#eventHistory;
+  }
+  /**
+   * Emit an event to subscribers
+   * @param event - The event to emit (without id/timestamp)
+   * @param causedBy - Optional array of event IDs that caused this event
+   * @returns The generated event ID
+   */
+  emitEvent(event, causedBy) {
+    const eventId = ulid();
+    const timestamp = Date.now();
+    const fullEvent = {
+      id: `evt-${timestamp}-${Math.random().toString(36).slice(2)}`,
+      timestamp,
+      ...event
+    };
+    if (!isEventTypeExposed(this.#options.exposure, event.type)) {
+      return eventId;
+    }
+    this.#eventHistory.push({ eventId, timestamp, event: fullEvent, causedBy });
+    const trackingKey = event.source ? `${event.type}:${event.source}` : event.type;
+    this.#recentEventIds.set(trackingKey, eventId);
+    const eventData = event.data;
+    if (eventData?.messageId) {
+      this.#recentEventIds.set(`message:${eventData.messageId}`, eventId);
+    }
+    if (eventData?.agentId) {
+      this.#recentEventIds.set(`${event.type}:agent:${eventData.agentId}`, eventId);
+    }
+    while (this.#eventHistory.length > this.#maxEventHistory) {
+      this.#eventHistory.shift();
+    }
+    for (const subscription of this.#subscriptions.values()) {
+      if (this.#matchesFilter(fullEvent, subscription.filter)) {
+        const participant = this.#participants.get(subscription.participantId);
+        if (participant) {
+          subscription.sequenceNumber++;
+          participant.connection.sendNotification(NOTIFICATION_METHODS.EVENT, {
+            subscriptionId: subscription.id,
+            sequenceNumber: subscription.sequenceNumber,
+            eventId,
+            timestamp,
+            event: fullEvent,
+            causedBy
+          });
+        }
+      }
+    }
+    return eventId;
+  }
+  /**
+   * Deliver a message notification to a participant
+   */
+  deliverMessage(participantId, message) {
+    const participant = this.#participants.get(participantId);
+    if (participant) {
+      participant.connection.sendNotification(NOTIFICATION_METHODS.MESSAGE, {
+        message
+      });
+    }
+  }
+  /**
+   * Handle incoming requests
+   */
+  async #handleRequest(connection, method, params) {
+    switch (method) {
+      // =======================================================================
+      // Core Methods
+      // =======================================================================
+      case CORE_METHODS.CONNECT:
+        return this.#handleConnect(connection, params);
+      case CORE_METHODS.DISCONNECT:
+        return this.#handleDisconnect(connection, params);
+      case CORE_METHODS.SEND:
+        return this.#handleSend(connection, params);
+      case CORE_METHODS.SUBSCRIBE:
+        return this.#handleSubscribe(connection, params);
+      case CORE_METHODS.UNSUBSCRIBE:
+        return this.#handleUnsubscribe(connection, params);
+      case CORE_METHODS.REPLAY:
+        return this.#handleReplay(params);
+      // =======================================================================
+      // Observation Methods
+      // =======================================================================
+      case OBSERVATION_METHODS.AGENTS_LIST:
+        return this.#handleAgentsList(connection, params);
+      case OBSERVATION_METHODS.AGENTS_GET:
+        return this.#handleAgentsGet(params);
+      case OBSERVATION_METHODS.SCOPES_LIST:
+        return this.#handleScopesList(connection);
+      // =======================================================================
+      // Lifecycle Methods
+      // =======================================================================
+      case LIFECYCLE_METHODS.AGENTS_REGISTER:
+        return this.#handleAgentsRegister(connection, params);
+      case LIFECYCLE_METHODS.AGENTS_UNREGISTER:
+        return this.#handleAgentsUnregister(params);
+      case LIFECYCLE_METHODS.AGENTS_SPAWN:
+        return this.#handleAgentsSpawn(
+          connection,
+          params
+        );
+      // =======================================================================
+      // State Methods
+      // =======================================================================
+      case STATE_METHODS.AGENTS_UPDATE:
+        return this.#handleAgentsUpdate(connection, params);
+      case STATE_METHODS.AGENTS_STOP:
+        return this.#handleAgentsStop(params);
+      // =======================================================================
+      // Scope Methods
+      // =======================================================================
+      case SCOPE_METHODS.SCOPES_CREATE:
+        return this.#handleScopesCreate(params);
+      case SCOPE_METHODS.SCOPES_JOIN:
+        return this.#handleScopesJoin(params);
+      case SCOPE_METHODS.SCOPES_LEAVE:
+        return this.#handleScopesLeave(params);
+      // =======================================================================
+      // Steering Methods
+      // =======================================================================
+      case STEERING_METHODS.INJECT:
+        return this.#handleInject(params);
+      // =======================================================================
+      // Federation Methods
+      // =======================================================================
+      case FEDERATION_METHODS.FEDERATION_ROUTE:
+        return this.#handleFederationRoute(params);
+      // =======================================================================
+      // Notification Methods (client → server)
+      // =======================================================================
+      case NOTIFICATION_METHODS.SUBSCRIBE_ACK:
+        return this.#handleSubscriptionAck(params);
+      // =======================================================================
+      // Permission Methods
+      // =======================================================================
+      case PERMISSION_METHODS.PERMISSIONS_UPDATE:
+        return this.#handlePermissionsUpdate(
+          connection,
+          params
+        );
+      default:
+        throw MAPRequestError.methodNotFound(method);
+    }
+  }
+  // ===========================================================================
+  // Core Method Handlers
+  // ===========================================================================
+  #handleConnect(connection, params) {
+    const participantId = params.participantId || `participant-${this.#nextParticipantId++}`;
+    const participant = {
+      id: participantId,
+      type: params.participantType,
+      name: params.name,
+      connection,
+      subscriptions: /* @__PURE__ */ new Set(),
+      capabilities: params.capabilities
+    };
+    this.#participants.set(participantId, participant);
+    connection.closed.then(() => {
+      this.#handleParticipantDisconnect(participantId);
+    });
+    this.emitEvent({
+      type: EVENT_TYPES.PARTICIPANT_CONNECTED,
+      source: participantId,
+      data: { participantId, participantType: params.participantType, name: params.name }
+    });
+    return buildConnectResponse({
+      protocolVersion: PROTOCOL_VERSION,
+      sessionId: this.#sessionId,
+      participantId,
+      capabilities: this.#options.capabilities ?? {
+        observation: { canObserve: true, canQuery: true },
+        messaging: { canSend: true, canReceive: true, canBroadcast: true },
+        lifecycle: { canSpawn: true, canRegister: true, canUnregister: true, canStop: true, canSteer: true },
+        scopes: { canCreateScopes: true, canManageScopes: true },
+        streaming: { supportsAck: true, supportsPause: true }
+      },
+      systemInfo: {
+        name: this.#options.name ?? "Test MAP Server",
+        version: this.#options.version ?? "1.0.0"
+      }
+    });
+  }
+  #handleDisconnect(connection, params) {
+    for (const [id, participant] of this.#participants) {
+      if (participant.connection === connection) {
+        this.#handleParticipantDisconnect(id, params?.policy);
+        break;
+      }
+    }
+    return { acknowledged: true };
+  }
+  #handleParticipantDisconnect(participantId, policy) {
+    const participant = this.#participants.get(participantId);
+    if (!participant) return;
+    for (const subId of participant.subscriptions) {
+      this.#subscriptions.delete(subId);
+    }
+    const disconnectEventId = this.emitEvent({
+      type: EVENT_TYPES.PARTICIPANT_DISCONNECTED,
+      source: participantId,
+      data: { participantId, participantType: participant.type }
+    });
+    const ownedAgents = Array.from(this.#agents.values()).filter((a) => a.ownerId === participantId);
+    for (const agent of ownedAgents) {
+      const agentBehavior = policy?.agentBehavior ?? "unregister";
+      if (agentBehavior === "unregister") {
+        this.#terminateAgentTree(agent.id, [disconnectEventId]);
+      } else if (agentBehavior === "orphan") {
+        const previousOwner = agent.ownerId;
+        agent.ownerId = null;
+        this.emitEvent(
+          {
+            type: EVENT_TYPES.AGENT_ORPHANED,
+            source: agent.id,
+            data: { agentId: agent.id, previousOwner }
+          },
+          [disconnectEventId]
+          // Caused by the disconnect event
+        );
+      }
+    }
+    this.#participants.delete(participantId);
+  }
+  /**
+   * Terminate an agent and all its descendants
+   * @param agentId - Agent to terminate
+   * @param causedBy - Event IDs that caused this termination (e.g., disconnect event)
+   */
+  #terminateAgentTree(agentId, causedBy) {
+    const children = Array.from(this.#agents.values()).filter((a) => a.parent === agentId);
+    for (const child of children) {
+      this.#terminateAgentTree(child.id, causedBy);
+    }
+    const agent = this.#agents.get(agentId);
+    if (agent) {
+      this.#agents.delete(agentId);
+      for (const scope of this.#scopes.values()) {
+        scope.members.delete(agentId);
+      }
+      this.emitEvent(
+        {
+          type: EVENT_TYPES.AGENT_UNREGISTERED,
+          source: agentId,
+          data: { agentId, reason: "owner_disconnected" }
+        },
+        causedBy
+      );
+    }
+  }
+  #handleAgentsList(connection, params) {
+    let agents = Array.from(this.#agents.values());
+    const permissionContext = this.#buildPermissionContext(connection);
+    if (permissionContext) {
+      agents = filterVisibleAgents(agents, permissionContext);
+    }
+    if (params?.filter) {
+      const { states, roles, scopes, parent } = params.filter;
+      if (states?.length) {
+        agents = agents.filter((a) => states.includes(a.state));
+      }
+      if (roles?.length) {
+        agents = agents.filter((a) => a.role && roles.includes(a.role));
+      }
+      if (scopes?.length) {
+        agents = agents.filter((a) => a.scopes?.some((s) => scopes.includes(s)));
+      }
+      if (parent) {
+        agents = agents.filter((a) => a.parent === parent);
+      }
+    }
+    return buildAgentsListResponse(agents);
+  }
+  #handleAgentsGet(params) {
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    const children = params.include?.children ? Array.from(this.#agents.values()).filter((a) => a.parent === params.agentId) : void 0;
+    const descendants = params.include?.descendants ? this.#getDescendants(params.agentId) : void 0;
+    return buildAgentsGetResponse(agent, children, descendants);
+  }
+  /**
+   * Get all descendants of an agent recursively
+   */
+  #getDescendants(agentId) {
+    const descendants = [];
+    const children = Array.from(this.#agents.values()).filter((a) => a.parent === agentId);
+    for (const child of children) {
+      descendants.push(child);
+      descendants.push(...this.#getDescendants(child.id));
+    }
+    return descendants;
+  }
+  #handleSend(connection, params) {
+    const messageId = `msg-${this.#nextMessageId++}`;
+    const delivered = [];
+    let senderId;
+    let senderAgentId;
+    for (const [id, participant] of this.#participants) {
+      if (participant.connection === connection) {
+        senderId = id;
+        senderAgentId = participant.agentId;
+        break;
+      }
+    }
+    const message = {
+      id: messageId,
+      from: senderId ?? "unknown",
+      to: params.to,
+      timestamp: Date.now(),
+      payload: params.payload,
+      meta: params.meta
+    };
+    this.#messages.push(message);
+    const recipients = this.#resolveAddress(params.to, senderAgentId);
+    for (const recipientId of recipients) {
+      const participant = this.#participants.get(recipientId);
+      if (participant) {
+        this.deliverMessage(recipientId, message);
+        delivered.push(recipientId);
+      }
+    }
+    this.emitEvent({
+      type: EVENT_TYPES.MESSAGE_SENT,
+      source: senderId,
+      data: { messageId, to: params.to }
+    });
+    return buildSendResponse(messageId, delivered);
+  }
+  #handleSubscribe(connection, params) {
+    let participantId;
+    for (const [id, participant] of this.#participants) {
+      if (participant.connection === connection) {
+        participantId = id;
+        break;
+      }
+    }
+    if (!participantId) {
+      throw MAPRequestError.authRequired();
+    }
+    const subscriptionId = `sub-${this.#nextSubscriptionId++}`;
+    const subscription = {
+      id: subscriptionId,
+      participantId,
+      filter: params?.filter,
+      sequenceNumber: 0
+    };
+    this.#subscriptions.set(subscriptionId, subscription);
+    this.#participants.get(participantId).subscriptions.add(subscriptionId);
+    return buildSubscribeResponse(subscriptionId);
+  }
+  #handleUnsubscribe(_connection, params) {
+    const subscription = this.#subscriptions.get(params.subscriptionId);
+    if (subscription) {
+      this.#subscriptions.delete(params.subscriptionId);
+      const participant = this.#participants.get(subscription.participantId);
+      if (participant) {
+        participant.subscriptions.delete(params.subscriptionId);
+      }
+    }
+    return buildUnsubscribeResponse(params.subscriptionId);
+  }
+  #handleReplay(params) {
+    const {
+      afterEventId,
+      fromTimestamp,
+      toTimestamp,
+      filter,
+      limit = 100
+    } = params ?? {};
+    let events = [...this.#eventHistory];
+    if (afterEventId) {
+      const idx = events.findIndex((e) => e.eventId === afterEventId);
+      if (idx >= 0) {
+        events = events.slice(idx + 1);
+      }
+    }
+    if (fromTimestamp !== void 0) {
+      events = events.filter((e) => e.timestamp >= fromTimestamp);
+    }
+    if (toTimestamp !== void 0) {
+      events = events.filter((e) => e.timestamp <= toTimestamp);
+    }
+    if (filter) {
+      events = events.filter((e) => this.#matchesFilter(e.event, filter));
+    }
+    const hasMore = events.length > limit;
+    events = events.slice(0, Math.min(limit, 1e3));
+    return {
+      events: events.map((e) => ({
+        eventId: e.eventId,
+        timestamp: e.timestamp,
+        event: e.event,
+        causedBy: e.causedBy
+      })),
+      hasMore,
+      totalCount: this.#eventHistory.length
+    };
+  }
+  // ===========================================================================
+  // Structure Method Handlers
+  // ===========================================================================
+  #handleAgentsRegister(connection, params) {
+    const agentId = params.agentId || `agent-${this.#nextAgentId++}`;
+    if (this.#agents.has(agentId)) {
+      throw MAPRequestError.agentExists(agentId);
+    }
+    let ownerId = "unknown";
+    for (const [participantId, participant] of this.#participants) {
+      if (participant.connection === connection) {
+        ownerId = participantId;
+        participant.agentId = agentId;
+        break;
+      }
+    }
+    const agent = {
+      id: agentId,
+      name: params.name,
+      description: params.description,
+      role: params.role,
+      parent: params.parent,
+      ownerId,
+      // v2: Track which participant owns this agent
+      state: "registered",
+      scopes: params.scopes,
+      visibility: params.visibility,
+      capabilities: params.capabilities,
+      metadata: params.metadata,
+      permissionOverrides: params.permissionOverrides,
+      lifecycle: {
+        createdAt: Date.now()
+      }
+    };
+    this.#agents.set(agentId, agent);
+    this.emitEvent({
+      type: EVENT_TYPES.AGENT_REGISTERED,
+      source: agentId,
+      data: { agentId, name: agent.name, role: agent.role, ownerId }
+    });
+    return buildAgentsRegisterResponse(agent);
+  }
+  #handleAgentsUnregister(params) {
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    const agentCopy = { ...agent };
+    this.#agents.delete(params.agentId);
+    for (const scope of this.#scopes.values()) {
+      scope.members.delete(params.agentId);
+    }
+    this.emitEvent({
+      type: EVENT_TYPES.AGENT_UNREGISTERED,
+      source: params.agentId,
+      data: { agentId: params.agentId, reason: params.reason }
+    });
+    return buildAgentsUnregisterResponse(agentCopy);
+  }
+  #handleAgentsUpdate(connection, params) {
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    let requestingParticipantId;
+    for (const [id, p] of this.#participants) {
+      if (p.connection === connection) {
+        requestingParticipantId = id;
+        break;
+      }
+    }
+    const previousState = agent.state;
+    if (params.state) {
+      agent.state = params.state;
+    }
+    if (params.metadata) {
+      agent.metadata = { ...agent.metadata, ...params.metadata };
+    }
+    if (params.permissionOverrides) {
+      const existingOverrides = agent.permissionOverrides ?? {};
+      const newOverrides = {};
+      if (existingOverrides.canSee || params.permissionOverrides.canSee) {
+        newOverrides.canSee = {
+          ...existingOverrides.canSee,
+          ...params.permissionOverrides.canSee
+        };
+      }
+      if (existingOverrides.canMessage || params.permissionOverrides.canMessage) {
+        newOverrides.canMessage = {
+          ...existingOverrides.canMessage,
+          ...params.permissionOverrides.canMessage
+        };
+      }
+      if (existingOverrides.acceptsFrom || params.permissionOverrides.acceptsFrom) {
+        newOverrides.acceptsFrom = {
+          ...existingOverrides.acceptsFrom,
+          ...params.permissionOverrides.acceptsFrom
+        };
+      }
+      agent.permissionOverrides = newOverrides;
+      this.emitEvent({
+        type: EVENT_TYPES.PERMISSIONS_AGENT_UPDATED,
+        source: params.agentId,
+        data: {
+          agentId: params.agentId,
+          changes: params.permissionOverrides,
+          effectivePermissions: newOverrides,
+          updatedBy: requestingParticipantId
+        }
+      });
+    }
+    if (params.state && params.state !== previousState) {
+      this.emitEvent({
+        type: EVENT_TYPES.AGENT_STATE_CHANGED,
+        source: params.agentId,
+        data: { agentId: params.agentId, previousState, newState: params.state }
+      });
+    }
+    return buildAgentsUpdateResponse(agent);
+  }
+  #handleAgentsSpawn(connection, params) {
+    if (!this.#agents.has(params.parent)) {
+      throw MAPRequestError.agentNotFound(params.parent);
+    }
+    return this.#handleAgentsRegister(connection, {
+      name: params.name,
+      role: params.role,
+      parent: params.parent
+    });
+  }
+  #handleAgentsStop(params) {
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    agent.state = "stopping";
+    this.emitEvent({
+      type: EVENT_TYPES.AGENT_STATE_CHANGED,
+      source: params.agentId,
+      data: { agentId: params.agentId, previousState: agent.state, newState: "stopping" }
+    });
+    return { stopping: true, agent };
+  }
+  #handleScopesList(connection) {
+    let scopes = Array.from(this.#scopes.values()).map(({ members, ...scope }) => scope);
+    const permissionContext = this.#buildPermissionContext(connection);
+    if (permissionContext) {
+      scopes = filterVisibleScopes(scopes, permissionContext);
+    }
+    return buildScopesListResponse(scopes);
+  }
+  #handleScopesCreate(params) {
+    const scopeId = params.scopeId || `scope-${this.#nextScopeId++}`;
+    const scope = {
+      id: scopeId,
+      name: params.name,
+      description: params.description,
+      parent: params.parent,
+      joinPolicy: params.joinPolicy,
+      visibility: params.visibility,
+      members: /* @__PURE__ */ new Set()
+    };
+    this.#scopes.set(scopeId, scope);
+    this.emitEvent({
+      type: EVENT_TYPES.SCOPE_CREATED,
+      data: { scopeId, name: scope.name }
+    });
+    const { members, ...scopeWithoutMembers } = scope;
+    return buildScopesCreateResponse(scopeWithoutMembers);
+  }
+  #handleScopesJoin(params) {
+    const scope = this.#scopes.get(params.scopeId);
+    if (!scope) {
+      throw MAPRequestError.scopeNotFound(params.scopeId);
+    }
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    scope.members.add(params.agentId);
+    if (!agent.scopes) {
+      agent.scopes = [];
+    }
+    if (!agent.scopes.includes(params.scopeId)) {
+      agent.scopes.push(params.scopeId);
+    }
+    this.emitEvent({
+      type: EVENT_TYPES.SCOPE_MEMBER_JOINED,
+      source: params.agentId,
+      data: { scopeId: params.scopeId, agentId: params.agentId }
+    });
+    const { members, ...scopeWithoutMembers } = scope;
+    return buildScopesJoinResponse(scopeWithoutMembers, agent);
+  }
+  #handleScopesLeave(params) {
+    const scope = this.#scopes.get(params.scopeId);
+    if (!scope) {
+      throw MAPRequestError.scopeNotFound(params.scopeId);
+    }
+    scope.members.delete(params.agentId);
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    if (agent.scopes) {
+      agent.scopes = agent.scopes.filter((s) => s !== params.scopeId);
+    }
+    this.emitEvent({
+      type: EVENT_TYPES.SCOPE_MEMBER_LEFT,
+      source: params.agentId,
+      data: { scopeId: params.scopeId, agentId: params.agentId }
+    });
+    const { members, ...scopeWithoutMembers } = scope;
+    return buildScopesLeaveResponse(scopeWithoutMembers, agent);
+  }
+  // ===========================================================================
+  // Extension Method Handlers
+  // ===========================================================================
+  #handleInject(params) {
+    const agent = this.#agents.get(params.agentId);
+    if (!agent) {
+      throw MAPRequestError.agentNotFound(params.agentId);
+    }
+    return { injected: true, delivery: params.delivery ?? "queue" };
+  }
+  // ===========================================================================
+  // Helpers
+  // ===========================================================================
+  /**
+   * Build a permission context for a connection.
+   * Returns undefined if no exposure configuration is set.
+   */
+  #buildPermissionContext(connection) {
+    if (!this.#options.exposure) {
+      return void 0;
+    }
+    let participant;
+    for (const p of this.#participants.values()) {
+      if (p.connection === connection) {
+        participant = p;
+        break;
+      }
+    }
+    if (!participant) {
+      return void 0;
+    }
+    const ownedAgentIds = [];
+    for (const agent of this.#agents.values()) {
+      if (agent.ownerId === participant.id) {
+        ownedAgentIds.push(agent.id);
+      }
+    }
+    const scopeMembership = /* @__PURE__ */ new Map();
+    for (const [scopeId, scope] of this.#scopes) {
+      const memberAgentIds = Array.from(scope.members).filter(
+        (agentId) => ownedAgentIds.includes(agentId)
+      );
+      if (memberAgentIds.length > 0) {
+        scopeMembership.set(scopeId, memberAgentIds);
+      }
+    }
+    return {
+      system: { exposure: this.#options.exposure },
+      participant: {
+        id: participant.id,
+        type: participant.type,
+        capabilities: this.#options.capabilities ?? {
+          observation: { canObserve: true, canQuery: true },
+          messaging: { canSend: true, canReceive: true, canBroadcast: true },
+          lifecycle: { canSpawn: true, canRegister: true, canUnregister: true, canStop: true, canSteer: true },
+          scopes: { canCreateScopes: true, canManageScopes: true }
+        }
+      },
+      ownedAgentIds,
+      scopeMembership
+    };
+  }
+  #resolveAddress(address, senderAgentId) {
+    if (typeof address === "string") {
+      return [this.#findParticipantForAgent(address) ?? address];
+    }
+    if ("agent" in address && !("system" in address)) {
+      const participantId = this.#findParticipantForAgent(address.agent);
+      return participantId ? [participantId] : [];
+    }
+    if ("agents" in address) {
+      return address.agents.map((agentId) => this.#findParticipantForAgent(agentId)).filter((id) => id !== void 0);
+    }
+    if ("scope" in address) {
+      const scope = this.#scopes.get(address.scope);
+      if (!scope) return [];
+      return Array.from(scope.members).map((agentId) => this.#findParticipantForAgent(agentId)).filter((id) => id !== void 0);
+    }
+    if ("broadcast" in address) {
+      return Array.from(this.#participants.keys());
+    }
+    if ("role" in address) {
+      const agents = Array.from(this.#agents.values()).filter((a) => a.role === address.role);
+      return agents.map((a) => this.#findParticipantForAgent(a.id)).filter((id) => id !== void 0);
+    }
+    if ("parent" in address || "children" in address || "siblings" in address || "ancestors" in address || "descendants" in address) {
+      return this.#resolveHierarchicalAddress(address, senderAgentId);
+    }
+    return [];
+  }
+  /**
+   * Resolve hierarchical address relative to sender agent
+   */
+  #resolveHierarchicalAddress(address, senderAgentId) {
+    if (!senderAgentId) return [];
+    const senderAgent = this.#agents.get(senderAgentId);
+    if (!senderAgent) return [];
+    const targetAgentIds = [];
+    const depth = address.depth;
+    if (address.parent && senderAgent.parent) {
+      targetAgentIds.push(senderAgent.parent);
+    }
+    if (address.children) {
+      const children = Array.from(this.#agents.values()).filter((a) => a.parent === senderAgentId);
+      targetAgentIds.push(...children.map((a) => a.id));
+    }
+    if (address.siblings && senderAgent.parent) {
+      const siblings = Array.from(this.#agents.values()).filter((a) => a.parent === senderAgent.parent && a.id !== senderAgentId);
+      targetAgentIds.push(...siblings.map((a) => a.id));
+    }
+    if (address.ancestors) {
+      let currentAgent = senderAgent;
+      let currentDepth = 0;
+      while (currentAgent.parent && (depth === void 0 || currentDepth < depth)) {
+        targetAgentIds.push(currentAgent.parent);
+        currentAgent = this.#agents.get(currentAgent.parent);
+        if (!currentAgent) break;
+        currentDepth++;
+      }
+    }
+    if (address.descendants) {
+      const collectDescendants = (agentId, currentDepth) => {
+        if (depth !== void 0 && currentDepth >= depth) return;
+        const children = Array.from(this.#agents.values()).filter((a) => a.parent === agentId);
+        for (const child of children) {
+          targetAgentIds.push(child.id);
+          collectDescendants(child.id, currentDepth + 1);
+        }
+      };
+      collectDescendants(senderAgentId, 0);
+    }
+    return targetAgentIds.map((agentId) => this.#findParticipantForAgent(agentId)).filter((id) => id !== void 0);
+  }
+  /**
+   * Find the participant ID that registered a given agent
+   */
+  #findParticipantForAgent(agentId) {
+    for (const [participantId, participant] of this.#participants) {
+      if (participant.agentId === agentId) {
+        return participantId;
+      }
+    }
+    return void 0;
+  }
+  #matchesFilter(event, filter) {
+    if (!filter) return true;
+    if (filter.eventTypes?.length) {
+      if (!filter.eventTypes.includes(event.type)) {
+        return false;
+      }
+    }
+    if (filter.agents?.length && event.source) {
+      if (!filter.agents.includes(event.source)) {
+        return false;
+      }
+    }
+    if (filter.fromAgents?.length && event.source) {
+      if (!filter.fromAgents.includes(event.source)) {
+        return false;
+      }
+    }
+    if (filter.scopes?.length) {
+      const eventData = event.data;
+      const scopeId = eventData?.scopeId;
+      if (!scopeId || !filter.scopes.includes(scopeId)) {
+        return false;
+      }
+    }
+    if (filter.fromRoles?.length && event.source) {
+      const agent = this.#agents.get(event.source);
+      if (!agent?.role || !filter.fromRoles.includes(agent.role)) {
+        return false;
+      }
+    }
+    if (filter.correlationIds?.length) {
+      const eventData = event.data;
+      const correlationId = eventData?.correlationId;
+      if (!correlationId || !filter.correlationIds.includes(correlationId)) {
+        return false;
+      }
+    }
+    if (filter.metadataMatch) {
+      const eventData = event.data;
+      const metadata = eventData?.metadata;
+      if (!metadata) return false;
+      for (const [key, value] of Object.entries(filter.metadataMatch)) {
+        if (metadata[key] !== value) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  // ===========================================================================
+  // Federation Method Handlers
+  // ===========================================================================
+  #handleFederationRoute(params) {
+    const { systemId, envelope, message } = params;
+    let actualMessage;
+    if (envelope && isValidEnvelope(envelope)) {
+      if (this.#options.federationRouting) {
+        const result = processFederationEnvelope(
+          envelope,
+          this.#options.federationRouting
+        );
+        if (!result.success) {
+          throw new MAPRequestError(result.errorCode, result.errorMessage);
+        }
+      }
+      actualMessage = unwrapEnvelope(envelope);
+    } else if (message) {
+      actualMessage = message;
+    } else {
+      throw MAPRequestError.invalidParams("Missing envelope or message");
+    }
+    this.#messages.push(actualMessage);
+    this.emitEvent({
+      type: EVENT_TYPES.MESSAGE_SENT,
+      source: actualMessage.from,
+      data: {
+        messageId: actualMessage.id,
+        from: actualMessage.from,
+        to: actualMessage.to,
+        federatedTo: systemId
+      }
+    });
+    return { routed: true, messageId: actualMessage.id };
+  }
+  // ===========================================================================
+  // Notification Handlers
+  // ===========================================================================
+  #handleSubscriptionAck(params) {
+    const { subscriptionId, upToSequence } = params;
+    const subscription = this.#subscriptions.get(subscriptionId);
+    if (subscription) {
+      subscription.lastAckedSequence = upToSequence;
+    }
+  }
+  /**
+   * Get ack state for a subscription (for testing assertions)
+   */
+  getSubscriptionAckState(subscriptionId) {
+    const subscription = this.#subscriptions.get(subscriptionId);
+    if (!subscription) return void 0;
+    return {
+      sequenceNumber: subscription.sequenceNumber,
+      lastAckedSequence: subscription.lastAckedSequence
+    };
+  }
+  // ===========================================================================
+  // Permission Handlers
+  // ===========================================================================
+  /**
+   * Handle permissions update request.
+   * Updates client capabilities and emits permission update event.
+   */
+  #handlePermissionsUpdate(connection, params) {
+    const { clientId, permissions } = params;
+    const targetParticipant = this.#participants.get(clientId);
+    if (!targetParticipant) {
+      throw MAPRequestError.invalidParams(`Client ${clientId} not found`);
+    }
+    let requestingParticipantId;
+    for (const [id, p] of this.#participants) {
+      if (p.connection === connection) {
+        requestingParticipantId = id;
+        break;
+      }
+    }
+    const existingCapabilities = targetParticipant.capabilities ?? {};
+    const effectivePermissions = {};
+    if (existingCapabilities.observation) {
+      effectivePermissions.observation = { ...existingCapabilities.observation };
+    }
+    if (existingCapabilities.messaging) {
+      effectivePermissions.messaging = { ...existingCapabilities.messaging };
+    }
+    if (existingCapabilities.lifecycle) {
+      effectivePermissions.lifecycle = { ...existingCapabilities.lifecycle };
+    }
+    if (existingCapabilities.scopes) {
+      effectivePermissions.scopes = { ...existingCapabilities.scopes };
+    }
+    if (existingCapabilities.federation) {
+      effectivePermissions.federation = { ...existingCapabilities.federation };
+    }
+    if (existingCapabilities.streaming) {
+      effectivePermissions.streaming = { ...existingCapabilities.streaming };
+    }
+    if (permissions.observation) {
+      effectivePermissions.observation = {
+        ...effectivePermissions.observation,
+        ...permissions.observation
+      };
+    }
+    if (permissions.messaging) {
+      effectivePermissions.messaging = {
+        ...effectivePermissions.messaging,
+        ...permissions.messaging
+      };
+    }
+    if (permissions.lifecycle) {
+      effectivePermissions.lifecycle = {
+        ...effectivePermissions.lifecycle,
+        ...permissions.lifecycle
+      };
+    }
+    if (permissions.scopes) {
+      effectivePermissions.scopes = {
+        ...effectivePermissions.scopes,
+        ...permissions.scopes
+      };
+    }
+    if (permissions.federation) {
+      effectivePermissions.federation = {
+        ...effectivePermissions.federation,
+        ...permissions.federation
+      };
+    }
+    if (permissions.streaming) {
+      effectivePermissions.streaming = {
+        ...effectivePermissions.streaming,
+        ...permissions.streaming
+      };
+    }
+    targetParticipant.capabilities = effectivePermissions;
+    this.emitEvent({
+      type: EVENT_TYPES.PERMISSIONS_CLIENT_UPDATED,
+      data: {
+        clientId,
+        changes: permissions,
+        effectivePermissions,
+        changedBy: requestingParticipantId
+      }
+    });
+    return {
+      success: true,
+      effectivePermissions
+    };
+  }
+};
+
+// src/subscription/index.ts
+var Subscription = class {
+  id;
+  filter;
+  #eventHandlers = /* @__PURE__ */ new Set();
+  #overflowHandlers = /* @__PURE__ */ new Set();
+  #eventQueue = [];
+  #bufferSize;
+  #unsubscribe;
+  #sendAck;
+  // Deduplication tracking
+  #seenEventIds = /* @__PURE__ */ new Set();
+  #seenEventIdOrder = [];
+  // For LRU eviction
+  #maxSeenEventIds;
+  #eventResolver = null;
+  #pauseResolver = null;
+  #state = "active";
+  #lastSequenceNumber = -1;
+  #lastEventId;
+  #lastTimestamp;
+  // Overflow tracking
+  #totalDropped = 0;
+  #oldestDroppedId;
+  #newestDroppedId;
+  // Ack support
+  #serverSupportsAck = false;
+  constructor(id, unsubscribe, options = {}, sendAck) {
+    this.id = id;
+    this.filter = options.filter;
+    this.#bufferSize = options.bufferSize ?? 1e3;
+    this.#maxSeenEventIds = options.maxSeenEventIds ?? 1e4;
+    this.#unsubscribe = unsubscribe;
+    this.#sendAck = sendAck;
+  }
+  /**
+   * Current subscription state
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * Whether the subscription is closed
+   */
+  get isClosed() {
+    return this.#state === "closed";
+  }
+  /**
+   * Whether the subscription is paused
+   */
+  get isPaused() {
+    return this.#state === "paused";
+  }
+  /**
+   * Last received sequence number (for ordering verification)
+   */
+  get lastSequenceNumber() {
+    return this.#lastSequenceNumber;
+  }
+  /**
+   * Last received eventId (for replay positioning)
+   */
+  get lastEventId() {
+    return this.#lastEventId;
+  }
+  /**
+   * Last received server timestamp
+   */
+  get lastTimestamp() {
+    return this.#lastTimestamp;
+  }
+  /**
+   * Number of events currently buffered
+   */
+  get bufferedCount() {
+    return this.#eventQueue.length;
+  }
+  /**
+   * Number of eventIds being tracked for deduplication
+   */
+  get trackedEventIdCount() {
+    return this.#seenEventIds.size;
+  }
+  /**
+   * Total number of events dropped due to buffer overflow
+   */
+  get totalDropped() {
+    return this.#totalDropped;
+  }
+  /**
+   * Whether the server supports acknowledgments
+   */
+  get supportsAck() {
+    return this.#serverSupportsAck && !!this.#sendAck;
+  }
+  /**
+   * Pause event delivery from the async iterator.
+   * Events are still buffered but not yielded until resume() is called.
+   * Event handlers (on('event', ...)) still receive events while paused.
+   */
+  pause() {
+    if (this.#state === "closed") return;
+    this.#state = "paused";
+  }
+  /**
+   * Resume event delivery from the async iterator.
+   * Any events buffered during pause will be yielded.
+   */
+  resume() {
+    if (this.#state === "closed") return;
+    this.#state = "active";
+    if (this.#pauseResolver) {
+      this.#pauseResolver();
+      this.#pauseResolver = null;
+    }
+    if (this.#eventResolver && this.#eventQueue.length > 0) {
+      const event = this.#eventQueue.shift();
+      this.#eventResolver(event);
+      this.#eventResolver = null;
+    }
+  }
+  /**
+   * Acknowledge events up to a sequence number.
+   * No-op if server doesn't support acks.
+   *
+   * @param upToSequence - Acknowledge all events up to and including this sequence.
+   *                       If omitted, acknowledges up to lastSequenceNumber.
+   */
+  ack(upToSequence) {
+    if (!this.supportsAck) return;
+    const seq = upToSequence ?? this.#lastSequenceNumber;
+    if (seq < 0) return;
+    this.#sendAck({
+      subscriptionId: this.id,
+      upToSequence: seq
+    });
+  }
+  on(type, handler) {
+    if (type === "event") {
+      this.#eventHandlers.add(handler);
+    } else if (type === "overflow") {
+      this.#overflowHandlers.add(handler);
+    }
+    return this;
+  }
+  off(type, handler) {
+    if (type === "event") {
+      this.#eventHandlers.delete(handler);
+    } else if (type === "overflow") {
+      this.#overflowHandlers.delete(handler);
+    }
+    return this;
+  }
+  /**
+   * Register a one-time event handler
+   */
+  once(type, handler) {
+    if (type === "event") {
+      const wrapper = (event) => {
+        this.off("event", wrapper);
+        handler(event);
+      };
+      this.on("event", wrapper);
+    }
+    return this;
+  }
+  /**
+   * Unsubscribe and close the subscription
+   */
+  async unsubscribe() {
+    if (this.#state === "closed") return;
+    this.#state = "closed";
+    if (this.#eventResolver) {
+      this.#eventResolver(null);
+      this.#eventResolver = null;
+    }
+    if (this.#pauseResolver) {
+      this.#pauseResolver();
+      this.#pauseResolver = null;
+    }
+    this.#eventHandlers.clear();
+    this.#overflowHandlers.clear();
+    this.#seenEventIds.clear();
+    this.#seenEventIdOrder.length = 0;
+    await this.#unsubscribe();
+  }
+  /**
+   * Set whether server supports acknowledgments.
+   * Called by connection after capability negotiation.
+   * @internal
+   */
+  _setServerSupportsAck(supports) {
+    this.#serverSupportsAck = supports;
+  }
+  /**
+   * Push an event to the subscription (called by connection)
+   * @internal
+   */
+  _pushEvent(params) {
+    if (this.#state === "closed") return;
+    const { sequenceNumber, eventId, timestamp, event } = params;
+    if (eventId) {
+      if (this.#seenEventIds.has(eventId)) {
+        return;
+      }
+      this.#seenEventIds.add(eventId);
+      this.#seenEventIdOrder.push(eventId);
+      while (this.#seenEventIds.size > this.#maxSeenEventIds) {
+        const oldestId = this.#seenEventIdOrder.shift();
+        if (oldestId) {
+          this.#seenEventIds.delete(oldestId);
+        }
+      }
+      this.#lastEventId = eventId;
+    }
+    if (timestamp !== void 0) {
+      this.#lastTimestamp = timestamp;
+    }
+    if (this.#lastSequenceNumber >= 0 && sequenceNumber !== this.#lastSequenceNumber + 1) {
+      console.warn(
+        `MAP: Subscription ${this.id} sequence gap: expected ${this.#lastSequenceNumber + 1}, got ${sequenceNumber}`
+      );
+    }
+    this.#lastSequenceNumber = sequenceNumber;
+    for (const handler of this.#eventHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error("MAP: Event handler error:", error);
+      }
+    }
+    if (this.#eventResolver && this.#state === "active") {
+      this.#eventResolver(event);
+      this.#eventResolver = null;
+      return;
+    }
+    if (this.#eventQueue.length < this.#bufferSize) {
+      this.#eventQueue.push(event);
+    } else {
+      this.#totalDropped++;
+      if (eventId) {
+        if (this.#oldestDroppedId === void 0) {
+          this.#oldestDroppedId = eventId;
+        }
+        this.#newestDroppedId = eventId;
+      }
+      const info = {
+        eventsDropped: 1,
+        oldestDroppedId: this.#oldestDroppedId,
+        newestDroppedId: this.#newestDroppedId,
+        timestamp: Date.now(),
+        totalDropped: this.#totalDropped
+      };
+      for (const handler of this.#overflowHandlers) {
+        try {
+          handler(info);
+        } catch (error) {
+          console.error("MAP: Overflow handler error:", error);
+        }
+      }
+      console.warn(`MAP: Subscription ${this.id} buffer full, dropping event`);
+    }
+  }
+  /**
+   * Mark the subscription as closed (called by connection)
+   * @internal
+   */
+  _close() {
+    this.#state = "closed";
+    if (this.#eventResolver) {
+      this.#eventResolver(null);
+      this.#eventResolver = null;
+    }
+    if (this.#pauseResolver) {
+      this.#pauseResolver();
+      this.#pauseResolver = null;
+    }
+  }
+  /**
+   * Async iterator implementation
+   */
+  async *[Symbol.asyncIterator]() {
+    while (!this.isClosed) {
+      while (this.isPaused) {
+        await new Promise((resolve) => {
+          this.#pauseResolver = resolve;
+        });
+        if (this.isClosed) {
+          while (this.#eventQueue.length > 0) {
+            yield this.#eventQueue.shift();
+          }
+          return;
+        }
+      }
+      if (this.#eventQueue.length > 0) {
+        yield this.#eventQueue.shift();
+        continue;
+      }
+      const event = await new Promise((resolve) => {
+        this.#eventResolver = resolve;
+      });
+      if (event === null) {
+        break;
+      }
+      yield event;
+    }
+    while (this.#eventQueue.length > 0) {
+      yield this.#eventQueue.shift();
+    }
+  }
+};
+function createSubscription(id, unsubscribe, options, sendAck) {
+  return new Subscription(id, unsubscribe, options, sendAck);
+}
+
+// src/connection/client.ts
+var ClientConnection = class {
+  #connection;
+  #subscriptions = /* @__PURE__ */ new Map();
+  #subscriptionStates = /* @__PURE__ */ new Map();
+  #reconnectionHandlers = /* @__PURE__ */ new Set();
+  #options;
+  #sessionId = null;
+  #serverCapabilities = null;
+  #connected = false;
+  #lastConnectOptions;
+  #isReconnecting = false;
+  constructor(stream, options = {}) {
+    this.#connection = new BaseConnection(stream, options);
+    this.#options = options;
+    this.#connection.setNotificationHandler(this.#handleNotification.bind(this));
+    if (options.reconnection?.enabled && options.createStream) {
+      this.#connection.onStateChange((newState) => {
+        if (newState === "closed" && this.#connected && !this.#isReconnecting) {
+          void this.#handleDisconnect();
+        }
+      });
+    }
+  }
+  // ===========================================================================
+  // Connection Lifecycle
+  // ===========================================================================
+  /**
+   * Connect to the MAP system
+   */
+  async connect(options) {
+    const params = {
+      protocolVersion: PROTOCOL_VERSION,
+      participantType: "client",
+      name: this.#options.name,
+      capabilities: this.#options.capabilities,
+      sessionId: options?.sessionId,
+      auth: options?.auth
+    };
+    const result = await this.#connection.sendRequest(CORE_METHODS.CONNECT, params);
+    this.#sessionId = result.sessionId;
+    this.#serverCapabilities = result.capabilities;
+    this.#connected = true;
+    this.#connection._transitionTo("connected");
+    this.#lastConnectOptions = options;
+    return result;
+  }
+  /**
+   * Disconnect from the MAP system
+   */
+  async disconnect(reason) {
+    if (!this.#connected) return;
+    try {
+      await this.#connection.sendRequest(
+        CORE_METHODS.DISCONNECT,
+        reason ? { reason } : void 0
+      );
+    } finally {
+      for (const subscription of this.#subscriptions.values()) {
+        subscription._close();
+      }
+      this.#subscriptions.clear();
+      await this.#connection.close();
+      this.#connected = false;
+    }
+  }
+  /**
+   * Whether the client is connected
+   */
+  get isConnected() {
+    return this.#connected && !this.#connection.isClosed;
+  }
+  /**
+   * Current session ID
+   */
+  get sessionId() {
+    return this.#sessionId;
+  }
+  /**
+   * Server capabilities
+   */
+  get serverCapabilities() {
+    return this.#serverCapabilities;
+  }
+  /**
+   * AbortSignal that triggers when the connection closes
+   */
+  get signal() {
+    return this.#connection.signal;
+  }
+  /**
+   * Promise that resolves when the connection closes
+   */
+  get closed() {
+    return this.#connection.closed;
+  }
+  // ===========================================================================
+  // Session Management
+  // ===========================================================================
+  /**
+   * List available sessions
+   */
+  async listSessions() {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LIST);
+  }
+  /**
+   * Load an existing session
+   */
+  async loadSession(sessionId) {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LOAD, { sessionId });
+  }
+  /**
+   * Close the current session
+   */
+  async closeSession(sessionId) {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_CLOSE, { sessionId });
+  }
+  // ===========================================================================
+  // Agent Queries
+  // ===========================================================================
+  /**
+   * List agents with optional filters
+   */
+  async listAgents(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.AGENTS_LIST, options);
+  }
+  /**
+   * Get a single agent by ID
+   */
+  async getAgent(agentId, options) {
+    const params = { agentId, ...options };
+    return this.#connection.sendRequest(
+      OBSERVATION_METHODS.AGENTS_GET,
+      params
+    );
+  }
+  /**
+   * Get the agent structure/hierarchy graph
+   */
+  async getStructureGraph(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.STRUCTURE_GRAPH, options);
+  }
+  // ===========================================================================
+  // Scope Queries
+  // ===========================================================================
+  /**
+   * List scopes
+   */
+  async listScopes(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_LIST, options);
+  }
+  /**
+   * Get a single scope by ID
+   */
+  async getScope(scopeId) {
+    const result = await this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_GET, { scopeId });
+    return result.scope;
+  }
+  /**
+   * List members of a scope
+   */
+  async getScopeMembers(scopeId, options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_MEMBERS, {
+      scopeId,
+      ...options
+    });
+  }
+  // ===========================================================================
+  // Messaging
+  // ===========================================================================
+  /**
+   * Send a message to an address
+   */
+  async send(to, payload, meta) {
+    const params = { to };
+    if (payload !== void 0) params.payload = payload;
+    if (meta) params.meta = meta;
+    return this.#connection.sendRequest(CORE_METHODS.SEND, params);
+  }
+  /**
+   * Send a message to a specific agent
+   */
+  async sendToAgent(agentId, payload, meta) {
+    return this.send({ agent: agentId }, payload, meta);
+  }
+  /**
+   * Send a message to all agents in a scope
+   */
+  async sendToScope(scopeId, payload, meta) {
+    return this.send({ scope: scopeId }, payload, meta);
+  }
+  /**
+   * Send a message to agents with a specific role
+   */
+  async sendToRole(role, payload, meta, withinScope) {
+    return this.send({ role, within: withinScope }, payload, meta);
+  }
+  /**
+   * Broadcast a message to all agents
+   */
+  async broadcast(payload, meta) {
+    return this.send({ broadcast: true }, payload, meta);
+  }
+  /**
+   * Send a request and wait for a correlated response
+   *
+   * This is a higher-level pattern for request/response messaging.
+   * A correlationId is automatically generated.
+   */
+  async request(to, payload, options) {
+    const correlationId = `req-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const responseSub = await this.subscribe({
+      // We'll filter in the handler since subscription filters don't support correlationId
+    });
+    try {
+      await this.send(to, payload, {
+        ...options?.meta,
+        expectsResponse: true,
+        correlationId
+      });
+      const timeout = options?.timeout ?? 3e4;
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`Request timed out after ${timeout}ms`)), timeout);
+      });
+      const responsePromise = (async () => {
+        for await (const event of responseSub) {
+          if (event.type === "message_delivered" && event.data && event.data.correlationId === correlationId) {
+            return event.data.message;
+          }
+        }
+        throw new Error("Subscription closed before response received");
+      })();
+      return await Promise.race([responsePromise, timeoutPromise]);
+    } finally {
+      await responseSub.unsubscribe();
+    }
+  }
+  // ===========================================================================
+  // Subscriptions
+  // ===========================================================================
+  /**
+   * Subscribe to events
+   */
+  async subscribe(filter) {
+    const params = {};
+    if (filter) params.filter = filter;
+    const result = await this.#connection.sendRequest(CORE_METHODS.SUBSCRIBE, params);
+    const serverSupportsAck = this.#serverCapabilities?.streaming?.supportsAck === true;
+    const sendAck = serverSupportsAck ? (ackParams) => {
+      this.#connection.sendNotification(NOTIFICATION_METHODS.SUBSCRIBE_ACK, ackParams);
+    } : void 0;
+    const subscription = createSubscription(
+      result.subscriptionId,
+      () => this.unsubscribe(result.subscriptionId),
+      { filter },
+      sendAck
+    );
+    if (serverSupportsAck) {
+      subscription._setServerSupportsAck(true);
+    }
+    this.#subscriptions.set(result.subscriptionId, subscription);
+    if (this.#options.reconnection?.restoreSubscriptions !== false) {
+      this.#subscriptionStates.set(result.subscriptionId, {
+        filter,
+        handlers: /* @__PURE__ */ new Set()
+      });
+      const originalPushEvent = subscription._pushEvent.bind(subscription);
+      subscription._pushEvent = (event) => {
+        const state = this.#subscriptionStates.get(result.subscriptionId);
+        if (state && event.eventId) {
+          state.lastEventId = event.eventId;
+        }
+        originalPushEvent(event);
+      };
+    }
+    return subscription;
+  }
+  /**
+   * Unsubscribe from events
+   */
+  async unsubscribe(subscriptionId) {
+    const subscription = this.#subscriptions.get(subscriptionId);
+    if (subscription) {
+      subscription._close();
+      this.#subscriptions.delete(subscriptionId);
+    }
+    this.#subscriptionStates.delete(subscriptionId);
+    await this.#connection.sendRequest(CORE_METHODS.UNSUBSCRIBE, { subscriptionId });
+  }
+  // ===========================================================================
+  // Event Replay
+  // ===========================================================================
+  /**
+   * Replay historical events.
+   *
+   * Uses keyset pagination - pass the last eventId from the previous
+   * response to get the next page.
+   *
+   * @example
+   * ```typescript
+   * // Replay all events from the last hour
+   * const result = await client.replay({
+   *   fromTimestamp: Date.now() - 3600000,
+   *   filter: { eventTypes: ['agent.registered'] },
+   *   limit: 100
+   * });
+   *
+   * // Paginate through results
+   * let afterEventId: string | undefined;
+   * do {
+   *   const page = await client.replay({ afterEventId, limit: 100 });
+   *   for (const item of page.events) {
+   *     console.log(item.eventId, item.event);
+   *   }
+   *   afterEventId = page.events.at(-1)?.eventId;
+   * } while (page.hasMore);
+   * ```
+   */
+  async replay(params = {}) {
+    const limit = Math.min(params.limit ?? 100, 1e3);
+    return this.#connection.sendRequest(
+      CORE_METHODS.REPLAY,
+      { ...params, limit }
+    );
+  }
+  /**
+   * Replay all events matching filter, handling pagination automatically.
+   *
+   * Returns an async generator for streaming through all results.
+   *
+   * @example
+   * ```typescript
+   * for await (const item of client.replayAll({
+   *   filter: { eventTypes: ['agent.registered'] }
+   * })) {
+   *   console.log(item.eventId, item.event);
+   * }
+   * ```
+   */
+  async *replayAll(params = {}) {
+    let afterEventId;
+    let hasMore = true;
+    while (hasMore) {
+      const result = await this.replay({ ...params, afterEventId });
+      for (const item of result.events) {
+        yield item;
+      }
+      hasMore = result.hasMore;
+      afterEventId = result.events.at(-1)?.eventId;
+      if (result.events.length === 0) {
+        break;
+      }
+    }
+  }
+  // ===========================================================================
+  // Steering (requires canSteer capability)
+  // ===========================================================================
+  /**
+   * Inject context into a running agent
+   */
+  async inject(agentId, content, delivery) {
+    const params = { agentId, content };
+    if (delivery) params.delivery = delivery;
+    return this.#connection.sendRequest(STEERING_METHODS.INJECT, params);
+  }
+  // ===========================================================================
+  // Lifecycle Control (requires canStop capability)
+  // ===========================================================================
+  /**
+   * Request an agent to stop
+   */
+  async stopAgent(agentId, options) {
+    return this.#connection.sendRequest(STATE_METHODS.AGENTS_STOP, {
+      agentId,
+      ...options
+    });
+  }
+  /**
+   * Suspend an agent
+   */
+  async suspendAgent(agentId, reason) {
+    return this.#connection.sendRequest(STATE_METHODS.AGENTS_SUSPEND, {
+      agentId,
+      reason
+    });
+  }
+  /**
+   * Resume a suspended agent
+   */
+  async resumeAgent(agentId) {
+    return this.#connection.sendRequest(STATE_METHODS.AGENTS_RESUME, { agentId });
+  }
+  // ===========================================================================
+  // Reconnection
+  // ===========================================================================
+  /**
+   * Current connection state
+   */
+  get state() {
+    return this.#connection.state;
+  }
+  /**
+   * Whether the connection is currently reconnecting
+   */
+  get isReconnecting() {
+    return this.#isReconnecting;
+  }
+  /**
+   * Register a handler for reconnection events.
+   *
+   * @param handler - Function called when reconnection events occur
+   * @returns Unsubscribe function to remove the handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = client.onReconnection((event) => {
+   *   switch (event.type) {
+   *     case 'disconnected':
+   *       console.log('Connection lost');
+   *       break;
+   *     case 'reconnecting':
+   *       console.log(`Reconnecting, attempt ${event.attempt}`);
+   *       break;
+   *     case 'reconnected':
+   *       console.log('Reconnected successfully');
+   *       break;
+   *     case 'reconnectFailed':
+   *       console.log('Failed to reconnect:', event.error);
+   *       break;
+   *   }
+   * });
+   * ```
+   */
+  onReconnection(handler) {
+    this.#reconnectionHandlers.add(handler);
+    return () => this.#reconnectionHandlers.delete(handler);
+  }
+  /**
+   * Register a handler for connection state changes.
+   *
+   * @param handler - Function called when state changes
+   * @returns Unsubscribe function to remove the handler
+   */
+  onStateChange(handler) {
+    return this.#connection.onStateChange(handler);
+  }
+  // ===========================================================================
+  // Internal
+  // ===========================================================================
+  /**
+   * Handle incoming notifications
+   */
+  async #handleNotification(method, params) {
+    switch (method) {
+      case NOTIFICATION_METHODS.EVENT: {
+        const eventParams = params;
+        const subscription = this.#subscriptions.get(eventParams.subscriptionId);
+        if (subscription) {
+          subscription._pushEvent(eventParams);
+        } else {
+          console.warn("MAP: Event for unknown subscription:", eventParams.subscriptionId);
+        }
+        break;
+      }
+      case NOTIFICATION_METHODS.MESSAGE: {
+        break;
+      }
+      default:
+        console.warn("MAP: Unknown notification:", method);
+    }
+  }
+  /**
+   * Emit a reconnection event to all registered handlers
+   */
+  #emitReconnectionEvent(event) {
+    for (const handler of this.#reconnectionHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error("MAP: Reconnection event handler error:", error);
+      }
+    }
+  }
+  /**
+   * Handle disconnect when auto-reconnect is enabled
+   */
+  async #handleDisconnect() {
+    this.#isReconnecting = true;
+    this.#connected = false;
+    this.#emitReconnectionEvent({ type: "disconnected" });
+    try {
+      await this.#attemptReconnect();
+    } catch (error) {
+      this.#isReconnecting = false;
+      this.#emitReconnectionEvent({
+        type: "reconnectFailed",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Attempt to reconnect with retry logic
+   */
+  async #attemptReconnect() {
+    const options = this.#options.reconnection;
+    const createStream = this.#options.createStream;
+    const retryPolicy = {
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
+      maxDelayMs: options.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+      jitter: options.jitter ?? DEFAULT_RETRY_POLICY.jitter
+    };
+    await withRetry(
+      async () => {
+        const newStream = await createStream();
+        await this.#connection.reconnect(newStream);
+        const connectResult = await this.connect(this.#lastConnectOptions);
+        this.#sessionId = connectResult.sessionId;
+        this.#serverCapabilities = connectResult.capabilities;
+      },
+      retryPolicy,
+      {
+        onRetry: (state) => {
+          this.#emitReconnectionEvent({
+            type: "reconnecting",
+            attempt: state.attempt,
+            delay: state.nextDelayMs,
+            error: state.lastError
+          });
+        }
+      }
+    );
+    this.#isReconnecting = false;
+    this.#emitReconnectionEvent({ type: "reconnected" });
+    if (options.restoreSubscriptions !== false) {
+      await this.#restoreSubscriptions();
+    }
+  }
+  /**
+   * Restore subscriptions after reconnection
+   */
+  async #restoreSubscriptions() {
+    const options = this.#options.reconnection;
+    const subscriptionEntries = Array.from(this.#subscriptionStates.entries());
+    this.#subscriptions.clear();
+    this.#subscriptionStates.clear();
+    for (const [oldId, state] of subscriptionEntries) {
+      try {
+        const newSubscription = await this.subscribe(state.filter);
+        const newId = newSubscription.id;
+        if (options.replayOnRestore !== false && state.lastEventId) {
+          const maxEvents = options.maxReplayEventsPerSubscription ?? 1e3;
+          try {
+            let replayedCount = 0;
+            let afterEventId = state.lastEventId;
+            let hasMore = true;
+            while (hasMore && replayedCount < maxEvents) {
+              const result = await this.replay({
+                afterEventId,
+                filter: state.filter,
+                limit: Math.min(100, maxEvents - replayedCount)
+              });
+              for (const replayedEvent of result.events) {
+                if (replayedCount >= maxEvents) break;
+                newSubscription._pushEvent({
+                  subscriptionId: newId,
+                  sequenceNumber: replayedCount + 1,
+                  eventId: replayedEvent.eventId,
+                  timestamp: replayedEvent.timestamp,
+                  event: replayedEvent.event
+                });
+                replayedCount++;
+              }
+              hasMore = result.hasMore;
+              afterEventId = result.events.at(-1)?.eventId;
+              if (result.events.length === 0) {
+                break;
+              }
+            }
+          } catch (replayError) {
+            console.warn("MAP: Failed to replay events for subscription:", oldId, replayError);
+          }
+        }
+        this.#emitReconnectionEvent({
+          type: "subscriptionRestored",
+          subscriptionId: oldId,
+          newSubscriptionId: newId
+        });
+      } catch (error) {
+        this.#emitReconnectionEvent({
+          type: "subscriptionRestoreFailed",
+          subscriptionId: oldId,
+          error: error instanceof Error ? error : new Error(String(error))
+        });
+      }
+    }
+  }
+};
+
+// src/stream/index.ts
+function createStreamPair() {
+  const clientToServer = [];
+  const serverToClient = [];
+  let clientToServerResolver = null;
+  let serverToClientResolver = null;
+  let clientToServerClosed = false;
+  let serverToClientClosed = false;
+  function createReadable(queue, _getResolver, setResolver, isClosed) {
+    return new ReadableStream({
+      async pull(controller) {
+        if (queue.length > 0) {
+          controller.enqueue(queue.shift());
+          return;
+        }
+        if (isClosed()) {
+          controller.close();
+          return;
+        }
+        const message = await new Promise((resolve) => {
+          setResolver((msg) => {
+            setResolver(null);
+            resolve(msg);
+          });
+        });
+        if (message === null) {
+          controller.close();
+        } else {
+          controller.enqueue(message);
+        }
+      }
+    });
+  }
+  function createWritable(queue, getResolver, setClosed) {
+    return new WritableStream({
+      write(message) {
+        const resolver = getResolver();
+        if (resolver) {
+          resolver(message);
+        } else {
+          queue.push(message);
+        }
+      },
+      close() {
+        setClosed();
+        const resolver = getResolver();
+        if (resolver) {
+          resolver(null);
+        }
+      }
+    });
+  }
+  const clientStream = {
+    // Client writes to server
+    writable: createWritable(
+      clientToServer,
+      () => clientToServerResolver,
+      () => {
+        clientToServerClosed = true;
+      }
+    ),
+    // Client reads from server
+    readable: createReadable(
+      serverToClient,
+      () => serverToClientResolver,
+      (r) => {
+        serverToClientResolver = r;
+      },
+      () => serverToClientClosed
+    )
+  };
+  const serverStream = {
+    // Server writes to client
+    writable: createWritable(
+      serverToClient,
+      () => serverToClientResolver,
+      () => {
+        serverToClientClosed = true;
+      }
+    ),
+    // Server reads from client
+    readable: createReadable(
+      clientToServer,
+      () => clientToServerResolver,
+      (r) => {
+        clientToServerResolver = r;
+      },
+      () => clientToServerClosed
+    )
+  };
+  return [clientStream, serverStream];
+}
+
+// src/testing/client.ts
+var TestClient = class _TestClient {
+  #connection;
+  #subscriptions = /* @__PURE__ */ new Map();
+  constructor(connection) {
+    this.#connection = connection;
+  }
+  /**
+   * Create and connect a test client
+   */
+  static async create(server, options = {}) {
+    const [clientStream, serverStream] = createStreamPair();
+    const connection = new ClientConnection(clientStream, options);
+    server.acceptConnection(serverStream);
+    const client = new _TestClient(connection);
+    if (options.autoConnect !== false) {
+      await connection.connect();
+    }
+    return client;
+  }
+  /**
+   * Get the underlying connection
+   */
+  get connection() {
+    return this.#connection;
+  }
+  /**
+   * Whether the client is connected
+   */
+  get isConnected() {
+    return this.#connection.isConnected;
+  }
+  /**
+   * Current session ID
+   */
+  get sessionId() {
+    return this.#connection.sessionId;
+  }
+  /**
+   * Connect to the server
+   */
+  async connect() {
+    await this.#connection.connect();
+  }
+  /**
+   * Disconnect from the server
+   */
+  async disconnect() {
+    for (const sub of this.#subscriptions.values()) {
+      await sub.unsubscribe();
+    }
+    this.#subscriptions.clear();
+    await this.#connection.disconnect();
+  }
+  // ===========================================================================
+  // Agent Queries
+  // ===========================================================================
+  /**
+   * List all agents
+   */
+  async listAgents(options) {
+    const result = await this.#connection.listAgents(options);
+    return result.agents;
+  }
+  /**
+   * Get agent by ID with optional hierarchy expansion
+   */
+  async getAgent(agentId, options) {
+    return this.#connection.getAgent(agentId, options);
+  }
+  /**
+   * Find agent by name
+   */
+  async findAgentByName(name) {
+    const agents = await this.listAgents();
+    return agents.find((a) => a.name === name);
+  }
+  /**
+   * Find agents by role
+   */
+  async findAgentsByRole(role) {
+    const result = await this.#connection.listAgents({ filter: { roles: [role] } });
+    return result.agents;
+  }
+  // ===========================================================================
+  // Scope Queries
+  // ===========================================================================
+  /**
+   * List all scopes
+   */
+  async listScopes(options) {
+    const result = await this.#connection.listScopes(options);
+    return result.scopes;
+  }
+  /**
+   * Get scope by ID
+   */
+  async getScope(scopeId) {
+    return this.#connection.getScope(scopeId);
+  }
+  // ===========================================================================
+  // Messaging
+  // ===========================================================================
+  /**
+   * Send message to agent
+   */
+  async sendTo(agentId, payload) {
+    const result = await this.#connection.sendToAgent(agentId, payload);
+    return result.messageId;
+  }
+  /**
+   * Broadcast to all agents
+   */
+  async broadcast(payload) {
+    const result = await this.#connection.broadcast(payload);
+    return result.messageId;
+  }
+  /**
+   * Send to all agents with a specific role
+   */
+  async sendToRole(role, payload) {
+    const result = await this.#connection.sendToRole(role, payload);
+    return result.messageId;
+  }
+  /**
+   * Send to all agents in a scope
+   */
+  async sendToScope(scopeId, payload) {
+    const result = await this.#connection.sendToScope(scopeId, payload);
+    return result.messageId;
+  }
+  // ===========================================================================
+  // Subscriptions
+  // ===========================================================================
+  /**
+   * Subscribe to events with automatic tracking
+   */
+  async subscribe(filter) {
+    const subscription = await this.#connection.subscribe(filter);
+    this.#subscriptions.set(subscription.id, subscription);
+    return subscription;
+  }
+  /**
+   * Collect events matching filter for a duration
+   */
+  async collectEvents(filter, durationMs) {
+    const events = [];
+    const subscription = await this.subscribe(filter);
+    subscription.on("event", (event) => events.push(event));
+    await new Promise((resolve) => setTimeout(resolve, durationMs));
+    await subscription.unsubscribe();
+    this.#subscriptions.delete(subscription.id);
+    return events;
+  }
+  /**
+   * Wait for a specific event type
+   */
+  async waitForEvent(eventType, timeoutMs = 5e3) {
+    const subscription = await this.subscribe({ eventTypes: [eventType] });
+    try {
+      return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error(`Timeout waiting for event: ${eventType}`));
+        }, timeoutMs);
+        subscription.on("event", (event) => {
+          clearTimeout(timeout);
+          resolve(event);
+        });
+      });
+    } finally {
+      await subscription.unsubscribe();
+      this.#subscriptions.delete(subscription.id);
+    }
+  }
+  // ===========================================================================
+  // Control
+  // ===========================================================================
+  /**
+   * Stop an agent
+   */
+  async stopAgent(agentId, reason) {
+    await this.#connection.stopAgent(agentId, { reason });
+  }
+  /**
+   * Inject context into an agent
+   */
+  async inject(agentId, content, delivery) {
+    await this.#connection.inject(agentId, content, delivery);
+  }
+};
+
+// src/connection/agent.ts
+var AgentConnection = class {
+  #connection;
+  #subscriptions = /* @__PURE__ */ new Map();
+  #options;
+  #messageHandlers = /* @__PURE__ */ new Set();
+  #reconnectionHandlers = /* @__PURE__ */ new Set();
+  #scopeMemberships = /* @__PURE__ */ new Set();
+  #agentId = null;
+  #sessionId = null;
+  #serverCapabilities = null;
+  #currentState = "registered";
+  #connected = false;
+  #lastConnectOptions;
+  #isReconnecting = false;
+  constructor(stream, options = {}) {
+    this.#connection = new BaseConnection(stream, options);
+    this.#options = options;
+    this.#connection.setNotificationHandler(this.#handleNotification.bind(this));
+    if (options.reconnection?.enabled && options.createStream) {
+      this.#connection.onStateChange((newState) => {
+        if (newState === "closed" && this.#connected && !this.#isReconnecting) {
+          void this.#handleDisconnect();
+        }
+      });
+    }
+  }
+  // ===========================================================================
+  // Connection Lifecycle
+  // ===========================================================================
+  /**
+   * Connect and register with the MAP system
+   */
+  async connect(options) {
+    const connectParams = {
+      protocolVersion: PROTOCOL_VERSION,
+      participantType: "agent",
+      participantId: options?.agentId,
+      name: this.#options.name,
+      capabilities: this.#options.capabilities,
+      auth: options?.auth
+    };
+    const connectResult = await this.#connection.sendRequest(CORE_METHODS.CONNECT, connectParams);
+    this.#sessionId = connectResult.sessionId;
+    this.#serverCapabilities = connectResult.capabilities;
+    this.#connected = true;
+    this.#lastConnectOptions = options;
+    const registerParams = {
+      agentId: options?.agentId,
+      name: this.#options.name,
+      role: this.#options.role,
+      parent: this.#options.parent,
+      scopes: this.#options.scopes,
+      visibility: this.#options.visibility,
+      capabilities: this.#options.capabilities
+    };
+    const registerResult = await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_REGISTER, registerParams);
+    this.#agentId = registerResult.agent.id;
+    this.#currentState = registerResult.agent.state;
+    this.#connection._transitionTo("connected");
+    return { connection: connectResult, agent: registerResult.agent };
+  }
+  /**
+   * Disconnect from the MAP system
+   */
+  async disconnect(reason) {
+    if (!this.#connected) return;
+    try {
+      if (this.#agentId) {
+        await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_UNREGISTER, {
+          agentId: this.#agentId,
+          reason
+        });
+      }
+      await this.#connection.sendRequest(
+        CORE_METHODS.DISCONNECT,
+        reason ? { reason } : void 0
+      );
+    } finally {
+      for (const subscription of this.#subscriptions.values()) {
+        subscription._close();
+      }
+      this.#subscriptions.clear();
+      await this.#connection.close();
+      this.#connected = false;
+    }
+  }
+  /**
+   * Whether the agent is connected
+   */
+  get isConnected() {
+    return this.#connected && !this.#connection.isClosed;
+  }
+  /**
+   * This agent's ID
+   */
+  get agentId() {
+    return this.#agentId;
+  }
+  /**
+   * Current session ID
+   */
+  get sessionId() {
+    return this.#sessionId;
+  }
+  /**
+   * Server capabilities
+   */
+  get serverCapabilities() {
+    return this.#serverCapabilities;
+  }
+  /**
+   * Current agent state
+   */
+  get state() {
+    return this.#currentState;
+  }
+  /**
+   * AbortSignal that triggers when the connection closes
+   */
+  get signal() {
+    return this.#connection.signal;
+  }
+  /**
+   * Promise that resolves when the connection closes
+   */
+  get closed() {
+    return this.#connection.closed;
+  }
+  // ===========================================================================
+  // Message Handling
+  // ===========================================================================
+  /**
+   * Register a handler for incoming messages
+   */
+  onMessage(handler) {
+    this.#messageHandlers.add(handler);
+    return this;
+  }
+  /**
+   * Remove a message handler
+   */
+  offMessage(handler) {
+    this.#messageHandlers.delete(handler);
+    return this;
+  }
+  // ===========================================================================
+  // State Management
+  // ===========================================================================
+  /**
+   * Update this agent's state
+   */
+  async updateState(state) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    const result = await this.#connection.sendRequest(STATE_METHODS.AGENTS_UPDATE, {
+      agentId: this.#agentId,
+      state
+    });
+    this.#currentState = result.agent.state;
+    return result.agent;
+  }
+  /**
+   * Update this agent's metadata
+   */
+  async updateMetadata(metadata) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    const result = await this.#connection.sendRequest(STATE_METHODS.AGENTS_UPDATE, {
+      agentId: this.#agentId,
+      metadata
+    });
+    return result.agent;
+  }
+  /**
+   * Mark this agent as busy
+   */
+  async busy() {
+    return this.updateState("busy");
+  }
+  /**
+   * Mark this agent as idle
+   */
+  async idle() {
+    return this.updateState("idle");
+  }
+  /**
+   * Mark this agent as done/stopped
+   */
+  async done(result) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    await this.updateState("stopped");
+    if (result) {
+      await this.updateMetadata({
+        exitCode: result.exitCode,
+        exitReason: result.exitReason
+      });
+    }
+  }
+  // ===========================================================================
+  // Child Agent Management
+  // ===========================================================================
+  /**
+   * Spawn a child agent
+   */
+  async spawn(options) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    const params = {
+      ...options,
+      parent: this.#agentId
+    };
+    return this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_SPAWN, params);
+  }
+  // ===========================================================================
+  // Messaging
+  // ===========================================================================
+  /**
+   * Send a message to an address
+   */
+  async send(to, payload, meta) {
+    const params = { to };
+    if (payload !== void 0) params.payload = payload;
+    if (meta) params.meta = meta;
+    return this.#connection.sendRequest(CORE_METHODS.SEND, params);
+  }
+  /**
+   * Send a message to the parent agent
+   */
+  async sendToParent(payload, meta) {
+    return this.send({ parent: true }, payload, {
+      ...meta,
+      relationship: "child-to-parent"
+    });
+  }
+  /**
+   * Send a message to child agents
+   */
+  async sendToChildren(payload, meta) {
+    return this.send({ children: true }, payload, {
+      ...meta,
+      relationship: "parent-to-child"
+    });
+  }
+  /**
+   * Send a message to a specific agent
+   */
+  async sendToAgent(agentId, payload, meta) {
+    return this.send({ agent: agentId }, payload, meta);
+  }
+  /**
+   * Send a message to all agents in a scope
+   */
+  async sendToScope(scopeId, payload, meta) {
+    return this.send({ scope: scopeId }, payload, meta);
+  }
+  /**
+   * Send a message to sibling agents
+   */
+  async sendToSiblings(payload, meta) {
+    return this.send({ siblings: true }, payload, {
+      ...meta,
+      relationship: "peer"
+    });
+  }
+  /**
+   * Reply to a message (uses correlationId from original)
+   */
+  async reply(originalMessage, payload, meta) {
+    return this.send({ agent: originalMessage.from }, payload, {
+      ...meta,
+      correlationId: originalMessage.meta?.correlationId ?? originalMessage.id,
+      isResult: true
+    });
+  }
+  // ===========================================================================
+  // Scope Management
+  // ===========================================================================
+  /**
+   * Create a new scope
+   */
+  async createScope(options) {
+    const result = await this.#connection.sendRequest(SCOPE_METHODS.SCOPES_CREATE, options);
+    return result.scope;
+  }
+  /**
+   * Join a scope
+   */
+  async joinScope(scopeId) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    const result = await this.#connection.sendRequest(SCOPE_METHODS.SCOPES_JOIN, {
+      scopeId,
+      agentId: this.#agentId
+    });
+    this.#scopeMemberships.add(scopeId);
+    return result;
+  }
+  /**
+   * Leave a scope
+   */
+  async leaveScope(scopeId) {
+    if (!this.#agentId) {
+      throw new Error("Agent not registered");
+    }
+    const result = await this.#connection.sendRequest(SCOPE_METHODS.SCOPES_LEAVE, {
+      scopeId,
+      agentId: this.#agentId
+    });
+    this.#scopeMemberships.delete(scopeId);
+    return result;
+  }
+  // ===========================================================================
+  // Subscriptions
+  // ===========================================================================
+  /**
+   * Subscribe to events
+   */
+  async subscribe(filter) {
+    const params = {};
+    if (filter) params.filter = filter;
+    const result = await this.#connection.sendRequest(CORE_METHODS.SUBSCRIBE, params);
+    const subscription = createSubscription(
+      result.subscriptionId,
+      () => this.unsubscribe(result.subscriptionId),
+      { filter }
+    );
+    this.#subscriptions.set(result.subscriptionId, subscription);
+    return subscription;
+  }
+  /**
+   * Unsubscribe from events
+   */
+  async unsubscribe(subscriptionId) {
+    const subscription = this.#subscriptions.get(subscriptionId);
+    if (subscription) {
+      subscription._close();
+      this.#subscriptions.delete(subscriptionId);
+    }
+    await this.#connection.sendRequest(CORE_METHODS.UNSUBSCRIBE, { subscriptionId });
+  }
+  // ===========================================================================
+  // Reconnection
+  // ===========================================================================
+  /**
+   * Current connection state
+   */
+  get connectionState() {
+    return this.#connection.state;
+  }
+  /**
+   * Whether the connection is currently reconnecting
+   */
+  get isReconnecting() {
+    return this.#isReconnecting;
+  }
+  /**
+   * Register a handler for reconnection events.
+   *
+   * @param handler - Function called when reconnection events occur
+   * @returns Unsubscribe function to remove the handler
+   */
+  onReconnection(handler) {
+    this.#reconnectionHandlers.add(handler);
+    return () => this.#reconnectionHandlers.delete(handler);
+  }
+  /**
+   * Register a handler for connection state changes.
+   *
+   * @param handler - Function called when state changes
+   * @returns Unsubscribe function to remove the handler
+   */
+  onStateChange(handler) {
+    return this.#connection.onStateChange(handler);
+  }
+  // ===========================================================================
+  // Internal
+  // ===========================================================================
+  /**
+   * Handle incoming notifications
+   */
+  async #handleNotification(method, params) {
+    switch (method) {
+      case NOTIFICATION_METHODS.EVENT: {
+        const eventParams = params;
+        const subscription = this.#subscriptions.get(eventParams.subscriptionId);
+        if (subscription) {
+          subscription._pushEvent(eventParams);
+        }
+        break;
+      }
+      case NOTIFICATION_METHODS.MESSAGE: {
+        const messageParams = params;
+        for (const handler of this.#messageHandlers) {
+          try {
+            await handler(messageParams.message);
+          } catch (error) {
+            console.error("MAP: Message handler error:", error);
+          }
+        }
+        break;
+      }
+      default:
+        console.warn("MAP: Unknown notification:", method);
+    }
+  }
+  /**
+   * Emit a reconnection event to all registered handlers
+   */
+  #emitReconnectionEvent(event) {
+    for (const handler of this.#reconnectionHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error("MAP: Reconnection event handler error:", error);
+      }
+    }
+  }
+  /**
+   * Handle disconnect when auto-reconnect is enabled
+   */
+  async #handleDisconnect() {
+    this.#isReconnecting = true;
+    this.#connected = false;
+    this.#emitReconnectionEvent({ type: "disconnected" });
+    try {
+      await this.#attemptReconnect();
+    } catch (error) {
+      this.#isReconnecting = false;
+      this.#emitReconnectionEvent({
+        type: "reconnectFailed",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Attempt to reconnect with retry logic
+   */
+  async #attemptReconnect() {
+    const options = this.#options.reconnection;
+    const createStream = this.#options.createStream;
+    const retryPolicy = {
+      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+      baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
+      maxDelayMs: options.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+      jitter: options.jitter ?? DEFAULT_RETRY_POLICY.jitter
+    };
+    const scopesToRestore = Array.from(this.#scopeMemberships);
+    await withRetry(
+      async () => {
+        const newStream = await createStream();
+        await this.#connection.reconnect(newStream);
+        const result = await this.connect({
+          agentId: this.#agentId ?? this.#lastConnectOptions?.agentId,
+          auth: this.#lastConnectOptions?.auth
+        });
+        this.#agentId = result.agent.id;
+        this.#sessionId = result.connection.sessionId;
+        this.#serverCapabilities = result.connection.capabilities;
+        this.#currentState = result.agent.state;
+      },
+      retryPolicy,
+      {
+        onRetry: (state) => {
+          this.#emitReconnectionEvent({
+            type: "reconnecting",
+            attempt: state.attempt,
+            delay: state.nextDelayMs,
+            error: state.lastError
+          });
+        }
+      }
+    );
+    this.#isReconnecting = false;
+    this.#emitReconnectionEvent({ type: "reconnected" });
+    if (options.restoreScopeMemberships !== false) {
+      await this.#restoreScopeMemberships(scopesToRestore);
+    }
+  }
+  /**
+   * Restore scope memberships after reconnection
+   */
+  async #restoreScopeMemberships(scopes) {
+    this.#scopeMemberships.clear();
+    for (const scopeId of scopes) {
+      try {
+        await this.joinScope(scopeId);
+      } catch (error) {
+        console.warn("MAP: Failed to restore scope membership:", scopeId, error);
+      }
+    }
+  }
+};
+
+// src/testing/agent.ts
+var TestAgent = class _TestAgent {
+  #connection;
+  #receivedMessages = [];
+  #subscriptions = /* @__PURE__ */ new Map();
+  constructor(connection) {
+    this.#connection = connection;
+    connection.onMessage((msg) => {
+      this.#receivedMessages.push(msg);
+    });
+  }
+  /**
+   * Create and connect a test agent
+   */
+  static async create(server, options = {}) {
+    const [clientStream, serverStream] = createStreamPair();
+    const connection = new AgentConnection(clientStream, options);
+    server.acceptConnection(serverStream);
+    const agent = new _TestAgent(connection);
+    if (options.autoConnect !== false) {
+      await connection.connect({ agentId: options.agentId });
+    }
+    return agent;
+  }
+  /**
+   * Get the underlying connection
+   */
+  get connection() {
+    return this.#connection;
+  }
+  /**
+   * Whether the agent is connected
+   */
+  get isConnected() {
+    return this.#connection.isConnected;
+  }
+  /**
+   * Agent ID
+   */
+  get id() {
+    return this.#connection.agentId;
+  }
+  /**
+   * Current state
+   */
+  get state() {
+    return this.#connection.state;
+  }
+  /**
+   * Session ID
+   */
+  get sessionId() {
+    return this.#connection.sessionId;
+  }
+  /**
+   * All messages received by this agent
+   */
+  get receivedMessages() {
+    return this.#receivedMessages;
+  }
+  /**
+   * Get the last received message
+   */
+  get lastMessage() {
+    return this.#receivedMessages[this.#receivedMessages.length - 1];
+  }
+  /**
+   * Clear received messages
+   */
+  clearMessages() {
+    this.#receivedMessages.length = 0;
+  }
+  /**
+   * Connect to the server
+   */
+  async connect(agentId) {
+    const result = await this.#connection.connect({ agentId });
+    return result.agent;
+  }
+  /**
+   * Disconnect from the server
+   */
+  async disconnect(reason) {
+    for (const sub of this.#subscriptions.values()) {
+      await sub.unsubscribe();
+    }
+    this.#subscriptions.clear();
+    await this.#connection.disconnect(reason);
+  }
+  // ===========================================================================
+  // State Management
+  // ===========================================================================
+  /**
+   * Update state
+   */
+  async setState(state) {
+    return this.#connection.updateState(state);
+  }
+  /**
+   * Mark as busy
+   */
+  async busy() {
+    return this.#connection.busy();
+  }
+  /**
+   * Mark as idle
+   */
+  async idle() {
+    return this.#connection.idle();
+  }
+  /**
+   * Mark as done
+   */
+  async done(exitCode, exitReason) {
+    await this.#connection.done({ exitCode, exitReason });
+  }
+  /**
+   * Update metadata
+   */
+  async setMetadata(metadata) {
+    return this.#connection.updateMetadata(metadata);
+  }
+  // ===========================================================================
+  // Child Agent Management
+  // ===========================================================================
+  /**
+   * Spawn a child agent
+   */
+  async spawn(options = {}) {
+    const result = await this.#connection.spawn(options);
+    return result.agent;
+  }
+  /**
+   * Spawn and return a connected TestAgent for the child
+   */
+  async spawnTestAgent(server, options = {}) {
+    await this.#connection.spawn({
+      name: options.name,
+      role: options.role,
+      agentId: options.agentId
+    });
+    const child = await _TestAgent.create(server, {
+      ...options,
+      parent: this.id,
+      autoConnect: false
+    });
+    return child;
+  }
+  // ===========================================================================
+  // Scope Management
+  // ===========================================================================
+  /**
+   * Create a scope
+   */
+  async createScope(name, options) {
+    return this.#connection.createScope({ name, ...options });
+  }
+  /**
+   * Join a scope
+   */
+  async joinScope(scopeId) {
+    return this.#connection.joinScope(scopeId);
+  }
+  /**
+   * Leave a scope
+   */
+  async leaveScope(scopeId) {
+    return this.#connection.leaveScope(scopeId);
+  }
+  // ===========================================================================
+  // Messaging
+  // ===========================================================================
+  /**
+   * Send to another agent
+   */
+  async sendTo(agentId, payload) {
+    const result = await this.#connection.sendToAgent(agentId, payload);
+    return result.messageId;
+  }
+  /**
+   * Send to parent
+   */
+  async sendToParent(payload) {
+    const result = await this.#connection.sendToParent(payload);
+    return result.messageId;
+  }
+  /**
+   * Send to children
+   */
+  async sendToChildren(payload) {
+    const result = await this.#connection.sendToChildren(payload);
+    return result.messageId;
+  }
+  /**
+   * Send to siblings
+   */
+  async sendToSiblings(payload) {
+    const result = await this.#connection.sendToSiblings(payload);
+    return result.messageId;
+  }
+  /**
+   * Send to scope
+   */
+  async sendToScope(scopeId, payload) {
+    const result = await this.#connection.sendToScope(scopeId, payload);
+    return result.messageId;
+  }
+  /**
+   * Reply to a message
+   */
+  async reply(message, payload) {
+    const result = await this.#connection.reply(message, payload);
+    return result.messageId;
+  }
+  /**
+   * Wait for a message
+   */
+  async waitForMessage(timeoutMs = 5e3) {
+    const startLen = this.#receivedMessages.length;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("Timeout waiting for message"));
+      }, timeoutMs);
+      const checkInterval = setInterval(() => {
+        if (this.#receivedMessages.length > startLen) {
+          clearTimeout(timeout);
+          clearInterval(checkInterval);
+          resolve(this.#receivedMessages[this.#receivedMessages.length - 1]);
+        }
+      }, 10);
+    });
+  }
+  // ===========================================================================
+  // Subscriptions
+  // ===========================================================================
+  /**
+   * Subscribe to events
+   */
+  async subscribe(filter) {
+    const subscription = await this.#connection.subscribe(filter);
+    this.#subscriptions.set(subscription.id, subscription);
+    return subscription;
+  }
+  /**
+   * Wait for a specific event
+   */
+  async waitForEvent(eventType, timeoutMs = 5e3) {
+    const subscription = await this.subscribe({ eventTypes: [eventType] });
+    try {
+      return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error(`Timeout waiting for event: ${eventType}`));
+        }, timeoutMs);
+        subscription.on("event", (event) => {
+          clearTimeout(timeout);
+          resolve(event);
+        });
+      });
+    } finally {
+      await subscription.unsubscribe();
+      this.#subscriptions.delete(subscription.id);
+    }
+  }
+};
+
+export { TestAgent, TestClient, TestServer };
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map