@taiga-ai/mcp-server 0.12.0-dev.421 → 0.13.0-dev.422

package/dist/index.js

@@ -211,6 +211,21 @@ var TaigaClient = class {
 		const qs = params.toString();
 		return this.request("GET", `/products/${seg(productId)}/documents${qs ? `?${qs}` : ""}`);
 	}
+	/**
+	* Stop or start the product's line. Stopping halts pulls and builds and
+	* stops the plan and build in flight; starting picks the interrupted work
+	* back up.
+	*/
+	async setLineStopped(productId, stopped) {
+		return this.request("PUT", `/products/${seg(productId)}/line`, { stopped });
+	}
+	/** Ask an agent for work: the job is queued and runs in the background. */
+	async createAgentJob(body) {
+		return this.request("POST", "/agent-jobs", body);
+	}
+	async getAgentJob(id, signal) {
+		return this.request("GET", `/agent-jobs/${seg(id)}`, void 0, { signal });
+	}
 	async getProductDocument(productId, type, origin) {
 		const qs = origin ? `?${new URLSearchParams({ origin })}` : "";
 		return this.request("GET", `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
@@ -229,12 +244,6 @@ var TaigaClient = class {
 	async getBacklogItem(itemId, signal) {
 		return this.request("GET", `/backlog/${seg(itemId)}`, void 0, { signal });
 	}
-	async createBacklogItem(productId, body) {
-		return this.request("POST", `/products/${seg(productId)}/backlog`, {
-			...body,
-			productId
-		});
-	}
 	/** A person's move on the line board: the column dropped into, and what to follow there. */
 	async transitionInitiative(itemId, body) {
 		return this.request("PUT", `/backlog/${seg(itemId)}/state`, body);
@@ -283,9 +292,6 @@ var TaigaClient = class {
 	async stopBuildRun(id) {
 		return this.request("POST", `/builds/${seg(id)}/stop`);
 	}
-	async resumeBuildRun(id) {
-		return this.request("POST", `/builds/${seg(id)}/resume`);
-	}
 	async listBuildRunSteps(id) {
 		return this.request("GET", `/builds/${seg(id)}/steps`);
 	}
@@ -329,13 +335,6 @@ const READ_ONLY = {
 	idempotentHint: true,
 	openWorldHint: false
 };
-/** A write that adds or edits a row and starts nothing: a created initiative, a moved one. */
-const WRITE = {
-	readOnlyHint: false,
-	destructiveHint: false,
-	idempotentHint: false,
-	openWorldHint: false
-};
 /**
 * A write that starts or stops paid work, or opens the door to it: queueing
 * an initiative, approving a plan, resuming or stopping a run. Each starts
@@ -347,6 +346,14 @@ const OPERATE = {
 	idempotentHint: false,
 	openWorldHint: false
 };
+/**
+* An OPERATE write that sets a value rather than adding one: the same call
+* twice leaves things as one call does (a review gate set, a line paused).
+*/
+const OPERATE_SETTING = {
+	...OPERATE,
+	idempotentHint: true
+};
 //#endregion
 //#region src/tools/inputs.ts
 /** The inputs several tools share, so a product or a page is named the same way everywhere. */
@@ -617,15 +624,7 @@ const PR_CLOSING_STATES = [
 	"todo",
 	"canceled"
 ];
-/**
-* What `PUT /backlog/:id/state` accepts: the drops, plus `plan`.
-*
-* `plan` is not a column a person drops into any more, but it is still a state
-* the endpoint takes -- it is how the Build station is told to start over
-* ("Plan again"). One endpoint for both because they are the same write: the
-* initiative's state, decided by a person.
-*/
-const INITIATIVE_TRANSITION_STATES = [...USER_DROP_STATES, "plan"];
+[...USER_DROP_STATES];
 /** Longest rejection comment on a plan (PRO-1324): a paragraph of direction,
 *  small enough that the prompt section it becomes stays a section. */
 const PLAN_REJECTION_COMMENT_MAX_CHARS = 2e3;
@@ -965,6 +964,91 @@ const BUILD_RUN_ACTIVE_STATUSES = BUILD_RUN_STATUSES.filter((s) => runDispositio
 */
 const BUILD_RUN_TERMINAL_STATUSES = BUILD_RUN_STATUSES.filter((s) => runDisposition(s) !== "in_flight");
 [...BUILD_RUN_ACTIVE_STATUSES.filter((s) => s !== "reviewing")];
+//#endregion
+//#region ../../packages/types/dist/agents.js
+/**
+* Why a PROMPTED `generate_backlog` job planned nothing.
+*
+* A prompted add asks the planner a question, and "no new initiative" is one of
+* its honest answers -- the backlog already covers the request, the request is
+* not a piece of work, or it is outside what this project builds. None of those
+* is a failed job, so each arrives as a completed one carrying the reason.
+*
+* The INITIAL bulk generate has no prompt and no such answer: an empty backlog
+* there is a broken run and still fails.
+*/
+const BACKLOG_GENERATION_EMPTY_OUTCOMES = [
+	"already_covered",
+	"invalid_request",
+	"out_of_scope",
+	"needs_decision"
+];
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function isStringOrNull(value) {
+	return value === null || typeof value === "string";
+}
+function isDecisionReason(value) {
+	if (!isRecord$1(value)) return false;
+	const { policyCode, quotedSpan, conflict, alternative, overridePath } = value;
+	return [
+		policyCode,
+		quotedSpan,
+		conflict,
+		alternative,
+		overridePath
+	].every((f) => typeof f === "string");
+}
+function isCoveringInitiative(value) {
+	return isRecord$1(value) && typeof value.id === "string" && value.id.length > 0 && typeof value.title === "string" && typeof value.priority === "number";
+}
+/**
+* Narrow an `agent_jobs.result` blob to {@link BacklogGenerationEmptyResult}.
+*
+* The blob is whatever the worker stored, and the reader navigates on
+* `coveredInitiative.id` and renders `message`, so EVERY field is checked: a
+* blob that only has the right `outcome` is not this shape, and narrowing it
+* would hand the page an undefined id to navigate to.
+*/
+function isBacklogGenerationEmptyResult(value) {
+	if (!isRecord$1(value)) return false;
+	const { outcome, message, coveredByPriority, coveredById, coveredInitiative, reason } = value;
+	return typeof outcome === "string" && BACKLOG_GENERATION_EMPTY_OUTCOMES.includes(outcome) && isStringOrNull(message) && (coveredByPriority === null || typeof coveredByPriority === "number" && Number.isInteger(coveredByPriority)) && isStringOrNull(coveredById) && (coveredInitiative === null || isCoveringInitiative(coveredInitiative)) && (reason === null || reason === void 0 || isDecisionReason(reason));
+}
+/**
+* The initiatives a `generate_backlog` job created, from its stored result
+* (PRO-2483), or null when the result does not say: a job finished before the
+* worker recorded them, a verdict that created nothing, or a blob that is not
+* this shape. Every entry must be a non-empty string, or none is trusted --
+* the reader navigates on them.
+*/
+function createdInitiativeIdsOf(result) {
+	if (!isRecord$1(result)) return null;
+	const ids = result.createdInitiativeIds;
+	if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string" && id.length > 0)) return null;
+	return ids;
+}
+/**
+* The initiatives a `generate_backlog` run added, each with the title it was
+* created with, as the worker writes them on `agent_jobs.result.createdInitiatives`
+* (PRO-2496), in the order they were created: what a reader needs to NAME
+* them, where {@link createdInitiativeIdsOf} (PRO-2483) only links them.
+*
+* Null when the result carries no such list: a run from before PRO-2496, which
+* may still carry the ids alone, a run that added nothing (see
+* {@link isBacklogGenerationEmptyResult}), or a run still going. A list with a malformed entry is null too rather than partly
+* read, so a reader never links an undefined id.
+*/
+function createdInitiativesOf(result) {
+	if (!isRecord$1(result)) return null;
+	const list = result.createdInitiatives;
+	if (!Array.isArray(list) || list.length === 0) return null;
+	return list.every((entry) => isRecord$1(entry) && typeof entry.id === "string" && entry.id.length > 0 && typeof entry.title === "string") ? list.map((entry) => ({
+		id: entry.id,
+		title: entry.title
+	})) : null;
+}
 [...TURN_EVENT_TRIGGERS];
 //#endregion
 //#region ../../packages/types/dist/maintenance.js
@@ -2163,6 +2247,105 @@ function registerDocumentTools(server, client) {
 	}
 }
 //#endregion
+//#region src/tools/jobs.ts
+/** What a job says about itself: its kind, how far it got, and why it failed. */
+const JOB_FIELDS = [
+	"id",
+	"type",
+	"documentType",
+	"targetId",
+	"status",
+	"progress",
+	"progressMessage",
+	"error",
+	"queuePosition",
+	"createdAt",
+	"startedAt",
+	"completedAt",
+	"cancelledAt"
+];
+/** A job that will not change again: it finished, failed, or was cancelled. */
+const SETTLED_JOB_STATUSES = /* @__PURE__ */ new Set([
+	"completed",
+	"failed",
+	"cancelled"
+]);
+/**
+* What an initiative request came to, read off its finished job: the
+* initiatives it added, or the answer that added none (the backlog already
+* covers it, it is not work to build, it is outside the product, or one of
+* the organization's policies does not allow it as asked, with the policy's
+* own words and the way to decide otherwise). Null while the job runs, and
+* for a job that is not an initiative request.
+*/
+function requestOutcome(job) {
+	if (job.type !== "generate_backlog" || job.status !== "completed") return null;
+	const created = createdInitiativesOf(job.result);
+	if (created) return {
+		outcome: "created",
+		initiatives: created
+	};
+	const ids = createdInitiativeIdsOf(job.result);
+	if (ids && ids.length > 0) return {
+		outcome: "created",
+		initiatives: ids.map((id) => ({ id }))
+	};
+	if (isBacklogGenerationEmptyResult(job.result)) {
+		const result = job.result;
+		return {
+			outcome: result.outcome,
+			message: result.message,
+			coveredBy: result.coveredInitiative,
+			policy: result.reason ?? null
+		};
+	}
+	return {
+		outcome: "unknown",
+		note: "The job finished without a result this server can read."
+	};
+}
+/** A job as the tools hand it over: its own fields, and for an initiative request, what came of it. */
+function jobReport(job) {
+	const outcome = requestOutcome(job);
+	return {
+		...pickFields([job], JOB_FIELDS)[0],
+		...outcome ? { outcome } : {}
+	};
+}
+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: background work a person asked an agent for, such as an initiative request (taiga_request_initiatives). It says where the job is (pending, processing, completed, failed, cancelled), its progress and any error. A finished initiative request also says what came of it: the initiatives it added, or why it added none (already covered by an existing initiative, not readable as work, outside the product, or not allowed by a policy, with the policy, the line it runs into and the way to decide otherwise). taiga_wait_for_job waits for a job to finish.",
+		inputSchema: { jobId: z.string().uuid().describe("Agent job ID -- a request tool returns it") },
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data))));
+}
+//#endregion
+//#region src/tools/request-prompt.ts
+/**
+* The planner's prompt for an initiative request, built as the web builds it
+* (apps/web/src/features/loops/delivery/components/planning/generateBacklogJob.ts):
+* title and description trimmed, the description's inline-image markdown
+* removed and the blank lines it leaves collapsed, joined by a blank line.
+* The planner reads `userPrompt` and nothing else of the request, so the same
+* words must make the same prompt from either surface.
+*
+* The image pattern is the web's (inline-image-doc-ids.ts), which keeps it in
+* lockstep with the API's `extractInlineImageDocIds`: the `![...](...)` form,
+* an exact UUID, and a terminator after `/image`.
+*/
+const INLINE_IMAGE_RE = /!\[(?:[^\]\\]|\\.)*\]\([^)]*?\/custom-documents\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\/image(?=[)?#\s])[^)]*\)/g;
+/** The description without its inline images, as the web strips it. */
+function stripInlineImages(markdown) {
+	return markdown.replace(INLINE_IMAGE_RE, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** The prompt for a title and a description; undefined when both are empty, which asks for a suggestion. */
+function requestPrompt(title, description) {
+	const body = stripInlineImages((description ?? "").trim());
+	return [(title ?? "").trim(), body].filter(Boolean).join("\n\n") || void 0;
+}
+//#endregion
 //#region src/tools/queue.ts
 /** How many entries the read names; past this an entry keeps its backlogItemId only. */
 const NAMED_ENTRIES = 25;
@@ -2220,7 +2403,8 @@ function waitingOn(rows) {
 * rather than failing the queue.
 */
 async function queueView(client, product, options = { name: "all" }) {
-	const entries = (await client.listQueue(product)).data.filter((entry) => entry.state !== "settled");
+	const [queue, paused] = await Promise.all([client.listQueue(product), linePausedSince(client, product)]);
+	const entries = queue.data.filter((entry) => entry.state !== "settled");
 	const canName = client.hasCapability("backlog:read");
 	const blocking = blockingIndex(entries, (entry) => entry.state);
 	const toName = !canName ? [] : options.name === "all" ? entries.slice(0, NAMED_ENTRIES).map((_, index) => index) : blocking >= 0 ? [blocking] : [];
@@ -2271,20 +2455,52 @@ async function queueView(client, product, options = { name: "all" }) {
 		return row;
 	});
 	const note = unnamed === 0 ? null : !canName ? "Entries carry backlogItemId only: naming them needs backlog:read, which this key lacks." : entries.length > NAMED_ENTRIES ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry backlogItemId only.` : "An entry whose initiative could not be read carries backlogItemId only; taiga_get_backlog_item reads it.";
+	const line = typeof paused === "string" ? `The line is paused (since ${paused}): nothing is planned or built until a person resumes it.` : null;
 	return {
+		linePaused: paused === null ? null : typeof paused === "string",
 		entries: rows,
-		waitingOn: waitingOn(rows),
+		waitingOn: line ?? waitingOn(rows),
 		...note ? { note } : {}
 	};
 }
+/**
+* When the product's line was paused, false when it runs, null when the
+* product cannot be read (the queue is still worth reading without it).
+*/
+async function linePausedSince(client, product) {
+	try {
+		const row = (await client.getProduct(product)).data;
+		return typeof row.lineStoppedAt === "string" ? row.lineStoppedAt : false;
+	} catch (error) {
+		if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+		throw error;
+	}
+}
 function registerQueueTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_queue", {
 		title: "Get the product queue",
-		description: "Read a product's queue, the line the coding agent works one initiative at a time: each entry in order with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why it stopped and what lifts it, and waitingOn, one sentence saying what the line is waiting for. The line advances only when the active entry's pull request merges, so an entry waiting on a review holds everything behind it. Use this when a queued initiative is not moving.",
+		description: "Read a product's queue, the line the coding agent works one initiative at a time: each entry in order with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why it stopped and what lifts it, linePaused (null when the product could not be read), and waitingOn, one sentence saying what the line is waiting for. The line advances only when the active entry's pull request merges, so an entry waiting on a review holds everything behind it. Use this when a queued initiative is not moving.",
 		inputSchema: { productId },
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => toolResult(await queueView(client, params.productId))));
+	if (!client.hasCapability("products:write")) return;
+	server.registerTool("taiga_pause_line", {
+		title: "Pause or resume a product's line",
+		description: "Pause the product's whole line, or resume it. Pausing cancels the plan being written and stops the build in flight where it stands (both are flagged), and nothing more is planned or built; initiatives keep their places. Resuming plans the interrupted initiative again from scratch, carries the interrupted build on from its first incomplete step, and the line picks up where it was; a build you had stopped yourself before pausing stays stopped. Idempotent. Pausing interrupts work and resuming starts it: read taiga_get_queue first to see what it would interrupt, and ask the person.",
+		inputSchema: {
+			productId,
+			paused: z.boolean().describe("true pauses the line, false resumes it")
+		},
+		annotations: OPERATE_SETTING
+	}, (params) => runTool(async () => {
+		const row = (await client.setLineStopped(params.productId, params.paused)).data;
+		return toolResult({
+			productId: row.id,
+			linePaused: typeof row.lineStoppedAt === "string",
+			lineStoppedAt: row.lineStoppedAt ?? null
+		});
+	}));
 }
 //#endregion
 //#region src/tools/backlogs.ts
@@ -2352,23 +2568,32 @@ const outcomeOf = (item) => {
 const outcome = (item) => toolResult(outcomeOf(item));
 /**
 * Each tool is registered under the capability its route requires, so a
-* key sees exactly what it may call: reads on backlog:read, the create and
-* the board move on backlog:write, queueing on both backlog:write and
-* products:write (the state route checks both for a drop into queue), the
-* resume and the review gate on products:write alone, as their routes are
-* (the item ID they take also comes back from a create or a queue), and the plan verdicts on
-* products:write together with backlog:read, because the plan ID they take
-* comes only from the plan read: a key that cannot read plans has nothing
-* to feed them.
+* key sees exactly what it may call: reads on backlog:read; the board move on
+* backlog:write; queueing on both backlog:write and products:write (the
+* state route checks both for a drop into queue); an initiative request
+* (an agent job), the resume and the review gate on products:write alone, as
+* their routes are (the item ID they take also comes back from a request or a
+* queue); the plan verdicts on products:write together with backlog:read,
+* because the plan ID they take comes only from the plan read; and Plan again
+* on the state route's two (backlog:write, then products:write for a move
+* into plan) together with backlog:read, because it reads the initiative's
+* place at the Build station first.
+*
+* The tools follow how Taiga is meant to be used (docs.tai.ga, Deliver):
+* new work is described and an agent writes the initiative; the queue is
+* the only way to start work; a run is stopped by moving its initiative out
+* of Build and carried on from the initiative.
 */
 function registerBacklogTools(server, client) {
 	const may = (capability) => client.hasCapability(capability);
 	if (may("backlog:read")) registerBacklogReads(server, client);
-	if (may("backlog:write")) registerBacklogWrites(server, client);
+	if (may("backlog:write")) registerMove(server, client);
+	if (may("products:write")) registerRequest(server, client);
 	if (may("backlog:write") && may("products:write")) registerQueue(server, client);
 	if (may("products:write")) registerResume(server, client);
 	if (may("products:write")) registerReviewGate(server, client);
 	if (may("backlog:read") && may("products:write")) registerPlanVerdicts(server, client);
+	if (may("backlog:read") && may("backlog:write") && may("products:write")) registerPlanAgain(server, client);
 }
 function registerBacklogReads(server, client) {
 	server.registerTool("taiga_list_backlog_items", {
@@ -2428,46 +2653,65 @@ function registerBacklogReads(server, client) {
 		});
 	}));
 }
-function registerBacklogWrites(server, client) {
-	server.registerTool("taiga_create_backlog_item", {
-		title: "Create backlog item",
-		description: "Create an initiative in the Backlog column of a product: a title and a brief in Markdown (the problem, what it looks like, what it covers and leaves alone), its category, priority and estimate. It starts nothing: the planner reads it only once it is queued (taiga_queue_backlog_item) or moved to Plan (taiga_move_backlog_item). Returns the new item with its ID.",
+function registerRequest(server, client) {
+	server.registerTool("taiga_request_initiatives", {
+		title: "Request new initiatives",
+		description: "Add work the way Taiga adds it: describe it, and an agent turns the request into initiatives in the product's Backlog. The agent reads the product documents and its repository, expands the request into a full brief, and sizes it: one piece of work stays one initiative, a program of work comes back as an ordered set with its dependencies linked. It can also add nothing, and says why: an existing initiative already covers the request, the request is not readable as work, it is outside what the product builds, or one of the organization's policies does not allow it as asked (named, with the line it runs into and the way to decide otherwise). Leave both title and description out and the agent suggests the one next initiative the product most needs. It runs in the background, a few minutes: this returns the job, and taiga_wait_for_job or taiga_get_job (both need products:read) say what came of it. One request per product at a time (CONFLICT while one runs). Inline images in the description are left out; the web is where a request carries images. It starts nothing on the line: new initiatives land in Backlog. Runs an agent; ask the person first.",
 		inputSchema: {
 			productId,
-			title: z.string().min(1).max(500).describe("The initiative title, as it appears on the board"),
-			description: z.string().min(1).max(2e4).describe("The brief in Markdown: the problem, what it looks like, what it covers and leaves alone"),
-			category: z.enum([
-				"feature",
-				"bug",
-				"tech_debt",
-				"improvement"
-			]).optional().describe("What kind of work (default feature)"),
-			priority: z.number().int().min(1).optional().describe("1 is the most urgent (default 3)"),
-			estimate: z.number().int().min(0).optional().describe("Story points, 0 for unestimated (default 0)")
+			title: z.string().max(500).optional().describe("What the work is, in a line"),
+			description: z.string().max(2e4).optional().describe("The request in Markdown: the problem, what it should look like, what it covers and leaves alone")
 		},
-		annotations: WRITE
+		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		const { productId: id, ...body } = params;
-		return outcome((await client.createBacklogItem(id, body)).data);
+		const userPrompt = requestPrompt(params.title, params.description);
+		const job = (await client.createAgentJob({
+			scope: "product",
+			type: "generate_backlog",
+			targetId: params.productId,
+			...userPrompt ? { metadata: { userPrompt } } : {}
+		})).data;
+		return toolResult(jobReport(job));
 	}));
+}
+function registerMove(server, client) {
 	server.registerTool("taiga_move_backlog_item", {
 		title: "Move backlog item on the board",
-		description: `Move an initiative to a column, or order it within one: backlog and todo are the idle columns; queue puts it in the line (taiga_queue_backlog_item says more); plan starts planning now; done and canceled take it off the line. A move to ${PR_CLOSING_STATES.join(", ")} CLOSES a pull request the initiative is still waiting on (a move to queue keeps it, and done leaves it to be merged). The initiative state machine refuses a move that is not allowed (CONFLICT: build cannot be dropped into, an initiative being planned cannot leave plan). A move into queue or plan starts paid work and needs products:write on the key; a key without it is refused here. Ask the person before a move that starts work (queue, plan) or closes a pull request (${PR_CLOSING_STATES.join(", ")} from build). archived: true files the initiative where it stands (pass its current column as state; from any column off the line, never from plan or build) and archived: false brings it back; an archived initiative is left out of lists unless includeArchived asks for it.`,
+		description: `Move an initiative on the board, or order it within a column: backlog and todo are yours and the line never moves an initiative out of them; queue puts it in the line (taiga_queue_backlog_item says more); done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan being written or the run in flight: that is how work is stopped, and it throws that work away. A move to ${PR_CLOSING_STATES.join(", ")} CLOSES a pull request the initiative is still waiting on (a move to queue keeps it, and done leaves it to be merged); Taiga leaves a comment on the pull request saying why. The state machine refuses a move that is not allowed (CONFLICT). A move into queue starts paid work and needs products:write. Ask the person before a move that starts work, stops work or closes a pull request. archived: true files the initiative where it stands (pass its current column as state; never from the Build station, plan or build) and archived: false brings it back; archived work is left out of lists unless includeArchived asks for it.`,
 		inputSchema: {
 			itemId,
-			state: z.enum(INITIATIVE_TRANSITION_STATES).describe("The column to move into"),
+			state: z.enum(USER_DROP_STATES).describe("The column to move into"),
 			afterId: z.string().uuid().nullable().optional().describe("The initiative to follow in that column; null for the head; omit to keep rank order"),
 			archived: z.boolean().optional().describe("true files the initiative where it stands, false brings it back; omit to leave as is")
 		},
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
 		const { itemId: id, ...body } = params;
-		if (LINE_STARTING_STATES.has(body.state) && !client.hasCapability("products:write")) return toolError("FORBIDDEN", `A move into ${body.state} starts agent work and needs products:write, which this key lacks.`);
+		if (body.state === "queue" && !client.hasCapability("products:write")) return toolError("FORBIDDEN", "A move into queue starts agent work and needs products:write, which this key lacks.");
 		return outcome((await client.transitionInitiative(id, body)).data);
 	}));
 }
-/** The columns a drop into starts paid work, which the state route gates on products:write. */
-const LINE_STARTING_STATES = /* @__PURE__ */ new Set(["queue", "plan"]);
+/** The two halves of the Build station, where Plan again is offered. */
+const BUILD_STATION = /* @__PURE__ */ new Set(["plan", "build"]);
+function registerPlanAgain(server, client) {
+	server.registerTool("taiga_plan_again", {
+		title: "Plan an initiative again",
+		description: "Supersede the plan of the initiative at the Build station and ask the planner for a new one: for a plan that failed, a plan you do not want built, or a run whose direction was wrong once it has stopped. The earlier plan is kept, and every run records which plan version it built; a pull request still open stays open. Offered only when the turn is yours: refused (CONFLICT) while an agent holds it (planning, building, reviewing). Also refused while a dependency is still in flight or a UI direction has no chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the Build station, put the initiative in the queue instead (taiga_queue_backlog_item): the queue is the only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run; ask the person first.",
+		inputSchema: {
+			itemId,
+			force: z.boolean().optional().describe("Plan anyway past an unsettled dependency or an unchosen UI direction; only when the person says so")
+		},
+		annotations: OPERATE
+	}, (params) => runTool(async () => {
+		const item = (await client.getBacklogItem(params.itemId)).data;
+		if (!BUILD_STATION.has(String(item.state))) return toolError("CONFLICT", `This initiative is in ${String(item.state)}, not at the Build station. The queue is the only way to start work: put it in the queue with taiga_queue_backlog_item and it is planned when its turn comes.`);
+		const body = {
+			state: "plan",
+			...params.force ? { force: true } : {}
+		};
+		return outcome((await client.transitionInitiative(params.itemId, body)).data);
+	}));
+}
 /** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
 const isApiFailure$1 = (error) => error instanceof TaigaApiError || isNetworkFailure(error);
 /**
@@ -2542,7 +2786,7 @@ function registerReviewGate(server, client) {
 			itemId,
 			autoBuild: autoBuildInput
 		},
-		annotations: OPERATE
+		annotations: OPERATE_SETTING
 	}, (params) => runTool(async () => {
 		const item = (await client.setAutoBuild(params.itemId, params.autoBuild)).data;
 		const gate = await reviewGate(client, item);
@@ -2556,7 +2800,7 @@ function registerReviewGate(server, client) {
 function registerResume(server, client) {
 	server.registerTool("taiga_resume_backlog_item", {
 		title: "Resume backlog item",
-		description: "Resume an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first incomplete step, a refused build start is cleared and retried. Does whatever the named cause needs, so prefer it to taiga_resume_build when the initiative is flagged. Refused (CONFLICT) when nothing is flagged or the cause has no resume. Starts paid work; ask the person first.",
+		description: "Resume an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first incomplete step (the steps already committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a run is the record of an attempt, and decisions about the work are made on the initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume. Starts paid work; ask the person first.",
 		inputSchema: { itemId },
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.resumeInitiative(params.itemId)).data)));
@@ -2678,7 +2922,7 @@ function registerBuildTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_list_builds", {
 		title: "List build runs",
-		description: "List the coding agent's runs, newest first: status, branch, pull request, step progress and the actions a person may take on each (stop is taiga_stop_build; resume and retry_from_failed_step are both taiga_resume_build, the same route; start_over is only in the web UI for now). With productId, the runs of that product, optionally of one backlog item; without it, the runs of every product the key can see, each row naming its product, and active: true narrows to the runs executing right now. Use this to see what Taiga already built or is building, then read one run with taiga_get_build. A run of a deleted initiative keeps its title.",
+		description: "List the coding agent's runs, newest first: status, branch, pull request, step progress and the actions a person may take on each. A run is the record of an attempt: work is carried on from its initiative (resume and retry_from_failed_step are taiga_resume_backlog_item; start_over is in the web only for now) and stopped by moving the initiative out of Build; a maintenance run, which has no initiative, is retried from its finding. With productId, the runs of that product, optionally of one backlog item; without it, the runs of every product the key can see, each row naming its product, and active: true narrows to the runs executing right now. Use this to see what Taiga already built or is building, then read one run with taiga_get_build. A run of a deleted initiative keeps its title.",
 		inputSchema: {
 			productId: productId.optional(),
 			backlogItemId: z.string().uuid().optional().describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
@@ -2697,7 +2941,7 @@ function registerBuildTools(server, client) {
 	}));
 	server.registerTool("taiga_get_build", {
 		title: "Get build run",
-		description: "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, status, commit, files changed, checks, any error and headline, the first paragraph of what the agent reported. Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it opened. Its actions list says what it accepts: stop (taiga_stop_build), resume or retry_from_failed_step (both taiga_resume_build), start_over (web UI only for now).",
+		description: "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, status, commit, files changed, checks, any error and headline, the first paragraph of what the agent reported. Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it opened. Its actions name what the initiative accepts for it: resume and retry_from_failed_step are taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
 		inputSchema: {
 			buildId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions and report (default false: a summary)")
@@ -2721,20 +2965,12 @@ function registerBuildTools(server, client) {
 	if (!client.hasCapability("products:write")) return;
 	server.registerTool("taiga_stop_build", {
 		title: "Stop a build run",
-		description: "Stop a run the coding agent is executing: the agent halts, its branch and any draft pull request stay, and the run can be resumed later with taiga_resume_build. Only a run whose actions include stop (taiga_list_builds shows them); the API refuses the rest with CONFLICT. Ask the person before calling this: it interrupts work in progress.",
+		description: "The emergency brake: stop a run the coding agent is executing when its initiative cannot be moved. The way to stop work is on the initiative: move it out of Build (taiga_move_backlog_item), which stops the plan or run in flight. Use this only for a run whose initiative does not offer that (it is finished, canceled or gone) yet the run is still going. The agent halts, its branch and any draft pull request stay. Only a run whose actions include stop; the API refuses the rest with CONFLICT. Ask the person before calling this: it interrupts work in progress.",
 		inputSchema: { buildId },
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
 		return toolResult(pickFields([(await client.stopBuildRun(params.buildId)).data], RUN_OUTCOME_FIELDS)[0]);
 	}));
-	server.registerTool("taiga_resume_build", {
-		title: "Resume a build run",
-		description: "Resume a stopped or failed run from its first incomplete step: the agent starts again on the same branch, which spends tokens and may push commits and open a pull request. This is the route behind both the resume and the retry_from_failed_step actions: the API accepts a run whose actions include one of them and refuses the rest with CONFLICT. start_over (a new run) is web-only for now. For an initiative the line stopped on, taiga_resume_backlog_item does whatever its cause needs instead. Ask the person before calling this.",
-		inputSchema: { buildId },
-		annotations: OPERATE
-	}, (params) => runTool(async () => {
-		return toolResult(pickFields([(await client.resumeBuildRun(params.buildId)).data], RUN_OUTCOME_FIELDS)[0]);
-	}));
 }
 //#endregion
 //#region src/tools/context.ts
@@ -18009,6 +18245,7 @@ function itemSignature(item) {
 		item.state,
 		item.planningStatus,
 		item.needsHumanCause,
+		item.autoBuild,
 		lifecycle.stage,
 		lifecycle.turn,
 		lifecycle.cta,
@@ -18206,6 +18443,25 @@ function registerWaitTools(server, client, options) {
 			run: now ? 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): an initiative request, a document, a refresh. Returns the job as taiga_get_job reads it, with what came of an initiative request, as soon as it settles (reached: true), or at the timeout with reached: false: call again to keep waiting. Most jobs take a few minutes.",
+		inputSchema: {
+			jobId: z.string().uuid().describe("Agent job ID -- a request tool returns it"),
+			timeoutSeconds
+		},
+		annotations: READ_ONLY
+	}, (params, extra) => 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, {
+			progressToken: extra._meta?.progressToken,
+			sendNotification: extra.sendNotification,
+			signal: extra.signal
+		});
+		return toolResult({
+			...outcome,
+			job: now ? jobReport(now) : null
+		});
+	}));
 }
 //#endregion
 //#region src/tools/index.ts
@@ -18241,6 +18497,7 @@ function registerAllTools(server, client, options = {}) {
 	registerBacklogTools(server, client);
 	registerBuildTools(server, client);
 	registerQueueTools(server, client);
+	registerJobTools(server, client);
 	registerWaitTools(server, client, options.wait ?? DEFAULT_WAIT_OPTIONS);
 	registerContextTools(server, client);
 	registerResources(server, client);
@@ -18286,20 +18543,26 @@ const SERVER_INSTRUCTIONS = [
 	"for them: runs, steps, commits and pull requests. taiga_list_builds without a product lists the runs of",
 	"every product the key can see, and active: true the ones executing now.",
 	"",
-	"**Operating the line** (taiga_create_backlog_item / taiga_queue_backlog_item / taiga_move_backlog_item /",
-	"taiga_resume_backlog_item / taiga_set_auto_build / taiga_get_plan / taiga_approve_plan / taiga_reject_plan /",
-	"taiga_stop_build / taiga_resume_build): create an initiative, put it in the queue the coding agent works,",
-	"move it on the board, decide whether its plan waits for a review (autoBuild: false) or is built at once, read",
-	"and approve or reject its plan, stop or resume a run. Queueing, approving and resuming start paid agent work",
-	"that pushes commits and opens pull requests; stopping interrupts it. Tell the person what you are about to",
-	"start or stop and wait for their yes before calling these; a client that prompts on destructive tools does",
-	"that for you. A refusal (CONFLICT) carries the API reason: say it as it is.",
+	"**Operating the line** works the way Taiga is meant to be used. New work is described, not written:",
+	"taiga_request_initiatives asks an agent, which reads the product and its repository, expands the request",
+	"into initiatives in the Backlog (or says why it added none: already covered, not work, out of scope, or a",
+	"policy that does not allow it) -- follow it with taiga_wait_for_job. The queue is the only way to start",
+	"work (taiga_queue_backlog_item): Taiga plans and builds one initiative at a time, in queue order, and starts",
+	"the next when the pull request merges. Whether a landed plan waits for a review is the review gate",
+	"(taiga_set_auto_build, or autoBuild on the queue); read it with taiga_get_plan and answer with",
+	"taiga_approve_plan or taiga_reject_plan. Decisions about the work are made on the initiative: stop work by",
+	"moving it out of Build (taiga_move_backlog_item), carry it on with taiga_resume_backlog_item, ask for a new",
+	"plan with taiga_plan_again; a run is the record of an attempt. taiga_pause_line pauses the whole line.",
+	"taiga_stop_build is the emergency brake for a run whose initiative cannot be moved. Queueing, approving,",
+	"resuming and requesting start paid agent work; stopping and pausing interrupt it. Tell the person what you",
+	"are about to start or stop and wait for their yes; a client that prompts on destructive tools does that",
+	"for you. A refusal (CONFLICT) carries the API reason: say it as it is.",
 	"",
-	"**Watching the line** (taiga_get_queue / taiga_wait_for_backlog_item / taiga_wait_for_build): the queue",
-	"read says what the line is waiting on (a plan to review, a pull request to merge, a halt and what lifts",
-	"it). Planning takes minutes and a build up to an hour: wait with the wait tools rather than reading the",
-	"same item again and again; each returns when the point is reached, when only a person can move it on,",
-	"or at its timeout (call again to keep waiting).",
+	"**Watching the line** (taiga_get_queue / taiga_wait_for_backlog_item / taiga_wait_for_build /",
+	"taiga_get_job / taiga_wait_for_job): the queue read says what the line is waiting on (a paused line, a plan",
+	"to review, a pull request to merge, a halt and what lifts it). Planning takes minutes and a build up to an",
+	"hour: wait with the wait tools rather than reading the same item again and again; each returns when the",
+	"point is reached, when only a person can move it on, or at its timeout (call again to keep waiting).",
 	"",
 	"**Sections.** Policies and instructions are maps of sections. Each section carries its text and two",
 	"provenance fields you can read past: `source` says where the text originally came from (template:",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.12.0-dev.421",
+  "version": "0.13.0-dev.422",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",