feat(dashboard-agent): let data lookups target another project/environment

Add a per-call project/environment override on list_runs, get_run,
get_run_trace, get_error, and get_queue, so a not-found lookup can be
retried elsewhere in the org. The env-JWT exchange targets and caches
per override; the default (no-override) path is unchanged. System
prompt gains the grounding rule to retry and name where it was found.

Author: kathiekiwi

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

@@ -115,7 +115,7 @@ export type DashboardAgentApiClient = {
   /** Whether this turn has both a delegated token and an origin to spend it on. */
   hasAuth: boolean;
   /** A GET as the environment JWT, or why no environment JWT could be made. */
-  envApiGet(path: string): Promise<EnvFetchResult>;
+  envApiGet(path: string, target?: ApiTarget): Promise<EnvFetchResult>;
   postQuery(query: string, period: string | undefined): Promise<QueryPostResult | EnvUnavailable>;
   validateChartQuery(query: string, period: string | undefined): Promise<string | null>;
 };
@@ -128,6 +128,11 @@ export type ApiClientContext = {
   environmentBranch?: string;
 };
 
+// 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 };
+
 export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient {
   const { userActorToken, apiOrigin, projectRef, environmentName, environmentBranch } = ctx;
   const origin = apiOrigin ? apiOrigin.replace(/\/$/, "") : "";
@@ -137,20 +142,20 @@ export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient
   // environment. Caching the promise makes concurrent calls share one exchange.
   type EnvJwt = { ok: true; token: string } | EnvUnavailable;
   const envJwts = new Map<string, Promise<EnvJwt>>();
-  function getEnvJwt(refresh = false): Promise<EnvJwt> {
-    if (!hasAuth || !projectRef || !environmentName) return Promise.resolve(MISSING_ENV);
-    const key = `${projectRef}/${environmentName}/${environmentBranch ?? ""}`;
+  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.
+    const ref = target?.projectRef ?? projectRef;
+    const env = target?.environmentName ?? environmentName;
+    const branch = target ? undefined : environmentBranch;
+    if (!hasAuth || !ref || !env) return Promise.resolve(MISSING_ENV);
+    const key = `${ref}/${env}/${branch ?? ""}`;
     if (refresh) envJwts.delete(key);
     let pending = envJwts.get(key);
     if (!pending) {
       // A failed exchange is not cached: a 403 or a 5xx would otherwise pin the whole turn.
-      pending = exchangeEnvJwt(
-        origin,
-        userActorToken!,
-        projectRef,
-        environmentName,
-        environmentBranch
-      ).then((result) => {
+      pending = exchangeEnvJwt(origin, userActorToken!, ref, env, branch).then((result) => {
         if (!result.ok) envJwts.delete(key);
         return result;
       });
@@ -165,22 +170,23 @@ export function createApiClient(ctx: ApiClientContext): DashboardAgentApiClient
    */
   async function withEnvJwt<T extends object>(
     call: (jwt: string) => Promise<T>,
-    isUnauthorized: (result: T) => boolean
+    isUnauthorized: (result: T) => boolean,
+    target?: ApiTarget
   ): Promise<T | EnvUnavailable> {
-    const jwt = await getEnvJwt();
+    const jwt = await getEnvJwt(false, target);
     if (!jwt.ok) return jwt;
     const first = await call(jwt.token);
     if (!isUnauthorized(first)) return first;
-    const fresh = await getEnvJwt(true);
+    const fresh = await getEnvJwt(true, target);
     if (!fresh.ok) return first;
     return call(fresh.token);
   }
 
   const unauthorizedGet = (result: FetchResult) =>
     !result.ok && "status" in result && result.status === 401;
 
-  function envApiGet(path: string): Promise<EnvFetchResult> {
-    return withEnvJwt((jwt) => apiGet(origin, path, jwt), unauthorizedGet);
+  function envApiGet(path: string, target?: ApiTarget): Promise<EnvFetchResult> {
+    return withEnvJwt((jwt) => apiGet(origin, path, jwt), unauthorizedGet, target);
   }
 
   // A POST, so it can't use envApiGet, but keeps the same JWT cache and one-shot

internal-packages/dashboard-agent/src/tool-api-client.ts

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ZodTypeAny } from "zod";
+import { buildApiTools } from "./tool-api";
+import { createApiClient } from "./tool-api-client";
+import {
+  getErrorSchema,
+  getQueueSchema,
+  getRunSchema,
+  getRunTraceSchema,
+  listRunsSchema,
+} from "./tool-schemas";
+
+/**
+ * The `project`/`environment` override on data lookups: the JWT exchange has to target
+ * the override, not ctx, and cache per target the same way the default path does. The
+ * default path (no override) must be byte-for-byte unchanged.
+ */
+
+const ORIGIN = "https://api.example.com";
+
+type Call = { url: string; body?: unknown };
+let calls: Call[] = [];
+
+function stubFetch() {
+  return vi.fn(async (input: any, init: any = {}) => {
+    const url = typeof input === "string" ? input : input.url;
+    calls.push({ url, body: init.body ? JSON.parse(init.body) : undefined });
+    if (url.endsWith("/jwt")) {
+      // The env JWT is minted for whichever project/environment segment the exchange
+      // addressed, so the token echoes it back for the assertions below.
+      const match = url.match(/\/api\/v1\/projects\/([^/]+)\/([^/]+)\/jwt$/);
+      return Response.json({ token: `jwt:${match![1]}/${match![2]}` });
+    }
+    return Response.json({ data: [] });
+  });
+}
+
+function tools() {
+  const ctx = {
+    userActorToken: "uat",
+    apiOrigin: ORIGIN,
+    projectRef: "proj_current",
+    environmentName: "prod",
+  };
+  return buildApiTools({
+    ctx,
+    client: createApiClient(ctx),
+    renderInvestigations: (() => []) as any,
+    spanLedger: { recordTraceSpans: () => {} },
+  });
+}
+
+const jwtCalls = () => calls.filter((c) => c.url.endsWith("/jwt"));
+
+beforeEach(() => {
+  calls = [];
+  vi.stubGlobal("fetch", stubFetch());
+});
+afterEach(() => vi.unstubAllGlobals());
+
+describe("the project/environment override", () => {
+  it("exchanges the JWT for the overridden project and environment, not ctx's", async () => {
+    const t = tools();
+
+    await (t.list_runs as any).execute(
+      { project: "proj_other", environment: "staging" },
+      {} as any
+    );
+
+    expect(jwtCalls()).toHaveLength(1);
+    expect(jwtCalls()[0].url).toBe(`${ORIGIN}/api/v1/projects/proj_other/staging/jwt`);
+  });
+
+  it("leaves the default path (no override) unchanged", async () => {
+    const t = tools();
+
+    await (t.list_runs as any).execute({}, {} as any);
+
+    expect(jwtCalls()).toHaveLength(1);
+    expect(jwtCalls()[0].url).toBe(`${ORIGIN}/api/v1/projects/proj_current/prod/jwt`);
+  });
+
+  it("caches the exchanged JWT per target within the turn", async () => {
+    const t = tools();
+
+    await (t.list_runs as any).execute(
+      { project: "proj_other", environment: "staging" },
+      {} as any
+    );
+    await (t.get_error as any).execute(
+      { errorId: "error_1", project: "proj_other", environment: "staging" },
+      {} as any
+    );
+    await (t.list_runs as any).execute({}, {} as any);
+
+    // One exchange for the override target, one for the default target — never re-exchanged.
+    expect(jwtCalls()).toHaveLength(2);
+  });
+
+  it("defaults environment to the current environment's name when only project is given", async () => {
+    const t = tools();
+
+    await (t.get_run as any).execute({ runId: "run_1", project: "proj_other" }, {} as any);
+
+    expect(jwtCalls()[0].url).toBe(`${ORIGIN}/api/v1/projects/proj_other/prod/jwt`);
+  });
+});
+
+describe("project/environment schema round-trip", () => {
+  it.each([
+    ["list_runs", listRunsSchema, {}],
+    ["get_run", getRunSchema, { runId: "run_1" }],
+    ["get_run_trace", getRunTraceSchema, { runId: "run_1" }],
+    ["get_error", getErrorSchema, { errorId: "error_1" }],
+    ["get_queue", getQueueSchema, { queue: "my-queue" }],
+  ])("%s accepts project/environment and stays valid without them", (_name, schema, base) => {
+    const inputSchema = schema.inputSchema as ZodTypeAny;
+    const withOverride = inputSchema.safeParse({
+      ...base,
+      project: "proj_other",
+      environment: "staging",
+    });
+    expect(withOverride.success).toBe(true);
+
+    const withoutOverride = inputSchema.safeParse(base);
+    expect(withoutOverride.success).toBe(true);
+  });
+});