@protobase/server 0.1.6 → 0.3.0

package/dist/assistant/file-conversation-store.d.ts

@@ -0,0 +1,8 @@
+import { ConversationStore } from "./conversation-store.js";
+//#region src/assistant/file-conversation-store.d.ts
+/**
+ * Conversations as files: `<directory>/<owner>/<id>.jsonl`, one record per line, appended as the chat goes on. A
+ * relative directory is resolved against the working directory; it is made on the first append.
+ */
+export declare const fileConversationStore: (directory: string) => ConversationStore;
+//#endregion

package/dist/assistant/file-conversation-store.js

@@ -0,0 +1,40 @@
+//#region src/assistant/file-conversation-store.ts
+const fs = () => import("node:fs/promises");
+const missing = (error) => error instanceof Error && error.code === "ENOENT";
+const segment = (name) => encodeURIComponent(name).replaceAll(".", "%2E");
+const extension = ".jsonl";
+/**
+* Conversations as files: `<directory>/<owner>/<id>.jsonl`, one record per line, appended as the chat goes on. A
+* relative directory is resolved against the working directory; it is made on the first append.
+*/
+const fileConversationStore = (directory) => {
+	const folder = (owner) => `${directory}/${segment(owner)}`;
+	const file = (owner, id) => `${folder(owner)}/${segment(id)}${extension}`;
+	return {
+		load: async (owner, id) => {
+			return (await (await fs()).readFile(file(owner, id), "utf8").catch((error) => {
+				if (missing(error)) return "";
+				throw error;
+			})).split("\n").slice(0, -1).map((line) => JSON.parse(line));
+		},
+		append: async (owner, id, records) => {
+			if (records.length === 0) return;
+			const { appendFile, mkdir } = await fs();
+			await mkdir(folder(owner), { recursive: true });
+			await appendFile(file(owner, id), records.map((record) => `${JSON.stringify(record)}\n`).join(""));
+		},
+		list: async (owner) => {
+			const { readdir, stat } = await fs();
+			const names = await readdir(folder(owner)).catch((error) => {
+				if (missing(error)) return [];
+				throw error;
+			});
+			return (await Promise.all(names.filter((name) => name.endsWith(extension)).map(async (name) => ({
+				id: decodeURIComponent(name.slice(0, -6)),
+				updatedAt: (await stat(`${folder(owner)}/${name}`)).mtime
+			})))).sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+		}
+	};
+};
+//#endregion
+export { fileConversationStore };

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

@@ -0,0 +1,28 @@
+import { Authenticator, Session } from "../types.js";
+import { Conversation } from "./conversations.js";
+import { Hono } from "hono";
+import { AssistantMessageRequest } from "@protobase/schema";
+//#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 | Promise<Conversation>;
+  /** Answers a message of the user with events on the conversation; called only while the backend is not replying. */
+  onMessage: (message: AssistantMessageRequest, 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,78 @@
+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 maxPageLength = 2e3;
+const messageOf = (body, max) => {
+	const { text, page } = isObject(body) ? body : {};
+	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`);
+	if (page !== void 0 && (typeof page !== "string" || page.length > maxPageLength)) throw badRequest("invalid-message", `"page" must be a path of at most ${maxPageLength} characters`);
+	return {
+		text: text.trim(),
+		...page && { page }
+	};
+};
+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", async (c) => {
+		const conversation = await 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 message = messageOf(await c.req.json(), backend.maxMessageLength ?? 4e3);
+		const conversation = await backend.conversationOf(session);
+		if (conversation.state().replying) throw new HttpProblem(409, "assistant-replying", "Conflict", "The assistant is still answering");
+		backend.onMessage(message, 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 (!(await 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,37 @@
+import { ModelSettings } from "./assistant-settings.js";
+import { Session } from "../types.js";
+import { ReasoningEffort } from "./chat-completions.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;
+  /** Text the model reads before the user's message, such as the page they are on; the transcript keeps it with the message. */
+  context?: string;
+  /** How much a reasoning model thinks before it answers (OpenRouter's `reasoning.effort`); the model's default without it. */
+  reasoning?: ReasoningEffort;
+  /**
+   * Marks prompt-cache breakpoints (`cache_control`) on the system prompt, the transcript before this turn and the
+   * latest message, so an endpoint that caches on them (OpenRouter, Anthropic) bills the repeated prefix as a cache read.
+   * Off by default: an endpoint that does not know the field may refuse it.
+   */
+  cache?: boolean;
+};
+/**
+ * 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. The transcript keeps
+ * every message as the model read it, so the next turn's request starts with the same prefix; the turn ends by saving
+ * the conversation.
+ */
+export declare const runTurn: (options: TurnOptions, text: string) => Promise<void>;
+//#endregion

package/dist/assistant/turn.js

@@ -0,0 +1,123 @@
+import { requestApproval } from "./approval.js";
+import { withCacheBreakpoints } from "./cache-breakpoints.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 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.";
+};
+const marked = (messages, before, cache) => cache ? withCacheBreakpoints(messages, [
+	0,
+	before,
+	messages.length - 1
+]) : messages;
+/**
+* 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. The transcript keeps
+* every message as the model read it, so the next turn's request starts with the same prefix; the turn ends by saving
+* the conversation.
+*/
+const runTurn = async (options, text) => {
+	const { model, conversation, session, system, tools = [], maxSteps = 8, reasoning, cache = false } = 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.remember({
+		role: "user",
+		content: options.context ? `${options.context}\n\n${text}` : text
+	});
+	const earlier = [{
+		role: "system",
+		content: system
+	}, ...conversation.transcript()];
+	const added = [];
+	const steps = async () => {
+		for (let step = 0; step < maxSteps; step++) {
+			const part = {
+				type: "text",
+				id: `${messageId}-${step}`,
+				text: ""
+			};
+			const { content, toolCalls, reasoningDetails } = await streamChatCompletion(model, marked([...earlier, ...added], earlier.length - 2, cache), (piece) => {
+				part.text += piece;
+				show({ ...part });
+			}, {
+				tools: specs,
+				reasoning
+			});
+			added.push({
+				role: "assistant",
+				content: content || null,
+				...toolCalls.length > 0 && { tool_calls: toolCalls },
+				...reasoningDetails.length > 0 && { reasoning_details: reasoningDetails }
+			});
+			if (toolCalls.length === 0) return;
+			for (const call of toolCalls) added.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().then(() => conversation.remember(...added), (error) => show({
+		type: "card",
+		id: `${messageId}-error`,
+		title: "The assistant could not answer",
+		tone: "danger",
+		body: failure(error, options.report)
+	}));
+	await conversation.save().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,14 @@ 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,
+		chats: assistant.chats,
+		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,15 @@ 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, ChatTextPart, Completion, CompletionOptions, ModelError, ReasoningDetail, ReasoningEffort, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
+import { ConversationRecord, ConversationStore } from "./assistant/conversation-store.js";
+import { Conversation, ConversationsOptions, conversationKey, createConversations } from "./assistant/conversations.js";
+import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-routes.js";
+import { fileConversationStore } from "./assistant/file-conversation-store.js";
+import { withCacheBreakpoints } from "./assistant/cache-breakpoints.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 ChatTextPart, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, ModelError, type ModelSettings, type NewUser, type PipelineHook, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, 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, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, seesAssistant, setUserBanned, setUserRole, streamChatCompletion, unauthorized, withCacheBreakpoints };

package/dist/index.js

@@ -1,10 +1,21 @@
+import { assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
+import { conversationKey, createConversations } from "./assistant/conversations.js";
+import { fileConversationStore } from "./assistant/file-conversation-store.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 { withCacheBreakpoints } from "./assistant/cache-breakpoints.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, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, seesAssistant, setUserBanned, setUserRole, streamChatCompletion, unauthorized, withCacheBreakpoints };

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;