@opengeni/contracts 3.1.0-canary.2 → 3.1.2

package/src/claude-subscription-usage.ts

@@ -0,0 +1,68 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+export const ClaudeUsageWindowId = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "five_hour",
+    "seven_day",
+    "seven_day_opus",
+    "seven_day_sonnet",
+    "seven_day_overage_included",
+    "overage",
+  ]),
+);
+export const ClaudeUsageWindow = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: ClaudeUsageWindowId,
+      usedPercent: z.number().finite().nonnegative().nullable(),
+      resetsAt: z.string().datetime().nullable(),
+      status: z.enum(["allowed", "allowed_warning", "rejected"]).nullable(),
+      observedAt: z.string().datetime(),
+      source: z.enum(["response_headers", "provider"]).optional(),
+    })
+    .strict(),
+);
+export type ClaudeUsageWindow = z.infer<typeof ClaudeUsageWindow>;
+
+/** One response's dispatch authority; never combine statuses from different responses. */
+export const ClaudeUsageRequestStatus = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      status: z.enum(["allowed", "allowed_warning", "rejected"]).nullable(),
+      resetsAt: z.string().datetime().nullable(),
+      representativeClaim: ClaudeUsageWindowId.nullable(),
+      overageStatus: z.enum(["allowed", "allowed_warning", "rejected"]).nullable(),
+      overageResetsAt: z.string().datetime().nullable(),
+      upstreamModelId: z.string().min(1).max(256).nullable(),
+      observedAt: z.string().datetime(),
+      source: z.enum(["response_headers", "provider"]).optional(),
+    })
+    .strict(),
+);
+export type ClaudeUsageRequestStatus = z.infer<typeof ClaudeUsageRequestStatus>;
+
+/** Provider observations, never an estimate based on Opengeni token counts. */
+export const ClaudeSubscriptionUsage = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      connected: z.boolean(),
+      credentialVersion: z.number().int().positive().nullable(),
+      windows: z.array(ClaudeUsageWindow).max(6),
+      observedAt: z.string().datetime().nullable(),
+      source: z.enum(["response_headers", "provider"]).nullable(),
+      refreshStatus: z.enum([
+        "not_checked",
+        "available",
+        "scope_required",
+        "unavailable",
+        "reconnect",
+      ]),
+      refreshCheckedAt: z.string().datetime().nullable(),
+      requestStatus: ClaudeUsageRequestStatus.nullable().optional(),
+      // Model-scoped dispatch evidence; allowances retain an ordering watermark.
+      requestRestrictions: z.array(ClaudeUsageRequestStatus).max(64).optional(),
+    })
+    .strict(),
+);
+export type ClaudeSubscriptionUsage = z.infer<typeof ClaudeSubscriptionUsage>;

package/src/client-error-report.ts

@@ -0,0 +1,343 @@
+/**
+ * Wire grammar of the web client error beacon (`POST /v1/client-errors`).
+ *
+ * A report is a closed error kind, the matched route PATTERN (never a concrete
+ * URL), the bundle revision, and optional error diagnostics: the error's name,
+ * message and stack, plus React's component stack for a render failure. The
+ * diagnostics are error text, not analytics. They can occasionally contain a
+ * fragment of user content (an error message that quotes a value), so they are
+ * scrubbed of obvious credentials and query strings by
+ * {@link scrubClientErrorText} and bounded per field by
+ * {@link CLIENT_ERROR_DETAIL_MAX_BYTES} in the browser, and the API re-applies
+ * the same projection to whatever it receives. The web client that projects a
+ * report, the API route that admits it, and the public structured-log
+ * projection that prints it all validate against these exact rules, so the
+ * browser can only send what the API accepts and logs.
+ *
+ * The same route also admits the closed operational signals below (requests
+ * that never reached the server, live-stream health, and web vitals). They
+ * follow the same rules: closed values only, a route pattern or page label,
+ * never a URL, message, identifier, or user content.
+ */
+export const CLIENT_ERRORS_PATH = "/v1/client-errors";
+
+export const CLIENT_ERROR_KINDS = [
+  "route_error",
+  "unhandled_rejection",
+  "window_error",
+  "chunk_load",
+] as const;
+export type ClientErrorKind = (typeof CLIENT_ERROR_KINDS)[number];
+
+/**
+ * Largest UTF-8 byte length of each error diagnostic field. A longer value is
+ * cut at the end, so a stack keeps its innermost frames.
+ */
+export const CLIENT_ERROR_DETAIL_MAX_BYTES = {
+  name: 128,
+  message: 1024,
+  stack: 4096,
+  componentStack: 4096,
+} as const;
+export type ClientErrorDetailField = keyof typeof CLIENT_ERROR_DETAIL_MAX_BYTES;
+export const CLIENT_ERROR_DETAIL_FIELDS = Object.keys(
+  CLIENT_ERROR_DETAIL_MAX_BYTES,
+) as ClientErrorDetailField[];
+
+/**
+ * Largest accepted report body. The detail fields total 9,344 bytes; JSON
+ * escaping at most doubles that, which leaves room for the closed fields.
+ */
+export const CLIENT_ERROR_REPORT_MAX_BYTES = 20 * 1024;
+
+const ROUTE_SEGMENT = String.raw`(?:[a-z]+(?:-[a-z]+)*|\$[A-Za-z][A-Za-z0-9]{0,31})`;
+
+/**
+ * A route pattern of at most 160 characters that is `/`, `unknown`, or up to
+ * twelve `/`-separated segments that are each either a lowercase literal
+ * (`variable-sets`) or a `$param` placeholder. The grammar excludes digits in
+ * literals, so a concrete id cannot pass as one.
+ */
+export const CLIENT_ERROR_ROUTE_PATTERN = new RegExp(
+  String.raw`^(?=.{1,160}$)(?:unknown|/|(?:/${ROUTE_SEGMENT}){1,12})$`,
+);
+
+/** The bundle revision token (a commit SHA, `dev`, or `unknown`). */
+export const CLIENT_ERROR_REVISION_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Error diagnostics. Every field is optional and already scrubbed and bounded. */
+export type ClientErrorDetail = Partial<Record<ClientErrorDetailField, string>>;
+
+export type ClientErrorReport = {
+  kind: ClientErrorKind;
+  route: string;
+  revision: string;
+  error?: ClientErrorDetail;
+};
+
+const REDACTED = "[redacted]";
+const TRUNCATED = "…[truncated]";
+
+// Hosts whose error URLs carry the error's arguments in the query string, and
+// nothing else (React's production error decoder links).
+const ERROR_DECODER_URL = /^https?:\/\/(?:react\.dev\/errors\/|reactjs\.org\/docs\/error-decoder)/i;
+
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+// Every control character except tab and newline.
+// oxlint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u001F\u007F]/g;
+const URL_WITH_QUERY = /\bhttps?:\/\/[^\s?#"'<>()`]*[?#][^\s"'<>()`]*/gi;
+const LINE_AND_COLUMN_SUFFIX = /(?::\d+){1,2}$/;
+// A credential, not prose such as "Basic authentication": it contains a digit.
+const AUTHORIZATION_VALUE =
+  /\b(Bearer|Basic|Token)\s+(?=[A-Za-z._~+/=-]*[0-9])[A-Za-z0-9._~+/=-]{8,}/gi;
+const JWT = /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}(?:\.[A-Za-z0-9_-]*)?/g;
+const KNOWN_TOKEN =
+  /\b(?:sk-(?:proj-|ant-)?|sk_(?:live|test)_|rk_(?:live|test)_|gh[pousr]_|github_pat_|glpat-|npm_|xox[abposr]-|ops_|AKIA|ASIA|AIza)[A-Za-z0-9_-]{12,}/g;
+// The value never starts with `[` or `…`, so an already redacted value and a
+// truncation marker are left alone and the scrubber stays idempotent.
+const SECRET_ASSIGNMENT =
+  /\b((?:access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?token|token|client[_-]?secret|secret|password|passwd|api[_-]?key|apikey|authorization|cookie|private[_-]?key)["']?\s*[:=]\s*["']?)[^\s"'&,;}[…][^\s"'&,;}]*/gi;
+const OPAQUE_RUN = /[A-Za-z0-9+=_-]{32,}/g;
+
+/**
+ * A long run that looks like a credential rather than a word, chunk name,
+ * path or UUID: it mixes letters and digits and has an unbroken stretch of at
+ * least 24 characters between `-`/`_` separators. Content-hashed asset names
+ * (`artifact-page-chrome-DkF3x9aB`) and UUIDs have no stretch that long.
+ */
+function isOpaqueCredential(run: string): boolean {
+  return (
+    /[0-9]/.test(run) &&
+    /[A-Za-z]/.test(run) &&
+    run.split(/[-_]/).some((stretch) => stretch.length >= 24)
+  );
+}
+
+/**
+ * Remove what an error text must never carry while keeping what makes it
+ * useful. Query strings and fragments are dropped from http(s) URLs (keeping a
+ * stack frame's `:line:column`); authorization values, JWTs, well-known API
+ * token formats, the values of `token=`/`password:`-style assignments, and
+ * long opaque letter-and-digit runs become `[redacted]`; control characters
+ * other than tab and newline become spaces. Messages, file names, route paths,
+ * UUIDs and stack frames survive. Applying it twice changes nothing.
+ */
+export function scrubClientErrorText(text: string): string {
+  return text
+    .replace(LONE_SURROGATE, "\uFFFD")
+    .replace(/\r\n?/g, "\n")
+    .replace(CONTROL_CHARACTERS, " ")
+    .replace(URL_WITH_QUERY, (url) => {
+      if (ERROR_DECODER_URL.test(url)) return url;
+      const cut = url.search(/[?#]/);
+      const suffix = url.slice(cut).match(LINE_AND_COLUMN_SUFFIX)?.[0] ?? "";
+      return url.slice(0, cut) + suffix;
+    })
+    .replace(AUTHORIZATION_VALUE, `$1 ${REDACTED}`)
+    .replace(JWT, REDACTED)
+    .replace(KNOWN_TOKEN, REDACTED)
+    .replace(SECRET_ASSIGNMENT, `$1${REDACTED}`)
+    .replace(OPAQUE_RUN, (run) => (isOpaqueCredential(run) ? REDACTED : run));
+}
+
+function utf8ByteLength(text: string): number {
+  return new TextEncoder().encode(text).byteLength;
+}
+
+/**
+ * Cut `text` to at most `maxBytes` UTF-8 bytes on a character boundary, ending
+ * with a truncation marker when anything was removed.
+ */
+export function boundClientErrorText(text: string, maxBytes: number): string {
+  if (utf8ByteLength(text) <= maxBytes) return text;
+  const budget = maxBytes - utf8ByteLength(TRUNCATED);
+  let bytes = 0;
+  let end = 0;
+  for (const character of text) {
+    const size = utf8ByteLength(character);
+    if (bytes + size > budget) break;
+    bytes += size;
+    end += character.length;
+  }
+  return text.slice(0, end) + TRUNCATED;
+}
+
+/** Whether `text` is already exactly what the projection would produce for it. */
+export function isProjectedClientErrorText(text: string, field: ClientErrorDetailField): boolean {
+  return (
+    text.length > 0 &&
+    utf8ByteLength(text) <= CLIENT_ERROR_DETAIL_MAX_BYTES[field] &&
+    scrubClientErrorText(text) === text
+  );
+}
+
+/**
+ * Project raw diagnostics into a {@link ClientErrorDetail}: non-string and
+ * blank fields are dropped, the rest scrubbed and then bounded. Returns
+ * `undefined` when nothing remains. Bounding after scrubbing keeps a cut from
+ * splitting a credential into a fragment the scrubber no longer recognizes;
+ * the marker cannot form one, so the result is stable under re-projection.
+ */
+export function projectClientErrorDetail(
+  raw: Partial<Record<ClientErrorDetailField, unknown>> | null | undefined,
+): ClientErrorDetail | undefined {
+  if (!raw) return undefined;
+  const detail: ClientErrorDetail = {};
+  for (const field of CLIENT_ERROR_DETAIL_FIELDS) {
+    const value = raw[field];
+    if (typeof value !== "string") continue;
+    const projected = boundClientErrorText(
+      scrubClientErrorText(value).trim(),
+      CLIENT_ERROR_DETAIL_MAX_BYTES[field],
+    );
+    if (projected) detail[field] = projected;
+  }
+  return Object.keys(detail).length > 0 ? detail : undefined;
+}
+
+/**
+ * Content-free operational signals that share the error beacon route. A
+ * signal report carries a `signal` discriminator and only closed values; a
+ * report without `signal` is a {@link ClientErrorReport}. Older API servers
+ * reject signal reports as invalid, so the extension is backward compatible in
+ * both directions.
+ */
+export const CLIENT_SIGNALS = ["request_failure", "stream", "web_vital"] as const;
+export type ClientSignal = (typeof CLIENT_SIGNALS)[number];
+
+/**
+ * Key product mutations whose failure before any HTTP response is counted.
+ * `send_message` includes sends the server queues behind an active turn.
+ */
+export const CLIENT_REQUEST_ACTIONS = [
+  "create_session",
+  "send_message",
+  "steer_message",
+  "composer_submit",
+  "retry_turn",
+  "connect_integration",
+  "connect_model",
+  "checkout_start",
+] as const;
+export type ClientRequestAction = (typeof CLIENT_REQUEST_ACTIONS)[number];
+
+/**
+ * Why a request never produced an HTTP response: the browser reported no
+ * connectivity (`offline`), the client's own deadline expired (`timeout`), or
+ * the transport failed (`network`). Cancellations the user or the app
+ * initiated are never reported.
+ */
+export const CLIENT_REQUEST_FAILURE_REASONS = ["network", "timeout", "offline"] as const;
+export type ClientRequestFailureReason = (typeof CLIENT_REQUEST_FAILURE_REASONS)[number];
+
+/** Browser live streams: one session's event stream, or the workspace live stream. */
+export const CLIENT_STREAMS = ["session", "workspace"] as const;
+export type ClientStream = (typeof CLIENT_STREAMS)[number];
+
+/**
+ * Live stream health: a live stream dropped and started reconnecting
+ * (`reconnect`), stopped reconnecting (`reconnect_exhausted`), or stayed
+ * disconnected for longer than the long-disconnect threshold while the tab
+ * was visible (`long_disconnect`).
+ */
+export const CLIENT_STREAM_EVENTS = [
+  "reconnect",
+  "reconnect_exhausted",
+  "long_disconnect",
+] as const;
+export type ClientStreamEvent = (typeof CLIENT_STREAM_EVENTS)[number];
+
+/** Core Web Vitals plus time to first byte, measured once per document. */
+export const CLIENT_WEB_VITAL_METRICS = ["lcp", "inp", "cls", "ttfb"] as const;
+export type ClientWebVitalMetric = (typeof CLIENT_WEB_VITAL_METRICS)[number];
+
+/**
+ * Largest accepted value: seconds for the timing metrics, the unitless layout
+ * shift score for `cls`.
+ */
+export const CLIENT_WEB_VITAL_MAX_VALUE: Readonly<Record<ClientWebVitalMetric, number>> = {
+  lcp: 600,
+  inp: 600,
+  cls: 100,
+  ttfb: 600,
+};
+
+/**
+ * The closed page labels of the web console's product-journey projection
+ * (`journeyPage` in apps/web/src/lib/analytics-journey.ts; a drift test keeps
+ * the two identical). Workspace pages are the first path segment after
+ * `/workspaces/<id>/`; the rest are exact top-level routes.
+ */
+export const CLIENT_PAGES = [
+  "sessions",
+  "priority",
+  "plugins",
+  "capabilities",
+  "documents",
+  "state",
+  "memory",
+  "schedules",
+  "artifacts",
+  "settings",
+  "organization",
+  "insights",
+  "machines",
+  "files",
+  "agents",
+  "secrets",
+  "variable-sets",
+  "environments",
+  "rigs",
+  "playground",
+  "read-only-chats",
+  "inbox",
+  "home",
+  "session-link",
+  "identity-link",
+  "checkout-return",
+  "integration-return",
+  "device",
+  "connect-agent",
+  "native-sign-in",
+  "reset-password",
+  "setup-account",
+  "account-auth",
+  "site-auth",
+  "personal-security",
+  "other",
+] as const;
+export type ClientPage = (typeof CLIENT_PAGES)[number];
+
+export type ClientRequestFailureReport = {
+  signal: "request_failure";
+  action: ClientRequestAction;
+  reason: ClientRequestFailureReason;
+  route: string;
+  revision: string;
+};
+
+export type ClientStreamReport = {
+  signal: "stream";
+  stream: ClientStream;
+  event: ClientStreamEvent;
+  route: string;
+  revision: string;
+};
+
+export type ClientWebVitalReport = {
+  signal: "web_vital";
+  metric: ClientWebVitalMetric;
+  page: ClientPage;
+  /** Seconds for timing metrics, the unitless score for `cls`. */
+  value: number;
+  revision: string;
+};
+
+export type ClientSignalReport =
+  | ClientRequestFailureReport
+  | ClientStreamReport
+  | ClientWebVitalReport;
+
+/** Every body the beacon route accepts. */
+export type ClientBeaconReport = ClientErrorReport | ClientSignalReport;

package/src/code-search.ts

@@ -0,0 +1,105 @@
+// Resolvers for the optional Jev-backed `code_search` agent tool. A separate
+// subpath keeps them out of browser bundles; only server code decides.
+
+/**
+ * Directories holding platform credential material that `code_search` never
+ * searches or reads, as path segments matched at any depth: Opengeni's
+ * sandbox state (`.opengeni/`: Codemode bearer tokens, Git credential files
+ * and bindings), the Azure CLI login cache (`.azure/`, from the sandbox's
+ * service-principal login with HOME=/workspace) and a Connected Machine
+ * agent's enrollment credentials (`.config/opengeni/`). The sandbox channel
+ * enforces this list; `@opengeni/jev` keeps the same list for its engine, and
+ * a worker test pins that the two agree.
+ */
+export const CODE_SEARCH_CREDENTIAL_DIRS: readonly (readonly string[])[] = [
+  [".opengeni"],
+  [".azure"],
+  [".config", "opengeni"],
+];
+
+/**
+ * The deployment half of the `code_search` decision. `split` gives the tool to
+ * a fixed half of sessions (see `codeSearchSessionInExperiment`) so staging can
+ * compare sessions with and without it.
+ */
+export type CodeSearchWorkspaceDefault = "off" | "on" | "split";
+export type CodeSearchDeploymentPolicy = {
+  available: boolean;
+  workspaceDefault: CodeSearchWorkspaceDefault;
+};
+
+/**
+ * What a workspace gets: the deployment decides first, so nothing enables the
+ * tool where the deployment does not offer it. Otherwise an explicit workspace
+ * choice wins, and an absent, null or malformed setting follows the deployment
+ * default. Only this field is read, so an invalid sibling setting cannot turn
+ * an explicit Off back into the deployment default.
+ */
+export function resolveWorkspaceCodeSearchMode(
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+): CodeSearchWorkspaceDefault {
+  if (!deployment.available) return "off";
+  const explicit = explicitWorkspaceCodeSearchSetting(settings);
+  if (explicit === true) return "on";
+  if (explicit === false) return "off";
+  return deployment.workspaceDefault;
+}
+
+function explicitWorkspaceCodeSearchSetting(settings: unknown): boolean | undefined {
+  const explicit =
+    typeof settings === "object" && settings !== null
+      ? (settings as { codeSearchEnabled?: unknown }).codeSearchEnabled
+      : undefined;
+  return typeof explicit === "boolean" ? explicit : undefined;
+}
+
+/**
+ * Fixed per-session half for the `split` experiment: 32-bit FNV-1a of the
+ * session id, low bit 0 gets the tool. Deterministic and dependency-free, so
+ * a root session's arm can be recomputed from its id. Child sessions inherit
+ * their parent's decision instead.
+ */
+export function codeSearchSessionInExperiment(sessionId: string): boolean {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < sessionId.length; index++) {
+    hash ^= sessionId.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return (hash & 1) === 0;
+}
+
+/**
+ * The decision frozen on a new root session when it is created. Later changes
+ * to the workspace setting or the deployment mode never turn the tool on for a
+ * session that was created without it.
+ */
+export function resolveSessionCodeSearchEnabled(
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+  sessionId: string,
+): boolean {
+  const mode = resolveWorkspaceCodeSearchMode(settings, deployment);
+  return mode === "on" || (mode === "split" && codeSearchSessionInExperiment(sessionId));
+}
+
+/**
+ * Whether a turn of this session gets `code_search`. Only a session frozen on
+ * at creation can have it. The deployment (mode off or no usable key) and an
+ * explicit workspace Off still pause it in running sessions, because they stop
+ * repository content going to Jev; undoing that switch-off gives it back to
+ * sessions frozen on. Each such change costs every affected session one
+ * prompt-cache miss, which is accepted for a deliberate switch. Nothing else
+ * changes the tool list of a running session.
+ */
+export function codeSearchEnabledForTurn(
+  frozen: boolean | null | undefined,
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+): boolean {
+  return (
+    frozen === true &&
+    deployment.available &&
+    explicitWorkspaceCodeSearchSetting(settings) !== false
+  );
+}

package/src/codex-provider-account-authority.ts

@@ -1,6 +1,9 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-const PositiveSafeInteger = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const PositiveSafeInteger = /* @__PURE__ */ defineSchema(() =>
+  z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+);
 
 /**
  * Opaque authority frozen at a Codex provider-account acceptance boundary.
@@ -10,21 +13,23 @@ const PositiveSafeInteger = z.number().int().positive().max(Number.MAX_SAFE_INTE
  * activation slice may use the user generation only together with separately
  * authorized durable state; this value is never sufficient authority alone.
  */
-export const CodexProviderAccountAuthoritySnapshotV1 = z.discriminatedUnion("scope", [
-  z
-    .object({
-      version: z.literal(1),
-      scope: z.literal("workspace"),
-    })
-    .strict(),
-  z
-    .object({
-      version: z.literal(1),
-      scope: z.literal("user"),
-      authorityGeneration: PositiveSafeInteger,
-    })
-    .strict(),
-]);
+export const CodexProviderAccountAuthoritySnapshotV1 = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("scope", [
+    z
+      .object({
+        version: z.literal(1),
+        scope: z.literal("workspace"),
+      })
+      .strict(),
+    z
+      .object({
+        version: z.literal(1),
+        scope: z.literal("user"),
+        authorityGeneration: PositiveSafeInteger,
+      })
+      .strict(),
+  ]),
+);
 
 export type CodexProviderAccountAuthoritySnapshotV1 = z.infer<
   typeof CodexProviderAccountAuthoritySnapshotV1