@mastra/core 1.3.0-alpha.2 → 1.4.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,527 @@
 # @mastra/core
 
+## 1.4.0-alpha.0
+
+### Minor Changes
+
+- Added Datasets and Experiments to core. Datasets let you store and version collections of test inputs with JSON Schema validation. Experiments let you run AI outputs against dataset items with configurable scorers to track quality over time. ([#12747](https://github.com/mastra-ai/mastra/pull/12747))
+
+  **New exports from `@mastra/core/datasets`:**
+  - `DatasetsManager` — orchestrates dataset CRUD, item versioning (SCD-2), and experiment execution
+  - `Dataset` — single-dataset handle for adding items and running experiments
+
+  **New storage domains:**
+  - `DatasetsStorage` — abstract base class for dataset persistence (datasets, items, versions)
+  - `ExperimentsStorage` — abstract base class for experiment lifecycle and result tracking
+
+  **Example:**
+
+  ```ts
+  import { Mastra } from '@mastra/core';
+
+  const mastra = new Mastra({
+    /* ... */
+  });
+
+  const dataset = await mastra.datasets.create({ name: 'my-eval-set' });
+  await dataset.addItems([{ input: { query: 'What is 2+2?' }, groundTruth: { answer: '4' } }]);
+
+  const result = await dataset.runExperiment({
+    targetType: 'agent',
+    targetId: 'my-agent',
+    scorerIds: ['accuracy'],
+  });
+  ```
+
+- Fix LocalFilesystem.resolvePath handling of absolute paths and improve filesystem info. ([#12971](https://github.com/mastra-ai/mastra/pull/12971))
+  - Fix absolute path resolution: paths were incorrectly stripped of leading slashes and resolved relative to basePath, causing PermissionError for valid paths (e.g. skills processor accessing project-local skills directories).
+  - Make `FilesystemInfo` generic (`FilesystemInfo<TMetadata>`) so providers can type their metadata.
+  - Move provider-specific fields (`basePath`, `contained`) to metadata in LocalFilesystem.getInfo().
+  - Update LocalFilesystem.getInstructions() for uncontained filesystems to warn agents against listing /.
+  - Use FilesystemInfo type in WorkspaceInfo instead of duplicated inline shape.
+
+- Add `workflow-step-progress` stream event for foreach workflow steps. Each iteration emits a progress event with `completedCount`, `totalCount`, `currentIndex`, `iterationStatus` (`success` | `failed` | `suspended`), and optional `iterationOutput`. Both the default and evented execution engines emit these events. ([#12838](https://github.com/mastra-ai/mastra/pull/12838))
+
+  The Mastra Studio UI now renders a progress bar with an N/total counter on foreach nodes, updating in real time as iterations complete:
+
+  ```ts
+  // Consuming progress events from the workflow stream
+  const run = workflow.createRun();
+  const result = await run.start({ inputData });
+  const stream = result.stream;
+
+  for await (const chunk of stream) {
+    if (chunk.type === 'workflow-step-progress') {
+      console.log(`${chunk.payload.completedCount}/${chunk.payload.totalCount} - ${chunk.payload.iterationStatus}`);
+    }
+  }
+  ```
+
+  `@mastra/react`: The `mapWorkflowStreamChunkToWatchResult` reducer now accumulates `foreachProgress` from `workflow-step-progress` events into step state, making progress data available to React consumers via the existing workflow watch hooks.
+
+- Added observational memory configuration support for stored agents. When creating or editing a stored agent in the playground, you can now enable observational memory and configure its settings including model provider/name, scope (thread or resource), share token budget, and detailed observer/reflector parameters like token limits, buffer settings, and blocking thresholds. The configuration is serialized as part of the agent's memory config and round-trips through storage. ([#12962](https://github.com/mastra-ai/mastra/pull/12962))
+
+  **Example usage in the playground:**
+
+  Enable the Observational Memory toggle in the Memory section, then configure:
+  - Top-level model (provider + model) used by both observer and reflector
+  - Scope: `thread` (per-conversation) or `resource` (shared across threads)
+  - Expand **Observer** or **Reflector** sections to override models and tune token budgets
+
+  **Programmatic usage via client SDK:**
+
+  ```ts
+  await client.createStoredAgent({
+    name: 'My Agent',
+    // ...other config
+    memory: {
+      observationalMemory: true, // enable with defaults
+      options: { lastMessages: 40 },
+    },
+  });
+
+  // Or with custom configuration:
+  await client.createStoredAgent({
+    name: 'My Agent',
+    memory: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        scope: 'resource',
+        shareTokenBudget: true,
+        observation: { messageTokens: 50000 },
+        reflection: { observationTokens: 60000 },
+      },
+      options: { lastMessages: 40 },
+    },
+  });
+  ```
+
+  **Programmatic usage via editor:**
+
+  ```ts
+  await editor.agent.create({
+    name: 'My Agent',
+    // ...other config
+    memory: {
+      observationalMemory: true, // enable with defaults
+      options: { lastMessages: 40 },
+    },
+  });
+
+  // Or with custom configuration:
+  await editor.agent.create({
+    name: 'My Agent',
+    memory: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        scope: 'resource',
+        shareTokenBudget: true,
+        observation: { messageTokens: 50000 },
+        reflection: { observationTokens: 60000 },
+      },
+      options: { lastMessages: 40 },
+    },
+  });
+  ```
+
+- Added MCP client storage domain and ToolProvider interface for integrating external tool catalogs with stored agents. ([#12974](https://github.com/mastra-ai/mastra/pull/12974))
+
+  **MCP Client Storage**
+
+  New storage domain for persisting MCP client configurations with CRUD operations. Each MCP client can contain multiple servers with independent tool selection:
+
+  ```ts
+  // Store an MCP client with multiple servers
+  await storage.mcpClients.create({
+    id: 'my-mcp',
+    name: 'My MCP Client',
+    servers: {
+      'github-server': { url: 'https://mcp.github.com/sse' },
+      'slack-server': { url: 'https://mcp.slack.com/sse' },
+    },
+  });
+  ```
+
+  LibSQL, PostgreSQL, and MongoDB storage adapters all implement the new MCP client domain.
+
+  **ToolProvider Interface**
+
+  New `ToolProvider` interface at `@mastra/core/tool-provider` enables third-party tool catalog integration (e.g., Composio, Arcade AI):
+
+  ```ts
+  import type { ToolProvider } from '@mastra/core/tool-provider';
+
+  # Providers implement: listToolkits(), listTools(), getToolSchema(), resolveTools()
+  ```
+
+  `resolveTools()` receives `requestContext` from the current request, enabling per-user API keys and credentials in multi-tenant setups:
+
+  ```ts
+  const tools = await provider.resolveTools(slugs, configs, {
+    requestContext: { apiKey: 'user-specific-key', userId: 'tenant-123' },
+  });
+  ```
+
+  **Tool Selection Semantics**
+
+  Both `mcpClients` and `integrationTools` on stored agents follow consistent three-state selection:
+  - `{ tools: undefined }` — provider registered, no tools selected
+  - `{ tools: {} }` — all tools from provider included
+  - `{ tools: { 'TOOL_SLUG': { description: '...' } } }` — specific tools with optional overrides
+
+- **Added** ([#12764](https://github.com/mastra-ai/mastra/pull/12764))
+  Added a `suppressFeedback` option to hide internal completion‑check messages from the stream. This keeps the conversation history clean while leaving existing behavior unchanged by default.
+
+  **Example**
+  Before:
+
+  ```ts
+  const agent = await mastra.createAgent({
+    completion: { validate: true },
+  });
+  ```
+
+  After:
+
+  ```ts
+  const agent = await mastra.createAgent({
+    completion: { validate: true, suppressFeedback: true },
+  });
+  ```
+
+- **Split workspace lifecycle interfaces** ([#12978](https://github.com/mastra-ai/mastra/pull/12978))
+
+  The shared `Lifecycle` interface has been split into provider-specific types that match actual usage:
+  - `FilesystemLifecycle` — two-phase: `init()` → `destroy()`
+  - `SandboxLifecycle` — three-phase: `start()` → `stop()` → `destroy()`
+
+  The base `Lifecycle` type is still exported for backward compatibility.
+
+  **Added `onInit` / `onDestroy` callbacks to `MastraFilesystem`**
+
+  The `MastraFilesystem` base class now accepts optional lifecycle callbacks via `MastraFilesystemOptions`, matching the existing `onStart` / `onStop` / `onDestroy` callbacks on `MastraSandbox`.
+
+  ```ts
+  const fs = new LocalFilesystem({
+    basePath: './data',
+    onInit: ({ filesystem }) => {
+      console.log('Filesystem ready:', filesystem.status);
+    },
+    onDestroy: ({ filesystem }) => {
+      console.log('Cleaning up...');
+    },
+  });
+  ```
+
+  `onInit` fires after the filesystem reaches `ready` status (non-fatal on failure). `onDestroy` fires before the filesystem is torn down.
+
+### Patch Changes
+
+- Update provider registry and model documentation with latest models and providers ([`7ef618f`](https://github.com/mastra-ai/mastra/commit/7ef618f3c49c27e2f6b27d7f564c557c0734325b))
+
+- Fixed agent version storage to persist the requestContextSchema field. Previously, requestContextSchema was defined on the agent snapshot type but was not included in the database schema, INSERT statements, or row parsing logic, causing it to be silently dropped when saving and loading agent versions. ([#13003](https://github.com/mastra-ai/mastra/pull/13003))
+
+- Fixed Anthropic API rejection errors caused by empty text content blocks in assistant messages. During streaming with web search citations, empty text parts could be persisted to the database and then rejected by Anthropic's API with 'text content blocks must be non-empty' errors. The fix filters out these empty text blocks before persistence, ensuring stored conversation history remains valid for Anthropic models. Fixes `#12553`. ([#12711](https://github.com/mastra-ai/mastra/pull/12711))
+
+- Improve error messages when processor workflows or model fallback retries fail. ([#12970](https://github.com/mastra-ai/mastra/pull/12970))
+  - Include the last error message and cause when all fallback models are exhausted, instead of the generic "Exhausted all fallback models" message.
+  - Extract error details from failed workflow results and individual step failures when a processor workflow fails, instead of just reporting "failed with status: failed".
+
+- Fixed tool-not-found errors crashing the agentic loop. When a model hallucinates a tool name (e.g., Gemini 3 Flash adding prefixes like `creating:view` instead of `view`), the error is now returned to the model as a tool result instead of throwing. This allows the model to self-correct and retry with the correct tool name on the next turn. The error message includes available tool names to help the model recover. Fixes #12895. ([#12961](https://github.com/mastra-ai/mastra/pull/12961))
+
+- Fixed structured output failing with Anthropic models when memory is enabled. The error "assistant message in the final position" occurred because the prompt sent to Anthropic ended with an assistant-role message, which is not supported when using output format. Resolves https://github.com/mastra-ai/mastra/issues/12800 ([#12835](https://github.com/mastra-ai/mastra/pull/12835))
+
+## 1.3.0
+
+### Minor Changes
+
+- Added mount support to workspaces, so you can combine multiple storage providers (S3, GCS, local disk, etc.) under a single directory tree. This lets agents access files from different sources through one unified filesystem. ([#12851](https://github.com/mastra-ai/mastra/pull/12851))
+
+  **Why:** Previously a workspace could only use one filesystem. With mounts, you can organize files from different providers under different paths — for example, S3 data at `/data` and GCS models at `/models` — without agents needing to know which provider backs each path.
+
+  **What's new:**
+  - Added `CompositeFilesystem` for combining multiple filesystems under one tree
+  - Added descriptive error types for sandbox and mount failures (e.g., `SandboxTimeoutError`, `MountError`)
+  - Improved `MastraFilesystem` and `MastraSandbox` base classes with safer concurrent lifecycle handling
+
+  ```ts
+  import { Workspace, CompositeFilesystem } from '@mastra/core/workspace';
+
+  // Mount multiple filesystems under one tree
+  const composite = new CompositeFilesystem({
+    mounts: {
+      '/data': s3Filesystem,
+      '/models': gcsFilesystem,
+    },
+  });
+
+  const workspace = new Workspace({
+    filesystem: composite,
+    sandbox: e2bSandbox,
+  });
+  ```
+
+- Supporting work to allow for cloning agents via the client SDK ([#12796](https://github.com/mastra-ai/mastra/pull/12796))
+
+- Added `requestContextSchema` and rule-based conditional fields for stored agents. ([#12896](https://github.com/mastra-ai/mastra/pull/12896))
+
+  Stored agent fields (`tools`, `model`, `workflows`, `agents`, `memory`, `scorers`, `inputProcessors`, `outputProcessors`, `defaultOptions`) can now be configured as conditional variants with rule groups that evaluate against request context at runtime. All matching variants accumulate — arrays are concatenated and objects are shallow-merged — so agents dynamically compose their configuration based on the incoming request context.
+
+  **New `requestContextSchema` field**
+
+  Stored agents now accept an optional `requestContextSchema` (JSON Schema) that is converted to a Zod schema and passed to the Agent constructor, enabling request context validation.
+
+  **Conditional field example**
+
+  ```ts
+  await agentsStore.create({
+    agent: {
+      id: 'my-agent',
+      name: 'My Agent',
+      instructions: 'You are a helpful assistant',
+      model: { provider: 'openai', name: 'gpt-4' },
+      tools: [
+        { value: { 'basic-tool': {} } },
+        {
+          value: { 'premium-tool': {} },
+          rules: {
+            operator: 'AND',
+            conditions: [{ field: 'tier', operator: 'equals', value: 'premium' }],
+          },
+        },
+      ],
+      requestContextSchema: {
+        type: 'object',
+        properties: { tier: { type: 'string' } },
+      },
+    },
+  });
+  ```
+
+- Implement underlying storage changes to allow for dynamic instructions in stored agents (for `@mastra/editor`) ([#12776](https://github.com/mastra-ai/mastra/pull/12776))
+
+- Add native `@ai-sdk/groq` support to model router. Groq models now use the official AI SDK package instead of falling back to OpenAI-compatible mode. ([#12741](https://github.com/mastra-ai/mastra/pull/12741))
+
+- **Added stored scorer definitions, editor namespace pattern, and generic storage domains** ([#12846](https://github.com/mastra-ai/mastra/pull/12846))
+  - Added a new `scorer-definitions` storage domain for storing LLM-as-judge and preset scorer configurations in the database
+  - Introduced a `VersionedStorageDomain` generic base class that unifies `AgentsStorage`, `PromptBlocksStorage`, and `ScorerDefinitionsStorage` with shared CRUD methods (`create`, `getById`, `getByIdResolved`, `update`, `delete`, `list`, `listResolved`)
+  - Flattened stored scorer type system: replaced nested `preset`/`customLLMJudge` config with top-level `type`, `instructions`, `scoreRange`, and `presetConfig` fields
+  - Refactored `MastraEditor` to use a namespace pattern (`editor.agent.*`, `editor.scorer.*`, `editor.prompt.*`) backed by a `CrudEditorNamespace` base class with built-in caching and an `onCacheEvict` hook
+  - Added `rawConfig` support to `MastraBase` and `MastraScorer` via `toRawConfig()`, so hydrated primitives carry their stored configuration
+  - Added prompt block and scorer registration to the `Mastra` class (`addPromptBlock`, `removePromptBlock`, `addScorer`, `removeScorer`)
+
+  **Creating a stored scorer (LLM-as-judge):**
+
+  ```ts
+  const scorer = await editor.scorer.create({
+    id: 'my-scorer',
+    name: 'Response Quality',
+    type: 'llm-judge',
+    instructions: 'Evaluate the response for accuracy and helpfulness.',
+    model: { provider: 'openai', name: 'gpt-4o' },
+    scoreRange: { min: 0, max: 1 },
+  });
+  ```
+
+  **Retrieving and resolving a stored scorer:**
+
+  ```ts
+  // Fetch the stored definition from DB
+  const definition = await editor.scorer.getById('my-scorer');
+
+  // Resolve it into a runnable MastraScorer instance
+  const runnableScorer = editor.scorer.resolve(definition);
+
+  // Execute the scorer
+  const result = await runnableScorer.run({
+    input: 'What is the capital of France?',
+    output: 'The capital of France is Paris.',
+  });
+  ```
+
+  **Editor namespace pattern (before/after):**
+
+  ```ts
+  // Before
+  const agent = await editor.getStoredAgentById('abc');
+  const prompts = await editor.listPromptBlocks();
+
+  // After
+  const agent = await editor.agent.getById('abc');
+  const prompts = await editor.prompt.list();
+  ```
+
+  **Generic storage domain methods (before/after):**
+
+  ```ts
+  // Before
+  const store = storage.getStore('agents');
+  await store.createAgent({ agent: input });
+  await store.getAgentById({ id: 'abc' });
+  await store.deleteAgent({ id: 'abc' });
+
+  // After
+  const store = storage.getStore('agents');
+  await store.create({ agent: input });
+  await store.getById('abc');
+  await store.delete('abc');
+  ```
+
+- Added mount status and error information to filesystem directory listings, so the UI can show whether each mount is healthy or has issues. Improved error handling when mount operations fail. Fixed tree formatter to use case-insensitive sorting to match native tree output. ([#12605](https://github.com/mastra-ai/mastra/pull/12605))
+
+- Added workspace registration and tool context support. ([#12607](https://github.com/mastra-ai/mastra/pull/12607))
+
+  **Why** - Makes it easier to manage multiple workspaces at runtime and lets tools read/write files in the intended workspace.
+
+  **Workspace Registration** - Added a workspace registry so you can list and fetch workspaces by id with `addWorkspace()`, `getWorkspaceById()`, and `listWorkspaces()`. Agent workspaces are auto-registered when adding agents.
+
+  **Before**
+
+  ```typescript
+  const mastra = new Mastra({ workspace: myWorkspace });
+  // No way to look up workspaces by id or list all workspaces
+  ```
+
+  **After**
+
+  ```typescript
+  const mastra = new Mastra({ workspace: myWorkspace });
+
+  // Look up by id
+  const ws = mastra.getWorkspaceById('my-workspace');
+
+  // List all registered workspaces
+  const allWorkspaces = mastra.listWorkspaces();
+
+  // Register additional workspaces
+  mastra.addWorkspace(anotherWorkspace);
+  ```
+
+  **Tool Workspace Access** - Tools can access the workspace through `context.workspace` during execution, enabling filesystem and sandbox operations.
+
+  ```typescript
+  const myTool = createTool({
+    id: 'file-reader',
+    execute: async ({ context }) => {
+      const fs = context.workspace?.filesystem;
+      const content = await fs?.readFile('config.json');
+      return { content };
+    },
+  });
+  ```
+
+  **Dynamic Workspace Configuration** - Workspace can be configured dynamically via agent config functions. Dynamically created workspaces are auto-registered with Mastra, making them available via `listWorkspaces()`.
+
+  ```typescript
+  const agent = new Agent({
+    workspace: ({ mastra, requestContext }) => {
+      // Return workspace dynamically based on context
+      const workspaceId = requestContext?.get('workspaceId') || 'default';
+      return mastra.getWorkspaceById(workspaceId);
+    },
+  });
+  ```
+
+- Add tool description overrides for stored agents: ([#12794](https://github.com/mastra-ai/mastra/pull/12794))
+  - Changed stored agent `tools` field from `string[]` to `Record<string, { description?: string }>` to allow per-tool description overrides
+  - When a stored agent specifies a custom `description` for a tool, the override is applied at resolution time
+  - Updated server API schemas, client SDK types, and editor resolution logic accordingly
+
+- **Breaking:** Removed `cloneAgent()` from the `Agent` class. Agent cloning is now handled by the editor package via `editor.agent.clone()`. ([#12904](https://github.com/mastra-ai/mastra/pull/12904))
+
+  If you were calling `agent.cloneAgent()` directly, use the editor's agent namespace instead:
+
+  ```ts
+  // Before
+  const result = await agent.cloneAgent({ newId: 'my-clone' });
+
+  // After
+  const editor = mastra.getEditor();
+  const result = await editor.agent.clone(agent, { newId: 'my-clone' });
+  ```
+
+  **Why:** The `Agent` class should not be responsible for storage serialization. The editor package already handles converting between runtime agents and stored configurations, so cloning belongs there.
+
+  **Added** `getConfiguredProcessorIds()` to the `Agent` class, which returns raw input/output processor IDs for the agent's configuration.
+
+### Patch Changes
+
+- Update provider registry and model documentation with latest models and providers ([`717ffab`](https://github.com/mastra-ai/mastra/commit/717ffab42cfd58ff723b5c19ada4939997773004))
+
+- Fixed observational memory progress bars resetting to zero after agent responses finish. ([#12934](https://github.com/mastra-ai/mastra/pull/12934))
+
+- Fixed issues with stored agents ([#12790](https://github.com/mastra-ai/mastra/pull/12790))
+
+- Fixed sub-agent tool approval and suspend events not being surfaced to the parent agent stream. This enables proper suspend/resume workflows and approval handling when nested agents require tool approvals. ([#12732](https://github.com/mastra-ai/mastra/pull/12732))
+
+  Related to issue #12552.
+
+- Fixed stale agent data in CMS pages by adding removeAgent method to Mastra and updating clearStoredAgentCache to clear both Editor cache and Mastra registry when stored agents are updated or deleted ([#12693](https://github.com/mastra-ai/mastra/pull/12693))
+
+- Fixed stored scorers not being registered on the Mastra instance. Scorers created via the editor are now automatically discoverable through `mastra.getScorer()` and `mastra.getScorerById()`, matching the existing behavior of stored agents. Previously, stored scorers could only be resolved inline but were invisible to the runtime registry, causing lookups to fail. ([#12903](https://github.com/mastra-ai/mastra/pull/12903))
+
+- Fixed `generateTitle` running on every conversation turn instead of only the first, which caused redundant title generation calls. This happened when `lastMessages` was disabled or set to `false`. Titles are now correctly generated only on the first turn. ([#12890](https://github.com/mastra-ai/mastra/pull/12890))
+
+- Fixed workflow step errors not being propagated to the configured Mastra logger. The execution engine now properly propagates the Mastra logger through the inheritance chain, and the evented step executor logs errors with structured MastraError context (matching the default engine behavior). Closes #12793 ([#12834](https://github.com/mastra-ai/mastra/pull/12834))
+
+- Update memory config and exports: ([#12704](https://github.com/mastra-ai/mastra/pull/12704))
+  - Updated `SerializedMemoryConfig` to allow `embedder?: EmbeddingModelId | string` for flexibility
+  - Exported `EMBEDDING_MODELS` and `EmbeddingModelInfo` for use in server endpoints
+
+- Fixed a catch-22 where third-party AI SDK providers (like `ollama-ai-provider-v2`) were rejected by both `stream()` and `streamLegacy()` due to unrecognized `specificationVersion` values. ([#12856](https://github.com/mastra-ai/mastra/pull/12856))
+
+  When a model has a `specificationVersion` that isn't `'v1'`, `'v2'`, or `'v3'` (e.g., from a third-party provider), two fixes now apply:
+  1. **Auto-wrapping in `resolveModelConfig()`**: Models with unknown spec versions that have `doStream`/`doGenerate` methods are automatically wrapped as AI SDK v5 models, preventing the catch-22 entirely.
+  2. **Improved error messages**: If a model still reaches the version check, error messages now show the actual unrecognized `specificationVersion` instead of creating circular suggestions between `stream()` and `streamLegacy()`.
+
+- Fixed routing output so users only see the final answer when routing handles a request directly. Previously, an internal routing explanation appeared before the answer and was duplicated. Fixes #12545. ([#12786](https://github.com/mastra-ai/mastra/pull/12786))
+
+- Supporting changes for async buffering in observational memory, including new config options, streaming events, and UI markers. ([#12891](https://github.com/mastra-ai/mastra/pull/12891))
+
+- Fixed an issue where processor retry (via `abort({ retry: true })` in `processOutputStep`) would send the rejected assistant response back to the LLM on retry. This confused models and often caused empty text responses. The rejected response is now removed from the message list before the retry iteration. ([#12799](https://github.com/mastra-ai/mastra/pull/12799))
+
+- Fixed Moonshot AI (moonshotai and moonshotai-cn) models using the wrong base URL. The Anthropic-compatible endpoint was not being applied, causing API calls to fail with an upstream LLM error. ([#12750](https://github.com/mastra-ai/mastra/pull/12750))
+
+- Fixed messages not being persisted to the database when using the stream-legacy endpoint. The thread is now saved to the database immediately when created, preventing a race condition where storage backends like PostgreSQL would reject message inserts because the thread didn't exist yet. Fixes #12566. ([#12774](https://github.com/mastra-ai/mastra/pull/12774))
+
+- When calling `mastra.setLogger()`, memory instances were not being updated with the new logger. This caused memory-related errors to be logged via the default ConsoleLogger instead of the configured logger. ([#12905](https://github.com/mastra-ai/mastra/pull/12905))
+
+- Fixed tool input validation failing when LLMs return stringified JSON for array or object parameters. Some models (e.g., GLM4.7) send `"[\"file.py\"]"` instead of `["file.py"]` for array fields, which caused Zod validation to reject the input. The validation pipeline now automatically detects and parses stringified JSON values when the schema expects an array or object. (GitHub #12757) ([#12771](https://github.com/mastra-ai/mastra/pull/12771))
+
+- Fixed working memory tools being injected when no thread or resource context is provided. Made working memory tool execute scope-aware: thread-scoped requires threadId, resource-scoped requires resourceId (previously both were always required regardless of scope). ([#12831](https://github.com/mastra-ai/mastra/pull/12831))
+
+- Fixed a crash when using agent workflows that have no input schema. Input now passes through on first invocation, so workflows run instead of failing. (#12739) ([#12785](https://github.com/mastra-ai/mastra/pull/12785))
+
+- Fixes issue where client tools could not be used with agent.network(). Client tools configured in an agent's defaultOptions will now be available during network execution. ([#12821](https://github.com/mastra-ai/mastra/pull/12821))
+
+  Fixes #12752
+
+- Steps now support an optional `metadata` property for storing arbitrary key-value data. This metadata is preserved through step serialization and is available in the workflow graph, enabling use cases like UI annotations or custom step categorization. ([#12861](https://github.com/mastra-ai/mastra/pull/12861))
+
+  ```diff
+  import { createStep } from "@mastra/core/workflows";
+  import { z } from "zod";
+
+  const step = createStep({
+    //...step information
+  +  metadata: {
+  +    category: "orders",
+  +    priority: "high",
+  +    version: "1.0.0",
+  +  },
+  });
+  ```
+
+  Metadata values must be serializable (no functions or circular references).
+
+- Fixed: You can now pass workflows with a `requestContextSchema` to the Mastra constructor without a type error. Related: #12773. ([#12857](https://github.com/mastra-ai/mastra/pull/12857))
+
+- Fixed TypeScript type errors when using `.optional().default()` in workflow input schemas. Workflows with default values in their schemas no longer produce false type errors when chaining steps with `.then()`. Fixes #12634 ([#12778](https://github.com/mastra-ai/mastra/pull/12778))
+
+- Fix setLogger to update workflow loggers ([#12889](https://github.com/mastra-ai/mastra/pull/12889))
+
+  When calling `mastra.setLogger()`, workflows were not being updated with the new logger. This caused workflow errors to be logged via the default ConsoleLogger instead of the configured logger (e.g., PinoLogger with HttpTransport), resulting in missing error logs in Cloud deployments.
+
 ## 1.3.0-alpha.2
 
 ### Patch Changes

package/datasets.d.ts

@@ -0,0 +1 @@
+export * from './dist/datasets';

package/dist/agent/agent.d.ts

@@ -79,7 +79,7 @@ export declare class Agent<TAgentId extends string = string, TTools extends Tool
      * ```
      */
     constructor(config: AgentConfig<TAgentId, TTools, TOutput, TRequestContext>);
-    getMastraInstance(): Mastra<Record<string, Agent<any, ToolsInput, undefined, unknown>>, Record<string, AnyWorkflow>, Record<string, import("..").MastraVectorProvider<any>>, Record<string, import("../tts").MastraTTS>, import("..").Logger, Record<string, import("../mcp").MCPServerBase<any>>, Record<string, MastraScorer<any, any, any, any>>, Record<string, import("..").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, Processor<any, unknown>>, Record<string, MastraMemory>> | undefined;
+    getMastraInstance(): Mastra<Record<string, Agent<any, ToolsInput, undefined, unknown>>, Record<string, AnyWorkflow>, Record<string, import("../vector").MastraVector<any>>, Record<string, import("../tts").MastraTTS>, import("../logger").IMastraLogger, Record<string, import("../mcp").MCPServerBase<any>>, Record<string, MastraScorer<any, any, any, any>>, Record<string, import("../tools").ToolAction<any, any, any, any, any, any, unknown>>, Record<string, Processor<any, unknown>>, Record<string, MastraMemory>> | undefined;
     /**
      * Gets the skills processors to add to input processors when workspace has skills.
      * @internal

package/dist/agent/index.cjs

@@ -1,53 +1,53 @@
 'use strict';
 
-var chunkFLHFB23E_cjs = require('../chunk-FLHFB23E.cjs');
-var chunkUE2G2LRP_cjs = require('../chunk-UE2G2LRP.cjs');
+var chunkUQ4SRS66_cjs = require('../chunk-UQ4SRS66.cjs');
+var chunkCZ4NQANZ_cjs = require('../chunk-CZ4NQANZ.cjs');
 
 
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.Agent; }
+  get: function () { return chunkUQ4SRS66_cjs.Agent; }
 });
 Object.defineProperty(exports, "TripWire", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.TripWire; }
+  get: function () { return chunkUQ4SRS66_cjs.TripWire; }
 });
 Object.defineProperty(exports, "isSupportedLanguageModel", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.isSupportedLanguageModel; }
+  get: function () { return chunkUQ4SRS66_cjs.isSupportedLanguageModel; }
 });
 Object.defineProperty(exports, "resolveThreadIdFromArgs", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.resolveThreadIdFromArgs; }
+  get: function () { return chunkUQ4SRS66_cjs.resolveThreadIdFromArgs; }
 });
 Object.defineProperty(exports, "supportedLanguageModelSpecifications", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.supportedLanguageModelSpecifications; }
+  get: function () { return chunkUQ4SRS66_cjs.supportedLanguageModelSpecifications; }
 });
 Object.defineProperty(exports, "tryGenerateWithJsonFallback", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.tryGenerateWithJsonFallback; }
+  get: function () { return chunkUQ4SRS66_cjs.tryGenerateWithJsonFallback; }
 });
 Object.defineProperty(exports, "tryStreamWithJsonFallback", {
   enumerable: true,
-  get: function () { return chunkFLHFB23E_cjs.tryStreamWithJsonFallback; }
+  get: function () { return chunkUQ4SRS66_cjs.tryStreamWithJsonFallback; }
 });
 Object.defineProperty(exports, "MessageList", {
   enumerable: true,
-  get: function () { return chunkUE2G2LRP_cjs.MessageList; }
+  get: function () { return chunkCZ4NQANZ_cjs.MessageList; }
 });
 Object.defineProperty(exports, "TypeDetector", {
   enumerable: true,
-  get: function () { return chunkUE2G2LRP_cjs.TypeDetector; }
+  get: function () { return chunkCZ4NQANZ_cjs.TypeDetector; }
 });
 Object.defineProperty(exports, "aiV5ModelMessageToV2PromptMessage", {
   enumerable: true,
-  get: function () { return chunkUE2G2LRP_cjs.aiV5ModelMessageToV2PromptMessage; }
+  get: function () { return chunkCZ4NQANZ_cjs.aiV5ModelMessageToV2PromptMessage; }
 });
 Object.defineProperty(exports, "convertMessages", {
   enumerable: true,
-  get: function () { return chunkUE2G2LRP_cjs.convertMessages; }
+  get: function () { return chunkCZ4NQANZ_cjs.convertMessages; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/agent/index.js

@@ -1,4 +1,4 @@
-export { Agent, TripWire, isSupportedLanguageModel, resolveThreadIdFromArgs, supportedLanguageModelSpecifications, tryGenerateWithJsonFallback, tryStreamWithJsonFallback } from '../chunk-ZRUTE56J.js';
-export { MessageList, TypeDetector, aiV5ModelMessageToV2PromptMessage, convertMessages } from '../chunk-ILQXPZCD.js';
+export { Agent, TripWire, isSupportedLanguageModel, resolveThreadIdFromArgs, supportedLanguageModelSpecifications, tryGenerateWithJsonFallback, tryStreamWithJsonFallback } from '../chunk-4X2YMIAC.js';
+export { MessageList, TypeDetector, aiV5ModelMessageToV2PromptMessage, convertMessages } from '../chunk-AY6DBRS3.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/agent/message-list/adapters/AIV4Adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIV4Adapter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/adapters/AIV4Adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,WAAW,EACxB,WAAW,IAAI,aAAa,EAE7B,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EACV,eAAe,EAIf,aAAa,EACb,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAYxB,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAEtC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,YAAY,IAAI,MAAM,CAAC;IACvB,iBAAiB,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACvE,mDAAmD;IACnD,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,eAAe,GAAG,qBAAqB;IAiJ7D;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa;IAsB9D;;OAEG;IACH,MAAM,CAAC,aAAa,CAClB,OAAO,EAAE,WAAW,GAAG,qBAAqB,EAC5C,GAAG,EAAE,kBAAkB,EACvB,aAAa,EAAE,aAAa,GAC3B,eAAe;IA2BlB;;OAEG;IACH,MAAM,CAAC,eAAe,CACpB,WAAW,EAAE,aAAa,EAC1B,GAAG,EAAE,kBAAkB,EACvB,aAAa,EAAE,aAAa,GAC3B,eAAe;CA+OnB"}
+{"version":3,"file":"AIV4Adapter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/adapters/AIV4Adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,WAAW,EACxB,WAAW,IAAI,aAAa,EAE7B,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EACV,eAAe,EAIf,aAAa,EACb,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AA8BxB,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAEtC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,YAAY,IAAI,MAAM,CAAC;IACvB,iBAAiB,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACvE,mDAAmD;IACnD,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,eAAe,GAAG,qBAAqB;IAiJ7D;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa;IAsB9D;;OAEG;IACH,MAAM,CAAC,aAAa,CAClB,OAAO,EAAE,WAAW,GAAG,qBAAqB,EAC5C,GAAG,EAAE,kBAAkB,EACvB,aAAa,EAAE,aAAa,GAC3B,eAAe;IA8BlB;;OAEG;IACH,MAAM,CAAC,eAAe,CACpB,WAAW,EAAE,aAAa,EAC1B,GAAG,EAAE,kBAAkB,EACvB,aAAa,EAAE,aAAa,GAC3B,eAAe;CAkPnB"}

package/dist/agent/message-list/adapters/AIV5Adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIV5Adapter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/adapters/AIV5Adapter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAA0B,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAmCzC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,YAAY,CAAC,IAAI,MAAM,CAAC;IACxB,iBAAiB,CAAC,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzE;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAAC,SAAS;IA8N9D;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,GAAG,eAAe;IAgMhE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAyC5C;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,EAAE,aAAa,GAAG,eAAe;CAkM1G"}
+{"version":3,"file":"AIV5Adapter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/adapters/AIV5Adapter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAA6C,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAqDzC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,YAAY,CAAC,IAAI,MAAM,CAAC;IACxB,iBAAiB,CAAC,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzE;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAAC,SAAS;IA8N9D;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,GAAG,eAAe;IAmMhE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAyC5C;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,EAAE,aAAa,GAAG,eAAe;CAoL1G"}

package/dist/agent/message-list/conversion/output-converter.d.ts

@@ -8,7 +8,8 @@ import type { AIV5Type } from '../types.js';
  */
 export declare function sanitizeAIV4UIMessages(messages: UIMessageV4[]): UIMessageV4[];
 /**
- * Sanitizes AIV5 UI messages by filtering out streaming states, data-* parts, and optionally incomplete tool calls.
+ * Sanitizes AIV5 UI messages by filtering out streaming states, data-* parts, empty text parts, and optionally incomplete tool calls.
+ * Handles legacy data by filtering empty text parts that may exist in pre-existing DB records.
  */
 export declare function sanitizeV5UIMessages(messages: AIV5Type.UIMessage[], filterIncompleteToolCalls?: boolean): AIV5Type.UIMessage[];
 /**

package/dist/agent/message-list/conversion/output-converter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-converter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/conversion/output-converter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,IAAI,aAAa,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIlG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzC;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CA6B7E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,EAC9B,yBAAyB,UAAQ,GAChC,QAAQ,CAAC,SAAS,EAAE,CAiDtB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,CAe7F;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,CAEzF;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,EAC9B,UAAU,EAAE,eAAe,EAAE,EAC7B,yBAAyB,UAAQ,GAChC,QAAQ,CAAC,YAAY,EAAE,CA2BzB;AAED;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,aAAa,EAAE,EACzB,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,cAAc,EAC9B,UAAU,EAAE,eAAe,EAAE,GAC5B,QAAQ,CAAC,YAAY,EAAE,CAKzB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,GAAG,QAAQ,CAAC,YAAY,GAAG,eAAe,GAAG,MAAM,GACxE,aAAa,CAef"}
+{"version":3,"file":"output-converter.d.ts","sourceRoot":"","sources":["../../../../src/agent/message-list/conversion/output-converter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,IAAI,aAAa,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIlG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzC;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CA6B7E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,EAC9B,yBAAyB,UAAQ,GAChC,QAAQ,CAAC,SAAS,EAAE,CA0DtB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,CAe7F;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,CAEzF;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,EAC9B,UAAU,EAAE,eAAe,EAAE,EAC7B,yBAAyB,UAAQ,GAChC,QAAQ,CAAC,YAAY,EAAE,CA2BzB;AAED;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,aAAa,EAAE,EACzB,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,cAAc,EAC9B,UAAU,EAAE,eAAe,EAAE,GAC5B,QAAQ,CAAC,YAAY,EAAE,CAKzB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,GAAG,QAAQ,CAAC,YAAY,GAAG,eAAe,GAAG,MAAM,GACxE,aAAa,CAef"}