feat(dashboard-agent): explicit project/environment target on every read tool

Every environment-bound read now accepts project/environment/branch, with the
chat's own scope as the default rather than the limit: list_tasks, list_errors,
get_query_schema, run_query, get_report, list_deploys and get_deploy join the
tools that already had it, and the source tools pass the target through the
run-snapshot resolution. run_query's POST goes out on the target's env JWT.

Preview and dev branches are targetable as environment "preview"/"dev" plus the
branchName list_environments returned, forwarded as x-trigger-branch on both the
JWT exchange and the delegated-token routes.

A target naming a project that list_projects did not report this turn is refused
before any exchange. That is client hygiene to save a pointless round trip, not a
boundary: authorization stays server-side on the exchange and every route.

Prompt prefix grows to 80,937 chars (assistant) / 88,550 (code); the ceilings and
the committed measurement move with it.

Author: kathiekiwi

internal-packages/dashboard-agent/src/__snapshots__/prompt-prefix.test.ts.snap

@@ -88,8 +88,8 @@ describe("the head-start and agent prefixes are the same prefix", () => {
  * drift. The snapshot below is the itemised diff a reviewer reads.
  */
 const PREFIX_BUDGET = {
-  assistant: { chars: 77_500, estimatedTokens: 19_500, tools: 24, promptChars: 27_000 },
-  code: { chars: 83_500, estimatedTokens: 21_000, tools: 28, promptChars: 29_600 },
+  assistant: { chars: 81_300, estimatedTokens: 20_600, tools: 24, promptChars: 27_800 },
+  code: { chars: 88_900, estimatedTokens: 22_500, tools: 28, promptChars: 30_300 },
 } as const;
 
 describe("the prefix stays inside its budget", () => {

internal-packages/dashboard-agent/src/prompt-prefix.test.ts

@@ -6,6 +6,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { sliceWellFormed } from "@internal/dashboard-agent-contracts";
 import { tool, type ToolSet } from "ai";
+import { crossProjectTarget, type ApiTarget, type TargetInput } from "./tool-api-client";
 import {
   getRepoInfoSchema,
   listFilesSchema,
@@ -209,19 +210,25 @@ export async function disposeRepoWorkspaces(): Promise<void> {
 }
 
 /** Resolve a run-pinned snapshot for a runId, or null. See the webapp's repo/snapshot route. */
-export type RunSnapshotResolver = (runId: string) => Promise<RepoSnapshot | null>;
+export type RunSnapshotResolver = (
+  runId: string,
+  target?: ApiTarget
+) => Promise<RepoSnapshot | null>;
 
 export function buildRepoTools(
   defaultSnapshot: RepoSnapshot,
   resolveRunSnapshot?: RunSnapshotResolver
 ): ToolSet {
   // Pick the snapshot for a call: a runId pins to that run's deployed commit
   // (resolved server-side), otherwise the default tracked-branch snapshot.
-  async function snapshotFor(runId?: string): Promise<RepoSnapshot | { error: string }> {
+  async function snapshotFor(
+    runId?: string,
+    target?: TargetInput
+  ): Promise<RepoSnapshot | { error: string }> {
     if (!runId) return defaultSnapshot;
     if (!resolveRunSnapshot)
       return { error: "Reading a specific run's source isn't available here." };
-    const snap = await resolveRunSnapshot(runId);
+    const snap = await resolveRunSnapshot(runId, target && crossProjectTarget(target));
     return (
       snap ?? {
         error: `Couldn't resolve the source for ${runId} (it may be a dev run, or the project has no connected repo).`,
@@ -232,9 +239,10 @@ export function buildRepoTools(
   // snapshotFor + ensureWorkspace, returning the workdir (plus the snapshot's dirty
   // stamp, for tools that surface it) or an error result.
   async function loadWorkdir(
-    runId?: string
+    runId?: string,
+    target?: TargetInput
   ): Promise<{ workdir: string; dirty: boolean } | { error: string }> {
-    const snap = await snapshotFor(runId);
+    const snap = await snapshotFor(runId, target);
     if ("error" in snap) return snap;
     try {
       // Canonicalize the root so the per-tool realpath checks below compare
@@ -251,8 +259,8 @@ export function buildRepoTools(
   return {
     get_repo_info: tool({
       ...getRepoInfoSchema,
-      execute: async ({ runId }) => {
-        const snap = await snapshotFor(runId);
+      execute: async ({ runId, project, environment, branch }) => {
+        const snap = await snapshotFor(runId, { project, environment, branch });
         if ("error" in snap) return snap;
         return {
           owner: snap.owner,
@@ -266,8 +274,8 @@ export function buildRepoTools(
 
     list_files: tool({
       ...listFilesSchema,
-      execute: async ({ glob, path, runId }) => {
-        const loaded = await loadWorkdir(runId);
+      execute: async ({ glob, path, runId, project, environment, branch }) => {
+        const loaded = await loadWorkdir(runId, { project, environment, branch });
         if ("error" in loaded) return loaded;
         const { workdir } = loaded;
         const args = ["--files"];
@@ -300,8 +308,8 @@ export function buildRepoTools(
 
     read_file: tool({
       ...readFileSchema,
-      execute: async ({ path, startLine, endLine, runId }) => {
-        const loaded = await loadWorkdir(runId);
+      execute: async ({ path, startLine, endLine, runId, project, environment, branch }) => {
+        const loaded = await loadWorkdir(runId, { project, environment, branch });
         if ("error" in loaded) return loaded;
         const { workdir, dirty } = loaded;
         const target = safeResolve(workdir, path);
@@ -350,8 +358,8 @@ export function buildRepoTools(
 
     search_code: tool({
       ...searchCodeSchema,
-      execute: async ({ query, glob, maxResults, runId }) => {
-        const loaded = await loadWorkdir(runId);
+      execute: async ({ query, glob, maxResults, runId, project, environment, branch }) => {
+        const loaded = await loadWorkdir(runId, { project, environment, branch });
         if ("error" in loaded) return loaded;
         const { workdir } = loaded;
         const cap = Math.min(maxResults ?? 40, MAX_MATCHES);

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

@@ -132,7 +132,11 @@ export type DashboardAgentApiClient = {
   hasAuth: boolean;
   /** A GET as the environment JWT, or why no environment JWT could be made. */
   envApiGet(path: string, target?: ApiTarget): Promise<EnvFetchResult>;
-  postQuery(query: string, period: string | undefined): Promise<QueryPostResult | EnvUnavailable>;
+  postQuery(
+    query: string,
+    period: string | undefined,
+    target?: ApiTarget
+  ): Promise<QueryPostResult | EnvUnavailable>;
   validateChartQuery(query: string, period: string | undefined): Promise<string | null>;
   /**
    * The canonical RuntimeEnvironment id for a target, proven by the same JWT exchange
@@ -153,8 +157,26 @@ export type ApiClientContext = {
 
 // A per-call override of which project/environment a data lookup targets, for reads
 // that cross into another project of the same organization. Omitted fields fall back
-// to the context's own project/environment.
-export type ApiTarget = { projectRef?: string; environmentName?: string };
+// to the context's own project/environment. `branch` picks a preview/dev branch out of
+// the family its name addresses; without it the name resolves to the parent.
+export type ApiTarget = { projectRef?: string; environmentName?: string; branch?: string };
+
+/** A tool call's explicit target: the project, environment and branch it names. */
+export type TargetInput = { project?: string; environment?: string; branch?: string };
+
+/**
+ * A tool call's optional target as an `ApiTarget`. `undefined` when nothing was given, so
+ * the default (ctx-scoped, branch-aware) path is unchanged rather than re-derived from ctx
+ * through an override.
+ */
+export function crossProjectTarget(input: TargetInput): ApiTarget | undefined {
+  if (!input.project && !input.environment && !input.branch) return undefined;
+  return {
+    projectRef: input.project,
+    environmentName: input.environment,
+    branch: input.branch,
+  };
+}
 
 export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient {
   const { userActorToken, apiOrigin, projectRef, environmentName, environmentBranch } = ctx;
@@ -166,12 +188,12 @@ export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient
   type EnvJwt = { ok: true; token: string } | EnvUnavailable;
   const envJwts = new Map<string, Promise<EnvJwt>>();
   function getEnvJwt(refresh = false, target?: ApiTarget): Promise<EnvJwt> {
-    // An override drops the branch: it names another project/environment, which the
-    // current branch can't be assumed to apply to. A field left off the override still
-    // falls back to ctx's own value.
+    // An override carries its own branch or none: it names another project/environment,
+    // which the current branch can't be assumed to apply to. A field left off the override
+    // still falls back to ctx's own value.
     const ref = target?.projectRef ?? projectRef;
     const env = target?.environmentName ?? environmentName;
-    const branch = target ? undefined : environmentBranch;
+    const branch = target ? target.branch : environmentBranch;
     if (!hasAuth || !ref || !env) return Promise.resolve(MISSING_ENV);
     const key = `${ref}/${env}/${branch ?? ""}`;
     if (refresh) envJwts.delete(key);
@@ -216,7 +238,8 @@ export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient
   // re-exchange on a 401. Shared by run_query and chart-block validation.
   async function postQuery(
     query: string,
-    period: string | undefined
+    period: string | undefined,
+    target?: ApiTarget
   ): Promise<QueryPostResult | EnvUnavailable> {
     const attempt = await withEnvJwt<{ res: Response } | { error: string }>(
       async (jwt) => {
@@ -237,7 +260,8 @@ export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient
           return { error: `Query request failed: ${(error as Error).message}` };
         }
       },
-      (result) => "res" in result && result.res.status === 401
+      (result) => "res" in result && result.res.status === 401,
+      target
     );
     if (isEnvUnavailable(attempt)) return attempt;
     if ("error" in attempt) return { ok: false, kind: "transport", error: attempt.error };