Replace the legacy 5-attempt retry cap on SSEStreamSubscription with
indefinite retry on a bounded jittered backoff. Adds a force-reconnect
path so the chat transport can recover from silent-dead-socket cases
on mobile (background-kill, bfcache restore) without waiting for the
next backoff slot.
SSEStreamSubscription:
- maxRetries default Infinity (was 5), retryDelayMs 100ms (was 1s),
new maxRetryDelayMs cap (5s), retryJitter 50%
- retryNow(): wake an in-flight backoff
- forceReconnect(): drop current connection AND wake backoff
- fetchTimeoutMs (30s default): aborts stuck connect attempts that
block forever on dead sockets
- stallTimeoutMs (opt-in): force reconnect on silent reader
- nonRetryableStatuses (default [404, 410]): short-circuit retry
for stream-gone / session-closed
- Fixed listener leak where each retry accumulated an abort listener
on the user signal because finally only ran once the recursion
unwound. Cleanup now runs per-attempt via cleanupAttempt() in both
the catch (before recursion) and finally paths.
TriggerChatTransport (browser):
- online -> forceReconnect (existing socket may be stale)
- pageshow.persisted -> forceReconnect (Safari bfcache restore)
- visibilitychange -> visible only:
* hidden >= 30s -> forceReconnect
* hidden < 30s -> retryNow (cheap wake)
- stallTimeoutMs: 60s (sized over typical agent thinking pauses)
Tests: 13 vitest cases covering retry-past-legacy-cap, backoff cap,
jitter variance, retryNow short-circuit, abort-during-backoff,
forceReconnect during fetch and during read (verifies Last-Event-ID
resume on the resumed request), fetchTimeout, stallTimeout, 404/410
short-circuit, custom nonRetryableStatuses, 503 still retries.
Refs TRI-8903.
- inline prototype-pollution guards at JSON Patch assignment sites in chat-client.ts so CodeQL can statically verify them (Set.has() check upstream wasn't being traced)
- wrap JSON.parse(payloadStr) in playground action's start handler to return 400 on malformed JSON instead of 500
The previous pass rolled 26 changesets into 8 but the consolidated
descriptions read like docs (full API surface dumps, multiple sections,
docs-style headers). Rewrote each so they fit a release-notes bullet
list — short, what-shipped framing, with one or two snippets where they
help, no exhaustive type / option enumeration.
Two fixes from Devin's review on PR #3173.
## SessionTriggerConfig is missing 3 fields the playground UI shows
The playground sidebar (`PlaygroundSidebar`) renders working controls for
`maxDuration`, `version`, and `region`. The action received the form fields,
but `SessionTriggerConfig` didn't accept them so they were `void`-suppressed
and silently dropped. Runs ignored the user's max-duration cap, the version
pin didn't apply, and region selection had no effect.
- `packages/core/src/v3/schemas/api.ts` — add three optional fields to
`SessionTriggerConfig`: `maxDuration` (positive int, seconds),
`lockToVersion` (string), `region` (string). All three forward to the
matching field on `TaskRunOptions`.
- `apps/webapp/app/services/realtime/sessionRunManager.server.ts` — extend
`triggerSessionRun`'s `body.options` to thread the three fields through
to `TriggerTaskService` when present.
- `apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.action.tsx`
— fold the three form fields into `triggerConfig`; remove the `void`
suppressions.
## Playground transport's clientData becomes stale after edits
The route constructs `TriggerChatTransport` directly via `useRef` (to avoid
the React-version mismatch the hook had). The hook normally calls
`setClientData` whenever `clientData` changes, but this manual construction
bypassed that — so `clientData` was captured at construction and never
updated. Per-turn `metadata` merges (`this.defaultMetadata` in
`packages/trigger-sdk/src/v3/chat.ts`) used the stale initial value for
the whole conversation. `startSession` was already reading from the live
ref so session creation was unaffected; this only fixed the per-turn path.
- `apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.playground.$agentParam/route.tsx`
— add a `useEffect` that calls `transport.setClientData(...)` whenever
`clientDataJson` changes.
Changeset (patch, @trigger.dev/core) for the schema additions; server-
changes file for the webapp-only behaviour fix.
- typesVersions: add `v3/chat-client` mapping. The export was declared in
`tshy.exports` and the conditional export block but missing from
`typesVersions` — `attw --pack` flagged "@trigger.dev/core/v3/chat-client"
as `node10: 💀 Resolution failed`.
- chat.store JSON Patch: add an `assertSafeKey` guard at the assignment
sites in `removeAt` / `insertAt`. parseJsonPointer already rejects
`__proto__` / `constructor` / `prototype`, but CodeQL's prototype-pollution
analysis doesn't trace through the parser boundary — the local check at
the assignment keeps the static analysis happy and is also a real
defense-in-depth backstop against any future caller that bypasses
parseJsonPointer.
- typesVersions: add `ai/skills-runtime` mapping (was missing → check-exports
failed with NoResolution on `@trigger.dev/sdk/ai/skills-runtime`).
- chat.store JSON Patch: reject `__proto__`, `constructor`, `prototype`
segments at parseJsonPointer. Closes the two CodeQL prototype-pollution
alerts on chat-client.ts:108 / :120 — a malicious patch like
`{ op: "replace", path: "/__proto__/x", value: 1 }` would otherwise
walk into Object.prototype via `parent[lastToken] = value`. Throws a
clear error on the whole patch instead.
The realtime stream caps each record at ~1 MiB. Today the chat.agent path
through StreamsWriterV2 surfaces a generic S2Error from deep in the
batching layer when a chunk exceeds the cap, with no chunk-type context
and no guidance for callers.
Add a pre-write byte check in StreamsWriterV2.initializeServerStream that
fires before the chunk hits the underlying batcher, and a typed
ChatChunkTooLargeError carrying the chunk's discriminant (type/kind),
serialized size, and cap. Also exports an isChatChunkTooLargeError guard
from the SDK so callers can branch cleanly.
Threshold is 1 MiB minus 1 KiB to leave headroom for the JSON record
envelope. The error message links to the new docs pattern (Pattern:
ID-reference for large tool outputs / out-of-band streams.writer for
run-scoped data).
Server-to-agent flows (`AgentChat` SDK class + cli-v3 MCP `start_agent_chat`) were building `triggerConfig.basePayload` without the `trigger: "preload"` and `messages: []` fields the agent runtime branches on. Result: the auto-triggered first run had `payload.trigger === undefined`, neither `onPreload` nor `onChatStart` fired, and `onTurnStart`'s DB-write blew up with PrismaClient "No record found" because no Chat row had been created.
Browser-mediated flows already had this right (`chat.createStartSessionAction` in `ai.ts:6951`); the server-side path now mirrors that shape.
- packages/trigger-sdk/src/v3/chat-client.ts — `AgentChat.ensureStarted` adds the two fields to `basePayload`. `chat-client-test`'s `pong` orchestrator now returns the assistant text instead of an empty string.
- packages/cli-v3/src/mcp/tools/agentChat.ts — same fix on `start_agent_chat`'s `createSession` call. Also drops the redundant separate `apiClient.triggerTask(...)` call: `POST /api/v1/sessions` now auto-triggers the first run and returns its runId, so a second trigger from the MCP would have produced a competing run on the same session. Use `session.runId` from the create response. The `preload` input flag becomes a no-op signal (response message wording only) since session-create always triggers a run now.
Verified end-to-end against local:
- `chat-client-test` orchestrator returns `{ text: "pong" }`
- MCP `start_agent_chat` → `send_agent_message` x2 → `close_agent_chat` succeeds, both turns reuse the same runId
Migration 029 added `task_kind` to `task_runs_v2`, and TASK_RUN_COLUMNS was updated, but the four test-data arrays in src/taskRuns.test.ts were not. ClickHouse rejects the inserts with "Cannot parse input: expected ',' before: ']'" because the array length is one short of the column count. All 7 internal/clickhouse unit-test shards on PR #3173 fail on this.
Pre-existing bug (predates my Sessions work) but blocking CI; verified the fix locally — `vitest run src/taskRuns.test.ts` now passes 4/4.
CreateSessionRequestBody now requires `taskIdentifier` and `triggerConfig` because Sessions are task-bound (the server reuses the config for every run scheduled by the session — initial + continuations). The MCP `agentChat` tool was still passing only `{ type, externalId }` from the pre-Sessions-as-run-manager API. Add `taskIdentifier: input.agentId` and a minimal `triggerConfig` with `basePayload: { chatId, ...clientData }` and the `chat:{chatId}` auto-tag.
Unblocks typecheck on PR #3173 (and Windows CLI v3 e2e, which builds cli-v3 in pre-test).
UX cleanup discovered during the Sessions e2e sweep. Three changes, one commit because they all live in the chat input row / debug panel area:
- Explicit "Preload" button next to "Send" that only renders when the chat has no messages and no session yet. Clicking calls transport.preload(chatId), which mints the session and triggers the first run with trigger:"preload". Self-hides once session is truthy. Replaces the inert "Preload new chats" sidebar checkbox (the visible `+ New Chat` button only navigated and never called transport.preload — preloadEnabled was wired through the context but read by nobody, since ChatApp.tsx is no longer the mounted chat sidebar). Drops the dead preloadEnabled state + checkbox from chat-settings-context, chat-sidebar, chat-sidebar-wrapper, and the chat-app.tsx legacy code path.
- Debug panel "Runs → View in dashboard" row, gated on dashboardUrl + a new NEXT_PUBLIC_TRIGGER_PROJECT_DASHBOARD_PATH env var. Resolves to the runs-list page filtered by chat:<chatId> tag — so opening the link drops you straight into the run list for the active chat. Threads the new prop through chat-view → chat → DebugPanel.
- window.__chat.sendAction(action) bridge wrapper that delegates to transport.sendAction(chatId, action). Lets smoke tests drive aiChatHydrated's actionSchema (undo/rollback/remove/replace) without reaching into React internals.
The reference's Chat / ChatSession Postgres tables are shared between local and test cloud targets. A row created with one webapp's PAT and lastEventId is poison if you switch the .env to the other target and reuse the same chatId — the transport gets a 401 or resumes from a sequence that doesn't exist on the other backend.
Adds:
- prisma/reset-chats.sql: TRUNCATE Chat, ChatSession (User survives — it's upserted by onPreload/onChatStart anyway).
- package.json db:reset:chats script wrapping prisma db execute --file.
Run `pnpm run db:reset:chats` between target switches and at the top of every smoke test. Codified in the ai-chat-e2e skill as a required prereq.
The reference's onTurnStart was using chat.defer for the messages write, which is fire-and-forget. If a user refreshed the page mid-stream, getChatMessages returned [] (the deferred write hadn't landed yet), useChat hydrated with empty initialMessages, and the resumed SSE stream pushed the assistant into an empty array — the user's message vanished from the rendered conversation forever.
Switch to await prisma.chat.update(...) so the write is durable before chat.agent begins streaming. Verified end-to-end against test cloud: mid-stream refresh now yields [user, assistant] with no duplication.
Aligns with the Warning added to docs/ai-chat/patterns/database-persistence.mdx in the docs branch.
- chat.createStartSessionAction now adds 'chat:{chatId}' as the first tag on the triggered run, matching the browser-mediated transport.doStart path. Customer-provided tags merge after, capped at 5. Without this, runs created via server actions were untagged, breaking the dashboard chat-id filter.
- references/ai-chat onTurnComplete persists Chat.messages and ChatSession.lastEventId in a single prisma.$transaction. Two parallel reads on the next page load (Promise.all([getChatMessages, getSessionForChat])) can otherwise observe messages post-write but lastEventId pre-write. The transport then resumes from the stale cursor and replays this turn's chunks on top of the already-persisted assistant message, duplicating the render. Applies to both the main chat.agent and the hydrated variant.
Persistent listeners registered via `session.in.on(...)` (e.g. chat.agent's
`stopInput.on` for the stop signal) must not 'consume' chunks. They filter
by `kind` and ignore non-matching chunks, so previously `#dispatch` was
silently dropping any chunk that arrived before a once-waiter had registered.
This race surfaced on test cloud (network round-trip > sync subscribe-time)
but not locally (zero-latency). Symptom: chat.agent's first user message
landed in S2 before `messagesInput.waitWithIdleTimeout` registered its
waiter, the tail received it, `#dispatch` saw the `stopInput` handler and
returned without buffering, the message was gone, the waitWithIdleTimeout
fell through to a durable waitpoint, and the race-check skipped seq 0
(since the tail's onPart had advanced `lastSeqNum` to 0).
Fix: when no once-waiter exists, invoke handlers AND buffer the chunk.
Handlers observe; they don't consume.
chat.agent now runs on top of the Session-as-run-manager primitive.
Public surface (`chat.agent({...})`, `useTriggerChatTransport`,
`chat.store` / `chat.defer` / `chat.history`, `AgentChat`) is unchanged;
the wiring underneath moves from per-run streams to the durable Session
row that owns its own runs.
Transport (TriggerChatTransport):
- Drop `getStartToken`. Replace with
`startSession({chatId, taskId, clientData}) => {publicAccessToken}` —
wraps a server action that calls `chat.createStartSessionAction`.
Idempotent on `(env, externalId)`.
- `clientData` (typed via `withClientData`) is threaded through
`startSession`'s params, so the first run's `basePayload.metadata`
matches per-turn `metadata`. Live-updated via `setClientData` when
the hook's `clientData` option changes.
- Drop transport-level `triggerConfig` / `triggerOptions` /
`idleTimeoutInSeconds`. All trigger config lives server-side in the
customer's `chat.createStartSessionAction(taskId, options)`.
- `transport.preload(chatId)` and lazy first `sendMessage` both route
through `startSession`, deduped via the in-flight pendingStarts map.
- `ChatSession` persistable shape drops `runId`; just `{lastEventId}`.
chat.agent runtime:
- New `chat.createStartSessionAction(taskId, options?)` — server-side
wrapper that calls `sessions.start` with `basePayload.{messages:[],
trigger: "preload"}` defaults plus the customer's overrides. Returns
`{sessionId, runId, publicAccessToken}`.
- `chat.requestUpgrade` calls `apiClient.endAndContinueSession` before
emitting the `trigger:upgrade-required` chunk. Server orchestrates
the swap; browser keeps streaming across the run handoff.
Webapp dashboard:
- Playground: `startSession` + `accessToken` both wired through the
Remix action (idempotent server-side start path). Preload button
now works. New session proxy routes for HEAD/GET on `/out` and POST
on `/in/append`; old run-stream proxies deleted.
- Run inspector Agent tab: SSE proxy now uses the canonical addressing
key (externalId if set, else friendlyId), matching what the agent
writes via `session.out`. Fixes the case where the Agent tab read
from a different S2 stream than the agent wrote to.
References (ai-chat):
- `chat-view` useEffect dance gone (just hydrates `initialSession`).
- `chat-app` `transport.preload(id)` routes through `startSession`.
- New `upgrade-test` agent + sidebar option for exercising
`chat.requestUpgrade` end-to-end.
- `ChatSession` schema simplified: drop `runId` / `sessionId`, keep
`publicAccessToken` + `lastEventId`.
- `chat-client-test` fixed for the new transport shape.
- Hello-world smoke stubs gutted to TODO placeholders — sessions
are now task-bound, so standalone-session smokes need rewriting.
Companion to the SDK opt-in. Webapp routes read X-Peek-Settled from the
request and skip the tail peek when it isn't set, so active
send-a-message paths can't race a stale trigger:turn-complete. Docs
note the opt-in semantics; .server-changes records the change for the
deploy log.
The webapp's peek-tail-settled shortcut on /realtime/v1/sessions/:id/out
previously fired on every io=out subscription. That race-tripped active
send-a-message paths: the SSE peek would see the prior turn's
trigger:turn-complete record before the newly-triggered run wrote its
first chunk, return wait=0 + X-Session-Settled:true, and close the
stream before any of the new turn's records landed.
Make the peek opt-in via an X-Peek-Settled: 1 request header. Only
TriggerChatTransport.reconnectToStream sets it (true reload-resume case
where settling early is fine); sendMessages and the rest leave it off
and stay on the normal long-poll. On the server side,
streamResponseFromSessionStream gates the peek on options.peekSettled
and skips it otherwise.
- apps/webapp: read X-Peek-Settled from the request, thread to
streamResponseFromSessionStream
- packages/trigger-sdk/chat.ts: peekSettled option on
subscribeToSessionStream + reconnectToStream sets it; sendMessages
does not
- docs/ai-chat/client-protocol.mdx + docs/sessions/reference.mdx:
document the opt-in semantics
- .server-changes/session-out-settled-signal.md: record the change
Pulls PENDING_MESSAGE_INJECTED_TYPE, ChatTaskWirePayload, and the
client-data inference helpers out of ai.ts (~7000 lines, statically
imports node:* via the skills runtime) into a new ai-shared.ts that
stays free of node-only imports. chat.ts and chat-react.ts now reach
for these via ai-shared so browser bundlers don't trace ai.ts's entire
module graph (Turbopack rejected the node: builtins outright).
Three dashboard-scoped stream routes were passing request.signal into
realtimeStream.streamResponse. That signal is broken under
Remix+Express (see apps/webapp/CLAUDE.md, nodejs/node#55428 — the chain
is severed when Remix internally clones the Request), so when a user
closes their dashboard tab the signal never fires. The underlying
RedisRealtimeStreams.streamResponse loops while(!signal.aborted) over
XREAD BLOCK and only exits on its 15s inactivity timeout; the S2 path
keeps the upstream fetch open for up to its 60s wait window.
Thread getRequestAbortSignal() through:
- resources/orgs/.../runs/$runParam/realtime/v1/streams/$runId/$streamId
- resources/orgs/.../runs/$runParam/realtime/v1/streams/$runId/input/$streamId
- resources/orgs/.../playground/realtime/v1/streams/$runId/$streamId
Each picks up the Express res.on('close')-backed signal that fires
reliably when the downstream client disconnects.
TriggerChatTransport.reconnectToStream previously returned null any time
state.isStreaming was falsy, which included undefined. That meant a
caller who dropped isStreaming from their ChatSession persistence (a
reasonable simplification now that the server can tell the client when
a session is settled via X-Session-Settled on the session.out SSE)
would get null on every reconnect and the UI would never resume
streaming.
Tighten the check to state.isStreaming === false so only an explicit
false triggers the fast-path skip. Undefined now falls through to open
the SSE and let the server decide — on a settled session the server
already closes the connection in ~1s via wait=0, so there is no 60s
hang to worry about.
Backward compatible: callers who still persist and hydrate isStreaming
(true/false) keep today's behavior exactly; callers who drop the flag
now get the server-authoritative path.
Final Phase F cleanup — `CHAT_STREAM_KEY`, `CHAT_MESSAGES_STREAM_ID`,
and `CHAT_STOP_STREAM_ID` were meaningful only when chat.agent I/O
lived on run-scoped Redis streams. The Session migration moved all
chat I/O onto the backing Session's `.in` / `.out` channels, so these
constants stopped describing how anything is addressed months ago and
have been dead-weight re-exports since.
Dropped from the public surface:
- `@trigger.dev/core/v3/chat-client` no longer exports the three
constants. The file keeps `ChatStoreChunk` + `applyChatStorePatch`
(the chat.store primitive's shared types).
- `@trigger.dev/sdk/ai` no longer re-exports them via the
`CHAT_STREAM_KEY` / `CHAT_MESSAGES_STREAM_ID` / `CHAT_STOP_STREAM_ID`
aliases introduced by the migration commit.
- Deletes `packages/trigger-sdk/src/v3/chat-constants.ts` (the shim
that bridged core's definitions to the SDK's public surface).
What stayed the same:
- `chat.stream.id` / `chat.messages.id` / `chat.stopSignal.id` still
contain the literal strings `"chat"` / `"chat-messages"` /
`"chat-stop"` — inlined as opaque breadcrumbs rather than
user-consumable constants. Telemetry attrs keep the same values,
so dashboards/spans don't shift.
- All runtime behavior is untouched. The `chatStream` / `messagesInput` /
`stopInput` facades still delegate through the Session handle
exactly as before; only the constant symbols are gone.
Migration note for external callers:
Anyone still importing the old constants should migrate to the
session primitives:
- `streams.writer(CHAT_STREAM_KEY, …)` → `sessions.open(sessionId).out.writer(…)`
- `streams.input(CHAT_MESSAGES_STREAM_ID)` → `sessions.open(sessionId).in.on(…)`
(filtered by `chunk.kind === "message"`)
- `streams.input(CHAT_STOP_STREAM_ID)` → `sessions.open(sessionId).in.on(…)`
(filtered by `chunk.kind === "stop"`)
Validated
- 86/86 SDK tests green.
- Webapp typecheck clean (core types used in SpanPresenter + AgentView
are untouched).
- ai-chat UI smoke passes end-to-end: new chat → send "Say hi in
three words." → first assistant text in 4.9s → sessionId + runId +
lastEventId all set.
Fixes the last set of issues that were blocking TriggerChatTransport
from running end-to-end against the ai-chat reference. Smoke now
passes: new chat → send → streamed assistant reply in ~4s → second
turn reuses the same session + run, lastEventId advances 10 → 21.
SDK (@trigger.dev/sdk)
- RenewRunAccessTokenParams carries the durable sessionId alongside
chatId + runId. Server-side renew handlers MUST mint the renewed
PAT with read:sessions:{sessionId} + write:sessions:{sessionId}
scopes (in addition to the existing run scopes) — without them,
the first append after expiry 401s on session.in/append and sends
the transport into a renew loop. transport.renewRunPatForSession
looks up the cached sessionId off `this.sessions` so existing
renew callers just need to spread the new field through.
- transport.preload(chatId) on the triggerTask callback path no
longer calls apiClient.createSession from the browser. Matches
sendMessages: when triggerTaskFn is configured the server action
(chat.createTriggerAction) creates the Session with its secret
key and returns sessionId alongside the run PAT. Browser
deployments using the callback flow therefore never need
write:sessions on any browser-facing token.
- chat.test.ts renew-spy assertions updated to match the new
{chatId, runId, sessionId} shape — 86/86 tests still green.
Webapp
- POST /api/v1/sessions gets allowJWT: true + corsStrategy: "all".
Pre-fix, the route rejected any CORS-preflighted browser call,
which broke the transport's direct accessToken fallback path
(sessions.create from the browser).
- POST /realtime/v1/sessions/:session/:io/append now exports both
{ action, loader }. The route builder installs the OPTIONS
preflight handler on the loader; without a loader export, the
preflight returned 400 ("No loader for route") and Chrome
surfaced the follow-up POST as net::ERR_FAILED. Same pattern
already in use on /api/v1/tasks/:id/trigger.
references/ai-chat
- Switch both chat-app.tsx and chat-view.tsx from
accessToken: getChatToken to triggerTask: triggerChat. This path
has the server action create the Session server-side with the
secret key, so the browser never hits POST /api/v1/sessions and
the returned PAT already carries the session scopes needed for
session.in/out.
- renewRunAccessTokenForChat(chatId, runId, sessionId?) now mints
tokens that include read:sessions:{sessionId} +
write:sessions:{sessionId} alongside the run scopes. Both call
sites thread the sessionId from the SDK's renew callback params.
- Drop executeJs / runInSecureSandbox / runInPRReviewSandbox to
decouple ai-chat trigger dev from the isolated-vm native binary
(its darwin-arm64 prebuild is broken against node 20.20.0 on
the current toolchain). Deletes src/lib/secure-sandbox.ts and
src/lib/pr-review-sandbox.ts, removes the executeJs tool from
chatTools, the secure-exec-bridge esbuild plugin from
trigger.config.ts (and its companion node-stdlib-browser-stub),
and the `secure-exec` dependency from package.json. E2B-backed
executeCode stays. If a future session needs the in-process V8
sandbox back, reintroduce through a different module (or pin a
prebuilt binary) to avoid this failure mode.
Smoke drove via the window.__chat bridge from Chrome DevTools MCP —
no click-based interaction needed.
Two coupled changes that together unblock end-to-end browser smoke
testing of TriggerChatTransport in the ai-chat reference and, more
broadly, let Next.js + Webpack client bundles pull types from
@trigger.dev/sdk/ai without hitting node: imports.
@trigger.dev/sdk
- New subpath @trigger.dev/sdk/ai/skills-runtime
(src/v3/agentSkillsRuntime.ts) owns the node-only skill tool
impls: runBashInSkill (node:child_process) + readFileInSkill
(node:fs/promises, node:path, with path-traversal guard).
- ai.ts drops the top-level node:child_process / node:fs/promises /
node:path imports. The auto-injected loadSkill / readFile / bash
tools in createAgentSkillTools() load the runtime via a
computed-string dynamic import (let path = "./agentSkillsRuntime.js";
await import(path)) — webpack can't statically trace the expression
so it drops the dependency from the client graph. Worker runtimes
resolve the relative import normally, so bash + readFile keep
working end-to-end on the server.
- Why it matters: even type-only imports from @trigger.dev/sdk/ai
(for example CompactionChunkData or the full tool-set type chain
that derives ChatUiMessage via InferUITools) trigger webpack to
trace ai.js. Pre-split, that trace hit node:child_process and
failed the client build with UnhandledSchemeError. With the split,
ai.ts's top-level graph is pure — no node: at the top — so type
consumers compile cleanly.
references/ai-chat
- components/chat.tsx extends the window.__chat test bridge with
session-era state (session / sessionId / lastEventId) and
generic waiters (waitForStatus + waitForMessage +
waitForFirstAssistantText) with configurable timeouts and clean
rejection. A driver (Chrome DevTools MCP, Playwright, etc.) can
now exercise the chat end-to-end through eval'd JS:
await window.__chat.send("hi");
const t = await window.__chat.waitForFirstAssistantText();
No more click-driven smokes. Existing steerOnToolCall +
steerAfterDelay / queueAfterDelay / promote helpers stay.
- Inlines a local structural CompactionChunkData type so
chat.tsx doesn't pull from @trigger.dev/sdk/ai for a single type
assertion. Defensive — the subpath split fixes the underlying
build issue, this just keeps the chat.tsx module graph minimal.
- Fixes a stale ChatSessionState shape in the DebugPanel session
prop type (sessionId is now optional, runId optional).
Known limitation (not in this commit)
Running the live UI smoke still requires a working chat-agent
backend for ai-chat, which depends on isolated-vm having a
prebuilt darwin-arm64 binary for node 20.20.0. On this machine
`pnpm rebuild isolated-vm` fails (node-gyp toolchain issue),
which is orthogonal to the session migration. Bridge
infrastructure is validated (all keys mount on window.__chat;
SDK tests 86/86 pass); exercising the send->stream->stop flow
end-to-end against the ai-chat agent is blocked on the native
build.
Migrates the dashboard's Agent tab (span inspector) onto the backing
Session's .out / .in channels so it stays in sync with
TriggerChatTransport, the server-side AgentChat, and the MCP chat
tools after the chat.agent -> Sessions migration.
Webapp
- SpanPresenter.server.ts extracts agentSession from the run payload:
prefers the explicit sessionId that TriggerChatTransport and
chat.createTriggerAction now thread through; falls back to chatId
for pre-Sessions agent runs (the session resource route accepts
either form via resolveSessionByIdOrExternalId).
- Span route (runs.$runParam.spans.$spanParam) threads agentSession
through AgentViewAuth. agentView is only minted when we have an
identifiable session — runs without one render a loading spinner
without subscribing.
- New dashboard resource route
resources.orgs.../runs.$runParam/realtime/v1/sessions/$sessionId/$io
proxies S2RealtimeStreams.streamResponseFromSessionStream under
dashboard session auth. The run param binds the resource hierarchy
(keeps callers from subscribing to arbitrary sessions); the session
identity is verified against the environment. GET-only — appends go
through the public session API, not the dashboard.
- AgentView.tsx:
- AgentViewAuth grows `sessionId: string`; `useAgentRunMessages`
threads it into the effect dep array and URL construction.
- Subscription URLs collapse from two run-scoped paths
(.../streams/{runId}/chat + .../streams/{runId}/input/chat-messages)
to one session base (.../sessions/{sessionId}/{out|in}).
- Local CHAT_STREAM_KEY / CHAT_MESSAGES_STREAM_ID constants dropped.
- `.in` parser switches from raw ChatTaskWirePayload to ChatInputChunk
tagged union: only kind: "message" chunks surface user messages
(pulled from chunk.payload.messages); kind: "stop" is ignored.
- `.out` parsing is unchanged — session v2 SSE already delivers
parsed UIMessageChunk objects via record.body.data.
SDK type fixes (byproducts)
- TriggerChatTransportOptions.sessions.sessionId is now optional so
pre-Sessions localStorage state (chatId -> {runId, token, lastEventId})
hydrates without migration. The runtime already `continue`s when
sessionId is missing and lets ensureSession upsert on next send;
the type just catches up.
- chat.test.ts session-change accumulator shape widened to match the
new runtime state (adds optional runId / sessionId fields).
Smoke
Opened a completed test-agent run (sessionId threaded via prior smoke
test) in the dashboard. Agent tab rendered:
- user message from initialMessages seed
- assistant reply streamed over session.out
Both SSE endpoints returned 200; no console errors. Full SDK test
suite still passes (86/86).
Rewires the three MCP agent-chat tools onto the Session primitive so
they stay in sync with TriggerChatTransport and the server-side
AgentChat after the chat.agent -> Sessions migration.
Tools affected: start_agent_chat, send_agent_message, close_agent_chat.
All live in packages/cli-v3/src/mcp/tools/agentChat.ts.
Changes
- Drop imports of CHAT_STREAM_KEY / CHAT_MESSAGES_STREAM_ID /
CHAT_STOP_STREAM_ID from @trigger.dev/core/v3/chat-client. Add a
local ChatInputChunk type + serializeInputChunk helper that mirrors
the transport's wire format (JSON.stringify({ kind, payload })).
- start_agent_chat: call apiClient.createSession({ type:
"chat.agent", externalId: chatId }) before triggering. The call is
idempotent on externalId so two MCP clients targeting the same
chatId converge. Thread sessionId into the trigger payload so the
agent's sessions.open(payload.sessionId) finds the backing session.
- send_agent_message: replace
sendInputStream(runId, CHAT_MESSAGES_STREAM_ID, payload) with
appendToSessionStream(sessionId, "in",
serializeInputChunk({ kind: "message", payload })). Fall-back path
on send failure re-triggers on the same session (reuse sessionId,
swap runId) instead of creating a new chat.
- close_agent_chat: send { kind: "message", payload: { trigger:
"close", ... } } via appendToSessionStream so the agent's turn loop
exits cleanly — matches the transport's close semantics.
- collectAgentResponse: subscribe URL moves from
/realtime/v1/streams/{runId}/chat to
/realtime/v1/sessions/{sessionId}/out. Session SSE uses v2/batch
format which already delivers parsed UIMessageChunk objects via
record.body.data, so the chunk-switch logic is unchanged.
trigger:upgrade-required path keeps the same session and triggers
a new run — previously it reused the old /streams/{newRunId}/chat
URL, now the URL is stable across runs on the same session.
- Scopes: write:inputStreams -> read:sessions + write:sessions. The
former was the transport's old input-stream write capability; the
session endpoints are the new surface.
- ChatSession state grows a sessionId field (friendlyId session_*).
runId stays but is now a live-run hint rather than durable identity.
Known limitation: the MCP server binary was spawned by Claude Code
at session start from the pre-migration bundle and stays in memory
for the lifetime of the Claude session — runtime verification has to
wait for the next session restart. Build passes; dist bundle
contains the new createSession / appendToSessionStream /
realtime/v1/sessions / Session ID references.
On-ramp doc for future Claude sessions and customer-facing docs.
Captures the state of the chat.agent system after the Session
migration (phases A-E + test infra) so the next session doesn't
have to reconstruct it from git log + code:
- Why the migration (run-scoped streams -> Session primitive).
- Session primitive crash course (externalId idempotency,
SessionHandle.in / .out, SSE resume, S2 direct writes).
- Chat mapping: one Session per chat, externalId = chatId,
ChatInputChunk tagged union, session-scoped PATs.
- ASCII flow diagrams for first message / subsequent turns / stop /
upgrade-required.
- Module layout (SDK / core / webapp), token mint sites (3 of them),
key invariants, public API surface (unchanged / grown / added).
- Known follow-ups (Phase F deferred: MCP agentChat tool, AgentView
dashboard component, ai-chat Next.js UI smoke, constant deletion).
- Smoke test sequences + git trail so a future reader can bisect.
Lives under .claude/architecture/ (repo-local notes directory, not
shipped to customers).
Unblocks the unit tests after the chat.agent -> Sessions migration
(phases B/C/D). Before: 43 passed / 43 failed (35 in chat.test.ts + 10
mockChatAgent + 2 skillsRuntime). After: 86 passed / 0 failed.
Core (@trigger.dev/core/v3/test)
- TestSessionStreamManager: in-memory SessionStreamManager keyed on
(sessionId, io) mirroring TestInputStreamManager. Dispatch rules
match production with one test-only tweak — when a record arrives
and only handlers are registered (no .once waiter), it's buffered
for the next once() instead of discarded. Production doesn't need
this because the SSE tail naturally serializes records after the
agent's turn-loop has re-registered a waiter; tests send
synchronously right after turn-complete, so without the buffer
the next waitWithIdleTimeout loses the message.
- runInMockTaskContext installs the manager via
sessionStreams.setGlobalManager, exposes drivers.sessions.in.send
/ .close, and tears down on exit.
SDK (@trigger.dev/sdk/v3/test)
- __setSessionOpenImplForTests hook in sessions.ts lets the harness
override sessions.open(id) with an in-memory SessionHandle.
SessionHandle constructor now accepts { in?, out? } overrides.
- TestSessionOutputChannel extends SessionOutputChannel and
intercepts pipe / writer / append into a shared TestSessionOutState
(chunks + listener registry). Never constructs SessionStreamInstance
so it avoids initializeSessionStream / StreamsWriterV2 entirely.
- mockChatAgent rewritten: drops CHAT_MESSAGES_STREAM_ID /
CHAT_STOP_STREAM_ID / the "chat" output stream key. sendMessage /
sendRegenerate / sendAction push ChatInputChunk { kind: "message",
payload } via drivers.sessions.in.send. sendStop pushes
{ kind: "stop" }. Turn-complete detection moves from
drivers.outputs.onWrite to a TestSessionOutputChannel listener.
chat.test.ts
- New URL-predicate helpers at the top (isSessionCreateUrl,
isTriggerTaskUrl, isSessionOutSubscribeUrl,
isSessionStreamAppendUrl) + defaultSessionCreateResponse /
defaultAppendResponse so every global.fetch mock speaks the
same vocabulary.
- Bulk-updated all 25 mock blocks: added session-create handler
(transport's accessToken path now lazily upserts via POST
/api/v1/sessions before trigger), swapped /realtime/v1/streams/
for /realtime/v1/sessions/ URL matchers, and replaced
(streams/ && /input/) append-URL matchers with
isSessionStreamAppendUrl.
- Three tests updated for new semantics: onSessionChange fires
twice on first message (ensureSession -> sessionId only, then
triggerNewRun -> adds runId + isStreaming). Async-token call
count goes 1 -> 2 on first message because ensureSession and
trigger both resolve the token with purpose: "trigger".
- "minimal wire payloads" test's body parsing updated — session.in
append body is a raw JSON.stringify({ kind, payload }) string,
not a { data } wrapper.
- Replaced the vestigial "custom streamKey URL" test with a
"subscribes to the backing Session's .out" assertion. streamKey
option is a no-op under sessions; removal can land in a follow-up.
- One test (stream closes without control chunk) legitimately
needs 9s for SSE-close fallback — bumped its timeout to 15s.
pipeChat (the internal that auto-pipes a chat.agent's returned
streamText result to the chat output) was still calling
streams.pipe(CHAT_STREAM_KEY, stream) — a run-scoped run-streams
path. After the session migration, the module-level facades
(chatStream, messagesInput, stopInput) routed correctly, but
pipeChat bypassed the facade and went straight to the old
run-scoped pipe. Result: the turn-complete control chunk reached
the session.out subscriber (written via chatStream.writer in
writeTurnCompleteChunk) but every streamed UIMessageChunk from the
LLM's turn was written to the dead run-scoped stream and never
surfaced on session.out.
Swap the pipe target to chatStream.pipe (the session-routed
facade). The target / streamKey options still type-check for
API parity but are no longer meaningful — sessions are the
address, and sub-agents that need to write to a parent chat open
the parent's Session explicitly. Smoke now catches all 14 chunks
(start / start-step / text-start / 7x text-delta / text-end /
finish-step / finish / trigger:turn-complete) with ids 0 through
13 from session.out, match: true.
Also adds references/hello-world/src/trigger/chatAgentSmoke.ts —
end-to-end validation:
- sessions.create with externalId = chatId
- trigger test-agent with {chatId, sessionId, messages, …}
- handle.out.read(...) SSE subscribe, capture chunks by id+type
- sessions.close on completion
Triggered from the dashboard or MCP as chat-agent-smoke. Requires
OPENAI_API_KEY in the dev env (the test-agent uses
openai:gpt-4o-mini).
Rewires the server-side AgentChat class in chat-client.ts onto the
Session primitive, matching the browser transport's shape.
- ChatSession persistence and SessionState internal state now key on
sessionId (friendlyId). runId is optional, just a 'live run' hint.
- triggerNewRun upserts the backing Session via sessions.create
(idempotent on externalId = chatId) before triggering so sessionId
rides along in payload.
- sendRaw, steer, sendAction, close, stop all go through
appendToSessionStream(sessionId, 'in',
serializeInputChunk({kind: …})). Stop becomes {kind: 'stop'};
messages become {kind: 'message', payload}; actions and close go
through the message payload with trigger='action' / 'close'.
- Subscribe moves from /realtime/v1/streams/{runId}/chat to
/realtime/v1/sessions/{sessionId}/out. Records arrive as JSON
strings; the loop parses them back into objects before the
trigger:turn-complete / trigger:upgrade-required dispatch.
- Upgrade-required path keeps the same Session, swaps runId only.
- Drops the CHAT_STREAM_KEY / CHAT_MESSAGES_STREAM_ID /
CHAT_STOP_STREAM_ID imports from chat-constants.js — chat-client.ts
no longer references the legacy stream keys (the constants file
itself will be deleted in Phase F along with the three references
still in ai.ts's re-exports and chat-constants.ts itself).
Server-side auth uses apiClientManager.accessToken (the env secret
key), which has full scopes — no token-scoping changes needed here.
The browser transport's token-scope updates (Phase E) already cover
the client side.
Rewires chat.agent's internal I/O and TriggerChatTransport's send +
subscribe paths onto the Session primitive. Minimum token-scope work
included so the transport's session endpoints actually authenticate.
Phase B — chat.agent internals (ai.ts)
- New ChatInputChunk tagged union (`kind: "message" | "stop"`) —
replaces the two-stream split (chat-messages + chat-stop) with a
single Session `.in` channel.
- New chatSessionHandleKey locals slot populated at run start from
`payload.sessionId ?? payload.chatId`. Every module-level helper
now resolves to the per-run session handle.
- Module-level `chatStream`, `messagesInput`, `stopInput` become thin
facades over the session. `chatStream` mirrors
`RealtimeDefinedStream<UIMessageChunk>` and delegates to
`handle.out`. `messagesInput` / `stopInput` mirror
`RealtimeDefinedInputStream<…>` and filter `.in` by kind — the two
internal `.on()`/`.waitWithIdleTimeout()` callers and the
`chat.messages` / `chat.createStopSignal` public exposures keep
their existing shapes.
- Every `streams.writer(CHAT_STREAM_KEY, …)` callsite swaps to
`chatStream.writer(…)` so all chat output flows through
`session.out` → `SessionStreamInstance` → direct-to-S2.
- Threaded `sessionId` through `ChatTaskWirePayload` /
`ChatTaskPayload` / `ChatTaskRunPayload` so advanced users can
`sessions.open(sessionId)` directly from `run()`.
Phase C — TriggerChatTransport (chat.ts)
- `ChatSessionState` keys durable identity on `sessionId` (friendlyId);
`runId` becomes an optional hint about whether a run is live.
- `ensureSession(chatId)` lazily upserts the Session via
`apiClient.createSession({type: "chat.agent", externalId: chatId})`
on the direct `accessToken` path. Idempotent — two tabs on the
same chat converge.
- `sendMessages`, `sendPendingMessage`, `stopGeneration`,
`sendAction` all go through `appendToSessionStream(sessionId, "in",
serializeInputChunk({kind: …}))` — one endpoint, one tag per
record.
- SSE subscribe URL moves from `/realtime/v1/streams/{runId}/chat` to
`/realtime/v1/sessions/{sessionId}/out`. The old run-scoped
`subscribeToStream` is replaced by `subscribeToSessionStream`.
Incoming chunks come back as JSON strings on the session channel
(server wraps records as `{data, id}` on S2), so the subscribe
loop parses them back into objects to keep the rest of the control
flow (turn-complete / upgrade-required / skipToTurnComplete)
unchanged.
- Upgrade-required re-trigger keeps the same Session and swaps only
the runId + token.
- `getSession` / `setSession` / `setOnSessionChange` / persistence
shape all grow a `sessionId` field (runId now optional).
Phase E — minimum token scopes
- `chat.createTriggerAction` (server side) now creates the Session
before triggering so it can (a) thread `sessionId` into the run
payload and (b) mint a token with both run and session scopes.
Returns `sessionId` in its result so the transport can skip its
own `sessions.create` call on the server-side-trigger path.
- `TriggerChatTaskResult` gains optional `sessionId`.
- The two in-run PAT refresh sites (preloadAccessToken,
turnAccessToken) add `read:sessions:{sessionId}` +
`write:sessions:{sessionId}` alongside the existing run scopes.
Known follow-ups (deferred to later passes)
- Phase D: `AgentChat` / `ChatStream` in chat-client.ts still uses
the old `/realtime/v1/streams/{runId}/chat` path. Used by server-
side task-to-task compositions, not the browser transport.
- Phase F: delete CHAT_STREAM_KEY, CHAT_MESSAGES_STREAM_ID,
CHAT_STOP_STREAM_ID from chat-constants.ts + ai-chat smoke verify.
Build the client-side half of the Session channel extensions that the
sessions PR shipped on the server. Pairs with POST
/api/v1/runs/:runFriendlyId/session-streams/wait and the
append-fires-waitpoints wiring on the session append handler.
Extend SessionHandle with two asymmetric channels mirroring the
run-scoped streams primitives:
- .in (SessionInputChannel) mirrors streams.input. on / once / peek /
wait / waitWithIdleTimeout for the task to consume; send for
external clients to produce. .wait / .waitWithIdleTimeout suspend
the run on a session-stream waitpoint; it resumes when a record
lands on .in, same semantics as streams.input.wait on a run-scoped
input stream.
- .out (SessionOutputChannel) mirrors streams.define. append / pipe /
writer for the task to produce records — all three route through
SessionStreamInstance -> StreamsWriterV2 for uniform parsed-object
serialization on the subscribe side. read returns an SSE subscription
for external consumers.
The two channels are disjoint classes with zero overlapping methods.
SessionHandle is { id, in, out } so directional tags stay at every
call site. No public initialize() — S2 credentials are an internal
detail of pipe / writer.
Core
- StandardSessionStreamManager + sessionStreams global: SSE-backed
tail with once/on/peek buffering, auto-reconnect, lastSeqNum
resume. Keyed on {sessionId, io}. Registered in dev- and managed-
run workers; taskExecutor clears handlers at run end alongside
input streams.
- SessionStreamInstance: S2-only parallel of StreamInstance. Fetches
session S2 creds via initializeSessionStream and pipes through
StreamsWriterV2.
- ApiClient.createSessionStreamWaitpoint — calls the new server route.
Reference
- references/hello-world/src/trigger/sessionsSmoke.ts now exercises
.out.writer alongside .out.append.
- references/hello-world/src/trigger/sessionsWaitSmoke.ts (new) —
end-to-end waitpoint validation. Orchestrator suspends on
.in.waitWithIdleTimeout; a delayed sender task fires the waitpoint
via .in.send; orchestrator resumes with the payload. match: true.
Client-side pair to the Session primitive server PR (TRI-8627).
Run-scoped streams.pipe / streams.input are untouched.
@trigger.dev/core ApiClient
- createSession / retrieveSession / updateSession / closeSession —
zodfetch against /api/v1/sessions control plane
- listSessions — CursorPagePromise<SessionItem>, follows the runs/waitpoints
convention (page[size], page[after], page[before] + filter[*])
- initializeSessionStream — PUT /realtime/v1/sessions/:session/:io,
returns S2 creds in headers (feeds StreamsWriterV2 directly)
- appendToSessionStream — POST …/append
- subscribeToSessionStream — reuses SSEStreamSubscription for SSE
subscribes (auto-retry, Last-Event-ID resume, abort propagation), so
session subscribers get the exact same semantics as runs.fetchStream.
Returns AsyncIterableStream<T>.
@trigger.dev/sdk sessions namespace
- sessions.create / retrieve / update / close / list — wraps the ApiClient
with the standard tracer + accessoryAttributes + mergeRequestOptions.
Returns ApiPromise / CursorPagePromise.
- sessions.open(id) returns a SessionHandle with .out and .in
SessionChannels. Each channel exposes append / send / subscribe /
initialize. The handle is polymorphic on friendlyId or externalId.
- auth.ts adds the `sessions` permission on PublicTokenPermissionProperties
so auth.createPublicToken({ read: { sessions: ["session_abc"] } }) works.
Reference
- references/hello-world/src/trigger/sessionsSmoke.ts — idempotent
Trigger.dev task that exercises every code path (control-plane CRUD,
polymorphic lookup, list with tag/type/status/externalId filters, cursor
pagination, out.initialize + append + subscribe SSE round-trip, in.send,
close + idempotent re-close). Trigger via
mcp__trigger__trigger_task(taskId: "sessions-smoke").
Verified live against the local webapp (project hello-world): 10/10
steps pass end-to-end, S2 round-trip returns appended chunks through the
shared SSEStreamSubscription pipeline.
Two correctness fixes caught during end-to-end validation:
1. Resolve skill.path relative to the file that called skills.define(),
not the project root. The resource catalog already captures filePath
on each SkillManifest — use it to compute the source folder.
2. In dev, copy skill bundles to {workingDir}/.trigger/skills/ (where
the worker's cwd resolves). In deploy, keep copying to
{outputPath}/.trigger/skills/ so the Dockerfile COPY . /app lands
them at /app/.trigger/skills/.
Also upgrade the skill-discovery failure log from debug to warn so
config mistakes surface in the dev console instead of disappearing
silently.
Finally, update the ai-chat reference's aiChat.run() to pass chatTools
through chat.toStreamTextOptions({ tools: chatTools }) instead of
spreading them after — the auto-injected loadSkill/readFile/bash tools
would otherwise get overwritten by the explicit tools: chatTools key.
Full Phase 1 for the new ai.skills primitive — SDK + CLI, no
backend. Developer-authored folders (SKILL.md + scripts/references/
assets) discovered at build time, bundled into the deploy image at
/app/.trigger/skills/{id}/, and auto-wired into streamText at
runtime via the loadSkill/readFile/bash tools.
Adds a time-utils example skill to the ai-chat reference: two bash
scripts (now.sh, add.sh) plus a timezones.txt cheat-sheet, wired
into the aiChat agent via chat.skills.set() in onChatStart and
onPreload. Exercises the full pipeline end-to-end.
Changeset: patch bump for @trigger.dev/sdk, @trigger.dev/core,
@trigger.dev/build, trigger.dev.
New first-class bundling step (not a build extension): after esbuild
produces the worker bundle, fork the indexer locally to discover
skills registered via ai.skills.define(), validate each skill's
SKILL.md, and copy the folder into {outputPath}/.trigger/skills/{id}/.
Hooks into both buildWorker() (deploy) and devSession's updateBundle
(dev) right after createBuildManifestFromBundle and before the
extension onBuildComplete hook, so extensions can observe the
annotated manifest.skills. The existing Dockerfile COPY picks up the
new .trigger/skills/ subdirectory without changes.
Also: managed-index-worker and dev-index-worker now emit
resourceCatalog.listSkillManifests() in the INDEX_COMPLETE message
so downstream stages can see the skill list.
Part 3/3 of Phase 1 for the new ai.skills primitive.
skills.define({ id, path }) registers a skill with the resource
catalog and returns a SkillHandle. SkillHandle.local() reads the
bundled SKILL.md from ./.trigger/skills/{id}/ at runtime, parses
frontmatter, and returns a ResolvedSkill ready for chat.skills.set().
chat.skills.set([...]) stores resolved skills for the current run.
chat.toStreamTextOptions() auto-injects the skills preamble into the
system prompt and merges three tools — loadSkill, readFile, bash —
scoped per-skill with path-traversal guards and output caps (64 KB
stdout/stderr, 1 MB readFile). Bash executes in the worker container
with the turn's abort signal, no sandbox — skills are developer code.
Shared packages/build/src/internal/copyFiles.ts extracted from the
additionalFiles extension so the CLI's built-in skill bundler and the
existing extension share one glob + copy implementation.
Part 2/3 of Phase 1 for the new ai.skills primitive.
SkillMetadata + SkillManifest zod schemas alongside the existing
task/prompt ones. registerSkillMetadata / listSkillManifests /
getSkillManifest on ResourceCatalog (both Standard and Noop), wired
through the ResourceCatalogAPI facade. BuildManifest + WorkerManifest
gain an optional `skills` array so the built-in CLI bundler can
annotate discoveries and the indexer can report them.
Part 1/3 of Phase 1 for the new ai.skills primitive.
run() is invoked with trigger: "action" after onAction processes a
typed action, but the type previously omitted it. Adding it lets
users cleanly short-circuit the LLM call for actions that don't
need a response (e.g. user-initiated compaction):
if (trigger === "action") return;
Exit the loop after the current turn completes without the
upgrade-required signal that chat.requestUpgrade() sends. Use when an
agent finishes its work on its own terms — one-shot responses, goal
achieved, budget exhausted — instead of waiting idle for the next
user message. Callable from run(), chat.defer(),
onBeforeTurnComplete, or onTurnComplete.
Resolves TRI-8391.
Surface the AI SDK's FinishReason on TurnCompleteEvent and
BeforeTurnCompleteEvent. Gives hooks a clean signal for distinguishing
a normal turn end from one paused on a pending tool call (HITL flows
like ask_user). Undefined for manual pipeChat() or aborted streams.
Drives a chat.agent definition through real turns offline — send
messages, actions, and stop signals; inspect captured chunks; assert
on hook order. Pre-seed dependencies via setupLocals so hooks read
test instances (DB clients, stubs) via locals.get() instead of
leaking through untrusted clientData.
Adds ai-chat reference tests exercising the harness across basic
flow, onValidateMessages, hydrateMessages, and actions.
In-memory managers for locals, lifecycle hooks, runtime, input streams,
and realtime streams, plus a mock TaskContext. Lets task code be driven
end-to-end without hitting the Trigger.dev runtime — send data into
input streams, inspect chunks written to output streams, and pre-seed
locals for dependency injection.
Eric Allam