@multi-agent-protocol/sdk 0.0.3 → 0.0.4

package/dist/index.cjs

@@ -227,9 +227,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 +716,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 +1546,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 +1571,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 +1637,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 +1674,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);
       }
@@ -1747,7 +1802,7 @@ function sortCausalOrder(events) {
 }
 
 // src/connection/client.ts
-var ClientConnection = class {
+var ClientConnection = class _ClientConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #subscriptionStates = /* @__PURE__ */ new Map();
@@ -1771,6 +1826,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 +1891,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,14 +1904,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();
@@ -1811,6 +1924,7 @@ var ClientConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the client is connected
@@ -2346,7 +2460,7 @@ var ClientConnection = class {
 };
 
 // src/connection/agent.ts
-var AgentConnection = class {
+var AgentConnection = class _AgentConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #options;
@@ -2373,6 +2487,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 +2559,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 +2584,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 +2597,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 +2610,7 @@ var AgentConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the agent is connected
@@ -4350,6 +4530,89 @@ 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);
+}
+
 Object.defineProperty(exports, "monotonicFactory", {
   enumerable: true,
   get: function () { return ulid.monotonicFactory; }
@@ -4392,6 +4655,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;
@@ -4485,15 +4749,20 @@ 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.isAddress = isAddress;
+exports.isAgentAddress = isAgentAddress;
 exports.isAgentExposed = isAgentExposed;
 exports.isBroadcastAddress = isBroadcastAddress;
 exports.isDirectAddress = isDirectAddress;
@@ -4513,14 +4782,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;