@multi-agent-protocol/sdk 0.0.2 → 0.0.4

package/dist/testing.d.cts

@@ -1,4 +1,4 @@
-import { P as ParticipantCapabilities, dy as SystemExposure, d as FederationRoutingConfig, S as Stream, aC as BaseConnection, f as SessionId, A as AgentId, m as Agent, l as ScopeId, n as Scope, c as Message, q as Event, j as ParticipantId, L as SubscriptionId, aI as ClientConnectionOptions, aH as ClientConnection, ae as AgentsListRequestParams, ct as ScopesListRequestParams, p as SubscriptionFilter, cR as Subscription, e as EventType, Y as AgentConnectionOptions, X as AgentConnection } from './index-C7XPWnxS.cjs';
+import { P as ParticipantCapabilities, dA as SystemExposure, d as FederationRoutingConfig, S as Stream, aD as BaseConnection, f as SessionId, A as AgentId, m as Agent, l as ScopeId, n as Scope, c as Message, q as Event, j as ParticipantId, L as SubscriptionId, aK as ClientConnectionOptions, aJ as ClientConnection, af as AgentsListRequestParams, cv as ScopesListRequestParams, p as SubscriptionFilter, cT as Subscription, e as EventType, Z as AgentConnectionOptions, Y as AgentConnection } from './index-Z76qC_Us.cjs';
 
 /**
  * Test MAP Server Implementation

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { P as ParticipantCapabilities, dy as SystemExposure, d as FederationRoutingConfig, S as Stream, aC as BaseConnection, f as SessionId, A as AgentId, m as Agent, l as ScopeId, n as Scope, c as Message, q as Event, j as ParticipantId, L as SubscriptionId, aI as ClientConnectionOptions, aH as ClientConnection, ae as AgentsListRequestParams, ct as ScopesListRequestParams, p as SubscriptionFilter, cR as Subscription, e as EventType, Y as AgentConnectionOptions, X as AgentConnection } from './index-C7XPWnxS.js';
+import { P as ParticipantCapabilities, dA as SystemExposure, d as FederationRoutingConfig, S as Stream, aD as BaseConnection, f as SessionId, A as AgentId, m as Agent, l as ScopeId, n as Scope, c as Message, q as Event, j as ParticipantId, L as SubscriptionId, aK as ClientConnectionOptions, aJ as ClientConnection, af as AgentsListRequestParams, cv as ScopesListRequestParams, p as SubscriptionFilter, cT as Subscription, e as EventType, Z as AgentConnectionOptions, Y as AgentConnection } from './index-Z76qC_Us.js';
 
 /**
  * Test MAP Server Implementation

package/dist/testing.js

@@ -2032,6 +2032,211 @@ var TestServer = class {
   }
 };
 
+// src/stream/index.ts
+function websocketStream(ws) {
+  const messageQueue = [];
+  let messageResolver = null;
+  let closed = false;
+  let closeError = null;
+  ws.addEventListener("message", (event) => {
+    try {
+      const message = JSON.parse(event.data);
+      if (messageResolver) {
+        messageResolver({ value: message, done: false });
+        messageResolver = null;
+      } else {
+        messageQueue.push(message);
+      }
+    } catch {
+      console.error("MAP: Failed to parse WebSocket message:", event.data);
+    }
+  });
+  ws.addEventListener("close", () => {
+    closed = true;
+    if (messageResolver) {
+      messageResolver({ value: void 0, done: true });
+      messageResolver = null;
+    }
+  });
+  ws.addEventListener("error", () => {
+    closeError = new Error("WebSocket error");
+    closed = true;
+    if (messageResolver) {
+      messageResolver({ value: void 0, done: true });
+      messageResolver = null;
+    }
+  });
+  const readable = new ReadableStream({
+    async pull(controller) {
+      if (messageQueue.length > 0) {
+        controller.enqueue(messageQueue.shift());
+        return;
+      }
+      if (closed) {
+        if (closeError) {
+          controller.error(closeError);
+        } else {
+          controller.close();
+        }
+        return;
+      }
+      await new Promise((resolve) => {
+        messageResolver = resolve;
+      }).then((result) => {
+        if (result.done) {
+          controller.close();
+        } else {
+          controller.enqueue(result.value);
+        }
+      });
+    }
+  });
+  const writable = new WritableStream({
+    async write(message) {
+      if (ws.readyState === WebSocket.CONNECTING) {
+        await new Promise((resolve, reject) => {
+          const onOpen = () => {
+            ws.removeEventListener("error", onError);
+            resolve();
+          };
+          const onError = () => {
+            ws.removeEventListener("open", onOpen);
+            reject(new Error("WebSocket failed to connect"));
+          };
+          ws.addEventListener("open", onOpen, { once: true });
+          ws.addEventListener("error", onError, { once: true });
+        });
+      }
+      if (ws.readyState !== WebSocket.OPEN) {
+        throw new Error("WebSocket is not open");
+      }
+      ws.send(JSON.stringify(message));
+    },
+    close() {
+      ws.close();
+    },
+    abort() {
+      ws.close();
+    }
+  });
+  return { readable, writable };
+}
+function 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 = [];
+  let clientToServerResolver = null;
+  let serverToClientResolver = null;
+  let clientToServerClosed = false;
+  let serverToClientClosed = false;
+  function createReadable(queue, _getResolver, setResolver, isClosed) {
+    return new ReadableStream({
+      async pull(controller) {
+        if (queue.length > 0) {
+          controller.enqueue(queue.shift());
+          return;
+        }
+        if (isClosed()) {
+          controller.close();
+          return;
+        }
+        const message = await new Promise((resolve) => {
+          setResolver((msg) => {
+            setResolver(null);
+            resolve(msg);
+          });
+        });
+        if (message === null) {
+          controller.close();
+        } else {
+          controller.enqueue(message);
+        }
+      }
+    });
+  }
+  function createWritable(queue, getResolver, setClosed) {
+    return new WritableStream({
+      write(message) {
+        const resolver = getResolver();
+        if (resolver) {
+          resolver(message);
+        } else {
+          queue.push(message);
+        }
+      },
+      close() {
+        setClosed();
+        const resolver = getResolver();
+        if (resolver) {
+          resolver(null);
+        }
+      }
+    });
+  }
+  const clientStream = {
+    // Client writes to server
+    writable: createWritable(
+      clientToServer,
+      () => clientToServerResolver,
+      () => {
+        clientToServerClosed = true;
+      }
+    ),
+    // Client reads from server
+    readable: createReadable(
+      serverToClient,
+      () => serverToClientResolver,
+      (r) => {
+        serverToClientResolver = r;
+      },
+      () => serverToClientClosed
+    )
+  };
+  const serverStream = {
+    // Server writes to client
+    writable: createWritable(
+      serverToClient,
+      () => serverToClientResolver,
+      () => {
+        serverToClientClosed = true;
+      }
+    ),
+    // Server reads from client
+    readable: createReadable(
+      clientToServer,
+      () => clientToServerResolver,
+      (r) => {
+        clientToServerResolver = r;
+      },
+      () => clientToServerClosed
+    )
+  };
+  return [clientStream, serverStream];
+}
+
 // src/subscription/index.ts
 var Subscription = class {
   id;
@@ -2348,7 +2553,7 @@ function createSubscription(id, unsubscribe, options, sendAck) {
 }
 
 // src/connection/client.ts
-var ClientConnection = class {
+var ClientConnection = class _ClientConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #subscriptionStates = /* @__PURE__ */ new Map();
@@ -2372,6 +2577,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
   // ===========================================================================
   /**
@@ -2384,6 +2642,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);
@@ -2396,14 +2655,18 @@ 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 subscription of this.#subscriptions.values()) {
         subscription._close();
@@ -2412,6 +2675,7 @@ var ClientConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the client is connected
@@ -2946,99 +3210,6 @@ var ClientConnection = class {
   }
 };
 
-// src/stream/index.ts
-function createStreamPair() {
-  const clientToServer = [];
-  const serverToClient = [];
-  let clientToServerResolver = null;
-  let serverToClientResolver = null;
-  let clientToServerClosed = false;
-  let serverToClientClosed = false;
-  function createReadable(queue, _getResolver, setResolver, isClosed) {
-    return new ReadableStream({
-      async pull(controller) {
-        if (queue.length > 0) {
-          controller.enqueue(queue.shift());
-          return;
-        }
-        if (isClosed()) {
-          controller.close();
-          return;
-        }
-        const message = await new Promise((resolve) => {
-          setResolver((msg) => {
-            setResolver(null);
-            resolve(msg);
-          });
-        });
-        if (message === null) {
-          controller.close();
-        } else {
-          controller.enqueue(message);
-        }
-      }
-    });
-  }
-  function createWritable(queue, getResolver, setClosed) {
-    return new WritableStream({
-      write(message) {
-        const resolver = getResolver();
-        if (resolver) {
-          resolver(message);
-        } else {
-          queue.push(message);
-        }
-      },
-      close() {
-        setClosed();
-        const resolver = getResolver();
-        if (resolver) {
-          resolver(null);
-        }
-      }
-    });
-  }
-  const clientStream = {
-    // Client writes to server
-    writable: createWritable(
-      clientToServer,
-      () => clientToServerResolver,
-      () => {
-        clientToServerClosed = true;
-      }
-    ),
-    // Client reads from server
-    readable: createReadable(
-      serverToClient,
-      () => serverToClientResolver,
-      (r) => {
-        serverToClientResolver = r;
-      },
-      () => serverToClientClosed
-    )
-  };
-  const serverStream = {
-    // Server writes to client
-    writable: createWritable(
-      serverToClient,
-      () => serverToClientResolver,
-      () => {
-        serverToClientClosed = true;
-      }
-    ),
-    // Server reads from client
-    readable: createReadable(
-      clientToServer,
-      () => clientToServerResolver,
-      (r) => {
-        clientToServerResolver = r;
-      },
-      () => clientToServerClosed
-    )
-  };
-  return [clientStream, serverStream];
-}
-
 // src/testing/client.ts
 var TestClient = class _TestClient {
   #connection;
@@ -3231,7 +3402,7 @@ var TestClient = class _TestClient {
 };
 
 // src/connection/agent.ts
-var AgentConnection = class {
+var AgentConnection = class _AgentConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #options;
@@ -3258,6 +3429,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
   // ===========================================================================
   /**
@@ -3270,6 +3501,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);
@@ -3294,9 +3526,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, {
@@ -3304,10 +3539,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();
@@ -3316,6 +3552,7 @@ var AgentConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the agent is connected