@mastra/server 1.58.0-alpha.1 → 1.58.0-alpha.3

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-server
 description: Documentation for @mastra/server. Use when working with @mastra/server APIs, configuration, or implementation.
 metadata:
   package: "@mastra/server"
-  version: "1.58.0-alpha.1"
+  version: "1.58.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.58.0-alpha.1",
+  "version": "1.58.0-alpha.3",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-a2a.md

@@ -57,6 +57,18 @@ A2A represents work as messages and tasks. Messages carry text, file, or structu
 
 Tasks are stateful units of work with IDs and lifecycle states. Clients can follow long-running work and send follow-up turns. They can also cancel work or resubscribe after a disconnect.
 
+## Protocol versions
+
+Mastra supports A2A Protocol v0.3 and v1.0 on the same agent card and execution URLs. The `A2A-Version` request header selects the wire protocol:
+
+- Missing, empty, or `0.3`: Uses the existing v0.3 API.
+- `1.0`: Uses the v1.0 API.
+- Any other value: Returns a `VersionNotSupported` protocol error.
+
+Existing `A2AAgent` and `MastraClient.getA2A()` integrations continue to use v0.3. Use `MastraClient.getA2AV1()` for v1.0 requests. The v1 client sends `A2A-Version: 1.0` automatically and adds the `tasks/list` operation.
+
+Import v1.0 protocol types and codecs from `@mastra/core/a2a/v1`. The existing `@mastra/core/a2a/client` export remains on v0.3.
+
 ## Get started
 
 A2A has two common paths in Mastra:
@@ -155,6 +167,33 @@ for await (const event of updates) {
 }
 ```
 
+### Use the v1.0 client
+
+Use `getA2AV1()` to opt into the A2A v1.0 wire protocol. The protocol package provides codecs for creating v1 request values from JSON-shaped input:
+
+```typescript
+import { ListTasksRequest } from '@mastra/core/a2a/v1'
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'https://agent.example.com',
+})
+
+const a2a = client.getA2AV1('weather-agent')
+const response = await a2a.listTasks(
+  ListTasksRequest.fromJSON({
+    contextId: 'customer-support',
+    pageSize: 20,
+  }),
+)
+
+for (const task of response.tasks) {
+  console.log(task.id, task.status)
+}
+```
+
+The v1.0 client supports `getAgentCard()`, `sendMessage()`, `sendMessageStream()`, `getTask()`, `listTasks()`, `cancelTask()`, and `resubscribeTask()`.
+
 ## Configure subagent calls
 
 `A2AAgent` accepts request options for authenticated or constrained environments:

package/dist/docs/references/reference-server-routes.md

@@ -171,17 +171,31 @@ The route returns:
 
 ## Workflows
 
-| Method | Path                                      | Description                     |
-| ------ | ----------------------------------------- | ------------------------------- |
-| `GET`  | `/api/workflows`                          | List all workflows              |
-| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID              |
-| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run       |
-| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result |
-| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution       |
-| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow       |
-| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously           |
-| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
-| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
+| Method | Path                                      | Description                                           |
+| ------ | ----------------------------------------- | ----------------------------------------------------- |
+| `GET`  | `/api/workflows`                          | List all workflows                                    |
+| `GET`  | `/api/workflows/run-counts`               | Get per-workflow counts of running and suspended runs |
+| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID                                    |
+| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run                             |
+| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result                       |
+| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution                             |
+| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow                             |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously                                 |
+| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs                                    |
+| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                                      |
+
+### Run counts response
+
+The `/api/workflows/run-counts` endpoint returns counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs for every registered workflow. The record is keyed by the workflow's registry key from the Mastra config, and the server may cache the response for a few seconds:
+
+```typescript
+{
+  [workflowRegistryKey: string]: {
+    running: number;
+    suspended: number;
+  };
+}
+```
 
 ### Stored workflows