feat(dashboard-agent): locate tool replaces the not-found sweep

Author: kathiekiwi

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

@@ -1349,6 +1349,7 @@ describe("buildDashboardAgentTools", () => {
         "list_projects",
         "list_runs",
         "list_tasks",
+        "locate",
         "navigate_to",
         "run_query",
         "render_view",

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

@@ -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: 81_300, estimatedTokens: 20_600, tools: 24, promptChars: 27_800 },
-  code: { chars: 88_900, estimatedTokens: 22_500, tools: 28, promptChars: 30_300 },
+  assistant: { chars: 79_400, estimatedTokens: 20_100, tools: 25, promptChars: 27_500 },
+  code: { chars: 87_000, estimatedTokens: 22_000, tools: 29, promptChars: 30_100 },
 } as const;
 
 describe("the prefix stays inside its budget", () => {

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

@@ -16,6 +16,7 @@ import {
   listProjectsSchema,
   listRunsSchema,
   listTasksSchema,
+  locateSchema,
   renderViewSchema,
   runQuerySchema,
   searchDocsSchema,
@@ -215,6 +216,38 @@ export function withLiveState(metrics: unknown, queueType: "task" | "custom", li
   };
 }
 
+/**
+ * The org-wide locator. A user-level route, so it spends the delegated token directly, and
+ * the organization comes only from that token's claim — never from the model.
+ */
+export function buildLocateTool(args: {
+  ctx: DashboardAgentToolContext;
+  client: DashboardAgentApiClient;
+}): ToolSet {
+  const { userActorToken } = args.ctx;
+  const { origin, hasAuth } = args.client;
+  return {
+    locate: tool({
+      ...locateSchema,
+      execute: async ({ kind, id }) => {
+        if (!hasAuth) return NO_AUTH;
+        const result = await apiGet(
+          origin,
+          `/api/v1/locate/${kind}/${encodeURIComponent(id)}`,
+          userActorToken!
+        );
+        // A failed locate is not a `found: false`: it never proves absence.
+        if (!result.ok) {
+          return {
+            error: `Couldn't locate ${kind} ${id}${fetchReason(result)}. That is not evidence it doesn't exist.`,
+          };
+        }
+        return result.data;
+      },
+    }),
+  };
+}
+
 /** Failed `run_query` calls in a row before the tool tells the model to stop and answer. */
 export const MAX_CONSECUTIVE_QUERY_FAILURES = 3;
 
@@ -774,7 +807,7 @@ export function buildApiTools(args: {
           if ("status" in result && result.status === 404) {
             const scope = target ? "that project/environment" : "the current environment";
             return {
-              error: `No commit found for run ${runId} in ${scope}. That is not evidence the run isn't locked to a deployment — sweep (list_projects, then get_run with project/environment) before concluding, then retry this call with project/environment for wherever it's found.`,
+              error: `No commit found for run ${runId} in ${scope}. That is not evidence the run isn't locked to a deployment — call locate before concluding, then retry this call with the project/environment it names.`,
             };
           }
           return { error: `Couldn't resolve the commit for ${runId}${fetchReason(result)}.` };

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

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildLocateTool } from "./tool-api";
+import { createApiClient } from "./tool-api-client";
+
+/**
+ * The org-wide locator replaces the model-driven not-found sweep, so what it hands back
+ * has to keep "not here" and "couldn't look" apart: only the route's own `found: false`
+ * is an absence.
+ */
+
+const ORIGIN = "https://api.example.com";
+
+let calls: Array<{ url: string; auth: string | null }> = [];
+
+function stubFetch(reply: (url: string) => Response) {
+  return vi.fn(async (input: any, init: any = {}) => {
+    const url = typeof input === "string" ? input : input.url;
+    calls.push({ url, auth: new Headers(init.headers ?? {}).get("authorization") });
+    return reply(url);
+  });
+}
+
+function locate(overrides: Record<string, unknown> = {}) {
+  const ctx = {
+    userActorToken: "uat",
+    apiOrigin: ORIGIN,
+    projectRef: "proj_current",
+    environmentName: "prod",
+    ...overrides,
+  };
+  return buildLocateTool({ ctx, client: createApiClient(ctx) }).locate as any;
+}
+
+beforeEach(() => (calls = []));
+afterEach(() => vi.unstubAllGlobals());
+
+describe("locate", () => {
+  it("asks the org-wide route with the delegated token and passes the scopes through", async () => {
+    const found = {
+      found: true,
+      checked: "organization",
+      scopes: [
+        {
+          projectRef: "proj_other",
+          projectName: "Other",
+          environmentName: "preview",
+          environmentType: "PREVIEW",
+          branchName: "feat/x",
+          targetable: true,
+        },
+      ],
+    };
+    vi.stubGlobal(
+      "fetch",
+      stubFetch(() => Response.json(found))
+    );
+
+    const result = await locate().execute({ kind: "run", id: "run_abc" }, {} as any);
+
+    expect(calls).toEqual([{ url: `${ORIGIN}/api/v1/locate/run/run_abc`, auth: "Bearer uat" }]);
+    expect(result).toEqual(found);
+  });
+
+  it("passes a not-found through verbatim", async () => {
+    vi.stubGlobal(
+      "fetch",
+      stubFetch(() => Response.json({ found: false, checked: "organization" }))
+    );
+
+    expect(await locate().execute({ kind: "error", id: "error_abc" }, {} as any)).toEqual({
+      found: false,
+      checked: "organization",
+    });
+    expect(calls[0].url).toBe(`${ORIGIN}/api/v1/locate/error/error_abc`);
+  });
+
+  it("reports a 401 or 403 as a failed lookup, never as an absence", async () => {
+    for (const status of [401, 403]) {
+      calls = [];
+      vi.stubGlobal(
+        "fetch",
+        stubFetch(() => new Response("", { status }))
+      );
+
+      const result = await locate().execute({ kind: "run", id: "run_abc" }, {} as any);
+
+      expect(result).toEqual({
+        error: `Couldn't locate run run_abc (status ${status}). That is not evidence it doesn't exist.`,
+      });
+    }
+  });
+
+  it("says so when the turn has no delegated access", async () => {
+    vi.stubGlobal(
+      "fetch",
+      stubFetch(() => Response.json({}))
+    );
+
+    const result = await locate({ userActorToken: undefined }).execute(
+      { kind: "run", id: "run_abc" },
+      {} as any
+    );
+
+    expect(result).toEqual({ error: "No delegated access is available for this turn." });
+    expect(calls).toEqual([]);
+  });
+});