feat(sdk,ai-chat): skills runtime subpath + ai-chat browser test bridge

Two coupled changes that together unblock end-to-end browser smoke
testing of TriggerChatTransport in the ai-chat reference and, more
broadly, let Next.js + Webpack client bundles pull types from
@trigger.dev/sdk/ai without hitting node: imports.

@trigger.dev/sdk

- New subpath @trigger.dev/sdk/ai/skills-runtime
  (src/v3/agentSkillsRuntime.ts) owns the node-only skill tool
  impls: runBashInSkill (node:child_process) + readFileInSkill
  (node:fs/promises, node:path, with path-traversal guard).
- ai.ts drops the top-level node:child_process / node:fs/promises /
  node:path imports. The auto-injected loadSkill / readFile / bash
  tools in createAgentSkillTools() load the runtime via a
  computed-string dynamic import (let path = "./agentSkillsRuntime.js";
  await import(path)) — webpack can't statically trace the expression
  so it drops the dependency from the client graph. Worker runtimes
  resolve the relative import normally, so bash + readFile keep
  working end-to-end on the server.
- Why it matters: even type-only imports from @trigger.dev/sdk/ai
  (for example CompactionChunkData or the full tool-set type chain
  that derives ChatUiMessage via InferUITools) trigger webpack to
  trace ai.js. Pre-split, that trace hit node:child_process and
  failed the client build with UnhandledSchemeError. With the split,
  ai.ts's top-level graph is pure — no node: at the top — so type
  consumers compile cleanly.

references/ai-chat

- components/chat.tsx extends the window.__chat test bridge with
  session-era state (session / sessionId / lastEventId) and
  generic waiters (waitForStatus + waitForMessage +
  waitForFirstAssistantText) with configurable timeouts and clean
  rejection. A driver (Chrome DevTools MCP, Playwright, etc.) can
  now exercise the chat end-to-end through eval'd JS:
    await window.__chat.send("hi");
    const t = await window.__chat.waitForFirstAssistantText();
  No more click-driven smokes. Existing steerOnToolCall +
  steerAfterDelay / queueAfterDelay / promote helpers stay.
- Inlines a local structural CompactionChunkData type so
  chat.tsx doesn't pull from @trigger.dev/sdk/ai for a single type
  assertion. Defensive — the subpath split fixes the underlying
  build issue, this just keeps the chat.tsx module graph minimal.
- Fixes a stale ChatSessionState shape in the DebugPanel session
  prop type (sessionId is now optional, runId optional).

Known limitation (not in this commit)

Running the live UI smoke still requires a working chat-agent
backend for ai-chat, which depends on isolated-vm having a
prebuilt darwin-arm64 binary for node 20.20.0. On this machine
`pnpm rebuild isolated-vm` fails (node-gyp toolchain issue),
which is orthogonal to the session migration. Bridge
infrastructure is validated (all keys mount on window.__chat;
SDK tests 86/86 pass); exercising the send->stream->stop flow
end-to-end against the ai-chat agent is blocked on the native
build.

Author: ericallam

.changeset/skills-runtime-subpath.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Split the skill-runtime primitives (`bash` + `readFile` tool implementations, backed by `node:child_process` + `node:fs/promises`) out of `@trigger.dev/sdk/ai` into a new `@trigger.dev/sdk/ai/skills-runtime` subpath. Fixes client-bundle build errors (`UnhandledSchemeError: Reading from "node:child_process"…`) that hit Next.js + Webpack when a browser page imports types from `@trigger.dev/sdk/ai` (for example `ChatUiMessage` via a shared tools file). The chat-agent factory now loads the runtime lazily via a computed-string dynamic import, so server workers still get full skill support without any caller changes.

packages/trigger-sdk/package.json

@@ -25,6 +25,7 @@
       ".": "./src/v3/index.ts",
       "./v3": "./src/v3/index.ts",
       "./ai": "./src/v3/ai.ts",
+      "./ai/skills-runtime": "./src/v3/agentSkillsRuntime.ts",
       "./ai/test": "./src/v3/test/index.ts",
       "./chat": "./src/v3/chat.ts",
       "./chat/react": "./src/v3/chat-react.ts"
@@ -142,6 +143,17 @@
         "default": "./dist/commonjs/v3/ai.js"
       }
     },
+    "./ai/skills-runtime": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/agentSkillsRuntime.ts",
+        "types": "./dist/esm/v3/agentSkillsRuntime.d.ts",
+        "default": "./dist/esm/v3/agentSkillsRuntime.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/agentSkillsRuntime.d.ts",
+        "default": "./dist/commonjs/v3/agentSkillsRuntime.js"
+      }
+    },
     "./ai/test": {
       "import": {
         "@triggerdotdev/source": "./src/v3/test/index.ts",

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

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as nodePath from "node:path";
+
+/**
+ * Server-only runtime for the auto-injected skill tools
+ * (`loadSkill` / `readFile` / `bash`) that `chat.agent({ skills })`
+ * wires up. Split off from `./ai.ts` so the chat-agent surface in
+ * `@trigger.dev/sdk/ai` stays importable from client bundles —
+ * Next.js + Webpack reject top-level `node:*` imports anywhere in a
+ * client graph, even when a consumer only pulls in types.
+ *
+ * The SDK's `ai.ts` loads this module via a computed-string dynamic
+ * import inside each tool's `execute` — webpack treats the
+ * expression as an unknown dependency and skips static tracing, so
+ * the node-only symbols here never surface in a client build. The
+ * module resolves fine at runtime on a server worker because the
+ * relative path (`./agentSkillsRuntime.js`) lands next to `ai.js` in
+ * the emitted dist.
+ *
+ * Public subpath: `@trigger.dev/sdk/ai/skills-runtime`. Customers
+ * who want to eagerly bundle the runtime server-side (e.g. warming
+ * it on worker bootstrap) can import from there.
+ */
+
+const DEFAULT_BASH_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_READ_FILE_BYTES = 1024 * 1024;
+
+export type BashSkillInput = {
+  /** Absolute path to the skill's root (used as `cwd`). */
+  skillPath: string;
+  /** The bash command to run. */
+  command: string;
+  /** Optional abort signal forwarded to `spawn()`. */
+  abortSignal?: AbortSignal;
+};
+
+export type BashSkillResult =
+  | { exitCode: number | null; stdout: string; stderr: string }
+  | { error: string };
+
+export type ReadFileInSkillInput = {
+  /** Absolute path to the skill's root — the relative path must resolve inside it. */
+  skillPath: string;
+  /** Relative path the tool caller supplied. */
+  relativePath: string;
+};
+
+export type ReadFileInSkillResult = { content: string } | { error: string };
+
+function truncate(s: string, limit: number): string {
+  if (s.length <= limit) return s;
+  return s.slice(0, limit) + `\n…[truncated ${s.length - limit} bytes]`;
+}
+
+/**
+ * Path-traversal guard: confirm `relative` resolves inside `root`.
+ * Throws if it escapes via `..` or an absolute prefix. Returns the
+ * absolute resolved path.
+ */
+function safeJoinInside(root: string, relative: string): string {
+  if (nodePath.isAbsolute(relative)) {
+    throw new Error(`Path must be relative to the skill directory: ${relative}`);
+  }
+  const resolved = nodePath.resolve(root, relative);
+  const normalized = nodePath.resolve(root) + nodePath.sep;
+  if (resolved !== nodePath.resolve(root) && !resolved.startsWith(normalized)) {
+    throw new Error(`Path escapes the skill directory: ${relative}`);
+  }
+  return resolved;
+}
+
+export async function readFileInSkill({
+  skillPath,
+  relativePath,
+}: ReadFileInSkillInput): Promise<ReadFileInSkillResult> {
+  let absolute: string;
+  try {
+    absolute = safeJoinInside(skillPath, relativePath);
+  } catch (err) {
+    return { error: (err as Error).message };
+  }
+  try {
+    const content = await fs.readFile(absolute, "utf8");
+    return { content: truncate(content, DEFAULT_READ_FILE_BYTES) };
+  } catch (err) {
+    return { error: (err as Error).message };
+  }
+}
+
+export async function runBashInSkill({
+  skillPath,
+  command,
+  abortSignal,
+}: BashSkillInput): Promise<BashSkillResult> {
+  return new Promise<BashSkillResult>((resolvePromise) => {
+    let child;
+    try {
+      child = spawn("bash", ["-c", command], {
+        cwd: skillPath,
+        signal: abortSignal,
+      });
+    } catch (err) {
+      resolvePromise({ error: (err as Error).message });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += chunk.toString();
+    });
+    child.once("close", (code: number | null) => {
+      resolvePromise({
+        exitCode: code,
+        stdout: truncate(stdout, DEFAULT_BASH_OUTPUT_BYTES),
+        stderr: truncate(stderr, DEFAULT_BASH_OUTPUT_BYTES),
+      });
+    });
+    child.once("error", (err: Error) => {
+      resolvePromise({ error: err.message });
+    });
+  });
+}

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

@@ -57,9 +57,29 @@ import { locals } from "./locals.js";
 import { metadata } from "./metadata.js";
 import type { ResolvedPrompt } from "./prompt.js";
 import type { ResolvedSkill } from "./skill.js";
-import { spawn } from "node:child_process";
-import * as fs from "node:fs/promises";
-import * as nodePath from "node:path";
+// Bash-skill runtime lives in `./agentSkillsRuntime.ts` (exposed as
+// the `@trigger.dev/sdk/ai/skills-runtime` subpath) so `ai.ts`'s
+// top-level graph stays free of `node:*` imports. The chat-agent
+// surface in `@trigger.dev/sdk/ai` exports types like
+// `ChatUiMessage` / `CompactionChunkData` that frontend code
+// sometimes imports; Next.js + Webpack reject top-level node
+// builtins in the client graph even when only the type is used.
+//
+// The load path uses a computed-string variable so bundlers skip
+// static tracing — webpack emits a "Critical dependency" info-level
+// warning and defers resolution to runtime. On a server worker the
+// relative path lands next to `ai.js` in the emitted dist; on a
+// client bundle the bash tool is never invoked so the dynamic
+// import never fires.
+type BashRuntimeModule = typeof import("./agentSkillsRuntime.js");
+
+let cachedBashRuntime: BashRuntimeModule | undefined;
+async function loadAgentSkillsRuntime(): Promise<BashRuntimeModule> {
+  if (cachedBashRuntime) return cachedBashRuntime;
+  const modulePath: string = "./agentSkillsRuntime.js";
+  cachedBashRuntime = (await import(modulePath)) as BashRuntimeModule;
+  return cachedBashRuntime;
+}
 import { streams } from "./streams.js";
 import {
   sessions,
@@ -2231,9 +2251,6 @@ function getChatPrompt(): ChatPromptValue {
 /** @internal */
 const chatSkillsKey = locals.create<ResolvedSkill[]>("chat.skills");
 
-/** Limits applied by the auto-injected `loadSkill` / `readFile` / `bash` tools. */
-const DEFAULT_READ_FILE_BYTES = 1024 * 1024; // 1 MB
-const DEFAULT_BASH_OUTPUT_BYTES = 64 * 1024; // 64 KB
 
 /**
  * Store resolved skills for the current run. Call from any hook
@@ -2264,33 +2281,11 @@ function buildSkillsSystemPrompt(skills: ResolvedSkill[]): string {
   ].join("\n");
 }
 
-function truncate(s: string, limit: number): string {
-  if (s.length <= limit) return s;
-  return s.slice(0, limit) + `\n…[truncated ${s.length - limit} bytes]`;
-}
-
 /** Resolve a skill by its frontmatter `name`. */
 function findSkillByName(skills: ResolvedSkill[], name: string): ResolvedSkill | undefined {
   return skills.find((s) => s.frontmatter.name === name);
 }
 
-/**
- * Check that `candidate` resolves inside `root` — guards against path
- * traversal via `..` or absolute paths. Returns the resolved path or
- * throws.
- */
-function safeJoinInside(root: string, relative: string): string {
-  if (nodePath.isAbsolute(relative)) {
-    throw new Error(`Path must be relative to the skill directory: ${relative}`);
-  }
-  const resolved = nodePath.resolve(root, relative);
-  const normalized = nodePath.resolve(root) + nodePath.sep;
-  if (resolved !== nodePath.resolve(root) && !resolved.startsWith(normalized)) {
-    throw new Error(`Path escapes the skill directory: ${relative}`);
-  }
-  return resolved;
-}
-
 /**
  * Build the three tools we auto-inject into `streamText` when skills are
  * set: `loadSkill`, `readFile`, `bash`. Scoped per-skill by name.
@@ -2351,15 +2346,12 @@ export function buildSkillTools(skills: ResolvedSkill[]): Record<string, Tool> {
       if (!skill) {
         return { error: `Skill "${skillName}" not found.` };
       }
-      let absolute: string;
-      try {
-        absolute = safeJoinInside(skill.path, relPath);
-      } catch (err) {
-        return { error: (err as Error).message };
-      }
       try {
-        const content = await fs.readFile(absolute, "utf8");
-        return { content: truncate(content, DEFAULT_READ_FILE_BYTES) };
+        const { readFileInSkill } = await loadAgentSkillsRuntime();
+        return await readFileInSkill({
+          skillPath: skill.path,
+          relativePath: relPath,
+        });
       } catch (err) {
         return { error: (err as Error).message };
       }
@@ -2389,41 +2381,16 @@ export function buildSkillTools(skills: ResolvedSkill[]): Record<string, Tool> {
       if (!skill) {
         return { error: `Skill "${skillName}" not found.` };
       }
-      return await new Promise<{
-        exitCode: number | null;
-        stdout: string;
-        stderr: string;
-      } | { error: string }>((resolvePromise) => {
-        let child;
-        try {
-          child = spawn("bash", ["-c", command], {
-            cwd: skill.path,
-            signal: abortSignal,
-          });
-        } catch (err) {
-          resolvePromise({ error: (err as Error).message });
-          return;
-        }
-
-        let stdout = "";
-        let stderr = "";
-        child.stdout?.on("data", (chunk: Buffer | string) => {
-          stdout += chunk.toString();
-        });
-        child.stderr?.on("data", (chunk: Buffer | string) => {
-          stderr += chunk.toString();
-        });
-        child.once("close", (code: number | null) => {
-          resolvePromise({
-            exitCode: code,
-            stdout: truncate(stdout, DEFAULT_BASH_OUTPUT_BYTES),
-            stderr: truncate(stderr, DEFAULT_BASH_OUTPUT_BYTES),
-          });
-        });
-        child.once("error", (err: Error) => {
-          resolvePromise({ error: err.message });
+      try {
+        const { runBashInSkill } = await loadAgentSkillsRuntime();
+        return await runBashInSkill({
+          skillPath: skill.path,
+          command,
+          abortSignal,
         });
-      });
+      } catch (err) {
+        return { error: (err as Error).message };
+      }
     },
   });