@taiga-ai/mcp-server 0.25.0-rc.472 → 0.26.0-dev.479

package/src/tools/wait.ts

@@ -1,490 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { BUILD_RUN_TERMINAL_STATUSES, resolveAutoBuild } from '@taiga/types';
-import type { BacklogItem, BacklogItemLifecycle, BuildRunWithContext } from '@taiga/types';
-import { z } from 'zod';
-import { idInput } from './inputs.js';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { READ_ONLY } from './annotations.js';
-import { isNetworkFailure, runTool, toolResult } from './errors.js';
-import { SETTLED_JOB_STATUSES, jobReport } from './jobs.js';
-import { criteriaCounts, pickFields } from './summarize.js';
-import { situationOf } from './backlogs.js';
-import { readableRow } from './builds.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 Item = WithoutTenant<BacklogItem>;
-type Run = WithoutTenant<BuildRunWithContext>;
-
-/** The pull-request fields an initiative's latest run and a build run both carry. */
-type PullRequestFields = Pick<Run, 'prUrl' | 'prMerged' | 'prState'>;
-
-/** 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;
-  notify: (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<T>(
-  read: (signal: AbortSignal) => Promise<T>,
-  judge: (now: T, first: T) => Verdict,
-  timeoutMs: number,
-  options: WaitOptions,
-  progress: Progress
-) {
-  const started = Date.now();
-  const deadline = started + timeoutMs;
-  let first: T | null = null;
-  let now: T | 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
-        .notify({
-          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: PullRequestFields): 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];
-
-// The API sends a lifecycle on every backlog item (backlogItemSchema); a
-// response without one reads as no lifecycle rather than failing the wait.
-const latestBuildOf = (item: Item) => item.lifecycle?.latestBuild ?? null;
-const lifecycleOf = (item: Item): Partial<BacklogItemLifecycle> => item.lifecycle ?? {};
-
-/** What "changed" compares: where the item is, whose turn it is and how its latest run stands. */
-function itemSignature(item: Item): string {
-  const lifecycle = lifecycleOf(item);
-  const run = latestBuildOf(item);
-  return JSON.stringify([
-    item.state,
-    item.planningStatus,
-    item.needsHumanCause,
-    // The review gate decides whose turn a landed plan is, while the lifecycle reads the same either way.
-    item.autoBuild,
-    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: Item, 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: Item, first: Item, 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: Item, first: Item): 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: Item) {
-  const run = latestBuildOf(item);
-  const situation = situationOf(item);
-  return {
-    ...(situation ? { situation } : {}),
-    ...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',
-  'reviewEscalation',
-  'error',
-  'prNumber',
-  'baseBranch',
-  'actions',
-] as const;
-
-const runSignature = (run: Run) =>
-  JSON.stringify([run.status, run.completedSteps, run.prUrl, run.prState, run.prMerged]);
-
-function judgeBuild(until: BuildCondition) {
-  return (run: Run, first: Run): 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_initiative',
-      {
-        title: 'Wait for an initiative',
-        description:
-          'Wait until an initiative reaches a condition instead of polling: changed, planned, your_turn (waits on ' +
-          'a person), pr_open (open now; merged or closed does not count), run_settled (latest run stopped moving) ' +
-          'or done. Returns reached: true when it ' +
-          'holds; early with stoppedBecause when only a person can move it (a flag, failed plan, plan or pull ' +
-          'request awaiting review, a cancel); or reached: false at the timeout: call again. A condition already ' +
-          'true answers at once. Planning takes minutes, a run up to an hour.',
-        inputSchema: z.object({
-          initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it'),
-          until: z.enum(ITEM_CONDITIONS).describe('What to wait for'),
-          timeoutSeconds,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params, ctx) =>
-        runTool(async () => {
-          const gate: GateDefault = { product: undefined };
-          const read = async (signal: AbortSignal) => {
-            const item = (await client.getBacklogItem(params.initiativeId, signal)).data;
-            // 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.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: ctx.mcpReq._meta?.progressToken,
-              notify: ctx.mcpReq.notify,
-              signal: ctx.mcpReq.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_run',
-      {
-        title: 'Wait for a run',
-        description:
-          'Wait until a run reaches a condition: changed, step_done (one more step finished), pr_open (open now) ' +
-          'or settled (in review, completed, failed, stopped). Returns reached: true when it holds; early with ' +
-          'stoppedBecause if the run settled without it; or reached: false at the timeout: call again. A settled ' +
-          'run answers settled at once; run is null if the first read timed out.',
-        inputSchema: z.object({
-          runId: idInput('run', 'taiga_list_runs gives it'),
-          until: z.enum(BUILD_CONDITIONS).describe('What to wait for'),
-          timeoutSeconds,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params, ctx) =>
-        runTool(async () => {
-          const result = await waitFor(
-            async (signal) => (await client.getBuildRun(params.runId, signal)).data,
-            judgeBuild(params.until),
-            (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
-            options,
-            {
-              progressToken: ctx.mcpReq._meta?.progressToken,
-              notify: ctx.mcpReq.notify,
-              signal: ctx.mcpReq.signal,
-            }
-          );
-          const { now, ...outcome } = result;
-          return toolResult({
-            until: params.until,
-            ...outcome,
-            run: now ? readableRow(pickFields([now], RUN_REPORT_FIELDS)[0]!) : null,
-          });
-        })
-    );
-  }
-
-  if (client.hasCapability('products:read')) {
-    server.registerTool(
-      'taiga_wait_for_job',
-      {
-        title: 'Wait for an agent job',
-        description:
-          'Wait until an agent job finishes (completed, failed or cancelled). Returns the job as taiga_get_job ' +
-          "reads it, with an initiative request's outcome, and reached: true; or reached: false at the timeout: " +
-          'call again to keep waiting. Most jobs take a few minutes.',
-        inputSchema: z.object({
-          jobId: idInput('job', 'the tool that started the job returned it'),
-          timeoutSeconds,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params, ctx) =>
-        runTool(async () => {
-          const result = 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) * 1000,
-            options,
-            {
-              progressToken: ctx.mcpReq._meta?.progressToken,
-              notify: ctx.mcpReq.notify,
-              signal: ctx.mcpReq.signal,
-            }
-          );
-          const { now, ...outcome } = result;
-          return toolResult({ ...outcome, job: now ? jobReport(now) : null });
-        })
-    );
-  }
-}

package/src/version.test.ts

@@ -1,10 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { describe, expect, it } from 'vitest';
-import { SERVER_VERSION } from './version.js';
-
-describe('SERVER_VERSION', () => {
-  it('is the version in package.json, not a hand-kept copy', () => {
-    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
-    expect(SERVER_VERSION).toBe(pkg.version);
-  });
-});

package/src/version.ts

@@ -1,14 +0,0 @@
-import { createRequire } from 'node:module';
-
-/**
- * This package's own version, read from package.json at runtime.
- *
- * Read at runtime rather than inlined at build: the publish workflow sets the
- * final version (`0.3.0-dev.<run>`, `0.3.0-rc.<run>`) after the bundle is
- * built, so only a runtime read reports what was actually published. Both
- * `src/` and the bundled `dist/index.js` sit one level under the package root,
- * and npm always ships package.json.
- */
-const pkg = createRequire(import.meta.url)('../package.json') as { version: string };
-
-export const SERVER_VERSION: string = pkg.version;

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "extends": "@tsconfig/strictest/tsconfig.json",
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "declarationMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "resolveJsonModule": true,
-    "types": ["node"],
-
-    // @tsconfig/strictest leaves these two out, so every package sets them.
-    "verbatimModuleSyntax": true,
-    "erasableSyntaxOnly": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"],
-  "references": [{ "path": "../../packages/types" }]
-}

package/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    include: ['src/**/*.test.ts'],
-    environment: 'node',
-    testTimeout: 10_000,
-  },
-});