@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.1

package/.docs/organized/changelogs/%40mastra%2Fcore.md

@@ -1,502 +1,502 @@
 # @mastra/core
 
-## 1.0.0-beta.9
+## 1.0.4
 
-### Minor Changes
+## 1.0.4-alpha.0
 
-- Add stored agents support ([#10953](https://github.com/mastra-ai/mastra/pull/10953))
+## 1.0.0
 
-  Agents can now be stored in the database and loaded at runtime. This lets you persist agent configurations and dynamically create executable Agent instances from storage.
+### Major Changes
 
-  ```typescript
-  import { Mastra } from '@mastra/core';
-  import { LibSQLStore } from '@mastra/libsql';
+- Moving scorers under the eval domain, api method consistency, prebuilt evals, scorers require ids. ([#9589](https://github.com/mastra-ai/mastra/pull/9589))
 
-  const mastra = new Mastra({
-    storage: new LibSQLStore({ url: ':memory:' }),
-    tools: { myTool },
-    scorers: { myScorer },
-  });
+- Scorers for Agents will now use `MastraDBMessage` instead of `UIMessage` ([#9702](https://github.com/mastra-ai/mastra/pull/9702))
+  - Scorer input/output types now use `MastraDBMessage[]` with nested `content` object structure
+  - Added `getTextContentFromMastraDBMessage()` helper function to extract text content from `MastraDBMessage` objects
+  - Added `createTestMessage()` helper function for creating `MastraDBMessage` objects in tests with optional tool invocations support
+  - Updated `extractToolCalls()` to access tool invocations from nested `content` structure
+  - Updated `getUserMessageFromRunInput()` and `getAssistantMessageFromRunOutput()` to use new message structure
+  - Removed `createUIMessage()`
 
-  // Create agent in storage via API or directly
-  await mastra.getStorage().createAgent({
-    agent: {
-      id: 'my-agent',
-      name: 'My Agent',
-      instructions: 'You are helpful',
-      model: { provider: 'openai', name: 'gpt-4' },
-      tools: { myTool: {} },
-      scorers: { myScorer: { sampling: { type: 'ratio', rate: 0.5 } } },
-    },
-  });
+- Every Mastra primitive (agent, MCPServer, workflow, tool, processor, scorer, and vector) now has a get, list, and add method associated with it. Each primitive also now requires an id to be set. ([#9675](https://github.com/mastra-ai/mastra/pull/9675))
 
-  // Load and use the agent
-  const agent = await mastra.getStoredAgentById('my-agent');
-  const response = await agent.generate({ messages: 'Hello!' });
+  Primitives that are added to other primitives are also automatically added to the Mastra instance
 
-  // List all stored agents with pagination
-  const { agents, total, hasMore } = await mastra.listStoredAgents({
-    page: 0,
-    perPage: 10,
-  });
-  ```
+- Update handlers to use `listWorkflowRuns` instead of `getWorkflowRuns`. Fix type names from `StoragelistThreadsByResourceIdInput/Output` to `StorageListThreadsByResourceIdInput/Output`. ([#9507](https://github.com/mastra-ai/mastra/pull/9507))
 
-  Also adds a memory registry to Mastra so stored agents can reference memory instances by key.
+- Refactor workflow and tool types to remove Zod-specific constraints ([#11814](https://github.com/mastra-ai/mastra/pull/11814))
 
-### Patch Changes
+  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.
 
-- Add agentId and agentName attributes to MODEL_GENERATION spans. This allows users to correlate gen_ai.usage metrics with specific agents when analyzing LLM operation spans. The attributes are exported as gen_ai.agent.id and gen_ai.agent.name in the OtelExporter. ([#10984](https://github.com/mastra-ai/mastra/pull/10984))
+  **Workflow Changes:**
+  - Removed `z.ZodObject<any>` and `z.ZodType<any>` constraints from all workflow generic types
+  - Updated method signatures to use `TInput` and `TState` directly instead of `z.infer<TInput>` and `z.infer<TState>`
+  - Aligned conditional types across all workflow implementations using `TInput extends unknown` pattern
+  - Fixed `TSteps` generic to properly use `TEngineType` instead of `any`
 
-- Fix JSON parsing errors when LLMs output unescaped newlines in structured output strings ([#10965](https://github.com/mastra-ai/mastra/pull/10965))
+  **Tool Changes:**
+  - Removed Zod schema constraints from `ToolExecutionContext` and related interfaces
+  - Simplified type parameters from `TSuspendSchema extends ZodLikeSchema` to `TSuspend` and `TResume`
+  - Updated tool execution context types to use generic types
 
-  Some LLMs (particularly when not using native JSON mode) output actual newline characters inside JSON string values instead of properly escaped `\n` sequences. This breaks JSON parsing and causes structured output to fail.
+  **Type Utilities:**
+  - Refactored type helpers to work with generic schemas instead of Zod-specific types
+  - Updated type extraction utilities for better compatibility
 
-  This change adds preprocessing to escape unescaped control characters (`\n`, `\r`, `\t`) within JSON string values before parsing, making structured output more robust across different LLM providers.
+  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.
 
-- Fix toolCallId propagation in agent network tool execution. The toolCallId property was undefined at runtime despite being required by TypeScript type definitions in AgentToolExecutionContext. Now properly passes the toolCallId through to the tool's context during network tool execution. ([#10951](https://github.com/mastra-ai/mastra/pull/10951))
+- Remove `getMessagesPaginated()` and add `perPage: false` support ([#9670](https://github.com/mastra-ai/mastra/pull/9670))
 
-- Exports `convertFullStreamChunkToMastra` from the stream module for AI SDK stream chunk transformations. ([#10911](https://github.com/mastra-ai/mastra/pull/10911))
+  Removes deprecated `getMessagesPaginated()` method. The `listMessages()` API and score handlers now support `perPage: false` to fetch all records without pagination limits.
 
-## 1.0.0-beta.8
+  **Storage changes:**
+  - `StoragePagination.perPage` type changed from `number` to `number | false`
+  - All storage implementations support `perPage: false`:
+    - Memory: `listMessages()`
+    - Scores: `listScoresBySpan()`, `listScoresByRunId()`, `listScoresByExecutionId()`
+  - HTTP query parser accepts `"false"` string (e.g., `?perPage=false`)
 
-### Patch Changes
+  **Memory changes:**
+  - `memory.query()` parameter type changed from `StorageGetMessagesArg` to `StorageListMessagesInput`
+  - Uses flat parameters (`page`, `perPage`, `include`, `filter`, `vectorSearchString`) instead of `selectBy` object
 
-- Fix saveScore not persisting ID correctly, breaking getScoreById retrieval ([#10915](https://github.com/mastra-ai/mastra/pull/10915))
+  **Stricter validation:**
+  - `listMessages()` requires non-empty, non-whitespace `threadId` (throws error instead of returning empty results)
 
-  **What Changed**
-  - saveScore now correctly returns scores that can be retrieved with getScoreById
-  - Validation errors now include contextual information (scorer, entity, trace details) for easier debugging
+  **Migration:**
 
-  **Impact**
-  Previously, calling getScoreById after saveScore would return null because the generated ID wasn't persisted to the database. This is now fixed across all store implementations, ensuring consistent behavior and data integrity.
-
-- `setState` is now async ([#10944](https://github.com/mastra-ai/mastra/pull/10944))
-  - `setState` must now be awaited: `await setState({ key: value })`
-  - State updates are merged automatically—no need to spread the previous state
-  - State data is validated against the step's `stateSchema` when `validateInputs` is enabled (default: `true`)
-
-- Add human-in-the-loop support for workflows used in agent ([#10871](https://github.com/mastra-ai/mastra/pull/10871))
-
-## 1.0.0-beta.7
+  ```typescript
+  // Storage/Memory: Replace getMessagesPaginated with listMessages
+  - storage.getMessagesPaginated({ threadId, selectBy: { pagination: { page: 0, perPage: 20 } } })
+  + storage.listMessages({ threadId, page: 0, perPage: 20 })
+  + 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 })
+  ```
 
-### Minor Changes
+- **Removed `storage.getMessages()`** ([#9695](https://github.com/mastra-ai/mastra/pull/9695))
 
-- Add `disableInit` option to all storage adapters ([#10851](https://github.com/mastra-ai/mastra/pull/10851))
+  The `getMessages()` method has been removed from all storage implementations. Use `listMessages()` instead, which provides pagination support.
 
-  Adds a new `disableInit` config option to all storage providers that allows users to disable automatic table creation/migrations at runtime. This is useful for CI/CD pipelines where you want to run migrations during deployment with elevated credentials, then run the application with `disableInit: true` so it doesn't attempt schema changes at runtime.
+  **Migration:**
 
   ```typescript
-  // CI/CD script - run migrations
-  const storage = new PostgresStore({
-    connectionString: DATABASE_URL,
-    id: 'pg-storage',
-  });
-  await storage.init();
+  // Before
+  const messages = await storage.getMessages({ threadId: 'thread-1' });
 
-  // Runtime - skip auto-init
-  const storage = new PostgresStore({
-    connectionString: DATABASE_URL,
-    id: 'pg-storage',
-    disableInit: true,
+  // 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
   ```
 
-### Patch Changes
+  **Message ordering default**
 
-- Add time-to-first-token (TTFT) support for Langfuse integration ([#10781](https://github.com/mastra-ai/mastra/pull/10781))
+  `listMessages()` defaults to ASC (oldest first) ordering by `createdAt`, matching the previous `getMessages()` behavior.
 
-  Adds `completionStartTime` to model generation spans, which Langfuse uses to calculate TTFT metrics. The timestamp is automatically captured when the first content chunk arrives during streaming.
+  **To use DESC ordering (newest first):**
 
   ```typescript
-  // completionStartTime is now automatically captured and sent to Langfuse
-  // enabling TTFT metrics in your Langfuse dashboard
-  const result = await agent.stream('Hello');
+  const result = await storage.listMessages({
+    threadId: 'thread-1',
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+  });
   ```
 
-- Updated OtelExporters, Bridge, and Arize packages to better implement GenAI v1.38.0 Otel Semantic Conventions. See: ([#10591](https://github.com/mastra-ai/mastra/pull/10591))
-  https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/gen-ai/README.md
-
-- Standardize error IDs across all storage and vector stores using centralized helper functions (`createStorageErrorId` and `createVectorErrorId`). This ensures consistent error ID patterns (`MASTRA_STORAGE_{STORE}_{OPERATION}_{STATUS}` and `MASTRA_VECTOR_{STORE}_{OPERATION}_{STATUS}`) across the codebase for better error tracking and debugging. ([#10913](https://github.com/mastra-ai/mastra/pull/10913))
-
-- fix: generate unique text IDs for Anthropic/Google providers ([#10740](https://github.com/mastra-ai/mastra/pull/10740))
+  **Renamed `client.getThreadMessages()` → `client.listThreadMessages()`**
 
-  Workaround for duplicate text-start/text-end IDs in multi-step agentic flows.
-
-  The `@ai-sdk/anthropic` and `@ai-sdk/google` providers use numeric indices ("0", "1", etc.) for text block IDs that reset for each LLM call. This caused duplicate IDs when an agent does TEXT → TOOL → TEXT, breaking message ordering and storage.
-
-  The fix replaces numeric IDs with UUIDs, maintaining a map per step so text-start, text-delta, and text-end chunks for the same block share the same UUID. OpenAI's UUIDs pass through unchanged.
-
-  Related: #9909
-
-- Fix sub-agent requestContext propagation in listAgentTools ([#10844](https://github.com/mastra-ai/mastra/pull/10844))
-
-  Sub-agents with dynamic model configurations were broken because `requestContext` was not being passed to `getModel()` when creating agent tools. This caused sub-agents using function-based model configurations to receive an empty context instead of the parent's context.
-
-  No code changes required for consumers - this fix restores expected behavior for dynamic model configurations in sub-agents.
-
-- Fix ToolStream type error when piping streams with different types ([#10845](https://github.com/mastra-ai/mastra/pull/10845))
-
-  Changes `ToolStream` to extend `WritableStream<unknown>` instead of `WritableStream<T>`. This fixes the TypeScript error when piping `objectStream` or `fullStream` to `writer` in workflow steps.
-
-  Before:
+  **Migration:**
 
   ```typescript
-  // TypeError: ToolStream<ChunkType> is not assignable to WritableStream<Partial<StoryPlan>>
-  await response.objectStream.pipeTo(writer);
-  ```
-
-  After:
-
-  ```typescript
-  // Works without type errors
-  await response.objectStream.pipeTo(writer);
-  ```
-
-- feat: add native Perplexity provider support ([#10885](https://github.com/mastra-ai/mastra/pull/10885))
-
-- When sending the first message to a new thread with PostgresStore, users would get a "Thread not found" error. This happened because the thread was created in memory but not persisted to the database before the MessageHistory output processor tried to save messages. ([#10881](https://github.com/mastra-ai/mastra/pull/10881))
-
-  **Before:**
-
-  ```ts
-  threadObject = await memory.createThread({
-    // ...
-    saveThread: false, // thread not in DB yet
-  });
-  // Later: MessageHistory calls saveMessages() -> PostgresStore throws "Thread not found"
-  ```
+  // Before
+  const response = await client.getThreadMessages(threadId, { agentId });
 
-  **After:**
-
-  ```ts
-  threadObject = await memory.createThread({
-    // ...
-    saveThread: true, // thread persisted immediately
-  });
-  // MessageHistory can now save messages without error
+  // After
+  const response = await client.listThreadMessages(threadId, { agentId });
   ```
 
-- Emit error chunk and call onError when agent workflow step fails ([#10907](https://github.com/mastra-ai/mastra/pull/10907))
-
-  When a workflow step fails (e.g., tool not found), the error is now properly emitted as an error chunk to the stream and the onError callback is called. This fixes the issue where agent.generate() would throw "promise 'text' was not resolved or rejected" instead of the actual error message.
+  The response format remains the same.
 
-- fix(core): use agent description when converting agent to tool ([#10879](https://github.com/mastra-ai/mastra/pull/10879))
+  **Removed `StorageGetMessagesArg` type**
 
-- Adds native @ai-sdk/deepseek provider support instead of using the OpenAI-compatible fallback. ([#10822](https://github.com/mastra-ai/mastra/pull/10822))
+  Use `StorageListMessagesInput` instead:
 
   ```typescript
-  const agent = new Agent({
-    model: 'deepseek/deepseek-reasoner',
-  });
+  // Before
+  import type { StorageGetMessagesArg } from '@mastra/core';
 
-  // With provider options for reasoning
-  const response = await agent.generate('Solve this problem', {
-    providerOptions: {
-      deepseek: {
-        thinking: { type: 'enabled' },
-      },
-    },
-  });
+  // After
+  import type { StorageListMessagesInput } from '@mastra/core';
   ```
 
-  Also updates the doc generation scripts so DeepSeek provider options show up in the generated docs.
+- - Removes modelSettings.abortSignal in favour of top-level abortSignal only. Also removes the deprecated output field - use structuredOutput.schema instead. ([`9e1911d`](https://github.com/mastra-ai/mastra/commit/9e1911db2b4db85e0e768c3f15e0d61e319869f6))
+  - The deprecated generateVNext() and streamVNext() methods have been removed since they're now the stable generate() and stream() methods.
+  - The deprecated `output` option has been removed entirely, in favour of `structuredOutput`.
 
-- Return state too if `includeState: true` is in `outputOptions` and workflow run is not successful ([#10806](https://github.com/mastra-ai/mastra/pull/10806))
+  Method renames to clarify the API surface:
+  - getDefaultGenerateOptions → getDefaultGenerateOptionsLegacy
+  - getDefaultStreamOptions → getDefaultStreamOptionsLegacy
+  - getDefaultVNextStreamOptions → getDefaultStreamOptions
 
-- feat: Add partial response support for agent and workflow list endpoints ([#10886](https://github.com/mastra-ai/mastra/pull/10886))
+- Bump minimum required Node.js version to 22.13.0 ([#9706](https://github.com/mastra-ai/mastra/pull/9706))
 
-  Add optional `partial` query parameter to `/api/agents` and `/api/workflows` endpoints to return minimal data without schemas, reducing payload size for list views:
-  - When `partial=true`: tool schemas (inputSchema, outputSchema) are omitted
-  - When `partial=true`: workflow steps are replaced with stepCount integer
-  - When `partial=true`: workflow root schemas (inputSchema, outputSchema) are omitted
-  - Maintains backward compatibility when partial parameter is not provided
+- 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))
 
-  ## Server Endpoint Usage
+- Add new list methods to storage API: `listMessages`, `listMessagesById`, `listThreadsByResourceId`, and `listWorkflowRuns`. Most methods are currently wrappers around existing methods. Full implementations will be added when migrating away from legacy methods. ([#9489](https://github.com/mastra-ai/mastra/pull/9489))
 
-  ```http
-  # Get partial agent data (no tool schemas)
-  GET /api/agents?partial=true
+- Update tool execution signature ([#9587](https://github.com/mastra-ai/mastra/pull/9587))
 
-  # Get full agent data (default behavior)
-  GET /api/agents
+  Consolidated the 3 different execution contexts to one
 
-  # Get partial workflow data (stepCount instead of steps, no schemas)
-  GET /api/workflows?partial=true
+  ```typescript
+  // before depending on the context the tool was executed in
+  tool.execute({ context: data });
+  tool.execute({ context: { inputData: data } });
+  tool.execute(data);
 
-  # Get full workflow data (default behavior)
-  GET /api/workflows
+  // now, for all contexts
+  tool.execute(data, context);
   ```
 
-  ## Client SDK Usage
+  **Before:**
 
   ```typescript
-  import { MastraClient } from '@mastra/client-js';
-
-  const client = new MastraClient({ baseUrl: 'http://localhost:4111' });
-
-  // Get partial agent list (smaller payload)
-  const partialAgents = await client.listAgents({ partial: true });
-
-  // Get full agent list with tool schemas
-  const fullAgents = await client.listAgents();
+  inputSchema: z.object({ something: z.string() }),
+  execute: async ({ context, tracingContext, runId, ... }) => {
+    return doSomething(context.string);
+  }
+  ```
 
-  // Get partial workflow list (smaller payload)
-  const partialWorkflows = await client.listWorkflows({ partial: true });
+  **After:**
 
-  // Get full workflow list with steps and schemas
-  const fullWorkflows = await client.listWorkflows();
+  ```typescript
+  inputSchema: z.object({ something: z.string() }),
+  execute: async (inputData, context) => {
+    const { agent, mcp, workflow, ...sharedContext } = context
+
+    // context that only an agent would get like toolCallId, messages, suspend, resume, etc
+    if (agent) {
+      doSomething(inputData.something, agent)
+    // context that only a workflow would get like runId, state, suspend, resume, etc
+    } else if (workflow) {
+      doSomething(inputData.something, workflow)
+    // context that only a workflow would get like "extra", "elicitation"
+    } else if (mcp) {
+      doSomething(inputData.something, mcp)
+    } else {
+      // Running a tool in no execution context
+      return doSomething(inputData.something);
+    }
+  }
   ```
 
-- Fix processInputStep so it runs correctly. ([#10909](https://github.com/mastra-ai/mastra/pull/10909))
+- The `@mastra/core` package no longer allows top-level imports except for `Mastra` and `type Config`. You must use subpath imports for all other imports. ([#9544](https://github.com/mastra-ai/mastra/pull/9544))
 
-- Updated dependencies [[`6c59a40`](https://github.com/mastra-ai/mastra/commit/6c59a40e0ad160467bd13d63a8a287028d75b02d), [`3076c67`](https://github.com/mastra-ai/mastra/commit/3076c6778b18988ae7d5c4c5c466366974b2d63f), [`0bada2f`](https://github.com/mastra-ai/mastra/commit/0bada2f2c1234932cf30c1c47a719ffb64b801c5), [`cc60ff6`](https://github.com/mastra-ai/mastra/commit/cc60ff616541a3b0fb531a7e469bf9ae7bb90528)]:
-  - @mastra/observability@1.0.0-beta.3
+  For example:
 
-## 1.0.0-beta.6
+  ```diff
+    import { Mastra, type Config } from "@mastra/core";
+  - import { Agent } from "@mastra/core";
+  - import { createTool } from "@mastra/core";
+  - import { createStep } from "@mastra/core";
 
-### Major Changes
+  + import { Agent } from "@mastra/core/agent";
+  + import { createTool } from "@mastra/core/tools";
+  + import { createStep } from "@mastra/core/workflows";
+  ```
 
-- Changed `.branch()` result schema to make all branch output fields optional. ([#10693](https://github.com/mastra-ai/mastra/pull/10693))
+- This simplifies the Memory API by removing the confusing rememberMessages method and renaming query to recall for better clarity. ([#9701](https://github.com/mastra-ai/mastra/pull/9701))
 
-  **Breaking change**: Branch outputs are now optional since only one branch executes at runtime. Update your workflow schemas to handle optional branch results.
+  The rememberMessages method name implied it might persist data when it was actually just retrieving messages, same as query. Having two methods that did essentially the same thing was unnecessary.
 
-  **Before:**
+  Before:
 
   ```typescript
-  const workflow = createWorkflow({...})
-    .branch([
-      [condition1, stepA],  // outputSchema: { result: z.string() }
-      [condition2, stepB],  // outputSchema: { data: z.number() }
-    ])
-    .map({
-      finalResult: { step: stepA, path: 'result' }  // Expected non-optional
-    });
+  // Two methods that did the same thing
+  memory.rememberMessages({ threadId, resourceId, config, vectorMessageSearch });
+  memory.query({ threadId, resourceId, perPage, vectorSearchString });
   ```
 
-  **After:**
+  After:
 
   ```typescript
-  const workflow = createWorkflow({...})
-    .branch([
-      [condition1, stepA],
-      [condition2, stepB],
-    ])
-    .map({
-      finalResult: {
-        step: stepA,
-        path: 'result'  // Now optional - provide fallback
-      }
-    });
+  // Single unified method with clear purpose
+  memory.recall({ threadId, resourceId, perPage, vectorMessageSearch, threadConfig });
   ```
 
-  **Why**: Branch conditionals execute only one path, so non-executed branches don't produce outputs. The type system now correctly reflects this runtime behavior.
+  All usages have been updated across the codebase including tests. The agent now calls recall directly with the appropriate parameters.
 
-  Related issue: https://github.com/mastra-ai/mastra/issues/10642
+- Rename RuntimeContext to RequestContext ([#9511](https://github.com/mastra-ai/mastra/pull/9511))
 
-### Minor Changes
+- Implement listMessages API for replacing previous methods ([#9531](https://github.com/mastra-ai/mastra/pull/9531))
 
-- Memory system now uses processors. Memory processors (`MessageHistory`, `SemanticRecall`, `WorkingMemory`) are now exported from `@mastra/memory/processors` and automatically added to the agent pipeline based on your memory config. Core processors (`ToolCallFilter`, `TokenLimiter`) remain in `@mastra/core/processors`. ([#9254](https://github.com/mastra-ai/mastra/pull/9254))
+- 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))
 
-- Add reserved keys in RequestContext for secure resourceId/threadId setting from middleware ([#10657](https://github.com/mastra-ai/mastra/pull/10657))
+- **Breaking Change**: Convert OUTPUT generic from `OutputSchema` constraint to plain generic ([#11741](https://github.com/mastra-ai/mastra/pull/11741))
 
-  This allows middleware to securely set `resourceId` and `threadId` via reserved keys in RequestContext (`MASTRA_RESOURCE_ID_KEY` and `MASTRA_THREAD_ID_KEY`), which take precedence over client-provided values for security.
+  This change removes the direct dependency on Zod typings in the public API by converting all `OUTPUT extends OutputSchema` generic constraints to plain `OUTPUT` generics throughout the codebase. This is preparation for moving to a standard schema approach.
+  - All generic type parameters previously constrained to `OutputSchema` (e.g., `<OUTPUT extends OutputSchema = undefined>`) are now plain generics with defaults (e.g., `<OUTPUT = undefined>`)
+  - Affects all public APIs including `Agent`, `MastraModelOutput`, `AgentExecutionOptions`, and stream/generate methods
+  - `InferSchemaOutput<OUTPUT>` replaced with `OUTPUT` throughout
+  - `PartialSchemaOutput<OUTPUT>` replaced with `Partial<OUTPUT>`
+  - Schema fields now use `NonNullable<OutputSchema<OUTPUT>>` instead of `OUTPUT` directly
+  - Added `FullOutput<OUTPUT>` type representing complete output with all fields
+  - Added `AgentExecutionOptionsBase<OUTPUT>` type
+  - `getFullOutput()` method now returns `Promise<FullOutput<OUTPUT>>`
+  - `Agent` class now generic: `Agent<TAgentId, TTools, TOutput>`
+  - `agent.generate()` and `agent.stream()` methods have updated signatures
+  - `MastraModelOutput<OUTPUT>` no longer requires `OutputSchema` constraint
+  - Network route and streaming APIs updated to use plain OUTPUT generic
 
-- feat(workflows): add suspendData parameter to step execute function ([#10734](https://github.com/mastra-ai/mastra/pull/10734))
-
-  Adds a new `suspendData` parameter to workflow step execute functions that provides access to the data originally passed to `suspend()` when the step was suspended. This enables steps to access context about why they were suspended when they are later resumed.
-
-  **New Features:**
-  - `suspendData` parameter automatically populated in step execute function when resuming
-  - Type-safe access to suspend data matching the step's `suspendSchema`
-  - Backward compatible - existing workflows continue to work unchanged
-
-  **Example:**
+  **Before:**
 
   ```typescript
-  const step = createStep({
-    suspendSchema: z.object({ reason: z.string() }),
-    resumeSchema: z.object({ approved: z.boolean() }),
-    execute: async ({ suspend, suspendData, resumeData }) => {
-      if (!resumeData?.approved) {
-        return await suspend({ reason: 'Approval required' });
-      }
-
-      // Access original suspend data when resuming
-      console.log(`Resuming after: ${suspendData?.reason}`);
-      return { result: 'Approved' };
-    },
+  const output = await agent.generate<z.ZodType>([...], {
+    structuredOutput: { schema: mySchema }
   });
-  ```
 
-- feat(storage): support querying messages from multiple threads ([#10663](https://github.com/mastra-ai/mastra/pull/10663))
-  - Fixed TypeScript errors where `threadId: string | string[]` was being passed to places expecting `Scalar` type
-  - Added proper multi-thread support for `listMessages` across all adapters when `threadId` is an array
-  - Updated `_getIncludedMessages` to look up message threadId by ID (since message IDs are globally unique)
-  - **upstash**: Added `msg-idx:{messageId}` index for O(1) message lookups (backwards compatible with fallback to scan for old messages, with automatic backfill)
-
-- Adds trace tagging support to the BrainTrust and Langfuse tracing exporters. ([#10765](https://github.com/mastra-ai/mastra/pull/10765))
+  **After:**
+  const output = await agent.generate<z.infer<typeof mySchema>>([...], {
+    structuredOutput: { schema: mySchema }
+  });
+  // Or rely on type inference:
+  const output = await agent.generate([...], {
+    structuredOutput: { schema: mySchema }
+  });
 
-- Add `messageList` parameter to `processOutputStream` for accessing remembered messages during streaming ([#10608](https://github.com/mastra-ai/mastra/pull/10608))
+  ```
 
-- Unify transformScoreRow functions across storage adapters ([#10648](https://github.com/mastra-ai/mastra/pull/10648))
+- Remove `getThreadsByResourceId` and `getThreadsByResourceIdPaginated` methods from storage interfaces in favor of `listThreadsByResourceId`. The new method uses `offset`/`limit` pagination and a nested `orderBy` object structure (`{ field, direction }`). ([#9536](https://github.com/mastra-ai/mastra/pull/9536))
 
-  Added a unified `transformScoreRow` function in `@mastra/core/storage` that provides schema-driven row transformation for score data. This eliminates code duplication across 10 storage adapters while maintaining store-specific behavior through configurable options:
-  - `preferredTimestampFields`: Preferred source fields for timestamps (PostgreSQL, Cloudflare D1)
-  - `convertTimestamps`: Convert timestamp strings to Date objects (MSSQL, MongoDB, ClickHouse)
-  - `nullValuePattern`: Skip values matching pattern (ClickHouse's `'_null_'`)
-  - `fieldMappings`: Map source column names to schema fields (LibSQL's `additionalLLMContext`)
+- Remove `getMessagesById` method from storage interfaces in favor of `listMessagesById`. The new method only returns V2-format messages and removes the format parameter, simplifying the API surface. Users should migrate from `getMessagesById({ messageIds, format })` to `listMessagesById({ messageIds })`. ([#9534](https://github.com/mastra-ai/mastra/pull/9534))
 
-  Each store adapter now uses the unified function with appropriate options, reducing ~200 lines of duplicate transformation logic while ensuring consistent behavior across all storage backends.
+- Experimental auth -> auth ([#9660](https://github.com/mastra-ai/mastra/pull/9660))
 
-### Patch Changes
+- Renamed a bunch of observability/tracing-related things to drop the AI prefix. ([#9744](https://github.com/mastra-ai/mastra/pull/9744))
 
-- dependencies updates: ([#10110](https://github.com/mastra-ai/mastra/pull/10110))
-  - Updated dependency [`hono-openapi@^1.1.1` ↗︎](https://www.npmjs.com/package/hono-openapi/v/1.1.1) (from `^0.4.8`, in `dependencies`)
+- Removed MastraMessageV3 intermediary format, now we go from MastraDBMessage->aiv5 formats and back directly ([#9094](https://github.com/mastra-ai/mastra/pull/9094))
 
-- unexpected json parse issue, log error but dont fail ([#10241](https://github.com/mastra-ai/mastra/pull/10241))
+- **Breaking Change**: Remove legacy v1 watch events and consolidate on v2 implementation. ([#9252](https://github.com/mastra-ai/mastra/pull/9252))
 
-- Fixed a bug in agent networks where sometimes the task name was empty ([#10629](https://github.com/mastra-ai/mastra/pull/10629))
+  This change simplifies the workflow watching API by removing the legacy v1 event system and promoting v2 as the standard (renamed to just `watch`).
 
-- Adds `tool-result` and `tool-error` chunks to the processor.processOutputStream path. Processors now have access to these two chunks. ([#10645](https://github.com/mastra-ai/mastra/pull/10645))
+  **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
 
-- Include `.input` in workflow results for both engines and remove the option to omit them from Inngest workflows. ([#10688](https://github.com/mastra-ai/mastra/pull/10688))
+- Remove various deprecated APIs from agent class. ([#9257](https://github.com/mastra-ai/mastra/pull/9257))
+  - `agent.llm` → `agent.getLLM()`
+  - `agent.tools` → `agent.getTools()`
+  - `agent.instructions` → `agent.getInstructions()`
+  - `agent.speak()` → `agent.voice.speak()`
+  - `agent.getSpeakers()` → `agent.voice.getSpeakers()`
+  - `agent.listen` → `agent.voice.listen()`
+  - `agent.fetchMemory` → `(await agent.getMemory()).query()`
+  - `agent.toStep` → Add agent directly to the step, workflows handle the transformation
 
-- `getSpeakers` endpoint returns an empty array if voice is not configured on the agent and `getListeners` endpoint returns `{ enabled: false }` if voice is not figured on the agent. ([#10560](https://github.com/mastra-ai/mastra/pull/10560))
+- Pagination APIs now use `page`/`perPage` instead of `offset`/`limit` ([#9592](https://github.com/mastra-ai/mastra/pull/9592))
 
-  When no voice is set on agent don't throw error, by default set voice to undefined rather than DefaultVoice which throws errors when it is accessed.
+  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.
 
-- SimpleAuth and improved CloudAuth ([#10490](https://github.com/mastra-ai/mastra/pull/10490))
+  **Affected APIs:**
+  - `Memory.listThreadsByResourceId()`
+  - `Memory.listMessages()`
+  - `Storage.listWorkflowRuns()`
 
-- When LLMs like Claude Sonnet 4.5 and Gemini 2.4 call tools with all-optional parameters, they send `args: undefined` instead of `args: {}`. This caused validation to fail with "root: Required". ([#10728](https://github.com/mastra-ai/mastra/pull/10728))
+  **Migration:**
 
-  The fix normalizes `undefined`/`null` to `{}` for object schemas and `[]` for array schemas before validation.
+  ```typescript
+  // Before
+  await memory.listThreadsByResourceId({
+    resourceId: 'user-123',
+    offset: 20,
+    limit: 10,
+  });
 
-- Fixed tool validation error messages so logs show Zod validation errors directly instead of hiding them inside structured JSON. ([#10579](https://github.com/mastra-ai/mastra/pull/10579))
+  // After
+  await memory.listThreadsByResourceId({
+    resourceId: 'user-123',
+    page: 2, // page = Math.floor(offset / limit)
+    perPage: 10,
+  });
 
-- Fix error when spreading config objects in Mastra constructor ([#10718](https://github.com/mastra-ai/mastra/pull/10718))
+  // Before
+  await memory.listMessages({
+    threadId: 'thread-456',
+    offset: 20,
+    limit: 10,
+  });
 
-  Adds validation guards to handle undefined/null values that can occur when config objects are spread (`{ ...config }`). Previously, if getters or non-enumerable properties resulted in undefined values during spread, the constructor would throw cryptic errors when accessing `.id` or `.name` on undefined objects.
+  // After
+  await memory.listMessages({
+    threadId: 'thread-456',
+    page: 2,
+    perPage: 10,
+  });
 
-- Fix GPT-5/o3 reasoning models failing with "required reasoning item" errors when using memory with tools. Empty reasoning is now stored with providerMetadata to preserve OpenAI's item_reference. ([#10585](https://github.com/mastra-ai/mastra/pull/10585))
+  // Before
+  await storage.listWorkflowRuns({
+    workflowName: 'my-workflow',
+    offset: 20,
+    limit: 10,
+  });
 
-- Fix generateTitle model type to accept AI SDK LanguageModelV2 ([#10541](https://github.com/mastra-ai/mastra/pull/10541))
+  // After
+  await storage.listWorkflowRuns({
+    workflowName: 'my-workflow',
+    page: 2,
+    perPage: 10,
+  });
+  ```
 
-  Updated the `generateTitle.model` config option to accept `MastraModelConfig` instead of `MastraLanguageModel`. This allows users to pass raw AI SDK `LanguageModelV2` models (e.g., `anthropic.languageModel('claude-3-5-haiku-20241022')`) directly without type errors.
+  **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
 
-  Previously, passing a standard `LanguageModelV2` would fail because `MastraLanguageModelV2` has different `doGenerate`/`doStream` return types. Now `MastraModelConfig` is used consistently across:
-  - `memory/types.ts` - `generateTitle.model` config
-  - `agent.ts` - `genTitle`, `generateTitleFromUserMessage`, `resolveTitleGenerationConfig`
-  - `agent-legacy.ts` - `AgentLegacyCapabilities` interface
+- ```ts ([#9709](https://github.com/mastra-ai/mastra/pull/9709))
+  import { Mastra } from '@mastra/core';
+  import { Observability } from '@mastra/observability'; // Explicit import
 
-- Fix message ordering when using toAISdkV5Messages or prepareStep ([#10686](https://github.com/mastra-ai/mastra/pull/10686))
+  const mastra = new Mastra({
+    ...other_config,
+    observability: new Observability({
+      default: { enabled: true },
+    }), // Instance
+  });
+  ```
 
-  Messages without `createdAt` timestamps were getting shuffled because they all received identical timestamps during conversion. Now messages are assigned monotonically increasing timestamps via `generateCreatedAt()`, preserving input order.
+  Instead of:
 
-  Before:
+  ```ts
+  import { Mastra } from '@mastra/core';
+  import '@mastra/observability/init'; // Explicit import
 
-  ```
-  Input:  [user: "hello", assistant: "Hi!", user: "bye"]
-  Output: [user: "bye", assistant: "Hi!", user: "hello"]  // shuffled!
+  const mastra = new Mastra({
+    ...other_config,
+    observability: {
+      default: { enabled: true },
+    },
+  });
   ```
 
-  After:
+  Also renamed a bunch of:
+  - `Tracing` things to `Observability` things.
+  - `AI-` things to just things.
 
-  ```
-  Input:  [user: "hello", assistant: "Hi!", user: "bye"]
-  Output: [user: "hello", assistant: "Hi!", user: "bye"]  // correct order
-  ```
+- Changing getAgents -> listAgents, getTools -> listTools, getWorkflows -> listWorkflows ([#9495](https://github.com/mastra-ai/mastra/pull/9495))
 
-- Fix Scorer not using custom gateways registered with Mastra ([#10778](https://github.com/mastra-ai/mastra/pull/10778))
+- Removed old tracing code based on OpenTelemetry ([#9237](https://github.com/mastra-ai/mastra/pull/9237))
 
-  Scorers now have access to custom gateways when resolving models. Previously, calling `resolveModelConfig` in the scorer didn't pass the Mastra instance, so custom gateways were never available.
+- Remove deprecated vector prompts and cohere provider from code ([#9596](https://github.com/mastra-ai/mastra/pull/9596))
 
-- Fix workflow run status not being updated from storage snapshot in createRun ([#10664](https://github.com/mastra-ai/mastra/pull/10664))
+- Renamed MastraStorage to MastraCompositeStore for better clarity. The old MastraStorage name remains available as a deprecated alias for backward compatibility, but will be removed in a future version. ([#12093](https://github.com/mastra-ai/mastra/pull/12093))
 
-  When createRun is called with an existing runId, it now correctly updates the run's status from the storage snapshot. This fixes the issue where different workflow instances (e.g., different API requests) would get a run with 'pending' status instead of the correct status from storage (e.g., 'suspended').
+  **Migration:**
 
-- Pass resourceId and threadId to network agent's subAgent when it has its own memory ([#10592](https://github.com/mastra-ai/mastra/pull/10592))
+  Update your imports and usage:
 
-- use `agent.getMemory` to fetch the memory instance on the Agent class to make sure that storage gets set if memory doesn't set it itself. ([#10556](https://github.com/mastra-ai/mastra/pull/10556))
+  ```typescript
+  // Before
+  import { MastraStorage } from '@mastra/core/storage';
 
-- Built-in processors that use internal agents (PromptInjectionDetector, ModerationProcessor, PIIDetector, LanguageDetector, StructuredOutputProcessor) now accept `providerOptions` to control model behavior. ([#10651](https://github.com/mastra-ai/mastra/pull/10651))
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: { ... }
+  });
 
-  This lets you pass provider-specific settings like `reasoningEffort` for OpenAI thinking models:
+  // After
+  import { MastraCompositeStore } from '@mastra/core/storage';
 
-  ```typescript
-  const processor = new PromptInjectionDetector({
-    model: 'openai/o1-mini',
-    threshold: 0.7,
-    strategy: 'block',
-    providerOptions: {
-      openai: {
-        reasoningEffort: 'low',
-      },
-    },
+  const storage = new MastraCompositeStore({
+    id: 'composite',
+    domains: { ... }
   });
   ```
 
-- Improved typing for `workflow.then` to allow the provided steps `inputSchema` to be a subset of the previous steps `outputSchema`. Also errors if the provided steps `inputSchema` is a superset of the previous steps outputSchema. ([#10763](https://github.com/mastra-ai/mastra/pull/10763))
+  The new name better reflects that this is a composite storage implementation that routes different domains (workflows, traces, messages) to different underlying stores, avoiding confusion with the general "Mastra Storage" concept.
 
-- Fix type issue with workflow `.parallel()` when passing multiple steps, one or more of which has a `resumeSchema` provided. ([#10708](https://github.com/mastra-ai/mastra/pull/10708))
+- Mark as stable ([`83d5942`](https://github.com/mastra-ai/mastra/commit/83d5942669ce7bba4a6ca4fd4da697a10eb5ebdc))
 
-- Adds bidirectional integration with otel tracing via a new @mastra/otel-bridge package. ([#10482](https://github.com/mastra-ai/mastra/pull/10482))
-
-- Adds `processInputStep` method to the Processor interface. Unlike `processInput` which runs once at the start, this runs at each step of the agentic loop (including tool call continuations). ([#10650](https://github.com/mastra-ai/mastra/pull/10650))
-
-  ```ts
-  const processor: Processor = {
-    id: 'my-processor',
-    processInputStep: async ({ messages, messageList, stepNumber, systemMessages }) => {
-      // Transform messages at each step before LLM call
-      return messageList;
-    },
-  };
-  ```
+- Changed `.branch()` result schema to make all branch output fields optional. ([#10693](https://github.com/mastra-ai/mastra/pull/10693))
 
-- When using output processors with `agent.generate()`, `result.text` was returning the unprocessed LLM response instead of the processed text. ([#10735](https://github.com/mastra-ai/mastra/pull/10735))
+  **Breaking change**: Branch outputs are now optional since only one branch executes at runtime. Update your workflow schemas to handle optional branch results.
 
   **Before:**
 
-  ```ts
-  const result = await agent.generate('hello');
-  result.text; // "hello world" (unprocessed)
-  result.response.messages[0].content[0].text; // "HELLO WORLD" (processed)
+  ```typescript
+  const workflow = createWorkflow({...})
+    .branch([
+      [condition1, stepA],  // outputSchema: { result: z.string() }
+      [condition2, stepB],  // outputSchema: { data: z.number() }
+    ])
+    .map({
+      finalResult: { step: stepA, path: 'result' }  // Expected non-optional
+    });
   ```
 
   **After:**
 
-  ```ts
-  const result = await agent.generate('hello');
-  result.text; // "HELLO WORLD" (processed)
+  ```typescript
+  const workflow = createWorkflow({...})
+    .branch([
+      [condition1, stepA],
+      [condition2, stepB],
+    ])
+    .map({
+      finalResult: {
+        step: stepA,
+        path: 'result'  // Now optional - provide fallback
+      }
+    });
   ```
 
-  The bug was caused by the `text` delayed promise being resolved twice - first correctly with the processed text, then overwritten with the unprocessed buffered text.
+  **Why**: Branch conditionals execute only one path, so non-executed branches don't produce outputs. The type system now correctly reflects this runtime behavior.
 
-- Refactored default engine to fit durable execution better, and the inngest engine to match. ([#10627](https://github.com/mastra-ai/mastra/pull/10627))
-  Also fixes requestContext persistence by relying on inngest step memoization.
+  Related issue: https://github.com/mastra-ai/mastra/issues/10642
 
-  Unifies some of the stepResults and error formats in both engines.
+- Enforcing id required on Processor primitive ([#9591](https://github.com/mastra-ai/mastra/pull/9591))
 
-- Allow direct access to server app handle directly from Mastra instance. ([#10598](https://github.com/mastra-ai/mastra/pull/10598))
+- **Breaking Changes:** ([#9045](https://github.com/mastra-ai/mastra/pull/9045))
+  - Moved `generateTitle` from `threads.generateTitle` to top-level memory option
+  - Changed default value from `true` to `false`
+  - Using `threads.generateTitle` now throws an error
 
-  ```ts
-  // Before: HTTP request to localhost
-  const response = await fetch(`http://localhost:5000/api/tools`);
+  **Migration:**
+  Replace `threads: { generateTitle: true }` with `generateTitle: true` at the top level of memory options.
 
-  // After: Direct call via app.fetch()
-  const app = mastra.getServerApp<Hono>();
-  const response = await app.fetch(new Request('http://internal/api/tools'));
-  ```
+  **Playground:**
+  The playground UI now displays thread IDs instead of "Chat from" when titles aren't generated.
 
-  - Added `mastra.getServerApp<T>()` to access the underlying Hono/Express app
-  - Added `mastra.getMastraServer()` and `mastra.setMastraServer()` for adapter access
-  - Added `MastraServerBase` class in `@mastra/core/server` for adapter implementations
-  - Server adapters now auto-register with Mastra in their constructor
+- Renamed `MastraMessageV2` to `MastraDBMessage` ([#9255](https://github.com/mastra-ai/mastra/pull/9255))
+  Made the return format of all methods that return db messages consistent. It's always `{ messages: MastraDBMessage[] }` now, and messages can be converted after that using `@mastra/ai-sdk/ui`'s `toAISdkV4/5Messages()` function
 
-- Fix network agent not getting `text-delta` from subAgent when `.stream` is used ([#10533](https://github.com/mastra-ai/mastra/pull/10533))
+- moved ai-tracing code into @mastra/observability ([#9661](https://github.com/mastra-ai/mastra/pull/9661))
 
-- Fix discriminatedUnion schema information lost when json schema is converted to zod ([#10500](https://github.com/mastra-ai/mastra/pull/10500))
+- Remove legacy evals from Mastra ([#9491](https://github.com/mastra-ai/mastra/pull/9491))
 
-- Fix writer.custom not working during workflow resume operations ([#10720](https://github.com/mastra-ai/mastra/pull/10720))
+- Use tool's outputSchema to validate results and return an error object if schema does not match output results. ([#9664](https://github.com/mastra-ai/mastra/pull/9664))
 
-... 5993 more lines hidden. See full changelog in package directory.
+  ```typescript
+  const getUserTool = createTool({
+    id: 'get-user',
+    outputSchema: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string().email(),
+
+... 11704 more lines hidden. See full changelog in package directory.