@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/model-account-settings.ts

@@ -0,0 +1,210 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/**
+ * Organization model-account settings with lockable workspace overrides and
+ * the organization overview (contract SUB-SET-01..05). The organization sets
+ * every value; a shared workspace may override a value unless the
+ * organization locked it. Each effective value reports where it comes from.
+ */
+export const MODEL_ACCOUNT_SETTING_KEYS = [
+  "rotation",
+  "providers",
+  "crossProviderFailover",
+  "fallbackOrder",
+  "personalConnectionsAllowed",
+  "personalFallbackAllowed",
+] as const;
+export const ModelAccountSettingKey = /* @__PURE__ */ defineSchema(() =>
+  z.enum(MODEL_ACCOUNT_SETTING_KEYS),
+);
+export type ModelAccountSettingKey = z.infer<typeof ModelAccountSettingKey>;
+
+/** organization: the organization value; workspace: this workspace's override; locked: the organization value, which workspaces cannot override. */
+export const ModelAccountSettingSource = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["organization", "workspace", "locked"]),
+);
+export type ModelAccountSettingSource = z.infer<typeof ModelAccountSettingSource>;
+
+const SAFE_KEY = (key: string) => !["__proto__", "constructor", "prototype"].includes(key);
+const ModelId = /* @__PURE__ */ defineSchema(() => z.string().min(1).max(200).refine(SAFE_KEY));
+const ProviderId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{1,31}$/)
+    .refine(SAFE_KEY),
+);
+
+export const ModelAccountRotationMode = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["spread", "primary_first"]),
+);
+export type ModelAccountRotationMode = z.infer<typeof ModelAccountRotationMode>;
+
+/** Ordered fallback models for a preferred model (at most 64 models, 8 fallbacks each). */
+export const ModelAccountFallbackOrder = /* @__PURE__ */ defineSchema(() =>
+  z
+    .record(ModelId, z.array(ModelId).max(8))
+    .refine((value) => Object.keys(value).length <= 64, "At most 64 models"),
+);
+
+export const ModelAccountSettingValues = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    rotation: z.record(
+      z.string(),
+      z.object({
+        mode: ModelAccountRotationMode,
+        primaryConnectionId: z.string().nullable().optional(),
+      }),
+    ),
+    providers: z.record(
+      z.string(),
+      z.object({
+        inferenceSource: z.enum(["automatic", "workspace", "organization"]).optional(),
+        useOrganizationAccounts: z.boolean(),
+        enabled: z.boolean(),
+      }),
+    ),
+    crossProviderFailover: z.boolean(),
+    fallbackOrder: z.record(z.string(), z.array(z.string())),
+    personalConnectionsAllowed: z.boolean(),
+    personalFallbackAllowed: z.boolean(),
+  }),
+);
+export type ModelAccountSettingValues = z.infer<typeof ModelAccountSettingValues>;
+
+const ModelAccountSettingSources = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    rotation: ModelAccountSettingSource,
+    providers: ModelAccountSettingSource,
+    crossProviderFailover: ModelAccountSettingSource,
+    fallbackOrder: ModelAccountSettingSource,
+    personalConnectionsAllowed: ModelAccountSettingSource,
+    personalFallbackAllowed: ModelAccountSettingSource,
+  }),
+);
+
+const EntrySource = /* @__PURE__ */ defineSchema(() =>
+  z.record(z.string(), z.enum(["organization", "workspace"])),
+);
+
+/** Effective values with one source per setting and, for map-valued settings, per entry. */
+const ModelAccountSettingsView = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    values: ModelAccountSettingValues,
+    sources: ModelAccountSettingSources,
+    entrySources: z.object({
+      rotation: EntrySource,
+      providers: EntrySource,
+      fallbackOrder: EntrySource,
+    }),
+  }),
+);
+
+export const OrganizationModelAccountSettings = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    organizationId: z.string(),
+    values: ModelAccountSettingValues,
+    locked: z.array(ModelAccountSettingKey),
+    /** Pass back as `expectedVersion` to refuse a write over a concurrent change. */
+    version: z.number().int().nonnegative(),
+    updatedAt: z.string().nullable(),
+  }),
+);
+export type OrganizationModelAccountSettings = z.infer<typeof OrganizationModelAccountSettings>;
+
+/**
+ * PATCH body for the organization: omitted fields are kept; `fallbackOrder`
+ * and `locked` replace the stored value; `rotation` sets the mode of each
+ * named provider whose accounts run on the shared core. Locking a setting
+ * clears every workspace override of it.
+ */
+export const UpdateOrganizationModelAccountSettingsRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      crossProviderFailover: z.boolean().optional(),
+      fallbackOrder: ModelAccountFallbackOrder.optional(),
+      personalConnectionsAllowed: z.boolean().optional(),
+      personalFallbackAllowed: z.boolean().optional(),
+      rotation: z
+        .record(ProviderId, z.object({ mode: ModelAccountRotationMode }).strict())
+        .optional(),
+      locked: z.array(ModelAccountSettingKey).max(MODEL_ACCOUNT_SETTING_KEYS.length).optional(),
+      expectedVersion: z.number().int().nonnegative().optional(),
+    })
+    .strict(),
+);
+export type UpdateOrganizationModelAccountSettingsRequest = z.infer<
+  typeof UpdateOrganizationModelAccountSettingsRequest
+>;
+
+/** A workspace's stored overrides: null follows the organization. */
+export const ModelAccountSettingOverrides = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    rotation: z.record(z.string(), z.unknown()).nullable(),
+    providers: z.record(z.string(), z.unknown()).nullable(),
+    crossProviderFailover: z.boolean().nullable(),
+    fallbackOrder: z.record(z.string(), z.array(z.string())).nullable(),
+    personalConnectionsAllowed: z.boolean().nullable(),
+    personalFallbackAllowed: z.boolean().nullable(),
+  }),
+);
+
+export const WorkspaceModelAccountSettings = /* @__PURE__ */ defineSchema(() =>
+  ModelAccountSettingsView.extend({
+    workspaceId: z.string(),
+    locked: z.array(ModelAccountSettingKey),
+    overrides: ModelAccountSettingOverrides,
+    version: z.number().int().nonnegative(),
+    updatedAt: z.string().nullable(),
+    /** Whether the caller may change this workspace's overrides. */
+    canEdit: z.boolean(),
+  }),
+);
+export type WorkspaceModelAccountSettings = z.infer<typeof WorkspaceModelAccountSettings>;
+
+/**
+ * PATCH body for a workspace: omitted fields are kept and `null` follows the
+ * organization again. `fallbackOrder` and `rotation` change entry by entry;
+ * a `null` entry follows the organization for that entry. A setting the
+ * organization locked cannot be set.
+ */
+export const UpdateWorkspaceModelAccountSettingsRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      crossProviderFailover: z.boolean().nullable().optional(),
+      personalConnectionsAllowed: z.boolean().nullable().optional(),
+      personalFallbackAllowed: z.boolean().nullable().optional(),
+      fallbackOrder: z
+        .record(ModelId, z.array(ModelId).max(8).nullable())
+        .refine((value) => Object.keys(value).length <= 64, "At most 64 models")
+        .nullable()
+        .optional(),
+      rotation: z
+        .record(ProviderId, z.object({ mode: ModelAccountRotationMode }).strict().nullable())
+        .nullable()
+        .optional(),
+      expectedVersion: z.number().int().nonnegative().optional(),
+    })
+    .strict(),
+);
+export type UpdateWorkspaceModelAccountSettingsRequest = z.infer<
+  typeof UpdateWorkspaceModelAccountSettingsRequest
+>;
+
+export const ModelAccountSettingsOverviewWorkspace = /* @__PURE__ */ defineSchema(() =>
+  ModelAccountSettingsView.extend({
+    workspaceId: z.string(),
+    name: z.string(),
+  }),
+);
+
+/** Every shared workspace's effective settings and sources, in pages ordered by workspace id. */
+export const ModelAccountSettingsOverview = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    organization: OrganizationModelAccountSettings,
+    workspaces: z.array(ModelAccountSettingsOverviewWorkspace),
+    /** Pass as `after` for the next page; null after the last workspace. */
+    nextCursor: z.string().nullable(),
+  }),
+);
+export type ModelAccountSettingsOverview = z.infer<typeof ModelAccountSettingsOverview>;

package/src/model-availability.ts

@@ -0,0 +1,22 @@
+/**
+ * `details.code` on a 422 `validation_failed` envelope when the requested or
+ * stored model is not in the live model catalog (retired, removed, or never
+ * offered). Retrying the same request cannot succeed; the client must choose
+ * another model. Additive to the public error envelope: `code` stays
+ * `validation_failed` and the message keeps its historical text.
+ */
+export const MODEL_UNAVAILABLE_ERROR_CODE = "model_unavailable" as const;
+
+/** Typed cause for a model that is not selectable in the live catalog. */
+export class ModelUnavailableError extends Error {
+  readonly code = MODEL_UNAVAILABLE_ERROR_CODE;
+
+  constructor(readonly modelId: string) {
+    super(`model is not available: ${modelId}`);
+    this.name = "ModelUnavailableError";
+  }
+}
+
+export function isModelUnavailableError(error: unknown): error is ModelUnavailableError {
+  return error instanceof ModelUnavailableError;
+}

package/src/model-connection-access.ts

@@ -1,17 +1,64 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const ModelConnectionAccessPolicy = z
-  .object({
-    allowedModels: z.array(z.string().trim().min(1).max(256)).max(500).nullable(),
-    allowedWorkspaces: z.array(z.string().uuid()).max(500).nullable(),
-    allowPersonalWorkspaces: z.boolean(),
-    version: z.number().int().positive(),
-  })
-  .strict();
+export const ModelConnectionAccessPolicy = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      allowedModels: z.array(z.string().trim().min(1).max(256)).max(500).nullable(),
+      /**
+       * Organization-pool grants: the shared workspaces that may use the account,
+       * or null for every shared workspace, including ones created later. A
+       * workspace's own copy (`localWorkspaceIds` in the response) is reported
+       * separately and is never cleared by this list.
+       */
+      allowedWorkspaces: z.array(z.string().uuid()).max(500).nullable(),
+      allowPersonalWorkspaces: z.boolean(),
+      /**
+       * Organization memberships of the chosen people, or null when the account
+       * is not limited to people. Non-null requires `allowedWorkspaces: []` and
+       * `allowPersonalWorkspaces: false`. Only organization accounts on the shared
+       * subscription core support it (`peopleSupported`).
+       */
+      allowedPeople: z.array(z.string().uuid()).max(1000).nullable().optional(),
+      /** Explicit owner consent to convert a personal subscription into a shared account. */
+      sharePersonal: z.literal(true).optional(),
+      version: z.number().int().positive(),
+    })
+    .strict(),
+);
 
-export const ModelConnectionAccessResponse = z.object({
-  policy: ModelConnectionAccessPolicy,
-  models: z.array(z.object({ id: z.string(), label: z.string() })),
-  workspaces: z.array(z.object({ id: z.string().uuid(), name: z.string() })),
-  personalWorkspacesSupported: z.boolean(),
-});
+export const ModelConnectionAccessResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    policy: ModelConnectionAccessPolicy,
+    models: z.array(z.object({ id: z.string(), label: z.string() })),
+    workspaces: z.array(z.object({ id: z.string().uuid(), name: z.string() })),
+    personalWorkspacesSupported: z.boolean(),
+    /**
+     * The account can be limited to chosen people (`allowedPeople`): an
+     * organization account no workspace manages (people scope would hide it
+     * from a managing workspace's administrators).
+     */
+    peopleSupported: z.boolean().optional(),
+    /** The people an administrator can choose: active members of the organization. */
+    people: z
+      .array(
+        z.object({
+          id: z.string().uuid(),
+          name: z.string().nullable(),
+          email: z.string().nullable(),
+        }),
+      )
+      .max(1000)
+      .optional(),
+    /**
+     * Workspaces that use the account as their own (it was connected there).
+     * They keep it whatever is chosen for workspaces; choosing people limits
+     * them to the chosen people too.
+     */
+    localWorkspaceIds: z.array(z.string().uuid()).max(500).optional(),
+    /** The workspace whose administrators also manage the account, if any. */
+    managedByWorkspaceId: z.string().uuid().nullable().optional(),
+    /** Exact personal owner is also an organization administrator; sharing requires explicit consent. */
+    personalSharingSupported: z.boolean().optional(),
+  }),
+);

package/src/model-context-inspector.ts

@@ -1,4 +1,6 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
+import { AGENT_PROMPT_MODULE_IDS, AgentPromptModuleId } from "./agent-config";
 
 export const MODEL_CONTEXT_SNAPSHOT_VERSION = 1 as const;
 export const MODEL_CONTEXT_INSTRUCTIONS_MAX_UTF8_BYTES = 8 * 1024 * 1024;
@@ -7,119 +9,151 @@ export const MODEL_CONTEXT_LAYER_MAX_COUNT = 16;
 export const MODEL_CONTEXT_TOOL_MAX_COUNT = 2_048;
 export const MODEL_CONTEXT_SKILL_MAX_COUNT = 1_024;
 
-export const ModelContextInstructionLayerId = z.enum([
-  "skill_catalog",
-  "operational_contract",
-  "persona_and_core",
-  "workspace_governance",
-  "session_instructions",
-  "workspace_memory",
-  "codemode",
-  "git_bindings",
-  "builtin_skills",
-  "genesis_title",
-  "sdk_capability_instructions",
-  "sandbox_preamble",
-  "sandbox_filesystem",
-  "sent_system_instructions",
-]);
+export const ModelContextInstructionLayerId = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "skill_catalog",
+    "operational_contract",
+    "persona_and_core",
+    "workspace_governance",
+    "session_instructions",
+    "workspace_memory",
+    "codemode",
+    "code_search",
+    "git_bindings",
+    "builtin_skills",
+    "genesis_title",
+    "sdk_capability_instructions",
+    "sandbox_preamble",
+    "sandbox_filesystem",
+    "sent_system_instructions",
+    "identity",
+  ]),
+);
 export type ModelContextInstructionLayerId = z.infer<typeof ModelContextInstructionLayerId>;
 
-export const ModelContextInstructionLayer = z
-  .object({
-    id: ModelContextInstructionLayerId,
-    title: z.string().min(1).max(120),
-    content: z.string(),
-    utf8Bytes: z.number().int().nonnegative(),
-    estimatedTokens: z.number().int().nonnegative(),
-  })
-  .strict();
+/** One prompt module inside a layer (modular operational contract only). */
+export const ModelContextInstructionModule = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: AgentPromptModuleId,
+      chars: z.number().int().nonnegative(),
+    })
+    .strict(),
+);
+export type ModelContextInstructionModule = z.infer<typeof ModelContextInstructionModule>;
+
+export const ModelContextInstructionLayer = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: ModelContextInstructionLayerId,
+      title: z.string().min(1).max(120),
+      content: z.string(),
+      utf8Bytes: z.number().int().nonnegative(),
+      estimatedTokens: z.number().int().nonnegative(),
+      // Composition-order prompt modules of a modular operational contract.
+      modules: z
+        .array(ModelContextInstructionModule)
+        .max(AGENT_PROMPT_MODULE_IDS.length)
+        .optional(),
+    })
+    .strict(),
+);
 export type ModelContextInstructionLayer = z.infer<typeof ModelContextInstructionLayer>;
 
-export const ModelContextToolVisibility = z.enum(["eager", "searchable"]);
+export const ModelContextToolVisibility = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["eager", "searchable"]),
+);
 export type ModelContextToolVisibility = z.infer<typeof ModelContextToolVisibility>;
 
-export const ModelContextTool = z
-  .object({
-    name: z.string().min(1).max(256),
-    type: z.string().min(1).max(64),
-    visibility: ModelContextToolVisibility,
-    description: z.string().max(16_384).optional(),
-    namespace: z.string().max(256).optional(),
-    schema: z.unknown().optional(),
-    utf8Bytes: z.number().int().nonnegative(),
-    estimatedTokens: z.number().int().nonnegative(),
-  })
-  .strict();
+export const ModelContextTool = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: z.string().min(1).max(256),
+      type: z.string().min(1).max(64),
+      visibility: ModelContextToolVisibility,
+      description: z.string().max(16_384).optional(),
+      namespace: z.string().max(256).optional(),
+      schema: z.unknown().optional(),
+      utf8Bytes: z.number().int().nonnegative(),
+      estimatedTokens: z.number().int().nonnegative(),
+    })
+    .strict(),
+);
 export type ModelContextTool = z.infer<typeof ModelContextTool>;
 
-export const ModelContextSkillKind = z.enum([
-  "preference_descriptor",
-  "runtime_skill",
-  "native_tool_skill",
-]);
+export const ModelContextSkillKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["preference_descriptor", "runtime_skill", "native_tool_skill"]),
+);
 export type ModelContextSkillKind = z.infer<typeof ModelContextSkillKind>;
 
-export const ModelContextSkill = z
-  .object({
-    kind: ModelContextSkillKind,
-    name: z.string().min(1).max(128),
-    description: z.string().max(8_192),
-    source: z.string().max(64).optional(),
-    path: z.string().max(1_024).optional(),
-  })
-  .strict();
+export const ModelContextSkill = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      kind: ModelContextSkillKind,
+      name: z.string().min(1).max(128),
+      description: z.string().max(8_192),
+      source: z.string().max(64).optional(),
+      path: z.string().max(1_024).optional(),
+    })
+    .strict(),
+);
 export type ModelContextSkill = z.infer<typeof ModelContextSkill>;
 
-export const ModelContextTokenCounts = z
-  .object({
-    instructions: z.number().int().nonnegative(),
-    tools: z.number().int().nonnegative(),
-    prefix: z.number().int().nonnegative(),
-  })
-  .strict();
+export const ModelContextTokenCounts = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      instructions: z.number().int().nonnegative(),
+      tools: z.number().int().nonnegative(),
+      prefix: z.number().int().nonnegative(),
+    })
+    .strict(),
+);
 export type ModelContextTokenCounts = z.infer<typeof ModelContextTokenCounts>;
 
-export const ModelContextSnapshot = z
-  .object({
-    version: z.literal(MODEL_CONTEXT_SNAPSHOT_VERSION),
-    capturedAt: z.string().datetime(),
-    source: z.literal("model_request"),
-    requestIndex: z.number().int().nonnegative(),
-    instructions: z.string(),
-    // Absent on historical SDK-prefix captures. Never infer a wire payload.
-    providerRequest: z
-      .object({
-        provider: z.string(),
-        body: z.string().nullable(),
-        unavailableReason: z.string().optional(),
-        parts: z.array(
-          z
-            .object({
-              key: z.string(),
-              estimatedTokens: z.number().int().nonnegative().nullable(),
-              utf8Bytes: z.number().int().nonnegative(),
-              itemEstimatedTokens: z.array(z.number().int().nonnegative().nullable()).optional(),
-            })
-            .strict(),
-        ),
-      })
-      .strict()
-      .optional(),
-    layers: z.array(ModelContextInstructionLayer).max(MODEL_CONTEXT_LAYER_MAX_COUNT),
-    tools: z.array(ModelContextTool).max(MODEL_CONTEXT_TOOL_MAX_COUNT),
-    skills: z.array(ModelContextSkill).max(MODEL_CONTEXT_SKILL_MAX_COUNT),
-    tokens: ModelContextTokenCounts,
-  })
-  .strict();
+export const ModelContextSnapshot = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(MODEL_CONTEXT_SNAPSHOT_VERSION),
+      capturedAt: z.string().datetime(),
+      source: z.literal("model_request"),
+      requestIndex: z.number().int().nonnegative(),
+      instructions: z.string(),
+      // Absent on historical SDK-prefix captures. Never infer a wire payload.
+      providerRequest: z
+        .object({
+          provider: z.string(),
+          body: z.string().nullable(),
+          unavailableReason: z.string().optional(),
+          parts: z.array(
+            z
+              .object({
+                key: z.string(),
+                estimatedTokens: z.number().int().nonnegative().nullable(),
+                utf8Bytes: z.number().int().nonnegative(),
+                itemEstimatedTokens: z.array(z.number().int().nonnegative().nullable()).optional(),
+              })
+              .strict(),
+          ),
+        })
+        .strict()
+        .optional(),
+      layers: z.array(ModelContextInstructionLayer).max(MODEL_CONTEXT_LAYER_MAX_COUNT),
+      tools: z.array(ModelContextTool).max(MODEL_CONTEXT_TOOL_MAX_COUNT),
+      skills: z.array(ModelContextSkill).max(MODEL_CONTEXT_SKILL_MAX_COUNT),
+      tokens: ModelContextTokenCounts,
+    })
+    .strict(),
+);
 export type ModelContextSnapshot = z.infer<typeof ModelContextSnapshot>;
 
-export const SessionModelContextResponse = z
-  .object({
-    sessionId: z.string().uuid(),
-    attemptId: z.string().uuid().nullable(),
-    turnId: z.string().uuid().nullable(),
-    snapshot: ModelContextSnapshot.nullable(),
-  })
-  .strict();
+export const SessionModelContextResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      sessionId: z.string().uuid(),
+      attemptId: z.string().uuid().nullable(),
+      turnId: z.string().uuid().nullable(),
+      snapshot: ModelContextSnapshot.nullable(),
+    })
+    .strict(),
+);
 export type SessionModelContextResponse = z.infer<typeof SessionModelContextResponse>;