@protobase/server 0.1.6 → 0.3.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,47 @@
+//#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.
+ * `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 = {
+  url?: string;
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  chats?: string;
+  fetch?: typeof fetch;
+};
+export type AssistantSettings = {
+  kind: 'external';
+  url: string;
+} | {
+  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"];
+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,55 @@
+//#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",
+	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. */
+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 }
+		},
+		chats: value("chats") ?? ".protobase/chats"
+	};
+};
+//#endregion
+export { assistantRoles, assistantSettings, assistantVariables, defaultChatsDirectory, openRouterModel, openRouterUrl, seesAssistant };

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

@@ -0,0 +1,44 @@
+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. Conversations are files in the `chats` directory.
+* On OpenRouter it caches the prompt and asks for little reasoning.
+*/
+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, page }, session, conversation) => {
+			const { body } = await meta.forCaller(session);
+			await runTurn({
+				model,
+				conversation,
+				session,
+				system: appContext(body.resources, body.views),
+				tools,
+				report,
+				...page && { context: pageContext(page) },
+				...onOpenRouter && {
+					cache: true,
+					reasoning: "low"
+				}
+			}, text);
+		}
+	});
+};
+//#endregion
+export { builtInAssistant };

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

@@ -0,0 +1,74 @@
+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 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 | ChatTextPart[];
+} | {
+  role: 'assistant';
+  content: string | ChatTextPart[] | null;
+  tool_calls?: ToolCall[];
+  reasoning_details?: ReasoningDetail[];
+} | {
+  role: 'tool';
+  tool_call_id: 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';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+};
+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 {
+  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. `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?: CompletionOptions) => Promise<Completion>;
+//#endregion

package/dist/assistant/chat-completions.js

@@ -0,0 +1,101 @@
+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 = [], reasoning, 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 },
+			...reasoning && { reasoning: { effort: reasoning } }
+		}),
+		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;
+};
+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. `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);
+	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),
+		reasoningDetails: reasoningDetails.filter(Boolean)
+	};
+};
+//#endregion
+export { ModelError, streamChatCompletion };

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

@@ -0,0 +1,41 @@
+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 = {
+  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 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;
+};
+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 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: ({ store, keepMessages, keepTranscript }?: ConversationsOptions) => (owner: string, id?: string) => Promise<Conversation>;
+//#endregion

package/dist/assistant/conversations.js

@@ -0,0 +1,108 @@
+import { applyAssistantEvent, emptyAssistantState } from "@protobase/schema";
+//#region src/assistant/conversations.ts
+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) => {
+			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,
+		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);
+		},
+		act: (partId, actionId) => {
+			const handler = actions.get(partId);
+			handler?.(actionId);
+			return handler !== void 0;
+		}
+	};
+};
+/** The owner of a user's conversations, per tenant. */
+const conversationKey = (session) => JSON.stringify([session.tenant ?? null, session.user.id]);
+/**
+* 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 = ({ 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 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;
+	};
+};
+//#endregion
+export { conversationKey, createConversations };