@mastra/core 1.6.0 → 1.7.0-alpha.0

package/dist/docs/references/docs-server-custom-api-routes.md

@@ -1,267 +0,0 @@
-# Custom API Routes
-
-By default, Mastra automatically exposes registered agents and workflows via its server. For additional behavior you can define your own HTTP routes.
-
-Routes are provided with a helper `registerApiRoute()` from `@mastra/core/server`. Routes can live in the same file as the `Mastra` instance but separating them helps keep configuration concise.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-
-export const mastra = new Mastra({
-  server: {
-    apiRoutes: [
-      registerApiRoute("/my-custom-route", {
-        method: "GET",
-        handler: async (c) => {
-          const mastra = c.get("mastra");
-          const agent = await mastra.getAgent("my-agent");
-
-          return c.json({ message: "Custom route" });
-        },
-      }),
-    ],
-  },
-});
-```
-
-Once registered, a custom route will be accessible from the root of the server. For example:
-
-```bash
-curl http://localhost:4111/my-custom-route
-```
-
-Each route's handler receives the Hono `Context`. Within the handler you can access the `Mastra` instance to fetch or call agents and workflows.
-
-## Middleware
-
-To add route-specific middleware pass a `middleware` array when calling `registerApiRoute()`.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-
-export const mastra = new Mastra({
-  server: {
-    apiRoutes: [
-      registerApiRoute("/my-custom-route", {
-        method: "GET",
-        middleware: [
-          async (c, next) => {
-            console.log(`${c.req.method} ${c.req.url}`);
-            await next();
-          },
-        ],
-        handler: async (c) => {
-          return c.json({ message: "Custom route with middleware" });
-        },
-      }),
-    ],
-  },
-});
-```
-
-## OpenAPI Documentation
-
-Custom routes can include OpenAPI metadata to appear in the Swagger UI alongside Mastra server routes. Pass an `openapi` option with standard OpenAPI operation fields.
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-import { z } from "zod";
-
-export const mastra = new Mastra({
-  server: {
-    apiRoutes: [
-      registerApiRoute("/items/:itemId", {
-        method: "GET",
-        openapi: {
-          summary: "Get item by ID",
-          description: "Retrieves a single item by its unique identifier",
-          tags: ["Items"],
-          parameters: [
-            {
-              name: "itemId",
-              in: "path",
-              required: true,
-              description: "The item ID",
-              schema: { type: "string" },
-            },
-          ],
-          responses: {
-            200: {
-              description: "Item found",
-              content: {
-                "application/json": {
-                  schema: {
-                    type: "object",
-                    properties: {
-                      id: { type: "string" },
-                      name: { type: "string" },
-                    },
-                  },
-                },
-              },
-            },
-            404: {
-              description: "Item not found",
-            },
-          },
-        },
-        handler: async (c) => {
-          const itemId = c.req.param("itemId");
-          return c.json({ id: itemId, name: "Example Item" });
-        },
-      }),
-    ],
-  },
-});
-```
-
-### Using Zod Schemas
-
-Zod schemas in the `openapi` configuration are converted to JSON Schema when the OpenAPI document is generated:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-import { z } from "zod";
-
-const ItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-});
-
-const CreateItemSchema = z.object({
-  name: z.string().min(1),
-  price: z.number().positive(),
-});
-
-export const mastra = new Mastra({
-  server: {
-    apiRoutes: [
-      registerApiRoute("/items", {
-        method: "POST",
-        openapi: {
-          summary: "Create a new item",
-          tags: ["Items"],
-          requestBody: {
-            required: true,
-            content: {
-              "application/json": {
-                schema: CreateItemSchema,
-              },
-            },
-          },
-          responses: {
-            201: {
-              description: "Item created",
-              content: {
-                "application/json": {
-                  schema: ItemSchema,
-                },
-              },
-            },
-          },
-        },
-        handler: async (c) => {
-          const body = await c.req.json();
-          return c.json({ id: "new-id", ...body }, 201);
-        },
-      }),
-    ],
-  },
-});
-```
-
-### Viewing in Swagger UI
-
-When running in development mode (`mastra dev`) or with `swaggerUI: true` in build options, your custom routes appear in the Swagger UI at `/swagger-ui`.
-
-```typescript
-export const mastra = new Mastra({
-  server: {
-    build: {
-      swaggerUI: true, // Enable in production builds
-    },
-    apiRoutes: [
-      // Your routes...
-    ],
-  },
-});
-```
-
-## Authentication
-
-When authentication is configured on your Mastra server, custom API routes require authentication by default. To make a route publicly accessible, set `requiresAuth: false`:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-import { MastraJwtAuth } from "@mastra/auth";
-
-export const mastra = new Mastra({
-  server: {
-    auth: new MastraJwtAuth({
-      secret: process.env.MASTRA_JWT_SECRET,
-    }),
-    apiRoutes: [
-      // Protected route (default behavior)
-      registerApiRoute("/protected-data", {
-        method: "GET",
-        handler: async (c) => {
-          // Access authenticated user from request context
-          const user = c.get("requestContext").get("user");
-          return c.json({ message: "Authenticated user", user });
-        },
-      }),
-
-      // Public route (no authentication required)
-      registerApiRoute("/webhooks/github", {
-        method: "POST",
-        requiresAuth: false, // Explicitly opt out of authentication
-        handler: async (c) => {
-          const payload = await c.req.json();
-          // Process webhook without authentication
-          return c.json({ received: true });
-        },
-      }),
-    ],
-  },
-});
-```
-
-### Authentication behavior
-
-- **No auth configured**: All routes (built-in and custom) are public
-
-- **Auth configured**:
-
-  - Mastra-provided routes (`/api/agents/*`, `/api/workflows/*`, etc.) require authentication
-  - Custom routes require authentication by default
-  - Custom routes can opt out with `requiresAuth: false`
-
-### Accessing user information
-
-When a request is authenticated, the user object is available in the request context:
-
-```typescript
-registerApiRoute("/user-profile", {
-  method: "GET",
-  handler: async (c) => {
-    const requestContext = c.get("requestContext");
-    const user = requestContext.get("user");
-
-    return c.json({ user });
-  },
-})
-```
-
-For more information about authentication providers, see the [Auth documentation](https://mastra.ai/docs/server/auth).
-
-## Related
-
-- [registerApiRoute() Reference](https://mastra.ai/reference/server/register-api-route) - Full API reference
-- [Server Middleware](https://mastra.ai/docs/server/middleware) - Global middleware configuration
-- [Mastra Server](https://mastra.ai/docs/server/mastra-server) - Server configuration options

package/dist/docs/references/docs-server-mastra-client.md

@@ -1,243 +0,0 @@
-# Mastra Client SDK
-
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
-
-## Prerequisites
-
-To ensure smooth local development, make sure you have:
-
-- Node.js `v22.13.0` or later
-- TypeScript `v4.7` or higher (if using TypeScript)
-- Your local Mastra server running (typically on port `4111`)
-
-## Usage
-
-The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
-
-## Installation
-
-To use the Mastra Client SDK, install the required dependencies:
-
-**npm**:
-
-```bash
-npm install @mastra/client-js@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/client-js@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/client-js@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/client-js@latest
-```
-
-### Initialize the `MastraClient`
-
-Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111",
-});
-```
-
-## Core APIs
-
-The Mastra Client SDK exposes all resources served by the Mastra Server
-
-- **[Agents](https://mastra.ai/reference/client-js/agents)**: Generate responses and stream conversations.
-- **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
-- **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
-- **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.
-- **[Vectors](https://mastra.ai/reference/client-js/vectors)**: Use vector embeddings for semantic search.
-- **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
-- **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: Monitor app performance and trace activity.
-
-## Generating responses
-
-Call `.generate()` with a string prompt:
-
-```typescript
-import { mastraClient } from "lib/mastra-client";
-
-const testAgent = async () => {
-  try {
-    const agent = mastraClient.getAgent("testAgent");
-
-    const response = await agent.generate("Hello");
-
-    console.log(response.text);
-  } catch (error) {
-    return "Error occurred while generating response";
-  }
-};
-```
-
-> **Info:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
-
-## Streaming responses
-
-Use `.stream()` for real-time responses with a string prompt:
-
-```typescript
-import { mastraClient } from "lib/mastra-client";
-
-const testAgent = async () => {
-  try {
-    const agent = mastraClient.getAgent("testAgent");
-
-    const stream = await agent.stream("Hello");
-
-    stream.processDataStream({
-      onTextPart: (text) => {
-        console.log(text);
-      },
-    });
-  } catch (error) {
-    return "Error occurred while generating response";
-  }
-};
-```
-
-> **Info:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
-
-## Configuration options
-
-`MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const mastraClient = new MastraClient({
-  retries: 3,
-  backoffMs: 300,
-  maxBackoffMs: 5000,
-  headers: {
-    "X-Development": "true",
-  },
-});
-```
-
-> **Info:** Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
-
-## Adding request cancelling
-
-`MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.
-
-Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-
-export const controller = new AbortController();
-
-export const mastraClient = new MastraClient({
-  baseUrl: process.env.MASTRA_API_URL || "http://localhost:4111",
-  abortSignal: controller.signal,
-});
-```
-
-### Using the `AbortController`
-
-Calling `.abort()` will cancel any ongoing requests tied to that signal.
-
-```typescript
-import { mastraClient, controller } from "lib/mastra-client";
-
-const handleAbort = () => {
-  controller.abort();
-};
-```
-
-## Client tools
-
-Define tools directly in client-side applications using the `createTool()` function. Pass them to agents via the `clientTools` parameter in `.generate()` or `.stream()` calls.
-
-This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.
-
-```typescript
-import { createTool } from "@mastra/client-js";
-import { z } from "zod";
-
-const handleClientTool = async () => {
-  try {
-    const agent = mastraClient.getAgent("colorAgent");
-
-    const colorChangeTool = createTool({
-      id: "color-change-tool",
-      description: "Changes the HTML background color",
-      inputSchema: z.object({
-        color: z.string(),
-      }),
-      outputSchema: z.object({
-        success: z.boolean(),
-      }),
-      execute: async (inputData) => {
-        const { color } = inputData;
-
-        document.body.style.backgroundColor = color;
-        return { success: true };
-      },
-    });
-
-    const response = await agent.generate("Change the background to blue", {
-      clientTools: { colorChangeTool },
-    });
-
-    console.log(response);
-  } catch (error) {
-    console.error(error);
-  }
-};
-```
-
-### Client tool's agent
-
-This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview) configured to return hex color codes, intended to work with the browser-based client tool defined above.
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-
-export const colorAgent = new Agent({
-  id: "color-agent",
-  name: "Color Agent",
-  instructions: `You are a helpful CSS assistant.
-  You can change the background color of web pages.
-  Respond with a hex reference for the color requested by the user`,
-  model: "openai/gpt-5.1",
-});
-```
-
-## Server-side environments
-
-You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:
-
-```typescript
-export async function action() {
-  const agent = mastraClient.getAgent("testAgent");
-
-  const stream = await agent.stream("Hello");
-
-  return new Response(stream.body);
-}
-```
-
-## Best practices
-
-1. **Error Handling**: Implement proper [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
-2. **Environment Variables**: Use environment variables for configuration.
-3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs) when needed.
-4. **Performance**: Monitor application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry) and traces.

package/dist/docs/references/docs-server-mastra-server.md

@@ -1,71 +0,0 @@
-# Server Overview
-
-Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.
-
-> **Info:** This page covers the [`server`](https://mastra.ai/reference/configuration) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/server/server-adapters).
-
-## Server architecture
-
-Mastra uses [Hono](https://hono.dev) as its underlying HTTP server framework. When you build a Mastra application using `mastra build`, it generates a Hono-based HTTP server in the `.mastra` directory.
-
-The server provides:
-
-- API endpoints for all registered agents and workflows
-- Custom API routes and middleware
-- Authentication with multiple providers
-- Request context for dynamic configuration
-- Stream data redaction for secure responses
-
-## Configuration
-
-Configure the server by passing a `server` object to the `Mastra` constructor:
-
-```typescript
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  server: {
-    port: 3000, // Defaults to 4111
-    host: "0.0.0.0", // Defaults to 'localhost'
-  },
-});
-```
-
-> **Info:** Visit the [configuration reference](https://mastra.ai/reference/configuration) for a full list of available server options.
-
-## Server features
-
-- **[Middleware](https://mastra.ai/docs/server/middleware)**: Intercept requests for authentication, logging, CORS, or injecting request-specific context.
-- **[Custom API Routes](https://mastra.ai/docs/server/custom-api-routes)**: Extend the server with your own HTTP endpoints that have access to the Mastra instance.
-- **[Request Context](https://mastra.ai/docs/server/request-context)**: Pass request-specific values to agents, tools, and workflows based on runtime conditions.
-- **[Server Adapters](https://mastra.ai/docs/server/server-adapters)**: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server.
-- **[Custom Adapters](https://mastra.ai/docs/server/custom-adapters)**: Build adapters for frameworks not officially supported.
-- **[Mastra Client SDK](https://mastra.ai/docs/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments.
-- **[Authentication](https://mastra.ai/docs/server/auth)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.
-
-## Stream data redaction
-
-When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
-
-This behavior is only configurable by using [server adapters](https://mastra.ai/docs/server/server-adapters). For server adapters, stream data redaction is enabled by default, too.
-
-## TypeScript configuration
-
-Mastra requires `module` and `moduleResolution` settings compatible with modern Node.js. Legacy options like `CommonJS` or `node` are not supported.
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"]
-}
-```