@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/azdo/src/lib/agent-token.ts

@@ -0,0 +1,167 @@
+// Azure DevOps agent-identity TOKEN MINTING (split out of ./agent-identity.ts
+// 2026-09-28: packages/agent-hooks imports agent-identity.ts's resolution
+// exports for its `adl-identity` rule, and agent-hooks' `check` gate requires
+// 100% funcs/lines with no ignore patterns. bun instruments the whole
+// imported file, so `getAccessToken`/`resolveAgentIdBinary`/
+// `resetAccessTokenCacheForTests` -- never called by the hook -- made
+// agent-hooks' gate fail on code it never exercises. Moving minting here
+// keeps agent-identity.ts to pure resolution, which the hook's own tests
+// cover completely.
+//
+// Token flow, mirroring bin/git-ado's agent path exactly (same two pinned
+// addresses, same two-hop exec):
+//
+//   adl-agent-id exec --agent <agent> -- adl id token <agent> --json
+//
+// (docs/architecture/cli-design.md §7 P4 folded the standalone `ado-token`
+// binary into `adl id token`, byte-for-byte the same contract: the agent is
+// positional and comes first, `--json` is a flag after it; see
+// apps/cli/src/ado-token.ts, which is now the single implementation `adl id
+// token` and this module both rely on -- this module cannot call it
+// in-process because the proxy env (HTTPS_PROXY / NODE_EXTRA_CA_CERTS) is
+// set by agent-vault for the SPAWNED child only, never for this process.)
+//
+// adl-agent-id mints a short-lived, proxy-only Agent Vault session for
+// <agent> and execs `adl id token <agent> --json` inside it; that prints
+// {"access_token":...,"expires_in":...} on stdout. This process never sees
+// the vault proxy, the CA, or a client secret -- only the finished bearer
+// token, read from the child's stdout PIPE (never argv, never logged).
+//
+// ADL_AGENT_ID_ADDR and ADL_AGENT_ID_VAULT_ADDR are PINNED to the same two
+// constants bin/git-ado pins, for the same reason stated there: a caller
+// that could redirect either one could redirect the signed broker request
+// or the minted token to a server of its choosing. They are fixed constants
+// here too, not read from the environment -- see
+// tests/agent-id-constants-pinned.test.ts, which fails if the two copies
+// drift.
+
+export const ADL_AGENT_ID_ADDR_CONST = 'https://agentid.amsterdamdatalabs.com';
+export const ADL_AGENT_ID_VAULT_ADDR_CONST = 'https://agentid-vault.walrus-morray.ts.net';
+
+function resolveAgentIdBinary(env: NodeJS.ProcessEnv): string {
+  const resolved = Bun.which('adl-agent-id', { PATH: env.PATH ?? '' });
+  if (!resolved) {
+    throw new Error(
+      'adl-agent-id not found on PATH: reconcile the global-tools manifest before running Azure DevOps tools',
+    );
+  }
+  return resolved;
+}
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+/** One cache entry per agent name, for the life of this process. */
+const tokenCache = new Map<string, CachedToken>();
+
+/** Test seam: forget every cached token. */
+export function resetAccessTokenCacheForTests(): void {
+  tokenCache.clear();
+}
+
+/**
+ * OVERRIDING whatever the caller's environment carried -- adl-agent-id
+ * resolves both only from the environment (there is no --broker/--vault
+ * flag), so this is the one place that decides where the signed request and
+ * the vault session go, exactly as bin/git-ado does for the git path. Shared
+ * by both the async and sync mint below -- one pinned pair, not two copies.
+ */
+function mintEnv(env: NodeJS.ProcessEnv): Record<string, string | undefined> {
+  return {
+    ...env,
+    ADL_AGENT_ID_ADDR: ADL_AGENT_ID_ADDR_CONST,
+    ADL_AGENT_ID_VAULT_ADDR: ADL_AGENT_ID_VAULT_ADDR_CONST,
+  };
+}
+
+const MINT_COMMAND = (agentIdBin: string, agent: string): string[] => [
+  agentIdBin,
+  'exec',
+  '--agent',
+  agent,
+  '--',
+  'adl',
+  'id',
+  'token',
+  agent,
+  '--json',
+];
+
+/** Parses and validates `adl id token --json`'s stdout; shared by both mints. */
+function parseMintedToken(stdout: string): { accessToken: string; expiresAt: number } {
+  let parsed: { access_token?: string; expires_in?: number };
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch {
+    throw new Error('ado-token --json produced unparseable output');
+  }
+  if (!parsed.access_token || !Number.isFinite(parsed.expires_in) || (parsed.expires_in as number) <= 0) {
+    throw new Error('ado-token --json response is missing a valid access_token or expires_in');
+  }
+  return { accessToken: parsed.access_token, expiresAt: Date.now() + (parsed.expires_in! - 60) * 1000 };
+}
+
+/**
+ * The bearer token for `agent`, minted through
+ * `adl-agent-id exec --agent <agent> -- adl id token <agent> --json` and
+ * cached in memory until `expires_in - 60s`. The JSON is parsed straight off
+ * the child's stdout pipe; nothing here logs it.
+ */
+export async function getAccessToken(agent: string): Promise<string> {
+  const cached = tokenCache.get(agent);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.accessToken;
+  }
+
+  const agentIdBin = resolveAgentIdBinary(process.env);
+  const proc = Bun.spawn(MINT_COMMAND(agentIdBin, agent), { env: mintEnv(process.env), stdout: 'pipe', stderr: 'pipe' });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`adl-agent-id exec -- adl id token --json failed (exit ${exitCode}): ${stderr.trim()}`);
+  }
+
+  const { accessToken, expiresAt } = parseMintedToken(stdout);
+  tokenCache.set(agent, { accessToken, expiresAt });
+  return accessToken;
+}
+
+/**
+ * Synchronous counterpart to `getAccessToken`, same command/parsing/pinned
+ * addresses and the same in-memory cache -- for callers whose call sites are
+ * all sync (packages/repo-controls' doctor/hook checks), where importing the
+ * async mint across the package boundary would mean threading `await`
+ * through code that has none today. STATUS.md 12p finding M9: this is the
+ * ONE mint every surface uses now; packages/repo-controls/src/azure-devops-governance.ts
+ * no longer keeps its own copy.
+ *
+ * `env` defaults to `process.env` (matching `getAccessToken`) but is
+ * threaded through UNMERGED -- not layered on top of `process.env` -- so a
+ * caller that resolves its own hermetic env (governance.ts's doctor/hook
+ * requests, and their tests) gets that exact env for both the
+ * `adl-agent-id` PATH lookup and the spawned child, never a silent fallback
+ * to the real machine's environment.
+ */
+export function getAccessTokenSync(agent: string, env: NodeJS.ProcessEnv = process.env): string {
+  const cached = tokenCache.get(agent);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.accessToken;
+  }
+
+  const agentIdBin = resolveAgentIdBinary(env);
+  const proc = Bun.spawnSync(MINT_COMMAND(agentIdBin, agent), { env: mintEnv(env), stdout: 'pipe', stderr: 'pipe' });
+  const stdout = proc.stdout.toString();
+  const stderr = proc.stderr.toString();
+  if (proc.exitCode !== 0) {
+    throw new Error(`adl-agent-id exec -- adl id token --json failed (exit ${proc.exitCode}): ${stderr.trim()}`);
+  }
+
+  const { accessToken, expiresAt } = parseMintedToken(stdout);
+  tokenCache.set(agent, { accessToken, expiresAt });
+  return accessToken;
+}

package/packages/azdo/src/lib/client.ts

@@ -0,0 +1,259 @@
+// Azure DevOps client. Authenticates as the SESSION's own agent identity
+// (ADL_AGENT_ID_AGENT) via lib/agent-identity.ts -- see that file for the
+// token flow. P2 (2026-09-27, Tarun) replaced the earlier Agent Vault
+// client-credentials binding this file used to hold directly.
+import { spawnSync } from 'node:child_process';
+import { resolveAgentIdentity } from './agent-identity.ts';
+import { getAccessToken } from './agent-token.ts';
+
+export interface AdoClientConfig {
+  /** Full `.../_apis` base URL override. Defaults to the real Azure DevOps
+   * REST base built from org/project; set directly (or via
+   * AZURE_DEVOPS_BASE_URL) to point at a different Azure DevOps Server
+   * instance, or at a local stub in tests. */
+  baseUrl?: string;
+}
+
+/**
+ * The Azure DevOps organization and project every tool in this package
+ * addresses, and the ONLY place their defaults are written.
+ *
+ * `enact-webview` is a REPOSITORY inside the `Enact` project, not a project —
+ * `azdo-wit.ts` used to default the project to it, so work-item calls hit a
+ * different URL than the PR and build calls in the same process. Anything
+ * needing these values imports from here rather than restating them.
+ */
+export const DEFAULT_ORG = 'amsterdamdatalabs';
+export const DEFAULT_PROJECT = 'Enact';
+/** The one PR target this opinionated tool opens against. */
+export const PR_TARGET_BRANCH = 'integration';
+
+/** Current checkout branch, or undefined when git cannot determine it. */
+export function currentBranch(cwd?: string): string | undefined {
+  const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    ...(cwd === undefined ? {} : { cwd }),
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  return result.status === 0 ? configured(result.stdout) : undefined;
+}
+
+/** Treat blank and whitespace-only env values as unset, never as an empty path segment. */
+function configured(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export interface AzureRemote {
+  readonly org: string;
+  readonly project: string;
+  readonly repository: string;
+}
+
+/**
+ * Pull org/project/repository out of an Azure DevOps remote URL.
+ *
+ *   git@ssh.dev.azure.com:v3/<org>/<project>/<repo>
+ *   https://dev.azure.com/<org>/<project>/_git/<repo>[.git]
+ *   https://<org>.visualstudio.com/<project>/_git/<repo>
+ *
+ * Returns null for anything else rather than guessing — a GitHub remote must
+ * not silently yield an Azure target.
+ */
+export function parseAzureRemote(url: string): AzureRemote | null {
+  const decode = (value: string) => {
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+  const build = (org: string, project: string, repo: string): AzureRemote | null => {
+    const parts = [org, project, repo.replace(/\.git$/, '')].map(decode);
+    return parts.every((p) => p.length > 0) ? { org: parts[0]!, project: parts[1]!, repository: parts[2]! } : null;
+  };
+
+  const ssh = /^(?:ssh:\/\/)?git@(?:ssh\.)?dev\.azure\.com[:/]v3\/([^/]+)\/([^/]+)\/([^/]+?)\/?$/.exec(url.trim());
+  if (ssh) return build(ssh[1]!, ssh[2]!, ssh[3]!);
+
+  const https = /^https?:\/\/(?:[^@/]+@)?dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+?)\/?$/.exec(url.trim());
+  if (https) return build(https[1]!, https[2]!, https[3]!);
+
+  const legacy = /^https?:\/\/(?:[^@/]+@)?([^./]+)\.visualstudio\.com\/([^/]+)\/_git\/([^/]+?)\/?$/.exec(url.trim());
+  if (legacy) return build(legacy[1]!, legacy[2]!, legacy[3]!);
+
+  return null;
+}
+
+/**
+ * The Azure coordinates of the checkout this process is running in, read once
+ * from `git remote get-url origin`.
+ *
+ * This is why no environment variable is needed: the working directory already
+ * knows which repository it is. Before this, an unset `AZURE_DEVOPS_REPO` fell
+ * through to `enact-webview`, so a PR call made from any other repo was aimed
+ * at enact-webview and Azure answered TF401398 "branch does not exist" — a
+ * truthful error about the wrong target, which is the expensive kind.
+ *
+ * Cached: the remote cannot change under a running server, and this sits on
+ * every tool call.
+ */
+let remoteCache: AzureRemote | null | undefined;
+export function currentRemote(cwd?: string): AzureRemote | null {
+  if (cwd !== undefined) {
+    const probe = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8', timeout: 5000 });
+    return probe.status === 0 ? parseAzureRemote(probe.stdout ?? '') : null;
+  }
+  if (remoteCache !== undefined) return remoteCache;
+  const result = spawnSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf8', timeout: 5000 });
+  remoteCache = result.status === 0 ? parseAzureRemote(result.stdout ?? '') : null;
+  return remoteCache;
+}
+
+/** Test seam: forget the cached remote. */
+export function resetRemoteCache(): void {
+  remoteCache = undefined;
+}
+
+export function resolveOrg(cwd?: string): string {
+  return configured(process.env.AZURE_DEVOPS_ORG) ?? currentRemote(cwd)?.org ?? DEFAULT_ORG;
+}
+
+export function resolveProject(cwd?: string): string {
+  return configured(process.env.AZURE_DEVOPS_PROJECT) ?? currentRemote(cwd)?.project ?? DEFAULT_PROJECT;
+}
+
+/**
+ * Which repository a call addresses: the explicit per-call argument first (one
+ * session can span repos), then `AZURE_DEVOPS_REPO` as an override, then the
+ * checkout's own git remote.
+ *
+ * There is deliberately NO default. A fallback constant is what made this fail
+ * silently: with `DEFAULT_REPO = 'enact-webview'` in place, every call from a
+ * repo that was not enact-webview was confidently aimed at enact-webview, and
+ * the only symptom was Azure answering TF401398 "branch does not exist" — a
+ * truthful error about a target nobody chose. Throwing names the real problem
+ * at the point it occurs.
+ *
+ * org/project keep their defaults: unlike the repository, they are constant
+ * across this fleet, and a wrong one fails visibly at the URL rather than
+ * writing somewhere real.
+ */
+export function resolveRepository(repository?: string, cwd?: string): string {
+  const resolved = configured(repository) ?? configured(process.env.AZURE_DEVOPS_REPO) ?? currentRemote(cwd)?.repository;
+  if (resolved === undefined) {
+    throw new Error(
+      'Cannot determine the Azure DevOps repository: no `repository` argument, no AZURE_DEVOPS_REPO, ' +
+        'and `git remote get-url origin` in this working directory is not an Azure DevOps remote. ' +
+        'Pass `repository` explicitly or run from a checkout of the target repo.',
+    );
+  }
+  return resolved;
+}
+
+/**
+ * `https://dev.azure.com/{org}/{project}` — the ONE place the host and both
+ * segments are written. The REST base appends `/_apis`; human-facing links
+ * append `/_git/...`. Two builders restating this shape can disagree about
+ * where a project lives just as easily as two default constants could.
+ */
+export function adoProjectUrl(): string {
+  return `https://dev.azure.com/${resolveOrg()}/${resolveProject()}`;
+}
+
+export class AdoClient {
+  private config: Required<AdoClientConfig>;
+
+  constructor(config: AdoClientConfig = {}) {
+    this.config = {
+      baseUrl: config.baseUrl ?? process.env.AZURE_DEVOPS_BASE_URL ?? '',
+    };
+  }
+
+  private get baseUrl(): string {
+    if (this.config.baseUrl) return this.config.baseUrl;
+    return `${adoProjectUrl()}/_apis`;
+  }
+
+  // No proxy, no CA override, no vault: the session's own bearer token goes
+  // straight to Azure DevOps (or, in tests, to AZURE_DEVOPS_BASE_URL's local
+  // stub). See lib/agent-identity.ts for where the token comes from and why.
+  private async acquireAccessToken(): Promise<string> {
+    return getAccessToken(resolveAgentIdentity().agent);
+  }
+
+  async request<T>(
+    path: string,
+    options: {
+      method?: string;
+      body?: any;
+      queryParams?: Record<string, string>;
+      contentType?: string;
+    } = {}
+  ): Promise<T> {
+    const token = await this.acquireAccessToken();
+    const method = options.method ?? 'GET';
+    const contentType = options.contentType ?? 'application/json';
+
+    let url = `${this.baseUrl}${path}`;
+    if (options.queryParams) {
+      const params = new URLSearchParams(options.queryParams);
+      url += `?${params.toString()}`;
+    }
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': contentType,
+    };
+
+    const resp = await fetch(url, {
+      redirect: 'error',
+      method,
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      throw new Error(`Azure DevOps API error: ${resp.status} ${text}`);
+    }
+
+    return resp.json() as Promise<T>;
+  }
+
+  async get<T>(path: string, queryParams?: Record<string, string>): Promise<T> {
+    return this.request<T>(path, { ...(queryParams === undefined ? {} : { queryParams }) });
+  }
+
+  async post<T>(path: string, body: any, queryParams?: Record<string, string>, contentType?: string): Promise<T> {
+    return this.request<T>(path, {
+      method: 'POST',
+      body,
+      ...(queryParams === undefined ? {} : { queryParams }),
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  async patch<T>(path: string, body: any, queryParams?: Record<string, string>, contentType?: string): Promise<T> {
+    return this.request<T>(path, {
+      method: 'PATCH',
+      body,
+      ...(queryParams === undefined ? {} : { queryParams }),
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  /** Pull Request Reviewers — Create Pull Request Reviewer (add a reviewer or cast a vote) uses PUT; nothing else in this package needed it until azdo-pr-review.ts. */
+  async put<T>(path: string, body: any, queryParams?: Record<string, string>, contentType?: string): Promise<T> {
+    return this.request<T>(path, {
+      method: 'PUT',
+      body,
+      ...(queryParams === undefined ? {} : { queryParams }),
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+}

package/packages/azdo/src/lib/graph-identity.ts

@@ -0,0 +1,153 @@
+// Azure DevOps Graph identity resolution: turn one of this fleet's three
+// agent display names ("agent-tarun" / "agent-vivek" / "agent-reviewer" —
+// verified live against the Graph service by azdo-repo-doctor.ts, which
+// posts each name as-is to the Subject Query below and expects an EXACT
+// `displayName` match) into the legacy GUID identity id that the Git REST
+// APIs use everywhere else (`createdBy.id`, `reviewers[].id`, the
+// `autoCompleteSetBy.id` this package already sends in azdo-pr.ts).
+//
+// Two REST calls, both against the org-scoped Graph host (a different host
+// from `dev.azure.com/{org}/{project}`, same as azdo-repo-doctor.ts already
+// established for the same reason):
+//
+//   1. Graph — Subject Query (display name -> Graph descriptor)
+//      POST https://vssps.dev.azure.com/{org}/_apis/graph/subjectquery?api-version=7.1-preview.1
+//      body: { query: <displayName>, subjectKind: ['User'] }
+//      https://learn.microsoft.com/en-us/rest/api/azure/devops/graph/subject-query/query
+//
+//   2. Graph — Storage Keys — Get (descriptor -> legacy GUID identity id)
+//      GET https://vssps.dev.azure.com/{org}/_apis/graph/storagekeys/{subjectDescriptor}?api-version=7.1
+//      https://learn.microsoft.com/en-us/rest/api/azure/devops/graph/storage-keys/get
+//      response: { value: "<guid>" } — this IS the same identity-id shape as
+//      the Git PR APIs' `id`/`reviewerId`/`createdBy.id` (the well-known
+//      "storage key" / legacy VSID bridge the official az CLI extension uses
+//      to resolve "who am I" into an identity a Git API will accept).
+//
+// Extracted out of azdo-repo-doctor.ts (2026-09-27, C3): that file resolves
+// descriptors for its own read-only ACL checks and had this exact
+// vsspsBaseUrl()/fetchJson()/postJson()/resolveAgentDescriptor() quartet
+// private to itself. azdo-pr-review.ts (C3, docs/operations/agent-permissions.md rows
+// 6-8) needs the SAME descriptor lookup plus the storage-key hop the doctor
+// never needed, so the shared half moved here rather than being copied a
+// second time — repo-doctor.ts now imports it instead of defining its own.
+import { resolveAgentIdentity } from './agent-identity.ts';
+import { getAccessToken } from './agent-token.ts';
+import { resolveOrg } from './client.ts';
+
+/** Treat blank and whitespace-only env overrides as unset, like lib/client.ts's own `configured()`. */
+function configured(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/** The Graph service host — a different host from dev.azure.com entirely. */
+export function vsspsBaseUrl(): string {
+  return configured(process.env.AZURE_DEVOPS_VSSPS_BASE_URL) ?? `https://vssps.dev.azure.com/${resolveOrg()}`;
+}
+
+export async function fetchJson<T>(url: string, label: string): Promise<T> {
+  const token = await getAccessToken(resolveAgentIdentity().agent);
+  const resp = await fetch(url, { headers: { Authorization: `Bearer ${token}` }, redirect: 'error' });
+  if (!resp.ok) {
+    throw new Error(`Azure DevOps API error (${label}): ${resp.status} ${(await resp.text()).slice(0, 300)}`);
+  }
+  return resp.json() as Promise<T>;
+}
+
+export async function postJson<T>(url: string, body: unknown, label: string): Promise<T> {
+  const token = await getAccessToken(resolveAgentIdentity().agent);
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    redirect: 'error',
+  });
+  if (!resp.ok) {
+    throw new Error(`Azure DevOps API error (${label}): ${resp.status} ${(await resp.text()).slice(0, 300)}`);
+  }
+  return resp.json() as Promise<T>;
+}
+
+export interface GraphSubjectQueryResponse {
+  value?: Array<{ displayName?: string; descriptor?: string }>;
+}
+
+/** Resolve `displayName` to its Graph descriptor, or undefined when the Subject Query finds no exact match. */
+export async function resolveAgentDescriptor(displayName: string): Promise<string | undefined> {
+  const result = await postJson<GraphSubjectQueryResponse>(
+    `${vsspsBaseUrl()}/_apis/graph/subjectquery?api-version=7.1-preview.1`,
+    { query: displayName, subjectKind: ['User'] },
+    'Graph subject query',
+  );
+  return (result.value ?? []).find((subject) => subject.displayName === displayName)?.descriptor;
+}
+
+interface GraphStorageKeyResponse {
+  value?: string;
+}
+
+/** Resolve a Graph `descriptor` to its legacy GUID storage key, or undefined when Graph has none on file. */
+export async function resolveIdentityStorageKey(descriptor: string): Promise<string | undefined> {
+  const result = await fetchJson<GraphStorageKeyResponse>(
+    `${vsspsBaseUrl()}/_apis/graph/storagekeys/${encodeURIComponent(descriptor)}?api-version=7.1`,
+    'Graph storage key',
+  );
+  return result.value;
+}
+
+interface IdentitiesResponse {
+  count?: number;
+  value?: Array<{ descriptor?: string; providerDisplayName?: string; customDisplayName?: string }>;
+}
+
+/**
+ * Resolve a LEGACY/SERVICE identity (a build service, not a Graph 'User' or
+ * 'Group' subject — `resolveAgentDescriptor()` above cannot find these) by
+ * its exact display name, via Identities - Read Identities on the vssps
+ * host — NOT Graph subjectquery:
+ *   GET https://vssps.dev.azure.com/{org}/_apis/identities?searchFilter=General&filterValue=<name>&queryMembership=None&api-version=7.1
+ *   https://learn.microsoft.com/en-us/rest/api/azure/devops/ims/identities/read-identities
+ * Returns the identity's `descriptor` (accepted by the same
+ * `accesscontrollists` `descriptors` filter every other lookup in this
+ * package uses).
+ *
+ * Verified live 2026-09-29 against amsterdamdatalabs/Infrastructure-AzDo's
+ * real project build service: for a SERVICE identity, `providerDisplayName`
+ * is the raw provider-side id (e.g. the project GUID, "a20912fc-..."), NOT
+ * the friendly Security-tab name — the friendly name Azure DevOps shows in
+ * the UI comes back in `customDisplayName` instead. Matching only on
+ * `providerDisplayName` (the field the REST docs describe as "the display
+ * name") silently missed a real, correctly-permissioned identity — the
+ * General search itself already found it (count: 1); the exact-match gate
+ * was reading the wrong field. Match whichever of the two is the friendly
+ * name; returns undefined only when NEITHER equals `displayName` exactly.
+ */
+export async function resolveIdentityByDisplayName(displayName: string): Promise<string | undefined> {
+  const url = `${vsspsBaseUrl()}/_apis/identities?searchFilter=General&filterValue=${encodeURIComponent(displayName)}&queryMembership=None&api-version=7.1`;
+  const result = await fetchJson<IdentitiesResponse>(url, 'Read identities');
+  return (result.value ?? []).find(
+    (identity) => identity.customDisplayName === displayName || identity.providerDisplayName === displayName,
+  )?.descriptor;
+}
+
+/**
+ * `agent` (one of "agent-tarun" / "agent-vivek" / "agent-reviewer") -> the
+ * GUID identity id a Git PR API call accepts as `reviewers/{reviewerId}` or
+ * expects back as `createdBy.id`. Throws — never returns a partial or guessed
+ * id — when either hop finds nothing, naming which hop failed.
+ */
+export async function resolveAgentIdentityId(agent: string): Promise<string> {
+  const descriptor = await resolveAgentDescriptor(agent);
+  if (!descriptor) {
+    throw new Error(
+      `could not resolve an Azure DevOps identity for '${agent}': Graph subject query returned no exact display-name match`,
+    );
+  }
+  const storageKey = await resolveIdentityStorageKey(descriptor);
+  if (!storageKey) {
+    throw new Error(
+      `could not resolve an Azure DevOps identity for '${agent}': Graph returned a descriptor but no storage key for it`,
+    );
+  }
+  return storageKey;
+}

package/packages/azdo/src/lib/validate-pr-metadata.ts

@@ -0,0 +1,57 @@
+const TITLE_PATTERN = /^(feat|fix|docs|refactor|perf|chore)(\([a-z0-9][a-z0-9-]*\))?: .+$/
+const REQUIRED_SECTIONS = ['Summary', 'Why', 'Changes']
+
+export function validatePullRequestMetadata(title: string, description: string): string[] {
+  return [...validatePullRequestTitle(title), ...validatePullRequestDescription(description)]
+}
+
+export function validatePullRequestTitle(title: string): string[] {
+  const errors: string[] = []
+  const subject = title.slice(title.indexOf(':') + 1).trim()
+
+  if (title.length > 80) errors.push('title exceeds 80 characters')
+  if (!TITLE_PATTERN.test(title)) errors.push('title must use <type>(<scope>): <subject>')
+  if (subject !== subject.toLowerCase()) errors.push('title subject must be lowercase')
+  if (subject.endsWith('.')) errors.push('title must not end with a period')
+
+  return errors
+}
+
+export function validatePullRequestDescription(description: string): string[] {
+  const errors: string[] = []
+  for (const section of REQUIRED_SECTIONS) {
+    const match = description.match(new RegExp(`(?:^|\\n)## ${section}[ \\t]*\\n([\\s\\S]*?)(?=\\n## |$)`, 'i'))
+    if (!match?.[1]?.trim()) errors.push(`description requires a non-empty ## ${section} section`)
+  }
+  return errors
+}
+
+async function loadPullRequest() {
+  const collection = required('SYSTEM_COLLECTIONURI')
+  const project = required('SYSTEM_TEAMPROJECTID')
+  const repository = required('BUILD_REPOSITORY_ID')
+  const pullRequest = required('SYSTEM_PULLREQUEST_PULLREQUESTID')
+  const token = required('SYSTEM_ACCESSTOKEN')
+  const url = `${collection}${project}/_apis/git/repositories/${repository}/pullRequests/${pullRequest}?api-version=7.1`
+  const response = await fetch(url, {
+    headers: { Authorization: `Basic ${btoa(`:${token}`)}` },
+  })
+  if (!response.ok) throw new Error(`Azure DevOps PR lookup failed: ${response.status} ${response.statusText}`)
+  return response.json() as Promise<{ title?: string; description?: string }>
+}
+
+function required(name: string) {
+  const value = process.env[name]
+  if (!value) throw new Error(`missing ${name}`)
+  return value
+}
+
+if (import.meta.main) {
+  const pullRequest = await loadPullRequest()
+  const errors = validatePullRequestMetadata(pullRequest.title ?? '', pullRequest.description ?? '')
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`pr-policy: FAIL — ${error}`)
+    process.exit(1)
+  }
+  console.log('pr-policy: PASS')
+}