@mastra/client-js 1.17.2-alpha.3 → 1.18.0-alpha.11

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './client.js';
 export * from './types.js';
 export * from './tools.js';
 export type { ChannelPlatformInfo, ChannelInstallationInfo, ChannelConnectOAuth, ChannelConnectDeepLink, ChannelConnectImmediate, ChannelConnectResult, } from './resources/channels.js';
+export type { AgentCardSignatureKeyProviderInput, AgentCardVerificationKey, GetAgentCardOptions, VerifyAgentCardSignatureOptions, } from './resources/a2a.js';
 export { RequestContext } from '@mastra/core/request-context';
 export type { UIMessageWithMetadata } from '@mastra/core/agent';
 export type { Body, Client, ClientMethod, ClientPath, ClientRequest, ClientResponse, ClientResponseKind, ClientRoute, PathParams, QueryParams, RouteKey, RouteRequest, RouteResponse, RouteResponseType, RouteTypes, } from './route-types.generated.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kCAAkC,EAClC,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -6,6 +6,8 @@ import { RequestContext } from '@mastra/core/request-context';
 export { RequestContext } from '@mastra/core/request-context';
 import { zodToJsonSchema as zodToJsonSchema$1 } from '@mastra/schema-compat/zod-to-json';
 import { MastraA2AError } from '@mastra/core/a2a';
+import canonicalize from 'canonicalize';
+import { base64url, decodeProtectedHeader, compactVerify, importX509, importSPKI, importJWK } from 'jose';
 
 // src/resources/agent.ts
 function normalizeRoutePath(path) {
@@ -464,8 +466,14 @@ var Agent = class extends BaseResource {
     const queryParams = new URLSearchParams();
     if (params?.page !== void 0) queryParams.set("page", String(params.page));
     if (params?.perPage !== void 0) queryParams.set("perPage", String(params.perPage));
-    if (params?.orderBy) queryParams.set("orderBy", params.orderBy);
-    if (params?.sortDirection) queryParams.set("sortDirection", params.sortDirection);
+    if (params?.orderBy) {
+      if (params.orderBy.field) {
+        queryParams.set("orderBy[field]", params.orderBy.field);
+      }
+      if (params.orderBy.direction) {
+        queryParams.set("orderBy[direction]", params.orderBy.direction);
+      }
+    }
     const queryString = queryParams.toString();
     const contextString = requestContextQueryString(requestContext);
     return this.request(
@@ -1639,6 +1647,43 @@ var Agent = class extends BaseResource {
     };
     return streamResponse;
   }
+  /**
+   * Resumes a suspended agent stream until idle with custom resume data.
+   * Used to continue execution after a suspension point (e.g., workflow suspend within an agent).
+   */
+  async resumeStreamUntilIdle(resumeData, options) {
+    const processedParams = {
+      ...options,
+      resumeData,
+      requestContext: parseClientRequestContext(options.requestContext),
+      clientTools: processClientTools(options.clientTools),
+      structuredOutput: options.structuredOutput ? {
+        ...options.structuredOutput,
+        schema: standardSchemaToJSONSchema(toStandardSchema(options.structuredOutput.schema))
+      } : void 0
+    };
+    let readableController;
+    const readable = new ReadableStream({
+      start(controller) {
+        readableController = controller;
+      }
+    });
+    const response = await this.processStreamResponse(processedParams, readableController, "resume-stream-until-idle");
+    const streamResponse = new Response(readable, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+    streamResponse.processDataStream = async ({
+      onChunk
+    }) => {
+      await processMastraStream({
+        stream: streamResponse.body,
+        onChunk
+      });
+    };
+    return streamResponse;
+  }
   /**
    * Approves a pending tool call and returns the complete response (non-streaming).
    * Used when `requireToolApproval` is enabled with generate() to allow the agent to proceed.
@@ -1860,8 +1905,22 @@ var MemoryThread = class extends BaseResource {
   /**
    * Builds the query string for agentId (if provided)
    */
-  getAgentIdQueryParam(prefix = "?") {
-    return this.agentId ? `${prefix}agentId=${this.agentId}` : "";
+  getAgentIdQueryParam(prefix = "?", overrideAgentId) {
+    const agentId = overrideAgentId ?? this.agentId;
+    return agentId ? `${prefix}agentId=${agentId}` : "";
+  }
+  /**
+   * Resolves the agentId to use for a write request. Prefers the per-call value, falls back
+   * to the constructor value, and throws if neither is set.
+   */
+  requireAgentId(perCallAgentId, methodName) {
+    const agentId = perCallAgentId ?? this.agentId;
+    if (!agentId) {
+      throw new Error(
+        `MemoryThread.${methodName}() requires an agentId. Pass it via getMemoryThread({ threadId, agentId }) or as a parameter to ${methodName}().`
+      );
+    }
+    return agentId;
   }
   /**
    * Retrieves the memory thread details
@@ -1875,25 +1934,30 @@ var MemoryThread = class extends BaseResource {
   }
   /**
    * Updates the memory thread properties
-   * @param params - Update parameters including title, metadata, and optional request context
+   * @param params - Update parameters including title, metadata, and optional request context.
+   *                 `agentId` is required by the server; pass it here if not supplied on the constructor.
    * @returns Promise containing updated thread details
    */
   update(params) {
-    const agentIdParam = this.getAgentIdQueryParam("?");
-    const contextParam = requestContextQueryString(params.requestContext, agentIdParam ? "&" : "?");
+    const agentId = this.requireAgentId(params.agentId, "update");
+    const { agentId: _omitAgentId, requestContext, ...body } = params;
+    const agentIdParam = `?agentId=${agentId}`;
+    const contextParam = requestContextQueryString(requestContext, "&");
     return this.request(`/memory/threads/${this.threadId}${agentIdParam}${contextParam}`, {
       method: "PATCH",
-      body: params
+      body
     });
   }
   /**
    * Deletes the memory thread
-   * @param requestContext - Optional request context to pass as query parameter
+   * @param opts - Optional `agentId` (required by the server when not supplied on the constructor)
+   *               and request context.
    * @returns Promise containing deletion result
    */
-  delete(requestContext) {
-    const agentIdParam = this.getAgentIdQueryParam("?");
-    const contextParam = requestContextQueryString(requestContext, agentIdParam ? "&" : "?");
+  delete(opts = {}) {
+    const agentId = this.requireAgentId(opts.agentId, "delete");
+    const agentIdParam = `?agentId=${agentId}`;
+    const contextParam = requestContextQueryString(opts.requestContext, "&");
     return this.request(`/memory/threads/${this.threadId}${agentIdParam}${contextParam}`, {
       method: "DELETE"
     });
@@ -1923,37 +1987,46 @@ var MemoryThread = class extends BaseResource {
    * Deletes one or more messages from the thread
    * @param messageIds - Can be a single message ID (string), array of message IDs,
    *                     message object with id property, or array of message objects
-   * @param requestContext - Optional request context to pass as query parameter
+   * @param opts - Optional `agentId` (required by the server when not supplied on the constructor)
+   *               and request context. For backwards compatibility a `RequestContext` may also be
+   *               passed directly as the second argument.
    * @returns Promise containing deletion result
    */
-  deleteMessages(messageIds, requestContext) {
-    const queryParams = {};
-    if (this.agentId) queryParams.agentId = this.agentId;
-    const query = new URLSearchParams(queryParams);
-    const queryString = query.toString();
-    return this.request(
-      `/memory/messages/delete${queryString ? `?${queryString}` : ""}${requestContextQueryString(requestContext, queryString ? "&" : "?")}`,
-      {
-        method: "POST",
-        body: { messageIds }
-      }
-    );
+  deleteMessages(messageIds, opts = {}) {
+    const { agentId: explicitAgentId, requestContext } = normalizeWriteOpts(opts);
+    const agentId = this.requireAgentId(explicitAgentId, "deleteMessages");
+    const queryString = `agentId=${agentId}`;
+    return this.request(`/memory/messages/delete?${queryString}${requestContextQueryString(requestContext, "&")}`, {
+      method: "POST",
+      body: { messageIds }
+    });
   }
   /**
    * Clones the thread with all its messages to a new thread
-   * @param params - Clone parameters including optional new thread ID, title, metadata, and message filters
+   * @param params - Clone parameters including optional new thread ID, title, metadata, and message filters.
+   *                 `agentId` is required by the server; pass it here if not supplied on the constructor.
    * @returns Promise containing the cloned thread and copied messages
    */
   clone(params = {}) {
-    const { requestContext, ...body } = params;
-    const agentIdParam = this.getAgentIdQueryParam("?");
-    const contextParam = requestContextQueryString(requestContext, agentIdParam ? "&" : "?");
+    const agentId = this.requireAgentId(params.agentId, "clone");
+    const { agentId: _omitAgentId, requestContext, ...body } = params;
+    const agentIdParam = `?agentId=${agentId}`;
+    const contextParam = requestContextQueryString(requestContext, "&");
     return this.request(`/memory/threads/${this.threadId}/clone${agentIdParam}${contextParam}`, {
       method: "POST",
       body
     });
   }
 };
+function normalizeWriteOpts(opts) {
+  if (!opts || typeof opts !== "object") return {};
+  if ("agentId" in opts || "requestContext" in opts) {
+    const o = opts;
+    return { agentId: o.agentId, requestContext: o.requestContext };
+  }
+  if (Object.keys(opts).length === 0) return {};
+  return { requestContext: opts };
+}
 
 // src/resources/vector.ts
 var Vector = class extends BaseResource {
@@ -2774,6 +2847,102 @@ async function* processA2AStream(stream) {
     reader.releaseLock();
   }
 }
+var DEFAULT_AGENT_CARD_SIGNATURE_ALGORITHMS = [
+  "ES256",
+  "ES384",
+  "ES512",
+  "RS256",
+  "RS384",
+  "RS512",
+  "PS256",
+  "PS384",
+  "PS512"
+];
+function stripAgentCardSignatures(agentCard) {
+  const unsignedCard = structuredClone(agentCard);
+  delete unsignedCard.signatures;
+  return unsignedCard;
+}
+function isCryptoKey(value) {
+  const cryptoKeyConstructor = globalThis.CryptoKey;
+  return typeof cryptoKeyConstructor !== "undefined" && value instanceof cryptoKeyConstructor;
+}
+function isPem(value) {
+  return value.includes("-----BEGIN ");
+}
+function isCertificate(value) {
+  return value.includes("-----BEGIN CERTIFICATE-----");
+}
+async function importVerificationKey(key, algorithm) {
+  if (isCryptoKey(key) || key instanceof Uint8Array) {
+    return key;
+  }
+  if (key instanceof ArrayBuffer) {
+    return new Uint8Array(key);
+  }
+  if (typeof key === "string") {
+    if (algorithm.startsWith("HS")) {
+      return new TextEncoder().encode(key);
+    }
+    if (!isPem(key)) {
+      throw new Error("Expected a PEM-encoded public key or certificate string for Agent Card verification");
+    }
+    if (isCertificate(key)) {
+      return importX509(key, algorithm);
+    }
+    return importSPKI(key, algorithm);
+  }
+  return importJWK(key, algorithm);
+}
+async function verifyAgentCardSignatureIfPresent(agentCard, options) {
+  const signatures = agentCard.signatures ?? [];
+  if (signatures.length === 0) {
+    return agentCard;
+  }
+  const canonicalPayload = canonicalize(stripAgentCardSignatures(agentCard));
+  if (!canonicalPayload) {
+    throw new MastraClientError(200, "OK", "Failed to canonicalize A2A Agent Card for signature verification");
+  }
+  const allowedAlgorithms = options.algorithms ?? [...DEFAULT_AGENT_CARD_SIGNATURE_ALGORITHMS];
+  const encodedPayload = base64url.encode(canonicalPayload);
+  const verificationErrors = [];
+  for (const [index, signature] of signatures.entries()) {
+    try {
+      const compactJws = `${signature.protected}.${encodedPayload}.${signature.signature}`;
+      const protectedHeader = decodeProtectedHeader(compactJws);
+      if (typeof protectedHeader.alg !== "string") {
+        throw new Error('Agent Card signature is missing a protected "alg" header');
+      }
+      if (!allowedAlgorithms.includes(protectedHeader.alg)) {
+        throw new Error(`Agent Card signature algorithm "${protectedHeader.alg}" is not allowed`);
+      }
+      const verificationKey = await options.keyProvider({
+        agentCard,
+        signature,
+        protectedHeader,
+        alg: protectedHeader.alg,
+        kid: typeof protectedHeader.kid === "string" ? protectedHeader.kid : void 0,
+        jku: typeof protectedHeader.jku === "string" ? protectedHeader.jku : void 0,
+        index
+      });
+      if (!verificationKey) {
+        throw new Error("No verification key was provided for Agent Card signature verification");
+      }
+      const importedKey = await importVerificationKey(verificationKey, protectedHeader.alg);
+      await compactVerify(compactJws, importedKey, {
+        algorithms: allowedAlgorithms
+      });
+      return agentCard;
+    } catch (error) {
+      verificationErrors.push(error instanceof Error ? error.message : "Unknown verification failure");
+    }
+  }
+  throw new MastraClientError(
+    200,
+    "OK",
+    `A2A Agent Card signature verification failed: ${verificationErrors.join("; ")}`
+  );
+}
 
 // src/resources/a2a.ts
 function createA2AJsonRpcError(response) {
@@ -2816,16 +2985,21 @@ var A2A = class extends BaseResource {
   agentId;
   /**
    * Get the agent card with metadata about the agent.
+   * @param options - Optional Agent Card verification settings
    * @returns Promise containing the agent card information
    */
-  async getAgentCard() {
-    return this.request(`/.well-known/${this.agentId}/agent-card.json`);
+  async getAgentCard(options) {
+    const agentCard = await this.request(`/.well-known/${this.agentId}/agent-card.json`);
+    if (!options?.verifySignature) {
+      return agentCard;
+    }
+    return verifyAgentCardSignatureIfPresent(agentCard, options.verifySignature);
   }
   /**
    * @deprecated Use getAgentCard() instead.
    */
-  async getCard() {
-    return this.getAgentCard();
+  async getCard(options) {
+    return this.getAgentCard(options);
   }
   /**
    * Get the authenticated extended agent card.
@@ -3838,8 +4012,14 @@ var StoredAgent = class extends BaseResource {
     const queryParams = new URLSearchParams();
     if (params?.page !== void 0) queryParams.set("page", String(params.page));
     if (params?.perPage !== void 0) queryParams.set("perPage", String(params.perPage));
-    if (params?.orderBy) queryParams.set("orderBy", params.orderBy);
-    if (params?.sortDirection) queryParams.set("sortDirection", params.sortDirection);
+    if (params?.orderBy) {
+      if (params.orderBy.field) {
+        queryParams.set("orderBy[field]", params.orderBy.field);
+      }
+      if (params.orderBy.direction) {
+        queryParams.set("orderBy[direction]", params.orderBy.direction);
+      }
+    }
     const queryString = queryParams.toString();
     const contextString = requestContextQueryString(requestContext);
     return this.request(
@@ -3992,8 +4172,14 @@ var StoredPromptBlock = class extends BaseResource {
     const queryParams = new URLSearchParams();
     if (params?.page !== void 0) queryParams.set("page", String(params.page));
     if (params?.perPage !== void 0) queryParams.set("perPage", String(params.perPage));
-    if (params?.orderBy) queryParams.set("orderBy", params.orderBy);
-    if (params?.sortDirection) queryParams.set("sortDirection", params.sortDirection);
+    if (params?.orderBy) {
+      if (params.orderBy.field) {
+        queryParams.set("orderBy[field]", params.orderBy.field);
+      }
+      if (params.orderBy.direction) {
+        queryParams.set("orderBy[direction]", params.orderBy.direction);
+      }
+    }
     const queryString = queryParams.toString();
     const contextString = requestContextQueryString(requestContext, queryString ? "&" : "?");
     return this.request(
@@ -4194,8 +4380,14 @@ var StoredScorer = class extends BaseResource {
     const queryParams = new URLSearchParams();
     if (params?.page !== void 0) queryParams.set("page", String(params.page));
     if (params?.perPage !== void 0) queryParams.set("perPage", String(params.perPage));
-    if (params?.orderBy) queryParams.set("orderBy", params.orderBy);
-    if (params?.sortDirection) queryParams.set("sortDirection", params.sortDirection);
+    if (params?.orderBy) {
+      if (params.orderBy.field) {
+        queryParams.set("orderBy[field]", params.orderBy.field);
+      }
+      if (params.orderBy.direction) {
+        queryParams.set("orderBy[direction]", params.orderBy.direction);
+      }
+    }
     const queryString = queryParams.toString();
     const contextString = requestContextQueryString(requestContext);
     return this.request(
@@ -4871,8 +5063,14 @@ var MastraClient = class extends BaseResource {
     if (params.agentId) queryParams.set("agentId", params.agentId);
     if (params.page !== void 0) queryParams.set("page", params.page.toString());
     if (params.perPage !== void 0) queryParams.set("perPage", params.perPage.toString());
-    if (params.orderBy) queryParams.set("orderBy", params.orderBy);
-    if (params.sortDirection) queryParams.set("sortDirection", params.sortDirection);
+    if (params.orderBy) {
+      if (params.orderBy.field) {
+        queryParams.set("orderBy[field]", params.orderBy.field);
+      }
+      if (params.orderBy.direction) {
+        queryParams.set("orderBy[direction]", params.orderBy.direction);
+      }
+    }
     const queryString = queryParams.toString();
     const response = await this.request(
       `/memory/threads${queryString ? `?${queryString}` : ""}${requestContextQueryString(params.requestContext, queryString ? "&" : "?")}`
@@ -4937,13 +5135,13 @@ var MastraClient = class extends BaseResource {
     }
     return this.request(url);
   }
-  deleteThread(threadId, opts = {}) {
-    let url = "";
-    if (opts.agentId) {
-      url = `/memory/threads/${threadId}?agentId=${opts.agentId}${requestContextQueryString(opts.requestContext, "&")}`;
-    } else if (opts.networkId) {
-      url = `/memory/network/threads/${threadId}?networkId=${opts.networkId}${requestContextQueryString(opts.requestContext, "&")}`;
+  deleteThread(threadId, opts) {
+    if (!opts || !!opts.agentId === !!opts.networkId) {
+      throw new Error(
+        "MastraClient.deleteThread() requires exactly one of agentId or networkId. The server cannot resolve which memory store owns the thread without one, and passing both is ambiguous."
+      );
     }
+    const url = opts.agentId ? `/memory/threads/${threadId}?agentId=${opts.agentId}${requestContextQueryString(opts.requestContext, "&")}` : `/memory/network/threads/${threadId}?networkId=${opts.networkId}${requestContextQueryString(opts.requestContext, "&")}`;
     return this.request(url, { method: "DELETE" });
   }
   /**
@@ -6213,6 +6411,8 @@ var MastraClient = class extends BaseResource {
     if (params.runId) searchParams.set("runId", params.runId);
     if (params.threadId) searchParams.set("threadId", params.threadId);
     if (params.resourceId) searchParams.set("resourceId", params.resourceId);
+    if (params.toolName) searchParams.set("toolName", params.toolName);
+    if (params.toolCallId) searchParams.set("toolCallId", params.toolCallId);
     if (params.fromDate) searchParams.set("fromDate", params.fromDate.toISOString());
     if (params.toDate) searchParams.set("toDate", params.toDate.toISOString());
     if (params.dateFilterBy) searchParams.set("dateFilterBy", params.dateFilterBy);