@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 0.0.0-prerelease-streamfix-20260909094302

package/docs/reports.mdx

@@ -1,157 +0,0 @@
----
-title: "Project health report"
-sidebarTitle: "Health report"
-description: "Get a deterministic verdict on your project's health — split into Flow, Execution, and Liveness — from the CLI, an MCP tool or prompt, or the HTTP API."
----
-
-**The health report answers one question — "is my project healthy, and if not, is the problem my code or the platform?" — with a deterministic verdict, not a dashboard.** The server computes the verdict from your telemetry; no LLM interprets it, so the same numbers always produce the same answer.
-
-Every report reads a live window of your project's data and returns a headline verdict, the evidence behind it, and a single suggested next action. The only report today is `health`.
-
-## What the report measures
-
-The report splits a project into three dimensions, each with its own verdict:
-
-| Dimension | Question | What a bad verdict means |
-| --- | --- | --- |
-| **Flow** | Is work starting? | Runs are queuing but not being picked up — a concurrency limit, a throttle, or a trigger spike. |
-| **Execution** | Are the runs that start succeeding? | Runs are failing or slowing more than your baseline — usually your code. |
-| **Liveness** | Is the telemetry fresh? | The data behind the report is stale, so the verdict can't be trusted. |
-
-Splitting Flow from Execution is the point: a project can be failing to _start_ work (Flow) while every run that does start _completes_ fine (Execution), or the reverse. The report names which one, so you know whether to look at your concurrency settings or your task code.
-
-Each dimension carries a severity — healthy, degraded, or failing — and the report leads with the worst one as its headline. The headline finding is expanded with its supporting metrics; the others collapse to a one-line verdict.
-
-## Reading the report
-
-Here is `trigger report health` for a project whose runs are backing up against the environment concurrency limit:
-
-```text
-/report health        prod · last 1h · vs 7d normal
-
-✕ Flow stalled — at your env concurrency limit for the last 40 min
-
-  concurrency     100/100           ▄▅▆▇████   40 min at limit
-  pending         1,240      ↑ 6×   ▁▂▄▅▆▇██   (normal ~120)
-  start latency   p95 8.2s   ↑ 4×   ▁▂▃▄▆▇██   (normal ~2s)
-
-  why:  runs are finishing at ~90/min
-        nothing dead-lettered
-
-✓ EXECUTION   runs are executing normally
-
-✓ LIVENESS    fresh — telemetry current, updated 12s ago
-
-  read: limit saturated → incoming work exceeds capacity → backlog grows
-
-→ Raise the env concurrency limit
-  Read concurrency docs
-  or do nothing — backlog drains in ~26.7 min once triggers ease
-```
-
-The verdict reads top to bottom:
-
-- **Headline** — the worst finding, stated as a verdict with the breach window. Here Flow is stalled because concurrency has been pinned at its limit for 40 minutes.
-- **Evidence** — the metrics behind the headline, each with a sparkline over the window, its movement against your baseline (`↑ 6×` means six times normal), and an annotation (`40 min at limit`) or baseline (`normal ~120`).
-- **`why:`** — the facts that support the verdict, including what the problem _isn't_ (runs are still finishing, nothing is dead-lettered — so it's not your code).
-- **Sibling findings** — Execution and Liveness, each a one-line verdict.
-- **`read:`** — the causal chain in one line.
-- **Next steps** — the primary action first (`→`), then any alternatives.
-
-### The verdict vocabulary
-
-Every surface carries meaning in glyphs, never color alone, so the report is legible in a monochrome terminal or a plain-text MCP host:
-
-| Glyph | Meaning |
-| --- | --- |
-| `✓` | Healthy |
-| `⚠` | Degraded |
-| `✕` | Failing |
-| `○` | Genuinely unknown — neither good nor bad |
-| `⚑` | The data behind the report can't be trusted |
-| `↑` `↓` `→` | Above, below, or flat against the baseline |
-
-<Note>
-  The markdown surface swaps the status glyphs for traffic-light emoji (`🟢` `🟡` `🔴` `⚪` `🚩`) — the one color cue a chat host that renders neither ANSI nor HTML can show. The glyph and the emoji mean the same thing.
-</Note>
-
-## Surfaces
-
-The same report renders four ways.
-
-### CLI: `trigger report`
-
-Print an interpreted report for an environment. The command defaults to the `health` report and the `prod` environment — a manual production check.
-
-```bash
-npx trigger.dev@latest report health --env prod --period 24h
-```
-
-| Flag | Default | Description |
-| --- | --- | --- |
-| `[key]` | `health` | The report to render (positional argument). |
-| `-e, --env` | `prod` | The environment: `dev`, `staging`, `prod`, or `preview`. |
-| `-b, --branch` | — | The preview branch. Required when `--env preview`. |
-| `--period` | `1h` | The live window: `30m`, `1h`, `24h`, `7d`. Minutes to weeks, max 90 days. |
-| `-p, --project-ref` | from config | The project ref (`proj_…`). Required if there is no `trigger.config.ts`. |
-| `-c, --config` | — | Path to the config file. |
-
-The command prints only the report — no banner — so it pipes cleanly. Output is ANSI-colored in a real terminal and plain markdown when piped:
-
-```bash
-trigger report health > health.md   # markdown, no escape codes
-```
-
-Color follows the [supports-color](https://github.com/chalk/supports-color) convention: `NO_COLOR` (any value) or `FORCE_COLOR=0` disables color outright; `FORCE_COLOR` set to anything else force-enables it. Both win over TTY detection — which matters for agents spawned on a PTY, where `isTTY` is `true` but escape codes would be garbled.
-
-### MCP tool: `get_report`
-
-Fetch the report from an AI coding tool through the [Trigger.dev MCP server](/mcp-introduction). The tool returns plain markdown by default, or ANSI when `color` is set (for hosts that display escapes in tool output). It is read-only.
-
-| Parameter | Default | Description |
-| --- | --- | --- |
-| `key` | — | The report to render. Currently only `health`. |
-| `environment` | `dev` | The environment. The MCP server is dev-centric, so an unspecified environment reports on `dev` — pass `environment` explicitly to report on production. |
-| `period` | `1h` | Time window shorthand, e.g. `1h`, `24h`, `7d`. |
-| `color` | `false` | Return ANSI-colored text instead of markdown. |
-| `projectRef` | auto-detected | The project ref. Detected from `trigger.config.ts` if present. |
-| `branch` | — | The preview branch, for preview or branchable dev environments. |
-
-### MCP prompt: `/report`
-
-The MCP server also registers a `report` prompt, which hosts that support MCP prompts surface as a slash command (Claude Code renders it as `/mcp__trigger__report`). Running `/report health` calls `get_report` for you and shows the result verbatim in a fenced code block, preserving the monospace alignment and sparklines.
-
-### HTTP API: `GET /api/v1/reports/:key`
-
-The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with a token scoped to read the report's query tables (`read:query`).
-
-| Query param | Default | Description |
-| --- | --- | --- |
-| `period` | `1h` | The live window, same grammar as the CLI. |
-| `format` | `markdown` | `markdown`, `ansi`, or `json`. |
-
-`format=markdown` and `format=ansi` return the rendered text. `format=json` returns the `ReportViewModel` — the semantic payload behind the render, where verdicts are codes rather than prose, for building your own surface on top of the report.
-
-```bash
-curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \
-  -H "Authorization: Bearer $TRIGGER_ACCESS_TOKEN"
-```
-
-An unknown report key returns `404` with the list of available keys.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="MCP server" icon="plug" href="/mcp-introduction">
-    Connect your AI coding tool to Trigger.dev.
-  </Card>
-  <Card title="MCP tools" icon="wrench" href="/mcp-tools">
-    Every tool the MCP server exposes, including `get_report`.
-  </Card>
-  <Card title="Concurrency & queues" icon="layer-group" href="/queue-concurrency">
-    Configure the concurrency limits the Flow verdict checks against.
-  </Card>
-  <Card title="Query your data" icon="magnifying-glass" href="/observability/query">
-    Run TRQL queries against the same telemetry the report reads.
-  </Card>
-</CardGroup>

package/docs/troubleshooting-zod.mdx

@@ -1,158 +0,0 @@
----
-title: "Zod"
-description: "Resolve Zod typechecking, test, and deployment errors when upgrading to Trigger.dev v4.6."
----
-
-**Trigger.dev v4.6 uses Zod 4 by default. Zod 3.25.56 and later 3.x releases remain supported.**
-
-Use this guide if typechecking, tests, or deployment fail after upgrading. The supported project dependency range is `^3.25.56 || ^4.0.0`.
-
-| Your project's Zod dependency | What to do |
-| --- | --- |
-| No direct Zod dependency | No Zod-specific change is needed. Trigger.dev installs a compatible runtime dependency automatically. |
-| Zod below 3.25.56 | Upgrade before using Trigger.dev v4.6. These versions are unsupported. |
-| Zod 3.25.56 or later in the 3.x release line | Keep using your Zod 3 schemas with supported SDK APIs. Review the cross-major caveats below. |
-| Zod 4.x | Supported and the recommended default. |
-
-Passing your own supported Zod 3 schema to [`schemaTask`](/tasks/schemaTask) or `toolTask` remains supported. This does not make Zod 3 and Zod 4 schemas interchangeable when you compose or inspect them yourself.
-
-## Typechecking, tests, or deployment fail after upgrading
-
-An older Zod installation can be missing the entry points, types, or schema behavior that Trigger.dev v4.6 requires.
-
-Expect TypeScript errors when an unsupported version is resolved, particularly with `skipLibCheck: false`. Tests may also fail when they import or execute schemas. Deployment loads your task code, so an incompatible runtime installation causes deployment errors even if your local tooling skips typechecking. A passing local test suite does not establish that an unsupported version is safe to deploy.
-
-Symptoms include missing `zod/v4` or `zod/v4/core` exports, missing Zod types, incompatible generic parameters, and errors while loading tasks. The exact failure depends on the version and dependency tree; not every unsupported version fails at the same stage.
-
-### Check the installed version
-
-Inspect the resolved dependencies in the package that contains your tasks, not only the version range in `package.json`:
-
-<CodeGroup>
-```bash npm
-npm ls zod
-```
-
-```bash pnpm
-pnpm why zod
-```
-
-```bash bun
-bun pm ls --all
-```
-</CodeGroup>
-
-Check the lockfile and any dependency overrides or resolutions as well. An override can keep an old Zod version installed even after you update a direct dependency.
-
-### Update Zod
-
-Choose whether to move your application to Zod 4 or keep its existing Zod 3 schemas:
-
-<Tabs>
-  <Tab title="Move to Zod 4">
-    Install the latest Zod 4 release:
-
-    <CodeGroup>
-    ```bash npm
-    npm install zod@4
-    ```
-
-    ```bash pnpm
-    pnpm add zod@4
-    ```
-
-    ```bash bun
-    bun add zod@4
-    ```
-    </CodeGroup>
-
-    Review [Zod's migration guide](https://zod.dev/v4/changelog) for changes to your own schemas and error handling.
-  </Tab>
-  <Tab title="Stay on Zod 3">
-    Install the latest Zod 3 patch rather than pinning the minimum supported version:
-
-    <CodeGroup>
-    ```bash npm
-    npm install zod@3
-    ```
-
-    ```bash pnpm
-    pnpm add zod@3
-    ```
-
-    ```bash bun
-    bun add zod@3
-    ```
-    </CodeGroup>
-
-    Your existing `import { z } from "zod"` continues to use Zod 3. Trigger.dev's own schemas use the Zod 4 implementation included in the supported Zod 3 package.
-  </Tab>
-</Tabs>
-
-Other dependencies can require a higher minimum than Trigger.dev. For example, an AI SDK dependency may require Zod 3.25.76 or Zod 4. Meet those peer requirements too; do not force a lower version across every dependency.
-
-### Verify the update
-
-- Commit the updated manifest and lockfile, and make sure CI uses them.
-- Recheck the installed Zod versions in your local and deployment environments.
-- Run your project's TypeScript checks and tests, including code that constructs or inspects schemas.
-- Keep the CLI and SDK versions aligned using the [package upgrade guide](/upgrading-packages), then retry deployment.
-
-Do not use `skipLibCheck` or ignored peer-dependency warnings as a compatibility fix. They do not change the runtime package that deployment loads. You do not need to add Zod as a direct dependency if your application does not import it.
-
-## Parsing still fails with a supported Zod 3 version
-
-Supporting a Zod 3 schema as an SDK input is different from nesting a Trigger.dev-exported Zod 4 schema inside a Zod 3 object. Cross-major composition can fail during typechecking or parsing.
-
-For example, this mixes a Zod 3 object with a Zod 4 `RetryOptions` schema:
-
-```ts incompatible-schemas.ts
-import { z } from "zod"; // Project dependency is Zod 3.
-import { RetryOptions } from "@trigger.dev/core/v3";
-
-const schema = z.object({ retry: RetryOptions });
-schema.parse({ retry: {} });
-```
-
-Use Zod 4 for every schema in the composed object. The `zod/v4` entry point is available in both supported Zod 3 packages and Zod 4 packages:
-
-```ts compatible-schemas.ts
-import { z } from "zod/v4";
-import { RetryOptions } from "@trigger.dev/core/v3";
-
-const schema = z.object({ retry: RetryOptions });
-schema.parse({ retry: {} });
-```
-
-Alternatively, keep the Zod 3 and Trigger.dev schemas separate and call each schema's parser independently. You do not need to migrate unrelated application schemas to use this approach.
-
-## An `instanceof` check stops matching
-
-A Zod 4 error is not an instance of the Zod 3 `ZodError` constructor. A constructor check against your project's Zod 3 import can stop matching errors produced by Trigger.dev's schemas:
-
-```ts mismatched-error-check.ts
-import { z } from "zod"; // Project dependency is Zod 3.
-import { RetryOptions } from "@trigger.dev/core/v3";
-
-const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
-
-if (!result.success) {
-  console.log(result.error instanceof z.ZodError); // false
-}
-```
-
-Use the result returned by the schema you called instead of a constructor from another Zod installation:
-
-```ts schema-error-handling.ts
-import { RetryOptions } from "@trigger.dev/core/v3";
-
-const result = RetryOptions.safeParse({ maxAttempts: "invalid" });
-
-if (!result.success) {
-  console.error(result.error.issues);
-}
-```
-
-The same caveat applies to checks such as `schema instanceof z.ZodObject`. Multiple installed copies can also have different constructors, even within the same major version. Prefer parsing and the returned validation result over inspecting classes or private fields such as `_def`.
-
-These examples are not an exhaustive list of cross-major differences. If errors remain after updating, check which Zod implementation creates each schema and which code composes, parses, or inspects it.