feat(chat): add mailbox helpers for custom agents - #4644
Conversation
🦋 Changeset detectedLatest commit: f4d1826 The changes in this PR will be included in the next version bump. This PR includes changesets to release 29 packages
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 |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: Your plan includes up to 10 reviews per rolling hour; 6 remain after this review. WalkthroughThe change adds durable session stream records with stable IDs, sequence numbers, and payloads. Session stream managers now support record retrieval, predicate filtering, peeking, exact consumption, cursor tracking, and redelivery. Waitpoints can return record envelopes and preserve legacy responses. The chat SDK exposes Merge Risk: 🟡 Moderate · up to The PR changes custom-agent message consumption and suspend/resume cursor handling, but merge readiness is not established because the waitpoint test path can validate an incorrect sequence contract and a persistence failure can prevent waitpoint registration, causing delayed recovery through timeouts. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
|
Hi @gtremper, thanks for your interest in contributing! This project requires that pull request authors are vouched, and you are not in the list of vouched users. This PR will be closed automatically. See https://github.com/triggerdotdev/trigger.dev/blob/main/CONTRIBUTING.md for more details. |
gtremper
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
5b39fb8 to
6abc529
Compare
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/core/src/v3/test/session-waitpoint-backend.ts (1)
165-193: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
deliveredSeqNumcan belong to a different record thanvalue.
onPartoverwritesdeliveredSeqNumfor every delivered part, butreader.read()returns only the first record. When the subscription delivers several parts before that read resolves, the returned pair mixes the first record'sdatawith the last part'sseqNum. Callers then consume a sequence that was never delivered and skip the records in between.Capture the first part id only.
🐛 Proposed fix
onPart: (part) => { const seqNum = Number.parseInt(part.id, 10); - if (Number.isFinite(seqNum)) { + if (deliveredSeqNum === undefined && Number.isFinite(seqNum)) { deliveredSeqNum = seqNum; } },
🧹 Nitpick comments (4)
packages/core/src/v3/sessionStreams/wireProtocol.ts (1)
72-88: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider a zod schema for the envelope parse.
parseSessionStreamWaitpointRecordvalidates the envelope with hand-written predicates. The repository guideline asks for zod validation inpackages/core. A smallz.object({ type: z.literal(...), version: z.literal(1), seqNum: z.number().finite(), data: z.unknown() })withsafeParsegives the same result and removes theascasts.This is optional. The current checks are correct.
As per coding guidelines: "Use zod for validation in packages/core and apps/webapp".
Source: Coding guidelines
apps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.ts (1)
161-168: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReuse
sessionStreamWaitpointOutputfor the race-check completion.This block re-implements the record-v1 envelope decision that
sessionStreamWaitpointOutputalready owns inapps/webapp/app/services/sessionStreamWaitpointCache.server.ts. The append route, the playground route, andwebhookEngine.server.tsall call the helper. Two copies of the same wire contract can drift when the envelope version changes.♻️ Proposed refactor
- value: - body.responseFormat === "record-v1" - ? serializeSessionStreamWaitpointRecord(record.data, record.seqNum) - : record.data, - type: - body.responseFormat === "record-v1" - ? SESSION_STREAM_WAITPOINT_RECORD_CONTENT_TYPE - : "application/json", - isError: false, + ...sessionStreamWaitpointOutput( + { id: result.waitpoint.id, responseFormat: body.responseFormat }, + record.data, + record.seqNum + ),Then import
sessionStreamWaitpointOutputfrom~/services/sessionStreamWaitpointCache.serverand drop the now-unused core imports on lines 4-5 if nothing else uses them.apps/webapp/app/services/sessionStreamWaitpointCache.server.ts (1)
116-129: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winRegister the waitpoint id before the format key.
The format write now runs first. If
redis.setthrows, the catch block swallows the error and theevalnever runs, so the waitpoint id never enters the set. The append handler then cannot wake the waiter, and the run only recovers on timeout.Run the
evalfirst, then write the optional format metadata. A missing format key degrades to raw data, which the SDK handles. A missing set member does not degrade gracefully.♻️ Proposed reordering
- if (responseFormat) { - await redis.set(buildFormatKey(waitpointId), responseFormat, "PX", effectiveTtlMs); - } else { - await redis.del(buildFormatKey(waitpointId)); - } - await redis.eval(ADD_WAITPOINT_SCRIPT, 1, key, waitpointId, String(effectiveTtlMs)); + + if (responseFormat) { + await redis.set(buildFormatKey(waitpointId), responseFormat, "PX", effectiveTtlMs); + } else { + await redis.del(buildFormatKey(waitpointId)); + }Note the race this introduces: an append between the two writes completes the waitpoint with raw data. That is the same degradation the SDK already handles, and it is safer than losing the wake-up.
packages/trigger-sdk/src/v3/sessions.ts (1)
784-798: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueRename the shadowing
responsevariable.The inner
const responseshadows the outer waitpointresponsethat the span attributes read at line 823. The current code is correct, because the inner binding is block-scoped. A later edit that moves code out of this block would silently read the wrong object.Rename it to
recordsResponse.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 7740311b-0d5e-4339-bee0-60096bb0ec4c
📒 Files selected for processing (16)
apps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/schemas/api.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/manager.test.tspackages/core/src/v3/sessionStreams/manager.tspackages/core/src/v3/sessionStreams/noopManager.tspackages/core/src/v3/sessionStreams/types.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/core/src/v3/test/test-session-stream-manager.tspackages/trigger-sdk/src/v3/sessions.tspackages/trigger-sdk/test/pending-message-drain.test.ts
🚧 Files skipped from review as they are similar to previous changes (4)
- packages/core/src/v3/sessionStreams/manager.test.ts
- packages/core/src/v3/sessionStreams/noopManager.ts
- packages/core/src/v3/test/test-session-stream-manager.ts
- packages/core/src/v3/sessionStreams/manager.ts
Included review availability: Your plan includes up to 10 reviews per rolling hour; 7 remain after this review.
📜 Review details
🧰 Additional context used
📓 Path-based instructions (17)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
**/*.{ts,tsx}: Use types over interfaces for TypeScript
Avoid using enums; prefer string unions or const objects instead
**/*.{ts,tsx}: Prefer static imports over dynamic imports. Only use dynamicimport()when:
- Circular dependencies cannot be resolved otherwise
- Code splitting is genuinely needed for performance
- The module must be loaded conditionally at runtime
Zod is pinned to a single version across the entire monorepo (currently3.25.76). When adding zod to a new or existing package, use the exact same version as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another).
Do not reintroduce V1.
Add crumbs as you write code — not just when debugging.
Do not invent new namespaces — pick from this table or ask first.
Files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
{packages/core,apps/webapp}/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use zod for validation in packages/core and apps/webapp
Files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use function declarations instead of default exports
Files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
**/*.ts
📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)
**/*.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 metrics such as UUIDs/IDs (envId, userId, runId, projectId, organizationId), unbounded integers (itemCount, batchSize, retryCount), timestamps (createdAt, startTime), or free-form strings (errorMessage, taskName, queueName)
When exporting OTEL metrics via OTLP to Prometheus, be aware that the exporter automatically adds unit suffixes to metric names (e.g., 'my_duration_ms' becomes 'my_duration_ms_milliseconds', 'my_counter' becomes 'my_counter_total'). Account for these transformations when writing Grafana dashboards or Prometheus queries
Files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
packages/core/**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (packages/core/CLAUDE.md)
Never import the root package (
@trigger.dev/core). Always use subpath imports such as@trigger.dev/core/v3,@trigger.dev/core/v3/utils,@trigger.dev/core/logger, or@trigger.dev/core/schemas
Files:
packages/core/src/v3/schemas/api.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/core/src/v3/sessionStreams/types.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
packages/**/*.{ts,tsx}: - Public packages (packages/*): Usebuild.
Always import from@trigger.dev/sdk. Never use@trigger.dev/sdk/v3or deprecatedclient.defineJob.
Files:
packages/core/src/v3/schemas/api.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.ts
packages/core/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
- packages/core (
@trigger.dev/core): Shared types. Import subpaths only (never root).
Files:
packages/core/src/v3/schemas/api.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/core/src/v3/sessionStreams/types.ts
apps/webapp/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)
apps/webapp/**/*.{ts,tsx}: Access environment variables through theenvexport ofenv.server.tsinstead of directly accessingprocess.env
Use subpath exports from@trigger.dev/corepackage instead of importing from the root@trigger.dev/corepath
Files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
apps/webapp/app/**/*.{ts,tsx}
📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)
apps/webapp/app/**/*.{ts,tsx}: For dashboard changes, visually verify the running Remix app with Chrome DevTools MCP, using snapshots, screenshots, interaction, and console-message checks as appropriate.
UseuseCallbackanduseMemoonly for context provider values, expensive derived data used as a dependency, or stable references required by dependency arrays; do not wrap ordinary event handlers or trivial computations.
Use named constants for sentinel or placeholder values instead of scattering raw string literals across comparisons.
Files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
apps/webapp/app/routes/**/*.ts
📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)
apps/webapp/app/routes/**/*.ts: Use Remix flat-file route conventions with dot-separated segments; for example,api.v1.tasks.$taskId.trigger.tsmaps to/api/v1/tasks/:taskId/trigger.
PAT-authenticated API routes must resolve their target organization or project within the caller's membership scope, using a membership filter or a helper such asfindProjectByReforresolveOrganizationForApiUser; RBAC authorization alone is insufficient.
Files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.ts
apps/webapp/app/**/*.ts
📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)
apps/webapp/app/**/*.ts: Never userequest.signalto detect client disconnects. UsegetRequestAbortSignal()fromapp/services/httpAsyncStorage.server.ts, which is wired to Express response close events.
Access environment variables through theenvexport fromapp/env.server.ts; never useprocess.envdirectly.
Always use PrismafindFirstinstead offindUnique.
Always use the$transactionhelper from~/db.server, never callprisma.$transactionor$replica.$transactiondirectly. Pass isolation levels as strings, useSerializablefor correctness-critical read-then-write invariants, and guard possibly undefined helper results when a definite value is required.
Files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
apps/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
apps/**/*.{ts,tsx}: - Apps and internal packages (apps/*,internal-packages/*): Usetypecheck. Never usebuildfor these — building proves almost nothing about correctness.
Always import from@trigger.dev/sdk. Never use@trigger.dev/sdk/v3or deprecatedclient.defineJob.
Files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
apps/webapp/app/v3/**/*.ts
📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)
New code must target Run Engine V2 through the singleton in
app/v3/runEngine.server.ts; do not reintroduce V1 execution paths. V1 branches may only reject or finalize gracefully with a clean 4xx.
Files:
apps/webapp/app/v3/webhookEngine.server.ts
packages/trigger-sdk/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
In the Trigger.dev SDK (packages/trigger-sdk), prefer isomorphic code like fetch and ReadableStream instead of Node.js-specific code
Files:
packages/trigger-sdk/test/pending-message-drain.test.tspackages/trigger-sdk/src/v3/sessions.ts
**/*.{test,spec}.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use vitest for all tests in the Trigger.dev repository
We use vitest exclusively. Never mock anything - use testcontainers instead.
Files:
packages/trigger-sdk/test/pending-message-drain.test.ts
packages/trigger-sdk/**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (packages/trigger-sdk/CLAUDE.md)
Always import from
@trigger.dev/sdk. Never use@trigger.dev/sdk/v3(deprecated path alias)
Files:
packages/trigger-sdk/test/pending-message-drain.test.tspackages/trigger-sdk/src/v3/sessions.ts
**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Test files go next to source files (e.g.,
MyService.ts->MyService.test.ts).
Files:
packages/trigger-sdk/test/pending-message-drain.test.ts
🧠 Learnings (25)
📚 Learning: 2026-03-22T13:26:12.060Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3244
File: apps/webapp/app/components/code/TextEditor.tsx:81-86
Timestamp: 2026-03-22T13:26:12.060Z
Learning: In the triggerdotdev/trigger.dev codebase, do not flag `navigator.clipboard.writeText(...)` calls for `missing-await`/`unhandled-promise` issues. These clipboard writes are intentionally invoked without `await` and without `catch` handlers across the project; keep that behavior consistent when reviewing TypeScript/TSX files (e.g., usages like in `apps/webapp/app/components/code/TextEditor.tsx`).
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-03-22T19:24:14.403Z
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 3187
File: apps/webapp/app/v3/services/alerts/deliverErrorGroupAlert.server.ts:200-204
Timestamp: 2026-03-22T19:24:14.403Z
Learning: In the triggerdotdev/trigger.dev codebase, webhook URLs are not expected to contain embedded credentials/secrets (e.g., fields like `ProjectAlertWebhookProperties` should only hold credential-free webhook endpoints). During code review, if you see logging or inclusion of raw webhook URLs in error messages, do not automatically treat it as a credential-leak/secrets-in-logs issue by default—first verify the URL does not contain embedded credentials (for example, no username/password in the URL, no obvious secret/token query params or fragments). If the URL is credential-free per this project’s conventions, allow the logging.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-05-18T08:21:27.694Z
Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3632
File: apps/webapp/sentry.server.ts:4-21
Timestamp: 2026-05-18T08:21:27.694Z
Learning: When handling Prisma error P1001 ("Can't reach database server") in TypeScript, don’t assume a single error shape. Prisma can surface P1001 via two different error classes/fields: `PrismaClientKnownRequestError` exposes it as `err.code === "P1001"` (common during mid-query connection drops), while `PrismaClientInitializationError` exposes it as `err.errorCode === "P1001"` (common on client startup failure). Therefore, predicates should use `err.code === "P1001" || err.errorCode === "P1001"`. Do not flag `err.code === "P1001"` as “unreachable/never matches,” as it is expected in production.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-05-18T08:21:27.694Z
Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3632
File: apps/webapp/sentry.server.ts:4-21
Timestamp: 2026-05-18T08:21:27.694Z
Learning: When handling Prisma errors for P1001 ("Can't reach database server"), do not assume it only appears under a single property name. Prisma may surface P1001 via either `PrismaClientKnownRequestError` (`err.code === "P1001"`, e.g., mid-query connection drops) or `PrismaClientInitializationError` (`err.errorCode === "P1001"`, e.g., client startup connection failure). To reliably detect the condition, check `err.code === "P1001" || err.errorCode === "P1001"`, and avoid review rules that would incorrectly flag `err.code === "P1001"` as unreachable/never-matching.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-13T19:53:13.759Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3937
File: packages/trigger-sdk/skills/realtime-and-frontend/SKILL.md:258-260
Timestamp: 2026-06-13T19:53:13.759Z
Learning: When reviewing code that uses `trigger.dev/react-hooks`’s `useRealtimeRun`, preserve the call signature where the first argument is the full realtime handle object (not `handle.id`). This is intentional to maintain type-safety and is consistent with the official docs; do not suggest changing the first argument from the handle object to `handle.id`.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-17T17:13:49.929Z
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 3948
File: apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.bulk-actions.$bulkActionParam/route.tsx:48-62
Timestamp: 2026-06-17T17:13:49.929Z
Learning: In triggerdotdev/trigger.dev, within `dashboardLoader`/`dashboardAction` (or similar context resolver code) whenever you resolve an organization ID from an organization slug for RBAC/enterprise authorization scope, always read from the primary Prisma client (`prisma`), not `$replica`. Using `$replica` can hit replica-lag and cause the RBAC lookup/authorization to run without the correct org scope (bypassing intended role enforcement). Implement the slug→org lookup with `prisma.organization.findFirst(...)` (or equivalent primary-client query) and add an inline comment documenting why the primary client is required (replica lag could lead to unscoped RBAC checks).
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-23T13:04:21.413Z
Learnt from: carderne
Repo: triggerdotdev/trigger.dev PR: 4023
File: apps/webapp/app/services/upsertBranch.server.ts:14-18
Timestamp: 2026-06-23T13:04:21.413Z
Learning: In TypeScript, it’s valid to `import { type X }` and then use `typeof X` in a type-only position, e.g. `type Alias = z.infer<typeof X>`. The `type` modifier suppresses the runtime import, but the type checker still has the full exported type so `z.infer<typeof X>` can resolve correctly. In code reviews, don’t flag this as a TypeScript compile error as long as `typeof X` is used in a type context (e.g., with `z.infer`, `type` aliases, generics), not as a runtime value.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-04T18:16:35.386Z
Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3836
File: apps/supervisor/src/backpressure/backpressureMonitor.ts:3-5
Timestamp: 2026-06-04T18:16:35.386Z
Learning: When reviewing TypeScript in this repo, apply the rule “prefer type aliases over interfaces” only to data/object shapes and union/intersection type modeling. If an interface is being used as a behavioral contract for collaborators to implement (e.g., method-shape interfaces that define required behavior, such as `BackpressureLogger` / `BackpressureSignalSource` in `apps/supervisor/src/backpressure/backpressureMonitor.ts`), keep it as an `interface` and do not flag it as a type-alias-vs-interface violation.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-09T17:58:04.699Z
Learnt from: 0ski
Repo: triggerdotdev/trigger.dev PR: 3879
File: apps/webapp/app/models/vercelIntegration.server.ts:619-630
Timestamp: 2026-06-09T17:58:04.699Z
Learning: In this codebase, outbound raw `fetch` calls should typically rely on Node/undici’s default request timeout (about ~300s) rather than adding a per-call `AbortController` + `setTimeout` wrapper inside individual functions (e.g. in files like `apps/webapp/app/models/vercelIntegration.server.ts`). During code review, do not flag the absence of a per-call timeout on a single `fetch` as an issue; if per-call timeouts are needed, they should be implemented via a codebase-wide convention (e.g., a shared fetch wrapper or documented pattern) rather than ad-hoc per-function changes.
Applied to files:
packages/core/src/v3/schemas/api.tsapps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tspackages/core/src/v3/sessionStreams/index.tspackages/core/src/v3/sessionStreams/wireProtocol.tspackages/trigger-sdk/test/pending-message-drain.test.tspackages/core/src/v3/test/session-waitpoint-backend.tspackages/trigger-sdk/src/v3/sessions.tspackages/core/src/v3/sessionStreams/types.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-05-12T21:04:05.815Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3542
File: apps/webapp/app/components/sessions/v1/SessionStatus.tsx:1-3
Timestamp: 2026-05-12T21:04:05.815Z
Learning: In this Remix + TypeScript codebase, do not flag a server/client boundary violation when a file imports only types from a module matching `*.server`.
Specifically, it’s safe to import types using `import type { Foo } from "*.server"` or `import { type Foo } from "*.server"` because TypeScript erases type-only imports at compile time and they emit no JavaScript, so they won’t cross the Remix server/client bundle boundary.
Only raise the boundary concern for value imports (e.g., `import { Foo }` without `type`, or `import Foo`), since those produce JavaScript output.
Applied to files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-06-25T18:21:51.905Z
Learnt from: carderne
Repo: triggerdotdev/trigger.dev PR: 4039
File: apps/webapp/app/routes/invite-revoke.tsx:0-0
Timestamp: 2026-06-25T18:21:51.905Z
Learning: During the Zod v4 migration in the triggerdotdev/trigger.dev webapp, ensure any imports from `conform-to/zod` use the Zod-4 subpath: `conform-to/zod/v4` (e.g., `import { parseWithZod } from "conform-to/zod/v4"`). Do not import from the package root `conform-to/zod`, because it is the Zod 3 implementation and may load Zod-3-only symbols (e.g., `ZodBranded`, `ZodEffects`), which can throw at module load (notably with `zod4.4.3`). This should be enforced across `apps/webapp/**/*` where helpers like `parseWithZod` and `conformZodMessage` are used.
Applied to files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-07-03T17:10:21.498Z
Learnt from: 0ski
Repo: triggerdotdev/trigger.dev PR: 4148
File: apps/webapp/app/models/orgMember.server.ts:149-168
Timestamp: 2026-07-03T17:10:21.498Z
Learning: In triggerdotdev/trigger.dev, `User.email` (Prisma schema: `internal-packages/database/prisma/schema.prisma`) currently does NOT use `citext` and does NOT have a `lower(email)` functional unique index. Therefore, do not introduce Prisma queries like `where: { email: { equals: <value>, mode: "insensitive" } }` (or any case-insensitive lookup) against `User.email`, because it can force sequential scans of the `users` table under load. During review, ensure email is normalized (e.g., lowercased/trimmed) before both writes and subsequent lookups, and if true case-insensitive behavior/uniqueness is required, implement it via a separate app-wide migration (e.g., switch to `citext` and/or add a functional unique index with backfill) rather than bolting it onto individual feature PRs.
Applied to files:
apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.tsapps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.tsapps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-03-29T19:16:28.864Z
Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3291
File: apps/webapp/app/v3/featureFlags.ts:53-65
Timestamp: 2026-03-29T19:16:28.864Z
Learning: When reviewing TypeScript code that uses Zod v3, treat `z.coerce.*()` schemas as their direct Zod type (e.g., `z.coerce.boolean()` returns a `ZodBoolean` with `_def.typeName === "ZodBoolean"`) rather than a `ZodEffects`. Only `.preprocess()`, `.refine()`/`.superRefine()`, and `.transform()` are expected to wrap schemas in `ZodEffects`. Therefore, in reviewers’ logic like `getFlagControlType`, do not flag/unblock failures that require unwrapping `ZodEffects` when the input schema is a `z.coerce.*` schema.
Applied to files:
apps/webapp/app/v3/webhookEngine.server.ts
📚 Learning: 2026-06-09T16:27:26.195Z
Learnt from: myftija
Repo: triggerdotdev/trigger.dev PR: 3878
File: apps/webapp/app/v3/services/computeTemplateCreation.server.ts:0-0
Timestamp: 2026-06-09T16:27:26.195Z
Learning: When working in triggerdotdev/trigger.dev code related to worker-group/region default resolution (e.g., defaultWorkerInstanceGroupId handling used by getGlobalDefaultWorkerGroup, getDefaultWorkerGroupForProject, and RegionsPresenter), do NOT add org-level featureFlags overrides in only one resolution site. That can cause template creation routing/decisions to diverge from actual run routing. If org-level override of the default region/worker group is required, it must be centralized in getGlobalDefaultWorkerGroup so every resolution path remains aligned.
Applied to files:
apps/webapp/app/v3/webhookEngine.server.ts
📚 Learning: 2026-05-05T09:38:02.512Z
Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3523
File: apps/webapp/app/routes/api.v3.batches.ts:178-181
Timestamp: 2026-05-05T09:38:02.512Z
Learning: When reviewing code that catches `ServiceValidationError` in `*.server.ts` files, do not blindly forward `error.status` to HTTP responses, because SVEs may be thrown with non-default statuses (e.g., 400/500) and forwarding them can cause client-visible behavioral regressions (e.g., surfacing 500s to clients). Prefer a safe default response status of `error.status ?? 422`, but only after confirming via the reachable call graph that the caught `ServiceValidationError` instances are expected to carry those non-default statuses; otherwise, normalize to `422` to avoid unexpected client-visible 5xx behavior.
Applied to files:
apps/webapp/app/v3/webhookEngine.server.tsapps/webapp/app/services/sessionStreamWaitpointCache.server.ts
📚 Learning: 2026-05-14T08:21:07.614Z
Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3614
File: apps/webapp/app/v3/mollifier/mollifierGate.server.ts:48-52
Timestamp: 2026-05-14T08:21:07.614Z
Learning: When using Trigger.dev v3 feature flags in the webapp, prefer the existing per-org gating mechanism supported by `flag()` via the `overrides` argument. Pass `Organization.featureFlags` (from `environment.organization.featureFlags`) as the `overrides` value; overrides must take precedence over the global `featureFlag` row. Do not require schema changes or add an `orgId` field to `FlagsOptions` for per-org gating—use the overrides pattern consistently (e.g., in gate flows like `resolveOrgFlag` and any server code that threads `environment.organization.featureFlags` into the gate call).
Applied to files:
apps/webapp/app/v3/webhookEngine.server.ts
📚 Learning: 2026-05-18T14:40:02.173Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3658
File: packages/core/src/v3/realtimeStreams/manager.test.ts:1-147
Timestamp: 2026-05-18T14:40:02.173Z
Learning: In this repo’s trigger.dev codebase, the “never mock — use testcontainers” guideline should only be applied to integration tests that talk to real external services (e.g., Redis, Postgres, S2). For unit tests that validate in-memory logic (e.g., deduplication/cache behavior in StandardRealtimeStreamsManager and similar module-boundary call counting), it is allowed to use Vitest mocks like `vi.fn()` and to stub/mock `ApiClient` objects to count calls or simulate in-process collaborators. Do not flag `vi.fn()`-based mocks as policy violations in these unit-test scenarios; reserve the rule for true external-service integration tests.
Applied to files:
packages/trigger-sdk/test/pending-message-drain.test.ts
📚 Learning: 2026-05-18T14:40:02.173Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3658
File: packages/core/src/v3/realtimeStreams/manager.test.ts:1-147
Timestamp: 2026-05-18T14:40:02.173Z
Learning: In the triggerdotdev/trigger.dev repo, the policy “Never mock anything — use testcontainers instead” should only be enforced for integration tests that interact with real external services (e.g., Redis, Postgres) via actual infrastructure. For unit tests that exercise pure in-memory logic (e.g., cache semantics) it is OK to stub collaborators such as `ApiClient` using Vitest (`vi.fn()`) to assert call counts or control behavior. Do not flag `vi.fn()`-based `ApiClient` stubs in unit tests as violations of the testcontainers policy.
Applied to files:
packages/trigger-sdk/test/pending-message-drain.test.ts
📚 Learning: 2026-05-19T22:37:47.286Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3671
File: packages/trigger-sdk/test/recovery-boot.test.ts:456-457
Timestamp: 2026-05-19T22:37:47.286Z
Learning: In `packages/trigger-sdk` (Trigger.dev SDK), `logger.warn` (and other SDK logger methods) should route to the Trigger.dev structured logger sink, not to `console.warn`. In SDK tests, `vi.spyOn(console, "warn")` (or similar console spies) should only be used to suppress stray console output; reviewers should not suggest asserting on `console.warn` spies to verify SDK-internal warning/fallback log behavior. Use the SDK’s structured-logger outputs/capture approach instead of console spies.
Applied to files:
packages/trigger-sdk/test/pending-message-drain.test.tspackages/trigger-sdk/src/v3/sessions.ts
📚 Learning: 2026-06-16T09:19:47.637Z
Learnt from: d-cs
Repo: triggerdotdev/trigger.dev PR: 3960
File: apps/webapp/test/prismaInfrastructureErrorCapture.test.ts:0-0
Timestamp: 2026-06-16T09:19:47.637Z
Learning: In this repo’s Vitest setup, `vitest.config.ts` uses `globals: true`, so identifiers like `vi`, `describe`, `it`, and `expect` are available as globals in Vitest test files. During code review, do not flag missing `vi`/`describe`/`it`/`expect` imports as a runtime error or correctness issue when they’re used in `*.test.ts/tsx` or `*.spec.ts/tsx` files. Explicit imports are still preferred for consistency, but they’re not required for runtime behavior.
Applied to files:
packages/trigger-sdk/test/pending-message-drain.test.ts
📚 Learning: 2026-08-16T18:36:58.179Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 4537
File: packages/trigger-sdk/test/normalizeKeyString.test.ts:1-2
Timestamp: 2026-08-16T18:36:58.179Z
Learning: For related SDK `chat.agent` tests in the Trigger.dev repository—including chat channels, handover, snapshot, and transport-event coverage—keep new test files under `packages/trigger-sdk/test/` rather than colocating them with the `packages/trigger-sdk/src/v3/` source files.
Applied to files:
packages/trigger-sdk/test/pending-message-drain.test.ts
📚 Learning: 2026-03-31T21:37:27.212Z
Learnt from: isshaddad
Repo: triggerdotdev/trigger.dev PR: 3283
File: docs/migration-n8n.mdx:19-21
Timestamp: 2026-03-31T21:37:27.212Z
Learning: When reviewing code in `packages/trigger-sdk/src/v3`, treat `tasks.triggerAndWait()` and `tasks.batchTriggerAndWait()` as real exported APIs. They are defined in `shared.ts` and re-exported via the `tasks` object in `tasks.ts`, and they take the task ID string as their first argument (not a task instance). This is distinct from the instance methods `yourTask.triggerAndWait()` and `yourTask.batchTriggerAndWait()`. Do not flag calls to `tasks.triggerAndWait()` or `tasks.batchTriggerAndWait()` as non-existent or incorrectly invoked.
Applied to files:
packages/trigger-sdk/src/v3/sessions.ts
📚 Learning: 2026-05-17T08:08:12.370Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3644
File: packages/trigger-sdk/src/v3/ai.ts:8695-8746
Timestamp: 2026-05-17T08:08:12.370Z
Learning: In the Trigger v3 session resume/streams logic, ensure session resumption uses sequence cursors rather than timestamps. Specifically: for each turn-complete control record written to `session.out`, include a `session-in-event-id` header whose value is the committed-consume cursor (`session.in.lastDispatchedSeqNum`). On boot/resume, scan `session.out` for the latest turn-complete record, read the `session-in-event-id` header, and seed the `sessionStreams` manager for `.in` using both `lastSeqNum` and `lastDispatchedSeqNum` so previously processed user messages are not replayed. Do not use `setMinTimestamp`/`lastOutTimestamp` for resume ordering in this flow.
Applied to files:
packages/trigger-sdk/src/v3/sessions.ts
📚 Learning: 2026-05-18T14:19:56.437Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3655
File: packages/trigger-sdk/src/v3/ai.ts:8667-8731
Timestamp: 2026-05-18T14:19:56.437Z
Learning: In the Trigger SDK (v3) when making raw `fetch` calls to the Trigger API (including override paths such as `createChatStartSessionAction`), set the request headers to match `ApiClient`: `Content-Type`, `Authorization`, and `x-trigger-source: "sdk"`. Also forward the current preview branch by setting `x-trigger-branch` to `apiClientManager.branchName`. Prefer using the shared `overrideRequestHeaders(accessToken)` helper instead of manually constructing headers, so requests route correctly to preview environments.
Applied to files:
packages/trigger-sdk/src/v3/sessions.ts
📚 Learning: 2026-03-26T09:02:07.973Z
Learnt from: myftija
Repo: triggerdotdev/trigger.dev PR: 3274
File: apps/webapp/app/services/runsReplicationService.server.ts:922-924
Timestamp: 2026-03-26T09:02:07.973Z
Learning: When parsing Trigger.dev task run annotations in server-side services, keep `TaskRun.annotations` strictly conforming to the `RunAnnotations` schema from `trigger.dev/core/v3`. If the code already uses `RunAnnotations.safeParse` (e.g., in a `#parseAnnotations` helper), treat that as intentional/necessary for atomic, schema-accurate annotation handling. Do not recommend relaxing the annotation payload schema or using a permissive “passthrough” parse path, since the annotations are expected to be written atomically in one operation and should not contain partial/legacy payloads that would require a looser parser.
Applied to files:
apps/webapp/app/services/sessionStreamWaitpointCache.server.ts
🔇 Additional comments (9)
packages/core/src/v3/sessionStreams/types.ts (1)
22-28: LGTM!Also applies to: 60-92, 127-127
packages/core/src/v3/sessionStreams/index.ts (1)
97-103: LGTM!apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.realtime.v1.sessions.$session.$io.append.ts (1)
16-19: LGTM!Also applies to: 120-148
apps/webapp/app/services/sessionStreamWaitpointCache.server.ts (2)
171-198: LGTM!Also applies to: 309-312
28-39: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚖️ Poor tradeoffMake record-v1 sequence loss observable and recoverable. When an append loses its idempotency claim, no
seqNumis available, so the waitpoint helper silently returns raw data even when record-v1 was requested. The client can then fall back to legacy cursor recovery and replay the record. Please recover the committed sequence for duplicate appends or surface the downgrade before completing the waitpoint, with consistent handling across both append routes and webhook redelivery.packages/core/src/v3/schemas/api.ts (1)
1672-1673: LGTM!packages/core/src/v3/test/session-waitpoint-backend.ts (1)
4-7: LGTM!Also applies to: 20-20, 79-79, 122-135
packages/trigger-sdk/src/v3/sessions.ts (1)
28-37: LGTM!Also applies to: 689-692, 719-728, 743-783, 799-813
packages/trigger-sdk/test/pending-message-drain.test.ts (1)
8-13: LGTM!Also applies to: 78-92, 271-333, 334-374, 376-410, 412-444
| if (seqNum !== undefined) { | ||
| sessionStreams.consumeRecord(this.sessionId, "in", seqNum); | ||
| sessionStreams.setLastSeqNum(this.sessionId, "in", seqNum); | ||
| } |
There was a problem hiding this comment.
🟡 A chat message can be answered twice after a suspended run wakes up
The message that woke the run is left sitting in the run's local inbox (no consumeRecord call at packages/trigger-sdk/src/v3/sessions.ts:806-809) whenever its position in the channel cannot be identified, so the loop can pick it up and answer it a second time.
Impact: A user can receive two responses to the same message, and the conversation history records it twice.
Why the record survives the resume now that the buffer is no longer cleared
Before this PR, session.in.wait() dropped the local buffer on disconnectStream and unconditionally bumped the seen-sequence cursor, so a record delivered through the waitpoint could not also be delivered from the buffer or replayed by the SSE tail. Now disconnectStream deliberately preserves buffered records (packages/core/src/v3/sessionStreams/manager.ts:375-391, packages/core/src/v3/sessionStreams/types.ts:127) and the only de-duplication is consumeRecord(seqNum) / setLastSeqNum(seqNum) guarded by if (seqNum !== undefined).
seqNum is undefined whenever the waitpoint output carries no record-v1 envelope and the legacy recovery lookup fails:
- an older webapp instance completed the waitpoint (raw
application/jsonoutput); - a new webapp instance completed it but had no append sequence to attach — in
apps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.ts:205-221appendSeqstaysundefinedwhen theX-Part-Idclaim was lost (retry/concurrent POST), andsessionStreamWaitpointOutputthen falls back to raw data (apps/webapp/app/services/sessionStreamWaitpointCache.server.ts:28-39); - the
readSessionStreamRecordsfallback throws, finds no match, or finds more than one match (packages/trigger-sdk/src/v3/sessions.ts:784-803).
In that case: (a) if the record landed on the still-live tail between waitpoint registration and disconnectStream, it is buffered and the next warm once() / chat.messages.next() returns it again; and (b) lastSeqNum is not advanced, so the reconnecting SSE tail resumes from before the record and re-delivers it.
A safe fallback would be to discard buffered records up to and including the record returned by the waitpoint (or at minimum drop the matching payload from the buffer) when the exact sequence cannot be recovered.
Prompt for agents
In SessionInputChannel.wait() (packages/trigger-sdk/src/v3/sessions.ts), the record delivered through the waitpoint is only removed from the local session-stream buffer and acknowledged when its S2 sequence number is known (record-v1 envelope, or a unique match from the legacy readSessionStreamRecords lookup). Since disconnectStream no longer clears the buffer (packages/core/src/v3/sessionStreams/manager.ts), a record that arrived on the still-live tail between waitpoint registration and disconnectStream stays buffered, and lastSeqNum is not advanced, so the same message can be returned again by the next warm once()/next() read or re-delivered by the reconnecting SSE tail — producing a duplicate turn. Note the sequence can also be unknown against a current server: the public append route leaves appendSeq undefined when the X-Part-Id idempotency claim is lost, so sessionStreamWaitpointOutput falls back to raw output. Consider making the unknown-sequence path defensive: e.g. drop buffered records whose payload matches the record just returned (or drop everything at/below the head that the waitpoint output corresponds to), so the resumed record cannot be handed to the loop a second time, while still leaving the persisted cursor conservative.
Was this helpful? React with 👍 or 👎 to provide feedback.
| #takeBufferedRecord( | ||
| key: string, | ||
| predicate: SessionStreamRecordPredicate | undefined | ||
| ): SessionStreamRecord | undefined { | ||
| const buffered = this.buffer.get(key); | ||
| if (!buffered || buffered.length === 0) return undefined; | ||
|
|
||
| const record = buffered[0]!; | ||
| if (predicate && !predicate(record)) return undefined; | ||
|
|
||
| buffered.shift(); | ||
| if (buffered.length === 0) { | ||
| this.buffer.delete(key); | ||
| } | ||
| this.#advanceLastDispatched(key, record.seqNum); | ||
| this.#drainOnceWaitersFromBuffer(key); | ||
| return record; | ||
| } |
There was a problem hiding this comment.
🔍 next() can stall behind a buffered record no one consumes
next() uses a predicate waiter that only ever matches the buffer head (#takeBufferedRecord / #drainOnceWaitersFromBuffer in packages/core/src/v3/sessionStreams/manager.ts:245-262,635-646), so if the head is a non-message record that no consumer takes, next() never resolves and hasPending() reports false even though messages are queued behind it. The docs assume every control record has its own consumer (docs/ai-chat/custom-agents.mdx:265-268), but a stop record is only consumed if the loop called chat.createStopSignal(); a hand-rolled loop that uses next() without a stop signal can deadlock its mailbox permanently. Worth documenting explicitly, or having next() skip/park kinds that have no registered consumer.
Was this helpful? React with 👍 or 👎 to provide feedback.
| lastDispatchedSeqNum(sessionId: string, io: SessionChannelIO): number | undefined { | ||
| return this.lastDispatchedSeqNums.get(keyFor(sessionId, io)); | ||
| const key = keyFor(sessionId, io); | ||
| const highWatermark = this.lastDispatchedSeqNums.get(key); | ||
| if (highWatermark === undefined) return undefined; | ||
|
|
||
| const unconsumedSeqNums = this.unconsumedSeqNums.get(key); | ||
| if (!unconsumedSeqNums || unconsumedSeqNums.size === 0) return highWatermark; | ||
|
|
||
| let earliestUnconsumedSeqNum = Infinity; | ||
| for (const seqNum of unconsumedSeqNums) { | ||
| earliestUnconsumedSeqNum = Math.min(earliestUnconsumedSeqNum, seqNum); | ||
| } | ||
|
|
||
| const safeCursor = Math.min(highWatermark, earliestUnconsumedSeqNum - 1); | ||
| return safeCursor >= 0 ? safeCursor : undefined; |
There was a problem hiding this comment.
🔍 Clamped cursor can be pinned indefinitely by one unconsumed buffered record
lastDispatchedSeqNum() now returns min(highWatermark, earliestUnconsumed - 1). Combined with disconnectStream no longer clearing the buffer, a single record that nothing ever consumes (an unrecognised kind, or a handover record on a non-handover boot — handoverInput only reads via waitWithIdleTimeout, it registers no on handler) permanently pins the value stamped as session-in-event-id on every subsequent turn-complete. The next worker boot then resumes .in from before that record and replays every later message, duplicating turns. Mitigated in practice because chat.messages.waitWithIdleTimeout drains buffer heads regardless of kind, but the failure mode is now persistent rather than reset at each suspend.
Was this helpful? React with 👍 or 👎 to provide feedback.
| idempotencyKey: options?.idempotencyKey, | ||
| idempotencyKeyTTL: options?.idempotencyKeyTTL, | ||
| tags: options?.tags, | ||
| lastSeqNum: sessionStreams.lastSeqNum(this.sessionId, "in"), | ||
| lastSeqNum: lastConsumedSeqNum, | ||
| responseFormat: SESSION_STREAM_WAITPOINT_RESPONSE_FORMAT, |
There was a problem hiding this comment.
🔍 wait() now registers with the consumed cursor, letting the server race-check re-serve already-received records
lastSeqNum sent to createSessionStreamWaitpoint switched from the received cursor to the clamped consumed cursor. The server race-check (apps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.ts:146-168) reads records[0] after that cursor, so it can now hand back a record the local tail already received and left buffered/unconsumed (e.g. a handover record). The message facade loops and discards non-message kinds while consumeRecord(seqNum) removes it from the buffer, so such a record would be silently dropped rather than reaching its intended consumer. Not flagged as a bug because the message wait paths perform a warm once() (predicate-free, drains any head kind) before suspending, which normally empties the buffer first — but it is a new reachable path worth confirming for the handover flow.
(Refers to lines 719-728)
Was this helpful? React with 👍 or 👎 to provide feedback.
2 participants
Summary
Adds two helpers for raw
chat.customAgent()loops:chat.messages.hasPending()checks whether the buffered head is a message without consuming it.chat.messages.next()consumes one message at a time, with an optional timeout.This lets a custom loop own message sequencing without advancing past input it has not handled. Records returned by
next()include stableidandseqNumfields.The same cursor rule now applies when
session.in.wait()suspends a run. It starts from the consumed cursor, keeps buffered records available, and commits only the exact record returned by the waitpoint. New servers return that sequence in a versioned envelope. The SDK falls back to a durable-record lookup with older servers.The waitpoint response format is stored separately from the waitpoint ID so rolling deploys remain compatible with older server instances.
Existing behavior for
peek(),on(), andwaitWithIdleTimeout()is unchanged.next()returnsundefinedwhen it times out.Testing
Changelog
Custom agents can now check for pending chat messages and consume them one at a time.
Checklist