@mastra/server 0.0.0-agui-20250501191909 → 0.0.0-cloud-transporter-20250513033346

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,25 +1,39 @@
 import type { Agent } from '@mastra/core/agent';
+import type { AgentCard } from '@mastra/core/a2a';
 import type { AgentNetwork } from '@mastra/core/network';
+import type { Artifact } from '@mastra/core/a2a';
 import type { BaseLogMessage } from '@mastra/core/logger';
 import { CoreMessage } from 'ai';
+import type { CoreMessage as CoreMessage_2 } from '@mastra/core/llm';
 import { EvalRow } from '@mastra/core/storage';
 import { GenerateObjectResult } from 'ai';
 import { GenerateTextResult } from 'ai';
+import type { JSONRPCError } from '@mastra/core/a2a';
+import { JSONRPCResponse } from '@mastra/core/a2a';
+import type { Logger } from '@mastra/core/logger';
 import type { Mastra } from '@mastra/core/mastra';
 import type { MastraMemory } from '@mastra/core/memory';
 import { Message } from 'ai';
+import type { Message as Message_2 } from '@mastra/core/a2a';
 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 type { RuntimeContext } from '@mastra/core/runtime-context';
-import type { RuntimeContext as RuntimeContext_2 } from '@mastra/core/di';
-import { SerializedStepFlowEntry } from '@mastra/core/workflows/vNext';
+import { RuntimeContext } from '@mastra/core/runtime-context';
+import { RuntimeContext as RuntimeContext_2 } from '@mastra/core/di';
+import type { SerializedStepFlowEntry } from '@mastra/core/workflows/vNext';
 import { Step } from '@mastra/core/workflows';
 import { StepExecutionContext } from '@mastra/core/workflows';
 import { StepGraph } from '@mastra/core/workflows';
 import { StorageThreadType } from '@mastra/core/memory';
+import { Task } from '@mastra/core/a2a';
+import { TaskAndHistory } from '@mastra/core/a2a';
+import type { TaskContext } from '@mastra/core/a2a';
+import type { TaskIdParams } from '@mastra/core/a2a';
+import type { TaskQueryParams } from '@mastra/core/a2a';
+import type { TaskSendParams } from '@mastra/core/a2a';
+import type { TaskStatus } from '@mastra/core/a2a';
 import type { ToolAction } from '@mastra/core/tools';
 import type { VercelTool } from '@mastra/core/tools';
 import type { Workflow } from '@mastra/core/workflows';
@@ -30,6 +44,17 @@ import type { WorkflowRuns } from '@mastra/core/storage';
 import { ZodType } from 'zod';
 import { ZodTypeDef } from 'zod';
 
+export declare namespace a2a {
+    export {
+        getAgentCardByIdHandler,
+        handleTaskSend,
+        handleTaskGet,
+        handleTaskSendSubscribe,
+        handleTaskCancel,
+        getAgentExecutionHandler
+    }
+}
+
 export declare namespace agents {
     export {
         getAgentsHandler,
@@ -46,12 +71,18 @@ export declare interface ApiError extends Error {
     status?: number;
 }
 
+export declare function applyUpdateToTaskAndHistory(current: TaskAndHistory, update: Omit<TaskStatus, 'timestamp'> | Artifact): TaskAndHistory;
+
 declare type ClientErrorStatusCode = 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451;
 
 export declare interface Context {
     mastra: Mastra;
 }
 
+export declare function convertToCoreMessage(message: Message_2): CoreMessage_2;
+
+export declare function createErrorResponse(id: number | string | null, error: JSONRPCError<unknown>): JSONRPCResponse<null, unknown>;
+
 export declare function createIndex({ mastra, vectorName, index, }: Pick<VectorContext, 'mastra' | 'vectorName'> & {
     index: CreateIndexRequest;
 }): Promise<{
@@ -68,6 +99,15 @@ export declare function createRunHandler({ mastra, workflowId, runId: prevRunId,
     runId: string;
 }>;
 
+export declare function createSuccessResponse<T>(id: number | string | null, result: T): JSONRPCResponse<T>;
+
+export declare function createTaskContext({ task, userMessage, history, activeCancellations, }: {
+    task: Task;
+    userMessage: Message_2;
+    history: Message_2[];
+    activeCancellations: Set<string>;
+}): TaskContext;
+
 export declare function createThreadHandler({ mastra, agentId, body, }: Pick<MemoryContext, 'mastra' | 'agentId'> & {
     body?: Omit<Parameters<MastraMemory['createThread']>[0], 'resourceId'> & {
         resourceId?: string;
@@ -98,15 +138,17 @@ export declare function describeIndex({ mastra, vectorName, indexName, }: Pick<V
     metric: string | undefined;
 }>;
 
-export declare function executeAgentToolHandler({ mastra, agentId, toolId, data, runtimeContext, }: Pick<ToolsContext, 'mastra' | 'toolId'> & {
+export declare function executeAgentToolHandler({ mastra, agentId, toolId, data, runtimeContext, runtimeContextFromRequest, }: Pick<ToolsContext, 'mastra' | 'toolId'> & {
     agentId?: string;
     data: any;
-    runtimeContext: RuntimeContext;
+    runtimeContext: RuntimeContext_2;
+    runtimeContextFromRequest: Record<string, unknown>;
 }): Promise<any>;
 
-export declare function executeToolHandler(tools: ToolsContext['tools']): ({ mastra, runId, toolId, data, runtimeContext, }: Pick<ToolsContext, "mastra" | "toolId" | "runId"> & {
+export declare function executeToolHandler(tools: ToolsContext['tools']): ({ mastra, runId, toolId, data, runtimeContext, runtimeContextFromRequest, }: Pick<ToolsContext, "mastra" | "toolId" | "runId"> & {
     data?: unknown;
-    runtimeContext: RuntimeContext;
+    runtimeContext: RuntimeContext_2;
+    runtimeContextFromRequest: Record<string, unknown>;
 }) => Promise<any>;
 
 export declare function generateHandler({ mastra, runtimeContext, agentId, body, }: Context & {
@@ -114,6 +156,7 @@ export declare function generateHandler({ mastra, runtimeContext, agentId, body,
     agentId: string;
     body: GetBody<'generate'> & {
         resourceid?: string;
+        runtimeContext?: Record<string, unknown>;
     };
 }): Promise<GenerateTextResult<any, any>>;
 
@@ -141,10 +184,32 @@ export declare function getAgentByIdHandler({ mastra, runtimeContext, agentId, }
     name: any;
     instructions: string;
     tools: any;
+    workflows: {};
     provider: string;
     modelId: string;
 }>;
 
+export declare function getAgentCardByIdHandler({ mastra, agentId, executionUrl, provider, version, runtimeContext, }: Context & {
+    runtimeContext: RuntimeContext;
+    agentId: keyof ReturnType<typeof mastra.getAgents>;
+    executionUrl?: string;
+    version?: string;
+    provider?: {
+        organization: string;
+        url: string;
+    };
+}): Promise<AgentCard>;
+
+export declare function getAgentExecutionHandler({ requestId, mastra, agentId, runtimeContext, method, params, taskStore, logger, }: Context & {
+    requestId: string;
+    runtimeContext: RuntimeContext;
+    agentId: string;
+    method: 'tasks/send' | 'tasks/sendSubscribe' | 'tasks/get' | 'tasks/cancel';
+    params: TaskSendParams | TaskQueryParams | TaskIdParams;
+    taskStore?: InMemoryTaskStore;
+    logger?: Logger;
+}): Promise<any>;
+
 export declare function getAgentsHandler({ mastra, runtimeContext }: Context & {
     runtimeContext: RuntimeContext;
 }): Promise<any>;
@@ -187,7 +252,9 @@ export declare function getMemoryStatusHandler({ mastra, agentId }: Pick<MemoryC
     result: boolean;
 }>;
 
-export declare function getMessagesHandler({ mastra, agentId, threadId, }: Pick<MemoryContext, 'mastra' | 'agentId' | 'threadId'>): Promise<{
+export declare function getMessagesHandler({ mastra, agentId, threadId, limit, }: Pick<MemoryContext, 'mastra' | 'agentId' | 'threadId'> & {
+    limit?: number;
+}): Promise<{
     messages: CoreMessage[];
     uiMessages: Message[];
 }>;
@@ -240,16 +307,22 @@ 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;
+    steps: SerializedStep[];
     name: string | undefined;
     stepGraph: SerializedStepFlowEntry[];
     inputSchema: string | undefined;
     outputSchema: string | undefined;
 }>;
 
-export declare function getVNextWorkflowRunHandler({ mastra, workflowId, runId, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReturnType<NewWorkflow['getWorkflowRun']>>;
+export declare function getVNextWorkflowRunByIdHandler({ mastra, workflowId, runId, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'>): Promise<ReturnType<NewWorkflow['getWorkflowRunById']>>;
 
-export declare function getVNextWorkflowRunsHandler({ mastra, workflowId }: VNextWorkflowContext): Promise<WorkflowRuns>;
+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>;
 
@@ -265,12 +338,60 @@ 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>;
 
 export declare function handleError(error: unknown, defaultMessage: string): never;
 
+export declare function handleTaskCancel({ requestId, taskStore, agentId, taskId, logger, }: {
+    requestId: string;
+    taskStore: InMemoryTaskStore;
+    agentId: string;
+    taskId: string;
+    logger?: Logger;
+}): Promise<JSONRPCResponse<Task, unknown>>;
+
+export declare function handleTaskGet({ requestId, taskStore, agentId, taskId, }: {
+    requestId: string;
+    taskStore: InMemoryTaskStore;
+    agentId: string;
+    taskId: string;
+}): Promise<JSONRPCResponse<TaskAndHistory, unknown>>;
+
+export declare function handleTaskSend({ requestId, params, taskStore, agent, logger, runtimeContext, }: {
+    requestId: string;
+    params: TaskSendParams;
+    taskStore: InMemoryTaskStore;
+    agent: Agent;
+    logger?: Logger;
+    runtimeContext: RuntimeContext;
+}): Promise<JSONRPCResponse<null, unknown> | JSONRPCResponse<Task, unknown>>;
+
+export declare function handleTaskSendSubscribe({ requestId, params, taskStore, agent, logger, runtimeContext, }: {
+    requestId: string;
+    params: TaskSendParams;
+    taskStore: InMemoryTaskStore;
+    agent: Agent;
+    logger?: Logger;
+    runtimeContext: RuntimeContext;
+}): AsyncGenerator<JSONRPCResponse<null, unknown> | JSONRPCResponse<Task, unknown> | JSONRPCResponse<    {
+state: string;
+message: {
+role: string;
+parts: {
+type: string;
+text: string;
+}[];
+};
+}, unknown>, void, unknown>;
+
 /**
  * `HTTPException` must be used when a fatal error such as authentication failure occurs.
  *
@@ -332,8 +453,31 @@ declare type HTTPExceptionOptions = {
  */
 declare type InfoStatusCode = 100 | 101 | 102 | 103;
 
+export declare class InMemoryTaskStore {
+    private store;
+    activeCancellations: Set<string>;
+    load({ agentId, taskId }: {
+        agentId: string;
+        taskId: string;
+    }): Promise<TaskAndHistory | null>;
+    save({ agentId, data }: {
+        agentId: string;
+        data: TaskAndHistory;
+    }): Promise<void>;
+}
+
 export declare function listIndexes({ mastra, vectorName }: Pick<VectorContext, 'mastra' | 'vectorName'>): Promise<string[]>;
 
+export declare function loadOrCreateTaskAndHistory({ agentId, taskId, taskStore, message, sessionId, metadata, logger, }: {
+    agentId: string;
+    taskId: string;
+    taskStore: InMemoryTaskStore;
+    message: Message_2;
+    sessionId?: string | null;
+    metadata?: Record<string, unknown> | null;
+    logger?: Logger;
+}): Promise<TaskAndHistory>;
+
 export declare namespace logs {
     export {
         getLogsHandler,
@@ -381,6 +525,8 @@ declare interface NetworkContext extends Context {
     runtimeContext: RuntimeContext;
 }
 
+export declare function normalizeError(error: any, reqId: number | string | null, taskId?: string, logger?: Logger): JSONRPCResponse<null, unknown>;
+
 declare interface QueryRequest {
     indexName: string;
     queryVector: number[];
@@ -395,12 +541,13 @@ export declare function queryVectors({ mastra, vectorName, query, }: Pick<Vector
 
 declare type RedirectStatusCode = 300 | 301 | 302 | 303 | 304 | DeprecatedStatusCode | 307 | 308;
 
-export declare function resumeAsyncVNextWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: VNextWorkflowContext & {
+export declare function resumeAsyncVNextWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, runtimeContextFromRequest, }: VNextWorkflowContext & {
     body: {
         step: string | string[];
         resumeData?: unknown;
     };
     runtimeContext?: RuntimeContext_2;
+    runtimeContextFromRequest?: Record<string, unknown>;
 }): Promise<WorkflowResult<ZodType<any, ZodTypeDef, any>, NewStep<string, any, any, any, any>[]>>;
 
 export declare function resumeAsyncWorkflowHandler({ mastra, workflowId, runId, body, runtimeContext, }: WorkflowContext & {
@@ -437,11 +584,21 @@ export declare function saveMessagesHandler({ mastra, agentId, body, }: Pick<Mem
     };
 }): Promise<MessageType[]>;
 
+declare type SerializedStep = {
+    id: string;
+    description: string;
+    inputSchema: string | undefined;
+    outputSchema: string | undefined;
+    resumeSchema: string | undefined;
+    suspendSchema: string | undefined;
+};
+
 declare type ServerErrorStatusCode = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
 
-export declare function startAsyncVNextWorkflowHandler({ mastra, runtimeContext, workflowId, runId, inputData, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+export declare function startAsyncVNextWorkflowHandler({ mastra, runtimeContext, workflowId, runId, inputData, runtimeContextFromRequest, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
     inputData?: unknown;
     runtimeContext?: RuntimeContext_2;
+    runtimeContextFromRequest?: Record<string, unknown>;
 }): 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'> & {
@@ -449,9 +606,10 @@ export declare function startAsyncWorkflowHandler({ mastra, runtimeContext, work
     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 startVNextWorkflowRunHandler({ mastra, runtimeContext, workflowId, runId, inputData, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
+export declare function startVNextWorkflowRunHandler({ mastra, runtimeContext, workflowId, runId, inputData, runtimeContextFromRequest, }: Pick<VNextWorkflowContext, 'mastra' | 'workflowId' | 'runId'> & {
     inputData?: unknown;
     runtimeContext?: RuntimeContext_2;
+    runtimeContextFromRequest?: Record<string, unknown>;
 }): Promise<{
     message: string;
 }>;
@@ -487,6 +645,7 @@ export declare function streamGenerateHandler({ mastra, runtimeContext, agentId,
     agentId: string;
     body: GetBody<'stream'> & {
         resourceid?: string;
+        runtimeContext?: string;
     };
 }): Promise<Response | undefined>;
 
@@ -513,6 +672,8 @@ declare interface TelemetryContext extends Context {
         page?: number;
         perPage?: number;
         attribute?: string | string[];
+        fromDate?: Date;
+        toDate?: Date;
     };
 }
 
@@ -604,7 +765,7 @@ export declare namespace vNextWorkflows {
     export {
         getVNextWorkflowsHandler,
         getVNextWorkflowByIdHandler,
-        getVNextWorkflowRunHandler,
+        getVNextWorkflowRunByIdHandler,
         createVNextWorkflowRunHandler,
         startAsyncVNextWorkflowHandler,
         startVNextWorkflowRunHandler,