@protobase/server 0.1.5 → 0.2.0

package/dist/aggregate-service.js

@@ -5,8 +5,8 @@ import { readTransaction } from "./transactions.js";
 import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { parseParams } from "./params.js";
 import { facetCounts, histogram, series } from "@protobase/query";
-import { z } from "zod";
 import { sql } from "kysely";
+import { z } from "zod";
 //#region src/aggregate-service.ts
 const field = z.string().min(1);
 const filter = z.string().optional();

package/dist/assistant/app-context.js

@@ -0,0 +1,29 @@
+//#region src/assistant/app-context.ts
+const fieldLine = (field, view) => {
+	const label = view?.fields[field.name]?.label;
+	const traits = [
+		field.type === "enum" && field.enumValues ? `one of ${field.enumValues.join(", ")}` : field.type,
+		field.relation && `links to ${field.relation.resource}`,
+		field.nullable && "optional",
+		field.readOnly && "read-only"
+	].filter(Boolean);
+	return `  - ${field.name}${field.column === field.name ? "" : ` (column ${field.column})`}${label ? `, "${label}"` : ""}: ${traits.join(", ")}`;
+};
+const tableName = (model) => model.table.schema ? `${model.table.schema}.${model.table.name}` : model.table.name;
+const resourceBlock = (model, view) => {
+	const names = view?.names ? `, "${view.names.plural}"` : "";
+	const help = view?.help ? `\n  ${view.help}` : "";
+	return `- ${model.name} (table ${tableName(model)}${names})${help}\n${Object.values(model.fields).map((field) => fieldLine(field, view)).join("\n")}`;
+};
+/**
+* The built-in assistant's system prompt: what the app is, from what the caller may see of it in `/meta` (their
+* restricted models and views), and how to use the query tools.
+*/
+const appContext = (resources, views) => [
+	"You are the assistant inside an admin app built with Protobase, on a PostgreSQL database. You answer questions about the app and its data.",
+	"To look at the data, call run_read_only_query with one SELECT; the user sees its rows as a table, so do not repeat them all. To change data, and only when the user asks for a change, call propose_write_query: the user has to approve the statement before it runs. Never claim a change ran unless the tool returned its rows.",
+	"Answer briefly, in plain text.",
+	resources.length === 0 ? "The user can see no resources." : `The resources the user can see, with their tables and fields:\n${resources.map((model) => resourceBlock(model, views.find((view) => view.resource === model.name))).join("\n")}`
+].join("\n\n");
+//#endregion
+export { appContext };

package/dist/assistant/approval.d.ts

@@ -0,0 +1,26 @@
+import { Conversation } from "./conversations.js";
+import { AssistantTone } from "@protobase/schema";
+//#region src/assistant/approval.d.ts
+export type ApprovalRequest = {
+  title: string;
+  body?: string;
+  /** Monospace text, such as the statement that runs on approval. */
+  code?: string;
+  fields?: Array<{
+    label: string;
+    value: string;
+  }>;
+  tone?: AssistantTone;
+  badge?: string;
+  approveLabel?: string;
+  rejectLabel?: string;
+  /** Without an answer by then, the request is `expired`. Default 10 minutes. */
+  timeoutMs?: number;
+};
+export type ApprovalAnswer = 'approved' | 'rejected' | 'expired';
+/**
+ * Shows a card with Approve and Reject buttons in the assistant message `messageId` and resolves with the user's
+ * answer, or `expired` after the timeout. The card then loses its buttons and says what was answered.
+ */
+export declare const requestApproval: (conversation: Conversation, messageId: string, request: ApprovalRequest) => Promise<ApprovalAnswer>;
+//#endregion

package/dist/assistant/approval.js

@@ -0,0 +1,58 @@
+//#region src/assistant/approval.ts
+const notes = {
+	approved: "Approved.",
+	rejected: "Rejected. Nothing ran.",
+	expired: "Not answered in time. Nothing ran."
+};
+/**
+* Shows a card with Approve and Reject buttons in the assistant message `messageId` and resolves with the user's
+* answer, or `expired` after the timeout. The card then loses its buttons and says what was answered.
+*/
+const requestApproval = (conversation, messageId, request) => {
+	const card = {
+		type: "card",
+		id: crypto.randomUUID(),
+		title: request.title,
+		tone: request.tone ?? "warning",
+		...request.badge && { badge: request.badge },
+		...request.body && { body: request.body },
+		...request.code && { code: request.code },
+		...request.fields && { fields: request.fields }
+	};
+	conversation.apply({
+		type: "part",
+		messageId,
+		part: {
+			...card,
+			actions: [{
+				id: "approve",
+				label: request.approveLabel ?? "Approve",
+				style: "primary"
+			}, {
+				id: "reject",
+				label: request.rejectLabel ?? "Reject"
+			}]
+		}
+	});
+	return new Promise((resolve) => {
+		const answer = (value) => {
+			clearTimeout(timer);
+			stop();
+			conversation.apply({
+				type: "part",
+				messageId,
+				part: {
+					...card,
+					note: notes[value]
+				}
+			});
+			resolve(value);
+		};
+		const timer = setTimeout(() => answer("expired"), request.timeoutMs ?? 6e5);
+		const stop = conversation.onAction(card.id, (actionId) => {
+			if (actionId === "approve" || actionId === "reject") answer(actionId === "approve" ? "approved" : "rejected");
+		});
+	});
+};
+//#endregion
+export { requestApproval };

package/dist/assistant/assistant-settings.d.ts

@@ -0,0 +1,43 @@
+//#region src/assistant/assistant-settings.d.ts
+/** An OpenAI-compatible chat completions endpoint for the built-in assistant. */
+export type ModelSettings = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  fetch?: typeof fetch;
+};
+/**
+ * `url`: an assistant backend elsewhere, which the dock talks to instead of the built-in one.
+ * `apiKey`, `model`, `baseUrl`: the built-in assistant, which answers questions about the app with a chat model.
+ * Each falls back to its environment variable; `fetch` replaces the model endpoint, for tests.
+ */
+export type AssistantOptions = {
+  url?: string;
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+};
+export type AssistantSettings = {
+  kind: 'external';
+  url: string;
+} | {
+  kind: 'built-in';
+  model: ModelSettings;
+};
+export declare const assistantVariables: {
+  readonly url: "PROTOBASE_ASSISTANT_URL";
+  readonly apiKey: "PROTOBASE_ASSISTANT_API_KEY";
+  readonly model: "PROTOBASE_ASSISTANT_MODEL";
+  readonly baseUrl: "PROTOBASE_ASSISTANT_BASE_URL";
+};
+/** The roles that see the assistant: `/meta` names it, and the built-in one answers, only for a caller with one of them. */
+export declare const assistantRoles: readonly ["admin", "ai"];
+export declare const seesAssistant: (roles: readonly string[]) => boolean;
+/**
+ * Which assistant the app has: the backend at `url` when one is set, otherwise the built-in one when an API key is
+ * set, otherwise none (also when the option is `false`). The built-in one calls OpenRouter unless `baseUrl` names
+ * another OpenAI-compatible endpoint, which then needs a `model`. A value that cannot work stops the server at startup.
+ */
+export declare const assistantSettings: (option: AssistantOptions | false | undefined, env: Record<string, string | undefined>) => AssistantSettings | undefined;
+//#endregion

package/dist/assistant/assistant-settings.js

@@ -0,0 +1,51 @@
+//#region src/assistant/assistant-settings.ts
+const assistantVariables = {
+	url: "PROTOBASE_ASSISTANT_URL",
+	apiKey: "PROTOBASE_ASSISTANT_API_KEY",
+	model: "PROTOBASE_ASSISTANT_MODEL",
+	baseUrl: "PROTOBASE_ASSISTANT_BASE_URL"
+};
+const openRouterUrl = "https://openrouter.ai/api/v1";
+const openRouterModel = "openrouter/auto";
+/** The roles that see the assistant: `/meta` names it, and the built-in one answers, only for a caller with one of them. */
+const assistantRoles = ["admin", "ai"];
+const seesAssistant = (roles) => assistantRoles.some((role) => roles.includes(role));
+const checkedUrl = (url, source) => {
+	if (!URL.canParse(url)) throw new Error(`${source} is not a URL; use https://...`);
+	const { protocol } = new URL(url);
+	if (protocol !== "https:" && protocol !== "http:") throw new Error(`${source} must start with https:// or http://, not ${protocol}//`);
+	return url.replace(/\/+$/, "");
+};
+/**
+* Which assistant the app has: the backend at `url` when one is set, otherwise the built-in one when an API key is
+* set, otherwise none (also when the option is `false`). The built-in one calls OpenRouter unless `baseUrl` names
+* another OpenAI-compatible endpoint, which then needs a `model`. A value that cannot work stops the server at startup.
+*/
+const assistantSettings = (option, env) => {
+	if (option === false) return void 0;
+	const value = (key) => {
+		return (option?.[key] ?? env[assistantVariables[key]])?.trim() || void 0;
+	};
+	const source = (key) => option?.[key] === void 0 ? assistantVariables[key] : `options.assistant.${key}`;
+	const url = value("url");
+	if (url) return {
+		kind: "external",
+		url: checkedUrl(url, source("url"))
+	};
+	const apiKey = value("apiKey");
+	if (!apiKey) return void 0;
+	const baseUrl = checkedUrl(value("baseUrl") ?? "https://openrouter.ai/api/v1", source("baseUrl"));
+	const model = value("model") ?? (baseUrl === "https://openrouter.ai/api/v1" ? "openrouter/auto" : void 0);
+	if (!model) throw new Error(`${assistantVariables.model} (or options.assistant.model) is required with an endpoint other than OpenRouter's`);
+	return {
+		kind: "built-in",
+		model: {
+			baseUrl,
+			apiKey,
+			model,
+			...option && option.fetch && { fetch: option.fetch }
+		}
+	};
+};
+//#endregion
+export { assistantRoles, assistantSettings, assistantVariables, openRouterModel, openRouterUrl, seesAssistant };

package/dist/assistant/built-in-assistant.js

@@ -0,0 +1,35 @@
+import { seesAssistant } from "./assistant-settings.js";
+import { appContext } from "./app-context.js";
+import { conversationKey, createConversations } from "./conversations.js";
+import { assistantProtocolRoutes } from "./protocol-routes.js";
+import { readOnlyQueryTool, readWriteQueryTool } from "./query-tools.js";
+import { runTurn } from "./turn.js";
+//#region src/assistant/built-in-assistant.ts
+/**
+* Protobase's own assistant: answers questions about the app, reads its data with read-only queries and proposes
+* changes the user approves, for callers with the `admin` or `ai` role. Made only of the exported building blocks and
+* its prompt, which describes what the caller may see of the app.
+*/
+const builtInAssistant = ({ model, db, meta, authenticate, report }) => {
+	const conversations = createConversations();
+	const tools = [readOnlyQueryTool(db), readWriteQueryTool(db)];
+	return assistantProtocolRoutes({
+		authenticate,
+		allows: (session) => seesAssistant(session.user.roles),
+		conversationOf: (session) => conversations(conversationKey(session)),
+		report,
+		onMessage: async (text, session, conversation) => {
+			const { body } = await meta.forCaller(session);
+			await runTurn({
+				model,
+				conversation,
+				session,
+				system: appContext(body.resources, body.views),
+				tools,
+				report
+			}, text);
+		}
+	});
+};
+//#endregion
+export { builtInAssistant };

package/dist/assistant/chat-completions.d.ts

@@ -0,0 +1,50 @@
+import { ModelSettings } from "./assistant-settings.js";
+//#region src/assistant/chat-completions.d.ts
+export type ToolCall = {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+/** A message of a chat completion: what the model reads, and the tool calls it made with their results. */
+export type ChatMessage = {
+  role: 'system' | 'user';
+  content: string;
+} | {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: ToolCall[];
+} | {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+};
+/** A tool as the endpoint's `tools` field describes it: a function with JSON Schema parameters. */
+export type ToolSpec = {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+};
+export type Completion = {
+  content: string;
+  toolCalls: ToolCall[];
+};
+/** A failed call to the model endpoint, with a message an admin can act on. */
+export declare class ModelError extends Error {
+  name: string;
+}
+/**
+ * Streams a chat completion from an OpenAI-compatible endpoint (`POST <baseUrl>/chat/completions` with `stream: true`),
+ * offering `tools` and calling `onText` with each piece of the answer. Resolves with the whole answer and the tool
+ * calls the model made; rejects with a `ModelError`.
+ */
+export declare const streamChatCompletion: (settings: ModelSettings, messages: ChatMessage[], onText: (text: string) => void, options?: {
+  tools?: ToolSpec[];
+  signal?: AbortSignal;
+}) => Promise<Completion>;
+//#endregion

package/dist/assistant/chat-completions.js

@@ -0,0 +1,87 @@
+import { readEventStream } from "@protobase/schema";
+//#region src/assistant/chat-completions.ts
+/** A failed call to the model endpoint, with a message an admin can act on. */
+var ModelError = class extends Error {
+	name = "ModelError";
+};
+const errorText = async (response) => {
+	const text = await response.text();
+	if (!text) return void 0;
+	if (!response.headers.get("content-type")?.includes("json")) return text.slice(0, 300);
+	const body = JSON.parse(text);
+	const message = typeof body.error === "string" ? body.error : body.error?.message ?? body.message;
+	return typeof message === "string" ? message : void 0;
+};
+const statusHints = {
+	401: "check the API key",
+	402: "the account behind the API key is out of credit",
+	403: "the API key may not use this model",
+	404: "check the base URL and the model",
+	429: "the endpoint is rate limiting; try again shortly"
+};
+const refusal = async (response, settings) => {
+	const detail = await errorText(response);
+	const hint = statusHints[response.status];
+	return new ModelError(`The model endpoint ${settings.baseUrl} answered ${response.status}${detail ? `: ${detail}` : ""}${hint ? ` (${hint})` : ""}`);
+};
+const send = (settings, messages, tools, signal) => {
+	return (settings.fetch ?? fetch)(`${settings.baseUrl}/chat/completions`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			accept: "text/event-stream",
+			authorization: `Bearer ${settings.apiKey}`
+		},
+		body: JSON.stringify({
+			model: settings.model,
+			messages,
+			stream: true,
+			...tools.length > 0 && { tools }
+		}),
+		signal
+	}).catch((error) => {
+		if (error instanceof Error && error.name === "AbortError") throw error;
+		throw new ModelError(`Could not reach the model endpoint ${settings.baseUrl}`, { cause: error });
+	});
+};
+const addToolCall = (calls, delta) => {
+	const call = calls[delta.index] ??= {
+		id: "",
+		type: "function",
+		function: {
+			name: "",
+			arguments: ""
+		}
+	};
+	if (delta.id) call.id = delta.id;
+	if (delta.function?.name) call.function.name += delta.function.name;
+	if (delta.function?.arguments) call.function.arguments += delta.function.arguments;
+};
+/**
+* Streams a chat completion from an OpenAI-compatible endpoint (`POST <baseUrl>/chat/completions` with `stream: true`),
+* offering `tools` and calling `onText` with each piece of the answer. Resolves with the whole answer and the tool
+* calls the model made; rejects with a `ModelError`.
+*/
+const streamChatCompletion = async (settings, messages, onText, options = {}) => {
+	const response = await send(settings, messages, options.tools ?? [], options.signal);
+	if (!response.ok) throw await refusal(response, settings);
+	if (!response.body) throw new ModelError(`The model endpoint ${settings.baseUrl} answered without a body`);
+	let content = "";
+	const toolCalls = [];
+	await readEventStream(response.body, (data) => {
+		if (data === "[DONE]") return;
+		const chunk = JSON.parse(data);
+		if (chunk.error) throw new ModelError(`The model endpoint ${settings.baseUrl} stopped: ${chunk.error.message ?? "unknown error"}`);
+		const delta = chunk.choices?.[0]?.delta;
+		for (const call of delta?.tool_calls ?? []) addToolCall(toolCalls, call);
+		if (!delta?.content) return;
+		content += delta.content;
+		onText(delta.content);
+	});
+	return {
+		content,
+		toolCalls: toolCalls.filter(Boolean)
+	};
+};
+//#endregion
+export { ModelError, streamChatCompletion };

package/dist/assistant/conversations.d.ts

@@ -0,0 +1,24 @@
+import { Session } from "../types.js";
+import { ChatMessage } from "./chat-completions.js";
+import { AssistantEvent, AssistantState } from "@protobase/schema";
+//#region src/assistant/conversations.d.ts
+export type Conversation = {
+  state: () => AssistantState;
+  apply: (event: AssistantEvent) => void;
+  /** Calls `listener` with every later event until the returned function is called. */
+  subscribe: (listener: (event: AssistantEvent) => void) => () => void;
+  /** The chat as the model reads it, tool calls and their results included; turns add to it. */
+  transcript: ChatMessage[];
+  /** Calls `handler` with the action's id when a button of part `partId` is clicked, until the returned function is called. */
+  onAction: (partId: string, handler: (actionId: string) => void) => () => void;
+  /** Hands a click to the part's handler; false when no handler waits for that part. */
+  act: (partId: string, actionId: string) => boolean;
+};
+/** One conversation per user and tenant. */
+export declare const conversationKey: (session: Session) => string;
+/**
+ * Conversations in this process's memory, by key (see `conversationKey`): shared by a user's open tabs, gone on a
+ * restart, each cut to its last `keep` messages.
+ */
+export declare const createConversations: (keep?: number) => (key: string) => Conversation;
+//#endregion

package/dist/assistant/conversations.js

@@ -0,0 +1,50 @@
+import { applyAssistantEvent, emptyAssistantState } from "@protobase/schema";
+//#region src/assistant/conversations.ts
+const createConversation = (keep) => {
+	let state = emptyAssistantState;
+	const listeners = /* @__PURE__ */ new Set();
+	const actions = /* @__PURE__ */ new Map();
+	return {
+		state: () => state,
+		apply: (event) => {
+			const next = applyAssistantEvent(state, event);
+			state = next.messages.length > keep ? {
+				...next,
+				messages: next.messages.slice(-keep)
+			} : next;
+			for (const listener of listeners) listener(event);
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		transcript: [],
+		onAction: (partId, handler) => {
+			actions.set(partId, handler);
+			return () => actions.delete(partId);
+		},
+		act: (partId, actionId) => {
+			const handler = actions.get(partId);
+			handler?.(actionId);
+			return handler !== void 0;
+		}
+	};
+};
+/** One conversation per user and tenant. */
+const conversationKey = (session) => JSON.stringify([session.tenant ?? null, session.user.id]);
+/**
+* Conversations in this process's memory, by key (see `conversationKey`): shared by a user's open tabs, gone on a
+* restart, each cut to its last `keep` messages.
+*/
+const createConversations = (keep = 50) => {
+	const byKey = /* @__PURE__ */ new Map();
+	return (key) => {
+		const existing = byKey.get(key);
+		if (existing) return existing;
+		const conversation = createConversation(keep);
+		byKey.set(key, conversation);
+		return conversation;
+	};
+};
+//#endregion
+export { conversationKey, createConversations };

package/dist/assistant/protocol-routes.d.ts

@@ -0,0 +1,27 @@
+import { Authenticator, Session } from "../types.js";
+import { Conversation } from "./conversations.js";
+import { Hono } from "hono";
+//#region src/assistant/protocol-routes.d.ts
+export type AssistantBackend = {
+  /** Resolves the caller from the request's bearer token, or throws a 401 problem. */
+  authenticate: Authenticator;
+  /** Whether the caller may use the assistant; others get 403. */
+  allows: (session: Session) => boolean;
+  conversationOf: (session: Session) => Conversation;
+  /** Answers a message of the user with events on the conversation; called only while the backend is not replying. */
+  onMessage: (text: string, session: Session, conversation: Conversation) => Promise<void>;
+  /** Gets errors of `onMessage` and of requests that become a 500. */
+  report?: (error: unknown) => void;
+  /** The longest message accepted. Default 4000. */
+  maxMessageLength?: number;
+};
+/**
+ * The assistant protocol's requests as a Hono app: `GET /events` (the event stream, a `state` event first),
+ * `POST /messages` and `POST /actions`. Mount it where `/api/meta` says the backend is.
+ */
+export declare const assistantProtocolRoutes: (backend: AssistantBackend) => Hono<{
+  Variables: {
+    session: Session;
+  };
+}, import("hono/types").BlankSchema, "/">;
+//#endregion

package/dist/assistant/protocol-routes.js

@@ -0,0 +1,73 @@
+import { HttpProblem, badRequest, forbidden, notFound } from "../problem.js";
+import { createErrorHandler } from "../error-handler.js";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+//#region src/assistant/protocol-routes.ts
+const isObject = (body) => typeof body === "object" && body !== null;
+const textOf = (body, max) => {
+	const text = isObject(body) ? body.text : void 0;
+	if (typeof text !== "string" || !text.trim()) throw badRequest("invalid-message", "The body must be { \"text\": \"...\" }");
+	if (text.length > max) throw badRequest("invalid-message", `A message is at most ${max} characters`);
+	return text.trim();
+};
+const actionOf = (body) => {
+	const { partId, actionId } = isObject(body) ? body : {};
+	if (typeof partId !== "string" || typeof actionId !== "string") throw badRequest("invalid-action", "The body must be { \"partId\": \"...\", \"actionId\": \"...\" }");
+	return {
+		partId,
+		actionId
+	};
+};
+/**
+* The assistant protocol's requests as a Hono app: `GET /events` (the event stream, a `state` event first),
+* `POST /messages` and `POST /actions`. Mount it where `/api/meta` says the backend is.
+*/
+const assistantProtocolRoutes = (backend) => {
+	const app = new Hono();
+	app.onError(createErrorHandler(backend.report));
+	app.use("*", async (c, next) => {
+		const session = await backend.authenticate(c.req.raw);
+		if (!backend.allows(session)) throw forbidden("assistant-forbidden", "The assistant needs the admin or ai role");
+		c.set("session", session);
+		await next();
+	});
+	app.get("/events", (c) => {
+		const conversation = backend.conversationOf(c.get("session"));
+		return streamSSE(c, async (stream) => {
+			const queue = [{
+				type: "state",
+				state: conversation.state()
+			}];
+			let wake = () => {};
+			const unsubscribe = conversation.subscribe((event) => {
+				queue.push(event);
+				wake();
+			});
+			stream.onAbort(() => {
+				unsubscribe();
+				wake();
+			});
+			while (!stream.aborted) {
+				const event = queue.shift();
+				if (event) await stream.writeSSE({ data: JSON.stringify(event) });
+				else await new Promise((resolve) => wake = resolve);
+			}
+		});
+	});
+	app.post("/messages", async (c) => {
+		const session = c.get("session");
+		const text = textOf(await c.req.json(), backend.maxMessageLength ?? 4e3);
+		const conversation = backend.conversationOf(session);
+		if (conversation.state().replying) throw new HttpProblem(409, "assistant-replying", "Conflict", "The assistant is still answering");
+		backend.onMessage(text, session, conversation).catch((error) => backend.report?.(error));
+		return c.body(null, 202);
+	});
+	app.post("/actions", async (c) => {
+		const { partId, actionId } = actionOf(await c.req.json());
+		if (!backend.conversationOf(c.get("session")).act(partId, actionId)) throw notFound("No card waits for that action");
+		return c.body(null, 202);
+	});
+	return app;
+};
+//#endregion
+export { assistantProtocolRoutes };

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

@@ -0,0 +1,15 @@
+import { AssistantTool } from "./tools.js";
+import { QueryOptions } from "./run-query.js";
+import { Db } from "@protobase/query";
+//#region src/assistant/query-tools.d.ts
+/**
+ * Lets the model read the app's database: one SELECT per call, in a read-only transaction (see `runReadOnlyQuery`).
+ * The rows show as a table in the chat. It runs as the app's database role, outside Protobase's access rules.
+ */
+export declare const readOnlyQueryTool: (db: Db, options?: QueryOptions) => AssistantTool;
+/**
+ * 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;
+//#endregion

package/dist/assistant/query-tools.js

@@ -0,0 +1,76 @@
+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
+});
+const isDatabaseError = (error) => error instanceof Error && /^[0-9A-Z]{5}$/.test(String(error.code));
+const refused = (error) => {
+	if (isDatabaseError(error)) return `Postgres refused the statement: ${error.message}`;
+	throw error;
+};
+const shown = (result, statement, context) => {
+	context.show({
+		type: "table",
+		id: crypto.randomUUID(),
+		columns: result.columns,
+		rows: result.rows,
+		caption: statement,
+		...result.truncated && { truncated: true }
+	});
+	const json = JSON.stringify(result);
+	return json.length > maxResultLength ? `${json.slice(0, maxResultLength)}... (cut off)` : json;
+};
+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`).
+* The rows show as a table in the chat. It runs as the app's database role, outside Protobase's access rules.
+*/
+const readOnlyQueryTool = (db, options = {}) => defineTool({
+	name: "run_read_only_query",
+	description: `Runs one PostgreSQL SELECT on the app's database in a read-only transaction and returns up to ${options.rowLimit ?? 200} rows as JSON ({ columns, rows, truncated }). The user sees the rows as a table. Use it to answer questions about the data. It cannot change anything.`,
+	parameters: {
+		type: "object",
+		properties: { sql: sqlParameter("One SELECT statement, without a trailing semicolon.") },
+		required: ["sql"]
+	},
+	run: async (args, context) => {
+		const statement = statementOf(args);
+		if (!statement) return "Pass the statement as { \"sql\": \"select ...\" }.";
+		return runReadOnlyQuery(db, statement, options).then((result) => shown(result, statement, context), refused);
+	}
+});
+/**
+* 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.
+*/
+const readWriteQueryTool = (db, options = {}) => defineTool({
+	name: "propose_write_query",
+	description: "Proposes one PostgreSQL INSERT, UPDATE or DELETE ending in a RETURNING clause. The user sees the statement and your summary and must approve it; only then it runs in a read-write transaction, and you get the returned rows as JSON, or the answer that it did not run. Use it only when the user asked for a change.",
+	parameters: {
+		type: "object",
+		properties: {
+			sql: sqlParameter("One INSERT, UPDATE or DELETE with a RETURNING clause, without a trailing semicolon."),
+			summary: {
+				type: "string",
+				description: "What the statement changes, in one plain sentence for the user."
+			}
+		},
+		required: ["sql", "summary"]
+	},
+	run: async (args, context) => {
+		const statement = statementOf(args);
+		if (!statement) return "Pass the statement as { \"sql\": \"update ... returning ...\", \"summary\": \"...\" }.";
+		const answer = await context.approve({
+			title: "Run this change?",
+			body: typeof args.summary === "string" ? args.summary : void 0,
+			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);
+	}
+});
+//#endregion
+export { readOnlyQueryTool, readWriteQueryTool };

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

@@ -0,0 +1,24 @@
+import { Db } from "@protobase/query";
+//#region src/assistant/run-query.d.ts
+export type QueryOptions = {
+  /** Postgres cancels the statement after this long. Default 5000. */
+  timeoutMs?: number;
+  /** At most this many rows come back; `truncated` says there were more. Default 200. */
+  rowLimit?: number;
+};
+export type QueryResult = {
+  columns: string[];
+  rows: unknown[][];
+  truncated: boolean;
+};
+/**
+ * Runs one SELECT (or VALUES, or a WITH query) in a READ ONLY transaction that is always rolled back, so nothing it
+ * does, settings included, outlives it. Postgres refuses any write in it, and the statement cannot leave it.
+ */
+export declare const runReadOnlyQuery: (db: Db, statement: string, options?: QueryOptions) => Promise<QueryResult>;
+/**
+ * Runs one INSERT, UPDATE or DELETE with a RETURNING clause (or a query) in a READ WRITE transaction, committed when it
+ * succeeds. Only call it for a statement the user approved.
+ */
+export declare const runReadWriteQuery: (db: Db, statement: string, options?: QueryOptions) => Promise<QueryResult>;
+//#endregion

package/dist/assistant/run-query.js

@@ -0,0 +1,39 @@
+import { sql } from "kysely";
+//#region src/assistant/run-query.ts
+const wrapped = (statement, rowLimit) => sql`with result as (\n${sql.raw(statement.trim().replace(/;\s*$/, ""))}\n) select * from result limit ${rowLimit + 1}`;
+const cell = (value) => {
+	if (typeof value === "bigint") return value.toString();
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof Uint8Array) return `\\x${Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+	return value;
+};
+const resultOf = (rows, rowLimit) => ({
+	columns: Object.keys(rows[0] ?? {}),
+	rows: rows.slice(0, rowLimit).map((row) => Object.values(row).map(cell)),
+	truncated: rows.length > rowLimit
+});
+const run = (db, statement, options, begin, end) => db.connection().execute(async (connection) => {
+	const rowLimit = options.rowLimit ?? 200;
+	await sql.raw(begin).execute(connection);
+	let succeeded = false;
+	try {
+		await sql`select set_config('statement_timeout', ${String(options.timeoutMs ?? 5e3)}, true)`.execute(connection);
+		const { rows } = await wrapped(statement, rowLimit).execute(connection);
+		succeeded = true;
+		return resultOf(rows, rowLimit);
+	} finally {
+		await sql.raw(end(succeeded)).execute(connection);
+	}
+});
+/**
+* Runs one SELECT (or VALUES, or a WITH query) in a READ ONLY transaction that is always rolled back, so nothing it
+* does, settings included, outlives it. Postgres refuses any write in it, and the statement cannot leave it.
+*/
+const runReadOnlyQuery = (db, statement, options = {}) => run(db, statement, options, "begin transaction read only", () => "rollback");
+/**
+* Runs one INSERT, UPDATE or DELETE with a RETURNING clause (or a query) in a READ WRITE transaction, committed when it
+* succeeds. Only call it for a statement the user approved.
+*/
+const runReadWriteQuery = (db, statement, options = {}) => run(db, statement, options, "begin transaction read write", (succeeded) => succeeded ? "commit" : "rollback");
+//#endregion
+export { runReadOnlyQuery, runReadWriteQuery };

package/dist/assistant/tools.d.ts

@@ -0,0 +1,26 @@
+import { Session } from "../types.js";
+import { Conversation } from "./conversations.js";
+import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
+import { AssistantPart } from "@protobase/schema";
+//#region src/assistant/tools.d.ts
+export type ToolContext = {
+  session: Session;
+  conversation: Conversation;
+  /** Adds a part, such as a table of results, to the assistant message the turn is writing. */
+  show: (part: AssistantPart) => void;
+  /** Asks the user to approve with a card in that message (see `requestApproval`). */
+  approve: (request: ApprovalRequest) => Promise<ApprovalAnswer>;
+};
+/**
+ * A function the model may call during a turn. `parameters` is the JSON Schema of its arguments; `run` gets them
+ * parsed, but not checked against the schema, and returns what the model reads as the result.
+ */
+export type AssistantTool = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  run: (args: Record<string, unknown>, context: ToolContext) => Promise<string>;
+};
+/** Typed identity, for a tool of your own. */
+export declare const defineTool: (tool: AssistantTool) => AssistantTool;
+//#endregion

package/dist/assistant/tools.js

@@ -0,0 +1,5 @@
+//#region src/assistant/tools.ts
+/** Typed identity, for a tool of your own. */
+const defineTool = (tool) => tool;
+//#endregion
+export { defineTool };

package/dist/assistant/turn.d.ts

@@ -0,0 +1,26 @@
+import { ModelSettings } from "./assistant-settings.js";
+import { Session } from "../types.js";
+import { Conversation } from "./conversations.js";
+import { AssistantTool } from "./tools.js";
+//#region src/assistant/turn.d.ts
+export type TurnOptions = {
+  model: ModelSettings;
+  conversation: Conversation;
+  session: Session;
+  /** The system prompt. */
+  system: string;
+  tools?: AssistantTool[];
+  /** Model calls in one turn before it stops. Default 8. */
+  maxSteps?: number;
+  /** Gets errors other than the model endpoint's refusals, which the user only sees as a failure. */
+  report?: (error: unknown) => void;
+  /** Transcript messages kept for the next turns. Default 40. */
+  keep?: number;
+};
+/**
+ * One turn of the chat: adds the user's message, then calls the model with the transcript and the tools, runs the
+ * tools it calls and calls it again with their results, until it answers without a tool call. Its text streams into
+ * one assistant message, beside the parts tools show; a failure ends the turn with a danger card.
+ */
+export declare const runTurn: (options: TurnOptions, text: string) => Promise<void>;
+//#endregion

package/dist/assistant/turn.js

@@ -0,0 +1,117 @@
+import { requestApproval } from "./approval.js";
+import { ModelError, streamChatCompletion } from "./chat-completions.js";
+//#region src/assistant/turn.ts
+const toolResult = async (call, tools, context) => {
+	const tool = tools.find((entry) => entry.name === call.function.name);
+	if (!tool) return `There is no tool named "${call.function.name}".`;
+	const args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+	if (typeof args !== "object" || args === null || Array.isArray(args)) return "The arguments must be a JSON object.";
+	return tool.run(args, context);
+};
+const trimmed = (transcript, keep) => {
+	if (transcript.length <= keep) return transcript;
+	const start = transcript.findIndex((message, index) => index >= transcript.length - keep && message.role === "user");
+	return start === -1 ? transcript.slice(-1) : transcript.slice(start);
+};
+const failure = (error, report) => {
+	if (error instanceof ModelError) return error.message;
+	if (error instanceof SyntaxError) return "The model answered with JSON that could not be read.";
+	report?.(error);
+	return "The server failed to answer.";
+};
+/**
+* One turn of the chat: adds the user's message, then calls the model with the transcript and the tools, runs the
+* tools it calls and calls it again with their results, until it answers without a tool call. Its text streams into
+* one assistant message, beside the parts tools show; a failure ends the turn with a danger card.
+*/
+const runTurn = async (options, text) => {
+	const { model, conversation, session, system, tools = [], maxSteps = 8 } = options;
+	const messageId = crypto.randomUUID();
+	const show = (part) => conversation.apply({
+		type: "part",
+		messageId,
+		part
+	});
+	const context = {
+		session,
+		conversation,
+		show,
+		approve: (request) => requestApproval(conversation, messageId, request)
+	};
+	const specs = tools.map((tool) => ({
+		type: "function",
+		function: {
+			name: tool.name,
+			description: tool.description,
+			parameters: tool.parameters
+		}
+	}));
+	conversation.apply({
+		type: "message",
+		message: {
+			id: crypto.randomUUID(),
+			from: "user",
+			parts: [{
+				type: "text",
+				id: crypto.randomUUID(),
+				text
+			}]
+		}
+	});
+	conversation.apply({
+		type: "patch",
+		replying: true
+	});
+	conversation.transcript = trimmed([...conversation.transcript, {
+		role: "user",
+		content: text
+	}], options.keep ?? 40);
+	const before = conversation.transcript.length;
+	const steps = async () => {
+		for (let step = 0; step < maxSteps; step++) {
+			const part = {
+				type: "text",
+				id: `${messageId}-${step}`,
+				text: ""
+			};
+			const { content, toolCalls } = await streamChatCompletion(model, [{
+				role: "system",
+				content: system
+			}, ...conversation.transcript], (piece) => {
+				part.text += piece;
+				show({ ...part });
+			}, { tools: specs });
+			conversation.transcript.push({
+				role: "assistant",
+				content: content || null,
+				...toolCalls.length > 0 && { tool_calls: toolCalls }
+			});
+			if (toolCalls.length === 0) return;
+			for (const call of toolCalls) conversation.transcript.push({
+				role: "tool",
+				tool_call_id: call.id,
+				content: await toolResult(call, tools, context)
+			});
+		}
+		show({
+			type: "text",
+			id: `${messageId}-stopped`,
+			text: `Stopped after ${maxSteps} steps.`
+		});
+	};
+	await steps().catch((error) => {
+		conversation.transcript.splice(before);
+		show({
+			type: "card",
+			id: `${messageId}-error`,
+			title: "The assistant could not answer",
+			tone: "danger",
+			body: failure(error, options.report)
+		});
+	}).finally(() => conversation.apply({
+		type: "patch",
+		replying: false
+	}));
+};
+//#endregion
+export { runTurn };

package/dist/create-admin.js

@@ -1,9 +1,11 @@
+import { assistantSettings } from "./assistant/assistant-settings.js";
+import { createErrorHandler } from "./error-handler.js";
+import { builtInAssistant } from "./assistant/built-in-assistant.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { authBasePath } from "./better-auth/create-auth.js";
 import { statusRoute } from "./better-auth/status-route.js";
 import { checkShell } from "./check-shell.js";
 import { checkViews } from "./check-views.js";
-import { createErrorHandler } from "./error-handler.js";
 import { createMeta } from "./meta.js";
 import { buildRegistry } from "./registry.js";
 import { batchRoute } from "./routes/batch.js";
@@ -28,6 +30,8 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		models: Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model])),
 		actions: (resource) => new Set(viewModels.filter((view) => view.resource === resource).flatMap((view) => view.actions.map((action) => action.name)))
 	});
+	const systemPath = basePath.slice(0, basePath.lastIndexOf("/"));
+	const assistant = assistantSettings(options.assistant, globalThis.process?.env ?? {});
 	const deps = {
 		db,
 		registry,
@@ -35,7 +39,7 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		pages: pageModels,
 		...userMenuModel && { userMenu: userMenuModel },
 		basePath,
-		systemPath: basePath.slice(0, basePath.lastIndexOf("/")),
+		systemPath,
 		statementTimeoutMs: options.statementTimeoutMs ?? 15e3,
 		guard: createScanGuard(db, options.scanGuard),
 		hooks: options.writeHooks ?? [],
@@ -44,7 +48,8 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 			...options.roles && { roles: options.roles },
 			...options.defaultAccess && { defaultAccess: options.defaultAccess }
 		},
-		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false
+		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false,
+		...assistant && { assistant: assistant.kind === "external" ? assistant.url : `${systemPath}/assistant` }
 	};
 	const meta = createMeta(deps);
 	const onError = createErrorHandler(options.onUnhandledError);
@@ -76,6 +81,13 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		app.route(authBasePath, statusRoute(auth));
 		app.on(["GET", "POST"], `${authBasePath}/*`, (c) => auth.handler(c.req.raw));
 	}
+	if (assistant?.kind === "built-in") app.route(`${systemPath}/assistant`, builtInAssistant({
+		model: assistant.model,
+		db,
+		meta,
+		authenticate,
+		report: options.onUnhandledError
+	}));
 	app.route("/", batchRoute(deps, authenticate, meta));
 	app.route(basePath, api);
 	app.route(deps.systemPath || "/", system);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { ResourceSource, configExports } from "./resource-source.js";
+import { AssistantOptions, AssistantSettings, ModelSettings, assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
 import { Admin, AdminOptions, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
 import { CreateAdminInput, createAdmin } from "./create-admin.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
@@ -8,4 +9,12 @@ import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./pr
 import { BetterAuthAuthenticatorOptions, betterAuthAuthenticator } from "./better-auth/authenticator.js";
 import { NewUser, StoredUser, createUser, deleteUser, hasUsers, listUsers, parseRoles, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
 import { IssueTokenOptions, issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
-export { type Admin, type AdminAuth, type AdminOptions, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, type NewUser, type PipelineHook, type ResourceSource, type ScanGuardMode, type Session, type StoredUser, type TenantValue, type User, type UserCreatedHook, type ViewSource, type WriteEvent, type WriteOperation, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, createAdmin, createAuth, createUser, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, roleChoices, setUserBanned, setUserRole, unauthorized };
+import { ChatMessage, Completion, ModelError, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
+import { Conversation, conversationKey, createConversations } from "./assistant/conversations.js";
+import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-routes.js";
+import { ApprovalAnswer, ApprovalRequest, requestApproval } from "./assistant/approval.js";
+import { AssistantTool, ToolContext, defineTool } from "./assistant/tools.js";
+import { TurnOptions, runTurn } from "./assistant/turn.js";
+import { QueryOptions, QueryResult, runReadOnlyQuery, runReadWriteQuery } from "./assistant/run-query.js";
+import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.js";
+export { type Admin, type AdminAuth, type AdminOptions, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type ChatMessage, type Completion, type Conversation, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, ModelError, type ModelSettings, type NewUser, type PipelineHook, type QueryOptions, type QueryResult, type ResourceSource, type ScanGuardMode, type Session, type StoredUser, type TenantValue, type ToolCall, type ToolContext, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WriteEvent, type WriteOperation, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defineTool, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, seesAssistant, setUserBanned, setUserRole, streamChatCompletion, unauthorized };

package/dist/index.js

@@ -1,10 +1,19 @@
+import { assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
+import { conversationKey, createConversations } from "./assistant/conversations.js";
+import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
+import { assistantProtocolRoutes } from "./assistant/protocol-routes.js";
+import { runReadOnlyQuery, runReadWriteQuery } from "./assistant/run-query.js";
+import { defineTool } from "./assistant/tools.js";
+import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.js";
+import { requestApproval } from "./assistant/approval.js";
+import { ModelError, streamChatCompletion } from "./assistant/chat-completions.js";
+import { runTurn } from "./assistant/turn.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { createUser, deleteUser, hasUsers, listUsers, parseRoles, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
-import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
 import { jwtAuthenticator } from "./auth/jwt.js";
 import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
 import { issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
-export { HttpProblem, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, createAdmin, createAuth, createUser, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, roleChoices, setUserBanned, setUserRole, unauthorized };
+export { HttpProblem, ModelError, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defineTool, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, seesAssistant, setUserBanned, setUserRole, streamChatCompletion, unauthorized };

package/dist/meta.js

@@ -1,3 +1,4 @@
+import { seesAssistant } from "./assistant/assistant-settings.js";
 import { sha256Hex, stableJson } from "./hash.js";
 import { requestAccess } from "./request-access.js";
 import { pruneView } from "./view-access.js";
@@ -45,7 +46,8 @@ const createMeta = (deps) => {
 					"delete"
 				].filter((op) => resolved.operations[op] && (resolved.recordChecks.includes(op) || resolved.rowFilter[op] !== void 0))
 			}])),
-			...deps.userMenu && { userMenu: { items: deps.userMenu.items.filter(shown) } }
+			...deps.userMenu && { userMenu: { items: deps.userMenu.items.filter(shown) } },
+			...deps.assistant && seesAssistant(session.user.roles) && { assistant: { url: deps.assistant } }
 		};
 		return {
 			body,

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { AssistantOptions } from "./assistant/assistant-settings.js";
 import { Hono } from "hono";
 import { PageModel } from "@protobase/layout";
 import { ResolveOptions, ResourceModel, ViewModel } from "@protobase/schema";
@@ -86,6 +87,8 @@ export type AdminOptions = {
   audit?: AuditQueue;
   /** Called with every error the API turns into a 500, so the host can report it. */
   onUnhandledError?: (error: unknown) => void;
+  /** The assistant in the admin app's dock: a backend elsewhere or the built-in one (see `AssistantOptions`); `false` turns it off. */
+  assistant?: AssistantOptions | false;
 };
 export type ViewSource = {
   toModel(): ViewModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,9 +32,9 @@
     "kysely": "^0.29.6",
     "nodemailer": "^10.0.16",
     "zod": "^4.6.5",
-    "@protobase/query": "0.1.5",
-    "@protobase/layout": "0.1.5",
-    "@protobase/schema": "0.1.5"
+    "@protobase/layout": "0.2.0",
+    "@protobase/query": "0.2.0",
+    "@protobase/schema": "0.2.0"
   },
   "scripts": {
     "build": "tsdown"