@mastra/core 1.1.0-alpha.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,369 @@
 # @mastra/core
 
+## 1.1.0
+
+### Minor Changes
+
+- Restructured stored agents to use a thin metadata record with versioned configuration snapshots. ([#12488](https://github.com/mastra-ai/mastra/pull/12488))
+
+  The agent record now only stores metadata fields (id, status, activeVersionId, authorId, metadata, timestamps). All configuration fields (name, instructions, model, tools, etc.) live exclusively in version snapshot rows, enabling full version history and rollback.
+
+  **Key changes:**
+  - Stored Agent records are now thin metadata-only (StorageAgentType)
+  - All config lives in version snapshots (StorageAgentSnapshotType)
+  - New resolved type (StorageResolvedAgentType) merges agent record + active version config
+  - Renamed `ownerId` to `authorId` for multi-tenant filtering
+  - Changed `memory` field type from `string` to `Record<string, unknown>`
+  - Added `status` field ('draft' | 'published') to agent records
+  - Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
+  - Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
+  - List endpoints return resolved agents (thin record + active version config)
+  - Auto-versioning on update with retention limits and race condition handling
+
+- Added dynamic agent management with CRUD operations and version tracking ([#12038](https://github.com/mastra-ai/mastra/pull/12038))
+
+  **New Features:**
+  - Create, edit, and delete agents directly from the Mastra Studio UI
+  - Full version history for agents with compare and restore capabilities
+  - Visual diff viewer to compare agent configurations across versions
+  - Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
+  - AI-powered instruction enhancement
+
+  **Storage:**
+  - New storage interfaces for stored agents and agent versions
+  - PostgreSQL, LibSQL, and MongoDB implementations included
+  - In-memory storage for development and testing
+
+  **API:**
+  - RESTful endpoints for agent CRUD operations
+  - Version management endpoints (create, list, activate, restore, delete, compare)
+  - Automatic versioning on agent updates when enabled
+
+  **Client SDK:**
+  - JavaScript client with full support for stored agents and versions
+  - Type-safe methods for all CRUD and version operations
+
+  **Usage Example:**
+
+  ```typescript
+  // Server-side: Configure storage
+  import { Mastra } from '@mastra/core';
+  import { PgAgentsStorage } from '@mastra/pg';
+
+  const mastra = new Mastra({
+    agents: { agentOne },
+    storage: {
+      agents: new PgAgentsStorage({
+        connectionString: process.env.DATABASE_URL,
+      }),
+    },
+  });
+
+  // Client-side: Use the SDK
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:3000' });
+
+  // Create a stored agent
+  const agent = await client.createStoredAgent({
+    name: 'Customer Support Agent',
+    description: 'Handles customer inquiries',
+    model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
+    instructions: 'You are a helpful customer support agent...',
+    tools: ['search', 'email'],
+  });
+
+  // Create a version snapshot
+  await client.storedAgent(agent.id).createVersion({
+    name: 'v1.0 - Initial release',
+    changeMessage: 'First production version',
+  });
+
+  // Compare versions
+  const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');
+  ```
+
+  **Why:**
+  This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.
+
+- Added unified Workspace API for agent filesystem access, code execution, and search capabilities. ([#11986](https://github.com/mastra-ai/mastra/pull/11986))
+
+  **New Workspace class** combines filesystem, sandbox, and search into a single interface that agents can use for file operations, command execution, and content search.
+
+  **Key features:**
+  - Filesystem operations (read, write, copy, move, delete) through pluggable providers
+  - Code and command execution in secure sandboxed environments with optional OS-level isolation
+  - Keyword search, semantic search, and hybrid search modes
+  - Skills system for discovering and using SKILL.md instruction files
+  - Safety controls including read-before-write guards, approval flows, and read-only mode
+
+  **Usage:**
+
+  ```typescript
+  import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+
+  const workspace = new Workspace({
+    filesystem: new LocalFilesystem({ basePath: './workspace' }),
+    sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+    bm25: true,
+  });
+
+  const agent = new Agent({
+    workspace,
+    // Agent automatically receives workspace tools
+  });
+  ```
+
+- Added `status` field to `listTraces` response. The status field indicates the trace state: `success` (completed without error), `error` (has error), or `running` (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the `error` and `endedAt` fields. ([#12213](https://github.com/mastra-ai/mastra/pull/12213))
+
+- Added `RequestContext.all` to access the entire `RequestContext` object values. ([#12259](https://github.com/mastra-ai/mastra/pull/12259))
+
+  ```typescript
+  const { userId, featureFlags } = requestContext.all;
+  ```
+
+  Added `requestContextSchema` support to tools, agents, workflows, and steps. Define a Zod schema to validate and type requestContext values at runtime.
+
+  **Tool example:**
+
+  ```typescript
+  import { createTool } from '@mastra/core/tools';
+  import { z } from 'zod';
+
+  const myTool = createTool({
+    id: 'my-tool',
+    inputSchema: z.object({ query: z.string() }),
+    requestContextSchema: z.object({
+      userId: z.string(),
+      apiKey: z.string(),
+    }),
+    execute: async (input, context) => {
+      // context.requestContext is typed as RequestContext<{ userId: string, apiKey: string }>
+      const userId = context.requestContext?.get('userId');
+      return { result: 'success' };
+    },
+  });
+  ```
+
+  **Agent example:**
+
+  ```typescript
+  import { Agent } from '@mastra/core/agent';
+  import { z } from 'zod';
+
+  const agent = new Agent({
+    name: 'my-agent',
+    model: openai('gpt-4o'),
+    requestContextSchema: z.object({
+      userId: z.string(),
+      featureFlags: z
+        .object({
+          debugMode: z.boolean().optional(),
+          enableSearch: z.boolean().optional(),
+        })
+        .optional(),
+    }),
+    instructions: ({ requestContext }) => {
+      // Access validated context values with type safety
+      const { userId, featureFlags } = requestContext.all;
+
+      const baseInstructions = `You are a helpful assistant. The current user ID is: ${userId}.`;
+
+      if (featureFlags?.debugMode) {
+        return `${baseInstructions} Debug mode is enabled - provide verbose responses.`;
+      }
+
+      return baseInstructions;
+    },
+    tools: ({ requestContext }) => {
+      const tools: Record<string, any> = {
+        weatherInfo,
+      };
+
+      // Conditionally add tools based on validated feature flags
+      const { featureFlags } = requestContext.all;
+      if (featureFlags?.enableSearch) {
+        tools['web_search_preview'] = openai.tools.webSearchPreview();
+      }
+
+      return tools;
+    },
+  });
+  ```
+
+  **Workflow example:**
+
+  ```typescript
+  import { createWorkflow } from '@mastra/core/workflows';
+  import { z } from 'zod';
+
+  const workflow = createWorkflow({
+    id: 'my-workflow',
+    inputSchema: z.object({ data: z.string() }),
+    requestContextSchema: z.object({
+      tenantId: z.string(),
+    }),
+  });
+
+  const step = createStep({
+    id: 'my-step',
+    description: 'My step description',
+    inputSchema: z.object({ data: z.string() }),
+    outputSchema: z.object({ result: z.string() }),
+    requestContextSchema: z.object({
+      userId: z.string(),
+    }),
+    execute: async ({ inputData, requestContext }) => {
+      const userId = requestContext?.get('userId');
+      return {
+        result: 'some result here',
+      };
+    },
+  });
+
+  workflow.then(step).commit();
+  ```
+
+  When requestContextSchema is defined, validation runs automatically and throws an error if required context values are missing or invalid.
+
+### Patch Changes
+
+- dependencies updates: ([#10184](https://github.com/mastra-ai/mastra/pull/10184))
+  - Updated dependency [`@isaacs/ttlcache@^2.1.4` ↗︎](https://www.npmjs.com/package/@isaacs/ttlcache/v/2.1.4) (from `^1.4.1`, in `dependencies`)
+
+- Update provider registry and model documentation with latest models and providers ([`1cf5d2e`](https://github.com/mastra-ai/mastra/commit/1cf5d2ea1b085be23e34fb506c80c80a4e6d9c2b))
+
+- Fixed skill loading error caused by Zod version conflicts between v3 and v4. Replaced Zod schemas with plain TypeScript validation functions in skill metadata validation. ([#12485](https://github.com/mastra-ai/mastra/pull/12485))
+
+- Fix model router routing providers that use non-default AI SDK packages (e.g. `@ai-sdk/anthropic`, `@ai-sdk/openai`) to their correct SDK instead of falling back to `openai-compatible`. Add `cerebras`, `togetherai`, and `deepinfra` as native SDK providers. ([#12450](https://github.com/mastra-ai/mastra/pull/12450))
+
+- Make suspendedToolRunId nullable to fix the null issue in tool input validation ([#12303](https://github.com/mastra-ai/mastra/pull/12303))
+
+- Fixed agent.network() to properly pass requestContext to workflow runs. Workflow execution now includes user metadata (userId, resourceId) for observability and analytics. (Fixes #12330) ([#12379](https://github.com/mastra-ai/mastra/pull/12379))
+
+- Fix ModelRouterLanguageModel to propagate supportedUrls from underlying model providers ([#12167](https://github.com/mastra-ai/mastra/pull/12167))
+
+  Previously, `ModelRouterLanguageModel` (used when specifying models as strings like `"mistral/mistral-large-latest"` or `"openai/gpt-4o"`) had `supportedUrls` hardcoded as an empty object. This caused Mastra to download all file URLs and convert them to bytes/base64, even when the model provider supports URLs natively.
+
+  This fix:
+  - Changes `supportedUrls` to a lazy `PromiseLike` that resolves the underlying model's supported URL patterns
+  - Updates `llm-execution-step.ts` to properly await `supportedUrls` when preparing messages
+
+  **Impact:**
+  - Mistral: PDF URLs are now passed directly (fixes #12152)
+  - OpenAI: Image URLs (and PDF URLs in response models) are now passed directly
+  - Anthropic: Image URLs are now passed directly
+  - Google: Files from Google endpoints are now passed directly
+
+  **Note:** Users who were relying on Mastra to download files from URLs that model providers cannot directly access (internal URLs, auth-protected URLs) may need to adjust their approach by either using base64-encoded content or ensuring URLs are publicly accessible to the model provider.
+
+- Extended readOnly memory option to also apply to working memory. When readOnly: true, working memory data is provided as context but the updateWorkingMemory tool is not available. ([#12471](https://github.com/mastra-ai/mastra/pull/12471))
+
+  **Example:**
+
+  ```typescript
+  // Working memory is loaded but agent cannot update it
+  const response = await agent.generate('What do you know about me?', {
+    memory: {
+      thread: 'conversation-123',
+      resource: 'user-alice-456',
+      options: { readOnly: true },
+    },
+  });
+  ```
+
+- fix(core): skip non-serializable values in RequestContext.toJSON ([#12344](https://github.com/mastra-ai/mastra/pull/12344))
+
+- Fixed TypeScript error when calling bail() in workflow steps. bail() now accepts any value, so workflows can exit early with a custom result. Fixes #12424. ([#12429](https://github.com/mastra-ai/mastra/pull/12429))
+
+- Fixed type error when using createTool with Agent when exactOptionalPropertyTypes is enabled in TypeScript config. The ProviderDefinedTool structural type now correctly marks inputSchema as optional and allows execute to be undefined, matching the ToolAction interface. Fixes #12281 ([#12325](https://github.com/mastra-ai/mastra/pull/12325))
+
+- Fixed tracingOptions.tags not being preserved when merging defaultOptions with call-site options. Tags set in agent's defaultOptions.tracingOptions are now correctly passed to all observability exporters (Langfuse, Langsmith, Braintrust, Datadog, etc.). Fixes #12209. ([#12220](https://github.com/mastra-ai/mastra/pull/12220))
+
+- Added activeTools parameter support to model loop stream. The activeTools parameter can now be passed through the ModelLoopStreamArgs to control which tools are available during LLM execution. ([#12082](https://github.com/mastra-ai/mastra/pull/12082))
+
+- Fixed agent network crashing with 'Invalid task input' error when routing agent returns malformed JSON for tool/workflow prompts. The error is now fed back to the routing agent, allowing it to retry with valid JSON on the next iteration. ([#12486](https://github.com/mastra-ai/mastra/pull/12486))
+
+- Fixed type error when passing MastraVoice implementations (like OpenAIVoice) directly to Agent's voice config. Previously, the voice property only accepted CompositeVoice, requiring users to wrap their voice provider. Now you can pass any MastraVoice implementation directly. ([#12329](https://github.com/mastra-ai/mastra/pull/12329))
+
+  **Before (required wrapper):**
+
+  ```typescript
+  const agent = new Agent({
+    voice: new CompositeVoice({ output: new OpenAIVoice() }),
+  });
+  ```
+
+  **After (direct usage):**
+
+  ```typescript
+  const agent = new Agent({
+    voice: new OpenAIVoice(),
+  });
+  ```
+
+  Fixes #12293
+
+- Fixed output processors not being applied to messages saved during network execution. When using agent.network(), configured output processors (like TraceIdInjector for feedback attribution) are now correctly applied to all messages before they are saved to storage. ([#12346](https://github.com/mastra-ai/mastra/pull/12346))
+
+- Removed deprecated Google `text-embedding-004` embedding model from the model router. Google shut down this model on January 14, 2026. Use `google/gemini-embedding-001` instead. ([#12433](https://github.com/mastra-ai/mastra/pull/12433))
+
+- Fixed tool input validation failing when LLMs send null for optional fields (#12362). Zod's .optional() only accepts undefined, not null, causing validation errors with Gemini and other LLMs. Validation now retries with null values stripped when the initial attempt fails, so .optional() fields accept null while .nullable() fields continue to work correctly. ([#12396](https://github.com/mastra-ai/mastra/pull/12396))
+
+- Tracing fixes: ([#12370](https://github.com/mastra-ai/mastra/pull/12370))
+  - Spans now inherit entityType/entityId from the closest non-internal parent (#12250)
+  - Processor spans correctly track separate input and output data
+  - Model chunk spans are now emitted for all streaming chunks
+  - Internal framework spans no longer appear in exported traces
+
+- Fixed generated provider types so IDs starting with digits no longer break TypeScript builds ([#12418](https://github.com/mastra-ai/mastra/pull/12418))
+
+- Fixed network mode not applying user-configured input/output processors (like token limiters) to the routing agent. This caused unbounded context growth during network iterations. ([#12074](https://github.com/mastra-ai/mastra/pull/12074))
+
+  User-configured processors are now correctly passed to the routing agent, while memory-derived processors (which could interfere with routing logic) are excluded.
+
+  Fixes #12016
+
+- Fixed repeated build failures caused by stale global cache (~/.cache/mastra/) containing invalid TypeScript in provider-types.generated.d.ts. Provider names starting with digits (e.g. 302ai) are now properly quoted, and the global cache sync validates .d.ts files before copying to prevent corrupted files from overwriting correct ones. ([#12425](https://github.com/mastra-ai/mastra/pull/12425))
+
+- Update @isaacs/ttlcache to v2 and fix import for v2 compatibility (changed from default to named export) ([#10184](https://github.com/mastra-ai/mastra/pull/10184))
+
+- Fixed custom data parts from writer.custom() breaking subsequent messages with Gemini. Messages containing only data-\* parts no longer produce empty content arrays that cause Gemini to fail with 'must include at least one parts field'. ([#12373](https://github.com/mastra-ai/mastra/pull/12373))
+
+- Improve autoresume prompt sent to LLM to ensure gemini resumes well. ([#12320](https://github.com/mastra-ai/mastra/pull/12320))
+  Gemini sometimes doesn't use the previous messages to create inputData for the tool to resume, the prompt was updated to make sure it gets the inputData from the suspended tool call.
+
+- Fixed sub-agents in Agent Networks seeing completion-check feedback from prior iterations, so delegated agents stay focused on their task. Fixes #12224 ([#12338](https://github.com/mastra-ai/mastra/pull/12338))
+
+- Fix TypeScript types for custom API route handlers to include `requestContext` in Hono context Variables. Previously, only `mastra` was typed, causing TypeScript errors when accessing `c.get('requestContext')` even though the runtime correctly provided this context. ([#12419](https://github.com/mastra-ai/mastra/pull/12419))
+
+- Let callers cancel a running agent network call and handle abort callbacks. ([#12351](https://github.com/mastra-ai/mastra/pull/12351))
+
+  **Example**
+  Before:
+
+  ```ts
+  const stream = await agent.network(task);
+  ```
+
+  After:
+
+  ```ts
+  const controller = new AbortController();
+  const stream = await agent.network(task, {
+    abortSignal: controller.signal,
+    onAbort: ({ primitiveType, primitiveId }) => {
+      logger.info(`Aborted ${primitiveType}:${primitiveId}`);
+    },
+  });
+
+  controller.abort();
+  ```
+
+  Related issue: `#12282`
+
+## 1.1.0-alpha.2
+
 ## 1.1.0-alpha.1
 
 ### Minor Changes

package/dist/agent/index.cjs

@@ -1,37 +1,37 @@
 'use strict';
 
-var chunkIKS5Z56O_cjs = require('../chunk-IKS5Z56O.cjs');
+var chunkSLMSUZBA_cjs = require('../chunk-SLMSUZBA.cjs');
 var chunkIUODLQMU_cjs = require('../chunk-IUODLQMU.cjs');
 
 
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.Agent; }
+  get: function () { return chunkSLMSUZBA_cjs.Agent; }
 });
 Object.defineProperty(exports, "TripWire", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.TripWire; }
+  get: function () { return chunkSLMSUZBA_cjs.TripWire; }
 });
 Object.defineProperty(exports, "isSupportedLanguageModel", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.isSupportedLanguageModel; }
+  get: function () { return chunkSLMSUZBA_cjs.isSupportedLanguageModel; }
 });
 Object.defineProperty(exports, "resolveThreadIdFromArgs", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.resolveThreadIdFromArgs; }
+  get: function () { return chunkSLMSUZBA_cjs.resolveThreadIdFromArgs; }
 });
 Object.defineProperty(exports, "supportedLanguageModelSpecifications", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.supportedLanguageModelSpecifications; }
+  get: function () { return chunkSLMSUZBA_cjs.supportedLanguageModelSpecifications; }
 });
 Object.defineProperty(exports, "tryGenerateWithJsonFallback", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.tryGenerateWithJsonFallback; }
+  get: function () { return chunkSLMSUZBA_cjs.tryGenerateWithJsonFallback; }
 });
 Object.defineProperty(exports, "tryStreamWithJsonFallback", {
   enumerable: true,
-  get: function () { return chunkIKS5Z56O_cjs.tryStreamWithJsonFallback; }
+  get: function () { return chunkSLMSUZBA_cjs.tryStreamWithJsonFallback; }
 });
 Object.defineProperty(exports, "MessageList", {
   enumerable: true,

package/dist/agent/index.js

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

package/dist/{chunk-C6YO523J.cjs → chunk-4ACKGMN2.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkIKS5Z56O_cjs = require('./chunk-IKS5Z56O.cjs');
+var chunkSLMSUZBA_cjs = require('./chunk-SLMSUZBA.cjs');
 var chunkRIPKI7ON_cjs = require('./chunk-RIPKI7ON.cjs');
 var chunk4U7ZLI36_cjs = require('./chunk-4U7ZLI36.cjs');
 var pMap = require('p-map');
@@ -291,7 +291,7 @@ async function runEvals(config) {
   };
 }
 function isWorkflow(target) {
-  return target instanceof chunkIKS5Z56O_cjs.Workflow;
+  return target instanceof chunkSLMSUZBA_cjs.Workflow;
 }
 function isWorkflowScorerConfig(scorers) {
   return typeof scorers === "object" && !Array.isArray(scorers) && ("workflow" in scorers || "steps" in scorers);
@@ -382,7 +382,7 @@ async function executeWorkflow(target, item) {
 }
 async function executeAgent(agent, item) {
   const model = await agent.getModel();
-  if (chunkIKS5Z56O_cjs.isSupportedLanguageModel(model)) {
+  if (chunkSLMSUZBA_cjs.isSupportedLanguageModel(model)) {
     return await agent.generate(item.input, {
       scorers: {},
       returnScorerData: true,
@@ -612,5 +612,5 @@ async function saveSingleScore({
 
 exports.createOnScorerHook = createOnScorerHook;
 exports.runEvals = runEvals;
-//# sourceMappingURL=chunk-C6YO523J.cjs.map
-//# sourceMappingURL=chunk-C6YO523J.cjs.map
+//# sourceMappingURL=chunk-4ACKGMN2.cjs.map
+//# sourceMappingURL=chunk-4ACKGMN2.cjs.map