@umituz/web-ai 1.2.0 → 1.4.0

package/README.md

@@ -90,6 +90,12 @@ The pieces a backend-proxy chat stack needs, all persistence-free:
 - `buildUsageDailySeries` / `usageWindowTotals` / `usageTrendOf` /
   `errorRatePct` — turn sparse SQL day aggregates into zero-filled usage
   series and dashboard math.
+- `deriveConversationTitle(content, { fallback, maxChars })` — first-line
+  title derivation for new conversations (Markdown prefix strip, collapse,
+  truncate).
+- `planStuckRecovery(task, now)` / `STUCK_TASK_THRESHOLD_MS` — recovery
+  decision for queue rows found stale in `running`; sits next to
+  `canStartTask` / `planTaskFailure`.
 
 ## Client-side chat over your own backend
 

package/dist/core/index.cjs

@@ -322,6 +322,31 @@ function aiErrorStatus(code) {
   return AI_ERROR_STATUS[code];
 }
 
+// src/core/errors/ai-failure.ts
+var TYPE_TO_CODE = {
+  ["INVALID_API_KEY" /* INVALID_API_KEY */]: "invalid_key",
+  ["MISSING_CONFIG" /* MISSING_CONFIG */]: "missing_key",
+  ["NETWORK_ERROR" /* NETWORK_ERROR */]: "network",
+  ["ABORT_ERROR" /* ABORT_ERROR */]: "timeout",
+  ["RATE_LIMIT_ERROR" /* RATE_LIMIT_ERROR */]: "rate_limited",
+  ["SERVER_ERROR" /* SERVER_ERROR */]: "upstream_error",
+  ["CLIENT_ERROR" /* CLIENT_ERROR */]: "invalid_request",
+  ["UNKNOWN_ERROR" /* UNKNOWN_ERROR */]: "upstream_error"
+};
+function aiFailureOf(error) {
+  if (error instanceof AiError) {
+    return { code: error.code, status: AI_ERROR_STATUS[error.code], message: error.userMessage };
+  }
+  if (error instanceof AIError) {
+    const code = TYPE_TO_CODE[error.type];
+    return { code, status: AI_ERROR_STATUS[code], message: CODE_MESSAGES[code] };
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    return { code: "timeout", status: AI_ERROR_STATUS.timeout, message: CODE_MESSAGES.timeout };
+  }
+  return { code: "upstream_error", status: AI_ERROR_STATUS.upstream_error, message: CODE_MESSAGES.upstream_error };
+}
+
 // src/core/executor/retry-executor.strategy.ts
 var RetryExecutor = class {
   constructor(retryManager2, options) {
@@ -925,6 +950,34 @@ function failoverCandidate(primary, fallback) {
   return fallback;
 }
 
+// src/core/utils/title.ts
+function deriveConversationTitle(content, options = {}) {
+  const fallback = options.fallback ?? "";
+  const maxChars = options.maxChars ?? 60;
+  const firstLine = content.split("\n").map((line) => line.trim()).find((line) => line.length > 0);
+  const cleaned = (firstLine ?? fallback).replace(/^#{1,6}\s+/, "").replace(/^[>*-]\s+/, "").replace(/\s+/g, " ");
+  if (cleaned.length === 0) return fallback;
+  return cleaned.length > maxChars ? `${cleaned.slice(0, maxChars).trimEnd()}\u2026` : cleaned;
+}
+
+// src/core/utils/allowance-window.ts
+var DEFAULT_ALLOWANCE_WINDOW_MS = 36e5;
+function createAllowanceWindow(options) {
+  const windowMs = options.windowMs ?? DEFAULT_ALLOWANCE_WINDOW_MS;
+  const buckets = /* @__PURE__ */ new Map();
+  return {
+    allow(key, now = Date.now()) {
+      const bucket = buckets.get(key);
+      if (bucket === void 0 || now - bucket.windowStart >= windowMs) {
+        buckets.set(key, { windowStart: now, count: 1 });
+        return true;
+      }
+      bucket.count += 1;
+      return bucket.count <= options.limit;
+    }
+  };
+}
+
 // src/core/constants/protocol.constants.ts
 var SSE_PREFIX = "data: ";
 var SSE_DONE_MARKER = "[DONE]";
@@ -1304,6 +1357,11 @@ function planTaskFailure(task, errorDetail, backoffBaseMs, now = /* @__PURE__ */
     }
   };
 }
+var STUCK_TASK_THRESHOLD_MS = 15 * 60 * 1e3;
+function planStuckRecovery(task, now = /* @__PURE__ */ new Date(), thresholdMs = STUCK_TASK_THRESHOLD_MS) {
+  if (now.getTime() - task.updatedAt.getTime() < thresholdMs) return null;
+  return task.attempts >= task.maxAttempts ? { action: "fail" } : { action: "requeue" };
+}
 
 // src/core/sse/sse-response.service.ts
 var SSE_BRIDGE_EVENTS = {
@@ -1903,21 +1961,52 @@ async function readSseResponse(response, callbacks) {
     callbacks.onError?.("request_failed", "The server returned an empty stream.");
     return;
   }
-  const reader = response.body.getReader();
+  for await (const event of iterateSseJson(response)) {
+    if (event) dispatchSseEvent(event, callbacks);
+  }
+}
+function dataPayloadOf(frame) {
+  let data = null;
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("data:")) {
+      const payload = line.slice(5).trim();
+      data = data === null ? payload : `${data}
+${payload}`;
+    }
+  }
+  return data !== null && data.length > 0 ? data : null;
+}
+async function* iterateSseData(source) {
+  const body = source instanceof Response ? source.body : source;
+  if (!body) {
+    throw new Error("iterateSseData: the response has no body to read");
+  }
+  const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    let separator = buffer.indexOf("\n\n");
-    while (separator !== -1) {
-      const rawEvent = buffer.slice(0, separator);
-      buffer = buffer.slice(separator + 2);
-      separator = buffer.indexOf("\n\n");
-      const event = parseSseEvent(rawEvent);
-      if (!event) continue;
-      dispatchSseEvent(event, callbacks);
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        boundary = buffer.indexOf("\n\n");
+        const data = dataPayloadOf(frame);
+        if (data) yield data;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+async function* iterateSseJson(source) {
+  for await (const data of iterateSseData(source)) {
+    try {
+      yield JSON.parse(data);
+    } catch {
     }
   }
 }
@@ -2062,6 +2151,7 @@ exports.CODE_MESSAGES = CODE_MESSAGES;
 exports.CacheManager = CacheManager;
 exports.CompositeExecutor = CompositeExecutor;
 exports.DEFAULT_AI_IDENTITY = DEFAULT_AI_IDENTITY;
+exports.DEFAULT_ALLOWANCE_WINDOW_MS = DEFAULT_ALLOWANCE_WINDOW_MS;
 exports.DEFAULT_API_KEY_RULE = DEFAULT_API_KEY_RULE;
 exports.DEFAULT_EMBED_BATCH_SIZE = DEFAULT_EMBED_BATCH_SIZE;
 exports.DEFAULT_ERROR_CLASSIFICATION_RULE = DEFAULT_ERROR_CLASSIFICATION_RULE;
@@ -2100,6 +2190,7 @@ exports.SSE_BRIDGE_EVENTS = SSE_BRIDGE_EVENTS;
 exports.SSE_DONE_MARKER = SSE_DONE_MARKER;
 exports.SSE_PREFIX = SSE_PREFIX;
 exports.STATUS_TO_CODE = STATUS_TO_CODE;
+exports.STUCK_TASK_THRESHOLD_MS = STUCK_TASK_THRESHOLD_MS;
 exports.SYSTEM_PROMPT_VERSION = SYSTEM_PROMPT_VERSION;
 exports.StreamingResponseParser = StreamingResponseParser;
 exports.StructuredPromptBuilder = StructuredPromptBuilder;
@@ -2113,6 +2204,7 @@ exports.USER_FRIENDLY_ERROR_MESSAGES = USER_FRIENDLY_ERROR_MESSAGES;
 exports.accumulateReport = accumulateReport;
 exports.aiErrorMessage = aiErrorMessage;
 exports.aiErrorStatus = aiErrorStatus;
+exports.aiFailureOf = aiFailureOf;
 exports.asObjectArray = asObjectArray;
 exports.asRecord = asRecord;
 exports.asStringArray = asStringArray;
@@ -2138,11 +2230,13 @@ exports.classifyHttpStatus = classifyHttpStatus;
 exports.computeCostMicros = computeCostMicros;
 exports.cosineSimilarity = cosineSimilarity;
 exports.countChanges = countChanges;
+exports.createAllowanceWindow = createAllowanceWindow;
 exports.createRemoteChatClient = createRemoteChatClient;
 exports.createSseResponse = createSseResponse;
 exports.debounce = debounce;
 exports.debounceManager = debounceManager;
 exports.defaultSseDeltaExtractor = defaultSseDeltaExtractor;
+exports.deriveConversationTitle = deriveConversationTitle;
 exports.deriveSnippetTitle = deriveSnippetTitle;
 exports.describeAIErrorType = describeAIErrorType;
 exports.diffLines = diffLines;
@@ -2175,6 +2269,8 @@ exports.isTextTier = isTextTier;
 exports.isTransientError = isTransientError;
 exports.isValidApiKey = isValidApiKey;
 exports.isWithinWindow = isWithinWindow;
+exports.iterateSseData = iterateSseData;
+exports.iterateSseJson = iterateSseJson;
 exports.magnitude = magnitude;
 exports.mergeTierOverrides = mergeTierOverrides;
 exports.nextAttemptDelayMs = nextAttemptDelayMs;
@@ -2183,6 +2279,7 @@ exports.normalizeSources = normalizeSources;
 exports.normalizeSseChunk = normalizeSseChunk;
 exports.oneOfCatalog = oneOfCatalog;
 exports.parseSseEvent = parseSseEvent;
+exports.planStuckRecovery = planStuckRecovery;
 exports.planTaskFailure = planTaskFailure;
 exports.readSseResponse = readSseResponse;
 exports.repairCommonJsonDefects = repairCommonJsonDefects;