@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.481

package/src/tools/backlogs.ts

@@ -1,802 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import {
-  type ActivityEvent,
-  type ActivityActor,
-  type BacklogItem,
-  BUILD_RUN_STATUSES,
-  INITIATIVE_STATES,
-  PLAN_REJECTION_COMMENT_MAX_CHARS,
-  PR_CLOSING_STATES,
-  USER_DROP_STATES,
-  renderHalt,
-  resolveAutoBuild,
-  type BuildRunStatus,
-  type Halt,
-} from '@taiga/types';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
-import { idInput, pagination, productId } from './inputs.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { jobReport } from './jobs.js';
-import { requestPrompt } from './request-prompt.js';
-import { queueView } from './queue.js';
-import { handbackNextStep, handbackSaid, landedDisposition } from './builds.js';
-import { SEARCH_PAGE_SIZE, criteriaCounts, itemRows, page, pickFields, searchPages } from './summarize.js';
-
-/** What a list row needs to say for the model to pick an item to read in full. */
-export const BACKLOG_SUMMARY_FIELDS = [
-  'id',
-  'title',
-  'category',
-  'status',
-  'state',
-  'planningStatus',
-  'priority',
-  'estimate',
-  'origin',
-  'needsHumanCause',
-  'archivedAt',
-  'createdAt',
-  'updatedAt',
-] as const;
-
-/**
- * What an initiative says about itself after a write: where it is on the
- * line, whose turn it is and what the line is waiting for. Not the brief,
- * the criteria or the technical context the caller already has.
- */
-const ITEM_OUTCOME_FIELDS = [
-  'id',
-  'productId',
-  'title',
-  'status',
-  'state',
-  'planningStatus',
-  'needsHumanCause',
-  'needsHumanDetail',
-  'autoBuild',
-  'archivedAt',
-  'lifecycle',
-] as const;
-
-/**
- * What the lifecycle on an initiative says, and the call each next step is.
- * needsHumanCause is only the line's flag; a plan that failed outside the line
- * leaves it null, and the lifecycle is what says why and what moves it on.
- */
-const LIFECYCLE_MEANING =
-  'situation says in a sentence where it stands and what moves it on. lifecycle.cta names the next call: ' +
-  'start_plan taiga_queue_initiative, retry_plan taiga_plan_again (planFailureCause says why), start_build ' +
-  'taiga_approve_plan, resume_build taiga_resume_initiative, retry_build a fresh run (web only), review_pr and ' +
-  'view_pr the pull request. needsHumanCause is set only when the line stopped on it.';
-
-/** The move each call to action is, in the tools' words. */
-const CTA_MOVE: Record<string, string> = {
-  start_plan: 'taiga_queue_initiative puts it on the line to be planned and built (paid work: ask first)',
-  retry_plan: 'taiga_plan_again asks for a new plan (paid work: ask first)',
-  start_build:
-    'read the plan with taiga_get_plan, then taiga_approve_plan builds it or taiga_reject_plan sends it back',
-  resume_build: 'taiga_resume_initiative carries the run on (paid work: ask first)',
-  retry_build: 'a new run starts over from the web; taiga_move_initiative takes it off the line',
-  review_pr: 'a person reviews and merges the pull request',
-  view_pr: 'the line merges the pull request once its checks pass',
-};
-
-/** How a run stands, as the end of "its latest run ...", by disposition. */
-const RUN_STANDS: Record<string, string> = {
-  in_flight: 'is running',
-  gated: 'is in review',
-  succeeded: 'merged',
-  unmerged: 'settled unmerged',
-  failed: 'failed',
-  stopped: 'was stopped',
-  rejected: 'had its pull request closed without merging',
-};
-
-/** Where an initiative is, in a phrase, by its lifecycle stage. */
-const STAGE: Record<string, string> = {
-  backlog: 'In the backlog, not on the line yet',
-  planning: 'Being planned',
-  planned: 'Planned',
-  building: 'Being built',
-  in_review: 'Its pull request is in review',
-  done: 'Done',
-  canceled: 'Canceled',
-};
-
-/**
- * Where an initiative stands and what moves it on, in one sentence (PRO-2800).
- * Five fields carried it (status, state, planningStatus, needsHumanCause,
- * lifecycle) and a reviewing agent had to read the queue, the initiative and
- * the run together to say what had happened; the lifecycle the API derives
- * already decides it. Null for a row without a lifecycle.
- */
-export function situationOf(item: Record<string, unknown>): string | null {
-  const life = item['lifecycle'] as
-    | { turn?: unknown; stage?: unknown; cta?: unknown; planFailureCause?: unknown; latestBuild?: unknown }
-    | null
-    | undefined;
-  if (!life || typeof life.stage !== 'string') return null;
-  const parts: string[] = [];
-  let stage = STAGE[life.stage] ?? life.stage;
-  if (life.stage === 'planning' && life.turn === 'you') {
-    stage = `Planning stopped${typeof life.planFailureCause === 'string' ? ` (${life.planFailureCause})` : ''}`;
-  }
-  const build = life.latestBuild as { status?: unknown; prNumber?: unknown; prMerged?: unknown } | null | undefined;
-  if (build && typeof build.status === 'string' && life.stage !== 'done' && life.stage !== 'canceled') {
-    const pr = typeof build.prNumber === 'number' ? ` (PR #${build.prNumber})` : '';
-    const said = (BUILD_RUN_STATUSES as readonly string[]).includes(build.status)
-      ? RUN_STANDS[landedDisposition(build.status as BuildRunStatus, build.prMerged === true)]
-      : build.status;
-    stage += `; its latest run ${said}${pr}`;
-    // Handed back: what the agent could not get past, which "in review" alone hides.
-    const handback = handbackSaid((build as { reviewEscalation?: unknown }).reviewEscalation);
-    if (handback) stage += `, handed back because ${handback}`;
-  }
-  if (life.stage === 'done' || life.stage === 'canceled') stage += endingSaid(item);
-  parts.push(`${stage}.`);
-  if (typeof item['needsHumanCause'] === 'string') {
-    const halt = renderHalt({ cause: item['needsHumanCause'], params: {} } as unknown as Halt);
-    const detail = typeof item['needsHumanDetail'] === 'string' ? item['needsHumanDetail'] : '';
-    // The halt says what stopped the line; the detail is the run's own reason, kept beside it.
-    const why = [halt, detail]
-      .filter(Boolean)
-      .map((text) => text.replace(/\.$/, ''))
-      .join('. ');
-    if (why) parts.push(`The line stopped on it: ${why}.`);
-  }
-  const turn = life.turn === 'you' ? "A person's turn" : life.turn === 'agent' ? "The agent's turn" : null;
-  const handedBack = handbackSaid((build as { reviewEscalation?: unknown } | null | undefined)?.reviewEscalation);
-  const move =
-    life.cta === 'review_pr' && handedBack
-      ? `a person should ${handbackNextStep((build as { reviewEscalation?: unknown }).reviewEscalation)}`
-      : typeof life.cta === 'string'
-        ? CTA_MOVE[life.cta]
-        : undefined;
-  if (life.cta === 'view_pr') parts.push(`Nothing to do: ${move}.`);
-  else if (turn && move) parts.push(`${turn}: ${move}.`);
-  else if (turn) parts.push(`${turn}.`);
-  else if (move) parts.push(`Next: ${move}.`);
-  return parts.join(' ');
-}
-
-/**
- * How a settled initiative ended, as the rest of its "Done" or "Canceled"
- * sentence (PRO-2821): the pull request that landed it, the move that settled
- * it and who made it, and what took over. Only the single read carries
- * `ending`; a list row says nothing more.
- */
-function endingSaid(item: Record<string, unknown>) {
-  const ending = item['ending'] as
-    | {
-        via?: unknown;
-        at?: unknown;
-        by?: { name?: unknown; type?: unknown } | null;
-        landedPr?: { number?: unknown } | null;
-        supersededBy?: { id?: unknown; title?: unknown } | null;
-      }
-    | null
-    | undefined;
-  // The single read's ending decides. A list row has none, and its latest run cannot say how it ended: a merged
-  // initiative can be reopened and moved to Done by hand, keeping that run. It says Done or Canceled alone.
-  const merged = typeof ending?.landedPr?.number === 'number' ? ending.landedPr.number : null;
-  const said: string[] = [];
-  if (merged !== null) said.push(`: PR #${merged} merged`);
-  else if (ending && (ending.via === 'moved' || ending.via === 'off_the_line')) {
-    const who =
-      typeof ending.by?.name === 'string' ? ending.by.name : ending.by?.type === 'system' ? 'Taiga' : 'someone';
-    const when = typeof ending.at === 'string' ? ` on ${ending.at.slice(0, 10)}` : '';
-    said.push(ending.via === 'off_the_line' ? ` by ${who}${when}, who took it off the line` : ` by ${who}${when}`);
-  }
-  const next = ending?.supersededBy;
-  if (next && typeof next.id === 'string') {
-    said.push(`; superseded by "${String(next.title)}" (${next.id})`);
-  }
-  return said.join('');
-}
-
-/** A row or item with its situation added when it has a lifecycle. */
-export function withSituation(
-  item: Record<string, unknown>,
-  row: Record<string, unknown> = item
-): Record<string, unknown> {
-  const situation = situationOf(item);
-  return situation ? { ...row, situation } : row;
-}
-
-/** List rows, each with its situation. */
-export function situatedRows(items: Record<string, unknown>[]): Record<string, unknown>[] {
-  return itemRows(items, BACKLOG_SUMMARY_FIELDS).map((row, index) => withSituation(items[index]!, row));
-}
-
-/** What each plan failure cause means for whoever reads it next (PLAN_FAILURE_CAUSES in @taiga/types). */
-const PLAN_FAILURE_MEANING: Record<string, string> = {
-  agent_error: 'The planning agent failed. Planning again is the usual next step.',
-  worker_lost: 'Nobody was running the planning any more (the worker stopped). Planning again is the usual next step.',
-  cancelled: 'A person stopped the planning (by says who). Ask before planning it again.',
-};
-
-/**
- * Who or what ended a failed plan, and when, from the initiative's history
- * (PRO-2780): planFailureCause alone said "cancelled" with nobody behind it.
- * Best effort: a history the API will not give leaves the item as it was.
- */
-async function planFailureOf(
-  client: TaigaClient,
-  initiativeId: string,
-  itemCause: unknown
-): Promise<Record<string, unknown> | null> {
-  let events: WithoutTenant<ActivityEvent>[];
-  try {
-    events = (await client.listBacklogItemActivity(initiativeId)).data;
-  } catch (error) {
-    if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
-    throw error;
-  }
-  // Only a failure of the latest attempt: one before the last plan_started
-  // belongs to an earlier attempt, even when it failed for the same reason.
-  let failed: WithoutTenant<ActivityEvent> | undefined;
-  for (const event of [...events].reverse()) {
-    if (event.kind !== 'turn') continue;
-    if (event.trigger === 'plan_started') break;
-    if (event.trigger === 'plan_failed') {
-      failed = event;
-      break;
-    }
-  }
-  if (!failed) return null;
-  const actor: Partial<ActivityActor> = failed.actor ?? {};
-  const data: { cause?: unknown } = failed.data ?? {};
-  const cause = typeof data.cause === 'string' ? data.cause : null;
-  // The event is recorded best effort: one that disagrees with the item's own
-  // cause belongs to an earlier failure, and its who and when are not this one's.
-  if (typeof itemCause === 'string' && cause !== itemCause) {
-    return {
-      cause: itemCause,
-      meaning: PLAN_FAILURE_MEANING[itemCause] ?? 'Planning ended without a plan.',
-      at: null,
-      by: null,
-    };
-  }
-  return {
-    cause,
-    meaning: (cause && PLAN_FAILURE_MEANING[cause]) ?? 'Planning ended without a plan.',
-    at: failed.occurredAt ?? null,
-    by: typeof actor.name === 'string' ? actor.name : (actor.type ?? null),
-  };
-}
-
-const planId = idInput('plan', "taiga_get_plan gives the initiative's active plan and its ID");
-
-const initiativeId = idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it');
-
-/** The plan without its steps' prose: enough to approve it or say what a run will do. */
-const PLAN_SUMMARY_FIELDS = ['id', 'backlogItemId', 'version', 'status', 'createdAt'] as const;
-const PLAN_STEP_SUMMARY_FIELDS = [
-  'id',
-  'orderIndex',
-  'title',
-  'layer',
-  'dependencies',
-  'writes',
-  'reads',
-  'createsResources',
-] as const;
-
-type Item = WithoutTenant<BacklogItem>;
-
-/** The outcome fields of an initiative, with how many of its criteria are met, and where it stands. */
-const outcomeOf = (item: Item) =>
-  withSituation(item as unknown as Record<string, unknown>, {
-    ...pickFields([item], ITEM_OUTCOME_FIELDS)[0],
-    criteria: criteriaCounts(item),
-  });
-
-const outcome = (item: Item) => toolResult(outcomeOf(item));
-
-/** The statuses an initiative in each board column can have: the API keeps in_progress after a first run. */
-const COLUMN_STATUSES: Record<(typeof INITIATIVE_STATES)[number], readonly string[]> = {
-  backlog: ['all', 'open', 'backlog', 'in_progress'],
-  todo: ['all', 'open', 'backlog', 'in_progress'],
-  queue: ['all', 'open', 'backlog', 'in_progress'],
-  plan: ['all', 'open', 'backlog', 'in_progress'],
-  build: ['all', 'open', 'in_progress'],
-  done: ['all', 'done'],
-  canceled: ['all', 'canceled'],
-};
-
-/**
- * Each tool is registered under the capability its route requires, so a
- * key sees exactly what it may call: reads on backlog:read; the board move on
- * backlog:write; queueing on both backlog:write and products:write (the
- * state route checks both for a drop into queue); an initiative request
- * (an agent job), the resume and the review gate on products:write alone, as
- * their routes are (the item ID they take also comes back from a request or a
- * queue); the plan verdicts on products:write together with backlog:read,
- * because the plan ID they take comes only from the plan read; and Plan again
- * on the state route's two (backlog:write, then products:write for a move
- * into plan) together with backlog:read, because it reads the initiative's
- * place at the Build station first.
- *
- * The tools follow how Taiga is meant to be used (docs.tai.ga, Deliver):
- * new work is described and an agent writes the initiative; the queue is
- * the only way to start work; a run is stopped by moving its initiative out
- * of Build and carried on from the initiative.
- */
-export function registerBacklogTools(server: McpServer, client: TaigaClient) {
-  const may = (capability: string) => client.hasCapability(capability);
-  if (may('backlog:read')) registerBacklogReads(server, client);
-  if (may('backlog:write')) registerMove(server, client);
-  if (may('products:write')) registerRequest(server, client);
-  if (may('backlog:write') && may('products:write')) registerQueue(server, client);
-  if (may('products:write')) registerResume(server, client);
-  if (may('products:write')) registerReviewGate(server, client);
-  if (may('backlog:read') && may('products:write')) registerPlanVerdicts(server, client);
-  if (may('backlog:read') && may('backlog:write') && may('products:write')) registerPlanAgain(server, client);
-}
-
-function registerBacklogReads(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_list_initiatives',
-    {
-      title: 'List initiatives',
-      description:
-        "List a product's open initiatives (not done or canceled; status: 'all' for every one): title, " +
-        'category, status, place on the line (backlog, todo, queue, plan, build, done), situation (where it ' +
-        'stands and what moves it on) and criteria (acceptance criteria met, confirmed with evidence or checked ' +
-        'off by a person; null before planning, so a done initiative can show fewer met than it has). query ' +
-        'finds one by title, state one board column; taiga_get_initiative reads it in full. Archived ones are ' +
-        'left out unless asked for.',
-      inputSchema: z.object({
-        productId,
-        query: z
-          .string()
-          .trim()
-          .min(1)
-          .max(200)
-          .optional()
-          .describe('Part of the title, any case: only the items that contain it'),
-        status: z
-          .enum(['open', 'all', 'backlog', 'in_progress', 'done', 'canceled'])
-          .optional()
-          .describe(
-            'open (default without state): not done or canceled; all: every one; in_progress covers everything between backlog and done'
-          ),
-        planningStatus: z
-          .enum(['unplanned', 'planning', 'planned', 'failed'])
-          .optional()
-          .describe('Only items whose plan is in this state'),
-        state: z
-          .enum(INITIATIVE_STATES)
-          .optional()
-          .describe(
-            'Only items in this column of the board: backlog, todo, queue, plan, build, done or canceled (status groups them coarser)'
-          ),
-        category: z.enum(['feature', 'bug', 'tech_debt', 'improvement']).optional().describe('Only this category'),
-        includeArchived: z.boolean().optional().describe('Include archived items (default false)'),
-        ...pagination,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const { query, state, status = state === undefined ? 'open' : 'all', ...filters } = params;
-        // A column and a status that cannot meet answered an empty list with no complaint (PRO-2800).
-        if (state !== undefined && !COLUMN_STATUSES[state].includes(status)) {
-          return toolError(
-            'VALIDATION_ERROR',
-            `No initiative is in the ${state} column with status ${status}: pass state alone, or a status it can have (${COLUMN_STATUSES[state].join(', ')}).`
-          );
-        }
-        // Two reviews asked "what is in the backlog" and got the whole history, done and canceled first
-        // (PRO-2800): open is the default. The API filters by one status only, so open, a board column and a
-        // title are read across pages here.
-        const apiFilters = { ...filters, status: status === 'open' || status === 'all' ? undefined : status };
-        const open = status === 'open';
-        if (query === undefined && state === undefined && !open) {
-          const result = await client.listBacklogItems(params.productId, apiFilters);
-          return toolResult(page(situatedRows(result.data as Record<string, unknown>[]), result.nextCursor));
-        }
-        if (params.cursor !== undefined) {
-          return toolError(
-            'VALIDATION_ERROR',
-            "Open items, a board column or a title search answer one page; narrow them, or pass status: 'all' " +
-              '(or one status) to page through every item.'
-          );
-        }
-        // A title search under the open default said nothing of the done and canceled ones it matched: a
-        // reviewer searched "secret detection", got [], and concluded the work never existed (PRO-2800). Counted
-        // in the same pass; exact when the pass read every page.
-        let closedSeen = 0;
-        const needle = (query ?? '').toLowerCase();
-        const found = await searchPages(
-          (cursor) => client.listBacklogItems(params.productId, { ...apiFilters, limit: SEARCH_PAGE_SIZE, cursor }),
-          query ?? '',
-          (row) => [row.title],
-          params.limit ?? 25,
-          (row) => {
-            if (state !== undefined && row.state !== state) return false;
-            if (!open || !['done', 'canceled'].includes(row.status)) return true;
-            if (query !== undefined && String(row.title).toLowerCase().includes(needle)) closedSeen += 1;
-            return false;
-          }
-        );
-        const hidden = query !== undefined && state === undefined && !found.more ? closedSeen : 0;
-        return toolResult({
-          ...page(situatedRows(found.rows), null),
-          ...(hidden > 0
-            ? {
-                closedMatches: `${hidden} done or canceled initiative${hidden === 1 ? ' also matches' : 's also match'}; status: 'all' lists them.`,
-              }
-            : {}),
-          ...(found.more
-            ? {
-                more:
-                  'There may be more than the limit carries: narrow it with state or query, or list one status ' +
-                  '(backlog, in_progress, done or canceled) without them, which pages.',
-              }
-            : {}),
-        });
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_initiative',
-    {
-      title: 'Get initiative',
-      description:
-        'Read one initiative in full: description, acceptance criteria (which are met), technical context, ' +
-        'dependencies and source documents. Read it before implementing. A failed plan carries planFailure ' +
-        `(cause, meaning, when, by whom). ${LIFECYCLE_MEANING}`,
-      inputSchema: z.object({
-        initiativeId,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const item = (await client.getBacklogItem(params.initiativeId)).data;
-        const row = item as unknown as Record<string, unknown>;
-        if (item.planningStatus !== 'failed') return toolResult(withSituation(row));
-        // Always undefined: the API sends the cause only under `lifecycle`, so
-        // planFailureOf's cross-check never fires (PRO-2799). Kept as it was.
-        const ownCause = (item as { planFailureCause?: unknown }).planFailureCause;
-        const planFailure = await planFailureOf(client, params.initiativeId, ownCause);
-        return toolResult(withSituation(row, planFailure ? { ...item, planFailure } : item));
-      })
-  );
-
-  server.registerTool(
-    'taiga_get_plan',
-    {
-      title: 'Get the active plan',
-      description:
-        "Read an initiative's active plan: its steps in order, each with title, layer, dependencies (the " +
-        'orderIndex of the steps it builds on), files written and read, and resources created. Enough to approve ' +
-        "or reject it (taiga_approve_plan, taiga_reject_plan); full: true adds each step's complete instructions " +
-        '(thousands of tokens). NOT_FOUND when there is no active plan yet; planningStatus says whether one is ' +
-        'being generated.',
-      inputSchema: z.object({
-        initiativeId,
-        full: z.boolean().optional().describe("Carry each step's complete instructions (default false: a summary)"),
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const plan = (await client.getActivePlan(params.initiativeId)).data;
-        if (params.full) return toolResult(plan);
-        const steps = Array.isArray(plan.steps) ? plan.steps : [];
-        return toolResult({
-          ...pickFields([plan], PLAN_SUMMARY_FIELDS)[0],
-          steps: pickFields(steps, PLAN_STEP_SUMMARY_FIELDS),
-        });
-      })
-  );
-}
-
-function registerRequest(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_request_initiatives',
-    {
-      title: 'Request new initiatives',
-      description:
-        "Ask an agent to turn described work into initiatives in the product's Backlog, and return the job. One " +
-        'piece of work becomes one initiative, a program an ordered set with dependencies. It may add none and ' +
-        'say why (already covered, not work, outside the product, or a named policy forbids it). Omit title and ' +
-        'description for the one next initiative the product most needs. taiga_wait_for_job gives the outcome. ' +
-        'One request per product at a time (CONFLICT). Nothing goes on the line.',
-      inputSchema: z.object({
-        productId,
-        title: z.string().max(500).optional().describe('What the work is, in a line'),
-        description: z
-          .string()
-          .max(20_000)
-          .optional()
-          .describe('The request in Markdown: the problem, what it should look like, what it covers and leaves alone'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const userPrompt = requestPrompt(params.title, params.description);
-        const job = (
-          await client.createAgentJob({
-            scope: 'product',
-            type: 'generate_backlog',
-            targetId: params.productId,
-            ...(userPrompt ? { metadata: { userPrompt } } : {}),
-          })
-        ).data;
-        return toolResult(jobReport(job));
-      })
-  );
-}
-
-function registerMove(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_move_initiative',
-    {
-      title: 'Move initiative on the board',
-      description:
-        'Move an initiative between columns, take it off the line, or reorder it. The line never takes from ' +
-        'backlog or todo; queue puts it on the line (taiga_queue_initiative), the only way to start work; done ' +
-        'and canceled finish it by hand. Nothing moves into Build by hand; moving out of Build stops and ' +
-        `discards the plan or run in flight. A move to ${PR_CLOSING_STATES.join(', ')} CLOSES a pull request the ` +
-        'initiative waits on (with a comment on it); queue keeps it open, and done leaves it to merge. Refused (CONFLICT) if not allowed; queue needs products:write. Ask first before ' +
-        'starting or stopping work or closing a pull request. archived: true archives it in place (pass its ' +
-        'current column as state; never from the Build station); false restores it.',
-      inputSchema: z.object({
-        initiativeId,
-        state: z.enum(USER_DROP_STATES).describe('The column to move into'),
-        afterId: idInput('initiative', 'taiga_list_initiatives gives it')
-          .nullable()
-          .optional()
-          .describe('The initiative to follow in that column; null for the head; omit to keep rank order'),
-        archived: z
-          .boolean()
-          .optional()
-          .describe('true files the initiative where it stands, false brings it back; omit to leave as is'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const { initiativeId: id, ...body } = params;
-        // What the route checks on top of backlog:write for a drop into the
-        // queue; refused here so the model learns which capability, not just
-        // that it was forbidden.
-        if (body.state === 'queue' && !client.hasCapability('products:write')) {
-          return toolError(
-            'FORBIDDEN',
-            'A move into queue starts agent work and needs products:write, which this key lacks.'
-          );
-        }
-        return outcome((await client.transitionInitiative(id, body)).data);
-      })
-  );
-}
-
-/** The two halves of the Build station, where Plan again is offered. */
-const BUILD_STATION: ReadonlySet<string> = new Set(['plan', 'build']);
-
-function registerPlanAgain(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_plan_again',
-    {
-      title: 'Plan an initiative again',
-      description:
-        'Replace the plan of the initiative at the Build station with a new one: for a failed plan, one you do ' +
-        'not want built, or a stopped run that went wrong. The old plan is kept; an open pull request stays ' +
-        'open. Refused (CONFLICT) while an agent holds the turn, and while a dependency is in flight or a UI ' +
-        'direction has no chosen concept unless force is set (the person decides). Off the Build station, use ' +
-        'taiga_queue_initiative; to send a plan back with direction, taiga_reject_plan.',
-      inputSchema: z.object({
-        initiativeId,
-        force: z
-          .boolean()
-          .optional()
-          .describe(
-            'Plan anyway past an unsettled dependency or an unchosen UI direction; only when the person says so'
-          ),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const item = (await client.getBacklogItem(params.initiativeId)).data;
-        if (!BUILD_STATION.has(String(item.state))) {
-          return toolError(
-            'CONFLICT',
-            `This initiative is in ${String(item.state)}, not at the Build station. The queue is the only way to ` +
-              'start work: put it in the queue with taiga_queue_initiative and it is planned when its turn comes.'
-          );
-        }
-        const body = { state: 'plan', ...(params.force ? { force: true } : {}) };
-        return outcome((await client.transitionInitiative(params.initiativeId, body)).data);
-      })
-  );
-}
-
-/** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
-const isApiFailure = (error: unknown) => error instanceof TaigaApiError || isNetworkFailure(error);
-
-/**
- * Whether this initiative's plan builds the moment it lands, and which scope
- * decided it: its own setting, or the product's default when it has none.
- * Null when the product cannot be read; the outcome then says so instead.
- */
-async function reviewGate(client: TaigaClient, item: Item) {
-  const own = typeof item.autoBuild === 'boolean' ? item.autoBuild : null;
-  try {
-    // The product's default answers only when the initiative has no answer of its own.
-    const product: { autoBuild?: boolean | null } = own === null ? (await client.getProduct(item.productId)).data : {};
-    // Absent on the product reads as its true default (@taiga/types).
-    const productDefault = typeof product.autoBuild === 'boolean' ? product.autoBuild : true;
-    const builds = resolveAutoBuild({ initiative: own, product: productDefault });
-    return {
-      buildsWithoutReview: builds,
-      decidedBy: own === null ? 'product' : 'initiative',
-      meaning: builds
-        ? 'The plan is built as soon as it lands; nobody reads it first.'
-        : 'The line stops at the plan for a person to approve or reject it (taiga_get_plan, taiga_approve_plan).',
-    };
-  } catch (error) {
-    if (!isApiFailure(error)) throw error;
-    return null;
-  }
-}
-
-/** Where a queued initiative stands in its product's line; null, and the outcome says so, when the queue cannot be read. */
-async function placeInQueue(client: TaigaClient, item: Item) {
-  try {
-    const view = await queueView(client, item.productId, { name: 'blocking' });
-    const entry = view.entries.find((row) => row.backlogItemId === item.id);
-    return { position: entry?.position ?? null, of: view.entries.length, waitingOn: view.waitingOn };
-  } catch (error) {
-    if (!isApiFailure(error)) throw error;
-    return null;
-  }
-}
-
-const autoBuildInput = z
-  .boolean()
-  .nullable()
-  .describe(
-    "false stops the line at this initiative's plan for a person to read it; true builds it as soon as it lands; " +
-      "null follows the product's default"
-  );
-
-function registerQueue(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_queue_initiative',
-    {
-      title: 'Queue initiative',
-      description:
-        "Put an initiative on the product's line, where initiatives are planned and built one at a time, each " +
-        'advancing when the previous pull request merges. Starts a planner run, then a coding run that pushes ' +
-        'commits and opens a pull request. autoBuild: false makes the plan wait for a person before it is built ' +
-        '(otherwise the product default; the result says which); the gate is set first and stays set if the move ' +
-        'is refused. An initiative already queued stays put unless afterId says where; one being planned or ' +
-        'built cannot move (CONFLICT). Returns the initiative with its state, review gate and place on the line.',
-      inputSchema: z.object({
-        initiativeId,
-        afterId: idInput('initiative', 'taiga_list_initiatives gives it')
-          .nullable()
-          .optional()
-          .describe(
-            'The queued initiative to follow; null for the head of the queue; omit to append a new entry or leave a queued one where it is'
-          ),
-        autoBuild: autoBuildInput
-          .optional()
-          .describe(
-            "Set the initiative's review gate before queueing: false to read the plan first, true to build it at " +
-              'once, null to follow the product; omit to leave the gate as it is'
-          ),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        const { initiativeId: id, autoBuild, ...placement } = params;
-        // The gate first: set after the move, a plan landing in between
-        // would be built under the old answer.
-        if (autoBuild !== undefined) await client.setAutoBuild(id, autoBuild);
-        // The move the web makes: one write that answers with the refreshed
-        // item, rather than the queue route plus two reads around it.
-        const item = (await client.transitionInitiative(id, { state: 'queue', ...placement })).data;
-        const [gate, queue] = await Promise.all([reviewGate(client, item), placeInQueue(client, item)]);
-        return toolResult({
-          ...outcomeOf(item),
-          reviewGate: gate,
-          queue,
-          ...(gate && queue
-            ? {}
-            : { note: 'Part of the outcome could not be read; taiga_get_line and taiga_get_product say the rest.' }),
-        });
-      })
-  );
-}
-
-function registerReviewGate(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_set_auto_build',
-    {
-      title: "Set an initiative's review gate",
-      description:
-        "Set an initiative's review gate: true builds each plan as soon as it lands, false makes it wait for a " +
-        'person to approve or reject it, null follows the product default. Applies to every plan the initiative ' +
-        'gets, including one being written now; opening the gate on a plan already waiting starts its run at ' +
-        'once. Returns the initiative with the gate now in force.',
-      inputSchema: z.object({ initiativeId, autoBuild: autoBuildInput }),
-      annotations: OPERATE_SETTING,
-    },
-    (params) =>
-      runTool(async () => {
-        const item = (await client.setAutoBuild(params.initiativeId, params.autoBuild)).data;
-        const gate = await reviewGate(client, item);
-        return toolResult({
-          ...outcomeOf(item),
-          reviewGate: gate,
-          ...(gate ? {} : { note: "The product's default could not be read; taiga_get_product says it." }),
-        });
-      })
-  );
-}
-
-function registerResume(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_resume_initiative',
-    {
-      title: 'Resume initiative',
-      description:
-        'Carry on an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is ' +
-        'planned again, a stopped or failed run resumes from its first unfinished step (committed steps are ' +
-        'kept), a refused run start is cleared and retried. Refused (CONFLICT) when nothing is flagged or the ' +
-        'cause has no resume; a failed plan with needsHumanCause null (lifecycle.cta retry_plan, ' +
-        'planFailureCause says why) needs taiga_plan_again.',
-      inputSchema: z.object({ initiativeId }),
-      annotations: OPERATE,
-    },
-    (params) => runTool(async () => outcome((await client.resumeInitiative(params.initiativeId)).data))
-  );
-}
-
-function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
-  server.registerTool(
-    'taiga_approve_plan',
-    {
-      title: 'Approve a plan',
-      description:
-        "Approve an initiative's plan and start its run, as the Start run button does. Read the plan first with " +
-        'taiga_get_plan and pass its ID. Refused (CONFLICT) if the plan was replaced since, while a new plan is ' +
-        'being generated, or while a run is already going. The run pushes commits and opens a pull request.',
-      inputSchema: z.object({ planId }),
-      annotations: OPERATE,
-    },
-    (params) => runTool(async () => outcome((await client.approvePlan(params.planId)).data))
-  );
-
-  server.registerTool(
-    'taiga_reject_plan',
-    {
-      title: 'Reject a plan',
-      description:
-        "Send an initiative's plan back with a comment: the planner writes a new plan from it, with the comment " +
-        'as reviewer feedback, and the new plan replaces this one when it lands. Read the plan first with ' +
-        'taiga_get_plan and pass its ID. Starts a planner run.',
-      inputSchema: z.object({
-        planId,
-        comment: z
-          .string()
-          .trim()
-          .min(1)
-          .max(PLAN_REJECTION_COMMENT_MAX_CHARS)
-          .describe('What the next plan should do differently: a paragraph of direction'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) => runTool(async () => outcome((await client.rejectPlan(params.planId, { comment: params.comment })).data))
-  );
-}