@mastra/mcp-docs-server 1.2.8-alpha.17 → 1.2.8-alpha.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.docs/docs/mastra-platform/overview.md +1 -1
- package/.docs/docs/mastra-platform/workspace.md +111 -0
- package/.docs/docs/workspace/filesystem.md +1 -0
- package/.docs/docs/workspace/sandbox.md +1 -0
- package/.docs/models/gateways/openrouter.md +2 -1
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/alibaba-token-plan-cn.md +22 -21
- package/.docs/models/providers/alibaba-token-plan.md +22 -21
- package/.docs/models/providers/novita-ai.md +3 -1
- package/.docs/models/providers/zenmux.md +2 -1
- package/.docs/reference/evals/context-recall.md +205 -0
- package/.docs/reference/index.md +3 -0
- package/.docs/reference/workspace/platform-filesystem.md +182 -0
- package/.docs/reference/workspace/platform-sandbox.md +200 -0
- package/CHANGELOG.md +7 -0
- package/package.json +6 -6
|
@@ -10,7 +10,7 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
|
|
|
10
10
|
|
|
11
11
|
Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy), or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
|
|
12
12
|
|
|
13
|
-
Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`)
|
|
13
|
+
Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspace) per environment that gives agents a filesystem and a sandbox with no manual configuration.
|
|
14
14
|
|
|
15
15
|
## Get started
|
|
16
16
|
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# Workspace
|
|
4
|
+
|
|
5
|
+
A workspace gives an environment two things your agents can use at runtime:
|
|
6
|
+
|
|
7
|
+
- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
|
|
8
|
+
- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
|
|
9
|
+
|
|
10
|
+
Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle; your deploy code only needs to construct the providers.
|
|
11
|
+
|
|
12
|
+
## When workspaces are provisioned
|
|
13
|
+
|
|
14
|
+
New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
|
|
15
|
+
|
|
16
|
+
Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
|
|
17
|
+
|
|
18
|
+
If provisioning fails for an environment — for example while Railway is under load — the Workspaces tab shows the failure and offers a retry. The environment itself is still created; only the workspace is unavailable until you retry.
|
|
19
|
+
|
|
20
|
+
## Use the workspace from your code
|
|
21
|
+
|
|
22
|
+
Install the provider package:
|
|
23
|
+
|
|
24
|
+
**npm**:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm install @mastra/platform-workspace
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**pnpm**:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pnpm add @mastra/platform-workspace
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Yarn**:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
yarn add @mastra/platform-workspace
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Bun**:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
bun add @mastra/platform-workspace
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Compose the providers into a workspace and register it with Mastra:
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
import { Workspace } from '@mastra/core/workspace'
|
|
52
|
+
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
|
|
53
|
+
|
|
54
|
+
export const workspace = new Workspace({
|
|
55
|
+
filesystem: new PlatformFilesystem(),
|
|
56
|
+
sandbox: new PlatformSandbox(),
|
|
57
|
+
})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { Mastra } from '@mastra/core'
|
|
62
|
+
import { workspace } from './workspace'
|
|
63
|
+
|
|
64
|
+
export const mastra = new Mastra({
|
|
65
|
+
workspace,
|
|
66
|
+
})
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
|
|
70
|
+
|
|
71
|
+
## Injected environment variables
|
|
72
|
+
|
|
73
|
+
Every deploy that runs on a platform environment with a workspace receives these variables:
|
|
74
|
+
|
|
75
|
+
| Variable | Contents |
|
|
76
|
+
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `MASTRA_PLATFORM_ACCESS_TOKEN` | Access token scoped to the deploy. Used by the workspace providers to authenticate. |
|
|
78
|
+
| `MASTRA_PROJECT_ID` | Project the deploy belongs to. |
|
|
79
|
+
| `MASTRA_ENVIRONMENT_ID` | Environment the deploy belongs to. Selects which sandbox pool the platform uses. |
|
|
80
|
+
| `MASTRA_PLATFORM_BUCKET_NAME` | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes. |
|
|
81
|
+
|
|
82
|
+
These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
|
|
83
|
+
|
|
84
|
+
## Local development
|
|
85
|
+
|
|
86
|
+
Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
MASTRA_PLATFORM_ACCESS_TOKEN=your-access-token
|
|
90
|
+
MASTRA_PROJECT_ID=your-project-id
|
|
91
|
+
MASTRA_ENVIRONMENT_ID=your-environment-id
|
|
92
|
+
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform — they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
|
|
96
|
+
|
|
97
|
+
For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
|
|
98
|
+
|
|
99
|
+
## Inspect the workspace
|
|
100
|
+
|
|
101
|
+
The Workspaces tab in your platform project shows, per environment:
|
|
102
|
+
|
|
103
|
+
- Bucket status and its contents, with upload, download, and delete actions.
|
|
104
|
+
- Recent sandbox sessions with their command, exit code, and duration.
|
|
105
|
+
- Provisioning failures with a **Retry** action.
|
|
106
|
+
|
|
107
|
+
## See also
|
|
108
|
+
|
|
109
|
+
- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem) — reference for the filesystem provider.
|
|
110
|
+
- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox) — reference for the sandbox provider.
|
|
111
|
+
- [Environments](https://mastra.ai/docs/mastra-platform/environments) — how environments scope workspaces, variables, and databases.
|
|
@@ -23,6 +23,7 @@ Available providers:
|
|
|
23
23
|
- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
|
|
24
24
|
- [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
|
|
25
25
|
- [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
|
|
26
|
+
- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): Stores files in a Mastra Platform workspace bucket
|
|
26
27
|
- [`GoogleDriveFilesystem`](https://mastra.ai/reference/workspace/google-drive-filesystem): Stores files inside a Google Drive folder
|
|
27
28
|
- [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
|
|
28
29
|
- [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends
|
|
@@ -26,6 +26,7 @@ A sandbox provider executes commands in a controlled environment:
|
|
|
26
26
|
- [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
|
|
27
27
|
- [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
|
|
28
28
|
- [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
|
|
29
|
+
- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): Executes commands in a sandbox tied to a Mastra Platform environment
|
|
29
30
|
- [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
|
|
30
31
|
|
|
31
32
|
## Basic usage
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# OpenRouter
|
|
4
4
|
|
|
5
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 337 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
8
8
|
|
|
@@ -140,6 +140,7 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
140
140
|
| `kwaipilot/kat-coder-pro-v2` |
|
|
141
141
|
| `kwaipilot/kat-coder-pro-v2.5` |
|
|
142
142
|
| `mancer/weaver` |
|
|
143
|
+
| `meituan/longcat-2.0` |
|
|
143
144
|
| `meta-llama/llama-3.1-70b-instruct` |
|
|
144
145
|
| `meta-llama/llama-3.1-8b-instruct` |
|
|
145
146
|
| `meta-llama/llama-3.2-1b-instruct` |
|
package/.docs/models/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Model Providers
|
|
4
4
|
|
|
5
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
5
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4852 models from 156 providers through a single API.
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Alibaba Token Plan (China)
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 19 Alibaba Token Plan (China) models through Mastra's model router. Authentication is handled automatically using the `ALIBABA_TOKEN_PLAN_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Alibaba Token Plan (China) documentation](https://www.alibabacloud.com/help/zh/model-studio/token-plan-overview).
|
|
8
8
|
|
|
@@ -34,26 +34,27 @@ for await (const chunk of stream) {
|
|
|
34
34
|
|
|
35
35
|
## Models
|
|
36
36
|
|
|
37
|
-
| Model
|
|
38
|
-
|
|
|
39
|
-
| `alibaba-token-plan-cn/deepseek-v3.2`
|
|
40
|
-
| `alibaba-token-plan-cn/deepseek-v4-flash`
|
|
41
|
-
| `alibaba-token-plan-cn/deepseek-v4-pro`
|
|
42
|
-
| `alibaba-token-plan-cn/glm-5`
|
|
43
|
-
| `alibaba-token-plan-cn/glm-5.1`
|
|
44
|
-
| `alibaba-token-plan-cn/glm-5.2`
|
|
45
|
-
| `alibaba-token-plan-cn/kimi-k2.5`
|
|
46
|
-
| `alibaba-token-plan-cn/kimi-k2.6`
|
|
47
|
-
| `alibaba-token-plan-cn/kimi-k2.7-code`
|
|
48
|
-
| `alibaba-token-plan-cn/MiniMax-M2.5`
|
|
49
|
-
| `alibaba-token-plan-cn/qwen-image-2.0`
|
|
50
|
-
| `alibaba-token-plan-cn/qwen-image-2.0-pro`
|
|
51
|
-
| `alibaba-token-plan-cn/qwen3.6-flash`
|
|
52
|
-
| `alibaba-token-plan-cn/qwen3.6-plus`
|
|
53
|
-
| `alibaba-token-plan-cn/qwen3.7-max`
|
|
54
|
-
| `alibaba-token-plan-cn/qwen3.7-plus`
|
|
55
|
-
| `alibaba-token-plan-cn/
|
|
56
|
-
| `alibaba-token-plan-cn/wan2.7-image
|
|
37
|
+
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
38
|
+
| ------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
39
|
+
| `alibaba-token-plan-cn/deepseek-v3.2` | 131K | | | | | | — | — |
|
|
40
|
+
| `alibaba-token-plan-cn/deepseek-v4-flash` | 1.0M | | | | | | — | — |
|
|
41
|
+
| `alibaba-token-plan-cn/deepseek-v4-pro` | 1.0M | | | | | | — | — |
|
|
42
|
+
| `alibaba-token-plan-cn/glm-5` | 203K | | | | | | — | — |
|
|
43
|
+
| `alibaba-token-plan-cn/glm-5.1` | 203K | | | | | | — | — |
|
|
44
|
+
| `alibaba-token-plan-cn/glm-5.2` | 1.0M | | | | | | — | — |
|
|
45
|
+
| `alibaba-token-plan-cn/kimi-k2.5` | 262K | | | | | | — | — |
|
|
46
|
+
| `alibaba-token-plan-cn/kimi-k2.6` | 262K | | | | | | — | — |
|
|
47
|
+
| `alibaba-token-plan-cn/kimi-k2.7-code` | 262K | | | | | | — | — |
|
|
48
|
+
| `alibaba-token-plan-cn/MiniMax-M2.5` | 197K | | | | | | — | — |
|
|
49
|
+
| `alibaba-token-plan-cn/qwen-image-2.0` | 8K | | | | | | — | — |
|
|
50
|
+
| `alibaba-token-plan-cn/qwen-image-2.0-pro` | 8K | | | | | | — | — |
|
|
51
|
+
| `alibaba-token-plan-cn/qwen3.6-flash` | 1.0M | | | | | | — | — |
|
|
52
|
+
| `alibaba-token-plan-cn/qwen3.6-plus` | 1.0M | | | | | | — | — |
|
|
53
|
+
| `alibaba-token-plan-cn/qwen3.7-max` | 1.0M | | | | | | — | — |
|
|
54
|
+
| `alibaba-token-plan-cn/qwen3.7-plus` | 1.0M | | | | | | — | — |
|
|
55
|
+
| `alibaba-token-plan-cn/qwen3.8-max-preview` | 1.0M | | | | | | — | — |
|
|
56
|
+
| `alibaba-token-plan-cn/wan2.7-image` | 8K | | | | | | — | — |
|
|
57
|
+
| `alibaba-token-plan-cn/wan2.7-image-pro` | 8K | | | | | | — | — |
|
|
57
58
|
|
|
58
59
|
## Advanced configuration
|
|
59
60
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Alibaba Token Plan
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 19 Alibaba Token Plan models through Mastra's model router. Authentication is handled automatically using the `ALIBABA_TOKEN_PLAN_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Alibaba Token Plan documentation](https://www.alibabacloud.com/help/en/model-studio/token-plan-overview).
|
|
8
8
|
|
|
@@ -34,26 +34,27 @@ for await (const chunk of stream) {
|
|
|
34
34
|
|
|
35
35
|
## Models
|
|
36
36
|
|
|
37
|
-
| Model
|
|
38
|
-
|
|
|
39
|
-
| `alibaba-token-plan/deepseek-v3.2`
|
|
40
|
-
| `alibaba-token-plan/deepseek-v4-flash`
|
|
41
|
-
| `alibaba-token-plan/deepseek-v4-pro`
|
|
42
|
-
| `alibaba-token-plan/glm-5`
|
|
43
|
-
| `alibaba-token-plan/glm-5.1`
|
|
44
|
-
| `alibaba-token-plan/glm-5.2`
|
|
45
|
-
| `alibaba-token-plan/kimi-k2.5`
|
|
46
|
-
| `alibaba-token-plan/kimi-k2.6`
|
|
47
|
-
| `alibaba-token-plan/kimi-k2.7-code`
|
|
48
|
-
| `alibaba-token-plan/MiniMax-M2.5`
|
|
49
|
-
| `alibaba-token-plan/qwen-image-2.0`
|
|
50
|
-
| `alibaba-token-plan/qwen-image-2.0-pro`
|
|
51
|
-
| `alibaba-token-plan/qwen3.6-flash`
|
|
52
|
-
| `alibaba-token-plan/qwen3.6-plus`
|
|
53
|
-
| `alibaba-token-plan/qwen3.7-max`
|
|
54
|
-
| `alibaba-token-plan/qwen3.7-plus`
|
|
55
|
-
| `alibaba-token-plan/
|
|
56
|
-
| `alibaba-token-plan/wan2.7-image
|
|
37
|
+
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
38
|
+
| ---------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
39
|
+
| `alibaba-token-plan/deepseek-v3.2` | 131K | | | | | | — | — |
|
|
40
|
+
| `alibaba-token-plan/deepseek-v4-flash` | 1.0M | | | | | | — | — |
|
|
41
|
+
| `alibaba-token-plan/deepseek-v4-pro` | 1.0M | | | | | | — | — |
|
|
42
|
+
| `alibaba-token-plan/glm-5` | 203K | | | | | | — | — |
|
|
43
|
+
| `alibaba-token-plan/glm-5.1` | 203K | | | | | | — | — |
|
|
44
|
+
| `alibaba-token-plan/glm-5.2` | 1.0M | | | | | | — | — |
|
|
45
|
+
| `alibaba-token-plan/kimi-k2.5` | 262K | | | | | | — | — |
|
|
46
|
+
| `alibaba-token-plan/kimi-k2.6` | 262K | | | | | | — | — |
|
|
47
|
+
| `alibaba-token-plan/kimi-k2.7-code` | 262K | | | | | | — | — |
|
|
48
|
+
| `alibaba-token-plan/MiniMax-M2.5` | 197K | | | | | | — | — |
|
|
49
|
+
| `alibaba-token-plan/qwen-image-2.0` | 8K | | | | | | — | — |
|
|
50
|
+
| `alibaba-token-plan/qwen-image-2.0-pro` | 8K | | | | | | — | — |
|
|
51
|
+
| `alibaba-token-plan/qwen3.6-flash` | 1.0M | | | | | | — | — |
|
|
52
|
+
| `alibaba-token-plan/qwen3.6-plus` | 1.0M | | | | | | — | — |
|
|
53
|
+
| `alibaba-token-plan/qwen3.7-max` | 1.0M | | | | | | — | — |
|
|
54
|
+
| `alibaba-token-plan/qwen3.7-plus` | 1.0M | | | | | | — | — |
|
|
55
|
+
| `alibaba-token-plan/qwen3.8-max-preview` | 1.0M | | | | | | — | — |
|
|
56
|
+
| `alibaba-token-plan/wan2.7-image` | 8K | | | | | | — | — |
|
|
57
|
+
| `alibaba-token-plan/wan2.7-image-pro` | 8K | | | | | | — | — |
|
|
57
58
|
|
|
58
59
|
## Advanced configuration
|
|
59
60
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# NovitaAI
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 107 NovitaAI models through Mastra's model router. Authentication is handled automatically using the `NOVITA_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [NovitaAI documentation](https://novita.ai/docs/guides/introduction).
|
|
8
8
|
|
|
@@ -90,6 +90,8 @@ for await (const chunk of stream) {
|
|
|
90
90
|
| `novita-ai/moonshotai/kimi-k2-thinking` | 262K | | | | | | $0.60 | $3 |
|
|
91
91
|
| `novita-ai/moonshotai/kimi-k2.5` | 262K | | | | | | $0.60 | $3 |
|
|
92
92
|
| `novita-ai/moonshotai/kimi-k2.6` | 262K | | | | | | $0.80 | $3 |
|
|
93
|
+
| `novita-ai/moonshotai/kimi-k2.7-code` | 262K | | | | | | $0.95 | $4 |
|
|
94
|
+
| `novita-ai/moonshotai/kimi-k3` | 1.0M | | | | | | $3 | $15 |
|
|
93
95
|
| `novita-ai/nousresearch/hermes-2-pro-llama-3-8b` | 8K | | | | | | $0.14 | $0.14 |
|
|
94
96
|
| `novita-ai/openai/gpt-oss-120b` | 131K | | | | | | $0.05 | $0.25 |
|
|
95
97
|
| `novita-ai/openai/gpt-oss-20b` | 131K | | | | | | $0.04 | $0.15 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# ZenMux
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 120 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [ZenMux documentation](https://docs.zenmux.ai).
|
|
8
8
|
|
|
@@ -84,6 +84,7 @@ for await (const chunk of stream) {
|
|
|
84
84
|
| `zenmux/moonshotai/kimi-k2.7-code` | 262K | | | | | | $0.95 | $4 |
|
|
85
85
|
| `zenmux/moonshotai/kimi-k2.7-code-free` | 262K | | | | | | — | — |
|
|
86
86
|
| `zenmux/moonshotai/kimi-k3` | 1.0M | | | | | | $3 | $15 |
|
|
87
|
+
| `zenmux/moonshotai/kimi-k3-free` | 1.0M | | | | | | — | — |
|
|
87
88
|
| `zenmux/openai/gpt-5` | 400K | | | | | | $1 | $10 |
|
|
88
89
|
| `zenmux/openai/gpt-5-codex` | 400K | | | | | | $1 | $10 |
|
|
89
90
|
| `zenmux/openai/gpt-5.1` | 400K | | | | | | $1 | $10 |
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# Context recall scorer
|
|
4
|
+
|
|
5
|
+
The `createContextRecallScorer()` function creates a scorer that evaluates how well retrieved context covers the claims in a ground-truth reference answer. It measures retrieval completeness by checking what fraction of the ground truth's claims are attributable to the retrieved context.
|
|
6
|
+
|
|
7
|
+
This scorer requires a ground-truth reference answer, making it suitable for labeled datasets in CI or test environments. When `groundTruth` is not provided in the run, the scorer returns a score of 0 rather than throwing an error.
|
|
8
|
+
|
|
9
|
+
## RAG retrieval evaluation
|
|
10
|
+
|
|
11
|
+
Ideal for evaluating retrieval completeness in RAG pipelines where:
|
|
12
|
+
|
|
13
|
+
- You need to verify the retriever fetches all necessary information
|
|
14
|
+
- You have labeled datasets with known-correct answers
|
|
15
|
+
- You want to catch regressions in what the retriever returns
|
|
16
|
+
|
|
17
|
+
## Dataset-driven testing
|
|
18
|
+
|
|
19
|
+
Use when running evaluations against curated test sets:
|
|
20
|
+
|
|
21
|
+
- CI pipelines with ground-truth labeled questions
|
|
22
|
+
- A/B testing retrieval strategies
|
|
23
|
+
- Benchmarking embedding models for coverage
|
|
24
|
+
|
|
25
|
+
## Parameters
|
|
26
|
+
|
|
27
|
+
**model** (`MastraModelConfig`): The language model to use for evaluating claim attribution
|
|
28
|
+
|
|
29
|
+
**options** (`ContextRecallMetricOptions`): Configuration options for the scorer
|
|
30
|
+
|
|
31
|
+
**Note**: Either `context` or `contextExtractor` must be provided. When both are provided, `contextExtractor` is used only if the run input and output are agent-shaped (`MastraDBMessage[]`); otherwise the scorer falls back to `context`.
|
|
32
|
+
|
|
33
|
+
## `.run()` returns
|
|
34
|
+
|
|
35
|
+
**score** (`number`): Recall score between 0 and scale (default 0-1), representing the fraction of ground-truth claims covered by the context
|
|
36
|
+
|
|
37
|
+
**reason** (`string`): Human-readable explanation of which ground-truth claims were and were not found in the context
|
|
38
|
+
|
|
39
|
+
## Scoring details
|
|
40
|
+
|
|
41
|
+
### Claim attribution
|
|
42
|
+
|
|
43
|
+
Context Recall uses a two-step LLM evaluation followed by a deterministic score calculation:
|
|
44
|
+
|
|
45
|
+
1. **Claim extraction**: The ground-truth answer is decomposed into atomic claims
|
|
46
|
+
2. **Attribution check**: Each claim is checked against the retrieval context for support
|
|
47
|
+
|
|
48
|
+
The score is then calculated as the ratio of attributed claims to total claims, multiplied by scale.
|
|
49
|
+
|
|
50
|
+
### Scoring formula
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
Context Recall = attributed_claims / total_claims × scale
|
|
54
|
+
|
|
55
|
+
Where:
|
|
56
|
+
- attributed_claims = number of ground-truth claims supported by the context
|
|
57
|
+
- total_claims = total number of claims extracted from the ground truth
|
|
58
|
+
- Attribution is binary: a claim is either supported (yes) or not (no)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Score interpretation
|
|
62
|
+
|
|
63
|
+
These ranges assume the default `scale` of 1. When using a custom scale, multiply accordingly.
|
|
64
|
+
|
|
65
|
+
- **0.9-1.0**: Excellent recall — context covers nearly all ground-truth claims
|
|
66
|
+
- **0.7-0.8**: Good recall — most claims are covered, minor gaps
|
|
67
|
+
- **0.4-0.6**: Moderate recall — significant information missing from context
|
|
68
|
+
- **0.1-0.3**: Poor recall — most ground-truth claims not found in context
|
|
69
|
+
- **0.0**: No recall — none of the ground-truth claims are in the context
|
|
70
|
+
|
|
71
|
+
### Reason analysis
|
|
72
|
+
|
|
73
|
+
The reason field explains:
|
|
74
|
+
|
|
75
|
+
- Which ground-truth claims were found in the context
|
|
76
|
+
- Which claims were missing and what information gaps exist
|
|
77
|
+
- Specific context pieces that supported attributed claims
|
|
78
|
+
|
|
79
|
+
### Optimization insights
|
|
80
|
+
|
|
81
|
+
Use results to:
|
|
82
|
+
|
|
83
|
+
- **Improve retrieval**: Identify what types of information the retriever misses
|
|
84
|
+
- **Tune chunk size**: Ensure chunks contain enough detail to cover ground-truth claims
|
|
85
|
+
- **Evaluate embeddings**: Test different embedding models for better information coverage
|
|
86
|
+
- **Expand knowledge base**: Add documents that cover frequently missed claims
|
|
87
|
+
|
|
88
|
+
### Example calculation
|
|
89
|
+
|
|
90
|
+
Given ground truth: "Einstein was born in 1879. He developed relativity. He won the Nobel Prize."
|
|
91
|
+
|
|
92
|
+
Claims extracted: 3
|
|
93
|
+
|
|
94
|
+
- "Einstein was born in 1879" → attributed (context mentions birthdate)
|
|
95
|
+
- "Einstein developed relativity" → attributed (context covers relativity)
|
|
96
|
+
- "Einstein won the Nobel Prize" → not attributed (context doesn't mention Nobel Prize)
|
|
97
|
+
|
|
98
|
+
Recall = 2/3 = 0.67
|
|
99
|
+
|
|
100
|
+
## Scorer configuration
|
|
101
|
+
|
|
102
|
+
### Dynamic context extraction
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
const scorer = createContextRecallScorer({
|
|
106
|
+
model: 'openai/gpt-5.5',
|
|
107
|
+
options: {
|
|
108
|
+
contextExtractor: (input, output) => {
|
|
109
|
+
const query = input?.inputMessages?.[0]?.content || ''
|
|
110
|
+
const searchResults = vectorDB.search(query, { limit: 10 })
|
|
111
|
+
return searchResults.map(result => result.content)
|
|
112
|
+
},
|
|
113
|
+
scale: 1,
|
|
114
|
+
},
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Static context evaluation
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
const scorer = createContextRecallScorer({
|
|
122
|
+
model: 'openai/gpt-5.5',
|
|
123
|
+
options: {
|
|
124
|
+
context: [
|
|
125
|
+
'Document 1: Einstein was born on 14 March 1879 in Ulm, Germany.',
|
|
126
|
+
'Document 2: Einstein published the theory of special relativity in 1905.',
|
|
127
|
+
'Document 3: Einstein moved to the United States in 1933.',
|
|
128
|
+
],
|
|
129
|
+
},
|
|
130
|
+
})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Example
|
|
134
|
+
|
|
135
|
+
Evaluate RAG retrieval completeness against a labeled dataset:
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
import { runEvals } from '@mastra/core/evals'
|
|
139
|
+
import { createContextRecallScorer } from '@mastra/evals/scorers/prebuilt'
|
|
140
|
+
import { myAgent } from './agent'
|
|
141
|
+
|
|
142
|
+
const scorer = createContextRecallScorer({
|
|
143
|
+
model: 'openai/gpt-5.5',
|
|
144
|
+
options: {
|
|
145
|
+
contextExtractor: (input, output) => {
|
|
146
|
+
// Extract context from tool invocation results in the agent output
|
|
147
|
+
return output
|
|
148
|
+
.filter(msg => msg?.role === 'assistant')
|
|
149
|
+
.flatMap(msg => msg?.content?.toolInvocations ?? [])
|
|
150
|
+
.filter((tool: any) => tool.state === 'result')
|
|
151
|
+
.map((tool: any) => JSON.stringify(tool.result))
|
|
152
|
+
},
|
|
153
|
+
},
|
|
154
|
+
})
|
|
155
|
+
|
|
156
|
+
const result = await runEvals({
|
|
157
|
+
data: [
|
|
158
|
+
{
|
|
159
|
+
input: 'What are the health benefits of green tea?',
|
|
160
|
+
groundTruth:
|
|
161
|
+
'Green tea contains antioxidants that reduce inflammation, L-theanine that improves focus, and catechins that boost metabolism.',
|
|
162
|
+
},
|
|
163
|
+
{
|
|
164
|
+
input: 'How does photosynthesis work?',
|
|
165
|
+
groundTruth:
|
|
166
|
+
'Photosynthesis converts sunlight into chemical energy using chlorophyll in chloroplasts, producing glucose and oxygen from carbon dioxide and water.',
|
|
167
|
+
},
|
|
168
|
+
],
|
|
169
|
+
scorers: [scorer],
|
|
170
|
+
target: myAgent,
|
|
171
|
+
onItemComplete: ({ scorerResults }) => {
|
|
172
|
+
console.log({
|
|
173
|
+
score: scorerResults[scorer.id].score,
|
|
174
|
+
reason: scorerResults[scorer.id].reason,
|
|
175
|
+
})
|
|
176
|
+
},
|
|
177
|
+
})
|
|
178
|
+
|
|
179
|
+
console.log(result.scores)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
For more details on `runEvals`, see the [runEvals reference](https://mastra.ai/reference/evals/run-evals).
|
|
183
|
+
|
|
184
|
+
To add this scorer to an agent, see the [Scorers overview](https://mastra.ai/docs/evals/overview) guide.
|
|
185
|
+
|
|
186
|
+
## Comparison with context precision
|
|
187
|
+
|
|
188
|
+
Choose the right scorer for your needs:
|
|
189
|
+
|
|
190
|
+
| Use case | Context Recall | Context Precision |
|
|
191
|
+
| ------------------------- | ------------------------ | ----------------------------- |
|
|
192
|
+
| **What it measures** | Coverage of ground truth | Relevance of retrieved chunks |
|
|
193
|
+
| **Direction** | Ground truth → context | Context → ground truth |
|
|
194
|
+
| **Position sensitive** | No | Yes (rewards early placement) |
|
|
195
|
+
| **Requires ground truth** | Yes | Yes |
|
|
196
|
+
| **Failure mode caught** | Missing information | Irrelevant noise |
|
|
197
|
+
|
|
198
|
+
Use both together for a complete picture of retrieval quality: precision catches junk in the context, recall catches gaps.
|
|
199
|
+
|
|
200
|
+
## Related
|
|
201
|
+
|
|
202
|
+
- [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision): Evaluates if retrieved context is relevant and well-ranked
|
|
203
|
+
- [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance): Evaluates context usage and quality
|
|
204
|
+
- [Faithfulness Scorer](https://mastra.ai/reference/evals/faithfulness): Measures answer groundedness in context
|
|
205
|
+
- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers): Creating your own evaluation metrics
|
package/.docs/reference/index.md
CHANGED
|
@@ -143,6 +143,7 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
143
143
|
- [Completeness](https://mastra.ai/reference/evals/completeness)
|
|
144
144
|
- [Content Similarity Scorer](https://mastra.ai/reference/evals/content-similarity)
|
|
145
145
|
- [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision)
|
|
146
|
+
- [Context Recall Scorer](https://mastra.ai/reference/evals/context-recall)
|
|
146
147
|
- [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance)
|
|
147
148
|
- [Faithfulness](https://mastra.ai/reference/evals/faithfulness)
|
|
148
149
|
- [Hallucination](https://mastra.ai/reference/evals/hallucination)
|
|
@@ -394,6 +395,8 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
394
395
|
- [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
|
|
395
396
|
- [MesaFilesystem](https://mastra.ai/reference/workspace/mesa-filesystem)
|
|
396
397
|
- [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
|
|
398
|
+
- [PlatformFilesystem](https://mastra.ai/reference/workspace/platform-filesystem)
|
|
399
|
+
- [PlatformSandbox](https://mastra.ai/reference/workspace/platform-sandbox)
|
|
397
400
|
- [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
|
|
398
401
|
- [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
|
|
399
402
|
- [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# PlatformFilesystem
|
|
4
|
+
|
|
5
|
+
Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
|
|
6
|
+
|
|
7
|
+
Use `PlatformFilesystem` when your agent runs on a Mastra Platform deployment and you want the filesystem to be backed by the platform-provisioned bucket. For direct S3 access, see [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem). For a local directory during development, see [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem).
|
|
8
|
+
|
|
9
|
+
> **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
**npm**:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @mastra/platform-workspace
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
**pnpm**:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @mastra/platform-workspace
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**Yarn**:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
yarn add @mastra/platform-workspace
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Bun**:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
bun add @mastra/platform-workspace
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Configure the platform credentials. The access token, project ID, and bucket name fall back to environment variables, so a Mastra Platform deployment can pass zero constructor options.
|
|
38
|
+
|
|
39
|
+
**.env file**:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
|
|
43
|
+
MASTRA_PROJECT_ID=your-project-id
|
|
44
|
+
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Constructor**:
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
new PlatformFilesystem({
|
|
51
|
+
accessToken: 'your-platform-access-token',
|
|
52
|
+
projectId: 'your-project-id',
|
|
53
|
+
bucketName: 'your-bucket-name',
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
|
|
58
|
+
|
|
59
|
+
## Usage
|
|
60
|
+
|
|
61
|
+
Add a `PlatformFilesystem` to a workspace and assign it to an agent:
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
import { Agent } from '@mastra/core/agent'
|
|
65
|
+
import { Workspace } from '@mastra/core/workspace'
|
|
66
|
+
import { PlatformFilesystem } from '@mastra/platform-workspace'
|
|
67
|
+
|
|
68
|
+
const workspace = new Workspace({
|
|
69
|
+
filesystem: new PlatformFilesystem({
|
|
70
|
+
// accessToken, projectId, bucketName all fall back to env vars
|
|
71
|
+
}),
|
|
72
|
+
})
|
|
73
|
+
|
|
74
|
+
const agent = new Agent({
|
|
75
|
+
id: 'file-agent',
|
|
76
|
+
name: 'File Agent',
|
|
77
|
+
instructions: 'You are a research assistant that reads and writes reports.',
|
|
78
|
+
model: 'anthropic/claude-sonnet-4-6',
|
|
79
|
+
workspace,
|
|
80
|
+
})
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Reading and writing files
|
|
84
|
+
|
|
85
|
+
Object keys are percent-encoded per segment, so filenames with `?`, `#`, `%`, `&`, `+`, or spaces are preserved end-to-end:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
const fs = new PlatformFilesystem()
|
|
89
|
+
|
|
90
|
+
await fs.writeFile('/analyses/repo.md', markdown)
|
|
91
|
+
const content = await fs.readFile('/analyses/repo.md')
|
|
92
|
+
const entries = await fs.readdir('/analyses')
|
|
93
|
+
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Read-only mode
|
|
97
|
+
|
|
98
|
+
Pass `readOnly: true` to mount the bucket read-only. Any mutating call throws `WorkspaceReadOnlyError`:
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
const fs = new PlatformFilesystem({ readOnly: true })
|
|
102
|
+
|
|
103
|
+
await fs.readFile('/analyses/repo.md') // ok
|
|
104
|
+
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Overwrite semantics
|
|
108
|
+
|
|
109
|
+
`writeFile` supports `overwrite: false` and throws `FileExistsError` when the destination already exists.
|
|
110
|
+
|
|
111
|
+
`copyFile` and `moveFile` always overwrite the destination. Passing `overwrite: false` to either method throws an error rather than silently overwriting.
|
|
112
|
+
|
|
113
|
+
### Appending files
|
|
114
|
+
|
|
115
|
+
`appendFile` is a read-modify-write and is not atomic. Concurrent appends to the same path can overwrite each other. For concurrent writers, use `writeFile` with distinct keys.
|
|
116
|
+
|
|
117
|
+
## Constructor parameters
|
|
118
|
+
|
|
119
|
+
**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
|
|
120
|
+
|
|
121
|
+
**projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
|
|
122
|
+
|
|
123
|
+
**bucketName** (`string`): Platform bucket name to store files in. Falls back to the MASTRA\_PLATFORM\_BUCKET\_NAME environment variable.
|
|
124
|
+
|
|
125
|
+
**readOnly** (`boolean`): When true, all mutating calls throw WorkspaceReadOnlyError. (Default: `false`)
|
|
126
|
+
|
|
127
|
+
**displayName** (`string`): Human-readable name shown in workspace UIs.
|
|
128
|
+
|
|
129
|
+
**description** (`string`): Short description shown in workspace UIs.
|
|
130
|
+
|
|
131
|
+
**icon** (`FilesystemIcon`): Icon shown in workspace UIs.
|
|
132
|
+
|
|
133
|
+
**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
|
|
134
|
+
|
|
135
|
+
**id** (`string`): Unique identifier for this filesystem instance. (Default: `Auto-generated`)
|
|
136
|
+
|
|
137
|
+
**fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
|
|
138
|
+
|
|
139
|
+
## Properties
|
|
140
|
+
|
|
141
|
+
**id** (`string`): Filesystem instance identifier.
|
|
142
|
+
|
|
143
|
+
**name** (`string`): Provider name ('PlatformFilesystem').
|
|
144
|
+
|
|
145
|
+
**provider** (`string`): Provider identifier ('platform').
|
|
146
|
+
|
|
147
|
+
**readOnly** (`boolean | undefined`): Whether the filesystem was mounted read-only.
|
|
148
|
+
|
|
149
|
+
## Errors
|
|
150
|
+
|
|
151
|
+
Filesystem-specific errors match the standard workspace error types:
|
|
152
|
+
|
|
153
|
+
- `FileNotFoundError`: The path does not exist. Thrown by `readFile`, `stat`, and `deleteFile` (unless `force: true` is set).
|
|
154
|
+
- `FileExistsError`: `writeFile` was called with `overwrite: false` and the destination already exists.
|
|
155
|
+
- `WorkspaceReadOnlyError`: A mutating call was made on a read-only filesystem.
|
|
156
|
+
|
|
157
|
+
Other Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string):
|
|
158
|
+
|
|
159
|
+
```typescript
|
|
160
|
+
import { FileNotFoundError, PlatformApiError } from '@mastra/platform-workspace'
|
|
161
|
+
|
|
162
|
+
try {
|
|
163
|
+
await fs.readFile('/missing.txt')
|
|
164
|
+
} catch (err) {
|
|
165
|
+
if (err instanceof FileNotFoundError) {
|
|
166
|
+
// handle missing file
|
|
167
|
+
} else if (err instanceof PlatformApiError) {
|
|
168
|
+
if (err.code === 'authentication_error') {
|
|
169
|
+
// refresh token
|
|
170
|
+
}
|
|
171
|
+
console.error(err.status, err.code, err.proxyMessage)
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`code` and `proxyMessage` are `undefined` when the response body is not JSON, for example an HTML 502 from a load balancer.
|
|
177
|
+
|
|
178
|
+
## Related
|
|
179
|
+
|
|
180
|
+
- [PlatformSandbox reference](https://mastra.ai/reference/workspace/platform-sandbox)
|
|
181
|
+
- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
|
|
182
|
+
- [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# PlatformSandbox
|
|
4
|
+
|
|
5
|
+
Executes commands inside a Mastra Platform sandbox tied to a Platform environment. Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed.
|
|
6
|
+
|
|
7
|
+
Use `PlatformSandbox` when your agent runs on a Mastra Platform deployment and you want the sandbox to be provisioned and managed by the platform. For self-hosted Railway sandboxes, see [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox). For a local sandbox during development, see [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox).
|
|
8
|
+
|
|
9
|
+
> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
**npm**:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @mastra/platform-workspace
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
**pnpm**:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @mastra/platform-workspace
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**Yarn**:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
yarn add @mastra/platform-workspace
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Bun**:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
bun add @mastra/platform-workspace
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Configure the platform credentials. The access token, project ID, and environment ID fall back to environment variables, so a Mastra Platform deployment can pass zero constructor options.
|
|
38
|
+
|
|
39
|
+
**.env file**:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
|
|
43
|
+
MASTRA_PROJECT_ID=your-project-id
|
|
44
|
+
MASTRA_ENVIRONMENT_ID=your-environment-id
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Constructor**:
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
new PlatformSandbox({
|
|
51
|
+
accessToken: 'your-platform-access-token',
|
|
52
|
+
projectId: 'your-project-id',
|
|
53
|
+
environmentId: 'your-environment-id',
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
|
|
58
|
+
|
|
59
|
+
## Usage
|
|
60
|
+
|
|
61
|
+
Add a `PlatformSandbox` to a workspace and assign it to an agent:
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
import { Agent } from '@mastra/core/agent'
|
|
65
|
+
import { Workspace } from '@mastra/core/workspace'
|
|
66
|
+
import { PlatformSandbox } from '@mastra/platform-workspace'
|
|
67
|
+
|
|
68
|
+
const workspace = new Workspace({
|
|
69
|
+
sandbox: new PlatformSandbox({
|
|
70
|
+
// accessToken, projectId, environmentId all fall back to env vars
|
|
71
|
+
idleTimeoutMinutes: 30,
|
|
72
|
+
}),
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
const agent = new Agent({
|
|
76
|
+
id: 'code-agent',
|
|
77
|
+
name: 'Code Agent',
|
|
78
|
+
instructions: 'You are a coding assistant working in this workspace.',
|
|
79
|
+
model: 'anthropic/claude-sonnet-4-6',
|
|
80
|
+
workspace,
|
|
81
|
+
})
|
|
82
|
+
|
|
83
|
+
const response = await agent.generate(
|
|
84
|
+
'Print "Hello, world!" and show the current working directory.',
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
console.log(response.text)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Private networking
|
|
91
|
+
|
|
92
|
+
Set `networkIsolation` to `PRIVATE` to join the environment's private network and reach other services running in the same Mastra Platform environment:
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
const workspace = new Workspace({
|
|
96
|
+
sandbox: new PlatformSandbox({
|
|
97
|
+
networkIsolation: 'PRIVATE',
|
|
98
|
+
}),
|
|
99
|
+
})
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The default `ISOLATED` mode allows outbound internet access only, with no private network connectivity.
|
|
103
|
+
|
|
104
|
+
### Reattaching to a running sandbox
|
|
105
|
+
|
|
106
|
+
Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one. This is useful for stateful agents that resume between requests:
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
const sandbox = new PlatformSandbox({
|
|
110
|
+
sandboxId: 'sbx_abc123',
|
|
111
|
+
})
|
|
112
|
+
await sandbox.start()
|
|
113
|
+
|
|
114
|
+
const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
When `sandboxId` is set, `environmentId` is not required because the sandbox already exists.
|
|
118
|
+
|
|
119
|
+
### Executing commands
|
|
120
|
+
|
|
121
|
+
`executeCommand` runs a command on the remote sandbox and returns its output. Pass `args` to have arguments safely shell-quoted:
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
const result = await sandbox.executeCommand('python', ['analyze.py'], {
|
|
125
|
+
timeout: 30_000,
|
|
126
|
+
cwd: '/workspace',
|
|
127
|
+
env: { INPUT: 'repo' },
|
|
128
|
+
})
|
|
129
|
+
|
|
130
|
+
console.log(result.stdout)
|
|
131
|
+
console.log(result.exitCode)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
> **Warning:** The `command` argument is a shell string and is concatenated verbatim into the remote shell. This lets you use pipes, redirects, and chaining (`ls -la | grep foo`) but means untrusted input must be passed through `args` (safely quoted) or shell-quoted by the caller. Untrusted `command` values allow arbitrary shell execution on the sandbox.
|
|
135
|
+
|
|
136
|
+
## Constructor parameters
|
|
137
|
+
|
|
138
|
+
**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
|
|
139
|
+
|
|
140
|
+
**projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
|
|
141
|
+
|
|
142
|
+
**environmentId** (`string`): Platform environment ID the sandbox belongs to. Falls back to the MASTRA\_ENVIRONMENT\_ID environment variable. Required unless sandboxId is passed.
|
|
143
|
+
|
|
144
|
+
**sandboxId** (`string`): Existing sandbox ID to reattach to instead of creating a new sandbox. When set, environmentId is not required.
|
|
145
|
+
|
|
146
|
+
**idleTimeoutMinutes** (`number`): How long the sandbox stays alive with no activity before the platform destroys it.
|
|
147
|
+
|
|
148
|
+
**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): Network mode. 'ISOLATED' (default) allows outbound internet only. 'PRIVATE' joins the platform environment's private network.
|
|
149
|
+
|
|
150
|
+
**env** (`Record<string, string>`): Environment variables baked into the sandbox at creation time. Per-command environment variables can also be passed to executeCommand.
|
|
151
|
+
|
|
152
|
+
**timeout** (`number`): Default command execution timeout in milliseconds. Overridable per call via ExecuteCommandOptions.timeout.
|
|
153
|
+
|
|
154
|
+
**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
|
|
155
|
+
|
|
156
|
+
**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
|
|
157
|
+
|
|
158
|
+
**fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
|
|
159
|
+
|
|
160
|
+
## Properties
|
|
161
|
+
|
|
162
|
+
**id** (`string`): Sandbox instance identifier.
|
|
163
|
+
|
|
164
|
+
**name** (`string`): Provider name ('PlatformSandbox').
|
|
165
|
+
|
|
166
|
+
**provider** (`string`): Provider identifier ('platform').
|
|
167
|
+
|
|
168
|
+
**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'.
|
|
169
|
+
|
|
170
|
+
**processes** (`PlatformProcessManager`): Background process manager. See SandboxProcessManager reference.
|
|
171
|
+
|
|
172
|
+
## Errors
|
|
173
|
+
|
|
174
|
+
Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string); the raw response body stays available on `.body`:
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
import { PlatformApiError } from '@mastra/platform-workspace'
|
|
178
|
+
|
|
179
|
+
try {
|
|
180
|
+
await sandbox.executeCommand('cat', ['/missing.txt'])
|
|
181
|
+
} catch (err) {
|
|
182
|
+
if (err instanceof PlatformApiError) {
|
|
183
|
+
if (err.code === 'not_found') {
|
|
184
|
+
// handle missing resource
|
|
185
|
+
} else if (err.code === 'authentication_error') {
|
|
186
|
+
// refresh token
|
|
187
|
+
}
|
|
188
|
+
console.error(err.status, err.code, err.proxyMessage)
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`code` and `proxyMessage` are `undefined` when the response body is not JSON, for example an HTML 502 from a load balancer.
|
|
194
|
+
|
|
195
|
+
## Related
|
|
196
|
+
|
|
197
|
+
- [PlatformFilesystem reference](https://mastra.ai/reference/workspace/platform-filesystem)
|
|
198
|
+
- [RailwaySandbox reference](https://mastra.ai/reference/workspace/railway-sandbox)
|
|
199
|
+
- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
|
|
200
|
+
- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 1.2.8-alpha.18
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`0a2c22c`](https://github.com/mastra-ai/mastra/commit/0a2c22c902604439ec490319e14c17f331e0c84c), [`3a8024c`](https://github.com/mastra-ai/mastra/commit/3a8024ce615f8aa89479c0d71fe61d10bb0040be)]:
|
|
8
|
+
- @mastra/core@1.52.0-alpha.9
|
|
9
|
+
|
|
3
10
|
## 1.2.8-alpha.16
|
|
4
11
|
|
|
5
12
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.8-alpha.
|
|
3
|
+
"version": "1.2.8-alpha.19",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
"jsdom": "^26.1.0",
|
|
29
29
|
"local-pkg": "^1.1.2",
|
|
30
30
|
"zod": "^4.4.3",
|
|
31
|
-
"@mastra/
|
|
32
|
-
"@mastra/
|
|
31
|
+
"@mastra/mcp": "^1.15.0-alpha.0",
|
|
32
|
+
"@mastra/core": "1.52.0-alpha.9"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
35
|
"@hono/node-server": "^1.19.14",
|
|
@@ -42,12 +42,12 @@
|
|
|
42
42
|
"eslint": "^10.7.0",
|
|
43
43
|
"hono": "^4.12.8",
|
|
44
44
|
"tsup": "^8.5.1",
|
|
45
|
-
"tsx": "^4.
|
|
45
|
+
"tsx": "^4.23.1",
|
|
46
46
|
"typescript": "^6.0.3",
|
|
47
47
|
"vitest": "4.1.10",
|
|
48
48
|
"@internal/lint": "0.0.114",
|
|
49
|
-
"@
|
|
50
|
-
"@
|
|
49
|
+
"@mastra/core": "1.52.0-alpha.9",
|
|
50
|
+
"@internal/types-builder": "0.0.89"
|
|
51
51
|
},
|
|
52
52
|
"homepage": "https://mastra.ai",
|
|
53
53
|
"repository": {
|