@multi-agent-protocol/sdk 0.0.5 → 0.0.7

package/dist/testing.d.cts

@@ -1,4 +1,4 @@
-import { P as ParticipantCapabilities, fp as SystemExposure, d as FederationRoutingConfig, S as Stream, cl 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, cs as ClientConnectionOptions, cr as ClientConnection, bZ as AgentsListRequestParams, ee as ScopesListRequestParams, p as SubscriptionFilter, eC as Subscription, e as EventType, bH as AgentConnectionOptions, O as AgentConnection } from './index-DMcRbXOS.cjs';
+import { P as ParticipantCapabilities, fE as SystemExposure, d as FederationRoutingConfig, S as Stream, cw 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, cD as ClientConnectionOptions, cC as ClientConnection, c1 as AgentsListRequestParams, eq as ScopesListRequestParams, p as SubscriptionFilter, eQ as Subscription, e as EventType, bL as AgentConnectionOptions, W as AgentConnection } from './index-BQXp4_rd.cjs';
 import 'events';
 
 /**

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { P as ParticipantCapabilities, fp as SystemExposure, d as FederationRoutingConfig, S as Stream, cl 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, cs as ClientConnectionOptions, cr as ClientConnection, bZ as AgentsListRequestParams, ee as ScopesListRequestParams, p as SubscriptionFilter, eC as Subscription, e as EventType, bH as AgentConnectionOptions, O as AgentConnection } from './index-DMcRbXOS.js';
+import { P as ParticipantCapabilities, fE as SystemExposure, d as FederationRoutingConfig, S as Stream, cw 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, cD as ClientConnectionOptions, cC as ClientConnection, c1 as AgentsListRequestParams, eq as ScopesListRequestParams, p as SubscriptionFilter, eQ as Subscription, e as EventType, bL as AgentConnectionOptions, W as AgentConnection } from './index-BQXp4_rd.js';
 import 'events';
 
 /**

package/dist/testing.js

@@ -1,6 +1,86 @@
+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) {
   return typeof message === "object" && message !== null && "jsonrpc" in message && message.jsonrpc === "2.0" && "id" in message && "method" in message;
@@ -110,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"
 };
@@ -120,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,
@@ -133,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,
@@ -272,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)
   // ==========================================================================
@@ -1851,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;
@@ -2043,6 +2145,7 @@ var TestServer = class {
 };
 
 // src/stream/index.ts
+init_agentic_mesh();
 function websocketStream(ws) {
   const messageQueue = [];
   let messageResolver = null;
@@ -3113,6 +3216,33 @@ var ACPStreamConnection = class extends EventEmitter {
     });
   }
   // ===========================================================================
+  // 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
   // ===========================================================================
   /**
@@ -3151,6 +3281,8 @@ var ClientConnection = class _ClientConnection {
   #connected = false;
   #lastConnectOptions;
   #isReconnecting = false;
+  #lastResumeToken;
+  #onTokenExpiring;
   constructor(stream, options = {}) {
     this.#connection = new BaseConnection(stream, options);
     this.#options = options;
@@ -3216,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 = {
@@ -3236,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
@@ -3254,6 +3569,9 @@ 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();
@@ -4138,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
   // ===========================================================================
@@ -4174,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