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

package/src/tools/documents.ts

@@ -1,375 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import type { FactoryDocument, TenantDocument } from '@taiga/types';
-import { z } from 'zod';
-import { TaigaApiError, type TaigaClient, type TaigaDocument, type WithoutTenant } from '../client.js';
-import { READ_ONLY } from './annotations.js';
-import { idInput, pagination } from './inputs.js';
-import {
-  FACTORY_DOCUMENT_TYPES,
-  OTHER_TENANT_DOCUMENT_TYPES,
-  POLICY_TYPES,
-  TENANT_DOCUMENT_TYPES,
-  named,
-} from './catalogue.js';
-import { runTool, toolError, toolResult } from './errors.js';
-import {
-  applySectionEdit,
-  sectionContent,
-  sectionReadResult,
-  policySectionsInput,
-  sectionsOf,
-  stripProvenance,
-} from './sections.js';
-import { page, pickFields } from './summarize.js';
-
-/**
- * What a document row needs to say for the model to pick one and read it in
- * full. Not the content, not who wrote it.
- */
-const DOCUMENT_SUMMARY_FIELDS = ['type', 'name', 'description', 'version', 'isDraft', 'hasDraft', 'updatedAt'] as const;
-
-/** 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 {
-  const said = reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ''}`.trim() : 'the request failed';
-  return `${what} could not be checked (${said}).`;
-}
-
-/** `a (v3), b (v1)` for a not-found message. */
-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
-    .filter((row) => row.isDraft === false)
-    .map((row) => `${row.type} (v${String(row.version)})`)
-    .join(', ');
-}
-
-const DRAFT_WRITE = {
-  readOnlyHint: false,
-  destructiveHint: false,
-  idempotentHint: true,
-  openWorldHint: false,
-} as const;
-// Publishing replaces the version every agent and person reads, and there is
-// no unpublish: destructive so a host that confirms destructive tools asks
-// first. Not idempotent: a second call publishes the same draft once more.
-const PUBLISH = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false } as const;
-
-/** A section id, described with the read tool of its own scope, which lists the valid ids. */
-export function sectionIdFrom(readTool: string) {
-  return z
-    .string()
-    .min(1)
-    .describe(
-      `Section id -- the keys of \`data.sections\` in ${readTool}, e.g. summary, scope, apiDesign. ` +
-        'An id that does not exist yet adds a section.'
-    );
-}
-export const sectionContentInput = z
-  .string()
-  .describe('The full new Markdown text of the section; it replaces the old text');
-const tenantDocumentType = z
-  .enum(TENANT_DOCUMENT_TYPES)
-  // The enum lists every type; the description only says which are policies.
-  .describe('Document type: the policy_* ones are policies');
-
-/**
- * The read, save and publish calls for one document scope. The tools are the
- * same for a company policy and for factory instructions; only the routes and
- * the capability gate differ.
- */
-export interface DocumentScope {
-  getDraft(): Promise<{ data: TaigaDocument | null }>;
-  getPublished(): Promise<{ data: TaigaDocument }>;
-  saveDraft(data: Record<string, unknown>): Promise<{ data: TaigaDocument }>;
-  publish(): Promise<{ data: TaigaDocument; warnings?: unknown }>;
-}
-
-/** Everything the model needs back from a write, without the content it already holds. */
-function documentSummary(doc: TaigaDocument) {
-  const { data, ...rest } = doc;
-  return { ...rest, sections: Object.keys(sectionsOf(data) ?? {}) };
-}
-
-/**
- * The document a section edit starts from: the draft when one exists, else
- * the published version, else (instructions documents start empty and
- * unpublished, PRO-502) an empty section map. The API seeds the draft the
- * same way on the first save, so the merge happens on what it would hold.
- */
-async function editBase(scope: DocumentScope): Promise<Record<string, unknown>> {
-  const draft = (await scope.getDraft()).data;
-  if (draft) return draft.data;
-  try {
-    return (await scope.getPublished()).data.data;
-  } catch (error) {
-    if (error instanceof TaigaApiError && error.status === 404) return { sections: {} };
-    throw error;
-  }
-}
-
-/**
- * Edit one section of a document's draft; the edit keeps every other section
- * and the section's own metadata, see sections.ts.
- */
-export async function updateSection(scope: DocumentScope, type: string, id: string, content: string) {
-  const base = await editBase(scope);
-  const sections = sectionsOf(base);
-  if (!sections) {
-    return toolError(
-      'UNSUPPORTED_DOCUMENT',
-      `Document ${type} is not made of sections and cannot be edited section by section. Edit it in the Taiga app.`
-    );
-  }
-  const saved = await scope.saveDraft({ ...base, sections: applySectionEdit(sections, id, content) });
-  return toolResult({
-    ...documentSummary(saved.data),
-    section: { id, content: sectionContent(sectionsOf(saved.data.data) ?? {}, id) },
-  });
-}
-
-/**
- * Publish the draft; the API answers 404 when there is none and 400 when the
- * residue gate refuses it. A publish can succeed with warnings about this
- * publish (a product document citing a policy control that does not exist),
- * which are kept: they are the only way the publisher hears of them.
- */
-export async function publishDraft(scope: DocumentScope) {
-  const published = await scope.publish();
-  return toolResult({
-    ...documentSummary(published.data),
-    ...(published.warnings ? { warnings: published.warnings } : {}),
-  });
-}
-
-export function registerDocumentTools(server: McpServer, client: TaigaClient) {
-  // ── Company-level policy documents ──────────────────────────────────
-
-  if (client.hasCapability('tenant:documents:read')) {
-    server.registerTool(
-      'taiga_get_document',
-      {
-        title: 'Get company document',
-        description:
-          "Read one of the organization's documents by type, or without type list them all (type, name, version, " +
-          `draft state). The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) set the rules for every ` +
-          `product; the others (${named(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and ` +
-          'instructions. Policies are long: pass ' +
-          'sections: [] for the outline, then the section ids you need, or a control id such as SEC-5.1; ' +
-          'unknownSections names ids it lacks. A miss says which documents are published and whether a draft ' +
-          "exists. A section's source (template, overlay-<id>, cloud-preset:<providers>) and priority (core: every " +
-          'organization keeps it) do not change what it requires.',
-        inputSchema: z.object({
-          type: tenantDocumentType.optional(),
-          sections: policySectionsInput,
-          ...pagination,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          // One tool for the list and the read (PRO-2800): the catalogue's weight is the cost every review ranks
-          // first, and a list tool beside each read was the read without a type.
-          if (params.type === undefined) {
-            if (params.sections) return toolError('VALIDATION_ERROR', 'Name the document (type) to read its sections.');
-            const result = await client.listTenantDocuments({ limit: params.limit, cursor: params.cursor });
-            return toolResult(page(summaries(result.data), result.nextCursor));
-          }
-          const type = params.type;
-          if (params.limit !== undefined || params.cursor !== undefined) {
-            return toolError(
-              'VALIDATION_ERROR',
-              'limit and cursor page the list; omit type to list, or drop them to read.'
-            );
-          }
-          try {
-            const result = await client.getTenantDocument(type);
-            const doc = stripProvenance(result.data);
-            return params.sections
-              ? sectionReadResult(doc, params.sections, type, {
-                  controlIds: (POLICY_TYPES as readonly string[]).includes(type),
-                })
-              : toolResult(doc);
-          } catch (error) {
-            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
-            // Best effort, each part on its own: a failed lookup must not turn
-            // a miss into an outage, nor blank the part that did answer.
-            const [draft, all] = await Promise.allSettled([
-              client.getTenantDocumentDraft(type),
-              client.listTenantDocuments({ limit: 100 }),
-            ]);
-            const parts = [`No published ${type}.`];
-            if (draft.status === 'fulfilled') {
-              parts.push(
-                draft.value.data
-                  ? 'A draft exists; taiga_publish_document publishes it once the person asks.'
-                  : 'There is no draft either.'
-              );
-            } else {
-              parts.push(failedLookup('The draft', draft.reason));
-            }
-            if (all.status === 'fulfilled') {
-              const published = publishedList(all.value.data);
-              parts.push(published ? `Published documents: ${published}.` : 'Nothing is published yet.');
-            } else {
-              parts.push(failedLookup('The published list', all.reason));
-            }
-            return toolError('NOT_FOUND', parts.join(' '));
-          }
-        })
-    );
-  }
-
-  // The edit reads the draft and the published version before it writes,
-  // and those routes need tenant:documents:read; a write-only scoped key
-  // would get a tool that 403s on every call.
-  if (client.hasCapability('tenant:documents:read') && client.hasCapability('tenant:documents:write')) {
-    const tenantScope = (type: string): DocumentScope => ({
-      getDraft: () => client.getTenantDocumentDraft(type),
-      getPublished: () => client.getTenantDocument(type),
-      saveDraft: (data) => client.saveTenantDocumentDraft(type, { data }),
-      publish: () => client.publishTenantDocument(type),
-    });
-
-    server.registerTool(
-      'taiga_update_document',
-      {
-        title: 'Update a section of a company document draft',
-        description:
-          "Replace one section's text in a company policy document's draft; other sections stay. Read the document " +
-          'with taiga_get_document first for its sections. Readers keep the published version until ' +
-          'taiga_publish_document. Use it when a policy is outdated or wrong.',
-        inputSchema: z.object({
-          type: tenantDocumentType,
-          sectionId: sectionIdFrom('taiga_get_document'),
-          content: sectionContentInput,
-        }),
-        annotations: DRAFT_WRITE,
-      },
-      (params) => runTool(() => updateSection(tenantScope(params.type), params.type, params.sectionId, params.content))
-    );
-
-    server.registerTool(
-      'taiga_publish_document',
-      {
-        title: 'Publish a company document draft',
-        description:
-          "Publish a company policy document's draft as its next version, which every agent and person reads from " +
-          'then on. Only when the person asked; save edits first with taiga_update_document. A refusal names what ' +
-          'to fix in the draft.',
-        inputSchema: z.object({
-          type: tenantDocumentType,
-        }),
-        annotations: PUBLISH,
-      },
-      (params) => runTool(() => publishDraft(tenantScope(params.type)))
-    );
-  }
-
-  // ── Factory instructions ────────────────────────────────────────────
-
-  if (client.hasCapability('factories:read')) {
-    server.registerTool(
-      'taiga_get_factory_document',
-      {
-        title: 'Get factory instructions',
-        description:
-          "Read a factory's instructions: the domain context, tech preferences and conventions its products " +
-          'follow. If nothing is published, it says whether a draft exists and how to write one.',
-        inputSchema: z.object({
-          factoryId: idInput('factory', 'taiga_list_factories (query finds one by name) gives it'),
-          type: z.enum(FACTORY_DOCUMENT_TYPES).default('factory_instructions').describe('Document type'),
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          try {
-            const result = await client.getFactoryDocument(params.factoryId, params.type);
-            return toolResult(stripProvenance(result.data));
-          } catch (error) {
-            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
-            // A factory that does not exist answers the same 404 as one with
-            // nothing published, and the draft route does not check the
-            // factory for a break-glass key: read the factory first, so its
-            // 404 propagates as the factory missing rather than as "nothing
-            // published yet".
-            await client.getFactory(params.factoryId);
-            // The draft route answers 200 with null for a visible factory
-            // with no draft, so its 404 is also the factory out of scope and
-            // propagates. Any other failure is named.
-            const detail = await client
-              .getFactoryDocumentDraft(params.factoryId, params.type)
-              .then((draft) =>
-                draft.data
-                  ? 'A draft exists; taiga_publish_factory_document publishes it once the person asks.'
-                  : 'There is no draft either: write one with taiga_update_factory_document, then publish it when the person asks.'
-              )
-              .catch((reason: unknown) => {
-                if (reason instanceof TaigaApiError && reason.status === 404) throw reason;
-                return failedLookup('The draft', reason);
-              });
-            return toolError('NOT_FOUND', `This factory has no published ${params.type} yet. ${detail}`);
-          }
-        })
-    );
-  }
-
-  // Writing factory instructions needs factories:read (to find the factory) and
-  // factories:documents:write, which is what the API routes require: members
-  // hold it for their own factories, and tenant:documents:write (company
-  // policies) does not stand in for it.
-  if (client.hasCapability('factories:read') && client.hasCapability('factories:documents:write')) {
-    const factoryScope = (factoryId: string, type: string): DocumentScope => ({
-      getDraft: () => client.getFactoryDocumentDraft(factoryId, type),
-      getPublished: () => client.getFactoryDocument(factoryId, type),
-      saveDraft: (data) => client.saveFactoryDocumentDraft(factoryId, type, { data }),
-      publish: () => client.publishFactoryDocument(factoryId, type),
-    });
-    const factoryId = idInput('factory', 'taiga_list_factories (query finds one by name) gives it');
-    const factoryDocumentType = z
-      .enum(FACTORY_DOCUMENT_TYPES)
-      .default('factory_instructions')
-      .describe('Document type');
-
-    server.registerTool(
-      'taiga_update_factory_document',
-      {
-        title: 'Update a section of factory instructions',
-        description:
-          "Replace the text of a factory's instructions draft (its one section, `instructions`). Read it first " +
-          'with taiga_get_factory_document. Products follow the published version until ' +
-          'taiga_publish_factory_document.',
-        inputSchema: z.object({
-          factoryId,
-          type: factoryDocumentType,
-          sectionId: sectionIdFrom('taiga_get_factory_document').default('instructions'),
-          content: sectionContentInput,
-        }),
-        annotations: DRAFT_WRITE,
-      },
-      (params) =>
-        runTool(() =>
-          updateSection(factoryScope(params.factoryId, params.type), params.type, params.sectionId, params.content)
-        )
-    );
-
-    server.registerTool(
-      'taiga_publish_factory_document',
-      {
-        title: 'Publish factory instructions draft',
-        description:
-          "Publish a factory's instructions draft as the next version every product in the factory follows. Only " +
-          'when the person asked; save edits first with taiga_update_factory_document.',
-        inputSchema: z.object({ factoryId, type: factoryDocumentType }),
-        annotations: PUBLISH,
-      },
-      (params) => runTool(() => publishDraft(factoryScope(params.factoryId, params.type)))
-    );
-  }
-}

package/src/tools/errors.ts

@@ -1,172 +0,0 @@
-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',
-  latestBuild: 'latestRun',
-};
-
-/**
- * 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. */
-/**
- * Run actions only the web offers (PRO-2800): start_over was listed beside what an agent can call, on runs and on
- * every initiative's latest run, while the descriptions said it was web only. Split apart wherever actions appear.
- */
-const WEB_ONLY_ACTIONS = new Set(['start_over']);
-
-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> = {};
-  const actions = (value as Record<string, unknown>)['actions'];
-  if (Array.isArray(actions) && actions.some((action) => WEB_ONLY_ACTIONS.has(String(action)))) {
-    const webOnly = actions.filter((action) => WEB_ONLY_ACTIONS.has(String(action)));
-    value = {
-      ...(value as Record<string, unknown>),
-      actions: actions.filter((action) => !WEB_ONLY_ACTIONS.has(String(action))),
-      webOnlyActions: webOnly,
-    };
-  }
-  for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
-    Object.defineProperty(out, PRODUCT_WORDS[key] ?? key, {
-      value: OPAQUE_MAPS.has(key) ? inner : inProductWords(inner),
-      enumerable: true,
-      writable: true,
-      configurable: true,
-    });
-  }
-  return out;
-}
-
-/** The API's 404 sentence in the product's words: "Backlog item not found" is an initiative not found. */
-export function inProductWording(said: string): string {
-  return (
-    said
-      .replace(/^Backlog item not found/i, 'Initiative not found')
-      .replace(/^Build run step not found/i, 'Run step not found')
-      .replace(/^Build run not found/i, 'Run not found')
-      .replace(/^Custom document not found/i, 'Knowledge file not found')
-      // A missing branch names the list of the ones that exist, as every other miss does.
-      .replace(
-        /^(Branch "[^"]*" does not exist in \S+?)\.?$/i,
-        '$1. taiga_list_repository_branches lists the branches it has.'
-      )
-      // The API's word for a second link names no way out; the tool has two.
-      .replace(
-        /^This product already has a repository\. Change it instead of linking another\./i,
-        'This product already has a repository. Pass replacesRepositoryId to swap it in one step, or ' +
-          'taiga_unlink_repository first (taiga_list_product_repositories gives its ID).'
-      )
-  );
-}
-
-/** A successful tool result: one JSON text block the model reads. */
-export function toolResult(value: unknown): CallToolResult {
-  return { content: [{ type: 'text', text: JSON.stringify(inProductWords(value), null, 2) }] };
-}
-
-/**
- * A failed tool result the model can branch on: a stable code and a message
- * that says what to do next. Returned, not thrown, so the client sees
- * `isError` rather than a protocol error.
- */
-export function toolError(error: string, message: string, details?: Record<string, unknown>): CallToolResult {
-  return {
-    // 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,
-  };
-}
-
-/**
- * fetch rejects with a TypeError carrying a `cause` when the API cannot be
- * reached; a TypeError from our own code carries none and is a bug to surface.
- */
-export function isNetworkFailure(error: unknown): error is TypeError {
-  return error instanceof TypeError && 'cause' in error;
-}
-
-/** What went wrong on the wire: undici's message is the constant "fetch failed", the cause says why. */
-export function networkFailureDetail(error: TypeError): string {
-  const cause = error.cause as { code?: unknown; message?: unknown } | undefined;
-  const why = typeof cause?.code === 'string' ? cause.code : typeof cause?.message === 'string' ? cause.message : null;
-  return why ? `${error.message} (${why})` : error.message;
-}
-
-/**
- * The code a status implies when the API sent none. 400 is VALIDATION_ERROR,
- * the code the API itself sends, so a refusal by this server and one by the
- * API read the same.
- */
-const CODE_BY_STATUS: Record<number, string> = {
-  400: 'VALIDATION_ERROR',
-  401: 'UNAUTHENTICATED',
-  403: 'FORBIDDEN',
-  404: 'NOT_FOUND',
-  409: 'CONFLICT',
-  429: 'RATE_LIMITED',
-};
-
-/** What the API said, in one phrase: the status, the code it sent (or the one its status implies), its message. */
-export function apiFailureText(error: TaigaApiError): string {
-  return `${error.status} ${apiFailureCode(error)}${error.apiMessage ? `: ${error.apiMessage}` : ''}`;
-}
-
-/** The code the API sent, or the one its status implies: the code a model branches on. */
-export function apiFailureCode(error: TaigaApiError): string {
-  return error.code ?? CODE_BY_STATUS[error.status] ?? 'API_ERROR';
-}
-
-/** Whether a failure is the API's refusal or absence of a thing, as opposed to the API failing. */
-export function isMissOrRefusal(error: unknown): error is TaigaApiError {
-  return error instanceof TaigaApiError && (error.status === 404 || error.status === 403);
-}
-
-/**
- * Run a tool handler and turn a failure into a structured error. An API
- * refusal keeps the API's own code when it sent one and its message whole:
- * on a refused publish that names the section holding template residue,
- * which is what the model needs to fix the draft. A failed connection is
- * structured too, so every failure the model sees has the same shape.
- */
-export async function runTool(handler: () => Promise<CallToolResult>): Promise<CallToolResult> {
-  try {
-    return await handler();
-  } catch (error) {
-    if (error instanceof TaigaApiError) {
-      const code = error.code ?? CODE_BY_STATUS[error.status] ?? 'API_ERROR';
-      const said = error.apiMessage ?? `Taiga API answered ${error.status}.`;
-      // A miss says where the right IDs are (hints.ts): the API's own word is bare.
-      const worded = inProductWording(said);
-      const message = error.status === 404 ? withNotFoundHint(worded) : worded;
-      return toolError(code, message, error.details);
-    }
-    if (isNetworkFailure(error)) {
-      return toolError(
-        'NETWORK_ERROR',
-        `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`
-      );
-    }
-    throw error;
-  }
-}

package/src/tools/hints.ts

@@ -1,99 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-/**
- * The next step after the API answers 404. The API's own word is bare
- * ("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> = {
-  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 linkable repository id is not a link ID.",
-  replacesRepositoryId: "taiga_list_product_repositories lists the product's repository links.",
-  linkableRepositoryId:
-    'taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.',
-  installationId: 'taiga_list_linkable_repositories lists the connected GitHub accounts.',
-  jobId: 'A job ID is what the tool that started the job returned (taiga_request_initiatives, taiga_start_import).',
-  factoryId: 'taiga_list_factories lists the factories the key can see.',
-  findingId: "taiga_list_findings lists a product's findings.",
-  violationId: "taiga_get_policy_standing lists a product's policy violations.",
-  environmentId: "taiga_list_environments lists the product's environments with their IDs; a product ID is not one.",
-  knowledgeId: 'taiga_list_knowledge lists the knowledge files.',
-  productId:
-    'taiga_list_products lists the products the key can see; a name is not an ID (taiga_get_product takes a slug).',
-};
-
-/** A hint chosen from what the API said, for a tool whose 404 can mean two things. */
-type Hint = (said: string) => string | undefined;
-
-/** Where an argument means something else on one tool, or the tool's 404 needs its own word. */
-const BY_TOOL: Record<string, Hint> = {
-  taiga_resolve_action: () => 'taiga_list_action_required lists the items with their IDs.',
-  // "No active plan" is the plan's miss; anything else is the initiative's,
-  // and sending an agent that mistyped an ID to taiga_plan_again would start
-  // paid planning to fix a typo.
-  taiga_get_plan: (said) =>
-    /\bplan\b/i.test(said)
-      ? 'taiga_get_initiative says whether one is being generated (planningStatus planning) or failed, and ' +
-        'taiga_plan_again asks for a new one.'
-      : 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,
-  linkableRepositoryId: /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 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;
-  const given = Object.keys(args).filter((key) => (args as Record<string, unknown>)[key] != null && BY_ARGUMENT[key]);
-  // The product last: a product the key cannot see is answered "Product not
-  // 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;
-  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. */
-export const notFoundHints = new AsyncLocalStorage<Hint | undefined>();
-
-/** The API's 404 message with the hint of the call in progress, if it has one. */
-export function withNotFoundHint(said: string): string {
-  const hint = notFoundHints.getStore()?.(said);
-  return hint ? `${withStop(said)} ${hint}` : said;
-}
-
-/** A sentence ends in a stop before the next one is added to it. */
-export function withStop(text: string): string {
-  return /[.!?]$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
-}