feat(chat): auto-hydrate chat.local values in ai.tool subtasks

Author: ericallam

docs/guides/ai-chat.mdx

@@ -1122,9 +1122,11 @@ run: async ({ messages, signal }) => {
 
 Use `chat.local` to create typed, run-scoped data that persists across turns and is accessible from anywhere — the run function, tools, nested helpers. Each run gets its own isolated copy, and locals are automatically cleared between runs.
 
+When a subtask is invoked via `ai.tool()`, initialized locals are automatically serialized into the subtask's metadata and hydrated on first access — no extra code needed. Subtask changes to hydrated locals are local to the subtask and don't propagate back to the parent.
+
 ### Declaring and initializing
 
-Declare locals at module level, then initialize them inside a lifecycle hook where you have context (chatId, clientData, etc.):
+Declare locals at module level with a unique `id`, then initialize them inside a lifecycle hook where you have context (chatId, clientData, etc.):
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
@@ -1133,12 +1135,12 @@ import { openai } from "@ai-sdk/openai";
 import { z } from "zod";
 import { db } from "@/lib/db";
 
-// Declare at module level — multiple locals can coexist
+// Declare at module level — each local needs a unique id
 const userContext = chat.local<{
   name: string;
   plan: "free" | "pro";
   messageCount: number;
-}>();
+}>({ id: "userContext" });
 
 export const myChat = chat.task({
   id: "my-chat",
@@ -1172,7 +1174,7 @@ export const myChat = chat.task({
 Locals are accessible from anywhere during task execution — including AI SDK tools:
 
 ```ts
-const userContext = chat.local<{ plan: "free" | "pro" }>();
+const userContext = chat.local<{ plan: "free" | "pro" }>({ id: "userContext" });
 
 const premiumTool = tool({
   description: "Access premium features",
@@ -1186,6 +1188,49 @@ const premiumTool = tool({
 });
 ```
 
+### Accessing from subtasks
+
+When you use `ai.tool()` to expose a subtask, chat locals are automatically available read-only:
+
+```ts
+import { chat, ai } from "@trigger.dev/sdk/ai";
+import { schemaTask } from "@trigger.dev/sdk";
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { z } from "zod";
+
+const userContext = chat.local<{ name: string; plan: "free" | "pro" }>({ id: "userContext" });
+
+export const analyzeData = schemaTask({
+  id: "analyze-data",
+  schema: z.object({ query: z.string() }),
+  run: async ({ query }) => {
+    // userContext.name just works — auto-hydrated from parent metadata
+    console.log(`Analyzing for ${userContext.name}`);
+    // Changes here are local to this subtask and don't propagate back
+  },
+});
+
+export const myChat = chat.task({
+  id: "my-chat",
+  onChatStart: async ({ clientData }) => {
+    userContext.init({ name: "Alice", plan: "pro" });
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({
+      model: openai("gpt-4o"),
+      messages,
+      tools: { analyzeData: ai.tool(analyzeData) },
+      abortSignal: signal,
+    });
+  },
+});
+```
+
+<Note>
+  Values must be JSON-serializable for subtask access. Non-serializable values (functions, class instances, etc.) will be lost during transfer.
+</Note>
+
 ### Dirty tracking and persistence
 
 The `hasChanged()` method returns `true` if any property was set since the last check, then resets the flag. Use it in lifecycle hooks to only persist when data actually changed:
@@ -1207,7 +1252,7 @@ onTurnComplete: async ({ chatId }) => {
 
 | Method | Description |
 |--------|-------------|
-| `chat.local<T>()` | Create a typed local (declare at module level) |
+| `chat.local<T>({ id })` | Create a typed local with a unique id (declare at module level) |
 | `local.init(value)` | Initialize with a value (call in hooks or `run`) |
 | `local.hasChanged()` | Returns `true` if modified since last check, resets flag |
 | `local.get()` | Returns a plain object copy (for serialization) |
@@ -1337,7 +1382,7 @@ See [onTurnComplete](#onturncomplete) for the full field reference.
 |--------|-------------|
 | `chat.task(options)` | Create a chat task |
 | `chat.pipe(source, options?)` | Pipe a stream to the frontend (from anywhere inside a task) |
-| `chat.local<T>()` | Create a per-run typed local (see [Per-run data](#per-run-data-with-chatlocal)) |
+| `chat.local<T>({ id })` | Create a per-run typed local (see [Per-run data](#per-run-data-with-chatlocal)) |
 | `chat.createAccessToken(taskId)` | Create a public access token for a chat task |
 | `chat.setTurnTimeout(duration)` | Override turn timeout at runtime (e.g. `"2h"`) |
 | `chat.setTurnTimeoutInSeconds(seconds)` | Override turn timeout at runtime (in seconds) |

packages/trigger-sdk/src/v3/ai.ts

@@ -40,6 +40,8 @@ export type ToolCallExecutionOptions = {
   turn?: number;
   continuation?: boolean;
   clientData?: unknown;
+  /** Serialized chat.local values from the parent run. @internal */
+  chatLocals?: Record<string, unknown>;
 };
 
 /** Chat context stored in locals during each chat.task turn for auto-detection. */
@@ -121,6 +123,18 @@ function toolFromTask<
         toolMeta.clientData = chatCtx.clientData;
       }
 
+      // Serialize initialized chat.local values for subtask hydration
+      const chatLocals: Record<string, unknown> = {};
+      for (const entry of chatLocalRegistry) {
+        const value = locals.get(entry.key);
+        if (value !== undefined) {
+          chatLocals[entry.id] = value;
+        }
+      }
+      if (Object.keys(chatLocals).length > 0) {
+        toolMeta.chatLocals = chatLocals;
+      }
+
       return await task
         .triggerAndWait(input as inferSchemaIn<TTaskSchema>, {
           metadata: {
@@ -1546,8 +1560,31 @@ function cleanupAbortedParts(message: UIMessage): UIMessage {
 const CHAT_LOCAL_KEY: unique symbol = Symbol("chatLocalKey");
 /** @internal Symbol for storing the dirty-tracking locals key. */
 const CHAT_LOCAL_DIRTY_KEY: unique symbol = Symbol("chatLocalDirtyKey");
-/** @internal Counter for generating unique locals IDs. */
-let chatLocalCounter = 0;
+
+// ---------------------------------------------------------------------------
+// chat.local registry — tracks all declared locals for serialization
+// ---------------------------------------------------------------------------
+
+type ChatLocalEntry = { key: ReturnType<typeof locals.create>; id: string };
+const chatLocalRegistry = new Set<ChatLocalEntry>();
+
+/** @internal Run-scoped flag to ensure hydration happens at most once per run. */
+const chatLocalsHydratedKey = locals.create<boolean>("chat.locals.hydrated");
+
+/**
+ * Hydrate chat.local values from subtask metadata (set by toolFromTask).
+ * Runs once per run — subsequent calls are no-ops.
+ * @internal
+ */
+function hydrateLocalsFromMetadata(): void {
+  if (locals.get(chatLocalsHydratedKey)) return;
+  locals.set(chatLocalsHydratedKey, true);
+  const opts = metadata.get(METADATA_KEY) as ToolCallExecutionOptions | undefined;
+  if (!opts?.chatLocals) return;
+  for (const [id, value] of Object.entries(opts.chatLocals)) {
+    locals.set(locals.create(id), value);
+  }
+}
 
 /**
  * A Proxy-backed, run-scoped data object that appears as `T` to users.
@@ -1574,12 +1611,16 @@ export type ChatLocal<T extends Record<string, unknown>> = T & {
  *
  * Multiple locals can coexist — each gets its own isolated run-scoped storage.
  *
+ * The `id` is required and must be unique across all `chat.local()` calls in
+ * your project. It's used to serialize values into subtask metadata so that
+ * `ai.tool()` subtasks can auto-hydrate parent locals (read-only).
+ *
  * @example
  * ```ts
  * import { chat } from "@trigger.dev/sdk/ai";
  *
- * const userPrefs = chat.local<{ theme: string; language: string }>();
- * const gameState = chat.local<{ score: number; streak: number }>();
+ * const userPrefs = chat.local<{ theme: string; language: string }>({ id: "userPrefs" });
+ * const gameState = chat.local<{ score: number; streak: number }>({ id: "gameState" });
  *
  * export const myChat = chat.task({
  *   id: "my-chat",
@@ -1603,9 +1644,12 @@ export type ChatLocal<T extends Record<string, unknown>> = T & {
  * });
  * ```
  */
-function chatLocal<T extends Record<string, unknown>>(): ChatLocal<T> {
-  const localKey = locals.create<T>(`chat.local.${chatLocalCounter++}`);
-  const dirtyKey = locals.create<boolean>(`chat.local.${chatLocalCounter++}.dirty`);
+function chatLocal<T extends Record<string, unknown>>(options: { id: string }): ChatLocal<T> {
+  const id = `chat.local.${options.id}`;
+  const localKey = locals.create<T>(id);
+  const dirtyKey = locals.create<boolean>(`${id}.dirty`);
+
+  chatLocalRegistry.add({ key: localKey, id });
 
   const target = {} as any;
   target[CHAT_LOCAL_KEY] = localKey;
@@ -1633,7 +1677,11 @@ function chatLocal<T extends Record<string, unknown>>(): ChatLocal<T> {
       }
       if (prop === "get") {
         return () => {
-          const current = locals.get(localKey);
+          let current = locals.get(localKey);
+          if (current === undefined) {
+            hydrateLocalsFromMetadata();
+            current = locals.get(localKey);
+          }
           if (current === undefined) {
             throw new Error(
               "local.get() called before initialization. Call local.init() first."
@@ -1645,12 +1693,21 @@ function chatLocal<T extends Record<string, unknown>>(): ChatLocal<T> {
       // toJSON for serialization (JSON.stringify(local))
       if (prop === "toJSON") {
         return () => {
-          const current = locals.get(localKey);
+          let current = locals.get(localKey);
+          if (current === undefined) {
+            hydrateLocalsFromMetadata();
+            current = locals.get(localKey);
+          }
           return current ? { ...current } : undefined;
         };
       }
 
-      const current = locals.get(localKey);
+      let current = locals.get(localKey);
+      if (current === undefined) {
+        // Auto-hydrate from parent metadata in subtask context
+        hydrateLocalsFromMetadata();
+        current = locals.get(localKey);
+      }
       if (current === undefined) return undefined;
       return (current as any)[prop];
     },
@@ -1673,18 +1730,30 @@ function chatLocal<T extends Record<string, unknown>>(): ChatLocal<T> {
 
     has(_target, prop) {
       if (typeof prop === "symbol") return prop in _target;
-      const current = locals.get(localKey);
+      let current = locals.get(localKey);
+      if (current === undefined) {
+        hydrateLocalsFromMetadata();
+        current = locals.get(localKey);
+      }
       return current !== undefined && prop in current;
     },
 
     ownKeys() {
-      const current = locals.get(localKey);
+      let current = locals.get(localKey);
+      if (current === undefined) {
+        hydrateLocalsFromMetadata();
+        current = locals.get(localKey);
+      }
       return current ? Reflect.ownKeys(current) : [];
     },
 
     getOwnPropertyDescriptor(_target, prop) {
       if (typeof prop === "symbol") return undefined;
-      const current = locals.get(localKey);
+      let current = locals.get(localKey);
+      if (current === undefined) {
+        hydrateLocalsFromMetadata();
+        current = locals.get(localKey);
+      }
       if (current === undefined || !(prop in current)) return undefined;
       return {
         configurable: true,

references/ai-chat/src/trigger/chat.ts

@@ -134,12 +134,12 @@ const userContext = chat.local<{
   plan: "free" | "pro";
   preferredModel: string | null;
   messageCount: number;
-}>();
+}>({ id: "userContext" });
 
 // Per-run dynamic tools — loaded from DB in onPreload/onChatStart
 const userToolDefs = chat.local<
   Array<{ name: string; description: string; responseTemplate: string }>
->();
+>({ id: "userToolDefs" });
 
 // --------------------------------------------------------------------------
 // Subtask: deep research — fetches multiple URLs and streams progress