@multi-agent-protocol/sdk 0.1.4 → 0.1.6

package/dist/index.cjs

@@ -232,6 +232,7 @@ var TASK_METHODS = {
 var NOTIFICATION_METHODS = {
   EVENT: "map/event",
   MESSAGE: "map/message",
+  SEND: "map/send",
   /** Client acknowledges received events (for backpressure) */
   SUBSCRIBE_ACK: "map/subscribe.ack",
   /** Server notifies client that auth is about to expire */
@@ -3720,7 +3721,8 @@ var ClientConnection = class _ClientConnection {
         }
         break;
       }
-      case NOTIFICATION_METHODS.MESSAGE: {
+      case NOTIFICATION_METHODS.MESSAGE:
+      case "map/send": {
         break;
       }
       default:
@@ -3873,7 +3875,9 @@ var AgentConnection = class _AgentConnection {
   constructor(stream, options = {}) {
     this.#connection = new BaseConnection(stream, options);
     this.#options = options;
-    this.#connection.setNotificationHandler(this.#handleNotification.bind(this));
+    this.#connection.setNotificationHandler(
+      this.#handleNotification.bind(this)
+    );
     if (options.reconnection?.enabled && options.createStream) {
       this.#connection.onStateChange((newState) => {
         if (newState === "closed" && this.#connected && !this.#isReconnecting) {
@@ -3942,6 +3946,52 @@ var AgentConnection = class _AgentConnection {
     await agent.connect({ auth: options?.auth });
     return agent;
   }
+  /**
+   * Create an AgentConnection over WebSocket without performing the MAP handshake.
+   *
+   * Use this when you need to control the connection flow — e.g., to handle
+   * server-driven auth negotiation before registration.
+   *
+   * @example
+   * ```typescript
+   * const agent = await AgentConnection.createConnection('ws://localhost:8080', {
+   *   name: 'Worker',
+   *   role: 'processor',
+   * });
+   *
+   * const result = await agent.connectOnly();
+   * if (result.authRequired) {
+   *   await agent.authenticate({ method: result.authRequired.methods[0], token: cred });
+   * }
+   * await agent.register();
+   * ```
+   */
+  static async createConnection(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;
+    return new _AgentConnection(stream, {
+      name: options?.name,
+      role: options?.role,
+      capabilities: options?.capabilities,
+      visibility: options?.visibility,
+      parent: options?.parent,
+      scopes: options?.scopes,
+      createStream,
+      reconnection
+    });
+  }
   /**
    * Connect and register an agent via agentic-mesh transport.
    *
@@ -4038,6 +4088,65 @@ var AgentConnection = class _AgentConnection {
     this.#connection._transitionTo("connected");
     return { connection: connectResult, agent: registerResult.agent };
   }
+  /**
+   * Connect to the MAP system without registering an agent.
+   *
+   * Use this when the server may require authentication before registration.
+   * After connecting, check `authRequired` in the response and call
+   * `authenticate()` if needed, then `register()` to complete the handshake.
+   *
+   * @example
+   * ```typescript
+   * const result = await agent.connectOnly();
+   *
+   * if (result.authRequired) {
+   *   const method = result.authRequired.methods[0];
+   *   await agent.authenticate({ method, token: myCredential });
+   * }
+   *
+   * await agent.register();
+   * ```
+   */
+  async connectOnly(options) {
+    const connectParams = {
+      protocolVersion: PROTOCOL_VERSION,
+      participantType: "agent",
+      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);
+    this.#sessionId = connectResult.sessionId;
+    this.#serverCapabilities = connectResult.capabilities;
+    this.#connected = true;
+    this.#lastConnectOptions = options;
+    return connectResult;
+  }
+  /**
+   * Register as an agent after connecting.
+   *
+   * Call this after `connectOnly()` and optional `authenticate()` to complete
+   * the connection handshake. Uses the options provided during construction
+   * (name, role, scopes, etc.) unless overridden.
+   */
+  async register(overrides) {
+    const registerParams = {
+      agentId: overrides?.agentId ?? this.#lastConnectOptions?.agentId,
+      name: overrides?.name ?? this.#options.name,
+      role: overrides?.role ?? this.#options.role,
+      parent: this.#options.parent,
+      scopes: this.#options.scopes,
+      visibility: this.#options.visibility,
+      capabilities: this.#options.capabilities
+    };
+    const registerResult = await this.#connection.sendRequest(LIFECYCLE_METHODS.AGENTS_REGISTER, registerParams);
+    this.#agentId = registerResult.agent.id;
+    this.#currentState = registerResult.agent.state;
+    this.#connection._transitionTo("connected");
+    return registerResult.agent;
+  }
   /**
    * Authenticate with the server after connection.
    *
@@ -4050,20 +4159,15 @@ var AgentConnection = class _AgentConnection {
    *
    * @example
    * ```typescript
-   * const agent = new AgentConnection(stream, { name: 'MyAgent' });
-   *
-   * // First connect to get auth requirements
-   * const connectResult = await agent.connectOnly();
+   * const result = await agent.connectOnly();
    *
-   * if (connectResult.authRequired) {
+   * if (result.authRequired) {
    *   const authResult = await agent.authenticate({
-   *     method: 'api-key',
-   *     token: process.env.AGENT_API_KEY,
+   *     method: result.authRequired.methods[0],
+   *     token: myCredential,
    *   });
-   *
    *   if (authResult.success) {
-   *     // Now register the agent
-   *     await agent.register({ name: 'MyAgent', role: 'worker' });
+   *     await agent.register();
    *   }
    * }
    * ```
@@ -4109,10 +4213,7 @@ var AgentConnection = class _AgentConnection {
           reason
         });
       }
-      const result = await this.#connection.sendRequest(
-        CORE_METHODS.DISCONNECT,
-        reason ? { reason } : void 0
-      );
+      const result = await this.#connection.sendRequest(CORE_METHODS.DISCONNECT, reason ? { reason } : void 0);
       resumeToken = result.resumeToken;
     } finally {
       for (const subscription of this.#subscriptions.values()) {
@@ -4428,10 +4529,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Created conversation and participant info
    */
   async createConversation(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_CREATE,
-      params ?? {}
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_CREATE, params ?? {});
   }
   /**
    * Get a conversation by ID with optional includes.
@@ -4441,10 +4539,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Conversation details with requested includes
    */
   async getConversation(conversationId, include) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_GET,
-      { conversationId, include }
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_GET, { conversationId, include });
   }
   /**
    * List conversations with optional filters.
@@ -4453,10 +4548,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Paginated list of conversations
    */
   async listConversations(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_LIST,
-      params ?? {}
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_LIST, params ?? {});
   }
   /**
    * Close a conversation.
@@ -4466,10 +4558,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The closed conversation
    */
   async closeConversation(conversationId, reason) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_CLOSE,
-      { conversationId, reason }
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_CLOSE, { conversationId, reason });
   }
   /**
    * Join an existing conversation.
@@ -4478,10 +4567,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Conversation, participant, and optional history
    */
   async joinConversation(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_JOIN,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_JOIN, params);
   }
   /**
    * Leave a conversation.
@@ -4491,10 +4577,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Leave confirmation with timestamp
    */
   async leaveConversation(conversationId, reason) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_LEAVE,
-      { conversationId, reason }
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_LEAVE, { conversationId, reason });
   }
   /**
    * Invite a participant to a conversation.
@@ -4503,10 +4586,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Invite result
    */
   async inviteToConversation(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_INVITE,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_INVITE, params);
   }
   /**
    * Record a turn (message) in a conversation.
@@ -4515,10 +4595,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The created turn
    */
   async recordTurn(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_TURN,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_TURN, params);
   }
   /**
    * List turns in a conversation with optional filters.
@@ -4527,10 +4604,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Paginated list of turns
    */
   async listTurns(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_TURNS_LIST,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_TURNS_LIST, params);
   }
   /**
    * Create a thread in a conversation.
@@ -4539,10 +4613,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The created thread
    */
   async createThread(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_THREAD_CREATE,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_THREAD_CREATE, params);
   }
   /**
    * List threads in a conversation.
@@ -4551,10 +4622,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Paginated list of threads
    */
   async listThreads(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_THREAD_LIST,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_THREAD_LIST, params);
   }
   /**
    * Get a summary of a conversation.
@@ -4563,10 +4631,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Generated summary with optional key points, decisions, and questions
    */
   async getConversationSummary(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_SUMMARY,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_SUMMARY, params);
   }
   /**
    * Replay turns from a conversation, optionally from a specific point.
@@ -4575,10 +4640,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Replayed turns with pagination info
    */
   async replayConversation(params) {
-    return this.#connection.sendRequest(
-      MAIL_METHODS.MAIL_REPLAY,
-      params
-    );
+    return this.#connection.sendRequest(MAIL_METHODS.MAIL_REPLAY, params);
   }
   /**
    * Send a message to an agent with mail context attached.
@@ -4625,10 +4687,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The created task
    */
   async createTask(params) {
-    return this.#connection.sendRequest(
-      TASK_METHODS.TASKS_CREATE,
-      params
-    );
+    return this.#connection.sendRequest(TASK_METHODS.TASKS_CREATE, params);
   }
   /**
    * Assign a task to an agent.
@@ -4638,10 +4697,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The updated task
    */
   async assignTask(taskId, agentId) {
-    return this.#connection.sendRequest(
-      TASK_METHODS.TASKS_ASSIGN,
-      { taskId, agentId }
-    );
+    return this.#connection.sendRequest(TASK_METHODS.TASKS_ASSIGN, { taskId, agentId });
   }
   /**
    * Update a task's status or fields.
@@ -4650,10 +4706,7 @@ var AgentConnection = class _AgentConnection {
    * @returns The updated task
    */
   async updateTask(params) {
-    return this.#connection.sendRequest(
-      TASK_METHODS.TASKS_UPDATE,
-      params
-    );
+    return this.#connection.sendRequest(TASK_METHODS.TASKS_UPDATE, params);
   }
   /**
    * List tasks with optional filters.
@@ -4662,10 +4715,7 @@ var AgentConnection = class _AgentConnection {
    * @returns Paginated list of tasks
    */
   async listTasks(params) {
-    return this.#connection.sendRequest(
-      TASK_METHODS.TASKS_LIST,
-      params ?? {}
-    );
+    return this.#connection.sendRequest(TASK_METHODS.TASKS_LIST, params ?? {});
   }
   // ===========================================================================
   // Internal
@@ -4677,17 +4727,21 @@ var AgentConnection = class _AgentConnection {
     switch (method) {
       case NOTIFICATION_METHODS.EVENT: {
         const eventParams = params;
-        const subscription = this.#subscriptions.get(eventParams.subscriptionId);
+        const subscription = this.#subscriptions.get(
+          eventParams.subscriptionId
+        );
         if (subscription) {
           subscription._pushEvent(eventParams);
         }
         break;
       }
-      case NOTIFICATION_METHODS.MESSAGE: {
+      case NOTIFICATION_METHODS.MESSAGE:
+      case NOTIFICATION_METHODS.SEND: {
         const messageParams = params;
+        const message = messageParams.message ?? messageParams;
         for (const handler of this.#messageHandlers) {
           try {
-            await handler(messageParams.message);
+            await handler(message);
           } catch (error) {
             console.error("MAP: Message handler error:", error);
           }
@@ -4780,7 +4834,11 @@ var AgentConnection = class _AgentConnection {
       try {
         await this.joinScope(scopeId);
       } catch (error) {
-        console.warn("MAP: Failed to restore scope membership:", scopeId, error);
+        console.warn(
+          "MAP: Failed to restore scope membership:",
+          scopeId,
+          error
+        );
       }
     }
   }