@protobase/server 0.51.2 → 0.52.0

package/dist/aggregate-groups.js

@@ -1,8 +1,8 @@
 import { badRequest } from "./problem.js";
-import { readTransaction } from "./transactions.js";
-import { parseParams } from "./params.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
+import { readTransaction } from "./transactions.js";
 import { splitGroups } from "./aggregate-splits.js";
+import { parseParams } from "./params.js";
 import { scoped, seriesRange } from "./aggregate-service.js";
 import { z } from "zod";
 import { groupTotals, series } from "@protobase/query";

package/dist/aggregate-service.js

@@ -1,15 +1,15 @@
 import { badRequest } from "./problem.js";
 import { checkedFilter } from "./filter-input.js";
 import { requestAccess, requireOperation } from "./request-access.js";
-import { readTransaction } from "./transactions.js";
-import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
-import { parseParams } from "./params.js";
 import { readScope } from "./read-scope.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
+import { readTransaction } from "./transactions.js";
+import { parseParams } from "./params.js";
 import { rangeEnd, rangeStart } from "./range-ends.js";
+import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { z } from "zod";
-import { sql } from "kysely";
 import { facetCounts, histogram, series, tenantCondition, withoutField } from "@protobase/query";
+import { sql } from "kysely";
 //#region src/aggregate-service.ts
 const field = z.string().min(1);
 const filter = z.string().optional();

package/dist/aggregate-splits.js

@@ -1,5 +1,5 @@
-import { readTransaction } from "./transactions.js";
 import { labelRequests, relatedLabels } from "./related-labels.js";
+import { readTransaction } from "./transactions.js";
 import { series, splitSeries } from "@protobase/query";
 //#region src/aggregate-splits.ts
 /**

package/dist/assistant/batch-approval.js

@@ -1,59 +1,57 @@
-const shownResources = 20;
-const valueLength = 80;
-const nameLength = 60;
-const unicodeEscape = (char) => {
-	const code = char.codePointAt(0);
-	return code > 65535 ? `\\u{${code.toString(16)}}` : `\\u${code.toString(16).padStart(4, "0")}`;
-};
-const escaped = (json) => json.replace(/[\p{Cc}\p{Cf}\u2028\u2029`<>]/gu, unicodeEscape).replace(/"(?:[^"\\]|\\.)*"/g, (text) => text.replace(/[[\]]/g, unicodeEscape));
-const cut = (text, length) => text.length > length ? `${text.slice(0, length - 1)}…` : text;
-const quoted = (value, length) => cut(escaped(JSON.stringify(value) ?? "null"), length);
-const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
-const counted = (value, length) => {
-	const text = escaped(JSON.stringify(value) ?? "null");
-	return text.length > length ? `${text.slice(0, length)}… (${plural(text.length - length, "more character")})` : text;
-};
-const fieldsOf = (data) => `{${Object.entries(data).map(([name, value]) => `${counted(name, nameLength)}:${counted(value, valueLength)}`).join(",")}}`;
-const lineOf = (operation, index) => {
-	const target = operation.op === "create" ? quoted(operation.resource, nameLength) : `${quoted(operation.resource, nameLength)} ${quoted(operation.key, nameLength)}`;
-	const values = operation.op === "delete" ? "" : ` ${fieldsOf(operation.data)}`;
-	return `${index + 1}. ${operation.op} ${target}${values}`;
-};
-const countsOf = (operations) => {
-	const counts = /* @__PURE__ */ new Map();
-	for (const { op, resource } of operations) {
-		const known = counts.get(resource) ?? {
-			create: 0,
-			update: 0,
-			delete: 0
+import { createChange, recordName, resourceLabel, shown, updateChange } from "./write-prompts.js";
+const isRef = (value) => typeof value === "object" && value !== null && typeof value.$ref === "string";
+const refOfKey = (key) => Array.isArray(key) ? key.find(isRef) : isRef(key) ? key : void 0;
+const joined = (fields, none) => fields.length > 0 ? fields.map(({ label, value }) => `${label}: ${value}`).join("; ") : none;
+/** The approval of `operations` as one transaction. */
+const batchApproval = ({ text, described, operations, before, softDeletes }) => {
+	const creates = new Map(operations.flatMap((operation, index) => operation.op === "create" && operation.ref ? [[operation.ref, {
+		index,
+		resource: operation.resource
+	}]] : []));
+	const refName = ({ $ref }) => {
+		const created = creates.get($ref);
+		return created ? text.fromWrite(resourceLabel(described(created.resource)), created.index + 1) : `"${shown($ref)}"`;
+	};
+	const dataOf = (data) => Object.fromEntries(Object.entries(data).map(([name, value]) => [name, isRef(value) ? refName(value) : value]));
+	const nameOf = (operation, index) => {
+		const ref = refOfKey(operation.key);
+		return ref ? refName(ref) : recordName(described(operation.resource), operation.key, before.get(index) ?? {});
+	};
+	const entryOf = (operation, index) => {
+		const resource = described(operation.resource);
+		const label = (action) => `${index + 1}. ${action}`;
+		if (operation.op === "create") {
+			const { action, fields } = createChange(text, resource, dataOf(operation.data));
+			return {
+				label: label(action),
+				value: joined(fields, text.noFields)
+			};
+		}
+		if (operation.op === "update") {
+			const { action, fields } = updateChange(text, resource, nameOf(operation, index), before.get(index) ?? {}, dataOf(operation.data));
+			return {
+				label: label(action),
+				value: joined(fields, text.noChanges)
+			};
+		}
+		return {
+			label: label(text.deleteAction(nameOf(operation, index))),
+			value: softDeletes.has(operation.resource) ? text.restorable : text.permanent
 		};
-		known[op] += 1;
-		counts.set(resource, known);
-	}
-	return [...counts];
-};
-const capped = (lines) => lines.length > shownResources ? [...lines.slice(0, shownResources), `and ${plural(lines.length - shownResources, "more resource")}`] : lines;
-/**
-* The approval of `operations`; `softDeletes` names the resources whose deletes can be restored, and a delete on any
-* other is said to be permanent.
-*/
-const batchApproval = (operations, softDeletes) => {
-	const counts = countsOf(operations);
-	const permanent = counts.filter(([resource, { delete: deletes }]) => deletes > 0 && !softDeletes.has(resource));
-	const lasting = permanent.reduce((sum, [, { delete: deletes }]) => sum + deletes, 0);
-	const warning = lasting > 0 ? [`${plural(lasting, "delete")} cannot be undone:`, ...capped(permanent.map(([resource, { delete: deletes }]) => `${plural(deletes, "delete")} in ${quoted(resource, nameLength)}`))] : [];
-	const summary = capped(counts.map(([resource, count]) => `${quoted(resource, nameLength)}: ${plural(count.create, "create")}, ${plural(count.update, "update")}, ${plural(count.delete, "delete")}`));
+	};
+	const permanent = operations.filter((operation) => operation.op === "delete" && !softDeletes.has(operation.resource)).length;
 	const rest = operations.length - 50;
-	const lines = operations.slice(0, 50).map(lineOf);
 	return {
-		title: `Run ${plural(operations.length, "write")} in one transaction?`,
+		title: text.batchTitle(operations.length),
 		body: [
-			...warning,
-			"Either all of them are written or none.",
-			...summary
+			...permanent > 0 ? [text.permanentDeletes(permanent)] : [],
+			text.allOrNone,
+			...rest > 0 ? [text.moreWrites(rest)] : []
 		].join("\n"),
-		code: [...lines, ...rest > 0 ? [`and ${plural(rest, "more operation")}, counted above`] : []].join("\n"),
-		approveLabel: "Write all"
+		fields: operations.slice(0, 50).map(entryOf),
+		tone: permanent > 0 ? "danger" : "warning",
+		approveLabel: text.writeAll,
+		rejectLabel: text.reject
 	};
 };
 //#endregion

package/dist/assistant/batch-before.js

@@ -0,0 +1,38 @@
+import { HttpProblem, preconditionFailed } from "../problem.js";
+import { ifMatchSatisfied } from "../etag.js";
+import { keyOf } from "./record-tool-args.js";
+import { hidden } from "./record-before.js";
+//#region src/assistant/batch-before.ts
+const atOperation = (error, index, { op, resource }) => error instanceof HttpProblem ? new HttpProblem(error.status, error.slug, error.title, error.detail, {
+	...error.extras,
+	operation: index,
+	op,
+	resource
+}) : error;
+const recordAt = async (context, operation, key, index) => {
+	const current = await context.records.get(operation.resource, key).catch((error) => {
+		if (hidden(error)) return void 0;
+		throw atOperation(error, index, operation);
+	});
+	if (current && operation.etag && !ifMatchSatisfied(operation.etag, current.etag)) throw atOperation(preconditionFailed("The record changed since it was read; fetch it again"), index, operation);
+	return current?.record;
+};
+/**
+* The records the first `count` operations update or delete, by index, as the caller reads them now, for the approval
+* to name and show what changes; one they may not read, or whose key points at a create in the batch, is left out. A
+* record changed since its operation's etag rejects before asking, as the batch would fail after the user approved;
+* so does any other refusal of the read, naming the operation.
+*/
+const batchBefore = async (context, operations, count) => {
+	const before = /* @__PURE__ */ new Map();
+	for (const [index, operation] of operations.slice(0, count).entries()) {
+		if (operation.op === "create") continue;
+		const key = keyOf(operation.key);
+		if (key === void 0) continue;
+		const record = await recordAt(context, operation, key, index);
+		if (record) before.set(index, record);
+	}
+	return before;
+};
+//#endregion
+export { batchBefore };

package/dist/assistant/batch-echo.js

@@ -0,0 +1,36 @@
+import { HttpProblem } from "../problem.js";
+import { keyOf } from "./record-tool-args.js";
+import { writeEcho } from "./write-echo.js";
+//#region src/assistant/batch-echo.ts
+const unread = (error) => {
+	if (error instanceof HttpProblem && error.status < 500) return void 0;
+	throw error;
+};
+/**
+* Each update's record as the caller reads it before the batch, for the read-only fields the batch changes; undefined
+* for a create, a delete, and an update of a record created earlier in the batch, whose key is a `$ref`.
+*/
+const recordsBefore = async (context, operations) => {
+	const befores = [];
+	for (const operation of operations) {
+		const key = operation.op === "update" ? keyOf(operation.key) : void 0;
+		befores.push(key === void 0 ? void 0 : await context.records.get(operation.resource, key).then((current) => current.record, unread));
+	}
+	return befores;
+};
+/** The batch's results, each create's and update's record cut to its key, etag, written and changed read-only fields, and `fields`. */
+const batchEcho = async (context, operations, results, befores, fields) => {
+	const { models } = await context.resources();
+	return results.map((result, index) => {
+		if (result.op !== "create" && result.op !== "update") return result;
+		const operation = operations[index];
+		const { record: _record, etag: _etag, ...rest } = result;
+		const model = models.find((candidate) => candidate.name === result.resource);
+		return {
+			...rest,
+			...writeEcho(model, result, operation.data, befores[index], fields[index])
+		};
+	});
+};
+//#endregion
+export { batchEcho, recordsBefore };

package/dist/assistant/batch-write-args.js

@@ -1,22 +1,26 @@
+import { echoFieldsOf } from "./write-echo.js";
 //#region src/assistant/batch-write-args.ts
 /**
 * The `batch_write` tool's arguments, checked before anything is asked or written: only creates, updates and deletes,
 * only the fields each takes, an update's ETag always given, and no more operations than the REST batch takes. A
-* delete's ETag passes exactly as sent, so one left out stays left out.
+* delete's ETag passes exactly as sent, so one left out stays left out. A create's or update's `fields`, what to give
+* back of its record, comes apart from the operation the REST batch runs.
 */
 const fieldsOf = {
 	create: [
 		"op",
 		"resource",
 		"data",
-		"ref"
+		"ref",
+		"fields"
 	],
 	update: [
 		"op",
 		"resource",
 		"key",
 		"etag",
-		"data"
+		"data",
+		"fields"
 	],
 	delete: [
 		"op",
@@ -39,12 +43,13 @@ const problemOf = (value, index) => {
 	if (unknown.length > 0) return `${at} has fields a ${op} does not take: ${unknown.map((name) => JSON.stringify(name)).join(", ")}`;
 	if (!isText(value.resource)) return `${at} needs the resource's name`;
 	if (op !== "delete" && !isObject(value.data)) return `${at} needs its data as an object of field names to values`;
+	if (op !== "delete" && !echoFieldsOf(value.fields)) return `${at} has fields that are not a list of field names`;
 	if (op === "create") return value.ref === void 0 || isText(value.ref) ? void 0 : `${at} has a ref that is not a name`;
 	if (!isKey(value.key)) return `${at} needs the record's key: a string, a number, a list of them, or { "$ref": "<name>" }`;
 	if (op === "update" && !isText(value.etag)) return `${at} needs the etag the record was read with, or "*" to update any version`;
 	if (op === "delete" && "etag" in value && typeof value.etag !== "string") return `${at} has an etag that is not a string`;
 };
-/** The operations to run, or why the batch is refused, naming the operation at fault. */
+/** The operations to run, each with the fields to give back of its record, or why the batch is refused, naming the operation at fault. */
 const batchOperationsOf = (args) => {
 	const unknown = Object.keys(args).filter((name) => name !== "operations");
 	if (unknown.length > 0) return { problem: `The batch takes only "operations", not ${unknown.map((name) => JSON.stringify(name)).join(", ")}` };
@@ -57,7 +62,11 @@ const batchOperationsOf = (args) => {
 	}
 	const refs = operations.flatMap((operation) => operation.ref === void 0 ? [] : [operation.ref]);
 	if (new Set(refs).size !== refs.length) return { problem: "Each create may use a ref name once" };
-	return { operations };
+	const fields = operations.map((operation) => echoFieldsOf(operation.fields));
+	return {
+		operations: operations.map(({ fields: _fields, ...operation }) => operation),
+		fields
+	};
 };
 //#endregion
 export { batchOperationsOf };

package/dist/assistant/batch-write-tool.js

@@ -1,12 +1,20 @@
 import { HttpProblem } from "../problem.js";
+import { forcedJson } from "./result-budget.js";
 import { defineTool } from "./tools.js";
+import { cutRecordNote } from "./budgeted-page.js";
+import { writeText } from "./write-messages.js";
+import { describedResource } from "./write-prompts.js";
+import { fieldsParameter } from "./write-echo.js";
 import { batchApproval } from "./batch-approval.js";
+import { batchBefore } from "./batch-before.js";
+import { batchEcho, recordsBefore } from "./batch-echo.js";
 import { batchOperationsOf } from "./batch-write-args.js";
 //#region src/assistant/batch-write-tool.ts
 /**
 * `batch_write`: many creates, updates and deletes across resources in one transaction, through the REST API's batch
-* write, after the user approves the batch once. Over MCP the tool runs again from the start with the user's answer, so
-* everything before `approve` only checks the arguments and builds the approval text: nothing is read or written.
+* write, after the user approves the batch once, seeing each write in their language. Over MCP the tool runs again from
+* the start with the user's answer, so everything before `approve` only checks the arguments and reads what the approval
+* names: nothing is written.
 */
 const writes = {
 	readOnlyHint: false,
@@ -44,10 +52,17 @@ const softDeleteSet = async (context, operations) => {
 		});
 	}
 };
-const softDeletesFor = async (context, operations) => {
-	if (!operations.some((operation) => operation.op === "delete")) return /* @__PURE__ */ new Set();
-	const { models } = await context.resources();
-	return new Set(models.filter((model) => model.softDelete).map((model) => model.name));
+const approvalOf = async (context, operations) => {
+	const before = await batchBefore(context, operations, 50).catch(refused);
+	if (typeof before === "string") return before;
+	const readable = await context.resources();
+	return batchApproval({
+		text: writeText(context.locale ?? "en"),
+		described: (resource) => describedResource(readable, resource),
+		operations,
+		before,
+		softDeletes: new Set(readable.models.filter((model) => model.softDelete).map((model) => model.name))
+	});
 };
 const operationsParameter = (input) => ({
 	type: "array",
@@ -84,14 +99,15 @@ const operationsParameter = (input) => ({
 			ref: {
 				type: "string",
 				description: "A create's name, for later operations to point at."
-			}
+			},
+			fields: fieldsParameter
 		}
 	}
 });
 /** Runs many writes in one transaction once the user approves them, under the caller's access rules. */
 const batchWriteTool = (input = {}) => defineTool({
 	name: "batch_write",
-	description: `Creates, updates and deletes records across resources in one transaction: either all are written or none, and an update or delete with an etag fails the batch when its record changed since. Returns { results } with each created or updated record and its new etag. The user approves the batch in their client first; nothing is written without it.${input.resources ? ` It writes only ${input.resources.join(", ")}.` : ""}`,
+	description: `Creates, updates and deletes records across resources in one transaction: either all are written or none, and an update or delete with an etag fails the batch when its record changed since. Returns { results }: each created or updated record's key, new etag and, in record, the fields written and the read-only fields the batch changed. The user approves the batch in their client first; nothing is written without it.${input.resources ? ` It writes only ${input.resources.join(", ")}.` : ""}`,
 	parameters: {
 		type: "object",
 		properties: { operations: operationsParameter(input) },
@@ -101,14 +117,17 @@ const batchWriteTool = (input = {}) => defineTool({
 	run: async (args, context) => {
 		const parsed = batchOperationsOf(args);
 		if ("problem" in parsed) return refusal("invalid-argument", `${parsed.problem}; nothing was written.`);
-		const { operations } = parsed;
+		const { operations, fields } = parsed;
 		const outsideRefusal = outside(input, operations);
 		if (outsideRefusal) return outsideRefusal;
 		const softDeleteRefusal = await softDeleteSet(context, operations).catch(refused);
 		if (softDeleteRefusal) return softDeleteRefusal;
-		const answer = await context.approve(batchApproval(operations, await softDeletesFor(context, operations)));
+		const approval = await approvalOf(context, operations);
+		if (typeof approval === "string") return approval;
+		const answer = await context.approve(approval);
 		if (answer !== "approved") return `The user did not approve this batch (${answer}); nothing was written.`;
-		return context.records.batch(operations).then((results) => JSON.stringify({ results }), refused);
+		const befores = await recordsBefore(context, operations);
+		return context.records.batch(operations).then(async (results) => forcedJson({ results: await batchEcho(context, operations, results, befores, fields) }, cutRecordNote), refused);
 	}
 });
 //#endregion

package/dist/assistant/budgeted-page.js

@@ -0,0 +1,30 @@
+import { budgetedJson, forcedJson, leadingFit } from "./result-budget.js";
+//#region src/assistant/budgeted-page.ts
+/** How a record tool's result says to read a field it cut. */
+const cutRecordNote = "The fields in cut_fields were cut to fit the size limit, each with its full length; read the rest of one with get_record and its field, offset and max_chars arguments.";
+const fewerNote = (count) => `Only ${count} records fit the size limit; pass next_page_token as page_token for the next ones. ${cutRecordNote}`;
+/**
+* A page of records as JSON within the size budget: its strings trimmed, then, when that does not fit, the page
+* listed again with as many records as fit, so its next_page_token goes on from the last one returned.
+*/
+const budgetedPage = async (page, params, list) => {
+	const json = budgetedJson(page, cutRecordNote);
+	if (json) return json;
+	if (page.items.length <= 1) return forcedJson(page, cutRecordNote);
+	const fits = (count) => budgetedJson({
+		...page,
+		items: page.items.slice(0, count),
+		note: fewerNote(count)
+	}, fewerNote(count)) !== void 0;
+	const count = leadingFit(page.items.length - 1, fits);
+	const fewer = await list({
+		...params,
+		page_size: count
+	});
+	return forcedJson({
+		...fewer,
+		note: fewerNote(fewer.items.length)
+	}, fewerNote(fewer.items.length));
+};
+//#endregion
+export { budgetedPage, cutRecordNote };

package/dist/assistant/comment-tools.d.ts

@@ -0,0 +1,20 @@
+import { AssistantTool } from "./tools.js";
+import { WriteRecordToolsInput } from "./write-tool-limits.js";
+//#region src/assistant/comment-tools.d.ts
+/** The resources whose records take comments (`.comments()`), the only ones the comment tools reach. */
+export type CommentToolsInput = {
+  commented: string[];
+};
+/** Reads a page of a record's comments, newest first, under the caller's access rules. */
+export declare const listCommentsTool: (input: CommentToolsInput) => AssistantTool;
+/**
+ * Adds the caller's comment to a record once the user approves it, under the caller's access rules. Given `resources`,
+ * it comments only on those, and refuses any other before asking.
+ */
+export declare const addCommentTool: (input: CommentToolsInput & WriteRecordToolsInput) => AssistantTool;
+/**
+ * `list_comments`, and `add_comment` when `writes` allows writing: on the resources with comments, and of those only
+ * the ones `writes` lists when it lists some. None when no resource takes comments.
+ */
+export declare const commentTools: ({ commented }: CommentToolsInput, writes: false | WriteRecordToolsInput) => AssistantTool[];
+//#endregion

package/dist/assistant/comment-tools.js

@@ -0,0 +1,120 @@
+import { notFound } from "../problem.js";
+import { defineTool } from "./tools.js";
+import { parseCommentInput } from "../comments/comment-input.js";
+import { keyOf, keyParameter, refused, resourceOf, resourceParameter } from "./record-tool-args.js";
+import { commentApproval } from "./write-prompts.js";
+import { approvalTexts } from "./record-before.js";
+import { notApproved, onlyNote, outside } from "./write-tool-limits.js";
+//#region src/assistant/comment-tools.ts
+const defaultPageSize = 20;
+const maxPageSize = 100;
+const resourceParameterOf = (resources) => ({
+	...resourceParameter,
+	description: `The resource's name: one of ${resources.join(", ")}, whose records take comments.`
+});
+const commentsOf = (context) => {
+	if (!context.comments) throw new Error("The comment tools need ToolContext.comments, which the MCP endpoint gives");
+	return context.comments;
+};
+const uncommented = ({ commented }, resource) => commented.includes(resource) ? void 0 : refused(notFound(`${resource} takes no comments`));
+/** Reads a page of a record's comments, newest first, under the caller's access rules. */
+const listCommentsTool = (input) => defineTool({
+	name: "list_comments",
+	description: "Lists the comments on one record, newest first, as JSON ({ items: [{ author, created_at, text }], next_page_token }). Pass next_page_token back as page_token for the next page; it is empty on the last.",
+	parameters: {
+		type: "object",
+		properties: {
+			resource: resourceParameterOf(input.commented),
+			key: keyParameter,
+			page_size: {
+				type: "integer",
+				minimum: 1,
+				maximum: maxPageSize,
+				description: `Comments per page, ${defaultPageSize} by default.`
+			},
+			page_token: {
+				type: "string",
+				description: "The next_page_token of the previous page."
+			}
+		},
+		required: ["resource", "key"]
+	},
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	run: async (args, context) => {
+		const resource = resourceOf(args);
+		const key = keyOf(args.key);
+		if (!resource || key === void 0) return "Pass the resource and key as { \"resource\": \"<name>\", \"key\": \"<key>\" }.";
+		const refusal = uncommented(input, resource);
+		if (refusal) return refusal;
+		const params = {
+			page_size: typeof args.page_size === "number" ? Math.min(args.page_size, maxPageSize) : defaultPageSize,
+			...typeof args.page_token === "string" && args.page_token && { page_token: args.page_token }
+		};
+		return commentsOf(context).list(resource, key, params).then((page) => JSON.stringify(page), refused);
+	}
+});
+/**
+* Adds the caller's comment to a record once the user approves it, under the caller's access rules. Given `resources`,
+* it comments only on those, and refuses any other before asking.
+*/
+const addCommentTool = (input) => defineTool({
+	name: "add_comment",
+	description: `Adds a comment by you to one record and returns it as JSON ({ author, created_at, text }). The user approves each comment in their client first; nothing is written without it.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			resource: resourceParameterOf(input.resources ?? input.commented),
+			key: keyParameter,
+			text: {
+				type: "string",
+				description: "The comment, plain text."
+			}
+		},
+		required: [
+			"resource",
+			"key",
+			"text"
+		]
+	},
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		openWorldHint: false
+	},
+	run: async (args, context) => {
+		const resource = resourceOf(args);
+		const key = keyOf(args.key);
+		const text = typeof args.text === "string" ? args.text : void 0;
+		if (!resource || key === void 0 || text === void 0) return "Pass the resource, key and text as { \"resource\": \"<name>\", \"key\": \"<key>\", \"text\": \"<comment>\" }.";
+		const refusal = outside(input, resource) ?? uncommented(input, resource);
+		if (refusal) return refusal;
+		const invalid = await Promise.resolve().then(() => parseCommentInput({ body: text }, String(context.session.user.id))).then(() => void 0, refused);
+		if (invalid) return invalid;
+		const current = await context.records.get(resource, key).catch(refused);
+		if (typeof current === "string") return current;
+		const { text: texts, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(commentApproval(texts, described, key, current.record, text));
+		if (answer !== "approved") return notApproved(answer);
+		return commentsOf(context).add(resource, key, text).then((comment) => JSON.stringify(comment), refused);
+	}
+});
+/**
+* `list_comments`, and `add_comment` when `writes` allows writing: on the resources with comments, and of those only
+* the ones `writes` lists when it lists some. None when no resource takes comments.
+*/
+const commentTools = ({ commented }, writes) => {
+	if (commented.length === 0) return [];
+	const list = listCommentsTool({ commented });
+	if (writes === false) return [list];
+	const resources = writes.resources?.filter((name) => commented.includes(name));
+	if (resources?.length === 0) return [list];
+	return [list, addCommentTool({
+		commented,
+		...resources && { resources }
+	})];
+};
+//#endregion
+export { addCommentTool, commentTools, listCommentsTool };

package/dist/assistant/count-records-tool.d.ts

@@ -0,0 +1,5 @@
+import { AssistantTool } from "./tools.js";
+//#region src/assistant/count-records-tool.d.ts
+/** Counts a resource's records, in all or per value of a field, through the REST API's `count=exact` and `:aggregate`. */
+export declare const countRecordsTool: () => AssistantTool;
+//#endregion

package/dist/assistant/count-records-tool.js

@@ -0,0 +1,84 @@
+import { exactCountLimit } from "../list-service.js";
+import { defineTool } from "./tools.js";
+import { invalidShowDeleted, refused, resourceOf, resourceParameter, showDeletedOf, showDeletedParameter } from "./record-tool-args.js";
+//#region src/assistant/count-records-tool.ts
+const maxGroups = 1e3;
+const invalid = (parameter, message) => JSON.stringify({
+	error: "invalid-parameter",
+	message: `Invalid parameter ${parameter}: ${message}`
+});
+const total = async (context, resource, filter, showDeleted) => {
+	const page = await context.records.list(resource, {
+		...filter !== void 0 && { filter },
+		page_size: 1,
+		count: "exact",
+		...showDeleted && { show_deleted: true }
+	});
+	if (page.total_size !== void 0) return { count: page.total_size };
+	return {
+		more_than: exactCountLimit,
+		estimate: page.total_size_estimate
+	};
+};
+/** Counts a resource's records, in all or per value of a field, through the REST API's `count=exact` and `:aggregate`. */
+const countRecordsTool = () => defineTool({
+	name: "count_records",
+	description: `Counts the records of a resource that a filter finds, without returning them, as JSON. Without group_by it answers { count }, or { more_than: ${exactCountLimit}, estimate } when more match. With group_by, a filterable field, it answers { group_by, groups: [{ value, count, label? }] }: the records per value, largest first, adding up to what the filter finds; a date or timestamp group_by counts per day over the last 30 days instead. filter uses the AIP-160 syntax of list_records.`,
+	parameters: {
+		type: "object",
+		properties: {
+			resource: resourceParameter,
+			filter: {
+				type: "string",
+				description: "An AIP-160 filter on filterable fields, such as status = \"open\" AND amount > 10."
+			},
+			group_by: {
+				type: "string",
+				description: "A filterable field to count the records of per value, such as status."
+			},
+			limit: {
+				type: "integer",
+				minimum: 1,
+				maximum: maxGroups,
+				description: "With group_by, the most groups to return, 100 by default."
+			},
+			label: {
+				type: "string",
+				description: "With a relation group_by, a field of the linked resource to name each value by, such as name."
+			},
+			show_deleted: {
+				...showDeletedParameter,
+				description: "true also counts soft-deleted records; only without group_by, on a resource list_resources marks soft_delete."
+			}
+		},
+		required: ["resource"]
+	},
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	run: async (args, context) => {
+		const resource = resourceOf(args);
+		if (!resource) return "Pass the resource as { \"resource\": \"<name>\" }.";
+		const showDeleted = showDeletedOf(args);
+		if (showDeleted === void 0) return invalidShowDeleted;
+		const filter = typeof args.filter === "string" ? args.filter : void 0;
+		const groupBy = typeof args.group_by === "string" && args.group_by ? args.group_by : void 0;
+		if (groupBy === void 0) {
+			if (args.limit !== void 0 || args.label !== void 0) return invalid(args.limit !== void 0 ? "limit" : "label", "Only with group_by");
+			return total(context, resource, filter, showDeleted).then((counted) => JSON.stringify(counted), refused);
+		}
+		if (showDeleted) return invalid("show_deleted", "Not with group_by");
+		if (args.limit !== void 0 && !Number.isInteger(args.limit)) return invalid("limit", "Pass a whole number");
+		if (args.label !== void 0 && typeof args.label !== "string") return invalid("label", "Pass a field name");
+		const params = {
+			group_by: groupBy,
+			...filter !== void 0 && { filter },
+			...typeof args.limit === "number" && { limit: args.limit },
+			...typeof args.label === "string" && { label: args.label }
+		};
+		return context.records.aggregate(resource, params).then((groups) => JSON.stringify(groups), refused);
+	}
+});
+//#endregion
+export { countRecordsTool };