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

package/docs/ai-chat/patterns/recovery-boot.mdx

@@ -0,0 +1,233 @@
+---
+title: "Recovery boot"
+sidebarTitle: "Recovery boot"
+description: "Recover from cancel-mid-stream, crashes, and OOM kills with full conversational context. The smart default Just Works; the onRecoveryBoot hook is the override path for advanced policies."
+---
+
+When a `chat.agent` run dies in the middle of streaming a response — the user cancels, the worker OOMs, or an unhandled exception kills the process — the durable streams hold what was in flight. The next run boots as a continuation, reads both stream tails, and reconstructs a chain that preserves the partial response so any follow-up (`keep going`, `actually do X instead`, a new question) has full context.
+
+The behavior is automatic. The `onRecoveryBoot` hook is opt-in for policies that need something different.
+
+## The scenario
+
+```ts
+// Turn 1 is mid-essay when the user clicks Cancel.
+window.__chat.send("Write me a long essay about espresso");
+// ... assistant has written 3000 characters ...
+window.__chat.stop();                              // OR: server-side cancel_run
+
+// User decides what they want next.
+window.__chat.send("keep going");                  // OR: "what's 7+8?", or anything
+```
+
+The cancelled run never wrote `onTurnComplete`. The snapshot is stale or absent. `session.out` has a half-written assistant message. `session.in` has the original user message (the run consumed it but never marked the turn complete) plus the new follow-up.
+
+A naive continuation would either re-run the cancelled essay (the user already chose to stop) or drop everything (no context for the follow-up). Recovery boot handles this without either failure mode.
+
+## The smart default
+
+On a continuation boot, the runtime reads:
+
+- **Snapshot** — settled turns persisted by the last successful `onTurnComplete`.
+- **`session.out` tail past the snapshot cursor** — closed assistant turns plus, optionally, a `partialAssistant` (the trailing message whose stream never received a `finish` chunk). `cleanupAbortedParts` has already stripped streaming-in-progress fragments.
+- **`session.in` tail past the last `turn-complete` cursor** — user messages the dead run hadn't acknowledged.
+
+If there's a `partialAssistant` and two or more `inFlightUsers`, the runtime splices `[firstInFlightUser, partialAssistant]` onto the chain. The remaining in-flight users dispatch as fresh turns. The model sees:
+
+```
+[ ...settledMessages,  // chain through the last completed turn
+  firstInFlightUser,   // the question the dead run was answering
+  partialAssistant,    // the dead run's incomplete response
+  followUpUser ]       // the new turn the customer just sent
+```
+
+Modern instruction-following models prioritize the latest user message. The follow-up determines the response:
+
+| Follow-up | Model behavior |
+|---|---|
+| "keep going" / "continue" / "more" | Continues the partial essay from where it stopped. |
+| "actually, what's 7+8?" | Answers the new question. Prior context doesn't derail it. |
+| "scrap that, do something else" | Abandons the partial work and follows the new direction. |
+
+No customer code needed for any of these.
+
+## When to register `onRecoveryBoot`
+
+The hook fires when recovery state is non-empty (either `partialAssistant` is defined or there's at least one in-flight user). Register it when you need a policy different from "preserve context":
+
+- **Drop the partial entirely.** Your UX means "cancel discards the work — start fresh from the follow-up."
+- **Synthesize tool results.** The partial has tool calls in `input-available` state (HITL was mid-call when the run died). Return a chain that has fabricated `output-available` results so the model can continue.
+- **Emit a recovery banner.** Write a `data-chat-recovery` UIMessage chunk via `ctx.writer` so the frontend can render "Recovering interrupted response..." before the model speaks.
+- **Persist recovered state.** Use `beforeBoot` to flush the partial to your own database before the next turn starts.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  onRecoveryBoot: async ({ partialAssistant, inFlightUsers, writer, cause, previousRunId }) => {
+    writer.write({
+      type: "data-chat-recovery",
+      data: { cause, previousRunId, partialPresent: partialAssistant !== undefined },
+      transient: true,
+    });
+    // Return nothing → fall through to smart default.
+  },
+  run: async ({ messages, signal }) =>
+    streamText({ model, messages, abortSignal: signal }),
+});
+```
+
+## Hook reference
+
+### Fires when
+
+The hook fires once on a continuation boot, AFTER both stream tails have been read, AND only when there's a partial assistant — the mid-stream-died signal:
+
+```ts
+const shouldFire = partialAssistant !== undefined;
+```
+
+In-flight users alone don't fire the hook. Graceful exits like `chat.requestUpgrade()` and `chat.endRun()` may leave an unacknowledged user on `session.in` (the message that triggered the upgrade, the next message after endRun), but no partial — that's a normal continuation, not recovery. The next message just dispatches as turn 1 on the new run via the normal session.in pump.
+
+Skipped scenarios (where the hook does NOT fire):
+
+- A clean continuation after `chat.endRun()` with no buffered follow-up.
+- A fresh chat (no continuation, attempt 1).
+- An OOM retry that booted onto a complete snapshot (no partial on the tail).
+- `chat.requestUpgrade()` graceful exit — predecessor ended cleanly before processing, no partial.
+- An agent with [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) registered. Customers using `hydrateMessages` own persistence — recovery decisions live in their own DB query.
+
+### Event shape
+
+```ts
+type RecoveryBootEvent<TUIM extends UIMessage = UIMessage> = {
+  ctx: TaskRunContext;
+  chatId: string;
+  runId: string;
+  previousRunId: string;
+  cause: "cancelled" | "crashed" | "unknown";
+  settledMessages: TUIM[];
+  inFlightUsers: TUIM[];
+  partialAssistant: TUIM | undefined;
+  pendingToolCalls: Array<{
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    partIndex: number;
+  }>;
+  writer: ChatWriter;
+};
+```
+
+<Note>
+  `cause` is currently always `"unknown"` — the run engine doesn't yet plumb the
+  real reason into the continuation payload. The enum is forward-looking; don't
+  branch behavior on it for now.
+</Note>
+
+### Return shape
+
+Every field is optional. Returning `undefined` (or nothing) accepts the smart default for every field.
+
+```ts
+type RecoveryBootResult<TUIM extends UIMessage = UIMessage> = {
+  chain?: TUIM[];
+  recoveredTurns?: TUIM[];
+  beforeBoot?: () => Promise<void>;
+};
+```
+
+- **`chain`** — replaces the seed chain. Defaults to `[...settledMessages, firstInFlightUser, partialAssistant]` when there's a partial **and two or more** in-flight users, otherwise `settledMessages` alone.
+- **`recoveredTurns`** — user messages to dispatch as fresh turns after the chain is restored. Defaults to `inFlightUsers.slice(1)` when the smart default consumed the first user, otherwise `inFlightUsers`.
+- **`beforeBoot`** — runs after the writer flushes and before the first recovered turn fires. Use for blocking persistence (write the partial to your DB so a later turn can reference it). Errors bubble — wrap your own try/catch if you want to soft-fail.
+
+<Note>
+  The splice needs a follow-up user to answer, so it only applies with two or
+  more in-flight users. With exactly one — the plain OOM or crash-mid-answer
+  case — the orphan partial is dropped and that single user is re-dispatched as
+  a fresh turn, so the interrupted question still gets answered.
+</Note>
+
+## Examples
+
+### Drop the partial — strict "cancel means discard"
+
+The customer's UX treats cancel as "throw the work away":
+
+```ts
+onRecoveryBoot: async ({ inFlightUsers, partialAssistant }) => {
+  if (!partialAssistant) return;          // No partial → nothing to drop
+  return {
+    chain: undefined,                      // Use settledMessages, don't splice partial
+    recoveredTurns: inFlightUsers.slice(1) // Still skip the first user (the dead run was answering it)
+  };
+}
+```
+
+### Synthesize tool results for a mid-call interruption
+
+The dead run was processing a tool call when it died. The partial has tool parts in `input-available` state with no `output-available`. Synthesize a result so the model can keep going:
+
+```ts
+onRecoveryBoot: async ({ partialAssistant, pendingToolCalls, settledMessages, inFlightUsers }) => {
+  if (pendingToolCalls.length === 0) return;
+
+  // Rebuild the partial with synthetic outputs for any input-available tool call.
+  const repaired = {
+    ...partialAssistant!,
+    parts: partialAssistant!.parts!.map((part, i) => {
+      const pending = pendingToolCalls.find(p => p.partIndex === i);
+      if (!pending) return part;
+      return {
+        ...part,
+        state: "output-available" as const,
+        output: { interrupted: true, reason: "previous run was cancelled" },
+      };
+    }),
+  };
+
+  return {
+    chain: [...settledMessages, inFlightUsers[0]!, repaired],
+    recoveredTurns: inFlightUsers.slice(1),
+  };
+}
+```
+
+### Persist the partial before the next turn fires
+
+```ts
+onRecoveryBoot: async ({ chatId, partialAssistant }) => {
+  return {
+    beforeBoot: async () => {
+      if (partialAssistant) {
+        await db.partial.create({
+          data: { chatId, partialJson: JSON.stringify(partialAssistant) },
+        });
+      }
+    },
+  };
+}
+```
+
+## Interaction with other features
+
+### `hydrateMessages`
+
+If your agent registers [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages), the runtime skips snapshot read, `session.out` replay, `session.in` replay, AND `onRecoveryBoot`. Your DB is the source of truth — recovery decisions live in your own query. To detect a cancel-recovery scenario yourself, persist a `runState: "in-progress"` flag in `onTurnStart` and check for it in `hydrateMessages`.
+
+### `chat.requestUpgrade()`
+
+[`chat.requestUpgrade()`](/ai-chat/patterns/version-upgrades) is a graceful exit — the old run doesn't crash, it returns cleanly. The new continuation run boots with a clean `session.out` tail (`partialAssistant` is undefined) and the upgrade-trigger message on `session.in` (one in-flight user). The smart default doesn't splice (it requires both partial AND in-flight users), so the chain is just `settledMessages` and the in-flight user dispatches as a fresh turn. `onRecoveryBoot` still fires (there's an in-flight user) — use it to emit an "upgraded" signal to the UI if you want.
+
+### Hooks throwing
+
+If the body of `onRecoveryBoot` throws (or rejects), the runtime logs a warning and falls back to the smart default — the run does not fail. Wrap your own try/catch if you want stricter handling.
+
+`beforeBoot` is the exception: it's the contract you opted into for blocking persistence, so errors thrown there **bubble** and fail the run rather than dispatch recovered turns against half-persisted state. Wrap it yourself if you want to soft-fail.
+
+## See also
+
+- [OOM resilience](/ai-chat/patterns/oom-resilience) — `oomMachine` opt-in for automatic memory-driven recovery; uses the same recovery boot path.
+- [Persistence and replay](/ai-chat/patterns/persistence-and-replay) — the snapshot + dual-tail replay model that recovery boot sits on top of.
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks) — where `onRecoveryBoot` sits in the broader hook taxonomy.

package/docs/ai-chat/patterns/redacting-telemetry.mdx

@@ -0,0 +1,117 @@
+---
+title: "Redact chat content from traces"
+sidebarTitle: "Redact chat content"
+description: "Stop a chat agent recording user messages and clientData on its spans, turn off AI SDK prompt and response recording, or redact span content with a span processor before it leaves the worker."
+---
+
+A chat agent's run trace records conversation content by default: the user's message, the `clientData` your frontend sends, and, through AI SDK telemetry, the prompts and responses of each model call. This page covers the three controls that change that, and what they don't cover.
+
+## What the run trace records
+
+| Span | Content | Control |
+| --- | --- | --- |
+| `chat turn N` | The last user message (`chat.user_message`) and its first 80 characters as the span preview | `telemetry.recordUserMessage` |
+| `chat turn N` | The raw `clientData` (`chat.client_data`) | `telemetry.recordClientData` |
+| `pending message injected` | Messages sent mid-turn (`pending.messages`) | `telemetry.recordUserMessage` |
+| AI SDK model call spans (on by default with the `streamText` from `run`) | Prompt messages, response text, tool calls | `telemetry.recordUserMessage` for the default config, or `experimental_telemetry` on the model call |
+| Any span | Everything above, plus your own attributes and span events | A span processor |
+
+## Stop recording chat content
+
+Set `telemetry` on the agent to stop the chat runtime recording the user's message and `clientData` on its spans. Both default to `true`.
+
+```ts /trigger/support-agent.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  telemetry: { recordUserMessage: false, recordClientData: false },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+The spans still appear in the trace with their timings and token usage. The turn spans have no preview text. `recordUserMessage: false` also keeps prompts and responses out of the AI SDK spans that the `streamText` passed to `run()` turns on, with or without a prompt stored by `chat.prompt.set()`, and leaves a stored prompt's variables out of the span metadata, unless the call passes its own `experimental_telemetry`.
+
+## Stop the AI SDK recording prompts and responses
+
+The `streamText` passed to `run()` turns AI SDK telemetry on, so each model call and tool call is a span in the run trace (pass `experimental_telemetry: { isEnabled: false }` to turn the spans off). If you call `streamText` from `ai` yourself, pass `experimental_telemetry` to get them. Those spans include prompts and responses unless you turn that off with `recordInputs` and `recordOutputs`:
+
+```ts /trigger/support-agent.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  telemetry: { recordUserMessage: false, recordClientData: false },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      // Replaces the default telemetry config (and chat.prompt.set()'s), so keep isEnabled on
+      experimental_telemetry: { isEnabled: true, recordInputs: false, recordOutputs: false },
+    }),
+});
+```
+
+If you use `chat.prompt.set()`, your `experimental_telemetry` replaces the one it adds, including the metadata that links each generation to its prompt version. To keep that link, redact with a span processor instead.
+
+## Redact instead of dropping
+
+To keep the content but strip sensitive values from it, add a span processor in `trigger.config.ts`. It runs on every span before export, so one processor covers the chat runtime's spans, the AI SDK spans and your own.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import type { AttributeValue, Attributes } from "@opentelemetry/api";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const EMAIL = /[\w.+-]+@[\w-]+\.[\w.]+/g;
+
+function redact(value: AttributeValue | undefined): AttributeValue | undefined {
+  if (typeof value === "string") return value.replace(EMAIL, "[email]");
+  // Some attributes are string arrays, like the messages sent mid-turn
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      typeof item === "string" ? item.replace(EMAIL, "[email]") : item
+    ) as AttributeValue;
+  }
+  return value;
+}
+
+function scrub(attributes: Attributes) {
+  for (const key of Object.keys(attributes)) attributes[key] = redact(attributes[key]);
+}
+
+const redactEmails: SpanProcessor = {
+  onStart: () => {},
+  onEnding: (span) => {
+    scrub(span.attributes);
+    for (const event of span.events) scrub(event.attributes ?? {});
+  },
+  onEnd: () => {},
+  forceFlush: async () => {},
+  shutdown: async () => {},
+};
+
+export default defineConfig({
+  project: "<project ref>",
+  telemetry: { spanProcessors: [redactEmails] },
+});
+```
+
+Scrubbing every string value, rather than matching attribute names, also catches the turn preview text. See [Span processors](/config/config-file#span-processors) for when each hook runs and which attributes are kept.
+
+## What spans don't cover
+
+These controls change the run trace only. Conversation content also reaches the platform in two other places:
+
+- **Session streams.** Each message your frontend sends is written to the session's `session.in` stream, and the agent's output to `session.out`. They hold message content for their retention window, and the session view in the dashboard reads from them. See [transcript storage limits](/ai-chat/transcript-storage#guarantees-and-limits).
+- **The run payload.** A chat agent run's payload includes `clientData` as `metadata`, and every `session.in` record carries it too. Send an id in `clientData` and look up the rest in `onPreload` or `run` instead of sending the values themselves.
+
+To keep a value off the platform entirely, redact or tokenize it in your frontend or backend before it's sent. The model then sees the redacted value too, unless your tools resolve the tokens.
+
+## Verify it
+
+Send a message containing a marker value (an email address, for example), then open the run in the dashboard. Select the `chat turn 1` span and check its properties: the marker is gone, or shows as `[email]` with the span processor above. The span list shows the same redacted preview.

package/docs/ai-chat/patterns/skills.mdx

@@ -0,0 +1,214 @@
+---
+title: "Agent Skills"
+sidebarTitle: "Agent Skills"
+description: "Ship reusable capabilities (folders with SKILL.md + scripts) that a chat agent discovers and invokes on demand."
+---
+
+Agent skills are reusable capabilities you ship as folders — a `SKILL.md` describing when and how to use them, plus optional scripts, references, and assets. The chat agent sees a short description of each skill in its system prompt, loads the full instructions on demand via a `loadSkill` tool, and invokes the bundled scripts via `bash` — all without you wiring anything up manually.
+
+Built on the [AI SDK cookbook pattern](https://ai-sdk.dev/cookbook/guides/agent-skills). Works with any provider (OpenAI, Anthropic, Gemini, etc.) — not tied to Anthropic's server-side skills.
+
+## Why skills?
+
+Compared to regular AI SDK tools:
+
+- **Tools** are typed functions you pre-declare. Great when you know up-front exactly what capability the agent needs.
+- **Skills** are folders the model discovers and reads on demand. Great when the capability is a bundle of instructions + helper scripts that would be awkward to encode as a single tool.
+
+PDFs are the canonical example: you don't want to ask the LLM to parse PDF bytes inline. You want it to `bash scripts/extract.py report.pdf` using a bundled `pdfplumber` wrapper. A skill ships the script, the instructions, and any reference notes together.
+
+Dashboard-editable `SKILL.md` is on the roadmap so a platform team can tighten a skill's description or "when to use" text without a redeploy. Today, skills are SDK-only — defined in your task code and shipped with each deploy.
+
+## Trust model
+
+Skills are **developer-authored code**, not end-user-supplied. The same developer who writes the `chat.agent()` writes the skill bundle. The trust boundary is identical to any `tool.execute` handler the developer writes — scripts run directly in the Trigger.dev worker container, no sandboxing required.
+
+This makes skills different from the Claude Code / end-user model where arbitrary user-provided skills need isolation. Don't accept skill paths from untrusted input.
+
+## Skill folder layout
+
+A skill is a directory under your project (conventionally `trigger/skills/{id}/`):
+
+```
+trigger/skills/time-utils/
+├── SKILL.md              # Required — frontmatter + instructions
+├── scripts/
+│   ├── now.sh
+│   └── add.sh
+├── references/
+│   └── timezones.txt
+└── assets/               # Optional — templates, data files, etc.
+```
+
+### SKILL.md
+
+Frontmatter is YAML-subset — only `name` and `description` are required:
+
+```md
+---
+name: time-utils
+description: Compute and format dates/times in arbitrary timezones. Use when the user asks "what time is it", timezone conversions, or date math.
+---
+
+# Time utilities
+
+## When to use
+
+- The user asks for the current time in a timezone
+- The user wants date math ("3 days from now")
+
+## Scripts
+
+### `scripts/now.sh [TZ]`
+Prints the current time in the given IANA timezone (default `UTC`).
+
+### `scripts/add.sh DAYS [TZ]`
+Prints a date `DAYS` days from now.
+
+## Tips
+- IANA timezone names only (`America/New_York`, not `EST`).
+- See `references/timezones.txt` for a cheat-sheet.
+```
+
+The **description** is what the model sees in its system prompt — write it like you're explaining to the agent when to reach for the skill.
+
+The **body** is loaded on demand via the `loadSkill` tool when the agent decides to use the skill. Write it like documentation for the agent.
+
+## Defining and using a skill
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { skills } from "@trigger.dev/sdk";
+import { stepCountIs } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const timeUtilsSkill = skills.define({
+  id: "time-utils",
+  path: "./skills/time-utils",
+});
+
+export const agent = chat.agent({
+  id: "docs-chat",
+  onChatStart: async () => {
+    chat.skills.set([await timeUtilsSkill.local()]);
+  },
+  run: async ({ messages, signal, streamText }) => {
+    return streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    });
+  },
+});
+```
+
+`skills.define({ id, path })` does two things:
+
+1. Registers the skill with the Trigger.dev build system so the CLI **automatically bundles the folder** into your deploy image at `/app/.trigger/skills/{id}/`. No `trigger.config.ts` changes, no build extension — it just works.
+2. Returns a `SkillHandle` you use at runtime.
+
+`skill.local()` reads the bundled `SKILL.md` from disk and returns a `ResolvedSkill` with the parsed frontmatter + body + on-disk path.
+
+`chat.skills.set([...])` stores the resolved skills for the current run. The `streamText` from `run`'s argument picks them up automatically:
+
+- The frontmatter `description` lands in the system prompt under "Available skills:".
+- Three tools are added: `loadSkill`, `readFile`, `bash` — scoped per skill.
+
+## What gets auto-injected
+
+When you spread `chat.toStreamTextOptions()` with skills set, the AI SDK call receives three tools:
+
+### `loadSkill({ name })`
+
+Returns the full `SKILL.md` body for the named skill. The model calls this first when it decides a skill is relevant, to load the full instructions.
+
+### `readFile({ skill, path })`
+
+Reads a file inside the skill's bundled folder. Paths are relative to the skill's root and are rejected if they attempt to escape via `..` or absolute paths. Output is capped at 1 MB per call.
+
+Use for reference files and templates that the model should read literally:
+
+```
+readFile({ skill: "time-utils", path: "references/timezones.txt" })
+```
+
+### `bash({ skill, command })`
+
+Runs a bash command with `cwd` set to the skill's root. Stdout and stderr are captured and returned (each capped at 64 KB per call, with tail truncation). The turn's abort signal propagates — cancelling the run kills the child process.
+
+Use to invoke the skill's bundled scripts:
+
+```
+bash({ skill: "time-utils", command: "bash scripts/now.sh America/Los_Angeles" })
+```
+
+Script runtime expectations are yours to manage. If your skill uses `extract.py`, your deploy image needs Python — add it via your build config the same way you would for any other task dependency.
+
+## How discovery works in the model
+
+The model sees a short preamble appended to your system prompt:
+
+```
+Available skills (call `loadSkill` to read the full instructions before using one):
+- time-utils: Compute and format dates/times in arbitrary timezones...
+- pdf-processing: Extract text from PDFs, fill forms...
+```
+
+When the user asks something that matches a description, the model calls `loadSkill({ name: "time-utils" })` to load the body, then follows the body's instructions — typically by calling `bash` or `readFile` on the bundled scripts.
+
+This is **progressive disclosure**: each skill costs ~100 tokens up front (its one-line description), and only the ones the model actually uses pay the full context cost.
+
+## Mixing skills with custom tools
+
+If you also define your own AI SDK tools, pass them through `chat.toStreamTextOptions()` so the merge is explicit:
+
+```ts
+return streamText({
+  model: anthropic("claude-sonnet-4-5"),
+  messages,
+  abortSignal: signal,
+  tools: {
+    webFetch,       // your tool
+    deepResearch,   // your tool
+  },
+  stopWhen: stepCountIs(15),
+});
+```
+
+Your tools win on name conflicts. (Pick names that don't collide with `loadSkill` / `readFile` / `bash` to keep things predictable.)
+
+Also declare those same tools on the agent's [`tools`](/ai-chat/tools) config. `toStreamTextOptions` merges them with the skill tools for the model call, while the config option threads them into history re-conversion so any `toModelOutput` survives across turns. The auto-injected skill tools (`loadSkill` / `readFile` / `bash`) don't define `toModelOutput`, so they don't need to be on the config.
+
+## Bundling
+
+Bundling is **built-in to the CLI** — there's no extension to import. When you run `trigger deploy` or `trigger dev`:
+
+1. esbuild bundles your task code as usual.
+2. The CLI forks the indexer locally against the bundled output, collects every `skills.define({ path })` registration.
+3. Each skill's folder is copied to `{outputPath}/.trigger/skills/{id}/` via a recursive copy.
+4. The existing Dockerfile `COPY` picks up `.trigger/skills/` along with the rest of the bundle — no Dockerfile changes.
+
+If you're running `trigger dev`, the same layout appears in the local dev output directory, so `skill.local()` works the same way.
+
+## Path scoping rules
+
+- `skill.path` always resolves to `${process.cwd()}/.trigger/skills/{id}/` at runtime. Don't hardcode paths elsewhere.
+- `readFile` rejects `..` segments and absolute paths — the tool only exposes files inside the skill's own directory.
+- `bash` runs with `cwd` set to the skill's root. Inside the script, relative paths resolve against the skill directory.
+- Cross-skill access isn't provided — each skill is isolated by design. If two skills need to share data, either duplicate the shared file or consolidate the skills.
+
+## Current limitations
+
+- `skill.resolve()` (backend-managed overrides) is not available yet — use `.local()` for now. Dashboard-editable `SKILL.md` is on the roadmap.
+- No per-skill metrics in the dashboard yet.
+- No Anthropic `/v1/skills` integration — use the portable path today; we're tracking the Anthropic optimization separately.
+
+## Full example
+
+See [`projects/ai-chat/src/trigger/skills/time-utils/`](https://github.com/triggerdotdev/references/tree/main/projects/ai-chat/src/trigger/skills/time-utils) in the [references repo](https://github.com/triggerdotdev/references) for a working skill that bundles two bash scripts and a reference cheat-sheet, wired into a `chat.agent` that answers timezone questions.
+
+## Related
+
+- [AI SDK cookbook — Agent Skills](https://ai-sdk.dev/cookbook/guides/agent-skills) — the userland pattern we build on
+- [Anthropic Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) — Anthropic's codified version (server-side, optional future integration)