@opengeni/contracts 0.44.1 → 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 = 512 * 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/canonical-human-identities.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+
+export const CanonicalHumanIdentityStatus = z.enum([
+  "active",
+  "recovery_required",
+  "disputed",
+  "disabled",
+]);
+export type CanonicalHumanIdentityStatus = z.infer<typeof CanonicalHumanIdentityStatus>;
+
+export const CanonicalHumanLoginBindingStatus = z.enum([
+  "active",
+  "recovery_pending",
+  "stale",
+  "disputed",
+  "revoked",
+]);
+export type CanonicalHumanLoginBindingStatus = z.infer<typeof CanonicalHumanLoginBindingStatus>;
+
+export const CanonicalHumanRecoveryState = z.enum([
+  "ready",
+  "recovery_required",
+  "lost_factor",
+  "disputed",
+  "disabled",
+]);
+export type CanonicalHumanRecoveryState = z.infer<typeof CanonicalHumanRecoveryState>;
+
+export const CanonicalHumanLoginBinding = z.object({
+  id: z.string().uuid(),
+  providerId: z.string().min(1).max(128),
+  providerAccountId: z.string().min(1).max(1024),
+  status: CanonicalHumanLoginBindingStatus,
+  revision: z.number().int().positive(),
+  verifiedAt: z.string().datetime(),
+  lastVerifiedAt: z.string().datetime(),
+  revokedAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+export type CanonicalHumanLoginBinding = z.infer<typeof CanonicalHumanLoginBinding>;
+
+export const CanonicalHumanIdentityProjection = z.object({
+  activeIdentity: z.object({
+    id: z.string().uuid(),
+    displayName: z.string().min(1).max(256),
+    status: CanonicalHumanIdentityStatus,
+    identityRevision: z.number().int().positive(),
+    authRevision: z.number().int().positive(),
+    activeLoginBindingId: z.string().uuid().nullable(),
+    recoveryState: CanonicalHumanRecoveryState,
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+  }),
+  loginBindings: z.array(CanonicalHumanLoginBinding).max(64),
+});
+export type CanonicalHumanIdentityProjection = z.infer<typeof CanonicalHumanIdentityProjection>;
+
+const OperationFields = {
+  operationId: z.string().uuid().optional(),
+  expectedIdentityRevision: z.number().int().positive(),
+  reason: z.string().trim().min(1).max(512),
+} as const;
+
+export const LinkCanonicalHumanLoginBindingRequest = z.object({
+  ...OperationFields,
+  providerId: z.string().trim().min(1).max(128),
+  providerAccountId: z.string().trim().min(1).max(1024),
+});
+export type LinkCanonicalHumanLoginBindingRequest = z.infer<
+  typeof LinkCanonicalHumanLoginBindingRequest
+>;
+
+export const CanonicalHumanBindingOperationRequest = z.object({
+  ...OperationFields,
+});
+export type CanonicalHumanBindingOperationRequest = z.infer<
+  typeof CanonicalHumanBindingOperationRequest
+>;
+
+export const CanonicalHumanIdentityMutationOutcome = z.enum(["applied", "lost_factor", "disputed"]);
+export type CanonicalHumanIdentityMutationOutcome = z.infer<
+  typeof CanonicalHumanIdentityMutationOutcome
+>;
+
+export const CanonicalHumanIdentityMutationResponse = z.object({
+  outcome: CanonicalHumanIdentityMutationOutcome,
+  operationId: z.string().uuid(),
+  identity: CanonicalHumanIdentityProjection,
+});
+export type CanonicalHumanIdentityMutationResponse = z.infer<
+  typeof CanonicalHumanIdentityMutationResponse
+>;

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>;