@taiga-ai/mcp-server 0.26.0-dev.515 → 0.26.0-dev.518

package/dist/index.js

@@ -2688,7 +2688,7 @@ function setupNextStep(product) {
 	if (product?.status !== "draft") return null;
 	if (isImportedProduct(product)) switch (importStatusOf(product)) {
 		case "analyzing":
-		case "generating_docs": return `The import is running and derives the documents from the code (taiga_wait_for_job follows its job). Then review them, and ${FINISH_DISCOVERY}`;
+		case "generating_docs": return `The import is running and derives the documents from the code (taiga_wait (jobId) follows its job). Then review them, and ${FINISH_DISCOVERY}`;
 		case "complete": return "The import is done: review the reality documents (taiga_get_product_document without type), then taiga_finish_discovery opens the product and starts planning its first initiatives (paid agent work: ask the person first).";
 		case "failed":
 		case "cancelled": return "The last import did not finish: taiga_start_import runs it again.";
@@ -2724,7 +2724,7 @@ const BY_ARGUMENT = {
 	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.",
+	environmentId: "taiga_get_deployments 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)."
 };
@@ -3308,7 +3308,7 @@ function nextStepFor(state) {
 		if (state.linked === false) return "Link its repository (taiga_list_linkable_repositories, then taiga_link_repository), then taiga_start_import.";
 		if (state.linked === null && state.importState === "not started") return setupNextStep(state.product);
 		switch (state.importState) {
-			case "running": return "The import is running and derives the documents from the code; taiga_wait_for_job follows it.";
+			case "running": return "The import is running and derives the documents from the code; taiga_wait (jobId) follows it.";
 			case "failed": return "The last import did not finish: taiga_start_import runs it again.";
 			case "complete":
 				if (state.missing && state.missing.length > 0) return `The import finished but ${named(state.missing)} ${state.missing.length === 1 ? "is" : "are"} not published: taiga_get_product_document without type shows them, taiga_publish_product_document publishes a draft.`;
@@ -3787,7 +3787,7 @@ function registerProductTools(server, client) {
 		}));
 		server.registerTool("taiga_get_product", {
 			title: "Get product",
-			description: "Read one product and its settings by ID, slug or git remote URL (git remote get-url origin; a URL linked to more than one product is refused with their IDs): name, factory, kind, autonomy, what Taiga builds (application, infrastructure, deployment) and network access, unsetMeans saying what a null setting follows. In setup, readiness says whether it can finish now and what is missing (repository, import, unpublished documents, unstamped checks), plus nextStep. For initiatives, runs and findings, use taiga_get_product_context.",
+			description: "Read one product's settings only (for where it stands, use taiga_get_product_context), by ID, slug or git remote URL (git remote get-url origin; a URL linked to more than one product is refused with their IDs): name, factory, kind, autonomy, what Taiga builds (application, infrastructure, deployment) and network access, unsetMeans saying what a null setting follows. In setup, readiness says whether it can finish now and what is missing (repository, import, unpublished documents, unstamped checks), plus nextStep. For initiatives, runs and findings, use taiga_get_product_context.",
 			inputSchema: z.object({
 				productId: productId.optional(),
 				slug: slug.optional(),
@@ -4139,7 +4139,7 @@ function registerJobTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_job", {
 		title: "Get an agent job",
-		description: "Read one agent job, such as a taiga_request_initiatives request: status (pending, processing, completed, failed, cancelled), progress and any error. A finished initiative request lists the initiatives it added, or why none (already covered, not readable as work, outside the product, or not allowed by a policy, with the rule it conflicts with and how to decide otherwise). taiga_wait_for_job waits for it.",
+		description: "Read one agent job, such as a taiga_request_initiatives request: status (pending, processing, completed, failed, cancelled), progress and any error. A finished initiative request lists the initiatives it added, or why none (already covered, not readable as work, outside the product, or not allowed by a policy, with the rule it conflicts with and how to decide otherwise). taiga_wait (jobId) waits for it.",
 		inputSchema: z.object({ jobId: idInput("job", "the tool that started the job returned it") }),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data))));
@@ -4221,6 +4221,20 @@ const RUN_OUTCOME_FIELDS = [
 * stalled in the hardening pass after the steps and the retry continues it.
 * Null for a run still going or that finished.
 */
+/**
+* The line of a failed step's error that says why (PRO-2941): a review found the reason buried in a
+* 2,000-character dump of git and lint output, behind runtime warnings. The first line that reads as an error,
+* else the first line; capped. Null when no step failed with an error.
+*/
+function failureCause(steps) {
+	const failed = steps.find((step) => step["status"] === "failed" && typeof step["error"] === "string");
+	if (!failed) return null;
+	const lines = String(failed["error"]).split("\n").map((line) => line.trim()).filter((line) => line && !/^\(node:\d+\)|^\(Use `node|^[⋯✔↓]/u.test(line));
+	const telling = lines.find((line) => /\berror\b|cannot|not found|denied|refused|no such/iu.test(line)) ?? lines.find((line) => /fail|✖/iu.test(line)) ?? lines[0];
+	if (!telling) return null;
+	const said = telling.length > 200 ? `${telling.slice(0, 197)}...` : telling;
+	return `step ${String(failed["stepOrder"])}: ${said}`;
+}
 function stoppedIn(run, steps) {
 	if (run.prMerged === true || run.status !== "failed" && run.status !== "stopped") return null;
 	if (!steps.some((step) => step.status !== "planned")) return "before the first step started, while setting up the run (cloning, preparing the workspace)";
@@ -4625,7 +4639,7 @@ function registerBuildTools(server, client) {
 	}));
 	server.registerTool("taiga_get_run", {
 		title: "Get run",
-		description: "Read one coding-agent run: status and outcome (one sentence), pull request, hardening, and each step with its status, commit, files, verification and headline. scanCoverage names security scanners that did not run, and why. verification is Taiga's check after a step (tests, lint, build); verificationNote says when one failed throughout. A failed or stopped run has stoppedIn and failedReasonMeans. full: true adds the complete instructions and reports. To resume: taiga_resume_initiative; to stop: move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
+		description: "Read one coding-agent run: status and outcome (one sentence), pull request, hardening, and each step with its status, commit, files, verification and headline. scanCoverage names security scanners that did not run, and why. verification is Taiga's check after a step (tests, lint, build); verificationNote says when one failed throughout. A failed or stopped run has stoppedIn, failedReasonMeans and cause (the line of the failed step's error that says why). full: true adds the complete instructions and reports. To resume: taiga_resume_initiative; to stop: move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
 		inputSchema: z.object({
 			runId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions and report (default false: a summary)")
@@ -4636,7 +4650,11 @@ function registerBuildTools(server, client) {
 		const runRow = run.data;
 		const rows = steps.data.map((step) => neverStarted(step));
 		const where = stoppedIn(runRow, rows);
-		const stop = where ? { stoppedIn: where } : {};
+		const cause = failureCause(rows);
+		const stop = {
+			...where ? { stoppedIn: where } : {},
+			...cause ? { cause } : {}
+		};
 		const states = await initiativeStates(client, [runRow]);
 		const readable = withInitiativeState(readableRun(runRow), states);
 		const note = verificationNote(rows);
@@ -4818,7 +4836,7 @@ async function queueView(client, product, options = { name: "all" }) {
 	return {
 		linePaused: paused === null ? null : typeof paused === "string",
 		entries: rows.map(({ lifecycle: _lifecycle, runId: _runId, ...row }) => row),
-		waitingOn: line ?? waitingOn(rows, idle ? station : null),
+		waitingOn: line ?? waitingOn(rows, idle ? station : null) ?? (rows.length === 0 && "offTheLine" in offLine ? `Nothing is queued. ${offLine.offTheLine}` : null),
 		...offLine,
 		...note ? { note } : {}
 	};
@@ -5247,7 +5265,7 @@ function registerBacklogReads(server, client) {
 function registerRequest(server, client) {
 	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.",
+		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 (jobId) 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"),
@@ -5484,12 +5502,31 @@ function groupKey(row) {
 	const rule = typeof location?.ruleId === "string" ? location.ruleId : null;
 	return rule ? `${String(row["kind"])}|${String(row["severity"])}|${status}|${link}|${rule}` : null;
 }
-/** Where one finding is, in a few characters: its path and line, or its package. */
+/**
+* Where one finding is, in a few characters: its file and line (and the resource a scanner names), or its package.
+* A review read seven "CKV_GHA_7" where the location keeps no path: the file is in sourcePaths.
+*/
 function whereOf(row) {
 	const location = row["location"];
-	if (typeof location?.path === "string") return location.line ? `${location.path}:${String(location.line)}` : location.path;
+	const paths = Array.isArray(row["sourcePaths"]) ? row["sourcePaths"] : [];
+	const file = typeof location?.path === "string" ? location.path : typeof paths[0] === "string" ? paths[0] : null;
+	if (file) {
+		const at = location?.line ? `${file}:${String(location.line)}` : file;
+		return typeof location?.resource === "string" ? `${at} ${location.resource}` : at;
+	}
 	return [row["packageName"], row["currentVersion"]].filter(Boolean).join(" ") || String(row["id"]);
 }
+/** The words every member's title opens with, at a word boundary; empty when they share fewer than 20 characters. */
+function sharedTitle(titles) {
+	let prefix = titles[0] ?? "";
+	for (const title of titles.slice(1)) {
+		let at = 0;
+		while (at < prefix.length && prefix[at] === title[at]) at += 1;
+		prefix = prefix.slice(0, at);
+	}
+	const cut = (prefix.length === (titles[0] ?? "").length ? prefix : prefix.slice(0, Math.max(0, prefix.lastIndexOf(" ")))).trim().replace(/[\s,(:;-]+$/, "");
+	return cut.length >= 20 ? cut : "";
+}
 /**
 * Findings of one rule or license verdict on a page, folded into one row (PRO-2941): a review read seven
 * CKV_GHA_7 rows and fifteen sharp license rows, identical but for where. The first stands for them, with
@@ -5517,12 +5554,14 @@ function grouped(rows, fold) {
 		if (members.length === 1) return members[0];
 		const where = members.map(whereOf);
 		const first = members[0];
-		const shared = Object.fromEntries(Object.entries(first).filter(([key, value]) => key !== "id" && members.every((member) => JSON.stringify(member[key]) === JSON.stringify(value))));
+		const shared = Object.fromEntries(Object.entries(first).filter(([key, value]) => key !== "id" && key !== "title" && members.every((member) => JSON.stringify(member[key]) === JSON.stringify(value))));
 		const location = first["location"];
-		const said = first["kind"] === "license_violation" ? licenseVerdict(first) : typeof location?.ruleId === "string" ? location.ruleId : String(first["title"]);
+		const words = sharedTitle(members.map((member) => String(member["title"] ?? "")));
+		const rule = typeof location?.ruleId === "string" ? location.ruleId : null;
+		const said = first["kind"] === "license_violation" ? licenseVerdict(first) : words ? rule && !words.includes(rule) ? `${rule}: ${words}` : words : rule ?? String(first["title"]);
 		return {
 			...shared,
-			...shared["title"] === void 0 ? { title: said } : {},
+			title: said,
 			count: members.length,
 			findingIds: members.map((member) => member["id"]),
 			where: where.slice(0, GROUP_WHERE),
@@ -5661,8 +5700,11 @@ function standingSummary(standing) {
 		bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
 	}
 	const stated = (state) => controls.filter((c) => c["state"] === state).length;
+	const withAny = (key) => controls.filter((control) => Number(control[key] ?? 0) > 0).length;
 	return {
-		controls: listed.length,
+		controlsWithViolations: listed.length,
+		controlsBreached: withAny("findingCount"),
+		controlsDiverged: withAny("divergenceCount"),
 		controlsInPolicies: controls.length,
 		controlsMet: stated("met"),
 		controlsNotApplicable: stated("not_applicable"),
@@ -6148,6 +6190,8 @@ function isDue(row, now) {
 }
 /** Pages read for the summary; past this it says it counted only those. */
 const SUMMARY_PAGE = 100;
+/** Rows an org-wide first page carries when the caller names no limit: the summary answers the rest. */
+const ORG_WIDE_ROWS = 10;
 /** Pages the summary reads before it says it stopped: 1,000 items. */
 const SUMMARY_PAGES = 10;
 /** Every item the summary counts, up to SUMMARY_PAGES pages; nextCursor set when it stopped short. Null on failure. */
@@ -6269,8 +6313,10 @@ function registerInboxTools(server, client) {
 			...resolved ? { resolved: true } : {}
 		};
 		const first = params.cursor === void 0;
+		const limit = params.limit ?? (params.productId ? void 0 : ORG_WIDE_ROWS);
 		const result = await client.listInbox({
 			...query,
+			...limit !== void 0 ? { limit } : {},
 			...first ? { withTotal: true } : {}
 		});
 		const overview = !first || resolved ? null : !result.nextCursor ? result : await everyItem(client, query);
@@ -6309,7 +6355,7 @@ function registerInboxTools(server, client) {
 			...checked.unchecked > 0 ? (() => {
 				const onPage = due.filter((row) => checked.uncheckedIds.has(String(row["id"]))).length;
 				const beyond = checked.unchecked - onPage;
-				return { staleNote: `${[...onPage > 0 ? [`${onPage} review${onPage === 1 ? "" : "s"} on this page could not be checked for whether the subject moved on: those rows say staleChecked: false, and their readWith read tells`] : [], ...beyond > 0 ? [`${beyond} review${beyond === 1 ? "" : "s"} counted in the summary but not on this page could not be checked either, so the summary counts them open`] : []].join("; ")}.` };
+				return { staleNote: `${[...onPage > 0 ? [`${onPage} review${onPage === 1 ? "" : "s"} on this page could not be checked for whether the subject moved on: those rows say staleChecked: false, and their readWith read tells`] : [], ...beyond > 0 ? [`${beyond} review${beyond === 1 ? "" : "s"} past this page could not be checked, so the summary counts them as open`] : []].join("; ")}.` };
 			})() : {}
 		});
 	}));
@@ -6700,13 +6746,12 @@ async function standingPart(client, productId) {
 	const standing = (await client.getPolicyStanding(productId)).data;
 	const summary = standingSummary(standing);
 	const state = standing.assessment?.state;
-	const controls = Array.isArray(standing.controls) ? standing.controls : [];
-	const withAny = (key) => controls.filter((control) => Number(control[key] ?? 0) > 0).length;
 	return {
 		openViolations: summary.violations,
 		bySeverity: summary.bySeverity,
-		controlsBreached: withAny("findingCount"),
-		controlsDiverged: withAny("divergenceCount"),
+		controlsWithViolations: summary.controlsWithViolations,
+		controlsBreached: summary.controlsBreached,
+		controlsDiverged: summary.controlsDiverged,
 		controlsMet: summary.controlsMet,
 		controlsNotApplicable: summary.controlsNotApplicable,
 		...state === "never" || state === "failed" ? { note: `The assessment ${state === "never" ? "has never run" : "failed"}: no violations here is not an all-clear.` } : {}
@@ -7073,7 +7118,7 @@ function deploymentLines(rows) {
 		};
 	});
 }
-const environmentId = idInput("environment", "taiga_list_environments lists them; a product ID is not one");
+const environmentId = idInput("environment", "taiga_get_deployments lists them; a product ID is not one");
 /** The windows the pages offer, as the schema's own values rather than a number checked afterwards. */
 const windowDays = z.literal([
 	30,
@@ -7083,11 +7128,11 @@ const windowDays = z.literal([
 /** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
 const isApiFailure = (error) => error instanceof TaigaApiError || isNetworkFailure(error);
 /** A part that may fail on its own without failing the read: null and the reason, or the value. */
-async function part(read) {
+async function part(read, rethrow = () => false) {
 	try {
 		return { value: await read() };
 	} catch (error) {
-		if (!isApiFailure(error)) throw error;
+		if (!isApiFailure(error) || rethrow(error)) throw error;
 		return { unavailable: error instanceof TaigaApiError ? `${error.status}: ${error.apiMessage ?? ""}`.trim() : "unreachable" };
 	}
 }
@@ -7118,7 +7163,7 @@ function registerObserveTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_deployments", {
 		title: "Get what runs where",
-		description: "Read what runs in each of a product's environments and its recent deployments, newest first: commit, pull request, status, deployer and, on failure, the provider's error. What runs is the latest successful deployment, so a newer failure shows beside it. History is mirrored from the provider, including deployments made outside Taiga; syncStatus says when it last synced. environmentId narrows to one environment. Taiga never deploys.",
+		description: "Read a product's environments with their IDs, what runs in each, and its recent deployments, newest first: commit, pull request, status, deployer and, on failure, the provider's error. What runs is the latest successful deployment, so a newer failure shows beside it. History is mirrored from the provider, including deployments made outside Taiga; syncStatus says when it last synced. environmentId narrows to one environment. Taiga never deploys.",
 		inputSchema: z.object({
 			productId,
 			environmentId: environmentId.optional(),
@@ -7126,25 +7171,31 @@ function registerObserveTools(server, client) {
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const [environments, current, history, sync] = await Promise.all([
+		const [environments, currentRead, historyRead, sync] = await Promise.all([
 			allEnvironments(client, params.productId),
-			client.getCurrentDeployments(params.productId),
-			client.listDeployments(params.productId, {
+			part(() => client.getCurrentDeployments(params.productId)),
+			part(() => client.listDeployments(params.productId, {
 				environmentId: params.environmentId,
 				limit: params.limit ?? 10,
 				cursor: params.cursor
-			}),
+			}), (error) => Boolean(params.environmentId) && error instanceof TaigaApiError && error.status === 404),
 			part(() => client.getDeploymentSyncStatus(params.productId))
 		]);
-		const now = current.data;
-		const note = environments.rows.length === 0 ? "This product has no environments yet: an environment is defined with taiga_create_environment, and its deployments are mirrored from the provider once it is." : history.data.length === 0 && !params.cursor ? "No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last synced), or nothing has been deployed." : null;
-		const live = new Set([...now.current ?? [], ...now.deploying ?? []].map((row) => row.id));
+		const now = "value" in currentRead ? currentRead.value.data : null;
+		const history = "value" in historyRead ? historyRead.value : null;
+		const note = environments.rows.length === 0 ? "This product has no environments yet: an environment is defined with taiga_create_environment, and its deployments are mirrored from the provider once it is." : history && history.data.length === 0 && !params.cursor ? "No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last synced), or nothing has been deployed." : null;
+		const live = new Set([...now?.current ?? [], ...now?.deploying ?? []].map((row) => row.id));
+		const unavailable = {
+			..."unavailable" in currentRead ? { running: currentRead.unavailable } : {},
+			..."unavailable" in historyRead ? { history: historyRead.unavailable } : {}
+		};
 		return toolResult({
 			environments: pickFields(environments.rows, ENVIRONMENT_FIELDS),
 			...environments.more ? { moreEnvironments: true } : {},
-			running: deploymentLines(now.current ?? []),
-			deploying: deploymentLines(now.deploying ?? []),
-			history: page(deploymentLines(history.data.filter((row) => !live.has(row.id))), history.nextCursor),
+			running: now ? deploymentLines(now.current ?? []) : null,
+			deploying: now ? deploymentLines(now.deploying ?? []) : null,
+			history: history ? page(deploymentLines(history.data.filter((row) => !live.has(row.id))), history.nextCursor) : null,
+			...Object.keys(unavailable).length > 0 ? { unavailable } : {},
 			..."value" in sync ? { syncStatus: sync.value.data } : {
 				syncStatus: null,
 				syncUnavailable: sync.unavailable
@@ -7152,19 +7203,6 @@ function registerObserveTools(server, client) {
 			...note ? { note } : {}
 		});
 	}));
-	server.registerTool("taiga_list_environments", {
-		title: "List a product's environments",
-		description: "List a product's environments with ID, type, order and App URL. These are the environment IDs taiga_get_delivery_metrics, taiga_get_monitoring and taiga_update_environment take. taiga_get_deployments lists them too, with what runs where.",
-		inputSchema: z.object({ productId }),
-		annotations: READ_ONLY
-	}, (params) => runTool(async () => {
-		const { rows, more } = await allEnvironments(client, params.productId);
-		return toolResult({
-			data: pickFields(rows, ENVIRONMENT_FIELDS),
-			...more ? { more: "More environments than this answer reads; the rest were left out." } : {},
-			...rows.length === 0 ? { note: "No environment is defined yet; taiga_create_environment adds one." } : {}
-		});
-	}));
 	server.registerTool("taiga_get_delivery_metrics", {
 		title: "Get delivery metrics",
 		description: "Read DORA's five delivery metrics for one environment (the page shows production) over 30, 60 or 90 days: deployment frequency, lead time, failed deployment recovery time, change-failure rate and rework rate, each with its trend against the window before and a performance band (none for rework rate). Computed from deployments, not incidents; previews and checks do not count. Under ten deployments a trend is approximate; a metric with no data says so instead of a number. Without environmentId, the product's production environment when it has exactly one.",
@@ -7184,7 +7222,7 @@ function registerObserveTools(server, client) {
 				note: "This product has no environments, so there is nothing to measure: an environment is defined with taiga_create_environment, and its deployments are mirrored from the provider once it is."
 			});
 			const production = all.filter((env) => env.type === "production");
-			if (production.length !== 1 || more) return toolError("VALIDATION_ERROR", `Pass environmentId: the product has ${more ? "more environments than one read holds, and " : ""}${production.length === 0 ? "no" : production.length} production environment${production.length === 1 ? "" : "s"}${more ? " among the first" : ""}. taiga_list_environments lists them with their IDs.`, { environments: all.map((env) => ({
+			if (production.length !== 1 || more) return toolError("VALIDATION_ERROR", `Pass environmentId: the product has ${more ? "more environments than one read holds, and " : ""}${production.length === 0 ? "no" : production.length} production environment${production.length === 1 ? "" : "s"}${more ? " among the first" : ""}. taiga_get_deployments lists them with their IDs.`, { environments: all.map((env) => ({
 				id: env.id,
 				name: env.name,
 				type: env.type
@@ -7313,7 +7351,7 @@ function registerProductDocumentWrites(server, client) {
 	}, (params) => runTool(async () => toolResult((await client.markProductDocumentReviewed(params.productId, params.type)).data)));
 	if (canRead) server.registerTool("taiga_regenerate_product_document", {
 		title: "Regenerate a product document",
-		description: "Regenerate one product document from the documents it derives from, when it is outdated or needs another pass, and return the job. The result is published and documents derived from it are marked outdated. The Specification (from the Discovery conversation) and the Look & Feel (from its concepts) are made in the web. Documents Discovery requires regenerate only while Discovery is open; the optional Service Blueprint any time. taiga_wait_for_job says when it is done.",
+		description: "Regenerate one product document from the documents it derives from, when it is outdated or needs another pass, and return the job. The result is published and documents derived from it are marked outdated. The Specification (from the Discovery conversation) and the Look & Feel (from its concepts) are made in the web. Documents Discovery requires regenerate only while Discovery is open; the optional Service Blueprint any time. taiga_wait (jobId) says when it is done.",
 		inputSchema: z.object({
 			productId,
 			type: generatedType
@@ -22658,7 +22696,7 @@ function registerSetupTools(server, client) {
 	}));
 	server.registerTool("taiga_refresh_reality_documents", {
 		title: "Refresh a product's documents from its code",
-		description: "Derive the reality documents again from the code on the branch Taiga works on (effectiveBranch): all, or the ones named. For a document the import misread, refresh it instead of importing again; unchanged sections are not republished. Returns the job; taiga_wait_for_job says when it is done.",
+		description: "Derive the reality documents again from the code on the branch Taiga works on (effectiveBranch): all, or the ones named. For a document the import misread, refresh it instead of importing again; unchanged sections are not republished. Returns the job; taiga_wait (jobId) says when it is done.",
 		inputSchema: z.object({
 			productId,
 			docTypes: z.array(z.enum(REALITY_DERIVED_DOCUMENT_TYPES)).min(1).max(REALITY_DERIVED_DOCUMENT_TYPES.length).optional().describe("The documents to refresh; omit for all")
@@ -22687,7 +22725,7 @@ function registerSetupTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_start_import", {
 		title: "Import a codebase into a product",
-		description: "Start importing a product created for import, and return the job. Taiga reads the linked repository and derives the full document set from the code, citing the files. Then the scanners sweep it, the documents are assessed against policies, and the first initiatives are planned when Discovery finishes. Refused for a scratch product, without a linked repository, or while an import runs. taiga_wait_for_job says when it is done (it takes a while).",
+		description: "Start importing a product created for import, and return the job. Taiga reads the linked repository and derives the full document set from the code, citing the files. Then the scanners sweep it, the documents are assessed against policies, and the first initiatives are planned when Discovery finishes. Refused for a scratch product, without a linked repository, or while an import runs. taiga_wait (jobId) says when it is done (it takes a while).",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
@@ -22954,20 +22992,25 @@ function judgeBuild(until) {
 		return null;
 	};
 }
+/** What each target may be waited for. A job has one condition, finished, so it takes none. */
+const UNTIL_FOR = {
+	initiative: ITEM_CONDITIONS,
+	run: BUILD_CONDITIONS
+};
+const ALL_CONDITIONS = [.../* @__PURE__ */ new Set([...ITEM_CONDITIONS, ...BUILD_CONDITIONS])];
+/**
+* One tool for waiting (PRO-2941): three wait tools, one per thing waited on, were two more names in a catalogue
+* every review ranked too large. The ID says what is waited on; until says for what, refused when it does not
+* apply to that thing.
+*/
 function registerWaitTools(server, client, options) {
-	if (client.hasCapability("backlog:read")) server.registerTool("taiga_wait_for_initiative", {
-		title: "Wait for an initiative",
-		description: "Wait until an initiative reaches a condition instead of polling: changed, planned, your_turn (waits on a person), pr_open (open now; merged or closed does not count), run_settled (latest run stopped moving) or done. Returns reached: true when it holds; early with stoppedBecause when only a person can move it (a flag, failed plan, plan or pull request awaiting review, a cancel); or reached: false at the timeout: call again. A condition already true answers at once. Planning takes minutes, a run up to an hour.",
-		inputSchema: z.object({
-			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it"),
-			until: z.enum(ITEM_CONDITIONS).describe("What to wait for"),
-			timeoutSeconds
-		}),
-		annotations: READ_ONLY
-	}, (params, ctx) => runTool(async () => {
+	const items = client.hasCapability("backlog:read");
+	const runs = client.hasCapability("products:read");
+	if (!items && !runs) return;
+	const waitInitiative = async (target, until, params, ctx) => {
 		const gate = { product: void 0 };
 		const read = async (signal) => {
-			const item = (await client.getBacklogItem(params.initiativeId, signal)).data;
+			const item = (await client.getBacklogItem(target, signal)).data;
 			if (gate.product === void 0 && typeof item.autoBuild !== "boolean") gate.product = client.hasCapability("products:read") ? await client.getProduct(String(item.productId), signal).then((p) => {
 				const value = p.data.autoBuild;
 				return typeof value === "boolean" ? value : true;
@@ -22977,48 +23020,31 @@ function registerWaitTools(server, client, options) {
 			}) : null;
 			return item;
 		};
-		const { now, ...outcome } = await waitFor(read, judgeItem(params.until, gate), (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
+		const { now, ...outcome } = await waitFor(read, judgeItem(until, gate), (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
 			progressToken: ctx.mcpReq._meta?.progressToken,
 			notify: ctx.mcpReq.notify,
 			signal: ctx.mcpReq.signal
 		});
 		return toolResult({
-			until: params.until,
+			until,
 			...outcome,
 			item: now ? itemReport(now) : null
 		});
-	}));
-	if (client.hasCapability("products:read")) server.registerTool("taiga_wait_for_run", {
-		title: "Wait for a run",
-		description: "Wait until a run reaches a condition: changed, step_done (one more step finished), pr_open (open now) or settled (in review, completed, failed, stopped). Returns reached: true when it holds; early with stoppedBecause if the run settled without it; or reached: false at the timeout: call again. A settled run answers settled at once; run is null if the first read timed out.",
-		inputSchema: z.object({
-			runId: idInput("run", "taiga_list_runs gives it"),
-			until: z.enum(BUILD_CONDITIONS).describe("What to wait for"),
-			timeoutSeconds
-		}),
-		annotations: READ_ONLY
-	}, (params, ctx) => runTool(async () => {
-		const { now, ...outcome } = await waitFor(async (signal) => (await client.getBuildRun(params.runId, signal)).data, judgeBuild(params.until), (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
+	};
+	const waitRun = async (target, until, params, ctx) => {
+		const { now, ...outcome } = await waitFor(async (signal) => (await client.getBuildRun(target, signal)).data, judgeBuild(until), (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
 			progressToken: ctx.mcpReq._meta?.progressToken,
 			notify: ctx.mcpReq.notify,
 			signal: ctx.mcpReq.signal
 		});
 		return toolResult({
-			until: params.until,
+			until,
 			...outcome,
 			run: now ? readableRow(pickFields([now], RUN_REPORT_FIELDS)[0]) : null
 		});
-	}));
-	if (client.hasCapability("products:read")) server.registerTool("taiga_wait_for_job", {
-		title: "Wait for an agent job",
-		description: "Wait until an agent job finishes (completed, failed or cancelled). Returns the job as taiga_get_job reads it, with an initiative request's outcome, and reached: true; or reached: false at the timeout: call again to keep waiting. Most jobs take a few minutes.",
-		inputSchema: z.object({
-			jobId: idInput("job", "the tool that started the job returned it"),
-			timeoutSeconds
-		}),
-		annotations: READ_ONLY
-	}, (params, ctx) => runTool(async () => {
-		const { now, ...outcome } = await waitFor(async (signal) => (await client.getAgentJob(params.jobId, signal)).data, (job) => SETTLED_JOB_STATUSES.has(String(job.status)) ? { reached: true } : null, (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
+	};
+	const waitJob = async (target, params, ctx) => {
+		const { now, ...outcome } = await waitFor(async (signal) => (await client.getAgentJob(target, signal)).data, (job) => SETTLED_JOB_STATUSES.has(String(job.status)) ? { reached: true } : null, (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1e3, options, {
 			progressToken: ctx.mcpReq._meta?.progressToken,
 			notify: ctx.mcpReq.notify,
 			signal: ctx.mcpReq.signal
@@ -23027,6 +23053,38 @@ function registerWaitTools(server, client, options) {
 			...outcome,
 			job: now ? jobReport(now) : null
 		});
+	};
+	server.registerTool("taiga_wait", {
+		title: "Wait for an initiative, run or job",
+		description: "Wait instead of polling, for one of: an initiative (initiativeId) to reach until: changed, planned, your_turn (waits on a person), pr_open (open now; merged or closed does not count), run_settled (latest run stopped moving) or done; a run (runId) to reach until: changed, step_done, pr_open or settled (in review, completed, failed, stopped); or an agent job (jobId) to finish, which takes no until. Returns reached: true when it holds; early with stoppedBecause when it cannot happen without a person; or reached: false at the timeout: call again. A condition already true answers at once. Planning takes minutes, a run up to an hour, most jobs a few minutes.",
+		inputSchema: z.object({
+			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it").optional(),
+			runId: idInput("run", "taiga_list_runs gives it").optional(),
+			jobId: idInput("job", "the tool that started the job returned it").optional(),
+			until: z.enum(ALL_CONDITIONS).optional().describe("What to wait for: an initiative and a run need one"),
+			timeoutSeconds
+		}),
+		annotations: READ_ONLY
+	}, (params, ctx) => runTool(async () => {
+		if ([
+			"initiativeId",
+			"runId",
+			"jobId"
+		].filter((key) => params[key] !== void 0).length !== 1) return toolError("VALIDATION_ERROR", "Name exactly one of initiativeId, runId or jobId: the thing to wait on.");
+		if (params.jobId !== void 0) {
+			if (params.until !== void 0) return toolError("VALIDATION_ERROR", "A job is waited on until it finishes: leave until out.");
+			if (!runs) return toolError("FORBIDDEN", "Waiting on a job needs products:read, which this key lacks.");
+			return waitJob(params.jobId, params, ctx);
+		}
+		const kind = params.initiativeId !== void 0 ? "initiative" : "run";
+		const allowed = UNTIL_FOR[kind];
+		if (params.until === void 0 || !allowed.includes(params.until)) return toolError("VALIDATION_ERROR", `Waiting on ${kind === "initiative" ? "an initiative" : "a run"} takes until: ${allowed.join(", ")}.`);
+		if (kind === "initiative") {
+			if (!items) return toolError("FORBIDDEN", "Waiting on an initiative needs backlog:read, which this key lacks.");
+			return waitInitiative(params.initiativeId, params.until, params, ctx);
+		}
+		if (!runs) return toolError("FORBIDDEN", "Waiting on a run needs products:read, which this key lacks.");
+		return waitRun(params.runId, params.until, params, ctx);
 	}));
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.26.0-dev.515",
+  "version": "0.26.0-dev.518",
   "description": "Taiga for AI coding assistants: read products, policies, initiatives and runs, and operate the line, over MCP",
   "mcpName": "ga.tai/mcp-server",
   "type": "module",