@protobase/server 0.53.0 → 0.53.2

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

@@ -1,7 +1,5 @@
 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";
@@ -127,7 +125,7 @@ const batchWriteTool = (input = {}) => defineTool({
 		const answer = await context.approve(approval);
 		if (answer !== "approved") return `The user did not approve this batch (${answer}); nothing was written.`;
 		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);
+		return context.records.batch(operations).then(async (results) => JSON.stringify({ results: await batchEcho(context, operations, results, befores, fields) }), refused);
 	}
 });
 //#endregion

package/dist/assistant/list-fields.js

@@ -0,0 +1,9 @@
+import { listColumnNames } from "@protobase/schema/internal";
+//#region src/assistant/list-fields.ts
+/**
+* The fields `list_records` returns when it is not told which: the key, then the columns of the resource's table as
+* the caller's view lists them, leaving out the related columns, which are not fields.
+*/
+const listFields = (model, view) => [.../* @__PURE__ */ new Set([...model.primaryKey, ...listColumnNames(model, view)])].filter((name) => Object.hasOwn(model.fields, name) && !model.fields[name].writeOnly);
+//#endregion
+export { listFields };

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, more) => {
+const shown = (result, statement, context) => {
 	context.show({
 		type: "table",
 		id: crypto.randomUUID(),
@@ -20,9 +20,9 @@ const shown = (result, statement, context, more) => {
 		caption: statement,
 		...result.truncated && { truncated: true }
 	});
-	return budgetedQueryResult(result, more);
+	const json = JSON.stringify(result);
+	return json.length > maxResultLength ? `${json.slice(0, maxResultLength)}... (cut off)` : json;
 };
-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 }); 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.`,
+	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.`,
 	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, readOn), refused);
+		return runReadOnlyQuery(db, statement, options).then((result) => shown(result, statement, context), 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-fields.js

@@ -0,0 +1,13 @@
+import { pickFields } from "../rows.js";
+import { selectedFields } from "../params.js";
+//#region src/assistant/record-fields.ts
+/** `record` with only `fields`, each one of those it holds, which are those the caller may read; all of it without. */
+const recordFields = (model, record, fields) => {
+	const readable = Object.fromEntries(Object.keys(record).map((name) => [name, model.fields[name]]));
+	return pickFields(record, selectedFields({
+		...model,
+		fields: readable
+	}, fields));
+};
+//#endregion
+export { recordFields };

package/dist/assistant/record-tools.js

@@ -1,9 +1,7 @@
 import { notFound } from "../problem.js";
-import { forcedJson } from "./result-budget.js";
 import { defineTool } from "./tools.js";
+import { listFields } from "./list-fields.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 = {
@@ -39,6 +37,7 @@ const resourceSummary = (model, view) => ({
 const resourceDetail = (model, view) => ({
 	...resourceSummary(model, view),
 	...view?.help && { help: view.help },
+	list_fields: listFields(model, view),
 	fields: Object.values(model.fields).map((field) => fieldEntry(field, view))
 });
 const viewOf = ({ views }, model) => views.find((view) => view.resource === model.name);
@@ -59,7 +58,7 @@ const listResourcesTool = () => defineTool({
 /** Describes one resource the caller may read, with its fields, their labels, help and values, and which fields filters and sorts take. */
 const describeResourceTool = () => defineTool({
 	name: "describe_resource",
-	description: "Describes one resource you may read, as JSON: its name, label, help, key fields, whether it soft deletes (soft_delete) and fields (name, type, label, help, enum values, the resource a relation links to, and whether it is optional, read-only, filterable and sortable). Filters and order_by in list_records take only fields marked filterable or sortable.",
+	description: "Describes one resource you may read, as JSON: its name, label, help, key fields, whether it soft deletes (soft_delete) and fields (name, type, label, help, enum values, the resource a relation links to, and whether it is optional, read-only, filterable and sortable), and list_fields, the fields list_records returns when not told which. Filters and order_by in list_records take only fields marked filterable or sortable.",
 	parameters: {
 		type: "object",
 		properties: { resource: resourceParameter },
@@ -75,14 +74,42 @@ const describeResourceTool = () => defineTool({
 		return JSON.stringify(resourceDetail(model, viewOf(resources, model)));
 	}
 });
+const fieldsParameter = (what) => ({
+	type: "array",
+	items: { type: "string" },
+	minItems: 1,
+	description: `The fields to return, such as ["id", "status"], or ["*"] for every field; ${what}.`
+});
+/** The fields named, `*` when they ask for every field, or `undefined` when none are. */
+const fieldsOf = (value) => {
+	if (!Array.isArray(value) || value.length === 0 || !value.every((name) => typeof name === "string")) return void 0;
+	return value.includes("*") ? "*" : value;
+};
+/** Without `fields`, the resource's list fields, the page naming the others in `omitted_fields`; `*` asks for all. */
+const listedFields = async (resource, value, context) => {
+	const named = fieldsOf(value);
+	if (named === "*") return {};
+	if (named) return { fields: named };
+	const readable = await context.resources();
+	const model = readable.models.find((each) => each.name === resource);
+	if (!model) return {};
+	const fields = listFields(model, viewOf(readable, model));
+	const omitted = Object.keys(model.fields).filter((name) => !fields.includes(name));
+	if (omitted.length === 0) return {};
+	return {
+		fields,
+		omitted
+	};
+};
 /** 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. 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.`,
+	description: `Finds records of a resource and returns a page of them as JSON ({ items, next_page_token, total_size_estimate }). Name the fields you need in fields, such as ["id", "status"]; without it each record has its resource's list_fields, the columns of its table in the app, and the page names the others in omitted_fields: pass ["*"] for every field. filter uses AIP-160 syntax on filterable fields, such as status = "open" AND amount > 10, and order_by a comma-separated list of sortable fields, each optionally followed by desc. total_size_estimate is an estimate, not an exact count. Keep page_size small and 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.`,
 	parameters: {
 		type: "object",
 		properties: {
 			resource: resourceParameter,
+			fields: fieldsParameter("without it, the list_fields describe_resource names"),
 			filter: {
 				type: "string",
 				description: "An AIP-160 filter on filterable fields, such as status = \"open\" AND amount > 10."
@@ -111,28 +138,32 @@ const listRecordsTool = () => defineTool({
 		if (!resource) return "Pass the resource as { \"resource\": \"<name>\" }.";
 		const showDeleted = showDeletedOf(args);
 		if (showDeleted === void 0) return invalidShowDeleted;
+		const { fields, omitted } = await listedFields(resource, args.fields, context);
 		const params = {
 			...typeof args.filter === "string" && { filter: args.filter },
 			...typeof args.order_by === "string" && { order_by: args.order_by },
 			...typeof args.page_token === "string" && { page_token: args.page_token },
+			...fields && { fields },
 			page_size: typeof args.page_size === "number" ? Math.min(args.page_size, maxPageSize) : defaultPageSize,
 			...showDeleted && { show_deleted: true }
 		};
-		const list = (paged) => context.records.list(resource, paged);
-		return list(params).then((page) => budgetedPage(page, params, list)).catch(refused);
+		return context.records.list(resource, params).then((page) => JSON.stringify({
+			...page,
+			...omitted && { omitted_fields: omitted }
+		}), 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 }), 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.",
+	description: "Reads one record of a resource by its key and returns it as JSON ({ record, etag }). Name the fields you need in fields, such as [\"id\", \"status\"]; without it, or with [\"*\"], the record has every field, long texts included. show_deleted: true also finds a soft-deleted record.",
 	parameters: {
 		type: "object",
 		properties: {
 			resource: resourceParameter,
 			key: keyParameter,
-			show_deleted: showDeletedParameter,
-			...pieceParameters
+			fields: fieldsParameter("without it, every field"),
+			show_deleted: showDeletedParameter
 		},
 		required: ["resource", "key"]
 	},
@@ -143,8 +174,11 @@ 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;
-		const shown = (found) => readsPiece(args) ? fieldPiece(found, args) : forcedJson(found, cutRecordNote);
-		return context.records.get(resource, key, { show_deleted: showDeleted }).then(shown, refused);
+		const fields = fieldsOf(args.fields);
+		return context.records.get(resource, key, {
+			show_deleted: showDeleted,
+			...Array.isArray(fields) && { fields }
+		}).then((record) => JSON.stringify(record), refused);
 	}
 });
 /**

package/dist/assistant/records.d.ts

@@ -61,9 +61,13 @@ 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. */
+  /**
+   * With `show_deleted`, also finds a soft-deleted record, as the REST API's `show_deleted` does. With `fields`, the
+   * record holds those fields only, each checked against the fields the caller may read.
+   */
   get: (resource: string, key: RecordKeyInput, options?: {
     show_deleted?: boolean;
+    fields?: string[];
   }) => Promise<ToolRecord>;
   create: (resource: string, data: Row) => Promise<ToolRecord>;
   /** With `etag`, fails with 412 when the record changed since it was read; without, it updates any version. */

package/dist/assistant/records.js

@@ -5,6 +5,7 @@ import { decodeKeyText } from "../key.js";
 import { runBatch } from "../batch/run-batch.js";
 import { listRecords } from "../list-service.js";
 import { readRecord } from "../read-service.js";
+import { recordFields } from "./record-fields.js";
 import { encodeKey } from "@protobase/schema/internal";
 //#region src/assistant/records.ts
 const filterLength = 2e5;
@@ -29,11 +30,11 @@ const assistantRecords = (deps, session) => {
 	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 } = {}) => {
+		get: async (resource, input, { show_deleted, fields } = {}) => {
 			const { entry, key } = keyOf(resource, input);
 			const { record, etag } = await readRecord(deps, entry, session, key, show_deleted);
 			return {
-				record,
+				record: recordFields(entry.model, record, fields),
 				etag
 			};
 		},

package/dist/assistant/write-record-tools.js

@@ -1,7 +1,5 @@
-import { forcedJson } from "./result-budget.js";
 import { defineTool } from "./tools.js";
 import { keyOf, keyParameter, refused, resourceOf } from "./record-tool-args.js";
-import { cutRecordNote } from "./budgeted-page.js";
 import { createApproval, updateApproval } from "./write-prompts.js";
 import { approvalTexts, recordBefore } from "./record-before.js";
 import { forbiddenText, notApproved, onlyNote, outside, resourceParameterFor } from "./write-tool-limits.js";
@@ -43,7 +41,7 @@ const createRecordTool = (input = {}) => defineTool({
 		const { text, described } = await approvalTexts(context, resource);
 		const answer = await context.approve(createApproval(text, described, data));
 		if (answer !== "approved") return notApproved(answer);
-		return context.records.create(resource, data).then((written) => forcedJson(writeEcho(described.model, written, data, void 0, fields), cutRecordNote), refused);
+		return context.records.create(resource, data).then((written) => JSON.stringify(writeEcho(described.model, written, data, void 0, fields)), refused);
 	}
 });
 /** Updates one record by its key once the user approves it, under the caller's access rules. */
@@ -90,7 +88,7 @@ const updateRecordTool = (input = {}) => defineTool({
 		const { text, described } = await approvalTexts(context, resource);
 		const answer = await context.approve(updateApproval(text, described, key, before?.record ?? {}, data));
 		if (answer !== "approved") return notApproved(answer);
-		return context.records.update(resource, key, data, { etag }).then((written) => forcedJson(writeEcho(described.model, written, data, before?.record, fields), cutRecordNote), refused);
+		return context.records.update(resource, key, data, { etag }).then((written) => JSON.stringify(writeEcho(described.model, written, data, before?.record, fields)), refused);
 	}
 });
 /** `create_record`, `update_record` and `delete_record`, on the resources `input` allows. */

package/dist/index.d.ts

@@ -130,6 +130,7 @@ import { CommentToolsInput, addCommentTool, commentTools, listCommentsTool } fro
 import { McpApprovals, mcpApprovals } from "./mcp/mcp-approval-store.js";
 import { McpServerInput, mcpServer } from "./mcp/mcp-server.js";
 import { mcpIcons } from "./web-app/mcp-icons.js";
+import { mcpInstructions } from "./mcp/mcp-instructions.js";
 import { McpToolsInput, mcpTools } from "./mcp/mcp-tools.js";
 import { McpGateInput, mcpGate, sessionOf } from "./mcp/mcp-gate.js";
 import { McpHandlerInput, mcpHandler } from "./mcp/mcp-handler.js";
@@ -170,4 +171,4 @@ import { MobileRelease, ReleaseFile, ServedReleaseFile, composeRelease, releaseM
 import { MobileReleaseAppInput, OfferedRelease, mobileReleaseApp } from "./mobile-release/release-app.js";
 import { mobileSigningKeyVariable, readSigningKey } from "./mobile-release/signing-key.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, normalizeRoles } from "./better-auth/create-auth.js";
-export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/index.js

@@ -44,6 +44,7 @@ import { mcpToolContext } from "./mcp/mcp-context.js";
 import { mcpGate, sessionOf } from "./mcp/mcp-gate.js";
 import { mcpHandler } from "./mcp/mcp-handler.js";
 import { mcpRoutes } from "./mcp/mcp-routes.js";
+import { mcpInstructions } from "./mcp/mcp-instructions.js";
 import { mcpServer } from "./mcp/mcp-server.js";
 import { countRecordsTool } from "./assistant/count-records-tool.js";
 import { describeResourceTool, getRecordTool, listRecordsTool, listResourcesTool, readRecordTools } from "./assistant/record-tools.js";
@@ -128,4 +129,4 @@ import { jobsDrainApp } from "./jobs/drain-route.js";
 import { composeRelease, releaseManifest } from "./mobile-release/release.js";
 import { mobileReleaseApp } from "./mobile-release/release-app.js";
 import { mobileSigningKeyVariable, readSigningKey } from "./mobile-release/signing-key.js";
-export { ConnectionsBusy, DeviceStoreError, FatalJobError, HistoryStoreError, HttpProblem, MissingCredentials, ModelError, NotificationSendError, PushMessageError, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { ConnectionsBusy, DeviceStoreError, FatalJobError, HistoryStoreError, HttpProblem, MissingCredentials, ModelError, NotificationSendError, PushMessageError, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, releaseManifest, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/mcp/mcp-instructions.d.ts

@@ -0,0 +1,4 @@
+//#region src/mcp/mcp-instructions.d.ts
+/** What `mcpServer` tells a client when it connects: how to read the app's records without pulling more than it needs. */
+export declare const mcpInstructions: string;
+//#endregion

package/dist/mcp/mcp-instructions.js

@@ -0,0 +1,10 @@
+//#region src/mcp/mcp-instructions.ts
+/** What `mcpServer` tells a client when it connects: how to read the app's records without pulling more than it needs. */
+const mcpInstructions = [
+	"Call list_resources first to find the resources, then describe_resource for one: it names the resource's fields, which ones filters and sorts take, and its list_fields.",
+	"Name the fields you need in fields, such as [\"id\", \"status\"], on list_records and get_record: a record can hold long texts. Without fields, list_records returns the list_fields, the columns of the resource's table in the app, and names the others in omitted_fields; [\"*\"] asks for every field. get_record returns every field unless told which.",
+	"Filter on fields marked filterable, the indexed ones, rather than reading pages to search them, and keep page_size small: follow next_page_token only when you need more. total_size_estimate is an estimate, not an exact count: count_records counts.",
+	"For example, the open tasks, newest first, ten at a time: list_records { \"resource\": \"tasks\", \"fields\": [\"id\", \"status\", \"title\"], \"filter\": \"status = \\\"open\\\"\", \"order_by\": \"created_at desc\", \"page_size\": 10 }, then get_record { \"resource\": \"tasks\", \"key\": \"42\", \"fields\": [\"brief\"] } for one long text."
+].join("\n");
+//#endregion
+export { mcpInstructions };

package/dist/mcp/mcp-server.d.ts

@@ -10,6 +10,8 @@ export type McpServerInput = {
     title?: string;
     icons?: Icon[];
   };
+  /** What the server tells clients about using it when they connect; `mcpInstructions`, on reading records, by default. */
+  instructions?: string;
   tools: AssistantTool[];
   /** What each tool gets as its context, for the caller of the request; `approve` comes from each call's own answers. */
   context: Omit<ToolContext, 'approve'>;
@@ -26,5 +28,5 @@ export type McpServerInput = {
  * counts only for the call it was asked for, once, while it lasts; for a user holding one of `rolesWithoutApproval` it
  * is approved at once, and the client is never asked.
  */
-export declare const mcpServer: ({ info, tools, context, report, rolesWithoutApproval, approvals }: McpServerInput) => McpServer;
+export declare const mcpServer: ({ info, instructions, tools, context, report, rolesWithoutApproval, approvals }: McpServerInput) => McpServer;
 //#endregion

package/dist/mcp/mcp-server.js

@@ -2,6 +2,7 @@ import { isStatementTimeout } from "../statement-timeout.js";
 import { checkedTools } from "../assistant/checked-tools.js";
 import { ApprovalNeeded, approvalAsked, approvedUnasked, mcpApproval, writesUnasked } from "./mcp-approval.js";
 import { callHash, callScope, scopeHash } from "./mcp-call-hash.js";
+import { mcpInstructions } from "./mcp-instructions.js";
 import { CLIENT_CAPABILITIES_META_KEY, McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-server.ts
 const capabilitiesOf = (envelope) => envelope?.[CLIENT_CAPABILITIES_META_KEY];
@@ -33,8 +34,8 @@ const stopped = (tool) => ({
 * counts only for the call it was asked for, once, while it lasts; for a user holding one of `rolesWithoutApproval` it
 * is approved at once, and the client is never asked.
 */
-const mcpServer = ({ info, tools, context, report, rolesWithoutApproval = [], approvals }) => {
-	const server = new McpServer(info);
+const mcpServer = ({ info, instructions = mcpInstructions, tools, context, report, rolesWithoutApproval = [], approvals }) => {
+	const server = new McpServer(info, { instructions });
 	const unasked = writesUnasked(rolesWithoutApproval, context.session.user.roles);
 	for (const tool of checkedTools(tools)) {
 		const config = {

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.53.0";
+var version = "0.53.2";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.53.0",
+  "version": "0.53.2",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,9 +40,9 @@
     "@better-auth/passkey": "^1.7.12",
     "@better-auth/sso": "^1.7.12",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@protobase/layout": "0.53.0",
-    "@protobase/query": "0.53.0",
-    "@protobase/schema": "0.53.0",
+    "@protobase/layout": "0.53.2",
+    "@protobase/query": "0.53.2",
+    "@protobase/schema": "0.53.2",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",

package/dist/assistant/budgeted-page.js

@@ -1,30 +0,0 @@
-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/query-result-budget.js

@@ -1,32 +0,0 @@
-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/record-field-piece.js

@@ -1,54 +0,0 @@
-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/result-budget.js

@@ -1,72 +0,0 @@
-//#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 };