@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.481

package/src/tools/inbox.ts

@@ -1,546 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
-import { OPERATE, READ_ONLY } from './annotations.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { idInput, pagination, productId } from './inputs.js';
-import { page, pickFields } from './summarize.js';
-
-/**
- * Action Required (docs.tai.ga, Deliver): where work comes back to a person.
- * Things to review (a plan, a pull request, findings, policy violations) and
- * things to set up that only a person can (a secret, an account, a cloud
- * permission). The inbox is the team's: resolving an item clears it for
- * everybody, so these tools say what they clear.
- */
-
-type Row = Record<string, unknown>;
-
-/**
- * An item as a row: what it is, whose product, how long it has waited. Not
- * its metadata by default: a document decision carried its whole text there,
- * and fifty rows came to 57 KB (PRO-2800); full: true brings it.
- */
-const ITEM_FIELDS = [
-  'id',
-  'productId',
-  'productName',
-  'category',
-  'kind',
-  'subjectType',
-  'subjectId',
-  'title',
-  'summary',
-  'status',
-  'blocking',
-  'snoozedUntil',
-  'createdAt',
-  'resolvedAt',
-] as const;
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-/** When an item stopped waiting: its resolution, or now while it is open. */
-function waitedUntil(resolvedAt: unknown, now: number): number {
-  const at = typeof resolvedAt === 'string' ? Date.parse(resolvedAt) : NaN;
-  return Number.isNaN(at) ? now : at;
-}
-
-/**
- * The read that opens an item's subject (PRO-2800): rows carried subjectType and subjectId, and the reviewing agent
- * had to infer which tool takes them.
- */
-function readWith(row: Row, backlogRead: boolean): string | undefined {
-  switch (row['subjectType']) {
-    case 'build_run':
-      return 'taiga_get_run (runId: subjectId)';
-    case 'backlog_item':
-      // Only a tool the key has: the backlog reads need backlog:read.
-      return backlogRead ? 'taiga_get_plan (initiativeId: subjectId)' : undefined;
-    case 'product_document': {
-      // A document decision's subject is "<productId>:<type>:decision:<hash>", which no tool takes: name the
-      // document it is about, and say where the decision's own text is.
-      const type = /^[^:]+:([a-z_]+):decision:/.exec(String(row['subjectId']))?.[1];
-      return type
-        ? `taiga_get_product_document (productId, type: ${type}); the decision's text is this row with full: true`
-        : 'taiga_get_product_document (productId, no type)';
-    }
-    case 'inbox_task':
-      return 'taiga_list_setup_tasks (productId)';
-    case 'product':
-      return {
-        // Open, not one column: the item stands while one sits in backlog or todo.
-        review_backlog: backlogRead ? 'taiga_list_initiatives (productId)' : undefined,
-        review_maintenance: 'taiga_list_findings (productId)',
-        review_policy: 'taiga_get_policy_standing (productId)',
-        review_doc: 'taiga_get_product_document (productId, no type)',
-      }[String(row['kind'])];
-    default:
-      return undefined;
-  }
-}
-
-/** A summary past its first sentence: review_doc rows quoted two documents, 800 to 1,200 characters each. */
-const SUMMARY_LIMIT = 200;
-
-function firstSentence(text: unknown): unknown {
-  if (typeof text !== 'string') return text;
-  // The opening paragraph, as far as SUMMARY_LIMIT: a list after a colon ("could not resolve:\n1. ...") is where
-  // the quoted documents start, and a short summary keeps its second sentence ("N manual setup tasks flagged").
-  const head = text.split(/\n/)[0]!.trim();
-  if (head.length <= SUMMARY_LIMIT)
-    return head.length < text.trim().length ? `${head} (full: true has the rest)` : head;
-  const cut = head.slice(0, SUMMARY_LIMIT);
-  const end = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('; '));
-  return `${end > 40 ? cut.slice(0, end + 1) : cut}... (full: true has the rest)`;
-}
-
-/** A row as an agent reads it: the pull request to open when there is one, and how many days it has waited. */
-function itemRow(row: Row, now: number, full: boolean, backlogRead: boolean): Row {
-  const picked = pickFields([row], ITEM_FIELDS)[0]!;
-  const { snoozedUntil, resolvedAt, ...rest } = picked;
-  const metadata = (row['metadata'] ?? {}) as Row;
-  const created = typeof row['createdAt'] === 'string' ? Date.parse(row['createdAt']) : NaN;
-  // A pull request review's summary is one sentence per row ("The coding agent finished its turn on X. Review PR
-  // #N...") that the title and kind already say: the org-wide page was 5k tokens of it (PRO-2800).
-  // Fields at their usual value say nothing: open, not blocking (the org-wide page repeated them on every row).
-  const { summary, status, blocking, ...lean } = rest;
-  const read = readWith(row, backlogRead);
-  return {
-    ...lean,
-    ...(full ? { summary } : row['kind'] === 'review_pr' ? {} : { summary: firstSentence(summary) }),
-    ...(full || status !== 'open' ? { status } : {}),
-    ...(full || blocking === true ? { blocking } : {}),
-    ...(read ? { readWith: read } : {}),
-    ...(snoozedUntil ? { snoozedUntil } : {}),
-    ...(resolvedAt ? { resolvedAt } : {}),
-    ...(typeof metadata['prUrl'] === 'string' ? { prUrl: metadata['prUrl'] } : {}),
-    // A resolved item waited until it was resolved, not until now.
-    ...(Number.isNaN(created) ? {} : { waitingDays: Math.floor((waitedUntil(resolvedAt, now) - created) / DAY_MS) }),
-    ...(full ? { metadata: row['metadata'] } : {}),
-  };
-}
-
-/**
- * What is open, counted by product and kind: the answer to "what needs attention" without reading every row. An item
- * that no longer stands is counted under stale, not open or byKind, so nobody subtracts by hand (PRO-2800).
- */
-function summaryOf(rows: Row[], stale: Map<string, string>): Row[] {
-  const byProduct = new Map<
-    string,
-    { productId: string; product?: unknown; open: number; byKind: Record<string, number>; stale?: number }
-  >();
-  for (const row of rows) {
-    const key = String(row['productId']);
-    // A product-scoped read carries no names; the id is the product's, not a name.
-    const entry =
-      byProduct.get(key) ??
-      (row['productName']
-        ? { productId: key, product: row['productName'], open: 0, byKind: {} }
-        : { productId: key, open: 0, byKind: {} });
-    if (stale.has(String(row['id']))) {
-      entry.stale = (entry.stale ?? 0) + 1;
-    } else {
-      entry.open += 1;
-      entry.byKind[String(row['kind'])] = (entry.byKind[String(row['kind'])] ?? 0) + 1;
-    }
-    byProduct.set(key, entry);
-  }
-  return [...byProduct.values()].sort((a, b) => b.open - a.open);
-}
-
-/** Pull request reviews checked against their run and initiative; past this a row is left as it is. */
-const STALE_CHECKS = 10;
-
-/**
- * Which "Review & merge" items no longer stand, and why (PRO-2800): the run's
- * pull request closed or merged, or its initiative was canceled or finished
- * without it. Two reviewing agents counted such leftovers as live gates; the
- * row still is open in Action Required, so this says what it is now rather
- * than hiding it. Best effort, a handful of runs: a failed read leaves the
- * row as it was.
- */
-async function staleReviews(
-  client: TaigaClient,
-  rows: Row[]
-): Promise<{ stale: Map<string, string>; unchecked: number }> {
-  const byId = new Map(
-    rows
-      .filter((row) => row['kind'] === 'review_pr' && row['subjectType'] === 'build_run')
-      .map((row) => [String(row['id']), row])
-  );
-  const candidates = [...byId.values()].slice(0, STALE_CHECKS);
-  // Past the cap, and any check the API refused or failed (a key without
-  // backlog:read cannot read the initiative): unknown, not live.
-  let unchecked = byId.size - candidates.length;
-  const out = new Map<string, string>();
-  await Promise.all(
-    candidates.map(async (row) => {
-      try {
-        const run = (await client.getBuildRun(String(row['subjectId']))).data as unknown as Row;
-        if (run['prMerged'] === true) return void out.set(String(row['id']), 'its pull request has merged');
-        if (run['prState'] === 'closed') return void out.set(String(row['id']), 'its pull request was closed');
-        if (typeof run['backlogItemId'] !== 'string') return;
-        if (!client.hasCapability('backlog:read')) return void (unchecked += 1);
-        const item = (await client.getBacklogItem(run['backlogItemId'])).data as unknown as Row;
-        if (item['state'] === 'canceled' || item['status'] === 'canceled') {
-          out.set(String(row['id']), 'its initiative was canceled; the pull request is still open on the forge');
-        } else if (item['state'] === 'done' || item['status'] === 'done') {
-          out.set(String(row['id']), 'its initiative is done; this run is not the one that landed it');
-        }
-      } catch (error) {
-        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
-        unchecked += 1;
-      }
-    })
-  );
-  unchecked += await staleBacklogReviews(client, rows, out);
-  return { stale: out, unchecked };
-}
-
-/**
- * "Review Initiatives" items whose product has no initiative left in its backlog or todo column (PRO-2800): two reviews found one
- * waiting 15 days on a product whose initiatives had all moved on, with nothing an agent could act on. Best effort,
- * a handful of products; returns how many could not be checked.
- */
-async function staleBacklogReviews(client: TaigaClient, rows: Row[], out: Map<string, string>): Promise<number> {
-  // The page and the summary's read can carry the same row: each item once.
-  const asks = [
-    ...new Map(
-      rows
-        .filter((row) => row['kind'] === 'review_backlog' && typeof row['productId'] === 'string')
-        .map((row) => [String(row['id']), row])
-    ).values(),
-  ];
-  if (asks.length === 0) return 0;
-  if (!client.hasCapability('backlog:read')) return asks.length;
-  const products = [...new Set(asks.map((row) => String(row['productId'])))];
-  const checked = products.slice(0, STALE_CHECKS);
-  let unchecked = asks.filter((row) => !checked.includes(String(row['productId']))).length;
-  const empty = new Set<string>();
-  await Promise.all(
-    checked.map(async (productId) => {
-      try {
-        // The item asks for initiatives to be reviewed before they are planned: it stands while one sits in the
-        // backlog or todo column. Read by column, not status: status stays in_progress after a first run even when
-        // the initiative is moved back to todo, and one in Build is past review.
-        const pages = await Promise.all(
-          (['backlog', 'in_progress'] as const).map((status) =>
-            client.listBacklogItems(productId, { status, limit: 100 })
-          )
-        );
-        const waiting = pages.some((page) =>
-          page.data.some((item) => item.state === 'backlog' || item.state === 'todo')
-        );
-        if (waiting) return;
-        if (pages.some((page) => page.nextCursor)) {
-          unchecked += asks.filter((row) => row['productId'] === productId).length;
-          return;
-        }
-        empty.add(productId);
-      } catch (error) {
-        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
-        unchecked += asks.filter((row) => row['productId'] === productId).length;
-      }
-    })
-  );
-  for (const row of asks) {
-    if (empty.has(String(row['productId']))) {
-      out.set(String(row['id']), 'no initiative is in the backlog or todo now: the ones it asked about have moved on');
-    }
-  }
-  return unchecked;
-}
-
-/**
- * One product's Action Required as counts, the way the list's summary counts them: open is what still stands and is
- * not put off, stale and snoozed are counted apart. The product context reports these, so the two reads agree.
- */
-export async function attentionCounts(
-  client: TaigaClient,
-  rows: Row[]
-): Promise<{ open: number; byKind: Record<string, number>; stale?: number; snoozed?: number; staleNote?: string }> {
-  const now = Date.now();
-  const due = rows.filter((row) => isDue(row, now));
-  const { stale, unchecked } = await staleReviews(client, due);
-  const [entry] = summaryOf(due, stale);
-  const snoozed = rows.length - due.length;
-  return {
-    open: entry ? Number(entry['open']) : 0,
-    byKind: entry ? (entry['byKind'] as Record<string, number>) : {},
-    ...(entry && typeof entry['stale'] === 'number' ? { stale: entry['stale'] } : {}),
-    ...(snoozed > 0 ? { snoozed } : {}),
-    // Past the cap a review is counted open: say so, as the list does.
-    ...(unchecked > 0
-      ? {
-          staleNote: `${unchecked} review${unchecked === 1 ? ' was' : 's were'} not checked for staleness and count as open.`,
-        }
-      : {}),
-  };
-}
-
-/** An item the team has not put off: the page hides one until its snooze ends, and so does this. */
-function isDue(row: Row, now: number): boolean {
-  return !(
-    row['status'] === 'snoozed' &&
-    typeof row['snoozedUntil'] === 'string' &&
-    Date.parse(row['snoozedUntil']) > now
-  );
-}
-
-/** Pages read for the summary; past this it says it counted only those. */
-const SUMMARY_PAGE = 100;
-
-const SETUP_TASK_FIELDS = [
-  'id',
-  'productId',
-  'productName',
-  'category',
-  'phase',
-  'target',
-  'key',
-  'isSecret',
-  'title',
-  'providerDocUrl',
-  'providerActionUrl',
-  'inboxItemId',
-  'inboxItemStatus',
-  'createdAt',
-  'stale',
-] as const;
-
-/** The API's count across every page, on the first page; nothing from an API that does not send one. */
-function totalOf(result: { totalCount?: unknown }): { totalCount?: number } {
-  return typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {};
-}
-
-/**
- * One row per variable: tasks filed before the API merged a key's categories
- * (PRO-2782) still list JWT_SECRET once as a secret and once as an env_var.
- * The oldest row stays, and names the others under alsoFiledAs, so the
- * duplicates read as one thing to set with several records, not several things.
- */
-export function sameKeyOnce(rows: Row[]): Row[] {
-  const first = new Map<string, Row>();
-  const out: Row[] = [];
-  const isOpen = (row: Row) => row['inboxItemStatus'] !== 'done' && row['inboxItemStatus'] !== 'dismissed';
-  for (const row of rows) {
-    if (typeof row['key'] !== 'string' || !row['key']) {
-      out.push(row);
-      continue;
-    }
-    const key = `${String(row['productId'])}:${row['key']}`;
-    const kept = first.get(key);
-    if (!kept) {
-      const copy = { ...row };
-      first.set(key, copy);
-      out.push(copy);
-      continue;
-    }
-    const also = (kept['alsoFiledAs'] as Row[] | undefined) ?? [];
-    const record = (from: Row) => ({
-      id: from['id'],
-      category: from['category'],
-      title: from['title'],
-      inboxItemStatus: from['inboxItemStatus'],
-    });
-    if (!isOpen(kept) && isOpen(row)) {
-      // An open record of the variable leads: a done one must not make it read as done.
-      const { alsoFiledAs: _also, ...was } = kept;
-      for (const field of Object.keys(kept)) delete kept[field];
-      Object.assign(kept, row, { alsoFiledAs: [...also, record(was)] });
-    } else {
-      kept['alsoFiledAs'] = [...also, record(row)];
-      // Stale only while every open record is (PRO-2819): one raised after the code's documents were derived
-      // is a live ask, whichever record leads.
-      if (isOpen(row) && row['stale'] === undefined) delete kept['stale'];
-    }
-  }
-  return out;
-}
-
-/** A page of folded rows, saying how many records it folded so totalCount (records) and the rows reconcile. */
-function folded(rows: Row[], nextCursor: string | null, records: number) {
-  return { ...page(rows, nextCursor), ...(rows.length < records ? { recordsOnPage: records } : {}) };
-}
-
-export function registerInboxTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('products:read')) return;
-
-  server.registerTool(
-    'taiga_list_action_required',
-    {
-      title: 'List what needs a person',
-      description:
-        'List what waits on a person (Action Required), across every product the key can open or one; the list ' +
-        "is the team's. Reviews (plans, initiative sets, documents, pull requests, findings, policy violations) " +
-        'and setup only a person can do (secrets, variables, accounts, permissions). The first page opens with ' +
-        'summary (open items by product and kind; stale ones apart) and totalCount. Rows carry waitingDays, ' +
-        'readWith (the read that opens the subject), summary (its opening paragraph, up to 200 characters; none ' +
-        'on a pull request review, whose title says it) and, for a pull request, prUrl; ' +
-        'status and blocking appear when not open or when blocking; a review that no longer stands is marked stale. category: gate or setup; resolved: true ' +
-        'reads the archive; snoozed items are hidden (snoozedHidden); full: true adds metadata. Unlike ' +
-        'taiga_list_setup_tasks, which says exactly what to set and where.',
-      inputSchema: z.object({
-        productId: productId.optional(),
-        category: z.enum(['gate', 'setup']).optional().describe('gate: things to review; setup: things to set up'),
-        resolved: z.boolean().optional().describe('Read the resolved archive (done and dismissed) instead'),
-        full: z
-          .boolean()
-          .optional()
-          .describe("Carry each item's metadata, such as a document decision's whole text (default false)"),
-        ...pagination,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        // The route coerces any value to a boolean, so "false" would read the
-        // archive: send resolved only when it is asked for.
-        const { resolved, full, ...rest } = params;
-        const query = { ...rest, ...(resolved ? { resolved: true } : {}) };
-        const first = params.cursor === undefined;
-        const result = await client.listInbox({ ...query, ...(first ? { withTotal: true } : {}) });
-        // The summary counts what is open across products, on the first page:
-        // from the page itself when it holds everything, else from one read
-        // of up to SUMMARY_PAGE items. Best effort: a failed read leaves the
-        // summary out, not the page the agent asked for.
-        const overview =
-          !first || resolved
-            ? null
-            : !result.nextCursor
-              ? result
-              : await client.listInbox({ ...query, limit: SUMMARY_PAGE, cursor: undefined }).catch((error: unknown) => {
-                  if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
-                  throw error;
-                });
-        // The API returns snoozed items, as they are not done; the page hides
-        // one until its snooze ends, and so does this, so an agent does not
-        // act on what the team put off.
-        const now = Date.now();
-        const due_ = (row: Row) => isDue(row, now);
-        const rows = result.data as Row[];
-        const due = rows.filter(due_);
-        const hidden = rows.length - due.length;
-        const overviewDue = overview ? (overview.data as Row[]).filter(due_) : [];
-        const checked = resolved
-          ? { stale: new Map<string, string>(), unchecked: 0 }
-          : await staleReviews(client, [...due, ...overviewDue]);
-        const stale = checked.stale;
-        return toolResult({
-          ...(overview
-            ? {
-                summary: summaryOf(overviewDue, stale),
-                ...(overview.nextCursor ? { summaryNote: `The summary counts the first ${SUMMARY_PAGE} items.` } : {}),
-              }
-            : {}),
-          ...page(
-            due.map((row) => {
-              const item = itemRow(row, now, full === true, client.hasCapability('backlog:read'));
-              const why = stale.get(String(row['id']));
-              return why ? { ...item, stale: why } : item;
-            }),
-            result.nextCursor
-          ),
-          ...totalOf(result),
-          // totalCount is the API's, every item; the summary's open leaves stale and put-off ones out. A reviewer
-          // summed one and compared it with the other (68 against 63).
-          ...(overview &&
-          typeof result.totalCount === 'number' &&
-          (stale.size > 0 || overview.data.length > overviewDue.length || overview.nextCursor)
-            ? {
-                totalNote:
-                  'totalCount counts every item, stale and snoozed ones too; summary.open does not' +
-                  (overview.nextCursor ? `, and counts only the first ${SUMMARY_PAGE}.` : '.'),
-              }
-            : {}),
-          ...(hidden > 0 ? { snoozedHidden: hidden } : {}),
-          // Past the cap a review is not checked, so no stale on it is not "live".
-          ...(checked.unchecked > 0
-            ? {
-                staleNote: `${checked.unchecked} review${checked.unchecked === 1 ? ' was' : 's were'} not checked for staleness (past the cap, or the read was refused).`,
-              }
-            : {}),
-        });
-      })
-  );
-
-  server.registerTool(
-    'taiga_list_setup_tasks',
-    {
-      title: 'List setup tasks',
-      description:
-        'List what a person must set up for a product (secrets, variables, accounts), with exactly what and ' +
-        'where: key (the name to create; Taiga never stores values), the provider page, and phase: prereq (the ' +
-        'deploy fails without it), wiring (generated values back to providers) or followup (can wait until after ' +
-        'launch). Runs do not wait for them. One product or all, oldest first; includeDone: true adds done and ' +
-        'dismissed. A variable filed twice lists the others under alsoFiledAs; totalCount counts records, and a ' +
-        'page that folded some says recordsOnPage. stale on an open task says no document derived from the code ' +
-        'since it was raised mentions its key: it may not apply any more, so check before asking anyone to set ' +
-        'it. Unlike ' +
-        'taiga_list_action_required, which lists the same work as items to resolve.',
-      inputSchema: z.object({
-        productId: productId.optional(),
-        includeDone: z.boolean().optional().describe('Also the tasks already done or dismissed (default false)'),
-        ...pagination,
-      }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const { includeDone, ...rest } = params;
-        const result = await client.listSetupTasks({
-          ...rest,
-          ...(includeDone ? {} : { openOnly: true }),
-          ...(params.cursor === undefined ? { withTotal: true } : {}),
-        });
-        return toolResult({
-          ...folded(
-            sameKeyOnce(pickFields(result.data as Row[], SETUP_TASK_FIELDS)),
-            result.nextCursor,
-            result.data.length
-          ),
-          ...totalOf(result),
-        });
-      })
-  );
-
-  if (!client.hasCapability('products:write')) return;
-
-  server.registerTool(
-    'taiga_resolve_action',
-    {
-      title: 'Resolve or snooze an Action Required item',
-      description:
-        'Set an Action Required item for everybody: done, dismissed (does not apply), in_progress, or snooze it ' +
-        'until a time (null wakes it). Resolving a review approves or merges nothing; answer the plan or pull ' +
-        'request where it lives. Marking the product documents review done records, in your name, that every ' +
-        'published document was reviewed (in_progress withdraws it): only when the person says they read them. ' +
-        'Ask before clearing what the person has not dealt with.',
-      inputSchema: z.object({
-        actionId: idInput('Action Required item', 'taiga_list_action_required gives it'),
-        status: z.enum(['in_progress', 'done', 'dismissed']).optional().describe('What became of it'),
-        snoozedUntil: z
-          .string()
-          .datetime()
-          // format: date-time says it; the leap-year pattern beside it ran to hundreds of characters (PRO-2800).
-          .meta({ pattern: undefined })
-          .nullable()
-          .optional()
-          .describe('Hide it until this time (ISO 8601 in UTC, ending in Z); null wakes it now'),
-      }),
-      annotations: OPERATE,
-    },
-    (params) =>
-      runTool(async () => {
-        if (params.status === undefined && params.snoozedUntil === undefined) {
-          return toolError('VALIDATION_ERROR', 'Say what became of the item (status) or until when to snooze it.');
-        }
-        const result = await client.updateInboxItem(params.actionId, {
-          ...(params.status !== undefined ? { status: params.status } : {}),
-          ...(params.snoozedUntil !== undefined ? { snoozedUntil: params.snoozedUntil } : {}),
-        });
-        return toolResult(pickFields([result.data], ITEM_FIELDS)[0]);
-      })
-  );
-}