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

[ericallam]

tl;dr

Run AI SDK chat completions as durable Trigger.dev agents.

Define your agent in one function, wire useChat to it from React, and the conversation survives page refreshes, network blips, and process restarts. Tools, multi-turn state, HITL approvals, stop-mid-stream, branching, hydration from your own DB. Frontend stays standard AI SDK useChat — only the transport changes.

This PR ships the headline (chat.agent), the durability primitive underneath it (sessions), the browser transport, agent-side hooks, Agent Skills, an offline test harness, AI SDK tool helpers, an opt-in fast-path for cold-start TTFC (chat.headStart), and an MCP integration so AI assistants drive the same machinery the browser does.

What's in

chat.agent({ id, run })	The headline. Define your agent in one function, pass it to useChat from React, conversation persists.
sessions primitive	Durable, task-bound, bidirectional channel pair (session.in / session.out) keyed on externalId. One identity, many runs over time. Powers chat.agent and unblocks "approval loop" / "resume tomorrow" workflows generally.
chat.headStart	Opt-in fast path: run step 1 in your warm Next.js / Hono / Workers / Express handler while the agent boots in parallel. Cold-start TTFC drops ~50% on the first message; the agent still owns step 2+.
Agent Skills	Drop a folder with SKILL.md next to your task, register with skills.define(), agent gets a one-line summary in its prompt and discovers full instructions on demand. CLI bundles the folder into the deploy image automatically.
mockChatAgent	Unit-test agent definitions offline. Drives the real turn loop in-process, no network, no task runtime.
ai.toolExecute(task) / ai.tool(task)	Wire a Trigger subtask in as the execute of an AI SDK tool(). Per-tool isolation, retries, observability, shaped like ordinary AI SDK tools.
MCP agent-chat tools	Now run on Sessions, so AI assistants driving an agent get the same idempotent-by-chatId, durable-across-runs behavior the browser does.

chat.agent

// trigger/chat.ts
import { chat } from "@trigger.dev/sdk/ai";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export const myChat = chat.agent({
  id: "my-chat",
  run: async ({ messages, signal }) =>
    streamText({ model: openai("gpt-4o"), messages, abortSignal: signal }),
});

// app/components/chat.tsx
import { useChat } from "@ai-sdk/react";
import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";

const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
  startSession: ({ chatId, taskId }) => startChatSession({ chatId, taskId }),
});

const { messages, sendMessage, stop, status } = useChat({ transport });

That's the floor. Layer in lifecycle hooks (onPreload, onTurnStart, onTurnComplete, onValidateMessages, onBeforeTurnComplete, onChatStart, onWait) for persistence, validation, and pre-stream work; chat.store for typed shared-data slots both sides read/write; chat.endRun() for clean exit; transport.watch(chatId) for read-only dashboard tabs that observe a run without driving it; chat.requestUpgrade() for end-and-continue handoff to a fresh run on a new version.

Agents appear under Agents in the dashboard (separate from Tasks) and have their own Playground for testing.

Sessions

The primitive chat.agent is built on. One externalId (your chatId), many runs over time, with a stable .in channel clients write to and .out channel they subscribe to:

import { sessions } from "@trigger.dev/sdk";

const session = await sessions.create({
  externalId: chatId,
  taskIdentifier: "my-task",
});

await session.in.send({ kind: "message", payload: "..." });
for await (const chunk of session.out.read()) {
  /* render */
}

Inside the task, .in.wait() and .waitWithIdleTimeout() suspend the run on a session-stream waitpoint until the next record arrives. .out.append / .pipe / .writer produce records via direct-to-S2 writes. List sessions with sessions.list({ type, tag }) for inbox-style UIs.

A chat you were in yesterday resumes against the same session today, even after the original run idle-timed out or crashed. Pass resume: true on page load and the transport reconnects via sessionId + lastEventId, kicking off a new run only when the user sends.

chat.headStart

Cold-start tax for an agent's first turn is ~1.3s of boot + hooks before the LLM response can stream. chat.headStart runs step 1 in your warm Next.js / Hono / Workers / Express process while the agent run boots in parallel:

// app/api/chat/route.ts (any Web Fetch handler)
import { chat } from "@trigger.dev/sdk/chat-server";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { tools } from "@/lib/chat-tools-schemas";

export const POST = chat.headStart({
  agentId: "my-chat",
  run: async ({ chat: chatHelper }) =>
    streamText({
      ...chatHelper.toStreamTextOptions({ tools }),
      model: openai("gpt-4o"),
      system: "...",
    }),
});

// browser: opt in by pointing the transport at your handler
const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken,
  headStart: "/api/chat",
});

Pure-text first turns finish on the handler side (no LLM call from the trigger run at all). Tool-calling first turns hand ownership to the agent at the tool-call boundary so heavy execute deps stay in the trigger task. Subsequent turns bypass the endpoint entirely. Web Fetch by default; chat.toNodeListener(handler) for Express / Fastify / Koa. Verified locally: ~53% TTFC reduction (1561ms vs 3358ms) with persistence and tool execution behaving identically.

Agent Skills

Behavior packaged as a folder, version-controlled, bundled with the deploy image:

import { chat } from "@trigger.dev/sdk/ai";
import { skills } from "@trigger.dev/sdk";

const pdfSkill = skills.define({
  id: "pdf-extract",
  path: "./skills/pdf-extract",
});

export const agent = chat.agent({
  id: "docs-chat",
  onChatStart: async () => {
    chat.skills.set([await pdfSkill.local()]);
  },
  run: async ({ messages, signal }) => streamText({ /* ... */ }),
});

The agent gets a short summary in its system prompt and loads full instructions on demand via the built-in loadSkill tool. bash and readFile tools are scoped per-skill (path-traversal guards, output caps, abort-signal propagation). No trigger.config.ts changes needed; the CLI's indexer picks the folder up automatically. Built on the AI SDK cookbook agent-skills pattern, portable across providers.

mockChatAgent

Agent definitions are now unit-testable offline:

import { mockChatAgent } from "@trigger.dev/sdk/ai/test";
import { MockLanguageModelV3 } from "ai/test";

const harness = mockChatAgent(myChat, {
  setupLocals: ({ locals }) => locals.set(dbKey, fakeDb),
});

await harness.send({ text: "hi" });
expect(harness.allChunks).toContainText("hello");
expect(harness.hooks.onTurnComplete).toHaveBeenCalledTimes(1);

Drives the real turn loop in-process — no network, no task runtime. Pairs with MockLanguageModelV3 from ai/test for model mocking. The broader runInMockTaskContext it sits on is exported from @trigger.dev/core/v3/test for unit-testing any task code.

AI SDK tool helpers

import { ai } from "@trigger.dev/sdk/ai";
import { tool } from "ai";
import { z } from "zod";

const myTool = tool({
  description: "Look up a customer by id",
  inputSchema: z.object({ id: z.string() }),
  execute: ai.toolExecute(lookupCustomerSubtask),
});

ai.toolExecute(task) keeps the tool surface yours (description, schema, etc.) and just plugs Trigger's subtask machinery into the body. ai.tool(task) (the old toolFromTask) keeps doing the all-in-one wrap. Min ai peer is ^6.0.116 to avoid cross-version ToolSet mismatches in monorepos.

Browser transport hardening

• Resilient SSE reconnection — backoff + last-event-id replay so brief network blips don't drop turns.
• ChatChunkTooLargeError for chunks that exceed the wire limit (with size in the message), so streamText blowups don't swallow the cause.
• endpoint / headStart opt-in for the transport (above).
• Multi-tab read-only mode via transport.watch(chatId) for dashboard tabs that observe a run without driving it.

MCP agent-chat integration

The CLI MCP server's start_agent_chat / send_agent_message / close_agent_chat tools now run on Sessions, so AI assistants driving an agent get the same idempotent-by-chatId, durable-across-runs behavior the browser does. Required PAT scopes change from write:inputStreams to read:sessions + write:sessions.

Other fixes

• Fix dev workers spinning at 100% CPU after the parent CLI disconnects (orphaned worker IPC feedback loop, see dev-worker-disconnect-loop changeset for the gory details).
• fix(webapp) for the playground "save" action's uncaught JSON.parse (now returns a clean 400 instead of an unhandled 500).
• typesVersions entry for v3/chat-client + inline CodeQL guards.

Docs

Full guide at /ai-chat — overview, quick-start, frontend, backend, sessions, head start, hooks, persistence, hydration, types, testing, MCP, reference. Sequence diagrams cover first-turn / multi-turn / stop-signal / head-start (pure-text and tool-call paths).

Reference project

references/ai-chat demonstrates everything end-to-end: persistent chat, branching, multi-tab, head-start toggle, hydration mode, upgrade flow.

Versions

• @trigger.dev/sdk — minor bump (chat.agent, sessions, chat.headStart, ai tool helpers, mockChatAgent, agent skills)
• @trigger.dev/core — patch
• @trigger.dev/build — patch (Skills bundling)
• trigger.dev (CLI) — patch (Skills bundling, MCP Sessions migration, dev-worker disconnect fix)
• AI SDK peer raised to ai@^6.0.116.

Refs TRI-7532.

[changeset-bot]

🦋 Changeset detected

Latest commit: 76252d7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
@trigger.dev/sdk	Minor
@trigger.dev/core	Minor
@trigger.dev/build	Minor
trigger.dev	Minor
@trigger.dev/python	Minor
@internal/sdk-compat-tests	Patch
references-ai-chat	Patch
d3-chat	Patch
references-d3-openai-agents	Patch
references-nextjs-realtime	Patch
references-realtime-hooks-test	Patch
references-realtime-streams	Patch
references-telemetry	Patch
@trigger.dev/redis-worker	Minor
@trigger.dev/schema-to-json	Minor
@internal/cache	Patch
@internal/clickhouse	Patch
@internal/llm-model-catalog	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/schedule-engine	Patch
@internal/testcontainers	Patch
@internal/tracing	Patch
@internal/tsql	Patch
@internal/zod-worker	Patch
@trigger.dev/react-hooks	Minor
@trigger.dev/rsc	Minor
@trigger.dev/database	Minor
@trigger.dev/otlp-importer	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a browser-safe chat transport and factory (TriggerChatTransport, createChatTransport) and a React hook (useTriggerChatTransport) under @trigger.dev/sdk/chat. Extends the backend AI SDK (@trigger.dev/sdk/ai) with chat primitives (chatTask, pipeChat, createChatAccessToken, CHAT_STREAM_KEY), many chat-related types, and runtime helpers. Implements per-item oversized NDJSON handling (OversizedItemMarker, extractIndexAndTask) and removes BatchItemTooLargeError/related size checks. Adds InputStreamManager methods (setLastSeqNum, shiftBuffer, disconnectStream) and introduces StreamWriteResult and new realtime options (spanName, collapsed). Updates package exports, docs, tests, and package-installation guidance.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~150 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is entirely missing. The author provided no description content, violating the template requirement for testing details, changelog, and confirmation of following contributing guidelines.	Add a detailed PR description including testing steps, a changelog summary, and confirmation that contributing guidelines were followed per the provided template.
Docstring Coverage	⚠️ Warning	Docstring coverage is 68.18% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly summarizes the main change: introducing AI SDK custom useChat transport and chat.task harness, which aligns with the extensive additions across chat transport, backend task handling, and React integration.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/tri-7532-ai-sdk-chat-transport-and-chat-task-system

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

Devin Review found 3 new potential issues.

View 14 additional findings in Devin Review.

[devin-ai-integration]

🟡 taskKind not populated in locked-worker + specified-queue path, causing AGENT/SCHEDULED runs to be annotated as STANDARD

In the resolveQueueProperties method, the locked-worker branch that handles a specified queue override (lines 89–122) never assigns taskKind. The task lookup at line 118 only selects { ttl: true }, omitting triggerSource. When the caller provides a TTL (request.body.options?.ttl), the lookup is skipped entirely. In both cases taskKind stays undefined, so annotations.taskKind at apps/webapp/app/runEngine/services/triggerTask.server.ts:316 defaults to "STANDARD". This causes AGENT (and SCHEDULED) runs triggered with lockToVersion + a queue override to be replicated to ClickHouse with task_kind = 'STANDARD', making them invisible to the new "Source" filter in the run list when filtering by AGENT.

Contrast with the non-locked path that correctly reads triggerSource

The non-locked path at line 174 calls getTaskQueueInfo() which always returns taskKind: task?.triggerSource (line 238). The locked-worker path without a specified queue also correctly sets taskKind = lockedTask.triggerSource at line 162. Only the locked-worker-with-specified-queue branch is missing it.

(Refers to line 118)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🚩 SSEStreamSubscription auth errors now bypass retry — semantic change for all consumers

The isTriggerRealtimeAuthError check at runStream.ts:433 makes 401/403 errors from realtime streams non-retryable — the error is surfaced to the controller immediately. This is a behavioral change for ALL SSEStreamSubscription consumers (not just chat), including runs.subscribeToRun, sessions.subscribeToSessionStream, and the AgentView. Previously, auth errors would retry up to maxRetries times. The new behavior is correct (retrying an expired token is wasteful), but callers that relied on the old retry window to race a token refresh might see immediate failures. The chat transport handles this via its own auth-retry wrapper (callWithAuthRetry), but other consumers (e.g. useRealtimeRun hooks) should handle the error event and refresh tokens themselves. Tests at runStream.test.ts:475-514 cover both 401 and 403 cases.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🚩 Playground action uses prisma (write) for session upsert but playground SSE routes use $replica for reads — potential read-your-write consistency gap

The playground action at playground.action.tsx:151 writes the Session via prisma.session.upsert (the primary DB). But the playground SSE route at playground.realtime.v1.sessions.$session.$io.ts:44 reads the session via $replica (resolveSessionByIdOrExternalId uses the replica). Under replication lag, the SSE subscription could return 404 if the replica hasn't caught up with the session upsert. In practice, the delay between the action response reaching the browser and the browser opening the SSE connection provides enough time for replication in most setups, but under high load this race could surface.

---

Was this helpful? React with 👍 or 👎 to provide feedback.