feat(webapp): a consented watch investigation conducts itself

The wake seeded the card and said it had started looking, then nothing ran
it — the findings were left to a turn only the user could start. The watcher
now reports a delivered consented wake to the webapp, which mints the same
delegated user-actor token a turn gets and sends a `watch.investigate` action
into the chat; the agent conducts a real investigating turn on that card and
delivers the findings as its own message. Best-effort throughout: nothing here
can retry or invalidate the wake.

Author: kathiekiwi

.server-changes/dashboard-agent-watch-investigates-itself.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+When you ask a watch to investigate bad news, it now does the whole thing on its own: the chat tells you the watch resolved, and the findings arrive right after in their own message, with the investigation card. You no longer have to come back and ask.

apps/webapp/app/routes/api.v1.dashboard-agent.watches.$watchId.investigate.ts

@@ -0,0 +1,112 @@
+import { getWatch, isTerminalWatchStatus } from "@internal/dashboard-agent-db";
+import { json, type ActionFunctionArgs } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { dashboardAgentDb } from "~/services/dashboardAgentDb.server";
+import {
+  kickWatchInvestigation,
+  watchWantsInvestigation,
+} from "~/services/dashboardAgentWatchInvestigate.server";
+import { authorizeWatchEnvironment } from "~/services/dashboardAgentWatches.server";
+import {
+  bearerToken,
+  verifyWatchTokenFromRequest,
+} from "~/services/dashboardAgentWatchToken.server";
+import { logger } from "~/services/logger.server";
+
+/**
+ * `POST /api/v1/dashboard-agent/watches/:watchId/investigate` — the watcher task
+ * tells us it has delivered the wake for a watch whose creator pre-approved an
+ * investigation, so the agent can be sent off to actually conduct it.
+ *
+ * Same security model as the fired callback next door: the TOKEN only names a
+ * watch, the ROW is the authority on what happened, and the watch's initiating USER
+ * is re-authorized against the row's immutable project/environment before anything
+ * is minted — an investigation must never outlive the access the watch was created
+ * with. The caller's body is ignored entirely, so a replay can only ever re-ask for
+ * what the row already says; the agent then dedupes on the action's stable id.
+ *
+ * Nothing here can be steered by the model: the consent, the outcome, the user and
+ * the environment all come off the row.
+ */
+
+const ParamsSchema = z.object({ watchId: z.string().min(1) });
+
+export async function action({ request, params }: ActionFunctionArgs) {
+  if (request.method.toUpperCase() !== "POST") {
+    return json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  const parsedParams = ParamsSchema.safeParse(params);
+  if (!parsedParams.success) return json({ error: "Invalid params" }, { status: 400 });
+  const { watchId } = parsedParams.data;
+
+  const token = bearerToken(request);
+  if (!token) {
+    return json(
+      { error: "Invalid or missing access token", code: "unauthorized" },
+      { status: 401 }
+    );
+  }
+
+  const claims = await verifyWatchTokenFromRequest(token);
+  if (!claims) {
+    return json(
+      { error: "Invalid or missing access token", code: "unauthorized" },
+      { status: 401 }
+    );
+  }
+
+  if (claims.watchId !== watchId) {
+    return json({ error: "Not allowed for this watch", code: "watch_mismatch" }, { status: 403 });
+  }
+
+  const watch = await getWatch(dashboardAgentDb, { id: watchId });
+  if (!watch) {
+    return json({ error: "Watch not found", code: "not_found" }, { status: 404 });
+  }
+
+  // The row decides, on all three counts: it has to have resolved, the user has to
+  // have consented, and the outcome has to be one the consent covers.
+  if (!isTerminalWatchStatus(watch.status)) {
+    return json(
+      { error: `This watch is ${watch.status}`, code: "not_resolved", status: watch.status },
+      { status: 409 }
+    );
+  }
+
+  if (!watchWantsInvestigation(watch)) {
+    // Good news, neutral news, or no consent — the wake was the whole delivery.
+    return json({ ok: true, investigating: false });
+  }
+
+  const authorization = await authorizeWatchEnvironment({
+    userId: watch.userId,
+    organizationId: watch.organizationId,
+    projectId: watch.projectId,
+    environmentId: watch.environmentId,
+  });
+
+  if (!authorization.ok) {
+    logger.info("Dashboard agent watch resolved, but access was revoked; no investigation", {
+      watchId,
+    });
+    return json(
+      { error: "Access to this environment was revoked", code: "access_revoked" },
+      { status: 403 }
+    );
+  }
+
+  // Best-effort, and deliberately not an error to the caller: the wake has already
+  // been delivered and marked by the time we are called, so a failed kick must not
+  // make the watcher retry anything (§6). A turn that never starts — or one that
+  // dies mid-investigation — is caught by the stale-investigation sweep, which
+  // settles the card instead of leaving a spinner.
+  try {
+    await kickWatchInvestigation({ watch, environment: authorization.environment });
+  } catch (error) {
+    logger.error("Dashboard agent watch investigation could not be started", { watchId, error });
+    return json({ ok: true, investigating: false, code: "kick_failed" });
+  }
+
+  return json({ ok: true, investigating: true });
+}

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.in.$.ts

@@ -3,6 +3,7 @@ import { $replica } from "~/db.server";
 import { findProjectBySlug } from "~/models/project.server";
 import {
   dashboardAgentApiOrigin,
+  dashboardAgentEnvironmentName,
   mintDashboardAgentUserActorToken,
   resolveDashboardAgentRepoSnapshot,
 } from "~/services/dashboardAgent.server";
@@ -36,17 +37,6 @@ const FORWARDED_HEADERS = [
   "x-trigger-branch",
 ];
 
-// The API's env routes key on the canonical env name (dev/staging/prod/preview),
-// not the dashboard URL slug (e.g. staging's slug is "stg"). Map from the env
-// type so the agent's tools address the right environment. Preview branches
-// aren't threaded yet (they'd need the branch on every tool call) — a follow-up.
-const ENV_NAME_BY_TYPE: Record<string, string> = {
-  DEVELOPMENT: "dev",
-  STAGING: "staging",
-  PRODUCTION: "prod",
-  PREVIEW: "preview",
-};
-
 export async function action({ request, params }: ActionFunctionArgs) {
   const user = await requireUser(request);
   const { organizationSlug, projectParam, envParam } = EnvironmentParamSchema.parse(params);
@@ -79,7 +69,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
     where: { projectId: project.id, slug: envParam },
     select: { id: true, type: true },
   });
-  const environmentName = runtimeEnv ? ENV_NAME_BY_TYPE[runtimeEnv.type] : undefined;
+  const environmentName = dashboardAgentEnvironmentName(runtimeEnv?.type);
 
   // When the project has a connected GitHub repo, resolve a signed source-archive
   // pointer (code mode). Null otherwise -> the agent stays in assistant mode.
@@ -91,8 +81,18 @@ export async function action({ request, params }: ActionFunctionArgs) {
   try {
     const parsed = JSON.parse(raw) as {
       kind?: string;
-      payload?: { metadata?: Record<string, unknown> };
+      payload?: { trigger?: string; metadata?: Record<string, unknown> };
     };
+    // Actions are server business, not the browser's. A wake comes from the
+    // watcher task and the investigate kick from our own server hop, both writing
+    // to `.in` with an environment key — nothing arriving through this proxy may
+    // claim to be one. Refusing here (rather than letting the agent's action schema
+    // sort it out) keeps "an action was placed by the server" a real boundary: the
+    // proxy is the one path a browser can reach `.in` through, and it is also where
+    // a delegated token gets minted.
+    if (parsed.payload?.trigger === "action") {
+      return json({ error: "Not allowed" }, { status: 403 });
+    }
     if (parsed.kind === "message" && parsed.payload) {
       parsed.payload.metadata = {
         ...(parsed.payload.metadata ?? {}),

apps/webapp/app/services/dashboardAgent.server.ts

@@ -55,6 +55,21 @@ export function mintDashboardAgentUserActorToken(
   });
 }
 
+// The API's env routes key on the canonical env name (dev/staging/prod/preview),
+// not the dashboard URL slug (e.g. staging's slug is "stg"). Anything handing the
+// agent an environment maps from the type through here, so a tool built from an
+// injected token and a tool built from a kicked action address the same place.
+const ENV_NAME_BY_TYPE: Record<string, string> = {
+  DEVELOPMENT: "dev",
+  STAGING: "staging",
+  PRODUCTION: "prod",
+  PREVIEW: "preview",
+};
+
+export function dashboardAgentEnvironmentName(type: string | undefined): string | undefined {
+  return type ? ENV_NAME_BY_TYPE[type] : undefined;
+}
+
 // The session is created in whatever env DASHBOARD_AGENT_SECRET_KEY belongs to.
 // baseURL is the Trigger instance this webapp runs against (its own API origin).
 function dashboardAgentConfig() {

apps/webapp/app/services/dashboardAgentWatchInvestigate.server.ts

@@ -0,0 +1,118 @@
+/**
+ * The second half of a consented watch: making the agent CONDUCT the investigation
+ * its wake said had started.
+ *
+ * The wake seeds the card and says "I've started looking into why", but the wake
+ * turn deliberately carries no delegated token — it narrates what the check already
+ * established, it doesn't read. So the reading turn is kicked from here, where a
+ * token can be minted: one record on the chat's `in` stream with
+ * `trigger: "action"`, carrying a fresh short-lived delegated token for the watch's
+ * INITIATING user in the metadata, exactly the way the dashboard's `in` proxy
+ * injects a turn's token. The agent handles it as its own message.
+ *
+ * Security, all of it decided here and none of it model-suppliable:
+ * - the token is for `watch.userId`, minted against `watch.environmentId` — the
+ *   immutable snapshot the watch was created with, never anything from a request
+ *   body;
+ * - the caller re-authorizes that user against that environment first (the route
+ *   does, before calling in), so a revoked access investigates nothing;
+ * - the TTL is the same short one every turn's token gets;
+ * - the token is never logged and never reaches a browser.
+ */
+
+import type { WatchInvestigateAction } from "@internal/dashboard-agent";
+import { type Watch } from "@internal/dashboard-agent-db";
+import { watchResultNeedsAttention } from "@internal/dashboard-agent-contracts";
+import { ApiClient } from "@trigger.dev/core/v3";
+import { type AuthenticatedEnvironment } from "~/services/apiAuth.server";
+import {
+  dashboardAgentApiOrigin,
+  dashboardAgentEnvironmentName,
+  mintDashboardAgentUserActorToken,
+} from "~/services/dashboardAgent.server";
+import { env } from "~/env.server";
+
+/**
+ * Whether this resolved watch is one the consent covers.
+ *
+ * Consent is for ATTENTION outcomes only, and which those are is the contracts'
+ * mapping to decide — the same call the agent's wake makes, so the two can never
+ * disagree about what counts as bad news. A watch with no resolution (still active,
+ * or cancelled) has no outcome to investigate.
+ */
+export function watchWantsInvestigation(watch: Watch): boolean {
+  if (!watch.investigateOnAttention) return false;
+  if (!watch.resolution) return false;
+  return watchResultNeedsAttention({
+    kind: watch.spec.kind,
+    resolution: watch.resolution,
+    outcome: watch.observedOutcome,
+  });
+}
+
+/**
+ * The action the agent receives. Stable id, so a retried kick is a no-op.
+ *
+ * Typed against the agent's own contract (type-only import — the agent's runtime
+ * must never enter this bundle), so the two halves can't drift.
+ */
+export function watchInvestigateAction(watch: Watch): WatchInvestigateAction {
+  return {
+    type: "watch.investigate" as const,
+    id: `watch:${watch.id}:${watch.status}:investigate`,
+    watchId: watch.id,
+    identity: watch.identity,
+    spec: watch.spec,
+    facts: (watch.lastResult ?? {}) as Record<string, unknown>,
+    resolution: watch.resolution ?? undefined,
+    observed: watch.observedOutcome ?? undefined,
+    note: watch.spec.note,
+  };
+}
+
+/**
+ * Send the kick. Throws on failure — every caller treats it as best-effort, because
+ * the wake has already been delivered by the time we get here and nothing about
+ * this may retry or invalidate it (§6). A turn that dies mid-investigation is
+ * covered by the stale-investigation sweep, not by retrying this.
+ */
+export async function kickWatchInvestigation(params: {
+  watch: Watch;
+  environment: AuthenticatedEnvironment;
+}): Promise<void> {
+  const { watch, environment } = params;
+  const accessToken = env.DASHBOARD_AGENT_SECRET_KEY;
+  if (!accessToken) throw new Error("DASHBOARD_AGENT_SECRET_KEY is not set");
+
+  const apiOrigin = dashboardAgentApiOrigin();
+  // The agent's `clientData` for this record — the watch's own immutable tenancy
+  // plus the delegated token, which is what turns this into a turn that can read.
+  const metadata = {
+    userId: watch.userId,
+    organizationId: watch.organizationId,
+    projectId: watch.projectId,
+    environmentId: watch.environmentId,
+    projectRef: watch.projectRef ?? environment.project.externalRef,
+    environmentName: dashboardAgentEnvironmentName(environment.type),
+    apiOrigin,
+    userActorToken: await mintDashboardAgentUserActorToken(watch.userId, {
+      environmentId: watch.environmentId,
+    }),
+  };
+
+  const apiClient = new ApiClient(apiOrigin, accessToken);
+  await apiClient.appendToSessionStream(
+    // Sessions are addressable by externalId, which is the chat id.
+    watch.chatId,
+    "in",
+    JSON.stringify({
+      kind: "message",
+      payload: {
+        chatId: watch.chatId,
+        trigger: "action",
+        action: watchInvestigateAction(watch),
+        metadata,
+      },
+    })
+  );
+}