@tansy/ai 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/admin.d.ts +2 -0
  4. package/admin.js +17 -0
  5. package/ai.css +280 -0
  6. package/api.d.ts +91 -0
  7. package/api.js +79 -0
  8. package/assistant.d.ts +3 -0
  9. package/assistant.js +290 -0
  10. package/attach.d.ts +48 -0
  11. package/attach.js +141 -0
  12. package/attachments.d.ts +34 -0
  13. package/attachments.js +66 -0
  14. package/chats.d.ts +35 -0
  15. package/chats.js +78 -0
  16. package/client.d.ts +3 -0
  17. package/client.js +88 -0
  18. package/composer.d.ts +38 -0
  19. package/composer.js +155 -0
  20. package/errors.d.ts +5 -0
  21. package/errors.js +25 -0
  22. package/history.d.ts +15 -0
  23. package/history.js +47 -0
  24. package/icons.generated.d.ts +5 -0
  25. package/icons.generated.js +66 -0
  26. package/images.d.ts +21 -0
  27. package/images.js +23 -0
  28. package/index.d.ts +26 -0
  29. package/index.js +701 -0
  30. package/logic.d.ts +77 -0
  31. package/logic.js +166 -0
  32. package/markdown.d.ts +38 -0
  33. package/markdown.js +142 -0
  34. package/media.d.ts +24 -0
  35. package/media.js +64 -0
  36. package/messages.d.ts +891 -0
  37. package/messages.js +689 -0
  38. package/models.d.ts +7 -0
  39. package/models.js +47 -0
  40. package/package.json +46 -4
  41. package/parts.d.ts +59 -0
  42. package/parts.js +110 -0
  43. package/provider.d.ts +134 -0
  44. package/provider.js +117 -0
  45. package/role.d.ts +24 -0
  46. package/role.js +25 -0
  47. package/workflow/check.d.ts +46 -0
  48. package/workflow/check.js +63 -0
  49. package/workflow/client.d.ts +90 -0
  50. package/workflow/client.js +51 -0
  51. package/workflow/editor.d.ts +13 -0
  52. package/workflow/editor.js +133 -0
  53. package/workflow/engine.d.ts +232 -0
  54. package/workflow/engine.js +779 -0
  55. package/workflow/icons.d.ts +26 -0
  56. package/workflow/icons.js +67 -0
  57. package/workflow/model-picker.d.ts +22 -0
  58. package/workflow/model-picker.js +69 -0
  59. package/workflow/page.d.ts +3 -0
  60. package/workflow/page.js +118 -0
  61. package/workflow/routes.d.ts +12 -0
  62. package/workflow/routes.js +418 -0
  63. package/workflow/run.d.ts +8 -0
  64. package/workflow/run.js +162 -0
  65. package/workflow/schema.d.ts +183 -0
  66. package/workflow/schema.js +143 -0
  67. package/workflow/templates.d.ts +9 -0
  68. package/workflow/templates.js +81 -0
  69. package/workflow/workflow.css +241 -0
package/index.js ADDED
@@ -0,0 +1,701 @@
1
+ import { createHash } from "node:crypto";
2
+ import { z } from "zod";
3
+ import { convertToModelMessages, createUIMessageStreamResponse, dynamicTool, generateId, generateText, isStepCount, jsonSchema, Output, streamText, toUIMessageStream, validateUIMessages } from "ai";
4
+ import { apiPath, definePlugin, defineRoute, mergeMessagesByLanguage } from "tansy/plugin";
5
+ import { CHAT_ID, chatStore } from "./chats";
6
+ import { fillSchema, fillValues, forModel, jsonInstructions, systemPrompt, textOf, WRITE_ACTIONS, writePrompt } from "./logic";
7
+ import { chatModels, imageModels, ModelListError } from "./provider";
8
+ import { attachmentIdOf, attachmentStore, ATTACHMENT_ID } from "./attachments";
9
+ import { acceptedTypes, ATTACHMENT_TYPES, attachmentType, MAX_ATTACHMENT_BYTES, readableKinds } from "./media";
10
+ import { ASPECT_RATIOS, drawPicture, NoPicture } from "./images";
11
+ import { messages } from "./messages";
12
+ import { providerReason } from "./errors";
13
+ import { capabilitiesOf, listModels } from "./models";
14
+ import { workflowJob, workflowRoutes } from "./workflow/routes";
15
+ import { ASSISTANT_ROLE, assistantRole, givesRoles, ROLE_NAME, roleFor } from "./role";
16
+ export { WORKFLOWS } from "./workflow/routes";
17
+ export { ASSISTANT_ROLE } from "./role";
18
+ const PROVIDER_ID = /^[a-z][a-z0-9]{0,19}$/;
19
+ const optionsSchema = z.strictObject({
20
+ providers: z.array(z.object({ id: z.string().regex(PROVIDER_ID, "A provider's id is lowercase letters and digits."), label: z.string().min(1) }).loose()).min(1, "Add at least one provider, such as openai() from @tansy/ai-openai."),
21
+ provider: z.string(),
22
+ }).superRefine((value, issues) => {
23
+ const ids = value.providers.map((provider) => provider.id);
24
+ const twice = ids.find((id, index) => ids.indexOf(id) !== index);
25
+ if (twice)
26
+ issues.addIssue({ code: "custom", path: ["providers"], message: `The provider "${twice}" is listed twice.` });
27
+ if (!ids.includes(value.provider))
28
+ issues.addIssue({ code: "custom", path: ["provider"], message: `"${value.provider}" isn't one of the providers listed.` });
29
+ });
30
+ /** Using the assistant, filling forms and writing fields. Each acts with the person's own access, so it grants nothing else. */
31
+ export const USE = "ext.ai:use";
32
+ /** The model setting's description in other languages, which names each provider's default model as the English one does. ICU's quote character is doubled. */
33
+ const modelWords = (providers) => ({
34
+ // A provider's name is its brand, the same in every language.
35
+ ar: { settings: { imageProvider: { options: Object.fromEntries(providers.map((provider) => [provider.id, provider.label])) }, model: { description: `معرّف النموذج لدى ذلك المزوّد. الفارغ يستخدم النموذج الافتراضي للمزوّد: ${providers.map((provider) => `${provider.label}، ${provider.defaultModel || "لا يوجد"}`).join("؛ ").replace(/'/g, "''").replace(/[{}]/g, "")}.` } } },
36
+ });
37
+ /** The model settings offer the chosen provider's models, from GET /models. */
38
+ const MODEL_CHOICES = { route: "/models", with: ["provider"] };
39
+ /** Who may list a provider's models: whoever may change the plugin's settings, as listing uses the saved key. */
40
+ const SETTINGS = "setting:update";
41
+ /** How hard a model thinks before it answers, as the AI SDK names it. Providers without thinking ignore it. */
42
+ export const REASONING = ["provider-default", "none", "low", "medium", "high"];
43
+ /** A model id as providers write them: "gpt-6", "anthropic/claude-opus-5-5", "llama3.3:70b". */
44
+ const MODEL_ID = /^[A-Za-z0-9][\w.:/@+-]{0,199}$/;
45
+ /** The picture setting's choice for the assistant's own provider. */
46
+ const SAME = "same";
47
+ /** The provider a setting names, or the assistant's own for "same" or nothing. */
48
+ const providerOf = (value, fallback) => (value && value !== SAME ? value : fallback);
49
+ const sharedSettings = (value, providers) => [
50
+ { name: "provider", type: "select", default: value.provider, label: "Provider", description: "Who runs the model. Fill in that provider's settings below.", options: providers.map((provider) => ({ value: provider.id, label: provider.label })) },
51
+ { name: "model", type: "text", default: "", maxLength: 200, suggestions: MODEL_CHOICES, label: "Model", description: `The model's id at that provider. Empty uses the provider's default: ${providers.map((provider) => `${provider.label}, ${provider.defaultModel || "none"}`).join("; ")}.` },
52
+ { name: "fastModel", type: "text", default: "", maxLength: 200, suggestions: MODEL_CHOICES, label: "Model for writing fields", description: "A quicker, cheaper model for writing and improving one field. Empty uses the model above." },
53
+ { name: "imageProvider", type: "select", default: SAME, label: "Provider for pictures", description: "Who draws pictures when someone asks the assistant for one. Workflows choose their own.", options: [{ value: SAME, label: "The provider above" }, ...providers.map((provider) => ({ value: provider.id, label: provider.label }))] },
54
+ { name: "imageModel", type: "text", default: "", maxLength: 200, suggestions: { route: "/image-models", with: ["provider", "imageProvider"] }, label: "Model for pictures", description: "The model that draws in the chat: an image model, such as gpt-image-2, or one that answers with pictures, such as a Gemini image model. Empty: the assistant doesn't draw." },
55
+ { name: "chooseModel", type: "boolean", default: true, label: "People choose the model in the chat", description: "The assistant offers every model the key can use, and how long it thinks. Off keeps everyone on the model above." },
56
+ { name: "reasoning", type: "select", default: "provider-default", label: "Thinking", description: "How long the assistant thinks before it answers, on models that can. People can change it in the chat when they choose the model.", options: [
57
+ { value: "provider-default", label: "The model's default" },
58
+ { value: "none", label: "Off" },
59
+ { value: "low", label: "Low" },
60
+ { value: "medium", label: "Medium" },
61
+ { value: "high", label: "High" },
62
+ ] },
63
+ { name: "role", type: "text", default: ASSISTANT_ROLE, maxLength: 40, suggestions: { route: "/roles" }, label: "Role the AI acts with", description: "The AI can do only what this role and the person using it may both do. AI assistant, made with the plugin, reads and drafts content; change what it may do under Roles, or choose another role." },
64
+ { name: "chooseRole", type: "boolean", default: true, label: "Admins choose the role in the chat", description: "Lets people who may give users roles, admins by default, give the assistant another role for a chat. It still never gets more than their own access." },
65
+ { name: "instructions", type: "text", default: "", maxLength: 4000, multiline: true, label: "Site guidance", description: "Added to every request: who the site is for, its tone, words to use or avoid." },
66
+ { name: "maxSteps", type: "number", default: 12, min: 1, max: 50, integer: true, label: "Most tool calls per answer", description: "How many tool calls the assistant may make before it stops and answers." },
67
+ { name: "maxOutputTokens", type: "number", default: 4000, min: 256, max: 64000, integer: true, label: "Longest answer (tokens)" },
68
+ ];
69
+ function providerSettings(providers) {
70
+ return providers.flatMap((provider) => provider.settings().map((field) => {
71
+ if (!field.name.startsWith(provider.id))
72
+ throw new Error(`AI provider "${provider.id}": the setting "${field.name}" must start with "${provider.id}".`);
73
+ return field;
74
+ }));
75
+ }
76
+ const refuse = (status, code, message) => Response.json({ error: { code, message } }, { status });
77
+ /**
78
+ * Signs approvals the server asked for, so a request can't carry an approval the person
79
+ * never gave. Derived from the auth secret under its own label, so it is no other key.
80
+ */
81
+ const approvalSecret = () => {
82
+ const secret = process.env.BETTER_AUTH_SECRET;
83
+ return secret ? createHash("sha256").update(`tansy:ai-tool-approval:${secret}`).digest() : undefined;
84
+ };
85
+ /** A provider's message can quote the site's account, so it stays in the server log. */
86
+ function providerFailed(error) {
87
+ console.error("[ai] the provider failed", error);
88
+ return refuse(502, "AI_PROVIDER_FAILED", providerReason(error));
89
+ }
90
+ /** An error a tool threw for the caller, such as a refused rule, as the API would give it. Anything else stays in the log. */
91
+ function toolFailure(error) {
92
+ const known = error;
93
+ if (typeof known?.status === "number" && typeof known.code === "string")
94
+ return { error: { code: known.code, message: String(known.message), details: known.details } };
95
+ console.error("[ai] a tool failed", error);
96
+ return { error: { code: "TOOL_FAILED", message: "Something went wrong running that tool." } };
97
+ }
98
+ const chatId = z.string().regex(CHAT_ID);
99
+ /** Reads a request's body up to `max` bytes, or null when it is longer. */
100
+ async function readLimited(request, max) {
101
+ if (Number(request.headers.get("content-length") ?? 0) > max)
102
+ return null;
103
+ const reader = request.body?.getReader();
104
+ if (!reader)
105
+ return Buffer.alloc(0);
106
+ const chunks = [];
107
+ let total = 0;
108
+ for (;;) {
109
+ const { done, value } = await reader.read();
110
+ if (done)
111
+ break;
112
+ total += value.byteLength;
113
+ if (total > max) {
114
+ await reader.cancel().catch(() => undefined);
115
+ return null;
116
+ }
117
+ chunks.push(value);
118
+ }
119
+ return Buffer.concat(chunks);
120
+ }
121
+ /** A file name safe to keep and to send back in a header. */
122
+ const cleanName = (name) => name.normalize("NFKC").replace(/[^\p{L}\p{N}._ -]+/gu, "-").replace(/\s+/g, " ").trim().slice(0, 120) || "file";
123
+ const KIND_WORDS = { image: "pictures", file: "PDFs", audio: "sound", video: "video" };
124
+ /** All a chat's files sent to a model, at most: older ones past it are named rather than sent. */
125
+ const FILES_BUDGET = 24 * 1024 * 1024;
126
+ /**
127
+ * The conversation as the model gets it. The chat's files are the person's own attachments,
128
+ * read from the store: a file part pointing anywhere else is refused, so the server never
129
+ * fetches an address a request names. Text files become text, files the model can't read
130
+ * are named instead, and files from earlier messages past the budget are named too.
131
+ */
132
+ async function withFiles(messages, read, capabilities, modelId) {
133
+ const kinds = readableKinds(capabilities);
134
+ const lastUser = messages.findLastIndex((message) => message.role === "user");
135
+ let budget = FILES_BUDGET;
136
+ const out = [];
137
+ for (let index = messages.length - 1; index >= 0; index--) {
138
+ const message = messages[index];
139
+ if (!message.parts.some((part) => part.type === "file")) {
140
+ out.unshift(message);
141
+ continue;
142
+ }
143
+ // Only the person attaches files. Anything else claiming one is dropped.
144
+ if (message.role !== "user") {
145
+ out.unshift({ ...message, parts: message.parts.filter((part) => part.type !== "file") });
146
+ continue;
147
+ }
148
+ const parts = [];
149
+ for (const part of message.parts) {
150
+ if (part.type !== "file") {
151
+ parts.push(part);
152
+ continue;
153
+ }
154
+ const id = attachmentIdOf(part.url);
155
+ if (!id)
156
+ return refuse(400, "BAD_ATTACHMENT", "A file in the chat can't be read. Attach it again.");
157
+ const file = await read(id);
158
+ const name = file?.name ?? part.filename ?? "file";
159
+ if (!file) {
160
+ parts.push({ type: "text", text: `[The person attached "${name}", which is no longer kept.]` });
161
+ continue;
162
+ }
163
+ const kind = ATTACHMENT_TYPES[file.mediaType];
164
+ if (kind === "text") {
165
+ parts.push({ type: "text", text: `The person attached "${name}":\n\n\`\`\`\n${file.data.toString("utf8").slice(0, 100_000)}\n\`\`\`` });
166
+ continue;
167
+ }
168
+ if (!kind || !kinds.has(kind)) {
169
+ if (index === lastUser && capabilities.reported)
170
+ return refuse(400, "AI_CANT_READ", `${modelId} can't read ${KIND_WORDS[kind ?? ""] ?? "this kind of file"}. Choose a model that can, or remove the file.`);
171
+ parts.push({ type: "text", text: `[The person attached "${name}", which this model can't read.]` });
172
+ continue;
173
+ }
174
+ if (file.data.byteLength > budget) {
175
+ parts.push({ type: "text", text: `[The person attached "${name}" earlier in the chat.]` });
176
+ continue;
177
+ }
178
+ budget -= file.data.byteLength;
179
+ parts.push({ type: "file", mediaType: file.mediaType, filename: name, url: `data:${file.mediaType};base64,${file.data.toString("base64")}` });
180
+ }
181
+ out.unshift({ ...message, parts });
182
+ }
183
+ return out;
184
+ }
185
+ /** Whose chats these are. The routes need the AI permission, which only a signed-in person can hold. */
186
+ const ownerOf = (context) => (context.principal.kind === "user" ? context.principal.user.id : null);
187
+ const page = z.object({ collection: z.string().max(63).optional(), recordId: z.string().max(20).optional() }).optional();
188
+ /**
189
+ * An assistant in the dashboard on the Vercel AI SDK, with any model provider an adapter
190
+ * package brings. It chats, fills a record's form from a prompt, writes and improves single
191
+ * fields, and does anything an agent tool can, from core or any plugin, as the signed-in
192
+ * person, asking before every write. See docs/plugins/ai.md.
193
+ */
194
+ export function ai(options) {
195
+ const value = optionsSchema.parse({ provider: options.providers?.[0]?.id, ...Object.fromEntries(Object.entries(options).filter(([, option]) => option !== undefined)) });
196
+ const providers = options.providers;
197
+ const byId = new Map(providers.map((provider) => [provider.id, provider]));
198
+ const fields = [...sharedSettings(value, providers), ...providerSettings(providers)];
199
+ /**
200
+ * The model to use, or the response explaining why there isn't one. `picked` is the model,
201
+ * and `pickedProvider` the provider, the person chose in the chat, used only while the
202
+ * settings let people choose. Another provider than the site's starts on its own default model.
203
+ */
204
+ async function modelFor(context, kind, picked, pickedProvider) {
205
+ const settings = (await context.settings.get());
206
+ const own = byId.get(settings.provider);
207
+ if (!own || !own.ready(settings))
208
+ return { refused: refuse(503, "AI_NOT_SET_UP", `AI isn't set up yet. Add the ${own?.label ?? "provider"} settings under AI → Settings.`) };
209
+ const choosing = settings.chooseModel !== false;
210
+ const other = choosing && pickedProvider && pickedProvider !== own.id ? byId.get(pickedProvider) : undefined;
211
+ if (choosing && pickedProvider && pickedProvider !== own.id && (!other || !other.ready(settings)))
212
+ return { refused: refuse(400, "AI_PROVIDER_NOT_SET_UP", `${other?.label ?? "That provider"} isn't set up. Choose another provider in the chat.`) };
213
+ const provider = other ?? own;
214
+ const chosen = choosing && picked ? picked : "";
215
+ const id = chosen || (other ? other.defaultModel : (kind === "fast" && settings.fastModel.trim()) || settings.model.trim() || own.defaultModel);
216
+ if (!id)
217
+ return { refused: refuse(503, "AI_NOT_SET_UP", "Choose a model under AI → Settings.") };
218
+ return { model: provider.model(settings, id), settings, provider, modelId: id };
219
+ }
220
+ /** The model that draws in the chat, or null when the settings choose none or its provider isn't set up. */
221
+ const drawerFor = (settings) => {
222
+ const modelId = (settings.imageModel ?? "").trim();
223
+ const provider = byId.get(providerOf(settings.imageProvider, settings.provider));
224
+ return modelId && provider && provider.ready(settings) ? { provider, modelId } : null;
225
+ };
226
+ /** The thinking a chat asks for: the person's choice while they may choose, else the settings'. */
227
+ const reasoningFor = (settings, picked) => {
228
+ const reasoning = (settings.chooseModel !== false && picked) || settings.reasoning;
229
+ return reasoning && reasoning !== "provider-default" && REASONING.includes(reasoning) ? reasoning : undefined;
230
+ };
231
+ const describe = async (context, collection) => (await context.tools.call("describe_collection", { collection }));
232
+ return definePlugin({
233
+ name: "ai",
234
+ version: "0.1.0",
235
+ messages: mergeMessagesByLanguage(messages, ...providers.map((provider) => provider.messages), modelWords(providers)),
236
+ apiVersion: 1,
237
+ requires: { cms: "^0.1.0" },
238
+ admin: { server: "@tansy/ai/admin", client: "@tansy/ai/client" },
239
+ options: { schema: optionsSchema, value },
240
+ settings: { fields },
241
+ permissions: { "ext.ai": ["use", "workflows"] },
242
+ migrations: [{ id: "001-assistant-role", up: async ({ roles }) => { await roles.ensure(assistantRole); } }],
243
+ jobs: [workflowJob(providers)],
244
+ routes: [
245
+ ...workflowRoutes(providers),
246
+ defineRoute({
247
+ method: "GET",
248
+ path: "/status",
249
+ access: "permission",
250
+ permission: USE,
251
+ handler: async (context) => {
252
+ const chosen = await modelFor(context, "main");
253
+ if ("refused" in chosen)
254
+ return { ready: false };
255
+ const { settings, provider } = chosen;
256
+ return {
257
+ ready: true,
258
+ provider: provider.id,
259
+ providerLabel: provider.label,
260
+ model: chosen.modelId,
261
+ reasoning: REASONING.includes(settings.reasoning) ? settings.reasoning : "provider-default",
262
+ providerIcon: provider.icon,
263
+ chooseModel: settings.chooseModel !== false,
264
+ listsModels: Boolean(provider.models),
265
+ role: roleFor(settings),
266
+ // The providers set up, for the person to switch between while they may choose the model.
267
+ providers: settings.chooseModel === false ? [] : providers.filter((item) => item.ready(settings)).map((item) => ({
268
+ id: item.id,
269
+ label: item.label,
270
+ icon: item.icon,
271
+ model: item.id === provider.id ? chosen.modelId : item.defaultModel,
272
+ listsModels: Boolean(item.models),
273
+ })),
274
+ // Only someone who may give people roles may give the AI one.
275
+ chooseRole: settings.chooseRole !== false && givesRoles(context.principal),
276
+ };
277
+ },
278
+ }),
279
+ defineRoute({
280
+ method: "POST",
281
+ path: "/chat",
282
+ access: "permission",
283
+ permission: USE,
284
+ audit: "ai.chat",
285
+ rateLimit: { window: 60, max: 30 },
286
+ body: z.object({ messages: z.array(z.unknown()).min(1).max(100), page, chatId: chatId.optional(), provider: z.string().regex(PROVIDER_ID).optional(), model: z.string().regex(MODEL_ID).optional(), reasoning: z.enum(REASONING).optional(), role: z.string().regex(ROLE_NAME).optional() }),
287
+ handler: async (context) => {
288
+ const chosen = await modelFor(context, "main", context.body.model, context.body.provider);
289
+ if ("refused" in chosen)
290
+ return chosen.refused;
291
+ const { model, settings } = chosen;
292
+ if (context.body.role && !givesRoles(context.principal))
293
+ return refuse(403, "FORBIDDEN", "Only someone who may give people roles may choose the AI's role.");
294
+ // The AI gets what both the person and its role may do, so a role can only take access away.
295
+ const role = roleFor(settings, context.body.role);
296
+ let scoped;
297
+ try {
298
+ scoped = await context.tools.withRole(role);
299
+ }
300
+ catch {
301
+ return refuse(400, "AI_ROLE_MISSING", `The AI's role "${role}" doesn't exist any more. Choose another under AI → Settings or in the chat.`);
302
+ }
303
+ const available = await scoped.list();
304
+ const writes = new Set(available.filter((tool) => tool.write).map((tool) => tool.name));
305
+ const tools = Object.fromEntries(available.map((tool) => [tool.name, dynamicTool({
306
+ description: tool.description,
307
+ inputSchema: jsonSchema(tool.inputSchema),
308
+ execute: async (input) => {
309
+ try {
310
+ return forModel(await scoped.call(tool.name, input));
311
+ }
312
+ catch (error) {
313
+ return toolFailure(error);
314
+ }
315
+ },
316
+ })]));
317
+ const userId = ownerOf(context);
318
+ const files = attachmentStore(context.store);
319
+ const drawer = drawerFor(settings);
320
+ if (drawer && userId && !tools.generate_image) {
321
+ tools.generate_image = dynamicTool({
322
+ description: "Draws a picture from a description and shows it to the person in the chat. Describe the subject, style, colours and composition. Use it only when the person asks for a picture.",
323
+ inputSchema: jsonSchema({ type: "object", properties: { prompt: { type: "string", minLength: 1, maxLength: 4000, description: "What to draw, in detail." }, aspectRatio: { type: "string", enum: [...ASPECT_RATIOS], description: "The picture's shape. 1:1 when unsure." } }, required: ["prompt"], additionalProperties: false }),
324
+ execute: async (input) => {
325
+ const { prompt, aspectRatio } = input;
326
+ try {
327
+ const picture = await drawPicture({ ...drawer, settings, prompt: String(prompt).slice(0, 4000), aspectRatio: ASPECT_RATIOS.includes(aspectRatio) ? aspectRatio : undefined, abortSignal: AbortSignal.any([context.request.signal, AbortSignal.timeout(5 * 60_000)]) });
328
+ const mediaType = ATTACHMENT_TYPES[picture.mediaType] === "image" ? picture.mediaType : "image/png";
329
+ const name = `${cleanName(String(prompt).toLowerCase().split(/\s+/).slice(0, 6).join("-")).replace(/ /g, "-")}.${mediaType.split("/")[1].replace("jpeg", "jpg")}`;
330
+ const id = await files.put(userId, { data: picture.bytes, mediaType, name, drawn: true });
331
+ return { image: { url: apiPath(`/ext/ai/attachments/${id}`), mediaType, name }, model: drawer.modelId };
332
+ }
333
+ catch (error) {
334
+ if (error instanceof NoPicture)
335
+ return { error: { code: "AI_NO_PICTURE", message: error.message } };
336
+ console.error("[ai] drawing failed", error);
337
+ return { error: { code: "AI_IMAGE_FAILED", message: providerReason(error) } };
338
+ }
339
+ },
340
+ });
341
+ }
342
+ let messages;
343
+ try {
344
+ messages = await validateUIMessages({ messages: context.body.messages, tools: tools });
345
+ }
346
+ catch {
347
+ return refuse(400, "BAD_REQUEST", "The conversation couldn't be read. Start a new one.");
348
+ }
349
+ const user = context.principal.kind === "anonymous" ? "the signed-in person" : context.principal.user.name || context.principal.user.email;
350
+ const reasoning = reasoningFor(settings, context.body.reasoning);
351
+ const attached = messages.some((message) => message.parts.some((part) => part.type === "file"));
352
+ if (attached && !userId)
353
+ return refuse(400, "BAD_ATTACHMENT", "Only a signed-in person can attach files.");
354
+ const forModelMessages = attached
355
+ ? await withFiles(messages, (id) => files.get(userId, id), await capabilitiesOf(chosen.provider, settings, chosen.modelId), chosen.modelId)
356
+ : messages;
357
+ if (forModelMessages instanceof Response)
358
+ return forModelMessages;
359
+ context.auditTarget("ai", chosen.provider.id, { model: chosen.modelId, role, ...(reasoning ? { reasoning } : {}), ...(attached ? { files: true } : {}) });
360
+ const saveTo = userId && context.body.chatId ? context.body.chatId : null;
361
+ try {
362
+ const result = streamText({
363
+ model,
364
+ system: systemPrompt({ userName: user, role, instructions: settings.instructions, page: context.body.page, draws: Boolean(tools.generate_image) }),
365
+ messages: await convertToModelMessages(forModelMessages, { tools, ignoreIncompleteToolCalls: true }),
366
+ tools,
367
+ // Every write waits for the person, so text the model read can't make it change anything on its own.
368
+ toolApproval: ({ toolCall }) => (writes.has(toolCall.toolName) ? "user-approval" : undefined),
369
+ experimental_toolApprovalSecret: approvalSecret(),
370
+ stopWhen: isStepCount(settings.maxSteps),
371
+ maxOutputTokens: settings.maxOutputTokens,
372
+ ...(reasoning ? { reasoning } : {}),
373
+ abortSignal: context.request.signal,
374
+ });
375
+ return createUIMessageStreamResponse({
376
+ stream: toUIMessageStream({
377
+ stream: result.stream,
378
+ originalMessages: messages,
379
+ sendReasoning: true,
380
+ // Which model answered, for the answer's footer.
381
+ messageMetadata: ({ part }) => (part.type === "start" ? { model: chosen.modelId, provider: chosen.provider.id } : undefined),
382
+ generateMessageId: generateId,
383
+ // Saved when the answer ends, however it ends, so the chat is there after a reload.
384
+ onEnd: async ({ messages: finished }) => {
385
+ if (!saveTo || !userId)
386
+ return;
387
+ try {
388
+ await chatStore(context.store).save(userId, saveTo, finished);
389
+ }
390
+ catch (error) {
391
+ console.error("[ai] could not save the chat", error);
392
+ }
393
+ },
394
+ onError: (error) => {
395
+ console.error("[ai] the provider failed", error);
396
+ return providerReason(error);
397
+ },
398
+ }),
399
+ headers: { "cache-control": "no-store" },
400
+ });
401
+ }
402
+ catch (error) {
403
+ return providerFailed(error);
404
+ }
405
+ },
406
+ }),
407
+ defineRoute({
408
+ method: "GET",
409
+ path: "/models",
410
+ access: "permission",
411
+ permission: SETTINGS,
412
+ query: z.object({ provider: z.string().max(20).optional() }),
413
+ rateLimit: { window: 60, max: 30 },
414
+ handler: async (context) => {
415
+ const settings = (await context.settings.get());
416
+ const provider = byId.get(context.query.provider || settings.provider);
417
+ if (!provider)
418
+ return refuse(404, "NOT_FOUND", "There's no such provider.");
419
+ if (!provider.models)
420
+ return { options: [] };
421
+ if (!provider.ready(settings))
422
+ return refuse(400, "AI_NOT_SET_UP", `Save the ${provider.label} settings first, then reload the choices.`);
423
+ try {
424
+ return { options: chatModels(await provider.models(settings)).slice(0, 2000).map(({ value, label }) => ({ value, label })) };
425
+ }
426
+ catch (error) {
427
+ if (error instanceof ModelListError)
428
+ return refuse(502, "AI_MODELS_FAILED", error.message);
429
+ console.error("[ai] could not list models", error);
430
+ return refuse(502, "AI_MODELS_FAILED", "The provider's models couldn't be listed.");
431
+ }
432
+ },
433
+ }),
434
+ defineRoute({
435
+ method: "GET",
436
+ path: "/chat/models",
437
+ access: "permission",
438
+ permission: USE,
439
+ query: z.object({ provider: z.string().regex(PROVIDER_ID).optional() }),
440
+ rateLimit: { window: 60, max: 20 },
441
+ handler: async (context) => {
442
+ // The models the person may choose from in the chat, from the provider they chose. Only ids and names: never the key.
443
+ const settings = (await context.settings.get());
444
+ const provider = byId.get(context.query.provider || settings.provider);
445
+ if (!provider || !provider.ready(settings) || settings.chooseModel === false || !provider.models)
446
+ return { options: [] };
447
+ try {
448
+ return { options: chatModels(await listModels(provider, settings)).map(({ value, label }) => ({ value, label })) };
449
+ }
450
+ catch (error) {
451
+ if (error instanceof ModelListError)
452
+ return refuse(502, "AI_MODELS_FAILED", error.message);
453
+ console.error("[ai] could not list models", error);
454
+ return refuse(502, "AI_MODELS_FAILED", "The provider's models couldn't be listed.");
455
+ }
456
+ },
457
+ }),
458
+ defineRoute({
459
+ method: "GET",
460
+ path: "/chat/capabilities",
461
+ access: "permission",
462
+ permission: USE,
463
+ query: z.object({ model: z.string().regex(MODEL_ID).optional(), provider: z.string().regex(PROVIDER_ID).optional() }),
464
+ rateLimit: { window: 60, max: 60 },
465
+ handler: async (context) => {
466
+ // What the chat's model reads, for the composer to offer only files it can send.
467
+ const chosen = await modelFor(context, "main", context.query.model, context.query.provider);
468
+ if ("refused" in chosen)
469
+ return chosen.refused;
470
+ const capabilities = await capabilitiesOf(chosen.provider, chosen.settings, chosen.modelId);
471
+ return { model: chosen.modelId, accept: acceptedTypes(capabilities), reported: Boolean(capabilities.reported), maxBytes: MAX_ATTACHMENT_BYTES, draws: Boolean(drawerFor(chosen.settings)) };
472
+ },
473
+ }),
474
+ defineRoute({
475
+ method: "GET",
476
+ path: "/image-models",
477
+ access: "permission",
478
+ permission: SETTINGS,
479
+ query: z.object({ provider: z.string().max(20).optional(), imageProvider: z.string().max(20).optional() }),
480
+ rateLimit: { window: 60, max: 30 },
481
+ handler: async (context) => {
482
+ // The models that draw, for the picture setting to offer.
483
+ const settings = (await context.settings.get());
484
+ const provider = byId.get(context.query.imageProvider || context.query.provider ? providerOf(context.query.imageProvider, context.query.provider || settings.provider) : providerOf(settings.imageProvider, settings.provider));
485
+ if (!provider)
486
+ return refuse(404, "NOT_FOUND", "There's no such provider.");
487
+ if (!provider.models)
488
+ return { options: [] };
489
+ if (!provider.ready(settings))
490
+ return refuse(400, "AI_NOT_SET_UP", `Save the ${provider.label} settings first, then reload the choices.`);
491
+ try {
492
+ return { options: imageModels(await provider.models(settings)).slice(0, 2000).map(({ value, label }) => ({ value, label })) };
493
+ }
494
+ catch (error) {
495
+ if (error instanceof ModelListError)
496
+ return refuse(502, "AI_MODELS_FAILED", error.message);
497
+ console.error("[ai] could not list models", error);
498
+ return refuse(502, "AI_MODELS_FAILED", "The provider's models couldn't be listed.");
499
+ }
500
+ },
501
+ }),
502
+ defineRoute({
503
+ method: "POST",
504
+ path: "/attachments",
505
+ access: "permission",
506
+ permission: USE,
507
+ audit: "ai.attachment.upload",
508
+ rateLimit: { window: 60, max: 30 },
509
+ query: z.object({ name: z.string().max(255).default("file") }),
510
+ handler: async (context) => {
511
+ // A file for the chat, kept for its owner alone. The body is the file itself.
512
+ const userId = ownerOf(context);
513
+ if (!userId)
514
+ return refuse(403, "FORBIDDEN", "Only a signed-in person can attach files.");
515
+ const mediaType = attachmentType(context.request.headers.get("content-type") ?? "", context.query.name);
516
+ if (!mediaType)
517
+ return refuse(415, "UNSUPPORTED_FILE", "That kind of file can't be attached. Attach a picture, a PDF, a text file, sound or video.");
518
+ const data = await readLimited(context.request, MAX_ATTACHMENT_BYTES);
519
+ if (!data)
520
+ return refuse(413, "FILE_TOO_LARGE", `Attach files of up to ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB.`);
521
+ if (!data.byteLength)
522
+ return refuse(400, "EMPTY_FILE", "The file is empty.");
523
+ const name = cleanName(context.query.name);
524
+ const id = await attachmentStore(context.store).put(userId, { data, mediaType, name });
525
+ context.auditTarget("ai-attachment", id, { mediaType, bytes: data.byteLength });
526
+ return { id, url: apiPath(`/ext/ai/attachments/${id}`), mediaType, name, bytes: data.byteLength };
527
+ },
528
+ }),
529
+ defineRoute({
530
+ method: "GET",
531
+ path: "/attachments/:id",
532
+ access: "permission",
533
+ permission: USE,
534
+ handler: async (context) => {
535
+ const userId = ownerOf(context);
536
+ const file = userId && ATTACHMENT_ID.test(context.params.id) ? await attachmentStore(context.store).get(userId, context.params.id) : null;
537
+ if (!file)
538
+ return refuse(404, "NOT_FOUND", "There's no such file.");
539
+ // Only the types it was let in as, never anything a browser would run, and shown inline only when it is a picture, sound or video.
540
+ const kind = ATTACHMENT_TYPES[file.mediaType];
541
+ const type = kind ? file.mediaType : "application/octet-stream";
542
+ const inline = kind === "image" || kind === "audio" || kind === "video";
543
+ return new Response(new Uint8Array(file.data), { headers: {
544
+ "content-type": type,
545
+ "content-disposition": `${inline ? "inline" : "attachment"}; filename*=UTF-8''${encodeURIComponent(file.name)}`,
546
+ "cache-control": "private, max-age=86400",
547
+ "x-content-type-options": "nosniff",
548
+ "content-security-policy": "default-src 'none'; sandbox",
549
+ } });
550
+ },
551
+ }),
552
+ defineRoute({
553
+ method: "DELETE",
554
+ path: "/attachments/:id",
555
+ access: "permission",
556
+ permission: USE,
557
+ audit: "ai.attachment.delete",
558
+ handler: async (context) => {
559
+ const userId = ownerOf(context);
560
+ if (!userId || !ATTACHMENT_ID.test(context.params.id))
561
+ return refuse(404, "NOT_FOUND", "There's no such file.");
562
+ context.auditTarget("ai-attachment", context.params.id);
563
+ await attachmentStore(context.store).remove(userId, context.params.id);
564
+ return { deleted: true };
565
+ },
566
+ }),
567
+ defineRoute({
568
+ method: "GET",
569
+ path: "/roles",
570
+ access: "permission",
571
+ permission: USE,
572
+ handler: async (context) => {
573
+ // For whoever may choose the AI's role: in the chat, or under AI → Settings.
574
+ if (!givesRoles(context.principal) && !context.principal.permissions.has(SETTINGS))
575
+ return refuse(403, "FORBIDDEN", "Only someone who may give people roles may choose the AI's role.");
576
+ // Names and labels only. Choosing one can only narrow what the AI does for the person.
577
+ const roles = await context.tools.roles();
578
+ return { options: roles.map((role) => ({ value: role.name, label: role.label, ...(role.description ? { description: role.description } : {}) })) };
579
+ },
580
+ }),
581
+ defineRoute({
582
+ method: "GET",
583
+ path: "/chats",
584
+ access: "permission",
585
+ permission: USE,
586
+ handler: async (context) => {
587
+ const userId = ownerOf(context);
588
+ return { chats: userId ? await chatStore(context.store).list(userId) : [] };
589
+ },
590
+ }),
591
+ defineRoute({
592
+ method: "GET",
593
+ path: "/chats/:id",
594
+ access: "permission",
595
+ permission: USE,
596
+ handler: async (context) => {
597
+ const userId = ownerOf(context);
598
+ const chat = userId && CHAT_ID.test(context.params.id) ? await chatStore(context.store).get(userId, context.params.id) : null;
599
+ return chat ?? refuse(404, "NOT_FOUND", "There's no such chat.");
600
+ },
601
+ }),
602
+ defineRoute({
603
+ method: "DELETE",
604
+ path: "/chats/:id",
605
+ access: "permission",
606
+ permission: USE,
607
+ audit: "ai.chat.delete",
608
+ handler: async (context) => {
609
+ const userId = ownerOf(context);
610
+ if (!userId || !CHAT_ID.test(context.params.id))
611
+ return refuse(404, "NOT_FOUND", "There's no such chat.");
612
+ context.auditTarget("ai-chat", context.params.id);
613
+ await chatStore(context.store).remove(userId, context.params.id);
614
+ return { deleted: true };
615
+ },
616
+ }),
617
+ defineRoute({
618
+ method: "POST",
619
+ path: "/fill",
620
+ access: "permission",
621
+ permission: USE,
622
+ audit: "ai.fill",
623
+ rateLimit: { window: 60, max: 20 },
624
+ body: z.object({ collection: z.string().min(1).max(63), prompt: z.string().min(1).max(4000), values: z.record(z.string(), z.unknown()).default({}) }),
625
+ handler: async (context) => {
626
+ const chosen = await modelFor(context, "main");
627
+ if ("refused" in chosen)
628
+ return chosen.refused;
629
+ const collection = await describe(context, context.body.collection);
630
+ const schema = fillSchema(collection.fields);
631
+ if (!Object.keys(schema.properties).length)
632
+ return refuse(400, "NOTHING_TO_FILL", "This collection has no fields AI can fill.");
633
+ const current = Object.fromEntries(Object.entries(context.body.values).filter(([name]) => name in schema.properties).map(([name, item]) => [name, textOf(item) || item]));
634
+ context.auditTarget("collection", collection.slug, { model: chosen.modelId });
635
+ try {
636
+ const { output } = await generateText({
637
+ model: chosen.model,
638
+ system: [
639
+ `You fill in a record in the "${collection.name}" collection of a website's CMS. Give a value for each field the request lets you fill well, and leave out fields you'd have to guess. Write rich text as Markdown. Don't invent facts about real people, prices or dates.`,
640
+ chosen.settings.instructions.trim() ? `The site's own guidance:\n${chosen.settings.instructions.trim()}` : "",
641
+ jsonInstructions(schema),
642
+ ].filter(Boolean).join("\n\n"),
643
+ prompt: `Request: ${context.body.prompt}\n\nCurrent values, which the request may ask you to keep or change:\n${JSON.stringify(current).slice(0, 20_000)}`,
644
+ output: Output.object({ schema: jsonSchema(schema) }),
645
+ maxOutputTokens: chosen.settings.maxOutputTokens,
646
+ abortSignal: context.request.signal,
647
+ });
648
+ return { values: fillValues(collection.fields, output) };
649
+ }
650
+ catch (error) {
651
+ return providerFailed(error);
652
+ }
653
+ },
654
+ }),
655
+ defineRoute({
656
+ method: "POST",
657
+ path: "/write",
658
+ access: "permission",
659
+ permission: USE,
660
+ audit: "ai.write",
661
+ rateLimit: { window: 60, max: 40 },
662
+ body: z.object({
663
+ collection: z.string().min(1).max(63),
664
+ field: z.string().min(1).max(63),
665
+ action: z.enum(Object.keys(WRITE_ACTIONS)),
666
+ instruction: z.string().max(2000).optional(),
667
+ value: z.unknown().optional(),
668
+ values: z.record(z.string(), z.unknown()).default({}),
669
+ }),
670
+ handler: async (context) => {
671
+ const chosen = await modelFor(context, "fast");
672
+ if ("refused" in chosen)
673
+ return chosen.refused;
674
+ const collection = await describe(context, context.body.collection);
675
+ const field = collection.fields.find((item) => item.name === context.body.field);
676
+ if (!field || (field.type !== "rich_text" && field.schema?.type !== "string"))
677
+ return refuse(400, "NOT_WRITABLE", "AI can only write text fields.");
678
+ const value = textOf(context.body.value);
679
+ if (context.body.action !== "write" && !value.trim())
680
+ return refuse(400, "EMPTY_FIELD", "There's no text to work on yet. Choose Write instead.");
681
+ const record = Object.fromEntries(Object.entries(context.body.values).map(([name, item]) => [name, textOf(item)]));
682
+ context.auditTarget("collection", collection.slug, { field: field.name, action: context.body.action, model: chosen.modelId });
683
+ try {
684
+ const { text } = await generateText({
685
+ model: chosen.model,
686
+ system: chosen.settings.instructions.trim() ? `The site's own guidance:\n${chosen.settings.instructions.trim()}` : undefined,
687
+ prompt: writePrompt({ action: context.body.action, field, value, instruction: context.body.instruction, record, collection: collection.name }),
688
+ maxOutputTokens: chosen.settings.maxOutputTokens,
689
+ abortSignal: context.request.signal,
690
+ });
691
+ const written = text.trim().replace(/^```(?:markdown|md)?\n([\s\S]*)\n```$/, "$1");
692
+ return { value: field.type === "rich_text" ? fillValues([{ ...field, readonly: false }], { [field.name]: written })[field.name] ?? null : written };
693
+ }
694
+ catch (error) {
695
+ return providerFailed(error);
696
+ }
697
+ },
698
+ }),
699
+ ],
700
+ });
701
+ }