@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.10

package/.docs/reference/file-based-agents/schedules.md

@@ -0,0 +1,232 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Schedules
+
+A file-based agent discovers **schedules** from its `schedules/` directory. Each file declares one recurring task: a cron expression plus what the agent should do when it fires. Mastra registers them into schedule storage at startup, so a scheduled agent needs no runtime registration code.
+
+Use this page for the file-based convention. To create schedules at runtime instead, see [Schedules](https://mastra.ai/reference/schedules/overview).
+
+`defineSchedule` is re-exported from `@mastra/core/agent` so file-based agents need one import path. `@mastra/core/schedules` exports it too.
+
+## Quickstart
+
+Add a file under the agent's `schedules/` directory:
+
+```typescript
+import { defineSchedule } from '@mastra/core/agent'
+
+export default defineSchedule({
+  cron: '*/5 * * * *',
+  prompt: 'Check system health and report any failures.',
+})
+```
+
+Every five minutes, Mastra runs the `support` agent with that prompt.
+
+## Schedule identity
+
+A schedule's id is its path relative to `schedules/` with the extension stripped, so nested directories are a way to group related schedules:
+
+```text
+src/mastra/agents/
+└── support/
+    ├── config.ts
+    ├── instructions.md
+    └── schedules/
+        ├── heartbeat.ts      # id: heartbeat
+        ├── cleanup.md        # id: cleanup
+        └── billing/
+            └── sweep.ts      # id: billing/sweep
+```
+
+That id is stable across builds, which is what lets Mastra tell an edited schedule from a new one. Renaming or moving a file is treated as deleting one schedule and creating another.
+
+`heartbeat.ts` and `heartbeat.md` resolve to the same id, so declaring both is a build error.
+
+## Execution modes
+
+A schedule sets exactly one execution mode. Setting both, or neither, fails the build.
+
+### Prompt mode
+
+`prompt` runs the owning agent with a fixed message. This is fire-and-forget: nothing waits for the result.
+
+```typescript
+import { defineSchedule } from '@mastra/core/agent'
+
+export default defineSchedule({
+  cron: '0 9 * * 1',
+  timezone: 'America/New_York',
+  prompt: 'Summarize last week and post the digest.',
+})
+```
+
+### Handler mode
+
+`handler` computes the fire's parameters when the schedule triggers. Use it when the prompt depends on current state, when some fires should be skipped, or when the run needs channel delivery context.
+
+```typescript
+import { defineSchedule } from '@mastra/core/agent'
+
+export default defineSchedule({
+  cron: '0 3 * * *',
+  handler: async ({ mastra, agentId }) => {
+    const overdue = await findOverdueInvoices()
+
+    // Returning null skips this fire; nothing runs and the trigger is
+    // recorded with outcome 'skipped'.
+    if (overdue.length === 0) return null
+
+    return {
+      prompt: `Chase these overdue invoices: ${overdue.join(', ')}`,
+      threadId: 'billing-ops',
+      resourceId: agentId,
+    }
+  },
+})
+```
+
+The handler's return value is merged over the schedule's stored fields. Returning `undefined` applies no overrides, so the fire falls back to those stored fields. Since a handler-mode schedule can't declare a `prompt`, that fire then fails for a missing prompt. Return a `prompt` to run, or `null` to skip.
+
+Handlers are functions, so they can't be persisted on the stored schedule row. Mastra resolves them in-process when the schedule fires. A handler-mode schedule that supplies no prompt (and declares none) fails that fire with a reason rather than sending the agent an empty message.
+
+That in-process lookup means the process running the scheduler must have the owning agent registered. A normal deployment boots a single entry and gets that for free. Standalone workers need the same entry as your server. Boot one from a trimmed entry and it has no handler to call, so its fires fail rather than run.
+
+### Markdown schedules
+
+A `.md` schedule uses frontmatter for the cron and the document body as the prompt. This is prompt mode with more room to write:
+
+```markdown
+---
+cron: '0 3 * * *'
+timezone: 'UTC'
+name: 'nightly cleanup'
+---
+
+Review tickets untouched for 30 days.
+
+Close the ones that are clearly resolved and summarize the rest.
+```
+
+Always quote the cron. A leading `*` is a YAML alias, so `cron: */5 * * * *` is a parse error while `cron: "*/5 * * * *"` is fine.
+
+Frontmatter accepts every option below except `handler`, which needs a function and so needs a `.ts` or `.js` schedule module. `prompt` isn't settable either, because the body is the prompt. Unknown frontmatter fields fail the build rather than being silently ignored, so a typo like `ifIdel` is caught at build time.
+
+## Options
+
+**cron** (`string`): Standard five-field cron expression. Required. The scheduler evaluates schedules on a tick loop, so the effective granularity is one minute. Sub-minute fields are not supported.
+
+**prompt** (`string`): Message the agent runs on each fire. Set this or handler, not both.
+
+**handler** (`(ctx) => ScheduleOverrides | null | undefined`): Computes the fire at trigger time. Return overrides to apply, or null to skip this fire. Returning nothing applies no overrides, which fails the fire because handler mode has no stored prompt. Set this or prompt, not both.
+
+**timezone** (`string`): IANA timezone the cron is evaluated in (e.g. America/New\_York). Defaults to the host process timezone, which varies by deployment, so set this explicitly for anything time-of-day sensitive. DST transitions are handled by the timezone rules, so 0 9 \* \* \* stays 9am local across the shift.
+
+**name** (`string`): Free-form label shown in Studio and filterable via mastra.schedules.list({ name }).
+
+**threadId** (`string`): Sends the fire as a signal into an existing thread instead of starting a fresh run. Requires resourceId.
+
+**resourceId** (`string`): Owner of the target thread. Required when threadId is set.
+
+**signalType** (`'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'`): Signal category for the fire. Threaded schedules only. (Default: `'notification'`)
+
+**tagName** (`string`): XML tag the signal renders as, so a fire reaches the agent as \<schedule>…\</schedule>. (Default: `'schedule'`)
+
+**attributes** (`Record<string, string | number | boolean | null>`): Attributes rendered onto the signal XML tag.
+
+**providerOptions** (`Record<string, unknown>`): Provider options merged into the schedule signal payload on every fire. Must be JSON-safe.
+
+**ifActive** (`ScheduleIfActive`): What to do when the target thread is already streaming: deliver, persist, or discard. Threaded schedules only.
+
+**ifIdle** (`ScheduleIfIdle`): What to do when the target thread is idle: wake, persist, or discard. Threaded schedules only.
+
+**status** (`'active' | 'paused'`): Status the row is created with. Applies on first create only, because the sync never patches status so that pausing through the API survives a redeploy. Changing this value in code later has no effect on an existing schedule. (Default: `'active'`)
+
+**metadata** (`Record<string, unknown>`): Arbitrary JSON-safe data stored alongside the schedule row.
+
+## Testing a schedule in development
+
+Schedules fire on their cron cadence, which is impractical while iterating. Fire one on demand by id instead:
+
+```bash
+# List schedules to find the id
+curl http://localhost:4111/api/schedules
+
+# Fire one now, out-of-band from its cron
+curl -X POST http://localhost:4111/api/schedules/<scheduleId>/run
+```
+
+This records a trigger with `triggerKind: "manual"` and doesn't advance `nextFireAt`, so the regular cadence is unaffected. Studio lists the same schedules and their trigger history.
+
+Stored ids are namespaced and URL-encoded. `billing/sweep` on the `support` agent becomes `fsa_support__billing%2Fsweep`, so copy the id from the list response rather than assembling it by hand.
+
+## Registration and lifecycle
+
+Mastra syncs declared schedules into schedule storage when it starts, and again whenever an agent is registered afterward. Declaring a schedule is enough to start the scheduler, with no `scheduler: { enabled: true }` needed.
+
+The sync compares each declared schedule against its stored row and writes only what changed:
+
+- A new schedule file creates a row.
+- Editing `cron` or `timezone` patches the row and recomputes the next fire time, so an edited schedule never fires on its old cadence.
+- Deleting or renaming a schedule file deletes its row.
+- Pausing a schedule through the API survives a redeploy. The sync deliberately leaves `status` alone.
+
+The sync only removes rows belonging to agents registered in the current process, so a process holding a subset of your agents never deletes the others' schedules. When an agent is removed from the project entirely, its leftover rows are cleaned up on their next fire, when the scheduler finds no agent to run.
+
+Schedules created at runtime through `mastra.schedules.create(...)` live in a separate namespace and are never touched by this sync.
+
+## Limits
+
+**Root agents only.** Schedules must be declared on a top-level agent. A `schedules/` directory under `subagents/` is a build error, because subagents are wired into their parent rather than registered on the Mastra instance, so the scheduler could never resolve one as a target. Give the parent the schedule and let it delegate.
+
+**Storage required.** Schedules are persisted rows, so the instance needs [storage](https://mastra.ai/reference/file-based-agents/storage) configured. Rows in an in-memory store don't survive a restart.
+
+**Hosting.** The scheduler runs as a background worker inside the Mastra process, so it needs a host that keeps that process alive. Long-running Node servers and containers work. Environments that freeze or recycle the process between requests, which includes most serverless function platforms, will miss fires. Use the platform's own cron to call the run endpoint there instead.
+
+**Code-defined agents.** An agent directory whose `config.ts` exports `new Agent({...})` is used verbatim, so its `schedules/` directory is ignored with a warning. Use `mastra.schedules.create(...)` for those.
+
+## Example
+
+A support agent with two schedules: a fixed weekly digest, and a nightly sweep that only runs when there's something to do.
+
+```text
+src/mastra/agents/
+└── support/
+    ├── config.ts
+    ├── instructions.md
+    └── schedules/
+        ├── weekly-digest.md
+        └── billing/
+            └── sweep.ts
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.6-sol',
+})
+```
+
+```markdown
+---
+cron: '0 9 * * 1'
+timezone: 'America/New_York'
+---
+
+Summarize the past week's tickets and post the digest to the team channel.
+```
+
+```typescript
+import { defineSchedule } from '@mastra/core/agent'
+
+export default defineSchedule({
+  cron: '0 3 * * *',
+  timezone: 'America/New_York',
+  handler: async () => {
+    const overdue = await findOverdueInvoices()
+    if (overdue.length === 0) return null
+    return { prompt: `Draft reminders for ${overdue.length} overdue invoices.` }
+  },
+})
+```

package/.docs/reference/index.md

@@ -82,9 +82,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [createCodingAgent()](https://mastra.ai/reference/coding-agent/create-coding-agent)
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
+- [.addDynamicWorkflow()](https://mastra.ai/reference/core/addDynamicWorkflow)
+- [.addDynamicWorkflows()](https://mastra.ai/reference/core/addDynamicWorkflows)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)
-- [.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow)
-- [.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows)
 - [.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
 - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
@@ -189,6 +189,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Memory](https://mastra.ai/reference/file-based-agents/memory)
 - [Observability](https://mastra.ai/reference/file-based-agents/observability)
 - [Processors](https://mastra.ai/reference/file-based-agents/processors)
+- [Schedules](https://mastra.ai/reference/file-based-agents/schedules)
 - [Scorers](https://mastra.ai/reference/file-based-agents/scorers)
 - [Server](https://mastra.ai/reference/file-based-agents/server)
 - [Skills](https://mastra.ai/reference/file-based-agents/skills)
@@ -284,6 +285,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
 - [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
 - [MSSQL Storage](https://mastra.ai/reference/storage/mssql)
+- [OracleDB Storage](https://mastra.ai/reference/storage/oracledb)
 - [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
 - [Redis Storage](https://mastra.ai/reference/storage/redis)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
@@ -301,6 +303,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createBedrockKBTool()](https://mastra.ai/reference/tools/bedrock-kb-tool)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
@@ -325,6 +328,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Vector Store](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB Vector Store](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch Vector Store](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB Vector Store](https://mastra.ai/reference/vectors/oracledb)
 - [PG Vector Store](https://mastra.ai/reference/vectors/pg)
 - [Pinecone Vector Store](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
@@ -364,9 +368,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.speak()](https://mastra.ai/reference/voice/voice.speak)
 - [.updateConfig()](https://mastra.ai/reference/voice/voice.updateConfig)
 - [Overview](https://mastra.ai/reference/workers/overview)
+- [Dynamic Workflow Definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition)
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
-- [Stored Workflow Definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
 - [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -64,17 +64,19 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+
+A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
 ### What cost fields may be included
 
-| Field           | Description                                                                  |
-| --------------- | ---------------------------------------------------------------------------- |
-| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                   |
-| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                 |
-| `estimatedCost` | Estimated cost for this metric, calculated from token count and pricing tier |
-| `costUnit`      | Currency unit (e.g. `USD`)                                                   |
-| `costMetadata`  | Additional pricing context (tier information, error details)                 |
+| Field           | Description                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                                                         |
+| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                                                       |
+| `estimatedCost` | Estimated cost from token count and pricing tier, or a total reported by the provider                              |
+| `costUnit`      | Currency unit (e.g. `USD`)                                                                                         |
+| `costMetadata`  | Additional pricing context, including tier information, error details, and provider-reported cost source and scope |
 
 ## Correlation with traces
 

package/.docs/reference/rag/metadata-filters.md

@@ -2,7 +2,7 @@
 
 # Metadata filters
 
-Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
+Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into its native query format. For example, PgVector uses PostgreSQL JSONB predicates, while OracleDB stores metadata as Oracle JSON and compiles filters to `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE`, and `LIKE` predicates with bound values.
 
 ## Basic example
 
@@ -34,11 +34,11 @@ const results = await store.query({
 
 ### Array Operators
 
-`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
+`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
 
 ### Logical Operators
 
-`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
+`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB
 
 ### Element Operators
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -124,6 +124,14 @@ const results = await store.query({
 - Empty arrays in conditions are handled gracefully
 - Metadata is stored in a JSONB column for efficient querying
 
+### OracleDB
+
+- Metadata is stored as Oracle JSON alongside each `VECTOR` row
+- Scalar comparisons use `JSON_VALUE`, while array, existence, and element-match checks use `JSON_EXISTS`
+- `$regex` uses Oracle `REGEXP_LIKE`; string `$contains` uses case-insensitive `LIKE`
+- Nested fields are supported with dot notation and are converted to quoted Oracle JSON paths
+- User-provided metadata values are bound as parameters instead of interpolated into SQL
+
 ### PgVector
 
 - Full support for PostgreSQL's native JSON querying capabilities
@@ -211,6 +219,7 @@ const results = await store.query({
 - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [PgStore](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)

package/.docs/reference/server/register-api-route.md

@@ -22,6 +22,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved. For example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you change `apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference the new prefix, and update any client code (including `MastraClient` `apiPrefix`) that hits `/api/*`.
+
 ### options
 
 **method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route

package/.docs/reference/server/routes.md

@@ -171,30 +171,44 @@ 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                |
-
-### Stored workflows
-
-Stored workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows).
-
-| Method   | Path                                      | Description                                                                    |
-| -------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
-| `GET`    | `/api/stored/workflows`                   | List stored workflow definitions, filterable by `status` and `authorId`        |
-| `GET`    | `/api/stored/workflows/:storedWorkflowId` | Get a stored workflow definition by ID                                         |
-| `POST`   | `/api/stored/workflows`                   | Upsert a definition (plus optional helper `dependencies`) and live-register it |
-| `DELETE` | `/api/stored/workflows/:storedWorkflowId` | Delete a stored definition and unregister the live workflow                    |
-
-On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered stored workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
+| 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;
+  };
+}
+```
+
+### Dynamic workflows
+
+Dynamic workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows).
+
+| Method   | Path                                       | Description                                                                    |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/stored/workflows`                    | List dynamic workflow definitions, filterable by `status` and `authorId`       |
+| `GET`    | `/api/stored/workflows/:dynamicWorkflowId` | Get a dynamic workflow definition by ID                                        |
+| `POST`   | `/api/stored/workflows`                    | Upsert a definition (plus optional helper `dependencies`) and live-register it |
+| `DELETE` | `/api/stored/workflows/:dynamicWorkflowId` | Delete a dynamic workflow definition and unregister the live workflow          |
+
+On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered dynamic workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
 
 ### Create run request body
 

package/.docs/reference/storage/composite.md

@@ -251,6 +251,64 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
+## Closing connections
+
+`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({ id: 'composite', default: pgStore }),
+})
+
+process.on('SIGTERM', async () => {
+  // Releases the Postgres pool, so the process can exit
+  await mastra.shutdown()
+})
+```
+
+A store you construct only to supply a domain isn't reachable through the composite. Keep a reference to it and close it yourself:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ClickhouseStore } from '@mastra/clickhouse'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const clickhouseStore = new ClickhouseStore({
+  id: 'clickhouse-storage',
+  url: process.env.CLICKHOUSE_URL,
+  username: process.env.CLICKHOUSE_USERNAME,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: { observability: clickhouseStore.stores?.observability },
+  }),
+})
+
+process.on('SIGTERM', async () => {
+  await mastra.shutdown()
+  await clickhouseStore.close()
+})
+```
+
 ## Use cases
 
 ### Separate databases for different workloads