@mastra/mcp-docs-server 1.2.1-alpha.2 → 1.2.1-alpha.5

package/.docs/docs/agent-builder/overview.md

@@ -2,6 +2,8 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
+[YouTube video player](https://www.youtube-nocookie.com/embed/AbdgIu4Z07I)
+
 The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
 
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.

package/.docs/docs/agents/background-tasks.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.29.0`
 
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/agents/agent) option the agent is re-invoked automatically so the result is processed in the same call.
 
 ## When to use background tasks
 
@@ -119,7 +119,7 @@ If the agent has `backgroundTasks.disabled: true`, every tool call runs synchron
 
 ## Background tasks related stream chunks
 
-When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/streaming/background-task-streaming) SSE stream. Each stream covers a different set of chunk types:
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
 
 | Chunk type                  | When it fires                                                                          | Emitted by     |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
@@ -133,20 +133,20 @@ When a tool call dispatches as a background task, two streams may surface lifecy
 | `background-task-suspended` | The tool called `suspend()` from inside its execute.                                   | Manager stream |
 | `background-task-resumed`   | A suspended task was resumed via `manager.resume(taskId, resumeData)`.                 | Manager stream |
 
-`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the seven manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`, `background-task-resumed`) into the same `fullStream`.
+`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.stream()` with `untilIdle: true` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the seven manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`, `background-task-resumed`) into the same `fullStream`.
 
 `backgroundTaskManager.stream()` only emits the seven manager chunks.
 
 The full payload shapes are documented in the [background task chunks reference](https://mastra.ai/reference/streaming/ChunkType).
 
-## Keep the agent stream open with `streamUntilIdle()`
+## Keep the agent stream open with `untilIdle`
 
-`agent.stream()` returns once the LLM emits a final response even if a background task is still running. Use `agent.streamUntilIdle()` when you want the stream to stay open until every dispatched background task has completed and the LLM has had a chance to respond to the result:
+`agent.stream()` returns once the LLM emits a final response even if a background task is still running. Pass `untilIdle: true` when you want the stream to stay open until every dispatched background task has completed and the LLM has had a chance to respond to the result:
 
 ```typescript
-const stream = await agent.streamUntilIdle('Research solana for me', {
+const stream = await agent.stream('Research solana for me', {
   memory: { thread: 't1', resource: 'u1' },
-  maxIdleMs: 5 * 60_000,
+  untilIdle: true,
 })
 
 for await (const chunk of stream.fullStream) {
@@ -155,15 +155,22 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-When a background task completes, the result is injected into the agent memory, `streamUntilIdle()` re-enters the agentic loop so the LLM can react to it. The stream closes when no tasks are running and no completions are queued.
+When a background task completes, the result is injected into the agent memory, `stream()` re-enters the agentic loop so the LLM can react to it. The stream closes when no tasks are running and no completions are queued.
 
-`maxIdleMs` caps how long the stream waits between turns. The timer only runs while the wrapper is between turns, so a slow first token won't close the stream. The default is 5 minutes.
+Customize the idle timeout by passing an object instead of `true`. The timer only runs while the wrapper is between turns, so a slow first token won't close the stream. The default is 5 minutes:
 
-> **Note:** Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full API.
+```typescript
+const stream = await agent.stream('Research solana for me', {
+  memory: { thread: 't1', resource: 'u1' },
+  untilIdle: { maxIdleMs: 30_000 },
+})
+```
+
+> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/agents/agent) for the full API.
 
 ### Aggregate properties
 
-`streamUntilIdle()` returns a `MastraModelOutput` that looks like the one from `stream()`, but only `fullStream` spans the initial turn **and** any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
+`stream()` with `untilIdle` returns a `MastraModelOutput` that looks like the one from a regular `stream()` call, but only `fullStream` spans the initial turn **and** any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
 
 ## Subagents in the background
 
@@ -185,8 +192,9 @@ const supervisor = new Agent({
   },
 })
 
-const stream = await supervisor.streamUntilIdle('Research AI in education and write an article', {
+const stream = await supervisor.stream('Research AI in education and write an article', {
   memory: { thread: 't1', resource: 'u1' },
+  untilIdle: true,
 })
 ```
 
@@ -263,7 +271,7 @@ await mastra.backgroundTaskManager?.resume(taskId, {
 
 ### What happens to the agent loop
 
-When a task suspends mid-`streamUntilIdle()`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStreamUntilIdle(resumeData, { runId, toolCallId, memory })`: the resumed bg task runs to completion, its result lands in the message list, and the agent runs a follow-up turn — all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })`: the resumed bg task runs to completion, its result lands in the message list, and the agent runs a follow-up turn — all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
 
 ### Re-registering the executor on resume
 
@@ -296,10 +304,77 @@ export const mastra = new Mastra({
 })
 ```
 
+## Streaming
+
+### Subscribe to all task events
+
+Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
+
+```typescript
+const bgManager = mastra.backgroundTaskManager
+if (!bgManager) throw new Error('Background tasks are not enabled')
+
+const controller = new AbortController()
+const stream = bgManager.stream({ abortSignal: controller.signal })
+
+for await (const chunk of stream) {
+  switch (chunk.type) {
+    case 'background-task-running':
+      console.log('started', chunk.payload.taskId, chunk.payload.toolName)
+      break
+    case 'background-task-completed':
+      console.log('done', chunk.payload.taskId, chunk.payload.result)
+      break
+    case 'background-task-failed':
+      console.error('failed', chunk.payload.taskId, chunk.payload.error)
+      break
+  }
+}
+```
+
+The stream stays open until the caller's `AbortSignal` fires. Always pass an `abortSignal` so you can disconnect cleanly.
+
+### Filter the stream
+
+Pass any combination of filter options to narrow the events you receive. Filters apply to both the initial snapshot and the live event subscription.
+
+```typescript
+const stream = bgManager.stream({
+  agentId: 'researcher',
+  threadId: 't1',
+  resourceId: 'u1',
+  abortSignal: controller.signal,
+})
+```
+
+| Filter        | Description                                         |
+| ------------- | --------------------------------------------------- |
+| `agentId`     | Only events from tasks dispatched by this agent     |
+| `runId`       | Only events from this specific agent run            |
+| `threadId`    | Only events from tasks scoped to this memory thread |
+| `resourceId`  | Only events from tasks scoped to this resource      |
+| `taskId`      | Only events for a single task                       |
+| `abortSignal` | Closes the stream when the signal aborts            |
+
+### Look up task state directly
+
+For one-off lookups instead of a live stream, use `getTask` and `listTasks`:
+
+```typescript
+const task = await mastra.backgroundTaskManager?.getTask(taskId)
+const { tasks, total } = await mastra.backgroundTaskManager?.listTasks({
+  status: 'running',
+  agentId: 'researcher',
+})
+```
+
+These read from storage rather than the pubsub stream, so they're suitable for paginated lists and detail views.
+
 ## Related
 
-- [`Agent.streamUntilIdle()` reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
+- [`Agent.stream()` reference](https://mastra.ai/reference/agents/agent)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
+- [Durable agents](https://mastra.ai/docs/agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
 - [Storage](https://mastra.ai/docs/memory/storage)

package/.docs/docs/agents/durable-agents.md

@@ -0,0 +1,231 @@
+# Durable agents
+
+**Added in:** `@mastra/core@1.45.0`
+
+> **Warning:** Durable agents are currently in **beta**. APIs may change in future releases.
+
+A durable agent wraps a regular [`Agent`](https://mastra.ai/docs/agents/overview) so the agentic loop runs inside a workflow. Events flow through [PubSub](https://mastra.ai/docs/server/pubsub), which means a client can disconnect and reconnect without missing chunks. The run state is persisted, so it survives process restarts.
+
+## When to use durable agents
+
+Use a durable agent when any of the following apply:
+
+- The client may drop and reconnect mid-stream (mobile, spotty networks, long-running calls).
+- The agentic loop may outlive a single HTTP request (background research, multi-step tool use).
+- You need an observe/reconnect API where a second client picks up a stream that a first client started.
+- You want [Inngest-powered execution](https://mastra.ai/guides/deployment/inngest) with step memoization, retries, and monitoring.
+
+For short-lived, request-scoped calls where the client stays connected, a regular `Agent` with `stream()` or `generate()` is simpler.
+
+## Quickstart
+
+Wrap an existing agent with `createDurableAgent()` from `@mastra/core/agent/durable`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createDurableAgent } from '@mastra/core/agent/durable'
+
+const agent = new Agent({
+  id: 'researcher',
+  name: 'Researcher',
+  instructions: 'You research topics thoroughly.',
+  model: 'openai/gpt-5.5',
+})
+
+export const durableResearcher = createDurableAgent({ agent })
+```
+
+Register the durable agent with Mastra and call `stream()`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { durableResearcher } from './agents/researcher'
+
+const mastra = new Mastra({
+  agents: { durableResearcher },
+})
+
+const { output, runId, cleanup } = await durableResearcher.stream(
+  'Research quantum computing advances in 2025',
+)
+
+for await (const chunk of output.fullStream) {
+  // Process each chunk as it arrives
+}
+
+// Release PubSub subscriptions and clear the run from the registry.
+// If you skip this, an automatic cleanup timer fires after the stream ends.
+cleanup()
+```
+
+The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client.
+
+> **Note:** Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
+
+## How it works
+
+A durable agent adds three layers on top of a regular agent:
+
+1. **Workflow execution**: `stream()` serializes the messages and options into a workflow input, then triggers the agentic loop inside a durable workflow. The workflow runs the same loop as `Agent.stream()` but each step can be memoized and replayed.
+
+2. **PubSub streaming**: As the loop runs, chunks are published to a PubSub topic keyed by the run ID. The caller subscribes to this topic and pipes chunks into a `ReadableStream`. If the caller disconnects and reconnects, missed chunks are replayed from the cache.
+
+3. **Cache layer**: An optional cache (in-memory by default, Redis or another backend in production) stores published events so that a late subscriber can catch up.
+
+## Execution variants
+
+Mastra provides three factory functions that produce durable agents. They differ in how the workflow is executed:
+
+| Factory                | Package           | Best for                                                                                           |
+| ---------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
+| `createDurableAgent()` | `@mastra/core`    | Local development and single-process servers. You get a stream you can await directly.             |
+| `createEventedAgent()` | `@mastra/core`    | Background execution. The workflow starts without blocking, and you consume chunks through PubSub. |
+| `createInngestAgent()` | `@mastra/inngest` | Production deployments. Inngest adds step memoization, retries, and a monitoring dashboard.        |
+
+All three return an object you register with `Mastra` the same way as a regular agent. `createDurableAgent()` and `createEventedAgent()` return class instances that extend `Agent`. `createInngestAgent()` returns a Proxy-backed object that forwards `Agent` methods to the underlying agent.
+
+### In-process with `createDurableAgent()`
+
+Wrap your agent and call `stream()`. You get a `DurableAgentStreamResult` back in the same process. No external infrastructure is required, so this is the fastest way to get started:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createDurableAgent } from '@mastra/core/agent/durable'
+
+const agent = new Agent({
+  id: 'helper',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.5',
+})
+
+export const durableHelper = createDurableAgent({ agent })
+```
+
+### Fire-and-forget with `createEventedAgent()`
+
+The workflow starts in the background without blocking the caller. You still receive chunks through PubSub, so `stream()` returns a result you can consume. The HTTP handler that triggered the run does not need to wait for the workflow to finish:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createEventedAgent } from '@mastra/core/agent/durable'
+
+const agent = new Agent({
+  id: 'writer',
+  instructions: 'You write articles.',
+  model: 'openai/gpt-5.5',
+})
+
+export const eventedWriter = createEventedAgent({ agent })
+```
+
+### Inngest-powered with `createInngestAgent()`
+
+Run the workflow on the [Inngest](https://www.inngest.com/docs) platform. Each tool call becomes a memoized step that Inngest can retry independently, and you get a dashboard for monitoring runs:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createInngestAgent } from '@mastra/inngest'
+import { Inngest } from 'inngest'
+
+const inngest = new Inngest({ id: 'my-app' })
+
+const agent = new Agent({
+  id: 'analyst',
+  instructions: 'You analyze data.',
+  model: 'openai/gpt-5.5',
+})
+
+export const inngestAnalyst = createInngestAgent({ agent, inngest })
+```
+
+> **Note:** Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
+
+## Resumable streams
+
+Durable agents support resumable streams through PubSub and an event cache. When a client disconnects mid-stream, the cache continues storing events. The same client can reconnect by calling `observe()` with the `runId`:
+
+```typescript
+const { output, cleanup } = await durableResearcher.observe(runId)
+
+for await (const chunk of output.fullStream) {
+  // Chunks from the run, including any missed while disconnected
+}
+
+cleanup()
+```
+
+`createDurableAgent()` and `createEventedAgent()` use an in-memory cache by default, which means resumable streams work within a single process. For production, provide a persistent cache backend (e.g., Redis) so cached events survive process restarts:
+
+```typescript
+import { createDurableAgent } from '@mastra/core/agent/durable'
+import { RedisServerCache } from '@mastra/redis'
+
+const cache = new RedisServerCache({ url: 'redis://localhost:6379' })
+
+export const durableAgent = createDurableAgent({
+  agent,
+  cache,
+})
+```
+
+`createInngestAgent()` does not enable caching by default. Pass a `cache` option or register the agent with a `Mastra` instance that has a `serverCache` configured to enable resumable streams.
+
+## Streaming with background tasks
+
+Durable agents support the same [`untilIdle`](https://mastra.ai/reference/agents/durable-agent) option as regular agents. When `untilIdle` is set, `stream()` keeps the connection open across background-task continuations until the agent is idle:
+
+```typescript
+const { output, cleanup } = await durableAgent.stream('Research and summarize the topic', {
+  untilIdle: true,
+  memory: { thread: 'thread-1', resource: 'user-1' },
+})
+
+for await (const chunk of output.fullStream) {
+  // Chunks from the initial turn AND any follow-up turns triggered by
+  // background task completions
+}
+
+cleanup()
+```
+
+Pass `{ maxIdleMs }` to customize the idle timeout (defaults to 5 minutes):
+
+```typescript
+await durableAgent.stream('Research topic', {
+  untilIdle: { maxIdleMs: 30_000 },
+  memory: { thread: 'thread-1', resource: 'user-1' },
+})
+```
+
+> **Note:** Visit [Background tasks](https://mastra.ai/docs/agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+
+## Cleanup
+
+Every `stream()` and `observe()` call returns a `cleanup` function. Calling it unsubscribes from PubSub and removes the run from the internal registry. If you forget to call it, an automatic timer fires after the stream ends, but calling `cleanup()` yourself frees resources immediately.
+
+## Tool approval
+
+Durable agents support tool approval (human-in-the-loop). When a tool call requires approval, the workflow suspends, emits an `onSuspended` callback, and waits for the caller to resume with `resume()`:
+
+```typescript
+const { output, runId, cleanup } = await durableAgent.stream('Delete the old records', {
+  requireToolApproval: true,
+  onSuspended: ({ toolCallId, toolName, args }) => {
+    // Notify the user and ask for approval
+  },
+})
+```
+
+Resume the suspended run after approval:
+
+```typescript
+await durableAgent.resume(runId, { approved: true })
+```
+
+## Related
+
+- [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent)
+- [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent)
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest)
+- [Agent overview](https://mastra.ai/docs/agents/overview)

package/.docs/docs/agents/skills.md

@@ -0,0 +1,186 @@
+# Agent skills
+
+Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
+
+You can attach skills directly to an agent without setting up a workspace, filesystem, or sandbox. This is useful when you want portable, code-defined capabilities that travel with your agent definition.
+
+## When to use agent-level skills
+
+Use agent-level skills when:
+
+- You want self-contained agents that don't depend on a workspace
+- Skills are defined in code and don't need filesystem discovery
+- You're building packages or libraries that ship agent capabilities
+- You need per-request skill resolution based on context
+
+For filesystem-based skill discovery across a project, use [workspace skills](https://mastra.ai/docs/workspace/skills) instead.
+
+## Quickstart
+
+Define a skill inline and attach it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+const codeReview = createSkill({
+  name: 'code-review',
+  description: 'Use when reviewing code changes.',
+  instructions: `
+    When reviewing code:
+    1. Check for correctness and edge cases
+    2. Verify style consistency
+    3. Look for potential bugs
+  `,
+})
+
+export const reviewer = new Agent({
+  id: 'reviewer',
+  model: 'openai/gpt-5.5',
+  instructions: 'You are a code review assistant.',
+  skills: [codeReview],
+})
+```
+
+The agent automatically gets `skill`, `skill_read`, and `skill_search` tools so it can discover and load skills during conversations.
+
+## Defining inline skills
+
+Use `createSkill()` to create skills entirely in code:
+
+```typescript
+import { createSkill } from '@mastra/core/skills'
+
+export const releaseChecklist = createSkill({
+  name: 'release-checklist',
+  description: 'Use when preparing a release.',
+  instructions: `
+    ## Release Checklist
+    1. Run the full test suite
+    2. Update CHANGELOG.md
+    3. Bump version numbers
+    4. Create a git tag
+  `,
+  references: {
+    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
+  },
+})
+```
+
+The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, just like `references/` files in a filesystem skill.
+
+> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+
+## Filesystem path skills
+
+Point to skill directories on disk without a workspace:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+export const agent = new Agent({
+  id: 'my-agent',
+  model: 'openai/gpt-5.5',
+  skills: [
+    './skills/code-review', // path to a SKILL.md directory
+    './skills/testing', // another filesystem skill
+    createSkill({
+      /* ... */
+    }), // inline skill
+  ],
+})
+```
+
+Filesystem paths use `LocalSkillSource` under the hood, which reads `SKILL.md` files following the same format as [workspace skills](https://mastra.ai/docs/workspace/skills).
+
+## Dynamic skills
+
+For per-request skill resolution, pass a function:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSkill } from '@mastra/core/skills'
+
+const devSkill = createSkill({
+  name: 'dev-tools',
+  description: 'Developer productivity tools.',
+  instructions: '...',
+})
+
+const supportSkill = createSkill({
+  name: 'support-guide',
+  description: 'Customer support guidelines.',
+  instructions: '...',
+})
+
+export const agent = new Agent({
+  id: 'dynamic-agent',
+  model: 'openai/gpt-5.5',
+  skills: ({ requestContext }) => {
+    const role = requestContext.get('userRole')
+    if (role === 'developer') return [devSkill]
+    return [supportSkill]
+  },
+})
+```
+
+The resolver function receives `{ requestContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+
+## Merging with workspace skills
+
+When an agent has both `skills` and a workspace with skills configured, they merge. Agent-level skills take precedence on name conflicts:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { createSkill } from '@mastra/core/skills'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: ['skills'], // provides "code-review" skill
+})
+
+const customReview = createSkill({
+  name: 'code-review', // same name as workspace skill
+  description: 'Custom review process.',
+  instructions: '...',
+})
+
+export const agent = new Agent({
+  id: 'reviewer',
+  model: 'openai/gpt-5.5',
+  workspace,
+  skills: [customReview], // agent-level "code-review" wins
+})
+```
+
+## Programmatic skill access
+
+Use `agent.getSkill()` and `agent.listSkills()` to access skills from application code (e.g., in workflows or API routes):
+
+```typescript
+import { reviewer } from '../mastra/agents'
+
+// Get a specific skill by name
+const skill = await reviewer.getSkill('code-review')
+if (skill) {
+  console.log(skill.instructions)
+}
+
+// List all available skills
+const allSkills = await reviewer.listSkills()
+for (const meta of allSkills) {
+  console.log(`${meta.name}: ${meta.description}`)
+}
+```
+
+> **Note:** Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
+
+## Related
+
+- [Workspace skills](https://mastra.ai/docs/workspace/skills)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
+- [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill)
+- [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills)
+- [Agent skills specification](https://agentskills.io)

package/.docs/docs/agents/using-tools.md

@@ -292,6 +292,58 @@ await supportAgent.generate('Look up the order status', {
 
 Agent-level and per-execution hooks merge per key: passing only `beforeToolCall` at execution time keeps the agent-level `afterToolCall`.
 
+## Streaming
+
+Tools support lifecycle hooks that allow you to monitor different stages of tool execution during streaming. These hooks are particularly useful for logging or analytics.
+
+For generic `writer` API usage, see [Streaming](https://mastra.ai/guides/concepts/streaming).
+
+### Available Hooks
+
+- **onInputStart**: Called when tool call input streaming begins
+- **onInputDelta**: Called for each chunk of input as it streams in
+- **onInputAvailable**: Called when complete input is parsed and validated
+- **onOutput**: Called after the tool successfully executes with the output
+
+For detailed documentation on all lifecycle hooks, see the [createTool() reference](https://mastra.ai/reference/tools/create-tool).
+
+### Example: Using `onInputAvailable` and `onOutput`
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Get weather information',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  // Called when the complete input is available
+  onInputAvailable: ({ input, toolCallId }) => {
+    console.log(`Weather requested for: ${input.city}`)
+  },
+  execute: async input => {
+    const weather = await fetchWeather(input.city)
+    return weather
+  },
+  // Called after successful execution
+  onOutput: ({ output, toolName }) => {
+    console.log(`${toolName} result: ${output.temperature}°F, ${output.conditions}`)
+  },
+})
+```
+
+### Streaming tool input in UIs
+
+When a model generates a tool call, the arguments arrive incrementally as `tool-call-delta` stream chunks before the final `tool-call` chunk. UIs can listen for the corresponding `tool_input_start`, `tool_input_delta`, and `tool_input_end` events to render tool arguments as they stream in — for example, showing a file path or command immediately rather than waiting for the complete tool call.
+
+Using a partial JSON parser on the accumulated `argsTextDelta` fragments lets you extract usable argument values before the JSON is complete. This enables features like live diff previews for edit tools, streaming file content for write tools, and instant display of search patterns or file paths.
+
 ## Control tool selection
 
 Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.