@taiga-ai/mcp-server 0.18.0-dev.450 → 0.19.0-dev.451

package/src/tools/builds.ts

@@ -1,6 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { BuildRunStep, BuildRunWithContext } from '@taiga/types';
+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';
@@ -44,7 +50,9 @@ const RUN_OUTCOME_FIELDS = [
   'failedReason',
   'completedSteps',
   'totalSteps',
+  'prNumber',
   'prUrl',
+  'prMerged',
   'actions',
 ] as const;
 
@@ -81,10 +89,80 @@ export function stoppedIn(
   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',
+};
+
+/**
+ * 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)`
+      : '';
+  const reason = typeof run['failedReason'] === 'string' && run['failedReason'] ? `: ${run['failedReason']}` : '';
+  const sentence: Record<string, string> = {
+    in_flight: status === 'pending' ? 'Queued: waiting to start.' : `Running: ${RUNNING[status] ?? status}${progress}.`,
+    gated: `Waiting for a person to review and merge ${pr}.`,
+    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${reason}${progress}.`,
+    stopped: `Stopped before it finished${progress}.`,
+    rejected: `${pr} was closed without merging, so the work did not land.`,
+  };
+  return { disposition, outcome: sentence[disposition] ?? status };
+}
+
+/**
+ * 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).
+ */
+export function readableRun(run: Record<string, unknown>): Record<string, unknown> {
+  const { prDraft, ...rest } = run;
+  const said = runOutcome(run);
+  return {
+    ...rest,
+    // A PR number proves a PR exists (isSettledWithoutPr); the URL is nullable apart from it.
+    ...(typeof rest['prNumber'] === 'number' || rest['prUrl'] ? { prDraft } : {}),
+    ...(said ?? {}),
+  };
+}
+
 /** How many products the org-wide list names; past this a row keeps its productId only. */
 const NAMED_PRODUCTS = 100;
 
-const buildId = idInput('build run', 'taiga_list_builds gives it');
+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 = [
@@ -139,10 +217,12 @@ async function activityRows(
   for (const product of products?.data ?? []) {
     nameById.set(product.id, { name: product.name, slug: product.slug });
   }
-  const rows = pickFields(runs.data, BUILD_SUMMARY_FIELDS).map((row) => {
-    const product = nameById.get(String(row.productId));
-    return product ? { ...row, product } : row;
-  });
+  const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS)
+    .map(readableRun)
+    .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
@@ -161,24 +241,23 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
   server.registerTool(
-    'taiga_list_builds',
+    'taiga_list_runs',
     {
-      title: 'List build runs',
+      title: 'List runs',
       description:
-        "List the coding agent's runs, newest first: status, branch, pull request, step progress and the " +
-        'actions a person may take on each. A run is the record of an attempt: work is carried on from its ' +
-        'initiative (resume and retry_from_failed_step are taiga_resume_backlog_item; start_over is in the web ' +
-        'only for now) and stopped by moving the initiative out of Build; a maintenance run, which has no ' +
-        'initiative, is retried from its finding. With productId, ' +
-        'the runs of that product, optionally of one backlog item; without it, the runs of every product the ' +
-        'key can see, each row naming its product, and active: true narrows to the runs executing right now. ' +
-        'Use this to see what Taiga already built or is building, then read one run with taiga_get_build. ' +
-        'A run of a deleted initiative keeps its title.',
+        "List the coding agent's runs, newest first. A run is one attempt at building an initiative: its branch, " +
+        'pull request and step progress. Each row says how it stands in one sentence (outcome) and as a ' +
+        'disposition: in_flight (the agent is working), gated (a person owes a review and merge), succeeded ' +
+        '(merged), failed, stopped, rejected (the pull request was closed without merging) or unmerged. actions ' +
+        'name what a person may do with it. With productId, the runs of that product, optionally of one ' +
+        'initiative; without it, the runs of every product the key can see, each row naming its product, and ' +
+        'active: true narrows to the runs executing now. taiga_get_run reads one with its steps. Work is carried ' +
+        'on from the initiative (taiga_resume_initiative), not the run.',
       inputSchema: z.object({
         productId: productId.optional(),
-        backlogItemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it')
+        initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it')
           .optional()
-          .describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
+          .describe("Only this initiative's runs -- get from taiga_list_initiatives; needs productId"),
         active: z
           .boolean()
           .optional()
@@ -192,10 +271,10 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        if (!params.productId && params.backlogItemId) {
+        if (!params.productId && params.initiativeId) {
           return toolError(
             'VALIDATION_ERROR',
-            'backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).'
+            '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
@@ -207,29 +286,38 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
           );
         }
         if (params.productId) {
-          const result = await client.listBuildRuns(params.productId, params);
-          return toolResult(page(pickFields(result.data, BUILD_SUMMARY_FIELDS), result.nextCursor));
+          const result = await client.listBuildRuns(params.productId, {
+            backlogItemId: params.initiativeId,
+            limit: params.limit,
+            cursor: params.cursor,
+          });
+          return toolResult(
+            page(
+              pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map(readableRun),
+              result.nextCursor
+            )
+          );
         }
         return toolResult(await activityRows(client, params));
       })
   );
 
   server.registerTool(
-    'taiga_get_build',
+    'taiga_get_run',
     {
-      title: 'Get build run',
+      title: 'Get run',
       description:
-        "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, " +
-        'status, commit, files changed, checks, any error and headline, the first paragraph of what the agent ' +
-        "reported. Pass full: true for each step's complete instructions and report, several thousand tokens on " +
-        'a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it ' +
-        'opened. A run that failed or was stopped says where (stoppedIn: a step, or the hardening pass after ' +
-        'them) and when it last made progress (lastProgressAt). Its actions name what the initiative accepts ' +
-        'for it: resume and retry_from_failed_step (which continues from the first unfinished part) are ' +
-        'taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of ' +
-        'Build. A maintenance run has no initiative and is retried from its finding.',
+        'Get one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and ' +
+        "each step's title, status, commit, files changed, verification and headline, the first paragraph of " +
+        "what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), " +
+        'independent of what the agent says it ran: a docs-only step can show tests failed because the ' +
+        "repository's tests fail. A run that failed or was stopped says where (stoppedIn) and when it last made " +
+        "progress (lastProgressAt). Pass full: true for each step's complete instructions and report, several " +
+        'thousand tokens on a long run. Its actions name what the initiative accepts: resume and ' +
+        'retry_from_failed_step are taiga_resume_initiative; start_over is in the web only; to stop it, move the ' +
+        'initiative out of Build. A maintenance run has no initiative and is retried from its finding.',
       inputSchema: z.object({
-        buildId,
+        runId,
         full: z
           .boolean()
           .optional()
@@ -242,16 +330,16 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         // 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.buildId),
-          client.listBuildRunSteps(params.buildId),
+          client.getBuildRun(params.runId),
+          client.listBuildRunSteps(params.runId),
         ]);
         const runRow = run.data;
         const rows = steps.data;
         const where = stoppedIn(runRow, rows);
         const stop = where ? { stoppedIn: where } : {};
-        if (params.full) return toolResult({ ...runRow, ...stop, steps: steps.data });
+        if (params.full) return toolResult({ ...readableRun(runRow), ...stop, steps: steps.data });
         return toolResult({
-          ...runRow,
+          ...readableRun(runRow),
           ...stop,
           steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
             ...step,
@@ -264,23 +352,22 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:write')) return;
 
   server.registerTool(
-    'taiga_stop_build',
+    'taiga_stop_run',
     {
-      title: 'Stop a build run',
+      title: 'Stop a run',
       description:
         'The emergency brake: stop a run the coding agent is executing when its initiative cannot be moved. The ' +
-        'way to stop work is on the initiative: move it out of Build (taiga_move_backlog_item), which stops the ' +
+        'way to stop work is on the initiative: move it out of Build (taiga_move_initiative), which stops the ' +
         'plan or run in flight. Use this only for a run whose initiative does not offer that (it is finished, ' +
         'canceled or gone) yet the run is still going. The agent halts, its branch and any draft pull request ' +
-        'stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT. Ask the person ' +
-        'before calling this: it interrupts work in progress.',
-      inputSchema: z.object({ buildId }),
+        'stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT.',
+      inputSchema: z.object({ runId }),
       annotations: OPERATE,
     },
     (params) =>
       runTool(async () => {
-        const result = await client.stopBuildRun(params.buildId);
-        return toolResult(pickFields([result.data], RUN_OUTCOME_FIELDS)[0]);
+        const result = await client.stopBuildRun(params.runId);
+        return toolResult(readableRun(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]!));
       })
   );
 }

package/src/tools/catalogue.test.ts

@@ -10,7 +10,7 @@ import {
 } from '@taiga/types';
 import { TaigaClient } from '../client.js';
 import { registerAllTools, writeNotice } from './index.js';
-import { INSTRUCTIONS_HEAD, INSTRUCTIONS_HEAD_LIMIT, SERVER_INSTRUCTIONS } from './instructions.js';
+import { SERVER_INSTRUCTIONS, SERVER_INSTRUCTIONS_LIMIT } from './instructions.js';
 import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
 
 /**
@@ -108,7 +108,6 @@ describe('tool descriptions against the catalogue', () => {
 
     for (const type of POLICY_TYPES) {
       expect(list.description, type).toContain(type);
-      expect(SERVER_INSTRUCTIONS, type).toContain(type);
     }
     expect(typeEnum).toEqual([...TENANT_DOCUMENT_TYPES]);
   });
@@ -130,23 +129,30 @@ describe('tool descriptions against the catalogue', () => {
     expect(PRODUCT_DOCUMENT_NAMES.ui_direction).toBe('Look & Feel');
   });
 
-  it('explains both timelines and the section metadata in the server instructions', () => {
-    expect(SERVER_INSTRUCTIONS).toMatch(/plan: .*discovery/);
-    expect(SERVER_INSTRUCTIONS).toMatch(/reality: .*merged pull request/);
-    for (const term of ['`source`', '`priority: core`', 'overlay-<id>', 'cloud-preset:<providers>', 'brownfield']) {
-      expect(SERVER_INSTRUCTIONS).toContain(term);
-    }
-    // Nothing writes a `user` source: a hand edit keeps the source it had.
-    expect(SERVER_INSTRUCTIONS).not.toMatch(/user: edited/);
+  it('explains both timelines where a product document is read', async () => {
+    const tools = await allTools();
+    const origin = (
+      tools.find((t) => t.name === 'taiga_get_product_document')!.inputSchema.properties as Record<
+        string,
+        { description?: string }
+      >
+    )['origin']!.description;
+    expect(origin).toMatch(/plan: .*discovery/);
+    expect(origin).toMatch(/reality: .*merged pull request/);
   });
 
-  it('opens the instructions with where to start and when to ask, inside what a client shows before it cuts', () => {
-    // Claude Code shows about the first 2,000 characters; the review that
-    // found the cut read only the document taxonomy (PRO-2759).
-    expect(SERVER_INSTRUCTIONS.startsWith(INSTRUCTIONS_HEAD)).toBe(true);
-    expect(INSTRUCTIONS_HEAD.length).toBeLessThanOrEqual(INSTRUCTIONS_HEAD_LIMIT);
-    for (const must of ['taiga_get_product_context', 'Before you write', 'NOT_FOUND', 'initiative']) {
-      expect(INSTRUCTIONS_HEAD).toContain(must);
+  it('fits the whole instructions inside what Claude Code keeps, and says where to start and when to ask', () => {
+    // Claude Code loads only tool names and the instructions until the model
+    // searches, and cuts the instructions at 2,048 characters (PRO-2800).
+    expect(SERVER_INSTRUCTIONS.length).toBeLessThanOrEqual(SERVER_INSTRUCTIONS_LIMIT);
+    for (const must of [
+      'taiga_get_product_context',
+      'Before you write',
+      'NOT_FOUND',
+      'initiative',
+      'Only in the web',
+    ]) {
+      expect(SERVER_INSTRUCTIONS).toContain(must);
     }
   });
 });

package/src/tools/context.ts

@@ -4,9 +4,17 @@ import type { BacklogItem, Product } from '@taiga/types';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
-import { BACKLOG_SUMMARY_FIELDS } from './backlogs.js';
-import { POLICY_TYPES, defaultOriginFor, isImportedProduct, setupNextStep } from './catalogue.js';
-import { apiFailureText, isNetworkFailure, networkFailureDetail, runTool, toolError, toolResult } from './errors.js';
+import { situatedRows } from './backlogs.js';
+import { POLICY_TYPES, defaultOriginFor, isImportedProduct } from './catalogue.js';
+import {
+  apiFailureText,
+  inProductWords,
+  isNetworkFailure,
+  networkFailureDetail,
+  runTool,
+  toolError,
+  toolResult,
+} from './errors.js';
 import { productId, remoteUrl, slug } from './inputs.js';
 import { PRODUCT_SUMMARY_FIELDS, resolveProductRef } from './products.js';
 import {
@@ -19,7 +27,10 @@ import {
   type DocumentData,
   type StoredDocument,
 } from './sections.js';
-import { itemRows, pickFields } from './summarize.js';
+import { pickFields } from './summarize.js';
+import { readableRun } from './builds.js';
+import { setupReadiness } from './readiness.js';
+import { standingSummary } from './maintenance.js';
 
 /**
  * One call at the start of a coding session: everything the model would
@@ -43,10 +54,10 @@ const REPOSITORY_SUMMARY_FIELDS = [
   'isManaged',
 ] as const;
 
-/** How many of the latest runs to carry; taiga_list_builds pages the rest. */
+/** How many of the latest runs to carry; taiga_list_runs pages the rest. */
 const BUILDS_IN_CONTEXT = 10;
 
-/** A run as the bundle carries it: enough to say what was built and where; taiga_get_build has the rest. */
+/** A run as the bundle carries it: enough to say what was built and where; taiga_get_run has the rest. */
 const CONTEXT_BUILD_FIELDS = [
   'id',
   'runNumber',
@@ -56,6 +67,8 @@ const CONTEXT_BUILD_FIELDS = [
   'failedReason',
   'completedSteps',
   'totalSteps',
+  'baseBranch',
+  'prNumber',
   'prUrl',
   'prState',
   'prMerged',
@@ -105,7 +118,7 @@ const BACKLOG_PAGE_LIMIT = 10;
 
 /**
  * Open items the bundle carries, the newest of those read; past this it says truncated and
- * taiga_list_backlog_items pages the rest. Keeps a product with hundreds of
+ * taiga_list_initiatives pages the rest. Keeps a product with hundreds of
  * open initiatives inside the tool result the document budget is sized for.
  */
 const BACKLOG_IN_CONTEXT = 50;
@@ -117,6 +130,9 @@ const PARTS = {
   backlog: 'backlog:read',
   repositories: 'products:read',
   builds: 'products:read',
+  attention: 'products:read',
+  maintenance: 'products:read',
+  standing: 'products:read',
 } as const;
 type Part = keyof typeof PARTS;
 
@@ -281,7 +297,7 @@ async function backlogPart(client: TaigaClient, productId: string) {
   );
   if (rows.length > BACKLOG_IN_CONTEXT) truncated = true;
   return {
-    items: itemRows(rows.slice(-BACKLOG_IN_CONTEXT), BACKLOG_SUMMARY_FIELDS),
+    items: situatedRows(rows.slice(-BACKLOG_IN_CONTEXT)),
     truncated,
     // The list pages oldest first and takes no order, so a status past the
     // page cap was read only up to its oldest items: these are the newest of
@@ -290,7 +306,7 @@ async function backlogPart(client: TaigaClient, productId: string) {
       ? {
           note:
             `More than ${BACKLOG_PAGE_LIMIT * 100} open items in one status: only the oldest of them were read, so ` +
-            'the newest may be missing here; taiga_list_backlog_items pages the rest.',
+            'the newest may be missing here; taiga_list_initiatives pages the rest.',
         }
       : {}),
   };
@@ -309,8 +325,53 @@ async function repositoriesPart(client: TaigaClient, productId: string) {
 }
 
 async function buildsPart(client: TaigaClient, productId: string) {
-  const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data;
-  return pickFields(rows, CONTEXT_BUILD_FIELDS);
+  const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data as Record<string, unknown>[];
+  return pickFields(rows, CONTEXT_BUILD_FIELDS).map(readableRun);
+}
+
+/**
+ * What waits on a person for this product, counted by kind (PRO-2800): the
+ * reviewing agent called four tools to answer "how does it stand"; the
+ * counts say whether taiga_list_action_required is worth a call.
+ */
+async function attentionPart(client: TaigaClient, productId: string) {
+  const result = await client.listInbox({ productId, limit: 100, withTotal: true });
+  const now = Date.now();
+  const rows = result.data as Record<string, unknown>[];
+  const byKind: Record<string, number> = {};
+  for (const row of rows) byKind[String(row['kind'])] = (byKind[String(row['kind'])] ?? 0) + 1;
+  // Snoozed items are open too, so they count; the number says how many of
+  // them the team has put off for now.
+  const snoozed = rows.filter(
+    (row) =>
+      row['status'] === 'snoozed' && typeof row['snoozedUntil'] === 'string' && Date.parse(row['snoozedUntil']) > now
+  ).length;
+  return {
+    open: typeof result.totalCount === 'number' ? result.totalCount : rows.length,
+    byKind,
+    ...(snoozed > 0 ? { snoozed } : {}),
+    ...(result.nextCursor
+      ? { note: 'byKind and snoozed count the first 100; taiga_list_action_required pages the rest.' }
+      : {}),
+  };
+}
+
+/** The latest sweep and what it left open, as counts; taiga_list_findings lists them. */
+async function maintenancePart(client: TaigaClient, productId: string) {
+  const summary = (await client.getMaintenanceSummary(productId)).data as Record<string, unknown>;
+  const last = summary['lastRun'] as Record<string, unknown> | null | undefined;
+  return {
+    openFindings: summary['openFindings'],
+    bySeverity: summary['severityCounts'],
+    lastSweep: last ? { status: last['status'], completedAt: last['completedAt'] } : null,
+    ...(last ? {} : { note: 'Never swept: no findings is not an all-clear.' }),
+  };
+}
+
+/** Where the product stands against the policies, as counts; taiga_get_policy_standing has each violation. */
+async function standingPart(client: TaigaClient, productId: string) {
+  const summary = standingSummary((await client.getPolicyStanding(productId)).data);
+  return { openViolations: summary.violations, bySeverity: summary.bySeverity, controlsViolated: summary.controls };
 }
 
 export async function productContext(
@@ -329,18 +390,23 @@ export async function productContext(
     backlog: () => backlogPart(client, productId),
     repositories: () => repositoriesPart(client, productId),
     builds: () => buildsPart(client, productId),
+    attention: () => attentionPart(client, productId),
+    maintenance: () => maintenancePart(client, productId),
+    standing: () => standingPart(client, productId),
   };
   const parts = (Object.keys(fetchers) as Part[]).filter(granted);
-  const settled = await Promise.allSettled(parts.map((part) => fetchers[part]()));
+  const [settled, readiness] = await Promise.all([
+    Promise.allSettled(parts.map((part) => fetchers[part]())),
+    setupReadiness(client, product),
+  ]);
 
-  const nextStep = setupNextStep(product);
   const bundle: Record<string, unknown> = {
     product: {
       ...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
       projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
       defaultOrigin: defaultOriginFor(product),
-      // A product in setup says what it waits for: nothing else in the bundle does.
-      ...(nextStep ? { nextStep } : {}),
+      // A product in setup says what it still needs: nothing else in the bundle does.
+      ...(readiness ? { readiness } : {}),
     },
   };
   const unavailable: Record<string, string> = {};
@@ -357,15 +423,16 @@ export async function productContext(
     readNext:
       'Read a policy with taiga_get_document (sections: the ids listed here, for only those), the ' +
       "specification's or architecture's sections or another product document with taiga_get_product_document, " +
-      'a backlog item with taiga_get_backlog_item (taiga_list_backlog_items pages a truncated backlog) and a run ' +
-      'with taiga_get_build.',
+      'an initiative with taiga_get_initiative (taiga_list_initiatives pages a truncated backlog) and a run ' +
+      'with taiga_get_run.',
   };
   // Its own size, so a model can judge what one more read would cost: counted
   // with the field in place, until the count no longer changes its own length.
-  let characters = JSON.stringify(result, null, 2).length;
+  // Measured as sent: toolResult renames keys into the product's words.
+  let characters = JSON.stringify(inProductWords(result), null, 2).length;
   for (let measured = -1; measured !== characters;) {
     measured = characters;
-    characters = JSON.stringify({ ...result, characters: measured }, null, 2).length;
+    characters = JSON.stringify(inProductWords({ ...result, characters: measured }), null, 2).length;
   }
   return toolResult({ ...result, characters });
 }
@@ -378,17 +445,18 @@ export function registerContextTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get product context',
       description:
-        'Everything a coding session starts from, in one call: the product and which document timeline is its ' +
-        'own, its factory with the instructions in full, the specification and architecture from that timeline, ' +
-        'every published policy as its section ids, the open backlog items, the linked repositories and the ' +
-        'latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused ' +
-        'or failed is named under unavailable with what it said; a part the key cannot read is named under ' +
-        'notGranted; neither is shown as empty. The two documents come as their outline by default: each ' +
-        'section id with its size, to read with taiga_get_product_document naming the sections. Before writing ' +
-        `code, documents: budget brings as many whole sections as fit, about ${DOCUMENT_BUDGET / 1000}k ` +
-        'characters each, naming the ones left out; full brings them whole, tens of thousands of tokens on a ' +
-        'large product and more than some clients accept. characters says how large the result is. Call this ' +
-        'first, then read what you need.',
+        'Where a product stands and everything a coding session starts from, in one call. Name the product by ' +
+        'ID, slug or the git remote URL of a checkout. It carries: the product (and, while in setup, readiness: ' +
+        'what it still needs and the next move); its factory with the instructions in full; the specification ' +
+        'and architecture as outlines (section ids and sizes); every published policy as its section ids; the ' +
+        'open initiatives (not the done or canceled ones: taiga_list_initiatives has those); the linked ' +
+        'repositories; the latest runs, each with its outcome in a sentence; attention, what waits on a person ' +
+        'for it, counted by kind; maintenance, open findings by severity and the last sweep; standing, open ' +
+        'policy violations by severity. A part the API refused or failed is named under unavailable; a part the ' +
+        'key cannot read under notGranted; neither is shown as empty. Before writing code, documents: budget ' +
+        `brings the whole sections that fit, about ${DOCUMENT_BUDGET / 1000}k characters each, and full brings ` +
+        'them whole (tens of thousands of tokens on a large product). Unlike taiga_get_product, which is the ' +
+        'product record and its settings alone. Call this first, then read what you need.',
       inputSchema: z.object({
         productId: productId.optional(),
         slug: slug.optional(),

package/src/tools/documents.ts

@@ -184,7 +184,10 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'ids taiga_get_product_context lists for every policy, or sections: [] for the outline) and the read ' +
           'carries only those, listing the rest with their sizes and any id the document lacks ' +
           '(unknownSections). A read that finds no document says which documents are published and whether a ' +
-          'draft exists.',
+          "draft exists. Each section's source says where its text came from (template: Taiga's standard text; " +
+          'overlay-<id>: a jurisdiction or industry overlay; cloud-preset:<providers>: rendered for the ' +
+          "organization's clouds) and priority: core marks the sections every organization keeps; neither changes " +
+          'what the section requires.',
         inputSchema: z.object({
           type: tenantDocumentType,
           sections: sectionsInput,

package/src/tools/errors.ts

@@ -2,9 +2,41 @@ import type { CallToolResult } from '@modelcontextprotocol/server';
 import { TaigaApiError } from '../client.js';
 import { withNotFoundHint } from './hints.js';
 
+/**
+ * The API's names for the two IDs an agent chains most, in the product's
+ * words the tools take them in (PRO-2800): a row says initiativeId and runId,
+ * as taiga_get_initiative and taiga_get_run ask for them, rather than the
+ * storage names backlogItemId and buildRunId.
+ */
+const PRODUCT_WORDS: Record<string, string> = { backlogItemId: 'initiativeId', buildRunId: 'runId' };
+
+/**
+ * Maps whose keys are content, not API fields: a document's sections are keyed
+ * by ids a person or agent chose (a section may be called backlogItemId), and
+ * metadata and settings hold whatever their writer put there. Copied as they
+ * are, keys and all.
+ */
+const OPAQUE_MAPS = new Set(['sections', 'metadata', 'settings']);
+
+/** A copy of an API value with its keys in the product's words, values untouched. */
+export function inProductWords(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(inProductWords);
+  if (value === null || typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, inner] of Object.entries(value)) {
+    Object.defineProperty(out, PRODUCT_WORDS[key] ?? key, {
+      value: OPAQUE_MAPS.has(key) ? inner : inProductWords(inner),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}
+
 /** A successful tool result: one JSON text block the model reads. */
 export function toolResult(value: unknown): CallToolResult {
-  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+  return { content: [{ type: 'text', text: JSON.stringify(inProductWords(value), null, 2) }] };
 }
 
 /**
@@ -14,7 +46,13 @@ export function toolResult(value: unknown): CallToolResult {
  */
 export function toolError(error: string, message: string, details?: Record<string, unknown>): CallToolResult {
   return {
-    content: [{ type: 'text', text: JSON.stringify(details ? { error, message, details } : { error, message }) }],
+    // Details in the product's words too: a conflict naming the run in its way says runId, as the inputs do.
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(details ? { error, message, details: inProductWords(details) } : { error, message }),
+      },
+    ],
     isError: true,
   };
 }