@taiga-ai/mcp-server 0.25.0-rc.472 → 0.26.0-dev.479

package/src/tools/builds.ts

@@ -1,668 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import {
-  type BuildRunStep,
-  type BuildRunWithContext,
-  BUILD_RUN_STATUSES,
-  dispositionOf,
-  type BuildRunStatus,
-} from '@taiga/types';
-import type { TaigaClient, WithoutTenant } from '../client.js';
-import { OPERATE, READ_ONLY } from './annotations.js';
-import { idInput, pagination, productId } from './inputs.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { TaigaApiError } from '../client.js';
-import { page, pickFields } from './summarize.js';
-
-/** What a list row needs to say for the model to pick a run to read in full. */
-export const BUILD_SUMMARY_FIELDS = [
-  'id',
-  'runNumber',
-  'productId',
-  'backlogItemId',
-  'targetTitle',
-  'planId',
-  'status',
-  'failedReason',
-  'repositoryFullName',
-  'branch',
-  'baseBranch',
-  'completedSteps',
-  'totalSteps',
-  'prNumber',
-  'prUrl',
-  'prState',
-  'prDraft',
-  'prMerged',
-  'reviewEscalation',
-  'error',
-  'actions',
-  'createdAt',
-  'startedAt',
-  'completedAt',
-] as const;
-
-/** What a run says about itself after a stop or a resume: its state and what can be done next. */
-const RUN_OUTCOME_FIELDS = [
-  'id',
-  'runNumber',
-  'backlogItemId',
-  'status',
-  'failedReason',
-  'completedSteps',
-  'totalSteps',
-  'prNumber',
-  'prUrl',
-  'prDraft',
-  'prMerged',
-  'reviewEscalation',
-  'error',
-  'actions',
-] as const;
-
-/**
- * Where a run that ended without finishing stopped, from its steps and its
- * hardening result: a failed run with every step completed reads as nothing
- * failed, and retry_from_failed_step then reads as a mistake, when the agent
- * stalled in the hardening pass after the steps and the retry continues it.
- * Null for a run still going or that finished.
- */
-export function stoppedIn(
-  run: Pick<WithoutTenant<BuildRunWithContext>, 'prMerged' | 'status' | 'hardeningResult'>,
-  steps: readonly Pick<WithoutTenant<BuildRunStep>, 'status' | 'stepOrder' | 'title'>[]
-): string | null {
-  // A merged run is finished, whatever its status still says: the merge is
-  // latched apart from the status, which can stay at a stale failed or stopped.
-  if (run.prMerged === true || (run.status !== 'failed' && run.status !== 'stopped')) return null;
-  // No step started yet: the run never got past setting up (cloning, the
-  // workspace), whatever the first step is called.
-  const started = steps.some((step) => step.status !== 'planned');
-  if (!started) return 'before the first step started, while setting up the run (cloning, preparing the workspace)';
-  const open = steps.find((step) => step.status !== 'completed' && step.status !== 'skipped');
-  if (open) {
-    return open.status === 'planned'
-      ? `before step ${String(open.stepOrder)}, ${String(open.title)}, started (the ones before it completed)`
-      : `step ${String(open.stepOrder)}, ${String(open.title)} (${String(open.status)})`;
-  }
-  if (run.hardeningResult == null) {
-    return (
-      'after the last step, in hardening: the security scanners and their fixes the agent runs before the ' +
-      'pull request is ready. A retry continues from there; the steps stay.'
-    );
-  }
-  return 'after the steps and hardening, at the pull request';
-}
-
-/**
- * The disposition with the merge latch authoritative: a run whose pull
- * request merged landed, whatever settled status it kept when the completion
- * write after the merge failed (build.ts allows a merged run to stay failed
- * or stopped). A run still executing keeps its in-flight disposition.
- */
-export function landedDisposition(status: BuildRunStatus, prMerged: boolean): string {
-  const disposition = dispositionOf(status, prMerged);
-  return prMerged && disposition !== 'in_flight' ? 'succeeded' : disposition;
-}
-
-/** What each executing status is doing, in a phrase. */
-const RUNNING: Partial<Record<BuildRunStatus, string>> = {
-  cloning: 'setting up the workspace',
-  implementing: 'implementing the steps',
-  hardening: 'hardening: running the security scanners and fixing what they find',
-  pushing: 'pushing the branch',
-  ci_checking: "waiting for the pull request's CI",
-  ci_fixing: 'fixing what CI found',
-  reviewing: 'answering review comments on the pull request',
-};
-
-/** Why the agent handed a run back, in the web's words (apps/web handback), with the checks it names. */
-export function handbackSaid(escalation: unknown): string | null {
-  if (!escalation || typeof escalation !== 'object') return null;
-  const e = escalation as {
-    reason?: unknown;
-    rounds?: unknown;
-    failingChecks?: unknown;
-    file?: unknown;
-    blockers?: unknown;
-  };
-  const checks = Array.isArray(e.failingChecks)
-    ? (e.failingChecks as { name?: unknown }[]).map((check) => String(check.name)).join(', ')
-    : '';
-  const on = checks ? ` on ${checks}` : '';
-  const rounds =
-    typeof e.rounds === 'number' && e.rounds > 0
-      ? ` after ${e.rounds} automatic round${e.rounds === 1 ? '' : 's'}`
-      : '';
-  const blockers = Array.isArray(e.blockers)
-    ? (e.blockers as unknown[]).map((b) => READY_BLOCKER_SAID[String(b)] ?? String(b))
-    : [];
-  switch (e.reason) {
-    case 'ci_fix_cap':
-      return `CI is still failing${on}${rounds}`;
-    case 'ci_fix_stalled':
-      return `CI is still failing${on}, and the last fix round changed nothing`;
-    case 'conflict_cap':
-      return `the branch still conflicts with its base${rounds}`;
-    case 'review_bot_cap':
-      return `review bots still have open comments${rounds}`;
-    case 'ci_never_settled':
-      return 'CI did not finish in time';
-    case 'ready_blocked':
-      return `CI is green, but Taiga kept the pull request a draft${blockers.length ? `: ${blockers.join('; ')}` : ''}`;
-    case 'check_weakened':
-      return `CI went green only after a check was loosened${typeof e.file === 'string' ? ` in ${e.file}` : ''}`;
-    default:
-      return typeof e.reason === 'string' ? e.reason : null;
-  }
-}
-
-/** What a person does about a handback, by its reason, as the web's handback detail says it. */
-export function handbackNextStep(escalation: unknown): string {
-  const reason = escalation && typeof escalation === 'object' ? (escalation as { reason?: unknown }).reason : null;
-  if (reason === 'check_weakened') return 'review the loosened check on GitHub before merging';
-  if (reason === 'ci_never_settled')
-    return 'look at what is still running or queued in CI on GitHub, then review the pull request';
-  return 'fix it by hand, or review the pull request on GitHub, which hands it back to the agent';
-}
-
-/** The web's words for why Taiga keeps a pull request a draft. */
-const READY_BLOCKER_SAID: Record<string, string> = {
-  plan_incomplete: 'not every planned step shipped',
-  tests_failed: 'the tests Taiga ran after the build failed',
-  bar_lowering: 'a fix lowered a check instead of fixing the code',
-  bar_lowering_unchecked: 'Taiga could not check whether a fix lowered a check',
-  criticals_unresolved: "Taiga's own review left a critical issue unresolved",
-};
-
-/** The first sentence of a run's error, short enough for a row. */
-function errorSaid(error: unknown): string | null {
-  if (typeof error !== 'string' || !error.trim()) return null;
-  const first = error
-    .trim()
-    .split(/\n|(?<=[.!?])\s/)[0]!
-    .replace(/[.!?]$/, '');
-  return first.length > 240 ? `${first.slice(0, 240).trimEnd()}...` : first;
-}
-
-/**
- * How a run stands, in one sentence, with its disposition: the meaning the
- * status and the pull request facts carry between them
- * (PRO-2800). An agent read `closed` with failedReason null, every step
- * completed and hardening passed, and could not tell what had happened; the
- * status alone cannot say whether a completed run merged (dispositionOf).
- */
-export function runOutcome(run: Record<string, unknown>): { disposition: string; outcome: string } | null {
-  const status = run['status'] as BuildRunStatus;
-  if (!(BUILD_RUN_STATUSES as readonly string[]).includes(status)) return null;
-  const disposition = landedDisposition(status, run['prMerged'] === true);
-  const pr = typeof run['prNumber'] === 'number' ? `PR #${run['prNumber']}` : 'its pull request';
-  const progress =
-    typeof run['completedSteps'] === 'number' && typeof run['totalSteps'] === 'number'
-      ? ` (${run['completedSteps']} of ${run['totalSteps']} steps done)`
-      : '';
-  // The error says what happened; the failedReason is only its code (PRO-2800).
-  const why = errorSaid(run['error']) ?? (typeof run['failedReason'] === 'string' ? run['failedReason'] : null);
-  const handback = handbackSaid(run['reviewEscalation']);
-  const draft = run['prDraft'] === true ? `, still a draft` : '';
-  const sentence: Record<string, string> = {
-    in_flight: status === 'pending' ? 'Queued: waiting to start.' : `Running: ${RUNNING[status] ?? status}${progress}.`,
-    // A handback is a person's turn too, but not a plain review: say what the agent could not get past.
-    gated: handback
-      ? `Handed back to a person: ${handback}. ${pr}${draft ? `${draft},` : ''} waits for them to ${handbackNextStep(run['reviewEscalation'])}.`
-      : `Waiting for a person to review and merge ${pr}${draft}.`,
-    succeeded: `Merged: ${pr} is in ${typeof run['baseBranch'] === 'string' ? run['baseBranch'] : 'the base branch'}.`,
-    unmerged:
-      typeof run['prNumber'] === 'number' || run['prUrl']
-        ? `Settled without merging: ${pr} was left unmerged.`
-        : 'Settled without a merged pull request.',
-    failed: `Failed${why ? `: ${why}` : ''}${progress}.`,
-    stopped: `Stopped before it finished${progress}.`,
-    rejected: `${pr} was closed without merging, so the work did not land.${handback ? ` It had been handed back: ${handback}.` : ''}`,
-  };
-  return { disposition, outcome: sentence[disposition] ?? status };
-}
-
-/**
- * What hardening left blocking, in a sentence: the findings the run names (PRO-2817), or, for a run reported before
- * it recorded them, how many.
- */
-function hardeningSaid(blocking: number, named: Record<string, unknown>[]): string {
-  const count = `Hardening ended with ${blocking} blocking finding${blocking === 1 ? '' : 's'} it could not fix`;
-  if (named.length === 0) return `${count}; the run records how many, not which.`;
-  const shown = named.slice(0, 3).map((finding) => {
-    const message = String(finding['message']);
-    const where = finding['line'] ? `${String(finding['path'])}:${String(finding['line'])}` : String(finding['path']);
-    // Always where it is, though a scanner's title may repeat the path: a substring test would drop a real one.
-    return `${message} (${String(finding['tool'])}, ${where})`;
-  });
-  const rest = blocking - shown.length;
-  const recorded = named.length > shown.length ? `, ${named.length} recorded in taiga_get_run` : '';
-  return `${count}: ${shown.join('; ')}${rest > 0 ? `; and ${rest} more${recorded}` : ''}.`;
-}
-
-/**
- * What each failedReason means for the next move (PRO-2800): reviewers met dispatch_rejected and agent_reported as
- * bare enums. As @taiga/types documents them.
- */
-const FAILED_REASON_MEANS: Record<string, string> = {
-  agent_reported: 'the agent stopped and said why (error); resuming would likely hit the same wall',
-  server_orphan: 'the run stopped reporting (its machine died or ran out of memory); resuming can recover',
-  agent_stalled: 'the agent kept running but stopped making progress; resuming can recover',
-  user_stopped: 'it was stopped, by a person or because its initiative was settled',
-  timeout: 'it ran past its time limit; resuming continues from the unfinished step',
-  dispatch_rejected: 'the agent never started (its environment or credentials failed); resuming dispatches it again',
-  context_exhaustion: 'the agent ran out of context on a step; resuming starts that step fresh',
-};
-
-/**
- * A run row as an agent reads it: its outcome added, and prDraft only where
- * there is a pull request. The column defaults to true, so a run that never
- * opened one said it had a draft (PRO-2800). A list row leaves the full error
- * text out: its first sentence is in the outcome, and taiga_get_run has it all.
- */
-export function readableRun(run: Record<string, unknown>, opts: { row?: boolean } = {}): Record<string, unknown> {
-  // runtime names the machinery a run used (legacy or engineer): nothing an agent acts on.
-  const { prDraft, error, reviewEscalation, runtime: _runtime, ...rest } = run;
-  const said = runOutcome(run);
-  const means = FAILED_REASON_MEANS[String(run['failedReason'])];
-  const hardening = run['hardeningResult'] as { blockingFindings?: unknown; blocking?: unknown } | null | undefined;
-  const blocking = typeof hardening?.blockingFindings === 'number' ? hardening.blockingFindings : 0;
-  const named = Array.isArray(hardening?.blocking) ? (hardening.blocking as Record<string, unknown>[]) : [];
-  return {
-    ...rest,
-    ...(means ? { failedReasonMeans: means } : {}),
-    ...(blocking > 0
-      ? {
-          hardeningNote: hardeningSaid(blocking, named),
-        }
-      : {}),
-    // A row's outcome says the error and the handback; the full read keeps them whole.
-    ...(opts.row || error === undefined ? {} : { error }),
-    ...(opts.row || reviewEscalation === undefined ? {} : { reviewEscalation }),
-    // A PR number proves a PR exists (isSettledWithoutPr); the URL is nullable apart from it.
-    ...(typeof rest['prNumber'] === 'number' || rest['prUrl'] ? { prDraft } : {}),
-    ...(said ?? {}),
-  };
-}
-
-/** Distinct initiatives a run list reads to say which moved on; past this a waiting row says it was not checked. */
-const INITIATIVE_CHECKS = 10;
-
-/**
- * The status of the initiative behind each run still waiting on its pull
- * request (PRO-2800). A reviewing agent read a run of a canceled initiative as
- * "waiting for a person to review and merge" while Action Required called the
- * same review stale.
- *
- * The run says it itself since PRO-2808 (initiativeClosed: done, canceled,
- * archived, deleted, or null while live), for every key that can read it.
- * Against an API from before that, each initiative is read: a 404 is
- * 'deleted', and an initiative past the cap, one whose read failed, and every
- * one without backlog:read is 'unchecked', which withInitiativeState adds to
- * the row's outcome.
- */
-export async function initiativeStates(
-  client: TaigaClient,
-  rows: Record<string, unknown>[]
-): Promise<Map<string, string>> {
-  const states = new Map<string, string>();
-  // Only the runs that could still be waiting: a settled run's initiative changes nothing about it.
-  const waiting = rows.filter(
-    (row) => ['needs_review', 'completed'].includes(String(row['status'])) && row['prMerged'] !== true
-  );
-  const told = waiting.filter((row) => 'initiativeClosed' in row);
-  for (const row of told) {
-    if (typeof row['backlogItemId'] === 'string') {
-      states.set(row['backlogItemId'], typeof row['initiativeClosed'] === 'string' ? row['initiativeClosed'] : 'live');
-    }
-  }
-  const all = [
-    ...new Set(
-      waiting
-        .filter((row) => !('initiativeClosed' in row))
-        .map((row) => row['backlogItemId'])
-        .filter((id): id is string => typeof id === 'string' && !states.has(id))
-    ),
-  ];
-  // Without backlog:read, or past the cap, a waiting run's initiative is not read: it is marked unchecked so
-  // the row does not claim a person is waiting when nobody may be.
-  const ids = client.hasCapability('backlog:read') ? all.slice(0, INITIATIVE_CHECKS) : [];
-  for (const id of all) if (!ids.includes(id)) states.set(id, 'unchecked');
-  await Promise.all(
-    ids.map(async (id) => {
-      try {
-        const item = (await client.getBacklogItem(id)).data as unknown as Record<string, unknown>;
-        // Archiving keeps the status it had, so it is read apart, as the API reads it (initiativeClosed).
-        states.set(id, item['archivedAt'] ? 'archived' : String(item['status'] ?? item['state']));
-      } catch (error) {
-        if (error instanceof TaigaApiError && error.status === 404) return void states.set(id, 'deleted');
-        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
-        states.set(id, 'unchecked');
-      }
-    })
-  );
-  return states;
-}
-
-/**
- * How each way an initiative ends reads on a run it left waiting: the same set
- * Action Required closes a run's review for (PRO-2806). A done one's waiting
- * run is not the one that landed it: that run is merged and never waiting.
- */
-const INITIATIVE_ENDED: Record<string, string> = {
-  done: 'was marked done',
-  canceled: 'was canceled',
-  archived: 'was archived',
-  deleted: 'was deleted',
-};
-
-/** A readable run row that also says when its initiative ended while its pull request waited. */
-export function withInitiativeState(
-  row: Record<string, unknown>,
-  states: Map<string, string>
-): Record<string, unknown> {
-  const state = states.get(String(row['backlogItemId']));
-  // A run still executing is left as it is: its initiative's cancel stops it, and one still going after that is
-  // what taiga_stop_run is for.
-  if (!['gated', 'unmerged'].includes(String(row['disposition']))) return row;
-  if (state === 'unchecked') {
-    return { ...row, outcome: `${String(row['outcome'])} Whether its initiative still wants it was not checked.` };
-  }
-  const ended = state ? INITIATIVE_ENDED[state] : undefined;
-  if (!ended) return row;
-  const pr = typeof row['prNumber'] === 'number' ? `PR #${row['prNumber']}` : 'its pull request';
-  const open = row['prState'] === 'open' ? ` ${pr} is still open on the forge.` : '';
-  return {
-    ...row,
-    disposition: 'abandoned',
-    // Retry or start over cannot succeed once the initiative is gone.
-    actions: [],
-    outcome: `Its initiative ${ended}, so nobody is waiting on this run.${open}`,
-  };
-}
-
-/** A step that changed only prose: no code of its own could have broken a test. */
-const PROSE_ONLY = /(^|\/)(README|CHANGELOG|LICENSE|NOTICE|AUTHORS)$|\.(md|mdx|txt|rst|adoc)$/i;
-
-/**
- * What a check that failed after every step means (PRO-2800). Two reviews read
- * seven steps of "tests: failed" as seven breakages, while the headlines said
- * each step's own tests passed: a check that fails from the first step on,
- * docs-only steps included, is one the repository or the check environment
- * carries throughout. The check records no reason, so this says what the
- * pattern shows and no more.
- */
-export function verificationNote(steps: Record<string, unknown>[]): string | null {
-  const checked = steps.filter((step) => Array.isArray(step['verification']) && step['verification'].length > 0);
-  if (checked.length < 2) return null;
-  type Check = { check?: unknown; status?: unknown; reason?: unknown };
-  const failedOn = (step: Record<string, unknown>) =>
-    (step['verification'] as Check[]).filter((check) => check.status === 'failed').map((check) => String(check.check));
-  const always = failedOn(checked[0]!).filter((check) => checked.every((step) => failedOn(step).includes(check)));
-  if (always.length === 0) return null;
-  const prose = checked.find((step) => {
-    const files = step['filesChanged'];
-    return Array.isArray(files) && files.length > 0 && files.every((file) => PROSE_ONLY.test(String(file)));
-  });
-  // Two code steps both failing may be two real breakages; the pattern needs three, or a step with no code.
-  if (!prose && checked.length < 3) return null;
-  const reasons = [
-    ...new Set(
-      checked.flatMap((step) =>
-        (step['verification'] as Check[])
-          .filter((check) => check.status === 'failed' && always.includes(String(check.check)))
-          .map((check) => check.reason)
-          .filter((reason): reason is string => typeof reason === 'string' && reason.length > 0)
-      )
-    ),
-  ];
-  const first = checked[0]!['stepOrder'];
-  const last = checked[checked.length - 1]!['stepOrder'];
-  const proseSaid = prose ? `, including step ${String(prose['stepOrder'])}, which changed only documentation` : '';
-  return (
-    `Taiga's ${always.join(' and ')} check failed after every checked step (${String(first)} to ${String(last)})` +
-    `${proseSaid}. A check failing from the first step on is usually one the repository or the check ` +
-    'environment fails throughout, not one each step broke. ' +
-    (reasons.length > 0
-      ? `Its reason${reasons.length === 1 ? '' : 's'}: ${reasons.slice(0, 3).join('; ')}.`
-      : "It records no reason; each step's headline says what its own run found.")
-  );
-}
-
-/** readableRun for a list row. */
-export const readableRow = (run: Record<string, unknown>) => readableRun(run, { row: true });
-
-/** How many products the org-wide list names; past this a row keeps its productId only. */
-const NAMED_PRODUCTS = 100;
-
-const runId = idInput('run', 'taiga_list_runs gives it');
-
-/** A step without its instructions: what it is, how it stands and what it changed. */
-const STEP_SUMMARY_FIELDS = [
-  'stepOrder',
-  'title',
-  'status',
-  'currentPhase',
-  'commitSha',
-  'filesChanged',
-  'verification',
-  'error',
-  'errorClassification',
-  'startedAt',
-  'completedAt',
-] as const;
-
-/**
- * A step a failed run never reached reads as planned, as it was (PRO-2800): a run rejected before it began showed
- * each step failed with "still in flight", though none had started. The API reaches failed only through in_progress,
- * which sets startedAt, so a failed step without one is a planned step the run's failure swept up.
- */
-function neverStarted(step: Record<string, unknown>): Record<string, unknown> {
-  if (step['status'] !== 'failed' || step['startedAt']) return step;
-  // The sweep also stamped completedAt and an error; a planned step has neither.
-  const { error: _error, ...rest } = step;
-  return { ...rest, status: 'planned', completedAt: null };
-}
-
-/** Past this many characters a step's headline is cut; the full read has the rest. */
-const HEADLINE_LIMIT = 600;
-
-/**
- * The first paragraph of a step's summary: the agent writes its result
- * there (what changed, which checks passed), and the detail after it.
- */
-export function summaryHeadline(summary: unknown): string | null {
-  if (typeof summary !== 'string' || !summary.trim()) return null;
-  const first = summary
-    .trim()
-    .split(/\n\s*\n/, 1)[0]!
-    .trim();
-  return first.length > HEADLINE_LIMIT ? `${first.slice(0, HEADLINE_LIMIT).trimEnd()}...` : first;
-}
-
-/**
- * The runs of every product the key can see, each row naming its product.
- * The route carries product ids only; one products read names them, and a
- * failure of that read leaves the rows unnamed rather than failing the list.
- */
-async function activityRows(
-  client: TaigaClient,
-  opts: { active?: boolean | undefined; limit?: number | undefined; cursor?: string | undefined }
-) {
-  const [runs, products] = await Promise.all([
-    client.listBuildRunActivity(opts),
-    // Only the API failing or being unreachable leaves rows unnamed; a bug
-    // in this code surfaces.
-    client.listProducts({ limit: NAMED_PRODUCTS }).catch((error: unknown) => {
-      if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
-      throw error;
-    }),
-  ]);
-  const nameById = new Map<string, { name: string; slug: string }>();
-  for (const product of products?.data ?? []) {
-    nameById.set(product.id, { name: product.name, slug: product.slug });
-  }
-  const states = await initiativeStates(client, runs.data as Record<string, unknown>[]);
-  const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS)
-    .map(readableRow)
-    .map((row) => withInitiativeState(row, states))
-    .map((row) => {
-      const product = nameById.get(String(row['productId']));
-      return product ? { ...row, product } : row;
-    });
-  const unnamed = rows.some((row) => !('product' in row));
-  // Why a row stayed unnamed, by what the products read said: it failed, it
-  // was cut before that product, or it listed everything the key can see and
-  // the run's product is not among them (deleted since, or not visible).
-  const note = !unnamed
-    ? null
-    : !products
-      ? 'The products could not be read, so rows carry productId only; taiga_get_product names one.'
-      : products.nextCursor !== null
-        ? `Only the first ${NAMED_PRODUCTS} products could be named; a row without product carries productId only.`
-        : 'A row without product belongs to a product the key cannot list (deleted since, or not visible to it); it carries productId only.';
-  return { ...page(rows, runs.nextCursor), ...(note ? { note } : {}) };
-}
-
-export function registerBuildTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_list_runs',
-    {
-      title: 'List runs',
-      description:
-        'List coding agent runs, newest first: branch, pull request, step progress, outcome (one sentence), ' +
-        'actions and disposition: in_flight, gated (a person owes a review and merge), succeeded (merged), ' +
-        'failed, stopped, rejected (pull request closed unmerged), unmerged, or abandoned (its initiative ended: ' +
-        "done, canceled, archived or deleted). Without productId, every product's runs; active: true keeps " +
-        'running ones. taiga_get_run ' +
-        'reads one; carry work on from the initiative (taiga_resume_initiative).',
-      inputSchema: z.object({
-        productId: productId.optional(),
-        initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it')
-          .optional()
-          .describe("Only this initiative's runs -- get from taiga_list_initiatives; needs productId"),
-        active: z
-          .boolean()
-          .optional()
-          .describe(
-            'Only runs the agent is executing now (cloning through reviewing; a queued pending run is not yet ' +
-              'executing and is left out); for the org-wide list'
-          ),
-        ...pagination,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        if (!params.productId && params.initiativeId) {
-          return toolError(
-            'VALIDATION_ERROR',
-            'initiativeId narrows the runs of one product: pass its productId as well (the initiative carries it).'
-          );
-        }
-        // The product route has no such filter; a silently ignored one would
-        // hand the model finished runs as running.
-        if (params.productId && params.active) {
-          return toolError(
-            'VALIDATION_ERROR',
-            "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status."
-          );
-        }
-        if (params.productId) {
-          const result = await client.listBuildRuns(params.productId, {
-            backlogItemId: params.initiativeId,
-            limit: params.limit,
-            cursor: params.cursor,
-          });
-          const raw = result.data as Record<string, unknown>[];
-          const states = await initiativeStates(client, raw);
-          return toolResult(
-            page(
-              pickFields(raw, BUILD_SUMMARY_FIELDS)
-                .map(readableRow)
-                .map((row) => withInitiativeState(row, states)),
-              result.nextCursor
-            )
-          );
-        }
-        return toolResult(await activityRows(client, params));
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_run',
-    {
-      title: 'Get run',
-      description:
-        'Read one run with its steps: outcome, disposition, pull request, hardening, and per step its title, ' +
-        "status, commit, files changed, verification and headline (first paragraph of the agent's report). " +
-        "verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on " +
-        "the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped " +
-        'run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true ' +
-        'adds complete instructions and reports. actions: resume and retry_from_failed_step are ' +
-        'taiga_resume_initiative; webOnlyActions (start_over) are in the web; to stop it, move the initiative out of Build. A ' +
-        'maintenance run has no initiative and is retried from its finding.',
-      inputSchema: z.object({
-        runId,
-        full: z
-          .boolean()
-          .optional()
-          .describe("Carry each step's complete instructions and report (default false: a summary)"),
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        // Two routes, one answer: fanned out here rather than in the model's
-        // context, like the six-tool pattern asks.
-        const [run, steps] = await Promise.all([
-          client.getBuildRun(params.runId),
-          client.listBuildRunSteps(params.runId),
-        ]);
-        const runRow = run.data;
-        // Steps a failed run never reached read as planned before anything else reads them, stoppedIn included.
-        const rows = steps.data.map((step) =>
-          neverStarted(step as unknown as Record<string, unknown>)
-        ) as unknown as typeof steps.data;
-        const where = stoppedIn(runRow, rows);
-        const stop = where ? { stoppedIn: where } : {};
-        const states = await initiativeStates(client, [runRow as unknown as Record<string, unknown>]);
-        const readable = withInitiativeState(readableRun(runRow), states);
-        const note = verificationNote(rows as unknown as Record<string, unknown>[]);
-        const verification = note ? { verificationNote: note } : {};
-        if (params.full) return toolResult({ ...readable, ...stop, ...verification, steps: rows });
-        return toolResult({
-          ...readable,
-          ...stop,
-          ...verification,
-          steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
-            ...step,
-            headline: summaryHeadline(rows[index]!.summary),
-          })),
-        });
-      })
-  );
-
-  if (!client.hasCapability('products:write')) return;
-
-  server.registerTool(
-    'taiga_stop_run',
-    {
-      title: 'Stop a run',
-      description:
-        'Emergency stop for a run whose initiative cannot be moved out of Build (finished, canceled or gone) but ' +
-        'is still going. Normally stop work by moving the initiative out of Build with taiga_move_initiative. ' +
-        'The agent halts; its branch and any draft pull request stay. Only a run whose actions include stop; ' +
-        'others are refused (CONFLICT).',
-      inputSchema: z.object({ runId }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const result = await client.stopBuildRun(params.runId);
-        return toolResult(readableRow(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]!));
-      })
-  );
-}