@multi-agent-protocol/sdk 0.0.4 → 0.0.6

package/dist/index.cjs

@@ -1,8 +1,89 @@
 'use strict';
 
+var agenticMesh = require('agentic-mesh');
 var ulid = require('ulid');
+var events = require('events');
 var zod = require('zod');
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/stream/agentic-mesh.ts
+var agentic_mesh_exports = {};
+__export(agentic_mesh_exports, {
+  agenticMeshStream: () => agenticMeshStream
+});
+async function agenticMeshStream(config) {
+  if (!config.transport.active) {
+    await config.transport.start();
+  }
+  const connected = await config.transport.connect(config.peer);
+  if (!connected) {
+    throw new Error(`Failed to connect to peer: ${config.peer.peerId}`);
+  }
+  const streamId = `map-${config.localPeerId}-${Date.now()}`;
+  const tunnelStream = new agenticMesh.TunnelStream({
+    transport: config.transport,
+    peerId: config.peer.peerId,
+    streamId
+  });
+  await tunnelStream.open();
+  return tunnelStreamToMapStream(tunnelStream);
+}
+function tunnelStreamToMapStream(tunnel) {
+  let readingAborted = false;
+  const readable = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const frame of tunnel) {
+          if (readingAborted) break;
+          controller.enqueue(frame);
+        }
+        if (!readingAborted) {
+          controller.close();
+        }
+      } catch (error) {
+        if (!readingAborted) {
+          controller.error(error);
+        }
+      }
+    },
+    cancel() {
+      readingAborted = true;
+      tunnel.close().catch(() => {
+      });
+    }
+  });
+  const writable = new WritableStream({
+    async write(message) {
+      if (!tunnel.isOpen) {
+        throw new Error("Stream is not open");
+      }
+      await tunnel.write(message);
+    },
+    async close() {
+      await tunnel.close();
+    },
+    abort() {
+      readingAborted = true;
+      tunnel.close().catch(() => {
+      });
+    }
+  });
+  return { readable, writable };
+}
+var init_agentic_mesh = __esm({
+  "src/stream/agentic-mesh.ts"() {
+  }
+});
+
 // src/types/index.ts
 function isOrphanedAgent(agent) {
   return agent.ownerId === null;
@@ -88,6 +169,7 @@ var SESSION_METHODS = {
   SESSION_CLOSE: "map/session/close"
 };
 var AUTH_METHODS = {
+  AUTHENTICATE: "map/authenticate",
   AUTH_REFRESH: "map/auth/refresh"
 };
 var PERMISSION_METHODS = {
@@ -101,7 +183,9 @@ var NOTIFICATION_METHODS = {
   EVENT: "map/event",
   MESSAGE: "map/message",
   /** Client acknowledges received events (for backpressure) */
-  SUBSCRIBE_ACK: "map/subscribe.ack"
+  SUBSCRIBE_ACK: "map/subscribe.ack",
+  /** Server notifies client that auth is about to expire */
+  AUTH_EXPIRING: "map/auth/expiring"
 };
 var MAP_METHODS = {
   ...CORE_METHODS,
@@ -136,7 +220,10 @@ var AUTH_ERROR_CODES = {
   AUTH_REQUIRED: 1e3,
   AUTH_FAILED: 1001,
   TOKEN_EXPIRED: 1002,
-  PERMISSION_DENIED: 1003
+  PERMISSION_DENIED: 1003,
+  INSUFFICIENT_SCOPE: 1004,
+  METHOD_NOT_SUPPORTED: 1005,
+  INVALID_CREDENTIALS: 1006
 };
 var ROUTING_ERROR_CODES = {
   ADDRESS_NOT_FOUND: 2e3,
@@ -210,7 +297,8 @@ var CAPABILITY_REQUIREMENTS = {
   [SESSION_METHODS.SESSION_LIST]: [],
   [SESSION_METHODS.SESSION_LOAD]: [],
   [SESSION_METHODS.SESSION_CLOSE]: [],
-  // Auth
+  // Auth (no capability required - anyone can authenticate)
+  [AUTH_METHODS.AUTHENTICATE]: [],
   [AUTH_METHODS.AUTH_REFRESH]: [],
   // Permissions (system-only, no capability check - enforced by participant type)
   [PERMISSION_METHODS.PERMISSIONS_UPDATE]: [],
@@ -381,6 +469,27 @@ var MAPRequestError = class _MAPRequestError extends Error {
       { category: "auth" }
     );
   }
+  static insufficientScope(required) {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.INSUFFICIENT_SCOPE,
+      required ? `Insufficient scope: ${required}` : "Insufficient scope",
+      { category: "auth" }
+    );
+  }
+  static methodNotSupported(method) {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.METHOD_NOT_SUPPORTED,
+      `Authentication method not supported: ${method}`,
+      { category: "auth" }
+    );
+  }
+  static invalidCredentials(details) {
+    return new _MAPRequestError(
+      AUTH_ERROR_CODES.INVALID_CREDENTIALS,
+      details ?? "Invalid credentials",
+      { category: "auth" }
+    );
+  }
   // ==========================================================================
   // Routing Errors (2xxx)
   // ==========================================================================
@@ -562,6 +671,7 @@ var MAPTimeoutError = class extends Error {
 };
 
 // src/stream/index.ts
+init_agentic_mesh();
 function ndJsonStream(readable, writable) {
   const encoder = new TextEncoder();
   const decoder = new TextDecoder();
@@ -1801,948 +1911,1071 @@ function sortCausalOrder(events) {
   return result;
 }
 
-// src/connection/client.ts
-var ClientConnection = class _ClientConnection {
-  #connection;
-  #subscriptions = /* @__PURE__ */ new Map();
-  #subscriptionStates = /* @__PURE__ */ new Map();
-  #reconnectionHandlers = /* @__PURE__ */ new Set();
+// src/acp/types.ts
+var ACP_ERROR_CODES = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  REQUEST_CANCELLED: -32800,
+  AUTH_REQUIRED: -32e3,
+  SESSION_NOT_FOUND: -32002
+};
+var ACPError = class _ACPError extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "ACPError";
+    this.code = code;
+    this.data = data;
+  }
+  /**
+   * Create an ACPError from an error response.
+   */
+  static fromResponse(error) {
+    return new _ACPError(error.code, error.message, error.data);
+  }
+  /**
+   * Convert to JSON-RPC error object.
+   */
+  toErrorObject() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.data !== void 0 && { data: this.data }
+    };
+  }
+};
+var ACP_PROTOCOL_VERSION = 20241007;
+var ACP_METHODS = {
+  // Lifecycle
+  INITIALIZE: "initialize",
+  AUTHENTICATE: "authenticate",
+  // Session management
+  SESSION_NEW: "session/new",
+  SESSION_LOAD: "session/load",
+  SESSION_SET_MODE: "session/set_mode",
+  // Prompt
+  SESSION_PROMPT: "session/prompt",
+  SESSION_CANCEL: "session/cancel",
+  // Notifications
+  SESSION_UPDATE: "session/update",
+  // Agent→Client requests
+  REQUEST_PERMISSION: "request_permission",
+  FS_READ_TEXT_FILE: "fs/read_text_file",
+  FS_WRITE_TEXT_FILE: "fs/write_text_file",
+  TERMINAL_CREATE: "terminal/create",
+  TERMINAL_OUTPUT: "terminal/output",
+  TERMINAL_RELEASE: "terminal/release",
+  TERMINAL_WAIT_FOR_EXIT: "terminal/wait_for_exit",
+  TERMINAL_KILL: "terminal/kill"
+};
+function isACPRequest(msg) {
+  if (typeof msg !== "object" || msg === null) {
+    return false;
+  }
+  return "method" in msg && "id" in msg && msg.id !== void 0;
+}
+function isACPNotification(msg) {
+  if (typeof msg !== "object" || msg === null) {
+    return false;
+  }
+  return "method" in msg && !("id" in msg);
+}
+function isACPResponse(msg) {
+  if (typeof msg !== "object" || msg === null) {
+    return false;
+  }
+  return "id" in msg && !("method" in msg);
+}
+function isACPErrorResponse(response) {
+  if (typeof response !== "object" || response === null) {
+    return false;
+  }
+  return "error" in response;
+}
+function isACPSuccessResponse(response) {
+  if (typeof response !== "object" || response === null) {
+    return false;
+  }
+  return "result" in response;
+}
+function isACPEnvelope(payload) {
+  if (typeof payload !== "object" || payload === null) {
+    return false;
+  }
+  const envelope = payload;
+  if (typeof envelope.acp !== "object" || envelope.acp === null || typeof envelope.acpContext !== "object" || envelope.acpContext === null) {
+    return false;
+  }
+  const acpContext = envelope.acpContext;
+  return typeof acpContext.streamId === "string";
+}
+
+// src/acp/stream.ts
+var ACPStreamConnection = class extends events.EventEmitter {
+  #mapClient;
   #options;
+  #streamId;
+  #pendingRequests = /* @__PURE__ */ new Map();
+  #subscription = null;
   #sessionId = null;
-  #serverCapabilities = null;
-  #connected = false;
-  #lastConnectOptions;
+  #initialized = false;
+  #capabilities = null;
+  #closed = false;
+  #lastEventId = null;
   #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();
-        }
-      });
-    }
-  }
-  // ===========================================================================
-  // Static Factory Methods
-  // ===========================================================================
+  #unsubscribeReconnection = null;
   /**
-   * Connect to a MAP server via WebSocket URL.
-   *
-   * Handles:
-   * - WebSocket creation and connection
-   * - Stream wrapping
-   * - Auto-configuration of createStream for reconnection
-   * - Initial MAP protocol connect handshake
-   *
-   * @param url - WebSocket URL (ws:// or wss://)
-   * @param options - Connection options
-   * @returns Connected ClientConnection instance
-   *
-   * @example
-   * ```typescript
-   * const client = await ClientConnection.connect('ws://localhost:8080', {
-   *   name: 'MyClient',
-   *   reconnection: true
-   * });
+   * Create a new ACP stream connection.
    *
-   * // Already connected, ready to use
-   * const agents = await client.listAgents();
-   * ```
+   * @param mapClient - The underlying MAP client connection
+   * @param options - Stream configuration options
    */
-  static async connect(url, options) {
-    const parsedUrl = new URL(url);
-    if (!["ws:", "wss:"].includes(parsedUrl.protocol)) {
-      throw new Error(
-        `Unsupported protocol: ${parsedUrl.protocol}. Use ws: or wss:`
-      );
-    }
-    const timeout = options?.connectTimeout ?? 1e4;
-    const ws = new WebSocket(url);
-    await waitForOpen(ws, timeout);
-    const stream = websocketStream(ws);
-    const createStream = async () => {
-      const newWs = new WebSocket(url);
-      await waitForOpen(newWs, timeout);
-      return websocketStream(newWs);
-    };
-    const reconnection = options?.reconnection === true ? { enabled: true } : typeof options?.reconnection === "object" ? options.reconnection : void 0;
-    const client = new _ClientConnection(stream, {
-      name: options?.name,
-      capabilities: options?.capabilities,
-      createStream,
-      reconnection
+  constructor(mapClient, options) {
+    super();
+    this.#mapClient = mapClient;
+    this.#options = options;
+    this.#streamId = `acp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    this.#unsubscribeReconnection = mapClient.onReconnection((event) => {
+      void this.#handleReconnectionEvent(event);
     });
-    await client.connect({ auth: options?.auth });
-    return client;
   }
   // ===========================================================================
-  // Connection Lifecycle
+  // Public Properties
+  // ===========================================================================
+  /** Unique identifier for this ACP stream */
+  get streamId() {
+    return this.#streamId;
+  }
+  /** Target agent this stream connects to */
+  get targetAgent() {
+    return this.#options.targetAgent;
+  }
+  /** Current ACP session ID (null until newSession called) */
+  get sessionId() {
+    return this.#sessionId;
+  }
+  /** Whether initialize() has been called */
+  get initialized() {
+    return this.#initialized;
+  }
+  /** Agent capabilities from initialize response */
+  get capabilities() {
+    return this.#capabilities;
+  }
+  /** Whether the stream is closed */
+  get isClosed() {
+    return this.#closed;
+  }
+  /** Last processed event ID (for reconnection support) */
+  get lastEventId() {
+    return this.#lastEventId;
+  }
+  /** Whether the stream is currently reconnecting */
+  get isReconnecting() {
+    return this.#isReconnecting;
+  }
+  // ===========================================================================
+  // Reconnection Handling
   // ===========================================================================
   /**
-   * Connect to the MAP system
+   * Handle MAP reconnection events.
    */
-  async connect(options) {
-    const params = {
-      protocolVersion: PROTOCOL_VERSION,
-      participantType: "client",
-      name: this.#options.name,
-      capabilities: this.#options.capabilities,
-      sessionId: options?.sessionId,
-      resumeToken: options?.resumeToken,
-      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;
+  async #handleReconnectionEvent(event) {
+    if (this.#closed) return;
+    switch (event.type) {
+      case "disconnected":
+        this.#isReconnecting = true;
+        this.emit("reconnecting");
+        for (const [id, pending] of this.#pendingRequests) {
+          clearTimeout(pending.timeout);
+          pending.reject(new Error("Connection lost during ACP request"));
+          this.#pendingRequests.delete(id);
+        }
+        break;
+      case "reconnected":
+        await this.#handleReconnected();
+        break;
+      case "reconnectFailed":
+        this.#isReconnecting = false;
+        this.emit("error", event.error ?? new Error("MAP reconnection failed"));
+        break;
+    }
   }
   /**
-   * Disconnect from the MAP system
-   * @param reason - Optional reason for disconnecting
-   * @returns Resume token that can be used to resume this session later
+   * Handle successful MAP reconnection.
    */
-  async disconnect(reason) {
-    if (!this.#connected) return void 0;
-    let resumeToken;
+  async #handleReconnected() {
+    this.#subscription = null;
     try {
-      const result = await this.#connection.sendRequest(
-        CORE_METHODS.DISCONNECT,
-        reason ? { reason } : void 0
-      );
-      resumeToken = result.resumeToken;
-    } finally {
-      for (const subscription of this.#subscriptions.values()) {
-        subscription._close();
+      await this.#setupSubscription();
+      if (this.#sessionId) {
+        const sessionValid = await this.#verifySessionValid();
+        if (!sessionValid) {
+          const lostSessionId = this.#sessionId;
+          this.#sessionId = null;
+          this.emit("sessionLost", {
+            sessionId: lostSessionId,
+            reason: "Session no longer valid after reconnection"
+          });
+        }
       }
-      this.#subscriptions.clear();
-      await this.#connection.close();
-      this.#connected = false;
+      this.#isReconnecting = false;
+      this.emit("reconnected");
+    } catch (error) {
+      this.#isReconnecting = false;
+      this.emit("error", error instanceof Error ? error : new Error(String(error)));
     }
-    return resumeToken;
-  }
-  /**
-   * Whether the client is connected
-   */
-  get isConnected() {
-    return this.#connected && !this.#connection.isClosed;
   }
   /**
-   * Current session ID
+   * Verify that the current ACP session is still valid.
+   *
+   * Since ACP doesn't have a dedicated status check method, we attempt
+   * a lightweight operation (cancel with no effect) to verify the session.
    */
-  get sessionId() {
-    return this.#sessionId;
+  async #verifySessionValid() {
+    if (!this.#sessionId) return false;
+    try {
+      await this.#sendNotification(ACP_METHODS.SESSION_CANCEL, {
+        sessionId: this.#sessionId,
+        reason: "session_verification"
+      });
+      return true;
+    } catch {
+      return false;
+    }
   }
+  // ===========================================================================
+  // Internal Methods
+  // ===========================================================================
   /**
-   * Server capabilities
+   * Set up the subscription for receiving messages from the target agent.
    */
-  get serverCapabilities() {
-    return this.#serverCapabilities;
+  async #setupSubscription() {
+    if (this.#subscription) return;
+    this.#subscription = await this.#mapClient.subscribe({
+      fromAgents: [this.#options.targetAgent]
+    });
+    void this.#processEvents();
   }
   /**
-   * AbortSignal that triggers when the connection closes
+   * Process incoming events from the subscription.
    */
-  get signal() {
-    return this.#connection.signal;
-  }
+  async #processEvents() {
+    if (!this.#subscription) return;
+    try {
+      for await (const event of this.#subscription) {
+        if (this.#closed) break;
+        if (event.id) {
+          this.#lastEventId = event.id;
+        }
+        if (event.type === "message_delivered" && event.data) {
+          const message = event.data.message;
+          if (message?.payload) {
+            await this.#handleIncomingMessage(message);
+          }
+        }
+      }
+    } catch (error) {
+      if (!this.#closed) {
+        this.emit("error", error);
+      }
+    }
+  }
   /**
-   * Promise that resolves when the connection closes
-   */
-  get closed() {
-    return this.#connection.closed;
+   * Handle an incoming message from the target agent.
+   */
+  async #handleIncomingMessage(message) {
+    const payload = message.payload;
+    if (!isACPEnvelope(payload)) return;
+    const envelope = payload;
+    const { acp, acpContext } = envelope;
+    if (acpContext.streamId !== this.#streamId) return;
+    if (acp.id !== void 0 && !acp.method) {
+      const requestId = String(acp.id);
+      const pending = this.#pendingRequests.get(requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.#pendingRequests.delete(requestId);
+        if (acp.error) {
+          pending.reject(ACPError.fromResponse(acp.error));
+        } else {
+          pending.resolve(acp.result);
+        }
+      }
+      return;
+    }
+    if (acp.method && acp.id === void 0) {
+      await this.#handleNotification(acp.method, acp.params, acpContext);
+      return;
+    }
+    if (acp.method && acp.id !== void 0) {
+      await this.#handleAgentRequest(acp.id, acp.method, acp.params, acpContext, message);
+    }
   }
-  // ===========================================================================
-  // Session Management
-  // ===========================================================================
   /**
-   * List available sessions
+   * Handle an ACP notification from the agent.
    */
-  async listSessions() {
-    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LIST);
+  async #handleNotification(method, params, _acpContext) {
+    if (method === ACP_METHODS.SESSION_UPDATE) {
+      await this.#options.client.sessionUpdate(params);
+    }
   }
   /**
-   * Load an existing session
+   * Handle an agent→client request.
    */
-  async loadSession(sessionId) {
-    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LOAD, { sessionId });
+  async #handleAgentRequest(requestId, method, params, _ctx, originalMessage) {
+    let result;
+    let error;
+    try {
+      switch (method) {
+        case ACP_METHODS.REQUEST_PERMISSION:
+          result = await this.#options.client.requestPermission(
+            params
+          );
+          break;
+        case ACP_METHODS.FS_READ_TEXT_FILE:
+          if (!this.#options.client.readTextFile) {
+            throw new ACPError(-32601, "Method not supported: fs/read_text_file");
+          }
+          result = await this.#options.client.readTextFile(
+            params
+          );
+          break;
+        case ACP_METHODS.FS_WRITE_TEXT_FILE:
+          if (!this.#options.client.writeTextFile) {
+            throw new ACPError(-32601, "Method not supported: fs/write_text_file");
+          }
+          result = await this.#options.client.writeTextFile(
+            params
+          );
+          break;
+        case ACP_METHODS.TERMINAL_CREATE:
+          if (!this.#options.client.createTerminal) {
+            throw new ACPError(-32601, "Method not supported: terminal/create");
+          }
+          result = await this.#options.client.createTerminal(
+            params
+          );
+          break;
+        case ACP_METHODS.TERMINAL_OUTPUT:
+          if (!this.#options.client.terminalOutput) {
+            throw new ACPError(-32601, "Method not supported: terminal/output");
+          }
+          result = await this.#options.client.terminalOutput(
+            params
+          );
+          break;
+        case ACP_METHODS.TERMINAL_RELEASE:
+          if (!this.#options.client.releaseTerminal) {
+            throw new ACPError(-32601, "Method not supported: terminal/release");
+          }
+          result = await this.#options.client.releaseTerminal(
+            params
+          );
+          break;
+        case ACP_METHODS.TERMINAL_WAIT_FOR_EXIT:
+          if (!this.#options.client.waitForTerminalExit) {
+            throw new ACPError(-32601, "Method not supported: terminal/wait_for_exit");
+          }
+          result = await this.#options.client.waitForTerminalExit(
+            params
+          );
+          break;
+        case ACP_METHODS.TERMINAL_KILL:
+          if (!this.#options.client.killTerminal) {
+            throw new ACPError(-32601, "Method not supported: terminal/kill");
+          }
+          result = await this.#options.client.killTerminal(
+            params
+          );
+          break;
+        default:
+          throw new ACPError(-32601, `Unknown method: ${method}`);
+      }
+    } catch (e) {
+      if (e instanceof ACPError) {
+        error = e;
+      } else {
+        error = new ACPError(-32603, e.message);
+      }
+    }
+    const responseEnvelope = {
+      acp: {
+        jsonrpc: "2.0",
+        id: requestId,
+        ...error ? { error: error.toErrorObject() } : { result }
+      },
+      acpContext: {
+        streamId: this.#streamId,
+        sessionId: this.#sessionId,
+        direction: "client-to-agent"
+      }
+    };
+    await this.#mapClient.send(
+      { agent: this.#options.targetAgent },
+      responseEnvelope,
+      {
+        protocol: "acp",
+        correlationId: originalMessage.id
+      }
+    );
   }
   /**
-   * Close the current session
+   * Send an ACP request and wait for response.
    */
-  async closeSession(sessionId) {
-    return this.#connection.sendRequest(SESSION_METHODS.SESSION_CLOSE, { sessionId });
+  async #sendRequest(method, params) {
+    if (this.#closed) {
+      throw new Error("ACP stream is closed");
+    }
+    await this.#setupSubscription();
+    if (this.#closed) {
+      throw new Error("ACP stream closed");
+    }
+    const correlationId = `${this.#streamId}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const timeout = this.#options.timeout ?? 3e4;
+    const envelope = {
+      acp: {
+        jsonrpc: "2.0",
+        id: correlationId,
+        method,
+        ...params !== void 0 && { params }
+      },
+      acpContext: {
+        streamId: this.#streamId,
+        sessionId: this.#sessionId,
+        direction: "client-to-agent"
+      }
+    };
+    const resultPromise = new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.#pendingRequests.delete(correlationId);
+        reject(new Error(`ACP request timed out after ${timeout}ms: ${method}`));
+      }, timeout);
+      this.#pendingRequests.set(correlationId, {
+        resolve,
+        reject,
+        timeout: timeoutHandle,
+        method
+      });
+    });
+    try {
+      await this.#mapClient.send({ agent: this.#options.targetAgent }, envelope, {
+        protocol: "acp",
+        correlationId
+      });
+    } catch (err) {
+      const pending = this.#pendingRequests.get(correlationId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.#pendingRequests.delete(correlationId);
+      }
+      throw err;
+    }
+    if (this.#closed && !this.#pendingRequests.has(correlationId)) {
+      throw new Error("ACP stream closed");
+    }
+    return resultPromise;
   }
-  // ===========================================================================
-  // Agent Queries
-  // ===========================================================================
   /**
-   * List agents with optional filters
+   * Send an ACP notification (no response expected).
    */
-  async listAgents(options) {
-    return this.#connection.sendRequest(OBSERVATION_METHODS.AGENTS_LIST, options);
+  async #sendNotification(method, params) {
+    if (this.#closed) {
+      throw new Error("ACP stream is closed");
+    }
+    await this.#setupSubscription();
+    const envelope = {
+      acp: {
+        jsonrpc: "2.0",
+        method,
+        ...params !== void 0 && { params }
+      },
+      acpContext: {
+        streamId: this.#streamId,
+        sessionId: this.#sessionId,
+        direction: "client-to-agent"
+      }
+    };
+    await this.#mapClient.send({ agent: this.#options.targetAgent }, envelope, {
+      protocol: "acp"
+    });
   }
+  // ===========================================================================
+  // ACP Lifecycle Methods
+  // ===========================================================================
   /**
-   * Get a single agent by ID
+   * Initialize the ACP connection with the target agent.
    */
-  async getAgent(agentId, options) {
-    const params = { agentId, ...options };
-    return this.#connection.sendRequest(
-      OBSERVATION_METHODS.AGENTS_GET,
+  async initialize(params) {
+    if (this.#initialized) {
+      throw new Error("ACP stream already initialized");
+    }
+    const result = await this.#sendRequest(
+      ACP_METHODS.INITIALIZE,
       params
     );
+    this.#initialized = true;
+    this.#capabilities = result.agentCapabilities ?? null;
+    return result;
   }
   /**
-   * Get the agent structure/hierarchy graph
+   * Authenticate with the agent.
    */
-  async getStructureGraph(options) {
-    return this.#connection.sendRequest(OBSERVATION_METHODS.STRUCTURE_GRAPH, options);
+  async authenticate(params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before authenticate()");
+    }
+    return this.#sendRequest(
+      ACP_METHODS.AUTHENTICATE,
+      params
+    );
   }
   // ===========================================================================
-  // Scope Queries
+  // ACP Session Methods
   // ===========================================================================
   /**
-   * List scopes
+   * Create a new ACP session.
    */
-  async listScopes(options) {
-    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_LIST, options);
+  async newSession(params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before newSession()");
+    }
+    const result = await this.#sendRequest(
+      ACP_METHODS.SESSION_NEW,
+      params
+    );
+    this.#sessionId = result.sessionId;
+    return result;
   }
   /**
-   * Get a single scope by ID
+   * Load an existing ACP session.
    */
-  async getScope(scopeId) {
-    const result = await this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_GET, { scopeId });
-    return result.scope;
+  async loadSession(params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before loadSession()");
+    }
+    const result = await this.#sendRequest(
+      ACP_METHODS.SESSION_LOAD,
+      params
+    );
+    this.#sessionId = params.sessionId;
+    return result;
   }
   /**
-   * List members of a scope
+   * Set the session mode.
    */
-  async getScopeMembers(scopeId, options) {
-    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_MEMBERS, {
-      scopeId,
-      ...options
-    });
+  async setSessionMode(params) {
+    return this.#sendRequest(
+      ACP_METHODS.SESSION_SET_MODE,
+      params
+    );
   }
   // ===========================================================================
-  // Messaging
+  // ACP Prompt Methods
   // ===========================================================================
   /**
-   * 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
+   * Send a prompt to the agent.
+   * Updates are received via the sessionUpdate handler.
    */
-  async sendToRole(role, payload, meta, withinScope) {
-    return this.send({ role, within: withinScope }, payload, meta);
+  async prompt(params) {
+    if (!this.#sessionId) {
+      throw new Error("Must call newSession() or loadSession() before prompt()");
+    }
+    return this.#sendRequest(
+      ACP_METHODS.SESSION_PROMPT,
+      params
+    );
   }
   /**
-   * Broadcast a message to all agents
+   * Cancel ongoing operations for the current session.
    */
-  async broadcast(payload, meta) {
-    return this.send({ broadcast: true }, payload, meta);
+  async cancel(params) {
+    if (!this.#sessionId) {
+      throw new Error("No active session to cancel");
+    }
+    await this.#sendNotification(ACP_METHODS.SESSION_CANCEL, {
+      sessionId: this.#sessionId,
+      ...params
+    });
   }
+  // ===========================================================================
+  // Extension Methods
+  // ===========================================================================
   /**
-   * Send a request and wait for a correlated response
+   * Call an ACP extension method on the target agent.
    *
-   * This is a higher-level pattern for request/response messaging.
-   * A correlationId is automatically generated.
+   * Extension methods are prefixed with "_" (e.g., "_macro/spawnAgent").
+   * The agent must support the extension for this to succeed.
+   *
+   * @param method - The extension method name (e.g., "_macro/spawnAgent")
+   * @param params - Parameters to pass to the extension method
+   * @returns The result from the extension method
+   *
+   * @example
+   * ```typescript
+   * const result = await acp.callExtension("_macro/spawnAgent", {
+   *   task: "Implement feature X",
+   *   cwd: "/project"
+   * });
+   * ```
    */
-  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();
+  async callExtension(method, params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before callExtension()");
     }
+    return this.#sendRequest(method, params);
   }
   // ===========================================================================
-  // Subscriptions
+  // Lifecycle
   // ===========================================================================
   /**
-   * Subscribe to events
+   * Close this ACP stream and clean up resources.
    */
-  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);
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#unsubscribeReconnection) {
+      this.#unsubscribeReconnection();
+      this.#unsubscribeReconnection = null;
     }
-    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);
-      };
+    for (const [id, pending] of this.#pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("ACP stream closed"));
+      this.#pendingRequests.delete(id);
     }
-    return subscription;
-  }
-  /**
-   * Unsubscribe from events
-   */
-  async unsubscribe(subscriptionId) {
-    const subscription = this.#subscriptions.get(subscriptionId);
-    if (subscription) {
-      subscription._close();
-      this.#subscriptions.delete(subscriptionId);
+    if (this.#subscription) {
+      await this.#subscription.unsubscribe();
+      this.#subscription = null;
     }
-    this.#subscriptionStates.delete(subscriptionId);
-    await this.#connection.sendRequest(CORE_METHODS.UNSUBSCRIBE, { subscriptionId });
+    this.emit("close");
   }
-  // ===========================================================================
-  // Event Replay
-  // ===========================================================================
-  /**
-   * Replay historical events.
-   *
-   * Uses keyset pagination - pass the last eventId from the previous
-   * response to get the next page.
-   *
-   * @example
+};
+function createACPStream(mapClient, options) {
+  return new ACPStreamConnection(mapClient, options);
+}
+
+// src/connection/client.ts
+var ClientConnection = class _ClientConnection {
+  #connection;
+  #subscriptions = /* @__PURE__ */ new Map();
+  #subscriptionStates = /* @__PURE__ */ new Map();
+  #reconnectionHandlers = /* @__PURE__ */ new Set();
+  #acpStreams = /* @__PURE__ */ new Map();
+  #options;
+  #sessionId = null;
+  #serverCapabilities = null;
+  #connected = false;
+  #lastConnectOptions;
+  #isReconnecting = false;
+  #lastResumeToken;
+  #onTokenExpiring;
+  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();
+        }
+      });
+    }
+  }
+  // ===========================================================================
+  // Static Factory Methods
+  // ===========================================================================
+  /**
+   * Connect to a MAP server via WebSocket URL.
+   *
+   * Handles:
+   * - WebSocket creation and connection
+   * - Stream wrapping
+   * - Auto-configuration of createStream for reconnection
+   * - Initial MAP protocol connect handshake
+   *
+   * @param url - WebSocket URL (ws:// or wss://)
+   * @param options - Connection options
+   * @returns Connected ClientConnection instance
+   *
+   * @example
    * ```typescript
-   * // Replay all events from the last hour
-   * const result = await client.replay({
-   *   fromTimestamp: Date.now() - 3600000,
-   *   filter: { eventTypes: ['agent.registered'] },
-   *   limit: 100
+   * const client = await ClientConnection.connect('ws://localhost:8080', {
+   *   name: 'MyClient',
+   *   reconnection: true
    * });
    *
-   * // 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);
+   * // Already connected, ready to use
+   * const agents = await client.listAgents();
    * ```
    */
-  async replay(params = {}) {
-    const limit = Math.min(params.limit ?? 100, 1e3);
-    return this.#connection.sendRequest(
-      CORE_METHODS.REPLAY,
-      { ...params, limit }
-    );
+  static async connect(url, options) {
+    const parsedUrl = new URL(url);
+    if (!["ws:", "wss:"].includes(parsedUrl.protocol)) {
+      throw new Error(
+        `Unsupported protocol: ${parsedUrl.protocol}. Use ws: or wss:`
+      );
+    }
+    const timeout = options?.connectTimeout ?? 1e4;
+    const ws = new WebSocket(url);
+    await waitForOpen(ws, timeout);
+    const stream = websocketStream(ws);
+    const createStream = async () => {
+      const newWs = new WebSocket(url);
+      await waitForOpen(newWs, timeout);
+      return websocketStream(newWs);
+    };
+    const reconnection = options?.reconnection === true ? { enabled: true } : typeof options?.reconnection === "object" ? options.reconnection : void 0;
+    const client = new _ClientConnection(stream, {
+      name: options?.name,
+      capabilities: options?.capabilities,
+      createStream,
+      reconnection
+    });
+    await client.connect({ auth: options?.auth });
+    return client;
   }
   /**
-   * Replay all events matching filter, handling pagination automatically.
+   * Connect to a MAP server via agentic-mesh transport.
    *
-   * Returns an async generator for streaming through all results.
+   * Handles:
+   * - Dynamic import of agentic-mesh (optional peer dependency)
+   * - Stream creation over encrypted mesh tunnel
+   * - Auto-configuration of createStream for reconnection
+   * - Initial MAP protocol connect handshake
+   *
+   * Requires `agentic-mesh` to be installed as a peer dependency.
+   *
+   * @param options - Mesh connection options
+   * @returns Connected ClientConnection instance
    *
    * @example
    * ```typescript
-   * for await (const item of client.replayAll({
-   *   filter: { eventTypes: ['agent.registered'] }
-   * })) {
-   *   console.log(item.eventId, item.event);
-   * }
+   * import { createNebulaTransport } from 'agentic-mesh';
+   *
+   * const transport = createNebulaTransport({
+   *   configPath: '/etc/nebula/config.yml',
+   * });
+   *
+   * const client = await ClientConnection.connectMesh({
+   *   transport,
+   *   peer: { peerId: 'server', address: '10.0.0.1', port: 4242 },
+   *   localPeerId: 'my-client',
+   *   name: 'MeshClient',
+   *   reconnection: true
+   * });
+   *
+   * const agents = await client.listAgents();
    * ```
    */
-  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;
-      }
-    }
+  static async connectMesh(options) {
+    const { agenticMeshStream: agenticMeshStream2 } = await Promise.resolve().then(() => (init_agentic_mesh(), agentic_mesh_exports));
+    const streamConfig = {
+      transport: options.transport,
+      peer: options.peer,
+      localPeerId: options.localPeerId,
+      timeout: options.timeout
+    };
+    const stream = await agenticMeshStream2(streamConfig);
+    const createStream = async () => agenticMeshStream2(streamConfig);
+    const reconnection = options.reconnection === true ? { enabled: true } : typeof options.reconnection === "object" ? options.reconnection : void 0;
+    const client = new _ClientConnection(stream, {
+      name: options.name,
+      capabilities: options.capabilities,
+      createStream,
+      reconnection
+    });
+    await client.connect({ auth: options.auth });
+    return client;
   }
   // ===========================================================================
-  // Steering (requires canSteer capability)
+  // Connection Lifecycle
   // ===========================================================================
   /**
-   * Inject context into a running agent
+   * Connect to the MAP system
+   *
+   * @param options - Connection options
+   * @param options.sessionId - Specific session ID to use
+   * @param options.resumeToken - Token to resume a previously disconnected session
+   * @param options.auth - Authentication credentials
+   * @param options.onTokenExpiring - Callback invoked before token expires for proactive refresh
    */
-  async inject(agentId, content, delivery) {
-    const params = { agentId, content };
-    if (delivery) params.delivery = delivery;
-    return this.#connection.sendRequest(STEERING_METHODS.INJECT, params);
+  async connect(options) {
+    const params = {
+      protocolVersion: PROTOCOL_VERSION,
+      participantType: "client",
+      name: this.#options.name,
+      capabilities: this.#options.capabilities,
+      sessionId: options?.sessionId,
+      resumeToken: options?.resumeToken,
+      auth: options?.auth
+    };
+    const result = await this.#connection.sendRequest(CORE_METHODS.CONNECT, params);
+    this.#sessionId = result.sessionId;
+    this.#serverCapabilities = result.capabilities;
+    this.#connected = true;
+    if (result.resumeToken) {
+      this.#lastResumeToken = result.resumeToken;
+    }
+    if (options?.onTokenExpiring) {
+      this.#onTokenExpiring = options.onTokenExpiring;
+      this.#setupTokenExpiryMonitoring(result);
+    }
+    this.#connection._transitionTo("connected");
+    this.#lastConnectOptions = options;
+    return result;
   }
-  // ===========================================================================
-  // Lifecycle Control (requires canStop capability)
-  // ===========================================================================
   /**
-   * Request an agent to stop
+   * Get the resume token for this session.
+   * Can be used to reconnect and restore session state after disconnection.
+   *
+   * @returns The resume token, or undefined if not available
    */
-  async stopAgent(agentId, options) {
-    return this.#connection.sendRequest(STATE_METHODS.AGENTS_STOP, {
-      agentId,
-      ...options
-    });
+  getResumeToken() {
+    return this.#lastResumeToken;
   }
   /**
-   * Suspend an agent
+   * Reconnect to the server, optionally using a resume token to restore session.
+   *
+   * @param resumeToken - Token to resume previous session. If not provided, uses the last known token.
+   * @returns Connect response result
+   *
+   * @example
+   * ```typescript
+   * // Save token before disconnect
+   * const token = await client.disconnect();
+   *
+   * // Later, reconnect with the token
+   * const result = await client.reconnect(token);
+   * console.log('Reconnected:', result.reconnected);
+   * ```
    */
-  async suspendAgent(agentId, reason) {
-    return this.#connection.sendRequest(STATE_METHODS.AGENTS_SUSPEND, {
-      agentId,
-      reason
+  async reconnect(resumeToken) {
+    const tokenToUse = resumeToken ?? this.#lastResumeToken;
+    return this.connect({
+      ...this.#lastConnectOptions,
+      resumeToken: tokenToUse
     });
   }
   /**
-   * 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
+   * Set up monitoring for token expiration
    */
-  get isReconnecting() {
-    return this.#isReconnecting;
+  #setupTokenExpiryMonitoring(connectResult) {
+    const principal = connectResult.principal;
+    if (!principal?.expiresAt || !this.#onTokenExpiring) {
+      return;
+    }
+    const expiresAt = principal.expiresAt;
+    const now = Date.now();
+    const warningTime = expiresAt - 6e4;
+    const delay = warningTime - now;
+    if (delay > 0) {
+      setTimeout(async () => {
+        if (!this.#connected || !this.#onTokenExpiring) return;
+        try {
+          const newCredentials = await this.#onTokenExpiring(expiresAt);
+          if (newCredentials) {
+            const refreshResult = await this.refreshAuth({
+              method: newCredentials.method,
+              credential: newCredentials.credential
+            });
+            if (refreshResult.success && refreshResult.principal?.expiresAt) {
+              this.#setupTokenExpiryMonitoring({
+                ...connectResult,
+                principal: refreshResult.principal
+              });
+            }
+          }
+        } catch {
+        }
+      }, delay);
+    }
   }
   /**
-   * Register a handler for reconnection events.
+   * Authenticate with the server after connection.
    *
-   * @param handler - Function called when reconnection events occur
-   * @returns Unsubscribe function to remove the handler
+   * Use this when the server returns `authRequired` in the connect response,
+   * indicating that authentication is needed before accessing protected resources.
+   *
+   * @param auth - Authentication credentials
+   * @returns Authentication result with principal if successful
    *
    * @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;
+   * const connectResult = await client.connect();
+   *
+   * if (connectResult.authRequired) {
+   *   const authResult = await client.authenticate({
+   *     method: 'api-key',
+   *     credential: process.env.API_KEY,
+   *   });
+   *
+   *   if (authResult.success) {
+   *     console.log('Authenticated as:', authResult.principal?.id);
    *   }
-   * });
+   * }
    * ```
    */
-  onReconnection(handler) {
-    this.#reconnectionHandlers.add(handler);
-    return () => this.#reconnectionHandlers.delete(handler);
+  async authenticate(auth) {
+    const params = {
+      method: auth.method,
+      credential: auth.credential
+    };
+    const result = await this.#connection.sendRequest(AUTH_METHODS.AUTHENTICATE, params);
+    if (result.success && result.sessionId) {
+      this.#sessionId = result.sessionId;
+    }
+    return result;
   }
   /**
-   * Register a handler for connection state changes.
+   * Refresh authentication credentials.
    *
-   * @param handler - Function called when state changes
-   * @returns Unsubscribe function to remove the handler
+   * Use this to update credentials before they expire for long-lived connections.
+   *
+   * @param auth - New authentication credentials
+   * @returns Updated principal information
    */
-  onStateChange(handler) {
-    return this.#connection.onStateChange(handler);
+  async refreshAuth(auth) {
+    const params = {
+      method: auth.method,
+      credential: auth.credential
+    };
+    return this.#connection.sendRequest(AUTH_METHODS.AUTH_REFRESH, params);
   }
-  // ===========================================================================
-  // Internal
-  // ===========================================================================
   /**
-   * Handle incoming notifications
+   * Disconnect from the MAP system
+   * @param reason - Optional reason for disconnecting
+   * @returns Resume token that can be used to resume this session later
    */
-  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;
+  async disconnect(reason) {
+    if (!this.#connected) return void 0;
+    let resumeToken;
+    try {
+      const result = await this.#connection.sendRequest(
+        CORE_METHODS.DISCONNECT,
+        reason ? { reason } : void 0
+      );
+      resumeToken = result.resumeToken;
+      if (resumeToken) {
+        this.#lastResumeToken = resumeToken;
       }
-      case NOTIFICATION_METHODS.MESSAGE: {
-        break;
+    } finally {
+      for (const stream of this.#acpStreams.values()) {
+        await stream.close();
       }
-      default:
-        console.warn("MAP: Unknown notification:", method);
+      this.#acpStreams.clear();
+      for (const subscription of this.#subscriptions.values()) {
+        subscription._close();
+      }
+      this.#subscriptions.clear();
+      await this.#connection.close();
+      this.#connected = false;
     }
+    return resumeToken;
   }
   /**
-   * Emit a reconnection event to all registered handlers
+   * Whether the client is connected
    */
-  #emitReconnectionEvent(event) {
-    for (const handler of this.#reconnectionHandlers) {
-      try {
-        handler(event);
-      } catch (error) {
-        console.error("MAP: Reconnection event handler error:", error);
-      }
-    }
+  get isConnected() {
+    return this.#connected && !this.#connection.isClosed;
   }
   /**
-   * Handle disconnect when auto-reconnect is enabled
+   * Current session ID
    */
-  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))
-      });
-    }
+  get sessionId() {
+    return this.#sessionId;
   }
   /**
-   * Attempt to reconnect with retry logic
+   * Server capabilities
    */
-  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();
-    }
+  get serverCapabilities() {
+    return this.#serverCapabilities;
   }
   /**
-   * Restore subscriptions after reconnection
+   * AbortSignal that triggers when the connection closes
    */
-  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))
-        });
-      }
-    }
+  get signal() {
+    return this.#connection.signal;
   }
-};
-
-// src/connection/agent.ts
-var AgentConnection = class _AgentConnection {
-  #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();
-        }
-      });
-    }
+  /**
+   * Promise that resolves when the connection closes
+   */
+  get closed() {
+    return this.#connection.closed;
   }
   // ===========================================================================
-  // Static Factory Methods
+  // Session Management
   // ===========================================================================
   /**
-   * Connect and register an agent via WebSocket URL.
-   *
-   * Handles:
-   * - WebSocket creation and connection
-   * - Stream wrapping
-   * - Auto-configuration of createStream for reconnection
-   * - Initial MAP protocol connect handshake
-   * - Agent registration
-   *
-   * @param url - WebSocket URL (ws:// or wss://)
-   * @param options - Connection and agent options
-   * @returns Connected and registered AgentConnection instance
-   *
-   * @example
-   * ```typescript
-   * const agent = await AgentConnection.connect('ws://localhost:8080', {
-   *   name: 'Worker',
-   *   role: 'processor',
-   *   reconnection: true
-   * });
-   *
-   * // Already registered, ready to work
-   * agent.onMessage(handleMessage);
-   * await agent.busy();
-   * ```
+   * List available sessions
    */
-  static async connect(url, options) {
-    const parsedUrl = new URL(url);
-    if (!["ws:", "wss:"].includes(parsedUrl.protocol)) {
-      throw new Error(
-        `Unsupported protocol: ${parsedUrl.protocol}. Use ws: or wss:`
-      );
-    }
-    const timeout = options?.connectTimeout ?? 1e4;
-    const ws = new WebSocket(url);
-    await waitForOpen(ws, timeout);
-    const stream = websocketStream(ws);
-    const createStream = async () => {
-      const newWs = new WebSocket(url);
-      await waitForOpen(newWs, timeout);
-      return websocketStream(newWs);
-    };
-    const reconnection = options?.reconnection === true ? { enabled: true } : typeof options?.reconnection === "object" ? options.reconnection : void 0;
-    const agent = new _AgentConnection(stream, {
-      name: options?.name,
-      role: options?.role,
-      capabilities: options?.capabilities,
-      visibility: options?.visibility,
-      parent: options?.parent,
-      scopes: options?.scopes,
-      createStream,
-      reconnection
-    });
-    await agent.connect({ auth: options?.auth });
-    return agent;
+  async listSessions() {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LIST);
   }
-  // ===========================================================================
-  // Connection Lifecycle
-  // ===========================================================================
   /**
-   * Connect and register with the MAP system
+   * Load an existing session
    */
-  async connect(options) {
-    const connectParams = {
-      protocolVersion: PROTOCOL_VERSION,
-      participantType: "agent",
-      participantId: options?.agentId,
-      name: this.#options.name,
-      capabilities: this.#options.capabilities,
-      resumeToken: options?.resumeToken,
-      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
-   * @param reason - Optional reason for disconnecting
-   * @returns Resume token that can be used to resume this session later
-   */
-  async disconnect(reason) {
-    if (!this.#connected) return void 0;
-    let resumeToken;
-    try {
-      if (this.#agentId) {
-        await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_UNREGISTER, {
-          agentId: this.#agentId,
-          reason
-        });
-      }
-      const result = await this.#connection.sendRequest(
-        CORE_METHODS.DISCONNECT,
-        reason ? { reason } : void 0
-      );
-      resumeToken = result.resumeToken;
-    } finally {
-      for (const subscription of this.#subscriptions.values()) {
-        subscription._close();
-      }
-      this.#subscriptions.clear();
-      await this.#connection.close();
-      this.#connected = false;
-    }
-    return resumeToken;
-  }
-  /**
-   * 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;
+  async loadSession(sessionId) {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_LOAD, { sessionId });
   }
   /**
-   * Server capabilities
+   * Close the current session
    */
-  get serverCapabilities() {
-    return this.#serverCapabilities;
+  async closeSession(sessionId) {
+    return this.#connection.sendRequest(SESSION_METHODS.SESSION_CLOSE, { sessionId });
   }
+  // ===========================================================================
+  // Agent Queries
+  // ===========================================================================
   /**
-   * Current agent state
+   * List agents with optional filters
    */
-  get state() {
-    return this.#currentState;
+  async listAgents(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.AGENTS_LIST, options);
   }
   /**
-   * AbortSignal that triggers when the connection closes
+   * Get a single agent by ID
    */
-  get signal() {
-    return this.#connection.signal;
+  async getAgent(agentId, options) {
+    const params = { agentId, ...options };
+    return this.#connection.sendRequest(
+      OBSERVATION_METHODS.AGENTS_GET,
+      params
+    );
   }
   /**
-   * Promise that resolves when the connection closes
+   * Get the agent structure/hierarchy graph
    */
-  get closed() {
-    return this.#connection.closed;
+  async getStructureGraph(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.STRUCTURE_GRAPH, options);
   }
   // ===========================================================================
-  // Message Handling
+  // Scope Queries
   // ===========================================================================
   /**
-   * Register a handler for incoming messages
-   */
-  onMessage(handler) {
-    this.#messageHandlers.add(handler);
-    return this;
-  }
-  /**
-   * Remove a message handler
+   * List scopes
    */
-  offMessage(handler) {
-    this.#messageHandlers.delete(handler);
-    return this;
+  async listScopes(options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_LIST, options);
   }
-  // ===========================================================================
-  // State Management
-  // ===========================================================================
   /**
-   * Update this agent's state
+   * Get a single scope by ID
    */
-  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;
+  async getScope(scopeId) {
+    const result = await this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_GET, { scopeId });
+    return result.scope;
   }
   /**
-   * Update this agent's metadata
+   * List members of a scope
    */
-  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
+  async getScopeMembers(scopeId, options) {
+    return this.#connection.sendRequest(OBSERVATION_METHODS.SCOPES_MEMBERS, {
+      scopeId,
+      ...options
     });
-    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
@@ -2756,24 +2989,6 @@ var AgentConnection = class _AgentConnection {
     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
    */
@@ -2787,61 +3002,109 @@ var AgentConnection = class _AgentConnection {
     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)
+   * Send a message to agents with a specific role
    */
-  async reply(originalMessage, payload, meta) {
-    return this.send({ agent: originalMessage.from }, payload, {
-      ...meta,
-      correlationId: originalMessage.meta?.correlationId ?? originalMessage.id,
-      isResult: true
-    });
+  async sendToRole(role, payload, meta, withinScope) {
+    return this.send({ role, within: withinScope }, payload, meta);
   }
-  // ===========================================================================
-  // Scope Management
-  // ===========================================================================
   /**
-   * Create a new scope
+   * Broadcast a message to all agents
    */
-  async createScope(options) {
-    const result = await this.#connection.sendRequest(SCOPE_METHODS.SCOPES_CREATE, options);
-    return result.scope;
+  async broadcast(payload, meta) {
+    return this.send({ broadcast: true }, payload, meta);
   }
   /**
-   * Join a scope
+   * 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 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
+  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
     });
-    this.#scopeMemberships.add(scopeId);
-    return result;
+    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();
+    }
   }
+  // ===========================================================================
+  // ACP Streams
+  // ===========================================================================
   /**
-   * Leave a scope
+   * Create a virtual ACP stream connection to an agent.
+   *
+   * This allows clients to interact with ACP-compatible agents using the
+   * familiar ACP interface while routing all messages through MAP.
+   *
+   * @param options - Stream configuration options
+   * @returns ACPStreamConnection instance ready for initialize()
+   *
+   * @example
+   * ```typescript
+   * const acp = client.createACPStream({
+   *   targetAgent: 'coding-agent-1',
+   *   client: {
+   *     requestPermission: async (req) => ({
+   *       outcome: { outcome: 'selected', optionId: 'allow' }
+   *     }),
+   *     sessionUpdate: async (update) => {
+   *       console.log('Agent update:', update);
+   *     }
+   *   }
+   * });
+   *
+   * await acp.initialize({
+   *   protocolVersion: 20241007,
+   *   clientInfo: { name: 'IDE', version: '1.0' }
+   * });
+   * const { sessionId } = await acp.newSession({ cwd: '/project', mcpServers: [] });
+   * const result = await acp.prompt({
+   *   sessionId,
+   *   prompt: [{ type: 'text', text: 'Hello' }]
+   * });
+   *
+   * await acp.close();
+   * ```
    */
-  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
+  createACPStream(options) {
+    const stream = new ACPStreamConnection(this, options);
+    this.#acpStreams.set(stream.streamId, stream);
+    stream.on("close", () => {
+      this.#acpStreams.delete(stream.streamId);
     });
-    this.#scopeMemberships.delete(scopeId);
-    return result;
+    return stream;
+  }
+  /**
+   * Get an active ACP stream by ID.
+   */
+  getACPStream(streamId) {
+    return this.#acpStreams.get(streamId);
+  }
+  /**
+   * Get all active ACP streams.
+   */
+  get acpStreams() {
+    return this.#acpStreams;
   }
   // ===========================================================================
   // Subscriptions
@@ -2853,12 +3116,34 @@ var AgentConnection = class _AgentConnection {
     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 }
+      { 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;
   }
   /**
@@ -2870,15 +3155,119 @@ var AgentConnection = class _AgentConnection {
       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 connectionState() {
+  get state() {
     return this.#connection.state;
   }
   /**
@@ -2892,6 +3281,26 @@ var AgentConnection = class _AgentConnection {
    *
    * @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);
@@ -2919,18 +3328,12 @@ var AgentConnection = class _AgentConnection {
         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: {
-        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:
@@ -2978,19 +3381,13 @@ var AgentConnection = class _AgentConnection {
       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;
+        const connectResult = await this.connect(this.#lastConnectOptions);
+        this.#sessionId = connectResult.sessionId;
+        this.#serverCapabilities = connectResult.capabilities;
       },
       retryPolicy,
       {
@@ -3006,26 +3403,754 @@ var AgentConnection = class _AgentConnection {
     );
     this.#isReconnecting = false;
     this.#emitReconnectionEvent({ type: "reconnected" });
-    if (options.restoreScopeMemberships !== false) {
-      await this.#restoreScopeMemberships(scopesToRestore);
+    if (options.restoreSubscriptions !== false) {
+      await this.#restoreSubscriptions();
     }
   }
   /**
-   * Restore scope memberships after reconnection
+   * Restore subscriptions after reconnection
    */
-  async #restoreScopeMemberships(scopes) {
-    this.#scopeMemberships.clear();
-    for (const scopeId of scopes) {
+  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 {
-        await this.joinScope(scopeId);
-      } catch (error) {
-        console.warn("MAP: Failed to restore scope membership:", scopeId, error);
-      }
-    }
-  }
-};
-
-// src/federation/envelope.ts
+        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 _AgentConnection {
+  #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();
+        }
+      });
+    }
+  }
+  // ===========================================================================
+  // Static Factory Methods
+  // ===========================================================================
+  /**
+   * Connect and register an agent via WebSocket URL.
+   *
+   * Handles:
+   * - WebSocket creation and connection
+   * - Stream wrapping
+   * - Auto-configuration of createStream for reconnection
+   * - Initial MAP protocol connect handshake
+   * - Agent registration
+   *
+   * @param url - WebSocket URL (ws:// or wss://)
+   * @param options - Connection and agent options
+   * @returns Connected and registered AgentConnection instance
+   *
+   * @example
+   * ```typescript
+   * const agent = await AgentConnection.connect('ws://localhost:8080', {
+   *   name: 'Worker',
+   *   role: 'processor',
+   *   reconnection: true
+   * });
+   *
+   * // Already registered, ready to work
+   * agent.onMessage(handleMessage);
+   * await agent.busy();
+   * ```
+   */
+  static async connect(url, options) {
+    const parsedUrl = new URL(url);
+    if (!["ws:", "wss:"].includes(parsedUrl.protocol)) {
+      throw new Error(
+        `Unsupported protocol: ${parsedUrl.protocol}. Use ws: or wss:`
+      );
+    }
+    const timeout = options?.connectTimeout ?? 1e4;
+    const ws = new WebSocket(url);
+    await waitForOpen(ws, timeout);
+    const stream = websocketStream(ws);
+    const createStream = async () => {
+      const newWs = new WebSocket(url);
+      await waitForOpen(newWs, timeout);
+      return websocketStream(newWs);
+    };
+    const reconnection = options?.reconnection === true ? { enabled: true } : typeof options?.reconnection === "object" ? options.reconnection : void 0;
+    const agent = new _AgentConnection(stream, {
+      name: options?.name,
+      role: options?.role,
+      capabilities: options?.capabilities,
+      visibility: options?.visibility,
+      parent: options?.parent,
+      scopes: options?.scopes,
+      createStream,
+      reconnection
+    });
+    await agent.connect({ auth: options?.auth });
+    return agent;
+  }
+  /**
+   * Connect and register an agent via agentic-mesh transport.
+   *
+   * Handles:
+   * - Dynamic import of agentic-mesh (optional peer dependency)
+   * - Stream creation over encrypted mesh tunnel
+   * - Auto-configuration of createStream for reconnection
+   * - Initial MAP protocol connect handshake
+   * - Agent registration
+   *
+   * Requires `agentic-mesh` to be installed as a peer dependency.
+   *
+   * @param options - Mesh connection and agent options
+   * @returns Connected and registered AgentConnection instance
+   *
+   * @example
+   * ```typescript
+   * import { createNebulaTransport } from 'agentic-mesh';
+   *
+   * const transport = createNebulaTransport({
+   *   configPath: '/etc/nebula/config.yml',
+   * });
+   *
+   * const agent = await AgentConnection.connectMesh({
+   *   transport,
+   *   peer: { peerId: 'server', address: '10.0.0.1', port: 4242 },
+   *   localPeerId: 'my-agent',
+   *   name: 'MeshWorker',
+   *   role: 'processor',
+   *   reconnection: true
+   * });
+   *
+   * agent.onMessage(handleMessage);
+   * await agent.busy();
+   * ```
+   */
+  static async connectMesh(options) {
+    const { agenticMeshStream: agenticMeshStream2 } = await Promise.resolve().then(() => (init_agentic_mesh(), agentic_mesh_exports));
+    const streamConfig = {
+      transport: options.transport,
+      peer: options.peer,
+      localPeerId: options.localPeerId,
+      timeout: options.timeout
+    };
+    const stream = await agenticMeshStream2(streamConfig);
+    const createStream = async () => agenticMeshStream2(streamConfig);
+    const reconnection = options.reconnection === true ? { enabled: true } : typeof options.reconnection === "object" ? options.reconnection : void 0;
+    const agent = new _AgentConnection(stream, {
+      name: options.name,
+      role: options.role,
+      capabilities: options.capabilities,
+      visibility: options.visibility,
+      parent: options.parent,
+      scopes: options.scopes,
+      createStream,
+      reconnection
+    });
+    await agent.connect({ auth: options.auth });
+    return agent;
+  }
+  // ===========================================================================
+  // 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,
+      resumeToken: options?.resumeToken,
+      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 };
+  }
+  /**
+   * Authenticate with the server after connection.
+   *
+   * Use this when the server returns `authRequired` in the connect response,
+   * indicating that authentication is needed before registering or accessing
+   * protected resources.
+   *
+   * @param auth - Authentication credentials
+   * @returns Authentication result with principal if successful
+   *
+   * @example
+   * ```typescript
+   * const agent = new AgentConnection(stream, { name: 'MyAgent' });
+   *
+   * // First connect to get auth requirements
+   * const connectResult = await agent.connectOnly();
+   *
+   * if (connectResult.authRequired) {
+   *   const authResult = await agent.authenticate({
+   *     method: 'api-key',
+   *     token: process.env.AGENT_API_KEY,
+   *   });
+   *
+   *   if (authResult.success) {
+   *     // Now register the agent
+   *     await agent.register({ name: 'MyAgent', role: 'worker' });
+   *   }
+   * }
+   * ```
+   */
+  async authenticate(auth) {
+    const params = {
+      method: auth.method,
+      credential: auth.token
+    };
+    const result = await this.#connection.sendRequest(AUTH_METHODS.AUTHENTICATE, params);
+    if (result.success && result.sessionId) {
+      this.#sessionId = result.sessionId;
+    }
+    return result;
+  }
+  /**
+   * Refresh authentication credentials.
+   *
+   * Use this to update credentials before they expire for long-lived connections.
+   *
+   * @param auth - New authentication credentials
+   * @returns Updated principal information
+   */
+  async refreshAuth(auth) {
+    const params = {
+      method: auth.method,
+      credential: auth.token
+    };
+    return this.#connection.sendRequest(AUTH_METHODS.AUTH_REFRESH, params);
+  }
+  /**
+   * Disconnect from the MAP system
+   * @param reason - Optional reason for disconnecting
+   * @returns Resume token that can be used to resume this session later
+   */
+  async disconnect(reason) {
+    if (!this.#connected) return void 0;
+    let resumeToken;
+    try {
+      if (this.#agentId) {
+        await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_UNREGISTER, {
+          agentId: this.#agentId,
+          reason
+        });
+      }
+      const result = await this.#connection.sendRequest(
+        CORE_METHODS.DISCONNECT,
+        reason ? { reason } : void 0
+      );
+      resumeToken = result.resumeToken;
+    } finally {
+      for (const subscription of this.#subscriptions.values()) {
+        subscription._close();
+      }
+      this.#subscriptions.clear();
+      await this.#connection.close();
+      this.#connected = false;
+    }
+    return resumeToken;
+  }
+  /**
+   * 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,
@@ -3873,7 +4998,7 @@ var EventSchema = zod.z.object({
 var SubscriptionFilterSchema = zod.z.object({
   eventTypes: zod.z.array(EventTypeSchema).optional(),
   scopes: zod.z.array(ScopeIdSchema).optional(),
-  agents: zod.z.array(AgentIdSchema).optional(),
+  fromAgents: zod.z.array(AgentIdSchema).optional(),
   includeChildren: zod.z.boolean().optional(),
   _meta: MetaSchema
 }).strict();
@@ -4335,283 +5460,945 @@ function canPerformAction(context, action) {
       }
     }
   }
-  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
-      };
-    }
+  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;
+}
+
+// src/server/messages/address.ts
+var SEPARATOR = ":";
+var VALID_ADDRESS_TYPES = ["agent", "scope"];
+var InvalidAddressError = class extends Error {
+  constructor(address, reason) {
+    super(`Invalid address "${address}": ${reason}`);
+    this.name = "InvalidAddressError";
+  }
+};
+function formatAddress(type, id) {
+  if (!id) {
+    throw new InvalidAddressError("", "ID cannot be empty");
+  }
+  if (id.includes(SEPARATOR)) {
+    throw new InvalidAddressError(id, "ID cannot contain colon separator");
+  }
+  return `${type}${SEPARATOR}${id}`;
+}
+function parseAddress(address) {
+  const separatorIndex = address.indexOf(SEPARATOR);
+  if (separatorIndex === -1) {
+    throw new InvalidAddressError(address, "missing type prefix");
+  }
+  const type = address.slice(0, separatorIndex);
+  const id = address.slice(separatorIndex + 1);
+  if (!VALID_ADDRESS_TYPES.includes(type)) {
+    throw new InvalidAddressError(address, `invalid type "${type}", must be agent or scope`);
+  }
+  if (!id) {
+    throw new InvalidAddressError(address, "ID cannot be empty");
   }
-  return { allowed: true };
+  return {
+    type,
+    id
+  };
 }
-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;
-    }
+function isAddress(address) {
+  try {
+    parseAddress(address);
     return true;
-  });
+  } catch {
+    return false;
+  }
 }
-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 isAgentAddress(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type === "agent";
+  } catch {
+    return false;
+  }
 }
-function filterVisibleEvents(events, context) {
-  return events.filter((event) => {
-    if (!isEventTypeExposed(context.system.exposure, event.type)) {
-      return false;
-    }
-    return true;
-  });
+function isScopeAddress(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type === "scope";
+  } catch {
+    return false;
+  }
 }
-function matchesPatterns(value, patterns) {
-  return patterns.some((pattern) => matchGlob(value, pattern));
+function extractId(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.id;
+  } catch {
+    return address;
+  }
 }
-function matchGlob(value, pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
-  const regex = new RegExp(`^${escaped}$`);
-  return regex.test(value);
+function extractType(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type;
+  } catch {
+    return void 0;
+  }
 }
-function deepClone(obj) {
-  return JSON.parse(JSON.stringify(obj));
+function toAgent(agentId) {
+  return formatAddress("agent", agentId);
 }
-function deepMergePermissions(base, override) {
-  const result = { ...base };
-  if (override.canSee) {
-    result.canSee = { ...base.canSee, ...override.canSee };
+function toScope(scopeId) {
+  return formatAddress("scope", scopeId);
+}
+var MAPMeshPeer = class _MAPMeshPeer {
+  #meshPeer;
+  #config;
+  #gitService;
+  constructor(meshPeer, config) {
+    this.#meshPeer = meshPeer;
+    this.#config = config;
+    this.#gitService = meshPeer.git ? new GitSyncServiceImpl(meshPeer.git, config.git?.repoPath ?? process.cwd()) : null;
   }
-  if (override.canMessage) {
-    result.canMessage = { ...base.canMessage, ...override.canMessage };
+  // ===========================================================================
+  // Static Factory
+  // ===========================================================================
+  /**
+   * Create a new MAPMeshPeer.
+   *
+   * Requires `agentic-mesh` to be installed as a peer dependency.
+   *
+   * @param config - Peer configuration
+   * @returns Promise resolving to the created peer (not yet started)
+   */
+  static async create(config) {
+    const meshPeer = agenticMesh.createMeshPeer({
+      peerId: config.peerId,
+      peerName: config.peerName,
+      transport: config.transport,
+      git: config.git,
+      peers: config.peers,
+      map: config.map
+    });
+    return new _MAPMeshPeer(meshPeer, config);
   }
-  if (override.acceptsFrom) {
-    result.acceptsFrom = { ...base.acceptsFrom, ...override.acceptsFrom };
+  // ===========================================================================
+  // Properties
+  // ===========================================================================
+  /** Unique peer identifier */
+  get peerId() {
+    return this.#meshPeer.peerId;
   }
-  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";
+  /** Display name for this peer */
+  get peerName() {
+    return this.#meshPeer.peerName;
+  }
+  /** Whether the peer is currently running */
+  get isRunning() {
+    return this.#meshPeer.isRunning;
+  }
+  /** List of connected peer IDs */
+  get connectedPeers() {
+    return this.#meshPeer.connectedPeers;
+  }
+  /** Git sync service (null if git not enabled) */
+  get git() {
+    return this.#gitService;
+  }
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+  /**
+   * Start the mesh peer.
+   *
+   * This starts the transport, MAP server, and git service (if enabled),
+   * then connects to any initial peers specified in the config.
+   */
+  async start() {
+    await this.#meshPeer.start(this.#config.transport);
+  }
+  /**
+   * Stop the mesh peer.
+   *
+   * This disconnects from all peers, unregisters all agents,
+   * stops the git service, MAP server, and transport.
+   */
+  async stop() {
+    await this.#meshPeer.stop();
+  }
+  // ===========================================================================
+  // Peer Connections
+  // ===========================================================================
+  /**
+   * Connect to a remote peer.
+   *
+   * After connecting, agents on both peers will be discoverable
+   * and messages can be routed between them.
+   *
+   * @param endpoint - Peer endpoint to connect to
+   */
+  async connectToPeer(endpoint) {
+    await this.#meshPeer.connectToPeer(endpoint);
+  }
+  /**
+   * Disconnect from a peer.
+   *
+   * @param peerId - ID of peer to disconnect from
+   * @param reason - Optional reason for disconnecting
+   */
+  async disconnectFromPeer(peerId, reason) {
+    await this.#meshPeer.disconnectFromPeer(peerId, reason);
+  }
+  /**
+   * Check if connected to a specific peer.
+   *
+   * @param peerId - Peer ID to check
+   * @returns true if connected
+   */
+  isConnectedTo(peerId) {
+    return this.connectedPeers.includes(peerId);
+  }
+  // ===========================================================================
+  // Agent Management
+  // ===========================================================================
+  /**
+   * Create and register a local agent on this peer's MapServer.
+   *
+   * @param config - Agent configuration
+   * @returns The created agent
+   */
+  async createAgent(config) {
+    const agentConn = await this.#meshPeer.createAgent(config);
+    return new LocalAgentImpl(agentConn);
+  }
+  /**
+   * Get a local agent by ID.
+   *
+   * @param agentId - Agent ID to look up
+   * @returns The agent, or undefined if not found
+   */
+  getAgent(agentId) {
+    const conn = this.#meshPeer.getAgentConnection(agentId);
+    return conn ? new LocalAgentImpl(conn) : void 0;
+  }
+  /**
+   * Get all local agents on this peer.
+   */
+  getLocalAgents() {
+    return this.#meshPeer.getLocalAgents();
+  }
+  /**
+   * Get all known agents (local and discovered from connected peers).
+   */
+  getAllAgents() {
+    return this.#meshPeer.getAllAgents();
+  }
+  // ===========================================================================
+  // Scope Management
+  // ===========================================================================
+  /**
+   * Create a scope on this peer's MapServer.
+   *
+   * @param config - Scope configuration
+   * @returns The created scope
+   */
+  createScope(config) {
+    return this.#meshPeer.createScope(config);
+  }
+  /**
+   * Get a scope by ID.
+   *
+   * @param scopeId - Scope ID to look up
+   * @returns The scope, or undefined if not found
+   */
+  getScope(scopeId) {
+    return this.#meshPeer.getScope(scopeId);
+  }
+  /**
+   * List all scopes on this peer.
+   */
+  listScopes() {
+    return this.#meshPeer.listScopes();
+  }
+  // ===========================================================================
+  // Messaging
+  // ===========================================================================
+  /**
+   * Send a message from an agent to an address.
+   *
+   * Messages are routed to local agents or forwarded to connected peers.
+   *
+   * @param from - Sending agent ID
+   * @param to - Destination address
+   * @param payload - Message payload
+   * @param meta - Optional message metadata
+   * @returns Send result with delivery status
+   */
+  async send(from, to, payload, meta) {
+    return this.#meshPeer.send(from, to, payload, meta);
+  }
+  // ===========================================================================
+  // Events
+  // ===========================================================================
+  /**
+   * Subscribe to events from this peer's MapServer.
+   *
+   * @param filter - Optional filter for event types
+   * @returns Event subscription
+   */
+  subscribe(filter) {
+    return this.#meshPeer.subscribe(this.peerId, filter);
+  }
+  /**
+   * Register a handler for peer connection events.
+   *
+   * @param handler - Function called when a peer connects
+   * @returns Unsubscribe function
+   */
+  onPeerConnected(handler) {
+    this.#meshPeer.on("peer:connected", handler);
+    return () => this.#meshPeer.off("peer:connected", handler);
+  }
+  /**
+   * Register a handler for peer disconnection events.
+   *
+   * @param handler - Function called when a peer disconnects
+   * @returns Unsubscribe function
+   */
+  onPeerDisconnected(handler) {
+    this.#meshPeer.on("peer:disconnected", handler);
+    return () => this.#meshPeer.off("peer:disconnected", handler);
+  }
+  /**
+   * Register a handler for agent registration events.
+   *
+   * @param handler - Function called when an agent registers
+   * @returns Unsubscribe function
+   */
+  onAgentRegistered(handler) {
+    this.#meshPeer.on("agent:registered", handler);
+    return () => this.#meshPeer.off("agent:registered", handler);
+  }
+  /**
+   * Register a handler for agent unregistration events.
+   *
+   * @param handler - Function called when an agent unregisters
+   * @returns Unsubscribe function
+   */
+  onAgentUnregistered(handler) {
+    this.#meshPeer.on("agent:unregistered", handler);
+    return () => this.#meshPeer.off("agent:unregistered", handler);
+  }
+  /**
+   * Register a handler for error events.
+   *
+   * @param handler - Function called when an error occurs
+   * @returns Unsubscribe function
+   */
+  onError(handler) {
+    this.#meshPeer.on("error", handler);
+    return () => this.#meshPeer.off("error", handler);
   }
-}
-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]);
+var LocalAgentImpl = class {
+  #conn;
+  constructor(conn) {
+    this.#conn = conn;
+  }
+  get agentId() {
+    return this.#conn.agentId;
+  }
+  get name() {
+    return this.#conn.name;
+  }
+  get role() {
+    return this.#conn.role;
+  }
+  get state() {
+    return this.#conn.state;
+  }
+  async busy() {
+    await this.#conn.updateState("busy");
+  }
+  async idle() {
+    await this.#conn.updateState("idle");
+  }
+  async updateState(state) {
+    await this.#conn.updateState(state);
   }
-  if (agent.permissionOverrides) {
-    permissions = deepMergePermissions(permissions, agent.permissionOverrides);
+  async updateMetadata(metadata) {
+    await this.#conn.updateMetadata(metadata);
   }
-  if (agent.visibility && !agent.permissionOverrides?.canSee?.agents) {
-    permissions.canSee = permissions.canSee ?? {};
-    permissions.canSee.agents = mapVisibilityToRule(agent.visibility);
+  async send(to, payload, meta) {
+    return this.#conn.send(to, payload, meta);
   }
-  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;
+  onMessage(handler) {
+    const wrappedHandler = (message) => handler(message);
+    this.#conn.on("message", wrappedHandler);
+    return () => {
+      this.#conn.off("message", wrappedHandler);
+    };
   }
-  if (rule === "scoped") {
-    return (context.sharedScopes?.length ?? 0) > 0;
+  async unregister(reason) {
+    await this.#conn.unregister(reason);
   }
-  if (typeof rule === "object" && "include" in rule) {
-    return context.senderAgentId !== void 0 && rule.include.includes(context.senderAgentId);
+};
+var GitSyncServiceImpl = class {
+  #service;
+  #defaultRepoPath;
+  #defaultClient = null;
+  constructor(service, defaultRepoPath) {
+    this.#service = service;
+    this.#defaultRepoPath = defaultRepoPath;
+  }
+  get isRunning() {
+    return true;
   }
-  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);
+  get httpPort() {
+    return this.#service.httpPort;
   }
-  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);
+  createSyncClient(repoPath) {
+    return this.#service.createSyncClient(repoPath);
   }
-  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;
+  #getDefaultClient() {
+    if (!this.#defaultClient) {
+      this.#defaultClient = this.#service.createSyncClient(this.#defaultRepoPath);
+    }
+    return this.#defaultClient;
   }
-}
-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;
+  async sync(peerId, options) {
+    return this.#getDefaultClient().sync(peerId, options);
   }
-  if (canSee === "scoped") {
-    return (context.sharedScopes?.length ?? 0) > 0;
+  async pull(peerId, branch, options) {
+    return this.#getDefaultClient().pull(peerId, branch, options);
   }
-  if (canSee === "direct") {
-    return false;
+  async push(peerId, branch, options) {
+    return this.#getDefaultClient().push(peerId, branch, options);
   }
-  if (typeof canSee === "object" && "include" in canSee) {
-    return canSee.include.includes(targetAgentId);
+  async clone(peerId, destPath, options) {
+    return this.#getDefaultClient().clone(peerId, destPath, options);
   }
-  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;
+};
+
+// src/acp/adapter.ts
+var ACPAgentAdapter = class {
+  #mapAgent;
+  #handler;
+  #streamContexts = /* @__PURE__ */ new Map();
+  #pendingClientRequests = /* @__PURE__ */ new Map();
+  #clientRequestTimeout;
+  /**
+   * Create a new ACP agent adapter.
+   *
+   * @param mapAgent - The underlying MAP agent connection
+   * @param handler - Handler implementing ACP agent methods
+   * @param options - Optional configuration
+   */
+  constructor(mapAgent, handler, options) {
+    this.#mapAgent = mapAgent;
+    this.#handler = handler;
+    this.#clientRequestTimeout = options?.clientRequestTimeout ?? 3e4;
+    mapAgent.onMessage((message) => {
+      if (!message.payload || !isACPEnvelope(message.payload)) {
+        return;
+      }
+      const envelope = message.payload;
+      const { acp, acpContext } = envelope;
+      if (acp.id !== void 0 && !acp.method) {
+        void this.#handleMessage(message);
+        return;
+      }
+      if (acp.method) {
+        this.#trackStreamContext(acpContext, message.from);
+      }
+      queueMicrotask(() => void this.#handleMessage(message));
+    });
   }
-  if (canMessage === "scoped") {
-    return (context.sharedScopes?.length ?? 0) > 0;
+  /**
+   * Track stream context for a client request.
+   * This is called synchronously so that hasStream() works immediately.
+   */
+  #trackStreamContext(acpCtx, clientParticipantId) {
+    if (!this.#streamContexts.has(acpCtx.streamId)) {
+      this.#streamContexts.set(acpCtx.streamId, {
+        clientParticipantId,
+        sessionId: acpCtx.sessionId
+      });
+    } else if (acpCtx.sessionId) {
+      const streamCtx = this.#streamContexts.get(acpCtx.streamId);
+      streamCtx.sessionId = acpCtx.sessionId;
+    }
   }
-  if (typeof canMessage === "object" && "include" in canMessage) {
-    return canMessage.include.includes(targetAgentId);
+  // ===========================================================================
+  // Message Handling
+  // ===========================================================================
+  /**
+   * Handle incoming messages from MAP.
+   */
+  async #handleMessage(message) {
+    if (!message.payload || !isACPEnvelope(message.payload)) {
+      return;
+    }
+    const envelope = message.payload;
+    const { acp, acpContext } = envelope;
+    if (acp.id !== void 0 && !acp.method) {
+      const requestId = String(acp.id);
+      const pending = this.#pendingClientRequests.get(requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.#pendingClientRequests.delete(requestId);
+        if (acp.error) {
+          pending.reject(ACPError.fromResponse(acp.error));
+        } else {
+          pending.resolve(acp.result);
+        }
+      }
+      return;
+    }
+    if (acp.method) {
+      await this.#handleClientRequest(
+        acp.id,
+        acp.method,
+        acp.params,
+        acpContext,
+        message
+      );
+    }
   }
-  return false;
-}
-
-// src/server/messages/address.ts
-var SEPARATOR = ":";
-var VALID_ADDRESS_TYPES = ["agent", "scope"];
-var InvalidAddressError = class extends Error {
-  constructor(address, reason) {
-    super(`Invalid address "${address}": ${reason}`);
-    this.name = "InvalidAddressError";
+  /**
+   * Handle a client→agent request.
+   */
+  async #handleClientRequest(requestId, method, params, acpCtx, originalMessage) {
+    const ctx = {
+      streamId: acpCtx.streamId,
+      sessionId: acpCtx.sessionId,
+      clientParticipantId: originalMessage.from
+    };
+    let result;
+    let error;
+    try {
+      switch (method) {
+        case ACP_METHODS.INITIALIZE:
+          result = await this.#handler.initialize(
+            params,
+            ctx
+          );
+          break;
+        case ACP_METHODS.AUTHENTICATE:
+          if (!this.#handler.authenticate) {
+            throw new ACPError(-32601, "Method not implemented: authenticate");
+          }
+          result = await this.#handler.authenticate(
+            params,
+            ctx
+          );
+          break;
+        case ACP_METHODS.SESSION_NEW:
+          result = await this.#handler.newSession(
+            params,
+            ctx
+          );
+          const newSessionResult = result;
+          const streamContext = this.#streamContexts.get(acpCtx.streamId);
+          if (streamContext) {
+            streamContext.sessionId = newSessionResult.sessionId;
+          }
+          break;
+        case ACP_METHODS.SESSION_LOAD:
+          if (!this.#handler.loadSession) {
+            throw new ACPError(-32601, "Method not implemented: session/load");
+          }
+          result = await this.#handler.loadSession(
+            params,
+            ctx
+          );
+          break;
+        case ACP_METHODS.SESSION_SET_MODE:
+          if (!this.#handler.setSessionMode) {
+            throw new ACPError(-32601, "Method not implemented: session/set_mode");
+          }
+          result = await this.#handler.setSessionMode(
+            params,
+            ctx
+          );
+          break;
+        case ACP_METHODS.SESSION_PROMPT:
+          result = await this.#handler.prompt(params, ctx);
+          break;
+        case ACP_METHODS.SESSION_CANCEL:
+          await this.#handler.cancel(params, ctx);
+          return;
+        default:
+          throw new ACPError(-32601, `Unknown method: ${method}`);
+      }
+    } catch (e) {
+      if (e instanceof ACPError) {
+        error = e;
+      } else {
+        error = new ACPError(-32603, e.message);
+      }
+    }
+    if (requestId !== void 0) {
+      const responseEnvelope = {
+        acp: {
+          jsonrpc: "2.0",
+          id: requestId,
+          ...error ? { error: error.toErrorObject() } : { result }
+        },
+        acpContext: {
+          streamId: acpCtx.streamId,
+          sessionId: this.#streamContexts.get(acpCtx.streamId)?.sessionId ?? null,
+          direction: "agent-to-client"
+        }
+      };
+      this.#mapAgent.send(
+        { participant: originalMessage.from },
+        responseEnvelope,
+        {
+          protocol: "acp",
+          correlationId: originalMessage.id
+        }
+      ).catch((err) => {
+        console.error("ACP: Failed to send response:", err);
+      });
+    }
   }
-};
-function formatAddress(type, id) {
-  if (!id) {
-    throw new InvalidAddressError("", "ID cannot be empty");
+  // ===========================================================================
+  // Agent→Client Communication
+  // ===========================================================================
+  /**
+   * Send a session update notification to the client.
+   */
+  async sendSessionUpdate(streamId, notification) {
+    const streamCtx = this.#streamContexts.get(streamId);
+    if (!streamCtx) {
+      throw new Error(`Unknown stream: ${streamId}`);
+    }
+    const envelope = {
+      acp: {
+        jsonrpc: "2.0",
+        method: ACP_METHODS.SESSION_UPDATE,
+        params: notification
+      },
+      acpContext: {
+        streamId,
+        sessionId: streamCtx.sessionId,
+        direction: "agent-to-client"
+      }
+    };
+    await this.#mapAgent.send(
+      { participant: streamCtx.clientParticipantId },
+      envelope,
+      { protocol: "acp" }
+    );
   }
-  if (id.includes(SEPARATOR)) {
-    throw new InvalidAddressError(id, "ID cannot contain colon separator");
+  /**
+   * Send an agent→client request and wait for response.
+   */
+  async #sendClientRequest(streamId, method, params) {
+    const streamCtx = this.#streamContexts.get(streamId);
+    if (!streamCtx) {
+      throw new Error(`Unknown stream: ${streamId}`);
+    }
+    const correlationId = `agent-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const envelope = {
+      acp: {
+        jsonrpc: "2.0",
+        id: correlationId,
+        method,
+        params
+      },
+      acpContext: {
+        streamId,
+        sessionId: streamCtx.sessionId,
+        direction: "agent-to-client",
+        pendingClientRequest: {
+          requestId: correlationId,
+          method,
+          timeout: this.#clientRequestTimeout
+        }
+      }
+    };
+    await this.#mapAgent.send(
+      { participant: streamCtx.clientParticipantId },
+      envelope,
+      { protocol: "acp", correlationId }
+    );
+    return new Promise((resolve, reject) => {
+      const timeoutHandle = setTimeout(() => {
+        this.#pendingClientRequests.delete(correlationId);
+        reject(new Error(`Client request timed out: ${method}`));
+      }, this.#clientRequestTimeout);
+      this.#pendingClientRequests.set(correlationId, {
+        resolve,
+        reject,
+        timeout: timeoutHandle,
+        method
+      });
+    });
   }
-  return `${type}${SEPARATOR}${id}`;
-}
-function parseAddress(address) {
-  const separatorIndex = address.indexOf(SEPARATOR);
-  if (separatorIndex === -1) {
-    throw new InvalidAddressError(address, "missing type prefix");
+  /**
+   * Request permission from the client.
+   */
+  async requestPermission(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.REQUEST_PERMISSION, request);
   }
-  const type = address.slice(0, separatorIndex);
-  const id = address.slice(separatorIndex + 1);
-  if (!VALID_ADDRESS_TYPES.includes(type)) {
-    throw new InvalidAddressError(address, `invalid type "${type}", must be agent or scope`);
+  /**
+   * Read a text file from the client.
+   */
+  async readTextFile(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.FS_READ_TEXT_FILE, request);
   }
-  if (!id) {
-    throw new InvalidAddressError(address, "ID cannot be empty");
+  /**
+   * Write a text file on the client.
+   */
+  async writeTextFile(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.FS_WRITE_TEXT_FILE, request);
   }
-  return {
-    type,
-    id
-  };
-}
-function isAddress(address) {
-  try {
-    parseAddress(address);
-    return true;
-  } catch {
-    return false;
+  /**
+   * Create a terminal on the client.
+   */
+  async createTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_CREATE, request);
   }
-}
-function isAgentAddress(address) {
-  try {
-    const parsed = parseAddress(address);
-    return parsed.type === "agent";
-  } catch {
-    return false;
+  /**
+   * Get terminal output from the client.
+   */
+  async terminalOutput(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_OUTPUT, request);
   }
-}
-function isScopeAddress(address) {
-  try {
-    const parsed = parseAddress(address);
-    return parsed.type === "scope";
-  } catch {
-    return false;
+  /**
+   * Release a terminal on the client.
+   */
+  async releaseTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_RELEASE, request);
   }
-}
-function extractId(address) {
-  try {
-    const parsed = parseAddress(address);
-    return parsed.id;
-  } catch {
-    return address;
+  /**
+   * Wait for a terminal to exit on the client.
+   */
+  async waitForTerminalExit(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_WAIT_FOR_EXIT, request);
   }
-}
-function extractType(address) {
-  try {
-    const parsed = parseAddress(address);
-    return parsed.type;
-  } catch {
-    return void 0;
+  /**
+   * Kill a terminal command on the client.
+   */
+  async killTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_KILL, request);
   }
-}
-function toAgent(agentId) {
-  return formatAddress("agent", agentId);
-}
-function toScope(scopeId) {
-  return formatAddress("scope", scopeId);
-}
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+  /**
+   * Get the current session ID for a stream.
+   */
+  getSessionId(streamId) {
+    return this.#streamContexts.get(streamId)?.sessionId ?? null;
+  }
+  /**
+   * Get the client participant ID for a stream.
+   */
+  getClientParticipantId(streamId) {
+    return this.#streamContexts.get(streamId)?.clientParticipantId;
+  }
+  /**
+   * Check if a stream is active.
+   */
+  hasStream(streamId) {
+    return this.#streamContexts.has(streamId);
+  }
+  /**
+   * Remove a stream context (e.g., on disconnect).
+   */
+  removeStream(streamId) {
+    return this.#streamContexts.delete(streamId);
+  }
+};
 
 Object.defineProperty(exports, "monotonicFactory", {
   enumerable: true,
@@ -4621,6 +6408,12 @@ Object.defineProperty(exports, "ulid", {
   enumerable: true,
   get: function () { return ulid.ulid; }
 });
+exports.ACPAgentAdapter = ACPAgentAdapter;
+exports.ACPError = ACPError;
+exports.ACPStreamConnection = ACPStreamConnection;
+exports.ACP_ERROR_CODES = ACP_ERROR_CODES;
+exports.ACP_METHODS = ACP_METHODS;
+exports.ACP_PROTOCOL_VERSION = ACP_PROTOCOL_VERSION;
 exports.AGENT_ERROR_CODES = AGENT_ERROR_CODES;
 exports.AUTH_ERROR_CODES = AUTH_ERROR_CODES;
 exports.AUTH_METHODS = AUTH_METHODS;
@@ -4662,6 +6455,7 @@ exports.LIFECYCLE_METHODS = LIFECYCLE_METHODS;
 exports.MAPConnectionError = MAPConnectionError;
 exports.MAPErrorDataSchema = MAPErrorDataSchema;
 exports.MAPErrorSchema = MAPErrorSchema;
+exports.MAPMeshPeer = MAPMeshPeer;
 exports.MAPNotificationSchema = MAPNotificationSchema;
 exports.MAPRequestError = MAPRequestError;
 exports.MAPRequestSchema = MAPRequestSchema;
@@ -4711,6 +6505,7 @@ exports.SubscriptionIdSchema = SubscriptionIdSchema;
 exports.SystemAddressSchema = SystemAddressSchema;
 exports.TimestampSchema = TimestampSchema;
 exports.TransportTypeSchema = TransportTypeSchema;
+exports.agenticMeshStream = agenticMeshStream;
 exports.buildAgentsGetResponse = buildAgentsGetResponse;
 exports.buildAgentsListResponse = buildAgentsListResponse;
 exports.buildAgentsRegisterResponse = buildAgentsRegisterResponse;
@@ -4739,6 +6534,7 @@ exports.canSeeAgent = canSeeAgent;
 exports.canSeeScope = canSeeScope;
 exports.canSendToScope = canSendToScope;
 exports.compareUlid = compareUlid;
+exports.createACPStream = createACPStream;
 exports.createErrorResponse = createErrorResponse;
 exports.createEvent = createEvent;
 exports.createFederationEnvelope = createFederationEnvelope;
@@ -4761,6 +6557,12 @@ exports.getMethodsByCategory = getMethodsByCategory;
 exports.getRequiredCapabilities = getRequiredCapabilities;
 exports.hasCapability = hasCapability;
 exports.hasRequiredCapabilities = hasRequiredCapabilities;
+exports.isACPEnvelope = isACPEnvelope;
+exports.isACPErrorResponse = isACPErrorResponse;
+exports.isACPNotification = isACPNotification;
+exports.isACPRequest = isACPRequest;
+exports.isACPResponse = isACPResponse;
+exports.isACPSuccessResponse = isACPSuccessResponse;
 exports.isAddress = isAddress;
 exports.isAgentAddress = isAgentAddress;
 exports.isAgentExposed = isAgentExposed;