feat(webapp): dashboard agent — chat, reports, investigate (#4418)

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

Author: kathiekiwi

.changeset/chat-stream-mid-turn-reconnect.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+"trigger.dev": patch
+---
+
+Chat in the browser now reconnects when the connection drops mid-turn, instead of leaving the reply stuck as if it were still generating. Reports can be fetched as structured data with the `json` format, and the shortest report period is now one minute (`30m`, `1h`, `7d`). The `mint-token` command's help is clearer too: a token minted without `--cap` is read-only, and `--ttl` shows the correct maximum lifetime of 7 days.

.claude/skills/errors-api-e2e/SKILL.md

@@ -154,7 +154,7 @@ PASS: one run, `run_<RID>` (status maps to `FAILED`). Proves `filter[error]` ->
 ### 6. Attribution — `mint-token` -> JWT exchange records the acting user
 
 ```bash
-TOKEN=$(cli mint-token --profile $PROFILE --client errors-api-e2e 2>/dev/null)            # UAT
+TOKEN=$(cli mint-token --profile $PROFILE --client errors-api-e2e --cap read:errors,write:errors 2>/dev/null)            # UAT
 ENVJWT=$(curl -sS -X POST "$B/api/v1/projects/$REF/dev/jwt" -H "Authorization: Bearer $TOKEN" \
   -H 'Content-Type: application/json' -d '{"claims":{"scopes":["read:errors","write:errors"]}}' \
   | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

.gitattributes

@@ -0,0 +1,5 @@
+# Generated, not hand-written: collapsed in diffs and excluded from language stats.
+internal-packages/dashboard-agent-db/drizzle/meta/*.json linguist-generated=true
+internal-packages/dashboard-agent-db/drizzle/meta/** linguist-generated=true
+**/__snapshots__/*.snap linguist-generated=true
+pnpm-lock.yaml linguist-generated=true

.gitignore

@@ -85,3 +85,5 @@ ailogger-output.log
 
 # observability-map CLI output artifact, not committed
 observability-map.json
+
+.claude/worktrees/

.server-changes/dashboard-agent.md

@@ -0,0 +1,8 @@
+---
+area: webapp
+type: feature
+---
+
+Meet the dashboard agent: a chat in every environment that answers questions about your runs, queues, errors and health with real data and links, replacing Ask AI everywhere it used to appear. Investigate a failed run, an error, a backed-up queue or a run that hasn't started to get a worked-through answer — what happened, why, and how to fix it, with every claim linked to the runs, errors and deploys behind it. It reads your data read-only, works on preview and dev branches with that branch's own data, and reads the same everywhere — dashboard, terminal, editor. A very long chat keeps working: the agent summarises the earlier part and carries on.
+
+A sample of conversations is scored automatically so the agent keeps getting better; only the score and a one-line summary are kept, never your messages, data or code, and we can switch it off for your organization on request. The Docs button is gone from page headers — ask the agent instead, or open Documentation from Help & Feedback. Separately, a queue's wait times, peak depth, throughput and throttling can now be read from the API.

apps/webapp/.gitignore

@@ -7,6 +7,9 @@ node_modules
 /cypress/screenshots
 /cypress/videos
 
+# Output of `pnpm run agent-ui:screenshots`
+/screenshots
+
 /app/styles/tailwind.css
 
 # Ensure the .env symlink is not removed by accident
@@ -20,4 +23,4 @@ storybook-static
 
 /prisma/seed.js
 /prisma/populate.js
-.memory-snapshots
+.memory-snapshots

apps/webapp/app/components/AskAI.tsx

@@ -1,3 +1,9 @@
+/**
+ * @deprecated Superseded by the dashboard agent (`components/dashboard-agent`). Nothing mounts
+ * this any more — every Ask AI entry point now opens Ask Trigger. Kept until the agent has
+ * shipped, then removed along with `@kapaai/react-sdk` and `KAPA_AI_WEBSITE_ID`.
+ */
+
 import {
   ArrowPathIcon,
   ArrowUpIcon,
@@ -81,6 +87,8 @@ function useAskAIState() {
  * it around the popover, not inside, so the dialog and shortcut survive the popover closing.
  * `children` receives the open function, or undefined when Ask AI is unavailable (self-hosted, no
  * Kapa website id, or SSR).
+ *
+ * @deprecated See the note at the top of this file.
  */
 export function AskAIRoot({
   children,
@@ -137,6 +145,7 @@ function AskAIRootProvider({
   );
 }
 
+/** @deprecated See the note at the top of this file. */
 export function AskAI({ isCollapsed = false }: { isCollapsed?: boolean }) {
   const { isManagedCloud } = useFeatures();
   const websiteId = useKapaWebsiteId();

apps/webapp/app/components/code/StreamdownRenderer.test.ts

@@ -0,0 +1,80 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { restrictModelUrls, StreamdownRenderer } from "./StreamdownRenderer";
+
+// streamdown calls urlTransform(url, key, node) to compute each url attribute; a
+// returned undefined removes the attribute, so no request is ever issued.
+const img = { tagName: "img" } as any;
+const link = { tagName: "a" } as any;
+
+describe("restrictModelUrls (image src)", () => {
+  it("drops a remote model-authored image (the favicon beacon)", () => {
+    expect(
+      restrictModelUrls("https://www.google.com/s2/favicons?domain=evil", "src", img)
+    ).toBeUndefined();
+  });
+
+  it("drops any absolute or protocol-relative remote image", () => {
+    expect(restrictModelUrls("http://evil.tld/pixel.gif", "src", img)).toBeUndefined();
+    expect(restrictModelUrls("//evil.tld/pixel.gif", "src", img)).toBeUndefined();
+  });
+
+  it("keeps inline and same-origin images", () => {
+    expect(restrictModelUrls("data:image/png;base64,AAAA", "src", img)).toBe(
+      "data:image/png;base64,AAAA"
+    );
+    expect(restrictModelUrls("blob:abc", "src", img)).toBe("blob:abc");
+    expect(restrictModelUrls("/local/pic.png", "src", img)).toBe("/local/pic.png");
+  });
+});
+
+describe("restrictModelUrls (link href)", () => {
+  it("keeps http(s), mailto and relative links", () => {
+    expect(restrictModelUrls("https://trigger.dev/docs", "href", link)).toBe(
+      "https://trigger.dev/docs"
+    );
+    expect(restrictModelUrls("http://example.com", "href", link)).toBe("http://example.com");
+    expect(restrictModelUrls("mailto:hi@trigger.dev", "href", link)).toBe("mailto:hi@trigger.dev");
+    expect(restrictModelUrls("/runs/123", "href", link)).toBe("/runs/123");
+  });
+
+  it("drops unsafe link schemes", () => {
+    expect(restrictModelUrls("javascript:alert(1)", "href", link)).toBeUndefined();
+    expect(restrictModelUrls("data:text/html,<script>", "href", link)).toBeUndefined();
+  });
+});
+
+// Force the lazy component to load, then return its resolved default so we can render it
+// synchronously. This proves the policy is actually wired into the JSX, not just exported.
+async function resolveStreamdownRenderer() {
+  const lazy = StreamdownRenderer as unknown as {
+    _payload: unknown;
+    _init: (payload: unknown) => (props: { children: string }) => JSX.Element;
+  };
+  try {
+    lazy._init(lazy._payload);
+  } catch (thenable) {
+    await thenable;
+  }
+  return lazy._init(lazy._payload);
+}
+
+describe("StreamdownRenderer (rendered markdown)", () => {
+  it("never lets a model-authored remote image src reach the DOM", async () => {
+    const Renderer = await resolveStreamdownRenderer();
+    const markdown = [
+      "![x](https://www.google.com/s2/favicons?domain=SECRET.evil.tld)",
+      "![y](//evil.tld/pixel.gif)",
+      "![z](/local/pic.png)",
+    ].join("\n\n");
+    const html = renderToStaticMarkup(createElement(Renderer, null, markdown));
+
+    // No remote host is ever fetched: no absolute or protocol-relative image src survives.
+    expect(html).not.toContain('src="http');
+    expect(html).not.toContain('src="//');
+    expect(html).not.toContain("SECRET.evil.tld");
+    // A same-origin relative image is untouched, so the policy does not over-block.
+    expect(html).toContain('src="/local/pic.png"');
+  });
+});

apps/webapp/app/components/code/StreamdownRenderer.tsx

@@ -1,5 +1,32 @@
 import { lazy } from "react";
-import type { CodeHighlighterPlugin } from "streamdown";
+import type { CodeHighlighterPlugin, UrlTransform } from "streamdown";
+
+const SAFE_LINK_SCHEMES = new Set(["http:", "https:", "mailto:"]);
+
+/**
+ * URL policy for model-authored markdown. A remote image is fetched the moment it
+ * renders — no click — so it is a zero-click data beacon; we drop the src of any
+ * non-local image. Links stay clickable but only for safe, human-followable schemes.
+ * streamdown removes an attribute whose transform returns undefined, so no request fires.
+ */
+export const restrictModelUrls: UrlTransform = (url, key, node) => {
+  const value = url.trim();
+  const isImage = node.tagName === "img" || key === "src" || key === "srcset";
+
+  if (isImage) {
+    // Inline images carry their own bytes; a relative path resolves to our own origin.
+    if (/^data:/i.test(value) || /^blob:/i.test(value)) return url;
+    // Absolute or protocol-relative means a remote host — strip it so nothing is fetched.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//")) return undefined;
+    return url;
+  }
+
+  // Links: relative and protocol-relative are fine; otherwise require a safe scheme.
+  if (value.startsWith("//")) return url;
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(value);
+  if (!schemeMatch) return url;
+  return SAFE_LINK_SCHEMES.has(`${schemeMatch[1].toLowerCase()}:`) ? url : undefined;
+};
 
 export const StreamdownRenderer = lazy(() =>
   Promise.all([import("streamdown"), import("@streamdown/code"), import("./shikiTheme")]).then(
@@ -23,6 +50,7 @@ export const StreamdownRenderer = lazy(() =>
             isAnimating={isAnimating}
             plugins={{ code: codePlugin }}
             controls={{ code: { copy: false, download: false } }}
+            urlTransform={restrictModelUrls}
             linkSafety={{ enabled: false }}
           >
             {children}

apps/webapp/app/components/code/tsql/tsqlLinter.test.ts

@@ -68,9 +68,10 @@ describe("tsqlLinter", () => {
       expect(error).toContain("line");
     });
 
-    it("should handle missing FROM clause", () => {
-      const error = getTSQLError("SELECT * WHERE id = 1");
-      expect(error).not.toBeNull();
+    it("should accept a query without a FROM clause", () => {
+      // FROM is optional in the grammar (ClickHouse allows e.g. `SELECT 1`),
+      // so a FROM-less SELECT is syntactically valid.
+      expect(getTSQLError("SELECT * WHERE id = 1")).toBeNull();
     });
   });
 });