@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/azdo/src/azdo-pl.ts

@@ -0,0 +1,275 @@
+/**
+ * azdo-pl.ts — Azure DevOps build tool logic.
+ *
+ * Exported for direct, in-process use by mcp-server.ts — there is no CLI
+ * entry point here (nothing else in the repo invoked this file as a CLI).
+ *
+ * Org/project come from the environment (AZURE_DEVOPS_ORG /
+ * AZURE_DEVOPS_PROJECT, typically via the root .env, which Bun loads
+ * automatically) falling back to the AdoClient defaults. Nothing is
+ * hardcoded here.
+ *
+ * Timeline model: Stage → Phase → Job → Task, chained by parentId
+ * (Checkpoint records carry no user-facing state and are skipped).
+ */
+import { AdoClient } from './lib/client.ts'
+
+let client: AdoClient | undefined
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient()
+  return client
+}
+
+/** Test seam: forget the cached client — see azdo-wit.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
+/** GET a JSON payload. */
+async function getJson<T>(c: AdoClient, path: string, params?: Record<string, string>): Promise<T> {
+  return c.get<T>(path, { 'api-version': '7.1', ...params });
+}
+
+/**
+ * GET a plain-text payload. AdoClient's public API JSON-parses every
+ * response, and build logs are text/plain — so the bytes are fetched
+ * here, composed on the client's connection without modifying it.
+ */
+async function getText(c: AdoClient, path: string): Promise<string> {
+  const conn = c as unknown as {
+    baseUrl: string;
+    acquireAccessToken(): Promise<string>;
+  };
+  const resp = await fetch(`${conn.baseUrl}${path}?api-version=7.1`, {
+    headers: { Authorization: `Bearer ${await conn.acquireAccessToken()}` },
+  });
+  if (!resp.ok) throw new Error(`Azure DevOps API error: ${resp.status} ${(await resp.text()).slice(0, 300)}`);
+  return resp.text();
+}
+
+export interface TimelineNode {
+  type: string;
+  name: string;
+  state: string;
+  result?: string;
+  logId?: number;
+  startTime?: string;
+  children: TimelineNode[];
+}
+
+/** Rebuild the Stage → Phase → Job → Task tree from flat timeline records. */
+function buildTree(records: any[]): Map<string, TimelineNode> {
+  const nodes = new Map<string, TimelineNode>();
+  for (const r of records) {
+    if (r.type === 'Checkpoint') continue;
+    nodes.set(r.id, {
+      type: r.type,
+      name: r.name,
+      state: r.state,
+      result: r.result,
+      logId: r.log?.id,
+      startTime: r.startTime,
+      children: [],
+    });
+  }
+  for (const r of records) {
+    if (r.type === 'Checkpoint' || !r.parentId) continue;
+    nodes.get(r.parentId)?.children.push(nodes.get(r.id)!);
+  }
+  return nodes;
+}
+
+const TYPE_ORDER = ['Stage', 'Phase', 'Job', 'Task'];
+function sortTree(node: TimelineNode): void {
+  node.children.sort(
+    (a, b) => TYPE_ORDER.indexOf(a.type) - TYPE_ORDER.indexOf(b.type) || a.name.localeCompare(b.name),
+  );
+  for (const child of node.children) sortTree(child);
+}
+
+/** Failed Task leaves with their full path and log id. */
+function failedTasks(node: TimelineNode, trail: string[] = []): Array<{ path: string; logId?: number | undefined; name: string; startTime?: string | undefined }> {
+  const here = [...trail, `${node.type}:${node.name}`];
+  if (node.type === 'Task' && node.result === 'failed') return [{ path: here.join(' > '), logId: node.logId, name: node.name, startTime: node.startTime }];
+  return node.children.flatMap((child) => failedTasks(child, here));
+}
+
+type BuildFailure = { stage: string; name: string | null; path: string | null; logId?: number | null | undefined; startTime?: string | undefined };
+
+export function buildProgress(build: any, stages: TimelineNode[]): Record<string, unknown> {
+  const failures: BuildFailure[] = stages.flatMap<BuildFailure>((stage) => {
+    const tasks: BuildFailure[] = failedTasks(stage).map((failure) => ({ stage: stage.name, ...failure }));
+    return tasks.length > 0
+      ? tasks
+      : stage.result === 'failed'
+        ? [{ stage: stage.name, name: null, path: null, logId: null, startTime: stage.startTime }]
+        : [];
+  })
+    .sort((left, right) => (left.startTime ?? '9999').localeCompare(right.startTime ?? '9999'));
+  const settled = build.status === 'completed';
+  const stagesRunning = stages.filter((stage) => stage.state === 'inProgress').map((stage) => stage.name);
+  const stagesPending = stages.filter((stage) => stage.state === 'pending').map((stage) => stage.name);
+  const firstFailure = failures[0];
+  const outstanding = stagesRunning.length + stagesPending.length;
+  return {
+    settled,
+    failureSeen: failures.length > 0,
+    firstFailure: firstFailure ? { stage: firstFailure.stage, task: firstFailure.name, path: firstFailure.path, logId: firstFailure.logId, startTime: firstFailure.startTime } : null,
+    stagesRunning,
+    stagesPending,
+    hint: firstFailure
+      ? firstFailure.name
+        ? `Stage '${firstFailure.stage}' failed at task '${firstFailure.name}'${outstanding ? `; ${outstanding} stage(s) are still unfinished` : ''}. Re-read with tail for its log.`
+        : `Stage '${firstFailure.stage}' failed${outstanding ? `; ${outstanding} stage(s) are still unfinished` : ''}. Azure DevOps has not reported a failed task yet.`
+      : settled ? 'No failed task in the timeline.' : `Nothing has failed yet; ${outstanding} stage(s) still to finish.`,
+  };
+}
+
+async function resolveRepositoryId(c: AdoClient): Promise<{ repository: string; repositoryId: string }> {
+  const { resolveRepository } = await import('./lib/client.ts');
+  const repository = resolveRepository();
+  const resolved = await getJson<any>(c, `/git/repositories/${encodeURIComponent(repository)}`);
+  if (!resolved.id) throw new Error(`Azure DevOps returned no repository id for '${repository}'`);
+  return { repository, repositoryId: resolved.id };
+}
+
+export type BuildListOrGetArgs = { buildId?: string; branch?: string; top?: string; tail?: string };
+
+export async function buildListOrGet(args: BuildListOrGetArgs = {}): Promise<string> {
+  if (args.buildId !== undefined) {
+    const stray = ['branch', 'top'].filter((key) => args[key as 'branch' | 'top'] !== undefined);
+    if (stray.length) throw new Error(`buildId returns one run; ${stray.join(' and ')} only narrow a list and must be omitted`);
+    return buildGetRunDetail({ buildId: args.buildId, tail: args.tail });
+  }
+  if (args.tail !== undefined) throw new Error('tail only applies together with buildId');
+  const c = await getClient()
+  const { repository, repositoryId } = await resolveRepositoryId(c);
+  if (args.branch !== undefined) {
+    const runs = await getJson<any>(c, '/build/builds', { branchName: args.branch, repositoryId, repositoryType: 'TfsGit', '$top': args.top ?? '10' });
+    return JSON.stringify({ repository, branch: args.branch, builds: (runs.value ?? []).map((b: any) => ({
+      id: b.id, buildNumber: b.buildNumber, definition: b.definition?.name, definitionId: b.definition?.id,
+      status: b.status, result: b.result, sourceBranch: b.sourceBranch, sourceCommit: b.sourceVersion?.substring(0, 8), startTime: b.startTime, finishTime: b.finishTime, url: b._links?.web?.href,
+    })) }, null, 2);
+  }
+  const definitions = await getJson<any>(c, '/build/definitions', { repositoryId, repositoryType: 'TfsGit', includeLatestBuilds: 'true', ...(args.top === undefined ? {} : { '$top': args.top }) });
+  return JSON.stringify({
+    repository,
+    definitions: (definitions.value ?? []).map((definition: any) => ({
+      id: definition.id, name: definition.name, path: definition.path, queueStatus: definition.queueStatus,
+      revision: definition.revision, type: definition.type, url: definition.url,
+      latestBuild: definition.latestBuild ? { id: definition.latestBuild.id, buildNumber: definition.latestBuild.buildNumber, status: definition.latestBuild.status, result: definition.latestBuild.result, sourceBranch: definition.latestBuild.sourceBranch, sourceCommit: definition.latestBuild.sourceVersion?.substring(0, 8), finishTime: definition.latestBuild.finishTime } : null,
+    })),
+  }, null, 2);
+}
+
+export type BuildRunArgs = { id: string; branch?: string };
+
+export async function buildRun(args: BuildRunArgs): Promise<string> {
+  if (!args.id) throw new Error('id is required');
+  const definitionId = Number(args.id);
+  if (!Number.isInteger(definitionId) || definitionId < 1) throw new Error(`id must be a positive integer definition id; got '${args.id}'`);
+  const c = await getClient()
+  const body: any = { definition: { id: definitionId } };
+  if (args.branch) body.sourceBranch = args.branch;
+  const build = await c.post<any>('/build/builds', body, { 'api-version': '7.1' });
+  return JSON.stringify({
+    id: build.id,
+    buildNumber: build.buildNumber,
+    definition: build.definition?.name,
+    status: build.status,
+    url: build._links?.web?.href,
+  }, null, 2);
+}
+
+export type BuildRunDetailArgs = { buildId: string; tail?: string | undefined };
+
+export async function buildGetRunDetail(args: BuildRunDetailArgs): Promise<string> {
+  const buildId = Number(args.buildId);
+  if (!Number.isInteger(buildId) || buildId < 1) throw new Error(`buildId must be a positive integer; got '${args.buildId}'`);
+  const c = await getClient()
+  const build = await getJson<any>(c, `/build/builds/${buildId}`);
+  const timeline = await getJson<any>(c, `/build/builds/${buildId}/timeline`);
+  const nodes = buildTree(timeline.records);
+  const stages = timeline.records
+    .filter((r: any) => r.type === 'Stage')
+    .map((r: any) => nodes.get(r.id)!);
+  for (const stage of stages) sortTree(stage);
+  const failures = stages.flatMap((stage: TimelineNode) => failedTasks(stage));
+  const tail = args.tail === undefined ? undefined : Number(args.tail);
+  if (tail !== undefined && (!Number.isInteger(tail) || tail < 1)) throw new Error('tail must be a positive integer');
+  const failedTaskLogs: Array<Record<string, unknown>> | undefined = tail === undefined ? undefined : [];
+  if (tail !== undefined) {
+    const collect = async (node: TimelineNode): Promise<void> => {
+      if (node.type === 'Task' && node.result === 'failed' && node.logId !== undefined) {
+        const lines = (await getText(c, `/build/builds/${buildId}/logs/${node.logId}`)).split('\n').map((line) => line.replace(/\r/g, '').trim()).filter(Boolean);
+        failedTaskLogs!.push({ task: node.name, logId: node.logId, tail: lines.slice(-tail) });
+      }
+      for (const child of node.children) await collect(child);
+    };
+    for (const stage of stages) await collect(stage);
+  }
+  return JSON.stringify({
+    buildId: build.id,
+    buildNumber: build.buildNumber,
+    definition: build.definition?.name,
+    status: build.status,
+    result: build.result,
+    sourceBranch: build.sourceBranch,
+    sourceCommit: build.sourceVersion?.substring(0, 8),
+    startTime: build.startTime,
+    finishTime: build.finishTime,
+    url: build._links?.web?.href,
+    progress: buildProgress(build, stages),
+    stages,
+    failures,
+    failedTaskLogs,
+  }, null, 2);
+}
+
+export type BuildStageDetailArgs = { buildId: string; stageName: string; tail?: string };
+
+export async function buildGetStageDetail(args: BuildStageDetailArgs): Promise<string> {
+  const buildId = Number(args.buildId);
+  const stageName = args.stageName;
+  const tail = args.tail ? parseInt(args.tail) : undefined;
+  if (!buildId || !stageName) {
+    throw new Error('--build-id and --stage-name are required');
+  }
+  const c = await getClient()
+  const timeline = await getJson<any>(c, `/build/builds/${buildId}/timeline`);
+  const stage = timeline.records.find((r: any) => r.type === 'Stage' && r.name === stageName);
+  if (!stage) {
+    throw new Error(`Stage '${stageName}' not found`);
+  }
+  const nodes = buildTree(timeline.records);
+  const root = nodes.get(stage.id)!;
+  sortTree(root);
+  const failures = failedTasks(root);
+
+  let failedTaskLogs: Array<Record<string, unknown>> | undefined;
+  if (tail) {
+    failedTaskLogs = [];
+    const collect = async (node: TimelineNode): Promise<void> => {
+      if (node.type === 'Task' && node.result === 'failed' && node.logId != null) {
+        const lines = (await getText(c, `/build/builds/${buildId}/logs/${node.logId}`))
+          .split('\n')
+          .map((line) => line.replace(/\r/g, '').trim())
+          .filter(Boolean);
+        failedTaskLogs!.push({ task: node.name, logId: node.logId, tail: lines.slice(-tail) });
+      }
+      for (const child of node.children) await collect(child);
+    };
+    await collect(root);
+  }
+
+  return JSON.stringify({
+    stageName: root.name,
+    state: root.state,
+    result: root.result,
+    stage: root,
+    failedTaskCount: failures.length,
+    failures,
+    failedTaskLogs,
+  }, null, 2);
+}

package/packages/azdo/src/azdo-pr-review.ts

@@ -0,0 +1,160 @@
+// Azure DevOps pull request REVIEW tool logic — comment + vote (C3,
+// docs/operations/agent-permissions.md rows 6-8). Exported for direct, in-process use by
+// mcp-server.ts, mirroring azdo-pr.ts's own shape exactly: its own client
+// cache, its own resetClientForTests() test seam.
+//
+// REST APIs used (verified against Microsoft's docs 2026-09-27, cited again
+// at each call site below):
+//   - Pull Request Threads — Create (a general, non-file-scoped PR comment)
+//     POST {org}/{project}/_apis/git/repositories/{repository}/pullRequests/{pullRequestId}/threads?api-version=7.1
+//     https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-request-threads/create
+//   - Pull Requests — Get Pull Request (read the REAL target branch before
+//     casting a vote — see assertVoteTarget() below)
+//     GET {org}/{project}/_apis/git/repositories/{repository}/pullRequests/{pullRequestId}?api-version=7.1
+//   - Pull Request Reviewers — Create Pull Request Reviewer (its own title
+//     is literally "Add a reviewer to a pull request or cast a vote" — one
+//     PUT does both)
+//     PUT {org}/{project}/_apis/git/repositories/{repository}/pullRequests/{pullRequestId}/reviewers/{reviewerId}?api-version=7.1
+//     body: { vote: <int>, id: <reviewerId> }
+//     https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-request-reviewers/create-pull-request-reviewer
+//
+// `reviewerId` is never invented or accepted from the caller — there is no
+// such argument on this tool. lib/graph-identity.ts resolves the CALLING
+// agent's own identity (Graph Subject Query + Storage Keys — the same
+// two-hop bridge azdo-repo-doctor.ts already uses for its own read-only ACL
+// checks) into the legacy GUID id this endpoint expects.
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+import { AdoClient, resolveRepository } from './lib/client.ts';
+import { resolveAgentIdentityId } from './lib/graph-identity.ts';
+import { pullRequestsPath } from './azdo-pr.ts';
+
+let client: AdoClient | undefined;
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient();
+  return client;
+}
+
+/** Test seam: forget the cached client — see azdo-pr.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined;
+}
+
+const threadsPath = (repository: string, id: string): string => `${pullRequestsPath(repository, id)}/threads`;
+const reviewersPath = (repository: string, id: string, reviewerId: string): string =>
+  `${pullRequestsPath(repository, id)}/reviewers/${reviewerId}`;
+
+/**
+ * Vote names, matching `az repos pr set-vote --vote`'s own vocabulary so a
+ * later REWRITE rule (docs/operations/agent-permissions.md "Build order", Stream B) can
+ * translate one to the other without inventing a second vocabulary — mapped
+ * to the REST API's actual integer values (Pull Request Reviewers — Create
+ * Pull Request Reviewer's documented `vote` field: "10 - approved, 5 -
+ * approved with suggestions, 0 - no vote, -5 - waiting for author, -10 -
+ * rejected").
+ */
+export const VOTE_VALUES = {
+  approve: 10,
+  'approve-with-suggestions': 5,
+  reset: 0,
+  'wait-for-author': -5,
+  reject: -10,
+} as const;
+export type VoteName = keyof typeof VOTE_VALUES;
+export const VOTE_NAMES = Object.keys(VOTE_VALUES) as readonly VoteName[];
+
+/** Row 8's exact text — the hook (adl-pr-review-role.ts) uses the identical string; kept in sync by the shared test corpus, not by import (agent-hooks does not depend on this package). */
+export const NO_VOTE_GATE_ON_INTEGRATION_MESSAGE =
+  'no vote gate on integration — CI + auto-complete only, no human or agent review there';
+
+/** Row 7's exact text. */
+export function voteRoleDeniedMessage(agent: string): string {
+  return `human approval gate — an agent vote does not substitute for Tarun's or Vivek's own review (docs/operations/agent-permissions.md row 7); '${agent}' may still comment`;
+}
+
+export function targetBranchRequiredMessage(): string {
+  return "vote requires targetBranch (the pull request's real target branch) — refusing rather than casting a vote on a PR this call never named";
+}
+
+export function targetBranchMismatchMessage(claimed: string, actual: string): string {
+  return `targetBranch '${claimed}' does not match this pull request's real target '${actual}' — refusing rather than trusting a stale or wrong claim`;
+}
+
+export type PrReviewArgs = {
+  pullRequestId: string;
+  comment?: string;
+  vote?: VoteName;
+  /**
+   * The caller's claim about the PR's real target branch. Required when
+   * voting — never trusted alone: re-verified below against Azure DevOps's
+   * own `targetRefName` before any vote is cast, the same "ask Azure, not
+   * the caller" discipline azdo-pr.ts's assertBranchReadyForPr already uses
+   * for the ancestry check. Its only OTHER purpose is letting
+   * adl-pr-review-role.ts (packages/agent-hooks), which has no network
+   * access, fail closed before this function ever runs.
+   */
+  targetBranch?: string;
+  /** Overrides AZURE_DEVOPS_REPO for this call. */
+  repository?: string;
+};
+
+/** Rows 7 and 8, in the order the hook checks them (the more universal restriction — no gate on integration at all — first). */
+function assertVoteAllowed(targetBranch: string, agent: string): void {
+  if (targetBranch === 'integration') throw new Error(NO_VOTE_GATE_ON_INTEGRATION_MESSAGE);
+  if (targetBranch !== 'main') {
+    throw new Error(`votes are only defined for pull requests targeting 'main' or 'integration', not '${targetBranch}'`);
+  }
+  if (agent !== 'agent-reviewer') throw new Error(voteRoleDeniedMessage(agent));
+}
+
+export async function prReview(args: PrReviewArgs): Promise<string> {
+  const { pullRequestId, comment, vote, targetBranch, repository: repositoryArg } = args;
+  if (!pullRequestId) throw new Error('pullRequestId is required');
+  if (comment === undefined && vote === undefined) throw new Error('supply comment, vote, or both');
+  if (comment !== undefined && comment.trim() === '') throw new Error('comment must not be blank');
+  if (vote !== undefined && !VOTE_NAMES.includes(vote)) {
+    throw new Error(`vote must be one of ${VOTE_NAMES.join(', ')}`);
+  }
+
+  // Fail closed BEFORE any network call — a vote request that cannot prove
+  // it is allowed never gets far enough to leak a PR's existence, an
+  // identity lookup, or anything else via timing/side channel.
+  if (vote !== undefined) {
+    if (!targetBranch || targetBranch.trim() === '') throw new Error(targetBranchRequiredMessage());
+    assertVoteAllowed(targetBranch, resolveAgentIdentity().agent);
+  }
+
+  const repository = resolveRepository(repositoryArg);
+  const c = await getClient();
+  const result: Record<string, unknown> = {};
+
+  if (comment !== undefined) {
+    const thread = await c.post<any>(
+      threadsPath(repository, pullRequestId),
+      { comments: [{ parentCommentId: 0, content: comment, commentType: 1 }], status: 1 },
+      { 'api-version': '7.1' },
+    );
+    result.comment = { threadId: thread.id, commentId: thread.comments?.[0]?.id, content: comment };
+  }
+
+  if (vote !== undefined) {
+    // targetBranch and role were already asserted above; re-derive the REAL
+    // target from Azure DevOps and refuse on mismatch rather than trusting
+    // the caller's claim for the actual vote.
+    const pr = await c.get<any>(pullRequestsPath(repository, pullRequestId), { 'api-version': '7.1' });
+    const actualTarget = String(pr.targetRefName ?? '').replace(/^refs\/heads\//, '');
+    if (actualTarget !== targetBranch) throw new Error(targetBranchMismatchMessage(targetBranch!, actualTarget));
+
+    const agent = resolveAgentIdentity().agent;
+    const reviewerId = await resolveAgentIdentityId(agent);
+    const voteValue = VOTE_VALUES[vote];
+    await c.put<any>(
+      reviewersPath(repository, pullRequestId, reviewerId),
+      { vote: voteValue, id: reviewerId },
+      { 'api-version': '7.1' },
+    );
+    result.vote = { reviewerId, vote, voteValue };
+  }
+
+  return JSON.stringify(result, null, 2);
+}