@mastra/server 0.0.0-message-ordering-20250415215612 → 0.0.0-redis-cloud-transporter-20250508191651

package/README.md

@@ -1,159 +1,72 @@
-# @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

@@ -1,7 +1,6 @@
 import type { Agent } from '@mastra/core/agent';
 import type { AgentNetwork } from '@mastra/core/network';
 import type { BaseLogMessage } from '@mastra/core/logger';
-import type { Container } from '@mastra/core/di';
 import { CoreMessage } from 'ai';
 import { EvalRow } from '@mastra/core/storage';
 import { GenerateObjectResult } from 'ai';
@@ -10,8 +9,13 @@ import type { Mastra } from '@mastra/core/mastra';
 import type { MastraMemory } from '@mastra/core/memory';
 import { Message } from 'ai';
 import { MessageType } from '@mastra/core/memory';
+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 { 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';
 import { StepExecutionContext } from '@mastra/core/workflows';
 import { StepGraph } from '@mastra/core/workflows';
@@ -20,8 +24,11 @@ import type { ToolAction } from '@mastra/core/tools';
 import type { VercelTool } from '@mastra/core/tools';
 import type { Workflow } from '@mastra/core/workflows';
 import { WorkflowContext as WorkflowContext_2 } from '@mastra/core/workflows';
+import { WorkflowResult } from '@mastra/core/workflows/vNext';
 import { WorkflowRunResult } from '@mastra/core/workflows';
 import type { WorkflowRuns } from '@mastra/core/storage';
+import { ZodType } from 'zod';
+import { ZodTypeDef } from 'zod';
 
 export declare namespace agents {
     export {
@@ -67,6 +74,10 @@ export declare function createThreadHandler({ mastra, agentId, body, }: Pick<Mem
     };
 }): Promise<StorageThreadType>;
 
+export declare function createVNextWorkflowRunHandler({ mastra, workflowId, runId: prevRunId, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<{
+    runId: string;
+}>;
+
 export declare function deleteIndex({ mastra, vectorName, indexName, }: Pick<VectorContext, 'mastra' | 'vectorName'> & {
     indexName?: string;
 }): Promise<{
@@ -87,27 +98,28 @@ export declare function describeIndex({ mastra, vectorName, indexName, }: Pick<V
     metric: string | undefined;
 }>;
 
-export declare function executeAgentToolHandler({ mastra, agentId, toolId, data, container, }: Pick<ToolsContext, 'mastra' | 'toolId'> & {
+export declare function executeAgentToolHandler({ mastra, agentId, toolId, data, runtimeContext, }: Pick<ToolsContext, 'mastra' | 'toolId'> & {
     agentId?: string;
     data: any;
-    container: Container;
+    runtimeContext: RuntimeContext;
 }): Promise<any>;
 
-export declare function executeToolHandler(tools: ToolsContext['tools']): ({ mastra, runId, toolId, data, container, }: Pick<ToolsContext, "mastra" | "toolId" | "runId"> & {
+export declare function executeToolHandler(tools: ToolsContext['tools']): ({ mastra, runId, toolId, data, runtimeContext, }: Pick<ToolsContext, "mastra" | "toolId" | "runId"> & {
     data?: unknown;
-    container: Container;
+    runtimeContext: RuntimeContext;
 }) => Promise<any>;
 
-export declare function generateHandler({ mastra, container, agentId, body, }: Context & {
-    container: Container;
+export declare function generateHandler({ mastra, runtimeContext, agentId, body, }: Context & {
+    runtimeContext: RuntimeContext;
     agentId: string;
     body: GetBody<'generate'> & {
         resourceid?: string;
+        runtimeContext?: Record<string, unknown>;
     };
 }): Promise<GenerateTextResult<any, any>>;
 
-export declare function generateHandler_alias_1({ mastra, container, networkId, body, }: NetworkContext & {
-    container: Container;
+export declare function generateHandler_alias_1({ mastra, runtimeContext, networkId, body, }: NetworkContext & {
+    runtimeContext: RuntimeContext;
     body: {
         messages?: Parameters<AgentNetwork['generate']>[0];
     } & Parameters<AgentNetwork['generate']>[1];
@@ -121,11 +133,10 @@ export declare function generateSpeechHandler({ mastra, agentId, body, }: VoiceC
         text?: string;
         speakerId?: string;
     };
-}): Promise<{
-    audioData: Buffer<ArrayBuffer>;
-}>;
+}): Promise<NodeJS.ReadableStream>;
 
-export declare function getAgentByIdHandler({ mastra, agentId }: Context & {
+export declare function getAgentByIdHandler({ mastra, runtimeContext, agentId, }: Context & {
+    runtimeContext: RuntimeContext;
     agentId: string;
 }): Promise<{
     name: any;
@@ -135,7 +146,9 @@ export declare function getAgentByIdHandler({ mastra, agentId }: Context & {
     modelId: string;
 }>;
 
-export declare function getAgentsHandler({ mastra }: Context): Promise<any>;
+export declare function getAgentsHandler({ mastra, runtimeContext }: Context & {
+    runtimeContext: RuntimeContext;
+}): Promise<any>;
 
 declare type GetBody<T extends keyof Agent & {
     [K in keyof Agent]: Agent[K] extends (...args: any) => any ? K : never;
@@ -143,7 +156,8 @@ declare type GetBody<T extends keyof Agent & {
     messages: Parameters<Agent[T]>[0];
 } & Parameters<Agent[T]>[1];
 
-export declare function getEvalsByAgentIdHandler({ mastra, agentId }: Context & {
+export declare function getEvalsByAgentIdHandler({ mastra, runtimeContext, agentId, }: Context & {
+    runtimeContext: RuntimeContext;
     agentId: string;
 }): Promise<{
     id: string;
@@ -152,7 +166,8 @@ export declare function getEvalsByAgentIdHandler({ mastra, agentId }: Context &
     evals: EvalRow[];
 }>;
 
-export declare function getLiveEvalsByAgentIdHandler({ mastra, agentId }: Context & {
+export declare function getLiveEvalsByAgentIdHandler({ mastra, runtimeContext, agentId, }: Context & {
+    runtimeContext: RuntimeContext;
     agentId: string;
 }): Promise<{
     id: string;
@@ -178,7 +193,7 @@ export declare function getMessagesHandler({ mastra, agentId, threadId, }: Pick<
     uiMessages: Message[];
 }>;
 
-export declare function getNetworkByIdHandler({ mastra, networkId }: Pick<NetworkContext, 'mastra' | 'networkId'>): Promise<{
+export declare function getNetworkByIdHandler({ mastra, networkId, runtimeContext, }: Pick<NetworkContext, 'mastra' | 'networkId' | 'runtimeContext'>): Promise<{
     id: string;
     name: string;
     instructions: string;
@@ -193,7 +208,7 @@ export declare function getNetworkByIdHandler({ mastra, networkId }: Pick<Networ
     };
 }>;
 
-export declare function getNetworksHandler({ mastra }: Pick<NetworkContext, 'mastra'>): Promise<{
+export declare function getNetworksHandler({ mastra, runtimeContext, }: Pick<NetworkContext, 'mastra' | 'runtimeContext'>): Promise<{
     id: string;
     name: string;
     instructions: string;
@@ -225,6 +240,26 @@ export declare function getToolByIdHandler({ tools, toolId }: Pick<ToolsContext,
 
 export declare function getToolsHandler({ tools }: Pick<ToolsContext, 'tools'>): Promise<Record<string, any>>;
 
+export declare function getVNextWorkflowByIdHandler({ mastra, workflowId }: VNextWorkflowContext): Promise<{
+    steps: any;
+    name: string | undefined;
+    stepGraph: SerializedStepFlowEntry[];
+    inputSchema: string | undefined;
+    outputSchema: string | undefined;
+}>;
+
+export declare function getVNextWorkflowRunByIdHandler({ mastra, workflowId, runId, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReturnType<NewWorkflow['getWorkflowRunById']>>;
+
+export declare function getVNextWorkflowRunsHandler({ mastra, workflowId, fromDate, toDate, limit, offset, resourceId, }: VNextWorkflowContext & {
+    fromDate?: Date;
+    toDate?: Date;
+    limit?: number;
+    offset?: number;
+    resourceId?: string;
+}): Promise<WorkflowRuns>;
+
+export declare function getVNextWorkflowsHandler({ mastra }: VNextWorkflowContext): Promise<any>;
+
 export declare function getWorkflowByIdHandler({ mastra, workflowId }: WorkflowContext): Promise<{
     stepGraph: StepGraph;
     stepSubscriberGraph: Record<string, StepGraph>;
@@ -237,7 +272,13 @@ export declare function getWorkflowByIdHandler({ mastra, workflowId }: WorkflowC
 
 export declare function getWorkflowRunHandler({ mastra, workflowId, runId, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReturnType<Workflow['getRun']>>;
 
-export declare function getWorkflowRunsHandler({ mastra, workflowId }: WorkflowContext): Promise<WorkflowRuns>;
+export declare function getWorkflowRunsHandler({ mastra, workflowId, fromDate, toDate, limit, offset, resourceId, }: WorkflowContext & {
+    fromDate?: Date;
+    toDate?: Date;
+    limit?: number;
+    offset?: number;
+    resourceId?: string;
+}): Promise<WorkflowRuns>;
 
 export declare function getWorkflowsHandler({ mastra }: WorkflowContext): Promise<any>;
 
@@ -350,6 +391,7 @@ export declare namespace network {
 
 declare interface NetworkContext extends Context {
     networkId?: string;
+    runtimeContext: RuntimeContext;
 }
 
 declare interface QueryRequest {
@@ -366,20 +408,38 @@ export declare function queryVectors({ mastra, vectorName, query, }: Pick<Vector
 
 declare type RedirectStatusCode = 300 | 301 | 302 | 303 | 304 | DeprecatedStatusCode | 307 | 308;
 
-export declare function resumeAsyncWorkflowHandler({ mastra, workflowId, runId, body, container, }: WorkflowContext & {
+export declare function resumeAsyncVNextWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: VNextWorkflowContext & {
+    body: {
+        step: string | string[];
+        resumeData?: unknown;
+    };
+    runtimeContext?: RuntimeContext_2;
+}): Promise<WorkflowResult<ZodType<any, ZodTypeDef, any>, NewStep<string, any, any, any, any>[]>>;
+
+export declare function resumeAsyncWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: WorkflowContext & {
     body: {
         stepId: string;
         context: any;
     };
-    container: Container;
+    runtimeContext: RuntimeContext;
 }): Promise<Omit<WorkflowRunResult<any, Step<string, any, any, StepExecutionContext<any, WorkflowContext_2<any, Step<string, any, any, any>[], Record<string, any>>>>[], any>, "runId"> | undefined>;
 
-export declare function resumeWorkflowHandler({ mastra, workflowId, runId, body, container, }: WorkflowContext & {
+export declare function resumeVNextWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: VNextWorkflowContext & {
+    body: {
+        step: string | string[];
+        resumeData?: unknown;
+    };
+    runtimeContext?: RuntimeContext_2;
+}): Promise<{
+    message: string;
+}>;
+
+export declare function resumeWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: WorkflowContext & {
     body: {
         stepId: string;
         context: any;
     };
-    container: Container;
+    runtimeContext: RuntimeContext;
 }): Promise<{
     message: string;
 }>;
@@ -392,14 +452,26 @@ export declare function saveMessagesHandler({ mastra, agentId, body, }: Pick<Mem
 
 declare type ServerErrorStatusCode = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
 
-export declare function startAsyncWorkflowHandler({ mastra, container, workflowId, runId, triggerData, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+export declare function startAsyncVNextWorkflowHandler({ mastra, runtimeContext, workflowId, runId, inputData, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+    inputData?: unknown;
+    runtimeContext?: RuntimeContext_2;
+}): Promise<WorkflowResult<ZodType<any, ZodTypeDef, any>, NewStep<string, any, any, any, any>[]>>;
+
+export declare function startAsyncWorkflowHandler({ mastra, runtimeContext, workflowId, runId, triggerData, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
     triggerData?: unknown;
-    container: Container;
+    runtimeContext: RuntimeContext;
 }): Promise<WorkflowRunResult<any, Step<string, any, any, StepExecutionContext<any, WorkflowContext_2<any, Step<string, any, any, any>[], Record<string, any>>>>[], any>>;
 
-export declare function startWorkflowRunHandler({ mastra, container, workflowId, runId, triggerData, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+export declare function startVNextWorkflowRunHandler({ mastra, runtimeContext, workflowId, runId, inputData, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+    inputData?: unknown;
+    runtimeContext?: RuntimeContext_2;
+}): Promise<{
+    message: string;
+}>;
+
+export declare function startWorkflowRunHandler({ mastra, runtimeContext, workflowId, runId, triggerData, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
     triggerData?: unknown;
-    container: Container;
+    runtimeContext: RuntimeContext;
 }): Promise<{
     message: string;
 }>;
@@ -423,16 +495,17 @@ export declare function storeTelemetryHandler({ mastra, body }: Context & {
     traceCount: number;
 }>;
 
-export declare function streamGenerateHandler({ mastra, container, agentId, body, }: Context & {
-    container: Container;
+export declare function streamGenerateHandler({ mastra, runtimeContext, agentId, body, }: Context & {
+    runtimeContext: RuntimeContext;
     agentId: string;
     body: GetBody<'stream'> & {
         resourceid?: string;
+        runtimeContext?: string;
     };
 }): Promise<Response | undefined>;
 
-export declare function streamGenerateHandler_alias_1({ mastra, networkId, body, container, }: NetworkContext & {
-    container: Container;
+export declare function streamGenerateHandler_alias_1({ mastra, networkId, body, runtimeContext, }: NetworkContext & {
+    runtimeContext: RuntimeContext;
     body: {
         messages?: Parameters<AgentNetwork['stream']>[0];
     } & Parameters<AgentNetwork['stream']>[1];
@@ -454,6 +527,8 @@ declare interface TelemetryContext extends Context {
         page?: number;
         perPage?: number;
         attribute?: string | string[];
+        fromDate?: Date;
+        toDate?: Date;
     };
 }
 
@@ -536,6 +611,26 @@ declare interface VectorContext extends Context {
     vectorName?: string;
 }
 
+declare interface VNextWorkflowContext extends Context {
+    workflowId?: string;
+    runId?: string;
+}
+
+export declare namespace vNextWorkflows {
+    export {
+        getVNextWorkflowsHandler,
+        getVNextWorkflowByIdHandler,
+        getVNextWorkflowRunByIdHandler,
+        createVNextWorkflowRunHandler,
+        startAsyncVNextWorkflowHandler,
+        startVNextWorkflowRunHandler,
+        watchVNextWorkflowHandler,
+        resumeAsyncVNextWorkflowHandler,
+        resumeVNextWorkflowHandler,
+        getVNextWorkflowRunsHandler
+    }
+}
+
 export declare namespace voice {
     export {
         getSpeakersHandler,
@@ -548,6 +643,8 @@ declare interface VoiceContext extends Context {
     agentId?: string;
 }
 
+export declare function watchVNextWorkflowHandler({ mastra, workflowId, runId, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReadableStream_2<string>>;
+
 export declare function watchWorkflowHandler({ mastra, workflowId, runId, }: Pick<WorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReadableStream_2<string>>;
 
 declare interface WorkflowContext extends Context {