@multi-agent-protocol/sdk 0.0.2 → 0.0.4

package/dist/index.js

@@ -225,9 +225,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;
 }
@@ -717,6 +714,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 = [];
@@ -1523,9 +1544,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.
    *
@@ -1541,13 +1569,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());
         }
@@ -1606,6 +1635,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
@@ -1629,9 +1672,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);
       }
@@ -1745,7 +1800,7 @@ function sortCausalOrder(events) {
 }
 
 // src/connection/client.ts
-var ClientConnection = class {
+var ClientConnection = class _ClientConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #subscriptionStates = /* @__PURE__ */ new Map();
@@ -1769,6 +1824,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
   // ===========================================================================
   /**
@@ -1781,6 +1889,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);
@@ -1793,14 +1902,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();
@@ -1809,6 +1922,7 @@ var ClientConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the client is connected
@@ -2344,7 +2458,7 @@ var ClientConnection = class {
 };
 
 // src/connection/agent.ts
-var AgentConnection = class {
+var AgentConnection = class _AgentConnection {
   #connection;
   #subscriptions = /* @__PURE__ */ new Map();
   #options;
@@ -2371,6 +2485,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
   // ===========================================================================
   /**
@@ -2383,6 +2557,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);
@@ -2407,9 +2582,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, {
@@ -2417,10 +2595,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();
@@ -2429,6 +2608,7 @@ var AgentConnection = class {
       await this.#connection.close();
       this.#connected = false;
     }
+    return resumeToken;
   }
   /**
    * Whether the agent is connected
@@ -4348,6 +4528,89 @@ function canAgentMessageAgent(senderAgent, targetAgentId, context, config = DEFA
   return false;
 }
 
-export { AGENT_ERROR_CODES, AUTH_ERROR_CODES, AUTH_METHODS, AddressSchema, AgentConnection, AgentIdSchema, AgentLifecycleSchema, AgentRelationshipSchema, AgentSchema, AgentStateSchema, AgentVisibilitySchema, BaseConnection, BroadcastAddressSchema, CAPABILITY_REQUIREMENTS, CORE_METHODS, CausalEventBuffer, ClientConnection, CorrelationIdSchema, DEFAULT_AGENT_PERMISSION_CONFIG, DEFAULT_RETRY_POLICY, DeliverySemanticsSchema, DirectAddressSchema, ERROR_CODES, EVENT_TYPES, EXTENSION_METHODS, ErrorCategorySchema, EventSchema, EventTypeSchema, FEDERATION_ERROR_CODES, FEDERATION_METHODS, FederatedAddressSchema, FederationOutageBuffer, GatewayConnection, HierarchicalAddressSchema, JSONRPC_VERSION, JsonRpcVersionSchema, LIFECYCLE_METHODS, MAPConnectionError, MAPErrorDataSchema, MAPErrorSchema, MAPNotificationSchema, MAPRequestError, MAPRequestSchema, MAPResponseErrorSchema, MAPResponseSchema, MAPResponseSuccessSchema, MAPTimeoutError, MAP_METHODS, METHOD_REGISTRY, MessageIdSchema, MessageMetaSchema, MessagePrioritySchema, MessageRelationshipSchema, MessageSchema, MessageVisibilitySchema, MetaSchema, MultiAddressSchema, NOTIFICATION_METHODS, OBSERVATION_METHODS, PERMISSION_METHODS, PROTOCOL_ERROR_CODES, PROTOCOL_VERSION, ParticipantAddressSchema, ParticipantCapabilitiesSchema, ParticipantIdSchema, ParticipantTypeSchema, ProtocolVersionSchema, RESOURCE_ERROR_CODES, ROUTING_ERROR_CODES, RequestIdSchema, RoleAddressSchema, SCOPE_METHODS, SESSION_METHODS, STATE_METHODS, STEERING_METHODS, STRUCTURE_METHODS, ScopeAddressSchema, ScopeIdSchema, ScopeJoinPolicySchema, ScopeSchema, ScopeSendPolicySchema, ScopeVisibilitySchema, SessionIdSchema, Subscription, SubscriptionFilterSchema, SubscriptionIdSchema, SystemAddressSchema, TimestampSchema, TransportTypeSchema, buildAgentsGetResponse, buildAgentsListResponse, buildAgentsRegisterResponse, buildAgentsSpawnResponse, buildAgentsUnregisterResponse, buildAgentsUpdateResponse, buildConnectResponse, buildDisconnectResponse, buildScopesCreateResponse, buildScopesJoinResponse, buildScopesLeaveResponse, buildScopesListResponse, buildSendResponse, buildSubscribeResponse, buildUnsubscribeResponse, calculateDelay, canAgentAcceptMessage, canAgentMessageAgent, canAgentSeeAgent, canControlAgent, canJoinScope, canMessageAgent, canPerformAction, canPerformMethod, canSeeAgent, canSeeScope, canSendToScope, compareUlid, createErrorResponse, createEvent, createFederationEnvelope, createNotification, createRequest, createRetryPolicy, createStreamPair, createSubscription, createSuccessResponse, deepMergePermissions, filterVisibleAgents, filterVisibleEvents, filterVisibleScopes, getEnvelopeRoutingInfo, getMethodInfo, getMethodsByCategory, getRequiredCapabilities, hasCapability, hasRequiredCapabilities, isAgentExposed, isBroadcastAddress, isDirectAddress, isEnvelopeAtDestination, isErrorResponse, isEventTypeExposed, isFederatedAddress, isHierarchicalAddress, isNotification, isOrphanedAgent, isRequest, isResponse, isScopeAddress, isScopeExposed, isSuccessResponse, isValidEnvelope, isValidUlid, mapVisibilityToRule, ndJsonStream, processFederationEnvelope, resolveAgentPermissions, retryable, sleep, sortCausalOrder, ulidTimestamp, unwrapEnvelope, validateCausalOrder, websocketStream, withPayload, withRetry };
+// 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);
+}
+
+export { AGENT_ERROR_CODES, AUTH_ERROR_CODES, AUTH_METHODS, AddressSchema, AgentConnection, AgentIdSchema, AgentLifecycleSchema, AgentRelationshipSchema, AgentSchema, AgentStateSchema, AgentVisibilitySchema, BaseConnection, BroadcastAddressSchema, CAPABILITY_REQUIREMENTS, CORE_METHODS, CausalEventBuffer, ClientConnection, CorrelationIdSchema, DEFAULT_AGENT_PERMISSION_CONFIG, DEFAULT_RETRY_POLICY, DeliverySemanticsSchema, DirectAddressSchema, ERROR_CODES, EVENT_TYPES, EXTENSION_METHODS, ErrorCategorySchema, EventSchema, EventTypeSchema, FEDERATION_ERROR_CODES, FEDERATION_METHODS, FederatedAddressSchema, FederationOutageBuffer, GatewayConnection, HierarchicalAddressSchema, InvalidAddressError, JSONRPC_VERSION, JsonRpcVersionSchema, LIFECYCLE_METHODS, MAPConnectionError, MAPErrorDataSchema, MAPErrorSchema, MAPNotificationSchema, MAPRequestError, MAPRequestSchema, MAPResponseErrorSchema, MAPResponseSchema, MAPResponseSuccessSchema, MAPTimeoutError, MAP_METHODS, METHOD_REGISTRY, MessageIdSchema, MessageMetaSchema, MessagePrioritySchema, MessageRelationshipSchema, MessageSchema, MessageVisibilitySchema, MetaSchema, MultiAddressSchema, NOTIFICATION_METHODS, OBSERVATION_METHODS, PERMISSION_METHODS, PROTOCOL_ERROR_CODES, PROTOCOL_VERSION, ParticipantAddressSchema, ParticipantCapabilitiesSchema, ParticipantIdSchema, ParticipantTypeSchema, ProtocolVersionSchema, RESOURCE_ERROR_CODES, ROUTING_ERROR_CODES, RequestIdSchema, RoleAddressSchema, SCOPE_METHODS, SESSION_METHODS, STATE_METHODS, STEERING_METHODS, STRUCTURE_METHODS, ScopeAddressSchema, ScopeIdSchema, ScopeJoinPolicySchema, ScopeSchema, ScopeSendPolicySchema, ScopeVisibilitySchema, SessionIdSchema, Subscription, SubscriptionFilterSchema, SubscriptionIdSchema, SystemAddressSchema, TimestampSchema, TransportTypeSchema, buildAgentsGetResponse, buildAgentsListResponse, buildAgentsRegisterResponse, buildAgentsSpawnResponse, buildAgentsUnregisterResponse, buildAgentsUpdateResponse, buildConnectResponse, buildDisconnectResponse, buildScopesCreateResponse, buildScopesJoinResponse, buildScopesLeaveResponse, buildScopesListResponse, buildSendResponse, buildSubscribeResponse, buildUnsubscribeResponse, calculateDelay, canAgentAcceptMessage, canAgentMessageAgent, canAgentSeeAgent, canControlAgent, canJoinScope, canMessageAgent, canPerformAction, canPerformMethod, canSeeAgent, canSeeScope, canSendToScope, compareUlid, createErrorResponse, createEvent, createFederationEnvelope, createNotification, createRequest, createRetryPolicy, createStreamPair, createSubscription, createSuccessResponse, deepMergePermissions, extractId, extractType, filterVisibleAgents, filterVisibleEvents, filterVisibleScopes, formatAddress, getEnvelopeRoutingInfo, getMethodInfo, getMethodsByCategory, getRequiredCapabilities, hasCapability, hasRequiredCapabilities, isAddress, isAgentAddress, isAgentExposed, isBroadcastAddress, isDirectAddress, isEnvelopeAtDestination, isErrorResponse, isEventTypeExposed, isFederatedAddress, isHierarchicalAddress, isNotification, isOrphanedAgent, isRequest, isResponse, isScopeAddress, isScopeExposed, isSuccessResponse, isValidEnvelope, isValidUlid, mapVisibilityToRule, ndJsonStream, parseAddress, processFederationEnvelope, resolveAgentPermissions, retryable, sleep, sortCausalOrder, toAgent, toScope, ulidTimestamp, unwrapEnvelope, validateCausalOrder, waitForOpen, websocketStream, withPayload, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map