@mastra/mcp-docs-server 1.0.0-beta.13 → 1.0.0-beta.15

package/.docs/organized/changelogs/%40mastra%2Fclient-js.md

@@ -1,5 +1,177 @@
 # @mastra/client-js
 
+## 1.0.0-beta.15
+
+### Minor Changes
+
+- Unified observability schema with entity-based span identification ([#11132](https://github.com/mastra-ai/mastra/pull/11132))
+
+  ## What changed
+
+  Spans now use a unified identification model with `entityId`, `entityType`, and `entityName` instead of separate `agentId`, `toolId`, `workflowId` fields.
+
+  **Before:**
+
+  ```typescript
+  // Old span structure
+  span.agentId; // 'my-agent'
+  span.toolId; // undefined
+  span.workflowId; // undefined
+  ```
+
+  **After:**
+
+  ```typescript
+  // New span structure
+  span.entityType; // EntityType.AGENT
+  span.entityId; // 'my-agent'
+  span.entityName; // 'My Agent'
+  ```
+
+  ## New `listTraces()` API
+
+  Query traces with filtering, pagination, and sorting:
+
+  ```typescript
+  const { spans, pagination } = await storage.listTraces({
+    filters: {
+      entityType: EntityType.AGENT,
+      entityId: 'my-agent',
+      userId: 'user-123',
+      environment: 'production',
+      status: TraceStatus.SUCCESS,
+      startedAt: { start: new Date('2024-01-01'), end: new Date('2024-01-31') },
+    },
+    pagination: { page: 0, perPage: 50 },
+    orderBy: { field: 'startedAt', direction: 'DESC' },
+  });
+  ```
+
+  **Available filters:** date ranges (`startedAt`, `endedAt`), entity (`entityType`, `entityId`, `entityName`), identity (`userId`, `organizationId`), correlation IDs (`runId`, `sessionId`, `threadId`), deployment (`environment`, `source`, `serviceName`), `tags`, `metadata`, and `status`.
+
+  ## New retrieval methods
+  - `getSpan({ traceId, spanId })` - Get a single span
+  - `getRootSpan({ traceId })` - Get the root span of a trace
+  - `getTrace({ traceId })` - Get all spans for a trace
+
+  ## Backward compatibility
+
+  The legacy `getTraces()` method continues to work. When you pass `name: "agent run: my-agent"`, it automatically transforms to `entityId: "my-agent", entityType: AGENT`.
+
+  ## Migration
+
+  **Automatic:** SQL-based stores (PostgreSQL, LibSQL, MSSQL) automatically add new columns to existing `spans` tables on initialization. Existing data is preserved with new columns set to `NULL`.
+
+  **No action required:** Your existing code continues to work. Adopt the new fields and `listTraces()` API at your convenience.
+
+### Patch Changes
+
+- Add debugger-like click-through UI to workflow graph ([#11350](https://github.com/mastra-ai/mastra/pull/11350))
+
+- Add `getSystemPackages()` method to retrieve installed Mastra packages and their versions from the server ([#11211](https://github.com/mastra-ai/mastra/pull/11211))
+
+- Fix error parsing json body for reset agent endpoint ([#11379](https://github.com/mastra-ai/mastra/pull/11379))
+
+- Updated dependencies [[`33a4d2e`](https://github.com/mastra-ai/mastra/commit/33a4d2e4ed8af51f69256232f00c34d6b6b51d48), [`4aaa844`](https://github.com/mastra-ai/mastra/commit/4aaa844a4f19d054490f43638a990cc57bda8d2f), [`4a1a6cb`](https://github.com/mastra-ai/mastra/commit/4a1a6cb3facad54b2bb6780b00ce91d6de1edc08), [`31d13d5`](https://github.com/mastra-ai/mastra/commit/31d13d5fdc2e2380e2e3ee3ec9fb29d2a00f265d), [`4c62166`](https://github.com/mastra-ai/mastra/commit/4c621669f4a29b1f443eca3ba70b814afa286266), [`7bcbf10`](https://github.com/mastra-ai/mastra/commit/7bcbf10133516e03df964b941f9a34e9e4ab4177), [`4353600`](https://github.com/mastra-ai/mastra/commit/43536005a65988a8eede236f69122e7f5a284ba2), [`6986fb0`](https://github.com/mastra-ai/mastra/commit/6986fb064f5db6ecc24aa655e1d26529087b43b3), [`053e979`](https://github.com/mastra-ai/mastra/commit/053e9793b28e970086b0507f7f3b76ea32c1e838), [`e26dc9c`](https://github.com/mastra-ai/mastra/commit/e26dc9c3ccfec54ae3dc3e2b2589f741f9ae60a6), [`55edf73`](https://github.com/mastra-ai/mastra/commit/55edf7302149d6c964fbb7908b43babfc2b52145), [`27c0009`](https://github.com/mastra-ai/mastra/commit/27c0009777a6073d7631b0eb7b481d94e165b5ca), [`dee388d`](https://github.com/mastra-ai/mastra/commit/dee388dde02f2e63c53385ae69252a47ab6825cc), [`3f3fc30`](https://github.com/mastra-ai/mastra/commit/3f3fc3096f24c4a26cffeecfe73085928f72aa63), [`d90ea65`](https://github.com/mastra-ai/mastra/commit/d90ea6536f7aa51c6545a4e9215b55858e98e16d), [`d171e55`](https://github.com/mastra-ai/mastra/commit/d171e559ead9f52ec728d424844c8f7b164c4510), [`10c2735`](https://github.com/mastra-ai/mastra/commit/10c27355edfdad1ee2b826b897df74125eb81fb8), [`1924cf0`](https://github.com/mastra-ai/mastra/commit/1924cf06816e5e4d4d5333065ec0f4bb02a97799), [`b339816`](https://github.com/mastra-ai/mastra/commit/b339816df0984d0243d944ac2655d6ba5f809cde)]:
+  - @mastra/core@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- feat: Add field filtering and nested workflow control to workflow execution result endpoint ([#11246](https://github.com/mastra-ai/mastra/pull/11246))
+
+  Adds two optional query parameters to `/api/workflows/:workflowId/runs/:runId/execution-result` endpoint:
+  - `fields`: Request only specific fields (e.g., `status`, `result`, `error`)
+  - `withNestedWorkflows`: Control whether to fetch nested workflow data
+
+  This significantly reduces response payload size and improves response times for large workflows.
+
+  ## Server Endpoint Usage
+
+  ```http
+  # Get only status (minimal payload - fastest)
+  GET /api/workflows/:workflowId/runs/:runId/execution-result?fields=status
+
+  # Get status and result
+  GET /api/workflows/:workflowId/runs/:runId/execution-result?fields=status,result
+
+  # Get all fields but without nested workflow data (faster)
+  GET /api/workflows/:workflowId/runs/:runId/execution-result?withNestedWorkflows=false
+
+  # Get only specific fields without nested workflow data
+  GET /api/workflows/:workflowId/runs/:runId/execution-result?fields=status,steps&withNestedWorkflows=false
+
+  # Get full data (default behavior)
+  GET /api/workflows/:workflowId/runs/:runId/execution-result
+  ```
+
+  ## Client SDK Usage
+
+  ```typescript
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:4111' });
+  const workflow = client.getWorkflow('myWorkflow');
+
+  // Get only status (minimal payload - fastest)
+  const statusOnly = await workflow.runExecutionResult(runId, {
+    fields: ['status'],
+  });
+  console.log(statusOnly.status); // 'success' | 'failed' | 'running' | etc.
+
+  // Get status and result
+  const statusAndResult = await workflow.runExecutionResult(runId, {
+    fields: ['status', 'result'],
+  });
+
+  // Get all fields but without nested workflow data (faster)
+  const resultWithoutNested = await workflow.runExecutionResult(runId, {
+    withNestedWorkflows: false,
+  });
+
+  // Get specific fields without nested workflow data
+  const optimized = await workflow.runExecutionResult(runId, {
+    fields: ['status', 'steps'],
+    withNestedWorkflows: false,
+  });
+
+  // Get full execution result (default behavior)
+  const fullResult = await workflow.runExecutionResult(runId);
+  ```
+
+  ## Core API Changes
+
+  The `Workflow.getWorkflowRunExecutionResult` method now accepts an options object:
+
+  ```typescript
+  await workflow.getWorkflowRunExecutionResult(runId, {
+    withNestedWorkflows: false, // default: true, set to false to skip nested workflow data
+    fields: ['status', 'result'], // optional field filtering
+  });
+  ```
+
+  ## Inngest Compatibility
+
+  The `@mastra/inngest` package has been updated to use the new options object API. This is a non-breaking internal change - no action required from inngest workflow users.
+
+  ## Performance Impact
+
+  For workflows with large step outputs:
+  - Requesting only `status`: ~99% reduction in payload size
+  - Requesting `status,result,error`: ~95% reduction in payload size
+  - Using `withNestedWorkflows=false`: Avoids expensive nested workflow data fetching
+  - Combining both: Maximum performance optimization
+
+- Fix delayed promises rejecting when stream suspends on tool-call-approval ([#11278](https://github.com/mastra-ai/mastra/pull/11278))
+
+  When a stream ends in suspended state (e.g., requiring tool approval), the delayed promises like `toolResults`, `toolCalls`, `text`, etc. now resolve with partial results instead of rejecting with an error. This allows consumers to access data that was produced before the suspension.
+
+  Also improves generic type inference for `LLMStepResult` and related types throughout the streaming infrastructure.
+
+- Updated dependencies [[`4f94ed8`](https://github.com/mastra-ai/mastra/commit/4f94ed8177abfde3ec536e3574883e075423350c), [`ac3cc23`](https://github.com/mastra-ai/mastra/commit/ac3cc2397d1966bc0fc2736a223abc449d3c7719), [`a86f4df`](https://github.com/mastra-ai/mastra/commit/a86f4df0407311e0d2ea49b9a541f0938810d6a9), [`029540c`](https://github.com/mastra-ai/mastra/commit/029540ca1e582fc2dd8d288ecd4a9b0f31a954ef), [`66741d1`](https://github.com/mastra-ai/mastra/commit/66741d1a99c4f42cf23a16109939e8348ac6852e), [`01b20fe`](https://github.com/mastra-ai/mastra/commit/01b20fefb7c67c2b7d79417598ef4e60256d1225), [`0dbf199`](https://github.com/mastra-ai/mastra/commit/0dbf199110f22192ce5c95b1c8148d4872b4d119), [`a7ce182`](https://github.com/mastra-ai/mastra/commit/a7ce1822a8785ce45d62dd5c911af465e144f7d7)]:
+  - @mastra/core@1.0.0-beta.14
+
 ## 1.0.0-beta.13
 
 ### Patch Changes
@@ -326,177 +498,5 @@
   + storage.listMessages({ threadId, page: 0, perPage: false })  // Fetch all
 
   // Memory: Replace selectBy with flat parameters
-  - memory.query({ threadId, selectBy: { last: 20, include: [...] } })
-  + memory.query({ threadId, perPage: 20, include: [...] })
-
-  // Client SDK
-  - thread.getMessagesPaginated({ selectBy: { pagination: { page: 0 } } })
-  + thread.listMessages({ page: 0, perPage: 20 })
-  ```
-
-- # Major Changes ([#9695](https://github.com/mastra-ai/mastra/pull/9695))
-
-  ## Storage Layer
-
-  ### BREAKING: Removed `storage.getMessages()`
-
-  The `getMessages()` method has been removed from all storage implementations. Use `listMessages()` instead, which provides pagination support.
-
-  **Migration:**
-
-  ```typescript
-  // Before
-  const messages = await storage.getMessages({ threadId: 'thread-1' });
-
-  // After
-  const result = await storage.listMessages({
-    threadId: 'thread-1',
-    page: 0,
-    perPage: 50,
-  });
-  const messages = result.messages; // Access messages array
-  console.log(result.total); // Total count
-  console.log(result.hasMore); // Whether more pages exist
-  ```
-
-  ### Message ordering default
-
-  `listMessages()` defaults to ASC (oldest first) ordering by `createdAt`, matching the previous `getMessages()` behavior.
-
-  **To use DESC ordering (newest first):**
-
-  ```typescript
-  const result = await storage.listMessages({
-    threadId: 'thread-1',
-    orderBy: { field: 'createdAt', direction: 'DESC' },
-  });
-  ```
-
-  ## Client SDK
-
-  ### BREAKING: Renamed `client.getThreadMessages()` → `client.listThreadMessages()`
-
-  **Migration:**
-
-  ```typescript
-  // Before
-  const response = await client.getThreadMessages(threadId, { agentId });
-
-  // After
-  const response = await client.listThreadMessages(threadId, { agentId });
-  ```
-
-  The response format remains the same.
-
-  ## Type Changes
-
-  ### BREAKING: Removed `StorageGetMessagesArg` type
-
-  Use `StorageListMessagesInput` instead:
-
-  ```typescript
-  // Before
-  import type { StorageGetMessagesArg } from '@mastra/core';
-
-  // After
-  import type { StorageListMessagesInput } from '@mastra/core';
-  ```
-
-- Bump minimum required Node.js version to 22.13.0 ([#9706](https://github.com/mastra-ai/mastra/pull/9706))
-
-- Replace `getThreadsByResourceIdPaginated` with `listThreadsByResourceId` across memory handlers. Update client SDK to use `listThreads()` with `offset`/`limit` parameters instead of deprecated `getMemoryThreads()`. Consolidate `/api/memory/threads` routes to single paginated endpoint. ([#9508](https://github.com/mastra-ai/mastra/pull/9508))
-
-- Rename RuntimeContext to RequestContext ([#9511](https://github.com/mastra-ai/mastra/pull/9511))
-
-- Rename `defaultVNextStreamOptions` to `defaultOptions`. Add "Legacy" suffix to v1 option properties and methods (`defaultGenerateOptions` → `defaultGenerateOptionsLegacy`, `defaultStreamOptions` → `defaultStreamOptionsLegacy`). ([#9535](https://github.com/mastra-ai/mastra/pull/9535))
-
-- Remove deprecated methods from client-js ([#9480](https://github.com/mastra-ai/mastra/pull/9480))
-
-- Renamed a bunch of observability/tracing-related things to drop the AI prefix. ([#9744](https://github.com/mastra-ai/mastra/pull/9744))
-
-- **Breaking Change**: Remove legacy v1 watch events and consolidate on v2 implementation. ([#9252](https://github.com/mastra-ai/mastra/pull/9252))
-
-  This change simplifies the workflow watching API by removing the legacy v1 event system and promoting v2 as the standard (renamed to just `watch`).
-
-  ### What's Changed
-  - Removed legacy v1 watch event handlers and types
-  - Renamed `watch-v2` to `watch` throughout the codebase
-  - Removed `.watch()` method from client-js SDK (`Workflow` and `AgentBuilder` classes)
-  - Removed `/watch` HTTP endpoints from server and deployer
-  - Removed `WorkflowWatchResult` and v1 `WatchEvent` types
-
-- **BREAKING CHANGE**: Pagination APIs now use `page`/`perPage` instead of `offset`/`limit` ([#9592](https://github.com/mastra-ai/mastra/pull/9592))
-
-  All storage and memory pagination APIs have been updated to use `page` (0-indexed) and `perPage` instead of `offset` and `limit`, aligning with standard REST API patterns.
-
-  **Affected APIs:**
-  - `Memory.listThreadsByResourceId()`
-  - `Memory.listMessages()`
-  - `Storage.listWorkflowRuns()`
-
-  **Migration:**
-
-  ```typescript
-  // Before
-  await memory.listThreadsByResourceId({
-    resourceId: 'user-123',
-    offset: 20,
-    limit: 10,
-  });
-
-  // After
-  await memory.listThreadsByResourceId({
-    resourceId: 'user-123',
-    page: 2, // page = Math.floor(offset / limit)
-    perPage: 10,
-  });
-
-  // Before
-  await memory.listMessages({
-    threadId: 'thread-456',
-    offset: 20,
-    limit: 10,
-  });
-
-  // After
-  await memory.listMessages({
-    threadId: 'thread-456',
-    page: 2,
-    perPage: 10,
-  });
-
-  // Before
-  await storage.listWorkflowRuns({
-    workflowName: 'my-workflow',
-    offset: 20,
-    limit: 10,
-  });
-
-  // After
-  await storage.listWorkflowRuns({
-    workflowName: 'my-workflow',
-    page: 2,
-    perPage: 10,
-  });
-  ```
-
-  **Additional improvements:**
-  - Added validation for negative `page` values in all storage implementations
-  - Improved `perPage` validation to handle edge cases (negative values, `0`, `false`)
-  - Added reusable query parser utilities for consistent validation in handlers
-
-- ```([#9709](https://github.com/mastra-ai/mastra/pull/9709))
-  import { Mastra } from '@mastra/core';
-  import { Observability } from '@mastra/observability';  // Explicit import
-
-  const mastra = new Mastra({
-    ...other_config,
-    observability: new Observability({
-      default: { enabled: true }
-    })  // Instance
-  });
-  ```
-
-  Instead of:
 
-... 3375 more lines hidden. See full changelog in package directory.
+... 3547 more lines hidden. See full changelog in package directory.