@multi-agent-protocol/sdk 0.0.4 → 0.0.6

package/dist/testing.js

@@ -1,4 +1,85 @@
+import { TunnelStream } from 'agentic-mesh';
 import { ulid } from 'ulid';
+import { EventEmitter } from 'events';
+
+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 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/jsonrpc/index.ts
 function isRequest(message) {
@@ -61,6 +142,7 @@ var EVENT_TYPES = {
   PARTICIPANT_DISCONNECTED: "participant_disconnected",
   // Message events
   MESSAGE_SENT: "message_sent",
+  MESSAGE_DELIVERED: "message_delivered",
   // Scope events
   SCOPE_CREATED: "scope_created",
   SCOPE_MEMBER_JOINED: "scope_member_joined",
@@ -108,6 +190,10 @@ var SESSION_METHODS = {
   SESSION_LOAD: "map/session/load",
   SESSION_CLOSE: "map/session/close"
 };
+var AUTH_METHODS = {
+  AUTHENTICATE: "map/authenticate",
+  AUTH_REFRESH: "map/auth/refresh"
+};
 var PERMISSION_METHODS = {
   PERMISSIONS_UPDATE: "map/permissions/update"
 };
@@ -118,8 +204,7 @@ 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"};
 var PROTOCOL_ERROR_CODES = {
   PARSE_ERROR: -32700,
   INVALID_REQUEST: -32600,
@@ -131,7 +216,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,
@@ -270,6 +358,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)
   // ==========================================================================
@@ -1396,6 +1505,11 @@ var TestServer = class {
       if (participant) {
         this.deliverMessage(recipientId, message);
         delivered.push(recipientId);
+        this.emitEvent({
+          type: EVENT_TYPES.MESSAGE_DELIVERED,
+          source: senderAgentId ?? senderId,
+          data: { messageId, message, correlationId: params.meta?.correlationId }
+        });
       }
     }
     this.emitEvent({
@@ -1756,6 +1870,9 @@ var TestServer = class {
     if (typeof address === "string") {
       return [this.#findParticipantForAgent(address) ?? address];
     }
+    if ("participant" in address && address.participant) {
+      return this.#participants.has(address.participant) ? [address.participant] : [];
+    }
     if ("agent" in address && !("system" in address)) {
       const participantId = this.#findParticipantForAgent(address.agent);
       return participantId ? [participantId] : [];
@@ -1841,11 +1958,6 @@ var TestServer = class {
         return false;
       }
     }
-    if (filter.agents?.length && event.source) {
-      if (!filter.agents.includes(event.source)) {
-        return false;
-      }
-    }
     if (filter.fromAgents?.length && event.source) {
       if (!filter.fromAgents.includes(event.source)) {
         return false;
@@ -2033,6 +2145,7 @@ var TestServer = class {
 };
 
 // src/stream/index.ts
+init_agentic_mesh();
 function websocketStream(ws) {
   const messageQueue = [];
   let messageResolver = null;
@@ -2552,18 +2665,624 @@ function createSubscription(id, unsubscribe, options, sendAck) {
   return new Subscription(id, unsubscribe, options, sendAck);
 }
 
+// src/acp/types.ts
+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_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 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 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
+    });
+  }
+  // ===========================================================================
+  // Extension Methods
+  // ===========================================================================
+  /**
+   * Call an ACP extension method on the target agent.
+   *
+   * 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 callExtension(method, params) {
+    if (!this.#initialized) {
+      throw new Error("Must call initialize() before callExtension()");
+    }
+    return this.#sendRequest(method, 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");
+  }
+};
+
 // 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;
@@ -2629,11 +3348,70 @@ var ClientConnection = class _ClientConnection {
     await client.connect({ auth: options?.auth });
     return client;
   }
+  /**
+   * Connect to a MAP server 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
+   *
+   * Requires `agentic-mesh` to be installed as a peer dependency.
+   *
+   * @param options - Mesh connection options
+   * @returns Connected ClientConnection instance
+   *
+   * @example
+   * ```typescript
+   * 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();
+   * ```
+   */
+  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;
+  }
   // ===========================================================================
   // Connection Lifecycle
   // ===========================================================================
   /**
    * 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 connect(options) {
     const params = {
@@ -2649,10 +3427,134 @@ var ClientConnection = class _ClientConnection {
     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;
   }
+  /**
+   * 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
+   */
+  getResumeToken() {
+    return this.#lastResumeToken;
+  }
+  /**
+   * 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 reconnect(resumeToken) {
+    const tokenToUse = resumeToken ?? this.#lastResumeToken;
+    return this.connect({
+      ...this.#lastConnectOptions,
+      resumeToken: tokenToUse
+    });
+  }
+  /**
+   * Set up monitoring for token expiration
+   */
+  #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);
+    }
+  }
+  /**
+   * Authenticate with the server after connection.
+   *
+   * 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 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);
+   *   }
+   * }
+   * ```
+   */
+  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;
+  }
+  /**
+   * 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.credential
+    };
+    return this.#connection.sendRequest(AUTH_METHODS.AUTH_REFRESH, params);
+  }
   /**
    * Disconnect from the MAP system
    * @param reason - Optional reason for disconnecting
@@ -2667,7 +3569,14 @@ var ClientConnection = class _ClientConnection {
         reason ? { reason } : void 0
       );
       resumeToken = result.resumeToken;
+      if (resumeToken) {
+        this.#lastResumeToken = resumeToken;
+      }
     } finally {
+      for (const stream of this.#acpStreams.values()) {
+        await stream.close();
+      }
+      this.#acpStreams.clear();
       for (const subscription of this.#subscriptions.values()) {
         subscription._close();
       }
@@ -2849,6 +3758,65 @@ var ClientConnection = class _ClientConnection {
     }
   }
   // ===========================================================================
+  // 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
   // ===========================================================================
   /**
@@ -3488,6 +4456,66 @@ var AgentConnection = class _AgentConnection {
     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
   // ===========================================================================
@@ -3524,6 +4552,62 @@ var AgentConnection = class _AgentConnection {
     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