@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

package/.docs/docs/mastra-platform/studio.md

@@ -0,0 +1,87 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Studio on Mastra platform
+
+Studio on Mastra platform is a hosted visual workspace for testing agents and running workflows, plus inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
+
+You can deploy Studio from the CLI as shown below, or link a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
+
+> **Note:** `mastra studio deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.
+
+## Quickstart
+
+1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
+
+2. Install the `mastra` CLI globally:
+
+   **npm**:
+
+   ```bash
+   npm install -g mastra
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add -g mastra
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn global add mastra
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add --global mastra
+   ```
+
+3. Deploy Studio with a single command:
+
+   ```bash
+   mastra studio deploy
+   ```
+
+   On a successful deploy, the CLI outputs the URL of your deployed Studio instance.
+
+On your first deploy, the CLI prompts you to create a new project or select an existing one. It then creates a `.mastra-project.json` file in your project directory. This file links your local project to a platform project. It contains the `projectId`, `projectName`, and `organizationId`. Commit this file to your repository so CI/CD knows which project to deploy to.
+
+## How deploy works
+
+The `mastra studio deploy` command builds your project and compiles `src/mastra/` into `.mastra/output`. It packages that output as an artifact ZIP, then uploads and deploys it to a cloud sandbox.
+
+A deploy transitions through **queued → uploading → starting → running** or **failed** if something goes wrong. If a sandbox is already running for your project, the platform updates it in place with no downtime. Otherwise, it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys.
+
+See the [`mastra studio deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
+
+## Environment files
+
+A local env file is optional. When a `.env` or `.env.*` file is present in the project directory, the deploy bundles its environment variables.
+
+When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
+
+```bash
+mastra studio deploy --env-file .env.production --yes
+```
+
+To run the same codebase across `production` and `staging`, use the unified [`mastra deploy --env`](https://mastra.ai/docs/mastra-platform/deploy) command instead. [Environments](https://mastra.ai/docs/mastra-platform/environments) replace the earlier pattern of one project per environment.
+
+## Create a new project non-interactively
+
+`mastra studio deploy` can create a project on first run. If `--project <name>` doesn't match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+
+```bash
+mastra studio deploy --project "my-new-project" --yes
+```
+
+Use this from CI or AI coding agents instead of `mastra studio projects create`, which is interactive only.
+
+## Self-host Studio
+
+To deploy Studio on your own infrastructure, see [Studio deployment](https://mastra.ai/docs/studio/deployment).
+
+## Related
+
+- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -0,0 +1,123 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Trace Intelligence on Mastra platform
+
+Trace Intelligence finds recurring patterns across your agent's interactions. It analyzes traces captured by Mastra Observability, produces trace signals for four dimensions, and clusters similar trace signals into themes.
+
+Use Trace Intelligence to investigate questions such as:
+
+- What are users trying to accomplish?
+- Which goals tend to succeed, remain unresolved, or become blocked?
+- Which agent behaviors appear in successful and unsuccessful interactions?
+- How does user sentiment relate to goals and outcomes?
+
+> **Private beta:** Trace Intelligence is available by invitation for selected Mastra platform projects.
+
+## Get access
+
+1. Submit the [Trace Intelligence private beta form](https://mastra.ai/trace-intelligence) to request access.
+2. Confirm that [Mastra platform Observability](https://mastra.ai/docs/mastra-platform/observability) is enabled and that completed agent traces appear under **Traces**.
+3. Requires at least `@mastra/core@1.53.0` and `mastra@1.20.2`. Upgrade your project then deploy or redeploy Studio for the enrolled project. Local Studio and server-only deployments aren't supported during the private beta.
+4. Open the deployed Studio and select **Intelligence** in the sidebar.
+5. Send representative traffic to your agent and allow time for analysis.
+
+Once Mastra enrolls the project, you don't need to change your agent definition or calls.
+
+### When data is available
+
+Trace Intelligence needs enough processed traces from one agent to identify recurring patterns. Initial themes are usually available after at least **100 completed traces** from that agent have been processed.
+
+The trace count under **Traces** can reach 100 before Trace Intelligence is ready because the analysis pipeline runs asynchronously. Processing can take several minutes after the threshold is reached. Traces that can't be analyzed don't contribute, so 100 is a minimum, not an exact UI trigger.
+
+Trace Intelligence updates automatically as more traces arrive. Studio needs themes for at least two trace signal types before it can display the relationship flow.
+
+Use representative traffic. A small set of repeated test prompts can produce unrepresentative results, such as one broad theme or mostly Noise.
+
+## Understand the analysis
+
+Each analyzable completed trace produces four trace signals:
+
+| Trace signal  | Meaning                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| **Goal**      | What the user is trying to achieve or have completed.                                                  |
+| **Outcome**   | The final completed, partial, blocked, failed, unresolved, or unclear state.                           |
+| **Behavior**  | Observable agent actions and patterns, including tool use, omissions, retries, failures, and recovery. |
+| **Sentiment** | The user's emotional state or attitude.                                                                |
+
+Themes are clusters generated from similar trace signals. Clustering happens independently for each trace signal type. One trace can belong to a separate theme in every dimension: Goal, Outcome, Behavior, and Sentiment.
+
+### Themes and relationships
+
+The flow chart connects themes in adjacent trace signal columns:
+
+- A **node** represents a theme. Its count is the number of distinct traces assigned to that theme in the selected snapshot.
+- A **ribbon** connects traces assigned to themes in both adjacent columns. Its width represents the shared trace count.
+- Hover over or focus a node or ribbon to isolate its relationships.
+
+The flow shows association, not causation or execution order. For example, a ribbon between a Goal and an Outcome means that both themes occurred in the same traces. It doesn't show that the goal caused the outcome.
+
+### Distributions, Other, and Noise
+
+The cards below the flow show each trace signal's theme distribution:
+
+- **Trace count**: The number of distinct traces assigned to a theme in the selected snapshot.
+- **Stage share**: The percentage of analyzed traces for that trace signal assigned to the theme.
+
+Studio shows the most common themes for each trace signal type. It may combine smaller themes into **Other** to preserve totals without overcrowding the chart.
+
+**Noise** contains summaries that didn't consistently match a recurring theme in the selected snapshot. It doesn't necessarily indicate an error or a low-quality interaction. Noise can include rare requests and emerging patterns. It can also contain ambiguous interactions or unrelated cases. A large Noise share can indicate highly varied traffic or insufficient data for stable themes.
+
+### Snapshots
+
+A snapshot is a moving analysis window over a set of traces. Snapshots can overlap, so don't add their trace counts together. Compare trace count and stage share together because traffic volume can change between windows.
+
+A theme can persist, disappear, split, merge, or return across snapshots. Treat theme names and descriptions as generated summaries, not fixed taxonomies.
+
+## Use the Trace Intelligence page
+
+1. Use the **Agent** selector to switch between agents with available analysis. An agent doesn't appear until its first themes are ready.
+2. Select a theme in the flow to filter every column to traces containing that theme.
+3. Select **View theme details** to inspect its description, trace count, stage share, generated examples, and history.
+4. Select **Clear filter** to restore the complete flow.
+
+You can also:
+
+- Select a theme in a distribution card to open its details and generated example summaries.
+- Select **Noise** in a distribution card to inspect its distribution and generated example summaries.
+- Drag the distribution cards to reorder the trace signal columns and see a different relationship perspective.
+- Use the timeline to select a snapshot, or select **Play** to watch themes change over time.
+- Open a theme's history to see whether it persisted and how its coverage changed.
+
+Filtering the flow by a theme is unavailable for snapshots with more than 2,000 traces. Choose another snapshot or clear the active filter to return to the full flow. Theme and Noise details remain available from the distribution cards.
+
+## Troubleshooting
+
+### Intelligence isn't in the sidebar
+
+Confirm that Mastra enrolled the correct project, that you use the beta-compatible Mastra version, and that you redeployed Studio. The private beta doesn't support local Studio.
+
+### An agent is missing
+
+Confirm that its completed traces are listed under **Traces**. The agent is listed only after its first themes are ready. If it recently reached 100 traces, allow time for asynchronous processing.
+
+### The relationship flow is unavailable
+
+The flow requires themes for at least two trace signal types. Continue sending representative traffic and allow processing to finish.
+
+### Most summaries are Noise
+
+Collect more representative traffic and compare a later snapshot. Varied or rare interactions are harder to group, while repeated test prompts can produce an unrepresentative distribution.
+
+## Private-beta limitations
+
+- Trace Intelligence is available only for enrolled projects in deployed Studio.
+- Initial analysis requires at least 100 processed traces per agent. Some agents may require more.
+- Results depend on the diversity and quality of captured traces.
+- Trace signal summaries, theme labels, clustering, thresholds, and UI behavior can change during the beta.
+
+When reporting feedback, include the organization ID, project ID, agent ID, selected snapshot, and the theme or Noise examples that illustrate the issue.
+
+## Related
+
+- [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability)
+- [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio)

package/.docs/docs/mastra-platform/workspaces.md

@@ -0,0 +1,152 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspaces
+
+A workspace is a set of runtime resources the Mastra platform provisions and hands to your agents at deploy time. Each environment gets its own workspace so `production` and `staging` stay isolated.
+
+Every workspace exposes two capabilities:
+
+- One **bucket** for filesystem storage, wrapped by [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem). The bucket is a durable, environment-scoped store agents read from and write to across runs.
+- A pool of **on-demand sandboxes** for command execution, wrapped by [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox). Each `PlatformSandbox` instance provisions its own remote sandbox on `start()` and destroys it on `destroy()`. Agents typically spin up many sandboxes per session, use them for a task, and let them go.
+
+Workspaces are scoped to a single [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` don't share buckets or sandbox pools. The platform manages provisioning, authentication, and idle cleanup.
+
+## When workspaces are provisioned
+
+New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
+
+Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
+
+If provisioning fails for an environment, for example while the sandbox provider is under load, the Workspaces tab shows the failure and offers a retry. The environment itself is still created. Only the workspace is unavailable until you retry.
+
+## Use the workspace from your code
+
+Install the provider package:
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Compose the providers into a workspace and register it with Mastra:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
+
+export const workspace = new Workspace({
+  filesystem: new PlatformFilesystem(),
+  sandbox: new PlatformSandbox(),
+})
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workspace } from './workspace'
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+`PlatformFilesystem` and `PlatformSandbox` read their configuration from environment variables, so you don't pass any options on the platform. The platform injects them at deploy time. See [Environment variables](#environment-variables).
+
+## One bucket, many sandboxes
+
+`PlatformFilesystem` and `PlatformSandbox` have different lifecycles, which matters when you design agents.
+
+**`PlatformFilesystem` is a long-lived handle to the environment's bucket.** All requests, all agents, and all sandboxes in the environment read and write the same object storage. Anything an agent writes is visible on the next request unless you explicitly delete it.
+
+**`PlatformSandbox` is a client for provisioning ephemeral sandboxes.** Each `PlatformSandbox` instance owns one remote sandbox:
+
+- `start()` provisions a fresh sandbox (or reattaches when you passed `sandboxId`).
+- `executeCommand()` runs commands against it.
+- `destroy()` tears the sandbox down. `stop()` is an alias.
+
+The `sandbox` you pass to `Workspace` provides the tools an agent uses inside its own request. When your agent needs another isolated environment, for example a per-task workspace, a per-user tenant, or a background job that shouldn't touch the caller's shell state, construct another `PlatformSandbox`:
+
+```typescript
+import { PlatformSandbox } from '@mastra/platform-workspace'
+
+export async function runInFreshSandbox(command: string) {
+  const sandbox = new PlatformSandbox()
+  await sandbox.start()
+  try {
+    return await sandbox.executeCommand(command)
+  } finally {
+    await sandbox.destroy()
+  }
+}
+```
+
+Or clone a configured sandbox as the template for a fleet, so the clones inherit credentials, environment, network isolation, and defaults without repeating them:
+
+```typescript
+const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })
+
+const perProjectSandbox = template.clone({ id: `project-${projectId}` })
+await perProjectSandbox.start()
+```
+
+See [`PlatformSandbox` reference](https://mastra.ai/reference/workspace/platform-sandbox) for the full lifecycle, checkpoint recovery, reattachment, and clone options.
+
+## Environment variables
+
+Every deploy that runs on a platform environment with a workspace receives these variables automatically:
+
+| Variable                       | Contents                                                                                                                                        |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | Platform-issued JSON Web Token (JWT) the workspace providers use to authenticate. The token is scoped to the deploy's organization and project. |
+| `MASTRA_PROJECT_ID`            | Project the deploy belongs to.                                                                                                                  |
+| `MASTRA_ENVIRONMENT_ID`        | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                |
+| `MASTRA_PLATFORM_BUCKET_NAME`  | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                            |
+
+These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
+
+## Local development
+
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the project, environment, and bucket values from your project's **Workspaces** tab. For `MASTRA_PLATFORM_ACCESS_TOKEN`, create an `sk_` API token on your organization's settings page under **API Tokens**. Platform deploys use an injected JWT instead.
+
+```bash
+MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform, they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
+
+For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
+
+## Inspect the workspace
+
+The Workspaces tab in your platform project shows, per environment:
+
+- Bucket status and its contents, with upload, download, and delete actions.
+- Recent sandbox sessions with their command, exit code, and duration.
+- Provisioning failures with a **Retry** action.
+
+## See also
+
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): reference for the filesystem provider.
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): reference for the sandbox provider, including checkpoint recovery and cloning.
+- [Environments](https://mastra.ai/docs/mastra-platform/environments): how environments scope workspaces, variables, and databases.