cartethyia 2.7.9 → 2.8.1

package/src/observability/telemetry-row.ts

@@ -0,0 +1,125 @@
+// Shared telemetry insert-row mapping: the single column spelling for both the
+// write path (telemetry-buffer.ts) and the reconciliation backfill
+// (telemetry-reconciliation.ts). Before this module existed the two paths kept
+// hand-maintained mirrors that drifted — the backfill dropped creditUsed,
+// resolveMs, tokensPerSec, firstContentDeltaAtMs, lastEventAtMs,
+// payloadCaptureState, and degenerateStop, so a recovered row read as if those
+// events never happened. One mapper means a column change lands in both paths.
+import { telemetryEvents } from "../persistence/schema";
+import { clientNameFromUserAgent } from "./client-name";
+
+/**
+ * A normalized telemetry event, shaped like the raw `TelemetryEventRecord` the
+ * reconciliation job parses off disk. The write path normalizes its
+ * `TelemetryEventInput` (nested `usage`, token-count coercion) into this shape
+ * before calling {@link telemetryInsertRow}; the reconciliation path passes its
+ * parsed record directly.
+ */
+export interface TelemetryInsertRowSource {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly requestId: string;
+  readonly createdAt: Date | string;
+  readonly sourceSurface: string | null;
+  readonly requestedModel: string | null;
+  readonly reportedModel: string | null;
+  readonly requestedEffort: string | null;
+  readonly providerId: string | null;
+  readonly accountId: string | null;
+  readonly networkPoolId: string | null;
+  readonly endpoint: string | null;
+  readonly apiKeyId: string | null;
+  readonly userAgent: string | null;
+  readonly clientIp: string | null;
+  readonly latencyMs: number | null;
+  readonly ttfbMs: number | null;
+  readonly stream: boolean | null;
+  readonly status: string | null;
+  readonly httpStatus: number | null;
+  readonly errorOrigin: string | null;
+  readonly errorCategory: string | null;
+  readonly inputTokens: number | null;
+  readonly cachedInputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly reasoningTokens: number | null;
+  readonly estimatedCostUsd: number | null;
+  readonly creditUsed: number | null;
+  readonly resolveMs: number | null;
+  readonly tokensPerSec: number | null;
+  readonly firstContentDeltaAtMs: number | null;
+  readonly lastEventAtMs: number | null;
+  /** Why the drawer payloads are empty, or `captured`; absent when unrecorded. */
+  readonly payloadCaptureState?: string | null;
+  /** `true` for a degenerate-stop request; absent/null for everything else. */
+  readonly degenerateStop?: boolean;
+}
+
+/** Coerces a token count to the integer the schema columns store; `undefined` for an unavailable count. */
+export function tokenCountToInt(value: number | "unavailable" | undefined): number | undefined {
+  return typeof value === "number" ? Math.round(value) : undefined;
+}
+
+/**
+ * Maps a normalized event to its `telemetry_events` insert row.
+ *
+ * Every column below has a live producer on the write path, and the
+ * reconciliation backfill relies on this exact spelling to recover the same
+ * columns from a raw line. Contract details that are load-bearing:
+ *
+ * - `id = requestId` is what makes the unique index a working idempotency
+ *   boundary: a retry of the same request carries the same id.
+ * - `estimatedCostUsd` persists NULL when the route is unpriced, never the
+ *   text `"null"` — the analytics `partial` flag counts completed rows with no
+ *   persisted cost.
+ * - `creditUsed`/`tokensPerSec` use `!= null` so a measured zero is preserved
+ *   (numeric columns are string-typed in Drizzle).
+ * - `clientName` is derived here, once, via `clientNameFromUserAgent`, so the
+ *   write path and the backfill group the same client the same way.
+ */
+export function telemetryInsertRow(event: TelemetryInsertRowSource): typeof telemetryEvents.$inferInsert {
+  return {
+    id: event.requestId,
+    tenantId: event.tenantId,
+    requestId: event.requestId,
+    // Stamped here, not by the reader. A row without it has no real time, and a
+    // reader that invented one made every such row look like it happened just now.
+    createdAt: new Date(event.createdAt),
+    sourceSurface: event.sourceSurface as typeof telemetryEvents.$inferInsert.sourceSurface,
+    requestedModel: event.requestedModel,
+    reportedModel: event.reportedModel,
+    requestedEffort: event.requestedEffort,
+    endpoint: event.endpoint,
+    apiKeyId: event.apiKeyId,
+    userAgent: event.userAgent,
+    // Canonical client grouping, stamped once so SQL breakdowns group by it.
+    clientName: clientNameFromUserAgent(event.userAgent),
+    clientIp: event.clientIp,
+    providerId: event.providerId,
+    accountId: event.accountId,
+    networkPoolId: event.networkPoolId,
+    latencyMs: event.latencyMs,
+    ttfbMs: event.ttfbMs,
+    stream: event.stream,
+    httpStatus: event.httpStatus,
+    status: event.status as typeof telemetryEvents.$inferInsert.status,
+    errorCategory: event.errorCategory,
+    errorOrigin: event.errorOrigin,
+    inputTokens: event.inputTokens,
+    cachedInputTokens: event.cachedInputTokens,
+    outputTokens: event.outputTokens,
+    reasoningTokens: event.reasoningTokens,
+    // `estimated_cost` is `null` when the route is unpriced; persist NULL so
+    // the analytics `partial` flag can count it. `String(null)` would store the
+    // text "null", which the numeric column rejects.
+    estimatedCostUsd: event.estimatedCostUsd === null ? null : String(event.estimatedCostUsd),
+    // Provider-billed credit (Tencent buddy-meter `credit`, Qoder `credits`);
+    // NULL when the upstream reported no credit field.
+    creditUsed: event.creditUsed != null ? String(event.creditUsed) : null,
+    resolveMs: event.resolveMs,
+    tokensPerSec: event.tokensPerSec != null ? String(event.tokensPerSec) : null,
+    firstContentDeltaAtMs: event.firstContentDeltaAtMs,
+    lastEventAtMs: event.lastEventAtMs,
+    payloadCaptureState: event.payloadCaptureState ?? null,
+    degenerateStop: event.degenerateStop ?? null,
+  };
+}

package/src/persistence/db-mode.ts

@@ -48,7 +48,10 @@ export function resolveDbMode(env: NodeJS.ProcessEnv = process.env): DbMode {
  */
 export function resolveDataDir(env: NodeJS.ProcessEnv = process.env): string {
   const override = env.CARTETHYIA_DATA_DIR?.trim();
-  if (override) return override;
+  // Guard against a literal `"undefined"` value: a launcher that stringifies
+  // a missing env var (`String(undefined)`) would otherwise make the gateway
+  // write its state into a folder named `undefined/` in the CWD.
+  if (override && override !== "undefined") return override;
   if (process.platform === "win32") {
     const roaming = env.APPDATA?.trim();
     if (roaming) return join(roaming, "Cartethyia");

package/src/persistence/dialect.ts

@@ -16,6 +16,7 @@
 import { sql, type SQL } from "drizzle-orm";
 import { SQLiteBunSession } from "drizzle-orm/bun-sqlite";
 import { resolveDbMode } from "./db-mode";
+import { providerAccounts } from "./schema";
 
 /** True when the running backend is the embedded SQLite database. */
 export function sqliteDialect(): boolean {
@@ -67,6 +68,23 @@ export function isSqliteDatabase(database: unknown): boolean {
   return hasSqliteDialect(database);
 }
 
+/**
+ * The `EXISTS` subquery for "the column's cooldown object has an entry whose
+ * ISO deadline is still in the future". The JSON check is dialect-specific:
+ * PostgreSQL uses `jsonb_each_text` (with a shape guard), SQLite `json_each`
+ * on its `text` column (D07). Timestamps are stored as ISO strings on both
+ * backends, so the lexical comparison against `nowIso` is stable.
+ *
+ * Callers keep their own scoping around this fragment — a tenant path must
+ * never touch `tenant_id IS NULL` rows, and the global path must only touch
+ * them — so only the shared JSON subquery lives here.
+ */
+export function liveModelCooldownExistsSql(database: unknown, nowIso: string): SQL {
+  return isSqliteDatabase(database)
+    ? sql`EXISTS (SELECT 1 FROM json_each(${providerAccounts.modelCooldowns}) AS entry WHERE json_valid(${providerAccounts.modelCooldowns}) AND json_type(${providerAccounts.modelCooldowns}) = 'object' AND entry.value > ${nowIso})`
+    : sql`EXISTS (SELECT 1 FROM jsonb_each_text(${providerAccounts.modelCooldowns}) AS entry WHERE jsonb_typeof(${providerAccounts.modelCooldowns}) = 'object' AND entry.value > ${nowIso})`;
+}
+
 /**
  * The per-model cooldown object with every entry whose timestamp has passed
  * removed, or `'{}'` when nothing remains.

package/src/persistence/migrate.ts

@@ -25,11 +25,14 @@ export function resolveMigrationsFolder(): string {
   return folder;
 }
 
-export function migrationFiles(folder: string): readonly string[] {
+export function migrationFileIds(folder: string): readonly string[] {
   return readdirSync(folder)
     .filter((file) => /^\d{4}_.+\.sql$/.test(file))
-    .sort()
-    .map((file) => resolve(folder, file));
+    .sort();
+}
+
+export function migrationFiles(folder: string): readonly string[] {
+  return migrationFileIds(folder).map((file) => resolve(folder, file));
 }
 
 export function migrationIdFor(file: string): string {

package/src/persistence/schema.ts

@@ -309,6 +309,14 @@ export const providerAccounts = pgTable("provider_accounts", {
    * to an account that may well be refused.
    */
   quotaPlan: text("quota_plan"),
+  /**
+   * When `quota_plan` was last written by a successful quota read.
+   *
+   * The plan column is a bare string with no timestamp, so routing cannot tell
+   * a fresh plan from one recorded weeks ago. With the freshness horizon, a
+   * stale plan is downgraded to `unknown` instead of being trusted blindly.
+   */
+  quotaPlanFetchedAt: timestamp("quota_plan_fetched_at", { withTimezone: true }),
   /**
    * The last successful quota read for this account, as a JSON snapshot.
    *
@@ -808,6 +816,12 @@ export const providerRoutingSettings = pgTable(
     // dispatch automatically selects among every active network pool the
     // tenant owns (least-loaded/non-cooldown) — never an admin-pinned pool.
     skipProxy: boolean("skip_proxy").notNull().default(false),
+    // How device-code OAuth flows (start + poll) choose their egress:
+    // 'random' (default) routes them through a randomly selected active
+    // network pool so the upstream sees a rotating IP (avoids "multiple codes
+    // from one IP" detection for Cursor/Grok/device-code providers); 'direct'
+    // always dials direct egress.
+    deviceFlowProxy: text("device_flow_proxy").$type<DeviceFlowProxyMode>().notNull().default("random"),
   },
   (table) => ({
     tenantProviderUnique: uniqueIndex("provider_routing_settings_tenant_provider_idx").on(
@@ -827,6 +841,9 @@ export const poolRoutingStrategy = pgEnum("pool_routing_strategy", [
 ]);
 export type PoolRoutingStrategy = (typeof poolRoutingStrategy.enumValues)[number];
 
+/** Egress mode for device-code OAuth flows: random active pool, or direct. */
+export type DeviceFlowProxyMode = "random" | "direct";
+
 /**
  * Per-tenant selection strategy across the tenant's active network pools —
  * the pool-group counterpart to `provider_routing_settings`. `least_loaded`

package/src/persistence/ttl-cache.ts

@@ -1,4 +1,4 @@
-import { dedupeRequest } from "../network/deduplication";
+import { dedupeRequest } from "../network/util/dedupe";
 /**
  * Bounded TTL cache with automatic eviction.
  *
@@ -11,6 +11,12 @@ interface TtlCacheOptions {
   readonly ttlMs?: number;
   readonly maxEntries?: number;
   readonly now?: () => number;
+  /**
+   * LRU eviction order. When set, re-setting an existing key moves it to the
+   * newest position (delete-then-set), so oldest-first eviction becomes
+   * least-recently-used-first. Off by default: plain FIFO insertion order.
+   */
+  readonly lru?: boolean;
 }
 
 interface TtlCacheEntry<T> {
@@ -27,11 +33,13 @@ export class TtlCache<T> {
   private readonly ttlMs: number;
   private readonly maxEntries: number;
   private readonly now: () => number;
+  private readonly lru: boolean;
 
   constructor(opts: TtlCacheOptions = {}) {
     this.ttlMs = opts.ttlMs ?? 5_000;
     this.maxEntries = opts.maxEntries ?? 128;
     this.now = opts.now ?? Date.now;
+    this.lru = opts.lru ?? false;
   }
 
   /**
@@ -54,10 +62,21 @@ export class TtlCache<T> {
    */
   set(key: string, value: T): void {
     const now = this.now();
+    if (this.lru) this.cache.delete(key); // move to newest position
     this.cache.set(key, { value, at: now });
     this.evictIfNeeded(now);
   }
 
+  /**
+   * Peek at a stored value without checking the TTL or deleting on expiry.
+   * Returns only undefined when the key is absent. Callers that need the
+   * possibly-expired value (e.g. a stale fallback after a failed refetch)
+   * must read it before `get`, which removes expired entries.
+   */
+  peek(key: string): T | undefined {
+    return this.cache.get(key)?.value;
+  }
+
   /**
    * Delete a specific key.
    */
@@ -144,8 +163,7 @@ interface TtlCacheFamilyOptions {
 /**
  * A set of {@link TtlCache} instances keyed by TTL, created on first use.
  *
- * Two provider-side caches (`operations/provider-version-cache.ts` and
- * `operations/model-discovery-cache.ts`) had each hand-rolled the same
+ * Two provider-side caches in `operations/provider-caches.ts` had each hand-rolled the same
  * `Map<number, TtlCache<T>>` + `cacheFor(ttlMs)` memo plus the same
  * `for (const cache of caches.values()) cache.clear()` reset. Tests pass
  * `ttlMs: 0` to force a reload, which is why the per-TTL split exists at all —

package/src/protocol/codecs.ts

@@ -14,7 +14,7 @@ import type { CanonicalStopReason, CanonicalTerminalEvent, UsageRecord } from ".
 import { type WireFamily } from "./canonical-model";
 import type { GenerationControls } from "./canonical-model";
 import { BASE_PROTECTED_HEADERS, HEADER_CONTROL, HEADER_TOKEN } from "../security/outbound-headers";
-import { unwrapProviderToken } from "../providers/provider-credential-envelope";
+import { unwrapProviderToken } from "../providers/provider-credentials";
 
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder();
@@ -91,6 +91,63 @@ export function hash32(input: string): number {
 
 const CLAUDE_TOOL_PREFIX = "_";
 
+/**
+ * Per-request tool-name rename map, mirroring the two-way alias pattern the
+ * OpenCode free-tier fingerprint uses: a caller tool whose name collides with
+ * an upstream-reserved name (or with the built-in prefix) travels under an
+ * alias, and the response side restores the caller's original name.
+ *
+ * The map is a bag of `{ sent, original }` pairs so a provider can rename at
+ * build time and restore at decode time without guessing from a fixed prefix
+ * (a fixed prefix collides when a caller already uses it — `_bash` from a
+ * caller named `bash` vs a caller already named `_bash`).
+ */
+export interface ToolNameAlias {
+  /** Name sent to the upstream wire. */
+  readonly sent: string;
+  /** Caller's original name; restore to this on the way back. */
+  readonly original: string;
+}
+
+/** Restore a sent name to the caller's original, when it was renamed. */
+export function restoreAliasedToolName(
+  sent: string,
+  aliases: ReadonlyArray<ToolNameAlias>,
+): string {
+  for (const alias of aliases) {
+    if (alias.sent === sent) return alias.original;
+  }
+  return sent;
+}
+
+/**
+ * Registry of per-request tool renames, keyed by the canonical request object
+ * (the same object the builder saw and the decoder receives). This is the
+ * transport-agnostic way to pair `encodeWireRequest` with `decodeWireResponse`
+ * without threading a new parameter through every adapter: a request records
+ * its aliases at build time, and any decoder that still has the request can
+ * restore the caller's original tool names exactly.
+ *
+ * The WeakMap keeps no lifetime: entries die with the request object.
+ */
+const toolAliasesByRequest = new WeakMap<object, readonly ToolNameAlias[]>();
+
+/** Record the rename map a request produced. Idempotent per request. */
+export function recordToolAliases(request: object, aliases: readonly ToolNameAlias[]): void {
+  if (aliases.length === 0) return;
+  toolAliasesByRequest.set(request, aliases);
+}
+
+/** Read the rename map a request recorded, if any. */
+export function toolAliasesFor(request: object): readonly ToolNameAlias[] {
+  return toolAliasesByRequest.get(request) ?? [];
+}
+
+/** Restore a tool name exactly from the request's recorded renames. */
+export function restoreToolNameFor(request: object, sent: string): string {
+  return restoreAliasedToolName(sent, toolAliasesFor(request));
+}
+
 export type ClaudeWireObject = Record<string, unknown>;
 
 /**
@@ -366,7 +423,7 @@ function sanitizeSchemaWalk(value: unknown, walk: RewriteWalk): unknown {
 
 // OAuth tool-name prefixing
 
-const ANTHROPIC_BUILTIN_TOOL_NAMES = new Set([
+export const ANTHROPIC_BUILTIN_TOOL_NAMES = new Set([
   "web_search",
   "web_fetch",
   "code_execution",

package/src/protocol/dsml.ts

@@ -8,6 +8,7 @@
  * - CodeBuddy emits strict blocks (`<｜DSML｜ calls>…</｜DSML｜ calls>`)
  *   that must be parsed exactly, with declared-tool allowlisting.
  */
+import { MarkupStreamParser } from "./markup-stream-parser";
 export interface DsmlToolCall {
   readonly id: string;
   readonly name: string;
@@ -74,102 +75,49 @@ interface DsmlParseResult {
  * With no allowlist the generic name rule applies; with one, undeclared names
  * reject the whole block. The caller feeds chunks with `push` and drains the
  * tail with `flush`.
+ *
+ * The stateful prefix-buffer loop is the shared {@link MarkupStreamParser}
+ * scaffold; this class supplies the DSML grammar as a thin configuration.
  */
 export class DsmlStreamParser {
-  readonly #separators: readonly string[];
-  readonly #blockNames: readonly string[];
-  readonly #openers: readonly string[];
-  readonly #allowedNames: ReadonlySet<string>;
-  readonly #params: "json" | "string";
-  readonly #sortKeys: boolean;
-  readonly #maxBlockBytes: number;
-  readonly #id: (call: { readonly name: string }, index: number, seq: number) => string;
-  #pending = "";
-  #callSequence = 0;
+  readonly #parser: MarkupStreamParser<DsmlToolCall>;
 
   constructor(options: DsmlParseOptions = {}) {
-    this.#separators = options.separators ?? DEFAULT_SEPARATORS;
-    this.#blockNames = options.blockNames ?? DEFAULT_BLOCK_NAMES;
-    this.#openers = openers(this.#separators, this.#blockNames);
-    this.#allowedNames = options.allowedNames ?? new Set();
-    this.#params = options.params ?? "json";
-    this.#sortKeys = options.sortKeys ?? true;
-    this.#maxBlockBytes = options.maxBlockBytes ?? DEFAULT_MAX_BLOCK_BYTES;
-    this.#id = options.id ?? sequentialId;
+    const separators = options.separators ?? DEFAULT_SEPARATORS;
+    const blockNames = options.blockNames ?? DEFAULT_BLOCK_NAMES;
+    const allowedNames = options.allowedNames ?? new Set();
+    const params = options.params ?? "json";
+    const sortKeys = options.sortKeys ?? true;
+    const maxBlockBytes = options.maxBlockBytes ?? DEFAULT_MAX_BLOCK_BYTES;
+    const id = options.id ?? sequentialId;
+    this.#parser = new MarkupStreamParser<DsmlToolCall>({
+      openers: openers(separators, blockNames),
+      classifyOpener: (_pending, _index, opener) => {
+        const separator = separators.find((value) => opener.startsWith(`<${value}DSML`));
+        const blockName = blockNames.find((value) => opener.endsWith(` ${value}>`));
+        if (separator === undefined || blockName === undefined) return { kind: "literal" };
+        const close = `</${separator}DSML${separator} ${blockName}>`;
+        return {
+          kind: "found",
+          closer: close,
+          parse: (block) =>
+            parseStrictBlock(block, opener, close, separator, allowedNames, params, sortKeys),
+          callId: (call, index, seq) => ({ ...call, id: id(call, index, seq) }),
+        };
+      },
+      onUnclosed: (pending, openIndex) =>
+        pending.length - openIndex > maxBlockBytes
+          ? { kind: "passThrough" }
+          : "hold",
+    });
   }
 
   push(chunk: string): DsmlParseResult {
-    this.#pending += chunk;
-    let cursor = 0;
-    let visible = "";
-    const calls: DsmlToolCall[] = [];
-    for (;;) {
-      let openIndex = -1;
-      let opener = "";
-      for (const candidate of this.#openers) {
-        const index = this.#pending.indexOf(candidate, cursor);
-        if (index >= 0 && (openIndex < 0 || index < openIndex)) {
-          openIndex = index;
-          opener = candidate;
-        }
-      }
-      if (openIndex < 0) {
-        const safeEnd = this.#settledEnd(cursor);
-        visible += this.#pending.slice(cursor, safeEnd);
-        cursor = safeEnd;
-        break;
-      }
-      visible += this.#pending.slice(cursor, openIndex);
-      const separator = this.#separators.find((value) => opener.startsWith(`<${value}DSML`));
-      const blockName = this.#blockNames.find((value) => opener.endsWith(` ${value}>`));
-      if (separator === undefined || blockName === undefined) {
-        visible += "<";
-        cursor = openIndex + 1;
-        continue;
-      }
-      const close = `</${separator}DSML${separator} ${blockName}>`;
-      const closeIndex = this.#pending.indexOf(close, openIndex + opener.length);
-      if (closeIndex < 0) {
-        // An unclosed block past the cap is not markup — pass it through as
-        // text instead of buffering it indefinitely. Same fail-open as
-        // `feed()` in the reference bridge's `MAX_BLOCK_BYTES` guard.
-        if (this.#pending.length - openIndex > this.#maxBlockBytes) {
-          visible += this.#pending.slice(openIndex);
-          cursor = this.#pending.length;
-          break;
-        }
-        cursor = openIndex;
-        break;
-      }
-      const end = closeIndex + close.length;
-      const block = this.#pending.slice(openIndex, end);
-      const parsed = parseStrictBlock(block, opener, close, separator, this.#allowedNames, this.#params, this.#sortKeys);
-      if (parsed === undefined) visible += block;
-      else {
-        parsed.forEach((call, index) => {
-          calls.push({ ...call, id: this.#id(call, index, this.#callSequence++) });
-        });
-      }
-      cursor = end;
-    }
-    this.#pending = this.#pending.slice(cursor);
-    return { text: visible, calls };
+    return this.#parser.push(chunk);
   }
 
   flush(): DsmlParseResult {
-    const text = this.#pending;
-    this.#pending = "";
-    return { text, calls: [] };
-  }
-
-  #settledEnd(start: number): number {
-    const remaining = this.#pending.slice(start);
-    const maxOpener = this.#openers.reduce((max, opener) => Math.max(max, opener.length - 1), 0);
-    for (let length = Math.min(maxOpener, remaining.length); length > 0; length -= 1) {
-      const suffix = remaining.slice(-length);
-      if (this.#openers.some((opener) => opener.startsWith(suffix))) return this.#pending.length - length;
-    }
-    return this.#pending.length;
+    return this.#parser.flush();
   }
 }