cartethyia 2.7.9 → 2.8.1

package/src/transport/request/preparer.ts

@@ -5,7 +5,7 @@ import type { ApiKeyAdmissionService } from "../../security/admission/service";
 import type { VisionHandoffCall, VisionHandoffResult } from "../vision-handoff";
 import { isImageOrPlaceholderPart, lastImageCarryingUserTurnIndex } from "../vision-handoff";
 import type { CallerIdentity } from "../../security/access-control";
-import type { RouteCandidate as RouteCandidate, InMemoryRouteSnapshotService, RoutePlan } from "../routing/route-model";
+import type { RouteCandidate as RouteCandidate, InMemoryRouteSnapshotService, RoutePlan, RouteSnapshot } from "../routing/route-model";
 import type { RouteContinuationAffinity } from "../routing/route-model";
 import { resolveAliasTarget, type RoutingEngine } from "../routing/router";
 import { projectForRoute, routeCapabilitiesFor, deriveRequiredCapabilities } from "../../protocol/translation/capabilities";
@@ -80,7 +80,17 @@ function replaceImagePartsWithText(
     }
     const hasImage = message.content.some(isImageOrPlaceholderPart);
     if (!hasImage) return message;
-    return { ...message, content: message.content.filter((part) => !isImageOrPlaceholderPart(part)) };
+    // Never delete images silently (proposal Option E): replace a dropped
+    // older image with a marker so the main model at least knows something
+    // was there, instead of the loss being invisible.
+    return {
+      ...message,
+      content: message.content.flatMap((part) =>
+        isImageOrPlaceholderPart(part)
+          ? [{ kind: "text" as const, text: "[image omitted]" }]
+          : [part],
+      ),
+    };
   });
   const unchangedMessages = nextMessages.every(
     (message, i) => message === request.messages[i],
@@ -350,6 +360,61 @@ export class ProxyRequestPreparer {
 
   constructor(private readonly deps: ProxyRequestPreparerDeps) {}
 
+  /**
+   * The key's model-admission gate, shared by the canonical and native
+   * preparation paths: CLI-mapping eligibility → alias resolution → the
+   * model allowlist → the model-prefix gate, in that exact order. Rejects
+   * with the same `model_not_allowed` 403s (same code, status, message, and
+   * detail fields) on both paths, so a policy change here cannot silently
+   * split admission between the chat and native surfaces. Returns the state
+   * the gate computed that the caller still needs for routing: the resolved
+   * alias target and whether CLI mappings were eligible.
+   */
+  #resolveAliasAndGateModel(
+    model: string,
+    authorization: ResolvedApiKey,
+    clientUserAgent: string | undefined,
+    snapshot: RouteSnapshot,
+  ): { readonly resolvedTarget: string; readonly allowCliMappings: boolean } {
+    // Scope opts the key into the mapping table; the User-Agent decides whether
+    // *this* request may consume it. Without the UA gate, a Claude→DeepSeek
+    // remap would also rewrite a non-Claude caller that named `opus`.
+    const allowCliMappings = allowsCliToolMappings(authorization.scopes, {
+      ...(clientUserAgent === undefined ? {} : { userAgent: clientUserAgent }),
+    });
+    // CLI source→target mappings are an explicit API-key capability. Ordinary
+    // tenant aliases remain available to every key; only selected keys may
+    // consume the CLI mapping table.
+    const resolvedTarget = resolveAliasTarget(
+      snapshot,
+      authorization.tenantId,
+      model,
+      allowCliMappings,
+      authorization.cliMappingOwnerId ?? authorization.id,
+    );
+    // Pass `model` as the requested name so an allowlisted alias / a CLI
+    // remapping can authorize the resolved target (see modelRejectionReason).
+    const allowedForKey = isModelAllowed(authorization.snapshot, resolvedTarget, undefined, model);
+    if (
+      authorization.modelPrefix &&
+      !model.startsWith(authorization.modelPrefix) &&
+      !resolvedTarget.startsWith(authorization.modelPrefix) &&
+      !allowedForKey
+    )
+      throw new GatewayError(
+        "model_not_allowed",
+        403,
+        `This key may only use models starting with '${authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
+        { model, required_prefix: authorization.modelPrefix },
+      );
+    if (!allowedForKey) {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
+        model,
+      });
+    }
+    return { resolvedTarget, allowCliMappings };
+  }
+
   /** Injects the vision-handoff runner (called once from boot wiring). */
   bindVisionHandoff(
     runner: (input: VisionHandoffCall) => Promise<readonly VisionHandoffResult[]>,
@@ -391,47 +456,12 @@ export class ProxyRequestPreparer {
         ? initialRequest
         : withThinkingSuffixIntent({ ...initialRequest, model: bareModel }, thinkingIntent);
     const snapshot = await this.deps.snapshotService.getSnapshot();
-    // Scope opts the key into the mapping table; the User-Agent decides whether
-    // *this* request may consume it. Without the UA gate, a Claude→DeepSeek
-    // remap would also rewrite a non-Claude caller that named `opus`.
-    const allowCliMappings = allowsCliToolMappings(authorization.scopes, {
-      ...(input.clientUserAgent === undefined ? {} : { userAgent: input.clientUserAgent }),
-    });
-    // CLI source→target mappings are an explicit API-key capability. Ordinary
-    // tenant aliases remain available to every key; only selected keys may
-    // consume the CLI mapping table.
-    const resolvedTarget = resolveAliasTarget(
-      snapshot,
-      authorization.tenantId,
-      request.model,
-      allowCliMappings,
-      authorization.cliMappingOwnerId ?? authorization.id,
-    );
-    // Pass `request.model` as the requested name so an allowlisted alias / a
-    // CLI remapping can authorize the resolved target (see modelRejectionReason).
-    const allowedForKey = isModelAllowed(
-      authorization.snapshot,
-      resolvedTarget,
-      undefined,
+    const { allowCliMappings } = this.#resolveAliasAndGateModel(
       request.model,
+      authorization,
+      input.clientUserAgent,
+      snapshot,
     );
-    if (
-      authorization.modelPrefix &&
-      !request.model.startsWith(authorization.modelPrefix) &&
-      !resolvedTarget.startsWith(authorization.modelPrefix) &&
-      !allowedForKey
-    )
-      throw new GatewayError(
-        "model_not_allowed",
-        403,
-        `This key may only use models starting with '${authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
-        { model: request.model, required_prefix: authorization.modelPrefix },
-      );
-    if (!allowedForKey) {
-      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
-        model: request.model,
-      });
-    }
     // An inline image that cannot survive the upstream is dropped here rather
     // than dispatched: a provider rejects the whole request for one corrupt
     // attachment, and the buddy family reports it with no field named, so the
@@ -474,6 +504,7 @@ export class ProxyRequestPreparer {
           allowCliMappings,
           authorization.cliMappingOwnerId ?? authorization.id,
           continuationAffinity,
+          request.conversation_id ?? request.conversation?.conversation_id,
         );
       } catch (error) {
         // `plan()` collapses "no candidate supports this capability" into
@@ -541,6 +572,7 @@ export class ProxyRequestPreparer {
                   allowCliMappings,
                   authorization.cliMappingOwnerId ?? authorization.id,
                   continuationAffinity,
+                  request.conversation_id ?? request.conversation?.conversation_id,
                 );
                 plan = handoffPlan;
                 variantRequest = replaced;
@@ -725,42 +757,18 @@ export class ProxyRequestPreparer {
     readonly clientUserAgent?: string;
     readonly eligible: (candidate: RouteCandidate) => boolean;
     readonly emptyMessage: string;
+    /** Session identity for sticky routing (conversation id when present). */
+    readonly conversationId?: string;
   }): Promise<PreparedNativeRequest> {
     if (input.signal?.aborted)
       throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
     const snapshot = await this.deps.snapshotService.getSnapshot();
-    const allowCliMappings = allowsCliToolMappings(input.authorization.scopes, {
-      ...(input.clientUserAgent === undefined ? {} : { userAgent: input.clientUserAgent }),
-    });
-    const resolvedTarget = resolveAliasTarget(
-      snapshot,
-      input.authorization.tenantId,
-      input.model,
-      allowCliMappings,
-      input.authorization.cliMappingOwnerId ?? input.authorization.id,
-    );
-    const allowedForKey = isModelAllowed(
-      input.authorization.snapshot,
-      resolvedTarget,
-      undefined,
+    const { allowCliMappings } = this.#resolveAliasAndGateModel(
       input.model,
+      input.authorization,
+      input.clientUserAgent,
+      snapshot,
     );
-    if (
-      input.authorization.modelPrefix &&
-      !input.model.startsWith(input.authorization.modelPrefix) &&
-      !resolvedTarget.startsWith(input.authorization.modelPrefix) &&
-      !allowedForKey
-    )
-      throw new GatewayError(
-        "model_not_allowed",
-        403,
-        `This key may only use models starting with '${input.authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
-        { model: input.model, required_prefix: input.authorization.modelPrefix },
-      );
-    if (!allowedForKey)
-      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
-        model: input.model,
-      });
     const plan = await this.deps.routingEngine.plan(
       input.model,
       snapshot,
@@ -768,6 +776,8 @@ export class ProxyRequestPreparer {
       undefined,
       allowCliMappings,
       input.authorization.cliMappingOwnerId ?? input.authorization.id,
+      undefined,
+      input.conversationId,
     );
     if (input.signal?.aborted)
       throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");

package/src/transport/routing/bounded-lru.ts

@@ -1,5 +1,19 @@
 // Bounded LRU map: the one shared implementation for routing-layer caches.
 
+/**
+ * Evicts the oldest-inserted entry while `map.size > cap`. The shared
+ * insertion-order bound for caches whose read path must not refresh recency
+ * (unlike `BoundedLruMap`, whose `get` does). Eviction is one `keys().next()`
+ * and no bookkeeping arrays.
+ */
+export function evictOldestEntry<K>(map: Map<K, unknown>, cap: number): void {
+  while (map.size > cap) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
 /**
  * A capacity-bounded LRU `Map`.
  *

package/src/transport/routing/drain-reserve.ts

@@ -0,0 +1,129 @@
+// Drain urgency and reserve scoring for candidate ordering.
+//
+// Ported from oh-my-pi's `windowRequiredDrain` and reserve semantics
+// (`packages/ai/src/auth/usage-report.ts`, `policy.ts`): within the same rank
+// group, an account whose remaining quota is about to expire unused should be
+// burned first ("use it or lose it"), and an account parked in reserve (at or
+// below the reserve percent) should yield to non-reserve siblings.
+import {
+  totalRemainingPercent,
+  type ProviderQuotaWindow,
+} from "../../providers/quota/quota-contracts";
+
+/** Minimum time before reset that still counts as "some headroom" (1 minute). */
+const MIN_REMAINING_MS = 60_000;
+
+/** Usable fraction of a window: 0..1, with 0.5 neutral when unmeasured. */
+function usedFraction(window: ProviderQuotaWindow): number {
+  const used = window.usedPercent;
+  if (typeof used === "number" && Number.isFinite(used)) {
+    return Math.min(1, Math.max(0, used / 100));
+  }
+  const remaining = window.remainingPercent;
+  if (typeof remaining === "number" && Number.isFinite(remaining)) {
+    return Math.min(1, Math.max(0, 1 - remaining / 100));
+  }
+  if (typeof window.used === "number" && Number.isFinite(window.used)) {
+    if (typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0) {
+      return Math.min(1, Math.max(0, window.used / window.limit));
+    }
+  }
+  if (typeof window.remaining === "number" && Number.isFinite(window.remaining)) {
+    if (typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0) {
+      return Math.min(1, Math.max(0, 1 - window.remaining / window.limit));
+    }
+  }
+  return 0.5;
+}
+
+/** Reset instant (epoch ms) for a window, or undefined when it has no clock. */
+function resetAtMs(window: ProviderQuotaWindow): number | undefined {
+  if (window.resetsAt === null || window.resetsAt === undefined) return undefined;
+  const at = Date.parse(window.resetsAt);
+  return Number.isFinite(at) ? at : undefined;
+}
+
+/**
+ * Drain score for the most-urgent relevant window: headroom fraction divided by
+ * remaining hours until reset. Higher means quota that is about to expire
+ * unused and should be burned first. Returns 0 when no window carries usable
+ * evidence (the candidate is neutral, never penalized).
+ */
+export function drainScore(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  nowMs = Date.now(),
+): number {
+  if (windows === undefined || windows.length === 0) return 0;
+  let best = 0;
+  for (const window of windows) {
+    const headroom = 1 - usedFraction(window);
+    if (headroom <= 0) continue;
+    const resetAt = resetAtMs(window);
+    const durationMs = windowAccountingDurationMs(window);
+    let remainingMs = resetAt === undefined ? (durationMs ?? MIN_REMAINING_MS) : resetAt - nowMs;
+    if (durationMs !== undefined && durationMs > 0) {
+      remainingMs = Math.min(remainingMs, durationMs);
+    }
+    const remainingHours = Math.max(remainingMs, MIN_REMAINING_MS) / (60 * 60 * 1000);
+    best = Math.max(best, headroom / remainingHours);
+  }
+  return best;
+}
+
+function windowAccountingDurationMs(window: ProviderQuotaWindow): number | undefined {
+  // Providers state window durations in the kind label (e.g. "5h", "7d") when
+  // they do not carry an explicit duration field. Parse the common spellings;
+  // an unparseable label contributes no clock.
+  const text = `${window.kind} ${window.label}`.toLowerCase();
+  const m = /(\d+(?:\.\d+)?)\s*(h|hour|hr|d|day|m|min|minute|s|sec|second)\b/.exec(text);
+  if (!m) return undefined;
+  const value = Number(m[1]);
+  if (!Number.isFinite(value)) return undefined;
+  const unit = m[2];
+  if (unit === "h" || unit === "hour" || unit === "hr") return value * 60 * 60 * 1000;
+  if (unit === "d" || unit === "day") return value * 24 * 60 * 60 * 1000;
+  if (unit === "m" || unit === "min" || unit === "minute") return value * 60 * 1000;
+  if (unit === "s" || unit === "sec" || unit === "second") return value * 1000;
+  return undefined;
+}
+
+/**
+ * The account's remaining fraction (0..1) across its pooled credit and
+ * independent windows, or undefined when nothing is measured. Mirrors
+ * `totalRemainingPercent` (the router's existing aggregate) but normalized to a
+ * 0..1 fraction.
+ */
+export function remainingFraction(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+): number | undefined {
+  if (windows === undefined || windows.length === 0) return undefined;
+  const percent = totalRemainingPercent(windows);
+  if (percent === null) return undefined;
+  return Math.min(1, Math.max(0, percent / 100));
+}
+
+/** True when the account's remaining fraction is at or below the reserve percent. */
+export function isInReserve(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  reservePct: number,
+): boolean {
+  if (reservePct <= 0) return false;
+  const fraction = remainingFraction(windows);
+  if (fraction === undefined) return false;
+  return fraction * 100 <= reservePct;
+}
+
+/**
+ * True when a reserved account has healed above the reclaim threshold and may be
+ * reclaimed to full priority.
+ */
+export function isReclaimReady(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  reservePct: number,
+  reclaimAbovePct: number,
+): boolean {
+  if (reservePct <= 0 || reclaimAbovePct <= reservePct) return false;
+  const fraction = remainingFraction(windows);
+  if (fraction === undefined) return false;
+  return fraction * 100 >= reclaimAbovePct;
+}

package/src/transport/routing/plan-gate.ts

@@ -17,7 +17,13 @@
  * costs one refused request that the cooldown machinery already handles; a
  * wrong paid match silently blackholes a model.
  */
-const FREE_PLAN_MARKERS: readonly string[] = ["free"];
+/**
+ * The marker set that proves a plan string is free. Exported so every
+ * free-plan consumer — the routing plan gate here and the cooldown-tier
+ * derivation in `account-tier.ts` — reads the same list, so the two cannot
+ * drift apart about an account.
+ */
+export const FREE_PLAN_MARKERS: readonly string[] = ["free"];
 
 export function isFreePlanAccount(plan: string | null | undefined): boolean {
   if (plan === null || plan === undefined) return false;

package/src/transport/routing/round-robin.ts

@@ -36,3 +36,63 @@ const MAX_ROUND_ROBIN_ENTRIES = 1000;
 export function createRoundRobinMap(): BoundedLruMap<string, RoundRobinState> {
   return new BoundedLruMap<string, RoundRobinState>(MAX_ROUND_ROBIN_ENTRIES);
 }
+
+/** One session's sticky account: which provider account last served it, and when. */
+export interface StickySession {
+  readonly accountId: string;
+  readonly lastUsedAtMs: number;
+  /** Set only by an explicit operator pin; automatic warm stickiness leaves it absent. */
+  readonly explicit?: true;
+}
+
+/**
+ * Session → account stickiness per provider, bounded by an LRU. Used by the
+ * router to prefer the account that last served a session within the warm
+ * window — prompt-cache warmth is worth more than perfect load balance. A
+ * session id that is absent, evicted, or past the warm window simply carries
+ * no preference.
+ */
+export class StickySessionStore {
+  private readonly byProvider = new Map<string, BoundedLruMap<string, StickySession>>();
+
+  constructor(private readonly maxSessionsPerProvider: number) {}
+
+  private mapFor(providerId: string): BoundedLruMap<string, StickySession> {
+    let map = this.byProvider.get(providerId);
+    if (map === undefined) {
+      map = new BoundedLruMap<string, StickySession>(this.maxSessionsPerProvider);
+      this.byProvider.set(providerId, map);
+    }
+    return map;
+  }
+
+  /** The account last pinned to this session, or undefined. */
+  get(providerId: string, sessionId: string | undefined): StickySession | undefined {
+    if (sessionId === undefined) return undefined;
+    return this.mapFor(providerId).get(sessionId);
+  }
+
+  /** Record that `accountId` served `sessionId` now (or pin it explicitly). */
+  set(providerId: string, sessionId: string | undefined, accountId: string, explicit = false): void {
+    if (sessionId === undefined) return;
+    const now = Date.now();
+    this.mapFor(providerId).set(sessionId, {
+      accountId,
+      lastUsedAtMs: now,
+      ...(explicit ? { explicit: true as const } : {}),
+    });
+  }
+
+  /** Drop one session's stickiness (e.g. after the account is invalidated). */
+  clear(providerId: string, sessionId: string | undefined): void {
+    if (sessionId === undefined) return;
+    this.mapFor(providerId).delete(sessionId);
+  }
+
+  /** Total retained sticky entries across providers (for metrics/tests). */
+  size(): number {
+    let total = 0;
+    for (const map of this.byProvider.values()) total += map.size;
+    return total;
+  }
+}