kanbo-cli 0.2.0 → 0.3.0

package/dist/lib/mcp/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_manifest = require("../manifest-RDyoGrVR.cjs");
-const require_migrations_path = require("../migrations-path-CZxVOgeD.cjs");
+const require_manifest = require("../manifest-QPoQl8tn.cjs");
+const require_migrations_path = require("../migrations-path-DBCE17dT.cjs");
 let zod = require("zod");
 //#region src/mcp/http-transport.ts
 const IssueSchema = zod.z.object({
@@ -88,6 +88,26 @@ const SprintSchema = zod.z.object({
 	})
 });
 const PrimeSchema = zod.z.object({ text: zod.z.string() });
+const ACTOR_KINDS = [
+	"user",
+	"agent",
+	"provider-target",
+	"system"
+];
+/** A comment as the server lists it; who wrote it by the stored kind, `system.*` markers included. */
+const CardCommentSchema = zod.z.object({
+	id: zod.z.string(),
+	authorKind: zod.z.string(),
+	content: zod.z.string(),
+	createdAt: zod.z.number()
+});
+const FieldChangeSchema = zod.z.object({
+	field: zod.z.string(),
+	fromValue: zod.z.string().nullable(),
+	toValue: zod.z.string().nullable(),
+	actorKind: zod.z.enum(ACTOR_KINDS),
+	createdAt: zod.z.number()
+});
 function createHttpTransport(input) {
 	const { request } = input;
 	async function readColumns() {
@@ -111,36 +131,135 @@ function createHttpTransport(input) {
 		});
 		return column;
 	}
+	async function listCards(filters) {
+		const query = new URLSearchParams({
+			workspaceId: input.workspaceId(),
+			...filters
+		});
+		return zod.z.array(IssueSchema).parse(await request("GET", `/issues/?${query.toString()}`));
+	}
+	/**
+	* The cards a query picks. A server of the `/issues` routes filters on one
+	* column and on a parent, and no more; the rest of the query is applied here,
+	* to the cards it answered with, so the answer is the one the board file gives.
+	*
+	* The server filters on a parent's id only, and an agent may name the parent
+	* the way it names any card — `WOR-001`, `WOR-1`, `1`. The id is asked first;
+	* when no card answers it, the board is read whole to learn which card the
+	* reference names, and a reference that names none is refused as `issue_not_found`.
+	*/
+	async function cardPage(cardQuery) {
+		const columns = await readColumns();
+		const statusIds = cardQuery.columns === void 0 ? null : new Set(cardQuery.columns.map((column) => requireColumn(columns, column).id));
+		const filters = statusIds?.size === 1 ? { statusId: [...statusIds][0] } : {};
+		let parent = cardQuery.parent;
+		let rows = await listCards(parent === void 0 ? filters : {
+			...filters,
+			parentIssueId: parent
+		});
+		if (parent !== void 0 && rows.length === 0) {
+			const board = await listCards({});
+			const named = findCardRow(board, parent);
+			if (!named) throw new require_migrations_path.BoardError("issue_not_found", { issueId: parent });
+			parent = named.id;
+			rows = board;
+		}
+		const matched = rows.filter((row) => require_manifest.matchesKanboCardQuery(row, {
+			...cardQuery,
+			parent,
+			returned: void 0
+		}, statusIds));
+		const picked = cardQuery.returned === void 0 ? matched : (await withAttention(matched)).filter((row) => require_manifest.matchesKanboCardQuery(row, cardQuery, null));
+		const offset = cardQuery.offset ?? 0;
+		return {
+			cards: (await withAttention(picked.slice(offset, cardQuery.limit === void 0 ? void 0 : offset + cardQuery.limit))).map((row) => require_manifest.projectKanboCard(row, columns)),
+			total: picked.length,
+			offset
+		};
+	}
+	/**
+	* The cards with what a list says beside the ones a person has to look at or
+	* sent back — their comments read one card at a time, since the route lists
+	* none, and only for cards that are waiting, or neither waiting nor running.
+	*/
+	async function withAttention(rows) {
+		return await Promise.all(rows.map(async (row) => {
+			if (row.attention || row.waitingFor !== "human" && row.activeRun !== null) return row;
+			const comments = zod.z.array(CardCommentSchema).parse(await request("GET", `/issues/${encodeURIComponent(row.id)}/comments`));
+			const decision = comments.filter((comment) => comment.authorKind === "system.approved" || comment.authorKind === "system.returned").at(-1);
+			const returned = row.waitingFor !== "human" && decision?.authorKind === "system.returned";
+			const latest = comments.filter((comment) => comment.authorKind !== "system.run").at(-1);
+			const lastComment = (row.waitingFor === "human" || returned) && latest ? require_manifest.previewComment({
+				...latest,
+				authorKind: latest.authorKind
+			}) : null;
+			return {
+				...row,
+				attention: {
+					returned,
+					lastComment
+				}
+			};
+		}));
+	}
+	/** The ready cards, a page of them; the server answers the whole queue. */
+	async function readyPage({ returnedLimit, ...page }) {
+		const query = new URLSearchParams({ workspaceId: input.workspaceId() });
+		const cards = zod.z.array(IssueSchema).parse(await request("GET", `/issues/ready?${query.toString()}`));
+		const columns = await readColumns();
+		const offset = page.offset ?? 0;
+		const ready = {
+			cards: cards.slice(offset, page.limit === void 0 ? void 0 : offset + page.limit).map((row) => require_manifest.projectKanboCard(row, columns)),
+			total: cards.length,
+			offset
+		};
+		return returnedLimit === void 0 ? ready : {
+			...ready,
+			returned: await cardPage({
+				returned: true,
+				limit: returnedLimit
+			})
+		};
+	}
 	return {
 		prime: async () => PrimeSchema.parse(await request("GET", `/issues/prime?workspaceId=${encodeURIComponent(input.workspaceId())}`)),
-		ready: async ({ limit }) => {
-			const query = new URLSearchParams({ workspaceId: input.workspaceId() });
-			if (limit !== void 0) query.set("limit", String(limit));
-			const cards = zod.z.array(IssueSchema).parse(await request("GET", `/issues/ready?${query.toString()}`));
-			const columns = await readColumns();
-			return cards.map((row) => require_manifest.projectKanboCard(row, columns));
-		},
+		ready: async ({ limit }) => (await readyPage({ limit })).cards,
+		readyPage,
 		columns: readColumns,
 		sprints: async () => zod.z.array(SprintSchema).parse(await request("GET", `/issues/sprints?workspaceId=${encodeURIComponent(input.workspaceId())}`)).map(require_manifest.projectKanboSprint),
-		cardGet: async ({ card }) => {
+		cardGet: async ({ card, include = require_manifest.DEFAULT_KANBO_CARD_INCLUDES, commentLimit = 10 }) => {
 			const found = IssueSchema.parse(await request("GET", `/issues/${encodeURIComponent(card)}`));
-			const columns = await readColumns();
+			const wants = new Set(include);
+			const path = `/issues/${encodeURIComponent(found.id)}`;
 			const query = new URLSearchParams({
 				workspaceId: input.workspaceId(),
 				parentIssueId: found.id
 			});
-			const subCards = zod.z.array(IssueSchema).parse(await request("GET", `/issues/?${query.toString()}`));
+			const [columns, subCards, comments, runs, history, pullRequests] = await Promise.all([
+				readColumns(),
+				wants.has("subCards") ? request("GET", `/issues/?${query.toString()}`).then((rows) => zod.z.array(IssueSchema).parse(rows)) : null,
+				wants.has("comments") ? request("GET", `${path}/comments`).then((rows) => zod.z.array(CardCommentSchema).parse(rows)) : null,
+				wants.has("runs") ? request("GET", `${path}/runs`).then((rows) => zod.z.array(RunSchema).parse(rows)) : null,
+				wants.has("history") ? request("GET", `${path}/field-changes`).then((rows) => zod.z.array(FieldChangeSchema).parse(rows)) : null,
+				wants.has("prs") ? request("GET", `${path}/pull-requests`).then((rows) => zod.z.array(PullRequestSchema).parse(rows)) : null
+			]);
 			return {
 				...require_manifest.projectKanboCard(found, columns),
-				subCards: subCards.map((row) => require_manifest.projectKanboSubCard(row, columns))
+				...subCards ? { subCards: subCards.map((row) => require_manifest.projectKanboSubCard(row, columns)) } : {},
+				...comments ? {
+					comments: comments.slice(-commentLimit).map(require_manifest.projectKanboCardComment),
+					commentCount: comments.length
+				} : {},
+				...runs ? { runs: runs.map(require_manifest.projectKanboRun) } : {},
+				...history ? { history: history.map(require_manifest.projectKanboFieldChange) } : {},
+				...pullRequests ? { pullRequests: pullRequests.map(require_manifest.projectKanboPullRequest) } : {}
 			};
 		},
-		cardList: async ({ column, limit }) => {
-			const columns = await readColumns();
-			const query = new URLSearchParams({ workspaceId: input.workspaceId() });
-			if (column) query.set("statusId", requireColumn(columns, column).id);
-			return zod.z.array(IssueSchema).parse(await request("GET", `/issues/?${query.toString()}`)).slice(0, limit ?? Number.POSITIVE_INFINITY).map((row) => require_manifest.projectKanboCard(row, columns));
-		},
+		cardList: async ({ column, limit }) => (await cardPage({
+			columns: column ? [column] : void 0,
+			limit
+		})).cards,
+		cardPage,
 		cardCreate: async ({ title, description, column, parent, executionMode }) => await projectOne(await request("POST", "/issues/", {
 			workspaceId: input.workspaceId(),
 			...title !== void 0 ? { title } : {},
@@ -168,9 +287,25 @@ function createHttpTransport(input) {
 		})))
 	};
 }
+/**
+* The card a reference names among cards already read, the way the board file
+* resolves one: its id, its number, or its key without the padding (`WOR-1`).
+*/
+function findCardRow(rows, reference) {
+	const trimmed = reference.trim();
+	const byId = rows.find((row) => row.id === trimmed);
+	if (byId) return byId;
+	const key = /^(?:(.+)-)?(\d+)$/.exec(trimmed);
+	if (!key) return;
+	const [, prefix, digits] = key;
+	return rows.find((row) => row.number === Number(digits) && (prefix === void 0 || row.id.slice(0, row.id.lastIndexOf("-")).toUpperCase() === prefix.toUpperCase()));
+}
 //#endregion
+exports.DEFAULT_KANBO_CARD_INCLUDES = require_manifest.DEFAULT_KANBO_CARD_INCLUDES;
+exports.DEFAULT_KANBO_COMMENT_LIMIT = require_manifest.DEFAULT_KANBO_COMMENT_LIMIT;
 exports.KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI = require_manifest.KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI;
 exports.KANBO_CAPABILITIES_RESOURCE_URI = require_manifest.KANBO_CAPABILITIES_RESOURCE_URI;
+exports.KANBO_CARD_INCLUDES = require_manifest.KANBO_CARD_INCLUDES;
 exports.KANBO_MCP_INSTRUCTIONS = require_manifest.KANBO_MCP_INSTRUCTIONS;
 exports.KANBO_MCP_SERVER_NAME = require_manifest.KANBO_MCP_SERVER_NAME;
 exports.KANBO_TOOLS = require_manifest.KANBO_TOOLS;
@@ -179,7 +314,7 @@ exports.KANBO_TOOL_NAMES = require_manifest.KANBO_TOOL_NAMES;
 exports.buildKanboTools = require_manifest.buildKanboTools;
 exports.createHttpTransport = createHttpTransport;
 exports.createKanboMcpServer = require_manifest.createKanboMcpServer;
+exports.matchesKanboCardQuery = require_manifest.matchesKanboCardQuery;
+exports.pageOf = require_manifest.pageOf;
 exports.registerKanboCapabilitiesResources = require_manifest.registerKanboCapabilitiesResources;
 exports.registerKanboTools = require_manifest.registerKanboTools;
-
-//# sourceMappingURL=index.cjs.map

package/dist/lib/mcp/index.d.cts

@@ -1,5 +1,5 @@
 import { s as IssueRun, t as Issue } from "../schema-D0MyXcej.cjs";
-import { i as KanboToolName, n as KANBO_TOOL_NAMES, r as KanboToolCliEquivalent, s as EntryRule, t as KANBO_TOOL_CLI_EQUIVALENTS } from "../tool-names-WfH4IURz.cjs";
+import { _ as EntryRule, d as KANBO_TOOL_CLI_EQUIVALENTS, f as KANBO_TOOL_NAMES, i as IssueActorKind, m as KanboToolName, p as KanboToolCliEquivalent, r as CardLastComment } from "../approval-BsBk2xVr.cjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
@@ -40,13 +40,86 @@ interface KanboCardResult {
   /** The run going on right now, `null` when nobody is working on the card. */
   activeRun: KanboActiveRunResult | null;
   updatedAt: number;
+  /** Present on a list's card a person sent back that nobody has picked up again. */
+  returned?: true;
+  /** On a list's card waiting for a person or returned: its latest comment, cut short. */
+  lastComment?: CardLastComment;
 }
+/** What `kanbo_card_get` may bring along with the card. */
+export declare const KANBO_CARD_INCLUDES: readonly ['comments', 'subCards', 'runs', 'history', 'prs'];
+type KanboCardInclude = typeof KANBO_CARD_INCLUDES[number];
+/** What a card read brings along when the caller does not say: its latest comments and its sub-cards. */
+export declare const DEFAULT_KANBO_CARD_INCLUDES: readonly KanboCardInclude[];
+/** How many of its latest comments a card read brings along when the caller does not say. */
+export declare const DEFAULT_KANBO_COMMENT_LIMIT = 10;
 /**
  * A card read on its own, as `kanbo_card_get` hands it to an agent: the card,
- * and the sub-cards under it in board order. Its parent is `parentIssueId`.
+ * and whatever the read was asked to bring along — the sub-cards under it in
+ * board order, its latest comments, its runs, its field history, the pull
+ * requests it names. Its parent is `parentIssueId`.
  */
 interface KanboCardDetailResult extends KanboCardResult {
-  subCards: Pick<KanboCardResult, 'id' | 'title' | 'columnSlug'>[];
+  subCards?: Pick<KanboCardResult, 'id' | 'title' | 'columnSlug'>[];
+  /** The latest comments, oldest of them first; `commentCount` says how many the card has in all. */
+  comments?: KanboCardCommentResult[];
+  commentCount?: number;
+  /** Every run, first attempt first. */
+  runs?: KanboRunResult[];
+  /** Every tracked field change, oldest first. */
+  history?: KanboFieldChangeResult[];
+  pullRequests?: KanboPullRequestResult[];
+}
+/** A comment as a card read lists it: who wrote it — a person, an agent or the board — and what it says. */
+interface KanboCardCommentResult {
+  id: string;
+  author: IssueActorKind;
+  content: string;
+  createdAt: number;
+}
+/** One change to a tracked field of a card, and who made it. */
+interface KanboFieldChangeResult {
+  field: string;
+  from: string | null;
+  to: string | null;
+  actor: IssueActorKind;
+  createdAt: number;
+}
+/**
+ * Which cards `kanbo_card_list` picks, and which page of them. Every filter is
+ * optional and they all apply together.
+ */
+interface KanboCardQuery {
+  /** Cards in any of these columns, by slug or name. */
+  columns?: string[];
+  /** `true`: only cards waiting for a person; `false`: only cards waiting for no one. */
+  waitingForPerson?: boolean;
+  /** Only the sub-cards of this card, by its id. */
+  parent?: string;
+  /** `true`: only cards an agent is working on now; `false`: only cards nobody is. */
+  hasActiveRun?: boolean;
+  /** `true`: only cards a person sent back that nobody has picked up again; `false`: every other card. */
+  returned?: boolean;
+  /** Cards whose id, title or description contains this text, ignoring case. */
+  text?: string;
+  /** Cards changed at or after this moment, in unix seconds. */
+  updatedSince?: number;
+  /** Cards carrying every one of these labels. */
+  labels?: string[];
+  /** Cards of any of these priorities. */
+  priority?: Issue['priority'][];
+  offset?: number;
+  /** How many cards to return; every one picked when absent. */
+  limit?: number;
+}
+/** One page of cards, and how many the question picks in all. */
+interface KanboCardPage {
+  cards: KanboCardResult[];
+  total: number;
+  offset: number;
+}
+/** The ready cards, with the returned ones when they were asked for. */
+interface KanboReadyPage extends KanboCardPage {
+  returned?: KanboCardPage;
 }
 /** The run of a card that is going on right now. */
 interface KanboActiveRunResult {
@@ -167,15 +240,30 @@ interface KanboToolTransport {
   ready: (input: {
     limit?: number;
   }) => Promise<KanboCardResult[]>;
+  /**
+   * One page of the ready cards, and how many are ready in all — and, when
+   * `returnedLimit` is given, up to that many cards a person sent back
+   * (`KanboCardQuery.returned`), which an agent continues before anything new.
+   */
+  readyPage: (input: {
+    limit?: number;
+    offset?: number;
+    returnedLimit?: number;
+  }) => Promise<KanboReadyPage>;
   columns: () => Promise<KanboColumnResult[]>;
   sprints: () => Promise<KanboSprintResult[]>;
+  /** The card, with what `include` names — `DEFAULT_KANBO_CARD_INCLUDES` when absent. */
   cardGet: (input: {
     card: string;
+    include?: readonly KanboCardInclude[];
+    commentLimit?: number;
   }) => Promise<KanboCardDetailResult>;
   cardList: (input: {
     column?: string;
     limit?: number;
   }) => Promise<KanboCardResult[]>;
+  /** One page of the cards a query picks, and how many it picks in all. */
+  cardPage: (input: KanboCardQuery) => Promise<KanboCardPage>;
   cardCreate: (input: KanboCardCreateInput) => Promise<KanboCardResult>;
   cardUpdate: (input: KanboCardUpdateInput) => Promise<KanboCardResult>;
   cardMove: (input: {
@@ -204,6 +292,44 @@ interface KanboToolTransport {
   runStart: (input: KanboRunStartInput) => Promise<KanboRunResult>;
   runFinish: (input: KanboRunFinishInput) => Promise<KanboRunResult>;
 }
+/**
+ * A card as either transport already has it: the row's own fields with the
+ * labels decoded, plus what the run registry says about it.
+ */
+interface KanboCardFacts {
+  id: string;
+  number: number;
+  title: string;
+  description: string | null;
+  statusId: string | null;
+  statusLine: string | null;
+  waitingFor: 'human' | null;
+  priority: Issue['priority'];
+  labels: string[];
+  executionMode: Issue['executionMode'];
+  parentIssueId: string | null;
+  updatedAt: number;
+  attemptCount: number;
+  activeRun: KanboActiveRunResult | null;
+  /** What a list says beside a card a person has to look at, or sent back; absent where nobody asked. */
+  attention?: {
+    returned: boolean;
+    lastComment: CardLastComment | null;
+  };
+}
+/**
+ * Does the card answer the query? The filters of `KanboCardQuery`, applied to
+ * a card already read — for a transport whose server filters on less than the
+ * query names. `statusIds` are the query's columns, already resolved.
+ */
+export declare function matchesKanboCardQuery(card: KanboCardFacts & {
+  description: string | null;
+}, query: KanboCardQuery, statusIds: ReadonlySet<string> | null): boolean;
+/** A page cut out of cards already picked, in the order they were picked. */
+export declare function pageOf(cards: KanboCardResult[], input: {
+  offset?: number;
+  limit?: number;
+}): KanboCardPage;
 //#endregion
 //#region src/mcp/http-transport.d.ts
 /**
@@ -299,7 +425,17 @@ interface KanboTool {
   name: KanboToolName;
   title: string;
   description: string;
+  /** The arguments under their canonical names — what the tool publishes and the manifest lists. */
   inputSchema: KanboToolShape;
+  /**
+   * What the MCP server registers: the same JSON Schema as `inputSchema`, but
+   * accepting anything, so a call with a wrong or aliased argument reaches
+   * `run` — which answers it in a sentence — instead of the server's own
+   * validation dump.
+   */
+  registrationSchema: z.ZodType;
+  /** Other names each argument is accepted under, canonical name first. */
+  aliases: Readonly<Record<string, readonly string[]>>;
   run: (transport: KanboToolTransport, input: unknown) => Promise<KanboToolResult>;
 }
 //#endregion
@@ -359,5 +495,4 @@ export declare function registerKanboTools(server: McpServer, transport: KanboTo
  */
 export declare function createKanboMcpServer(transport: KanboToolTransport, options: KanboToolOptions): McpServer;
 //#endregion
-export { KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanboActiveRunResult, type KanboCardResult, type KanboColumnResult, type KanboCommentResult, type KanboHttpRequest, type KanboHttpTransportInput, type KanboPullRequestResult, type KanboRunResult, type KanboTool, type KanboToolCliEquivalent, type KanboToolName, type KanboToolOptions, type KanboToolRegistration, type KanboToolResult, type KanboToolTransport };
-//# sourceMappingURL=index.d.cts.map
+export { KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanboActiveRunResult, type KanboCardCommentResult, type KanboCardCreateInput, type KanboCardDetailResult, type KanboCardFacts, type KanboCardInclude, type KanboCardPage, type KanboCardQuery, type KanboCardResult, type KanboCardUpdateInput, type KanboColumnResult, type KanboCommentResult, type KanboFieldChangeResult, type KanboHttpRequest, type KanboHttpTransportInput, type KanboPullRequestResult, type KanboReadyPage, type KanboRunFinishInput, type KanboRunResult, type KanboRunStartInput, type KanboSprintResult, type KanboTool, type KanboToolCliEquivalent, type KanboToolName, type KanboToolOptions, type KanboToolRegistration, type KanboToolResult, type KanboToolTransport };

package/dist/lib/mcp/index.d.mts

@@ -1,5 +1,5 @@
 import { s as IssueRun, t as Issue } from "../schema-D0MyXcej.mjs";
-import { i as KanboToolName, n as KANBO_TOOL_NAMES, r as KanboToolCliEquivalent, s as EntryRule, t as KANBO_TOOL_CLI_EQUIVALENTS } from "../tool-names-3q_GEZej.mjs";
+import { _ as EntryRule, d as KANBO_TOOL_CLI_EQUIVALENTS, f as KANBO_TOOL_NAMES, i as IssueActorKind, m as KanboToolName, p as KanboToolCliEquivalent, r as CardLastComment } from "../approval-LRZ6ontC.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
@@ -40,13 +40,86 @@ interface KanboCardResult {
   /** The run going on right now, `null` when nobody is working on the card. */
   activeRun: KanboActiveRunResult | null;
   updatedAt: number;
+  /** Present on a list's card a person sent back that nobody has picked up again. */
+  returned?: true;
+  /** On a list's card waiting for a person or returned: its latest comment, cut short. */
+  lastComment?: CardLastComment;
 }
+/** What `kanbo_card_get` may bring along with the card. */
+export declare const KANBO_CARD_INCLUDES: readonly ['comments', 'subCards', 'runs', 'history', 'prs'];
+type KanboCardInclude = typeof KANBO_CARD_INCLUDES[number];
+/** What a card read brings along when the caller does not say: its latest comments and its sub-cards. */
+export declare const DEFAULT_KANBO_CARD_INCLUDES: readonly KanboCardInclude[];
+/** How many of its latest comments a card read brings along when the caller does not say. */
+export declare const DEFAULT_KANBO_COMMENT_LIMIT = 10;
 /**
  * A card read on its own, as `kanbo_card_get` hands it to an agent: the card,
- * and the sub-cards under it in board order. Its parent is `parentIssueId`.
+ * and whatever the read was asked to bring along — the sub-cards under it in
+ * board order, its latest comments, its runs, its field history, the pull
+ * requests it names. Its parent is `parentIssueId`.
  */
 interface KanboCardDetailResult extends KanboCardResult {
-  subCards: Pick<KanboCardResult, 'id' | 'title' | 'columnSlug'>[];
+  subCards?: Pick<KanboCardResult, 'id' | 'title' | 'columnSlug'>[];
+  /** The latest comments, oldest of them first; `commentCount` says how many the card has in all. */
+  comments?: KanboCardCommentResult[];
+  commentCount?: number;
+  /** Every run, first attempt first. */
+  runs?: KanboRunResult[];
+  /** Every tracked field change, oldest first. */
+  history?: KanboFieldChangeResult[];
+  pullRequests?: KanboPullRequestResult[];
+}
+/** A comment as a card read lists it: who wrote it — a person, an agent or the board — and what it says. */
+interface KanboCardCommentResult {
+  id: string;
+  author: IssueActorKind;
+  content: string;
+  createdAt: number;
+}
+/** One change to a tracked field of a card, and who made it. */
+interface KanboFieldChangeResult {
+  field: string;
+  from: string | null;
+  to: string | null;
+  actor: IssueActorKind;
+  createdAt: number;
+}
+/**
+ * Which cards `kanbo_card_list` picks, and which page of them. Every filter is
+ * optional and they all apply together.
+ */
+interface KanboCardQuery {
+  /** Cards in any of these columns, by slug or name. */
+  columns?: string[];
+  /** `true`: only cards waiting for a person; `false`: only cards waiting for no one. */
+  waitingForPerson?: boolean;
+  /** Only the sub-cards of this card, by its id. */
+  parent?: string;
+  /** `true`: only cards an agent is working on now; `false`: only cards nobody is. */
+  hasActiveRun?: boolean;
+  /** `true`: only cards a person sent back that nobody has picked up again; `false`: every other card. */
+  returned?: boolean;
+  /** Cards whose id, title or description contains this text, ignoring case. */
+  text?: string;
+  /** Cards changed at or after this moment, in unix seconds. */
+  updatedSince?: number;
+  /** Cards carrying every one of these labels. */
+  labels?: string[];
+  /** Cards of any of these priorities. */
+  priority?: Issue['priority'][];
+  offset?: number;
+  /** How many cards to return; every one picked when absent. */
+  limit?: number;
+}
+/** One page of cards, and how many the question picks in all. */
+interface KanboCardPage {
+  cards: KanboCardResult[];
+  total: number;
+  offset: number;
+}
+/** The ready cards, with the returned ones when they were asked for. */
+interface KanboReadyPage extends KanboCardPage {
+  returned?: KanboCardPage;
 }
 /** The run of a card that is going on right now. */
 interface KanboActiveRunResult {
@@ -167,15 +240,30 @@ interface KanboToolTransport {
   ready: (input: {
     limit?: number;
   }) => Promise<KanboCardResult[]>;
+  /**
+   * One page of the ready cards, and how many are ready in all — and, when
+   * `returnedLimit` is given, up to that many cards a person sent back
+   * (`KanboCardQuery.returned`), which an agent continues before anything new.
+   */
+  readyPage: (input: {
+    limit?: number;
+    offset?: number;
+    returnedLimit?: number;
+  }) => Promise<KanboReadyPage>;
   columns: () => Promise<KanboColumnResult[]>;
   sprints: () => Promise<KanboSprintResult[]>;
+  /** The card, with what `include` names — `DEFAULT_KANBO_CARD_INCLUDES` when absent. */
   cardGet: (input: {
     card: string;
+    include?: readonly KanboCardInclude[];
+    commentLimit?: number;
   }) => Promise<KanboCardDetailResult>;
   cardList: (input: {
     column?: string;
     limit?: number;
   }) => Promise<KanboCardResult[]>;
+  /** One page of the cards a query picks, and how many it picks in all. */
+  cardPage: (input: KanboCardQuery) => Promise<KanboCardPage>;
   cardCreate: (input: KanboCardCreateInput) => Promise<KanboCardResult>;
   cardUpdate: (input: KanboCardUpdateInput) => Promise<KanboCardResult>;
   cardMove: (input: {
@@ -204,6 +292,44 @@ interface KanboToolTransport {
   runStart: (input: KanboRunStartInput) => Promise<KanboRunResult>;
   runFinish: (input: KanboRunFinishInput) => Promise<KanboRunResult>;
 }
+/**
+ * A card as either transport already has it: the row's own fields with the
+ * labels decoded, plus what the run registry says about it.
+ */
+interface KanboCardFacts {
+  id: string;
+  number: number;
+  title: string;
+  description: string | null;
+  statusId: string | null;
+  statusLine: string | null;
+  waitingFor: 'human' | null;
+  priority: Issue['priority'];
+  labels: string[];
+  executionMode: Issue['executionMode'];
+  parentIssueId: string | null;
+  updatedAt: number;
+  attemptCount: number;
+  activeRun: KanboActiveRunResult | null;
+  /** What a list says beside a card a person has to look at, or sent back; absent where nobody asked. */
+  attention?: {
+    returned: boolean;
+    lastComment: CardLastComment | null;
+  };
+}
+/**
+ * Does the card answer the query? The filters of `KanboCardQuery`, applied to
+ * a card already read — for a transport whose server filters on less than the
+ * query names. `statusIds` are the query's columns, already resolved.
+ */
+export declare function matchesKanboCardQuery(card: KanboCardFacts & {
+  description: string | null;
+}, query: KanboCardQuery, statusIds: ReadonlySet<string> | null): boolean;
+/** A page cut out of cards already picked, in the order they were picked. */
+export declare function pageOf(cards: KanboCardResult[], input: {
+  offset?: number;
+  limit?: number;
+}): KanboCardPage;
 //#endregion
 //#region src/mcp/http-transport.d.ts
 /**
@@ -299,7 +425,17 @@ interface KanboTool {
   name: KanboToolName;
   title: string;
   description: string;
+  /** The arguments under their canonical names — what the tool publishes and the manifest lists. */
   inputSchema: KanboToolShape;
+  /**
+   * What the MCP server registers: the same JSON Schema as `inputSchema`, but
+   * accepting anything, so a call with a wrong or aliased argument reaches
+   * `run` — which answers it in a sentence — instead of the server's own
+   * validation dump.
+   */
+  registrationSchema: z.ZodType;
+  /** Other names each argument is accepted under, canonical name first. */
+  aliases: Readonly<Record<string, readonly string[]>>;
   run: (transport: KanboToolTransport, input: unknown) => Promise<KanboToolResult>;
 }
 //#endregion
@@ -359,5 +495,4 @@ export declare function registerKanboTools(server: McpServer, transport: KanboTo
  */
 export declare function createKanboMcpServer(transport: KanboToolTransport, options: KanboToolOptions): McpServer;
 //#endregion
-export { KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanboActiveRunResult, type KanboCardResult, type KanboColumnResult, type KanboCommentResult, type KanboHttpRequest, type KanboHttpTransportInput, type KanboPullRequestResult, type KanboRunResult, type KanboTool, type KanboToolCliEquivalent, type KanboToolName, type KanboToolOptions, type KanboToolRegistration, type KanboToolResult, type KanboToolTransport };
-//# sourceMappingURL=index.d.mts.map
+export { KANBO_TOOL_CLI_EQUIVALENTS, KANBO_TOOL_NAMES, type KanboActiveRunResult, type KanboCardCommentResult, type KanboCardCreateInput, type KanboCardDetailResult, type KanboCardFacts, type KanboCardInclude, type KanboCardPage, type KanboCardQuery, type KanboCardResult, type KanboCardUpdateInput, type KanboColumnResult, type KanboCommentResult, type KanboFieldChangeResult, type KanboHttpRequest, type KanboHttpTransportInput, type KanboPullRequestResult, type KanboReadyPage, type KanboRunFinishInput, type KanboRunResult, type KanboRunStartInput, type KanboSprintResult, type KanboTool, type KanboToolCliEquivalent, type KanboToolName, type KanboToolOptions, type KanboToolRegistration, type KanboToolResult, type KanboToolTransport };