@protobase/server 0.51.3 → 0.52.0

package/dist/assistant/query-result-budget.js

@@ -0,0 +1,32 @@
+import { budgetedJson, forcedJson, leadingFit } from "./result-budget.js";
+//#region src/assistant/query-result-budget.ts
+const cutCellNote = "The values in cut_fields were cut to fit the size limit, each with its full length (rows[r][c] is row r, column c); read the rest of one with substring(<column> from <start>), counting characters from 1.";
+const fewerRowsNote = (count, more) => `Only the first ${count} rows fit the size limit${more}. ${cutCellNote}`;
+/**
+* A query's result as JSON within the size budget: its strings trimmed, then, when that does not fit, only as many
+* leading rows as fit, marked truncated. `more` ends the note on the rows left out, such as how to read on.
+*/
+const budgetedQueryResult = (result, more) => {
+	const json = budgetedJson(result, cutCellNote);
+	if (json) return json;
+	if (result.rows.length <= 1) return forcedJson(result, cutCellNote);
+	const leading = (count) => {
+		const note = fewerRowsNote(count, more(count));
+		return {
+			result: {
+				...result,
+				rows: result.rows.slice(0, count),
+				truncated: true,
+				note
+			},
+			note
+		};
+	};
+	const { result: fewer, note } = leading(leadingFit(result.rows.length - 1, (count) => {
+		const { result, note } = leading(count);
+		return budgetedJson(result, note) !== void 0;
+	}));
+	return forcedJson(fewer, note);
+};
+//#endregion
+export { budgetedQueryResult };

package/dist/assistant/query-tools.js

@@ -1,7 +1,7 @@
+import { budgetedQueryResult } from "./query-result-budget.js";
 import { runReadOnlyQuery, runReadWriteQuery } from "./run-query.js";
 import { defineTool } from "./tools.js";
 //#region src/assistant/query-tools.ts
-const maxResultLength = 2e4;
 const sqlParameter = (description) => ({
 	type: "string",
 	description
@@ -11,7 +11,7 @@ const refused = (error) => {
 	if (isDatabaseError(error)) return `Postgres refused the statement: ${error.message}`;
 	throw error;
 };
-const shown = (result, statement, context) => {
+const shown = (result, statement, context, more) => {
 	context.show({
 		type: "table",
 		id: crypto.randomUUID(),
@@ -20,9 +20,9 @@ const shown = (result, statement, context) => {
 		caption: statement,
 		...result.truncated && { truncated: true }
 	});
-	const json = JSON.stringify(result);
-	return json.length > maxResultLength ? `${json.slice(0, maxResultLength)}... (cut off)` : json;
+	return budgetedQueryResult(result, more);
 };
+const readOn = (count) => `; add OFFSET ${count} to the statement to read on`;
 const statementOf = (args) => typeof args.sql === "string" && args.sql.trim() ? args.sql : void 0;
 /**
 * Lets the model read the app's database: one SELECT per call, in a read-only transaction (see `runReadOnlyQuery`).
@@ -31,7 +31,7 @@ const statementOf = (args) => typeof args.sql === "string" && args.sql.trim() ?
 */
 const readOnlyQueryTool = (db, options = {}) => defineTool({
 	name: "run_read_only_query",
-	description: `Runs one PostgreSQL SELECT on the app's database in a read-only transaction and returns up to ${options.rowLimit ?? 200} rows as JSON ({ columns, rows, truncated }). The user sees the rows as a table. Use it to answer questions about the data. It reads the app's resource tables only. It cannot change anything.`,
+	description: `Runs one PostgreSQL SELECT on the app's database in a read-only transaction and returns up to ${options.rowLimit ?? 200} rows as JSON ({ columns, rows, truncated }); a result too large for one answer holds fewer rows, with long values cut and named in cut_fields, and a note on reading the rest. The user sees the rows as a table. Use it to answer questions about the data. It reads the app's resource tables only. It cannot change anything.`,
 	parameters: {
 		type: "object",
 		properties: { sql: sqlParameter("One SELECT statement, without a trailing semicolon.") },
@@ -44,7 +44,7 @@ const readOnlyQueryTool = (db, options = {}) => defineTool({
 	run: async (args, context) => {
 		const statement = statementOf(args);
 		if (!statement) return "Pass the statement as { \"sql\": \"select ...\" }.";
-		return runReadOnlyQuery(db, statement, options).then((result) => shown(result, statement, context), refused);
+		return runReadOnlyQuery(db, statement, options).then((result) => shown(result, statement, context, readOn), refused);
 	}
 });
 /**
@@ -79,7 +79,7 @@ const readWriteQueryTool = (db, options = {}) => defineTool({
 			code: statement
 		});
 		if (answer !== "approved") return `The user did not approve the statement (${answer}); nothing ran.`;
-		return runReadWriteQuery(db, statement, options).then((result) => shown(result, statement, context), refused);
+		return runReadWriteQuery(db, statement, options).then((result) => shown(result, statement, context, () => ""), refused);
 	}
 });
 //#endregion

package/dist/assistant/record-before.js

@@ -4,6 +4,7 @@ import { refused } from "./record-tool-args.js";
 import { writeText } from "./write-messages.js";
 import { describedResource } from "./write-prompts.js";
 //#region src/assistant/record-before.ts
+/** Whether the caller's read rules hide the record from them, which leaves the write's own rules to decide. */
 const hidden = (error) => error instanceof HttpProblem && (error.status === 403 || error.status === 404);
 /**
 * The record as the caller reads it now, for what an approval names and shows before a write: undefined when they may
@@ -17,4 +18,4 @@ const approvalTexts = async (context, resource) => ({
 	described: describedResource(await context.resources(), resource)
 });
 //#endregion
-export { approvalTexts, recordBefore };
+export { approvalTexts, hidden, recordBefore };

package/dist/assistant/record-field-piece.js

@@ -0,0 +1,54 @@
+import { forcedJson } from "./result-budget.js";
+//#region src/assistant/record-field-piece.ts
+/** get_record's arguments that read one field in pieces, such as a field a result cut to fit its size limit. */
+const pieceParameters = {
+	field: {
+		type: "string",
+		description: "One field to read alone, in pieces: max_chars characters of its value from offset. A value that is not text reads as its JSON."
+	},
+	offset: {
+		type: "integer",
+		minimum: 0,
+		description: "With field: the character to start at, 0 by default."
+	},
+	max_chars: {
+		type: "integer",
+		minimum: 1,
+		maximum: 3e4,
+		description: "With field: the characters to read, 20000 by default."
+	}
+};
+const defaultChars = 2e4;
+const maxChars = 3e4;
+const invalid = (message) => JSON.stringify({
+	error: "invalid-parameter",
+	message
+});
+const countOf = (value, fallback) => value === void 0 ? fallback : typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+/** Whether the call reads one field in pieces rather than the whole record. */
+const readsPiece = (args) => args.field !== void 0;
+/**
+* The piece of `args.field` of `found` the call asks for, as JSON ({ field, offset, length, value, next_offset }), where
+* length is the whole value's and next_offset is absent once the piece reaches its end.
+*/
+const fieldPiece = (found, args) => {
+	const field = args.field;
+	if (typeof field !== "string" || !Object.hasOwn(found.record, field)) return invalid(`Invalid parameter field: pass one of ${Object.keys(found.record).join(", ")}`);
+	const offset = countOf(args.offset, 0);
+	if (offset === void 0) return invalid("Invalid parameter offset: pass a whole number from 0");
+	const chars = countOf(args.max_chars, defaultChars);
+	if (!chars) return invalid(`Invalid parameter max_chars: pass a whole number from 1 to ${maxChars}`);
+	const raw = found.record[field];
+	const text = typeof raw === "string" ? raw : JSON.stringify(raw) ?? "null";
+	const end = offset + Math.min(chars, maxChars);
+	const piece = {
+		field,
+		offset,
+		length: text.length,
+		value: text.slice(offset, end),
+		...end < text.length && { next_offset: end }
+	};
+	return forcedJson(piece, "The value was cut to fit the size limit; pass a smaller max_chars.");
+};
+//#endregion
+export { fieldPiece, pieceParameters, readsPiece };

package/dist/assistant/record-tool-args.js

@@ -1,10 +1,13 @@
 import { HttpProblem } from "../problem.js";
+import { queryProblem } from "../error-handler.js";
+import { QueryError } from "@protobase/query";
 //#region src/assistant/record-tool-args.ts
 /** A refusal the model can act on (no such resource, not allowed, a bad filter) is its to read; anything else fails the call. */
 const refused = (error) => {
-	if (error instanceof HttpProblem && error.status < 500) return JSON.stringify({
-		error: error.slug,
-		message: error.detail
+	const problem = error instanceof QueryError ? queryProblem(error) : error;
+	if (problem instanceof HttpProblem && problem.status < 500) return JSON.stringify({
+		error: problem.slug,
+		message: problem.detail
 	});
 	throw error;
 };

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

@@ -6,6 +6,9 @@ export declare const listResourcesTool: () => AssistantTool;
 export declare const listRecordsTool: () => AssistantTool;
 /** Reads one record by its key, under the caller's access rules. */
 export declare const getRecordTool: () => AssistantTool;
-/** `list_resources`, `list_records` and `get_record`: reading the app's records as the caller, through the REST API's rules. */
+/**
+ * `list_resources`, `list_records`, `count_records` and `get_record`: reading and counting the app's records as the
+ * caller, through the REST API's rules.
+ */
 export declare const readRecordTools: () => AssistantTool[];
 //#endregion

package/dist/assistant/record-tools.js

@@ -1,5 +1,9 @@
+import { forcedJson } from "./result-budget.js";
 import { defineTool } from "./tools.js";
 import { invalidShowDeleted, keyOf, keyParameter, refused, resourceOf, resourceParameter, showDeletedOf, showDeletedParameter } from "./record-tool-args.js";
+import { budgetedPage, cutRecordNote } from "./budgeted-page.js";
+import { fieldPiece, pieceParameters, readsPiece } from "./record-field-piece.js";
+import { countRecordsTool } from "./count-records-tool.js";
 //#region src/assistant/record-tools.ts
 const readOnly = {
 	readOnlyHint: true,
@@ -45,7 +49,7 @@ const listResourcesTool = () => defineTool({
 /** Finds records of a resource with the REST API's filters, sorting and pages, under the caller's access rules. */
 const listRecordsTool = () => defineTool({
 	name: "list_records",
-	description: `Finds records of a resource and returns a page of them as JSON ({ items, next_page_token, total_size_estimate }). filter uses AIP-160 syntax, such as status = "open" AND amount > 10, and order_by a comma-separated list of fields, each optionally followed by desc. Pass next_page_token back as page_token for the next page; it is empty on the last. show_deleted: true also returns soft-deleted records.`,
+	description: `Finds records of a resource and returns a page of them as JSON ({ items, next_page_token, total_size_estimate }). filter uses AIP-160 syntax, such as status = "open" AND amount > 10, and order_by a comma-separated list of fields, each optionally followed by desc. Pass next_page_token back as page_token for the next page; it is empty on the last. A page too large for one result holds fewer records, with long values cut and named in cut_fields, and a note on reading the rest. show_deleted: true also returns soft-deleted records.`,
 	parameters: {
 		type: "object",
 		properties: {
@@ -85,19 +89,21 @@ const listRecordsTool = () => defineTool({
 			page_size: typeof args.page_size === "number" ? Math.min(args.page_size, maxPageSize) : defaultPageSize,
 			...showDeleted && { show_deleted: true }
 		};
-		return context.records.list(resource, params).then((page) => JSON.stringify(page), refused);
+		const list = (paged) => context.records.list(resource, paged);
+		return list(params).then((page) => budgetedPage(page, params, list)).catch(refused);
 	}
 });
 /** Reads one record by its key, under the caller's access rules. */
 const getRecordTool = () => defineTool({
 	name: "get_record",
-	description: "Reads one record of a resource by its key and returns it as JSON ({ record, etag }). show_deleted: true also finds a soft-deleted record.",
+	description: "Reads one record of a resource by its key and returns it as JSON ({ record, etag }), with long values cut and named in cut_fields when it is too large for one result. field reads one field alone, in pieces from offset. show_deleted: true also finds a soft-deleted record.",
 	parameters: {
 		type: "object",
 		properties: {
 			resource: resourceParameter,
 			key: keyParameter,
-			show_deleted: showDeletedParameter
+			show_deleted: showDeletedParameter,
+			...pieceParameters
 		},
 		required: ["resource", "key"]
 	},
@@ -108,13 +114,18 @@ const getRecordTool = () => defineTool({
 		if (!resource || key === void 0) return "Pass the resource and key as { \"resource\": \"<name>\", \"key\": \"<key>\" }.";
 		const showDeleted = showDeletedOf(args);
 		if (showDeleted === void 0) return invalidShowDeleted;
-		return context.records.get(resource, key, { show_deleted: showDeleted }).then((record) => JSON.stringify(record), refused);
+		const shown = (found) => readsPiece(args) ? fieldPiece(found, args) : forcedJson(found, cutRecordNote);
+		return context.records.get(resource, key, { show_deleted: showDeleted }).then(shown, refused);
 	}
 });
-/** `list_resources`, `list_records` and `get_record`: reading the app's records as the caller, through the REST API's rules. */
+/**
+* `list_resources`, `list_records`, `count_records` and `get_record`: reading and counting the app's records as the
+* caller, through the REST API's rules.
+*/
 const readRecordTools = () => [
 	listResourcesTool(),
 	listRecordsTool(),
+	countRecordsTool(),
 	getRecordTool()
 ];
 //#endregion

package/dist/assistant/records.d.ts

@@ -1,4 +1,5 @@
 import { Row } from "../types.js";
+import "../registry.js";
 import "../deps.js";
 import { BatchOperation } from "../batch/schema.js";
 import { BatchResult } from "../batch/run-batch.js";
@@ -36,12 +37,30 @@ export type RecordPage = {
   total_size_estimate: number;
   total_size?: number;
 };
+/** The parameters of the REST API's `:aggregate` that count records per value of a field, as values. */
+export type AggregateParams = {
+  group_by: string;
+  filter?: string;
+  limit?: number;
+  label?: string;
+};
+/** Records per value of `group_by` as the REST API's `:aggregate` gives them, largest group first. */
+export type RecordGroups = {
+  group_by: string;
+  groups: Array<{
+    value: unknown;
+    count: number;
+    label?: string;
+  }>;
+};
 /**
  * The app's resources as the session's user: their access rules, tenant scope, validation and write hooks apply as
  * in the REST API. A refusal or a missing record rejects with an `HttpProblem`, which a tool can turn into text.
  */
 export type ToolRecords = {
   list: (resource: string, params?: ListParams) => Promise<RecordPage>;
+  /** Counts per value of a field, as `GET /{resource}:aggregate` does, under the same access rules as `list`. */
+  aggregate: (resource: string, params: AggregateParams) => Promise<RecordGroups>;
   /** With `show_deleted`, also finds a soft-deleted record, as the REST API's `show_deleted` does. */
   get: (resource: string, key: RecordKeyInput, options?: {
     show_deleted?: boolean;

package/dist/assistant/records.js

@@ -1,4 +1,5 @@
 import { notFound } from "../problem.js";
+import { aggregate } from "../aggregate-groups.js";
 import { runWrite } from "../write-pipeline.js";
 import { decodeKeyText } from "../key.js";
 import { runBatch } from "../batch/run-batch.js";
@@ -7,22 +8,27 @@ import { readRecord } from "../read-service.js";
 import { encodeKey } from "@protobase/schema/internal";
 //#region src/assistant/records.ts
 const filterLength = 2e5;
+/** The admin's resource named `resource`; a 404 when there is none. */
+const toolEntry = (deps, resource) => {
+	const entry = deps.registry.find(resource);
+	if (!entry) throw notFound(`There is no resource "${resource}"`);
+	return entry;
+};
+/** The resource named `resource` and a record's key in it, as a tool passes them. */
+const toolKey = (deps, resource, key) => {
+	const entry = toolEntry(deps, resource);
+	return {
+		entry,
+		key: decodeKeyText(entry, Array.isArray(key) ? encodeKey(key) : String(key))
+	};
+};
 /** `ToolRecords` over the admin's resources for `session`. */
 const assistantRecords = (deps, session) => {
-	const entryOf = (resource) => {
-		const entry = deps.registry.find(resource);
-		if (!entry) throw notFound(`There is no resource "${resource}"`);
-		return entry;
-	};
-	const keyOf = (resource, key) => {
-		const entry = entryOf(resource);
-		return {
-			entry,
-			key: decodeKeyText(entry, Array.isArray(key) ? encodeKey(key) : String(key))
-		};
-	};
+	const entryOf = (resource) => toolEntry(deps, resource);
+	const keyOf = (resource, key) => toolKey(deps, resource, key);
 	return {
 		list: async (resource, params = {}) => (await listRecords(deps, entryOf(resource), session, params, filterLength)).body,
+		aggregate: async (resource, params) => (await aggregate(deps, entryOf(resource), session, params)).body,
 		get: async (resource, input, { show_deleted } = {}) => {
 			const { entry, key } = keyOf(resource, input);
 			const { record, etag } = await readRecord(deps, entry, session, key, show_deleted);
@@ -60,6 +66,7 @@ const withoutAdmin = () => Promise.reject(/* @__PURE__ */ new Error("This assist
 /** Records for a turn without an admin around it, such as in a backend of its own: every call fails. */
 const noRecords = {
 	list: withoutAdmin,
+	aggregate: withoutAdmin,
 	get: withoutAdmin,
 	create: withoutAdmin,
 	update: withoutAdmin,
@@ -68,4 +75,4 @@ const noRecords = {
 	batch: withoutAdmin
 };
 //#endregion
-export { assistantRecords, noRecords };
+export { assistantRecords, noRecords, toolEntry, toolKey };

package/dist/assistant/result-budget.js

@@ -0,0 +1,72 @@
+//#region src/assistant/result-budget.ts
+/**
+* Keeps a tool result within what a model's client takes: over the budget, its longest string values are trimmed, each
+* named in `cut_fields` with its full length, and a `note` says how to read the rest. A tool with a list returns fewer
+* items when trimming alone does not fit (see `leadingFit`).
+*/
+/** The characters of JSON one tool result may hold. */
+const resultBudget = 4e4;
+const stringFloor = 500;
+const neverCut = /* @__PURE__ */ new Set(["next_page_token", "etag"]);
+const pathOf = (path, key) => path ? `${path}.${key}` : key;
+const trimmed = (value, cap, path, cuts) => {
+	if (typeof value === "string") {
+		if (value.length <= cap) return value;
+		cuts.push({
+			field: path,
+			length: value.length
+		});
+		return `${value.slice(0, cap)}…`;
+	}
+	if (Array.isArray(value)) return value.map((item, index) => trimmed(item, cap, `${path}[${index}]`, cuts));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, !path && neverCut.has(key) ? item : trimmed(item, cap, pathOf(path, key), cuts)]));
+	return value;
+};
+const longestString = (value) => {
+	if (typeof value === "string") return value.length;
+	if (value !== null && typeof value === "object") return Math.max(0, ...Object.values(value).map(longestString));
+	return 0;
+};
+const cutAt = (result, cap, note) => {
+	const cuts = [];
+	const value = trimmed(result, cap, "", cuts);
+	return JSON.stringify(cuts.length ? {
+		...value,
+		cut_fields: cuts,
+		note
+	} : value);
+};
+/**
+* `result` as JSON within `budget`, its strings trimmed as little as fits but to no fewer than `floor` characters;
+* undefined when even that does not fit. `note` says how to read a cut field's rest.
+*/
+const budgetedJson = (result, note, budget = resultBudget, floor = stringFloor) => {
+	const json = JSON.stringify(result);
+	if (json.length <= budget) return json;
+	const plain = JSON.parse(json);
+	let low = floor;
+	let high = longestString(plain);
+	if (low >= high) return void 0;
+	if (cutAt(plain, low, note).length > budget) return void 0;
+	while (high - low > 1) {
+		const cap = Math.floor((low + high) / 2);
+		if (cutAt(plain, cap, note).length <= budget) low = cap;
+		else high = cap;
+	}
+	return cutAt(plain, low, note);
+};
+/** `result` as JSON within `budget` if it can be, its strings trimmed down to nothing when they must; never undefined. */
+const forcedJson = (result, note, budget = resultBudget) => budgetedJson(result, note, budget) ?? budgetedJson(result, note, budget, 0) ?? cutAt(JSON.parse(JSON.stringify(result)), 0, note);
+/** The most leading items of `count`, at least 1, for which `fits` holds, `fits` holding for fewer when it does for more. */
+const leadingFit = (count, fits) => {
+	let low = 1;
+	let high = count;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (fits(middle)) low = middle;
+		else high = middle - 1;
+	}
+	return low;
+};
+//#endregion
+export { budgetedJson, forcedJson, leadingFit, resultBudget };

package/dist/assistant/tools.d.ts

@@ -1,5 +1,6 @@
 import { Session } from "../types.js";
 import { ToolRecords } from "./records.js";
+import { ToolComments } from "../comments/tool-comment-types.js";
 import { Conversation } from "./conversations.js";
 import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
 import { Locale } from "@protobase/schema/internal";
@@ -24,6 +25,8 @@ export type ToolContext = {
   records: ToolRecords;
   /** The resources the caller may read, each restricted to their fields, with their views. */
   resources: () => Promise<ReadableResources>;
+  /** Records' comments as the session's user, which the MCP endpoint gives its tools; absent elsewhere. */
+  comments?: ToolComments;
 };
 /** MCP's tool hints, which an MCP client may show or act on; the dock ignores them. */
 export type ToolAnnotations = {

package/dist/assistant/write-echo.js

@@ -0,0 +1,41 @@
+//#region src/assistant/write-echo.ts
+const fieldsParameter = {
+	type: "array",
+	items: { type: "string" },
+	description: "More fields of the written record to return than its key, etag, the fields written and the read-only fields that changed; [\"*\"] returns all of them."
+};
+/** `fields` as a list of field names, absent being none; undefined for any other value. */
+const echoFieldsOf = (value) => {
+	if (value === void 0) return [];
+	if (Array.isArray(value) && value.every((name) => typeof name === "string" && name !== "")) return value;
+};
+const invalidFields = JSON.stringify({
+	error: "invalid-parameter",
+	message: "Invalid parameter fields: pass a list of field names, or [\"*\"] for all"
+});
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const readOnlyChanged = (model, record, before) => Object.values(model?.fields ?? {}).filter((field) => field.readOnly && (before ? !same(before[field.name], record[field.name]) : record[field.name] !== null)).map((field) => field.name);
+const keyOf = (model, record) => {
+	const parts = model.primaryKey.map((name) => record[name]);
+	return parts.length === 1 ? parts[0] : parts;
+};
+const pick = (record, names) => Object.fromEntries(names.filter((name) => Object.hasOwn(record, name)).map((name) => [name, record[name]]));
+/**
+* The written record, small: `before` is the record as the caller read it before the write, undefined for a create or
+* one they could not read. Without the resource's model, the key and the read-only fields are unknown and left out.
+*/
+const writeEcho = (model, written, data, before, fields) => {
+	const { record, etag } = written;
+	const echoed = fields.includes("*") ? record : pick(record, [
+		...Object.keys(data),
+		...readOnlyChanged(model, record, before),
+		...fields
+	]);
+	return {
+		...model && { key: keyOf(model, record) },
+		etag,
+		record: echoed
+	};
+};
+//#endregion
+export { echoFieldsOf, fieldsParameter, invalidFields, writeEcho };

package/dist/assistant/write-messages.js

@@ -3,9 +3,19 @@ import { defineMessages } from "../locale/messages.js";
 /** The texts of the approvals the write tools ask for, which the user reads in their client. */
 const writeText = defineMessages({
 	en: {
-		createTitle: (resource, title) => `Create ${resource}${title === void 0 ? "" : ` "${title}"`}?`,
-		updateTitle: (record) => `Update ${record}?`,
-		deleteTitle: (record) => `Delete ${record}?`,
+		createAction: (resource, title) => `Create ${resource}${title === void 0 ? "" : ` "${title}"`}`,
+		updateAction: (record) => `Update ${record}`,
+		deleteAction: (record) => `Delete ${record}`,
+		asked: (action) => `${action}?`,
+		batchTitle: (count) => `Run ${count} ${count === 1 ? "write" : "writes"} in one transaction?`,
+		allOrNone: "Either all of them are written or none.",
+		permanentDeletes: (count) => `${count} ${count === 1 ? "delete cannot" : "deletes cannot"} be undone: those records are removed for good.`,
+		moreWrites: (count) => `And ${count} more ${count === 1 ? "write" : "writes"}, not listed.`,
+		fromWrite: (resource, write) => `the ${resource} from write ${write}`,
+		writeAll: "Write all",
+		noFields: "No fields.",
+		commentTitle: (record) => `Comment on ${record}?`,
+		comment: "Comment",
 		create: "Create",
 		update: "Update",
 		delete: "Delete",
@@ -20,9 +30,19 @@ const writeText = defineMessages({
 		no: "No"
 	},
 	nl: {
-		createTitle: (resource, title) => `${resource}${title === void 0 ? "" : ` "${title}"`} aanmaken?`,
-		updateTitle: (record) => `${record} bijwerken?`,
-		deleteTitle: (record) => `${record} verwijderen?`,
+		createAction: (resource, title) => `${resource}${title === void 0 ? "" : ` "${title}"`} aanmaken`,
+		updateAction: (record) => `${record} bijwerken`,
+		deleteAction: (record) => `${record} verwijderen`,
+		asked: (action) => `${action}?`,
+		batchTitle: (count) => `${count} ${count === 1 ? "schrijfactie" : "schrijfacties"} in één transactie uitvoeren?`,
+		allOrNone: "Ze worden allemaal opgeslagen of geen enkele.",
+		permanentDeletes: (count) => `${count} ${count === 1 ? "verwijdering kan" : "verwijderingen kunnen"} niet ongedaan worden gemaakt: die records worden definitief verwijderd.`,
+		moreWrites: (count) => `En nog ${count} ${count === 1 ? "schrijfactie" : "schrijfacties"}, niet vermeld.`,
+		fromWrite: (resource, write) => `de ${resource} uit schrijfactie ${write}`,
+		writeAll: "Alles opslaan",
+		noFields: "Geen velden.",
+		commentTitle: (record) => `Reageren op ${record}?`,
+		comment: "Reageren",
 		create: "Aanmaken",
 		update: "Bijwerken",
 		delete: "Verwijderen",

package/dist/assistant/write-prompts.js

@@ -13,6 +13,7 @@ const shown = (text) => {
 	const line = text.replace(hiddenCharacters, " ");
 	return line.length > longest ? `${line.slice(0, 199)}…` : line;
 };
+/** The resource's singular label, as a record page names it. */
 const resourceLabel = ({ name, view }) => shown(view?.names?.singular ?? humanize(name));
 const fieldLabel = ({ view }, name) => shown(view?.fields[name]?.label ?? humanize(name));
 const shownValue = (text, described, name, value) => {
@@ -37,21 +38,19 @@ const titleOfNew = (described, data) => {
 	return title === "" ? void 0 : title;
 };
 const same = (before, after) => JSON.stringify(before ?? null) === JSON.stringify(after ?? null);
-/** `Create Task "Fix the sign-in lockout"?`, with each field the new record is given by its label. */
-const createApproval = (text, described, data) => ({
-	title: text.createTitle(resourceLabel(described), titleOfNew(described, data)),
+/** A create as one change: `Create Task "Fix the sign-in lockout"`, and each field the new record is given by its label. */
+const createChange = (text, described, data) => ({
+	action: text.createAction(resourceLabel(described), titleOfNew(described, data)),
 	fields: Object.entries(data).map(([name, value]) => ({
 		label: fieldLabel(described, name),
 		value: shownValue(text, described, name, value)
-	})),
-	approveLabel: text.create,
-	rejectLabel: text.reject
+	}))
 });
 /**
-* `Update Task #42 "Fix the sign-in lockout"?`, with each field that changes as `In flight -> Done`. A field the
-* caller cannot read before, such as a sensitive one, shows its new value alone.
+* An update of the record named `record` as one change: `Update Task #42 "Fix the sign-in lockout"`, and each field that
+* changes as `In flight -> Done`. A field the caller cannot read before, such as a sensitive one, shows its new value alone.
 */
-const updateApproval = (text, described, key, current, data) => {
+const updateChange = (text, described, record, current, data) => {
 	const fields = Object.entries(data).filter(([name, value]) => !Object.hasOwn(current, name) || !same(current[name], value)).map(([name, value]) => {
 		const after = shownValue(text, described, name, value);
 		const before = Object.hasOwn(current, name) ? `${shownValue(text, described, name, current[name])} -> ` : "";
@@ -61,7 +60,25 @@ const updateApproval = (text, described, key, current, data) => {
 		};
 	});
 	return {
-		title: text.updateTitle(recordName(described, key, current)),
+		action: text.updateAction(record),
+		fields
+	};
+};
+/** `Create Task "Fix the sign-in lockout"?`, with each field the new record is given by its label. */
+const createApproval = (text, described, data) => {
+	const { action, fields } = createChange(text, described, data);
+	return {
+		title: text.asked(action),
+		fields,
+		approveLabel: text.create,
+		rejectLabel: text.reject
+	};
+};
+/** `Update Task #42 "Fix the sign-in lockout"?`, with each field that changes, or saying none does. */
+const updateApproval = (text, described, key, current, data) => {
+	const { action, fields } = updateChange(text, described, recordName(described, key, current), current, data);
+	return {
+		title: text.asked(action),
 		...fields.length > 0 ? { fields } : { body: text.noChanges },
 		approveLabel: text.update,
 		rejectLabel: text.reject
@@ -69,11 +86,19 @@ const updateApproval = (text, described, key, current, data) => {
 };
 /** `Delete Task #42 "Fix the sign-in lockout"?`, saying whether it can be restored (a soft delete) or is gone for good. */
 const deleteApproval = (text, described, key, current, restorable) => ({
-	title: text.deleteTitle(recordName(described, key, current)),
+	title: text.asked(text.deleteAction(recordName(described, key, current))),
 	body: restorable ? text.restorable : text.permanent,
 	tone: restorable ? "warning" : "danger",
 	approveLabel: restorable ? text.delete : text.deleteForGood,
 	rejectLabel: text.reject
 });
+const hiddenInComment = /[\p{Cf}\p{Zl}\p{Zp}]|[^\P{Cc}\n]/gu;
+/** `Comment on Task #42 "Fix the sign-in lockout"?`, with the whole comment, as it will be posted. */
+const commentApproval = (text, described, key, current, comment) => ({
+	title: text.commentTitle(recordName(described, key, current)),
+	body: comment.trim().replace(hiddenInComment, " "),
+	approveLabel: text.comment,
+	rejectLabel: text.reject
+});
 //#endregion
-export { createApproval, deleteApproval, describedResource, updateApproval };
+export { commentApproval, createApproval, createChange, deleteApproval, describedResource, recordName, resourceLabel, shown, updateApproval, updateChange };