@mastra/server 2.0.2 → 2.0.3-alpha.0

package/README.md

@@ -1,159 +1,74 @@
-# @mastra/deployer
+# @mastra/server
 
-Core deployment infrastructure for Mastra applications, handling build, packaging, and deployment processes.
+Typed HTTP handlers and utilities for exposing a `Mastra` instance over HTTP.
+This package powers `mastra dev` and can be added to your own server to provide
+REST and streaming endpoints for agents, workflows, telemetry and more.
 
 ## Installation
 
 ```bash
-npm install @mastra/deployer
+npm install @mastra/server
 ```
 
-## Overview
-
-The `@mastra/deployer` package provides the foundational deployment infrastructure for Mastra applications. It handles:
-
-- Project building and bundling
-- Dependency management
-- Environment configuration
-- Development and production deployments
-
 ## Usage
 
-```typescript
-import { Deployer } from '@mastra/deployer';
+The handlers are framework agnostic functions which accept a `Mastra` instance
+and a request context. They are typically mounted under a URL prefix within your
+web framework of choice:
 
-// Create a deployer instance
-const deployer = new Deployer({
-  dir: '/path/to/project',
-  type: 'Deploy', // or 'Dev' for development mode
+```typescript
+import { Hono } from 'hono';
+import { handlers } from '@mastra/server';
+import { mastra } from './mastra-instance';
+
+const app = new Hono();
+
+app.get('/mastra/agents', ctx =>
+  handlers.agents.getAgentsHandler({ mastra, runtimeContext: ctx }),
+);
+app.post('/mastra/agents/:id/generate', async ctx => {
+  const body = await ctx.req.json();
+  return handlers.agents.generateHandler({
+    mastra,
+    runtimeContext: ctx,
+    agentId: ctx.req.param('id'),
+    body,
+  });
 });
 
-// Install dependencies
-await deployer.install();
-
-// Write package.json
-await deployer.writePackageJson();
-
-// Get Mastra instance
-const { mastra } = await deployer.getMastra();
+// Mount additional handlers as required
 ```
 
-## Configuration
-
-### Required Parameters
-
-- `dir`: Project directory path
-- `type`: Deployment type ('Deploy' or 'Dev')
+Running `mastra dev` starts a local development UI at
+`http://localhost:3000` using these handlers.
 
-## Features
+## Available Handler Groups
 
-### Project Structure Management
+- **Agents** - list defined agents, retrieve metadata, and run `generate`
+  or `stream`.
+- **Workflows** - start and inspect workflow runs.
+- **Tools** - discover tools available to the `Mastra` instance.
+- **Memory** - interact with configured memory stores.
+- **Logs** - query runtime logs when a supporting logger transport is used.
+- **Telemetry** - expose metrics produced by the telemetry subsystem.
+- **Networks** - interact with agent networks.
+- **Vector / Voice** - endpoints related to vector stores and voice synthesis.
 
-- Creates and manages `.mastra` directory
-- Handles package.json generation and updates
-- Manages project dependencies
+Handlers return JSON serialisable data and throw an `HTTPException` (subclass of
+`Error`) when a failure should result in a non-2xx HTTP status.
 
-### Dependency Management
+## OpenAPI Spec Generation
 
-- Automatic dependency installation
-- Workspace dependency resolution
-- Version management for @mastra packages
+The local OpenAPI specification used by the CLI playground and similar tools can
+be refreshed by running:
 
-### Environment Handling
-
-- Support for multiple environment files:
-  - `.env`
-  - `.env.development`
-  - `.env.local`
-- Environment variable validation and processing
-
-### Build Process
-
-- Project bundling
-- Asset management
-- Source code transformation
-
-### Development Support
-
-- Development server configuration
-- Hot reloading capabilities
-- Debug logging
-
-## Project Structure
-
-The deployer creates and manages the following structure:
-
-```
-your-project/
-├── .mastra/
-│   ├── package.json
-│   ├── mastra.mjs
-│   └── index.mjs
-├── .env
-├── .env.development
-├── .env.local
-└── package.json
-```
-
-## Package.json Management
-
-The deployer automatically manages dependencies in the `.mastra/package.json`:
-
-```json
-{
-  "name": "server",
-  "version": "1.0.0",
-  "type": "module",
-  "dependencies": {
-    "@mastra/loggers": "latest",
-    "hono": "4.6.17",
-    "@hono/node-server": "^1.13.7",
-    "superjson": "^2.2.2",
-    "zod-to-json-schema": "^3.24.1"
-  }
-}
+```bash
+pnpm run pull:openapispec
 ```
 
-## Methods
-
-### `install()`
-
-Installs and updates project dependencies.
-
-### `writePackageJson()`
-
-Generates or updates the package.json in the .mastra directory.
-
-### `getMastra()`
-
-Returns the Mastra instance for the project.
-
-### `getMastraPath()`
-
-Returns the path to the .mastra directory.
-
-## Error Handling
-
-The deployer includes comprehensive error handling for:
-
-- Dependency installation failures
-- File system operations
-- Environment configuration issues
-- Build process errors
-
-## Logging
-
-Built-in logging support through @mastra/core:
-
-- Debug information
-- Installation progress
-- Build status
-- Error reporting
+within the `@mastra/server` directory.
 
-## Related Packages
+## License
 
-- `@mastra/core`: Core Mastra functionality
-- `@mastra/loggers`: Logging infrastructure
-- Deployer implementations:
-  - `@mastra/deployer-cloudflare`
-  - Other platform-specific deployers
+Released under the Elastic License 2.0. The full license text is available in
+this repository.

package/dist/_tsup-dts-rollup.d.cts

@@ -13,7 +13,7 @@ import { NewStep } from '@mastra/core/workflows/vNext';
 import type { NewWorkflow } from '@mastra/core/workflows/vNext';
 import type { QueryResult } from '@mastra/core/vector';
 import { ReadableStream as ReadableStream_2 } from 'node:stream/web';
-import type { RuntimeContext } from '@mastra/core/runtime-context';
+import { RuntimeContext } from '@mastra/core/runtime-context';
 import type { RuntimeContext as RuntimeContext_2 } from '@mastra/core/di';
 import { SerializedStepFlowEntry } from '@mastra/core/workflows/vNext';
 import { Step } from '@mastra/core/workflows';
@@ -114,6 +114,7 @@ export declare function generateHandler({ mastra, runtimeContext, agentId, body,
     agentId: string;
     body: GetBody<'generate'> & {
         resourceid?: string;
+        runtimeContext?: Record<string, unknown>;
     };
 }): Promise<GenerateTextResult<any, any>>;
 
@@ -499,6 +500,7 @@ export declare function streamGenerateHandler({ mastra, runtimeContext, agentId,
     agentId: string;
     body: GetBody<'stream'> & {
         resourceid?: string;
+        runtimeContext?: string;
     };
 }): Promise<Response | undefined>;
 

package/dist/_tsup-dts-rollup.d.ts

@@ -13,7 +13,7 @@ import { NewStep } from '@mastra/core/workflows/vNext';
 import type { NewWorkflow } from '@mastra/core/workflows/vNext';
 import type { QueryResult } from '@mastra/core/vector';
 import { ReadableStream as ReadableStream_2 } from 'node:stream/web';
-import type { RuntimeContext } from '@mastra/core/runtime-context';
+import { RuntimeContext } from '@mastra/core/runtime-context';
 import type { RuntimeContext as RuntimeContext_2 } from '@mastra/core/di';
 import { SerializedStepFlowEntry } from '@mastra/core/workflows/vNext';
 import { Step } from '@mastra/core/workflows';
@@ -114,6 +114,7 @@ export declare function generateHandler({ mastra, runtimeContext, agentId, body,
     agentId: string;
     body: GetBody<'generate'> & {
         resourceid?: string;
+        runtimeContext?: Record<string, unknown>;
     };
 }): Promise<GenerateTextResult<any, any>>;
 
@@ -499,6 +500,7 @@ export declare function streamGenerateHandler({ mastra, runtimeContext, agentId,
     agentId: string;
     body: GetBody<'stream'> & {
         resourceid?: string;
+        runtimeContext?: string;
     };
 }): Promise<Response | undefined>;
 

package/dist/{chunk-4BIX6GMY.cjs → chunk-6Q7UXAYJ.cjs}

@@ -4,6 +4,7 @@ var chunk5SWCVTNL_cjs = require('./chunk-5SWCVTNL.cjs');
 var chunkQN4KF3BH_cjs = require('./chunk-QN4KF3BH.cjs');
 var chunkZLBRQFDD_cjs = require('./chunk-ZLBRQFDD.cjs');
 var chunkFV45V6WC_cjs = require('./chunk-FV45V6WC.cjs');
+var runtimeContext = require('@mastra/core/runtime-context');
 
 // src/server/handlers/agents.ts
 var agents_exports = {};
@@ -124,7 +125,7 @@ async function getLiveEvalsByAgentIdHandler({
 }
 async function generateHandler({
   mastra,
-  runtimeContext,
+  runtimeContext: runtimeContext$1,
   agentId,
   body
 }) {
@@ -133,14 +134,18 @@ async function generateHandler({
     if (!agent) {
       throw new chunkFV45V6WC_cjs.HTTPException(404, { message: "Agent not found" });
     }
-    const { messages, resourceId, resourceid, ...rest } = body;
+    const { messages, resourceId, resourceid, runtimeContext: agentRuntimeContext, ...rest } = body;
     const finalResourceId = resourceId ?? resourceid;
+    const finalRuntimeContext = new runtimeContext.RuntimeContext([
+      ...Array.from(runtimeContext$1.entries()),
+      ...Array.from(Object.entries(agentRuntimeContext ?? {}))
+    ]);
     chunkQN4KF3BH_cjs.validateBody({ messages });
     const result = await agent.generate(messages, {
       ...rest,
       // @ts-expect-error TODO fix types
       resourceId: finalResourceId,
-      runtimeContext
+      runtimeContext: finalRuntimeContext
     });
     return result;
   } catch (error) {
@@ -149,7 +154,7 @@ async function generateHandler({
 }
 async function streamGenerateHandler({
   mastra,
-  runtimeContext,
+  runtimeContext: runtimeContext$1,
   agentId,
   body
 }) {
@@ -158,14 +163,18 @@ async function streamGenerateHandler({
     if (!agent) {
       throw new chunkFV45V6WC_cjs.HTTPException(404, { message: "Agent not found" });
     }
-    const { messages, resourceId, resourceid, ...rest } = body;
+    const { messages, resourceId, resourceid, runtimeContext: agentRuntimeContext, ...rest } = body;
     const finalResourceId = resourceId ?? resourceid;
+    const finalRuntimeContext = new runtimeContext.RuntimeContext([
+      ...Array.from(runtimeContext$1.entries()),
+      ...Array.from(Object.entries(agentRuntimeContext ?? {}))
+    ]);
     chunkQN4KF3BH_cjs.validateBody({ messages });
     const streamResult = await agent.stream(messages, {
       ...rest,
       // @ts-expect-error TODO fix types
       resourceId: finalResourceId,
-      runtimeContext
+      runtimeContext: finalRuntimeContext
     });
     const streamResponse = rest.output ? streamResult.toTextStreamResponse() : streamResult.toDataStreamResponse({
       sendUsage: true,

package/dist/{chunk-Y3SV5XK4.js → chunk-GVBJ5I2S.js}

@@ -2,6 +2,7 @@ import { stringify, esm_default } from './chunk-OMN3UI6X.js';
 import { validateBody } from './chunk-L7XE5QTW.js';
 import { handleError } from './chunk-3AHQ5RGN.js';
 import { __export, HTTPException } from './chunk-TRDNDNGQ.js';
+import { RuntimeContext } from '@mastra/core/runtime-context';
 
 // src/server/handlers/agents.ts
 var agents_exports = {};
@@ -131,14 +132,18 @@ async function generateHandler({
     if (!agent) {
       throw new HTTPException(404, { message: "Agent not found" });
     }
-    const { messages, resourceId, resourceid, ...rest } = body;
+    const { messages, resourceId, resourceid, runtimeContext: agentRuntimeContext, ...rest } = body;
     const finalResourceId = resourceId ?? resourceid;
+    const finalRuntimeContext = new RuntimeContext([
+      ...Array.from(runtimeContext.entries()),
+      ...Array.from(Object.entries(agentRuntimeContext ?? {}))
+    ]);
     validateBody({ messages });
     const result = await agent.generate(messages, {
       ...rest,
       // @ts-expect-error TODO fix types
       resourceId: finalResourceId,
-      runtimeContext
+      runtimeContext: finalRuntimeContext
     });
     return result;
   } catch (error) {
@@ -156,14 +161,18 @@ async function streamGenerateHandler({
     if (!agent) {
       throw new HTTPException(404, { message: "Agent not found" });
     }
-    const { messages, resourceId, resourceid, ...rest } = body;
+    const { messages, resourceId, resourceid, runtimeContext: agentRuntimeContext, ...rest } = body;
     const finalResourceId = resourceId ?? resourceid;
+    const finalRuntimeContext = new RuntimeContext([
+      ...Array.from(runtimeContext.entries()),
+      ...Array.from(Object.entries(agentRuntimeContext ?? {}))
+    ]);
     validateBody({ messages });
     const streamResult = await agent.stream(messages, {
       ...rest,
       // @ts-expect-error TODO fix types
       resourceId: finalResourceId,
-      runtimeContext
+      runtimeContext: finalRuntimeContext
     });
     const streamResponse = rest.output ? streamResult.toTextStreamResponse() : streamResult.toDataStreamResponse({
       sendUsage: true,

package/dist/server/handlers/agents.cjs

@@ -1,30 +1,30 @@
 'use strict';
 
-var chunk4BIX6GMY_cjs = require('../../chunk-4BIX6GMY.cjs');
+var chunk6Q7UXAYJ_cjs = require('../../chunk-6Q7UXAYJ.cjs');
 
 
 
 Object.defineProperty(exports, "generateHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.generateHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.generateHandler; }
 });
 Object.defineProperty(exports, "getAgentByIdHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.getAgentByIdHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.getAgentByIdHandler; }
 });
 Object.defineProperty(exports, "getAgentsHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.getAgentsHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.getAgentsHandler; }
 });
 Object.defineProperty(exports, "getEvalsByAgentIdHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.getEvalsByAgentIdHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.getEvalsByAgentIdHandler; }
 });
 Object.defineProperty(exports, "getLiveEvalsByAgentIdHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.getLiveEvalsByAgentIdHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.getLiveEvalsByAgentIdHandler; }
 });
 Object.defineProperty(exports, "streamGenerateHandler", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.streamGenerateHandler; }
+  get: function () { return chunk6Q7UXAYJ_cjs.streamGenerateHandler; }
 });

package/dist/server/handlers/agents.js

@@ -1 +1 @@
-export { generateHandler, getAgentByIdHandler, getAgentsHandler, getEvalsByAgentIdHandler, getLiveEvalsByAgentIdHandler, streamGenerateHandler } from '../../chunk-Y3SV5XK4.js';
+export { generateHandler, getAgentByIdHandler, getAgentsHandler, getEvalsByAgentIdHandler, getLiveEvalsByAgentIdHandler, streamGenerateHandler } from '../../chunk-GVBJ5I2S.js';

package/dist/server/handlers.cjs

@@ -5,7 +5,7 @@ var chunkM2RXDCPV_cjs = require('../chunk-M2RXDCPV.cjs');
 var chunkM56ECCHK_cjs = require('../chunk-M56ECCHK.cjs');
 var chunk55HTWX4C_cjs = require('../chunk-55HTWX4C.cjs');
 var chunkCHFORQ7J_cjs = require('../chunk-CHFORQ7J.cjs');
-var chunk4BIX6GMY_cjs = require('../chunk-4BIX6GMY.cjs');
+var chunk6Q7UXAYJ_cjs = require('../chunk-6Q7UXAYJ.cjs');
 var chunkSKBVVI24_cjs = require('../chunk-SKBVVI24.cjs');
 var chunk2FJURXCL_cjs = require('../chunk-2FJURXCL.cjs');
 var chunk5YGDYMRB_cjs = require('../chunk-5YGDYMRB.cjs');
@@ -35,7 +35,7 @@ Object.defineProperty(exports, "workflows", {
 });
 Object.defineProperty(exports, "agents", {
   enumerable: true,
-  get: function () { return chunk4BIX6GMY_cjs.agents_exports; }
+  get: function () { return chunk6Q7UXAYJ_cjs.agents_exports; }
 });
 Object.defineProperty(exports, "logs", {
   enumerable: true,

package/dist/server/handlers.js

@@ -3,7 +3,7 @@ export { vNextWorkflows_exports as vNextWorkflows } from '../chunk-OWNA6I2H.js';
 export { vector_exports as vector } from '../chunk-4JINXASC.js';
 export { voice_exports as voice } from '../chunk-Q6SHQECN.js';
 export { workflows_exports as workflows } from '../chunk-3XTEV33Q.js';
-export { agents_exports as agents } from '../chunk-Y3SV5XK4.js';
+export { agents_exports as agents } from '../chunk-GVBJ5I2S.js';
 export { logs_exports as logs } from '../chunk-3EJZQ6TQ.js';
 export { memory_exports as memory } from '../chunk-RBQASTUP.js';
 export { network_exports as network } from '../chunk-QJ3AHN64.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/server",
-  "version": "2.0.2",
+  "version": "2.0.3-alpha.0",
   "description": "",
   "type": "module",
   "files": [
@@ -46,7 +46,7 @@
   "license": "Elastic-2.0",
   "dependencies": {},
   "peerDependencies": {
-    "@mastra/core": "^0.9.2"
+    "@mastra/core": "^0.9.3-alpha.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^1.3.2",
@@ -59,7 +59,7 @@
     "vitest": "^2.1.9",
     "zod-to-json-schema": "^3.24.5",
     "@internal/lint": "0.0.3",
-    "@mastra/core": "0.9.2"
+    "@mastra/core": "0.9.3-alpha.0"
   },
   "scripts": {
     "build": "tsup src/index.ts src/server/handlers.ts src/server/handlers/*.ts !src/server/handlers/*.test.ts --format esm,cjs --clean --experimental-dts --treeshake=smallest --splitting",