@opengeni/contracts 0.50.0 → 1.0.0

package/src/artifacts.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { ToolGatewayIdentity } from "./tool-catalog";
 
-export const WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES = 4 * 1024 * 1024;
+export const WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES = 5_000_000_000;
+export const WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES = 5_000_000_000;
+export const WORKSPACE_ARTIFACT_SOURCE_MAX_FILES = Number.MAX_SAFE_INTEGER;
+export const WORKSPACE_ARTIFACT_REQUESTED_TOOLS_MAX = 128;
 export const WORKSPACE_ARTIFACT_TITLE_MAX_CHARS = 120;
 export const WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS = 2_000;
 export const WORKSPACE_ARTIFACT_LIST_MAX = 100;
@@ -21,6 +25,84 @@ export type WorkspaceArtifactSlug = z.infer<typeof WorkspaceArtifactSlug>;
 export const WorkspaceArtifactStatus = z.enum(["active", "archived"]);
 export type WorkspaceArtifactStatus = z.infer<typeof WorkspaceArtifactStatus>;
 
+export const WorkspaceArtifactSourcePath = z
+  .string()
+  .min(1)
+  .max(256)
+  .regex(/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u)
+  .refine(
+    (value) =>
+      !value
+        .split("/")
+        .some((segment) => segment === "." || segment === ".." || segment.length === 0),
+    { message: "artifact source paths must be relative and traversal-free" },
+  );
+export type WorkspaceArtifactSourcePath = z.infer<typeof WorkspaceArtifactSourcePath>;
+
+export const WorkspaceArtifactSourceFile = z
+  .object({
+    path: WorkspaceArtifactSourcePath,
+    content: z.string(),
+  })
+  .strict();
+export type WorkspaceArtifactSourceFile = z.infer<typeof WorkspaceArtifactSourceFile>;
+
+/** Retained editable source; the published runtime remains one exact HTML document. */
+export const WorkspaceArtifactSourceBundle = z
+  .object({
+    entrypoint: WorkspaceArtifactSourcePath,
+    files: z.array(WorkspaceArtifactSourceFile).min(1).max(WORKSPACE_ARTIFACT_SOURCE_MAX_FILES),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const paths = new Set<string>();
+    for (const [index, file] of value.files.entries()) {
+      if (paths.has(file.path)) {
+        context.addIssue({
+          code: "custom",
+          path: ["files", index, "path"],
+          message: "artifact source file paths must be unique",
+        });
+      }
+      paths.add(file.path);
+    }
+    if (!paths.has(value.entrypoint)) {
+      context.addIssue({
+        code: "custom",
+        path: ["entrypoint"],
+        message: "artifact source entrypoint must name one retained file",
+      });
+    }
+    if (
+      encoder.encode(JSON.stringify(value)).byteLength > WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: `artifact source exceeds ${WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+export type WorkspaceArtifactSourceBundle = z.infer<typeof WorkspaceArtifactSourceBundle>;
+
+export const WorkspaceArtifactRequestedTools = z
+  .array(ToolGatewayIdentity)
+  .max(WORKSPACE_ARTIFACT_REQUESTED_TOOLS_MAX)
+  .superRefine((tools, context) => {
+    const seen = new Set<string>();
+    for (const [index, identity] of tools.entries()) {
+      const key = `${identity.serverId}\u0000${identity.toolName}`;
+      if (seen.has(key)) {
+        context.addIssue({
+          code: "custom",
+          path: [index],
+          message: "requested artifact tools must be unique",
+        });
+      }
+      seen.add(key);
+    }
+  });
+export type WorkspaceArtifactRequestedTools = z.infer<typeof WorkspaceArtifactRequestedTools>;
+
 export const WorkspaceArtifactVersion = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -28,8 +110,16 @@ export const WorkspaceArtifactVersion = z.object({
   artifactId: z.string().uuid(),
   revision: z.number().int().positive(),
   contentType: z.literal("text/html"),
-  contentSha256: sha256,
+  contentSha256: sha256.nullable(),
   sizeBytes: z.number().int().positive().max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+  sourceSha256: sha256.nullable(),
+  sourceSizeBytes: z
+    .number()
+    .int()
+    .positive()
+    .max(WORKSPACE_ARTIFACT_SOURCE_MAX_UTF8_BYTES)
+    .nullable(),
+  requestedTools: WorkspaceArtifactRequestedTools,
   sourceSessionId: z.string().uuid().nullable(),
   sourceTurnId: z.string().uuid().nullable(),
   sourceAttemptId: z.string().uuid().nullable(),
@@ -54,7 +144,12 @@ export const WorkspaceArtifact = z.object({
 });
 export type WorkspaceArtifact = z.infer<typeof WorkspaceArtifact>;
 
-export const WorkspaceArtifactEventType = z.enum(["published", "rolled_back"]);
+export const WorkspaceArtifactEventType = z.enum([
+  "published",
+  "rolled_back",
+  "archived",
+  "restored",
+]);
 export type WorkspaceArtifactEventType = z.infer<typeof WorkspaceArtifactEventType>;
 
 export const WorkspaceArtifactEvent = z.object({
@@ -83,6 +178,9 @@ export const WorkspaceArtifactListQuery = z.object({
     .max(WORKSPACE_ARTIFACT_LIST_MAX)
     .default(WORKSPACE_ARTIFACT_LIST_DEFAULT),
   cursor: z.string().min(1).max(WORKSPACE_ARTIFACT_CURSOR_MAX_CHARS).optional(),
+  status: WorkspaceArtifactStatus.optional(),
+  /** Sites created or published by this session, including older versions. */
+  sourceSessionId: z.string().uuid().optional(),
 });
 export type WorkspaceArtifactListQuery = z.infer<typeof WorkspaceArtifactListQuery>;
 
@@ -115,22 +213,42 @@ export const WorkspaceArtifactHtml = z
     }
   });
 
-export const CreateWorkspaceArtifactRequest = z.object({
-  slug: WorkspaceArtifactSlug.optional(),
-  title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS),
-  description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
-  html: WorkspaceArtifactHtml,
-  idempotencyKey: z.string().trim().min(1).max(200),
-});
+export const CreateWorkspaceArtifactRequest = z
+  .object({
+    slug: WorkspaceArtifactSlug.optional(),
+    title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS),
+    description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
+    html: WorkspaceArtifactHtml.optional(),
+    uploadId: z.string().uuid().optional(),
+    source: WorkspaceArtifactSourceBundle.optional(),
+    requestedTools: WorkspaceArtifactRequestedTools.optional(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .refine((value) => (value.html !== undefined) !== (value.uploadId !== undefined), {
+    message: "Provide either html or uploadId",
+  })
+  .refine((value) => !value.uploadId || value.source === undefined, {
+    message: "Upload source using the prepared source URL",
+  });
 export type CreateWorkspaceArtifactRequest = z.infer<typeof CreateWorkspaceArtifactRequest>;
 
-export const PublishWorkspaceArtifactVersionRequest = z.object({
-  title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS).optional(),
-  description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
-  html: WorkspaceArtifactHtml,
-  expectedCurrentVersionId: z.string().uuid(),
-  idempotencyKey: z.string().trim().min(1).max(200),
-});
+export const PublishWorkspaceArtifactVersionRequest = z
+  .object({
+    title: z.string().trim().min(1).max(WORKSPACE_ARTIFACT_TITLE_MAX_CHARS).optional(),
+    description: z.string().max(WORKSPACE_ARTIFACT_DESCRIPTION_MAX_CHARS).nullable().optional(),
+    html: WorkspaceArtifactHtml.optional(),
+    uploadId: z.string().uuid().optional(),
+    source: WorkspaceArtifactSourceBundle.optional(),
+    requestedTools: WorkspaceArtifactRequestedTools.optional(),
+    expectedCurrentVersionId: z.string().uuid(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .refine((value) => (value.html !== undefined) !== (value.uploadId !== undefined), {
+    message: "Provide either html or uploadId",
+  })
+  .refine((value) => !value.uploadId || value.source === undefined, {
+    message: "Upload source using the prepared source URL",
+  });
 export type PublishWorkspaceArtifactVersionRequest = z.infer<
   typeof PublishWorkspaceArtifactVersionRequest
 >;
@@ -143,6 +261,14 @@ export const RollbackWorkspaceArtifactRequest = z.object({
 });
 export type RollbackWorkspaceArtifactRequest = z.infer<typeof RollbackWorkspaceArtifactRequest>;
 
+export const SetWorkspaceArtifactStatusRequest = z.object({
+  status: WorkspaceArtifactStatus,
+  expectedCurrentVersionId: z.string().uuid(),
+  reason: z.string().trim().min(1).max(4096),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type SetWorkspaceArtifactStatusRequest = z.infer<typeof SetWorkspaceArtifactStatusRequest>;
+
 export const WorkspaceArtifactMutationResponse = z.object({
   artifact: WorkspaceArtifact,
   version: WorkspaceArtifactVersion,
@@ -155,8 +281,10 @@ export const WorkspaceArtifactContentResponse = z.object({
   artifactId: z.string().uuid(),
   versionId: z.string().uuid(),
   contentType: z.literal("text/html"),
-  contentSha256: sha256,
+  contentSha256: sha256.nullable(),
   html: WorkspaceArtifactHtml,
+  source: WorkspaceArtifactSourceBundle,
+  requestedTools: WorkspaceArtifactRequestedTools,
 });
 export type WorkspaceArtifactContentResponse = z.infer<typeof WorkspaceArtifactContentResponse>;
 

package/src/atlassian-native-retirement.ts

@@ -0,0 +1,33 @@
+/** The former API/Knowledge-sync adapter is historical; hosted Atlassian MCP remains supported. */
+export const ATLASSIAN_NATIVE_RETIRED_REASON = "atlassian_native_retired" as const;
+export const ATLASSIAN_NATIVE_RETIRED_MESSAGE =
+  "Jira and Confluence knowledge sync has been retired. Connect Atlassian agent tools to use its hosted MCP server.";
+export const RETIRED_NATIVE_ATLASSIAN_TOOL_NAMES = [
+  "atlassian_sources_list",
+  "atlassian_search",
+  "atlassian_get",
+] as const;
+
+export function isRetiredNativeAtlassianTool(name: string): boolean {
+  return (RETIRED_NATIVE_ATLASSIAN_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+/** Match the native source identity, never the hosted MCP provider or a display name. */
+export function isRetiredNativeAtlassianSource(source: unknown): boolean {
+  if (!source || typeof source !== "object") return false;
+  const connection = (source as { connection?: unknown }).connection;
+  if (!connection || typeof connection !== "object") return false;
+  const provider = (connection as { providerDomain?: unknown }).providerDomain;
+  return typeof provider === "string" && provider.toLowerCase() === "api.atlassian.com";
+}
+
+/** Includes frozen historical source actions without changing their stored bytes. */
+export function isRetiredNativeAtlassianTask(task: {
+  agentConfig?: { knowledgeSource?: unknown } | null;
+  action?: { kind?: unknown } | null;
+}): boolean {
+  return (
+    isRetiredNativeAtlassianSource(task.agentConfig?.knowledgeSource) ||
+    (task.action?.kind === "knowledge_source_sync" && isRetiredNativeAtlassianSource(task.action))
+  );
+}

package/src/browser-storage.ts

@@ -0,0 +1,10 @@
+/** Persisted discriminator; null identity alone never implies ephemeral storage. */
+export const EPHEMERAL_CHROMIUM_DRIVER_ID = "opengeni.cdp.ephemeral-context.v1" as const;
+
+export function browserSessionStorageMode(session: {
+  driverId: string;
+}): "private_profile" | "ephemeral_context" {
+  return session.driverId === EPHEMERAL_CHROMIUM_DRIVER_ID
+    ? "ephemeral_context"
+    : "private_profile";
+}

package/src/bundled-skills.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const BundledSkillId = z.enum([
+  "builtin:opengeni-help",
+  "builtin:opengeni-client",
+  "builtin:opengeni-visualize",
+  "builtin:document-parsing",
+  "builtin:opengeni-skills",
+  "builtin:opengeni-projects",
+  "builtin:opengeni-schedules",
+  "builtin:opengeni-documents",
+  "builtin:opengeni-spreadsheets",
+  "builtin:opengeni-presentations",
+  "builtin:opengeni-sites",
+  "builtin:opengeni-video-generation",
+]);
+export type BundledSkillId = z.infer<typeof BundledSkillId>;
+export const BundledSkillSelection = z
+  .array(BundledSkillId)
+  .max(BundledSkillId.options.length)
+  .refine((ids) => new Set(ids).size === ids.length, "bundled Skill ids must be unique")
+  .transform((ids) => [...ids].sort());
+
+/** Undefined is defaults/inheritance; an explicit empty list disables bundles. */
+export function resolveBundledSkillSelection(
+  requested: readonly BundledSkillId[] | undefined,
+  parent: readonly BundledSkillId[] | undefined,
+): BundledSkillId[] | undefined {
+  const selected = requested === undefined ? parent : requested;
+  if (parent !== undefined && selected?.some((id) => !parent.includes(id)))
+    throw new Error("A child cannot widen its parent's bundled Skill selection");
+  return selected === undefined ? undefined : BundledSkillSelection.parse(selected);
+}
+
+// Immutable session configuration, following the existing create-identity
+// metadata convention. Callers cannot set this through arbitrary metadata.
+const BUNDLED_SKILL_SELECTION_KEY = "_opengeni_bundled_skill_ids_v1";
+export function withBundledSkillSelectionMetadata(
+  metadata: Record<string, unknown>,
+  ids: readonly BundledSkillId[] | undefined,
+): Record<string, unknown> {
+  const next = { ...metadata };
+  delete next[BUNDLED_SKILL_SELECTION_KEY];
+  if (ids !== undefined) next[BUNDLED_SKILL_SELECTION_KEY] = BundledSkillSelection.parse(ids);
+  return next;
+}
+/**
+ * Stored-data read. Ids are permanent, but a row written by a newer (or
+ * rolled-back-from) release can hold an id this build lacks. Such ids are
+ * dropped rather than failing the session read; dropping only narrows the
+ * stored selection and never turns it back into defaults. Input stays strict,
+ * and a value that is not a list of id strings still fails.
+ */
+const StoredBundledSkillSelection = z.array(z.string());
+const knownBundledSkillIds: ReadonlySet<string> = new Set(BundledSkillId.options);
+/**
+ * Exact stored selection for keyed create replay identity. Unlike the
+ * tolerant read, it keeps ids this build does not know: a retry must match
+ * what was stored, not the narrowed projection of it.
+ */
+export function storedBundledSkillSelectionIdentity(metadata: Record<string, unknown>): unknown {
+  return metadata[BUNDLED_SKILL_SELECTION_KEY];
+}
+export function bundledSkillSelectionFromMetadata(
+  metadata: Record<string, unknown>,
+): BundledSkillId[] | undefined {
+  const value = metadata[BUNDLED_SKILL_SELECTION_KEY];
+  if (value === undefined) return undefined;
+  const known = StoredBundledSkillSelection.parse(value).filter((id): id is BundledSkillId =>
+    knownBundledSkillIds.has(id),
+  );
+  return [...new Set(known)].sort();
+}

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

@@ -0,0 +1,12 @@
+import { XaiProviderAccountAuthoritySnapshotV1 } from "./xai-provider-account-authority";
+import type { z } from "zod";
+
+/** Same opaque pool selection shape; Claude's live authority is revalidated separately. */
+export const ClaudeProviderAccountAuthoritySnapshotV1 = XaiProviderAccountAuthoritySnapshotV1;
+export type ClaudeProviderAccountAuthoritySnapshotV1 = z.infer<
+  typeof ClaudeProviderAccountAuthoritySnapshotV1
+>;
+export const WORKSPACE_CLAUDE_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1 = {
+  version: 1,
+  scope: "workspace",
+} as const satisfies ClaudeProviderAccountAuthoritySnapshotV1;

package/src/claude-subscription-oauth.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+export const ClaudeSubscriptionSetupTokenRequest = z
+  .object({
+    token: z.string().trim().min(1).max(16384),
+    scope: z.enum(["workspace", "user"]).default("workspace"),
+    label: z.string().trim().max(200).nullable().optional(),
+    reconnectAccountId: z.string().uuid().optional(),
+    expectedCredentialVersion: z.number().int().positive().optional(),
+  })
+  .strict()
+  .refine(
+    (request) =>
+      Boolean(request.reconnectAccountId) === (request.expectedCredentialVersion !== undefined),
+    { message: "Replacing a setup token requires its account and credential version." },
+  );
+export type ClaudeSubscriptionSetupTokenRequest = z.infer<
+  typeof ClaudeSubscriptionSetupTokenRequest
+>;
+
+export const ClaudeSubscriptionOAuthStartRequest = z
+  .object({
+    scope: z.enum(["workspace", "user"]).default("workspace"),
+    reconnectAccountId: z.string().uuid().optional(),
+  })
+  .strict();
+export type ClaudeSubscriptionOAuthStartRequest = z.infer<
+  typeof ClaudeSubscriptionOAuthStartRequest
+>;
+
+export const ClaudeSubscriptionOAuthStartResponse = z
+  .object({
+    attemptId: z.string().uuid(),
+    authorizationUrl: z.string().url(),
+    expiresAt: z.string().datetime(),
+  })
+  .strict();
+export type ClaudeSubscriptionOAuthStartResponse = z.infer<
+  typeof ClaudeSubscriptionOAuthStartResponse
+>;
+
+export const ClaudeSubscriptionOAuthCompleteRequest = z
+  .object({
+    attemptId: z.string().uuid(),
+    code: z.string().trim().min(1).max(4096),
+  })
+  .strict();
+export type ClaudeSubscriptionOAuthCompleteRequest = z.infer<
+  typeof ClaudeSubscriptionOAuthCompleteRequest
+>;
+
+export const ClaudeSubscriptionOAuthCompleteResponse = z
+  .object({
+    connected: z.literal(true),
+    accountId: z.string().uuid(),
+    scope: z.enum(["organization", "workspace", "user"]),
+    credentialVersion: z.number().int().positive(),
+  })
+  .strict();
+export type ClaudeSubscriptionOAuthCompleteResponse = z.infer<
+  typeof ClaudeSubscriptionOAuthCompleteResponse
+>;

package/src/claude-subscription-usage.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+export const ClaudeUsageWindowId = z.enum([
+  "five_hour",
+  "seven_day",
+  "seven_day_opus",
+  "seven_day_sonnet",
+  "seven_day_overage_included",
+  "overage",
+]);
+export const ClaudeUsageWindow = 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 = 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 = 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,184 @@
+/**
+ * Wire grammar of the content-free web client error beacon
+ * (`POST /v1/client-errors`).
+ *
+ * A report is only a closed error kind, the matched route PATTERN (never a
+ * concrete URL), and the bundle revision. 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 values, 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 accepted report body. A valid report is well under 256 bytes. */
+export const CLIENT_ERROR_REPORT_MAX_BYTES = 512;
+
+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}$/;
+
+export type ClientErrorReport = { kind: ClientErrorKind; route: string; revision: string };
+
+/**
+ * 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",
+  "variable-sets",
+  "environments",
+  "rigs",
+  "home",
+  "session-link",
+  "identity-link",
+  "checkout-return",
+  "integration-return",
+  "device",
+  "connect-agent",
+  "reset-password",
+  "setup-account",
+  "account-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;