@protobase/server 0.2.0 → 0.3.1

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

@@ -9,6 +9,7 @@ export type ModelSettings = {
 /**
  * `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.
+ * `chats`: the directory the built-in assistant keeps conversations in, one file each.
  * Each falls back to its environment variable; `fetch` replaces the model endpoint, for tests.
  */
 export type AssistantOptions = {
@@ -16,6 +17,7 @@ export type AssistantOptions = {
   apiKey?: string;
   model?: string;
   baseUrl?: string;
+  chats?: string;
   fetch?: typeof fetch;
 };
 export type AssistantSettings = {
@@ -24,12 +26,14 @@ export type AssistantSettings = {
 } | {
   kind: 'built-in';
   model: ModelSettings;
+  chats: string;
 };
 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";
+  readonly chats: "PROTOBASE_ASSISTANT_CHATS";
 };
 /** 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"];

package/dist/assistant/assistant-settings.js

@@ -3,8 +3,11 @@ const assistantVariables = {
 	url: "PROTOBASE_ASSISTANT_URL",
 	apiKey: "PROTOBASE_ASSISTANT_API_KEY",
 	model: "PROTOBASE_ASSISTANT_MODEL",
-	baseUrl: "PROTOBASE_ASSISTANT_BASE_URL"
+	baseUrl: "PROTOBASE_ASSISTANT_BASE_URL",
+	chats: "PROTOBASE_ASSISTANT_CHATS"
 };
+/** Where the built-in assistant keeps conversations without `chats`: relative to the working directory. */
+const defaultChatsDirectory = ".protobase/chats";
 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. */
@@ -44,8 +47,9 @@ const assistantSettings = (option, env) => {
 			apiKey,
 			model,
 			...option && option.fetch && { fetch: option.fetch }
-		}
+		},
+		chats: value("chats") ?? ".protobase/chats"
 	};
 };
 //#endregion
-export { assistantRoles, assistantSettings, assistantVariables, openRouterModel, openRouterUrl, seesAssistant };
+export { assistantRoles, assistantSettings, assistantVariables, defaultChatsDirectory, openRouterModel, openRouterUrl, seesAssistant };

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

@@ -1,24 +1,28 @@
-import { seesAssistant } from "./assistant-settings.js";
+import { openRouterUrl, seesAssistant } from "./assistant-settings.js";
 import { appContext } from "./app-context.js";
 import { conversationKey, createConversations } from "./conversations.js";
+import { fileConversationStore } from "./file-conversation-store.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
+const pageContext = (page) => page && `The user is on the page ${page} of the app (/<resource> lists records, /<resource>/<key> shows one).`;
 /**
 * 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.
+* its prompt, which describes what the caller may see of the app. Conversations are files in the `chats` directory.
+* On OpenRouter it caches the prompt and asks for little reasoning.
 */
-const builtInAssistant = ({ model, db, meta, authenticate, report }) => {
-	const conversations = createConversations();
+const builtInAssistant = ({ model, chats, db, meta, authenticate, report }) => {
+	const conversations = createConversations({ store: fileConversationStore(chats) });
 	const tools = [readOnlyQueryTool(db), readWriteQueryTool(db)];
+	const onOpenRouter = model.baseUrl === openRouterUrl;
 	return assistantProtocolRoutes({
 		authenticate,
 		allows: (session) => seesAssistant(session.user.roles),
 		conversationOf: (session) => conversations(conversationKey(session)),
 		report,
-		onMessage: async (text, session, conversation) => {
+		onMessage: async ({ text, page }, session, conversation) => {
 			const { body } = await meta.forCaller(session);
 			await runTurn({
 				model,
@@ -26,7 +30,12 @@ const builtInAssistant = ({ model, db, meta, authenticate, report }) => {
 				session,
 				system: appContext(body.resources, body.views),
 				tools,
-				report
+				report,
+				...page && { context: pageContext(page) },
+				...onOpenRouter && {
+					cache: true,
+					reasoning: "low"
+				}
 			}, text);
 		}
 	});

package/dist/assistant/cache-breakpoints.d.ts

@@ -0,0 +1,9 @@
+import { ChatMessage } from "./chat-completions.js";
+//#region src/assistant/cache-breakpoints.d.ts
+/**
+ * The messages with a prompt-cache breakpoint (`cache_control`, as OpenRouter and Anthropic read it) at the end of each
+ * message at `indexes`: the endpoint caches everything up to it, tools included. A message without text, such as an
+ * assistant message of only tool calls, gets none.
+ */
+export declare const withCacheBreakpoints: (messages: ChatMessage[], indexes: number[]) => ChatMessage[];
+//#endregion

package/dist/assistant/cache-breakpoints.js

@@ -0,0 +1,25 @@
+//#region src/assistant/cache-breakpoints.ts
+const breakpoint = { type: "ephemeral" };
+const marked = (message) => {
+	if (!message.content) return message;
+	const parts = typeof message.content === "string" ? [{
+		type: "text",
+		text: message.content
+	}] : message.content;
+	const content = parts.map((part, index) => index === parts.length - 1 ? {
+		...part,
+		cache_control: breakpoint
+	} : part);
+	return {
+		...message,
+		content
+	};
+};
+/**
+* The messages with a prompt-cache breakpoint (`cache_control`, as OpenRouter and Anthropic read it) at the end of each
+* message at `indexes`: the endpoint caches everything up to it, tools included. A message without text, such as an
+* assistant message of only tool calls, gets none.
+*/
+const withCacheBreakpoints = (messages, indexes) => messages.map((message, index) => indexes.includes(index) ? marked(message) : message);
+//#endregion
+export { withCacheBreakpoints };

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

@@ -8,19 +8,39 @@ export type ToolCall = {
     arguments: string;
   };
 };
-/** A message of a chat completion: what the model reads, and the tool calls it made with their results. */
+/** A piece of a message's text; `cache_control` marks a prompt-cache breakpoint after it (OpenRouter, Anthropic). */
+export type ChatTextPart = {
+  type: 'text';
+  text: string;
+  cache_control?: {
+    type: 'ephemeral';
+  };
+};
+/**
+ * A message of a chat completion: what the model reads, and the tool calls it made with their results. An assistant
+ * message keeps the model's `reasoning_details` (OpenRouter), which a reasoning model needs back with its tool calls.
+ */
 export type ChatMessage = {
   role: 'system' | 'user';
-  content: string;
+  content: string | ChatTextPart[];
 } | {
   role: 'assistant';
-  content: string | null;
+  content: string | ChatTextPart[] | null;
   tool_calls?: ToolCall[];
+  reasoning_details?: ReasoningDetail[];
 } | {
   role: 'tool';
   tool_call_id: string;
-  content: string;
+  content: string | ChatTextPart[];
 };
+/** One block of a model's reasoning, as OpenRouter streams it: passed back unchanged, never shown. */
+export type ReasoningDetail = {
+  type: string;
+  index?: number;
+  [field: string]: unknown;
+};
+/** How much a reasoning model thinks before it answers, as OpenRouter's `reasoning.effort`. */
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /** A tool as the endpoint's `tools` field describes it: a function with JSON Schema parameters. */
 export type ToolSpec = {
   type: 'function';
@@ -33,6 +53,12 @@ export type ToolSpec = {
 export type Completion = {
   content: string;
   toolCalls: ToolCall[];
+  reasoningDetails: ReasoningDetail[];
+};
+export type CompletionOptions = {
+  tools?: ToolSpec[];
+  reasoning?: ReasoningEffort;
+  signal?: AbortSignal;
 };
 /** A failed call to the model endpoint, with a message an admin can act on. */
 export declare class ModelError extends Error {
@@ -40,11 +66,9 @@ export declare class ModelError extends Error {
 }
 /**
  * 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`.
+ * offering `tools` and calling `onText` with each piece of the answer. `reasoning` sets OpenRouter's reasoning effort,
+ * which other endpoints may refuse. Resolves with the whole answer, the tool calls the model made and its reasoning
+ * details; rejects with a `ModelError`.
  */
-export declare const streamChatCompletion: (settings: ModelSettings, messages: ChatMessage[], onText: (text: string) => void, options?: {
-  tools?: ToolSpec[];
-  signal?: AbortSignal;
-}) => Promise<Completion>;
+export declare const streamChatCompletion: (settings: ModelSettings, messages: ChatMessage[], onText: (text: string) => void, options?: CompletionOptions) => Promise<Completion>;
 //#endregion

package/dist/assistant/chat-completions.js

@@ -24,7 +24,7 @@ const refusal = async (response, settings) => {
 	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) => {
+const send = (settings, messages, { tools = [], reasoning, signal }) => {
 	return (settings.fetch ?? fetch)(`${settings.baseUrl}/chat/completions`, {
 		method: "POST",
 		headers: {
@@ -36,7 +36,8 @@ const send = (settings, messages, tools, signal) => {
 			model: settings.model,
 			messages,
 			stream: true,
-			...tools.length > 0 && { tools }
+			...tools.length > 0 && { tools },
+			...reasoning && { reasoning: { effort: reasoning } }
 		}),
 		signal
 	}).catch((error) => {
@@ -57,30 +58,43 @@ const addToolCall = (calls, delta) => {
 	if (delta.function?.name) call.function.name += delta.function.name;
 	if (delta.function?.arguments) call.function.arguments += delta.function.arguments;
 };
+const addReasoning = (details, piece) => {
+	const at = piece.index ?? details.length;
+	const detail = details[at];
+	if (!detail) {
+		details[at] = { ...piece };
+		return;
+	}
+	for (const [field, value] of Object.entries(piece)) detail[field] = (field === "text" || field === "summary" || field === "data") && typeof value === "string" && typeof detail[field] === "string" ? `${String(detail[field])}${value}` : value;
+};
 /**
 * 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`.
+* offering `tools` and calling `onText` with each piece of the answer. `reasoning` sets OpenRouter's reasoning effort,
+* which other endpoints may refuse. Resolves with the whole answer, the tool calls the model made and its reasoning
+* details; rejects with a `ModelError`.
 */
 const streamChatCompletion = async (settings, messages, onText, options = {}) => {
-	const response = await send(settings, messages, options.tools ?? [], options.signal);
+	const response = await send(settings, messages, options);
 	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 = [];
+	const reasoningDetails = [];
 	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);
+		for (const piece of delta?.reasoning_details ?? []) addReasoning(reasoningDetails, piece);
 		if (!delta?.content) return;
 		content += delta.content;
 		onText(delta.content);
 	});
 	return {
 		content,
-		toolCalls: toolCalls.filter(Boolean)
+		toolCalls: toolCalls.filter(Boolean),
+		reasoningDetails: reasoningDetails.filter(Boolean)
 	};
 };
 //#endregion

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

@@ -0,0 +1,28 @@
+import { ChatMessage } from "./chat-completions.js";
+import { AssistantEvent } from "@protobase/schema";
+//#region src/assistant/conversation-store.d.ts
+/**
+ * What a conversation keeps, appended in order: the chat the user sees as `state` and `message` events, and the
+ * transcript the model read, one `transcript` record per message, exactly as it was sent.
+ */
+export type ConversationRecord = Extract<AssistantEvent, {
+  type: 'state' | 'message';
+}> | {
+  type: 'transcript';
+  message: ChatMessage;
+};
+/**
+ * Where conversations live between requests and restarts, by owner (one user, see `conversationKey`) and id. The
+ * built-in assistant keeps them in files (`fileConversationStore`); a hosted backend can keep them in its database.
+ */
+export type ConversationStore = {
+  /** The conversation's records in the order they were appended; none for a conversation not started. */
+  load: (owner: string, id: string) => Promise<ConversationRecord[]>;
+  append: (owner: string, id: string, records: ConversationRecord[]) => Promise<void>;
+  /** The owner's conversations, the latest changed first. */
+  list: (owner: string) => Promise<Array<{
+    id: string;
+    updatedAt: Date;
+  }>>;
+};
+//#endregion

package/dist/assistant/conversations.d.ts

@@ -1,5 +1,6 @@
 import { Session } from "../types.js";
 import { ChatMessage } from "./chat-completions.js";
+import { ConversationStore } from "./conversation-store.js";
 import { AssistantEvent, AssistantState } from "@protobase/schema";
 //#region src/assistant/conversations.d.ts
 export type Conversation = {
@@ -7,18 +8,34 @@ export type Conversation = {
   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[];
+  /** The chat as the model read it, tool calls and their results included, oldest first. */
+  transcript: () => readonly ChatMessage[];
+  /** Adds messages to the transcript, as they were sent to the model or came from it. */
+  remember: (...messages: ChatMessage[]) => void;
+  /** Appends what changed since the last save to the store: the chat's changed messages and the transcript's new ones. */
+  save: () => Promise<void>;
   /** 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 type ConversationsOptions = {
+  /** Where conversations are kept; without one they live in this process's memory only. */
+  store?: ConversationStore;
+  /** Chat messages the user sees. Default 50. */
+  keepMessages?: number;
+  /**
+   * Transcript messages the model reads. Past it, the transcript drops its older half at the next user message, so
+   * the prefix a model endpoint caches stays the same for many turns. Default 40.
+   */
+  keepTranscript?: number;
+};
+/** The owner of a user's conversations, per 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.
+ * Conversations by owner (see `conversationKey`) and id, each loaded from the store on first use and then kept in this
+ * process's memory, shared by the owner's open tabs. A deployment of several instances needs each owner's requests on
+ * one instance, since a turn and its approvals run in the instance that started it.
  */
-export declare const createConversations: (keep?: number) => (key: string) => Conversation;
+export declare const createConversations: ({ store, keepMessages, keepTranscript }?: ConversationsOptions) => (owner: string, id?: string) => Promise<Conversation>;
 //#endregion

package/dist/assistant/conversations.js

@@ -1,24 +1,78 @@
 import { applyAssistantEvent, emptyAssistantState } from "@protobase/schema";
 //#region src/assistant/conversations.ts
-const createConversation = (keep) => {
+const remembered = (transcript, message, keep) => {
+	const next = [...transcript, message];
+	if (message.role !== "user" || next.length <= keep) return next;
+	return next.slice(next.findIndex((entry, index) => index >= next.length - keep / 2 && entry.role === "user"));
+};
+const createConversation = (records, keepMessages, keepTranscript, write) => {
 	let state = emptyAssistantState;
+	let transcript = [];
 	const listeners = /* @__PURE__ */ new Set();
 	const actions = /* @__PURE__ */ new Map();
+	let replaced = false;
+	const changed = /* @__PURE__ */ new Set();
+	let unsaved = [];
+	let saving = Promise.resolve();
+	const fold = (event) => {
+		const next = applyAssistantEvent(state, event);
+		state = next.messages.length > keepMessages ? {
+			...next,
+			messages: next.messages.slice(-keepMessages)
+		} : next;
+	};
+	const remember = (message) => {
+		transcript = remembered(transcript, message, keepTranscript);
+	};
+	for (const record of records) if (record.type === "transcript") remember(record.message);
+	else fold(record);
+	state = {
+		...state,
+		replying: false
+	};
+	const pending = () => {
+		const records = [...replaced ? [{
+			type: "state",
+			state: {
+				messages: state.messages,
+				replying: false
+			}
+		}] : state.messages.filter((message) => changed.has(message.id)).map((message) => ({
+			type: "message",
+			message
+		})), ...unsaved.map((message) => ({
+			type: "transcript",
+			message
+		}))];
+		replaced = false;
+		changed.clear();
+		unsaved = [];
+		return records;
+	};
 	return {
 		state: () => state,
 		apply: (event) => {
-			const next = applyAssistantEvent(state, event);
-			state = next.messages.length > keep ? {
-				...next,
-				messages: next.messages.slice(-keep)
-			} : next;
+			fold(event);
+			if (event.type === "state") replaced = true;
+			if (event.type === "message") changed.add(event.message.id);
+			if (event.type === "part") changed.add(event.messageId);
 			for (const listener of listeners) listener(event);
 		},
 		subscribe: (listener) => {
 			listeners.add(listener);
 			return () => listeners.delete(listener);
 		},
-		transcript: [],
+		transcript: () => transcript,
+		remember: (...messages) => {
+			for (const message of messages) remember(message);
+			unsaved.push(...messages);
+		},
+		save: () => {
+			const records = pending();
+			const next = () => records.length > 0 ? write(records) : Promise.resolve();
+			saving = saving.then(next, next);
+			return saving;
+		},
 		onAction: (partId, handler) => {
 			actions.set(partId, handler);
 			return () => actions.delete(partId);
@@ -30,19 +84,23 @@ const createConversation = (keep) => {
 		}
 	};
 };
-/** One conversation per user and tenant. */
+/** The owner of a user's conversations, per 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.
+* Conversations by owner (see `conversationKey`) and id, each loaded from the store on first use and then kept in this
+* process's memory, shared by the owner's open tabs. A deployment of several instances needs each owner's requests on
+* one instance, since a turn and its approvals run in the instance that started it.
 */
-const createConversations = (keep = 50) => {
-	const byKey = /* @__PURE__ */ new Map();
-	return (key) => {
-		const existing = byKey.get(key);
+const createConversations = ({ store, keepMessages = 50, keepTranscript = 40 } = {}) => {
+	const loaded = /* @__PURE__ */ new Map();
+	return (owner, id = "chat") => {
+		const key = JSON.stringify([owner, id]);
+		const existing = loaded.get(key);
 		if (existing) return existing;
-		const conversation = createConversation(keep);
-		byKey.set(key, conversation);
+		const write = (records) => store?.append(owner, id, records) ?? Promise.resolve();
+		const conversation = (store?.load(owner, id) ?? Promise.resolve([])).then((records) => createConversation(records, keepMessages, keepTranscript, write));
+		conversation.catch(() => loaded.delete(key));
+		loaded.set(key, conversation);
 		return conversation;
 	};
 };

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

@@ -1,15 +1,16 @@
 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;
+  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: (text: string, session: Session, conversation: Conversation) => Promise<void>;
+  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. */

package/dist/assistant/protocol-routes.js

@@ -4,11 +4,16 @@ 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;
+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`);
-	return text.trim();
+	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 : {};
@@ -31,8 +36,8 @@ const assistantProtocolRoutes = (backend) => {
 		c.set("session", session);
 		await next();
 	});
-	app.get("/events", (c) => {
-		const conversation = backend.conversationOf(c.get("session"));
+	app.get("/events", async (c) => {
+		const conversation = await backend.conversationOf(c.get("session"));
 		return streamSSE(c, async (stream) => {
 			const queue = [{
 				type: "state",
@@ -56,15 +61,15 @@ const assistantProtocolRoutes = (backend) => {
 	});
 	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);
+		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(text, session, conversation).catch((error) => backend.report?.(error));
+		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 (!backend.conversationOf(c.get("session")).act(partId, actionId)) throw notFound("No card waits for that action");
+		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;

package/dist/assistant/turn.d.ts

@@ -1,5 +1,6 @@
 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
@@ -14,13 +15,23 @@ export type TurnOptions = {
   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;
+  /** 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.
+ * 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

@@ -1,4 +1,5 @@
 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) => {
@@ -8,24 +9,26 @@ const toolResult = async (call, tools, context) => {
 	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.";
 };
+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.
+* 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 } = options;
+	const { model, conversation, session, system, tools = [], maxSteps = 8, reasoning, cache = false } = options;
 	const messageId = crypto.randomUUID();
 	const show = (part) => conversation.apply({
 		type: "part",
@@ -62,11 +65,15 @@ const runTurn = async (options, text) => {
 		type: "patch",
 		replying: true
 	});
-	conversation.transcript = trimmed([...conversation.transcript, {
+	conversation.remember({
 		role: "user",
-		content: text
-	}], options.keep ?? 40);
-	const before = conversation.transcript.length;
+		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 = {
@@ -74,20 +81,21 @@ const runTurn = async (options, text) => {
 				id: `${messageId}-${step}`,
 				text: ""
 			};
-			const { content, toolCalls } = await streamChatCompletion(model, [{
-				role: "system",
-				content: system
-			}, ...conversation.transcript], (piece) => {
+			const { content, toolCalls, reasoningDetails } = await streamChatCompletion(model, marked([...earlier, ...added], earlier.length - 2, cache), (piece) => {
 				part.text += piece;
 				show({ ...part });
-			}, { tools: specs });
-			conversation.transcript.push({
+			}, {
+				tools: specs,
+				reasoning
+			});
+			added.push({
 				role: "assistant",
 				content: content || null,
-				...toolCalls.length > 0 && { tool_calls: toolCalls }
+				...toolCalls.length > 0 && { tool_calls: toolCalls },
+				...reasoningDetails.length > 0 && { reasoning_details: reasoningDetails }
 			});
 			if (toolCalls.length === 0) return;
-			for (const call of toolCalls) conversation.transcript.push({
+			for (const call of toolCalls) added.push({
 				role: "tool",
 				tool_call_id: call.id,
 				content: await toolResult(call, tools, context)
@@ -99,16 +107,14 @@ const runTurn = async (options, text) => {
 			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({
+	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
 	}));

package/dist/create-admin.js

@@ -83,6 +83,7 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 	}
 	if (assistant?.kind === "built-in") app.route(`${systemPath}/assistant`, builtInAssistant({
 		model: assistant.model,
+		chats: assistant.chats,
 		db,
 		meta,
 		authenticate,

package/dist/index.d.ts

@@ -9,12 +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";
-import { ChatMessage, Completion, ModelError, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
-import { Conversation, conversationKey, createConversations } from "./assistant/conversations.js";
+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 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 };
+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,11 +1,13 @@
 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";
@@ -16,4 +18,4 @@ 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, 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 };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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/layout": "0.2.0",
-    "@protobase/query": "0.2.0",
-    "@protobase/schema": "0.2.0"
+    "@protobase/layout": "0.3.1",
+    "@protobase/schema": "0.3.1",
+    "@protobase/query": "0.3.1"
   },
   "scripts": {
     "build": "tsdown"