@opengeni/contracts 3.1.0-canary.2 → 3.1.2

package/src/model-display.ts

@@ -0,0 +1,221 @@
+/**
+ * One display identity for a model everywhere outside the Models settings page.
+ *
+ * Catalog ids carry routing facts (`codex/`, `organization-claude-subscription/`,
+ * `workspace-openrouter/anthropic/...`) and custom models may have no curated
+ * label. People should only ever see the model itself: `GPT-6.1 Sol`,
+ * `Opus 5.5`. The same upstream model therefore renders identically
+ * whether an organization or a workspace connection serves it.
+ *
+ * Pure and dependency-free so the API, SDK, React package and web app share it.
+ */
+
+export type ModelVendor =
+  | "openai"
+  | "anthropic"
+  | "xai"
+  | "google"
+  | "meta"
+  | "mistral"
+  | "deepseek"
+  | "moonshot"
+  | "qwen"
+  | "zhipu"
+  | "nvidia";
+
+export type ModelDisplayInput =
+  | string
+  | {
+      id: string;
+      label?: string | null | undefined;
+      logoUrl?: string | null | undefined;
+      upstreamModelId?: string | null | undefined;
+      deployment?: { upstreamModelId?: string | null | undefined } | null | undefined;
+    };
+
+/** Catalog maker logo; remote images must use HTTPS without embedded credentials. */
+export function modelLogoUrl(input: ModelDisplayInput): string | null {
+  const value = typeof input === "string" ? undefined : input.logoUrl;
+  if (!value || value.length > 2048 || value !== value.trim()) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+const WORDS: Readonly<Record<string, string>> = {
+  gpt: "GPT",
+  chatgpt: "ChatGPT",
+  claude: "Claude",
+  grok: "Grok",
+  gemini: "Gemini",
+  gemma: "Gemma",
+  llama: "Llama",
+  deepseek: "DeepSeek",
+  qwen: "Qwen",
+  glm: "GLM",
+  kimi: "Kimi",
+  mistral: "Mistral",
+  codestral: "Codestral",
+  devstral: "Devstral",
+  magistral: "Magistral",
+  nemotron: "Nemotron",
+  oss: "OSS",
+  // Region-pinned gateway routes (Opper `aws/claude-sonnet-4-6-eu`).
+  eu: "EU",
+};
+
+/** The upstream model slug without routing prefixes or `:variant` suffixes. */
+export function modelSlug(value: string): string {
+  const last = value.split("/").filter(Boolean).at(-1) ?? value;
+  return last.replace(/:[^:]*$/, "") || last;
+}
+
+function upstreamOf(input: Exclude<ModelDisplayInput, string>): string | null {
+  return input.upstreamModelId?.trim() || input.deployment?.upstreamModelId?.trim() || null;
+}
+
+function titleToken(token: string, index: number): string {
+  const lower = token.toLowerCase();
+  const word = WORDS[lower];
+  if (word) return word;
+  // OpenAI reasoning series stay lowercase: o3, o4 Mini.
+  if (index === 0 && /^o\d+$/.test(lower)) return lower;
+  // Sizes and lettered versions read as identifiers: 120B, V4, K3, A12B.
+  if (/^\d+(?:\.\d+)?[bkmt]$/.test(lower) || /^[a-z]\d+[a-z\d]*$/.test(lower)) {
+    return lower.toUpperCase();
+  }
+  if (/^\d/.test(token)) return lower;
+  return lower.charAt(0).toUpperCase() + lower.slice(1);
+}
+
+/** `claude-opus-5-5` → `Claude Opus 5.5`, `codex/gpt-6.1-sol` → `GPT-6.1 Sol`. */
+export function humanizeModelSlug(value: string): string {
+  const slug = modelSlug(value.trim())
+    // Snapshot dates are release detail, not a different model name.
+    .replace(/[-_](?:\d{8}|\d{4}-\d{2}-\d{2})$/, "")
+    .replace(/[-_]latest$/i, "");
+  const raw = slug.split(/[-_\s]+/).filter(Boolean);
+  if (raw.length === 0) return value.trim() || value;
+  // Consecutive short numbers are one version: 5-5 → 5.5, 3-5 → 3.5. Longer
+  // numbers are snapshots (gpt-4-1106-preview), never a minor version.
+  const tokens: string[] = [];
+  for (const token of raw) {
+    const previous = tokens.at(-1);
+    if (previous !== undefined && /^\d{1,2}$/.test(token) && /^\d{1,2}$/.test(previous)) {
+      tokens[tokens.length - 1] = `${previous}.${token}`;
+      continue;
+    }
+    tokens.push(token);
+  }
+  const words = tokens.map(titleToken);
+  // OpenAI's own spelling joins family and version: GPT-6.1, GPT-4o.
+  if (words[0] === "GPT" && words.length > 1 && /^\d/.test(words[1]!)) {
+    return [`GPT-${words[1]}`, ...words.slice(2)].join(" ");
+  }
+  return words.join(" ");
+}
+
+/**
+ * True when a catalog label is only the model's identifier: empty, or exactly
+ * its id, upstream id, or any trailing path of them (`claude-opus-4-8`,
+ * `anthropic/claude-sonnet-4.6`). Any other label is a curated name and wins.
+ */
+export function isRawModelLabel(
+  label: string,
+  ids: readonly (string | null | undefined)[] = [],
+): boolean {
+  const text = label.trim();
+  if (!text) return true;
+  return ids.some((id) => {
+    if (!id) return false;
+    const segments = id.trim().split("/").filter(Boolean);
+    return segments.some((_, index) => {
+      const tail = segments.slice(index).join("/");
+      return tail === text || modelSlug(tail) === text;
+    });
+  });
+}
+
+/**
+ * The clean name to show for a model: its curated catalog label when it has
+ * one, otherwise a readable form of the upstream model id. Never a routing
+ * prefix, connection id or connection scope. Anthropic's Opus, Sonnet and
+ * Haiku families drop the redundant `Claude` word (the maker mark already says
+ * it): `Opus 5.5`, `Sonnet 4.6 EU`.
+ */
+export function modelDisplayName(input: ModelDisplayInput): string {
+  if (typeof input === "string") {
+    // A bare id is humanized; text with spaces is already a name ("Workspace default").
+    return input.trim() && !/\s/.test(input.trim())
+      ? withoutClaudeFamilyPrefix(humanizeModelSlug(input))
+      : input;
+  }
+  const upstream = upstreamOf(input);
+  const label = input.label?.trim();
+  if (label && !isRawModelLabel(label, [input.id, upstream])) {
+    return withoutClaudeFamilyPrefix(label);
+  }
+  return withoutClaudeFamilyPrefix(humanizeModelSlug(upstream ?? label ?? input.id));
+}
+
+/** `Claude Opus 5.5` → `Opus 5.5`; other names (`Claude 3.5 Sonnet`) unchanged. */
+function withoutClaudeFamilyPrefix(name: string): string {
+  return name.replace(/^Claude\s+(?=(?:Opus|Sonnet|Haiku)\b)/, "");
+}
+
+const VENDOR_PATTERNS: ReadonlyArray<readonly [ModelVendor, RegExp]> = [
+  ["anthropic", /^claude\b/],
+  ["openai", /^(?:gpt|chatgpt|o\d+|codex|dall-e|sora|text-embedding|whisper)\b/],
+  ["xai", /^grok\b/],
+  ["google", /^(?:gemini|gemma)\b/],
+  ["meta", /^llama\b/],
+  ["mistral", /^(?:mistral|codestral|devstral|magistral|ministral|pixtral)\b/],
+  ["deepseek", /^deepseek\b/],
+  ["moonshot", /^(?:kimi|moonshot)\b/],
+  ["qwen", /^(?:qwen|qwq)\b/],
+  ["zhipu", /^glm\b/],
+  ["nvidia", /^nemotron\b/],
+];
+
+/** OpenRouter / Gateway vendor path segments (`anthropic/claude-…`). */
+const VENDOR_SEGMENTS: Readonly<Record<string, ModelVendor>> = {
+  anthropic: "anthropic",
+  openai: "openai",
+  "x-ai": "xai",
+  xai: "xai",
+  google: "google",
+  "meta-llama": "meta",
+  mistralai: "mistral",
+  deepseek: "deepseek",
+  moonshotai: "moonshot",
+  qwen: "qwen",
+  "z-ai": "zhipu",
+  nvidia: "nvidia",
+};
+
+function vendorFromSlug(slug: string): ModelVendor | null {
+  for (const [vendor, pattern] of VENDOR_PATTERNS) if (pattern.test(slug)) return vendor;
+  return null;
+}
+
+/** Who makes the model, for its logo. Null when it cannot be told. */
+export function modelVendor(input: ModelDisplayInput): ModelVendor | null {
+  const ids = typeof input === "string" ? [input] : [upstreamOf(input), input.id];
+  for (const id of ids) {
+    if (!id) continue;
+    const lower = id.trim().toLowerCase();
+    if (lower.startsWith("codex/")) return "openai";
+    if (lower.startsWith("supergrok/")) return "xai";
+    const vendor = vendorFromSlug(modelSlug(lower));
+    if (vendor) return vendor;
+    const segment = lower.split("/").filter(Boolean).at(-2);
+    if (segment && Object.hasOwn(VENDOR_SEGMENTS, segment)) return VENDOR_SEGMENTS[segment]!;
+  }
+  if (typeof input !== "string" && input.label) {
+    return vendorFromSlug(input.label.trim().toLowerCase().replace(/\s+/g, "-"));
+  }
+  return null;
+}

package/src/model-picker-order.ts

@@ -1,10 +1,11 @@
 export type ModelPickerBillingClass =
-  // Legacy public identifier for the OpenGeni presentation group, including
+  // Legacy public identifier for the Opengeni presentation group, including
   // free deployment models. Never use this UI grouping to decide settlement.
   | "opengeni_credits"
   | "external"
   | "codex_subscription"
   | "supergrok_subscription"
+  | "claude_subscription"
   | "byok"
   | "organization_byok";
 
@@ -15,11 +16,14 @@ const MODEL_PICKER_BILLING_CLASS_ORDER: readonly ModelPickerBillingClass[] = [
   "external",
   "codex_subscription",
   "supergrok_subscription",
+  "claude_subscription",
   "byok",
   "organization_byok",
 ];
 
 export type ModelPickerBillingCandidate = {
+  provider?: string | undefined;
+  providerId?: string | undefined;
   source?: string | undefined;
   cost?: "free" | "credits" | "subscription" | "workspace" | "organization" | undefined;
   billing?:
@@ -39,6 +43,13 @@ export type ModelPickerBillingCandidate = {
 export function modelPickerBillingClassFor(
   model: ModelPickerBillingCandidate,
 ): ModelPickerBillingClass {
+  if (
+    model.provider === "workspace-claude-subscription" ||
+    model.providerId === "workspace-claude-subscription" ||
+    model.provider === "organization-claude-subscription" ||
+    model.providerId === "organization-claude-subscription"
+  )
+    return "claude_subscription";
   if (model.cost === "credits" || model.cost === "free") return "opengeni_credits";
   if (model.cost === "workspace") return "byok";
   if (model.cost === "organization") return "organization_byok";

package/src/organization-access.ts

@@ -0,0 +1,217 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { Permission } from "./permissions";
+
+export const OrganizationAccessPreset = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["read_only", "full", "custom"]),
+);
+export type OrganizationAccessPreset = z.infer<typeof OrganizationAccessPreset>;
+
+export const OrganizationWorkspaceScope = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("all") }).strict(),
+    z
+      .object({
+        kind: z.literal("selected"),
+        workspaceIds: z
+          .array(
+            z
+              .string()
+              .uuid()
+              .transform((id) => id.toLowerCase()),
+          )
+          .max(500)
+          .refine((ids) => new Set(ids).size === ids.length, "Workspace IDs must be unique"),
+      })
+      .strict(),
+  ]),
+);
+export type OrganizationWorkspaceScope = z.infer<typeof OrganizationWorkspaceScope>;
+
+export const OrganizationActor = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["user", "organization"]),
+);
+export type OrganizationActor = z.infer<typeof OrganizationActor>;
+
+const aliases: Partial<Record<Permission, Permission>> = {
+  "environments:manage": "variable-sets:manage",
+  "environments:use": "variable-sets:use",
+};
+// Computed on first use, never at module load: the web build can place
+// `Permission` in a chunk that finishes initializing after this one, and a
+// top-level read of `Permission.options` then crashes the whole app.
+let permissionSets:
+  | { canonical: Permission[]; observational: Permission[]; readOnly: Permission[] }
+  | undefined;
+function sets() {
+  if (permissionSets) return permissionSets;
+  const canonical = Permission.options.filter((permission) => !aliases[permission]);
+  /** Everything that only observes. Reading secret values observes too. */
+  const observational = canonical.filter((permission) =>
+    /:(read|list|view|search)$/.test(permission),
+  );
+  /** Secret values are opt-in: Read only leaves them out, Custom can add them. */
+  const secretValue = new Set<Permission>(["secrets:read", "variable-sets:read"]);
+  const readOnly = observational.filter((permission) => !secretValue.has(permission));
+  permissionSets = { canonical, observational, readOnly };
+  return permissionSets;
+}
+
+/** Custom has no implicit permissions. Presets are expanded only by this helper. */
+export function organizationAccessPresetPermissions(
+  preset: OrganizationAccessPreset,
+): Permission[] {
+  return preset === "full"
+    ? [...sets().canonical]
+    : preset === "read_only"
+      ? [...sets().readOnly]
+      : [];
+}
+
+/** True when nothing can be changed, including an empty set and secret-value reads. */
+export function isReadOnlyPermissionSet(permissions: readonly Permission[]): boolean {
+  return permissions.every((permission) =>
+    sets().observational.includes(aliases[permission] ?? permission),
+  );
+}
+
+const OrganizationAccessPolicyInput = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      preset: OrganizationAccessPreset,
+      // Lazy for the same module-order reason as `sets()` above.
+      permissions: z.array(z.lazy(() => Permission)),
+      workspaceScope: OrganizationWorkspaceScope,
+    })
+    .strict(),
+);
+
+export type OrganizationAccessPolicy = z.infer<typeof OrganizationAccessPolicyInput>;
+
+/** Canonical ordering, alias mapping and labels; never adds an unrequested grant. */
+export function normalizeOrganizationAccessPolicy(
+  policy: OrganizationAccessPolicy,
+): OrganizationAccessPolicy {
+  const parsed = OrganizationAccessPolicyInput.parse(policy);
+  const requested = new Set(
+    parsed.permissions.map((permission) => aliases[permission] ?? permission),
+  );
+  const { canonical, readOnly } = sets();
+  const permissions = canonical.filter((permission) => requested.has(permission));
+  const same = (candidate: readonly Permission[]) =>
+    candidate.length === permissions.length &&
+    candidate.every((permission) => requested.has(permission));
+  return {
+    preset: same(canonical) ? "full" : same(readOnly) ? "read_only" : "custom",
+    permissions,
+    workspaceScope:
+      parsed.workspaceScope.kind === "selected"
+        ? { kind: "selected", workspaceIds: [...parsed.workspaceScope.workspaceIds].sort() }
+        : { kind: "all" },
+  };
+}
+
+export const OrganizationAccessPolicy = /* @__PURE__ */ defineSchema(() =>
+  OrganizationAccessPolicyInput.transform(normalizeOrganizationAccessPolicy),
+);
+
+/** Change what a connected agent can do. Only the person who connected it can. */
+export const UpdateOrganizationMcpConnectionRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({ access: OrganizationAccessPolicy }).strict(),
+);
+
+/**
+ * The answer to a pending agent sign-in: deny it, or approve it for one
+ * organization with the access the agent gets there.
+ */
+export const McpConnectionDecision = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("decision", [
+    z.object({ decision: z.literal("deny") }).strict(),
+    z
+      .object({
+        decision: z.literal("approve"),
+        organizationId: z.string().uuid(),
+        access: OrganizationAccessPolicy,
+      })
+      .strict(),
+  ]),
+);
+
+/* ----------------------------------------------------------------------------
+   Service accounts: an organization identity with no person behind it. It
+   holds organization API keys; its role caps what those keys can be given.
+   Up to admin, never owner.
+   -------------------------------------------------------------------------- */
+
+export const OrganizationServiceAccountRole = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["admin", "member"]),
+);
+export type OrganizationServiceAccountRole = z.infer<typeof OrganizationServiceAccountRole>;
+
+/** What only an organization administrator can do; a member service account's keys never hold it. */
+export const ORGANIZATION_ADMIN_ONLY_PERMISSIONS: readonly Permission[] = [
+  "account:admin",
+  "members:manage",
+  "billing:manage",
+  "api_keys:manage",
+  "usage_allowances:manage",
+];
+
+/** The permissions a service account's keys may hold, given its role. */
+export function serviceAccountAllowsPermission(
+  role: OrganizationServiceAccountRole,
+  permission: Permission,
+): boolean {
+  return role === "admin" || !ORGANIZATION_ADMIN_ONLY_PERMISSIONS.includes(permission);
+}
+
+export const OrganizationServiceAccount = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: z.string().uuid(),
+    organizationId: z.string().uuid(),
+    name: z.string().min(1).max(200),
+    description: z.string().nullable(),
+    role: OrganizationServiceAccountRole,
+    /** Keys that are not revoked, including expired ones. */
+    activeKeyCount: z.number().int().nonnegative(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }),
+);
+export type OrganizationServiceAccount = z.infer<typeof OrganizationServiceAccount>;
+
+export const ListOrganizationServiceAccountsResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    serviceAccounts: z.array(OrganizationServiceAccount),
+  }),
+);
+export type ListOrganizationServiceAccountsResponse = z.infer<
+  typeof ListOrganizationServiceAccountsResponse
+>;
+
+export const CreateOrganizationServiceAccountRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: z.string().trim().min(1).max(200),
+      description: z.string().trim().min(1).max(500).optional(),
+      role: OrganizationServiceAccountRole.default("member"),
+    })
+    .strict(),
+);
+export type CreateOrganizationServiceAccountRequest = z.infer<
+  typeof CreateOrganizationServiceAccountRequest
+>;
+
+export const UpdateOrganizationServiceAccountRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: z.string().trim().min(1).max(200).optional(),
+      description: z.string().trim().min(1).max(500).nullable().optional(),
+      role: OrganizationServiceAccountRole.optional(),
+    })
+    .strict()
+    .refine((request) => Object.keys(request).length > 0, "At least one change is required"),
+);
+export type UpdateOrganizationServiceAccountRequest = z.infer<
+  typeof UpdateOrganizationServiceAccountRequest
+>;

package/src/organization-integration-policy.ts

@@ -0,0 +1,63 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Catalog identities, never endpoint/domain matching. Custom transports are explicit categories. */
+export const OrganizationIntegrationKey = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[a-z0-9][a-z0-9._:-]*$/),
+);
+const keys = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(OrganizationIntegrationKey)
+    .max(10000)
+    .refine((values) => new Set(values).size === values.length, "Duplicate integration identities"),
+);
+export const OrganizationIntegrationPolicy = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      mode: z.enum(["unrestricted", "restricted"]).default("unrestricted"),
+      allowedIntegrationKeys: keys.default([]),
+      revision: z.number().int().nonnegative().safe().default(0),
+    })
+    .strict(),
+);
+export type OrganizationIntegrationPolicy = z.infer<typeof OrganizationIntegrationPolicy>;
+
+export const UpdateOrganizationIntegrationPolicyRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      mode: z.enum(["unrestricted", "restricted"]),
+      allowedIntegrationKeys: keys,
+      expectedRevision: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER - 1),
+      operationId: z.string().uuid(),
+    })
+    .strict(),
+);
+export type UpdateOrganizationIntegrationPolicyRequest = z.infer<
+  typeof UpdateOrganizationIntegrationPolicyRequest
+>;
+
+export class OrganizationIntegrationDeniedError extends Error {
+  constructor() {
+    super("Integration acquisition is not allowed by organization policy");
+    this.name = "OrganizationIntegrationDeniedError";
+  }
+}
+
+/** integrationKey must come from trusted classification, not client-supplied metadata. */
+export function assertOrganizationIntegrationAllowed(
+  policy: OrganizationIntegrationPolicy,
+  integrationKey: string | null,
+): void {
+  if (policy.mode === "unrestricted") return;
+  if (integrationKey === null || !policy.allowedIntegrationKeys.includes(integrationKey)) {
+    throw new OrganizationIntegrationDeniedError();
+  }
+}