@taiga-ai/mcp-server 0.9.0 → 0.10.0-rc.405

package/src/server.integration.test.ts

@@ -17,6 +17,8 @@ const ALL_CAPABILITIES = [
   'tenant:documents:read',
   'tenant:documents:write',
   'backlog:read',
+  'backlog:write',
+  'products:write',
 ];
 
 /**
@@ -24,10 +26,13 @@ const ALL_CAPABILITIES = [
  * sorted for deterministic comparison.
  */
 const ALL_TOOL_NAMES = [
+  'taiga_approve_plan',
+  'taiga_create_backlog_item',
   'taiga_get_backlog_item',
   'taiga_get_build',
   'taiga_get_document',
   'taiga_get_factory_document',
+  'taiga_get_plan',
   'taiga_get_product',
   'taiga_get_product_context',
   'taiga_get_product_document',
@@ -38,9 +43,15 @@ const ALL_TOOL_NAMES = [
   'taiga_list_factory_documents',
   'taiga_list_product_documents',
   'taiga_list_products',
+  'taiga_move_backlog_item',
   'taiga_publish_document',
   'taiga_publish_factory_document',
+  'taiga_queue_backlog_item',
+  'taiga_reject_plan',
   'taiga_resolve_product',
+  'taiga_resume_backlog_item',
+  'taiga_resume_build',
+  'taiga_stop_build',
   'taiga_update_document',
   'taiga_update_factory_document',
 ];
@@ -87,6 +98,15 @@ function sentBody(fetchSpy: ReturnType<typeof vi.fn>, method: string, pathPart:
   return JSON.parse((call![1] as RequestInit).body as string);
 }
 
+/** What the API answers when it refuses: the status and the error envelope its error handler sends. */
+class Refusal {
+  constructor(
+    readonly status: number,
+    readonly body: { error: string; code: string; message: string }
+  ) {}
+}
+const refusal = (status: number, code: string, message: string) => new Refusal(status, { error: code, code, message });
+
 function makeFetchRouter(routes: Record<string, unknown>) {
   return vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
     const { pathname: path, search } = new URL(url);
@@ -94,6 +114,17 @@ function makeFetchRouter(routes: Record<string, unknown>) {
     // Most specific first: a route keyed with its query string (the two
     // document timelines share a path) wins over one keyed by path alone.
     const body = routes[`${method} ${path}${search}`] ?? routes[`${method} ${path}`] ?? routes[path];
+    // A route given as a function answers or throws like fetch would.
+    if (typeof body === 'function') return (body as () => unknown)();
+    // A refusal the API would send, with its status: `refusal(409, {...})`.
+    if (body instanceof Refusal) {
+      return {
+        ok: false,
+        status: body.status,
+        json: () => Promise.resolve(body.body),
+        text: () => Promise.resolve(JSON.stringify(body.body)),
+      };
+    }
     if (body !== undefined) {
       return {
         ok: true,
@@ -325,13 +356,18 @@ describe('MCP server integration', () => {
         'taiga_list_builds',
         'taiga_get_build',
       ],
-      'backlog:read': ['taiga_list_backlog_items', 'taiga_get_backlog_item'],
+      'backlog:read': ['taiga_list_backlog_items', 'taiga_get_backlog_item', 'taiga_get_plan'],
       'factories:read': ['taiga_list_factories', 'taiga_list_factory_documents', 'taiga_get_factory_document'],
       'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document'],
     };
     const PAIRED_CONTRACT: Record<string, string[]> = {
       'tenant:documents:read tenant:documents:write': ['taiga_update_document', 'taiga_publish_document'],
       'factories:read factories:documents:write': ['taiga_update_factory_document', 'taiga_publish_factory_document'],
+      'backlog:write': ['taiga_create_backlog_item', 'taiga_move_backlog_item'],
+      'backlog:write products:write': ['taiga_queue_backlog_item'],
+      'products:write': ['taiga_resume_backlog_item'],
+      'backlog:read products:write': ['taiga_approve_plan', 'taiga_reject_plan'],
+      'products:read products:write': ['taiga_stop_build', 'taiga_resume_build'],
     };
 
     for (const [capability, expectedTools] of [...Object.entries(CONTRACT), ...Object.entries(PAIRED_CONTRACT)]) {
@@ -2456,8 +2492,29 @@ describe('MCP server integration', () => {
       const failure = await client.getPrompt({ name: 'taiga_start_session', arguments: {} }).catch((e: unknown) => e);
 
       expect(failure).toMatchObject({ code: -32602 });
+      // A slash command with no argument lands here; the message says how to pass one.
       expect(String((failure as Error).message)).toMatch(
-        /^MCP error -32602: VALIDATION_FAILED: Name the product exactly once/
+        /^MCP error -32602: VALIDATION_FAILED: Name the product exactly once: slug or productId or remoteUrl\. Pass the slug as the first argument \(\/taiga_start_session <slug>/
+      );
+    });
+
+    it('should take the slug as the first prompt argument, for a client that passes them positionally', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes });
+
+      const prompt = (await client.listPrompts()).prompts.find((p) => p.name === 'taiga_start_session')!;
+
+      expect(prompt.arguments!.map((a) => a.name)).toEqual(['slug', 'productId', 'remoteUrl']);
+    });
+
+    it('should still refuse two names at once', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes });
+
+      const failure = await client
+        .getPrompt({ name: 'taiga_start_session', arguments: { slug: 'web', productId: PRODUCT_ID } })
+        .catch((e: unknown) => e);
+
+      expect(String((failure as Error).message)).toMatch(
+        /Name the product exactly once: slug or productId or remoteUrl/
       );
     });
 
@@ -2557,6 +2614,612 @@ describe('MCP server integration', () => {
     });
   });
 
+  describe('operating the line', () => {
+    const PLAN_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60';
+    const OTHER_ITEM = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a61';
+    const lifecycle = { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null };
+    const item = {
+      id: ITEM_ID,
+      productId: PRODUCT_ID,
+      title: 'Add login',
+      description: 'A long brief the outcome must not echo',
+      status: 'backlog',
+      state: 'backlog',
+      planningStatus: 'unplanned',
+      needsHumanCause: null,
+      needsHumanDetail: null,
+      acceptanceCriteria: [{ criterion: 'Users can log in', met: false }],
+      technicalContext: { patterns: ['hexagonal'] },
+      lifecycle,
+    };
+    const queued = { ...item, state: 'queue', status: 'in_progress' };
+    const plan = {
+      id: PLAN_ID,
+      backlogItemId: ITEM_ID,
+      version: 1,
+      status: 'active',
+      steps: [{ id: 'step-1', planId: PLAN_ID, title: 'Add the route', writes: ['src/routes/login.ts'] }],
+    };
+    const run = {
+      id: BUILD_ID,
+      runNumber: 1,
+      productId: PRODUCT_ID,
+      backlogItemId: ITEM_ID,
+      targetTitle: 'Add login',
+      status: 'implementing',
+      failedReason: null,
+      completedSteps: 1,
+      totalSteps: 3,
+      prUrl: null,
+      actions: ['stop'],
+      error: 'noise the row must not carry',
+      metrics: { tokens: 1 },
+    };
+    const outcomeOf = (result: Record<string, unknown>) => parseToolResult(result);
+
+    it('should mark every tool that starts or stops agent work destructive, and the create not', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const { tools } = await client.listTools();
+      const byName = Object.fromEntries(tools.map((t) => [t.name, t.annotations]));
+
+      for (const name of [
+        'taiga_queue_backlog_item',
+        'taiga_move_backlog_item',
+        'taiga_resume_backlog_item',
+        'taiga_approve_plan',
+        'taiga_reject_plan',
+        'taiga_stop_build',
+        'taiga_resume_build',
+      ]) {
+        expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: false });
+      }
+      expect(byName.taiga_create_backlog_item).toMatchObject({ readOnlyHint: false, destructiveHint: false });
+      expect(byName.taiga_get_plan).toMatchObject({ readOnlyHint: true });
+    });
+
+    it('should create an initiative in the product and answer with where it stands, not the brief', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`POST /v1/products/${PRODUCT_ID}/backlog`]: { data: item } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_create_backlog_item',
+        arguments: {
+          productId: PRODUCT_ID,
+          title: 'Add login',
+          description: 'Users log in.',
+          category: 'feature',
+          priority: 2,
+        },
+      });
+
+      expect(result.isError).toBeFalsy();
+      // The route wants the product in the body as well as the path.
+      expect(sentBody(fetchSpy, 'POST', `/products/${PRODUCT_ID}/backlog`)).toEqual({
+        productId: PRODUCT_ID,
+        title: 'Add login',
+        description: 'Users log in.',
+        category: 'feature',
+        priority: 2,
+      });
+      const outcome = outcomeOf(result);
+      expect(outcome).toMatchObject({ id: ITEM_ID, state: 'backlog', lifecycle });
+      expect(outcome).not.toHaveProperty('description');
+      expect(outcome).not.toHaveProperty('acceptanceCriteria');
+    });
+
+    it('should refuse a create with no title or a brief past the limit before any request', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+      const before = fetchSpy.mock.calls.length;
+
+      for (const args of [
+        { productId: PRODUCT_ID, title: '', description: 'x' },
+        { productId: PRODUCT_ID, title: 'T', description: 'x'.repeat(20_001) },
+      ]) {
+        const result = await client.callTool({ name: 'taiga_create_backlog_item', arguments: args });
+        expect(result.isError).toBe(true);
+      }
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should queue an initiative with the move the web makes and answer with the refreshed item', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: queued } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } });
+
+      expect(result.isError).toBeFalsy();
+      // One write, no read around it: the route answers with the item.
+      expect(fetchSpy.mock.calls.filter((c: unknown[]) => (c[0] as string).includes('/backlog/'))).toHaveLength(1);
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'queue' });
+      expect(outcomeOf(result)).toMatchObject({ id: ITEM_ID, state: 'queue', status: 'in_progress' });
+      expect(outcomeOf(result)).not.toHaveProperty('description');
+    });
+
+    it('should place a queued initiative after another, or at the head with null', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: queued } },
+      });
+
+      await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID, afterId: OTHER_ITEM } });
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'queue', afterId: OTHER_ITEM });
+
+      fetchSpy.mockClear();
+      vi.stubGlobal('fetch', fetchSpy);
+      await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID, afterId: null } });
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'queue', afterId: null });
+    });
+
+    it("should hand the model the API's refusal when the initiative cannot move into the queue", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: refusal(409, 'CONFLICT', 'Stop the running agent before re-planning'),
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({ error: 'CONFLICT', message: 'Stop the running agent before re-planning' });
+    });
+
+    it('should report an item the key cannot see as a miss', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const result = await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result).error).toBe('NOT_FOUND');
+    });
+
+    it('should hide the queue from a key that may write the backlog but not start work, and the verdicts from one that cannot read the IDs they take', async () => {
+      const backlogOnly = await bootMcpPair({ capabilities: ['backlog:write'] });
+      const operatorOnly = await bootMcpPair({ capabilities: ['products:write'] });
+
+      expect(toolNames((await backlogOnly.client.listTools()).tools)).toEqual([
+        'taiga_create_backlog_item',
+        'taiga_move_backlog_item',
+      ]);
+      // The resume takes an item ID a create or a queue hands back, so it needs no backlog read;
+      // the verdicts take a plan ID only the plan read gives.
+      expect(toolNames((await operatorOnly.client.listTools()).tools)).toEqual(['taiga_resume_backlog_item']);
+    });
+
+    it('should move an initiative into plan with a full key, and refuse queue or plan for a key without products:write before any request', async () => {
+      const full = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...item, state: 'plan', planningStatus: 'planning' } },
+        },
+      });
+      const planned = await full.client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'plan' },
+      });
+      expect(planned.isError).toBeFalsy();
+      expect(sentBody(full.fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'plan' });
+      expect(outcomeOf(planned)).toMatchObject({ state: 'plan', planningStatus: 'planning' });
+
+      const narrow = await bootMcpPair({ capabilities: ['backlog:read', 'backlog:write'] });
+      const before = narrow.fetchSpy.mock.calls.length;
+      for (const state of ['queue', 'plan']) {
+        const result = await narrow.client.callTool({
+          name: 'taiga_move_backlog_item',
+          arguments: { itemId: ITEM_ID, state },
+        });
+        expect(result.isError, state).toBe(true);
+        expect(outcomeOf(result)).toEqual({
+          error: 'FORBIDDEN',
+          message: `A move into ${state} starts agent work and needs products:write, which this key lacks.`,
+        });
+      }
+      expect(narrow.fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it("should pass on the API's refusal of a create, a resume, a rejection and a run resume alike", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`POST /v1/products/${PRODUCT_ID}/backlog`]: refusal(400, 'VALIDATION_ERROR', 'title too long'),
+          [`POST /v1/backlog/${ITEM_ID}/resume`]: refusal(
+            409,
+            'CONFLICT',
+            'This initiative is not stopped, so there is nothing to resume.'
+          ),
+          [`POST /v1/plans/${PLAN_ID}/reject`]: refusal(409, 'CONFLICT', 'This plan has been replaced'),
+          [`POST /v1/builds/${BUILD_ID}/resume`]: refusal(409, 'CONFLICT', 'Build run is not resumable'),
+        },
+      });
+
+      const calls = [
+        [
+          'taiga_create_backlog_item',
+          { productId: PRODUCT_ID, title: 'T', description: 'D' },
+          'VALIDATION_ERROR',
+          'title too long',
+        ],
+        [
+          'taiga_resume_backlog_item',
+          { itemId: ITEM_ID },
+          'CONFLICT',
+          'This initiative is not stopped, so there is nothing to resume.',
+        ],
+        ['taiga_reject_plan', { planId: PLAN_ID, comment: 'Again' }, 'CONFLICT', 'This plan has been replaced'],
+        ['taiga_resume_build', { buildId: BUILD_ID }, 'CONFLICT', 'Build run is not resumable'],
+      ] as const;
+      for (const [name, args, error, message] of calls) {
+        const result = await client.callTool({ name, arguments: { ...args } });
+        expect(result.isError, name).toBe(true);
+        expect(outcomeOf(result), name).toEqual({ error, message });
+      }
+    });
+
+    it('should move an initiative on the board with the column and the neighbour to follow', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...item, state: 'todo' } } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'todo', afterId: null },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'todo', afterId: null });
+      expect(outcomeOf(result)).toMatchObject({ state: 'todo' });
+    });
+
+    it('should offer exactly the columns a person may drop into, and refuse build', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const { tools } = await client.listTools();
+      const move = tools.find((t) => t.name === 'taiga_move_backlog_item')!;
+      const props = move.inputSchema.properties as Record<string, { enum?: string[] }>;
+      expect(props.state!.enum).toEqual(['backlog', 'todo', 'queue', 'done', 'canceled', 'plan']);
+
+      const before = fetchSpy.mock.calls.length;
+      const result = await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'build' },
+      });
+      expect(result.isError).toBe(true);
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should pass the API refusal through when scope membership forbids a move', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: refusal(403, 'FORBIDDEN', 'Not a member of this product'),
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'todo' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({ error: 'FORBIDDEN', message: 'Not a member of this product' });
+    });
+
+    it('should resume an initiative the line stopped on and answer with the lifecycle', async () => {
+      const resumed = { ...item, needsHumanCause: null, lifecycle: { ...lifecycle, stage: 'building', turn: 'agent' } };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`POST /v1/backlog/${ITEM_ID}/resume`]: { data: resumed } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_resume_backlog_item', arguments: { itemId: ITEM_ID } });
+
+      expect(result.isError).toBeFalsy();
+      const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).endsWith('/resume'))!;
+      expect((call[1] as RequestInit).method).toBe('POST');
+      expect((call[1] as RequestInit).body).toBeNull();
+      expect(outcomeOf(result).lifecycle).toEqual(resumed.lifecycle);
+    });
+
+    it('should read the active plan with its steps and say when there is none', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: {
+          [`GET /v1/backlog/${ITEM_ID}/plans/active`]: { data: plan },
+          [`GET /v1/backlog/${OTHER_ITEM}/plans/active`]: refusal(404, 'NOT_FOUND', 'No active plan found'),
+        },
+      });
+
+      const found = await client.callTool({ name: 'taiga_get_plan', arguments: { itemId: ITEM_ID } });
+      expect(outcomeOf(found)).toEqual(plan);
+
+      const none = await client.callTool({ name: 'taiga_get_plan', arguments: { itemId: OTHER_ITEM } });
+      expect(none.isError).toBe(true);
+      expect(outcomeOf(none)).toEqual({ error: 'NOT_FOUND', message: 'No active plan found' });
+    });
+
+    it('should approve a plan by its ID and reject one with the comment', async () => {
+      const building = { ...item, status: 'in_progress', state: 'build', planningStatus: 'planned' };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`POST /v1/plans/${PLAN_ID}/approve`]: { data: building },
+          [`POST /v1/plans/${PLAN_ID}/reject`]: { data: { ...item, planningStatus: 'planning' } },
+        },
+      });
+
+      const approved = await client.callTool({ name: 'taiga_approve_plan', arguments: { planId: PLAN_ID } });
+      expect(approved.isError).toBeFalsy();
+      expect(outcomeOf(approved)).toMatchObject({ state: 'build' });
+
+      const rejected = await client.callTool({
+        name: 'taiga_reject_plan',
+        arguments: { planId: PLAN_ID, comment: '  Split the migration into its own step.  ' },
+      });
+      expect(rejected.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'POST', `/plans/${PLAN_ID}/reject`)).toEqual({
+        comment: 'Split the migration into its own step.',
+      });
+      expect(outcomeOf(rejected)).toMatchObject({ planningStatus: 'planning' });
+    });
+
+    it('should refuse an empty rejection comment, or one past the limit, before any request', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+      const before = fetchSpy.mock.calls.length;
+
+      for (const comment of ['   ', 'x'.repeat(2001)]) {
+        const result = await client.callTool({ name: 'taiga_reject_plan', arguments: { planId: PLAN_ID, comment } });
+        expect(result.isError).toBe(true);
+      }
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it("should pass on the API's refusal of a plan that was replaced", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`POST /v1/plans/${PLAN_ID}/approve`]: refusal(409, 'CONFLICT', 'This plan has been replaced') },
+      });
+
+      const result = await client.callTool({ name: 'taiga_approve_plan', arguments: { planId: PLAN_ID } });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({ error: 'CONFLICT', message: 'This plan has been replaced' });
+    });
+
+    it('should stop and resume a run and answer with its state and next actions, not its noise', async () => {
+      const stopped = { ...run, status: 'stopped', failedReason: 'user_stopped', actions: ['resume', 'start_over'] };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`POST /v1/builds/${BUILD_ID}/stop`]: { data: stopped },
+          [`POST /v1/builds/${BUILD_ID}/resume`]: { data: { ...run, status: 'pending', actions: ['stop'] } },
+        },
+      });
+
+      const stop = await client.callTool({ name: 'taiga_stop_build', arguments: { buildId: BUILD_ID } });
+      expect(stop.isError).toBeFalsy();
+      expect(outcomeOf(stop)).toEqual({
+        id: BUILD_ID,
+        runNumber: 1,
+        backlogItemId: ITEM_ID,
+        status: 'stopped',
+        failedReason: 'user_stopped',
+        completedSteps: 1,
+        totalSteps: 3,
+        prUrl: null,
+        actions: ['resume', 'start_over'],
+      });
+      const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).endsWith('/stop'))!;
+      expect((call[1] as RequestInit).body).toBeNull();
+
+      const resume = await client.callTool({ name: 'taiga_resume_build', arguments: { buildId: BUILD_ID } });
+      expect(resume.isError).toBeFalsy();
+      expect(outcomeOf(resume)).toMatchObject({ status: 'pending', actions: ['stop'] });
+    });
+
+    it("should pass on the API's refusal to stop a run that is not running", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`POST /v1/builds/${BUILD_ID}/stop`]: refusal(409, 'CONFLICT', 'Cannot stop a run that is completed'),
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_stop_build', arguments: { buildId: BUILD_ID } });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({ error: 'CONFLICT', message: 'Cannot stop a run that is completed' });
+    });
+
+    it('should list the runs of every product the key can see, each row naming its product', async () => {
+      const other = { ...run, id: OTHER_ITEM, productId: PRODUCT_ID_2, status: 'completed', actions: [] };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run, other], nextCursor: 'next' },
+          '/v1/products': {
+            data: [
+              { id: PRODUCT_ID, name: 'Web', slug: 'web' },
+              { id: PRODUCT_ID_2, name: 'API', slug: 'api' },
+            ],
+            nextCursor: null,
+          },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_builds', arguments: { active: true, limit: 10 } });
+
+      expect(result.isError).toBeFalsy();
+      const { data, nextCursor } = outcomeOf(result);
+      expect(nextCursor).toBe('next');
+      expect(data).toHaveLength(2);
+      expect(data[0]).toMatchObject({
+        id: BUILD_ID,
+        targetTitle: 'Add login',
+        actions: ['stop'],
+        product: { name: 'Web', slug: 'web' },
+      });
+      expect(data[0]).not.toHaveProperty('error');
+      expect(data[1].product).toEqual({ name: 'API', slug: 'api' });
+      const url = sentUrl(fetchSpy, '/builds');
+      expect(url.pathname).toBe('/v1/builds');
+      expect(url.searchParams.get('active')).toBe('true');
+      expect(url.searchParams.get('limit')).toBe('10');
+      expect(sentUrl(fetchSpy, '/products').searchParams.get('limit')).toBe('100');
+    });
+
+    it('should refuse backlogItemId without productId before any request rather than answer with every run', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({ name: 'taiga_list_builds', arguments: { backlogItemId: ITEM_ID } });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toMatchObject({ error: 'VALIDATION_FAILED' });
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should say when only the first page of products could be named', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [{ ...run, productId: PRODUCT_ID_2 }], nextCursor: null },
+          '/v1/products': { data: [{ id: PRODUCT_ID, name: 'Web', slug: 'web' }], nextCursor: 'more' },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_builds', arguments: {} });
+
+      const { data, note } = outcomeOf(result);
+      expect(data[0]).not.toHaveProperty('product');
+      expect(note).toMatch(/Only the first 100 products could be named/);
+    });
+
+    it('should say when an unnamed row belongs to a product the key cannot list, not that the page was cut', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [{ ...run, productId: PRODUCT_ID_2 }], nextCursor: null },
+          '/v1/products': { data: [{ id: PRODUCT_ID, name: 'Web', slug: 'web' }], nextCursor: null },
+        },
+      });
+
+      const { data, note } = outcomeOf(await client.callTool({ name: 'taiga_list_builds', arguments: {} }));
+
+      expect(data[0]).not.toHaveProperty('product');
+      expect(note).toMatch(/cannot list \(deleted since, or not visible/);
+      expect(note).not.toMatch(/first 100/);
+    });
+
+    it('should carry no note when the products page was cut but every row still got a name', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run], nextCursor: null },
+          '/v1/products': { data: [{ id: PRODUCT_ID, name: 'Web', slug: 'web' }], nextCursor: 'more' },
+        },
+      });
+
+      const result = outcomeOf(await client.callTool({ name: 'taiga_list_builds', arguments: {} }));
+
+      expect(result.data[0].product).toEqual({ name: 'Web', slug: 'web' });
+      expect(result).not.toHaveProperty('note');
+    });
+
+    it('should leave rows unnamed on a network failure of the products read, and surface a bug in it', async () => {
+      const offline = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run], nextCursor: null },
+          '/v1/products': () => {
+            throw new TypeError('fetch failed', { cause: { code: 'ECONNREFUSED' } });
+          },
+        },
+      });
+      const result = outcomeOf(await offline.client.callTool({ name: 'taiga_list_builds', arguments: {} }));
+      expect(result.data[0]).not.toHaveProperty('product');
+      expect(result.note).toMatch(/products could not be read/);
+
+      const buggy = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run], nextCursor: null },
+          '/v1/products': () => {
+            throw new Error('a bug in the products path');
+          },
+        },
+      });
+      const failure = await buggy.client.callTool({ name: 'taiga_list_builds', arguments: {} });
+      expect(failure.isError).toBe(true);
+      expect(JSON.stringify(failure.content)).toContain('a bug in the products path');
+      expect(JSON.stringify(failure.content)).not.toContain('could not be read');
+    });
+
+    it('should keep the org-wide rows when the products read fails, unnamed', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run], nextCursor: null },
+          '/v1/products': refusal(500, 'INTERNAL', 'boom'),
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_builds', arguments: {} });
+
+      expect(result.isError).toBeFalsy();
+      const { data, note } = outcomeOf(result);
+      expect(data[0]).toMatchObject({ id: BUILD_ID, productId: PRODUCT_ID });
+      expect(data[0]).not.toHaveProperty('product');
+      expect(note).toMatch(/products could not be read/);
+      expect(sentUrl(fetchSpy, '/builds').search).toBe('');
+    });
+
+    it('should carry no note when every product could be named', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          '/v1/builds': { data: [run], nextCursor: null },
+          '/v1/products': { data: [{ id: PRODUCT_ID, name: 'Web', slug: 'web' }], nextCursor: null },
+        },
+      });
+
+      expect(outcomeOf(await client.callTool({ name: 'taiga_list_builds', arguments: {} }))).not.toHaveProperty('note');
+    });
+
+    it('should refuse active with productId before any request rather than drop the filter', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({
+        name: 'taiga_list_builds',
+        arguments: { productId: PRODUCT_ID, active: true },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toMatchObject({ error: 'VALIDATION_FAILED' });
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should keep the product list unread on the product route', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}/builds`]: { data: [run], nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_builds', arguments: { productId: PRODUCT_ID } });
+
+      expect(result.isError).toBeFalsy();
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).endsWith('/v1/products?limit=100'))).toBe(
+        false
+      );
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail