feat(sdk): route chat.agent transcript persistence through a TranscriptStorage seam

[ericallam]

Summary

Introduces the TranscriptStorage seam inside chat.agent and makes the built-in snapshot writer its default implementation. No public option yet; the default path behaves as before, apart from the blob now being written as version 2.

Design

A storage has load (called once when a run boots to continue a conversation) and save (called after every turn, failed turn and history-changing action). save receives a changeset of id-addressed operations: put (upsert by message id), remove, truncateAfter and state, plus the stream cursors the next boot resumes from.

The runtime keeps a shadow of the transcript it last handed to save (ids in order plus a fingerprint per message) and diffs the accumulator against it. A changed message in the common prefix is an in-place put; anything past the prefix is one truncateAfter on the last common id followed by puts in order. Applying the result reproduces the accumulator exactly for any edit, and the common cases come out as the natural operations: a turn is two puts, an undo is one truncateAfter, a regenerate is a truncateAfter and a put. The shadow only advances when save resolves, so a failed save is folded into the next changeset; every operation is idempotent, so a retried changeset converges.

Every changeset also carries the whole transcript as it stands after the changes (entries with a final flag, plus the runtime's state). A row-per-message store applies the changes; a store that keeps the conversation as one document writes the transcript as-is and needs no state of its own between saves. The default storage is the second kind: it serialises the transcript and rewrites the blob, so a turn still costs one PUT and no GET, and nothing is held in memory between saves. The snapshot read and write helpers move to their own module so the storage can import them without a cycle; the test seams keep their import path.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f03adfb

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]

Walkthrough

The change adds transcript storage with reducers, shadow-based diffs, pagination, cursors, and version 2 snapshot persistence. It adds injectable and production snapshot I/O paths with failure handling. Chat agent persistence now uses transcript changesets for loading, completed turns, actions, and errors. Mocks and integration tests support version 1 compatibility and version 2 message envelopes.

Priority: ➖ Normal

Merge Risk: 🟡 Moderate · up to f03ad

The transcript migration is not yet merge-ready because continuation persistence can lose state or promote partial messages to complete, snapshot transfers lack destination validation, and the test harness can behave differently based on execution order.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides a detailed summary and design explanation, but it omits the required issue reference, checklist, testing section, changelog, and screenshots section from the repository templa…	Add the issue reference, complete the checklist, document the tests that were run, add a short changelog entry, and include screenshots or state that screenshots are not applicable.
Docstring Coverage	⚠️ Warning	Docstring coverage is 61.90% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 13 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: routing chat.agent transcript persistence through the TranscriptStorage seam.
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.

Full details: Description check

Explanation

The description provides a detailed summary and design explanation, but it omits the required issue reference, checklist, testing section, changelog, and screenshots section from the repository template.

• Fix all pre-merge checks with AI

✨ 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/transcript-storage-seam-tri-13667

---

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@f03adfb

trigger.dev

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

@trigger.dev/core

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

@trigger.dev/python

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

@trigger.dev/react-hooks

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

@trigger.dev/redis-worker

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

@trigger.dev/rsc

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

@trigger.dev/schema-to-json

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

@trigger.dev/sdk

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

commit: f03adfb

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

packages/trigger-sdk/src/v3/transcriptStorage.ts (1)

273-280: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Return nonFinalIds from snapshotTranscriptStorage.load. Version-2 entries persist final, but load maps them to messages and omits IDs where final: false. If continuation boot passes this result to createTranscriptShadow, the next unchanged save can mark a persisted partial message as final. Collect and return those IDs.

packages/trigger-sdk/src/v3/test/mock-chat-agent.ts (1)

813-813: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Keep the seeded input cursor monotonic.

TestSessionStreamManager.setLastSeqNum overwrites the cursor. If live input advances it to 5 and seedSessionInTail seeds two messages, the cursor becomes 2. The next automatic input receives sequence 3 and reuses an existing number. This can break replay and ordering assertions. Preserve the maximum, or reset the manager and seeded sequence numbers together.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 48a0c9ab-2982-4e39-a28f-151ae684d3fd

📥 Commits

Reviewing files that changed from the base of the PR and between 85f3ff1 and a075eb1.

📒 Files selected for processing (2)

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📜 Review details

⏰ Context from checks skipped due to timeout. (27)

• GitHub Check: webapp / 🧪 Unit Tests: Webapp (12, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (16, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (19, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (24, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (9, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (14, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (20, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (21, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (18, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (15, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (17, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (11, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (13, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (10, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (7, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (1, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (6, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (8, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (2, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (5, 24)
• GitHub Check: packages / 🧪 Unit Tests: Packages (1, 3)
• GitHub Check: e2e-webapp / 🧪 E2E Tests: Webapp (2, 2)
• GitHub Check: packages / 🧪 Unit Tests: Packages (2, 3)
• GitHub Check: internal / 🧪 Unit Tests: Internal
• GitHub Check: e2e-webapp / 🧪 E2E Tests: Webapp (1, 2)
• GitHub Check: packages / 🧪 Unit Tests: Packages (3, 3)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (7)

Always import from `@trigger.dev/sdk`.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

**Prefer static imports over dynamic imports.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Add crumbs as you write code — not just when debugging.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

In the Trigger.dev SDK (packages/trigger-sdk), prefer isomorphic code like fetch and ReadableStream instead of Node.js-specific code

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Use function declarations instead of default exports

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Use types over interfaces for TypeScript Avoid using enums; prefer string unions or const objects instead

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs Do not use high-cardinality attributes in OTEL metr...

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

Files:

• packages/trigger-sdk/src/v3/ai.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

🪛 ast-grep (0.45.2)

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

[warning] 7119-7122: Avoid logging sensitive data
Context: logger.warn("chat.agent: transcript load failed; continuing from the stream tail", {
error: error instanceof Error ? error.message : String(error),
sessionId: sessionIdForSnapshot,
})
Note: [CWE-532] Insertion of Sensitive Information into Log File.

(log-sensitive-data-typescript)

🔇 Additional comments (8)

packages/trigger-sdk/src/v3/test/mock-chat-agent.ts (2)

3-3: LGTM!

Also applies to: 104-104, 240-240, 314-314, 443-444, 453-456

---

414-419: 🗄️ Data Integrity & Integration

No change needed. drivers.sessions.in.send accepts (sessionId, data, io, metadata) and forwards io and metadata.seqNum to the test session stream manager.

packages/trigger-sdk/src/v3/ai.ts (6)

7902-7902: 🗄️ Data Integrity & Integration | ⚡ Quick win

Fix the stale clientData fallback used on the error-persistence path.

turnClientData is declared inside the turn loop as payload.metadata, where payload is the run's original boot payload captured once at function entry. This value is used only as the fallback for the turn-error transcript save when parseClientData(wireMetadata) throws before clientData is assigned at Line 7933.

For any turn after turn 0, currentWirePayload (the current wire message) differs from payload (the boot payload). If parsing fails on turn > 0, the error-path saveTranscript call records the turn-0 boot metadata instead of the current turn's metadata. A custom TranscriptStorage implementation that partitions or routes by clientData receives incorrect data for that changeset.

Seed the fallback from the current turn's wire payload instead of the fixed boot payload.

🐛 Proposed fix

-          let turnClientData: unknown = payload.metadata;
+          let turnClientData: unknown = currentWirePayload.metadata;

---

41-41: LGTM!

Also applies to: 79-86, 125-126, 133-133, 263-268

---

6951-6963: LGTM!

Also applies to: 6975-7031, 7043-7057, 7109-7130

---

7249-7253: LGTM!

Also applies to: 7257-7257, 8071-8073, 8442-8473, 8489-8489, 8501-8501, 9328-9339, 9711-9719

---

2283-2283: LGTM!

Also applies to: 2314-2324, 2335-2337, 3177-3180, 5857-5868, 6798-6798, 8627-8632, 9378-9389, 9736-9738, 10385-10461, 10505-10536, 11469-11473, 11690-11690, 11800-11802, 11921-11922, 13123-13166

---

12471-12471: LGTM!

Also applies to: 12515-12515, 12538-12542, 12624-12631, 12658-12661, 12677-12682, 12717-12717, 12754-12764, 12776-12777, 12786-12791

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/trigger-sdk/src/v3/test/mock-chat-agent.ts (1)

346-346: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add crumbs to the changed logic in all three files.

• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts#L346-L346: Mark the durable watermark declaration.
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts#L587-L601: Mark the restore and update path.
• packages/core/src/v3/sessionStreams/chatSnapshot.ts#L47-L47: Mark the V1 schema change.
• packages/core/src/v3/sessionStreams/chatSnapshot.ts#L84-L84: Mark the V2 schema change.
• packages/core/src/v3/sessionStreams/chatSnapshot.ts#L125-L125: Mark the V2 fallback.
• packages/core/src/v3/sessionStreams/chatSnapshot.ts#L143-L143: Mark the V1 fallback.
• packages/core/src/v3/test/test-session-stream-manager.ts#L223-L227: Mark the monotonic sequence update.

As per coding guidelines, add crumbs as you write code with // @Crumbs or `// `#region` `@crumbs; these markers are stripped before merge.

Source: Coding guidelines

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: b391e768-0910-449a-aaf2-21352bd98a39

📥 Commits

Reviewing files that changed from the base of the PR and between a075eb1 and f03adfb.

📒 Files selected for processing (3)

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📜 Review details

⏰ Context from checks skipped due to timeout. (44)

• GitHub Check: webapp / 🧪 Unit Tests: Webapp (23, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (21, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (19, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (7, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (24, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (22, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (16, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (20, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (15, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (12, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (11, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (9, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (13, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (18, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (10, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (6, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (17, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (3, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (14, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (4, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (8, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (5, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (2, 24)
• GitHub Check: webapp / 🧪 Unit Tests: Webapp (1, 24)
• GitHub Check: e2e / 🧪 CLI v3 tests (warp-windows-latest-x64-8x - pnpm)
• GitHub Check: sdk-compat / Node.js 22.23 (warp-ubuntu-latest-x64-4x)
• GitHub Check: sdk-compat / Node.js 24.18 (warp-ubuntu-latest-x64-4x)
• GitHub Check: sdk-compat / Node.js 26.4 (warp-ubuntu-latest-x64-4x)
• GitHub Check: sdk-compat / Cloudflare Workers
• GitHub Check: sdk-compat / Bun Runtime
• GitHub Check: e2e / 🧪 CLI v3 tests (warp-ubuntu-latest-x64-4x - npm)
• GitHub Check: sdk-compat / Deno Runtime
• GitHub Check: e2e / 🧪 CLI v3 tests (warp-windows-latest-x64-8x - npm)
• GitHub Check: internal / 🧪 Unit Tests: Internal
• GitHub Check: packages / 🧪 Unit Tests: Packages (3, 3)
• GitHub Check: packages / 🧪 Unit Tests: Packages (1, 3)
• GitHub Check: packages / 🧪 Unit Tests: Packages (2, 3)
• GitHub Check: runops-guard / runops-guard
• GitHub Check: e2e-webapp / 🧪 E2E Tests: Webapp (1, 2)
• GitHub Check: e2e-webapp / 🧪 E2E Tests: Webapp (2, 2)
• GitHub Check: typecheck / typecheck
• GitHub Check: code-quality / code-quality
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Build and publish previews

🧰 Additional context used

📓 Path-based instructions (10)

Always import from `@trigger.dev/sdk`.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

**Import subpaths only** (never root).

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts

**Prefer static imports over dynamic imports.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Add crumbs as you write code — not just when debugging.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Use zod for validation in packages/core and apps/webapp

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts

In the Trigger.dev SDK (packages/trigger-sdk), prefer isomorphic code like fetch and ReadableStream instead of Node.js-specific code

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Never import the root package (`@trigger.dev/core`).

📄 CodeRabbit inference engine (packages/core/CLAUDE.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts

Use function declarations instead of default exports

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

Use types over interfaces for TypeScript Avoid using enums; prefer string unions or const objects instead

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts

When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs Do not use high-cardinality attributes in OTEL metr...

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

Files:

• packages/core/src/v3/sessionStreams/chatSnapshot.ts
• packages/core/src/v3/test/test-session-stream-manager.ts
• packages/trigger-sdk/src/v3/test/mock-chat-agent.ts