@multi-agent-protocol/sdk 0.0.2

package/dist/index.js

@@ -0,0 +1,4353 @@
+export { monotonicFactory, ulid } from 'ulid';
+import { z } from 'zod';
+
+// src/types/index.ts
+function isOrphanedAgent(agent) {
+  return agent.ownerId === null;
+}
+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",
+  MESSAGE_DELIVERED: "message_delivered",
+  MESSAGE_FAILED: "message_failed",
+  // Scope events
+  SCOPE_CREATED: "scope_created",
+  SCOPE_DELETED: "scope_deleted",
+  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",
+  // System events
+  SYSTEM_ERROR: "system_error",
+  // Federation events
+  FEDERATION_CONNECTED: "federation_connected",
+  FEDERATION_DISCONNECTED: "federation_disconnected"
+};
+function createEvent(input) {
+  return {
+    id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: input.timestamp ?? Date.now(),
+    type: input.type,
+    source: input.source,
+    data: input.data,
+    causedBy: input.causedBy,
+    _meta: input._meta
+  };
+}
+var JSONRPC_VERSION = "2.0";
+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_DELETE: "map/scopes/delete",
+  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 AUTH_METHODS = {
+  AUTH_REFRESH: "map/auth/refresh"
+};
+var PERMISSION_METHODS = {
+  PERMISSIONS_UPDATE: "map/permissions/update"
+};
+var FEDERATION_METHODS = {
+  FEDERATION_CONNECT: "map/federation/connect",
+  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 MAP_METHODS = {
+  ...CORE_METHODS,
+  ...OBSERVATION_METHODS,
+  ...LIFECYCLE_METHODS,
+  ...STATE_METHODS,
+  ...STEERING_METHODS,
+  ...SCOPE_METHODS,
+  ...SESSION_METHODS,
+  ...AUTH_METHODS,
+  ...PERMISSION_METHODS,
+  ...FEDERATION_METHODS
+};
+var STRUCTURE_METHODS = {
+  ...LIFECYCLE_METHODS,
+  ...STATE_METHODS,
+  ...SCOPE_METHODS,
+  STRUCTURE_GRAPH: OBSERVATION_METHODS.STRUCTURE_GRAPH
+};
+var EXTENSION_METHODS = {
+  ...STEERING_METHODS,
+  ...FEDERATION_METHODS
+};
+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;
+var CAPABILITY_REQUIREMENTS = {
+  // Core
+  [CORE_METHODS.CONNECT]: [],
+  [CORE_METHODS.DISCONNECT]: [],
+  [CORE_METHODS.SEND]: ["messaging.canSend"],
+  [CORE_METHODS.SUBSCRIBE]: ["observation.canObserve"],
+  [CORE_METHODS.UNSUBSCRIBE]: ["observation.canObserve"],
+  // Observation
+  [OBSERVATION_METHODS.AGENTS_LIST]: ["observation.canQuery"],
+  [OBSERVATION_METHODS.AGENTS_GET]: ["observation.canQuery"],
+  [OBSERVATION_METHODS.SCOPES_LIST]: ["observation.canQuery"],
+  [OBSERVATION_METHODS.SCOPES_GET]: ["observation.canQuery"],
+  [OBSERVATION_METHODS.SCOPES_MEMBERS]: ["observation.canQuery"],
+  [OBSERVATION_METHODS.STRUCTURE_GRAPH]: ["observation.canQuery"],
+  // Lifecycle
+  [LIFECYCLE_METHODS.AGENTS_REGISTER]: ["lifecycle.canRegister"],
+  [LIFECYCLE_METHODS.AGENTS_UNREGISTER]: ["lifecycle.canUnregister"],
+  [LIFECYCLE_METHODS.AGENTS_SPAWN]: ["lifecycle.canSpawn"],
+  // State
+  [STATE_METHODS.AGENTS_UPDATE]: ["lifecycle.canRegister"],
+  [STATE_METHODS.AGENTS_SUSPEND]: ["lifecycle.canStop"],
+  [STATE_METHODS.AGENTS_RESUME]: ["lifecycle.canStop"],
+  [STATE_METHODS.AGENTS_STOP]: ["lifecycle.canStop"],
+  // Steering
+  [STEERING_METHODS.INJECT]: ["lifecycle.canSteer"],
+  // Scopes
+  [SCOPE_METHODS.SCOPES_CREATE]: ["scopes.canCreateScopes"],
+  [SCOPE_METHODS.SCOPES_DELETE]: ["scopes.canManageScopes"],
+  [SCOPE_METHODS.SCOPES_JOIN]: [],
+  [SCOPE_METHODS.SCOPES_LEAVE]: [],
+  // Session
+  [SESSION_METHODS.SESSION_LIST]: [],
+  [SESSION_METHODS.SESSION_LOAD]: [],
+  [SESSION_METHODS.SESSION_CLOSE]: [],
+  // Auth
+  [AUTH_METHODS.AUTH_REFRESH]: [],
+  // Permissions (system-only, no capability check - enforced by participant type)
+  [PERMISSION_METHODS.PERMISSIONS_UPDATE]: [],
+  // Federation
+  [FEDERATION_METHODS.FEDERATION_CONNECT]: ["federation.canFederate"],
+  [FEDERATION_METHODS.FEDERATION_ROUTE]: ["federation.canFederate"]
+};
+function isSuccessResponse(response) {
+  return "result" in response;
+}
+function isDirectAddress(address) {
+  return typeof address === "object" && "agent" in address && !("system" in address);
+}
+function isFederatedAddress(address) {
+  return typeof address === "object" && "system" in address && "agent" in address;
+}
+function isScopeAddress(address) {
+  return typeof address === "object" && "scope" in address;
+}
+function isBroadcastAddress(address) {
+  return typeof address === "object" && "broadcast" in address;
+}
+function isHierarchicalAddress(address) {
+  return typeof address === "object" && ("parent" in address || "children" in address || "ancestors" in address || "descendants" in address || "siblings" in address);
+}
+
+// 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/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/stream/index.ts
+function ndJsonStream(readable, writable) {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const messageReadable = new ReadableStream({
+    async start(controller) {
+      const reader = readable.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            if (buffer.trim()) {
+              try {
+                const message = JSON.parse(buffer.trim());
+                controller.enqueue(message);
+              } catch {
+                console.error("MAP: Failed to parse final message:", buffer);
+              }
+            }
+            controller.close();
+            break;
+          }
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed) {
+              try {
+                const message = JSON.parse(trimmed);
+                controller.enqueue(message);
+              } catch {
+                console.error("MAP: Failed to parse message:", trimmed);
+              }
+            }
+          }
+        }
+      } catch (error) {
+        controller.error(error);
+      } finally {
+        reader.releaseLock();
+      }
+    }
+  });
+  const messageWritable = new WritableStream({
+    async write(message) {
+      const writer = writable.getWriter();
+      try {
+        const json = JSON.stringify(message) + "\n";
+        await writer.write(encoder.encode(json));
+      } finally {
+        writer.releaseLock();
+      }
+    },
+    async close() {
+      await writable.close();
+    },
+    abort(reason) {
+      writable.abort(reason);
+    }
+  });
+  return {
+    readable: messageReadable,
+    writable: messageWritable
+  };
+}
+function websocketStream(ws) {
+  const messageQueue = [];
+  let messageResolver = null;
+  let closed = false;
+  let closeError = null;
+  ws.addEventListener("message", (event) => {
+    try {
+      const message = JSON.parse(event.data);
+      if (messageResolver) {
+        messageResolver({ value: message, done: false });
+        messageResolver = null;
+      } else {
+        messageQueue.push(message);
+      }
+    } catch {
+      console.error("MAP: Failed to parse WebSocket message:", event.data);
+    }
+  });
+  ws.addEventListener("close", () => {
+    closed = true;
+    if (messageResolver) {
+      messageResolver({ value: void 0, done: true });
+      messageResolver = null;
+    }
+  });
+  ws.addEventListener("error", () => {
+    closeError = new Error("WebSocket error");
+    closed = true;
+    if (messageResolver) {
+      messageResolver({ value: void 0, done: true });
+      messageResolver = null;
+    }
+  });
+  const readable = new ReadableStream({
+    async pull(controller) {
+      if (messageQueue.length > 0) {
+        controller.enqueue(messageQueue.shift());
+        return;
+      }
+      if (closed) {
+        if (closeError) {
+          controller.error(closeError);
+        } else {
+          controller.close();
+        }
+        return;
+      }
+      await new Promise((resolve) => {
+        messageResolver = resolve;
+      }).then((result) => {
+        if (result.done) {
+          controller.close();
+        } else {
+          controller.enqueue(result.value);
+        }
+      });
+    }
+  });
+  const writable = new WritableStream({
+    async write(message) {
+      if (ws.readyState === WebSocket.CONNECTING) {
+        await new Promise((resolve, reject) => {
+          const onOpen = () => {
+            ws.removeEventListener("error", onError);
+            resolve();
+          };
+          const onError = () => {
+            ws.removeEventListener("open", onOpen);
+            reject(new Error("WebSocket failed to connect"));
+          };
+          ws.addEventListener("open", onOpen, { once: true });
+          ws.addEventListener("error", onError, { once: true });
+        });
+      }
+      if (ws.readyState !== WebSocket.OPEN) {
+        throw new Error("WebSocket is not open");
+      }
+      ws.send(JSON.stringify(message));
+    },
+    close() {
+      ws.close();
+    },
+    abort() {
+      ws.close();
+    }
+  });
+  return { readable, writable };
+}
+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/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/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;
+  }
+};
+var ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var ENCODING_LEN = ENCODING.length;
+function ulidTimestamp(id) {
+  if (id.length !== 26) {
+    throw new Error(`Invalid ULID: expected 26 characters, got ${id.length}`);
+  }
+  let time = 0;
+  for (let i = 0; i < 10; i++) {
+    const char = id[i].toUpperCase();
+    const idx = ENCODING.indexOf(char);
+    if (idx === -1) {
+      throw new Error(`Invalid ULID character: ${char}`);
+    }
+    time = time * ENCODING_LEN + idx;
+  }
+  return time;
+}
+function compareUlid(a, b) {
+  return a.localeCompare(b);
+}
+function isValidUlid(id) {
+  if (typeof id !== "string" || id.length !== 26) {
+    return false;
+  }
+  for (let i = 0; i < 26; i++) {
+    if (ENCODING.indexOf(id[i].toUpperCase()) === -1) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// 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 retryable(fn, policy = DEFAULT_RETRY_POLICY) {
+  return (...args) => withRetry(() => fn(...args), policy);
+}
+function createRetryPolicy(options = {}) {
+  return { ...DEFAULT_RETRY_POLICY, ...options };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/utils/causal-buffer.ts
+var CausalEventBuffer = class {
+  #options;
+  /** Events seen (by eventId) - used to check if predecessors exist */
+  #seen = /* @__PURE__ */ new Set();
+  /** Events waiting for predecessors */
+  #pending = /* @__PURE__ */ new Map();
+  /** Map from eventId to events waiting for it */
+  #waitingFor = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.#options = {
+      maxWaitTime: options.maxWaitTime ?? 5e3,
+      maxBufferSize: options.maxBufferSize ?? 1e3,
+      onForcedRelease: options.onForcedRelease
+    };
+  }
+  /**
+   * Push an event into the buffer.
+   *
+   * @param event - The event to buffer
+   * @returns Events that are ready to be processed (in causal order)
+   */
+  push(event) {
+    const ready = [];
+    if (this.#seen.has(event.eventId)) {
+      return { ready, pending: this.#pending.size };
+    }
+    this.#seen.add(event.eventId);
+    if (!event.receivedAt) {
+      event = { ...event, receivedAt: Date.now() };
+    }
+    const missingPredecessors = this.#getMissingPredecessors(event);
+    if (missingPredecessors.length === 0) {
+      ready.push(event);
+      this.#releaseWaiting(event.eventId, ready);
+    } else {
+      this.#pending.set(event.eventId, event);
+      for (const predecessorId of missingPredecessors) {
+        if (!this.#waitingFor.has(predecessorId)) {
+          this.#waitingFor.set(predecessorId, /* @__PURE__ */ new Set());
+        }
+        this.#waitingFor.get(predecessorId).add(event.eventId);
+      }
+    }
+    this.#handleBufferOverflow(ready);
+    this.#handleTimeouts(ready);
+    return { ready, pending: this.#pending.size };
+  }
+  /**
+   * Get the number of events waiting for predecessors
+   */
+  get pendingCount() {
+    return this.#pending.size;
+  }
+  /**
+   * Get the number of unique events seen
+   */
+  get seenCount() {
+    return this.#seen.size;
+  }
+  /**
+   * Check if a specific event has been seen
+   */
+  hasSeen(eventId) {
+    return this.#seen.has(eventId);
+  }
+  /**
+   * Force release all pending events, regardless of missing predecessors.
+   * Useful for cleanup or when you know no more events are coming.
+   *
+   * @returns All pending events in the order they would be released
+   */
+  flush() {
+    const ready = [];
+    const pendingList = Array.from(this.#pending.values()).sort(
+      (a, b) => (a.receivedAt ?? 0) - (b.receivedAt ?? 0)
+    );
+    for (const event of pendingList) {
+      const missingPredecessors = this.#getMissingPredecessors(event);
+      if (missingPredecessors.length > 0) {
+        this.#options.onForcedRelease?.(event, missingPredecessors);
+      }
+      ready.push(event);
+    }
+    this.#pending.clear();
+    this.#waitingFor.clear();
+    return ready;
+  }
+  /**
+   * Clear all state (seen events, pending events)
+   */
+  clear() {
+    this.#seen.clear();
+    this.#pending.clear();
+    this.#waitingFor.clear();
+  }
+  /**
+   * Get missing predecessors for an event.
+   * A predecessor is considered "missing" if it hasn't been released yet
+   * (either not seen at all, or seen but still pending).
+   */
+  #getMissingPredecessors(event) {
+    if (!event.causedBy || event.causedBy.length === 0) {
+      return [];
+    }
+    return event.causedBy.filter((predecessorId) => {
+      return !this.#seen.has(predecessorId) || this.#pending.has(predecessorId);
+    });
+  }
+  /**
+   * Release events that were waiting for a specific predecessor
+   */
+  #releaseWaiting(predecessorId, ready) {
+    const waitingEventIds = this.#waitingFor.get(predecessorId);
+    if (!waitingEventIds) return;
+    this.#waitingFor.delete(predecessorId);
+    for (const waitingEventId of waitingEventIds) {
+      const waitingEvent = this.#pending.get(waitingEventId);
+      if (!waitingEvent) continue;
+      const stillMissing = this.#getMissingPredecessors(waitingEvent);
+      if (stillMissing.length === 0) {
+        this.#pending.delete(waitingEventId);
+        ready.push(waitingEvent);
+        this.#releaseWaiting(waitingEventId, ready);
+      }
+    }
+  }
+  /**
+   * Handle buffer overflow by force-releasing oldest events
+   */
+  #handleBufferOverflow(ready) {
+    while (this.#pending.size > this.#options.maxBufferSize) {
+      let oldest = null;
+      for (const event of this.#pending.values()) {
+        if (!oldest || (event.receivedAt ?? 0) < (oldest.receivedAt ?? 0)) {
+          oldest = event;
+        }
+      }
+      if (oldest) {
+        this.#forceRelease(oldest, ready);
+      }
+    }
+  }
+  /**
+   * Handle events that have been waiting too long
+   */
+  #handleTimeouts(ready) {
+    if (this.#options.maxWaitTime <= 0 || this.#options.maxWaitTime === Infinity) {
+      return;
+    }
+    const now = Date.now();
+    const toRelease = [];
+    for (const event of this.#pending.values()) {
+      const waitTime = now - (event.receivedAt ?? now);
+      if (waitTime >= this.#options.maxWaitTime) {
+        toRelease.push(event);
+      }
+    }
+    for (const event of toRelease) {
+      this.#forceRelease(event, ready);
+    }
+  }
+  /**
+   * Force release an event despite missing predecessors
+   */
+  #forceRelease(event, ready) {
+    const missingPredecessors = this.#getMissingPredecessors(event);
+    this.#pending.delete(event.eventId);
+    for (const predecessorId of event.causedBy ?? []) {
+      const waiting = this.#waitingFor.get(predecessorId);
+      if (waiting) {
+        waiting.delete(event.eventId);
+        if (waiting.size === 0) {
+          this.#waitingFor.delete(predecessorId);
+        }
+      }
+    }
+    if (missingPredecessors.length > 0) {
+      this.#options.onForcedRelease?.(event, missingPredecessors);
+    }
+    ready.push(event);
+    this.#releaseWaiting(event.eventId, ready);
+  }
+};
+function validateCausalOrder(events) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (event.causedBy) {
+      for (const predecessorId of event.causedBy) {
+        if (!seen.has(predecessorId)) {
+          return false;
+        }
+      }
+    }
+    seen.add(event.eventId);
+  }
+  return true;
+}
+function sortCausalOrder(events) {
+  const eventMap = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    eventMap.set(event.eventId, event);
+  }
+  const result = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  function visit(eventId) {
+    if (visited.has(eventId)) return;
+    if (visiting.has(eventId)) {
+      throw new Error(`Cycle detected involving event: ${eventId}`);
+    }
+    const event = eventMap.get(eventId);
+    if (!event) {
+      throw new Error(`Missing event: ${eventId}`);
+    }
+    visiting.add(eventId);
+    if (event.causedBy) {
+      for (const predecessorId of event.causedBy) {
+        if (!eventMap.has(predecessorId)) {
+          throw new Error(`Missing predecessor: ${predecessorId} for event: ${eventId}`);
+        }
+        visit(predecessorId);
+      }
+    }
+    visiting.delete(eventId);
+    visited.add(eventId);
+    result.push(event);
+  }
+  for (const event of events) {
+    visit(event.eventId);
+  }
+  return result;
+}
+
+// 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/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/federation/envelope.ts
+function createFederationEnvelope(payload, sourceSystem, targetSystem, options) {
+  return {
+    payload,
+    federation: {
+      sourceSystem,
+      targetSystem,
+      hopCount: 0,
+      maxHops: options?.maxHops,
+      path: options?.trackPath ? [sourceSystem] : void 0,
+      originTimestamp: Date.now(),
+      correlationId: options?.correlationId
+    }
+  };
+}
+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 isEnvelopeAtDestination(envelope, currentSystemId) {
+  return envelope.federation.targetSystem === currentSystemId;
+}
+function unwrapEnvelope(envelope) {
+  return envelope.payload;
+}
+function getEnvelopeRoutingInfo(envelope) {
+  const { federation } = envelope;
+  return {
+    source: federation.sourceSystem,
+    target: federation.targetSystem,
+    hops: federation.hopCount,
+    path: federation.path,
+    age: Date.now() - federation.originTimestamp,
+    correlationId: federation.correlationId
+  };
+}
+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";
+}
+function withPayload(envelope, newPayload) {
+  return {
+    payload: newPayload,
+    federation: envelope.federation
+  };
+}
+
+// src/federation/buffer.ts
+var DEFAULT_CONFIG = {
+  enabled: true,
+  maxMessages: 1e3,
+  maxBytes: 10 * 1024 * 1024,
+  // 10MB
+  retentionMs: 60 * 60 * 1e3,
+  // 1 hour
+  overflowStrategy: "drop-oldest"
+};
+var FederationOutageBuffer = class {
+  #config;
+  #buffers = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.#config = { ...DEFAULT_CONFIG, ...config };
+  }
+  /**
+   * Whether buffering is enabled.
+   */
+  get enabled() {
+    return this.#config.enabled;
+  }
+  /**
+   * Get the configuration.
+   */
+  get config() {
+    return this.#config;
+  }
+  /**
+   * Enqueue a message for a peer.
+   *
+   * @param peerId - Target peer system ID
+   * @param envelope - Message envelope to buffer
+   * @returns true if message was buffered, false if rejected
+   */
+  enqueue(peerId, envelope) {
+    if (!this.#config.enabled) return false;
+    let buffer = this.#buffers.get(peerId);
+    if (!buffer) {
+      buffer = { messages: [], totalEnqueued: 0, totalDropped: 0, totalBytes: 0 };
+      this.#buffers.set(peerId, buffer);
+    }
+    this.#evictExpired(buffer);
+    const messageSize = this.#estimateSize(envelope);
+    while (buffer.totalBytes + messageSize > this.#config.maxBytes && buffer.messages.length > 0) {
+      const removed = buffer.messages.shift();
+      buffer.totalBytes -= removed.size;
+      buffer.totalDropped++;
+    }
+    if (buffer.messages.length >= this.#config.maxMessages) {
+      switch (this.#config.overflowStrategy) {
+        case "drop-oldest": {
+          const removed = buffer.messages.shift();
+          buffer.totalBytes -= removed.size;
+          buffer.totalDropped++;
+          break;
+        }
+        case "drop-newest":
+          buffer.totalDropped++;
+          return false;
+        case "reject":
+          return false;
+      }
+    }
+    buffer.messages.push({
+      envelope,
+      enqueuedAt: Date.now(),
+      size: messageSize
+    });
+    buffer.totalEnqueued++;
+    buffer.totalBytes += messageSize;
+    return true;
+  }
+  /**
+   * Drain all buffered messages for a peer.
+   *
+   * Returns messages in FIFO order and clears the buffer.
+   *
+   * @param peerId - Target peer system ID
+   * @returns Array of buffered envelopes
+   */
+  drain(peerId) {
+    const buffer = this.#buffers.get(peerId);
+    if (!buffer) return [];
+    this.#evictExpired(buffer);
+    const messages = buffer.messages.map((m) => m.envelope);
+    buffer.messages = [];
+    buffer.totalBytes = 0;
+    return messages;
+  }
+  /**
+   * Peek at buffered messages without removing them.
+   *
+   * @param peerId - Target peer system ID
+   * @returns Array of buffered envelopes (still in buffer)
+   */
+  peek(peerId) {
+    const buffer = this.#buffers.get(peerId);
+    if (!buffer) return [];
+    this.#evictExpired(buffer);
+    return buffer.messages.map((m) => m.envelope);
+  }
+  /**
+   * Get statistics for all peer buffers.
+   *
+   * @returns Map of peer ID to buffer stats
+   */
+  stats() {
+    const result = /* @__PURE__ */ new Map();
+    const now = Date.now();
+    for (const [peerId, buffer] of this.#buffers) {
+      this.#evictExpired(buffer);
+      const oldestAge = buffer.messages.length > 0 ? now - buffer.messages[0].enqueuedAt : 0;
+      result.set(peerId, {
+        count: buffer.messages.length,
+        oldestAge,
+        totalEnqueued: buffer.totalEnqueued,
+        totalDropped: buffer.totalDropped,
+        totalBytes: buffer.totalBytes
+      });
+    }
+    return result;
+  }
+  /**
+   * Get count for a specific peer.
+   *
+   * @param peerId - Target peer system ID
+   * @returns Number of buffered messages
+   */
+  count(peerId) {
+    const buffer = this.#buffers.get(peerId);
+    if (!buffer) return 0;
+    this.#evictExpired(buffer);
+    return buffer.messages.length;
+  }
+  /**
+   * Check if buffer has messages for a peer.
+   *
+   * @param peerId - Target peer system ID
+   * @returns true if there are buffered messages
+   */
+  has(peerId) {
+    return this.count(peerId) > 0;
+  }
+  /**
+   * Clear buffer for a specific peer.
+   *
+   * @param peerId - Target peer system ID
+   */
+  clear(peerId) {
+    this.#buffers.delete(peerId);
+  }
+  /**
+   * Clear all buffers.
+   */
+  clearAll() {
+    this.#buffers.clear();
+  }
+  /**
+   * Get list of peers with buffered messages.
+   *
+   * @returns Array of peer IDs
+   */
+  peers() {
+    const result = [];
+    for (const [peerId, buffer] of this.#buffers) {
+      this.#evictExpired(buffer);
+      if (buffer.messages.length > 0) {
+        result.push(peerId);
+      }
+    }
+    return result;
+  }
+  /**
+   * Evict expired messages from a buffer.
+   */
+  #evictExpired(buffer) {
+    const cutoff = Date.now() - this.#config.retentionMs;
+    let removed = 0;
+    let bytesRemoved = 0;
+    while (buffer.messages.length > 0 && buffer.messages[0].enqueuedAt < cutoff) {
+      const msg = buffer.messages.shift();
+      bytesRemoved += msg.size;
+      removed++;
+    }
+    buffer.totalDropped += removed;
+    buffer.totalBytes -= bytesRemoved;
+  }
+  /**
+   * Estimate the size of an envelope in bytes.
+   */
+  #estimateSize(envelope) {
+    try {
+      return JSON.stringify(envelope).length * 2;
+    } catch {
+      return 1024;
+    }
+  }
+};
+
+// src/connection/gateway.ts
+var GatewayConnection = class {
+  #connection;
+  #options;
+  #connectedSystems = /* @__PURE__ */ new Map();
+  #reconnectionHandlers = /* @__PURE__ */ new Set();
+  #outageBuffer;
+  #lastSyncTimestamps = /* @__PURE__ */ new Map();
+  #sessionId = null;
+  #serverCapabilities = null;
+  #connected = false;
+  #isReconnecting = false;
+  #lastConnectOptions;
+  constructor(stream, options = {}) {
+    this.#connection = new BaseConnection(stream, options);
+    this.#options = options;
+    this.#outageBuffer = options.buffer?.enabled ? new FederationOutageBuffer(options.buffer) : null;
+    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 local MAP system
+   */
+  async connect(options) {
+    const params = {
+      protocolVersion: PROTOCOL_VERSION,
+      participantType: "gateway",
+      name: this.#options.name,
+      capabilities: this.#options.capabilities,
+      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 local MAP system
+   */
+  async disconnect(reason) {
+    if (!this.#connected) return;
+    try {
+      await this.#connection.sendRequest(
+        CORE_METHODS.DISCONNECT,
+        reason ? { reason } : void 0
+      );
+    } finally {
+      await this.#connection.close();
+      this.#connected = false;
+    }
+  }
+  /**
+   * Whether the gateway is connected to the local system
+   */
+  get isConnected() {
+    return this.#connected && !this.#connection.isClosed;
+  }
+  /**
+   * Current session ID
+   */
+  get sessionId() {
+    return this.#sessionId;
+  }
+  /**
+   * Server capabilities
+   */
+  get serverCapabilities() {
+    return this.#serverCapabilities;
+  }
+  /**
+   * List of connected remote systems
+   */
+  get connectedSystems() {
+    return new Map(this.#connectedSystems);
+  }
+  /**
+   * 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;
+  }
+  // ===========================================================================
+  // Federation
+  // ===========================================================================
+  /**
+   * Connect to a remote MAP system
+   */
+  async connectToSystem(systemId, endpoint, auth) {
+    const params = {
+      systemId,
+      endpoint,
+      auth
+    };
+    const result = await this.#connection.sendRequest(FEDERATION_METHODS.FEDERATION_CONNECT, params);
+    if (result.connected && result.systemInfo) {
+      this.#connectedSystems.set(systemId, {
+        name: result.systemInfo.name,
+        version: result.systemInfo.version
+      });
+    }
+    return result;
+  }
+  /**
+   * Route a message to a remote system.
+   *
+   * If routing config is provided, wraps the message in a federation envelope
+   * with proper metadata for multi-hop routing. Otherwise, sends raw message
+   * for backwards compatibility.
+   *
+   * During reconnection, messages are buffered if buffer is configured.
+   */
+  async routeToSystem(systemId, message) {
+    let envelope;
+    if (this.#options.routing) {
+      envelope = createFederationEnvelope(
+        message,
+        this.#options.routing.systemId,
+        systemId,
+        {
+          maxHops: this.#options.routing.maxHops,
+          trackPath: this.#options.routing.trackPath
+        }
+      );
+    }
+    if (this.#isReconnecting && this.#outageBuffer && envelope) {
+      const buffered = this.#outageBuffer.enqueue(systemId, envelope);
+      if (!buffered) {
+        this.#emitReconnectionEvent({
+          type: "bufferOverflow",
+          peerId: systemId,
+          messagesBuffered: this.#outageBuffer.count(systemId)
+        });
+      }
+      return { routed: false };
+    }
+    const params = { systemId };
+    if (envelope) {
+      params.envelope = envelope;
+    } else {
+      params.message = message;
+    }
+    const result = await this.#connection.sendRequest(FEDERATION_METHODS.FEDERATION_ROUTE, params);
+    if (result.routed) {
+      this.#lastSyncTimestamps.set(systemId, Date.now());
+    }
+    return result;
+  }
+  /**
+   * Check if a remote system is connected
+   */
+  isSystemConnected(systemId) {
+    return this.#connectedSystems.has(systemId);
+  }
+  // ===========================================================================
+  // Reconnection
+  // ===========================================================================
+  /**
+   * Current connection state
+   */
+  get state() {
+    return this.#connection.state;
+  }
+  /**
+   * Whether the connection is currently reconnecting
+   */
+  get isReconnecting() {
+    return this.#isReconnecting;
+  }
+  /**
+   * Get the outage buffer (for advanced use)
+   */
+  get outageBuffer() {
+    return this.#outageBuffer;
+  }
+  /**
+   * Get last sync timestamp for a peer
+   */
+  getLastSyncTimestamp(peerId) {
+    return this.#lastSyncTimestamps.get(peerId);
+  }
+  /**
+   * 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
+  // ===========================================================================
+  /**
+   * Emit a reconnection event to all registered handlers
+   */
+  #emitReconnectionEvent(event) {
+    for (const handler of this.#reconnectionHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        console.error("MAP: Gateway 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" });
+    await this.#drainBufferedMessages();
+    await this.#replayFromPeers();
+  }
+  /**
+   * Drain buffered messages after reconnection
+   */
+  async #drainBufferedMessages() {
+    if (!this.#outageBuffer) return;
+    const peers = this.#outageBuffer.peers();
+    for (const peerId of peers) {
+      const messages = this.#outageBuffer.drain(peerId);
+      if (messages.length === 0) continue;
+      for (const envelope of messages) {
+        try {
+          const params = {
+            systemId: peerId,
+            envelope
+          };
+          await this.#connection.sendRequest(FEDERATION_METHODS.FEDERATION_ROUTE, params);
+        } catch (error) {
+          console.warn("MAP: Failed to send buffered message to", peerId, error);
+        }
+      }
+      this.#emitReconnectionEvent({
+        type: "bufferDrained",
+        peerId,
+        messagesDrained: messages.length
+      });
+    }
+  }
+  /**
+   * Replay missed events from peers after reconnection
+   */
+  async #replayFromPeers() {
+    const replayOptions = this.#options.replay;
+    if (!replayOptions?.enabled) return;
+    const peersToReplay = Array.from(this.#lastSyncTimestamps.entries());
+    if (peersToReplay.length === 0) return;
+    for (const [peerId, lastSync] of peersToReplay) {
+      try {
+        await this.#replayFromPeer(peerId, lastSync);
+      } catch (error) {
+        console.warn("MAP: Failed to replay events from peer", peerId, error);
+      }
+    }
+  }
+  /**
+   * Replay missed events from a single peer
+   */
+  async #replayFromPeer(peerId, lastSyncTimestamp) {
+    const replayOptions = this.#options.replay;
+    const maxAge = replayOptions.maxAgeMs ?? 60 * 60 * 1e3;
+    const cutoff = Date.now() - maxAge;
+    if (lastSyncTimestamp < cutoff) {
+      return;
+    }
+    this.#emitReconnectionEvent({ type: "replayStarted", peerId });
+    let totalReplayed = 0;
+    const maxEvents = replayOptions.maxEvents ?? 1e3;
+    let afterEventId;
+    let hasMore = true;
+    while (hasMore && totalReplayed < maxEvents) {
+      const params = {
+        limit: Math.min(100, maxEvents - totalReplayed)
+      };
+      if (afterEventId) {
+        params.afterEventId = afterEventId;
+      } else {
+        params.fromTimestamp = lastSyncTimestamp;
+      }
+      if (replayOptions.eventTypes) {
+        params.filter = { eventTypes: replayOptions.eventTypes };
+      }
+      const result = await this.#connection.sendRequest(CORE_METHODS.REPLAY, params);
+      totalReplayed += result.events.length;
+      hasMore = result.hasMore;
+      afterEventId = result.events.at(-1)?.eventId;
+      if (result.events.length === 0) {
+        break;
+      }
+      const lastEvent = result.events.at(-1);
+      if (lastEvent) {
+        this.#lastSyncTimestamps.set(peerId, lastEvent.timestamp);
+      }
+    }
+    this.#emitReconnectionEvent({
+      type: "replayCompleted",
+      peerId,
+      eventsReplayed: totalReplayed
+    });
+  }
+};
+var JsonRpcVersionSchema = z.literal("2.0");
+var RequestIdSchema = z.union([z.string(), z.number().int()]);
+var ProtocolVersionSchema = z.literal(1);
+var TimestampSchema = z.number().int();
+var MetaSchema = z.record(z.unknown()).optional();
+var ParticipantIdSchema = z.string();
+var AgentIdSchema = z.string();
+var ScopeIdSchema = z.string();
+var SessionIdSchema = z.string();
+var MessageIdSchema = z.string();
+var SubscriptionIdSchema = z.string();
+var CorrelationIdSchema = z.string();
+var ParticipantTypeSchema = z.enum(["agent", "client", "system", "gateway"]);
+var TransportTypeSchema = z.enum(["websocket", "stdio", "inprocess", "http-sse"]);
+var ErrorCategorySchema = z.enum([
+  "protocol",
+  "auth",
+  "routing",
+  "agent",
+  "resource",
+  "federation",
+  "internal"
+]);
+var AgentVisibilitySchema = z.enum(["public", "parent-only", "scope", "system"]);
+var AgentStateSchema = z.union([
+  z.enum(["registered", "idle", "busy", "waiting", "stopping", "stopped", "error"]),
+  z.string().regex(/^x-/)
+]);
+var MessagePrioritySchema = z.enum(["low", "normal", "high", "urgent"]);
+var DeliverySemanticsSchema = z.enum(["at-most-once", "at-least-once", "exactly-once"]);
+var MessageRelationshipSchema = z.enum([
+  "peer",
+  "parent-to-child",
+  "child-to-parent",
+  "supervisor-to-supervised",
+  "broadcast"
+]);
+var EventTypeSchema = z.enum([
+  "agent.registered",
+  "agent.unregistered",
+  "agent.state-changed",
+  "agent.spawned",
+  "scope.created",
+  "scope.deleted",
+  "scope.joined",
+  "scope.left",
+  "message.sent",
+  "message.delivered",
+  "session.started",
+  "session.ended",
+  "system.error",
+  "system.shutdown"
+]);
+var ScopeJoinPolicySchema = z.enum(["open", "approval", "invite"]);
+var ScopeVisibilitySchema = z.enum(["public", "private", "unlisted"]);
+var MessageVisibilitySchema = z.enum(["members", "public"]);
+var ScopeSendPolicySchema = z.enum(["anyone", "members"]);
+var ParticipantCapabilitiesSchema = z.object({
+  observation: z.object({
+    canObserve: z.boolean().optional(),
+    canQuery: z.boolean().optional()
+  }).strict().optional(),
+  messaging: z.object({
+    canSend: z.boolean().optional(),
+    canReceive: z.boolean().optional(),
+    canBroadcast: z.boolean().optional()
+  }).strict().optional(),
+  lifecycle: z.object({
+    canSpawn: z.boolean().optional(),
+    canRegister: z.boolean().optional(),
+    canUnregister: z.boolean().optional(),
+    canSteer: z.boolean().optional(),
+    canStop: z.boolean().optional()
+  }).strict().optional(),
+  scopes: z.object({
+    canCreateScopes: z.boolean().optional(),
+    canManageScopes: z.boolean().optional()
+  }).strict().optional(),
+  _meta: MetaSchema
+}).strict();
+var DirectAddressSchema = z.object({ agent: AgentIdSchema }).strict();
+var MultiAddressSchema = z.object({ agents: z.array(AgentIdSchema).min(1) }).strict();
+var ScopeAddressSchema = z.object({ scope: ScopeIdSchema }).strict();
+var RoleAddressSchema = z.object({
+  role: z.string(),
+  scope: ScopeIdSchema.optional()
+}).strict();
+var HierarchicalAddressSchema = z.object({
+  parent: z.literal(true).optional(),
+  children: z.literal(true).optional(),
+  siblings: z.literal(true).optional(),
+  ancestors: z.literal(true).optional(),
+  descendants: z.literal(true).optional()
+}).strict();
+var BroadcastAddressSchema = z.object({ broadcast: z.literal(true) }).strict();
+var SystemAddressSchema = z.object({ system: z.literal(true) }).strict();
+var ParticipantAddressSchema = z.object({ participant: ParticipantIdSchema }).strict();
+var FederatedAddressSchema = z.object({
+  system: z.string(),
+  address: z.lazy(() => AddressSchema)
+}).strict();
+var AddressSchema = z.union([
+  DirectAddressSchema,
+  MultiAddressSchema,
+  ScopeAddressSchema,
+  RoleAddressSchema,
+  HierarchicalAddressSchema,
+  BroadcastAddressSchema,
+  SystemAddressSchema,
+  ParticipantAddressSchema,
+  FederatedAddressSchema
+]);
+var AgentRelationshipSchema = z.object({
+  type: z.enum(["peer", "supervisor", "supervised", "collaborator"]),
+  agentId: AgentIdSchema,
+  metadata: z.record(z.unknown()).optional(),
+  _meta: MetaSchema
+}).strict();
+var AgentLifecycleSchema = z.object({
+  createdAt: TimestampSchema.optional(),
+  startedAt: TimestampSchema.optional(),
+  stoppedAt: TimestampSchema.optional(),
+  lastActiveAt: TimestampSchema.optional(),
+  exitCode: z.number().int().optional(),
+  exitReason: z.string().optional(),
+  _meta: MetaSchema
+}).strict();
+var AgentSchema = z.object({
+  id: AgentIdSchema,
+  name: z.string().optional(),
+  description: z.string().optional(),
+  parent: AgentIdSchema.optional(),
+  relationships: z.array(AgentRelationshipSchema).optional(),
+  state: AgentStateSchema,
+  role: z.string().optional(),
+  scopes: z.array(ScopeIdSchema).optional(),
+  visibility: AgentVisibilitySchema.optional(),
+  lifecycle: AgentLifecycleSchema.optional(),
+  capabilities: ParticipantCapabilitiesSchema.optional(),
+  metadata: z.record(z.unknown()).optional(),
+  _meta: MetaSchema
+}).strict();
+var ScopeSchema = z.object({
+  id: ScopeIdSchema,
+  name: z.string().optional(),
+  parent: ScopeIdSchema.optional(),
+  children: z.array(ScopeIdSchema).optional(),
+  joinPolicy: ScopeJoinPolicySchema.optional(),
+  visibility: ScopeVisibilitySchema.optional(),
+  messageVisibility: MessageVisibilitySchema.optional(),
+  sendPolicy: ScopeSendPolicySchema.optional(),
+  metadata: z.record(z.unknown()).optional(),
+  _meta: MetaSchema
+}).strict();
+var MessageMetaSchema = z.object({
+  correlationId: CorrelationIdSchema.optional(),
+  causationId: MessageIdSchema.optional(),
+  traceId: z.string().optional(),
+  spanId: z.string().optional(),
+  priority: MessagePrioritySchema.optional(),
+  delivery: DeliverySemanticsSchema.optional(),
+  relationship: MessageRelationshipSchema.optional(),
+  expiresAt: TimestampSchema.optional(),
+  isResult: z.boolean().optional(),
+  _meta: MetaSchema
+}).strict();
+var MessageSchema = z.object({
+  id: MessageIdSchema,
+  from: ParticipantIdSchema,
+  to: AddressSchema,
+  timestamp: TimestampSchema,
+  payload: z.unknown().optional(),
+  meta: MessageMetaSchema.optional(),
+  _meta: MetaSchema
+}).strict();
+var EventSchema = z.object({
+  type: EventTypeSchema,
+  timestamp: TimestampSchema,
+  data: z.record(z.unknown()).optional(),
+  _meta: MetaSchema
+}).strict();
+var SubscriptionFilterSchema = z.object({
+  eventTypes: z.array(EventTypeSchema).optional(),
+  scopes: z.array(ScopeIdSchema).optional(),
+  agents: z.array(AgentIdSchema).optional(),
+  includeChildren: z.boolean().optional(),
+  _meta: MetaSchema
+}).strict();
+var MAPErrorDataSchema = z.object({
+  category: ErrorCategorySchema.optional(),
+  retryable: z.boolean().optional(),
+  retryAfterMs: z.number().int().optional(),
+  details: z.record(z.unknown()).optional(),
+  _meta: MetaSchema
+}).passthrough();
+var MAPErrorSchema = z.object({
+  code: z.number().int(),
+  message: z.string(),
+  data: MAPErrorDataSchema.optional()
+}).strict();
+var MAPRequestSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: RequestIdSchema,
+  method: z.string(),
+  params: z.record(z.unknown()).optional()
+}).strict();
+var MAPResponseSuccessSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: RequestIdSchema,
+  result: z.unknown()
+}).strict();
+var MAPResponseErrorSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  id: RequestIdSchema,
+  error: MAPErrorSchema
+}).strict();
+var MAPResponseSchema = z.union([MAPResponseSuccessSchema, MAPResponseErrorSchema]);
+var MAPNotificationSchema = z.object({
+  jsonrpc: JsonRpcVersionSchema,
+  method: z.string(),
+  params: z.record(z.unknown()).optional()
+}).strict();
+
+// src/protocol/index.ts
+var METHOD_REGISTRY = {
+  // Core methods
+  "connect": {
+    method: "map/connect",
+    category: "core",
+    capabilities: [],
+    description: "Establish connection to MAP system"
+  },
+  "disconnect": {
+    method: "map/disconnect",
+    category: "core",
+    capabilities: [],
+    description: "Disconnect from MAP system"
+  },
+  "send": {
+    method: "map/send",
+    category: "core",
+    capabilities: ["messaging.canSend"],
+    description: "Send a message to an address"
+  },
+  "subscribe": {
+    method: "map/subscribe",
+    category: "core",
+    capabilities: ["observation.canObserve"],
+    description: "Subscribe to event stream"
+  },
+  "unsubscribe": {
+    method: "map/unsubscribe",
+    category: "core",
+    capabilities: ["observation.canObserve"],
+    description: "Unsubscribe from event stream"
+  },
+  "replay": {
+    method: "map/replay",
+    category: "core",
+    capabilities: ["observation.canObserve"],
+    description: "Replay historical events with filtering and pagination"
+  },
+  // Observation methods
+  "agents/list": {
+    method: "map/agents/list",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "List agents with optional filters"
+  },
+  "agents/get": {
+    method: "map/agents/get",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "Get agent by ID with optional hierarchy"
+  },
+  "scopes/list": {
+    method: "map/scopes/list",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "List all scopes"
+  },
+  "scopes/get": {
+    method: "map/scopes/get",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "Get scope by ID"
+  },
+  "scopes/members": {
+    method: "map/scopes/members",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "List scope members"
+  },
+  "structure/graph": {
+    method: "map/structure/graph",
+    category: "observation",
+    capabilities: ["observation.canQuery"],
+    description: "Get agent hierarchy graph"
+  },
+  // Lifecycle methods
+  "agents/register": {
+    method: "map/agents/register",
+    category: "lifecycle",
+    capabilities: ["lifecycle.canRegister"],
+    description: "Register a new agent"
+  },
+  "agents/unregister": {
+    method: "map/agents/unregister",
+    category: "lifecycle",
+    capabilities: ["lifecycle.canUnregister"],
+    description: "Unregister an agent"
+  },
+  "agents/spawn": {
+    method: "map/agents/spawn",
+    category: "lifecycle",
+    capabilities: ["lifecycle.canSpawn"],
+    description: "Spawn a child agent"
+  },
+  // State methods
+  "agents/update": {
+    method: "map/agents/update",
+    category: "state",
+    capabilities: ["lifecycle.canRegister"],
+    description: "Update agent state or metadata"
+  },
+  "agents/suspend": {
+    method: "map/agents/suspend",
+    category: "state",
+    capabilities: ["lifecycle.canStop"],
+    description: "Suspend an agent"
+  },
+  "agents/resume": {
+    method: "map/agents/resume",
+    category: "state",
+    capabilities: ["lifecycle.canStop"],
+    description: "Resume a suspended agent"
+  },
+  "agents/stop": {
+    method: "map/agents/stop",
+    category: "state",
+    capabilities: ["lifecycle.canStop"],
+    description: "Stop an agent"
+  },
+  // Steering methods
+  "inject": {
+    method: "map/inject",
+    category: "steering",
+    capabilities: ["lifecycle.canSteer"],
+    description: "Inject context into an agent"
+  },
+  // Scope methods
+  "scopes/create": {
+    method: "map/scopes/create",
+    category: "scope",
+    capabilities: ["scopes.canCreateScopes"],
+    description: "Create a new scope"
+  },
+  "scopes/delete": {
+    method: "map/scopes/delete",
+    category: "scope",
+    capabilities: ["scopes.canManageScopes"],
+    description: "Delete a scope"
+  },
+  "scopes/join": {
+    method: "map/scopes/join",
+    category: "scope",
+    capabilities: [],
+    description: "Join a scope"
+  },
+  "scopes/leave": {
+    method: "map/scopes/leave",
+    category: "scope",
+    capabilities: [],
+    description: "Leave a scope"
+  },
+  // Session methods
+  "session/list": {
+    method: "map/session/list",
+    category: "session",
+    capabilities: [],
+    description: "List sessions"
+  },
+  "session/load": {
+    method: "map/session/load",
+    category: "session",
+    capabilities: [],
+    description: "Load a session"
+  },
+  "session/close": {
+    method: "map/session/close",
+    category: "session",
+    capabilities: [],
+    description: "Close a session"
+  },
+  // Auth methods
+  "auth/refresh": {
+    method: "map/auth/refresh",
+    category: "auth",
+    capabilities: [],
+    description: "Refresh authentication token"
+  },
+  // Federation methods
+  "federation/connect": {
+    method: "map/federation/connect",
+    category: "federation",
+    capabilities: ["federation.canFederate"],
+    description: "Connect to federated system"
+  },
+  "federation/route": {
+    method: "map/federation/route",
+    category: "federation",
+    capabilities: ["federation.canFederate"],
+    description: "Route message to federated system"
+  },
+  // Notification methods (client → server)
+  "subscription/ack": {
+    method: "map/subscribe.ack",
+    category: "notification",
+    capabilities: [],
+    description: "Acknowledge received events for backpressure flow control"
+  }
+};
+function getMethodsByCategory(category) {
+  return Object.values(METHOD_REGISTRY).filter((m) => m.category === category);
+}
+function getRequiredCapabilities(methodName) {
+  const info = METHOD_REGISTRY[methodName];
+  if (info) return info.capabilities;
+  const byWire = Object.values(METHOD_REGISTRY).find((m) => m.method === methodName);
+  return byWire?.capabilities ?? [];
+}
+function hasRequiredCapabilities(methodName, capabilities) {
+  const required = getRequiredCapabilities(methodName);
+  if (required.length === 0) return true;
+  for (const path of required) {
+    const [category, capability] = path.split(".");
+    const categoryCapabilities = capabilities[category];
+    if (!categoryCapabilities?.[capability]) {
+      return false;
+    }
+  }
+  return true;
+}
+function getMethodInfo(wireMethod) {
+  return Object.values(METHOD_REGISTRY).find((m) => m.method === wireMethod);
+}
+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 buildDisconnectResponse(session) {
+  return { session };
+}
+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 buildAgentsSpawnResponse(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 hasCapability(capabilities, path) {
+  const [category, cap] = path.split(".");
+  const categoryCapabilities = capabilities[category];
+  return categoryCapabilities?.[cap] ?? false;
+}
+function canPerformMethod(method, capabilities) {
+  return hasRequiredCapabilities(method, capabilities);
+}
+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 canSendToScope(scope, participant, memberAgentIds = []) {
+  if (participant.type === "system") return true;
+  const sendPolicy = scope.sendPolicy ?? "members";
+  switch (sendPolicy) {
+    case "any":
+      return true;
+    case "members":
+      return memberAgentIds.length > 0;
+    default:
+      return false;
+  }
+}
+function canJoinScope(scope, participantType, agentRole) {
+  const joinPolicy = scope.joinPolicy ?? "open";
+  switch (joinPolicy) {
+    case "open":
+      return true;
+    case "invite":
+      return false;
+    case "role":
+      if (!agentRole || !scope.autoJoinRoles) return false;
+      return scope.autoJoinRoles.includes(agentRole);
+    case "system":
+      return participantType === "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 canMessageAgent(agent, participant, ownedAgentIds = []) {
+  if (!canSeeAgent(agent, participant, ownedAgentIds)) {
+    return false;
+  }
+  return true;
+}
+function canControlAgent(agent, participant, ownedAgentIds = []) {
+  if (participant.type === "system") return true;
+  if (ownedAgentIds.includes(agent.id)) return true;
+  if (agent.parent && ownedAgentIds.includes(agent.parent)) return true;
+  return false;
+}
+function canPerformAction(context, action) {
+  if (action.target?.agentId) {
+    if (!isAgentExposed(context.system.exposure, action.target.agentId)) {
+      return {
+        allowed: false,
+        reason: "Agent not exposed by system configuration",
+        layer: 1
+      };
+    }
+  }
+  if (action.target?.scopeId) {
+    if (!isScopeExposed(context.system.exposure, action.target.scopeId)) {
+      return {
+        allowed: false,
+        reason: "Scope not exposed by system configuration",
+        layer: 1
+      };
+    }
+  }
+  if (action.target?.eventTypes) {
+    for (const eventType of action.target.eventTypes) {
+      if (!isEventTypeExposed(context.system.exposure, eventType)) {
+        return {
+          allowed: false,
+          reason: `Event type '${eventType}' not exposed by system configuration`,
+          layer: 1
+        };
+      }
+    }
+  }
+  const requiredCaps = getRequiredCapabilities(action.method);
+  for (const cap of requiredCaps) {
+    if (!hasCapability(context.participant.capabilities, cap)) {
+      return {
+        allowed: false,
+        reason: `Missing required capability: ${cap}`,
+        layer: 2
+      };
+    }
+  }
+  return { allowed: true };
+}
+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 filterVisibleEvents(events, context) {
+  return events.filter((event) => {
+    if (!isEventTypeExposed(context.system.exposure, event.type)) {
+      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);
+}
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+function deepMergePermissions(base, override) {
+  const result = { ...base };
+  if (override.canSee) {
+    result.canSee = { ...base.canSee, ...override.canSee };
+  }
+  if (override.canMessage) {
+    result.canMessage = { ...base.canMessage, ...override.canMessage };
+  }
+  if (override.acceptsFrom) {
+    result.acceptsFrom = { ...base.acceptsFrom, ...override.acceptsFrom };
+  }
+  return result;
+}
+function mapVisibilityToRule(visibility) {
+  switch (visibility) {
+    case "public":
+      return "all";
+    case "parent-only":
+      return "hierarchy";
+    case "scope":
+      return "scoped";
+    case "system":
+      return "direct";
+    default:
+      return "all";
+  }
+}
+var DEFAULT_AGENT_PERMISSION_CONFIG = {
+  defaultPermissions: {
+    canSee: {
+      agents: "all",
+      scopes: "all",
+      structure: "full"
+    },
+    canMessage: {
+      agents: "all",
+      scopes: "all"
+    },
+    acceptsFrom: {
+      agents: "all",
+      clients: "all",
+      systems: "all"
+    }
+  },
+  rolePermissions: {}
+};
+function resolveAgentPermissions(agent, config = DEFAULT_AGENT_PERMISSION_CONFIG) {
+  let permissions = deepClone(config.defaultPermissions);
+  if (agent.role && config.rolePermissions[agent.role]) {
+    permissions = deepMergePermissions(permissions, config.rolePermissions[agent.role]);
+  }
+  if (agent.permissionOverrides) {
+    permissions = deepMergePermissions(permissions, agent.permissionOverrides);
+  }
+  if (agent.visibility && !agent.permissionOverrides?.canSee?.agents) {
+    permissions.canSee = permissions.canSee ?? {};
+    permissions.canSee.agents = mapVisibilityToRule(agent.visibility);
+  }
+  return permissions;
+}
+function checkAgentAcceptance(rule, context) {
+  if (!rule || rule === "all") return true;
+  if (rule === "hierarchy") {
+    return context.isParent === true || context.isChild === true || context.isAncestor === true || context.isDescendant === true;
+  }
+  if (rule === "scoped") {
+    return (context.sharedScopes?.length ?? 0) > 0;
+  }
+  if (typeof rule === "object" && "include" in rule) {
+    return context.senderAgentId !== void 0 && rule.include.includes(context.senderAgentId);
+  }
+  return false;
+}
+function checkClientAcceptance(rule, senderId) {
+  if (!rule || rule === "all") return true;
+  if (rule === "none") return false;
+  if (typeof rule === "object" && "include" in rule) {
+    return rule.include.includes(senderId);
+  }
+  return false;
+}
+function checkSystemAcceptance(rule, senderSystemId) {
+  if (!rule || rule === "all") return true;
+  if (rule === "none") return false;
+  if (typeof rule === "object" && "include" in rule) {
+    return senderSystemId !== void 0 && rule.include.includes(senderSystemId);
+  }
+  return false;
+}
+function canAgentAcceptMessage(targetAgent, context, config = DEFAULT_AGENT_PERMISSION_CONFIG) {
+  const permissions = resolveAgentPermissions(targetAgent, config);
+  const acceptsFrom = permissions.acceptsFrom;
+  if (!acceptsFrom) return true;
+  switch (context.senderType) {
+    case "agent":
+      return checkAgentAcceptance(acceptsFrom.agents, context);
+    case "client":
+      return checkClientAcceptance(acceptsFrom.clients, context.senderId);
+    case "system":
+    case "gateway":
+      return checkSystemAcceptance(acceptsFrom.systems, context.senderSystemId);
+    default:
+      return false;
+  }
+}
+function canAgentSeeAgent(viewerAgent, targetAgentId, context, config = DEFAULT_AGENT_PERMISSION_CONFIG) {
+  const permissions = resolveAgentPermissions(viewerAgent, config);
+  const canSee = permissions.canSee?.agents;
+  if (!canSee || canSee === "all") return true;
+  if (canSee === "hierarchy") {
+    return context.isParent === true || context.isChild === true || context.isAncestor === true || context.isDescendant === true;
+  }
+  if (canSee === "scoped") {
+    return (context.sharedScopes?.length ?? 0) > 0;
+  }
+  if (canSee === "direct") {
+    return false;
+  }
+  if (typeof canSee === "object" && "include" in canSee) {
+    return canSee.include.includes(targetAgentId);
+  }
+  return false;
+}
+function canAgentMessageAgent(senderAgent, targetAgentId, context, config = DEFAULT_AGENT_PERMISSION_CONFIG) {
+  const permissions = resolveAgentPermissions(senderAgent, config);
+  const canMessage = permissions.canMessage?.agents;
+  if (!canMessage || canMessage === "all") return true;
+  if (canMessage === "hierarchy") {
+    return context.isParent === true || context.isChild === true || context.isAncestor === true || context.isDescendant === true;
+  }
+  if (canMessage === "scoped") {
+    return (context.sharedScopes?.length ?? 0) > 0;
+  }
+  if (typeof canMessage === "object" && "include" in canMessage) {
+    return canMessage.include.includes(targetAgentId);
+  }
+  return false;
+}
+
+export { AGENT_ERROR_CODES, AUTH_ERROR_CODES, AUTH_METHODS, AddressSchema, AgentConnection, AgentIdSchema, AgentLifecycleSchema, AgentRelationshipSchema, AgentSchema, AgentStateSchema, AgentVisibilitySchema, BaseConnection, BroadcastAddressSchema, CAPABILITY_REQUIREMENTS, CORE_METHODS, CausalEventBuffer, ClientConnection, CorrelationIdSchema, DEFAULT_AGENT_PERMISSION_CONFIG, DEFAULT_RETRY_POLICY, DeliverySemanticsSchema, DirectAddressSchema, ERROR_CODES, EVENT_TYPES, EXTENSION_METHODS, ErrorCategorySchema, EventSchema, EventTypeSchema, FEDERATION_ERROR_CODES, FEDERATION_METHODS, FederatedAddressSchema, FederationOutageBuffer, GatewayConnection, HierarchicalAddressSchema, JSONRPC_VERSION, JsonRpcVersionSchema, LIFECYCLE_METHODS, MAPConnectionError, MAPErrorDataSchema, MAPErrorSchema, MAPNotificationSchema, MAPRequestError, MAPRequestSchema, MAPResponseErrorSchema, MAPResponseSchema, MAPResponseSuccessSchema, MAPTimeoutError, MAP_METHODS, METHOD_REGISTRY, MessageIdSchema, MessageMetaSchema, MessagePrioritySchema, MessageRelationshipSchema, MessageSchema, MessageVisibilitySchema, MetaSchema, MultiAddressSchema, NOTIFICATION_METHODS, OBSERVATION_METHODS, PERMISSION_METHODS, PROTOCOL_ERROR_CODES, PROTOCOL_VERSION, ParticipantAddressSchema, ParticipantCapabilitiesSchema, ParticipantIdSchema, ParticipantTypeSchema, ProtocolVersionSchema, RESOURCE_ERROR_CODES, ROUTING_ERROR_CODES, RequestIdSchema, RoleAddressSchema, SCOPE_METHODS, SESSION_METHODS, STATE_METHODS, STEERING_METHODS, STRUCTURE_METHODS, ScopeAddressSchema, ScopeIdSchema, ScopeJoinPolicySchema, ScopeSchema, ScopeSendPolicySchema, ScopeVisibilitySchema, SessionIdSchema, Subscription, SubscriptionFilterSchema, SubscriptionIdSchema, SystemAddressSchema, TimestampSchema, TransportTypeSchema, buildAgentsGetResponse, buildAgentsListResponse, buildAgentsRegisterResponse, buildAgentsSpawnResponse, buildAgentsUnregisterResponse, buildAgentsUpdateResponse, buildConnectResponse, buildDisconnectResponse, buildScopesCreateResponse, buildScopesJoinResponse, buildScopesLeaveResponse, buildScopesListResponse, buildSendResponse, buildSubscribeResponse, buildUnsubscribeResponse, calculateDelay, canAgentAcceptMessage, canAgentMessageAgent, canAgentSeeAgent, canControlAgent, canJoinScope, canMessageAgent, canPerformAction, canPerformMethod, canSeeAgent, canSeeScope, canSendToScope, compareUlid, createErrorResponse, createEvent, createFederationEnvelope, createNotification, createRequest, createRetryPolicy, createStreamPair, createSubscription, createSuccessResponse, deepMergePermissions, filterVisibleAgents, filterVisibleEvents, filterVisibleScopes, getEnvelopeRoutingInfo, getMethodInfo, getMethodsByCategory, getRequiredCapabilities, hasCapability, hasRequiredCapabilities, isAgentExposed, isBroadcastAddress, isDirectAddress, isEnvelopeAtDestination, isErrorResponse, isEventTypeExposed, isFederatedAddress, isHierarchicalAddress, isNotification, isOrphanedAgent, isRequest, isResponse, isScopeAddress, isScopeExposed, isSuccessResponse, isValidEnvelope, isValidUlid, mapVisibilityToRule, ndJsonStream, processFederationEnvelope, resolveAgentPermissions, retryable, sleep, sortCausalOrder, ulidTimestamp, unwrapEnvelope, validateCausalOrder, websocketStream, withPayload, withRetry };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map