yontrack-mcp 1.13.0 → 1.14.1

package/README.md

@@ -9,6 +9,8 @@ The server uses the [Streamable HTTP transport](https://modelcontextprotocol.io/
 - **Read-only by default** — only query tools are active unless mutations are explicitly enabled
 - **Mutation tools** — create projects, branches, builds, validation stamps/runs, promotion levels/runs, and build links (opt-in via `YONTRACK_MUTATIONS_ENABLED=true`)
 - **Raw GraphQL access** — `graphql_query` tool for queries not covered by the dedicated tools
+- **Agent-context tools (Yontrack 6+)** — readiness, change log since what is deployed, what is deployed where, dependency builds at a level, agent policy
+- **Agent sessions** — forwards the agent session to Yontrack so that what an agent records is attributed to its session
 - **OAuth2 support** — required for claude.ai; enabled by setting two environment variables
 - **Docker image** — published to Docker Hub on every release (`nemerosa/yontrack-mcp:latest`)
 - **Helm chart** — OCI chart for Kubernetes deployments with full secret management support
@@ -32,6 +34,31 @@ By default only read-only tools are available. Set `YONTRACK_MUTATIONS_ENABLED=t
 
 > ✝ `graphql_query` is always registered but rejects requests whose query string starts with `mutation` when `YONTRACK_MUTATIONS_ENABLED` is not set.
 
+### Agent-context tools (Yontrack 6+)
+
+Read-only tools answering the questions an agent asks before promoting or deploying. They return compact JSON (names, `displayName`, statuses, missing items with their kinds, commit assistants) with links to the Yontrack UI when `YONTRACK_UI_URL` is set.
+
+| Tool | Answers |
+|---|---|
+| `build_readiness` | Is a build ready for a promotion level or a slot (environment + optional qualifier), and what is missing? |
+| `changes_since_deployed` | What changed (commits with their assistants, issues, dependency changes) between what is deployed in a slot, or the last build at a promotion level on the same branch, and a candidate build? |
+| `deployments` | What is deployed where for a project, and which pipelines are in progress? |
+| `dependency_builds_at_level` | Which builds of a dependency project are at a given promotion level? |
+| `agent_policy` | What may the agent behind the token do on a project? (`{ "agent": false }` for a human token) |
+
+These tools are **only available with Yontrack 6**. The server detects them by probing the Yontrack schema (for the `Readiness` and `AgentPolicy` types), not by reading its version: on Yontrack 5 they are not listed at all. The probe runs once per process; when Yontrack cannot be reached, the tools are hidden and the next request probes again (in `stdio` mode the server is built once, so restart it). Set `YONTRACK_AGENT_TOOLS` to `true` or `false` to skip the probe.
+
+On Yontrack 6, the `yontrack://schema` resource also serves the Yontrack 6 schema instead of the Yontrack 5 one.
+
+### Agent sessions
+
+When an agent uses this server with the token of an **agent account** (Yontrack 6), Yontrack can attribute what it records (builds, validations, promotions…) to the agent's session. The server sends the `X-Yontrack-Agent-Session` and `X-Yontrack-Agent-Session-Link` headers on every request to Yontrack, taken from:
+
+1. the same headers on the incoming MCP request, when it carries any (a shared HTTP deployment serving several agents), or else
+2. the `YONTRACK_AGENT_SESSION` and `YONTRACK_AGENT_SESSION_LINK` environment variables (one server process per agent, e.g. `stdio`).
+
+The session and its link are always taken together from the same source, and never invented: nothing is sent when neither is set. Yontrack validates them (at most 255 characters for the session, an absolute `https` URL for the link) and ignores them for human tokens and on Yontrack 5.
+
 ## Installation
 
 ### Cursor
@@ -124,6 +151,8 @@ helm install yontrack-mcp \
 | `yontrack.url` | URL of the Yontrack instance | `""` |
 | `yontrack.token` | Yontrack API token | `""` |
 | `yontrack.mutationsEnabled` | Enable mutation tools (create/promote/link operations) | `false` |
+| `yontrack.agentTools` | Agent-context tools: `auto` (detected on Yontrack 6), `true` or `false` | `auto` |
+| `yontrack.uiUrl` | URL of the Yontrack UI, for the links in the agent-context tools | `""` |
 | `oauth.serverUrl` | Public HTTPS URL of this server — enables OAuth2 when set with `oauth.authPassword` | `""` |
 | `oauth.authPassword` | Password for the browser authorization form — enables OAuth2 when set with `oauth.serverUrl` | `""` |
 | `persistence.enabled` | Create a PVC and mount it at `/data`; sets the clients file to `/data/clients.json` | `true` |
@@ -295,6 +324,10 @@ An API token is required to authenticate against Yontrack. To generate one, log
 | `YONTRACK_URL`               | Yes      | —                             | URL of the Yontrack instance (e.g. `https://yontrack.example.com`)                                                                                                                   |
 | `YONTRACK_TOKEN`             | Yes      | —                             | API token for authenticating against Yontrack                                                                                                                                        |
 | `YONTRACK_MUTATIONS_ENABLED` | No       | `false`                       | Set to `true` to enable mutation tools (create/promote/link operations). When unset or `false`, only read-only query tools are registered.                                           |
+| `YONTRACK_AGENT_TOOLS`       | No       | `auto`                        | Agent-context tools: `auto` registers them when Yontrack 6 is detected, `true` always, `false` never. See [Agent-context tools](#agent-context-tools-yontrack-6).                       |
+| `YONTRACK_UI_URL`            | No       | —                             | URL of the Yontrack UI (e.g. `https://yontrack.example.com`), used for the links returned by the agent-context tools. Links are left out when unset.                                |
+| `YONTRACK_AGENT_SESSION`     | No       | —                             | Agent session ID sent to Yontrack when the incoming MCP request carries no session headers. See [Agent sessions](#agent-sessions).                                                |
+| `YONTRACK_AGENT_SESSION_LINK`| No       | —                             | Link to the agent session (absolute `https` URL), sent together with `YONTRACK_AGENT_SESSION`.                                                                                      |
 | `YONTRACK_MCP_SERVER_URL`    | No       | —                             | Public HTTPS URL of this server. When set together with `YONTRACK_MCP_AUTH_PASSWORD`, enables OAuth2 (required for claude.ai).                                                       |
 | `YONTRACK_MCP_AUTH_PASSWORD` | No       | —                             | Password users must enter in the browser authorization form. Required together with `YONTRACK_MCP_SERVER_URL` to enable OAuth2.                                                      |
 | `YONTRACK_MCP_CLIENTS_FILE`  | No       | `./yontrack-mcp-clients.json` | File path where registered OAuth2 clients are persisted so they survive restarts. The Helm chart sets this automatically to `/data/clients.json` when `persistence.enabled` is true. |

package/build/capabilities.js

@@ -0,0 +1,40 @@
+import { gqlClient } from "./client.js";
+import { config } from "./config.js";
+const PROBE = `
+  query ProbeCapabilities {
+    readiness: __type(name: "Readiness") { name }
+    agentPolicy: __type(name: "AgentPolicy") { name }
+  }
+`;
+const NONE = { agentTools: false, agentPolicy: false };
+const ALL = { agentTools: true, agentPolicy: true };
+/**
+ * A definite answer is cached for the life of the probe. A probe error is not
+ * cached: the tools are hidden for that call and the next call probes again.
+ */
+export function createCapabilityProbe(mode) {
+    let cached;
+    async function get() {
+        if (mode === "true")
+            return ALL;
+        if (mode === "false")
+            return NONE;
+        if (cached)
+            return cached;
+        try {
+            const data = await gqlClient.request(PROBE);
+            cached = {
+                agentTools: data.readiness != null,
+                agentPolicy: data.agentPolicy != null,
+            };
+            return cached;
+        }
+        catch (err) {
+            process.stderr.write(`Could not probe Yontrack capabilities, hiding agent-context tools for now: ${err instanceof Error ? err.message : String(err)}\n`);
+            return NONE;
+        }
+    }
+    return { get };
+}
+const probe = createCapabilityProbe(config.YONTRACK_AGENT_TOOLS);
+export const getCapabilities = probe.get;

package/build/capabilities.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createCapabilityProbe } from "./capabilities.js";
+vi.mock("./client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("./client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("capability probe (auto)", () => {
+    it("detects Yontrack 6 when both Readiness and AgentPolicy exist", async () => {
+        mockRequest.mockResolvedValueOnce({
+            readiness: { name: "Readiness" },
+            agentPolicy: { name: "AgentPolicy" },
+        });
+        const probe = createCapabilityProbe("auto");
+        expect(await probe.get()).toEqual({ agentTools: true, agentPolicy: true });
+    });
+    it("detects Yontrack 5 when neither type exists", async () => {
+        mockRequest.mockResolvedValueOnce({ readiness: null, agentPolicy: null });
+        const probe = createCapabilityProbe("auto");
+        expect(await probe.get()).toEqual({ agentTools: false, agentPolicy: false });
+    });
+    it("enables agent tools without agent_policy when only Readiness exists", async () => {
+        mockRequest.mockResolvedValueOnce({ readiness: { name: "Readiness" }, agentPolicy: null });
+        const probe = createCapabilityProbe("auto");
+        expect(await probe.get()).toEqual({ agentTools: true, agentPolicy: false });
+    });
+    it("caches a definite answer for the life of the probe", async () => {
+        mockRequest.mockResolvedValueOnce({ readiness: null, agentPolicy: null });
+        const probe = createCapabilityProbe("auto");
+        await probe.get();
+        await probe.get();
+        expect(mockRequest).toHaveBeenCalledTimes(1);
+    });
+    it("hides the tools on a probe error and probes again next time", async () => {
+        mockRequest
+            .mockRejectedValueOnce(new Error("connection refused"))
+            .mockResolvedValueOnce({ readiness: { name: "Readiness" }, agentPolicy: { name: "AgentPolicy" } });
+        const probe = createCapabilityProbe("auto");
+        expect(await probe.get()).toEqual({ agentTools: false, agentPolicy: false });
+        expect(await probe.get()).toEqual({ agentTools: true, agentPolicy: true });
+        expect(mockRequest).toHaveBeenCalledTimes(2);
+    });
+});
+describe("capability probe (override)", () => {
+    it("forces the tools on without probing when set to true", async () => {
+        const probe = createCapabilityProbe("true");
+        expect(await probe.get()).toEqual({ agentTools: true, agentPolicy: true });
+        expect(mockRequest).not.toHaveBeenCalled();
+    });
+    it("forces the tools off without probing when set to false", async () => {
+        const probe = createCapabilityProbe("false");
+        expect(await probe.get()).toEqual({ agentTools: false, agentPolicy: false });
+        expect(mockRequest).not.toHaveBeenCalled();
+    });
+});

package/build/client.js

@@ -1,5 +1,10 @@
 import { GraphQLClient } from "graphql-request";
 import { config } from "./config.js";
+import { agentSessionHeaders } from "./session.js";
+/** Headers for every request to Yontrack, computed per request to carry the current agent session. */
+export function yontrackHeaders() {
+    return { "X-Ontrack-Token": config.YONTRACK_TOKEN, ...agentSessionHeaders() };
+}
 export const gqlClient = new GraphQLClient(`${config.YONTRACK_URL}/graphql`, {
-    headers: { "X-Ontrack-Token": config.YONTRACK_TOKEN },
+    headers: yontrackHeaders,
 });

package/build/client.test.js

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+const fetchMock = vi.fn();
+async function loadClient(env = {}) {
+    vi.resetModules();
+    delete process.env.YONTRACK_AGENT_SESSION;
+    delete process.env.YONTRACK_AGENT_SESSION_LINK;
+    Object.assign(process.env, env);
+    const client = await import("./client.js");
+    const session = await import("./session.js");
+    return { ...client, ...session };
+}
+function sentHeaders() {
+    const init = fetchMock.mock.calls[0][1];
+    return new Headers(init.headers);
+}
+beforeEach(() => {
+    fetchMock.mockReset();
+    fetchMock.mockImplementation(async () => new Response(JSON.stringify({ data: { ok: true } }), {
+        headers: { "Content-Type": "application/json" },
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+    delete process.env.YONTRACK_AGENT_SESSION;
+    delete process.env.YONTRACK_AGENT_SESSION_LINK;
+});
+describe("agent session headers", () => {
+    it("sends no session headers when none is configured", async () => {
+        const { gqlClient } = await loadClient();
+        await gqlClient.request("{ ok }");
+        const headers = sentHeaders();
+        expect(headers.get("X-Ontrack-Token")).toBe("test-token");
+        expect(headers.has("X-Yontrack-Agent-Session")).toBe(false);
+        expect(headers.has("X-Yontrack-Agent-Session-Link")).toBe(false);
+    });
+    it("sends the session configured in the environment", async () => {
+        const { gqlClient } = await loadClient({
+            YONTRACK_AGENT_SESSION: "env-session",
+            YONTRACK_AGENT_SESSION_LINK: "https://claude.ai/code/env-session",
+        });
+        await gqlClient.request("{ ok }");
+        const headers = sentHeaders();
+        expect(headers.get("X-Yontrack-Agent-Session")).toBe("env-session");
+        expect(headers.get("X-Yontrack-Agent-Session-Link")).toBe("https://claude.ai/code/env-session");
+    });
+    it("prefers the session of the incoming MCP request over the environment", async () => {
+        const { gqlClient, runWithAgentSession } = await loadClient({
+            YONTRACK_AGENT_SESSION: "env-session",
+            YONTRACK_AGENT_SESSION_LINK: "https://claude.ai/code/env-session",
+        });
+        await runWithAgentSession({ session: "req-session" }, () => gqlClient.request("{ ok }"));
+        const headers = sentHeaders();
+        expect(headers.get("X-Yontrack-Agent-Session")).toBe("req-session");
+        // The environment link belongs to the environment session: never mixed with the request one
+        expect(headers.has("X-Yontrack-Agent-Session-Link")).toBe(false);
+    });
+    it("forwards a request link without a session as is", async () => {
+        const { gqlClient, runWithAgentSession } = await loadClient();
+        await runWithAgentSession({ link: "https://claude.ai/code/abc" }, () => gqlClient.request("{ ok }"));
+        const headers = sentHeaders();
+        expect(headers.has("X-Yontrack-Agent-Session")).toBe(false);
+        expect(headers.get("X-Yontrack-Agent-Session-Link")).toBe("https://claude.ai/code/abc");
+    });
+    it("falls back to the environment when the request carries no session headers", async () => {
+        const { gqlClient, runWithAgentSession } = await loadClient({ YONTRACK_AGENT_SESSION: "env-session" });
+        await runWithAgentSession({}, () => gqlClient.request("{ ok }"));
+        expect(sentHeaders().get("X-Yontrack-Agent-Session")).toBe("env-session");
+    });
+});

package/build/config.js

@@ -6,13 +6,22 @@ const ConfigSchema = z.object({
         .string()
         .optional()
         .transform((v) => v === "true"),
+    YONTRACK_AGENT_TOOLS: z.enum(["auto", "true", "false"]).optional().default("auto"),
+    YONTRACK_UI_URL: z
+        .preprocess((v) => (v === "" ? undefined : v), z.string().url().optional())
+        .transform((v) => v?.replace(/\/+$/, "")),
+    YONTRACK_AGENT_SESSION: z.string().optional(),
+    YONTRACK_AGENT_SESSION_LINK: z.string().optional(),
 });
 let _config;
 try {
     _config = ConfigSchema.parse(process.env);
 }
 catch (err) {
-    process.stderr.write("Missing required environment variables: YONTRACK_URL and YONTRACK_TOKEN\n");
+    const details = err instanceof z.ZodError
+        ? err.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+        : String(err);
+    process.stderr.write(`Invalid or missing environment variables (YONTRACK_URL and YONTRACK_TOKEN are required): ${details}\n`);
     process.exit(1);
 }
 export const config = _config;

package/build/index.js

@@ -6,9 +6,12 @@ import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { createServer } from "./server.js";
 import { oauthConfig } from "./config.js";
+import { getCapabilities } from "./capabilities.js";
+import { agentSessionFromHeaders, runWithAgentSession } from "./session.js";
 import { createOAuthProvider, clientsStore, generateAuthCode, renderAuthFormHtml, } from "./auth.js";
 if (process.argv[2] === "stdio") {
-    const server = createServer();
+    // One process per agent: capabilities are probed once, the agent session comes from the environment
+    const server = createServer(undefined, await getCapabilities());
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
@@ -36,14 +39,16 @@ else {
     });
     // MCP request handler
     async function handleMcp(req, res) {
-        const server = createServer(oauthConfig?.serverUrl);
+        const server = createServer(oauthConfig?.serverUrl, await getCapabilities());
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
         });
         res.on("close", () => transport.close());
         await server.connect(transport);
+        // The agent session headers of this request are forwarded to Yontrack by every call it makes
+        await runWithAgentSession(agentSessionFromHeaders(req.headers), () => 
         // req.body is pre-parsed by express.json() for POST requests
-        await transport.handleRequest(req, res, req.body);
+        transport.handleRequest(req, res, req.body));
     }
     function oauthLog(msg) {
         process.stderr.write(`[oauth] ${msg}\n`);

package/build/server.js

@@ -1,6 +1,19 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerAllTools } from "./tools/index.js";
-export function createServer(serverUrl) {
+const INSTRUCTIONS = `
+Use the specific tools (list_projects, get_build, etc.) for simple, single-entity lookups.
+When a task would require calling multiple tools in a loop — for example fetching builds across many branches, or collecting validation runs for a list of builds — use graphql_query instead to retrieve all needed data in a single round-trip.
+Read the yontrack://schema resource before writing a GraphQL query to understand available types and fields.
+When displaying branches, builds, or other entities to the user, always prefer the displayName field over the name field.
+When displaying promotion levels (in any form: list, table, chart, or graph), always fetch their image using get_promotion_level_image for each level whose image field is true, and embed the returned base64 data directly as a data URI (e.g. <img src="data:image/png;base64,...">) alongside the promotion level name. Do not reference the MCP server URL for images as it is not accessible from the browser.
+`.trim();
+const AGENT_CONTEXT_INSTRUCTIONS = `
+To know whether a build is ready for a promotion level or a slot, what changed since what is deployed, what is deployed where, or which dependency builds are at a level, prefer build_readiness, changes_since_deployed, deployments and dependency_builds_at_level over graphql_query.
+`.trim();
+const AGENT_POLICY_INSTRUCTIONS = `
+To know what the agent behind the current token may do on a project (promote, deploy, record evidence), use agent_policy.
+`.trim();
+export function createServer(serverUrl, capabilities) {
     const server = new McpServer({
         name: "yontrack",
         version: "1.0.0",
@@ -8,14 +21,12 @@ export function createServer(serverUrl) {
             icons: [{ src: `${serverUrl}/yontrack.png`, mimeType: "image/png" }],
         }),
     }, {
-        instructions: `
-Use the specific tools (list_projects, get_build, etc.) for simple, single-entity lookups.
-When a task would require calling multiple tools in a loop — for example fetching builds across many branches, or collecting validation runs for a list of builds — use graphql_query instead to retrieve all needed data in a single round-trip.
-Read the yontrack://schema resource before writing a GraphQL query to understand available types and fields.
-When displaying branches, builds, or other entities to the user, always prefer the displayName field over the name field.
-When displaying promotion levels (in any form: list, table, chart, or graph), always fetch their image using get_promotion_level_image for each level whose image field is true, and embed the returned base64 data directly as a data URI (e.g. <img src="data:image/png;base64,...">) alongside the promotion level name. Do not reference the MCP server URL for images as it is not accessible from the browser.
-      `.trim(),
+        instructions: [
+            INSTRUCTIONS,
+            ...(capabilities.agentTools ? [AGENT_CONTEXT_INSTRUCTIONS] : []),
+            ...(capabilities.agentPolicy ? [AGENT_POLICY_INSTRUCTIONS] : []),
+        ].join("\n"),
     });
-    registerAllTools(server);
+    registerAllTools(server, capabilities);
     return server;
 }

package/build/server.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createServer } from "./server.js";
+async function connect(capabilities) {
+    const server = createServer(undefined, capabilities);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "test-client", version: "0.0.0" });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    return client;
+}
+describe("createServer", () => {
+    it("exposes the agent-context tools and mentions them on Yontrack 6", async () => {
+        const client = await connect({ agentTools: true, agentPolicy: true });
+        const names = (await client.listTools()).tools.map((t) => t.name);
+        expect(names).toEqual(expect.arrayContaining(["list_projects", "build_readiness", "agent_policy"]));
+        expect(client.getInstructions()).toContain("build_readiness");
+        expect(client.getInstructions()).toContain("agent_policy");
+    });
+    it("hides the agent-context tools and does not mention them on Yontrack 5", async () => {
+        const client = await connect({ agentTools: false, agentPolicy: false });
+        const names = (await client.listTools()).tools.map((t) => t.name);
+        expect(names).toContain("list_projects");
+        expect(names).not.toContain("build_readiness");
+        expect(client.getInstructions()).not.toContain("build_readiness");
+    });
+});

package/build/session.js

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { config } from "./config.js";
+/** Header names, identical on the incoming MCP request and on the outgoing Yontrack request. */
+export const AGENT_SESSION_HEADER = "X-Yontrack-Agent-Session";
+export const AGENT_SESSION_LINK_HEADER = "X-Yontrack-Agent-Session-Link";
+const storage = new AsyncLocalStorage();
+/** Runs `fn` with the agent session carried by the incoming MCP request. */
+export function runWithAgentSession(session, fn) {
+    return storage.run(session, fn);
+}
+/** Reads the agent session headers of an incoming HTTP request (Node lower-cases header names). */
+export function agentSessionFromHeaders(headers) {
+    const read = (name) => {
+        const value = headers[name.toLowerCase()];
+        return (Array.isArray(value) ? value[0] : value) || undefined;
+    };
+    return { session: read(AGENT_SESSION_HEADER), link: read(AGENT_SESSION_LINK_HEADER) };
+}
+/**
+ * Headers identifying the agent session, never invented:
+ * the incoming MCP request's session headers when it carries any, the environment otherwise.
+ * The session and its link are taken as a pair so that they always belong together.
+ * Yontrack validates them and ignores them for non-agent tokens.
+ */
+export function agentSessionHeaders() {
+    const fromRequest = storage.getStore();
+    const { session, link } = fromRequest && (fromRequest.session || fromRequest.link)
+        ? fromRequest
+        : { session: config.YONTRACK_AGENT_SESSION, link: config.YONTRACK_AGENT_SESSION_LINK };
+    return {
+        ...(session && { [AGENT_SESSION_HEADER]: session }),
+        ...(link && { [AGENT_SESSION_LINK_HEADER]: link }),
+    };
+}

package/build/tools/agent-context-support.js

@@ -0,0 +1,107 @@
+import { gqlClient } from "../client.js";
+import { config } from "../config.js";
+/** Link to a page of the Yontrack UI, or `undefined` when `YONTRACK_UI_URL` is not set. */
+export function uiLink(path) {
+    return config.YONTRACK_UI_URL ? `${config.YONTRACK_UI_URL}/${path}` : undefined;
+}
+export const slotLink = (slotId) => uiLink(`extension/environments/slot/${slotId}`);
+export const pipelineLink = (pipelineId) => uiLink(`extension/environments/pipeline/${pipelineId}`);
+export function compactBuild(build) {
+    return { name: build.name, displayName: build.displayName, link: uiLink(`build/${build.id}`) };
+}
+/** Display name of a slot: `environment` or `environment/qualifier`. */
+export function slotName(slot) {
+    return slot.qualifier ? `${slot.environment.name}/${slot.qualifier}` : slot.environment.name;
+}
+export class NotFoundError extends Error {
+}
+const RESOLVE_BUILD = `
+  query ResolveBuild(
+    $project: String!, $branch: String!, $build: String!,
+    $withLevels: Boolean!, $withSlot: Boolean!, $environment: String, $qualifier: String
+  ) {
+    builds(project: $project, branch: $branch, name: $build) {
+      id
+      name
+      displayName
+      branch @include(if: $withLevels) { promotionLevels { id name } }
+      slots(environment: $environment, qualifier: $qualifier) @include(if: $withSlot) {
+        id
+        qualifier
+        environment { name }
+        lastDeployedPipeline { id number build { id name displayName } }
+      }
+    }
+  }
+`;
+/**
+ * Resolves a build by names and, when given, its target (promotion level or slot).
+ * Throws a `NotFoundError` naming the missing entity.
+ */
+export async function resolveBuild(project, branch, build, target) {
+    const withLevels = target?.promotionLevel !== undefined;
+    const withSlot = target?.environment !== undefined;
+    const data = await gqlClient.request(RESOLVE_BUILD, {
+        project, branch, build, withLevels, withSlot,
+        environment: target?.environment ?? null,
+        qualifier: withSlot ? (target?.qualifier ?? "") : null,
+    });
+    const found = data.builds?.[0];
+    if (!found) {
+        throw new NotFoundError(`Build '${build}' not found on branch '${branch}' of project '${project}'`);
+    }
+    const buildRef = { id: found.id, name: found.name, displayName: found.displayName };
+    if (withLevels) {
+        const level = found.branch?.promotionLevels.find((l) => l.name === target.promotionLevel);
+        if (!level) {
+            throw new NotFoundError(`Promotion level '${target.promotionLevel}' not found on branch '${branch}' of project '${project}'`);
+        }
+        return {
+            build: buildRef,
+            target: { kind: "promotionLevel", id: level.id, name: level.name, link: uiLink(`promotionLevel/${level.id}`) },
+        };
+    }
+    if (withSlot) {
+        const slot = found.slots?.[0];
+        if (!slot) {
+            const qualifier = target.qualifier ? ` with qualifier '${target.qualifier}'` : "";
+            throw new NotFoundError(`No slot for project '${project}' in environment '${target.environment}'${qualifier}`);
+        }
+        return {
+            build: buildRef,
+            target: { kind: "slot", id: slot.id, name: slotName(slot), link: slotLink(slot.id), slot },
+        };
+    }
+    return { build: buildRef };
+}
+/** Reads the exactly-one-of target from tool arguments. */
+export function targetOf(args) {
+    const hasLevel = args.promotionLevel !== undefined;
+    const hasEnvironment = args.environment !== undefined;
+    if (hasLevel === hasEnvironment) {
+        return "Exactly one of 'promotionLevel' or 'environment' must be given";
+    }
+    if (!hasEnvironment && args.qualifier !== undefined) {
+        return "'qualifier' can only be used together with 'environment'";
+    }
+    return hasLevel
+        ? { promotionLevel: args.promotionLevel }
+        : { environment: args.environment, qualifier: args.qualifier };
+}
+export function errorResult(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+export function jsonResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+/** Turns a `NotFoundError` into an error result; other errors propagate. */
+export async function withNotFound(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof NotFoundError)
+            return errorResult(err.message);
+        throw err;
+    }
+}