feat(sdk): add mockChatAgent test harness with locals DI

Drives a chat.agent definition through real turns offline — send
messages, actions, and stop signals; inspect captured chunks; assert
on hook order. Pre-seed dependencies via setupLocals so hooks read
test instances (DB clients, stubs) via locals.get() instead of
leaking through untrusted clientData.

Adds ai-chat reference tests exercising the harness across basic
flow, onValidateMessages, hydrateMessages, and actions.

Author: ericallam

.changeset/mock-chat-agent-setup-locals.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Add `setupLocals` option to `mockChatAgent` for dependency injection in tests. Pre-seed `locals` (database clients, service stubs) before the agent's `run()` starts, so hooks read the test instance via `locals.get()` without leaking through untrusted `clientData`. Also exposes `drivers.locals.set()` on `runInMockTaskContext`.

.changeset/mock-chat-agent-test-harness.md

@@ -0,0 +1,8 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Add `mockChatAgent` test harness at `@trigger.dev/sdk/ai/test` for unit-testing `chat.agent` definitions offline. Drives a real agent's turn loop without network or task runtime: send messages, actions, and stop signals via driver methods, inspect captured output chunks, and verify hooks fire. Pairs with `MockLanguageModelV3` from `ai/test` for model mocking.
+
+Also adds `TestRunMetadataManager` to `@trigger.dev/core/v3/test` (in-memory metadata manager used by the harness), and exposes an `onWrite` hook on `TestRealtimeStreamsManager` so harnesses can react to stream writes without polling.

packages/trigger-sdk/package.json

@@ -25,6 +25,7 @@
       ".": "./src/v3/index.ts",
       "./v3": "./src/v3/index.ts",
       "./ai": "./src/v3/ai.ts",
+      "./ai/test": "./src/v3/test/index.ts",
       "./chat": "./src/v3/chat.ts",
       "./chat/react": "./src/v3/chat-react.ts"
     },
@@ -40,6 +41,9 @@
       "ai": [
         "dist/commonjs/v3/ai.d.ts"
       ],
+      "ai/test": [
+        "dist/commonjs/v3/test/index.d.ts"
+      ],
       "chat": [
         "dist/commonjs/v3/chat.d.ts"
       ],
@@ -72,6 +76,7 @@
     "ws": "^8.11.0"
   },
   "devDependencies": {
+    "@ai-sdk/provider": "3.0.8",
     "@arethetypeswrong/cli": "^0.15.4",
     "@types/debug": "^4.1.7",
     "@types/react": "^19.2.14",
@@ -137,6 +142,17 @@
         "default": "./dist/commonjs/v3/ai.js"
       }
     },
+    "./ai/test": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/test/index.ts",
+        "types": "./dist/esm/v3/test/index.d.ts",
+        "default": "./dist/esm/v3/test/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/test/index.d.ts",
+        "default": "./dist/commonjs/v3/test/index.js"
+      }
+    },
     "./chat": {
       "import": {
         "@triggerdotdev/source": "./src/v3/chat.ts",

packages/trigger-sdk/src/v3/test/index.ts

@@ -0,0 +1,23 @@
+// Importing this module installs an in-memory resource catalog so that
+// chat.agent() calls (which run at import time) register their task
+// functions where the test harness can find them.
+//
+// Users should import `@trigger.dev/sdk/ai/test` BEFORE their agent
+// modules so the registration side-effect runs first.
+import "./setup-catalog.js";
+
+export {
+  mockChatAgent,
+  type MockChatAgentOptions,
+  type MockChatAgentHarness,
+  type MockChatAgentTurn,
+} from "./mock-chat-agent.js";
+
+// Re-export the lower-level task context harness so consumers can build
+// their own test helpers without adding a separate `@trigger.dev/core`
+// dependency to their reference projects.
+export {
+  runInMockTaskContext,
+  type MockTaskContextDrivers,
+  type MockTaskContextOptions,
+} from "@trigger.dev/core/v3/test";