@b2y/ai-service 0.0.0-stage → 1.0.1

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.
@@ -0,0 +1,475 @@
1
+ import { z } from "zod";
2
+ import { dataClassificationSchema } from "../core/Context.js";
3
+ import { AiServiceError, createCancelledError, ErrorCodes, summarizeZodError, systemErrorCode } from "../core/Errors.js";
4
+ import { createDeadline } from "../core/Deadline.js";
5
+ import { APPROVED_PROVIDER_HOSTS, DEFAULT_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES } from "../constants/ProviderConstants.js";
6
+
7
+ // Types only: the contract every model backend implements (documented for editors via JSDoc).
8
+
9
+ /**
10
+ * How the provider is asked to constrain output. Support differs between servers and versions (vLLM and others), so this is a per-deployment setting confirmed by integration tests, never assumed. Output is always validated with Zod afterwards regardless of the mode.
11
+ * @typedef {"json_schema" | "json_object" | "none"} StructuredOutputMode
12
+ */
13
+
14
+ /**
15
+ * @typedef {Object} ProviderInfo
16
+ * @property {string} id
17
+ * @property {string} model
18
+ * @property {string | null} modelRevision
19
+ * @property {readonly DataClassification[]} allowedClassifications
20
+ * @property {StructuredOutputMode} structuredOutput
21
+ */
22
+
23
+ /**
24
+ * Only system and user roles exist: there is no tool or function-call role.
25
+ * @typedef {Object} ChatMessage
26
+ * @property {"system" | "user"} role
27
+ * @property {string} content
28
+ */
29
+
30
+ /**
31
+ * @typedef {Object} GenerationSettings
32
+ * @property {number} temperature
33
+ * @property {number} maxTokens
34
+ * @property {number} [topP]
35
+ * @property {number} [seed]
36
+ */
37
+
38
+ /**
39
+ * @typedef {Object} JsonSchemaFormat
40
+ * @property {string} name
41
+ * @property {object} schema
42
+ */
43
+
44
+ /**
45
+ * Deliberately has no `tools` field: the model cannot be offered tools.
46
+ * @typedef {Object} ChatRequest
47
+ * @property {readonly ChatMessage[]} messages
48
+ * @property {GenerationSettings} generation
49
+ * @property {JsonSchemaFormat} [jsonSchema]
50
+ */
51
+
52
+ /**
53
+ * @typedef {"stop" | "length" | "other"} FinishReason
54
+ */
55
+
56
+ /**
57
+ * @typedef {Object} ChatResult
58
+ * @property {string} content
59
+ * @property {FinishReason} finishReason
60
+ * @property {TokenUsage} usage
61
+ * @property {string} model
62
+ * @property {number} latencyMs
63
+ */
64
+
65
+ /**
66
+ * @typedef {Object} CallOptions
67
+ * @property {AbortSignal} [signal]
68
+ */
69
+
70
+ /**
71
+ * Contract every model backend implements. Implementations must throw AiServiceError only, and must never put prompt text, model output or raw response bodies into errors.
72
+ * @typedef {Object} ChatProvider
73
+ * @property {ProviderInfo} info
74
+ * @property {(request: ChatRequest, options?: CallOptions) => Promise<ChatResult>} complete
75
+ * @property {(options?: CallOptions) => Promise<void>} healthCheck
76
+ */
77
+
78
+ export {};
79
+
80
+ /** The provider base URL: HTTPS on the default port to an approved host, without credentials or a query. */
81
+ function providerBaseUrl(baseUrl) {
82
+ let url;
83
+ try {
84
+ url = new URL(baseUrl);
85
+ } catch {
86
+ throw configError("Provider baseUrl is not a valid URL", "invalid_url");
87
+ }
88
+ if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
89
+ throw configError("Provider baseUrl must be plain HTTPS", "insecure_url");
90
+ }
91
+ if (!APPROVED_PROVIDER_HOSTS.includes(url.hostname.toLowerCase())) throw configError("Provider host is not approved", "host_not_approved");
92
+ if (!url.pathname.endsWith("/")) url.pathname = `${url.pathname}/`;
93
+ return url;
94
+ }
95
+
96
+ function configError(message, reason) {
97
+ return new AiServiceError(ErrorCodes.CONFIG_INVALID, message, { details: { reason } });
98
+ }
99
+
100
+ /**
101
+ * @typedef {Object} ProviderDependencies
102
+ * @property {typeof globalThis.fetch} [fetch] - Injected for tests. Defaults to the global fetch, resolved at call time.
103
+ * @property {() => number} [now]
104
+ */
105
+
106
+ /** Network failures worth retrying: the server was briefly unreachable or the connection dropped. */
107
+ const TRANSIENT_NETWORK_CODES = new Set([
108
+ "ECONNREFUSED",
109
+ "ECONNRESET",
110
+ "ECONNABORTED",
111
+ "ETIMEDOUT",
112
+ "EPIPE",
113
+ "EAI_AGAIN",
114
+ "EHOSTUNREACH",
115
+ "ENETUNREACH",
116
+ "UND_ERR_SOCKET",
117
+ "UND_ERR_CLOSED",
118
+ "UND_ERR_CONNECT_TIMEOUT",
119
+ "UND_ERR_HEADERS_TIMEOUT",
120
+ "UND_ERR_BODY_TIMEOUT",
121
+ ]);
122
+
123
+ const providerConfigSchema = z.strictObject({
124
+ id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
125
+ baseUrl: z.string().min(1).max(2048),
126
+ model: z.string().min(1).max(200),
127
+ modelRevision: z.string().min(1).max(200).optional(),
128
+ // Visible ASCII only, so the key is a valid header value and can never
129
+ // surface in a header-validation error.
130
+ apiKey: z
131
+ .string()
132
+ .min(1)
133
+ .max(4096)
134
+ .regex(/^[\x21-\x7e]+$/),
135
+ timeoutMs: z.number().int().min(100).max(600_000),
136
+ allowedClassifications: z.array(dataClassificationSchema).min(1),
137
+ structuredOutput: z.enum(["json_schema", "json_object", "none"]),
138
+ maxRequestBytes: z.number().int().min(1024).max(5_000_000).default(DEFAULT_MAX_REQUEST_BYTES),
139
+ maxResponseBytes: z.number().int().min(1024).max(10_000_000).default(DEFAULT_MAX_RESPONSE_BYTES),
140
+ });
141
+
142
+ const completionResponseSchema = z.object({
143
+ model: z.string().optional(),
144
+ choices: z
145
+ .array(
146
+ z.object({
147
+ finish_reason: z.string().nullable().optional(),
148
+ message: z.object({
149
+ content: z.string().nullable().optional(),
150
+ tool_calls: z.array(z.unknown()).nullable().optional(),
151
+ }),
152
+ }),
153
+ )
154
+ .min(1),
155
+ usage: z
156
+ .object({
157
+ prompt_tokens: z.number().int().nonnegative().optional(),
158
+ completion_tokens: z.number().int().nonnegative().optional(),
159
+ total_tokens: z.number().int().nonnegative().optional(),
160
+ })
161
+ .nullable()
162
+ .optional(),
163
+ });
164
+
165
+ const modelListSchema = z.object({
166
+ data: z.array(z.object({ id: z.string() })),
167
+ });
168
+
169
+ /**
170
+ * The provider client for any OpenAI-compatible Chat Completions API (`POST {baseUrl}chat/completions`, `GET
171
+ * {baseUrl}models`), configured by AI_PROVIDER_CONFIG.
172
+ * @param {{ id: string, baseUrl: string, model: string, apiKey: string, timeoutMs: number, structuredOutput: StructuredOutputMode, allowedClassifications: DataClassification[], modelRevision?: string, maxRequestBytes?: number, maxResponseBytes?: number }} config
173
+ * @param {{ fetch?: typeof fetch, now?: () => number }} [dependencies]
174
+ * @returns {ChatProvider}
175
+ */
176
+ export function createProvider(config, dependencies = {}) {
177
+ const parsed = providerConfigSchema.safeParse(config);
178
+ if (!parsed.success) {
179
+ throw new AiServiceError(ErrorCodes.CONFIG_INVALID, "Provider configuration is invalid", {
180
+ details: summarizeZodError(parsed.error, providerConfigSchema),
181
+ });
182
+ }
183
+ const settings = parsed.data;
184
+ const baseUrl = providerBaseUrl(settings.baseUrl);
185
+ const completionsUrl = new URL("chat/completions", baseUrl);
186
+ const modelsUrl = new URL("models", baseUrl);
187
+ const now = dependencies.now ?? (() => performance.now());
188
+
189
+ const info = Object.freeze({
190
+ id: settings.id,
191
+ model: settings.model,
192
+ modelRevision: settings.modelRevision ?? null,
193
+ allowedClassifications: Object.freeze([...settings.allowedClassifications]),
194
+ structuredOutput: settings.structuredOutput,
195
+ });
196
+
197
+ function buildHeaders() {
198
+ return {
199
+ accept: "application/json",
200
+ "content-type": "application/json",
201
+ authorization: `Bearer ${settings.apiKey}`,
202
+ };
203
+ }
204
+
205
+ async function requestJson(url, body, callerSignal) {
206
+ if (body !== undefined && Buffer.byteLength(body, "utf8") > settings.maxRequestBytes) {
207
+ throw new AiServiceError(ErrorCodes.REQUEST_TOO_LARGE, "Provider request exceeds the configured size limit", {
208
+ details: { limitBytes: settings.maxRequestBytes },
209
+ });
210
+ }
211
+ if (callerSignal?.aborted === true) {
212
+ throw createCancelledError();
213
+ }
214
+
215
+ const deadline = createDeadline(settings.timeoutMs, callerSignal);
216
+ const { signal } = deadline;
217
+ const fetchImpl = dependencies.fetch ?? globalThis.fetch;
218
+
219
+ try {
220
+ const response = await fetchImpl(url, {
221
+ method: body === undefined ? "GET" : "POST",
222
+ headers: buildHeaders(),
223
+ ...(body === undefined ? {} : { body }),
224
+ signal,
225
+ // Redirects are refused: following one could send the request,
226
+ // including any Authorization header, to a host the policy never checked.
227
+ redirect: "error",
228
+ });
229
+
230
+ if (!response.ok) {
231
+ // A 400 may be the server refusing the model's own output under constrained decoding
232
+ // (for example Groq's json_validate_failed): read only its error code, from a bounded body.
233
+ const rejectedOutput = response.status === 400 && (await structuredOutputRejected(response));
234
+ if (!rejectedOutput) await discardBody(response);
235
+ if (rejectedOutput) {
236
+ throw new AiServiceError(ErrorCodes.PROVIDER_OUTPUT_REJECTED, "The provider rejected the model output as invalid structured output", {
237
+ details: { status: 400, reason: "structured_output_rejected" },
238
+ });
239
+ }
240
+ throw httpError(response.status, response.headers);
241
+ }
242
+ const contentType = response.headers.get("content-type") ?? "";
243
+ if (!contentType.toLowerCase().startsWith("application/json")) {
244
+ await discardBody(response);
245
+ throw invalidResponse("content_type");
246
+ }
247
+
248
+ const text = await readLimitedText(response, settings.maxResponseBytes);
249
+ try {
250
+ return JSON.parse(text);
251
+ } catch {
252
+ throw invalidResponse("not_json");
253
+ }
254
+ } catch (error) {
255
+ if (error instanceof AiServiceError) {
256
+ throw error;
257
+ }
258
+ if (callerSignal?.aborted === true) {
259
+ throw createCancelledError();
260
+ }
261
+ if (deadline.expired()) {
262
+ throw new AiServiceError(ErrorCodes.PROVIDER_TIMEOUT, "Provider request timed out", {
263
+ retryable: true,
264
+ details: { timeoutMs: settings.timeoutMs },
265
+ });
266
+ }
267
+ throw networkError(error);
268
+ } finally {
269
+ deadline.dispose();
270
+ }
271
+ }
272
+
273
+ async function complete(request, options = {}) {
274
+ const body = {
275
+ model: settings.model,
276
+ messages: request.messages.map((message) => ({ role: message.role, content: message.content })),
277
+ temperature: request.generation.temperature,
278
+ max_tokens: request.generation.maxTokens,
279
+ stream: false,
280
+ ...(request.generation.topP === undefined ? {} : { top_p: request.generation.topP }),
281
+ ...(request.generation.seed === undefined ? {} : { seed: request.generation.seed }),
282
+ };
283
+ if (request.jsonSchema !== undefined) {
284
+ if (settings.structuredOutput === "json_schema") {
285
+ body.response_format = {
286
+ type: "json_schema",
287
+ json_schema: { name: request.jsonSchema.name, schema: request.jsonSchema.schema, strict: true },
288
+ };
289
+ } else if (settings.structuredOutput === "json_object") {
290
+ body.response_format = { type: "json_object" };
291
+ }
292
+ }
293
+
294
+ const started = now();
295
+ const raw = await requestJson(completionsUrl, JSON.stringify(body), options.signal);
296
+ const parsed = completionResponseSchema.safeParse(raw);
297
+ if (!parsed.success) {
298
+ throw invalidResponse("shape");
299
+ }
300
+ const choice = parsed.data.choices[0];
301
+ if (choice === undefined) {
302
+ throw invalidResponse("shape");
303
+ }
304
+ if (choice.message.tool_calls != null && choice.message.tool_calls.length > 0) {
305
+ throw invalidResponse("tool_calls");
306
+ }
307
+ if (typeof choice.message.content !== "string") {
308
+ throw invalidResponse("missing_content");
309
+ }
310
+ if (parsed.data.model !== undefined && parsed.data.model !== settings.model) {
311
+ throw invalidResponse("model_mismatch");
312
+ }
313
+
314
+ return {
315
+ content: choice.message.content,
316
+ finishReason: mapFinishReason(choice.finish_reason),
317
+ usage: mapUsage(parsed.data.usage),
318
+ model: settings.model,
319
+ latencyMs: Math.max(0, now() - started),
320
+ };
321
+ }
322
+
323
+ async function healthCheck(options = {}) {
324
+ const raw = await requestJson(modelsUrl, undefined, options.signal);
325
+ const parsed = modelListSchema.safeParse(raw);
326
+ if (!parsed.success) {
327
+ throw invalidResponse("shape");
328
+ }
329
+ if (!parsed.data.data.some((entry) => entry.id === settings.model)) {
330
+ throw new AiServiceError(ErrorCodes.PROVIDER_UNAVAILABLE, "Configured model is not served by the provider", {
331
+ details: { reason: "model_not_served" },
332
+ });
333
+ }
334
+ }
335
+
336
+ return Object.freeze({ info, complete, healthCheck });
337
+ }
338
+
339
+ async function readLimitedText(response, limitBytes) {
340
+ const declaredLength = Number(response.headers.get("content-length") ?? Number.NaN);
341
+ if (Number.isFinite(declaredLength) && declaredLength > limitBytes) {
342
+ await discardBody(response);
343
+ throw responseTooLarge(limitBytes);
344
+ }
345
+ if (response.body === null) {
346
+ return "";
347
+ }
348
+
349
+ const reader = response.body.getReader();
350
+ const chunks = [];
351
+ let received = 0;
352
+ try {
353
+ for (;;) {
354
+ // The stream is typed `any` by the platform types; check each chunk instead of trusting it.
355
+ const result = await reader.read();
356
+ if (result.done) {
357
+ break;
358
+ }
359
+ const value = result.value;
360
+ if (!(value instanceof Uint8Array)) {
361
+ throw invalidResponse("body_chunk");
362
+ }
363
+ received += value.byteLength;
364
+ if (received > limitBytes) {
365
+ throw responseTooLarge(limitBytes);
366
+ }
367
+ chunks.push(value);
368
+ }
369
+ } catch (error) {
370
+ // Any failure while streaming abandons the body: release the connection.
371
+ await cancelReader(reader);
372
+ throw error;
373
+ }
374
+
375
+ try {
376
+ return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
377
+ } catch {
378
+ throw invalidResponse("invalid_utf8");
379
+ }
380
+ }
381
+
382
+ async function discardBody(response) {
383
+ try {
384
+ await response.body?.cancel();
385
+ } catch {
386
+ // The body is never read; failing to release it does not change the
387
+ // error already being reported to the caller.
388
+ }
389
+ }
390
+
391
+ async function cancelReader(reader) {
392
+ try {
393
+ await reader.cancel();
394
+ } catch {
395
+ // An already-errored stream rejects cancel(); the error being reported
396
+ // to the caller is the one that matters.
397
+ }
398
+ }
399
+
400
+ /** Classifies a fetch failure that was not a timeout or cancellation. */
401
+ function networkError(error) {
402
+ if (isRedirectRejection(error)) {
403
+ return new AiServiceError(ErrorCodes.PROVIDER_HTTP_ERROR, "Provider attempted a redirect, which is not allowed", {
404
+ details: { reason: "redirect" },
405
+ });
406
+ }
407
+ const code = systemErrorCode(error);
408
+ const transient = code !== undefined && TRANSIENT_NETWORK_CODES.has(code);
409
+ return new AiServiceError(ErrorCodes.PROVIDER_UNAVAILABLE, "Provider request failed", {
410
+ retryable: transient,
411
+ details: { reason: code ?? "request_failed" },
412
+ cause: error,
413
+ });
414
+ }
415
+
416
+ /** Node's fetch rejects with TypeError("fetch failed", { cause: Error("unexpected redirect") }) under redirect: "error". */
417
+ function isRedirectRejection(error) {
418
+ return error instanceof Error && error.cause instanceof Error && error.cause.message === "unexpected redirect";
419
+ }
420
+
421
+ /** Longest wait a provider's Retry-After may ask for (seconds); larger values are capped. */
422
+ const MAX_RETRY_AFTER_SECONDS = 300;
423
+
424
+ /** Error codes by which OpenAI-compatible servers report model output that failed their JSON schema. */
425
+ const OUTPUT_REJECTION_CODES = new Set(["json_validate_failed", "invalid_json_output"]);
426
+
427
+ async function structuredOutputRejected(response) {
428
+ try {
429
+ const body = JSON.parse(await readLimitedText(response, 64 * 1024));
430
+ return typeof body?.error?.code === "string" && OUTPUT_REJECTION_CODES.has(body.error.code);
431
+ } catch {
432
+ return false;
433
+ }
434
+ }
435
+
436
+ function httpError(status, headers) {
437
+ if (status === 429) {
438
+ // Rate limited: its own code, with the provider's Retry-After (seconds, bounded) when it sends one.
439
+ const raw = headers?.get?.("retry-after");
440
+ const header = typeof raw === "string" && /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : NaN;
441
+ const retryAfterSeconds = Number.isFinite(header) ? Math.min(MAX_RETRY_AFTER_SECONDS, Math.ceil(header)) : undefined;
442
+ return new AiServiceError(ErrorCodes.PROVIDER_RATE_LIMITED, "Provider rate limit reached (HTTP 429)", {
443
+ retryable: true,
444
+ details: { status, ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }) },
445
+ });
446
+ }
447
+ const retryable = status === 408 || status >= 500;
448
+ const code = status === 503 ? ErrorCodes.PROVIDER_UNAVAILABLE : ErrorCodes.PROVIDER_HTTP_ERROR;
449
+ return new AiServiceError(code, `Provider responded with HTTP ${String(status)}`, {
450
+ retryable,
451
+ details: { status },
452
+ });
453
+ }
454
+
455
+ function invalidResponse(reason) {
456
+ return new AiServiceError(ErrorCodes.PROVIDER_RESPONSE_INVALID, "Provider response is invalid", {
457
+ details: { reason },
458
+ });
459
+ }
460
+
461
+ function responseTooLarge(limitBytes) {
462
+ return new AiServiceError(ErrorCodes.PROVIDER_RESPONSE_INVALID, "Provider response exceeds the configured size limit", {
463
+ details: { reason: "too_large", limitBytes },
464
+ });
465
+ }
466
+
467
+ const mapFinishReason = (value) => (value === "stop" || value === "length" ? value : "other");
468
+
469
+ function mapUsage(usage) {
470
+ const promptTokens = usage?.prompt_tokens ?? null;
471
+ const completionTokens = usage?.completion_tokens ?? null;
472
+ const reportedTotal = usage?.total_tokens ?? null;
473
+ const derivedTotal = promptTokens !== null && completionTokens !== null ? promptTokens + completionTokens : null;
474
+ return { promptTokens, completionTokens, totalTokens: reportedTotal ?? derivedTotal };
475
+ }
@@ -0,0 +1,152 @@
1
+ // Server-side building blocks every application uses the same way: the AI runtime (service and chat history),
2
+ // ready-made HTTP endpoints with one error policy, a rate limiter, and read-only SQL execution.
3
+ import { createDefaultAiService } from "../core/AiService.js";
4
+ import { aiUserMessage, AiServiceError, errorCategory, ErrorCategories, isRateLimited, rateLimitInfo } from "../core/Errors.js";
5
+ import { createConversationHistory, scheduleConversationCleanup } from "../conversations/ConversationHistory.js";
6
+ import { createFolderConversationStore } from "../conversations/FolderConversationStore.js";
7
+ import { STATEMENT_TIMEOUT_MS } from "../constants/AnalyticsConstants.js";
8
+ import { CONVERSATION_LIST_LIMIT } from "../constants/ConversationConstants.js";
9
+ import { AI_MESSAGES, HTTP_STATUS, RATE_LIMIT_DEFAULTS, RESPONSE_STATUS } from "../constants/ServerConstants.js";
10
+ export { AI_MESSAGES, RESPONSE_STATUS } from "../constants/ServerConstants.js";
11
+
12
+ const noop = () => {};
13
+ const quietLogger = Object.freeze({ info: noop, warn: noop, error: noop });
14
+
15
+ /**
16
+ * The AI service and server-side chat history for an application, from its configuration. Without an API key
17
+ * the assistant is off (ai is null); without a folder, chats are not kept.
18
+ * @param {{ apiKey?: string, tasks: readonly object[], conversationsDir?: string, retentionDays?: number, logger?: object }} options
19
+ */
20
+ export function createAiRuntime({ apiKey, tasks, conversationsDir, retentionDays, logger = quietLogger }) {
21
+ if (!apiKey) return Object.freeze({ ai: null, history: null });
22
+ const ai = createDefaultAiService({ apiKey, tasks });
23
+ let history = null;
24
+ if (conversationsDir) {
25
+ history = createConversationHistory({ store: createFolderConversationStore({ root: conversationsDir }), ...(retentionDays ? { retentionDays } : {}) });
26
+ scheduleConversationCleanup({ history, onError: (error) => logger.warn("AI conversation cleanup failed", { code: error?.code || error?.name }) });
27
+ }
28
+ return Object.freeze({ ai, history });
29
+ }
30
+
31
+ /**
32
+ * Fixed-window limits in memory (one server instance): per user and per tenant. Keys come from the trusted
33
+ * context, so a user cannot reset them.
34
+ * @param {{ perUser?: number, perUserWindowMs?: number, perTenant?: number, perTenantWindowMs?: number, now?: () => number }} options
35
+ */
36
+ export function createRateLimiter({ perUser = RATE_LIMIT_DEFAULTS.perUser, perUserWindowMs = RATE_LIMIT_DEFAULTS.perUserWindowMs, perTenant = RATE_LIMIT_DEFAULTS.perTenant, perTenantWindowMs = RATE_LIMIT_DEFAULTS.perTenantWindowMs, now = () => Date.now() } = {}) {
37
+ const windows = new Map();
38
+ const hit = (key, limit, windowMs) => {
39
+ const at = now();
40
+ const entry = windows.get(key);
41
+ if (!entry || at - entry.start >= windowMs) {
42
+ windows.set(key, { start: at, count: 1 });
43
+ return { ok: true };
44
+ }
45
+ if (entry.count >= limit) return { ok: false, retryAfterSeconds: Math.ceil((entry.start + windowMs - at) / 1000) };
46
+ entry.count += 1;
47
+ return { ok: true };
48
+ };
49
+ const sweep = globalThis.setInterval(() => {
50
+ const at = now();
51
+ for (const [key, entry] of windows) if (at - entry.start > Math.max(perUserWindowMs, perTenantWindowMs)) windows.delete(key);
52
+ }, perUserWindowMs);
53
+ sweep.unref?.();
54
+ return Object.freeze({
55
+ take({ tenantId, userId }) {
56
+ const user = hit(`u:${tenantId}:${userId}`, perUser, perUserWindowMs);
57
+ return user.ok ? hit(`t:${tenantId}`, perTenant, perTenantWindowMs) : user;
58
+ },
59
+ });
60
+ }
61
+
62
+ /**
63
+ * Runs one statement in a READ ONLY transaction with a statement timeout (Sequelize or any client with the
64
+ * same transaction/query API). Values only through bind ($1) or named replacements (:name).
65
+ * @returns {Promise<{ rows: object[], fields: string[] }>}
66
+ */
67
+ export async function runReadOnly(sequelize, sql, { bind, replacements, timeoutMs = STATEMENT_TIMEOUT_MS } = {}) {
68
+ return sequelize.transaction(async (transaction) => {
69
+ await sequelize.query("SET TRANSACTION READ ONLY", { transaction });
70
+ await sequelize.query(`SET LOCAL statement_timeout = ${Math.max(1, Math.trunc(timeoutMs))}`, { transaction });
71
+ const [rows, result] = await sequelize.query(sql, { ...(bind ? { bind } : {}), ...(replacements ? { replacements } : {}), transaction, type: "RAW" });
72
+ const fields = Array.isArray(result?.fields) ? result.fields.map((field) => String(field.name)) : rows.length > 0 ? Object.keys(rows[0]) : [];
73
+ return { rows, fields };
74
+ });
75
+ }
76
+
77
+ /** Quoted, schema-qualified table names for the given Sequelize models: { key: model }. */
78
+ export function quoteTables(sequelize, models) {
79
+ const generator = sequelize.getQueryInterface().queryGenerator;
80
+ return Object.freeze(Object.fromEntries(Object.entries(models).map(([key, model]) => [key, generator.quoteTable(model.getTableName())])));
81
+ }
82
+
83
+ /** Express-style JSON reply in the B2Y shape { status, message, data }. */
84
+ const defaultRespond = (res, httpStatus, ok, message, data) => res.status(httpStatus).json({ status: ok ? RESPONSE_STATUS.SUCCESS : RESPONSE_STATUS.FAILURE, ...(message ? { message } : {}), ...(data !== undefined ? { data } : {}) });
85
+
86
+ /**
87
+ * The assistant's HTTP endpoints with one error policy for every application. resolve(req) returns
88
+ * { assistant, context } for a signed-in user, or null when the assistant is not available (not configured,
89
+ * or not in the plan); it may throw accessDenied(...) or a package authorization error.
90
+ * @param {{ resolve: (req: object) => Promise<{ assistant: object, context: object } | null>, limiter?: object, logger?: object,
91
+ * messages?: Partial<typeof AI_MESSAGES>, respond?: Function }} options
92
+ */
93
+ export function createAssistantEndpoints({ resolve, limiter = createRateLimiter(), logger = quietLogger, messages = {}, respond = defaultRespond }) {
94
+ if (typeof resolve !== "function") throw new TypeError("createAssistantEndpoints needs resolve(req)");
95
+ const text = { ...AI_MESSAGES, ...messages };
96
+ const fail = (res, error, what) => {
97
+ if (isRateLimited(error)) {
98
+ logger.warn(`${what} rate limited`, rateLimitInfo(error));
99
+ return respond(res, HTTP_STATUS.TOO_MANY, false, aiUserMessage(error), { rateLimited: true });
100
+ }
101
+ const category = error instanceof AiServiceError ? errorCategory(error) : null;
102
+ if (category === ErrorCategories.NOT_AUTHORIZED) {
103
+ logger.warn(`${what} refused`, { code: error.code });
104
+ return respond(res, HTTP_STATUS.FORBIDDEN, false, text.NOT_PERMITTED);
105
+ }
106
+ if (category === ErrorCategories.INPUT_INVALID) return respond(res, HTTP_STATUS.BAD_REQUEST, false, text.MESSAGE_TOO_LONG);
107
+ logger.warn(`${what} failed`, { code: error?.code || error?.name });
108
+ return respond(res, HTTP_STATUS.BAD_GATEWAY, false, text.NOT_ANSWERED);
109
+ };
110
+ const handle = (what, run) => async (req, res) => {
111
+ try {
112
+ return await run(req, res);
113
+ } catch (error) {
114
+ return fail(res, error, what);
115
+ }
116
+ };
117
+ return Object.freeze({
118
+ /** Whether the assistant is available to this user (the UI shows it only then). */
119
+ status: handle("AI status", async (req, res) => respond(res, HTTP_STATUS.OK, true, null, { enabled: Boolean(await resolve(req).catch(() => null)) })),
120
+ chat: handle("AI chat", async (req, res) => {
121
+ const ready = await resolve(req);
122
+ if (!ready) return respond(res, HTTP_STATUS.NOT_FOUND, false, text.NOT_AVAILABLE);
123
+ const allowed = limiter.take({ tenantId: ready.context.tenantId, userId: ready.context.actor.userId });
124
+ if (!allowed.ok) return respond(res, HTTP_STATUS.TOO_MANY, false, text.TOO_MANY_MESSAGES, { rateLimited: true, retryAfterSeconds: allowed.retryAfterSeconds });
125
+ const reply = await ready.assistant.reply({ message: req.body?.message, context: ready.context, conversationId: req.body?.conversationId });
126
+ logger.info("AI chat answered", { route: reply.route, status: reply.status, blocks: reply.blocks.length });
127
+ return respond(res, HTTP_STATUS.OK, true, text.ANSWERED, { conversationId: reply.conversationId, status: reply.status, blocks: reply.blocks });
128
+ }),
129
+ listConversations: handle("AI conversations", async (req, res) => {
130
+ const ready = await resolve(req);
131
+ const conversations = ready?.assistant.hasHistory ? await ready.assistant.listConversations({ context: ready.context, limit: CONVERSATION_LIST_LIMIT }) : [];
132
+ return respond(res, HTTP_STATUS.OK, true, null, { conversations });
133
+ }),
134
+ getConversation: handle("AI conversation", async (req, res) => {
135
+ const ready = await resolve(req);
136
+ const messages = ready?.assistant.hasHistory ? await ready.assistant.loadConversation({ context: ready.context, conversationId: req.params?.id }) : [];
137
+ return respond(res, HTTP_STATUS.OK, true, null, { messages });
138
+ }),
139
+ });
140
+ }
141
+
142
+ /**
143
+ * Registers the endpoints on an Express router (after the application's own authentication middleware): GET
144
+ * {base}/status, POST {base}/chat, GET {base}/conversations, GET {base}/conversations/:id.
145
+ */
146
+ export function mountAssistantRoutes(router, endpoints, base = "/ai") {
147
+ router.get(`${base}/status`, endpoints.status);
148
+ router.post(`${base}/chat`, endpoints.chat);
149
+ router.get(`${base}/conversations`, endpoints.listConversations);
150
+ router.get(`${base}/conversations/:id`, endpoints.getConversation);
151
+ return router;
152
+ }