cartethyia 2.5.4 → 2.5.6

package/src/network/pool/selector.ts

@@ -278,7 +278,7 @@ export class NetworkPoolSelector {
         // One script, not `SET` then `SADD`: a crash between the two left the
         // marker unindexed (invisible to the pool listing) or the index
         // pointing at a marker that expired. The script also arms the index
-        // set's own TTL, which previously had none and so grew without bound.
+        // set's own TTL, which must be armed or the index grows without bound.
         await redisEvalNumber(
           this.redis,
           COOLDOWN_FLAG_SCRIPT,
@@ -458,9 +458,10 @@ export class NetworkPoolSelector {
   /**
    * Removes one cooldown marker and its index entry in one atomic step.
    *
-   * The two writes used to be separate `DEL` + `SREM`, so a crash between them
-   * left the index listing a provider whose marker was gone — a pool would
-   * report a cooldown that no longer applied until the index entry expired.
+   * The two writes must not be separate `DEL` + `SREM`: a crash between them
+   * would leave the index listing a provider whose marker is gone — a pool
+   * would report a cooldown that no longer applies until the index entry
+   * expires.
    */
   private async clearRedisCooldown(poolId: string, providerId: string): Promise<void> {
     if (!this.redis) return;

package/src/network/retry.ts

@@ -7,6 +7,7 @@
  */
 
 import { exponentialBackoff, type BackoffOptions } from "./backoff";
+import { sleep as defaultSleep } from "../shared/sleep";
 
 export interface RetryOptions {
   readonly maxRetries?: number;
@@ -18,8 +19,6 @@ export interface RetryOptions {
   readonly shouldRetry?: (error: unknown, attempt: number) => boolean;
 }
 
-const defaultSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
 /**
  * Runs `fn`, retrying on failure with exponential backoff (100 ms, 200 ms,
  * 400 ms, …) capped at `maxDelayMs` and jittered by up to 25% to avoid a

package/src/network/ssrf.ts

@@ -73,10 +73,11 @@ function cidrContains(address: string, cidr: string): boolean {
   const [network, prefixText] = cidr.split("/");
   if (!network || prefixText === undefined) return false;
   // A present-but-blank prefix (`"10.0.0.0/"`) must be refused, not coerced.
-  // `Number("")` is 0 and `""` is not `undefined`, so the guard below used to fall
-  // through with `prefix = 0` — and a /0 admits every address of its family. An
-  // operator's typo therefore silently widened the allowlist to the whole IPv4
-  // space, including the link-local metadata endpoint this guard exists to refuse.
+  // `Number("")` is 0 and `""` is not `undefined`, so a plain truthiness check
+  // here would leave `prefix = 0` — and a /0 admits every address of its family.
+  // An operator's typo would therefore silently widen the allowlist to the whole
+  // IPv4 space, including the link-local metadata endpoint this guard exists to
+  // refuse.
   //
   // Requiring a run of digits (after trimming) also refuses the exotic spellings
   // `Number` accepts for zero — `-0`, `+0`, `0x0`, `0b0`, `0o0`, `0.0` — all of

package/src/observability/event-compaction.ts

@@ -1,70 +1,13 @@
 /**
- * Compaction for hourly telemetry files: old per-request rows become one
- * summary row per (tenant, API key, day).
+ * Bucket primitives for the per-day telemetry index.
  *
- * The problem this solves is growth, and growth alone. Hourly JSONL files were
- * never deleted, so every read of the usage list scanned every file ever
- * written — the cost grew with total volume, not with the number of users. An
- * install serving 20 users got slower purely by serving them longer.
- *
- * Compaction is **accumulation, not sampling**. A compacted row carries the
- * running sums of everything it replaced, so a total that read 2B tokens
- * before compaction still reads 2B after it. Nothing is estimated and nothing
- * is averaged away — the per-request rows are gone, their totals are not.
- *
- * What compaction cannot preserve is anything that needs the individual row:
- * the request list, per-request filters, and the detail drawer. Latency is the
- * interesting middle case — a percentile needs every sample, so compaction
- * keeps a fixed histogram instead. P50 stays available as an approximation and
- * is marked as one rather than silently reported as exact.
- *
- * Retention becomes tiered:
- *
- *   0 .. N days   hourly files, complete
- *   N .. M days   compacted daily summary
- *   beyond M      deleted
+ * Each day's events are folded into a `CompactedBucket` via `accumulate()` and
+ * stored as a `.index.json` file alongside the source `.events.jsonl`. Buckets
+ * are pure accumulators: every field is a running sum, min, or max — nothing
+ * is averaged or estimated away. `mergeBucketsInternal` adds two buckets so
+ * partial indexes can be merged without re-reading source files.
  */
 import type { TelemetryEventRecord } from "./event-log";
-import type { CartethyiaDatabase } from "../persistence/db-handle";
-import { consoleSettings } from "../persistence/schema";
-import { resolveTelemetryWindowMinutes } from "../config/telemetry";
-
-/**
- * The compaction age to apply on a pass with no explicit age given.
- *
- * Hourly files are **not** partitioned per tenant — one file per hour holds
- * every tenant's rows — so a per-tenant age cannot be honoured per file. The
- * safest reading of several tenants' preferences is the **largest**: compacting
- * smaller than one tenant asked for moves its requests into the summary before
- * that tenant expected, losing the per-request view of them, while keeping them
- * longer than another wanted only costs disk and a slower scan. Losing detail
- * is not reversible; using more disk is.
- *
- * Falls back to the deployment default when no tenant overrides, and never
- * exceeds the retention window (compacting at or past the delete age would
- * fold a file and discard it in the same pass).
- */
-export async function resolveEffectiveWindowMinutes(db: CartethyiaDatabase): Promise<number> {
-  const fallback = resolveTelemetryWindowMinutes();
-  try {
-    const rows = await db
-      .select({ preferences: consoleSettings.preferences })
-      .from(consoleSettings);
-    let widest = fallback;
-    for (const row of rows) {
-      const minutes = row.preferences?.telemetryWindowMinutes;
-      if (typeof minutes === "number" && Number.isFinite(minutes) && minutes > widest) {
-        widest = minutes;
-      }
-    }
-    return Math.floor(widest);
-  } catch {
-    return fallback;
-  }
-}
-
-/** Discriminator so a reader can tell a summary from a request row at a glance. */
-const COMPACTED_KIND = "compacted" as const;
 
 /**
  * Histogram bucket edges in milliseconds.
@@ -112,23 +55,53 @@ export interface CompactedBucket {
   readonly byProvider: Readonly<Record<string, number>>;
   readonly byClient: Readonly<Record<string, number>>;
   readonly byClientIp: Readonly<Record<string, number>>;
+  /**
+   * Requests per HTTP status, keyed by the status as a decimal string.
+   *
+   * Kept as counts for the same reason the other dimensions are: the Usage
+   * summary's status chips and the request-list filters read these, and without
+   * them every chip reads zero once the day's events have been folded — the
+   * numbers were on the source events, which no longer exist.
+   */
+  readonly byStatus: Readonly<Record<string, number>>;
+  /**
+   * Sum and count of gateway routing delay, so `avgResolveMs` survives
+   * compaction. Kept as a sum rather than an average of averages for the same
+   * reason the latency sum is: an average of per-file averages drifts as soon
+   * as the files hold different request counts.
+   */
+  readonly resolveSumMs: number;
+  readonly resolveCount: number;
 }
 
-/** One compacted row: the totals of everything it replaced, for one key/day. */
-export interface CompactedRow extends CompactedBucket {
-  readonly kind: typeof COMPACTED_KIND;
-  /** ISO day (UTC) this row summarises. */
-  readonly day: string;
-  readonly tenantId: string;
-  readonly apiKeyId: string | null;
-}
-
-/** A number from a value that may be a numeric string; 0 when unusable. */
-function numeric(value: unknown): number {
+/**
+ * A number from a value that may be a numeric string; 0 when unusable.
+ *
+ * Exported so readers of a compacted bucket coerce its fields the same way the
+ * fold does: a second local copy of "is this a number" is how one caller ends
+ * up summing `undefined` into NaN while another reads it as zero.
+ */
+export function numeric(value: unknown): number {
   const asNumber = typeof value === "number" ? value : Number(value);
   return Number.isFinite(asNumber) ? asNumber : 0;
 }
 
+/**
+ * The two fields added after the first index format, read defensively.
+ *
+ * An index file written before they existed carries neither, and `undefined +
+ 0` is `NaN` — which then propagates straight through every later fold and
+ * merge, so one old day turns the whole period's `avgResolveMs` into `NaN`.
+ * Reading them as 0/{} is the same answer an empty day gives, and a folded
+ * day that predates the field genuinely has no resolve measurement to report.
+ */
+function readResolveSum(bucket: CompactedBucket): number {
+  return numeric(bucket.resolveSumMs);
+}
+function readResolveCount(bucket: CompactedBucket): number {
+  return numeric(bucket.resolveCount);
+}
+
 /** Adds one occurrence to a count map, ignoring an absent key. */
 function bump(
   counts: Readonly<Record<string, number>> | undefined,
@@ -156,6 +129,9 @@ export function emptyBucket(): CompactedBucket {
     byProvider: {},
     byClient: {},
     byClientIp: {},
+    byStatus: {},
+    resolveSumMs: 0,
+    resolveCount: 0,
     requests: 0,
     inputTokens: 0,
     cachedTokens: 0,
@@ -207,11 +183,18 @@ export function accumulate(
   // summing, which turned a cost of 0.000966 into "00.000966". Coerced here so
   // every downstream sum is arithmetic.
   const priced = numeric(event.estimatedCostUsd);
+  const resolve = event.resolveMs;
+  const hasResolve = resolve !== null && resolve !== undefined && Number.isFinite(resolve);
   return {
     byModel: bump(into.byModel, event.requestedModel ?? event.reportedModel),
     byProvider: bump(into.byProvider, event.providerId),
     byClient: bump(into.byClient, event.sourceSurface),
     byClientIp: bump(into.byClientIp, event.clientIp),
+    // Keyed on the HTTP status, not the internal one: the chips and the filters
+    // are the status the client was given.
+    byStatus: bump(into.byStatus, event.httpStatus?.toString()),
+    resolveSumMs: readResolveSum(into) + (hasResolve ? resolve : 0),
+    resolveCount: readResolveCount(into) + (hasResolve ? 1 : 0),
     requests: into.requests + 1,
     inputTokens: into.inputTokens + (event.inputTokens ?? 0),
     cachedTokens: into.cachedTokens + (event.cachedInputTokens ?? 0),
@@ -251,13 +234,20 @@ export function accumulate(
  *
  * Returns the upper edge of the bucket that contains it — never a value
  * between edges, because a histogram cannot be more precise than the bucket
- * that holds the sample. `null` when there are no samples, and `null` when the
- * percentile falls in the overflow bucket, whose upper edge is unbounded.
+ * that holds the sample. `null` when there are no samples.
+ *
+ * The overflow bucket is the last one and has no upper edge, so it returns
+ * {@link HISTOGRAM_OVERFLOW_MS} — the top edge of the last real bucket — rather
+ * than `null`. Returning `null` there was read as "no data" by every caller,
+ * which collapsed a P95 of 40 s to `0 ms`: the slowest, most interesting
+ * percentiles were the ones reported as zero. Callers that can do better pass
+ * the period's `latencyMaxMs` as `overflowMs` and get that instead.
  */
 export function percentileFromHistogram(
   histogram: readonly number[],
   percentile: number,
-): (typeof LATENCY_BUCKETS_MS)[number] | null {
+  overflowMs?: number | null,
+): number | null {
   const total = histogram.reduce((sum, count) => sum + count, 0);
   if (total === 0) return null;
   const target = Math.ceil((percentile / 100) * total);
@@ -267,12 +257,21 @@ export function percentileFromHistogram(
     if (seen >= target) {
       // The bucket's upper edge: a percentile from a histogram can never be
       // more precise than the bucket that contains it.
-      return index < LATENCY_BUCKETS_MS.length ? LATENCY_BUCKETS_MS[index]! : null;
+      if (index < LATENCY_BUCKETS_MS.length) return LATENCY_BUCKETS_MS[index]!;
+      // Above the last edge. `latencyMaxMs` is the honest answer when the
+      // caller has it — it is the real slowest request in the period, so a
+      // percentile past the last edge is at most that. Falling back to the
+      // last edge rather than 0 keeps the figure in the right order of
+      // magnitude even when no max was recorded.
+      return overflowMs ?? HISTOGRAM_OVERFLOW_MS;
     }
   }
   return null;
 }
 
+/** Top edge of the last real latency bucket; the floor for an overflow answer. */
+export const HISTOGRAM_OVERFLOW_MS = LATENCY_BUCKETS_MS[LATENCY_BUCKETS_MS.length - 1]!;
+
 /** Newline count of a file, so a torn or unparsable line is detectable. */
 /** Adds two buckets. Exported so the day index can merge without duplicating it. */
 export function mergeBucketsInternal(a: CompactedBucket, b: CompactedBucket): CompactedBucket {
@@ -282,6 +281,9 @@ export function mergeBucketsInternal(a: CompactedBucket, b: CompactedBucket): Co
     byProvider: mergeCounts(a.byProvider, b.byProvider),
     byClient: mergeCounts(a.byClient, b.byClient),
     byClientIp: mergeCounts(a.byClientIp, b.byClientIp),
+    byStatus: mergeCounts(a.byStatus, b.byStatus),
+    resolveSumMs: readResolveSum(a) + readResolveSum(b),
+    resolveCount: readResolveCount(a) + readResolveCount(b),
     requests: a.requests + b.requests,
     inputTokens: a.inputTokens + b.inputTokens,
     cachedTokens: a.cachedTokens + b.cachedTokens,

package/src/observability/event-day-index.ts

@@ -12,17 +12,15 @@ import { TELEMETRY_EVENT_DIR, type TelemetryEventRecord } from "./event-log";
  * One sidecar index per day, beside that day's append-only event file.
  *
  * The event file grows all day and is never rewritten while it is open. The
- * index is the thing the dashboard reads: it holds the same totals and the same
- * breakdown counts the old per-day compaction produced, but they are maintained
- * incrementally from a byte watermark rather than rebuilt by folding and
- * deleting source files.
+ * index is the thing the dashboard reads: it holds the totals and the breakdown
+ * counts, maintained incrementally from a byte watermark rather than rebuilt by
+ * folding and deleting source files.
  *
- * That watermark is the whole reason this replaces the old scheme. Which file
- * was still being written used to be decided by comparing file *names*, so the
- * open file was periodically folded and unlinked mid-write, and its requests
- * never reached the summary. A byte offset has no such ambiguity: everything
- * below it is counted, everything above it is not, and re-reading the tail is
- * idempotent.
+ * The watermark is what makes that possible. Deciding which file was still
+ * being written by comparing file *names* lets the open file be folded and
+ * unlinked mid-write, so its requests never reach the summary. A byte offset
+ * has no such ambiguity: everything below it is counted, everything above it is
+ * not, and re-reading the tail is idempotent.
  */
 
 /**
@@ -58,16 +56,16 @@ export function utcDay(at: Date): string {
  * One hour's share of a bucket.
  *
  * The Traffic chart asks how a day was spent, which the totals alone cannot
- * answer. Twenty-four slots per bucket is small — four numbers each — and is
- * held *inside* the index rather than as the per-hour files this replaced.
+ * answer. Twenty-four slots per bucket is small — four numbers each — so it is
+ * held *inside* the index rather than as separate per-hour files.
  */
 /**
  * One named dimension's share of a bucket.
  *
  * The breakdown asks for tokens, errors and cost per model/provider/client/IP,
- * not merely how many requests each took. Counts alone were enough for the old
- * per-day totals, but the breakdown columns would all have read zero, so each
- * named entry carries the same running sums the bucket does.
+ * not merely how many requests each took. Counts alone would leave every
+ * breakdown column reading zero, so each named entry carries the same running
+ * sums the bucket does.
  */
 export interface IndexedDimension {
   readonly requests: number;

package/src/observability/event-log.ts

@@ -5,9 +5,9 @@ import { resolveDataDir } from "../persistence/db-mode";
 
 /**
  * Per-request telemetry lives in hourly JSONL files, not in Postgres. The
- * database keeps only the durable aggregate. Every reader that used to query
- * `telemetry_events` reads through here, so the file is the single source for
- * recent requests and the table is no longer written.
+ * database keeps only the durable aggregate; the files are the single source
+ * for recent requests and readers must go through this module, not a
+ * `telemetry_events` table.
  */
 /**
  * Where hourly event files and their compacted summaries live.
@@ -325,7 +325,7 @@ export async function queryTelemetryEvents(query: EventQuery): Promise<Telemetry
   //
   // The lower bound is the retention window, not just `since`: a caller that
   // asks for all time still must not scan files that have already been aged
-  // out, and one that passes no `since` at all used to read every file ever
+  // out, and one that passes no `since` at all must not read every file ever
   // written. Files older than retention are gone or compacted; either way they
   // are not here.
   const retentionFloor = hourStamp(

package/src/observability/logger.ts

@@ -115,12 +115,12 @@ function logArgs(
   msg: string,
   args: readonly unknown[],
 ): void {
-  // The level is consulted first. Building the safe copy used to happen
-  // unconditionally, so a `debug` call at the production `info` default still
-  // paid a depth-capped deep copy plus a JSON.stringify of every argument, on
-  // every request that reached it — the surface-detection debug line fires on
-  // almost every chat request. Pino's own level check happens inside `write`,
-  // which is already too late to skip the work.
+  // The level is consulted first. Building the safe copy unconditionally would
+  // make a `debug` call at the production `info` default still pay a
+  // depth-capped deep copy plus a JSON.stringify of every argument, on every
+  // request that reaches it — the surface-detection debug line fires on almost
+  // every chat request. Pino's own level check happens inside `write`, which is
+  // already too late to skip the work.
   if (!logger.isLevelEnabled(level)) return;
   const safeArgs = safeLogArgs(args);
   ring(level, msg, safeArgs);