@protobase/server 0.58.2 → 0.58.3

package/dist/assistant/batch-write-tool.d.ts

@@ -1,7 +1,7 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } from "./tools.js";
 import { WriteRecordToolsInput } from "./write-tool-limits.js";
 import "./write-record-tools.js";
 //#region src/assistant/batch-write-tool.d.ts
 /** Runs many writes in one transaction once the user approves them, under the caller's access rules. */
-export declare const batchWriteTool: (input?: WriteRecordToolsInput) => AssistantTool;
+export declare const batchWriteTool: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>;
 //#endregion

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

@@ -1,4 +1,4 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } 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. */
@@ -6,15 +6,15 @@ 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;
+export declare const listCommentsTool: (input: CommentToolsInput) => AssistantTool<ToolContext>;
 /**
  * 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;
+export declare const addCommentTool: (input: CommentToolsInput & WriteRecordToolsInput) => AssistantTool<ToolContext>;
 /**
  * `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[];
+export declare const commentTools: ({ commented }: CommentToolsInput, writes: false | WriteRecordToolsInput) => AssistantTool<ToolContext>[];
 //#endregion

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

@@ -1,5 +1,5 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } 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;
+export declare const countRecordsTool: () => AssistantTool<ToolContext>;
 //#endregion

package/dist/assistant/delete-record-tool.d.ts

@@ -1,6 +1,6 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } from "./tools.js";
 import { WriteRecordToolsInput } from "./write-tool-limits.js";
 //#region src/assistant/delete-record-tool.d.ts
 /** Deletes one record by its key and ETag once the user approves it, under the caller's access rules. */
-export declare const deleteRecordTool: (input?: WriteRecordToolsInput) => AssistantTool;
+export declare const deleteRecordTool: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>;
 //#endregion

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

@@ -1,4 +1,4 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } from "./tools.js";
 import { QueryOptions } from "./run-query.js";
 import { Db } from "@protobase/query";
 //#region src/assistant/query-tools.d.ts
@@ -7,10 +7,10 @@ import { Db } from "@protobase/query";
  * The rows show as a table in the chat. It runs as the query role, outside Protobase's access rules: it reads the
  * resources' tables only, never the auth schema.
  */
-export declare const readOnlyQueryTool: (db: Db, options?: QueryOptions) => AssistantTool;
+export declare const readOnlyQueryTool: (db: Db, options?: QueryOptions) => AssistantTool<ToolContext>;
 /**
  * Lets the model change the app's database, never on its own: each call shows the statement on an approval card, and
  * only the user's Approve runs it, in a read-write transaction (see `runReadWriteQuery`). Reject, or no answer, runs nothing.
  */
-export declare const readWriteQueryTool: (db: Db, options?: QueryOptions) => AssistantTool;
+export declare const readWriteQueryTool: (db: Db, options?: QueryOptions) => AssistantTool<ToolContext>;
 //#endregion

package/dist/assistant/record-tool-args.d.ts

@@ -0,0 +1,10 @@
+import "./records.js";
+//#region src/assistant/record-tool-args.d.ts
+/**
+ * A refusal the model can act on (no such resource, not allowed, a bad filter, a record a database constraint rejects)
+ * as `{ error, message }` JSON, as the REST API's problem words it; undefined for anything else.
+ */
+export declare const refusalOf: (error: unknown) => string | undefined;
+/** A refusal the model can act on is its to read, as `refusalOf` words it; anything else fails the call. */
+export declare const refused: (error: unknown) => string;
+//#endregion

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

@@ -2,15 +2,21 @@ import { problemOf } from "../error-handler.js";
 //#region src/assistant/record-tool-args.ts
 /**
 * A refusal the model can act on (no such resource, not allowed, a bad filter, a record a database constraint rejects)
-* is its to read, as the REST API's problem words it; anything else fails the call.
+* as `{ error, message }` JSON, as the REST API's problem words it; undefined for anything else.
 */
-const refused = (error) => {
+const refusalOf = (error) => {
 	const problem = problemOf(error);
-	if (problem && problem.status < 500) return JSON.stringify({
+	if (!problem || problem.status >= 500) return;
+	return JSON.stringify({
 		error: problem.slug,
 		message: problem.detail
 	});
-	throw error;
+};
+/** A refusal the model can act on is its to read, as `refusalOf` words it; anything else fails the call. */
+const refused = (error) => {
+	const refusal = refusalOf(error);
+	if (refusal === void 0) throw error;
+	return refusal;
 };
 /** `show_deleted` as JSON `true` or `false`, absent being `false`; undefined for any other value, such as `"true"` or `1`. */
 const showDeletedOf = (args) => {
@@ -47,4 +53,4 @@ const showDeletedParameter = {
 	description: "true also returns soft-deleted records; only on a resource list_resources marks soft_delete."
 };
 //#endregion
-export { invalidShowDeleted, keyOf, keyParameter, refused, resourceOf, resourceParameter, showDeletedOf, showDeletedParameter };
+export { invalidShowDeleted, keyOf, keyParameter, refusalOf, refused, resourceOf, resourceParameter, showDeletedOf, showDeletedParameter };

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

@@ -1,16 +1,16 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } from "./tools.js";
 //#region src/assistant/record-tools.d.ts
 /** Lists the resources the caller may read, small enough for a first call: names, labels and a line of help each, without fields. */
-export declare const listResourcesTool: () => AssistantTool;
+export declare const listResourcesTool: () => AssistantTool<ToolContext>;
 /** Describes one resource the caller may read, with its fields, their labels, help and values, and which fields filters and sorts take. */
-export declare const describeResourceTool: () => AssistantTool;
+export declare const describeResourceTool: () => AssistantTool<ToolContext>;
 /** Finds records of a resource with the REST API's filters, sorting and pages, under the caller's access rules. */
-export declare const listRecordsTool: () => AssistantTool;
+export declare const listRecordsTool: () => AssistantTool<ToolContext>;
 /** Reads one record by its key, under the caller's access rules. */
-export declare const getRecordTool: () => AssistantTool;
+export declare const getRecordTool: () => AssistantTool<ToolContext>;
 /**
  * `list_resources`, `describe_resource`, `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[];
+export declare const readRecordTools: () => AssistantTool<ToolContext>[];
 //#endregion

package/dist/assistant/record-tools.js

@@ -1,7 +1,7 @@
 import { notFound } from "../problem.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 { listFields } from "./list-fields.js";
 import { countRecordsTool } from "./count-records-tool.js";
 //#region src/assistant/record-tools.ts
 const readOnly = {

package/dist/assistant/tools.d.ts

@@ -36,17 +36,24 @@ export type ToolAnnotations = {
   idempotentHint?: boolean;
   openWorldHint?: boolean;
 };
+/** What every tool's context holds: a host's own MCP server, with no app records, gives its tools no more. */
+export type BaseToolContext = Pick<ToolContext, 'session' | 'locale' | 'approve'>;
 /**
  * A function the model may call during a turn. `parameters` is the JSON Schema of its arguments; `run` gets them
  * parsed, checked against the schema over MCP but not in the dock, and returns what the model reads as the result.
+ * `run` gets a `ToolContext` unless the tool names a smaller one, such as `BaseToolContext` for a host's MCP server.
  */
-export type AssistantTool = {
+export type AssistantTool<Context extends BaseToolContext = ToolContext> = {
   name: string;
   description: string;
   parameters: Record<string, unknown>;
-  run: (args: Record<string, unknown>, context: ToolContext) => Promise<string>;
+  run: (args: Record<string, unknown>, context: Context) => Promise<string>;
   annotations?: ToolAnnotations;
+  /** MCP's display name for the tool, which `tools/list` gives as is; the dock ignores it. */
+  title?: string;
+  /** MCP's `_meta` for the tool, such as `securitySchemes`, which `tools/list` gives as is; the dock ignores it. */
+  _meta?: Record<string, unknown>;
 };
 /** Typed identity, for a tool of your own. */
-export declare const defineTool: (tool: AssistantTool) => AssistantTool;
+export declare const defineTool: <Context extends BaseToolContext = ToolContext>(tool: AssistantTool<Context>) => AssistantTool<Context>;
 //#endregion

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

@@ -1,11 +1,11 @@
-import { AssistantTool } from "./tools.js";
+import { AssistantTool, ToolContext } from "./tools.js";
 import { WriteRecordToolsInput } from "./write-tool-limits.js";
 //#region src/assistant/write-record-tools.d.ts
 /** Creates a record of a resource once the user approves it, under the caller's access rules. */
-export declare const createRecordTool: (input?: WriteRecordToolsInput) => AssistantTool;
+export declare const createRecordTool: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>;
 /** Updates one record by its key once the user approves it, under the caller's access rules. */
-export declare const updateRecordTool: (input?: WriteRecordToolsInput) => AssistantTool;
+export declare const updateRecordTool: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>;
 /** `create_record`, `update_record` and `delete_record`, on the resources `input` allows. */
-export declare const writeRecordTools: (input?: WriteRecordToolsInput) => AssistantTool[];
+export declare const writeRecordTools: (input?: WriteRecordToolsInput) => AssistantTool<ToolContext>[];
 //#endregion
 export type { WriteRecordToolsInput };

package/dist/index.d.ts

@@ -48,7 +48,7 @@ import { ToolComment, ToolCommentPage, ToolComments } from "./comments/tool-comm
 import { ConversationRecord, ConversationStore } from "./assistant/conversation-store.js";
 import { Conversation, ConversationsOptions, conversationKey, createConversations } from "./assistant/conversations.js";
 import { ApprovalAnswer, ApprovalRequest, requestApproval } from "./assistant/approval.js";
-import { AssistantTool, ReadableResources, ToolAnnotations, ToolContext, defineTool } from "./assistant/tools.js";
+import { AssistantTool, BaseToolContext, ReadableResources, ToolAnnotations, ToolContext, defineTool } from "./assistant/tools.js";
 import { AssistantOptions, AssistantSettings, assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
 import { McpWrites } from "./mcp/mcp-writes.js";
 import { RuntimeOptions, runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
@@ -118,6 +118,7 @@ import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-
 import { fileConversationStore } from "./assistant/file-conversation-store.js";
 import { withCacheBreakpoints } from "./assistant/cache-breakpoints.js";
 import { TurnOptions, runTurn } from "./assistant/turn.js";
+import { refusalOf, refused } from "./assistant/record-tool-args.js";
 import { readableResources } from "./assistant/readable-resources.js";
 import { WidgetOptions, maxWidgetPropsBytes, widget } from "./assistant/widget.js";
 import { QueryOptions, QueryResult, runReadOnlyQuery, runReadWriteQuery } from "./assistant/run-query.js";
@@ -170,4 +171,4 @@ import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/ru
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.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 DecryptField, 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 FieldDecrypter, type FieldReader, 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, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, 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 RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKey, type RecordKeyInput, type RecordPage, 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 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, 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, 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, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, 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 BaseToolContext, 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 DecryptField, 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 FieldDecrypter, type FieldReader, 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, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, 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 RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKey, type RecordKeyInput, type RecordPage, 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 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, 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, 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, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, refusalOf, refused, relayed, 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 { refusalOf, refused } from "./assistant/record-tool-args.js";
 import { mcpInstructions } from "./mcp/mcp-instructions.js";
 import { mcpServer } from "./mcp/mcp-server.js";
 import { countRecordsTool } from "./assistant/count-records-tool.js";
@@ -126,4 +127,4 @@ import { enqueueJob } from "./jobs/declared-job.js";
 import { defineEmail } from "./mail/define-email.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.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, 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, 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, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, relayed, 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, 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, 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, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, refusalOf, refused, relayed, 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-server.d.ts

@@ -1,8 +1,8 @@
-import { AssistantTool, ToolContext } from "../assistant/tools.js";
+import { AssistantTool, BaseToolContext, ToolContext } from "../assistant/tools.js";
 import { McpApprovals } from "./mcp-approval-store.js";
 import { Icon, McpServer } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-server.d.ts
-export type McpServerInput = {
+export type McpServerInput<Context extends BaseToolContext = ToolContext> = {
   /** The name, version, title and icons the server tells clients when they connect, each icon an absolute URL. */
   info: {
     name: string;
@@ -12,10 +12,13 @@ export type McpServerInput = {
   };
   /** 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'>;
-  /** Gets the errors a tool throws, which the client only sees as a failure. */
+  tools: AssistantTool<Context>[];
+  /**
+   * What each tool gets as its context, for the caller of the request; `approve` comes from each call's own answers.
+   * A `ToolContext`, with the app's records, unless every tool takes a smaller one, such as `BaseToolContext`.
+   */
+  context: Omit<Context, 'approve'>;
+  /** Gets the errors a tool throws other than refusals, which the client only sees as a failure. */
   report: (error: unknown) => void;
   /** The roles whose calls are approved without asking the client: a user holding one of them is never asked. None by default. */
   rolesWithoutApproval?: readonly string[];
@@ -23,10 +26,12 @@ export type McpServerInput = {
   approvals: McpApprovals;
 };
 /**
- * An MCP server offering `tools` as MCP tools, each with its JSON Schema, its hints, and the text it returns. A tool
+ * An MCP server offering `tools` as MCP tools, each with its JSON Schema, its hints, its `title` and `_meta`, and the
+ * text it returns. A tool that throws an `HttpProblem` below 500, or a query error the REST API would answer below 500,
+ * refuses the call with `{ error, message }`, unreported; anything else it throws is reported and fails the call. A tool
  * that asks for approval makes the call ask the client's user, and runs again from the start with their answer, which
  * 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, instructions, tools, context, report, rolesWithoutApproval, approvals }: McpServerInput) => McpServer;
+export declare const mcpServer: <Context extends BaseToolContext = ToolContext>({ info, instructions, tools, context, report, rolesWithoutApproval, approvals }: McpServerInput<Context>) => McpServer;
 //#endregion

package/dist/mcp/mcp-server.js

@@ -1,5 +1,6 @@
 import { isStatementTimeout } from "../statement-timeout.js";
 import { checkedTools } from "../assistant/checked-tools.js";
+import { refusalOf } from "../assistant/record-tool-args.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";
@@ -21,6 +22,13 @@ const failed = {
 	}],
 	isError: true
 };
+const refusal = (text) => ({
+	content: [{
+		type: "text",
+		text
+	}],
+	isError: true
+});
 const stopped = (tool) => ({
 	content: [{
 		type: "text",
@@ -29,7 +37,9 @@ const stopped = (tool) => ({
 	isError: true
 });
 /**
-* An MCP server offering `tools` as MCP tools, each with its JSON Schema, its hints, and the text it returns. A tool
+* An MCP server offering `tools` as MCP tools, each with its JSON Schema, its hints, its `title` and `_meta`, and the
+* text it returns. A tool that throws an `HttpProblem` below 500, or a query error the REST API would answer below 500,
+* refuses the call with `{ error, message }`, unreported; anything else it throws is reported and fails the call. A tool
 * that asks for approval makes the call ask the client's user, and runs again from the start with their answer, which
 * 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.
@@ -41,7 +51,9 @@ const mcpServer = ({ info, instructions = mcpInstructions, tools, context, repor
 		const config = {
 			description: tool.description,
 			inputSchema: inputSchemaOf(tool.parameters),
-			...tool.annotations && { annotations: tool.annotations }
+			...tool.title !== void 0 && { title: tool.title },
+			...tool.annotations && { annotations: tool.annotations },
+			...tool._meta && { _meta: tool._meta }
 		};
 		const answer = async (args, ctx) => {
 			const bound = () => {
@@ -78,6 +90,8 @@ const mcpServer = ({ info, instructions = mcpInstructions, tools, context, repor
 			try {
 				return await answer(args, ctx);
 			} catch (error) {
+				const refusing = refusalOf(error);
+				if (refusing !== void 0) return refusal(refusing);
 				report(error);
 				return isStatementTimeout(error) ? stopped(tool.name) : failed;
 			}

package/dist/package.js

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

package/package.json

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