@mastra/mcp-docs-server 1.2.13-alpha.4 → 1.2.13-alpha.8

package/.docs/guides/deployment/mastra-workers.md

@@ -2,7 +2,7 @@
 
 # Deploy Mastra workers
 
-Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate processes so you can scale orchestration, scheduling, and background tasks independently from the API. This guide walks through a fully split deployment using Docker Compose.
+Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate processes so you can scale orchestration, scheduling, and background tasks independently from the API. This guide walks through a fully split deployment using Docker Compose or Kubernetes.
 
 > **Info:** This guide covers splitting workers into their own containers. If you only need workers to run in-process alongside the API, see [Workers](https://mastra.ai/docs/deployment/workers). No extra setup is required.
 
@@ -11,7 +11,7 @@ Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate proc
 You'll need:
 
 - A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
-- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/)
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/), or a [Kubernetes](https://kubernetes.io/docs/setup/) cluster with [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
 - A distributed PubSub backend: [Redis](https://redis.io/) for [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), or a [Google Cloud](https://cloud.google.com/) project for [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)
 - A shared database reachable from every container. See [supported storage backends](https://mastra.ai/reference/workers/overview) for the full list.
 
@@ -83,9 +83,13 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
    CMD ["node", "index.mjs"]
    ```
 
-3. Create a `docker-compose.yml` that runs the fully split topology. The file defines six services: a database, a PubSub backend, the API server, and three workers. Each worker container runs the same image with a different `MASTRA_WORKERS` value to control which worker starts.
+3. Define the fully split topology. The setup runs six services: a database, a PubSub backend, the API server, and three workers. Each worker runs the same image with a different `MASTRA_WORKERS` value to control which worker starts.
 
-   The API container sets `MASTRA_WORKERS: "false"` to disable all event processing. The orchestration worker sets `MASTRA_STEP_EXECUTION_URL` to point step execution requests at the API's internal URL. See [step execution URL](#step-execution-url) for details.
+   The API sets `MASTRA_WORKERS: "false"` to disable all event processing. The orchestration worker sets `MASTRA_STEP_EXECUTION_URL` to point step execution requests at the API's internal URL. See [step execution URL](#step-execution-url) for details.
+
+   All services share a `MASTRA_WORKER_AUTH_TOKEN`. Workers include this token in requests to the API so the API can verify the caller is a trusted internal service. See [worker authentication](https://mastra.ai/docs/server/auth/workers) for details.
+
+   **Docker Compose**:
 
    ```yaml
    services:
@@ -123,6 +127,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: 'false'
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          postgres:
            condition: service_healthy
@@ -141,6 +146,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: orchestration
          MASTRA_STEP_EXECUTION_URL: http://api:4111/api
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -151,6 +157,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: scheduler
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -161,6 +168,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: backgroundTasks
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -173,11 +181,296 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
 
    ```bash
    POSTGRES_PASSWORD=your-secure-password
+   MASTRA_WORKER_AUTH_TOKEN=your-shared-secret-token
    ```
 
    > **Note:** Remember to set any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key).
 
-4. Start the stack and verify the API responds:
+   **Kubernetes**:
+
+   Create a namespace and a Secret with your connection strings:
+
+   ```yaml
+   apiVersion: v1
+   kind: Namespace
+   metadata:
+     name: mastra-workers
+   ```
+
+   ```bash
+   kubectl apply -f k8s/namespace.yaml
+   kubectl create secret generic mastra-secrets -n mastra-workers \
+     --from-literal=POSTGRES_PASSWORD='your-password' \
+     --from-literal=DATABASE_URL='postgresql://mastra:your-password@postgres:5432/mastra' \
+     --from-literal=REDIS_URL='redis://redis:6379' \
+     --from-literal=MASTRA_WORKER_AUTH_TOKEN='your-shared-token'
+   ```
+
+   > **Note:** Add any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key) to the Secret or as additional `--from-literal` entries.
+
+   Build and push the Docker image to a registry your cluster can pull from:
+
+   ```bash
+   docker build -t your-registry/mastra-workers:latest ./app
+   docker push your-registry/mastra-workers:latest
+   ```
+
+   Apply Deployments and Services for the database, PubSub backend, API, and three workers. The example below uses in-cluster Postgres and Redis. In production, use managed services (e.g., Amazon RDS, Cloud SQL, ElastiCache, Memorystore).
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: postgres
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: postgres
+     template:
+       metadata:
+         labels:
+           app: postgres
+       spec:
+         containers:
+           - name: postgres
+             image: postgres:16-alpine
+             ports:
+               - containerPort: 5432
+             env:
+               - name: POSTGRES_USER
+                 value: mastra
+               - name: POSTGRES_PASSWORD
+                 valueFrom:
+                   secretKeyRef:
+                     name: mastra-secrets
+                     key: POSTGRES_PASSWORD
+               - name: POSTGRES_DB
+                 value: mastra
+             volumeMounts:
+               - name: pgdata
+                 mountPath: /var/lib/postgresql/data
+         volumes:
+           - name: pgdata
+             emptyDir: {}
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: postgres
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: postgres
+     ports:
+       - port: 5432
+         targetPort: 5432
+   ```
+
+   > **Caution:** The Postgres example above uses `emptyDir` for storage, which means data is lost when the pod restarts. In production, replace it with a `PersistentVolumeClaim` or use a managed database service.
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: redis
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: redis
+     template:
+       metadata:
+         labels:
+           app: redis
+       spec:
+         containers:
+           - name: redis
+             image: redis:7-alpine
+             args: ['--appendonly', 'yes']
+             ports:
+               - containerPort: 6379
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: redis
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: redis
+     ports:
+       - port: 6379
+         targetPort: 6379
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: api
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: api
+     template:
+       metadata:
+         labels:
+           app: api
+       spec:
+         containers:
+           - name: api
+             image: your-registry/mastra-workers:latest
+             ports:
+               - containerPort: 4111
+             env:
+               - name: MASTRA_WORKERS
+                 value: 'false'
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             readinessProbe:
+               httpGet:
+                 path: /api/agents
+                 port: 4111
+               initialDelaySeconds: 10
+               periodSeconds: 5
+             livenessProbe:
+               httpGet:
+                 path: /api/agents
+                 port: 4111
+               initialDelaySeconds: 15
+               periodSeconds: 10
+             resources:
+               requests:
+                 cpu: 500m
+                 memory: 512Mi
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: api
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: api
+     ports:
+       - port: 4111
+         targetPort: 4111
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: orchestration-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: orchestration-worker
+     template:
+       metadata:
+         labels:
+           app: orchestration-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: orchestration
+               - name: MASTRA_STEP_EXECUTION_URL
+                 value: http://api:4111/api
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: scheduler-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: scheduler-worker
+     template:
+       metadata:
+         labels:
+           app: scheduler-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: scheduler
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: background-task-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: background-task-worker
+     template:
+       metadata:
+         labels:
+           app: background-task-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: backgroundTasks
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   Apply all manifests and wait for the API to become ready:
+
+   ```bash
+   kubectl apply -f k8s/
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=api --timeout=90s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=orchestration-worker --timeout=60s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=scheduler-worker --timeout=60s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=background-task-worker --timeout=60s
+   ```
+
+4. Verify the stack is running and the API responds:
+
+   **Docker Compose**:
 
    ```bash
    docker compose up -d
@@ -185,6 +478,21 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
    curl http://localhost:4111/api/agents
    ```
 
+   **Kubernetes**:
+
+   ```bash
+   kubectl get pods -n mastra-workers
+   kubectl port-forward -n mastra-workers svc/api 4111:4111
+   ```
+
+   In a separate terminal:
+
+   ```bash
+   curl http://localhost:4111/api/agents
+   ```
+
+   A JSON list of your agents confirms the API and workers are running.
+
 ## Step execution URL
 
 In a fully split deployment, the orchestration worker runs in a separate container from the API. When it processes a workflow event, it delegates step execution to the API over HTTP.
@@ -203,11 +511,46 @@ Without this variable, the orchestration worker attempts to execute steps in-pro
 
 The orchestration and background task workers are safe to scale horizontally. PubSub consumer groups distribute events across instances, so each event is processed once:
 
+**Docker Compose**:
+
 ```bash
 docker compose up -d --scale orchestration-worker=3
 docker compose up -d --scale background-task-worker=2
 ```
 
+**Kubernetes**:
+
+```bash
+kubectl scale deployment/orchestration-worker -n mastra-workers --replicas=3
+kubectl scale deployment/background-task-worker -n mastra-workers --replicas=2
+```
+
+For automatic scaling, add a HorizontalPodAutoscaler:
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: orchestration-worker
+  namespace: mastra-workers
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: orchestration-worker
+  minReplicas: 1
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```
+
+> **Note:** CPU-based autoscaling needs the [metrics-server](https://github.com/kubernetes-sigs/metrics-server) running in the cluster. Managed clusters like GKE, EKS, and AKS include it by default.
+
 The API can also scale horizontally behind a load balancer.
 
 **Don't scale the scheduler worker.** Run exactly one instance. Multiple schedulers polling the same storage fire duplicate events for the same schedule.
@@ -229,4 +572,5 @@ Workers recover from crashes because the distributed PubSub backend persists una
 - [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
-- [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server): Build output and server configuration
+- [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server): Build output and server configuration
+- [Deploy Mastra to Kubernetes](https://mastra.ai/guides/deployment/kubernetes): Multi-pod deployment with durable agents

package/.docs/guides/deployment/vercel.md

@@ -86,6 +86,8 @@ export const mastra = new Mastra({
 
 After deploying, Studio is available at the root URL (`https://<your-project>.vercel.app/`) and the API remains at `/api/*`. Studio automatically connects to the API on the same origin, so you don't need additional environment variables.
 
+Studio serves its own pages from the CDN, and every other path goes to your server, so routes you add with [`registerApiRoute()`](https://mastra.ai/docs/server/custom-api-routes) stay reachable at their own paths. Avoid giving a custom route a path that Studio already uses (for example `/agents` or `/workflows`), since Studio claims those first.
+
 > **Warning:** Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.
 
 ## Optional overrides

package/.docs/models/gateways/openrouter.md

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 338 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 335 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -224,7 +224,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-4o-mini`                                       |
 | `openai/gpt-4o-mini-2024-07-18`                            |
 | `openai/gpt-5`                                             |
-| `openai/gpt-5-codex`                                       |
 | `openai/gpt-5-image`                                       |
 | `openai/gpt-5-image-mini`                                  |
 | `openai/gpt-5-mini`                                        |
@@ -264,12 +263,10 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/o1`                                                |
 | `openai/o1-pro`                                            |
 | `openai/o3`                                                |
-| `openai/o3-deep-research`                                  |
 | `openai/o3-mini`                                           |
 | `openai/o3-mini-high`                                      |
 | `openai/o3-pro`                                            |
 | `openai/o4-mini`                                           |
-| `openai/o4-mini-deep-research`                             |
 | `openai/o4-mini-high`                                      |
 | `openrouter/auto`                                          |
 | `openrouter/bodybuilder`                                   |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5151 models from 164 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5152 models from 164 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/hyper.md

@@ -2,7 +2,7 @@
 
 # ![Charm Hyper logo](https://models.dev/logos/hyper.svg)Charm Hyper
 
-Access 22 Charm Hyper models through Mastra's model router. Authentication is handled automatically using the `HYPER_API_KEY` environment variable.
+Access 23 Charm Hyper models through Mastra's model router. Authentication is handled automatically using the `HYPER_API_KEY` environment variable.
 
 Learn more in the [Charm Hyper documentation](https://hyper.charm.land).
 
@@ -50,6 +50,7 @@ for await (const chunk of stream) {
 | `hyper/llama-3.3-70b-instruct`                       | 128K    |       |           |       |       |       | $0.51      | $1          |
 | `hyper/llama-4-maverick-17b-128e-instruct-fp8`       | 430K    |       |           |       |       |       | $0.28      | $0.93       |
 | `hyper/minimax-m2.7`                                 | 205K    |       |           |       |       |       | $0.48      | $2          |
+| `hyper/minimax-m3`                                   | 512K    |       |           |       |       |       | $0.33      | $1          |
 | `hyper/qwen3-coder-480b-a35b-instruct-int4-mixed-ar` | 106K    |       |           |       |       |       | $0.57      | $2          |
 | `hyper/qwen3-next-80b-a3b-instruct`                  | 262K    |       |           |       |       |       | $0.12      | $1          |
 | `hyper/qwen3.6-flash`                                | 1.0M    |       |           |       |       |       | $1         | $4          |

package/.docs/models/providers/minimax.md

@@ -106,4 +106,4 @@ yarn add @ai-sdk/anthropic
 bun add @ai-sdk/anthropic
 ```
 
-For detailed provider-specific documentation, see the [AI SDK MiniMax (minimax.io) provider docs](https://ai-sdk.dev/providers/community-providers/minimax).
+For detailed provider-specific documentation, see the [AI SDK MiniMax (minimax.io) provider docs](https://ai-sdk.dev/providers/ai-sdk-providers/minimax).

package/.docs/models/providers/openai.md

@@ -59,9 +59,9 @@ for await (const chunk of stream) {
 | `openai/gpt-5.5`                | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `openai/gpt-5.5-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `openai/gpt-5.6`                | 1.1M    |       |           |       |       |       | $5         | $30         |
-| `openai/gpt-5.6-luna`           | 1.1M    |       |           |       |       |       | $1         | $6          |
+| `openai/gpt-5.6-luna`           | 1.1M    |       |           |       |       |       | $0.20      | $1          |
 | `openai/gpt-5.6-sol`            | 1.1M    |       |           |       |       |       | $5         | $30         |
-| `openai/gpt-5.6-terra`          | 1.1M    |       |           |       |       |       | $3         | $15         |
+| `openai/gpt-5.6-terra`          | 1.1M    |       |           |       |       |       | $2         | $12         |
 | `openai/gpt-image-1-mini`       | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-1.5`          | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-2`            | —       |       |           |       |       |       | $5         | $30         |

package/.docs/models/providers/opencode-go.md

@@ -2,7 +2,7 @@
 
 # ![OpenCode Go logo](https://models.dev/logos/opencode-go.svg)OpenCode Go
 
-Access 22 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 23 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Go documentation](https://opencode.ai/docs/zen).
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
 | `opencode-go/deepseek-v4-pro`   | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `opencode-go/glm-5.1`           | 203K    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/glm-5.2`           | 1.0M    |       |           |       |       |       | $1         | $4          |
+| `opencode-go/gpt-5.6-luna`      | 1.1M    |       |           |       |       |       | $0.10      | $0.60       |
 | `opencode-go/grok-4.5`          | 500K    |       |           |       |       |       | $2         | $6          |
 | `opencode-go/hy3`               | 256K    |       |           |       |       |       | $0.14      | $0.58       |
 | `opencode-go/kimi-k2.6`         | 262K    |       |           |       |       |       | $0.95      | $4          |

package/.docs/models/providers/opencode.md

@@ -77,7 +77,7 @@ for await (const chunk of stream) {
 | `opencode/gpt-5.4-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `opencode/gpt-5.5`                | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `opencode/gpt-5.5-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
-| `opencode/gpt-5.6-luna`           | 1.1M    |       |           |       |       |       | $1         | $6          |
+| `opencode/gpt-5.6-luna`           | 1.1M    |       |           |       |       |       | $0.20      | $1          |
 | `opencode/gpt-5.6-sol`            | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `opencode/gpt-5.6-terra`          | 1.1M    |       |           |       |       |       | $3         | $15         |
 | `opencode/grok-4.5`               | 500K    |       |           |       |       |       | $2         | $6          |

package/.docs/models/providers/perplexity-agent.md

@@ -2,7 +2,7 @@
 
 # ![Perplexity Agent logo](https://models.dev/logos/perplexity-agent.svg)Perplexity Agent
 
-Access 18 Perplexity Agent models through Mastra's model router. Authentication is handled automatically using the `PERPLEXITY_API_KEY` environment variable.
+Access 20 Perplexity Agent models through Mastra's model router. Authentication is handled automatically using the `PERPLEXITY_API_KEY` environment variable.
 
 Learn more in the [Perplexity Agent documentation](https://docs.perplexity.ai/docs/agent-api/models).
 
@@ -46,6 +46,8 @@ for await (const chunk of stream) {
 | `perplexity-agent/google/gemini-2.5-pro`             | 1.0M    |       |           |       |       |       | $1         | $10         |
 | `perplexity-agent/google/gemini-3-flash-preview`     | 1.0M    |       |           |       |       |       | $0.50      | $3          |
 | `perplexity-agent/google/gemini-3.1-pro-preview`     | 1.0M    |       |           |       |       |       | $2         | $12         |
+| `perplexity-agent/moonshot-ai/kimi-k2.7-code`        | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `perplexity-agent/moonshot-ai/kimi-k3`               | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `perplexity-agent/nvidia/nemotron-3-super-120b-a12b` | 1.0M    |       |           |       |       |       | $0.25      | $3          |
 | `perplexity-agent/openai/gpt-5-mini`                 | 400K    |       |           |       |       |       | $0.25      | $2          |
 | `perplexity-agent/openai/gpt-5.1`                    | 400K    |       |           |       |       |       | $1         | $10         |

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

@@ -174,6 +174,17 @@ const { output, cleanup } = await durableAgent.observe(runId, {
 await output.text
 ```
 
+By default `observe()` waits indefinitely for events. If the process running the run stops unexpectedly, the run stops producing events but never emits a completion event, so the observed stream would wait forever. Pass `idleTimeoutMs` to bound that wait: after that many milliseconds of silence the stream ends. An optional `isAlive` check is consulted first. Return `true` while the run is still being worked on (for example a long-running tool call, or a run paused waiting for human input) to keep waiting. Returning `false`, or omitting `isAlive`, ends the stream with an error. A transient throw from `isAlive` is treated as "still alive", so a momentary check failure never ends a live stream.
+
+```typescript
+const { output } = await durableAgent.observe(runId, {
+  idleTimeoutMs: 30_000,
+  isAlive: () => runHeartbeat.isFresh(runId),
+})
+```
+
+Ending a run on idle timeout runs the same cleanup as a run that errors (see the warning below), so its cached state is released rather than retained. Both options are opt-in. Omit them for the previous wait-indefinitely behavior.
+
 Returns: `Promise<DurableAgentStreamResult>`
 
 > **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()`. Let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
@@ -333,7 +344,7 @@ Returns: [`Promise<DurableAgentStreamResult>`](#durableagentstreamresult)
 
 ## DurableAgentStreamResult
 
-The object returned by `stream()`, `resume()`, and `observe()`.
+The object returned by `stream()`, `resume()`, `observe()`, and `recover()`.
 
 ```typescript
 interface DurableAgentStreamResult<OUTPUT = undefined> {

package/.docs/reference/cli/mastra.md

@@ -171,7 +171,7 @@ Comma-separated list of custom arguments to pass to the Node.js process, e.g. `-
 
 ## `mastra worker build`
 
-Bundles your Mastra application for worker deployment. Produces the same output as `mastra build` — a self-contained `.mastra/output/` directory.
+Bundles your Mastra application for worker deployment. Produces the same output as `mastra build`: a self-contained `.mastra/output/` directory.
 
 ```bash
 mastra worker build [options]
@@ -179,29 +179,45 @@ mastra worker build [options]
 
 ### Flags
 
-| Flag                  | Description                                                  |
-| --------------------- | ------------------------------------------------------------ |
-| `--dir <path>`        | Path to your Mastra source directory (default: `src/mastra`) |
-| `--root <path>`       | Project root directory (default: current directory)          |
-| `--tools <paths>`     | Comma-separated tool paths to include                        |
-| `--output-dir <path>` | Custom output directory (default: `.mastra/output`)          |
-| `--debug`             | Enable debug logging                                         |
+#### `--dir`
+
+Path to your Mastra source directory. Defaults to `src/mastra`.
+
+#### `--root`
+
+Project root directory. Defaults to the current directory.
+
+#### `--tools`
+
+Comma-separated tool paths to include in the bundle.
+
+#### `--output-dir`
+
+Custom output directory. Defaults to `.mastra/output`.
+
+#### `--debug`
+
+Enable debug logging during the build.
 
 ## `mastra worker start`
 
 > **Info:** You need to run `mastra worker build` or `mastra build` before using `mastra worker start`.
 
-Starts a worker process from a previously built bundle.
+Starts a worker process from a previously built bundle. The optional `name` argument sets `MASTRA_WORKERS` in the spawned process, controlling which worker starts.
 
 ```bash
 mastra worker start [name] [options]
 ```
 
-| Argument/Flag  | Description                                                         |
-| -------------- | ------------------------------------------------------------------- |
-| `name`         | Worker name to start. Sets `MASTRA_WORKERS` in the spawned process. |
-| `--dir <path>` | Path to the build output (default: `.mastra/output`)                |
-| `--env <path>` | Path to environment file (default: `.env.production`, then `.env`)  |
+### Flags
+
+#### `--dir`
+
+Path to the build output directory. Defaults to `.mastra/output`.
+
+#### `--env`
+
+Path to the environment file. Defaults to `.env.production`, falling back to `.env`.
 
 ### Examples