feat(webapp,dashboard-agent): read the connected repo source in code mode

When a project has a connected GitHub repo, the in-dashboard agent can now read
its source to ground answers. It pulls the repo at the tracked commit onto its
own filesystem and exposes read-only list, read, and grep tools, so it can
explain a run or error against the actual task code, citing file and line.

The webapp resolves a short-lived signed archive URL server-side and injects it
per turn, so the GitHub token never reaches the agent. With no connected repo
the agent stays in its usual assistant mode.

Author: ericallam

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

@@ -1,8 +1,10 @@
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
 import {
+  DASHBOARD_AGENT_CODE_SYSTEM_PROMPT,
   DASHBOARD_AGENT_MODEL,
   DASHBOARD_AGENT_SYSTEM_PROMPT,
+  dashboardAgentCodeToolSchemas,
   dashboardAgentToolSchemas,
 } from "@internal/dashboard-agent/tool-schemas";
 import { chat as chatServer } from "@trigger.dev/sdk/chat-server";
@@ -14,6 +16,7 @@ import {
   dashboardAgentApiOrigin,
   isDashboardAgentConfigured,
   mintDashboardAgentUserActorToken,
+  resolveDashboardAgentRepoSnapshot,
 } from "~/services/dashboardAgent.server";
 import { logger } from "~/services/logger.server";
 import { requireUser } from "~/services/session.server";
@@ -42,19 +45,30 @@ const ENV_NAME_BY_TYPE: Record<string, string> = {
 
 const anthropic = createAnthropic({ apiKey: env.ANTHROPIC_API_KEY });
 
-const headStartHandler = chatServer.headStart({
-  agentId: "dashboard-agent",
-  apiClient: {
-    baseURL: dashboardAgentApiOrigin(),
-    accessToken: env.DASHBOARD_AGENT_SECRET_KEY,
-  },
-  run: async ({ chat: helper }) =>
-    streamText({
-      ...helper.toStreamTextOptions({ tools: dashboardAgentToolSchemas }),
-      model: anthropic(DASHBOARD_AGENT_MODEL),
-      system: DASHBOARD_AGENT_SYSTEM_PROMPT,
-    }),
-});
+function makeHeadStartHandler(mode: "assistant" | "code") {
+  const tools = mode === "code" ? dashboardAgentCodeToolSchemas : dashboardAgentToolSchemas;
+  const system = mode === "code" ? DASHBOARD_AGENT_CODE_SYSTEM_PROMPT : DASHBOARD_AGENT_SYSTEM_PROMPT;
+  return chatServer.headStart({
+    agentId: "dashboard-agent",
+    apiClient: {
+      baseURL: dashboardAgentApiOrigin(),
+      accessToken: env.DASHBOARD_AGENT_SECRET_KEY,
+    },
+    run: async ({ chat: helper }) =>
+      streamText({
+        ...helper.toStreamTextOptions({ tools }),
+        model: anthropic(DASHBOARD_AGENT_MODEL),
+        system,
+      }),
+  });
+}
+
+// Two warm-step variants so step 1 matches the mode the agent run will be in: the
+// `code` one offers the source tools + prompt when the project has a connected repo.
+const headStartHandlers = {
+  assistant: makeHeadStartHandler("assistant"),
+  code: makeHeadStartHandler("code"),
+};
 
 export async function action({ request, params }: ActionFunctionArgs) {
   const user = await requireUser(request);
@@ -84,6 +98,10 @@ export async function action({ request, params }: ActionFunctionArgs) {
   });
   const environmentName = runtimeEnv ? ENV_NAME_BY_TYPE[runtimeEnv.type] : undefined;
 
+  // Code mode when the project has a connected repo: drives both the warm step's
+  // tools/prompt and the metadata the agent run picks up.
+  const repoSnapshot = await resolveDashboardAgentRepoSnapshot(project.id);
+
   // Inject the delegated token + context into the wire payload's metadata,
   // which becomes the handover-prepare run's payload (server-side, never the
   // browser). The head-start body is the flat wire payload with a top-level
@@ -98,6 +116,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
       apiOrigin: dashboardAgentApiOrigin(),
       projectRef: project.externalRef,
       environmentName,
+      ...(repoSnapshot ? { repoSnapshot } : {}),
     };
     forwarded = new Request(request.url, {
       method: "POST",
@@ -109,7 +128,8 @@ export async function action({ request, params }: ActionFunctionArgs) {
   }
 
   try {
-    return await headStartHandler(forwarded);
+    const handler = repoSnapshot ? headStartHandlers.code : headStartHandlers.assistant;
+    return await handler(forwarded);
   } catch (error) {
     logger.error("Dashboard agent head-start failed", { error });
     return json({ error: "The dashboard agent couldn't start." }, { status: 502 });

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

@@ -4,6 +4,7 @@ import { findProjectBySlug } from "~/models/project.server";
 import {
   dashboardAgentApiOrigin,
   mintDashboardAgentUserActorToken,
+  resolveDashboardAgentRepoSnapshot,
 } from "~/services/dashboardAgent.server";
 import { logger } from "~/services/logger.server";
 import { requireUser } from "~/services/session.server";
@@ -71,6 +72,10 @@ export async function action({ request, params }: ActionFunctionArgs) {
   });
   const environmentName = runtimeEnv ? ENV_NAME_BY_TYPE[runtimeEnv.type] : undefined;
 
+  // When the project has a connected GitHub repo, resolve a signed source-archive
+  // pointer (code mode). Null otherwise -> the agent stays in assistant mode.
+  const repoSnapshot = await resolveDashboardAgentRepoSnapshot(project.id);
+
   // Inject the delegated token + context into the turn's metadata.
   const raw = await request.text();
   let body = raw;
@@ -86,6 +91,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
         apiOrigin,
         projectRef: project.externalRef,
         environmentName,
+        ...(repoSnapshot ? { repoSnapshot } : {}),
       };
       body = JSON.stringify(parsed);
     }

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

@@ -1,7 +1,10 @@
 import { signUserActorToken } from "@trigger.dev/rbac";
 import { TriggerClient } from "@trigger.dev/sdk";
 import { chat } from "@trigger.dev/sdk/ai";
+import { prisma } from "~/db.server";
 import { env } from "~/env.server";
+import { githubApp } from "./gitHub.server";
+import { logger } from "./logger.server";
 
 const TASK_ID = "dashboard-agent";
 
@@ -72,3 +75,90 @@ export async function mintDashboardAgentToken(chatId: string): Promise<string> {
     expirationTime: "1h",
   });
 }
+
+// A signed, short-lived pointer to the project's connected repo at a commit. Only
+// the URL crosses to the agent; the GitHub token stays here. The agent's code
+// tools download + extract it on their own filesystem (see @internal/dashboard-agent).
+export type DashboardAgentRepoSnapshot = {
+  tarballUrl: string;
+  owner: string;
+  repo: string;
+  sha: string;
+  defaultBranch?: string;
+};
+
+// The GitHub archive redirect URL is valid for a few minutes; cache the resolved
+// pointer briefly so multi-turn chats don't re-mint a token + re-resolve on every
+// message. Keyed by project.
+const repoSnapshotCache = new Map<string, { snapshot: DashboardAgentRepoSnapshot; expiresAt: number }>();
+const REPO_SNAPSHOT_TTL_MS = 60_000;
+
+/**
+ * Resolve the code-mode repo snapshot for a project, or null when the GitHub App
+ * is disabled / no repo is connected (which keeps the agent in assistant mode).
+ *
+ * Mints a `contents:read` installation token scoped to the one repo, resolves the
+ * signed archive URL for the tracked branch's head commit, and returns just that
+ * URL. The token never leaves the server.
+ */
+export async function resolveDashboardAgentRepoSnapshot(
+  projectId: string
+): Promise<DashboardAgentRepoSnapshot | null> {
+  if (!githubApp) return null;
+
+  const cached = repoSnapshotCache.get(projectId);
+  if (cached && cached.expiresAt > Date.now()) return cached.snapshot;
+
+  const connected = await prisma.connectedGithubRepository.findFirst({
+    where: { projectId },
+    select: {
+      branchTracking: true,
+      repository: {
+        select: {
+          fullName: true,
+          defaultBranch: true,
+          installation: { select: { appInstallationId: true } },
+        },
+      },
+    },
+  });
+  if (!connected) return null;
+
+  const [owner, repo] = connected.repository.fullName.split("/");
+  if (!owner || !repo) return null;
+  const installationId = Number(connected.repository.installation.appInstallationId);
+  const defaultBranch = connected.repository.defaultBranch;
+  const tracking = connected.branchTracking as { prod?: { branch?: string } } | null;
+  const ref = tracking?.prod?.branch || defaultBranch;
+
+  try {
+    const octokit = await githubApp.getInstallationOctokit(installationId);
+    const branch = await octokit.rest.repos.getBranch({ owner, repo, branch: ref });
+    const sha = branch.data.commit.sha;
+
+    const token = await githubApp.octokit.rest.apps.createInstallationAccessToken({
+      installation_id: installationId,
+      repositories: [repo],
+      permissions: { contents: "read" },
+    });
+
+    // Resolve the signed archive URL without downloading the bytes server-side.
+    const redirect = await fetch(`https://api.github.com/repos/${owner}/${repo}/tarball/${sha}`, {
+      headers: {
+        Authorization: `Bearer ${token.data.token}`,
+        Accept: "application/vnd.github+json",
+        "User-Agent": "trigger-dashboard-agent",
+      },
+      redirect: "manual",
+    });
+    const tarballUrl = redirect.headers.get("location");
+    if (!tarballUrl) return null;
+
+    const snapshot: DashboardAgentRepoSnapshot = { tarballUrl, owner, repo, sha, defaultBranch };
+    repoSnapshotCache.set(projectId, { snapshot, expiresAt: Date.now() + REPO_SNAPSHOT_TTL_MS });
+    return snapshot;
+  } catch (error) {
+    logger.error("Failed to resolve dashboard agent repo snapshot", { error, projectId });
+    return null;
+  }
+}

internal-packages/dashboard-agent/src/dashboard-agent.ts

@@ -21,7 +21,7 @@ import {
 } from "ai";
 import { z } from "zod";
 import type { EvalTurnPayload, evalTurn } from "./eval-turn";
-import { systemPrompt, titlePrompt } from "./prompts";
+import { codeSystemPrompt, systemPrompt, titlePrompt } from "./prompts";
 import { buildDashboardAgentTools } from "./tools";
 
 /**
@@ -105,8 +105,21 @@ export const dashboardAgentToolsKey = locals.create<ToolSet>("dashboard-agent.to
 // The system prompt is dashboard-managed (text + model + config). Resolving it
 // is an API call, so cache it per worker process — workers are short-lived
 // (idleTimeoutInSeconds), so a dashboard edit lands within a recycle.
+type DashboardAgentMode = "assistant" | "code";
+
+// A turn is in `code` mode when the `in` proxy injected a repo snapshot (i.e. the
+// current project has a connected repo). Drives both the tool set and the prompt.
+function modeFor(clientData: { repoSnapshot?: unknown } | undefined): DashboardAgentMode {
+  return clientData?.repoSnapshot ? "code" : "assistant";
+}
+
 let cachedSystemPrompt: Awaited<ReturnType<typeof systemPrompt.resolve>> | undefined;
-async function getSystemPrompt() {
+let cachedCodePrompt: Awaited<ReturnType<typeof codeSystemPrompt.resolve>> | undefined;
+async function getSystemPrompt(mode: DashboardAgentMode = "assistant") {
+  if (mode === "code") {
+    cachedCodePrompt ??= await codeSystemPrompt.resolve({});
+    return cachedCodePrompt;
+  }
   cachedSystemPrompt ??= await systemPrompt.resolve({});
   return cachedSystemPrompt;
 }
@@ -197,6 +210,17 @@ const clientDataSchema = z.object({
   apiOrigin: z.string().optional(),
   projectRef: z.string().optional(),
   environmentName: z.string().optional(),
+  // Injected only when the current project has a connected GitHub repo: a signed,
+  // short-lived archive pointer the code-mode source tools read from.
+  repoSnapshot: z
+    .object({
+      tarballUrl: z.string(),
+      owner: z.string(),
+      repo: z.string(),
+      sha: z.string(),
+      defaultBranch: z.string().optional(),
+    })
+    .optional(),
 });
 
 export const dashboardAgent = chat.agent({
@@ -232,17 +256,18 @@ export const dashboardAgent = chat.agent({
     });
   },
 
-  onTurnStart: async ({ chatId, uiMessages }) => {
+  onTurnStart: async ({ chatId, uiMessages, clientData }) => {
     // Make the user's message durable in the display copy before the model
     // starts streaming. Awaited, never chat.defer — a mid-stream refresh must
     // not read an empty transcript.
     await getStore().persistMessages({ chatId, messages: uiMessages });
 
-    // Load the dashboard-managed system prompt for this turn. Set every turn so
+    // Load the dashboard-managed system prompt for this turn. The code-mode
+    // variant is used when the project has a connected repo. Set every turn so
     // continuation runs (which skip onChatStart) still get it; the resolve is
     // cached per process. The Anthropic cache breakpoint on the system block
     // carries through toStreamTextOptions() and survives suspend/resume.
-    chat.prompt.set(await getSystemPrompt(), {
+    chat.prompt.set(await getSystemPrompt(modeFor(clientData)), {
       providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
     });
   },
@@ -284,7 +309,7 @@ export const dashboardAgent = chat.agent({
     // sample rate here when this scales.
     if (clientData?.organizationId && clientData?.userId && responseMessage) {
       try {
-        const resolved = await getSystemPrompt();
+        const resolved = await getSystemPrompt(modeFor(clientData));
         // The current turn's question. On a Head Start turn it arrives in the
         // boot payload (not in newUIMessages), so take the latest user message
         // from the full transcript, which holds for normal turns too.

internal-packages/dashboard-agent/src/prompts.ts

@@ -1,5 +1,9 @@
 import { prompts } from "@trigger.dev/sdk";
-import { DASHBOARD_AGENT_MODEL, DASHBOARD_AGENT_SYSTEM_PROMPT } from "./tool-schemas";
+import {
+  DASHBOARD_AGENT_CODE_SYSTEM_PROMPT,
+  DASHBOARD_AGENT_MODEL,
+  DASHBOARD_AGENT_SYSTEM_PROMPT,
+} from "./tool-schemas";
 
 /**
  * Managed prompts for the dashboard agent. Defining them here registers them
@@ -20,6 +24,15 @@ export const systemPrompt = prompts.define({
   content: DASHBOARD_AGENT_SYSTEM_PROMPT,
 });
 
+// Code mode: used for turns where the current project has a connected GitHub
+// repo, so the agent has the source-reading tools too.
+export const codeSystemPrompt = prompts.define({
+  id: "dashboard-agent-system-code",
+  description: "System prompt for the in-dashboard agent when the project's GitHub repo is connected.",
+  model: `anthropic:${DASHBOARD_AGENT_MODEL}`,
+  content: DASHBOARD_AGENT_CODE_SYSTEM_PROMPT,
+});
+
 export const titlePrompt = prompts.define({
   id: "dashboard-agent-title",
   description: "Generates a short title for a dashboard agent conversation.",