feat(chat): hand run() a streamText with the managed options already applied

[ericallam]

Summary

Every run() had to spread chat.toStreamTextOptions(), and leaving it out dropped six things with no error: the managed prompt and its cache control, the registry-resolved model, the prompt's sampling config, telemetry, the skill tools, and the prepareStep that delivers steering, compaction and injected context.

Before:

import { chat } from "@trigger.dev/sdk/ai";
import { streamText, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

export const myChat = chat.agent({
  id: "my-chat",
  tools: { myTool },
  run: async ({ messages, tools, signal }) =>
    streamText({
      ...chat.toStreamTextOptions({ registry, tools }),
      model: anthropic("claude-sonnet-4-5"),
      system: "You are a helpful assistant.",
      messages,
      abortSignal: signal,
      stopWhen: stepCountIs(15),
    }),
});

After:

import { chat } from "@trigger.dev/sdk/ai";
import { stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

export const myChat = chat.agent({
  id: "my-chat",
  system: "You are a helpful assistant.",
  registry,
  tools: { myTool },
  run: async ({ messages, tools, signal, streamText }) =>
    streamText({
      model: anthropic("claude-sonnet-4-5"),
      messages,
      tools,
      abortSignal: signal,
      stopWhen: stepCountIs(15),
    }),
});

streamText comes from run's argument and shadows the one imported from ai, so the correct call is now the shorter one and the managed options cannot be lost by omission. chat.toStreamTextOptions() is unchanged and still supported, and is still the only option in a custom agent.

What changes when your options collide with the managed ones

Spread order decides the outcome today, and losing is silent:

streamText({ ...chat.toStreamTextOptions(), tools: myTools })       // skill tools dropped
streamText({ ...chat.toStreamTextOptions(), prepareStep: mine })    // steering, compaction and injection off

The managed streamText merges instead. tools are passed into the helper so skill tools survive, and a prepareStep you pass runs after the managed one rather than replacing it. Everything else you name is left alone and wins, telemetry included.

system is the exception: it can be set on chat.agent({ system }), through chat.prompt.set(), or at the call site, but only in one of them. Two at once throws and names the one that already owns it. No shape merges two system values across every supported AI SDK version, since v5 rejects an array of blocks and a structured block carries the provider options that make prompt caching work.

onAction

A response produced from an action gets the same streamText. Before, a regenerate answered with no system prompt and no skill tools, so the replacement answer came from a differently configured model than every other turn.

Before:

import { streamText } from "ai";

onAction: async ({ action, messages }) => {
  if (action.type !== "regenerate") return;
  chat.history.slice(0, -1);
  return streamText({ model: anthropic("claude-sonnet-4-5"), messages });
},

After:

onAction: async ({ action, messages, streamText }) => {
  if (action.type !== "regenerate") return;
  chat.history.slice(0, -1);
  return streamText({ model: anthropic("claude-sonnet-4-5"), messages });
},

The only edit is the destructure. The two calls look the same and produce answers configured differently.

chat.headStart and chat.startHeadStart

buildStreamTextOptions supplies messages, stopWhen: stepCountIs(1) and abortSignal. Step 1 belongs to the route handler and step 2 onward to the agent, so re-setting stopWhen after a spread hands over a stream that has already run past step 1.

Before:

import { streamText, stepCountIs } from "ai";

export const POST = chat.headStart({
  agentId: "my-chat",
  run: async ({ chat: helper }) =>
    streamText({
      ...helper.toStreamTextOptions({ tools: headStartTools }),
      model: anthropic("claude-sonnet-4-6"),
      system: "You are a helpful assistant.",
    }),
});

After:

export const POST = chat.headStart({
  agentId: "my-chat",
  run: async ({ streamText }) =>
    streamText({
      model: anthropic("claude-sonnet-4-6"),
      system: "You are a helpful assistant.",
      tools: headStartTools,
    }),
});

Passing messages, stopWhen or abortSignal to that streamText is a type error, with a runtime throw behind it for JavaScript callers. The old shape only warned in prose.

Also in here

• chat.agent() takes system, registry, cacheControl and systemProviderOptions, so a managed prompt's model and its cache breakpoint no longer have to be passed at the call site.
• ChatStreamText is exported for typing a loop factored out of run.

The signature is taken from the AI SDK's own declaration:

import type { streamText as aiStreamTextSignature } from "ai";
type AiStreamTextFn = typeof aiStreamTextSignature;

The peer range spans ai v5, v6 and v7, whose options differ. typeof resolves to whichever version is installed, so generics and tool inference are the caller's own and a v8 option needs no change here.

Verification

Typecheck and the full suite pass on both ai@6.0.116 and ai@7.0.66. The option merge is a pure function so the merged object can be asserted directly, which is how experimental_telemetry being dropped was caught: most streamText options never reach the provider, so a test that observes the model cannot see them.

Run end to end against a deployed agent with every run rewritten to the new form and no spread anywhere: steering, undo across a cold boot, and regenerate all still pass, a caller's own prepareStep runs while managed steering still fires inside the turn, and consecutive injections arrive one per turn. The handover-owned options are pinned by @ts-expect-error assertions in a typechecked test rather than only by the runtime throw.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0e34286

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

This PR includes changesets to release 27 packages

Name	Type
@trigger.dev/sdk	Minor
@trigger.dev/python	Minor
@internal/dashboard-agent	Patch
@trigger.dev/build	Minor
trigger.dev	Minor
@trigger.dev/core	Minor
@trigger.dev/react-hooks	Minor
@trigger.dev/redis-worker	Minor
@trigger.dev/rsc	Minor
@trigger.dev/schema-to-json	Minor
@trigger.dev/database	Minor
@trigger.dev/otlp-importer	Minor
@trigger.dev/rbac	Minor
@trigger.dev/sso	Minor
@internal/clickhouse	Patch
@internal/llm-model-catalog	Patch
@internal/metrics-pipeline	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/run-store	Patch
@internal/schedule-engine	Patch
@internal/tracing	Patch
@internal/webhook-engine	Patch
@internal/webhook-sources	Patch
@internal/testcontainers	Patch
@internal/cache	Patch

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]

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: Team

Run ID: 66a8a7df-229a-4eac-baf2-1fee89786d11

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

Walkthrough

The SDK now supplies managed streamText functions to agent runs and action handlers. These functions preserve prompts, tools, telemetry, registry settings, caching options, and prepareStep behavior. Head Start handlers receive bound functions that own handover options. Runtime exports, public types, tests, release notes, and chat-agent documentation were updated.

Merge Risk: 🟡 Moderate · up to f36bb

Some supported prompt configurations can be silently ignored, and copied action or Head Start examples can fail or use incorrect context. These issues should be corrected before merging the new public API.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 6 files. (17 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary API change: passing a managed streamText function to run().
Description check	✅ Passed	The description provides a detailed summary, before-and-after examples, behavior details, API changes, and verification results. It does not include the template's Closes issue line, checklist, change…

Full details: Docstring Coverage

Explanation

Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 6 files. (17 skipped: 17 unsupported.)

Full details: Description check

Explanation

The description provides a detailed summary, before-and-after examples, behavior details, API changes, and verification results. It does not include the template's Closes issue line, checklist, changelog, or screenshots sections, but the core change and testing information are complete.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/chat-bound-streamtext

---

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.}

[pkg-pr-new]

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@0e34286

trigger.dev

npm i https://pkg.pr.new/trigger.dev@0e34286

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@0e34286

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@0e34286

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@0e34286

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@0e34286

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@0e34286

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@0e34286

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@0e34286

commit: 0e34286

[ericallam]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🟡 Spread fallback drops agent settings

Agents using imported streamText with chat.toStreamTextOptions() lose configured system, registry, and cache settings. Responses can run without their intended prompt or model.

Prompt for agents

The new chat.agent options registry, system, cacheControl, and systemProviderOptions are captured only by createBoundStreamText. The documented fallback using the AI SDK's imported streamText with chat.toStreamTextOptions() cannot access them, so it is not equivalent. Make agent-level managed configuration available to toStreamTextOptions during the run, or narrow the documented contract and prevent this unsupported combination. Add coverage for an agent configured with these options whose run uses imported streamText plus the helper spread.

---

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