@mastra/client-js 1.39.0-alpha.13 → 1.39.0-alpha.14

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/client-js
 
+## 1.39.0-alpha.14
+
+### Patch Changes
+
+- Added the `skill_resolution` span type to the generated route types. ([#21232](https://github.com/mastra-ai/mastra/pull/21232))
+
+- Updated dependencies [[`210cb7a`](https://github.com/mastra-ai/mastra/commit/210cb7a167998c7bbf72cb3b93e6eb0563330239), [`5f798b3`](https://github.com/mastra-ai/mastra/commit/5f798b3362e9bdf4d690f85245606e146eef60b9), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`25ca73d`](https://github.com/mastra-ai/mastra/commit/25ca73d25dee7ce9f0ca72939e3a505c4db7257e), [`e1cead1`](https://github.com/mastra-ai/mastra/commit/e1cead17b5f3653cf00d2f90cc19b113119c02ba), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437)]:
+  - @mastra/core@1.58.0-alpha.14
+
 ## 1.39.0-alpha.13
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.39.0-alpha.13"
+  version: "1.39.0-alpha.14"
 ---
 
 ## When to use
@@ -20,14 +20,17 @@ Read the individual reference documents for detailed explanations and code examp
 - [Editor](references/docs-editor-overview.md) - Let collaborators update an agent in Studio, test their changes, and publish without editing code.
 - [Schedules](references/docs-long-running-agents-schedules.md) - Run an agent on a cron schedule to deliver a recurring prompt, with optional thread delivery and lifecycle hooks.
 - [Signals](references/docs-long-running-agents-signals.md) - Learn how to send real-time messages and context into a Mastra agent thread.
-- [Auth0](references/docs-server-auth-auth0.md) - Documentation for the @mastra/auth-auth0 package, which authenticates Mastra applications using Auth0 authentication.
-- [Clerk](references/docs-server-auth-clerk.md) - Documentation for the `@mastra/auth-clerk` package, which authenticates Mastra applications using Clerk authentication.
-- [Firebase](references/docs-server-auth-firebase.md) - Documentation for the `@mastra/auth-firebase` package, which authenticates Mastra applications using Firebase Authentication.
 - [JSON Web Token](references/docs-server-auth-jwt.md) - Documentation for JSON Web Token usage inside Mastra.
-- [Supabase](references/docs-server-auth-supabase.md) - Documentation for the `@mastra/auth-supabase` package, which authenticates Mastra applications using Supabase Auth.
-- [WorkOS](references/docs-server-auth-workos.md) - Documentation for the `@mastra/auth-workos` package, which authenticates Mastra applications using WorkOS authentication.
 - [Mastra client SDK](references/docs-server-mastra-client.md) - Learn how to set up and use the Mastra Client SDK
 
+### Integrations
+
+- [Auth0](references/integrations-auth-auth0.md) - Documentation for the @mastra/auth-auth0 package, which authenticates Mastra applications using Auth0 authentication.
+- [Clerk](references/integrations-auth-clerk.md) - Documentation for the `@mastra/auth-clerk` package, which authenticates Mastra applications using Clerk authentication.
+- [Firebase](references/integrations-auth-firebase.md) - Documentation for the `@mastra/auth-firebase` package, which authenticates Mastra applications using Firebase Authentication.
+- [Supabase](references/integrations-auth-supabase.md) - Documentation for the `@mastra/auth-supabase` package, which authenticates Mastra applications using Supabase Auth.
+- [WorkOS](references/integrations-auth-workos.md) - Documentation for the `@mastra/auth-workos` package, which authenticates Mastra applications using WorkOS authentication.
+
 ### Reference
 
 - [Reference: toAISdkMessages()](references/reference-ai-sdk-to-ai-sdk-messages.md) - API reference for toAISdkMessages(), a function to convert Mastra messages to AI SDK UI messages for AI SDK v5 or v6.
@@ -47,6 +50,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Vectors API](references/reference-client-js-vectors.md) - Learn how to work with vector embeddings for semantic search and similarity matching in Mastra using the client-js SDK.
 - [Reference: Workflows API](references/reference-client-js-workflows.md) - Learn how to interact with and execute automated workflows in Mastra using the client-js SDK.
 - [Reference: Versioning](references/reference-editor-versioning.md) - Reference for Editor version lifecycle, selection, sub-agent propagation, source behavior, REST endpoints, and SDK methods.
+- [Client SDK](references/reference-migrations-upgrade-to-v1-client.md) - Learn how to migrate client SDK changes when upgrading to v1.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.39.0-alpha.13",
+  "version": "1.39.0-alpha.14",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-long-running-agents-signals.md

@@ -147,7 +147,7 @@ Use XML-safe `tagName` and attribute names. They can contain letters, numbers, s
 
 #### Storage support
 
-Notification inbox storage is available in the storage adapters that support richer memory and signal workflows: [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). These adapters expose notification records through `getStore('notifications')`.
+Notification inbox storage is available in the storage adapters that support richer memory and signal workflows: [libSQL](https://mastra.ai/integrations/databases/libsql), [PostgreSQL](https://mastra.ai/integrations/databases/postgresql), and [MongoDB](https://mastra.ai/integrations/databases/mongodb). These adapters expose notification records through `getStore('notifications')`.
 
 ### Send processor context
 

package/dist/docs/references/reference-migrations-upgrade-to-v1-client.md

@@ -0,0 +1,339 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Client SDK
+
+Client SDK changes align with server-side API updates, including utility renames, updated pagination, and type naming conventions.
+
+## Changed
+
+### `messages` is now identical to `@mastra/core/agent` syntax
+
+The `messages` argument is now the first argument of the `generate`, `stream` and `network` method calls, similar to the NodeJS version in `@mastra/core/agent`.
+
+To migrate, move `messages` to the first argument of the method call:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+-  await agent.generate({
+-    messages: [...]
++  await agent.generate([...], {
+  });
+
+-  await agent.stream({
+-    messages: [...]
++  await agent.stream([...], {
+  });
+
+-  await agent.network({
+-    messages: [...]
++  await agent.network([...], {
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-msg-function-args .
+> ```
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from agent method calls. Use the `memory` option instead, which provides a cleaner API for memory configuration. This applies to both `@mastra/client-js` and `@mastra/react` packages.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+  await agent.generate([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+
++  await agent.stream([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+#### Using `@mastra/react` `useChat` hook
+
+The `useChat` hook internally passes the memory option when you provide a `threadId`. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to `sendMessage`, update them accordingly:
+
+```diff
+const { sendMessage } = useChat({ agentId: 'my-agent' });
+
+  await sendMessage({
+    message: 'Hello',
+    mode: 'stream',
+-   threadId: 'thread-123',
++   threadId: 'thread-123', // Still works - internally converted to memory option
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.generate([...], {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+});
+```
+
+### Client SDK types from `Get*` to `List*`
+
+Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.
+
+To migrate, update type imports to use the new naming pattern.
+
+```diff
+- import type {
+-   GetWorkflowRunsParams,
+-   GetWorkflowRunsResponse,
+-   GetMemoryThreadParams,
+- } from '@mastra/client-js';
++ import type {
++   ListWorkflowRunsParams,
++   ListWorkflowRunsResponse,
++   ListMemoryThreadsParams,
++ } from '@mastra/client-js';
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-sdk-types .
+> ```
+
+### Pagination parameters from `offset/limit` to `page/perPage`
+
+All client SDK methods that used `offset/limit` now use `page/perPage`, matching page-based web pagination.
+
+To migrate, update pagination parameters in all client SDK method calls. Example:
+
+```diff
+client.memory.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-offset-limit .
+> ```
+
+### `getMemoryThread` parameter structure
+
+The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+
+To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
+
+```diff
+- const thread = await client.getMemoryThread(threadId, agentId);
++ const thread = await client.getMemoryThread({ threadId, agentId });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-get-memory-thread .
+> ```
+
+### Unified `runById` API for workflow runs
+
+The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.
+
+The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.
+
+```diff
+const workflow = client.getWorkflow('my-workflow');
+
+- // Previously: runById returned raw WorkflowRun with snapshot
+- const run = await workflow.runById(runId, requestContext);
+- // Separately: runExecutionResult returned processed execution state
+- const result = await workflow.runExecutionResult(runId);
+
++ // Now: Single method returns unified WorkflowState
++ const run = await workflow.runById(runId, {
++   requestContext,  // Optional request context
++   fields: ['status', 'result'],  // Optional: request only specific fields
++   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
++ });
++ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
+```
+
+## Removed
+
+### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type
+
+The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.
+
+To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.
+
+```diff
+- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const result = await workflow.runExecutionResult(runId);
+
++ const workflow = client.getWorkflow('my-workflow');
++ const result = await workflow.runById(runId);
++ // Or with options for performance optimization:
++ const result = await workflow.runById(runId, {
++   fields: ['status', 'result'],  // Only fetch specific fields
++   withNestedWorkflows: false,     // Skip expensive nested workflow data
++ });
+```
+
+### `toAISdkFormat` function
+
+The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. Use the stream conversion utilities shown below instead.
+
+To migrate, use `toAISdkStream()` instead.
+
+```diff
+- import { toAISdkFormat } from '@mastra/ai-sdk';
+- const stream = toAISdkFormat(agentStream, { from: 'agent' });
++ import { toAISdkStream } from '@mastra/ai-sdk';
++ const stream = toAISdkStream(agentStream, { from: 'agent' });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-to-ai-sdk-format .
+> ```
+
+### Network memory methods
+
+Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.
+
+To migrate, use regular memory APIs instead of network memory.
+
+```diff
+- import { MastraClient } from '@mastra/client-js';
+-
+- const client = new MastraClient({ baseUrl: '...' });
+- const networkThread = client.networkMemory.getThread('thread-id');
+- const networkThread = client.memory.networkThread('thread-id', 'network-id');
+- await networkThread.get();
+- await networkThread.getMessages();
+
++ // Use regular memory thread APIs instead
++ const client = new MastraClient({ baseUrl: '...' });
++ const thread = client.memory.getThread('thread-id');
++ await thread.get();
++ const messages = await thread.listMessages();
+```
+
+### Watch-related types
+
+Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.
+
+To migrate, use workflow streaming APIs instead of watch.
+
+```diff
+- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const run = await workflow.createRun();
+- await run.watch((event: WatchEvent) => {
+-   console.log('Event:', event);
+- });
+
++ const workflow = client.getWorkflow('my-workflow');
++ const run = await workflow.createRun();
++ const stream = await run.stream({ inputData: { ... } });
++ for await (const chunk of stream) {
++   console.log('Event:', chunk);
++ }
+```
+
+### Run-related methods can't be called directly on workflow instance
+
+Run-related methods can't be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
+
+```diff
+- const result = await workflow.start({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const result = await run.start({ inputData: { ... } });
+```
+
+```diff
+- const result = await workflow.stream({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.
+
+```diff
++ const run = await workflow.createRun({ runId: '123' });
+- const stream = await run.streamVNext({ inputData: { ... } });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### Deprecated stream endpoints
+
+Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.
+
+To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.
+
+```diff
+- const response = await fetch('/api/agents/my-agent/stream/vnext', {
+-   method: 'POST',
+-   body: JSON.stringify({ messages: [...] }),
+- });
+
++ const response = await fetch('/api/agents/my-agent/stream', {
++   method: 'POST',
++   body: JSON.stringify({ messages: [...] }),
++ });
++
++ // Or use @mastra/ai-sdk for UI message transformations
+```
+
+### Network memory API endpoints
+
+Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.
+
+To migrate, use regular memory API endpoints.
+
+```diff
+- const networkThread = await fetch('/api/memory/network/threads/thread-123');
++ const thread = await fetch('/api/memory/threads/thread-123');
+```
+
+### Eval-related client SDK types
+
+Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.
+
+To migrate, use the new scorers API instead of legacy evals.

package/dist/route-types.generated.d.ts

@@ -1070,7 +1070,7 @@ type Shared_Type_69 = {
     /** When true, excludes the end date from results (uses < instead of <=) */
     endExclusive?: boolean | undefined;
 };
-type Shared_Type_70 = 'agent_run' | 'scorer_run' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping';
+type Shared_Type_70 = 'agent_run' | 'scorer_run' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping' | 'skill_resolution';
 type Shared_Type_71 = 'agent' | 'scorer' | 'rag_ingestion' | 'trajectory' | 'input_processor' | 'input_step_processor' | 'output_processor' | 'output_step_processor' | 'tool_result_processor' | 'workflow_step' | 'tool' | 'workflow_run' | 'memory';
 type Shared_Type_72 = {
     /** Total number of items available */
@@ -6772,7 +6772,7 @@ export type GetObservabilityTracesTraceIdSpanIdScores_Response = {
         entity: {
             [key: string]: unknown;
         };
-        entityType?: ('AGENT' | 'WORKFLOW' | 'TRAJECTORY' | 'STEP' | 'agent_run' | 'scorer_run' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping') | undefined;
+        entityType?: ('AGENT' | 'WORKFLOW' | 'TRAJECTORY' | 'STEP' | 'agent_run' | 'scorer_run' | 'scorer_step' | 'generic' | 'model_generation' | 'model_step' | 'model_inference' | 'model_chunk' | 'mcp_tool_call' | 'processor_run' | 'tool_call' | 'client_tool_call' | 'provider_tool_call' | 'workflow_run' | 'workflow_step' | 'workflow_conditional' | 'workflow_conditional_eval' | 'workflow_parallel' | 'workflow_loop' | 'workflow_sleep' | 'workflow_wait_event' | 'memory_operation' | 'workspace_action' | 'rag_ingestion' | 'rag_embedding' | 'rag_vector_operation' | 'rag_action' | 'graph_action' | 'mapping' | 'skill_resolution') | undefined;
         structuredOutput?: boolean | undefined;
         traceId?: string | undefined;
         spanId?: string | undefined;