feat(sdk): AI SDK custom useChat transport & chat.task harness

.changeset/ai-chat-sandbox-and-ctx.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Add `TaskRunContext` (`ctx`) to all `chat.task` lifecycle events, `CompactedEvent`, and `ChatTaskRunPayload`. Export `TaskRunContext` from `@trigger.dev/sdk`.
+

.changeset/ai-sdk-chat-transport.md

@@ -0,0 +1,42 @@
+---
+"@trigger.dev/sdk": minor
+---
+
+Add AI SDK chat transport integration via two new subpath exports:
+
+**`@trigger.dev/sdk/chat`** (frontend, browser-safe):
+- `TriggerChatTransport` — custom `ChatTransport` for the AI SDK's `useChat` hook that runs chat completions as durable Trigger.dev tasks
+- `createChatTransport()` — factory function
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { TriggerChatTransport } from "@trigger.dev/sdk/chat";
+
+const { messages, sendMessage } = useChat({
+  transport: new TriggerChatTransport({
+    task: "my-chat-task",
+    accessToken,
+  }),
+});
+```
+
+**`@trigger.dev/sdk/ai`** (backend, extends existing `ai.tool`/`ai.currentToolOptions`):
+- `chatTask()` — pre-typed task wrapper with auto-pipe support
+- `pipeChat()` — pipe a `StreamTextResult` or stream to the frontend
+- `CHAT_STREAM_KEY` — the default stream key constant
+- `ChatTaskPayload` type
+
+```ts
+import { chatTask } from "@trigger.dev/sdk/ai";
+import { streamText, convertToModelMessages } from "ai";
+
+export const myChatTask = chatTask({
+  id: "my-chat-task",
+  run: async ({ messages }) => {
+    return streamText({
+      model: openai("gpt-4o"),
+      messages: convertToModelMessages(messages),
+    });
+  },
+});
+```

.changeset/ai-tool-execute-helper.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Add `ai.toolExecute(task)` so you can pass Trigger's subtask/metadata wiring as the `execute` handler to AI SDK `tool()` while defining `description` and `inputSchema` yourself. Refactors `ai.tool()` to share the same internal handler.

.changeset/ai-tool-toolset-typing.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Align `ai.tool()` (`toolFromTask`) with the AI SDK `ToolSet` shape: Zod-backed tasks use static `tool()`; returns are asserted as `Tool & ToolSet[string]`. Raise the SDK's minimum `ai` devDependency to `^6.0.116` so emitted types resolve the same `ToolSet` as apps on AI SDK 6.0.x (avoids cross-version `ToolSet` mismatches in monorepos).
+

.changeset/chat-run-pat-renewal.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Add run-scoped PAT renewal for chat transport (`renewRunAccessToken`), fail fast on 401/403 for SSE without retry backoff, and export `isTriggerRealtimeAuthError` for auth-error detection.

.changeset/dry-sloths-divide.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Add `chat.withUIMessage<TUIMessage>()` for typed AI SDK `UIMessage` in chat task hooks, optional factory `streamOptions` merged with `uiMessageStreamOptions`, and `InferChatUIMessage` helper. Generic `ChatUIMessageStreamOptions`, compaction, and pending-message event types. `usePendingMessages` accepts a UI message type parameter; re-export `InferChatUIMessage` from `@trigger.dev/sdk/chat/react`.

.claude/rules/package-installation.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/package.json"
+---
+
+# Installing Packages
+
+When adding a new dependency to any package.json in the monorepo:
+
+1. **Look up the latest version** on npm before adding:
+   ```bash
+   pnpm view <package-name> version
+   ```
+   If unsure which version to use (e.g. major version compatibility), confirm with the user.
+
+2. **Edit the package.json directly** — do NOT use `pnpm add` as it can cause issues in the monorepo. Add the dependency with the correct version range (typically `^x.y.z`).
+
+3. **Run `pnpm i` from the repo root** after editing to install and update the lockfile:
+   ```bash
+   pnpm i
+   ```
+   Always run from the repo root, not from the package directory.

CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code when working with this repository. Su
 
 This is a pnpm 10.23.0 monorepo using Turborepo. Run commands from root with `pnpm run`.
 
+**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.
+
 ```bash
 pnpm run docker              # Start Docker services (PostgreSQL, Redis, Electric)
 pnpm run db:migrate           # Run database migrations

packages/build/package.json

@@ -31,7 +31,8 @@
       "./extensions/typescript": "./src/extensions/typescript.ts",
       "./extensions/puppeteer": "./src/extensions/puppeteer.ts",
       "./extensions/playwright": "./src/extensions/playwright.ts",
-      "./extensions/lightpanda": "./src/extensions/lightpanda.ts"
+      "./extensions/lightpanda": "./src/extensions/lightpanda.ts",
+      "./extensions/secureExec": "./src/extensions/secureExec.ts"
     },
     "sourceDialects": [
       "@triggerdotdev/source"
@@ -65,6 +66,9 @@
       ],
       "extensions/lightpanda": [
         "dist/commonjs/extensions/lightpanda.d.ts"
+      ],
+      "extensions/secureExec": [
+        "dist/commonjs/extensions/secureExec.d.ts"
       ]
     }
   },
@@ -207,6 +211,17 @@
         "types": "./dist/commonjs/extensions/lightpanda.d.ts",
         "default": "./dist/commonjs/extensions/lightpanda.js"
       }
+    },
+    "./extensions/secureExec": {
+      "import": {
+        "@triggerdotdev/source": "./src/extensions/secureExec.ts",
+        "types": "./dist/esm/extensions/secureExec.d.ts",
+        "default": "./dist/esm/extensions/secureExec.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/extensions/secureExec.d.ts",
+        "default": "./dist/commonjs/extensions/secureExec.js"
+      }
     }
   },
   "main": "./dist/commonjs/index.js",

packages/build/src/extensions/secureExec.ts

@@ -0,0 +1,172 @@
+import { BuildTarget } from "@trigger.dev/core/v3";
+import { BuildManifest } from "@trigger.dev/core/v3/schemas";
+import { BuildContext, BuildExtension } from "@trigger.dev/core/v3/build";
+import { dirname, resolve, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readPackageJSON } from "pkg-types";
+
+export type SecureExecOptions = {
+  /**
+   * Packages available inside the sandbox at runtime.
+   *
+   * These are `require()`'d inside the V8 isolate at runtime — the bundler
+   * never sees them statically. They are marked external and installed as
+   * deploy dependencies.
+   *
+   * @example
+   * ```ts
+   * secureExec({ packages: ["jszip", "lodash"] })
+   * ```
+   */
+  packages?: string[];
+};
+
+/**
+ * Build extension for [secure-exec](https://secureexec.dev) — run untrusted
+ * JavaScript/TypeScript in V8 isolates with configurable permissions.
+ *
+ * Handles the esbuild workarounds needed for secure-exec's runtime
+ * `require.resolve` calls, native binaries, and module-scope resolution.
+ *
+ * @example
+ * ```ts
+ * import { secureExec } from "@trigger.dev/build/extensions/secureExec";
+ *
+ * export default defineConfig({
+ *   build: {
+ *     extensions: [secureExec()],
+ *   },
+ * });
+ * ```
+ */
+export function secureExec(options?: SecureExecOptions): BuildExtension {
+  return new SecureExecExtension(options ?? {});
+}
+
+class SecureExecExtension implements BuildExtension {
+  public readonly name = "SecureExecExtension";
+
+  private userPackages: string[];
+
+  constructor(options: SecureExecOptions) {
+    this.userPackages = options.packages ?? [];
+  }
+
+  externalsForTarget(_target: BuildTarget) {
+    return [
+      // esbuild must not be bundled — it locates its native binary via a
+      // relative path from its JS API entry point. secure-exec uses esbuild
+      // at runtime to bundle polyfills for sandbox code.
+      "esbuild",
+      // User-specified packages are require()'d inside the V8 sandbox at
+      // runtime — the bundler never sees them statically.
+      ...this.userPackages,
+    ];
+  }
+
+  onBuildStart(context: BuildContext) {
+    context.logger.debug(`Adding ${this.name} esbuild plugins`);
+
+    // Plugin 1: Replace node-stdlib-browser with pre-resolved paths.
+    //
+    // Trigger's ESM shim anchors require.resolve() to the chunk path, so
+    // node-stdlib-browser's runtime require.resolve("./mock/empty.js") breaks.
+    // Fix: load the real node-stdlib-browser at build time (where require.resolve
+    // works), capture the resolved path map, and inline it as a static export.
+    const workingDir = context.workingDir;
+    context.registerPlugin({
+      name: "secure-exec-stdlib-resolver",
+      setup(build) {
+        build.onResolve({ filter: /^node-stdlib-browser$/ }, () => ({
+          path: "node-stdlib-browser",
+          namespace: "secure-exec-nsb-resolved",
+        }));
+        build.onLoad({ filter: /.*/, namespace: "secure-exec-nsb-resolved" }, () => {
+          const buildRequire = createRequire(join(workingDir, "package.json"));
+          const resolved = buildRequire("node-stdlib-browser");
+          return {
+            contents: `export default ${JSON.stringify(resolved)};`,
+            loader: "js",
+          };
+        });
+      },
+    });
+
+    // Plugin 2: Inline bridge.js at build time.
+    //
+    // bridge-loader.js in @secure-exec/node(js) uses __dirname and
+    // require.resolve("@secure-exec/core") at module scope to locate
+    // dist/bridge.js on disk. This fails in Trigger's bundled output.
+    // Fix: read bridge.js content at build time and inline it as a
+    // string literal so no runtime filesystem resolution is needed.
+    //
+    context.registerPlugin({
+      name: "secure-exec-bridge-inline",
+      setup(build) {
+        build.onLoad(
+          { filter: /[\\/]@secure-exec[\\/]node[\\/]dist[\\/]bridge-loader\.js$/ },
+          (args) => {
+            try {
+              const buildRequire = createRequire(args.path);
+              const coreEntry = buildRequire.resolve("@secure-exec/core");
+              const coreRoot = resolve(dirname(coreEntry), "..");
+              const bridgeCode = readFileSync(join(coreRoot, "dist", "bridge.js"), "utf8");
+
+              return {
+                contents: [
+                  `import { getIsolateRuntimeSource } from "@secure-exec/core";`,
+                  `const bridgeCodeCache = ${JSON.stringify(bridgeCode)};`,
+                  `export function getRawBridgeCode() { return bridgeCodeCache; }`,
+                  `export function getBridgeAttachCode() { return getIsolateRuntimeSource("bridgeAttach"); }`,
+                ].join("\n"),
+                loader: "js",
+              };
+            } catch {
+              // If we can't inline the bridge, let the normal loader handle it.
+              return undefined;
+            }
+          }
+        );
+      },
+    });
+  }
+
+  async onBuildComplete(context: BuildContext, _manifest: BuildManifest) {
+    if (context.target === "dev") {
+      return;
+    }
+
+    context.logger.debug(`Adding ${this.name} deploy dependencies`);
+
+    const dependencies: Record<string, string> = {};
+
+    // Resolve versions for user-specified sandbox packages
+    for (const pkg of this.userPackages) {
+      try {
+        const modulePath = await context.resolvePath(pkg);
+        if (!modulePath) {
+          dependencies[pkg] = "latest";
+          continue;
+        }
+
+        const packageJSON = await readPackageJSON(dirname(modulePath));
+        dependencies[pkg] = packageJSON.version ?? "latest";
+      } catch {
+        context.logger.warn(
+          `Could not resolve version for sandbox package ${pkg}, defaulting to latest`
+        );
+        dependencies[pkg] = "latest";
+      }
+    }
+
+    context.addLayer({
+      id: "secureExec",
+      dependencies,
+      image: {
+        // isolated-vm requires native compilation tools
+        pkgs: ["python3", "make", "g++"],
+      },
+    });
+  }
+}

packages/core/src/v3/apiClient/errors.ts

@@ -128,6 +128,18 @@ export class PermissionDeniedError extends ApiError {
   override readonly status: 403 = 403;
 }
 
+/**
+ * True when `error` is a 401/403 from the Trigger API (e.g. expired run-scoped PAT on realtime streams).
+ * Uses structural checks so it works even if multiple copies of `@trigger.dev/core` are bundled (subclass `instanceof` can fail).
+ */
+export function isTriggerRealtimeAuthError(error: unknown): boolean {
+  if (error === null || typeof error !== "object") {
+    return false;
+  }
+  const e = error as ApiError;
+  return e.name === "TriggerApiError" && (e.status === 401 || e.status === 403);
+}
+
 export class NotFoundError extends ApiError {
   override readonly status: 404 = 404;
 }

packages/core/src/v3/apiClient/runStream.ts

@@ -14,7 +14,7 @@ import {
   IOPacket,
   parsePacket,
 } from "../utils/ioSerialization.js";
-import { ApiError } from "./errors.js";
+import { ApiError, isTriggerRealtimeAuthError } from "./errors.js";
 import { ApiClient } from "./index.js";
 import { zodShapeStream } from "./stream.js";
 
@@ -344,6 +344,12 @@ export class SSEStreamSubscription implements StreamSubscription {
         return;
       }
 
+      if (isTriggerRealtimeAuthError(error)) {
+        this.options.onError?.(error as Error);
+        controller.error(error as Error);
+        return;
+      }
+
       // Retry on error
       await this.retryConnection(controller, error as Error);
     }

packages/core/src/v3/index.ts

@@ -80,6 +80,7 @@ export {
   getSchemaParseFn,
   type AnySchemaParseFn,
   type SchemaParseFn,
+  type inferSchemaOut,
   isSchemaZodEsque,
   isSchemaValibotEsque,
   isSchemaArkTypeEsque,

packages/core/src/v3/inputStreams/index.ts

@@ -51,6 +51,18 @@ export class InputStreamsAPI implements InputStreamManager {
     return this.#getManager().lastSeqNum(streamId);
   }
 
+  public setLastSeqNum(streamId: string, seqNum: number): void {
+    this.#getManager().setLastSeqNum(streamId, seqNum);
+  }
+
+  public shiftBuffer(streamId: string): boolean {
+    return this.#getManager().shiftBuffer(streamId);
+  }
+
+  public disconnectStream(streamId: string): void {
+    this.#getManager().disconnectStream(streamId);
+  }
+
   public clearHandlers(): void {
     this.#getManager().clearHandlers();
   }