fix(sdk): hydrate chat session handle from tool metadata in ai.toolExecute subtasks

`chat.stream.writer({ target: "root" })` and the rest of the
`chat.stream` helpers all funnel through `getChatSession()`, which
looked up the session handle in run-scoped `locals`. That key is only
populated inside a `chat.agent` run — `ai.toolExecute` subtasks
running in a separate worker process don't inherit it, so any chat
helper used from a subtask threw `"chat.agent session handle is not
initialized"`.

Resolve the handle lazily: if it's not in `locals`, fall back to the
`chatId` already threaded through tool metadata under `METADATA_KEY`
and call `sessions.open(chatId)` to materialize it. Cache the result
back into `locals` so subsequent calls in the same subtask hit the
fast path.

Author: ericallam

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

@@ -658,20 +658,35 @@ export async function __replaySessionOutTailProductionPathForTests<
 }
 
 /**
- * Resolve the Session handle for the current chat.agent run. Throws if
- * called outside of a chat.agent `run()` — every internal consumer is
- * inside the run, and every external consumer goes through the public
- * `sessions.open(id)` entry point.
+ * Resolve the Session handle for the current chat.agent run.
+ *
+ * Two contexts populate this:
+ *   1. Inside a `chat.agent` run — `locals.chatSessionHandleKey` is set
+ *      at boot (lines 4665 / 4760).
+ *   2. Inside an `ai.toolExecute` subtask — the tool wrapper threads the
+ *      parent's `chatId` through tool metadata under `METADATA_KEY`. We
+ *      lazily open the session from that chatId here so subtasks can use
+ *      `chat.stream.writer({ target: "root" })` to write back to the
+ *      parent's chat session without any wiring.
+ *
+ * Throws if neither is available.
  * @internal
  */
 function getChatSession(): SessionHandle {
-  const handle = locals.get(chatSessionHandleKey);
-  if (!handle) {
-    throw new Error(
-      "chat.agent session handle is not initialized. This indicates a chat.agent helper was used outside of a chat.agent run, or the transport did not send a sessionId."
-    );
+  let handle = locals.get(chatSessionHandleKey);
+  if (handle) return handle;
+
+  // Fallback: subtask context. The parent threaded chatId via tool metadata.
+  const toolMeta = metadata.get(METADATA_KEY) as ToolCallExecutionOptions | undefined;
+  if (toolMeta?.chatId) {
+    handle = sessions.open(toolMeta.chatId);
+    locals.set(chatSessionHandleKey, handle);
+    return handle;
   }
-  return handle;
+
+  throw new Error(
+    "chat.agent session handle is not initialized. This indicates a chat.agent helper was used outside of a chat.agent run, or the transport did not send a sessionId."
+  );
 }
 
 /**