feat(webapp): dashboard agent — UI - #4529

kathiekiwi · 2026-08-07T12:39:00Z

Stacked on #4418. Merge that first.

The UI slice of the dashboard agent: the side panel, the chat transport wiring, message and card rendering, suggested prompts, and chat history. #4418 works without this — the system is simply invisible. The diff is mostly components, so the notes below cover only the three decisions you can't read off the markup. Behavior and a hands-on walkthrough live in GUIDEBOOK.md, which lands with #4525.

Decisions worth knowing

Action rows always render at the end of a turn. The model's emission order isn't trusted for layout, so action blocks are split out of the stream and appended last. Display only — answered stays keyed on the emission index.
The last-chat memory is org-true. It's keyed by the chat's own organization, and a foreign or deleted chat comes back as a 404 the client treats as gone, rather than an empty chat it keeps around.
A dead stream self-heals from the settled transcript. Terminal records are written to the chat row after the client's stream closes, so the panel re-reads it. The poll gate is any unfinished turn — a dangling tool part, not just an open investigation.

Notes

Gated by canAccessDashboardAgent; no behavior change with the flag off.
Page marks: handle.agentPageContext on 47 routes, ~20 lines each.
Entry points: Ask Trigger button, ⌘J, Help & Feedback. The old ⌘I and ?aiHelp= links keep working.

Screenshots

… row The hand-built row stopped satisfying every column the authenticated-environment mapper reads, so both proxy cases failed. Stubbing the lookup keeps the fixture independent of the row's columns.

Route conflicts were the tab-title work meeting the agent page-context handle: both sides kept, duplicate meta exports resolved to pageMeta, duplicate imports merged with unused bindings dropped. Lockfile regenerated from the merged manifests.

…lowlist Replaces https://*.googleusercontent.com (a host with public write access) with CSP_IMG_SRC_ALLOWLIST: exact origins only, https outside development, deduplicated, bad entries warned about instead of failing the boot.

…ts message Classify a failed tool result locally into one of seven categories and send only the label; the message is dropped with every other free-text field. Unrecognised failures are unknown rather than guessed, and a bare string error field is now withheld too.

…the message withheld Also reuse the policy's errored-output check instead of a second copy of it.

…ack to its condition A per-condition fallback identified the condition rather than the submit, so a re-watch could replay a stale terminal outcome from the retention window.

A refusal that won the race kept the reserved watch id, so the user was told nothing was created while that watch stayed active.

…batch order A tick that could read nothing now moves the group's fairness key only, so a watch with a permanently broken reader stops crowding out the rest of an over-cap group. Dueness and the streak facts still follow the last real check.

… say

…t-wide routes The environments and runs listings are project-wide, so an environment-scoped user-actor token could read every environment its user can reach. Both routes now resolve the claim into a mandatory filter, and a conflicting request filter is refused rather than overridden.

…ntity The direct PAT authentication path returned identity only, so a user-actor token reaching it (admin routes and other direct callers) lost its environment scope. The claims now ride on the authentication result itself.

…ed token can do A user-actor token declaring no scope cap could mint an environment JWT with any scopes it asked for. The exchange now clamps the minted scopes to the actor's own ability, so a capless token is read-only, and only mints for its claimed environment.

…own timeout

…ad of re-deciding it replay() re-ran subscribe() for an already-recorded `created` submission. A retry that succeeded could flip the ledger to `enabled`, but the confirmation in the transcript is append-once, so the user kept being told email was unavailable while the system believed it was on. The replay now reads recordedExternalNotification() and takes no external decision. An attempt that dies before subscribing or before its outcome is recorded leaves the row `pending`, and the normal creation path subscribes on the retry.

… a colleague's The create-watch response matched any watch-alert channel in the project, so a second member was told they were subscribed while the mail went to the first. The channel's deduplication key is the only record of whose it is, so state resolution, subscribe and unsubscribe now share one owner lookup.

…n patch A recorded outcome is immutable now, so nothing calls it.

Settling the investigations row was invisible to the user. The panel builds the winning revision from the transcript's own `tool-render_view` parts and never reads that table, so a turn that ran out of steps left the card at `in_progress` forever: the database believed the investigation had finished while a refresh still showed "Working...". `settleOpenInvestigations` now returns the revisions it committed, and `onTurnComplete` appends each as one more card revision — after the transcript write and id-deduped on `investigation-settlement:{id}:{revision}`, so a failed append leaves the card visibly unclosed rather than silently lost, and a retry can't stack a second card. The card-building and the latest-revision reader move out of the watch lane and into the runtime both lanes share, so there is one shape, not two. The watch lane keeps its own message id: it dedupes on the action, not the revision.

…tles The sweep settled the row and appended nothing, so it visibly fixed nothing: the chat kept rendering the last card it had, which was still "Working…". The settle now returns the state and revision it wrote, and the sweep appends that as the closing card revision on the chat — id-deduped on `investigation-settlement:{id}:{revision}`, so a retried run can neither stack a second card nor open a second investigation. The append is scoped by chat id: a sweep runs off any session and has no user in context, unlike the turn lane.

… image sources

… user-actor token Binding a delegated token to its environment claim on the project-wide routes also refused any token that carries no claim at all, which the public PAT exchange used by MCP and the CLI is allowed to issue. Line the project-wide helper up with its neighbours: a claimless dashboard-agent token is still refused, everything else stays project-wide.

## What & why This is the system behind the Dashboard Agent — an assistant that answers questions about a project's runs, errors, queues, deploys and health, and can investigate failures end to end. The agent runs as a chat.agent task in its own Trigger project. It has no access to the main database or ClickHouse; all platform data is read through the public API using a delegated, read-only user token. Everything here is behind `canAccessDashboardAgent` and inert with the flag off. The UI that mounts the panel lands in #4529. ## Stack `#4418` (this, base) ← `#4529` UI ← `#4525` Watch ← `#4516` storybook gallery. The scenario/contract reference for the whole stack is `internal-packages/dashboard-agent/GUIDEBOOK.md` (it lands on the Watch branch): it states, per feature, what makes each thing happen and where that is decided. ## What's inside **Agent runtime and tools** — `internal-packages/dashboard-agent`: prompt, tool set (API reads, TRQL query, docs, navigation, evidence/investigations, repo source), conversation compaction, a prompt-prefix token budget pinned by snapshot test, and sampled LLM-judged turn evals. The package cannot import webapp server code, which is what makes the "no DB access" claim structural rather than a convention. **Contracts** — `internal-packages/dashboard-agent-contracts`: `trigger://` URIs, intents, and the block envelope every rendered card travels in. **Conversation store** — `internal-packages/dashboard-agent-db`: drizzle over postgres-js in its own `trigger_dashboard_agent` Postgres schema, plus one additive migration. **Auth boundary** — the user-actor token gains an optional environment claim; one guard (`userActorEnvironment.server.ts`) enforces it so routes don't each re-derive the rule. Token minting, cap ceiling, and the RBAC fallback path for self-hosted. **Transport** — webapp resource routes that mint the token and proxy each turn, and SDK-side mid-turn reconnect. **Public API the agent reads through** — orgs, projects, environments, runs, queue metrics, workers, a run's commit metadata, repo snapshot, reports, and `POST /api/v1/query`. **Reports** — the health report's layout is declared once and shared by the card, the markdown surface and the JSON/MCP surface, so the same report reads the same in the dashboard, the terminal and an editor. **Block renderers** — the report and investigation cards the flows above already emit (`app/components/dashboard-agent/`). The panel that hosts them, and the rest of the chat UI, is #4529. **Query safety and CSP** — see below. ## Key decisions - **The agent is a separate Trigger project, not webapp code.** It reads platform data over the public API with a delegated user-actor token whose `cap` ceilings it to read scopes. No Prisma, no ClickHouse, no webapp imports. - **The PAT-only auth helper now refuses user-actor tokens.** This is an intentional behavioral change: its callers consume only a bare userId and do not enforce delegated-token capabilities. Actor-aware routes continue through the scoped route builders instead. - **RBAC fallback builds a delegated token's ability from its own cap**, never the blanket ability a PAT gets (read-only when the token declares none). Without this, the agent's read-only cap would buy a write JWT on self-hosted. - **Org creation checks RBAC only for user-actor tokens, and only after the env gate**, so an install with `ORG_CREATION_API_ENABLED` off returns 404 rather than 403, and an ordinary PAT never consults an ability the route has no org to scope. Both orderings are pinned by test. - **The query path is read-only in depth.** TRQL rejects write statements at the grammar level (they don't parse, rather than being filtered), ClickHouse runs with `readonly=1`, and the org/project/env filters are injected server-side from the credential — the request body cannot widen scope. An unparseable query denies instead of falling through to the permissive resource. - **Document-wide img-src CSP.** Remote images are an outbound-request/exfiltration surface, so the policy permits only own-origin/data/blob, the required SSO avatar hosts, and the favicon endpoint. Operators can add exact origins through CSP_IMG_SRC_ALLOWLIST; wildcard hosts and bare schemes are intentionally not allowed. - **The chat transport reconnects on a mid-turn EOF** (`@trigger.dev/sdk`). A body that ends without a turn-complete is terminal only when the server says `X-Session-Settled: true`; otherwise the transport resubscribes from `lastEventId` with bounded backoff, and any record re-earns the budget. Previously a closed long-poll window or a proxy restart left the reply stuck as if still generating. - **Conversations live in their own datastore**, schema-scoped and foreign-key-free (it references `organizationId`/`userId` by id, because in cloud it is a different database). It is a display read-model for the History tab and transport resume; `chat.agent`'s object-store snapshot remains the model's source of truth. - **Deterministic first.** Reports and health checks contain no LLM — they are computed from the same data the dashboard shows, and the model only narrates and links them. That is what makes a number in an answer auditable. ## Testing - 63 new test files, run with `pnpm run test --filter webapp` and per-package vitest. Heaviest coverage on the auth boundary (`userActorPatOnlyBoundary`, `userActorTokenClaimsAndScopes`, `contextlessPatRoutes`, `rbacFallbackBranch`), TRQL read-only, the report layout, and the SDK reconnect. - The agent package has a separate eval lane (`pnpm run test:evals`, `vitest.eval.config.ts`) that hits the real model, so it never runs in `pnpm test`. - Live-tested against a local stack scenario by scenario; the GUIDEBOOK lists the condition each behaviour is expected under, which is what those runs were checked against. ## Changelog `.server-changes/dashboard-agent.md`, plus changesets for `@trigger.dev/core` (report schemas), `@trigger.dev/sdk` (chat reconnect) and the CLI's `mint-token` help text.

…g chat unmounts

…ft-delete idempotency (review)

…ool transcript

…rst as a draft guard

devin-ai-integration

Devin Review found 1 new potential issue.

#4529)

Watch is the agent noticing something later: you ask it to tell you when a condition holds, and it answers when it does — or when it can't any more. A watch is a **durable one-shot promise**. The condition is checked on a schedule by deterministic code (no LLM in the checks), the answer lands in the chat once, and then the watch is over. Ten kinds: three on a run, five on a queue, error recurrence, health recovery. ## Stack Stacked on **#4529** (UI), which is stacked on **#4418** (chat, reports, investigate). Merge those first. **#4516** (storybook gallery) sits on top of this branch. ## How to review [**GUIDEBOOK.md**](https://github.com/triggerdotdev/trigger.dev/blob/feat/dashboard-agent-flows-watch/internal-packages/dashboard-agent/GUIDEBOOK.md) on this branch is the behaviour reference — it states the conditions rather than the code, so you can predict what happens without running anything. "The ten watch kinds, and what makes each fire" and "Creating a watch" describe exactly this PR, and the tables there are the spec the code is written against. ## What's inside - **Ten watch kinds**, one deterministic check each (`dashboardAgentWatch*Checks.ts`), with the spec union in `dashboard-agent-contracts/src/watch.ts`. - **Scheduling** — each watch schedules its own next check; due watches of one `(environment, cadence)` group can be checked together in one batch pass, with a sweep as the backstop for expiry, redelivery and retention. - **Delivery** — the in-chat wake and card, an optional email alert (new `DASHBOARD_AGENT_WATCH` alert channel, so it shows on the project's Alerts page with one-click unsubscribe), and an optional investigation when the outcome needs attention. - **Submission ledger** — `watch_submissions`, keyed `(chat_id, client_request_id)`, so a retried card submission replays the recorded outcome instead of creating a second watch. - **Watch token** — a delayed-execution credential accepted only by the watch endpoints, re-checked against the user's live access on every tick. - **Unread work** — the panel polls for wakes that landed while it was closed, so a chat can go unread and light the launcher dot. ## Key decisions **A check result is a 4-way, and only two of them are verdicts.** `satisfied` / `terminal_unsatisfied` are answers; `pending` and `unavailable` are not. Any exception inside any check is caught in one place and becomes `unavailable` with an unverified observation — a check that failed is never evidence. **A completed window is an answer, and whether it is good or bad news is declared per kind, never inferred.** There is a table for that in the guidebook: `run_failed` completing its window is *good* news ("hasn't failed"), `backlog_drain` completing it is not. One rule overrides the table: a window that completed on an unverified observation is neutral and says only that the watch ended without a confirmed answer. **An unreadable source is never a negative answer** — and, because investigations only open on `attention`, it never starts one either. **Identity is `(chat, project, environment)` plus the condition,** enforced by a partial unique index over active rows (`watches_chat_active_identity_key`), not by the read-then-insert check. Cadence, window, note and `ticks` are deliberately not part of it. Two different chats may watch the same thing — a watch is a promise to a chat. **The server resolves the target's name, whatever the model calls it.** The model can't tell a task queue (`task/<id>`) from a custom queue, so both spellings are tried and the stored one wins — and the rewrite happens **before** identity and before the row is written, so the identity, the checks, the link and the wording all see one spelling. **Freshness fences.** Depth falls back from the live counter to the newest 60 s ClickHouse bucket, which only counts as current within 60 s of now. A non-current reading at or below the *quiet line* is refused as `unavailable` rather than believed, so a stale empty bucket is never read as "drained". The stall streak is the one piece of carried state: it lives in the previous check's facts and *freezes* on an unreadable reading rather than breaking. **Chain reliability.** There is no shared cron — each watch (or batch group) schedules its own next tick, so the failure mode to review is the chain dying. A failed batch check is caught, the next tick is scheduled anyway and the run resolves rather than failing, so the chain survives a check that couldn't run; the sweep re-arms groups and finalizes anything still active past its deadline, even when delivery isn't configured. Wake redelivery is id-deduped rather than conditional, because the sweep can't know whether the user was already told. Access is re-authorized on **every** check against the primary — replica lag would extend access the user has already lost. **Wording lives in one place.** `watch-wording.ts` is read by the card, banner, toast, email and the agent's own narration, and the numbers come from the frozen observation rather than a fresh read, so a retry produces the same sentence. Replay reproduces the **recorded** decision instead of deciding again — the transcript is append-once, so a second decision would contradict it forever. **Cancellation is the ending without an answer** — no resolution, no wake. One exception, decided during testing: a watch the *user* cancelled leaves a single neutral transcript line ("Stopped watching …"), keyed off the watch id so a retry can't repeat it. The other four reasons stay silent. **Email is opt-in and only a fired watch emails.** An expiry is narrated in the chat and nowhere else. Both gates (agent access, a configured email transport) are checked at subscribe time *and* again at delivery, and the subscription outcome is frozen on the ledger row so a retry replays it. Neither gate is a plan check. **One watch offer per turn.** The prompt and the renderer guard this independently — if the turn already proposed a watch card, the action button is dropped, because the card is the better affordance. Two eval cases pin the prompt side: exactly one offer with the line last and the button after it, and zero offers when the rendered card already carries one — deterministic assertions, over a real-model run. ## Testing Unit tests (vitest, testcontainers, no mocks) under `apps/webapp/test/dashboardAgentWatch*.test.ts` and `internal-packages/dashboard-agent/src/watch-*.test.ts` cover the invariants above: the 4-way check results and the freshness fences, identity/dedup and the submission ledger, queue-name resolution, the batch chain surviving a failed check, sweep boundaries and alert-once, tenancy and the watch token's scope, and the wording snapshot. The load-bearing ones were verified by control-breaking the guard first and checking the test goes red. Live-tested end to end against a local stack, following the guidebook: all ten watch kinds firing and expiring, cancellation, the email pair (a fired watch mails, an expired one does not), and watch recovery from a health report.

…unavailable (#4592) Restores the page-header docs buttons removed in #4529 / #4418, shown only when the dashboard agent is unavailable (feature flag off, or pages outside the environment layout). The buttons are restored verbatim at their original spots — 22 sites across 21 files — wrapped in a small `WhenAgentUnavailable` gate that reads the agent context (SSR-safe, no hydration flicker). Also: in the light theme, the query editor's Format/Clear/Copy toolbar gets a translucent white background (`light:bg-white/80`) instead of transparent, so it no longer blends into the code behind it. <img width="1215" height="133" alt="Screenshot 2026-08-12 at 17 26 02" src="https://github.com/user-attachments/assets/4bdba825-9cbd-4df4-b6ca-0ea6691a534b" />

kathiekiwi and others added 30 commits August 6, 2026 09:44

test(webapp): stub the agent proxy's environment lookup, not a Prisma…

933aeb9

… row The hand-built row stopped satisfying every column the authenticated-environment mapper reads, so both proxy cases failed. Stubbing the lookup keeps the fixture independent of the row's columns.

chore: ignore the agent worktrees directory

d73f3f5

test(webapp): assert the document img-src has no wildcard host

cd112ba

docs: document CSP_IMG_SRC_ALLOWLIST for self-hosted image hosts

5adba81

docs(dashboard-agent): tell the judge the error category is derived, …

9daa8f9

…the message withheld Also reuse the policy's errored-output check instead of a second copy of it.

fix(webapp): require the watch card's request id instead of falling b…

09d1b55

…ack to its condition A per-condition fallback identified the condition rather than the submit, so a re-watch could replay a stale terminal outcome from the retention window.

fix(webapp): cancel the watch a losing submit's winner does not name

22bf6d9

A refusal that won the race kept the reserved watch id, so the user was told nothing was created while that watch stayed active.

chore(dashboard-agent): drop the comments the code already says

240799d

chore(dashboard-agent): drop the test comments the assertions already…

478b30c

… say

style(webapp): format the sweep's authorization helper

4e00b79

test(webapp): give the container-backed user-actor scope tests their …

3336a47

…own timeout

chore(webapp): drop the comments the code already says

7a645e5

chore(webapp): drop the comments the tests already say

79482de

chore(rbac): keep the delegated-token invariant, drop the essay

d646809

chore(dashboard-agent-db): drop the submission's external-notificatio…

7b2f9c6

…n patch A recorded outcome is immutable now, so nothing calls it.

docs: note the agent's closed investigations, watch email honesty and…

07b83da

… image sources

test(webapp): fail if a route sets an over-broad image CSP

60a9584

style(webapp): format the route image CSP audit

e62d8c6

kathiekiwi added 2 commits August 11, 2026 16:30

chore: merge main into feat/dashboard-agent-flows

54ab14f

chore: merge feat/dashboard-agent-flows (main sync)

eca32d2