@multi-agent-protocol/sdk 0.1.9 → 0.1.11

package/dist/server.cjs

@@ -4639,6 +4639,11 @@ var InMemoryAgentStore = class {
         );
         if (!match) continue;
       }
+      if (filter?.persistentId !== void 0) {
+        if (agent.persistentIdentity?.persistentId !== filter.persistentId) {
+          continue;
+        }
+      }
       results.push({ ...agent });
     }
     return results;
@@ -4767,7 +4772,8 @@ var AgentRegistryImpl = class {
       registeredAt: now,
       lastStateChange: now,
       capabilities: params.capabilities,
-      capabilityDescriptor: params.capabilityDescriptor
+      capabilityDescriptor: params.capabilityDescriptor,
+      persistentIdentity: params.persistentIdentity
     };
     this.store.save(agent);
     this.eventBus.emit({
@@ -4862,6 +4868,38 @@ var AgentRegistryImpl = class {
     });
     return updatedAgent;
   }
+  /**
+   * Resume an orphaned agent under a new session.
+   * Updates sessionId, resets state to idle, optionally merges metadata,
+   * and optionally updates the persistent identity (e.g., with fresh proof).
+   * Emits agent.resumed event.
+   */
+  resume(id, newSessionId, metadata, persistentIdentity) {
+    const agent = this.store.get(id);
+    if (!agent) {
+      throw new AgentNotFoundError(id);
+    }
+    const previousSessionId = agent.sessionId;
+    const now = Date.now();
+    const resumedAgent = {
+      ...agent,
+      sessionId: newSessionId,
+      state: "idle",
+      lastStateChange: now,
+      metadata: metadata ? { ...agent.metadata, ...metadata } : agent.metadata,
+      ...persistentIdentity && { persistentIdentity }
+    };
+    this.store.save(resumedAgent);
+    this.eventBus.emit({
+      type: "agent.resumed",
+      data: {
+        agent: resumedAgent,
+        previousSessionId
+      },
+      source: { agentId: id, sessionId: newSessionId }
+    });
+    return resumedAgent;
+  }
   /**
    * Unregister all agents for a session.
    * Used for cleanup when a session disconnects.
@@ -5168,17 +5206,137 @@ var MAPRequestError = class _MAPRequestError extends Error {
 
 // src/server/agents/handlers.ts
 function createAgentHandlers(options) {
-  const { agents, sessions, authManager } = options;
+  const { agents, sessions, authManager, eventBus, identityVerifier, uniqueIdentity } = options;
   return {
     "map/agents/register": async (params, ctx) => {
-      const { name, role, metadata, capabilities, capabilityDescriptor } = params;
+      const { name, role, metadata, capabilities, capabilityDescriptor, persistentIdentity, resumePersistentIdentity } = params;
+      if (!name || typeof name !== "string" || name.trim() === "") {
+        throw new Error("Agent name is required");
+      }
+      let resolvedIdentity = persistentIdentity;
+      if (!resolvedIdentity) {
+        const tokenData = ctx.session.providers?.["agent-iam"]?.providerData;
+        if (tokenData?.persistentIdentity) {
+          const pi = tokenData.persistentIdentity;
+          if (pi.persistentId && pi.identityType) {
+            resolvedIdentity = {
+              persistentId: pi.persistentId,
+              identityType: pi.identityType,
+              publicKey: pi.publicKey,
+              publicKeyJwk: pi.publicKeyJwk,
+              // Token stores proof and challenge as separate strings;
+              // map to AgentIdentityProof object
+              proof: pi.proof && pi.challenge ? {
+                challenge: pi.challenge,
+                signature: pi.proof,
+                provenAt: (/* @__PURE__ */ new Date()).toISOString()
+              } : void 0,
+              verificationStatus: "auth-derived"
+            };
+          }
+        }
+      }
+      if (resolvedIdentity) {
+        if (!resolvedIdentity.persistentId || typeof resolvedIdentity.persistentId !== "string" || resolvedIdentity.persistentId.trim() === "") {
+          throw new Error("persistentIdentity.persistentId must be a non-empty string");
+        }
+        if (!resolvedIdentity.identityType || typeof resolvedIdentity.identityType !== "string") {
+          throw new Error("persistentIdentity.identityType is required");
+        }
+      }
+      if (resolvedIdentity && identityVerifier) {
+        const verificationContext = {
+          sessionId: ctx.session.id,
+          agentName: name,
+          isResumption: !!resumePersistentIdentity
+        };
+        try {
+          const status = await identityVerifier.verify(resolvedIdentity, verificationContext);
+          if (status) {
+            resolvedIdentity = { ...resolvedIdentity, verificationStatus: status };
+          }
+        } catch (verifyError) {
+          resolvedIdentity = { ...resolvedIdentity, verificationStatus: "unverified" };
+          if (eventBus) {
+            eventBus.emit({
+              type: "agent.identity.verification.failed",
+              data: {
+                persistentId: resolvedIdentity.persistentId,
+                identityType: resolvedIdentity.identityType,
+                error: verifyError instanceof Error ? verifyError.message : String(verifyError)
+              },
+              source: { sessionId: ctx.session.id }
+            });
+          }
+        }
+      }
+      const persistentId = resolvedIdentity?.persistentId;
+      if (persistentId) {
+        const existingAgents = agents.list({ persistentId });
+        const activeAgents = existingAgents.filter((a) => a.state !== "stopped");
+        if (resumePersistentIdentity && activeAgents.length > 0) {
+          const sorted = activeAgents.sort((a, b) => b.lastStateChange - a.lastStateChange);
+          const resumeTarget = sorted[0];
+          try {
+            if (sessions) {
+              try {
+                if (resumeTarget.sessionId !== ctx.session.id) {
+                  sessions.removeAgent(resumeTarget.sessionId, resumeTarget.id);
+                }
+              } catch {
+              }
+              sessions.addAgent(ctx.session.id, resumeTarget.id);
+            } else {
+              ctx.session.agentIds.push(resumeTarget.id);
+            }
+            const previousSessionId = resumeTarget.sessionId;
+            const resumedAgent = agents.resume(
+              resumeTarget.id,
+              ctx.session.id,
+              {
+                ...metadata || {},
+                resumedAt: Date.now(),
+                resumedFromSession: previousSessionId
+              },
+              resolvedIdentity
+            );
+            return {
+              agent: {
+                id: resumedAgent.id,
+                name: resumedAgent.name,
+                role: resumedAgent.role,
+                state: resumedAgent.state,
+                metadata: resumedAgent.metadata,
+                capabilities: resumedAgent.capabilities,
+                capabilityDescriptor: resumedAgent.capabilityDescriptor,
+                persistentIdentity: resumedAgent.persistentIdentity,
+                visibility: "public"
+              },
+              resumed: true,
+              resumedFrom: {
+                previousSessionId
+              }
+            };
+          } catch (resumeError) {
+            if (resumeError instanceof AgentNotFoundError) ; else {
+              throw resumeError;
+            }
+          }
+        }
+        if (uniqueIdentity && activeAgents.length > 0) {
+          throw new Error(
+            `An active agent with persistentId "${persistentId}" already exists. Use resumePersistentIdentity: true to resume it, or unregister the existing agent first.`
+          );
+        }
+      }
       const registeredAgent = agents.register({
         name,
         role,
         metadata,
         sessionId: ctx.session.id,
         capabilities,
-        capabilityDescriptor
+        capabilityDescriptor,
+        persistentIdentity: resolvedIdentity
       });
       if (sessions) {
         sessions.addAgent(ctx.session.id, registeredAgent.id);
@@ -5194,6 +5352,7 @@ function createAgentHandlers(options) {
           metadata: registeredAgent.metadata,
           capabilities: registeredAgent.capabilities,
           capabilityDescriptor: registeredAgent.capabilityDescriptor,
+          persistentIdentity: registeredAgent.persistentIdentity,
           visibility: "public"
         }
       };
@@ -5230,6 +5389,7 @@ function createAgentHandlers(options) {
           metadata: a.metadata,
           capabilities: a.capabilities,
           capabilityDescriptor: a.capabilityDescriptor,
+          persistentIdentity: a.persistentIdentity,
           visibility: "public"
         }))
       };
@@ -5249,6 +5409,7 @@ function createAgentHandlers(options) {
           metadata: agent.metadata,
           capabilities: agent.capabilities,
           capabilityDescriptor: agent.capabilityDescriptor,
+          persistentIdentity: agent.persistentIdentity,
           visibility: "public"
         }
       };
@@ -5274,6 +5435,7 @@ function createAgentHandlers(options) {
           metadata: agent.metadata,
           capabilities: agent.capabilities,
           capabilityDescriptor: agent.capabilityDescriptor,
+          persistentIdentity: agent.persistentIdentity,
           visibility: "public"
         }
       };
@@ -5323,7 +5485,8 @@ function createAgentHandlers(options) {
           parentId: parent
         },
         sessionId: ctx.session.id,
-        capabilityDescriptor
+        capabilityDescriptor,
+        persistentIdentity: parentAgent.persistentIdentity
       });
       if (sessions) {
         sessions.addAgent(ctx.session.id, childAgent.id);
@@ -5356,6 +5519,7 @@ function createAgentHandlers(options) {
           state: childAgent.state,
           metadata: childAgent.metadata,
           capabilityDescriptor: childAgent.capabilityDescriptor,
+          persistentIdentity: childAgent.persistentIdentity,
           visibility: "public"
         }
       };
@@ -7583,94 +7747,113 @@ function toScope(scopeId) {
 }
 
 // src/server/messages/handlers.ts
+function resolveRouteTarget(to) {
+  if (typeof to === "string") {
+    return { type: "string", value: to };
+  }
+  if (Array.isArray(to)) {
+    return to.map((item) => resolveRouteTarget(item));
+  }
+  if (to && typeof to === "object") {
+    const obj = to;
+    if (typeof obj.agent === "string" && !obj.system) {
+      return { type: "agent", id: obj.agent };
+    }
+    if (Array.isArray(obj.agents)) {
+      return { type: "agents", ids: obj.agents };
+    }
+    if (typeof obj.scope === "string") {
+      return { type: "scope", id: obj.scope };
+    }
+    if (obj.broadcast === true) {
+      return { type: "broadcast" };
+    }
+    if (typeof obj.role === "string") {
+      if (typeof obj.within === "string") {
+        return { type: "scope", id: obj.within };
+      }
+      return { type: "broadcast" };
+    }
+    if (obj.system === true) {
+      return { type: "broadcast" };
+    }
+    if (typeof obj.system === "string" && typeof obj.agent === "string") {
+      return { type: "agent", id: obj.agent };
+    }
+    if (typeof obj.participant === "string") {
+      return { type: "agent", id: obj.participant };
+    }
+    if (obj.participants === "all" || obj.participants === "agents") {
+      return { type: "broadcast" };
+    }
+    if (obj.parent || obj.children || obj.ancestors || obj.descendants || obj.siblings) {
+      return { type: "broadcast" };
+    }
+  }
+  return { type: "string", value: String(to) };
+}
 function createMessageHandlers(options) {
   const { messages, scopes, agents, turns } = options;
+  function sendToAgent(from, to, params) {
+    return messages.sendToAgent({
+      from,
+      to,
+      payload: params.payload,
+      replyTo: params.replyTo,
+      priority: params.priority,
+      ttlMs: params.ttlMs,
+      messageType: params.messageType
+    });
+  }
+  function sendToScope(from, scopeId, params) {
+    return messages.sendToScope({
+      from,
+      scopeId,
+      payload: params.payload,
+      excludeSender: true,
+      messageType: params.messageType
+    });
+  }
+  function resolveStringAddress(from, to, params) {
+    if (isAddress(to)) {
+      if (isScopeAddress(to)) {
+        const message3 = sendToScope(from, extractId(to), params);
+        return { messageId: message3.id };
+      } else {
+        const message3 = sendToAgent(from, extractId(to), params);
+        return { messageId: message3.id };
+      }
+    }
+    const scope = scopes.get(to);
+    const agent = agents?.get(to);
+    if (scope && agent) {
+      throw new Error(
+        `Ambiguous address "${to}" matches both an agent and a scope. Use "agent:${to}" or "scope:${to}" to disambiguate.`
+      );
+    }
+    if (scope) {
+      const message3 = sendToScope(from, to, params);
+      return { messageId: message3.id };
+    }
+    const message2 = sendToAgent(from, to, params);
+    return { messageId: message2.id };
+  }
   return {
     "map/send": async (params, ctx) => {
-      const { to, payload, replyTo, priority, ttlMs, messageType, meta } = params;
+      const sendParams = params;
+      const { to: rawTo, meta } = sendParams;
       const from = ctx.session.agentIds[0] ?? ctx.session.id;
+      const target = resolveRouteTarget(rawTo);
       let result;
-      if (Array.isArray(to)) {
+      if (Array.isArray(target)) {
         const results = [];
-        for (const recipient of to) {
-          if (isScopeAddress(recipient)) {
-            const scopeId = extractId(recipient);
-            const message2 = messages.sendToScope({
-              from,
-              scopeId,
-              payload,
-              excludeSender: true,
-              messageType
-            });
-            results.push(message2.id);
-          } else {
-            const agentId = isAgentAddress(recipient) ? extractId(recipient) : recipient;
-            const message2 = messages.sendToAgent({
-              from,
-              to: agentId,
-              payload,
-              replyTo,
-              priority,
-              ttlMs,
-              messageType
-            });
-            results.push(message2.id);
-          }
+        for (const t of target) {
+          const { messageId } = routeSingle(from, t, sendParams);
+          results.push(messageId);
         }
         result = { messageId: results[0], delivered: results };
-      } else if (isAddress(to)) {
-        if (isScopeAddress(to)) {
-          const scopeId = extractId(to);
-          const message2 = messages.sendToScope({
-            from,
-            scopeId,
-            payload,
-            excludeSender: true,
-            messageType
-          });
-          result = { messageId: message2.id };
-        } else {
-          const agentId = extractId(to);
-          const message2 = messages.sendToAgent({
-            from,
-            to: agentId,
-            payload,
-            replyTo,
-            priority,
-            ttlMs,
-            messageType
-          });
-          result = { messageId: message2.id };
-        }
       } else {
-        const scope = scopes.get(to);
-        const agent = agents?.get(to);
-        if (scope && agent) {
-          throw new Error(
-            `Ambiguous address "${to}" matches both an agent and a scope. Use "agent:${to}" or "scope:${to}" to disambiguate.`
-          );
-        }
-        if (scope) {
-          const message2 = messages.sendToScope({
-            from,
-            scopeId: to,
-            payload,
-            excludeSender: true,
-            messageType
-          });
-          result = { messageId: message2.id };
-        } else {
-          const message2 = messages.sendToAgent({
-            from,
-            to,
-            payload,
-            replyTo,
-            priority,
-            ttlMs,
-            messageType
-          });
-          result = { messageId: message2.id };
-        }
+        result = routeSingle(from, target, sendParams);
       }
       if (turns && meta?.mail?.conversationId) {
         try {
@@ -7678,7 +7861,7 @@ function createMessageHandlers(options) {
             conversationId: meta.mail.conversationId,
             participant: from,
             contentType: "data",
-            content: payload,
+            content: sendParams.payload,
             messageId: result.messageId,
             threadId: meta.mail.threadId,
             inReplyTo: meta.mail.inReplyTo,
@@ -7703,6 +7886,38 @@ function createMessageHandlers(options) {
       return { messageId: message2.id };
     }
   };
+  function routeSingle(from, target, params) {
+    switch (target.type) {
+      case "agent": {
+        const message2 = sendToAgent(from, target.id, params);
+        return { messageId: message2.id };
+      }
+      case "agents": {
+        const results = [];
+        for (const agentId of target.ids) {
+          const message2 = sendToAgent(from, agentId, params);
+          results.push(message2.id);
+        }
+        return { messageId: results[0] };
+      }
+      case "scope": {
+        const message2 = sendToScope(from, target.id, params);
+        return { messageId: message2.id };
+      }
+      case "broadcast": {
+        const message2 = messages.sendToAgent({
+          from,
+          to: "*",
+          payload: params.payload,
+          messageType: params.messageType
+        });
+        return { messageId: message2.id };
+      }
+      case "string": {
+        return resolveStringAddress(from, target.value, params);
+      }
+    }
+  }
 }
 
 // src/server/mail/stores/in-memory-conversation.ts
@@ -9977,6 +10192,9 @@ function createCredentialHandlers(options) {
             type: "credential.denied",
             data: {
               agentId: token.agentId,
+              ...token.persistentIdentity?.persistentId && {
+                persistentId: token.persistentIdentity.persistentId
+              },
               scope,
               resource,
               reason: check2.error
@@ -9992,6 +10210,9 @@ function createCredentialHandlers(options) {
           type: "credential.issued",
           data: {
             agentId: token.agentId,
+            ...token.persistentIdentity?.persistentId && {
+              persistentId: token.persistentIdentity.persistentId
+            },
             scope,
             resource,
             credentialType: credential.credentialType,
@@ -10919,6 +11140,7 @@ var AgentIAMProvider = class {
     const principal = {
       id: token.agentId,
       issuer: token.identity?.systemId ?? "agent-iam",
+      persistentId: token.persistentIdentity?.persistentId,
       claims: {
         scopes: token.scopes,
         delegatable: token.delegatable,
@@ -10947,7 +11169,8 @@ var AgentIAMProvider = class {
       requestedScopes: spawnRequest.requestedScopes ?? parentToken.scopes,
       delegatable: true,
       ttlMinutes: spawnRequest.ttlMinutes,
-      inheritIdentity: spawnRequest.inheritIdentity ?? true
+      inheritIdentity: spawnRequest.inheritIdentity ?? true,
+      inheritPersistentIdentity: spawnRequest.inheritIdentity ?? true
     });
     const serialized = this.#tokenService.serialize(childToken);
     return {
@@ -11044,6 +11267,7 @@ var AgentIAMFederationGateway = class {
     const principal = {
       id: `federated:${sourceSystemId}:${deserializedToken.agentId}`,
       issuer: sourceSystemId,
+      persistentId: deserializedToken.persistentIdentity?.persistentId,
       claims: {
         scopes: translatedScopes,
         federatedFrom: sourceSystemId,
@@ -11112,7 +11336,8 @@ var AgentIAMFederationGateway = class {
       requestedScopes: translatedScopes,
       delegatable: false,
       ttlMinutes: this.#federatedTTL,
-      inheritIdentity: true
+      inheritIdentity: true,
+      inheritPersistentIdentity: true
     });
     const withFederation = {
       ...delegated,
@@ -12837,6 +13062,13 @@ var FederatedAgentRegistry = class {
     }
     return unregisteredIds;
   }
+  /**
+   * Resume an orphaned agent under a new session.
+   * Delegates to the local registry.
+   */
+  resume(id, newSessionId, metadata, persistentIdentity) {
+    return this.local.resume(id, newSessionId, metadata, persistentIdentity);
+  }
   /**
    * Check if an agent is remote.
    */