@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/skills/trigger-chat-agent-advanced/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: trigger-chat-agent-advanced
+description: >
+  Advanced and operational chat.agent capabilities for Trigger.dev, loaded on demand. Load this when
+  working on the raw Sessions primitive (sessions / SessionHandle), a custom chat transport or the
+  realtime wire protocol, durable sub-agents (AgentChat, chat.stream.writer), human-in-the-loop,
+  steering, actions, background injection (chat.defer / chat.inject), fast starts (preload, Head
+  Start via @trigger.dev/sdk/chat-server), context resilience (compaction, recovery boot, OOM, large
+  payloads), chat.local run-scoped state, offline testing with mockChatAgent, or prerelease/version
+  upgrades. For the everyday chat.agent({...}) definition and the useTriggerChatTransport happy path,
+  use the trigger-authoring-chat-agent skill instead.
+type: core
+library: trigger.dev
+sources:
+  - docs/ai-chat/sessions.mdx
+  - docs/ai-chat/server-chat.mdx
+  - docs/ai-chat/client-protocol.mdx
+  - docs/ai-chat/pending-messages.mdx
+  - docs/ai-chat/actions.mdx
+  - docs/ai-chat/background-injection.mdx
+  - docs/ai-chat/compaction.mdx
+  - docs/ai-chat/fast-starts.mdx
+  - docs/ai-chat/chat-local.mdx
+  - docs/ai-chat/mcp.mdx
+  - docs/ai-chat/testing.mdx
+  - docs/ai-chat/upgrade-guide.mdx
+  - docs/ai-chat/patterns/sub-agents.mdx
+  - docs/ai-chat/patterns/human-in-the-loop.mdx
+  - docs/ai-chat/patterns/persistence-and-replay.mdx
+  - docs/ai-chat/patterns/recovery-boot.mdx
+  - docs/ai-chat/patterns/oom-resilience.mdx
+  - docs/ai-chat/patterns/large-payloads.mdx
+  - docs/ai-chat/patterns/version-upgrades.mdx
+  - docs/ai-chat/tools.mdx
+---
+
+# chat.agent: advanced and operational
+
+`chat.agent` is built on **Sessions**: a durable, task-bound, bi-directional I/O channel pair keyed
+on a stable `externalId` (e.g. `chatId`) that outlives any single run. This skill covers the layers
+beneath and around the everyday agent: the raw `sessions` API, server-side `AgentChat`, durable
+sub-agents, actions / background injection, fast starts, compaction and recovery, and the wire
+protocol for custom transports.
+
+Two `chat` namespaces are easy to confuse: the agent definition imports `chat` from
+`@trigger.dev/sdk/ai`; Head Start / Node-listener server entries import `chat` from
+`@trigger.dev/sdk/chat-server`.
+
+## Setup
+
+Happy path: drive an agent from server-side code (task, webhook, or script) with `AgentChat`.
+
+```ts
+import { AgentChat } from "@trigger.dev/sdk/chat";
+import type { myAgent } from "./trigger/my-agent";
+
+const chat = new AgentChat<typeof myAgent>({ agent: "my-chat", clientData: { userId: "user_123" } });
+const stream = await chat.sendMessage("Review PR #42");
+const text = await stream.text();
+await chat.close();
+```
+
+`sendMessage()` triggers a run on the first call, then reuses it via input streams. `ChatStream`
+exposes `text()`, `result()` (`{ text, toolCalls, toolResults }`), `messages()` (UIMessage
+snapshots), and the raw `.stream`. Other methods: `steer(text)`, `stop()`, `sendRaw(uiMessages)`,
+`sendAction(action)`, `preload()`, `reconnect()`.
+
+## Core patterns
+
+### 1. Raw Sessions for non-chat, bi-directional I/O
+
+Reach for `sessions` directly when the chat abstraction does not fit: agent inboxes, approval flows,
+server-to-server pipelines. `sessions.start` is idempotent on `(env, externalId)`; `externalId`
+cannot start with `session_`.
+
+```ts
+import { sessions } from "@trigger.dev/sdk";
+
+const { id, publicAccessToken } = await sessions.start({
+  type: "chat.agent",
+  externalId: chatId,
+  taskIdentifier: "my-chat",
+  triggerConfig: { tags: [`chat:${chatId}`], basePayload: { chatId, trigger: "preload" } },
+});
+
+const session = sessions.open(chatId); // no network call; methods are lazy
+await session.out.append({ kind: "message", text: "hello" });
+const next = await session.in.once<MyEvent>({ timeoutMs: 30_000 });
+```
+
+`sessions.open(id).in` also has `send`, `on(handler)`, `peek`, `wait` (suspends the run, only inside
+`task.run()`), and `waitWithIdleTimeout`. `.out` has `append`, `pipe`, `writer`, `read`,
+`writeControl`, and `trimTo`. List with `sessions.list({ type, tag, status, ... })` (`for await`),
+mutate with `sessions.update`, end with `sessions.close` (terminal, idempotent).
+
+### 2. Durable sub-agent as a streaming tool
+
+`AgentChat` inside an AI SDK `tool()` delegates to a durable sub-agent; its response streams as
+preliminary tool results. Give the tool a `toModelOutput` so the model sees a compact summary.
+
+```ts
+import { tool } from "ai";
+import { AgentChat } from "@trigger.dev/sdk/chat";
+import { z } from "zod";
+
+const researchTool = tool({
+  description: "Delegate research to a specialist agent.",
+  inputSchema: z.object({ topic: z.string() }),
+  execute: async function* ({ topic }, { abortSignal }) {
+    const chat = new AgentChat({ agent: "research-agent" });
+    const stream = await chat.sendMessage(topic, { abortSignal });
+    yield* stream.messages(); // UIMessage snapshots become preliminary tool results
+    await chat.close();
+  },
+  toModelOutput: ({ output: message }) => {
+    const lastText = message?.parts?.findLast((p: { type: string }) => p.type === "text") as
+      | { text?: string }
+      | undefined;
+    return { type: "text", value: lastText?.text ?? "Done." };
+  },
+});
+```
+
+For a subtask exposed via `execute: ai.toolExecute(task)`, stream progress to the agent's run with
+`chat.stream.writer({ target: "root" })`. `target` accepts `"self" | "parent" | "root" | <runId>`.
+Inside the subtask, read context with `ai.toolCallId()` and `ai.chatContextOrThrow<typeof myChat>()`
+(`{ chatId, turn, continuation, clientData }`).
+
+```ts
+import { chat, ai } from "@trigger.dev/sdk/ai";
+
+const { waitUntilComplete } = chat.stream.writer({
+  target: "root",
+  execute: ({ write }) =>
+    write({ type: "data-research-status", id: partId, data: { query, status: "in-progress" } }),
+});
+await waitUntilComplete();
+```
+
+### 3. Background injection: defer + inject
+
+`chat.defer(promise)` runs work in parallel with streaming (all deferred promises are awaited, with a
+5s timeout, before `onTurnComplete`). `chat.inject(messages)` queues `ModelMessage[]` that drain at
+the next turn start or `prepareStep` boundary.
+
+Two lanes, decided by role. A `role: "system"` message goes to the model's instructions, where it is
+trusted like the system prompt, and applies to the next turn only. Any other role joins the
+conversation and is untrusted by construction, so put checkable facts there and directives in the
+system lane. The instructions lane reaches the model only through the managed `streamText` (or a
+`chat.toStreamTextOptions()` spread), since that is where the SDK can set instructions.
+
+```ts
+export const myChat = chat.agent({
+  id: "my-chat",
+  onTurnComplete: async ({ messages }) => {
+    chat.defer(
+      (async () => {
+        const analysis = await analyzeConversation(messages);
+        chat.inject([{ role: "system", content: `[Analysis]\n\n${analysis}` }]);
+      })()
+    );
+  },
+  registry,
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ messages, abortSignal: signal, stopWhen: stepCountIs(15) }),
+});
+```
+
+### 4. Compaction (threshold-based)
+
+`compaction.shouldCompact` decides when, `summarize` produces the summary that replaces the model
+messages. UI messages are preserved by default (customize via `compactUIMessages`). The `prepareStep`
+that performs inner-loop compaction rides the managed `streamText`, which composes a `prepareStep`
+you pass after it. Spreading `chat.toStreamTextOptions()` and then passing your own replaces it,
+switching compaction off.
+
+```ts
+compaction: {
+  shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
+  summarize: async ({ messages }) =>
+    (await generateText({
+      model: anthropic("claude-haiku-4-5"),
+      messages: [...messages, { role: "user", content: "Summarize concisely." }],
+    })).text,
+},
+```
+
+### 5. Actions: edit state, and optionally answer
+
+`actionSchema` validates; `onAction` edits via `chat.history` (`slice`, `replace`, `rollbackTo`,
+`remove`, `getPendingToolCalls`, `extractNewToolResults`). An action fires `hydrateMessages` and
+`onAction` only. Return nothing for an edit-only action: no model call, and the turn counter does not
+advance. Return `chat.turn()` to answer after the edit: a turn runs on the edited history with
+everything a turn has (the agent's system prompt and tools, steering, compaction, injected
+instructions, `onTurnStart` and `onTurnComplete`, persistence), and `run()` receives it with
+`trigger: "action-turn"`. `onAction` has no `streamText` argument, and returning a
+`StreamTextResult`, string or `UIMessage` from it throws.
+
+Persistence splits by model. With transcript storage (`storage` on `chat.agent`; the platform
+snapshot by default), the runtime hands storage a changeset with `reason: "action"` after an action
+that changed the conversation: an undo is one `truncateAfter`, a regenerate is a `truncateAfter`
+followed by the new answer's `put` when the turn completes, and an edit is a `put` for the edited
+id. With the deprecated `hydrateMessages` your store is the source of truth and the runtime does
+not write, so mirror every mutation yourself: a regenerate is a delete and an insert, and the
+answer that follows `chat.turn()` arrives through `onTurnComplete` like any turn's answer.
+
+```ts
+export const myChat = chat.agent({
+  id: "my-chat",
+  actionSchema: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("undo") }),
+    z.object({ type: z.literal("regenerate") }),
+    z.object({ type: z.literal("rollback"), targetMessageId: z.string() }),
+  ]),
+  onAction: async ({ action }) => {
+    if (action.type === "undo") chat.history.slice(0, -2); // edit only
+    if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
+    if (action.type === "regenerate") {
+      chat.history.slice(0, -1);
+      return chat.turn(); // answer the edited history
+    }
+  },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+Send from the browser through `useChat`, so the answer a turn produces renders like any turn:
+`sendMessage(undefined, { body: { action: { type: "regenerate" } } })`, `regenerate({ body: { action } })`,
+or `useChatActions({ sendMessage })` from `@trigger.dev/sdk/chat/react`. For regeneration, use
+`regenerate()` from `useChat` (Vercel AI SDK) which removes the last assistant message before
+streaming the new one; calling `sendMessage` with a regenerate action appends without removal,
+leaving both answers visible. `transport.sendAction(chatId, action)` returns a raw stream the
+caller must read and apply itself. Server-side, use
+`agentChat.sendAction({ type: "rollback", targetMessageId: "msg-3" })`.
+
+### 6. Fast starts: Head Start
+
+`chat.headStart` (from `@trigger.dev/sdk/chat-server`, NOT `/ai`) returns a Web Fetch handler that
+serves turn 1 from your own warm process, then hands off to the agent on turn 2+. Tools passed here
+must be **schema-only** (a module importing `ai` + `zod` only); heavy executes stay in the task.
+
+```ts
+import { chat } from "@trigger.dev/sdk/chat-server";
+import { anthropic } from "@ai-sdk/anthropic";
+import { headStartTools } from "@/lib/chat-tools/schemas";
+
+export const chatHandler = chat.headStart({
+  agentId: "my-chat",
+  // `streamText` from the run argument owns `messages`, `prompt`, `stopWhen`
+  // and `abortSignal`: the handover needs `stopWhen: stepCountIs(1)` so the agent,
+  // not this handler, runs step 2 onward. Passing any of them is a type error.
+  run: async ({ streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-6"),
+      system: "You are helpful.",
+      tools: headStartTools,
+    }),
+});
+// Next.js: export const POST = chatHandler;  Transport: headStart: "/api/chat"
+```
+
+Node-only frameworks wrap a Web Fetch handler with `chat.toNodeListener(handler)`. Use the **same
+model** on both sides to avoid a tone shift between turn 1 and turn 2+.
+
+### 7. chat.local: init in onBoot, not onChatStart
+
+`chat.local<T>({ id })` is module-level, shallow-proxy, run-scoped state. Initialize it in `onBoot`
+(fires on every fresh worker, including continuation runs), never `onChatStart`.
+
+```ts
+const userContext = chat.local<{ name: string; plan: "free" | "pro" }>({ id: "userContext" });
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  onBoot: async ({ clientData }) => userContext.init({ name: "Alice", plan: "pro" }),
+  run: async ({ messages, signal }) => streamText({ /* ... */ }),
+});
+```
+
+### 8. Pending messages (mid-stream user input)
+
+A message sent while a turn is streaming should NOT cancel the stream. Configure
+`pendingMessages` (`shouldInject`, `prepare`, `onReceived`, `onInjected`) on the agent so the managed
+`streamText`'s `prepareStep` folds them in at the next boundary. An injected steering message is part
+of the conversation your hooks see, so it arrives in `uiMessages` and `newUIMessages` at
+`onTurnComplete` and an app persisting from there stores it without extra work. On the frontend, `usePendingMessages`
+returns `pending`, `steer(text)`, `queue(text)`, and `promoteToSteering(id)`; send via
+`transport.sendPendingMessage(chatId, uiMessage, metadata?)`.
+
+### 9. Recovery and version upgrades
+
+`onRecoveryBoot` fires only when a **partial assistant message exists on the tail** (interrupted
+deploy, crash, OOM retry). It does NOT fire on `chat.requestUpgrade()`, which is a graceful exit with
+no partial. `chat.requestUpgrade()` (called in `onTurnStart` / `onValidateMessages` to skip `run()`,
+or in `run()` / `chat.defer()` to exit after the turn) rotates the Session's `currentRunId` to a run
+on the latest deployment without a client reconnect. Pair it with a contract version on `clientData`.
+
+```ts
+const SUPPORTED_VERSIONS = new Set(["v2", "v3"]);
+onTurnStart: async ({ clientData }) => {
+  if (clientData?.protocolVersion && !SUPPORTED_VERSIONS.has(clientData.protocolVersion)) {
+    chat.requestUpgrade();
+  }
+},
+```
+
+For OOM resilience, set `oomMachine` (and `machine`) on the agent so retries land on a larger preset.
+
+### 10. Offline testing with mockChatAgent
+
+`@trigger.dev/sdk/ai/test` runs the real turn loop in-memory. Import it **before** the agent module
+so the resource catalog is installed. Drive with `sendMessage`, `sendRegenerate`, `sendAction`,
+`sendStop`, `sendHeadStart`, `sendHandover`; seed state with `seedSnapshot` / `seedSessionOutTail` /
+`seedSessionOutPartial` / `seedSessionInTail`; assert against `turn.chunks` and `harness.allChunks`.
+
+```ts
+import { mockChatAgent } from "@trigger.dev/sdk/ai/test"; // BEFORE the agent module
+import { myChatAgent } from "./my-chat.js";
+
+const harness = mockChatAgent(myChatAgent, { chatId: "test-1", clientData: { model } });
+try {
+  const turn = await harness.sendMessage({ id: "u1", role: "user", parts: [{ type: "text", text: "hi" }] });
+  // assert against turn.chunks
+} finally {
+  await harness.close();
+}
+```
+
+Options include `mode` (`"preload" | "submit-message" | "handover-prepare" | "continuation"`),
+`preload`, `continuation`, `previousRunId`, `snapshot`, `taskContext`, and `setupLocals`. Set
+`taskContext.ctx.attempt.number > 1` to simulate an OOM-retry attempt. `runInMockTaskContext` drives a
+non-chat task offline.
+
+### 11. Custom transport: the wire protocol
+
+Endpoints: `POST /api/v1/sessions` (create), `GET /realtime/v1/sessions/{id}/out` (SSE),
+`POST /realtime/v1/sessions/{id}/in/append`, `POST /api/v1/sessions/{id}/close`. `ChatInputChunk` is
+`{ kind: "message"; payload: ChatTaskWirePayload } | { kind: "stop"; message? }`. The
+`ChatTaskWirePayload` carries `chatId`, `trigger` (`submit-message | regenerate-message | preload |
+close | action | handover-prepare`), `message?`, `metadata?`, `action?`, `continuation?`,
+`previousRunId?`, and more. Control records are header-form: `trigger-control: turn-complete` (with
+optional `public-access-token`, `session-in-event-id`) and `trigger-control: upgrade-required`. The
+TS helpers `SSEStreamSubscription` and `controlSubtype(headers)` (documented in
+`docs/ai-chat/client-protocol.mdx`) handle batch decoding and control-record filtering for you.
+
+## Common mistakes
+
+- **CRITICAL: sending a follow-up by re-POSTing `POST /api/v1/sessions`.**
+  ```ts
+  // Wrong - a cached re-POST silently drops basePayload.message; basePayload is trigger config, not a channel
+  await fetch("/api/v1/sessions", { method: "POST", body: JSON.stringify({ ...createBody }) });
+  // Correct - append to the session's input channel
+  await fetch(`/realtime/v1/sessions/${id}/in/append`, { method: "POST", body: JSON.stringify({ kind: "message", payload }) });
+  ```
+
+- **Using the wrong token for `.in` / `.out`.** Use `publicAccessToken` from the create response
+  body (session-scoped). The `x-trigger-jwt` response header is run-scoped and cannot subscribe.
+
+- **Initializing `chat.local` in `onChatStart`.** It is skipped on continuation runs, so `run()`
+  crashes with `chat.local can only be modified after initialization`. Init in `onBoot`.
+
+- **`chat.defer` for the message-history write.** A mid-stream refresh would read `[]`. `await` that
+  write inline before the model streams; reserve `chat.defer` for analytics, audit, cache warming.
+
+- **Giving the HITL tool an `execute`.** `streamText` calls it immediately. Leave it execute-less;
+  the frontend supplies the answer via `addToolOutput` + `sendAutomaticallyWhen`.
+
+- **Declaring sub-agent / heavy tools only on `streamText`.** Also declare them on
+  `chat.agent({ tools })` (or pass to `convertToModelMessages(uiMessages, { tools })` in a custom
+  agent) so `toModelOutput` re-applies on every turn.
+
+- **Importing heavy-execute tools into the Head Start route module.** This is a build-time import
+  chain problem; runtime strip helpers do not fix it. Keep schemas in an `ai` + `zod`-only module.
+
+- **Returning a megabyte tool output on the stream.** One `tool-output-available` record over ~1 MiB
+  throws `ChatChunkTooLargeError`. Persist to your store, write the row first, then emit only an id.
+
+- **Setting `X-Peek-Settled: 1` on the active-send path.** It races the new turn's first chunk and
+  closes the stream early. Use it only on reconnect-on-reload paths.
+
+> Note on docs vocabulary: agent-side examples in some docs still use the legacy
+> `trigger:turn-complete` chunk type. That is the agent-emit vocabulary. A custom **reader** must
+> filter on the `trigger-control` header, not on `chunk.type`.
+>
+> MCP-driven agent chats (`list_agents`, `start_agent_chat`, `send_agent_message`,
+> `close_agent_chat`) are MCP server tools used from Claude Code / Cursor, not importable SDK
+> functions. See `/mcp-tools#agent-chat-tools`.
+
+## References
+
+- `trigger-authoring-chat-agent` skill - the everyday `chat.agent({...})` definition, lifecycle hooks, and
+  the `useTriggerChatTransport` happy path. Start there before reaching for this skill.
+- `trigger-realtime-and-frontend` skill - Realtime hooks and frontend streaming beyond the chat transport.
+- `trigger-authoring-tasks` skill - base `task()` semantics, `ctx`, and standard lifecycle hooks.
+
+Reference docs ship beside this skill in the same package, read them locally (no network), pinned to your installed version. The `sources:` frontmatter above lists every doc this skill draws from, all under `@trigger.dev/sdk/docs/ai-chat/` (including `patterns/`). For HITL, sessions, and sub-agents start with `sessions.mdx`, `server-chat.mdx`, `client-protocol.mdx`, `patterns/human-in-the-loop.mdx`, `patterns/sub-agents.mdx`.
+
+For `trigger.config.ts` and build extensions a chat-agent task may need (Prisma, Playwright, Python, etc.), read the bundled config docs under `@trigger.dev/sdk/docs/config/` (`config/extensions/` for the per-extension setup).
+
+## Version
+
+This skill is bundled inside `@trigger.dev/sdk` and read directly from `node_modules`, so it always matches your installed SDK version (see the adjacent `package.json`). The full documentation for these APIs ships alongside it under `@trigger.dev/sdk/docs/`.

package/skills/trigger-cost-savings/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: trigger-cost-savings
+description: >
+  Analyze Trigger.dev tasks, schedules, and runs for cost optimization opportunities. Use when
+  asked to reduce spend, optimize costs, audit usage, right-size machines, or review task
+  efficiency. Combines static source analysis with live run analysis via the Trigger.dev MCP
+  tools (list_runs, get_run_details, get_current_worker).
+type: core
+library: trigger.dev
+sources:
+  - docs/how-to-reduce-your-spend.mdx
+  - docs/machines.mdx
+  - docs/runs/max-duration.mdx
+  - docs/queue-concurrency.mdx
+  - docs/idempotency.mdx
+  - docs/triggering.mdx
+  - docs/errors-retrying.mdx
+  - docs/limits.mdx
+---
+
+# Trigger.dev Cost Savings Analysis
+
+Analyze task runs and configurations to find cost reduction opportunities. This skill pairs static source analysis with live run analysis via the Trigger.dev MCP server.
+
+## Before you start: read the canonical guidance
+
+The authoritative, version-pinned cost guidance ships beside this skill. Read it first so your recommendations match the installed SDK version:
+
+- `@trigger.dev/sdk/docs/how-to-reduce-your-spend.mdx` — the canonical "reduce your spend" guide (machine sizing, idempotency de-dup, parallelism, retries, `maxDuration`, checkpointed waits, debounce).
+- Supporting references: `@trigger.dev/sdk/docs/machines.mdx`, `runs/max-duration.mdx`, `queue-concurrency.mdx`, `idempotency.mdx`, `triggering.mdx` (debounce + batch), `errors-retrying.mdx` (`AbortTaskRunError`).
+
+## Prerequisites: MCP tools
+
+Live run analysis needs the **Trigger.dev MCP server**. Verify these tools are available:
+
+- `list_runs` — list runs with filters (status, task, time period, machine size)
+- `get_run_details` — get run logs, duration, and status
+- `get_current_worker` — get registered tasks and their configurations
+
+If they're not available, tell the user to install the MCP server:
+
+```bash
+npx trigger.dev@latest install-mcp
+```
+
+Without the MCP tools you can still do the static source analysis below; do not fabricate run data.
+
+## Analysis workflow
+
+### Step 1: Static analysis (source code)
+
+Scan task files for:
+
+1. **Oversized machines** — tasks on `large-1x`/`large-2x` without clear need.
+2. **Missing `maxDuration`** — no execution-time limit (runaway-cost risk).
+3. **Excessive retries** — `maxAttempts` > 5 without `AbortTaskRunError` for known-permanent failures.
+4. **Missing debounce** — high-frequency triggers without debounce.
+5. **Missing idempotency** — payment/critical tasks without idempotency keys.
+6. **Polling instead of waits** — `setTimeout`/`setInterval`/sleep loops instead of `wait.for()`.
+7. **Short waits** — `wait.for()` under 5 seconds (not checkpointed, wastes compute).
+8. **Sequential instead of batch** — multiple `triggerAndWait()` calls that could be `batchTriggerAndWait()`.
+9. **Over-scheduled crons** — schedules firing more often than needed.
+
+### Step 2: Run analysis (requires MCP tools)
+
+- **2a. Expensive tasks** — `list_runs` over `period: "30d"`/`"7d"`; find high total compute (duration × count), high failure rates, and large machines with short durations (over-provisioned).
+- **2b. Failure patterns** — `list_runs` with `status: "FAILED"`/`"CRASHED"`; separate transient (retryable) from permanent; suggest `AbortTaskRunError` for the latter; estimate wasted retry compute.
+- **2c. Machine utilization** — `get_run_details` on sample runs; if a `large-2x` task consistently runs in under a second, or is I/O-bound (API/DB), it's over-provisioned.
+- **2d. Schedule frequency** — `get_current_worker` to list cron patterns; flag schedules that are too frequent for their purpose.
+
+### Step 3: Generate recommendations
+
+Present a prioritized report with estimated impact:
+
+```markdown
+## Cost Optimization Report
+
+### High impact
+1. **Right-size `process-images`** — currently `large-2x`, average run 2s. `small-2x` could cut this task's cost by ~16x.
+   `machine: { preset: "small-2x" }`  // was "large-2x"
+
+### Medium impact
+2. **Debounce `sync-user-data`** — 847 runs/day, often bursty.
+   `debounce: { key: \`user-${userId}\`, delay: "5s" }`
+
+### Low impact / best practice
+3. **Add `maxDuration` to `generate-report`** — no timeout configured.
+   `maxDuration: 300`  // 5 minutes
+```
+
+## Machine preset costs (relative)
+
+Larger machines cost proportionally more per second of compute:
+
+| Preset | vCPU | RAM | Relative cost |
+|--------|------|-----|---------------|
+| micro | 0.25 | 0.25 GB | 0.25x |
+| small-1x | 0.5 | 0.5 GB | 1x (baseline) |
+| small-2x | 1 | 1 GB | 2x |
+| medium-1x | 1 | 2 GB | 2x |
+| medium-2x | 2 | 4 GB | 4x |
+| large-1x | 4 | 8 GB | 8x |
+| large-2x | 8 | 16 GB | 16x |
+
+## Key principles
+
+- **Waits > 5 seconds are free** — checkpointed, no compute charge.
+- **Start small, scale up** — the default `small-1x` is right for most tasks.
+- **I/O-bound tasks don't need big machines** — API calls and DB queries wait on the network.
+- **Debounce saves the most on high-frequency tasks** — it consolidates bursts into single runs.
+- **Idempotency prevents duplicate billed work** — especially for expensive operations.
+- **`AbortTaskRunError` stops wasteful retries** — don't pay to retry permanent failures.
+
+## Version
+
+This skill is bundled inside `@trigger.dev/sdk` and read directly from `node_modules`, so it always matches your installed SDK version (see the adjacent `package.json`). The full cost documentation ships alongside it under `@trigger.dev/sdk/docs/`.