@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/usage/telemetry-contract.ts

@@ -0,0 +1,237 @@
+/**
+ * The telemetry vocabulary both the proxy and the dashboard read.
+ *
+ * This module has NO imports, and that is its entire job. The dashboard is a separate TypeScript
+ * project with `erasableSyntaxOnly`, and a type-only import still pulls the imported file's whole
+ * import graph into that project. Importing these names from `./log` therefore dragged
+ * `node:fs`, `node:crypto` and the config barrel into the browser build, where a parameter
+ * property in `src/config/atomic-write.ts` fails to compile. The names below are the ones a
+ * browser legitimately needs, so they live where a browser can reach them.
+ *
+ * Anything added here must stay free of imports. A contract that acquires a dependency stops
+ * being a contract.
+ */
+
+/**
+ * Recovery kinds recorded per attempt in the usage log; the dashboard renders localized labels
+ * for these wire values.
+ *
+ * The roster is the single statement of this vocabulary and the type is derived from it. It was
+ * written twice once -- as a union and as the read-back whitelist -- and the two are not
+ * interchangeable: a member added only to the union compiles, is written to disk, and is dropped
+ * on the next read, so the row loses the field that says why it recovered. One declaration cannot
+ * drift from itself, and the dashboard now reads this one rather than keeping a third copy.
+ */
+export const ATTEMPT_RECOVERY_KIND_ROSTER = Object.freeze([
+  "transient-5xx",
+  "connection-reset",
+  "oauth-401",
+  "key-401",
+  "key-429",
+  "rate-limit-429",
+  "anthropic-oauth-429",
+  "oauth-account-429",
+  "image-413",
+  "console-go-upload-retry",
+  "opaque-blob-rejection",
+  "empty-completion",
+  "reasoning-effort-downgrade",
+] as const);
+
+export type AttemptRecoveryKind = typeof ATTEMPT_RECOVERY_KIND_ROSTER[number];
+
+/**
+ * Why a recovery this request was otherwise willing to make did not happen.
+ *
+ * Recorded separately from `recoveryKinds` and from `sendCount` because the question it answers
+ * is different from either. A log showing one physical send and no recovery kind used to be
+ * ambiguous: nothing was eligible, or something was and the send budget withheld it. Those need
+ * opposite follow-ups and the second was invisible (#5044).
+ *
+ * `sendCount` deliberately does not move for these. A refused attempt is not a physical send, and
+ * inflating the count to signal the refusal would corrupt the one number that means "requests this
+ * proxy actually made".
+ */
+export const ATTEMPT_RECOVERY_WITHHELD_ROSTER = Object.freeze([
+  "retry-send-budget",
+  "rotation-send-budget",
+] as const);
+
+export type AttemptRecoveryWithheld = typeof ATTEMPT_RECOVERY_WITHHELD_ROSTER[number];
+
+/**
+ * How far a failed exchange got, ordered by how much the DOWNSTREAM CLIENT observed.
+ *
+ * The order is by client observation rather than by upstream progress, because the question it
+ * answers is whether resending can duplicate something the caller already saw. An upstream that
+ * completed a turn we never relayed has committed nothing downstream; an upstream that emitted
+ * one token has.
+ *
+ * The roster lives here rather than beside the resend tables for the reason stated at the top of
+ * this file: the dashboard renders a label per member, and reaching the table module for the
+ * names would drag its import graph into the browser project. `src/lib/request-failure-model.ts`
+ * re-exports it, so every existing importer keeps its path and there is still exactly one
+ * declaration.
+ */
+export const REQUEST_FAILURE_STAGES = Object.freeze([
+  /** No response head exists. Whether the origin began the turn is not known from the stage alone. */
+  "pre-header",
+  /** A status line and headers exist, and no protocol body event has been parsed yet. */
+  "headers-only",
+  /** The protocol body began with control events only -- `response.created`, quota frames. */
+  "protocol-prelude",
+  /** At least one output-bearing event reached the caller. */
+  "semantic-output",
+  /** A tool call or other externally visible effect was emitted. */
+  "side-effect",
+  /** A terminal event settled the turn after its answer reached the caller. */
+  "terminal",
+] as const);
+
+export type RequestFailureStage = typeof REQUEST_FAILURE_STAGES[number];
+
+/**
+ * Why the request failed, as one closed dictionary for every layer.
+ *
+ * Bounded on purpose: these are wire values a maintainer reads and a metric labels by, never a
+ * credential, an account identifier, an upstream body or prompt content. That bound is what lets
+ * the value be a Prometheus label and a grouping key without a masking pass -- a closed roster
+ * has nothing to mask.
+ */
+export const REQUEST_FAILURE_CAUSES = Object.freeze([
+  /** The bytes provably never reached the origin: connect refused, DNS failure, TLS handshake. */
+  "transport-unsent",
+  /** The bytes left and the connection died before a head. The origin may be running the turn. */
+  "transport-ambiguous",
+  /** The origin answered that it would not start the turn now: 503, overloaded, backpressure. */
+  "upstream-declined",
+  /** A 429 rate limit. Capacity is momentarily gone; waiting is the remedy. */
+  "rate-limit",
+  /** Plan or credit quota is gone. Waiting out a retry window does not help; the account must change. */
+  "quota-exhausted",
+  /** Credentials were rejected: 401, 403 on identity. */
+  "credential-rejected",
+  /** The origin evaluated the content and refused it. Identical bytes get the identical refusal. */
+  "policy-refusal",
+  /**
+   * The origin rejected a request PARAMETER rather than the content: an unsupported reasoning
+   * effort, an unknown field. Distinct from `policy-refusal` because the remedy is opposite --
+   * the same content succeeds once the parameter is adjusted.
+   */
+  "parameter-rejected",
+  /** Opaque replay state was rejected as unverifiable. Only a request without it can succeed. */
+  "ciphertext-refusal",
+  /**
+   * The payload exceeded a size the origin accepts. A smaller rebuild of the same turn can
+   * succeed, which is why this is not the same answer as `payload-rejected`.
+   */
+  "payload-too-large",
+  /** The payload was rejected on its merits: unsupported media, malformed part. No repair helps. */
+  "payload-rejected",
+  /**
+   * The origin returned a server-side fault. Whether it had already begun the turn is not
+   * knowable from the status, so this is the honest classification for the mixed 5xx set the
+   * transient layer retries: 503 really did decline, 500 may not have.
+   */
+  "upstream-fault",
+  /** The turn settled carrying no usable output. */
+  "empty-output",
+  /** The caller went away. */
+  "client-cancelled",
+  /** This proxy refused before dispatch: send budget, route policy, replay refusal. */
+  "local-refusal",
+] as const);
+
+export type RequestFailureCause = typeof REQUEST_FAILURE_CAUSES[number];
+
+/**
+ * Whether this proxy may send the request again. Derived at READ time from the stage and the
+ * cause and never persisted, so a stored row cannot carry a verdict that the current table
+ * would no longer reach.
+ *
+ * Every refusal names WHY it refused, because the three reasons need different operator
+ * responses and used to arrive as one undifferentiated "no retry".
+ */
+export const RESEND_PERMISSIONS = Object.freeze([
+  /** The same request may be sent again. */
+  "permitted",
+  /** Only a modified request may be sent: rotated credential, stripped ciphertext. */
+  "permitted-after-repair",
+  /** Upstream execution state is unknown. No AUTOMATIC resend. */
+  "refused-ambiguous",
+  /** The caller already observed output or an externally visible effect. */
+  "refused-committed",
+  /** Identical bytes would get the identical answer. */
+  "refused-futile",
+] as const);
+
+export type ResendPermission = typeof RESEND_PERMISSIONS[number];
+
+/**
+ * Where a terminal or failure was observed on the wire.
+ *
+ * Declared here because three modules read it as a closed set -- the durable row's validator,
+ * the failure attribution and the failure fingerprint -- and a fourth restatement in a test is
+ * how a member added later leaves an "exhaustive" cross product green without exercising it.
+ */
+export const REQUEST_TRANSPORT_PHASES = Object.freeze([
+  "pre_headers",
+  "mid_stream",
+  "terminal_sse",
+] as const);
+
+export type RequestTransportPhase = typeof REQUEST_TRANSPORT_PHASES[number];
+
+/**
+ * What an attempt actually delivered, as five bounded counts (#3983).
+ *
+ * #3983 wanted these signals and emitted one debug line per event to get them. That is a second
+ * durable record: `emitDebugLine` writes the in-process ring AND stderr, and stderr is redirected
+ * to the service log under both launchd and systemd, so an installed service ends up with a
+ * per-event history beside the ledger, carrying its own retention, sequencing and identity. It
+ * also fingerprinted each payload under a process-global random key, which makes every repeated
+ * prompt fragment, tool name and error message correlatable for the process lifetime.
+ *
+ * Counts answer the same questions -- a missing terminal, adapter-to-client loss, empty output,
+ * partial output size -- and cannot carry content at all. They ride the attempt, so they inherit
+ * the ledger's normalization, masking and retention rather than acquiring their own.
+ *
+ * Counted where the event is DELIVERED, not where it is read. An adapter event the client never
+ * received is exactly the discrepancy worth seeing, and counting both ends at the reader would
+ * make the two numbers equal by construction.
+ */
+export interface AttemptDeliverySummary {
+  /** Events this attempt's adapter produced. */
+  adapterEvents: number;
+  /** Frames that reached the client transport, after a successful enqueue. */
+  relayedEvents: number;
+  /** UTF-8 bytes of output-bearing delta actually relayed. Never the content itself. */
+  semanticBytes: number;
+  /** Externally visible effects relayed: a tool call or a search call starting. */
+  sideEffectEvents: number;
+  /** Terminal frames relayed. Zero on a delivered stream is the missing-terminal signal. */
+  terminalEvents: number;
+}
+
+/**
+ * What one logical request spent upstream, decomposed by how much of it is explained.
+ *
+ * The counting half of the durable spend record, without the routing detail that sits beside it.
+ * Every surface that reports a send total reads these three numbers and none of them recomputes a
+ * total of its own -- a recomputed total is how the exporter and the dashboard ended up reporting
+ * different send counts for the same request.
+ */
+export interface RequestSpendTotals {
+  /** Physical upstream sends summed across every attempt, combo children included. */
+  sends: number;
+  /** Sends whose attempt reached a terminal status, so the spend has a known outcome. */
+  settled: number;
+  /**
+   * Sends charged with no terminal outcome behind them: an attempt abandoned mid-flight, or a
+   * budget charge no attempt row ever accounted for. Never folded into `settled` -- an unexplained
+   * send is the exact quantity this record exists to make visible.
+   */
+  unresolved: number;
+  /** Model sends the request execution budget charged. Absent when no budget was attached. */
+  reserved?: number;
+}

package/src/usage/timeline.ts

@@ -0,0 +1,236 @@
+import { cacheTokensFromUsage, usageAttributions } from "./summary";
+import type { PersistedUsageEntry } from "./log";
+import { usageDisplayTotalTokens } from "./totals";
+
+export type TimelineMetric = "total" | "input" | "output" | "cached";
+export type TimelineAggregation = "sum" | "average" | "max";
+export type TimelineGrouping = "model" | "modelAccount";
+export const TIMELINE_HOURS = [6, 24, 72, 168] as const;
+
+export interface TimelineQuery {
+  hours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+  now: number;
+}
+
+export interface TimelineSeries {
+  id: string;
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  total: number;
+  points: number[];
+}
+
+export interface UsageTimeline {
+  appliedFilters: { models: string[] | null; hiddenProviders: string[] };
+  start: number;
+  end: number;
+  bucketSeconds: number;
+  buckets: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  series: TimelineSeries[];
+  availableModels: string[];
+  missingMeasurements: number;
+  truncated: boolean;
+}
+
+const METRICS: readonly TimelineMetric[] = ["total", "input", "output", "cached"];
+const AGGREGATIONS: readonly TimelineAggregation[] = ["sum", "average", "max"];
+const GROUPINGS: readonly TimelineGrouping[] = ["model", "modelAccount"];
+
+function enumValue<T extends string>(value: string | null, values: readonly T[], fallback: T): T | { error: string } {
+  if (value === null || value === "") return fallback;
+  return values.includes(value as T) ? value as T : { error: `invalid value for parameter: ${value}` };
+}
+
+export function isTimelineModelId(value: unknown): value is string {
+  return typeof value === "string" && /^[^/\s]+\/\S+$/.test(value);
+}
+
+function parseModels(raw: string | null): string[] | null | { error: string } {
+  if (raw === null || raw.trim() === "") return null;
+  const models = raw.split(",").map(model => model.trim());
+  if (models.length > 100) return { error: "models must contain at most 100 identifiers" };
+  if (models.some(model => !isTimelineModelId(model))) {
+    return { error: "models must contain provider/model identifiers" };
+  }
+  return [...new Set(models)];
+}
+
+export function parseTimelineQuery(params: URLSearchParams, now: number): TimelineQuery | { error: string } {
+  const rawHours = params.get("hours") ?? "24";
+  const hoursNumber = Number(rawHours);
+  if (!TIMELINE_HOURS.includes(hoursNumber as typeof TIMELINE_HOURS[number])) {
+    return { error: "hours must be one of 6, 24, 72, 168" };
+  }
+  const bucketMinutes = Number(params.get("bucketMinutes") ?? "60");
+  if (!Number.isInteger(bucketMinutes) || bucketMinutes < 1 || bucketMinutes > 1440) {
+    return { error: "bucketMinutes must be an integer from 1 through 1440" };
+  }
+  const buckets = Math.ceil(hoursNumber * 60 / bucketMinutes);
+  if (buckets > 2000) return { error: "timeline bucket count must not exceed 2000" };
+  const metric = enumValue(params.get("metric"), METRICS, "total");
+  if (typeof metric !== "string") return metric;
+  const aggregation = enumValue(params.get("aggregation"), AGGREGATIONS, "sum");
+  if (typeof aggregation !== "string") return aggregation;
+  const grouping = enumValue(params.get("grouping"), GROUPINGS, "model");
+  if (typeof grouping !== "string") return grouping;
+  const models = parseModels(params.get("models"));
+  if (typeof models === "object" && models !== null && "error" in models) return models;
+  const hiddenProviders = params.getAll("hiddenProvider");
+  if (hiddenProviders.length > 100 || hiddenProviders.some(value => !value || /\s/.test(value))) {
+    return { error: "hiddenProvider must contain at most 100 nonblank provider names" };
+  }
+  if (!Number.isFinite(now)) return { error: "now must be finite" };
+  return {
+    hours: hoursNumber as TimelineQuery["hours"],
+    bucketMinutes,
+    metric,
+    aggregation,
+    grouping,
+    models: models as string[] | null,
+    hiddenProviders: [...new Set(hiddenProviders)].sort(),
+    now,
+  };
+}
+
+interface SeriesState {
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  points: number[];
+  requests: Map<number, Map<string, number>>;
+}
+
+function metricValue(metric: TimelineMetric, attribution: ReturnType<typeof usageAttributions>[number]): number | undefined {
+  if (metric === "total") return usageDisplayTotalTokens(attribution.usage, attribution.totalTokens);
+  if (metric === "input") return attribution.usage?.inputTokens;
+  if (metric === "output") return attribution.usage?.outputTokens;
+  return cacheTokensFromUsage(attribution.usage).read;
+}
+
+export function createTimelineAccumulator(query: TimelineQuery): { add(entry: PersistedUsageEntry): void; finish(): UsageTimeline } {
+  const bucketSeconds = query.bucketMinutes * 60;
+  const buckets = Math.ceil(query.hours * 60 / query.bucketMinutes);
+  const end = (Math.floor(query.now / 1000 / bucketSeconds) + 1) * bucketSeconds;
+  const start = end - buckets * bucketSeconds;
+  const startMs = start * 1000;
+  const endMs = end * 1000;
+  const series = new Map<string, SeriesState>();
+  const availableModels = new Set<string>();
+  const hiddenProviders = new Set(query.hiddenProviders);
+  let missingMeasurements = 0;
+
+  function add(entry: PersistedUsageEntry): void {
+    if (entry.timestamp < startMs || entry.timestamp >= endMs) return;
+    const bucket = Math.floor((entry.timestamp - startMs) / (bucketSeconds * 1000));
+    if (bucket < 0 || bucket >= buckets) return;
+    for (const attribution of usageAttributions(entry)) {
+      if (hiddenProviders.has(attribution.provider)) continue;
+      const modelId = `${attribution.provider}/${attribution.model}`;
+      availableModels.add(modelId);
+      if (query.models && !query.models.includes(modelId)) continue;
+      const id = query.grouping === "model"
+        ? modelId
+        : `${modelId} · ${attribution.accountLogLabel ?? "unknown"}`;
+      let state = series.get(id);
+      if (!state) {
+        state = {
+          provider: attribution.provider,
+          model: attribution.model,
+          ...(query.grouping === "modelAccount" ? { accountLogLabel: attribution.accountLogLabel ?? "unknown" } : {}),
+          points: Array<number>(buckets).fill(0),
+          requests: new Map(),
+        };
+        series.set(id, state);
+      }
+      const value = metricValue(query.metric, attribution);
+      if (value === undefined) {
+        missingMeasurements += 1;
+        continue;
+      }
+      if (query.aggregation === "sum") {
+        state.points[bucket] = (state.points[bucket] ?? 0) + value;
+      } else {
+        let requests = state.requests.get(bucket);
+        if (!requests) {
+          requests = new Map();
+          state.requests.set(bucket, requests);
+        }
+        requests.set(attribution.requestId, (requests.get(attribution.requestId) ?? 0) + value);
+      }
+    }
+  }
+
+  function finish(): UsageTimeline {
+    const rows = [...series].map(([id, state]): { row: TimelineSeries; state: SeriesState } => {
+      if (query.aggregation !== "sum") {
+        for (const [bucket, requests] of state.requests) {
+          const values = [...requests.values()];
+          state.points[bucket] = query.aggregation === "max"
+            ? Math.max(...values)
+            : values.reduce((sum, value) => sum + value, 0) / values.length;
+        }
+      }
+      const total = state.points.reduce((sum, value) => sum + value, 0);
+      return {
+        row: {
+          id,
+          provider: state.provider,
+          model: state.model,
+          ...(state.accountLogLabel !== undefined ? { accountLogLabel: state.accountLogLabel } : {}),
+          total,
+          points: state.points,
+        },
+        state,
+      };
+    }).sort((left, right) => right.row.total - left.row.total || left.row.id.localeCompare(right.row.id));
+    const kept = (rows.length > 24 ? rows.slice(0, 23) : rows).map(({ row }) => row);
+    if (rows.length > 24) {
+      const otherPoints = Array<number>(buckets).fill(0);
+      const folded = rows.slice(23);
+      if (query.aggregation === "sum") {
+        for (const { row } of folded) {
+          for (let index = 0; index < buckets; index += 1) otherPoints[index] = (otherPoints[index] ?? 0) + (row.points[index] ?? 0);
+        }
+      } else {
+        for (let index = 0; index < buckets; index += 1) {
+          const values = folded.flatMap(({ state }) => [...(state.requests.get(index)?.values() ?? [])]);
+          if (values.length > 0) {
+            otherPoints[index] = query.aggregation === "max"
+              ? Math.max(...values)
+              : values.reduce((sum, value) => sum + value, 0) / values.length;
+          }
+        }
+      }
+      kept.push({ id: "other", provider: "", model: "other", total: otherPoints.reduce((sum, value) => sum + value, 0), points: otherPoints });
+    }
+    return {
+      appliedFilters: {
+        models: query.models === null ? null : [...new Set(query.models)].sort(),
+        hiddenProviders: [...hiddenProviders].sort(),
+      },
+      start,
+      end,
+      bucketSeconds,
+      buckets,
+      metric: query.metric,
+      aggregation: query.aggregation,
+      grouping: query.grouping,
+      series: kept,
+      availableModels: [...availableModels].sort(),
+      missingMeasurements,
+      truncated: false,
+    };
+  }
+
+  return { add, finish };
+}

package/src/web-search/alpha-search.ts

@@ -14,6 +14,8 @@
 import { formatErrorResponse } from "../bridge";
 import { redactSecretString } from "../lib/redact";
 import { sidecarEnter } from "../lib/sidecar-tracker";
+import { admissionScopeDenial } from "../server/admission-model-scope";
+import type { DataPlaneAdmission } from "../server/auth-cors";
 import type { OcxConfig, OcxProviderConfig, OcxWebSearchSidecarConfig } from "../types";
 import { runAnthropicWebSearch } from "./anthropic-executor";
 import { runExaWebSearch } from "./exa-executor";
@@ -252,6 +254,7 @@ export async function handleAlphaSearchSidecarFallback(
   config: OcxConfig,
   signal?: AbortSignal,
   logCtx?: { provider: string },
+  admission?: DataPlaneAdmission,
 ): Promise<Response> {
   const resolution = resolveAlphaSearchSidecar(config);
   if (resolution.status === "missing-credential") {
@@ -266,6 +269,24 @@ export async function handleAlphaSearchSidecarFallback(
   const resolved = resolution.sidecar;
   if (logCtx) logCtx.provider = resolved.backend;
 
+  // This backend is a paid destination like any other, and the operator's
+  // configuration -- not the caller -- decides which one and which model. A key
+  // scoped away from it must not spend it by asking the search endpoint instead
+  // of the inference one. Exa has no configured provider entry, so its own
+  // backend name is the destination.
+  const settings = sidecarSettingsForAlphaSearch(resolved.backend, config);
+  const requestedModel = (body as { model?: unknown } | null)?.model;
+  const denial = admissionScopeDenial(
+    config,
+    admission,
+    typeof requestedModel === "string" && requestedModel.trim() ? requestedModel : undefined,
+    {
+      providerName: resolved.backend === "exa" ? resolved.backend : resolved.providerName,
+      modelId: settings.model,
+    },
+  );
+  if (denial) return denial;
+
   const queries = extractAlphaSearchQueries(body);
   if (queries.length === 0) {
     return formatErrorResponse(
@@ -275,7 +296,6 @@ export async function handleAlphaSearchSidecarFallback(
     );
   }
 
-  const settings = sidecarSettingsForAlphaSearch(resolved.backend, config);
   const sidecarExit = sidecarEnter("search");
   try {
     const texts: string[] = [];