@mastra/server 1.57.0 → 1.58.0-alpha.1

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.57.0"
+  version: "1.58.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -2,7 +2,7 @@
 
 # A2A (Agent-to-Agent)
 
-Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+Mastra supports version 0.3.0 of the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
 
 A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 
@@ -176,6 +176,38 @@ const remoteWeatherAgent = new A2AAgent({
 
 You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
 
+## Human-in-the-loop
+
+A2A models human-in-the-loop (HITL) work with the `input-required` task state. When a task pauses for input, the client provides the missing input by sending a follow-up message with the same `taskId`, and the server continues the task.
+
+Mastra maps its agent suspension model to this state in both directions:
+
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/api/.well-known/booking-agent/agent-card.json',
+})
+
+const result = await agent.generate('Book a flight to Paris', { runId: 'run-1' })
+
+if (result.finishReason === 'suspended') {
+  // Inspect result.suspendPayload, collect input from a human,
+  // then resume the remote task.
+  const resumed = await agent.resumeGenerate({ approved: true }, { runId: 'run-1' })
+  console.log(resumed.text)
+}
+```
+
+Follow-up messages for an `input-required` task can carry the resume data as a structured data part, or as JSON or plain text in a text part.
+
+When a resumed run requires additional input, the task returns to `input-required` and the flow repeats. Resuming a suspended run requires storage configured on the Mastra server so the suspended run state can be restored across requests.
+
+> **Note:** A2A task records live in an in-memory store, so a paused task can only be resumed by the same server process that suspended it. A server restart or a horizontally scaled deployment without sticky routing loses the task record, and a follow-up message fails with a task-not-found error.
+
 ## Push notifications
 
 Mastra supports A2A push notifications for remote agents that advertise `capabilities.pushNotifications`. Use push notifications when a client can't keep a stream open, or when a long-running task should update a callback URL after the original request ends.
@@ -192,7 +224,9 @@ await a2a.setTaskPushNotificationConfig({
 })
 ```
 
-Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, or `input-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, `rejected`, `input-required`, or `auth-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+
+Push notification configurations are stored in memory and must be registered again after a server restart.
 
 ## Sign and verify agent cards