@taiga-ai/mcp-server 0.11.0 → 0.12.0-dev.417

package/src/tools/wait.ts

@@ -0,0 +1,445 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { BUILD_RUN_TERMINAL_STATUSES, resolveAutoBuild } from '@taiga/types';
+import { z } from 'zod';
+import { TaigaApiError, type TaigaClient } from '../client.js';
+import { READ_ONLY } from './annotations.js';
+import { isNetworkFailure, runTool, toolResult } from './errors.js';
+import { criteriaCounts, pickFields } from './summarize.js';
+
+/**
+ * Waiting without a timer. A model in an editor has no clock: to learn that
+ * a plan landed or a run opened its pull request it either reads the item
+ * again and again or hands the wait to a shell loop outside the server. These
+ * tools poll on the server instead and return as soon as the condition holds,
+ * when it can no longer hold without a person, or at the timeout, whichever
+ * is first; a timeout is an answer too (reached: false), and the model calls
+ * again to keep waiting.
+ */
+
+export interface WaitOptions {
+  /** How often the API is read while waiting. */
+  pollIntervalMs: number;
+}
+
+export const DEFAULT_WAIT_OPTIONS: WaitOptions = { pollIntervalMs: 5_000 };
+
+/**
+ * Under the 60 seconds many clients allow a call by default (the MCP SDK's
+ * own request timeout), with room for the last read.
+ */
+const DEFAULT_TIMEOUT_SECONDS = 50;
+const MAX_TIMEOUT_SECONDS = 600;
+
+const timeoutSeconds = z
+  .number()
+  .int()
+  .min(1)
+  .max(MAX_TIMEOUT_SECONDS)
+  .optional()
+  .describe(
+    `How long to wait at most (default ${DEFAULT_TIMEOUT_SECONDS}). Keep it under your client's tool-call limit; ` +
+      'many stop a call at 60 seconds.'
+  );
+
+type Row = Record<string, unknown>;
+
+/** Why a wait ended: the condition held, it can no longer hold on its own, or time ran out. */
+type Verdict = { reached: true } | { reached: false; stoppedBecause: string } | null;
+
+interface Progress {
+  progressToken: string | number | undefined;
+  sendNotification: (notification: {
+    method: 'notifications/progress';
+    params: { progressToken: string | number; progress: number; total: number; message: string };
+  }) => Promise<void>;
+  signal: AbortSignal;
+}
+
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', done);
+      resolve();
+    }
+    signal.addEventListener('abort', done, { once: true });
+  });
+}
+
+/** Failed reads in a row a wait rides out before it gives up and says why. */
+const TRANSIENT_FAILURES_TOLERATED = 3;
+
+/** A failure the next read may not hit: rate limited, the API erroring or unreachable. Not a refusal or a miss. */
+function isTransient(error: unknown): boolean {
+  if (isNetworkFailure(error)) return true;
+  return error instanceof TaigaApiError && (error.status === 429 || error.status >= 500);
+}
+
+/**
+ * Read until `judge` gives a verdict or the time is up. Every read is bound
+ * by what is left of the timeout and by the call's cancellation, so a slow
+ * API cannot hold the wait past either: a read cut short ends the wait with
+ * the last state seen (none, when not even the first read came back). A
+ * read that fails transiently is ridden out, a few in a row and the first
+ * read included, so one 502 does not throw away minutes of waiting; a
+ * refusal fails as it comes. Each
+ * read that leaves the wait open reports progress when the client asked for
+ * it, which also keeps a client that resets its timeout on progress from
+ * cutting the wait short.
+ */
+async function waitFor(
+  read: (signal: AbortSignal) => Promise<Row>,
+  judge: (now: Row, first: Row) => Verdict,
+  timeoutMs: number,
+  options: WaitOptions,
+  progress: Progress
+) {
+  const started = Date.now();
+  const deadline = started + timeoutMs;
+  let first: Row | null = null;
+  let now: Row | null = null;
+  let verdict: Verdict = null;
+  let failures = 0;
+  for (let attempt = 0; !progress.signal.aborted; attempt += 1) {
+    if (attempt > 0) {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await pause(Math.min(options.pollIntervalMs, left), progress.signal);
+    }
+    const remaining = deadline - Date.now();
+    if (progress.signal.aborted || remaining <= 0) break;
+    const bound = AbortSignal.timeout(remaining);
+    try {
+      now = await read(AbortSignal.any([progress.signal, bound]));
+      first ??= now;
+      failures = 0;
+    } catch (error) {
+      // Cut short by the deadline or the cancellation: the wait is over, not failed.
+      if (bound.aborted || progress.signal.aborted) break;
+      failures += 1;
+      if (!isTransient(error) || failures >= TRANSIENT_FAILURES_TOLERATED) throw error;
+      continue;
+    }
+    verdict = judge(now, first);
+    if (verdict) break;
+    if (attempt > 0 && progress.progressToken !== undefined) {
+      // Best effort: a progress line the client cannot take does not end the wait.
+      await progress
+        .sendNotification({
+          method: 'notifications/progress',
+          params: {
+            progressToken: progress.progressToken,
+            // Milliseconds, so every notification is larger than the last, as the protocol asks.
+            progress: Date.now() - started,
+            total: timeoutMs,
+            message: 'Still waiting',
+          },
+        })
+        .catch(() => undefined);
+    }
+  }
+  const waitedSeconds = Math.round((Date.now() - started) / 1000);
+  if (verdict) return { ...verdict, waitedSeconds, now };
+  const stoppedBecause = progress.signal.aborted ? 'cancelled' : 'timeout';
+  return { reached: false, stoppedBecause, waitedSeconds, now };
+}
+
+const SETTLED_RUN: ReadonlySet<string> = new Set(BUILD_RUN_TERMINAL_STATUSES);
+
+/**
+ * A pull request that is open now. A run keeps its prUrl after the pull
+ * request merges or closes, so the URL alone says one existed, not that it
+ * is open; the mirrored state and the merged latch say which. An unknown
+ * state (null, just opened) counts as open.
+ */
+function prIsOpen(run: Row): boolean {
+  return typeof run.prUrl === 'string' && run.prUrl !== '' && run.prMerged !== true && run.prState !== 'closed';
+}
+
+// ---------------------------------------------------------------------------
+// Initiatives
+// ---------------------------------------------------------------------------
+
+const ITEM_CONDITIONS = ['changed', 'planned', 'your_turn', 'pr_open', 'run_settled', 'done'] as const;
+type ItemCondition = (typeof ITEM_CONDITIONS)[number];
+
+const latestBuildOf = (item: Row) => ((item.lifecycle as Row | undefined)?.latestBuild ?? null) as Row | null;
+const lifecycleOf = (item: Row) => (item.lifecycle ?? {}) as Row;
+
+/** What "changed" compares: where the item is, whose turn it is and how its latest run stands. */
+function itemSignature(item: Row): string {
+  const lifecycle = lifecycleOf(item);
+  const run = latestBuildOf(item);
+  return JSON.stringify([
+    item.state,
+    item.planningStatus,
+    item.needsHumanCause,
+    lifecycle.stage,
+    lifecycle.turn,
+    lifecycle.cta,
+    run?.id,
+    run?.status,
+    run?.completedSteps,
+    run?.prUrl,
+    run?.prState,
+    run?.prMerged,
+  ]);
+}
+
+/**
+ * The product's auto-build default, as far as the wait knows it: read once,
+ * and only when an initiative with no gate of its own needs it. Null when the
+ * key may not read it (or the product is gone); undefined until read.
+ */
+interface GateDefault {
+  product: boolean | null | undefined;
+}
+
+/**
+ * Whether the initiative waits on a person now: yes, no, or unknown. The
+ * lifecycle says `turn: 'you'` for every landed plan (`start_build`), but a
+ * plan whose review gate is open is waiting for the Build slot, not for
+ * anyone: the queue keeps such an entry active and starts it on its own. When
+ * the gate cannot be resolved (no gate of its own, and the product's default
+ * unreadable) the answer is unknown, and the wait says so rather than guess.
+ */
+function personTurn(item: Row, gate: GateDefault): 'yes' | 'no' | 'unknown' {
+  const lifecycle = lifecycleOf(item);
+  if (lifecycle.turn !== 'you') return 'no';
+  if (lifecycle.cta !== 'start_build') return 'yes';
+  const own = typeof item.autoBuild === 'boolean' ? item.autoBuild : null;
+  const product = typeof gate.product === 'boolean' ? gate.product : null;
+  if (own === null && product === null) return 'unknown';
+  return resolveAutoBuild({ initiative: own, product: product ?? true }) ? 'no' : 'yes';
+}
+
+function itemHolds(until: ItemCondition, item: Row, first: Row, gate: GateDefault): boolean {
+  const lifecycle = lifecycleOf(item);
+  const run = latestBuildOf(item);
+  switch (until) {
+    case 'changed':
+      return itemSignature(item) !== itemSignature(first);
+    case 'planned':
+      return item.planningStatus === 'planned';
+    case 'your_turn':
+      return personTurn(item, gate) === 'yes';
+    case 'pr_open':
+      return run !== null && prIsOpen(run);
+    case 'run_settled':
+      return run !== null && SETTLED_RUN.has(String(run.status));
+    case 'done':
+      return lifecycle.stage === 'done';
+  }
+}
+
+function judgeItem(until: ItemCondition, gate: GateDefault) {
+  return (item: Row, first: Row): Verdict => {
+    if (itemHolds(until, item, first, gate)) return { reached: true };
+    // "changed" is how a model waits for a person to act on a flagged or
+    // finished initiative, so none of the stops below apply to it.
+    if (until === 'changed') return null;
+    // Past these the condition cannot come true without a person acting.
+    if (typeof item.needsHumanCause === 'string') {
+      return { reached: false, stoppedBecause: `needs a person: ${item.needsHumanCause}` };
+    }
+    // The ordinary gates set no flag: a plan waiting for its verdict, a pull
+    // request waiting for a review. The lifecycle says whose turn it is.
+    const lifecycle = lifecycleOf(item);
+    const turn = personTurn(item, gate);
+    if (until !== 'your_turn' && turn === 'yes') {
+      return { reached: false, stoppedBecause: `waits on a person: ${String(lifecycle.cta ?? lifecycle.stage)}` };
+    }
+    if (turn === 'unknown') {
+      return {
+        reached: false,
+        stoppedBecause:
+          "the plan has landed, and whether it waits for a review is unknown: the product's default could not be read " +
+          '(it needs products:read)',
+      };
+    }
+    if (until === 'planned' && item.planningStatus === 'failed') {
+      return { reached: false, stoppedBecause: 'planning failed' };
+    }
+    const stage = lifecycleOf(item).stage;
+    // Canceled ends every wait, done included: it is not the done asked for.
+    if (stage === 'canceled' || (until !== 'done' && stage === 'done')) {
+      return { reached: false, stoppedBecause: `the initiative is ${String(stage)}` };
+    }
+    return null;
+  };
+}
+
+/** The initiative as a wait reports it: where it is, whose turn, its latest run and its criteria. */
+function itemReport(item: Row) {
+  const run = latestBuildOf(item);
+  return {
+    ...pickFields(
+      [item],
+      ['id', 'title', 'state', 'planningStatus', 'needsHumanCause', 'needsHumanDetail', 'autoBuild']
+    )[0],
+    lifecycle: pickFields([lifecycleOf(item)], ['turn', 'stage', 'cta', 'planFailureCause'])[0],
+    latestBuild: run
+      ? pickFields(
+          [run],
+          ['id', 'status', 'completedSteps', 'totalSteps', 'prUrl', 'prState', 'prMerged', 'actions']
+        )[0]
+      : null,
+    criteria: criteriaCounts(item),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Runs
+// ---------------------------------------------------------------------------
+
+const BUILD_CONDITIONS = ['changed', 'step_done', 'pr_open', 'settled'] as const;
+type BuildCondition = (typeof BUILD_CONDITIONS)[number];
+
+const RUN_REPORT_FIELDS = [
+  'id',
+  'backlogItemId',
+  'targetTitle',
+  'status',
+  'failedReason',
+  'completedSteps',
+  'totalSteps',
+  'prUrl',
+  'prState',
+  'prDraft',
+  'prMerged',
+  'actions',
+] as const;
+
+const runSignature = (run: Row) =>
+  JSON.stringify([run.status, run.completedSteps, run.prUrl, run.prState, run.prMerged]);
+
+function judgeBuild(until: BuildCondition) {
+  return (run: Row, first: Row): Verdict => {
+    const holds =
+      until === 'changed'
+        ? runSignature(run) !== runSignature(first)
+        : until === 'step_done'
+          ? Number(run.completedSteps ?? 0) > Number(first.completedSteps ?? 0)
+          : until === 'pr_open'
+            ? prIsOpen(run)
+            : SETTLED_RUN.has(String(run.status));
+    if (holds) return { reached: true };
+    // "changed" waits out a settled run too: a person resuming it is the change.
+    if (until !== 'changed' && SETTLED_RUN.has(String(run.status))) {
+      return { reached: false, stoppedBecause: `the run is ${String(run.status)}` };
+    }
+    return null;
+  };
+}
+
+export function registerWaitTools(server: McpServer, client: TaigaClient, options: WaitOptions) {
+  if (client.hasCapability('backlog:read')) {
+    server.registerTool(
+      'taiga_wait_for_backlog_item',
+      {
+        title: 'Wait for an initiative',
+        description:
+          'Wait until an initiative reaches a point, instead of reading it again and again: changed (anything ' +
+          'about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a ' +
+          'plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does ' +
+          'not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). ' +
+          'Returns as soon as that holds (reached: true), early when it cannot hold without a person (a flag, a ' +
+          'failed plan, a plan waiting for its verdict, a pull request waiting for a review, a cancelled ' +
+          'initiative, or a landed plan whose review gate cannot be read; stoppedBecause says which), or at the ' +
+          'timeout with reached: false: ' +
+          'call again to keep waiting. Conditions are states, not events: an initiative whose latest run is already ' +
+          'settled answers run_settled at once; item is null when not even the first read answered in time. ' +
+          'Planning takes minutes and a build up to an hour.',
+        inputSchema: {
+          itemId: z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items'),
+          until: z.enum(ITEM_CONDITIONS).describe('What to wait for'),
+          timeoutSeconds,
+        },
+        annotations: READ_ONLY,
+      },
+      (params, extra) =>
+        runTool(async () => {
+          const gate: GateDefault = { product: undefined };
+          const read = async (signal: AbortSignal) => {
+            const item = (await client.getBacklogItem(params.itemId, signal)).data as Row;
+            // The product's default, once, when this initiative has no gate of its own to answer with.
+            if (gate.product === undefined && typeof item.autoBuild !== 'boolean') {
+              gate.product = client.hasCapability('products:read')
+                ? await client
+                    .getProduct(String(item.productId), signal)
+                    .then((p) => {
+                      const value = (p.data as { autoBuild?: unknown }).autoBuild;
+                      return typeof value === 'boolean' ? value : true;
+                    })
+                    // Not allowed, or gone: unknown for good. Anything transient
+                    // propagates, so the wait rides it out and reads again.
+                    .catch((error: unknown) => {
+                      if (error instanceof TaigaApiError && (error.status === 403 || error.status === 404)) return null;
+                      throw error;
+                    })
+                : null;
+            }
+            return item;
+          };
+          const result = await waitFor(
+            read,
+            judgeItem(params.until, gate),
+            (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+            options,
+            {
+              progressToken: extra._meta?.progressToken,
+              sendNotification: extra.sendNotification,
+              signal: extra.signal,
+            }
+          );
+          const { now, ...outcome } = result;
+          return toolResult({ until: params.until, ...outcome, item: now ? itemReport(now) : null });
+        })
+    );
+  }
+
+  if (client.hasCapability('products:read')) {
+    server.registerTool(
+      'taiga_wait_for_build',
+      {
+        title: 'Wait for a run',
+        description:
+          "Wait until a coding agent's run reaches a point: changed (status, steps or pull request), step_done " +
+          '(one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in ' +
+          'review, completed, failed, stopped). ' +
+          'Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; ' +
+          'changed waits on, since a person resuming the run is a change), or at the timeout with reached: false: ' +
+          'call again to keep waiting. Conditions are states: a run already settled answers settled at once; run ' +
+          'is null when not even the first read answered in time.',
+        inputSchema: {
+          buildId: z.string().uuid().describe('Build run ID -- get from taiga_list_builds'),
+          until: z.enum(BUILD_CONDITIONS).describe('What to wait for'),
+          timeoutSeconds,
+        },
+        annotations: READ_ONLY,
+      },
+      (params, extra) =>
+        runTool(async () => {
+          const result = await waitFor(
+            async (signal) => (await client.getBuildRun(params.buildId, signal)).data as Row,
+            judgeBuild(params.until),
+            (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+            options,
+            {
+              progressToken: extra._meta?.progressToken,
+              sendNotification: extra.sendNotification,
+              signal: extra.signal,
+            }
+          );
+          const { now, ...outcome } = result;
+          return toolResult({
+            until: params.until,
+            ...outcome,
+            run: now ? pickFields([now], RUN_REPORT_FIELDS)[0] : null,
+          });
+        })
+    );
+  }
+}

package/tsconfig.json

@@ -11,6 +11,10 @@
     "resolveJsonModule": true,
     "types": ["node"],
 
+    // @tsconfig/strictest leaves these two out, so every package sets them.
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+
     // Preset flags this package still fails (PRO-2509). Each line is deleted
     // by the issue named beside it; no new line is added here.
     "noPropertyAccessFromIndexSignature": false // PRO-2519