@mastra/mcp-docs-server 1.1.33-alpha.3 → 1.1.33-alpha.6
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/agents/guardrails.md +60 -0
- package/.docs/docs/agents/processors.md +36 -0
- package/.docs/docs/deployment/workflow-runners.md +7 -1
- package/.docs/docs/mcp/overview.md +25 -0
- package/.docs/docs/server/auth/fga.md +141 -0
- package/.docs/docs/server/auth/workos.md +52 -9
- package/.docs/guides/deployment/temporal.md +232 -0
- package/.docs/models/gateways/openrouter.md +3 -1
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/alibaba.md +2 -1
- package/.docs/models/providers/cortecs.md +16 -2
- package/.docs/models/providers/firmware.md +7 -6
- package/.docs/models/providers/neuralwatt.md +84 -0
- package/.docs/models/providers/nvidia.md +2 -1
- package/.docs/models/providers/perplexity-agent.md +3 -1
- package/.docs/models/providers/synthetic.md +2 -1
- package/.docs/models/providers/zhipuai-coding-plan.md +9 -8
- package/.docs/models/providers.md +1 -0
- package/.docs/reference/auth/workos.md +54 -9
- package/.docs/reference/index.md +2 -0
- package/.docs/reference/processors/cost-guard-processor.md +112 -0
- package/.docs/reference/processors/processor-interface.md +5 -0
- package/.docs/reference/processors/regex-filter-processor.md +106 -0
- package/.docs/reference/tools/perplexity.md +0 -2
- package/.docs/reference/tools/tavily.md +0 -2
- package/CHANGELOG.md +8 -0
- package/package.json +5 -5
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Cortecs
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 49 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Cortecs documentation](https://cortecs.ai).
|
|
6
6
|
|
|
@@ -41,7 +41,12 @@ for await (const chunk of stream) {
|
|
|
41
41
|
| `cortecs/claude-opus4-6` | 1.0M | | | | | | $6 | $30 |
|
|
42
42
|
| `cortecs/claude-opus4-7` | 1.0M | | | | | | $6 | $28 |
|
|
43
43
|
| `cortecs/claude-sonnet-4` | 200K | | | | | | $3 | $17 |
|
|
44
|
+
| `cortecs/codestral-2508` | 256K | | | | | | $0.30 | $0.90 |
|
|
45
|
+
| `cortecs/deepseek-r1-0528` | 164K | | | | | | $0.58 | $2 |
|
|
44
46
|
| `cortecs/deepseek-v3-0324` | 128K | | | | | | $0.55 | $2 |
|
|
47
|
+
| `cortecs/deepseek-v3.2` | 164K | | | | | | $0.27 | $0.44 |
|
|
48
|
+
| `cortecs/deepseek-v4-flash` | 1.0M | | | | | | $0.13 | $0.27 |
|
|
49
|
+
| `cortecs/deepseek-v4-pro` | 1.0M | | | | | | $2 | $3 |
|
|
45
50
|
| `cortecs/devstral-2512` | 262K | | | | | | — | — |
|
|
46
51
|
| `cortecs/devstral-small-2512` | 262K | | | | | | — | — |
|
|
47
52
|
| `cortecs/gemini-2.5-pro` | 1.0M | | | | | | $2 | $11 |
|
|
@@ -53,22 +58,31 @@ for await (const chunk of stream) {
|
|
|
53
58
|
| `cortecs/glm-5.1` | 205K | | | | | | $1 | $4 |
|
|
54
59
|
| `cortecs/gpt-4.1` | 1.0M | | | | | | $2 | $9 |
|
|
55
60
|
| `cortecs/gpt-oss-120b` | 128K | | | | | | — | — |
|
|
61
|
+
| `cortecs/hermes-4-70b` | 128K | | | | | | $0.12 | $0.36 |
|
|
56
62
|
| `cortecs/intellect-3` | 128K | | | | | | $0.22 | $1 |
|
|
57
63
|
| `cortecs/kimi-k2-instruct` | 131K | | | | | | $0.55 | $3 |
|
|
58
64
|
| `cortecs/kimi-k2-thinking` | 262K | | | | | | $0.66 | $3 |
|
|
59
65
|
| `cortecs/kimi-k2.5` | 256K | | | | | | $0.55 | $3 |
|
|
60
66
|
| `cortecs/kimi-k2.6` | 256K | | | | | | $0.81 | $4 |
|
|
61
67
|
| `cortecs/llama-3.1-405b-instruct` | 128K | | | | | | — | — |
|
|
68
|
+
| `cortecs/llama-3.3-70b-instruct` | 131K | | | | | | $0.09 | $0.28 |
|
|
62
69
|
| `cortecs/minimax-m2` | 400K | | | | | | $0.39 | $2 |
|
|
63
70
|
| `cortecs/minimax-m2.1` | 196K | | | | | | $0.34 | $1 |
|
|
64
71
|
| `cortecs/minimax-m2.5` | 197K | | | | | | $0.32 | $1 |
|
|
65
72
|
| `cortecs/minimax-m2.7` | 203K | | | | | | $0.47 | $1 |
|
|
73
|
+
| `cortecs/mistral-large-2512` | 256K | | | | | | $0.50 | $2 |
|
|
74
|
+
| `cortecs/mixtral-8x7B-instruct-v0.1` | 32K | | | | | | $0.44 | $0.68 |
|
|
75
|
+
| `cortecs/nemotron-3-super-120b-a12b` | 262K | | | | | | $0.27 | $0.80 |
|
|
66
76
|
| `cortecs/nova-pro-v1` | 300K | | | | | | $1 | $4 |
|
|
67
77
|
| `cortecs/qwen-2.5-72b-instruct` | 33K | | | | | | $0.06 | $0.23 |
|
|
78
|
+
| `cortecs/qwen3-235b-a22b-instruct-2507` | 131K | | | | | | $0.06 | $0.41 |
|
|
68
79
|
| `cortecs/qwen3-32b` | 16K | | | | | | $0.10 | $0.33 |
|
|
80
|
+
| `cortecs/qwen3-coder-30b-a3b-instruct` | 262K | | | | | | $0.05 | $0.22 |
|
|
69
81
|
| `cortecs/qwen3-coder-480b-a35b-instruct` | 262K | | | | | | $0.44 | $2 |
|
|
70
82
|
| `cortecs/qwen3-coder-next` | 256K | | | | | | $0.16 | $0.84 |
|
|
71
83
|
| `cortecs/qwen3-next-80b-a3b-thinking` | 128K | | | | | | $0.16 | $1 |
|
|
84
|
+
| `cortecs/qwen3.5-122b-a10b` | 262K | | | | | | $0.44 | $3 |
|
|
85
|
+
| `cortecs/qwen3.5-397b-a17b` | 250K | | | | | | $0.60 | $4 |
|
|
72
86
|
|
|
73
87
|
## Advanced configuration
|
|
74
88
|
|
|
@@ -98,7 +112,7 @@ const agent = new Agent({
|
|
|
98
112
|
model: ({ requestContext }) => {
|
|
99
113
|
const useAdvanced = requestContext.task === "complex";
|
|
100
114
|
return useAdvanced
|
|
101
|
-
? "cortecs/qwen3-
|
|
115
|
+
? "cortecs/qwen3.5-397b-a17b"
|
|
102
116
|
: "cortecs/claude-4-5-sonnet";
|
|
103
117
|
}
|
|
104
118
|
});
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Firmware
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 26 Firmware models through Mastra's model router. Authentication is handled automatically using the `FIRMWARE_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Firmware documentation](https://docs.frogbot.ai).
|
|
6
6
|
|
|
@@ -38,25 +38,26 @@ for await (const chunk of stream) {
|
|
|
38
38
|
| `firmware/claude-opus-4-6` | 200K | | | | | | $5 | $25 |
|
|
39
39
|
| `firmware/claude-opus-4-7` | 200K | | | | | | $5 | $25 |
|
|
40
40
|
| `firmware/claude-sonnet-4-6` | 200K | | | | | | $3 | $15 |
|
|
41
|
-
| `firmware/deepseek-
|
|
41
|
+
| `firmware/deepseek-v4-pro` | 128K | | | | | | $2 | $3 |
|
|
42
42
|
| `firmware/gemini-2.5-flash` | 1.0M | | | | | | $0.30 | $3 |
|
|
43
43
|
| `firmware/gemini-2.5-pro` | 1.0M | | | | | | $1 | $10 |
|
|
44
44
|
| `firmware/gemini-3-1-pro-preview` | 1.0M | | | | | | $2 | $12 |
|
|
45
45
|
| `firmware/gemini-3-flash-preview` | 1.0M | | | | | | $0.50 | $3 |
|
|
46
|
-
| `firmware/gemini-3-pro-preview` | 1.0M | | | | | | $2 | $12 |
|
|
47
46
|
| `firmware/gpt-4o` | 128K | | | | | | $3 | $10 |
|
|
48
47
|
| `firmware/gpt-5-3-codex` | 400K | | | | | | $2 | $14 |
|
|
49
|
-
| `firmware/gpt-5-4`
|
|
50
|
-
| `firmware/gpt-5-
|
|
51
|
-
| `firmware/gpt-5-
|
|
48
|
+
| `firmware/gpt-5-4-mini` | 400K | | | | | | $0.75 | $5 |
|
|
49
|
+
| `firmware/gpt-5-4-nano` | 400K | | | | | | $0.20 | $1 |
|
|
50
|
+
| `firmware/gpt-5-5` | 272K | | | | | | $3 | $15 |
|
|
52
51
|
| `firmware/gpt-oss-120b` | 131K | | | | | | $0.15 | $0.60 |
|
|
53
52
|
| `firmware/gpt-oss-20b` | 131K | | | | | | $0.07 | $0.20 |
|
|
54
53
|
| `firmware/grok-4-1-fast-non-reasoning` | 2.0M | | | | | | $0.20 | $0.50 |
|
|
55
54
|
| `firmware/grok-4-1-fast-reasoning` | 2.0M | | | | | | $0.20 | $0.50 |
|
|
55
|
+
| `firmware/grok-4-3` | 1.0M | | | | | | $1 | $3 |
|
|
56
56
|
| `firmware/grok-code-fast-1` | 256K | | | | | | $0.20 | $2 |
|
|
57
57
|
| `firmware/kimi-k2-6` | 256K | | | | | | $0.95 | $4 |
|
|
58
58
|
| `firmware/kimi-k2.5` | 256K | | | | | | $0.60 | $3 |
|
|
59
59
|
| `firmware/minimax-m2-5` | 192K | | | | | | $0.30 | $1 |
|
|
60
|
+
| `firmware/minimax-m2-7` | 192K | | | | | | $0.30 | $1 |
|
|
60
61
|
| `firmware/qwen-3-6-plus` | 1.0M | | | | | | $0.50 | $3 |
|
|
61
62
|
| `firmware/zai-glm-5-1` | 198K | | | | | | $1 | $4 |
|
|
62
63
|
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Neuralwatt
|
|
2
|
+
|
|
3
|
+
Access 14 Neuralwatt models through Mastra's model router. Authentication is handled automatically using the `NEURALWATT_API_KEY` environment variable.
|
|
4
|
+
|
|
5
|
+
Learn more in the [Neuralwatt documentation](https://portal.neuralwatt.com/docs).
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
NEURALWATT_API_KEY=your-api-key
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
import { Agent } from "@mastra/core/agent";
|
|
13
|
+
|
|
14
|
+
const agent = new Agent({
|
|
15
|
+
id: "my-agent",
|
|
16
|
+
name: "My Agent",
|
|
17
|
+
instructions: "You are a helpful assistant",
|
|
18
|
+
model: "neuralwatt/MiniMaxAI/MiniMax-M2.5"
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
// Generate a response
|
|
22
|
+
const response = await agent.generate("Hello!");
|
|
23
|
+
|
|
24
|
+
// Stream a response
|
|
25
|
+
const stream = await agent.stream("Tell me a story");
|
|
26
|
+
for await (const chunk of stream) {
|
|
27
|
+
console.log(chunk);
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Neuralwatt documentation](https://portal.neuralwatt.com/docs) for details.
|
|
32
|
+
|
|
33
|
+
## Models
|
|
34
|
+
|
|
35
|
+
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
36
|
+
| --------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
37
|
+
| `neuralwatt/glm-5-fast` | 200K | | | | | | $1 | $4 |
|
|
38
|
+
| `neuralwatt/glm-5.1-fast` | 200K | | | | | | $1 | $4 |
|
|
39
|
+
| `neuralwatt/kimi-k2.5-fast` | 262K | | | | | | $0.52 | $3 |
|
|
40
|
+
| `neuralwatt/kimi-k2.6-fast` | 262K | | | | | | $0.69 | $3 |
|
|
41
|
+
| `neuralwatt/MiniMaxAI/MiniMax-M2.5` | 197K | | | | | | $0.35 | $1 |
|
|
42
|
+
| `neuralwatt/mistralai/Devstral-Small-2-24B-Instruct-2512` | 262K | | | | | | $0.12 | $0.35 |
|
|
43
|
+
| `neuralwatt/moonshotai/Kimi-K2.5` | 262K | | | | | | $0.52 | $3 |
|
|
44
|
+
| `neuralwatt/moonshotai/Kimi-K2.6` | 262K | | | | | | $0.69 | $3 |
|
|
45
|
+
| `neuralwatt/openai/gpt-oss-20b` | 16K | | | | | | $0.03 | $0.16 |
|
|
46
|
+
| `neuralwatt/Qwen/Qwen3.5-397B-A17B-FP8` | 262K | | | | | | $0.69 | $4 |
|
|
47
|
+
| `neuralwatt/Qwen/Qwen3.6-35B-A3B` | 131K | | | | | | $0.05 | $0.10 |
|
|
48
|
+
| `neuralwatt/qwen3.5-397b-fast` | 262K | | | | | | $0.69 | $4 |
|
|
49
|
+
| `neuralwatt/qwen3.6-35b-fast` | 131K | | | | | | $0.05 | $0.10 |
|
|
50
|
+
| `neuralwatt/zai-org/GLM-5.1-FP8` | 200K | | | | | | $1 | $4 |
|
|
51
|
+
|
|
52
|
+
## Advanced configuration
|
|
53
|
+
|
|
54
|
+
### Custom headers
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
const agent = new Agent({
|
|
58
|
+
id: "custom-agent",
|
|
59
|
+
name: "custom-agent",
|
|
60
|
+
model: {
|
|
61
|
+
url: "https://api.neuralwatt.com/v1",
|
|
62
|
+
id: "neuralwatt/MiniMaxAI/MiniMax-M2.5",
|
|
63
|
+
apiKey: process.env.NEURALWATT_API_KEY,
|
|
64
|
+
headers: {
|
|
65
|
+
"X-Custom-Header": "value"
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Dynamic model selection
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
const agent = new Agent({
|
|
75
|
+
id: "dynamic-agent",
|
|
76
|
+
name: "Dynamic Agent",
|
|
77
|
+
model: ({ requestContext }) => {
|
|
78
|
+
const useAdvanced = requestContext.task === "complex";
|
|
79
|
+
return useAdvanced
|
|
80
|
+
? "neuralwatt/zai-org/GLM-5.1-FP8"
|
|
81
|
+
: "neuralwatt/MiniMaxAI/MiniMax-M2.5";
|
|
82
|
+
}
|
|
83
|
+
});
|
|
84
|
+
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Nvidia
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 82 Nvidia models through Mastra's model router. Authentication is handled automatically using the `NVIDIA_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Nvidia documentation](https://docs.api.nvidia.com/nim/).
|
|
6
6
|
|
|
@@ -86,6 +86,7 @@ for await (const chunk of stream) {
|
|
|
86
86
|
| `nvidia/moonshotai/kimi-k2-instruct-0905` | 262K | | | | | | — | — |
|
|
87
87
|
| `nvidia/moonshotai/kimi-k2-thinking` | 262K | | | | | | — | — |
|
|
88
88
|
| `nvidia/moonshotai/kimi-k2.5` | 262K | | | | | | — | — |
|
|
89
|
+
| `nvidia/moonshotai/kimi-k2.6` | 262K | | | | | | — | — |
|
|
89
90
|
| `nvidia/nvidia/cosmos-nemotron-34b` | 131K | | | | | | — | — |
|
|
90
91
|
| `nvidia/nvidia/llama-3.1-nemotron-51b-instruct` | 128K | | | | | | — | — |
|
|
91
92
|
| `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | 128K | | | | | | — | — |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Perplexity Agent
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 18 Perplexity Agent models through Mastra's model router. Authentication is handled automatically using the `PERPLEXITY_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Perplexity Agent documentation](https://docs.perplexity.ai/docs/agent-api/models).
|
|
6
6
|
|
|
@@ -37,6 +37,7 @@ for await (const chunk of stream) {
|
|
|
37
37
|
| `perplexity-agent/anthropic/claude-haiku-4-5` | 200K | | | | | | $1 | $5 |
|
|
38
38
|
| `perplexity-agent/anthropic/claude-opus-4-5` | 200K | | | | | | $5 | $25 |
|
|
39
39
|
| `perplexity-agent/anthropic/claude-opus-4-6` | 200K | | | | | | $5 | $25 |
|
|
40
|
+
| `perplexity-agent/anthropic/claude-opus-4-7` | 1.0M | | | | | | $5 | $25 |
|
|
40
41
|
| `perplexity-agent/anthropic/claude-sonnet-4-5` | 200K | | | | | | $3 | $15 |
|
|
41
42
|
| `perplexity-agent/anthropic/claude-sonnet-4-6` | 200K | | | | | | $3 | $15 |
|
|
42
43
|
| `perplexity-agent/google/gemini-2.5-flash` | 1.0M | | | | | | $0.30 | $3 |
|
|
@@ -48,6 +49,7 @@ for await (const chunk of stream) {
|
|
|
48
49
|
| `perplexity-agent/openai/gpt-5.1` | 400K | | | | | | $1 | $10 |
|
|
49
50
|
| `perplexity-agent/openai/gpt-5.2` | 400K | | | | | | $2 | $14 |
|
|
50
51
|
| `perplexity-agent/openai/gpt-5.4` | 1.1M | | | | | | $3 | $15 |
|
|
52
|
+
| `perplexity-agent/openai/gpt-5.5` | 1.1M | | | | | | $5 | $30 |
|
|
51
53
|
| `perplexity-agent/perplexity/sonar` | 128K | | | | | | $0.25 | $3 |
|
|
52
54
|
| `perplexity-agent/xai/grok-4-1-fast-non-reasoning` | 2.0M | | | | | | $0.20 | $0.50 |
|
|
53
55
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Synthetic
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 33 Synthetic models through Mastra's model router. Authentication is handled automatically using the `SYNTHETIC_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Synthetic documentation](https://synthetic.new/pricing).
|
|
6
6
|
|
|
@@ -53,6 +53,7 @@ for await (const chunk of stream) {
|
|
|
53
53
|
| `synthetic/hf:moonshotai/Kimi-K2-Instruct-0905` | 262K | | | | | | $1 | $1 |
|
|
54
54
|
| `synthetic/hf:moonshotai/Kimi-K2-Thinking` | 262K | | | | | | $0.55 | $2 |
|
|
55
55
|
| `synthetic/hf:moonshotai/Kimi-K2.5` | 262K | | | | | | $0.55 | $2 |
|
|
56
|
+
| `synthetic/hf:moonshotai/Kimi-K2.6` | 262K | | | | | | $0.95 | $4 |
|
|
56
57
|
| `synthetic/hf:nvidia/Kimi-K2.5-NVFP4` | 262K | | | | | | $0.55 | $2 |
|
|
57
58
|
| `synthetic/hf:nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4` | 262K | | | | | | $0.30 | $1 |
|
|
58
59
|
| `synthetic/hf:openai/gpt-oss-120b` | 128K | | | | | | $0.10 | $0.10 |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Zhipu AI Coding Plan
|
|
2
2
|
|
|
3
|
-
Access
|
|
3
|
+
Access 5 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
|
|
4
4
|
|
|
5
5
|
Learn more in the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview).
|
|
6
6
|
|
|
@@ -32,12 +32,13 @@ for await (const chunk of stream) {
|
|
|
32
32
|
|
|
33
33
|
## Models
|
|
34
34
|
|
|
35
|
-
| Model
|
|
36
|
-
|
|
|
37
|
-
| `zhipuai-coding-plan/glm-4.5-air`
|
|
38
|
-
| `zhipuai-coding-plan/glm-4.7`
|
|
39
|
-
| `zhipuai-coding-plan/glm-5-turbo`
|
|
40
|
-
| `zhipuai-coding-plan/glm-5.1`
|
|
35
|
+
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
36
|
+
| ---------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
37
|
+
| `zhipuai-coding-plan/glm-4.5-air` | 131K | | | | | | — | — |
|
|
38
|
+
| `zhipuai-coding-plan/glm-4.7` | 205K | | | | | | — | — |
|
|
39
|
+
| `zhipuai-coding-plan/glm-5-turbo` | 200K | | | | | | — | — |
|
|
40
|
+
| `zhipuai-coding-plan/glm-5.1` | 200K | | | | | | — | — |
|
|
41
|
+
| `zhipuai-coding-plan/glm-5v-turbo` | 200K | | | | | | — | — |
|
|
41
42
|
|
|
42
43
|
## Advanced configuration
|
|
43
44
|
|
|
@@ -67,7 +68,7 @@ const agent = new Agent({
|
|
|
67
68
|
model: ({ requestContext }) => {
|
|
68
69
|
const useAdvanced = requestContext.task === "complex";
|
|
69
70
|
return useAdvanced
|
|
70
|
-
? "zhipuai-coding-plan/glm-
|
|
71
|
+
? "zhipuai-coding-plan/glm-5v-turbo"
|
|
71
72
|
: "zhipuai-coding-plan/glm-4.5-air";
|
|
72
73
|
}
|
|
73
74
|
});
|
|
@@ -63,6 +63,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
|
|
|
63
63
|
- [Morph](https://mastra.ai/models/providers/morph)
|
|
64
64
|
- [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
|
|
65
65
|
- [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
|
|
66
|
+
- [Neuralwatt](https://mastra.ai/models/providers/neuralwatt)
|
|
66
67
|
- [Nova](https://mastra.ai/models/providers/nova)
|
|
67
68
|
- [NovitaAI](https://mastra.ai/models/providers/novita-ai)
|
|
68
69
|
- [Nvidia](https://mastra.ai/models/providers/nvidia)
|
|
@@ -28,7 +28,13 @@ export const mastra = new Mastra({
|
|
|
28
28
|
|
|
29
29
|
**name** (`string`): Custom name for the auth provider instance. (Default: `"workos"`)
|
|
30
30
|
|
|
31
|
-
**
|
|
31
|
+
**redirectUri** (`string`): OAuth redirect URI used by WorkOS AuthKit. Set this when you use the built-in WorkOS sign-in flow. (Default: `process.env.WORKOS_REDIRECT_URI`)
|
|
32
|
+
|
|
33
|
+
**fetchMemberships** (`boolean`): Loads organization memberships during authentication. Set this to \`true\` when you use \`MastraFGAWorkos\` so FGA checks can resolve the correct organization membership ID. (Default: `false`)
|
|
34
|
+
|
|
35
|
+
**trustJwtClaims** (`boolean`): Trusts verified bearer-token claims enough to construct a \`WorkOSUser\` even when \`workos.userManagement.getUser()\` does not apply. Use this for service-account or machine-to-machine tokens backed by a WorkOS custom JWT template. (Default: `false`)
|
|
36
|
+
|
|
37
|
+
**jwtClaims** (`{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }`): Maps verified bearer JWT claims into the authenticated \`WorkOSUser\`. Useful for custom JWT templates that include \`organizationMembershipId\` or other FGA-specific claims.
|
|
32
38
|
|
|
33
39
|
## Environment variables
|
|
34
40
|
|
|
@@ -38,24 +44,63 @@ The following environment variables are automatically used when constructor opti
|
|
|
38
44
|
|
|
39
45
|
**WORKOS\_CLIENT\_ID** (`string`): Your WorkOS Client ID. Can be found in your WorkOS Dashboard under Applications.
|
|
40
46
|
|
|
47
|
+
**WORKOS\_REDIRECT\_URI** (`string`): OAuth redirect URI used by WorkOS AuthKit when you use the built-in session-based flow.
|
|
48
|
+
|
|
41
49
|
## Default authorization behavior
|
|
42
50
|
|
|
43
|
-
By default, `MastraAuthWorkos`
|
|
51
|
+
By default, `MastraAuthWorkos` authorizes any authenticated WorkOS user whose resolved user object includes both `id` and `workosId`.
|
|
44
52
|
|
|
45
53
|
1. **Token Verification**: The access token is verified with WorkOS to ensure it's valid and not expired
|
|
46
54
|
2. **User Retrieval**: User information is extracted from the verified token
|
|
47
|
-
3. **
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
55
|
+
3. **Authorization Decision**: Access is granted if the resolved user contains the required identifiers
|
|
56
|
+
|
|
57
|
+
This means that by default, `MastraAuthWorkos` acts as an authentication provider rather than a role gate.
|
|
58
|
+
|
|
59
|
+
## FGA membership loading
|
|
60
|
+
|
|
61
|
+
Set `fetchMemberships: true` when you use `MastraFGAWorkos`. This loads the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
|
|
62
|
+
|
|
63
|
+
When `fetchMemberships` is `false`, Mastra skips the extra WorkOS `listOrganizationMemberships()` call on each authenticated request.
|
|
64
|
+
|
|
65
|
+
## Service tokens and JWT claims
|
|
66
|
+
|
|
67
|
+
If your WorkOS JWT template includes custom claims, you can map them directly into the authenticated `WorkOSUser`.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
import { MastraAuthWorkos } from '@mastra/auth-workos'
|
|
71
|
+
|
|
72
|
+
const auth = new MastraAuthWorkos({
|
|
73
|
+
apiKey: process.env.WORKOS_API_KEY,
|
|
74
|
+
clientId: process.env.WORKOS_CLIENT_ID,
|
|
75
|
+
redirectUri: process.env.WORKOS_REDIRECT_URI,
|
|
76
|
+
trustJwtClaims: true,
|
|
77
|
+
jwtClaims: {
|
|
78
|
+
organizationId: 'org_id',
|
|
79
|
+
organizationMembershipId: 'urn:mastra:organization_membership_id',
|
|
80
|
+
},
|
|
81
|
+
})
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` is not the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
|
|
51
85
|
|
|
52
|
-
|
|
86
|
+
## Custom authorization
|
|
53
87
|
|
|
54
|
-
|
|
88
|
+
If you need stricter authorization, subclass `MastraAuthWorkos` and override `authorizeUser()`:
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
import { MastraAuthWorkos } from '@mastra/auth-workos'
|
|
92
|
+
import type { HonoRequest } from 'hono'
|
|
93
|
+
|
|
94
|
+
class AdminOnlyWorkosAuth extends MastraAuthWorkos {
|
|
95
|
+
async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
|
|
96
|
+
return user?.metadata?.role === 'admin'
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
55
100
|
|
|
56
101
|
## WorkOS user type
|
|
57
102
|
|
|
58
|
-
The `
|
|
103
|
+
The `WorkOSUser` type available inside `authorizeUser()` and other WorkOS auth hooks includes Mastra's normalized user fields plus WorkOS-specific metadata. WorkOS also allows administrators to set up custom JWT templates, so the exact structure may vary based on your configuration. The following example shows what a WorkOS-backed user object might look like:
|
|
59
104
|
|
|
60
105
|
```javascript
|
|
61
106
|
{
|
package/.docs/reference/index.md
CHANGED
|
@@ -160,6 +160,7 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
160
160
|
- [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
|
|
161
161
|
- [Spans](https://mastra.ai/reference/observability/tracing/spans)
|
|
162
162
|
- [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
|
|
163
|
+
- [CostGuardProcessor](https://mastra.ai/reference/processors/cost-guard-processor)
|
|
163
164
|
- [LanguageDetector](https://mastra.ai/reference/processors/language-detector)
|
|
164
165
|
- [MessageHistory](https://mastra.ai/reference/processors/message-history-processor)
|
|
165
166
|
- [ModerationProcessor](https://mastra.ai/reference/processors/moderation-processor)
|
|
@@ -167,6 +168,7 @@ The Reference section provides documentation of Mastra's API, including paramete
|
|
|
167
168
|
- [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)
|
|
168
169
|
- [Processor Interface](https://mastra.ai/reference/processors/processor-interface)
|
|
169
170
|
- [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
|
|
171
|
+
- [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
|
|
170
172
|
- [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
|
|
171
173
|
- [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
|
|
172
174
|
- [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# CostGuardProcessor
|
|
2
|
+
|
|
3
|
+
The `CostGuardProcessor` enforces monetary cost limits across the agentic loop, blocking or warning when a configurable cost threshold is exceeded.
|
|
4
|
+
|
|
5
|
+
It uses `processInputStep` to check the cost limit before each LLM call. Cost data is queried from the observability storage APIs (`getMetricAggregate`) for all scopes. For `resource` and `thread` scopes, it aggregates cost across runs within a configurable time window (defaults to 7 days). For `run` scope, it queries cost for the current trace.
|
|
6
|
+
|
|
7
|
+
For token-based limits, use `TokenLimiterProcessor` instead.
|
|
8
|
+
|
|
9
|
+
Supports three scoping modes:
|
|
10
|
+
|
|
11
|
+
- **Run scope**: Tracks cost within a single agent run via trace ID
|
|
12
|
+
- **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
|
|
13
|
+
- **Thread scope**: Tracks cumulative cost per `threadId` across runs
|
|
14
|
+
|
|
15
|
+
> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as a best-effort threshold, not a hard ceiling.
|
|
16
|
+
|
|
17
|
+
## Usage example
|
|
18
|
+
|
|
19
|
+
Track cumulative cost per resource (default scope):
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import { CostGuardProcessor } from '@mastra/core/processors'
|
|
23
|
+
|
|
24
|
+
const costGuard = new CostGuardProcessor({
|
|
25
|
+
maxCost: 1.0,
|
|
26
|
+
})
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Track cumulative cost per thread with a 24-hour window:
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import { CostGuardProcessor } from '@mastra/core/processors'
|
|
33
|
+
|
|
34
|
+
const costGuard = new CostGuardProcessor({
|
|
35
|
+
maxCost: 5.0,
|
|
36
|
+
scope: 'thread',
|
|
37
|
+
window: '24h',
|
|
38
|
+
})
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Attach to an agent with an `onViolation` callback:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import { Agent } from '@mastra/core/agent'
|
|
45
|
+
import { CostGuardProcessor } from '@mastra/core/processors'
|
|
46
|
+
|
|
47
|
+
const costGuard = new CostGuardProcessor({
|
|
48
|
+
maxCost: 5.0,
|
|
49
|
+
scope: 'resource',
|
|
50
|
+
window: '30d',
|
|
51
|
+
})
|
|
52
|
+
|
|
53
|
+
costGuard.onViolation = ({ detail }) => {
|
|
54
|
+
console.log(`Cost exceeded for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`)
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const agent = new Agent({
|
|
58
|
+
name: 'my-agent',
|
|
59
|
+
model: 'openai/gpt-5-nano',
|
|
60
|
+
processors: {
|
|
61
|
+
input: [costGuard],
|
|
62
|
+
},
|
|
63
|
+
})
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Constructor parameters
|
|
67
|
+
|
|
68
|
+
**maxCost** (`number`): Maximum estimated cost allowed (e.g. 0.50 for $0.50 USD). Must be a positive number. Uses cost data from observability metrics. This is an approximate limit due to metric persistence delays.
|
|
69
|
+
|
|
70
|
+
**scope** (`'run' | 'resource' | 'thread'`): Scope for cost tracking. 'run' tracks cost within the current agent run via trace ID. 'resource' tracks cumulative cost per resourceId across runs (default). 'thread' tracks cumulative cost per threadId across runs. All scopes require observability storage with getMetricAggregate support. (Default: `'resource'`)
|
|
71
|
+
|
|
72
|
+
**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Time window for cost aggregation when using 'resource' or 'thread' scope. Only applicable to non-run scopes. (Default: `'7d'`)
|
|
73
|
+
|
|
74
|
+
**strategy** (`'block' | 'warn'`): Strategy when the cost limit is exceeded. 'block' aborts with a TripWire error. 'warn' logs a warning but allows the step to proceed. (Default: `'block'`)
|
|
75
|
+
|
|
76
|
+
**message** (`string`): Custom message template for the abort reason. Supports {usage} and {limit} placeholders. (Default: `'Cost guard: cost limit exceeded ({usage}/{limit})'`)
|
|
77
|
+
|
|
78
|
+
## Instance properties
|
|
79
|
+
|
|
80
|
+
**id** (`'cost-guard'`): Processor identifier.
|
|
81
|
+
|
|
82
|
+
**name** (`'Cost Guard'`): Processor display name.
|
|
83
|
+
|
|
84
|
+
**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Callback invoked when a cost violation is detected, regardless of strategy. Part of the generalized Processor interface. Use for side effects like alerting, logging to external systems, or emailing users. Errors thrown by this callback are silently caught.
|
|
85
|
+
|
|
86
|
+
**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Checks cumulative estimated cost against maxCost before each LLM call. Queries observability storage for cost data: run scope filters by trace ID, resource/thread scopes filter by their respective IDs with a time window. Calls abort() when the limit is exceeded (block strategy) or logs a warning (warn strategy). Cost checks are approximate due to metric persistence delays.
|
|
87
|
+
|
|
88
|
+
## Error behavior
|
|
89
|
+
|
|
90
|
+
When the `block` strategy is active (default), `CostGuardProcessor` calls `abort()` with `retry: false` when the cost limit is exceeded. The TripWire metadata includes:
|
|
91
|
+
|
|
92
|
+
- `processorId`: `'cost-guard'`
|
|
93
|
+
- `usage`: Current cumulative usage (`estimatedCost`, `costUnit`)
|
|
94
|
+
- `maxCost`: The configured cost limit
|
|
95
|
+
- `scope`: The active scope (`'run'`, `'resource'`, or `'thread'`)
|
|
96
|
+
- `scopeKey`: The scope identifier for resource/thread scopes (if applicable)
|
|
97
|
+
|
|
98
|
+
## Scoping behavior
|
|
99
|
+
|
|
100
|
+
| Scope | Tracks across runs | Filter | Requires context |
|
|
101
|
+
| ---------- | ------------------ | --------------------------- | -------------------------------- |
|
|
102
|
+
| `run` | No | `traceId` from current span | Tracing context (automatic) |
|
|
103
|
+
| `resource` | Yes | `resourceId` + time window | `resourceId` in `RequestContext` |
|
|
104
|
+
| `thread` | Yes | `threadId` + time window | `threadId` in `RequestContext` |
|
|
105
|
+
|
|
106
|
+
All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance does not have observability storage configured, an error is thrown at registration time.
|
|
107
|
+
|
|
108
|
+
For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
|
|
109
|
+
|
|
110
|
+
For `resource` and `thread` scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, cost is treated as zero.
|
|
111
|
+
|
|
112
|
+
> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. There is a short delay between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.
|
|
@@ -80,6 +80,9 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
|
|
|
80
80
|
/** When true, processOutputStream also receives `data-*` chunks. Default: false. */
|
|
81
81
|
processDataParts?: boolean
|
|
82
82
|
|
|
83
|
+
/** Callback invoked when this processor detects a violation, regardless of strategy. */
|
|
84
|
+
onViolation?: (violation: ProcessorViolation) => void | Promise<void>
|
|
85
|
+
|
|
83
86
|
processInput?(
|
|
84
87
|
args: ProcessInputArgs<TTripwireMetadata>,
|
|
85
88
|
): Promise<ProcessInputResult> | ProcessInputResult
|
|
@@ -120,6 +123,8 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
|
|
|
120
123
|
|
|
121
124
|
**processDataParts** (`boolean`): When true, the processOutputStream method also receives \`data-\*\` chunks emitted by tools via writer.custom(). Defaults to false.
|
|
122
125
|
|
|
126
|
+
**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Optional callback invoked when the processor detects a policy violation, regardless of strategy (block or warn). Use for side effects like alerting, logging to external systems, or emailing users. Errors thrown by this callback are silently caught to prevent interfering with processor logic. The violation object contains processorId, message, and a processor-specific detail field.
|
|
127
|
+
|
|
123
128
|
## Message arguments
|
|
124
129
|
|
|
125
130
|
Most processor methods receive both `messages` and `messageList`. They point to the same underlying conversation but expose it differently.
|