@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.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.
Files changed (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
@@ -0,0 +1,715 @@
1
+ "use strict";
2
+
3
+ // Zero-dependency client for the OpenAI embeddings API and compatible servers
4
+ // (docs/plan-1.0.md R-8a): POST {baseUrl}/v1/embeddings over the global fetch
5
+ // of Node 22+. Every setting arrives through the options object from trusted
6
+ // project configuration; nothing here reads tool arguments. The API key is read
7
+ // once from the named environment variable and lives only in this closure.
8
+ // No server-controlled string is ever retained: an HTTP error carries a fixed
9
+ // message with the status, and its details hold the status plus a server code
10
+ // mapped onto a fixed enumeration (B-6, S-2). Filtering cannot promise
11
+ // secrecy; not retaining can.
12
+
13
+ const { EmbedderError } = require("./interface");
14
+ const { version: PACKAGE_VERSION } = require("../../package.json");
15
+
16
+ // Published limits of the OpenAI embeddings endpoint; compatible servers are
17
+ // usually looser, never stricter in a way the configuration cannot express.
18
+ // charsPerToken (4) is the reporting estimate; request budgets and the
19
+ // default truncation use conservativeCharsPerToken (3), because
20
+ // identifier-dense text (generated contracts, column lists) runs at about
21
+ // 2.6 characters per token and overflowed the 8,192-token input limit at
22
+ // 32,000 characters.
23
+ const OPENAI_EMBEDDING_LIMITS = Object.freeze({
24
+ maxBatch: 2048,
25
+ maxRequestTokens: 300000,
26
+ maxInputTokens: 8192,
27
+ charsPerToken: 4,
28
+ conservativeCharsPerToken: 3,
29
+ });
30
+
31
+ const OPENAI_EMBEDDER_DEFAULTS = Object.freeze({
32
+ batchSize: 512,
33
+ timeoutMs: 60000,
34
+ maxRetries: 5,
35
+ concurrency: 2,
36
+ maxInputChars: 24000,
37
+ maxRequestTokens: OPENAI_EMBEDDING_LIMITS.maxRequestTokens,
38
+ });
39
+
40
+ const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
41
+ const BACKOFF_BASE_MS = 500;
42
+ const BACKOFF_CAP_MS = 30000;
43
+ const RETRY_AFTER_CAP_MS = 60000;
44
+ const MAX_RESPONSE_BYTES = 256 * 1024 * 1024;
45
+ const PROBE_TEXT = "okf-mcp";
46
+ // An input the provider rejects (invalid_request) is retried once at half its
47
+ // length, never below this many characters.
48
+ const REJECTED_INPUT_FLOOR_CHARS = 2000;
49
+ // Extra requests one rejected request may spend isolating its bad inputs by
50
+ // bisection: 16 per halving level, enough for several rejected inputs in a
51
+ // full batch. A request whose every input is rejected (a configuration
52
+ // problem, not a document) exhausts it and fails as before.
53
+ function isolationBudget(inputs) {
54
+ return 16 * Math.ceil(Math.log2(inputs + 1)) + 8;
55
+ }
56
+ // The only server-derived value an error may carry: one of these constants,
57
+ // chosen from the HTTP status and the OpenAI-style error code or type.
58
+ const OPENAI_SERVER_CODES = Object.freeze([
59
+ "invalid_api_key",
60
+ "insufficient_quota",
61
+ "rate_limited",
62
+ "model_not_found",
63
+ "invalid_request",
64
+ "server_error",
65
+ "unknown",
66
+ ]);
67
+ // Node and undici error codes and names, which are not server-supplied.
68
+ const NODE_ERROR_CODE = /^[A-Za-z_]{1,48}$/;
69
+ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
70
+
71
+ function configError(field) {
72
+ return new EmbedderError(`Embedder option ${field} is invalid.`, "invalid_embedder_config", {
73
+ field,
74
+ });
75
+ }
76
+
77
+ function integerOption(options, field, min, max) {
78
+ const value = options[field] === undefined ? OPENAI_EMBEDDER_DEFAULTS[field] : options[field];
79
+ if (!Number.isSafeInteger(value) || value < min || value > max) throw configError(field);
80
+ return value;
81
+ }
82
+
83
+ function isLoopbackHost(hostname) {
84
+ const host = String(hostname || "").toLowerCase();
85
+ return (
86
+ host === "localhost" ||
87
+ host.endsWith(".localhost") ||
88
+ host === "[::1]" ||
89
+ host === "::1" ||
90
+ /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
91
+ );
92
+ }
93
+
94
+ // Accepts "https://api.openai.com", "https://api.openai.com/v1", or a gateway
95
+ // prefix such as "https://gw.example.com/openai"; rejects credentials, queries
96
+ // and fragments so the normalised URL is safe to print.
97
+ function parseBaseUrl(value) {
98
+ if (typeof value !== "string" || !value.trim()) throw configError("baseUrl");
99
+ let url;
100
+ try {
101
+ url = new URL(value);
102
+ } catch {
103
+ throw configError("baseUrl");
104
+ }
105
+ if (
106
+ (url.protocol !== "https:" && url.protocol !== "http:") ||
107
+ url.username ||
108
+ url.password ||
109
+ url.search ||
110
+ url.hash
111
+ ) {
112
+ throw configError("baseUrl");
113
+ }
114
+ const pathname = url.pathname.replace(/\/+$/, "");
115
+ const prefix = pathname.endsWith("/v1") ? pathname : `${pathname}/v1`;
116
+ return { host: url.host, hostname: url.hostname, endpoint: `${url.origin}${prefix}/embeddings` };
117
+ }
118
+
119
+ function parseRetryAfter(header, nowMs) {
120
+ if (typeof header !== "string" || !header.trim()) return null;
121
+ const value = header.trim();
122
+ let waitMs;
123
+ if (/^\d+(\.\d+)?$/.test(value)) {
124
+ waitMs = Number(value) * 1000;
125
+ } else {
126
+ const date = Date.parse(value);
127
+ if (!Number.isFinite(date)) return null;
128
+ waitMs = date - nowMs;
129
+ }
130
+ return Math.min(RETRY_AFTER_CAP_MS, Math.max(0, Math.round(waitMs)));
131
+ }
132
+
133
+ function backoffDelay(attempt, random) {
134
+ const base = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
135
+ return Math.floor(base / 2 + random() * (base / 2));
136
+ }
137
+
138
+ // Conservative estimate for request budgets: ceil(chars / 3).
139
+ function estimateTokens(text) {
140
+ return Math.max(1, Math.ceil(text.length / OPENAI_EMBEDDING_LIMITS.conservativeCharsPerToken));
141
+ }
142
+
143
+ // The provider refused the request's content (an HTTP 4xx that is not about
144
+ // the key, quota, model or rate): with several inputs, one of them may be the
145
+ // cause. Decided from our own enumerated code, never from server text.
146
+ function isInputRejection(error) {
147
+ return (
148
+ error instanceof EmbedderError &&
149
+ error.code === "embedder_http_error" &&
150
+ error.details?.serverCode === "invalid_request"
151
+ );
152
+ }
153
+
154
+ // Contiguous batches in input order, closed by the input count or the token
155
+ // budget, whichever comes first. An input that alone exceeds the budget gets
156
+ // a batch of its own; the client's configuration rules that case out, other
157
+ // callers of this helper may not.
158
+ function planBatches(inputs, batchSize, maxRequestTokens) {
159
+ const batches = [];
160
+ let current = null;
161
+ inputs.forEach((text, index) => {
162
+ const tokens = estimateTokens(text);
163
+ const oversized = tokens > maxRequestTokens;
164
+ if (
165
+ !current ||
166
+ oversized ||
167
+ current.texts.length >= batchSize ||
168
+ current.tokens + tokens > maxRequestTokens
169
+ ) {
170
+ current = { offset: index, texts: [], tokens: 0 };
171
+ batches.push(current);
172
+ }
173
+ current.texts.push(text);
174
+ current.tokens += tokens;
175
+ if (oversized) current = null;
176
+ });
177
+ return batches;
178
+ }
179
+
180
+ // Maps an error response onto SERVER_CODES. The body's code and type are
181
+ // compared with constants and then forgotten; the result is one of our own
182
+ // strings, so nothing a server sent can reach an error, a log or a receipt.
183
+ function classifyServerError(status, bodyText) {
184
+ let code = null;
185
+ let type = null;
186
+ try {
187
+ const parsed = JSON.parse(bodyText);
188
+ const source = parsed?.error && typeof parsed.error === "object" ? parsed.error : parsed;
189
+ if (source && typeof source === "object") {
190
+ code = typeof source.code === "string" ? source.code : null;
191
+ type = typeof source.type === "string" ? source.type : null;
192
+ }
193
+ } catch {
194
+ // A body that is not JSON contributes nothing.
195
+ }
196
+ // Status first: a 5xx is a server failure whatever the body claims, 401,
197
+ // 404 and 429 speak for themselves (a 429 or a 402/403 that names quota
198
+ // exhaustion is that instead). Other 4xx go by code, then by type; code
199
+ // beats type when both are present.
200
+ const quota = code === "insufficient_quota" || type === "insufficient_quota";
201
+ if (status >= 500 && status < 600) return "server_error";
202
+ if (status === 401) return "invalid_api_key";
203
+ if (status === 404) return "model_not_found";
204
+ if (status === 429) return quota ? "insufficient_quota" : "rate_limited";
205
+ if ((status === 402 || status === 403) && quota) return "insufficient_quota";
206
+ if (status >= 400 && status < 500) {
207
+ const byCode = {
208
+ invalid_api_key: "invalid_api_key",
209
+ model_not_found: "model_not_found",
210
+ insufficient_quota: "insufficient_quota",
211
+ }[code];
212
+ if (byCode) return byCode;
213
+ const byType = {
214
+ authentication_error: "invalid_api_key",
215
+ not_found_error: "model_not_found",
216
+ rate_limit_error: "rate_limited",
217
+ insufficient_quota: "insufficient_quota",
218
+ }[type];
219
+ return byType || "invalid_request";
220
+ }
221
+ return "unknown";
222
+ }
223
+
224
+ function abortError(reason) {
225
+ if (reason instanceof EmbedderError) return reason;
226
+ return new EmbedderError("Embeddings request was aborted.", "embedder_aborted");
227
+ }
228
+
229
+ async function readBody(response, controller) {
230
+ if (!response.body || typeof response.body.getReader !== "function") {
231
+ return String(await response.text());
232
+ }
233
+ const reader = response.body.getReader();
234
+ const chunks = [];
235
+ let received = 0;
236
+ for (;;) {
237
+ const { done, value } = await reader.read();
238
+ if (done) break;
239
+ received += value.byteLength;
240
+ if (received > MAX_RESPONSE_BYTES) {
241
+ controller.abort();
242
+ throw new EmbedderError(
243
+ "Embeddings response exceeded the size limit.",
244
+ "embedder_bad_response",
245
+ );
246
+ }
247
+ chunks.push(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
248
+ }
249
+ return Buffer.concat(chunks).toString("utf8");
250
+ }
251
+
252
+ function invalidVector(reason) {
253
+ return new EmbedderError(
254
+ "Embeddings response contained an invalid vector.",
255
+ "embedder_invalid_vector",
256
+ { reason },
257
+ );
258
+ }
259
+
260
+ // Structural problems (no list, wrong count, bad indices) return null and
261
+ // become embedder_bad_response. A vector that is empty, ragged, or holds a
262
+ // value that is not a finite number once stored as float32 (1e40 becomes
263
+ // Infinity and would poison every cosine score) throws
264
+ // embedder_invalid_vector; neither is retried.
265
+ function parseVectors(payload, expectedCount) {
266
+ const data = payload && typeof payload === "object" ? payload.data : null;
267
+ if (!Array.isArray(data) || data.length !== expectedCount) return null;
268
+ const vectors = new Array(expectedCount);
269
+ let dimension = null;
270
+ for (const entry of data) {
271
+ const index = entry?.index;
272
+ const embedding = entry?.embedding;
273
+ if (
274
+ !Number.isSafeInteger(index) ||
275
+ index < 0 ||
276
+ index >= expectedCount ||
277
+ vectors[index] !== undefined
278
+ ) {
279
+ return null;
280
+ }
281
+ if (!Array.isArray(embedding) || embedding.length === 0) throw invalidVector("empty");
282
+ if (dimension === null) dimension = embedding.length;
283
+ if (embedding.length !== dimension) throw invalidVector("ragged");
284
+ const vector = new Float32Array(dimension);
285
+ for (let position = 0; position < dimension; position += 1) {
286
+ const value = embedding[position];
287
+ if (typeof value !== "number" || !Number.isFinite(value)) {
288
+ throw invalidVector("not_a_number");
289
+ }
290
+ vector[position] = value;
291
+ if (!Number.isFinite(vector[position])) throw invalidVector("not_finite_as_float32");
292
+ }
293
+ vectors[index] = vector;
294
+ }
295
+ return { vectors, dimension };
296
+ }
297
+
298
+ function usageOf(payload) {
299
+ const usage = payload && typeof payload === "object" ? payload.usage : null;
300
+ const count = (field) =>
301
+ usage && Number.isSafeInteger(usage[field]) && usage[field] >= 0 ? usage[field] : 0;
302
+ return { promptTokens: count("prompt_tokens"), totalTokens: count("total_tokens") };
303
+ }
304
+
305
+ function createOpenAiEmbedder(options) {
306
+ const config = options && typeof options === "object" ? options : {};
307
+ const { hostname, endpoint } = parseBaseUrl(config.baseUrl);
308
+ const model = config.model;
309
+ if (
310
+ typeof model !== "string" ||
311
+ !model.trim() ||
312
+ model.length > 256 ||
313
+ /[\s\p{Cc}]/u.test(model)
314
+ ) {
315
+ throw configError("model");
316
+ }
317
+ const dimensions =
318
+ config.dimensions === undefined ? null : integerOption(config, "dimensions", 1, 65536);
319
+ const batchSize = integerOption(config, "batchSize", 1, OPENAI_EMBEDDING_LIMITS.maxBatch);
320
+ const timeoutMs = integerOption(config, "timeoutMs", 1, 3600000);
321
+ const maxRetries = integerOption(config, "maxRetries", 0, 20);
322
+ const concurrency = integerOption(config, "concurrency", 1, 64);
323
+ // The ceiling stays at the 0.11.0-rc.1 value (8,192 x 4) so existing
324
+ // configurations keep loading; an input the provider still rejects is
325
+ // halved and retried (embedBatch below).
326
+ const maxInputChars = integerOption(
327
+ config,
328
+ "maxInputChars",
329
+ 1,
330
+ OPENAI_EMBEDDING_LIMITS.maxInputTokens * OPENAI_EMBEDDING_LIMITS.charsPerToken,
331
+ );
332
+ const maxRequestTokens = integerOption(
333
+ config,
334
+ "maxRequestTokens",
335
+ 1,
336
+ OPENAI_EMBEDDING_LIMITS.maxRequestTokens,
337
+ );
338
+ if (
339
+ Math.ceil(maxInputChars / OPENAI_EMBEDDING_LIMITS.conservativeCharsPerToken) > maxRequestTokens
340
+ ) {
341
+ throw new EmbedderError(
342
+ "Embedder option maxRequestTokens must admit one input of maxInputChars characters.",
343
+ "invalid_embedder_config",
344
+ { field: "maxRequestTokens" },
345
+ );
346
+ }
347
+ const languages = config.languages === undefined ? [] : config.languages;
348
+ if (!Array.isArray(languages) || languages.some((code) => typeof code !== "string")) {
349
+ throw configError("languages");
350
+ }
351
+ const fetchImpl = config.fetch === undefined ? globalThis.fetch : config.fetch;
352
+ if (typeof fetchImpl !== "function") throw configError("fetch");
353
+ const env = config.env === undefined ? process.env : config.env;
354
+ const sleep = typeof config.sleep === "function" ? config.sleep : null;
355
+ const random = config.random || Math.random;
356
+ const now = config.now || Date.now;
357
+
358
+ let apiKey = null;
359
+ if (config.apiKeyEnv !== undefined && config.apiKeyEnv !== null) {
360
+ if (typeof config.apiKeyEnv !== "string" || !ENV_NAME.test(config.apiKeyEnv)) {
361
+ throw configError("apiKeyEnv");
362
+ }
363
+ const value = env[config.apiKeyEnv];
364
+ if (typeof value !== "string" || !value.trim()) {
365
+ throw new EmbedderError(
366
+ `Embedder API key environment variable ${config.apiKeyEnv} is not set.`,
367
+ "embedder_key_missing",
368
+ { variable: config.apiKeyEnv },
369
+ );
370
+ }
371
+ apiKey = value.trim();
372
+ }
373
+
374
+ const headers = {
375
+ accept: "application/json",
376
+ "content-type": "application/json",
377
+ "user-agent": `okf-mcp/${PACKAGE_VERSION}`,
378
+ ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
379
+ };
380
+ const state = { dimension: dimensions };
381
+ const counters = {
382
+ requests: 0,
383
+ retries: 0,
384
+ promptTokens: 0,
385
+ totalTokens: 0,
386
+ inputs: 0,
387
+ truncated: 0,
388
+ halved: 0,
389
+ rejected: 0,
390
+ };
391
+
392
+ function recordDimension(dimension) {
393
+ if (state.dimension === null) {
394
+ state.dimension = dimension;
395
+ return;
396
+ }
397
+ if (dimension !== state.dimension) {
398
+ throw new EmbedderError(
399
+ `Embeddings response dimension ${dimension} does not match the expected ${state.dimension}.`,
400
+ "embedder_dimension_mismatch",
401
+ { expected: state.dimension, received: dimension },
402
+ );
403
+ }
404
+ }
405
+
406
+ // One HTTP attempt. Returns { ok: true, vectors } or { ok: false, error,
407
+ // retryable, retryAfterMs }; throws only for conditions no retry can fix.
408
+ async function attempt(batch, signal) {
409
+ // An abort listener never fires for a signal that is already aborted.
410
+ if (signal.aborted) throw abortError(signal.reason);
411
+ const controller = new AbortController();
412
+ let timedOut = false;
413
+ const timer = setTimeout(() => {
414
+ timedOut = true;
415
+ controller.abort();
416
+ }, timeoutMs);
417
+ timer.unref?.();
418
+ const forward = () => controller.abort();
419
+ signal.addEventListener("abort", forward, { once: true });
420
+ counters.requests += 1;
421
+ try {
422
+ let response;
423
+ let bodyText;
424
+ try {
425
+ response = await fetchImpl(endpoint, {
426
+ method: "POST",
427
+ headers,
428
+ body: JSON.stringify({
429
+ model,
430
+ input: batch.texts,
431
+ encoding_format: "float",
432
+ ...(dimensions ? { dimensions } : {}),
433
+ }),
434
+ signal: controller.signal,
435
+ // A redirect would carry the whole batch to another destination
436
+ // and could turn a local endpoint remote; it is a configuration
437
+ // error, never followed.
438
+ redirect: "manual",
439
+ });
440
+ if (response.status >= 300 && response.status < 400) {
441
+ await response.body?.cancel?.();
442
+ throw new EmbedderError(
443
+ `Embeddings endpoint answered with a redirect (HTTP ${response.status}); configure the final base URL.`,
444
+ "embedder_redirect",
445
+ { status: response.status },
446
+ );
447
+ }
448
+ bodyText = await readBody(response, controller);
449
+ } catch (error) {
450
+ if (error instanceof EmbedderError) throw error;
451
+ if (signal.aborted) throw abortError(signal.reason);
452
+ if (timedOut) {
453
+ return {
454
+ ok: false,
455
+ retryable: true,
456
+ retryAfterMs: null,
457
+ error: new EmbedderError(
458
+ `Embeddings request timed out after ${timeoutMs} ms.`,
459
+ "embedder_timeout",
460
+ { timeoutMs },
461
+ ),
462
+ };
463
+ }
464
+ const cause = error?.cause?.code || error?.code || error?.name;
465
+ return {
466
+ ok: false,
467
+ retryable: true,
468
+ retryAfterMs: null,
469
+ error: new EmbedderError(
470
+ "Embeddings request failed before a response arrived.",
471
+ "embedder_network_error",
472
+ typeof cause === "string" && NODE_ERROR_CODE.test(cause) ? { cause } : undefined,
473
+ ),
474
+ };
475
+ }
476
+ if (!response.ok) {
477
+ const error = new EmbedderError(
478
+ `Embeddings request failed with HTTP ${response.status}.`,
479
+ "embedder_http_error",
480
+ { status: response.status, serverCode: classifyServerError(response.status, bodyText) },
481
+ );
482
+ error.status = response.status;
483
+ const retryable = RETRYABLE_STATUSES.has(response.status);
484
+ return {
485
+ ok: false,
486
+ retryable,
487
+ retryAfterMs: retryable
488
+ ? parseRetryAfter(response.headers.get("retry-after"), now())
489
+ : null,
490
+ error,
491
+ };
492
+ }
493
+ let payload;
494
+ try {
495
+ payload = JSON.parse(bodyText);
496
+ } catch {
497
+ throw new EmbedderError("Embeddings response was not JSON.", "embedder_bad_response");
498
+ }
499
+ const parsed = parseVectors(payload, batch.texts.length);
500
+ if (!parsed) {
501
+ throw new EmbedderError(
502
+ "Embeddings response did not contain one vector per input.",
503
+ "embedder_bad_response",
504
+ );
505
+ }
506
+ recordDimension(parsed.dimension);
507
+ const usage = usageOf(payload);
508
+ counters.promptTokens += usage.promptTokens;
509
+ counters.totalTokens += usage.totalTokens;
510
+ counters.inputs += batch.texts.length;
511
+ return { ok: true, vectors: parsed.vectors };
512
+ } finally {
513
+ clearTimeout(timer);
514
+ signal.removeEventListener("abort", forward);
515
+ }
516
+ }
517
+
518
+ // The retry wait keeps the process alive on purpose: a CLI run must not
519
+ // exit mid-retry. The timer is cleared the moment the run is aborted.
520
+ async function wait(ms, signal) {
521
+ if (signal.aborted) throw abortError(signal.reason);
522
+ await new Promise((resolve, reject) => {
523
+ let timer = null;
524
+ const onAbort = () => {
525
+ if (timer !== null) clearTimeout(timer);
526
+ reject(abortError(signal.reason));
527
+ };
528
+ const settle = () => {
529
+ signal.removeEventListener("abort", onAbort);
530
+ resolve();
531
+ };
532
+ signal.addEventListener("abort", onAbort, { once: true });
533
+ if (sleep) {
534
+ Promise.resolve(sleep(ms)).then(settle, (error) => {
535
+ signal.removeEventListener("abort", onAbort);
536
+ reject(error);
537
+ });
538
+ } else {
539
+ timer = setTimeout(settle, ms);
540
+ }
541
+ });
542
+ }
543
+
544
+ async function requestBatch(batch, signal) {
545
+ for (let retry = 0; ; retry += 1) {
546
+ const outcome = await attempt(batch, signal);
547
+ if (outcome.ok) return outcome.vectors;
548
+ if (!outcome.retryable || retry >= maxRetries) {
549
+ outcome.error.details = { ...(outcome.error.details || {}), attempts: retry + 1 };
550
+ throw outcome.error;
551
+ }
552
+ counters.retries += 1;
553
+ const delay =
554
+ outcome.retryAfterMs === null ? backoffDelay(retry, random) : outcome.retryAfterMs;
555
+ await wait(delay, signal);
556
+ }
557
+ }
558
+
559
+ // One planned batch, isolating rejected inputs: a multi-input request the
560
+ // provider refuses as invalid_request is split in halves (bisection) until
561
+ // the refused inputs stand alone; a lone refused input is retried once at
562
+ // half its length (floor REJECTED_INPUT_FLOOR_CHARS). An input refused even
563
+ // then yields null and its error is kept in `rejections`. Any other error,
564
+ // or an exhausted isolation budget, throws the error at hand.
565
+ async function embedBatch(batch, signal, budget, rejections) {
566
+ let failure;
567
+ try {
568
+ return await requestBatch(batch, signal);
569
+ } catch (error) {
570
+ if (!isInputRejection(error)) throw error;
571
+ failure = error;
572
+ }
573
+ const count = batch.texts.length;
574
+ if (count > 1) {
575
+ if (budget.remaining < 2) throw failure;
576
+ budget.remaining -= 2;
577
+ const middle = Math.ceil(count / 2);
578
+ const halves = [
579
+ { offset: batch.offset, texts: batch.texts.slice(0, middle) },
580
+ { offset: batch.offset + middle, texts: batch.texts.slice(middle) },
581
+ ];
582
+ const out = [];
583
+ for (const half of halves) {
584
+ out.push(...(await embedBatch(half, signal, budget, rejections)));
585
+ }
586
+ return out;
587
+ }
588
+ const text = batch.texts[0];
589
+ const shorter = Math.max(REJECTED_INPUT_FLOOR_CHARS, Math.floor(text.length / 2));
590
+ if (shorter < text.length) {
591
+ if (budget.remaining < 1) throw failure;
592
+ budget.remaining -= 1;
593
+ try {
594
+ const vectors = await requestBatch(
595
+ { offset: batch.offset, texts: [text.slice(0, shorter)] },
596
+ signal,
597
+ );
598
+ counters.halved += 1;
599
+ return vectors;
600
+ } catch (error) {
601
+ if (!isInputRejection(error)) throw error;
602
+ failure = error;
603
+ }
604
+ }
605
+ counters.rejected += 1;
606
+ rejections.push({ index: batch.offset, error: failure });
607
+ return [null];
608
+ }
609
+
610
+ // options.skipRejected: true returns null in place of the vector of an
611
+ // input the provider rejects even after the halving retry (the host records
612
+ // it as skipped); without it, such an input fails the call as before. A
613
+ // call whose every input (more than one) is rejected always fails: that is
614
+ // a configuration problem, not a document.
615
+ async function embed(texts, embedOptions) {
616
+ if (!Array.isArray(texts)) {
617
+ throw new EmbedderError("Embedder input must be an array of strings.", "invalid_input");
618
+ }
619
+ const inputs = texts.map((text, index) => {
620
+ if (typeof text !== "string") {
621
+ throw new EmbedderError("Embedder inputs must be strings.", "invalid_input", { index });
622
+ }
623
+ if (text.length > maxInputChars) {
624
+ counters.truncated += 1;
625
+ return text.slice(0, maxInputChars);
626
+ }
627
+ return text.length === 0 ? " " : text;
628
+ });
629
+ if (inputs.length === 0) return [];
630
+ const external = embedOptions?.signal;
631
+ const run = new AbortController();
632
+ const signal = external ? AbortSignal.any([external, run.signal]) : run.signal;
633
+ // A host that runs several calls at once passes concurrency: 1 so the
634
+ // requests in flight equal its own bound; the configured value stays the
635
+ // ceiling either way.
636
+ const requested = embedOptions?.concurrency;
637
+ const parallel =
638
+ Number.isSafeInteger(requested) && requested > 0
639
+ ? Math.min(concurrency, requested)
640
+ : concurrency;
641
+ const batches = planBatches(inputs, batchSize, maxRequestTokens);
642
+ const out = new Array(inputs.length);
643
+ const rejections = [];
644
+ let next = 0;
645
+ let failure = null;
646
+ const worker = async () => {
647
+ while (next < batches.length && !failure) {
648
+ const batch = batches[next];
649
+ next += 1;
650
+ try {
651
+ const budget = { remaining: isolationBudget(batch.texts.length) };
652
+ const vectors = await embedBatch(batch, signal, budget, rejections);
653
+ vectors.forEach((vector, position) => {
654
+ out[batch.offset + position] = vector;
655
+ });
656
+ } catch (error) {
657
+ failure = failure || error;
658
+ run.abort();
659
+ }
660
+ }
661
+ };
662
+ await Promise.all(Array.from({ length: Math.min(parallel, batches.length) }, worker));
663
+ if (failure) throw failure;
664
+ if (rejections.length) {
665
+ const everyInput = inputs.length > 1 && rejections.length === inputs.length;
666
+ if (embedOptions?.skipRejected !== true || everyInput) {
667
+ rejections.sort((left, right) => left.index - right.index);
668
+ throw rejections[0].error;
669
+ }
670
+ }
671
+ return out;
672
+ }
673
+
674
+ // The id keys the cache: the normalised endpoint (gateways differ by path),
675
+ // the model, the dimension and the truncation length all change what a
676
+ // stored vector means, so each is part of it.
677
+ const embedder = {
678
+ kind: "openai",
679
+ get id() {
680
+ const dimension = state.dimension === null ? "?" : state.dimension;
681
+ return `openai:${endpoint}:${model}:${dimension}:${maxInputChars}`;
682
+ },
683
+ get dimension() {
684
+ return state.dimension;
685
+ },
686
+ languages: languages.slice(),
687
+ remote: !isLoopbackHost(hostname),
688
+ maxBatch: batchSize,
689
+ maxInputChars,
690
+ concurrency,
691
+ model,
692
+ endpoint,
693
+ embed,
694
+ async probe() {
695
+ if (state.dimension === null) await embed([PROBE_TEXT]);
696
+ return { id: embedder.id, dimension: state.dimension };
697
+ },
698
+ usage() {
699
+ return { ...counters };
700
+ },
701
+ };
702
+ return embedder;
703
+ }
704
+
705
+ module.exports = {
706
+ OPENAI_EMBEDDER_DEFAULTS,
707
+ OPENAI_EMBEDDING_LIMITS,
708
+ OPENAI_SERVER_CODES,
709
+ REJECTED_INPUT_FLOOR_CHARS,
710
+ classifyServerError,
711
+ createOpenAiEmbedder,
712
+ isLoopbackHost,
713
+ parseRetryAfter,
714
+ planBatches,
715
+ };