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

package/src/tools/context.ts

@@ -1,21 +1,36 @@
 import type { McpServer, CallToolResult } from '@modelcontextprotocol/server';
 import { isSettledOrArchived } from '@taiga/types';
+import type { BacklogItem, Product } from '@taiga/types';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
-import { BACKLOG_SUMMARY_FIELDS } from './backlogs.js';
+import { situatedRows } from './backlogs.js';
+import { POLICY_TYPES, defaultOriginFor, isImportedProduct } from './catalogue.js';
 import {
-  POLICY_TYPES,
-  defaultOriginFor,
-  isImportedProduct,
-  setupNextStep,
-  type ProductSettingsView,
-} from './catalogue.js';
-import { apiFailureText, isNetworkFailure, networkFailureDetail, runTool, toolError, toolResult } from './errors.js';
+  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 { budgetSections, instructionsText, isRecord, sectionContent, sectionsOf, stripProvenance } from './sections.js';
-import { itemRows, pickFields } from './summarize.js';
+import {
+  budgetSections,
+  instructionsText,
+  isRecord,
+  sectionContent,
+  sectionsOf,
+  stripProvenance,
+  type DocumentData,
+  type StoredDocument,
+} from './sections.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
@@ -39,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',
@@ -52,6 +67,8 @@ const CONTEXT_BUILD_FIELDS = [
   'failedReason',
   'completedSteps',
   'totalSteps',
+  'baseBranch',
+  'prNumber',
   'prUrl',
   'prState',
   'prMerged',
@@ -72,7 +89,7 @@ export const DOCUMENT_BUDGET = 12_000;
  * which a session's opening read does not need. The full read keeps them.
  * Says whether any were dropped, so the bundle can tell the reader.
  */
-function withoutCitations(doc: Record<string, unknown>): { doc: Record<string, unknown>; dropped: boolean } {
+function withoutCitations(doc: StoredDocument): { doc: StoredDocument; dropped: boolean } {
   const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
   if (!sections) return { doc, dropped: false };
   let dropped = false;
@@ -84,7 +101,7 @@ function withoutCitations(doc: Record<string, unknown>): { doc: Record<string, u
       return [id, rest];
     })
   );
-  return { doc: { ...doc, data: { ...(doc.data as Record<string, unknown>), sections: kept } }, dropped };
+  return { doc: { ...doc, data: { ...(doc.data as DocumentData), sections: kept } }, dropped };
 }
 
 /**
@@ -101,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;
@@ -113,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;
 
@@ -133,7 +153,7 @@ function isNotFound(reason: unknown): boolean {
 
 /** The factory's standing guidance in full; null, with a note, when none is published or it is not section-shaped. */
 async function factoryPart(client: TaigaClient, factoryId: string) {
-  const factory = (await client.getFactory(factoryId)).data as Record<string, unknown>;
+  const factory = (await client.getFactory(factoryId)).data;
   const base = { id: factory.id, name: factory.name, slug: factory.slug };
   try {
     const doc = (await client.getFactoryDocument(factoryId, 'factory_instructions')).data;
@@ -165,9 +185,9 @@ async function factoryPart(client: TaigaClient, factoryId: string) {
  * outline by default, the whole sections up to a budget or in full when
  * asked. Null, with a note, where unpublished.
  */
-async function documentsPart(client: TaigaClient, product: Record<string, unknown>, depth: DocumentDepth) {
-  const productId = String(product.id);
-  const origin = defaultOriginFor(product as ProductSettingsView);
+async function documentsPart(client: TaigaClient, product: WithoutTenant<Product>, depth: DocumentDepth) {
+  const productId = product.id;
+  const origin = defaultOriginFor(product);
   const reads = await Promise.allSettled(
     CONTEXT_DOCUMENT_TYPES.map((type) => client.getProductDocument(productId, type, origin))
   );
@@ -176,7 +196,7 @@ async function documentsPart(client: TaigaClient, product: Record<string, unknow
   CONTEXT_DOCUMENT_TYPES.forEach((type, index) => {
     const read = reads[index]!;
     if (read.status === 'fulfilled') {
-      const doc = stripProvenance(read.value.data as Record<string, unknown>);
+      const doc = stripProvenance(read.value.data);
       if (depth === 'full') out[type] = doc;
       else if (depth === 'budget') {
         const lean = withoutCitations(doc);
@@ -200,7 +220,7 @@ async function documentsPart(client: TaigaClient, product: Record<string, unknow
           );
         } else out[type] = cut.doc;
       } else {
-        const sections = sectionsOf((doc.data as Record<string, unknown>) ?? {});
+        const sections = sectionsOf(doc.data ?? {});
         if (sections) {
           // Each id with the length of its text, so the next read is sized before it is
           // made (a reality section's citations come on top).
@@ -224,14 +244,14 @@ async function documentsPart(client: TaigaClient, product: Record<string, unknow
 
 /** Every published policy as its section ids, so the model knows which one to read with taiga_get_document. */
 async function policiesPart(client: TaigaClient) {
-  const rows = (await client.listTenantDocuments({ limit: 100 })).data as Record<string, unknown>[];
+  const rows = (await client.listTenantDocuments({ limit: 100 })).data;
   return rows
     .filter((row) => (POLICY_TYPES as readonly string[]).includes(String(row.type)) && row.isDraft === false)
     .map((row) => ({
       type: row.type,
       name: row.name,
       version: row.version,
-      sections: Object.keys(sectionsOf((row.data as Record<string, unknown>) ?? {}) ?? {}),
+      sections: Object.keys(sectionsOf(row.data ?? {}) ?? {}),
     }));
 }
 
@@ -249,7 +269,7 @@ const OPEN_BACKLOG_STATUSES = ['backlog', 'in_progress'] as const;
 async function backlogPart(client: TaigaClient, productId: string) {
   // Keyed by id: an item that moves from backlog to in_progress between the
   // two reads would otherwise appear twice.
-  const open = new Map<string, Record<string, unknown>>();
+  const open = new Map<string, WithoutTenant<BacklogItem>>();
   let truncated = false;
   let pageCapped = false;
   for (const status of OPEN_BACKLOG_STATUSES) {
@@ -261,10 +281,8 @@ async function backlogPart(client: TaigaClient, productId: string) {
         break;
       }
       const result = await client.listBacklogItems(productId, { status, limit: 100, cursor });
-      for (const row of result.data as Record<string, unknown>[]) {
-        if (
-          !isSettledOrArchived({ status: String(row.status), archivedAt: (row.archivedAt as string | null) ?? null })
-        ) {
+      for (const row of result.data) {
+        if (!isSettledOrArchived({ status: String(row.status), archivedAt: row.archivedAt ?? null })) {
           open.set(String(row.id), row);
         }
       }
@@ -279,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
@@ -288,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.',
         }
       : {}),
   };
@@ -301,22 +319,67 @@ async function backlogPart(client: TaigaClient, productId: string) {
 async function repositoriesPart(client: TaigaClient, productId: string) {
   const result = await client.listProductRepositories(productId);
   return {
-    items: pickFields(result.data as Record<string, unknown>[], REPOSITORY_SUMMARY_FIELDS),
+    items: pickFields(result.data, REPOSITORY_SUMMARY_FIELDS),
     truncated: result.nextCursor !== null,
   };
 }
 
 async function buildsPart(client: TaigaClient, productId: string) {
   const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data as Record<string, unknown>[];
-  return pickFields(rows, CONTEXT_BUILD_FIELDS);
+  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(
   client: TaigaClient,
-  product: Record<string, unknown>,
+  product: WithoutTenant<Product>,
   options: { documents: DocumentDepth }
 ): Promise<CallToolResult> {
-  const productId = String(product.id);
+  const productId = product.id;
   const granted = (part: Part) => client.hasCapability(PARTS[part]);
   const notGranted = (Object.keys(PARTS) as Part[]).filter((part) => !granted(part));
 
@@ -327,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 as ProductSettingsView) ? 'brownfield' : 'greenfield',
-      defaultOrigin: defaultOriginFor(product as ProductSettingsView),
-      // A product in setup says what it waits for: nothing else in the bundle does.
-      ...(nextStep ? { nextStep } : {}),
+      projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
+      defaultOrigin: defaultOriginFor(product),
+      // A product in setup says what it still needs: nothing else in the bundle does.
+      ...(readiness ? { readiness } : {}),
     },
   };
   const unavailable: Record<string, string> = {};
@@ -355,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 });
 }
@@ -376,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

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/server';
+import type { FactoryDocument, TenantDocument } from '@taiga/types';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
+import { TaigaApiError, type TaigaClient, type TaigaDocument, type WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { idInput, pagination } from './inputs.js';
 import {
@@ -27,7 +28,10 @@ import { page, pickFields } from './summarize.js';
  */
 const DOCUMENT_SUMMARY_FIELDS = ['type', 'name', 'description', 'version', 'isDraft', 'hasDraft', 'updatedAt'] as const;
 
-const summaries = (rows: unknown[]) => pickFields(rows as Record<string, unknown>[], DOCUMENT_SUMMARY_FIELDS);
+/** A row of the company or factory document list; product documents list through their own tools. */
+type ListedDocument = WithoutTenant<TenantDocument | FactoryDocument>;
+
+const summaries = (rows: ListedDocument[]) => pickFields(rows, DOCUMENT_SUMMARY_FIELDS);
 
 /** What a lookup behind a miss said when it failed, so an unknown stays unknown. */
 function failedLookup(what: string, reason: unknown): string {
@@ -36,10 +40,10 @@ function failedLookup(what: string, reason: unknown): string {
 }
 
 /** `a (v3), b (v1)` for a not-found message. */
-function publishedList(rows: unknown[]): string {
+function publishedList(rows: ListedDocument[]): string {
   // The list routes return the latest draft rows beside the published ones,
   // and a draft named as published sends the model into a second miss.
-  return (rows as { type: string; version: unknown; isDraft: boolean }[])
+  return rows
     .filter((row) => row.isDraft === false)
     .map((row) => `${row.type} (v${String(row.version)})`)
     .join(', ');
@@ -180,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,
   };
 }

package/src/tools/hints.ts

@@ -2,14 +2,16 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
  * The next step after the API answers 404. The API's own word is bare
- * ("Backlog item not found", "Repository link not found"), and an agent that
+ * ("Initiative not found", "Repository link not found"), and an agent that
  * hears only that guesses another ID, or a name. Each ID a tool takes names
  * the tool that lists the right ones; the tool's arguments say which apply.
  */
+const ITEM_ID_HINT =
+  "taiga_list_initiatives lists a product's initiatives with their IDs; a run or plan ID is not one.";
+
 const BY_ARGUMENT: Record<string, string> = {
-  itemId: "taiga_list_backlog_items lists a product's initiatives with their IDs; a run or plan ID is not one.",
-  backlogItemId: "taiga_list_backlog_items lists a product's initiatives with their IDs.",
-  buildId: 'taiga_list_builds lists the runs, of one product or of every product the key can see.',
+  initiativeId: ITEM_ID_HINT,
+  runId: 'taiga_list_runs lists the runs, of one product or of every product the key can see.',
   planId: "taiga_get_plan gives the initiative's active plan and its ID.",
   repositoryId:
     "taiga_list_product_repositories lists the product's repository links; a GitHub repository id is not a link ID.",
@@ -38,12 +40,35 @@ const BY_TOOL: Record<string, Hint> = {
   // paid planning to fix a typo.
   taiga_get_plan: (said) =>
     /\bplan\b/i.test(said)
-      ? 'taiga_get_backlog_item says whether one is being generated (planningStatus planning) or failed, and ' +
+      ? 'taiga_get_initiative says whether one is being generated (planningStatus planning) or failed, and ' +
         'taiga_plan_again asks for a new one.'
-      : BY_ARGUMENT.itemId,
+      : ITEM_ID_HINT,
+};
+
+/**
+ * What the API calls the thing each ID names, as its 404 says it ("Environment
+ * not found"). A tool given a right product and a wrong environment hinted
+ * at both, and the product's hint told the agent its correct product ID was
+ * the mistake (PRO-2800): a 404 that names its thing gets that ID's hint only.
+ */
+const MISSING_THING: Record<string, RegExp> = {
+  initiativeId: /backlog item|initiative/i,
+  runId: /\b(build )?run\b/i,
+  planId: /\bplan\b/i,
+  repositoryId: /repository link|\blink\b/i,
+  replacesRepositoryId: /repository link|\blink\b/i,
+  githubRepositoryId: /github repository/i,
+  installationId: /installation|account/i,
+  jobId: /\bjob\b/i,
+  factoryId: /factory|team/i,
+  findingId: /finding/i,
+  violationId: /violation/i,
+  environmentId: /environment/i,
+  knowledgeId: /knowledge|document/i,
+  productId: /\b(product|project) not found/i,
 };
 
-/** The hint for a 404 from one tool call: the tool's own, else one per ID it was given. */
+/** The hint for a 404 from one tool call: the tool's own, else the one for the ID the API says is missing. */
 export function notFoundHint(tool: string, args: unknown): Hint | undefined {
   if (BY_TOOL[tool]) return BY_TOOL[tool];
   if (typeof args !== 'object' || args === null) return undefined;
@@ -52,8 +77,11 @@ export function notFoundHint(tool: string, args: unknown): Hint | undefined {
   // found", which already says which ID it was; the others are named first.
   given.sort((a, b) => Number(a === 'productId') - Number(b === 'productId'));
   if (given.length === 0) return undefined;
-  const hint = given.map((key) => BY_ARGUMENT[key]).join(' ');
-  return () => hint;
+  return (said) => {
+    const named = given.filter((key) => MISSING_THING[key]?.test(said));
+    // A 404 that names none of them (or a bare one) still gets them all.
+    return (named.length > 0 ? named : given).map((key) => BY_ARGUMENT[key]).join(' ');
+  };
 }
 
 /** The hint of the tool call in progress, read by runTool when the API answers 404. */