4569657923
## 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.
154 lines
5.1 KiB
TypeScript
154 lines
5.1 KiB
TypeScript
import { beforeEach, describe, expect, it, vi } from "vitest";
|
|
|
|
/**
|
|
* The run-commit route answers with a deployment's git metadata — commit message, author, branch,
|
|
* PR title. The deployments list serves the same blob behind `read` on `deployments`, so a
|
|
* credential without that scope must not get it from here either.
|
|
*/
|
|
|
|
const { SESSION_SECRET } = vi.hoisted(() => ({
|
|
SESSION_SECRET: "test-session-secret-for-run-commit-authorization",
|
|
}));
|
|
|
|
const mocks = vi.hoisted(() => ({
|
|
can: vi.fn<(...args: any[]) => boolean>(),
|
|
resolveRunCommit: vi.fn<(...args: any[]) => Promise<any>>(),
|
|
}));
|
|
|
|
vi.mock("@internal/tracing", () => ({
|
|
getMeter: () => ({
|
|
createCounter: () => ({ add: vi.fn() }),
|
|
createHistogram: () => ({ record: vi.fn() }),
|
|
createObservableGauge: () => ({ addCallback: vi.fn() }),
|
|
}),
|
|
}));
|
|
vi.mock("~/env.server", () => ({
|
|
env: { SESSION_SECRET, APP_ORIGIN: "https://example.com" },
|
|
}));
|
|
vi.mock("~/services/logger.server", () => ({
|
|
logger: { debug: vi.fn(), error: vi.fn(), warn: vi.fn(), info: vi.fn() },
|
|
}));
|
|
vi.mock("~/services/rbac.server", () => ({
|
|
rbac: {
|
|
authenticateBearer: vi.fn(),
|
|
authenticateUserActor: async () => ({ ok: true, ability: { can: mocks.can } }),
|
|
authenticatePat: async () => ({ ok: true, ability: { can: mocks.can } }),
|
|
},
|
|
}));
|
|
vi.mock("~/services/personalAccessToken.server", () => ({
|
|
authenticateApiRequestWithPersonalAccessToken: vi.fn(),
|
|
isPersonalAccessToken: () => false,
|
|
// Test tokens carry no source PAT, so the liveness recheck always passes.
|
|
assertSourcePatActive: async () => true,
|
|
}));
|
|
vi.mock("~/services/organizationAccessToken.server", () => ({
|
|
authenticateApiRequestWithOrganizationAccessToken: vi.fn(),
|
|
isOrganizationAccessToken: () => false,
|
|
}));
|
|
vi.mock("~/services/realtime/jwtAuth.server", () => ({
|
|
isPublicJWT: () => false,
|
|
validatePublicJwtKey: vi.fn(),
|
|
}));
|
|
vi.mock("~/models/project.server", () => ({
|
|
findProjectByRef: async (externalRef: string, userId: string) =>
|
|
externalRef === PROJECT.externalRef && userId === USER_ID ? PROJECT : null,
|
|
}));
|
|
vi.mock("~/models/runtimeEnvironment.server", () => ({
|
|
authIncludeBase: {},
|
|
authIncludeWithParent: {},
|
|
findEnvironmentByApiKey: vi.fn(),
|
|
findEnvironmentByApiKeyWithResolution: vi.fn(),
|
|
findEnvironmentByPublicApiKey: vi.fn(),
|
|
toAuthenticated: (environment: any) => environment,
|
|
}));
|
|
vi.mock("~/db.server", () => ({
|
|
prisma: {},
|
|
$replica: {
|
|
user: {
|
|
findUnique: async ({ where }: any) => (where.id === USER_ID ? { id: where.id } : null),
|
|
},
|
|
runtimeEnvironment: {
|
|
findFirst: async ({ where }: any) => (where.slug === ENVIRONMENT.slug ? ENVIRONMENT : null),
|
|
},
|
|
workerDeployment: {
|
|
findFirst: async () => ({
|
|
git: { commitMessage: "fix billing for Acme Corp", commitAuthorName: "Alice" },
|
|
shortCode: "abcd",
|
|
deployedAt: new Date(),
|
|
}),
|
|
},
|
|
},
|
|
}));
|
|
vi.mock("~/services/dashboardAgent.server", () => ({
|
|
resolveRunCommit: mocks.resolveRunCommit,
|
|
}));
|
|
|
|
import { signUserActorToken } from "@trigger.dev/rbac";
|
|
import { loader as commitLoader } from "~/routes/api.v1.projects.$projectRef.$env.runs.$runId.commit";
|
|
|
|
const ORGANIZATION = { id: "org_1234", slug: "test-org" };
|
|
const PROJECT = { id: "proj_1234", externalRef: "proj_ref_1234", slug: "test-project" };
|
|
const USER_ID = "usr_member";
|
|
const ENVIRONMENT = {
|
|
id: "env_prod",
|
|
slug: "prod",
|
|
type: "PRODUCTION" as const,
|
|
apiKey: "tr_prod_abcdefghijklmnop",
|
|
organizationId: ORGANIZATION.id,
|
|
organization: ORGANIZATION,
|
|
projectId: PROJECT.id,
|
|
project: PROJECT,
|
|
};
|
|
|
|
async function getCommit(): Promise<{ status: number; body: any }> {
|
|
const token = await signUserActorToken(SESSION_SECRET, {
|
|
userId: USER_ID,
|
|
client: "dashboard-agent",
|
|
environmentId: ENVIRONMENT.id,
|
|
cap: ["read:runs"],
|
|
});
|
|
|
|
const response = await commitLoader({
|
|
request: new Request(
|
|
`https://example.com/api/v1/projects/${PROJECT.externalRef}/prod/runs/run_1/commit`,
|
|
{ headers: { Authorization: `Bearer ${token}` } }
|
|
),
|
|
params: { projectRef: PROJECT.externalRef, env: "prod", runId: "run_1" },
|
|
context: {} as any,
|
|
} as any);
|
|
return { status: response.status, body: await response.json() };
|
|
}
|
|
|
|
describe("reading a run's commit metadata", () => {
|
|
beforeEach(() => {
|
|
mocks.can.mockReset();
|
|
mocks.resolveRunCommit.mockReset();
|
|
// The commit resolves fine, so a refusal can only come from the gate.
|
|
mocks.resolveRunCommit.mockResolvedValue({
|
|
version: "20240101.1",
|
|
sha: "abc123",
|
|
dirty: false,
|
|
});
|
|
});
|
|
|
|
it("refuses a caller who may not read deployments", async () => {
|
|
mocks.can.mockImplementation((_action, resource) => resource?.type !== "deployments");
|
|
|
|
const result = await getCommit();
|
|
|
|
expect(result.status).toBe(403);
|
|
expect(JSON.stringify(result.body)).not.toContain("Acme Corp");
|
|
expect(mocks.resolveRunCommit).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("answers a caller who may", async () => {
|
|
mocks.can.mockReturnValue(true);
|
|
|
|
const result = await getCommit();
|
|
|
|
expect(result.status).toBe(200);
|
|
expect(result.body.sha).toBe("abc123");
|
|
expect(result.body.git.commitMessage).toBe("fix billing for Acme Corp");
|
|
});
|
|
});
|