@kwirthmagnify/kwirth-common-ai 0.5.69 → 0.5.71

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 (2) hide show
  1. package/dist/back.js +72 -8
  2. package/package.json +1 -1
package/dist/back.js CHANGED
@@ -81,6 +81,11 @@ class UsageLimitError extends Error {
81
81
  }
82
82
  exports.UsageLimitError = UsageLimitError;
83
83
  let usageService;
84
+ /* Accounting that degrades has to SAY SO, and loudly: while the counters are unreachable the ceilings are
85
+ not being enforced, and that is the kind of thing nobody notices until the bill arrives. `console.warn`
86
+ on purpose — this module has no logger of its own and must not acquire a dependency on one to be able
87
+ to report that it is flying blind. */
88
+ const logUsage = (msg) => console.warn(`[kwirth-common-ai] ${msg}`);
84
89
  /* The core calls this at startup. Without it everything below is a no-op and the LLM is reached as ever. */
85
90
  const setUsageService = (service) => { usageService = service; };
86
91
  exports.setUsageService = setUsageService;
@@ -171,21 +176,80 @@ const runWithUsageGuard = async (options, call) => {
171
176
  const origin = options.model && typeof options.model === 'object' ? modelOrigin.get(options.model) : undefined;
172
177
  if (!service || !origin)
173
178
  return await call();
174
- const { daily, monthly } = await service.read(EUsageScope.LLM_KEY, origin.subject);
175
- const exceeded = findExceeded(EUsageScope.LLM_KEY, origin.limits, daily, monthly);
176
- if (exceeded) {
177
- (_a = service.onCut) === null || _a === void 0 ? void 0 : _a.call(service, exceeded);
178
- throw new UsageLimitError(exceeded);
179
+ /*
180
+ 🔴 The bookkeeping must never be what breaks the feature.
181
+
182
+ Both halves of this used to be plain `await`s on a database, sitting in the critical path of every
183
+ AI call. When that database has a bad moment the cost is not a missing counter: it is the whole
184
+ call. Measured on 2026-10-14 — `core-ai-usage: Connection Error: Connection ended unexpectedly` one
185
+ second in, and then **exactly 120 seconds** until the caller's own timeout gave up. The AI never
186
+ got a chance; the two minutes were spent waiting on an accounting read that was never going to
187
+ answer, and the user saw a ticket open with no resolution guidance for no reason at all.
188
+
189
+ So: the read is BOUNDED and FAILS OPEN, and the write does not block the answer.
190
+
191
+ Failing open is a deliberate trade and it is the uncomfortable one: for the span of a sick usage
192
+ database, the ceilings are not enforced. The alternative is worse — an accounting hiccup leaving
193
+ every channel in Kwirth without AI. It is said loudly in the log so it cannot pass unnoticed, and
194
+ the limits apply again the moment the database answers.
195
+ */
196
+ const READ_TIMEOUT_MS = 5000;
197
+ let read;
198
+ const readStarted = Date.now();
199
+ try {
200
+ read = await Promise.race([
201
+ service.read(EUsageScope.LLM_KEY, origin.subject),
202
+ new Promise(r => setTimeout(() => r(undefined), READ_TIMEOUT_MS))
203
+ ]);
204
+ if (!read)
205
+ logUsage(`AI usage: the counters did not answer in ${READ_TIMEOUT_MS} ms — the call goes ahead and the LIMITS ARE NOT ENFORCED for it`);
206
+ }
207
+ catch (err) {
208
+ logUsage(`AI usage: the counters could not be read (${err}) — the call goes ahead and the LIMITS ARE NOT ENFORCED for it`);
209
+ }
210
+ /* 🔴 Se mide y se dice cuando pasa de un segundo, porque sin esto no hay forma de saber dónde se fue
211
+ el tiempo. El 2026-10-14 una llamada agotó un tope de 120 s y no se pudo determinar si el culpable
212
+ era el LLM o esta lectura: el `abortSignal` del llamante arranca ANTES de llegar aquí, así que el
213
+ aborto salta dentro del SDK en los dos casos y el mensaje es idéntico. Un tramo sin instrumentar
214
+ obliga a adivinar, y adivinar ya costó una tarde. */
215
+ const readMs = Date.now() - readStarted;
216
+ if (readMs > 1000)
217
+ logUsage(`AI usage: reading the counters took ${readMs} ms before the model was even called`);
218
+ if (read) {
219
+ const exceeded = findExceeded(EUsageScope.LLM_KEY, origin.limits, read.daily, read.monthly);
220
+ if (exceeded) {
221
+ (_a = service.onCut) === null || _a === void 0 ? void 0 : _a.call(service, exceeded);
222
+ throw new UsageLimitError(exceeded);
223
+ }
224
+ }
225
+ /* 🔴 En `finally`, no después del `await`. La primera versión medía solo el camino feliz, que es
226
+ justo el que no hacía falta medir: cuando una llamada se aborta por tiempo —el caso que se estaba
227
+ investigando— el log no se ejecutaba y seguíamos sin saber si el tiempo era del modelo o de la
228
+ contabilidad de aquí arriba (2026-10-14). Un tramo instrumentado solo cuando va bien no está
229
+ instrumentado. */
230
+ const callStarted = Date.now();
231
+ let ok = false;
232
+ let result;
233
+ try {
234
+ result = await call();
235
+ ok = true;
236
+ }
237
+ finally {
238
+ const callMs = Date.now() - callStarted;
239
+ if (callMs > 30000 || !ok)
240
+ logUsage(`AI usage: the model ${ok ? 'took' : 'FAILED after'} ${Math.round(callMs / 1000)} s (counters read in ${readMs} ms)`);
179
241
  }
180
- const result = await call();
181
242
  const tokensIn = (_c = (_b = result.usage) === null || _b === void 0 ? void 0 : _b.inputTokens) !== null && _c !== void 0 ? _c : 0;
182
243
  const tokensOut = (_e = (_d = result.usage) === null || _d === void 0 ? void 0 : _d.outputTokens) !== null && _e !== void 0 ? _e : 0;
183
- await service.add(EUsageScope.LLM_KEY, origin.subject, {
244
+ /* Sin `await`: la respuesta ya está. Esperar al apunte solo añade el tiempo de la base a lo que el
245
+ usuario percibe, y si la base está mal, lo añade entero. Lo que se pierde al fallar es un contador;
246
+ lo que se perdía antes era la llamada. */
247
+ void service.add(EUsageScope.LLM_KEY, origin.subject, {
184
248
  tokensIn,
185
249
  tokensOut,
186
250
  calls: 1,
187
251
  cost: costOf(origin, tokensIn, tokensOut)
188
- });
252
+ }).catch(err => logUsage(`AI usage: could not record ${tokensIn + tokensOut} token(s) of a call that DID happen (${err}) — the counters are now short`));
189
253
  return result;
190
254
  };
191
255
  exports.runWithUsageGuard = runWithUsageGuard;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kwirthmagnify/kwirth-common-ai",
3
- "version": "0.5.69",
3
+ "version": "0.5.71",
4
4
  "description": "Shared AI/LLM types and utilities for Kwirth AI plugins",
5
5
  "scripts": {
6
6
  "build": "del .\\dist\\* /s /q 2>nul & tsc",