@multi-agent-protocol/sdk 0.0.3 → 0.0.5

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var ulid = require('ulid');
+var events = require('events');
 var zod = require('zod');
 
 // src/types/index.ts
@@ -227,9 +228,6 @@ function isDirectAddress(address) {
 function isFederatedAddress(address) {
   return typeof address === "object" && "system" in address && "agent" in address;
 }
-function isScopeAddress(address) {
-  return typeof address === "object" && "scope" in address;
-}
 function isBroadcastAddress(address) {
   return typeof address === "object" && "broadcast" in address;
 }
@@ -719,6 +717,30 @@ function websocketStream(ws) {
   });
   return { readable, writable };
 }
+function waitForOpen(ws, timeoutMs = 1e4) {
+  return new Promise((resolve, reject) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      resolve();
+      return;
+    }
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error(`WebSocket connection timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const onOpen = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener("error", onError);
+      resolve();
+    };
+    const onError = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener("open", onOpen);
+      reject(new Error("WebSocket connection failed"));
+    };
+    ws.addEventListener("open", onOpen, { once: true });
+    ws.addEventListener("error", onError, { once: true });
+  });
+}
 function createStreamPair() {
   const clientToServer = [];
   const serverToClient = [];
@@ -1525,9 +1547,16 @@ var CausalEventBuffer = class {
     this.#options = {
       maxWaitTime: options.maxWaitTime ?? 5e3,
       maxBufferSize: options.maxBufferSize ?? 1e3,
+      multiCauseMode: options.multiCauseMode ?? "all",
       onForcedRelease: options.onForcedRelease
     };
   }
+  /**
+   * Get the current multi-cause mode.
+   */
+  get multiCauseMode() {
+    return this.#options.multiCauseMode;
+  }
   /**
    * Push an event into the buffer.
    *
@@ -1543,13 +1572,14 @@ var CausalEventBuffer = class {
     if (!event.receivedAt) {
       event = { ...event, receivedAt: Date.now() };
     }
-    const missingPredecessors = this.#getMissingPredecessors(event);
-    if (missingPredecessors.length === 0) {
+    const shouldRelease = this.#shouldReleaseEvent(event);
+    if (shouldRelease) {
       ready.push(event);
       this.#releaseWaiting(event.eventId, ready);
     } else {
       this.#pending.set(event.eventId, event);
-      for (const predecessorId of missingPredecessors) {
+      const predecessors = event.causedBy ?? [];
+      for (const predecessorId of predecessors) {
         if (!this.#waitingFor.has(predecessorId)) {
           this.#waitingFor.set(predecessorId, /* @__PURE__ */ new Set());
         }
@@ -1608,6 +1638,20 @@ var CausalEventBuffer = class {
     this.#pending.clear();
     this.#waitingFor.clear();
   }
+  /**
+   * Check if an event should be released based on its predecessors and the multi-cause mode.
+   */
+  #shouldReleaseEvent(event) {
+    if (!event.causedBy || event.causedBy.length === 0) {
+      return true;
+    }
+    const missingPredecessors = this.#getMissingPredecessors(event);
+    if (this.#options.multiCauseMode === "any") {
+      return missingPredecessors.length < event.causedBy.length;
+    } else {
+      return missingPredecessors.length === 0;
+    }
+  }
   /**
    * Get missing predecessors for an event.
    * A predecessor is considered "missing" if it hasn't been released yet
@@ -1631,9 +1675,21 @@ var CausalEventBuffer = class {
     for (const waitingEventId of waitingEventIds) {
       const waitingEvent = this.#pending.get(waitingEventId);
       if (!waitingEvent) continue;
-      const stillMissing = this.#getMissingPredecessors(waitingEvent);
-      if (stillMissing.length === 0) {
+      if (this.#shouldReleaseEvent(waitingEvent)) {
         this.#pending.delete(waitingEventId);
+        if (waitingEvent.causedBy) {
+          for (const otherPredId of waitingEvent.causedBy) {
+            if (otherPredId !== predecessorId) {
+              const waiting = this.#waitingFor.get(otherPredId);
+              if (waiting) {
+                waiting.delete(waitingEventId);
+                if (waiting.size === 0) {
+                  this.#waitingFor.delete(otherPredId);
+                }
+              }
+            }
+          }
+        }
         ready.push(waitingEvent);
         this.#releaseWaiting(waitingEventId, ready);
       }
@@ -1746,12 +1802,633 @@ function sortCausalOrder(events) {
   return result;
 }
 
+// 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;
+  #initialized = false;
+  #capabilities = null;
+  #closed = false;
+  #lastEventId = null;
+  #isReconnecting = false;
+  #unsubscribeReconnection = null;
+  /**
+   * Create a new ACP stream connection.
+   *
+   * @param mapClient - The underlying MAP client connection
+   * @param options - Stream configuration options
+   */
+  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);
+    });
+  }
+  // ===========================================================================
+  // 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
+  // ===========================================================================
+  /**
+   * Handle MAP reconnection events.
+   */
+  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;
+    }
+  }
+  /**
+   * Handle successful MAP reconnection.
+   */
+  async #handleReconnected() {
+    this.#subscription = null;
+    try {
+      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.#isReconnecting = false;
+      this.emit("reconnected");
+    } catch (error) {
+      this.#isReconnecting = false;
+      this.emit("error", error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  /**
+   * 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.
+   */
+  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
+  // ===========================================================================
+  /**
+   * Set up the subscription for receiving messages from the target agent.
+   */
+  async #setupSubscription() {
+    if (this.#subscription) return;
+    this.#subscription = await this.#mapClient.subscribe({
+      fromAgents: [this.#options.targetAgent]
+    });
+    void this.#processEvents();
+  }
+  /**
+   * Process incoming events from the subscription.
+   */
+  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);
+      }
+    }
+  }
+  /**
+   * 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);
+    }
+  }
+  /**
+   * Handle an ACP notification from the agent.
+   */
+  async #handleNotification(method, params, _acpContext) {
+    if (method === ACP_METHODS.SESSION_UPDATE) {
+      await this.#options.client.sessionUpdate(params);
+    }
+  }
+  /**
+   * Handle an agent→client request.
+   */
+  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
+      }
+    );
+  }
+  /**
+   * Send an ACP request and wait for response.
+   */
+  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;
+  }
+  /**
+   * Send an ACP notification (no response expected).
+   */
+  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
+  // ===========================================================================
+  /**
+   * Initialize the ACP connection with the target agent.
+   */
+  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;
+  }
+  /**
+   * Authenticate with the agent.
+   */
+  async authenticate(params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before authenticate()");
+    }
+    return this.#sendRequest(
+      ACP_METHODS.AUTHENTICATE,
+      params
+    );
+  }
+  // ===========================================================================
+  // ACP Session Methods
+  // ===========================================================================
+  /**
+   * Create a new ACP session.
+   */
+  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;
+  }
+  /**
+   * Load an existing ACP session.
+   */
+  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;
+  }
+  /**
+   * Set the session mode.
+   */
+  async setSessionMode(params) {
+    return this.#sendRequest(
+      ACP_METHODS.SESSION_SET_MODE,
+      params
+    );
+  }
+  // ===========================================================================
+  // ACP Prompt Methods
+  // ===========================================================================
+  /**
+   * Send a prompt to the agent.
+   * Updates are received via the sessionUpdate handler.
+   */
+  async prompt(params) {
+    if (!this.#sessionId) {
+      throw new Error("Must call newSession() or loadSession() before prompt()");
+    }
+    return this.#sendRequest(
+      ACP_METHODS.SESSION_PROMPT,
+      params
+    );
+  }
+  /**
+   * Cancel ongoing operations for the current session.
+   */
+  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
+    });
+  }
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+  /**
+   * Close this ACP stream and clean up resources.
+   */
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#unsubscribeReconnection) {
+      this.#unsubscribeReconnection();
+      this.#unsubscribeReconnection = null;
+    }
+    for (const [id, pending] of this.#pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("ACP stream closed"));
+      this.#pendingRequests.delete(id);
+    }
+    if (this.#subscription) {
+      await this.#subscription.unsubscribe();
+      this.#subscription = null;
+    }
+    this.emit("close");
+  }
+};
+function createACPStream(mapClient, options) {
+  return new ACPStreamConnection(mapClient, options);
+}
+
 // src/connection/client.ts
-var ClientConnection = class {
+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;
@@ -1771,6 +2448,59 @@ var ClientConnection = class {
     }
   }
   // ===========================================================================
+  // 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
+   * const client = await ClientConnection.connect('ws://localhost:8080', {
+   *   name: 'MyClient',
+   *   reconnection: true
+   * });
+   *
+   * // Already connected, ready to use
+   * const agents = await client.listAgents();
+   * ```
+   */
+  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;
+  }
+  // ===========================================================================
   // Connection Lifecycle
   // ===========================================================================
   /**
@@ -1783,6 +2513,7 @@ var ClientConnection = class {
       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);
@@ -1795,15 +2526,23 @@ var ClientConnection = class {
   }
   /**
    * 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;
+    if (!this.#connected) return void 0;
+    let resumeToken;
     try {
-      await this.#connection.sendRequest(
+      const result = await this.#connection.sendRequest(
         CORE_METHODS.DISCONNECT,
         reason ? { reason } : void 0
       );
+      resumeToken = result.resumeToken;
     } finally {
+      for (const stream of this.#acpStreams.values()) {
+        await stream.close();
+      }
+      this.#acpStreams.clear();
       for (const subscription of this.#subscriptions.values()) {
         subscription._close();
       }
@@ -1811,6 +2550,7 @@ var ClientConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the client is connected
@@ -1984,6 +2724,65 @@ var ClientConnection = class {
     }
   }
   // ===========================================================================
+  // ACP Streams
+  // ===========================================================================
+  /**
+   * 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();
+   * ```
+   */
+  createACPStream(options) {
+    const stream = new ACPStreamConnection(this, options);
+    this.#acpStreams.set(stream.streamId, stream);
+    stream.on("close", () => {
+      this.#acpStreams.delete(stream.streamId);
+    });
+    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
   // ===========================================================================
   /**
@@ -2346,7 +3145,7 @@ var ClientConnection = class {
 };
 
 // src/connection/agent.ts
-var AgentConnection = class {
+var AgentConnection = class _AgentConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #options;
@@ -2373,6 +3172,66 @@ var AgentConnection = class {
     }
   }
   // ===========================================================================
+  // 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;
+  }
+  // ===========================================================================
   // Connection Lifecycle
   // ===========================================================================
   /**
@@ -2385,6 +3244,7 @@ var AgentConnection = class {
       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);
@@ -2409,9 +3269,12 @@ var AgentConnection = class {
   }
   /**
    * 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;
+    if (!this.#connected) return void 0;
+    let resumeToken;
     try {
       if (this.#agentId) {
         await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_UNREGISTER, {
@@ -2419,10 +3282,11 @@ var AgentConnection = class {
           reason
         });
       }
-      await this.#connection.sendRequest(
+      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();
@@ -2431,6 +3295,7 @@ var AgentConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the agent is connected
@@ -4350,6 +5215,423 @@ function canAgentMessageAgent(senderAgent, targetAgentId, context, config = DEFA
   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 {
+    type,
+    id
+  };
+}
+function isAddress(address) {
+  try {
+    parseAddress(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isAgentAddress(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type === "agent";
+  } catch {
+    return false;
+  }
+}
+function isScopeAddress(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type === "scope";
+  } catch {
+    return false;
+  }
+}
+function extractId(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.id;
+  } catch {
+    return address;
+  }
+}
+function extractType(address) {
+  try {
+    const parsed = parseAddress(address);
+    return parsed.type;
+  } catch {
+    return void 0;
+  }
+}
+function toAgent(agentId) {
+  return formatAddress("agent", agentId);
+}
+function toScope(scopeId) {
+  return formatAddress("scope", scopeId);
+}
+
+// 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));
+    });
+  }
+  /**
+   * 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;
+    }
+  }
+  // ===========================================================================
+  // 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
+      );
+    }
+  }
+  /**
+   * 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);
+      });
+    }
+  }
+  // ===========================================================================
+  // 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" }
+    );
+  }
+  /**
+   * 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
+      });
+    });
+  }
+  /**
+   * Request permission from the client.
+   */
+  async requestPermission(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.REQUEST_PERMISSION, request);
+  }
+  /**
+   * Read a text file from the client.
+   */
+  async readTextFile(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.FS_READ_TEXT_FILE, request);
+  }
+  /**
+   * Write a text file on the client.
+   */
+  async writeTextFile(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.FS_WRITE_TEXT_FILE, request);
+  }
+  /**
+   * Create a terminal on the client.
+   */
+  async createTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_CREATE, request);
+  }
+  /**
+   * Get terminal output from the client.
+   */
+  async terminalOutput(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_OUTPUT, request);
+  }
+  /**
+   * Release a terminal on the client.
+   */
+  async releaseTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_RELEASE, request);
+  }
+  /**
+   * Wait for a terminal to exit on the client.
+   */
+  async waitForTerminalExit(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_WAIT_FOR_EXIT, request);
+  }
+  /**
+   * Kill a terminal command on the client.
+   */
+  async killTerminal(streamId, request) {
+    return this.#sendClientRequest(streamId, ACP_METHODS.TERMINAL_KILL, request);
+  }
+  // ===========================================================================
+  // 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,
   get: function () { return ulid.monotonicFactory; }
@@ -4358,6 +5640,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;
@@ -4392,6 +5680,7 @@ exports.FederatedAddressSchema = FederatedAddressSchema;
 exports.FederationOutageBuffer = FederationOutageBuffer;
 exports.GatewayConnection = GatewayConnection;
 exports.HierarchicalAddressSchema = HierarchicalAddressSchema;
+exports.InvalidAddressError = InvalidAddressError;
 exports.JSONRPC_VERSION = JSONRPC_VERSION;
 exports.JsonRpcVersionSchema = JsonRpcVersionSchema;
 exports.LIFECYCLE_METHODS = LIFECYCLE_METHODS;
@@ -4475,6 +5764,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;
@@ -4485,15 +5775,26 @@ exports.createStreamPair = createStreamPair;
 exports.createSubscription = createSubscription;
 exports.createSuccessResponse = createSuccessResponse;
 exports.deepMergePermissions = deepMergePermissions;
+exports.extractId = extractId;
+exports.extractType = extractType;
 exports.filterVisibleAgents = filterVisibleAgents;
 exports.filterVisibleEvents = filterVisibleEvents;
 exports.filterVisibleScopes = filterVisibleScopes;
+exports.formatAddress = formatAddress;
 exports.getEnvelopeRoutingInfo = getEnvelopeRoutingInfo;
 exports.getMethodInfo = getMethodInfo;
 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;
 exports.isBroadcastAddress = isBroadcastAddress;
 exports.isDirectAddress = isDirectAddress;
@@ -4513,14 +5814,18 @@ exports.isValidEnvelope = isValidEnvelope;
 exports.isValidUlid = isValidUlid;
 exports.mapVisibilityToRule = mapVisibilityToRule;
 exports.ndJsonStream = ndJsonStream;
+exports.parseAddress = parseAddress;
 exports.processFederationEnvelope = processFederationEnvelope;
 exports.resolveAgentPermissions = resolveAgentPermissions;
 exports.retryable = retryable;
 exports.sleep = sleep;
 exports.sortCausalOrder = sortCausalOrder;
+exports.toAgent = toAgent;
+exports.toScope = toScope;
 exports.ulidTimestamp = ulidTimestamp;
 exports.unwrapEnvelope = unwrapEnvelope;
 exports.validateCausalOrder = validateCausalOrder;
+exports.waitForOpen = waitForOpen;
 exports.websocketStream = websocketStream;
 exports.withPayload = withPayload;
 exports.withRetry = withRetry;