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

package/src/tools/backlogs.ts

@@ -1,15 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
-import {
-  INITIATIVE_TRANSITION_STATES,
-  PLAN_REJECTION_COMMENT_MAX_CHARS,
-  PR_CLOSING_STATES,
-  resolveAutoBuild,
-} from '@taiga/types';
-import { OPERATE, READ_ONLY, WRITE } from './annotations.js';
+import { PLAN_REJECTION_COMMENT_MAX_CHARS, PR_CLOSING_STATES, USER_DROP_STATES, resolveAutoBuild } from '@taiga/types';
+import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { pagination, productId } from './inputs.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { jobReport } from './jobs.js';
+import { requestPrompt } from './request-prompt.js';
 import { queueView } from './queue.js';
 import { criteriaCounts, itemRows, page, pickFields } from './summarize.js';
 
@@ -74,23 +71,32 @@ const outcome = (item: unknown) => 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.
  */
 export function registerBacklogTools(server: McpServer, client: TaigaClient) {
   const may = (capability: string) => 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: McpServer, client: TaigaClient) {
@@ -179,59 +185,71 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
   );
 }
 
-function registerBacklogWrites(server: McpServer, client: TaigaClient) {
+function registerRequest(server: McpServer, client: TaigaClient) {
   server.registerTool(
-    'taiga_create_backlog_item',
+    'taiga_request_initiatives',
     {
-      title: 'Create backlog item',
+      title: 'Request new initiatives',
       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.',
+        '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'),
+        title: z.string().max(500).optional().describe('What the work is, in a line'),
         description: z
           .string()
-          .min(1)
           .max(20_000)
-          .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)'),
+          .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 as Record<string, unknown>;
+        return toolResult(jobReport(job));
       })
   );
+}
 
+function registerMove(server: McpServer, client: TaigaClient) {
   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.',
+        '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()
@@ -248,13 +266,13 @@ function registerBacklogWrites(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const { itemId: id, ...body } = params;
-        // What the route checks on top of backlog:write for these two
-        // columns; refused here so the model learns which capability, not
-        // just that it was forbidden.
-        if (LINE_STARTING_STATES.has(body.state) && !client.hasCapability('products:write')) {
+        // What the route checks on top of backlog:write for a drop into the
+        // queue; refused here so the model learns which capability, not just
+        // that it was forbidden.
+        if (body.state === 'queue' && !client.hasCapability('products:write')) {
           return toolError(
             'FORBIDDEN',
-            `A move into ${body.state} starts agent work and needs products:write, which this key lacks.`
+            'A move into queue starts agent work and needs products:write, which this key lacks.'
           );
         }
         return outcome((await client.transitionInitiative(id, body)).data);
@@ -262,8 +280,50 @@ function registerBacklogWrites(server: McpServer, client: TaigaClient) {
   );
 }
 
-/** The columns a drop into starts paid work, which the state route gates on products:write. */
-const LINE_STARTING_STATES: ReadonlySet<string> = new Set(['queue', 'plan']);
+/** The two halves of the Build station, where Plan again is offered. */
+const BUILD_STATION: ReadonlySet<string> = new Set(['plan', 'build']);
+
+function registerPlanAgain(server: McpServer, client: TaigaClient) {
+  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 as Record<string, unknown>;
+        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 = (error: unknown) => error instanceof TaigaApiError || isNetworkFailure(error);
@@ -385,7 +445,7 @@ function registerReviewGate(server: McpServer, client: TaigaClient) {
         'initiative gets, including one being written now. Opening the gate on a plan that is already waiting ' +
         'starts its build, so ask the person first. Returns the initiative with the gate that now applies.',
       inputSchema: { itemId, autoBuild: autoBuildInput },
-      annotations: OPERATE,
+      annotations: OPERATE_SETTING,
     },
     (params) =>
       runTool(async () => {
@@ -407,10 +467,10 @@ function registerResume(server: McpServer, client: TaigaClient) {
       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.',
+        '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,
     },

package/src/tools/builds.ts

@@ -132,8 +132,10 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
       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, ' +
+        '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. ' +
@@ -191,8 +193,9 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         '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).',
+        '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
@@ -229,10 +232,12 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       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.',
+        '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,
     },
@@ -242,25 +247,4 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         return toolResult(pickFields([result.data as Record<string, unknown>], 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 () => {
-        const result = await client.resumeBuildRun(params.buildId);
-        return toolResult(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]);
-      })
-  );
 }

package/src/tools/index.ts

@@ -6,6 +6,7 @@ import { registerDocumentTools } from './documents.js';
 import { registerBacklogTools } from './backlogs.js';
 import { registerBuildTools } from './builds.js';
 import { registerContextTools } from './context.js';
+import { registerJobTools } from './jobs.js';
 import { registerPrompts } from './prompts.js';
 import { registerQueueTools } from './queue.js';
 import { registerResources } from './resources.js';
@@ -45,6 +46,7 @@ export function registerAllTools(server: McpServer, client: TaigaClient, 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);

package/src/tools/instructions.ts

@@ -46,20 +46,26 @@ export 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/src/tools/jobs.ts

@@ -0,0 +1,89 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createdInitiativeIdsOf, createdInitiativesOf, isBacklogGenerationEmptyResult } from '@taiga/types';
+import { z } from 'zod';
+import type { TaigaClient } from '../client.js';
+import { READ_ONLY } from './annotations.js';
+import { runTool, toolResult } from './errors.js';
+import { pickFields } from './summarize.js';
+
+/**
+ * Agent jobs: the background work a person asks an agent for (an initiative
+ * request, a document, a refresh). The job is the record of that ask: where
+ * it is, and what came of it.
+ */
+
+type Row = Record<string, unknown>;
+
+/** 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',
+] as const;
+
+/** A job that will not change again: it finished, failed, or was cancelled. */
+export const SETTLED_JOB_STATUSES: ReadonlySet<string> = 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: Row): Row | null {
+  if (job.type !== 'generate_backlog' || job.status !== 'completed') return null;
+  const created = createdInitiativesOf(job.result);
+  if (created) return { outcome: 'created', initiatives: created };
+  // A job finished before the result carried titles has the ids alone.
+  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. */
+export function jobReport(job: Row): Row {
+  const outcome = requestOutcome(job);
+  return { ...pickFields([job], JOB_FIELDS)[0], ...(outcome ? { outcome } : {}) };
+}
+
+export function registerJobTools(server: McpServer, client: TaigaClient) {
+  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 as Row)))
+  );
+}

package/src/tools/queue.ts

@@ -1,7 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { HALT_CAUSES, canResumeHalt, haltClearsItself, renderHalt, type Halt, type HaltCause } from '@taiga/types';
 import { TaigaApiError, type TaigaClient } from '../client.js';
-import { READ_ONLY } from './annotations.js';
+import { z } from 'zod';
+import { OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { productId } from './inputs.js';
 import { criteriaCounts } from './summarize.js';
@@ -84,7 +85,8 @@ export async function queueView(
   product: string,
   options: { name: 'all' | 'blocking' } = { name: 'all' }
 ) {
-  const entries = ((await client.listQueue(product)).data as Row[]).filter((entry) => entry.state !== 'settled');
+  const [queue, paused] = await Promise.all([client.listQueue(product), linePausedSince(client, product)]);
+  const entries = (queue.data as Row[]).filter((entry) => entry.state !== 'settled');
   const canName = client.hasCapability('backlog:read');
   // 'blocking' names only the entry the line waits on: a caller after one
   // position and waitingOn need no more reads than that.
@@ -144,7 +146,31 @@ export async function queueView(
         : 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.';
-  return { entries: rows, waitingOn: waitingOn(rows), ...(note ? { note } : {}) };
+  // A paused line answers before anything in it: nothing is planned or built until it is resumed.
+  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: 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: TaigaClient, product: string): Promise<string | false | null> {
+  try {
+    const row = (await client.getProduct(product)).data as { lineStoppedAt?: unknown };
+    return typeof row.lineStoppedAt === 'string' ? row.lineStoppedAt : false;
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+    throw error;
+  }
 }
 
 export function registerQueueTools(server: McpServer, client: TaigaClient) {
@@ -157,7 +183,8 @@ export function registerQueueTools(server: McpServer, client: TaigaClient) {
       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 ' +
+        '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 },
@@ -165,4 +192,34 @@ export function registerQueueTools(server: McpServer, client: TaigaClient) {
     },
     (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 as Row;
+        return toolResult({
+          productId: row.id,
+          linePaused: typeof row.lineStoppedAt === 'string',
+          lineStoppedAt: row.lineStoppedAt ?? null,
+        });
+      })
+  );
 }

package/src/tools/request-prompt.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { requestPrompt, stripInlineImages } from './request-prompt.js';
+
+const IMAGE = '![shot](/v1/custom-documents/0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c/image)';
+
+describe('requestPrompt', () => {
+  it('joins the trimmed title and description with a blank line', () => {
+    expect(requestPrompt('  Add login ', ' Users log in.  ')).toBe('Add login\n\nUsers log in.');
+  });
+
+  it('is undefined when both are empty, which asks the agent for a suggestion', () => {
+    expect(requestPrompt('   ', '\n\n')).toBeUndefined();
+    expect(requestPrompt(undefined, undefined)).toBeUndefined();
+  });
+
+  it('drops inline images and collapses the blank lines they and the author left', () => {
+    expect(requestPrompt('T', `Before\n\n${IMAGE}\n\n\n\nAfter`)).toBe('T\n\nBefore\n\nAfter');
+  });
+});
+
+describe('stripInlineImages', () => {
+  it('keeps an image that is not a Taiga inline image, and a link to one that is not an image', () => {
+    const external = '![logo](https://example.com/logo.png)';
+    const download = '[file](/v1/custom-documents/0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c/image)';
+    expect(stripInlineImages(`${external} ${download}`)).toBe(`${external} ${download}`);
+  });
+
+  it('does not take /imagefoo or /image/download for an inline image', () => {
+    const near = '![x](/v1/custom-documents/0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c/image/download)';
+    expect(stripInlineImages(near)).toBe(near);
+  });
+});