feat(sdk): browser-side chat client + transport (3/5)

[ericallam]

Layer 3 of 5 in the chat.agent stack split

The browser-facing half of chat.agent: a TriggerChatTransport that
plugs into Vercel's ai-sdk useChat, plus AgentChat for direct
programmatic use. Lets a Next.js or React app drive a chat.agent
task in trigger.dev cloud over SSE.

Targets feature/chat-agent-runtime — merge after #3543

Components

• TriggerChatTransport (packages/trigger-sdk/src/v3/chat.ts):
  Vercel ai-sdk Transport implementation. Delta-only wire sends, SSE
  reconnection with lastEventId resume, stop/abort cleanup, dynamic
  accessToken refresh, X-Peek-Settled fast-close.
• AgentChat (chat-client.ts): direct programmatic chat with the
  same underlying transport.
• useTriggerChatTransport (chat-react.ts): React hook for the
  ai-sdk Transport.
• chat-tab-coordinator: cross-tab leader election for shared SSE.
• auth.ts: token plumbing for the transport.
• packages/core/src/v3/chat-client.ts: shared envelope/wire types
  used by both browser and server runtime.

Stack

• L1 → main: #3542 Sessions dashboard, task_kind, and chat-ready hardening
• L2 → L1: #3543 chat.agent runtime
• L3 → L2 (this PR)
• L4 → L3: agent-view dashboard
• L5 → L4: ai-chat reference + MCP tooling

[changeset-bot]

⚠️ No Changeset found

Latest commit: a4bd26a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d4bcd9dc-ca29-493e-8a99-d8756903be52

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/chat-client-transport

---

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 2 potential issues.

View 7 additional findings in Devin Review.

[devin-ai-integration]

🔴 Spread order lets user's basePayload silently override required trigger: "preload"

In AgentChat.ensureStarted, the required trigger: "preload" value is set before spreading this.triggerConfigDefault?.basePayload. Because later spread keys override earlier ones in JavaScript, if a user's triggerConfig.basePayload happens to contain a trigger key, it silently overrides "preload". The comment at packages/trigger-sdk/src/v3/chat-client.ts:592-596 explicitly states this value is required: "Without this, AgentChat's first run skips both preload and start hooks, which is where customer apps typically upsert their Chat row." Compare how chatId is correctly placed after the spread (line 600) so it can't be overridden — trigger should follow the same pattern.

Suggested change

	trigger: "preload",
	...(this.triggerConfigDefault?.basePayload ?? {}),
	...(this.triggerConfigDefault?.basePayload ?? {}),
	trigger: "preload",

---

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

[devin-ai-integration]

🟡 Side effect inside setPendingMsgs state updater causes double message send in React strict mode

transport.sendPendingMessage(chatId, msg, metadata) is called inside the setPendingMsgs state updater function at line 410. React strict mode (development) double-invokes state updater functions to detect impurities — the first invocation's result is discarded, but the network side effect has already fired. Because the discarded first call sees the original prev state (with _mode: "queued"), and the second call also sees the same original prev, the message is sent to the backend twice.

Fix approach

Move the sendPendingMessage call outside the updater:

const msg = pendingMsgs.find((m) => m.id === id && m._mode === "queued");
if (!msg) return;
transport.sendPendingMessage(chatId, msg, metadata);
setPendingMsgs((prev) =>
  prev.map((m) => (m.id === id ? { ...m, _mode: "steering" as const } : m))
);

Prompt for agents

In usePendingMessages hook in packages/trigger-sdk/src/v3/chat-react.ts, the promoteToSteering callback calls transport.sendPendingMessage inside the setPendingMsgs state updater function (line 410). React strict mode double-invokes state updater functions for purity checks, so this network side effect fires twice in development. The fix is to extract the sendPendingMessage call out of the updater: read the current pendingMsgs from a ref or from the state snapshot before calling setPendingMsgs, send the message, then call setPendingMsgs with a pure updater that only changes _mode. Alternatively, use a separate useEffect triggered by a state change. The key constraint is that the updater function passed to setPendingMsgs must be side-effect-free.

---

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

[ericallam]

Folded into #3543. The browser-side chat client + transport code (TriggerChatTransport, AgentChat, chat-tab-coordinator, chat-react) was tightly coupled to the SDK package.json subpath exports declared in L2 — splitting them across two PRs created install/typecheck mismatches at the boundary. Both halves now live in #3543.

Stack is now 4 layers:

• feat: Sessions dashboard, task_kind, and chat-ready hardening (1/4) #3542 (L1) — Sessions dashboard + chat-ready hardening
• feat(sdk): chat.agent — runtime + browser transport (2/4) #3543 (L2) — chat.agent runtime + browser transport (this absorbed feat(sdk): browser-side chat client + transport (3/5) #3544)
• feat(webapp): agent-view dashboard for chat.agent runs (3/4) #3545 (L3, renamed from L4) — agent-view dashboard
• feat: ai-chat reference project + MCP agent-chat tooling (4/4) #3546 (L4, renamed from L5) — ai-chat reference + MCP tooling