Files
Katia Bulatova 4569657923 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.
2026-08-11 18:56:14 +02:00

219 lines
8.2 KiB
TypeScript

import type { LinksFunction, LoaderFunctionArgs, MetaFunction } from "@remix-run/node";
import type { CSSProperties } from "react";
import type { ShouldRevalidateFunction } from "@remix-run/react";
import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";
import { type UseDataFunctionReturn, typedjson, useTypedLoaderData } from "remix-typedjson";
import { ExternalScripts } from "remix-utils/external-scripts";
import type { ToastMessage } from "~/models/message.server";
import { commitSession, getSession } from "~/models/message.server";
// Fonts imported here so Vite rebases the urls and emits the woff2 assets
import "non.geist";
import "non.geist/mono";
import tailwindStylesheetUrl from "~/tailwind.css?url";
import { RouteErrorDisplay } from "./components/ErrorDisplay";
import { GlobalShortcuts } from "./components/GlobalShortcuts";
import { StaleAssetRecovery } from "./components/StaleAssetRecovery";
import { AppContainer, MainCenteredContainer } from "./components/layout/AppLayout";
import { ShortcutsProvider } from "./components/primitives/ShortcutsProvider";
import { Toast } from "./components/primitives/Toast";
import { TimezoneSetter } from "./components/TimezoneSetter";
import { env } from "./env.server";
import { featuresForRequest } from "./features.server";
import { usePostHog } from "./hooks/usePostHog";
import { useSystemThemeSync } from "./hooks/useSystemThemeSync";
import { getImpersonationState } from "./services/impersonation.server";
import { getUser } from "./services/session.server";
import {
normalizeThemeContrast,
normalizeThemePreference,
type ThemePreference,
} from "~/utils/themePreference";
import { cachedFlag } from "~/v3/featureFlags.server";
import { getTimezonePreference } from "./services/preferences/uiPreferences.server";
import { appTitle } from "./utils/pageTitle";
// Derived here (not inside StaleAssetRecovery) so the shared component takes
// the flag as a prop. NODE_ENV is statically replaced in browser bundles, and
// the ErrorBoundary can't rely on loader data.
const isProduction = process.env.NODE_ENV === "production";
export const links: LinksFunction = () => {
return [{ rel: "stylesheet", href: tailwindStylesheetUrl }];
};
export const headers = () => ({
"Referrer-Policy": "strict-origin-when-cross-origin",
"X-Content-Type-Options": "nosniff",
"Permissions-Policy":
"geolocation=(), microphone=(), camera=(), accelerometer=(), gyroscope=(), magnetometer=(), payment=(), usb=()",
});
export const meta: MetaFunction = ({ data }) => {
const typedData = data as UseDataFunctionReturn<typeof loader>;
return [
// Pages declare their own title with `pageMeta`; this is the fallback.
{ title: appTitle(typedData?.appEnv) },
{
name: "viewport",
content: "width=1024, initial-scale=1",
},
{
name: "robots",
content:
typeof window === "undefined" || window.location.hostname !== "cloud.trigger.dev"
? "noindex, nofollow"
: "index, follow",
},
];
};
export const loader = async ({ request }: LoaderFunctionArgs) => {
const session = await getSession(request.headers.get("cookie"));
const toastMessage = session.get("toastMessage") as ToastMessage;
const posthogProjectKey = env.POSTHOG_PROJECT_KEY;
const posthogUiHost = env.POSTHOG_HOST;
const features = featuresForRequest(request);
const timezone = await getTimezonePreference(request);
// Deprecated with `AskAI.tsx`: kept so the widget still has its config if it is ever remounted.
const kapa = {
websiteId: env.KAPA_AI_WEBSITE_ID,
};
const user = await getUser(request);
// Theme switching is feature-flagged; while off, everyone stays on the
// classic theme even if a preference was saved earlier. Admins always get
// the switcher so the team can dogfood before the flag flips. Cached: the
// root loader runs on every document request and client navigation.
const showThemeSwitcher = user
? user.admin || (await cachedFlag({ key: "hasThemeSwitcher", defaultValue: false }))
: false;
// Logged-out pages (login, invites) always render the branded Classic look.
const themePreference: ThemePreference = showThemeSwitcher
? normalizeThemePreference(user?.dashboardPreferences.theme)
: "classic";
const themeContrast = showThemeSwitcher
? normalizeThemeContrast(user?.dashboardPreferences.contrast)
: 0;
// Display-only: while impersonating, an admin can ask to see the dashboard
// the way the impersonated user sees it. Exposed from root so every route can
// read it.
//
// Resolved against the user this request authenticated as, which is the same
// condition `requireUser` applies — otherwise the flag the client reads and
// the `user.isViewingAsUser` the server computes could disagree, and the
// client-side admin UI would hide itself on a session that is not
// impersonating.
const { isViewingAsUser } = await getImpersonationState(request, user?.id);
const headers = new Headers();
headers.append("Set-Cookie", await commitSession(session));
return typedjson(
{
user,
isViewingAsUser,
toastMessage,
posthogProjectKey,
posthogUiHost,
features,
appEnv: env.APP_ENV,
appOrigin: env.APP_ORIGIN,
apiOrigin: env.API_ORIGIN ?? env.APP_ORIGIN,
triggerCliTag: env.TRIGGER_CLI_TAG,
kapa,
timezone,
showThemeSwitcher,
themePreference,
themeContrast,
// Consumed by ResizablePanel: the browser check must match between SSR
// and hydration, so it is derived from the request user-agent.
isFirefox: /firefox/i.test(request.headers.get("user-agent") ?? ""),
},
{ headers }
);
};
export type LoaderType = typeof loader;
export const shouldRevalidate: ShouldRevalidateFunction = (options) => {
if (options.formAction === "/resources/environment") {
return false;
}
return options.defaultShouldRevalidate;
};
export function ErrorBoundary() {
return (
<>
<html lang="en" className="h-full" data-theme="classic">
<head>
<meta charSet="utf-8" />
<StaleAssetRecovery isProduction={isProduction} />
<Meta />
<Links />
</head>
<body className="h-full overflow-hidden bg-background-dimmed antialiased">
<ShortcutsProvider>
<AppContainer>
<MainCenteredContainer>
<RouteErrorDisplay />
</MainCenteredContainer>
</AppContainer>
</ShortcutsProvider>
<Scripts />
</body>
</html>
</>
);
}
export default function App() {
const { posthogProjectKey, posthogUiHost, themePreference, themeContrast } =
useTypedLoaderData<typeof loader>();
usePostHog(posthogProjectKey, posthogUiHost);
useSystemThemeSync(themePreference);
// SSR falls back to dark for `system`; the inline script below corrects it
// before paint, and useSystemThemeSync keeps it live afterwards.
const resolvedTheme = themePreference === "system" ? "dark" : themePreference;
return (
<>
<html
lang="en"
className="h-full"
// The pre-paint script below may flip data-theme before hydration
suppressHydrationWarning
data-theme={resolvedTheme}
data-theme-preference={themePreference}
// Contrast overlay input for the System themes; Classic never reads it
style={{ "--theme-contrast": themeContrast / 100 } as CSSProperties}
>
<head>
<script
dangerouslySetInnerHTML={{
__html: `try{if(document.documentElement.getAttribute("data-theme-preference")==="system"){document.documentElement.setAttribute("data-theme",matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")}}catch(e){}`,
}}
/>
<StaleAssetRecovery isProduction={isProduction} />
<Meta />
<Links />
</head>
<body className="h-full overflow-hidden bg-background-dimmed antialiased">
<ShortcutsProvider>
<TimezoneSetter />
<GlobalShortcuts />
<Outlet />
<Toast />
</ShortcutsProvider>
<ScrollRestoration />
<ExternalScripts />
<Scripts />
</body>
</html>
</>
);
}