@vertesia/common 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/src/api-schemas/interaction.ts

@@ -5,6 +5,7 @@ import {
     JSONSchemaSchema,
     ModalitiesSchema,
     ModelOptionsSchema,
+    PromptCacheDiagnosticSchema,
     PromptRoleSchema,
     StatelessExecutionOptionsSchema,
     ToolDefinitionSchema,
@@ -25,6 +26,7 @@ import { ProjectRefSchema } from './apikey.js';
 import { ExecutionEnvironmentRefSchema } from './environment.js';
 import { AccountRefSchema } from './invites.js';
 import { AgentCheckpointConfigurationSchema } from './project-configuration.js';
+import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema, RunDataStorageLevelSchema } from './store.js';
 
 /**
@@ -40,7 +42,11 @@ export const ExecutionRunStatusSchema = z.enum(ExecutionRunStatus).meta({ id: 'E
 
 export const FacetSpecSchema = z
     .strictObject({
-        name: z.string(),
+        name: z.string().meta({
+            description:
+                'Key the buckets are returned under. `total` is reserved for the match count that every facet ' +
+                'response carries, and is rejected with a 400.',
+        }),
         field: z.string(),
     })
     .meta({ id: 'FacetSpec' });
@@ -401,6 +407,7 @@ export const PromptTemplateSchema = z
         name: z.string(),
         status: PromptStatusSchema,
         version: z.number(),
+        edit_revision: EditRevisionSchema,
         // The record this one was derived from. On a published version it is the draft it was
         // published from; on a fork it is the prompt that was forked, and the fork is itself a
         // draft. So `parent` alone does not tell you which kind of record this is — read `status`.
@@ -424,7 +431,15 @@ export const PromptTemplateSchema = z
 // The two payloads are projections of `PromptTemplate`, so they are derived from its canonical Zod
 // schema here. Leaving them as TypeScript utility types would give the generator only aliases with
 // no runtime properties to publish.
-const SERVER_OWNED_PROMPT_FIELDS = ['id', 'created_at', 'updated_at', 'created_by', 'updated_by', 'project'] as const;
+const SERVER_OWNED_PROMPT_FIELDS = [
+    'id',
+    'edit_revision',
+    'created_at',
+    'updated_at',
+    'created_by',
+    'updated_by',
+    'project',
+] as const;
 const SERVER_OWNED_PROMPT_FIELD_KEYS = Object.fromEntries(
     SERVER_OWNED_PROMPT_FIELDS.map((field) => [field, true as const]),
 ) as Record<(typeof SERVER_OWNED_PROMPT_FIELDS)[number], true>;
@@ -448,6 +463,7 @@ export const PromptTemplateCreatePayloadSchema = PromptTemplateSchema.pick({
 
 export const PromptTemplateUpdatePayloadSchema = PromptTemplateSchema.omit(SERVER_OWNED_PROMPT_FIELD_KEYS)
     .partial()
+    .extend({ expected_edit_revision: ExpectedEditRevisionSchema })
     .meta({ id: 'PromptTemplateUpdatePayload' });
 
 export const CachePolicySchema = z
@@ -896,6 +912,13 @@ export const PromptTemplateRefSchema = z
     })
     .meta({ id: 'PromptTemplateRef' });
 
+// Interaction writes may carry a populated prompt copied from an interaction response. New clients
+// preserve its revision while legacy clients never sent one, so the embedded request shape accepts
+// both. The standalone PromptTemplate response keeps the revision required.
+export const InteractionPromptTemplateInputSchema = PromptTemplateSchema.extend({
+    edit_revision: EditRevisionSchema.optional(),
+}).meta({ id: 'InteractionPromptTemplateInput' });
+
 export const RunSourceSchema = z
     .strictObject({
         type: RunSourceTypesSchema,
@@ -915,6 +938,12 @@ export const PromptSegmentDefSchema = z
     })
     .meta({ id: 'PromptSegmentDef' });
 
+export const InteractionPromptSegmentInputSchema = PromptSegmentDefSchema.extend({
+    template: z
+        .union([z.string(), PromptTemplateSchema, InteractionPromptTemplateInputSchema, PromptTemplateRefSchema])
+        .optional(),
+}).meta({ id: 'InteractionPromptSegmentInput' });
+
 export const InteractionEndpointSchema = z
     .strictObject({
         id: z.string(),
@@ -942,7 +971,7 @@ export const InteractionCreatePayloadSchema = z
         test_data: JSONObjectSchema.optional(),
         interaction_schema: z.union([JSONSchemaSchema, SchemaRefSchema]).optional(),
         cache_policy: CachePolicySchema.optional(),
-        prompts: z.array(PromptSegmentDefSchema),
+        prompts: z.array(InteractionPromptSegmentInputSchema),
         last_published_at: z.string().meta({ format: 'date-time' }).optional(),
         name: z.string(),
         description: z.string().optional(),
@@ -951,6 +980,7 @@ export const InteractionCreatePayloadSchema = z
         environment: z.union([z.string(), ExecutionEnvironmentRefSchema]).optional(),
         model: z.string().optional(),
         model_options: ModelOptionsSchema.optional(),
+        store_media_results: z.boolean().optional(),
         restriction: RunDataStorageLevelSchema.optional(),
         output_modality: ModalitiesSchema.meta({
             description: 'Deprecated: This is deprecated. Use CompletionResult.type information instead.',
@@ -965,6 +995,7 @@ export const InteractionCreatePayloadSchema = z
 export const InteractionSchema = z
     .strictObject({
         id: z.string(),
+        edit_revision: EditRevisionSchema,
         name: z.string(),
         endpoint: z.string(),
         description: z.string().optional(),
@@ -975,6 +1006,7 @@ export const InteractionSchema = z
         environment: z.union([z.string(), ExecutionEnvironmentRefSchema]).optional(),
         model: z.string().optional(),
         model_options: ModelOptionsSchema.optional(),
+        store_media_results: z.boolean().optional(),
         restriction: RunDataStorageLevelSchema.optional(),
         output_modality: ModalitiesSchema.meta({
             description: 'Deprecated: This is deprecated. Use CompletionResult.type information instead.',
@@ -1047,6 +1079,43 @@ export const CatalogInteractionRefSchema = z
             'Reference to an interaction in the catalog. Used in catalog listing. The id is composed of the namespace and the interaction name. Stored interactions can use `oid:` prefix. If no prefix is used it fallback on `oid:`.',
     });
 
+export const InCodeInteractionSchema = z
+    .strictObject({
+        type: z.enum(['sys', 'app', 'stored', 'draft']).meta({ description: 'The interaction type.' }),
+        id: z.string().meta({ description: 'The executable catalog interaction ID.' }),
+        name: z.string().meta({ description: 'The interaction code name.' }),
+        version: z.number().optional(),
+        published: z.boolean().optional(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        result_schema: z.union([JSONSchemaSchema, SchemaRefSchema]).optional(),
+        output_modality: ModalitiesSchema.optional(),
+        storage: RunDataStorageLevelSchema.optional(),
+        tags: z.array(z.string()).optional(),
+        agent_runner_options: AgentRunnerOptionsSchema.optional(),
+        model_options: ModelOptionsSchema.optional(),
+        prompts: z.array(InCodePromptSchema),
+        externalId: z.string().optional(),
+        runtime: z
+            .strictObject({
+                environment: z.string().optional(),
+                model: z.string().optional(),
+            })
+            .optional(),
+    })
+    .meta({
+        id: 'InCodeInteraction',
+        description: 'An executable interaction definition, including the prompt schemas required by clients.',
+    });
+
+export const ResolvedCatalogInteractionSchema = InCodeInteractionSchema.extend({
+    title: z.string().meta({ description: 'Display title, normalized from the interaction name when absent.' }),
+    tags: z.array(z.string()).meta({ description: 'Tags, normalized to an empty array when absent.' }),
+}).meta({
+    id: 'ResolvedCatalogInteraction',
+    description: 'A catalog interaction resolved to its complete executable definition.',
+});
+
 export const RunSearchPayloadSchema = z
     .strictObject({
         facets: z.array(FacetSpecSchema).optional(),
@@ -1140,6 +1209,7 @@ export const PromptSegmentRef_PromptTemplateRefSchema = z
 
 export const InteractionUpdatePayloadSchema = z
     .strictObject({
+        expected_edit_revision: ExpectedEditRevisionSchema,
         status: InteractionStatusSchema.optional(),
         parent: z.string().optional(),
         visibility: InteractionVisibilitySchema.optional(),
@@ -1147,7 +1217,7 @@ export const InteractionUpdatePayloadSchema = z
         test_data: JSONObjectSchema.optional(),
         interaction_schema: z.union([JSONSchemaSchema, SchemaRefSchema]).optional(),
         cache_policy: CachePolicySchema.optional(),
-        prompts: z.array(PromptSegmentDefSchema).optional(),
+        prompts: z.array(InteractionPromptSegmentInputSchema).optional(),
         last_published_at: z.string().meta({ format: 'date-time' }).optional(),
         name: z.string().optional(),
         endpoint: z.string().optional(),
@@ -1157,6 +1227,7 @@ export const InteractionUpdatePayloadSchema = z
         environment: z.union([z.string(), ExecutionEnvironmentRefSchema]).optional(),
         model: z.string().optional(),
         model_options: ModelOptionsSchema.optional(),
+        store_media_results: z.boolean().optional(),
         restriction: RunDataStorageLevelSchema.optional(),
         output_modality: ModalitiesSchema.meta({
             description: 'Deprecated: This is deprecated. Use CompletionResult.type information instead.',
@@ -1364,6 +1435,7 @@ export const ExecutionRunSchema: z.ZodType = z
         finish_reason: z.string().optional(),
         prompt: z.unknown().optional(),
         token_use: ExecutionTokenUsageSchema.optional(),
+        prompt_cache_diagnostics: z.array(PromptCacheDiagnosticSchema).optional(),
         chunks: z.number().optional(),
         execution_time: z.number().optional(),
         created_at: z.string().meta({ format: 'date-time' }),
@@ -1422,6 +1494,7 @@ export const InteractionExecutionResultSchema = z
         finish_reason: z.string().optional(),
         prompt: z.unknown().optional(),
         token_use: ExecutionTokenUsageSchema.optional(),
+        prompt_cache_diagnostics: z.array(PromptCacheDiagnosticSchema).optional(),
         chunks: z.number().optional(),
         execution_time: z.number().optional(),
         created_at: z.string().meta({ format: 'date-time' }),
@@ -1466,6 +1539,27 @@ export const PopulatedExecutionRunResultSchema = InteractionExecutionResultSchem
     description: 'An execution run with its completion result and its interaction reference populated.',
 });
 
+/**
+ * Stored run fields returned by the internal `/runs/find` projection endpoint.
+ * Callers choose an arbitrary MongoDB projection, so every field is optional and references remain ids.
+ */
+export const FindRunResultSchema = InteractionExecutionResultSchema.omit({
+    tool_use: true,
+    conversation: true,
+    options: true,
+})
+    .extend({
+        environment: z.string(),
+    })
+    .partial()
+    .meta({
+        id: 'FindRunResult',
+        description:
+            'A caller-selected subset of canonical stored run fields. Internal persistence fields are normalized at the API boundary.',
+    });
+
+export const FindRunResultArraySchema = z.array(FindRunResultSchema).meta({ id: 'FindRunResultArray' });
+
 /**
  * `result` in the shape the pre-`COMPLETION_RESULT_V1` endpoints report it.
  *
@@ -1521,8 +1615,10 @@ export const ExecutionRunRefSchema = z
             })
             .optional(),
         tags: z.array(z.string()).optional(),
-        environment: ExecutionEnvironmentRefSchema.meta({
-            description: 'Environment reference - populated with full object in API responses',
+        environment: z.union([ExecutionEnvironmentRefSchema, z.string(), z.null()]).meta({
+            description:
+                'Environment reference. API responses normally contain the populated environment object; the ' +
+                'stored environment ID or null is retained when the referenced environment no longer exists.',
         }),
         modelId: z.string().optional(),
         result_schema: JSONSchemaSchema.optional(),
@@ -1531,6 +1627,7 @@ export const ExecutionRunRefSchema = z
         finish_reason: z.string().optional(),
         prompt: z.unknown().optional(),
         token_use: ExecutionTokenUsageSchema.optional(),
+        prompt_cache_diagnostics: z.array(PromptCacheDiagnosticSchema).optional(),
         chunks: z.number().optional(),
         execution_time: z.number().optional(),
         created_at: z.string().meta({ format: 'date-time' }),
@@ -1552,6 +1649,8 @@ export const ExecutionRunRefSchema = z
                 'The Vertesia Workflow related to this Interaction Run.\n\nThis is only set when the interaction is executed as part of a workflow.',
         }).optional(),
         interaction: InteractionRefSchema.optional(),
+        result: z.array(CompletionResultSchema).optional(),
+        parameters: z.unknown().optional(),
     })
     .meta({ id: 'ExecutionRunRef' });
 
@@ -1604,6 +1703,10 @@ export const ConversationStateSchema = z
         tool_reference: ToolReferenceSchema.meta({
             description: 'Reference to tools stored in GCP instead of embedding full tool definitions',
         }).optional(),
+        tool_catalog_storage_id: z
+            .string()
+            .meta({ description: 'Artifact-storage scope containing the referenced tool catalog.' })
+            .optional(),
         active_tool_names: z
             .array(z.string())
             .meta({
@@ -1687,7 +1790,7 @@ export const ConversationStateSchema = z
             .array(z.string())
             .meta({
                 description:
-                    'Names of skills whose full instructions are already present in the live conversation history (i.e. were delivered by a prior `learn_<skill>` call). Used to make skill re-activation idempotent: a repeat call returns a short "already active" acknowledgement instead of re-dumping the instructions.\n\nUnlike `unlocked_tools` (which must survive a checkpoint so tools stay unlocked), this list is reset when a checkpoint compacts the conversation, because the summary no longer carries the skill instructions and the next call must re-deliver them.',
+                    'Names of skills whose full instructions are already present in the live conversation history (i.e. were delivered by a prior `learn_<skill>` call). Used to make skill re-activation idempotent: a repeat call returns a short "already active" acknowledgement instead of re-dumping the instructions.\n\nUnlike `unlocked_tools` (which must survive a checkpoint so tools stay unlocked), this list tracks only instructions present in the current compacted conversation. Checkpoints restore active builtin skill bodies and preserve their names; skills that cannot be restored are removed so the next call can re-deliver them.',
             })
             .optional(),
         initialization_call_ids: z
@@ -1775,6 +1878,7 @@ export const UpdateExecutionRunPayloadSchema = z
         finish_reason: z.string().optional(),
         prompt: z.unknown().optional(),
         token_use: ExecutionTokenUsageSchema.optional(),
+        prompt_cache_diagnostics: z.array(PromptCacheDiagnosticSchema).optional(),
         chunks: z.number().optional(),
         execution_time: z.number().optional(),
         created_at: z.string().meta({ format: 'date-time' }).optional(),
@@ -1990,12 +2094,36 @@ export const AsyncInteractionExecutionPayloadSchema = z
     })
     .meta({ id: 'AsyncInteractionExecutionPayload' });
 
+export const ConversationEnrichmentFields = {
+    title: z.string().min(1).meta({ description: 'Caller-provided conversation title.' }).optional(),
+    topic: z
+        .string()
+        .min(1)
+        .meta({ description: 'Caller-provided conversation topic. Suppresses automatic topic generation.' })
+        .optional(),
+    generate_topic: z
+        .boolean()
+        .meta({
+            description:
+                'Whether to generate a conversation title and topic automatically. Defaults to true; a caller-provided topic always suppresses generation.',
+        })
+        .optional(),
+    generate_lessons: z
+        .boolean()
+        .meta({
+            description:
+                'Whether to generate lessons automatically at completion. Defaults to true; conversation content remains searchable when disabled.',
+        })
+        .optional(),
+};
+
 export const AsyncConversationExecutionPayloadSchema = z
     .object({
         interaction: z.string().meta({
             description:
                 'The interaction name and suffixed by an optional tag or version separated from the name using a @ character If no version/tag part is specified then the latest version is used. Example: ReviewContract, ReviewContract@draft, ReviewContract@1, ReviewContract@some-tag',
         }),
+        ...ConversationEnrichmentFields,
         app_version: z
             .string()
             .meta({
@@ -2290,6 +2418,15 @@ export const ResolveInteractionQuerySchema = z
 // a union here would publish `anyOf` on an additionalProperties value, which the generated-client
 // rules rule out for a primitive-or-collection value. The emitted schema is what AJV compiles, so
 // array-or-number is enforced either way.
+// `total` is RESERVED: it is the match count and nothing else. The buckets live beside it under the
+// facet's own name, so the two never need the same slot. `computeFacets` used to seed the count and
+// then write the requested facets over it, so a caller who named a facet `total` got that facet's
+// buckets where the count belonged — an array in a field this schema types as a number. The server
+// now rejects that name with a 400 instead, which is why `total` can stay a plain number here.
+//
+// Widening it to the catchall's `['array', 'number']` is not an option regardless: a NAMED property
+// with a type array makes the Java generator reference a class it never writes (`AnyOfnumber`) and
+// the client stops compiling. The catchall gets away with it by becoming a map value, not a field.
 export const ComputedFacetResponseSchema = z
     .object({
         total: z.number().optional(),
@@ -2323,6 +2460,7 @@ export const ExecutionResponseSchema = z
     .strictObject({
         result: z.array(CompletionResultSchema),
         token_usage: ExecutionTokenUsageSchema.optional(),
+        prompt_cache_diagnostic: PromptCacheDiagnosticSchema.optional(),
         tool_use: z.array(ToolUseSchema).optional(),
         finish_reason: z.string().optional(),
         error: z
@@ -2340,8 +2478,16 @@ export const ExecutionResponseSchema = z
     })
     .meta({ id: 'ExecutionResponse' });
 
+const RunFacetSpecSchema = z.discriminatedUnion('name', [
+    z.strictObject({ name: z.literal('environments'), field: z.literal('environment') }),
+    z.strictObject({ name: z.literal('interactions'), field: z.literal('interaction') }),
+    z.strictObject({ name: z.literal('models'), field: z.literal('modelId') }),
+    z.strictObject({ name: z.literal('statuses'), field: z.literal('status') }),
+    z.strictObject({ name: z.literal('finish_reason'), field: z.literal('finish_reason') }),
+]);
+
 export const ComputeRunFacetPayloadSchema = z
-    .strictObject({ facets: z.array(FacetSpecSchema), query: RunSearchQuerySchema.optional() })
+    .strictObject({ facets: z.array(RunFacetSpecSchema).max(5), query: RunSearchQuerySchema.optional() })
     .meta({ id: 'ComputeRunFacetPayload' });
 
 export const RunSearchMetaResponseSchema = z
@@ -2356,6 +2502,28 @@ export const RunSearchMetaResponseSchema = z
     })
     .meta({ id: 'RunSearchMetaResponse' });
 
+const RunFacetBucketSchema = z.strictObject({
+    _id: z.string().nullable(),
+    count: z.number(),
+    name: z.string().optional(),
+    status: InteractionStatusSchema.optional(),
+    version: z.number().optional(),
+});
+
+/**
+ * Response returned by POST /runs/facets.
+ */
+export const ComputeRunFacetsResponseSchema = z
+    .strictObject({
+        environments: z.array(RunFacetBucketSchema).optional(),
+        interactions: z.array(RunFacetBucketSchema).optional(),
+        models: z.array(RunFacetBucketSchema).optional(),
+        statuses: z.array(RunFacetBucketSchema).optional(),
+        finish_reason: z.array(RunFacetBucketSchema).optional(),
+        total: z.number().optional(),
+    })
+    .meta({ id: 'ComputeRunFacetsResponse' });
+
 export const RunClonePayloadSchema = z
     .strictObject({
         source_run_id: z.string(),

package/src/api-schemas/llumiverse.contract.test.ts

@@ -5,8 +5,8 @@ import type { JsonObject } from './adapter.js';
 import { ApiSchemaComponents, apiComponentRef, validateApiRequest } from './registry.js';
 
 /**
- * The two llumiverse closures the registry publishes: `ModelOptions` with its twenty-three driver
- * option sets and four enums, and `JSONSchema` with its property map.
+ * The two llumiverse closures the registry publishes: `ModelOptions` with its driver option sets
+ * and enums, and `JSONSchema` with its property map.
  *
  * Their schemas live in `@llumiverse/common/schemas` — they describe llumiverse's types, and a copy
  * here would be exactly the drift this migration removes. What is checked HERE is the half that
@@ -21,9 +21,11 @@ function compile(name: string) {
 
 const UNION_MEMBERS = [
     'TextFallbackOptions',
+    'AzureFoundryChatOptions',
     'ImagenOptions',
     'VertexAIClaudeOptions',
     'VertexAIGeminiOptions',
+    'VertexAIGeminiOmniVideoOptions',
     'VertexAIGrokOptions',
     'NovaCanvasOptions',
     'BedrockConverseOptions',
@@ -42,7 +44,9 @@ const UNION_MEMBERS = [
     'OpenAiTextOptions',
     'OpenAiDalleOptions',
     'OpenAiGptImageOptions',
+    'XAIGrokImageOptions',
     'GroqOptions',
+    'MistralTextOptions',
 ];
 
 describe('the ModelOptions closure is published whole and enforced closed', () => {
@@ -78,8 +82,35 @@ describe('the ModelOptions closure is published whole and enforced closed', () =
         // published byte alone would not catch it.
         expect((ApiSchemaComponents.TextFallbackOptions as JsonObject).additionalProperties).toBe(false);
         expect(validate({ _option_id: 'text-fallback', top_p: 0.9, unknown_option: 1 })).toBe(false);
+        expect((ApiSchemaComponents.XAIGrokImageOptions as JsonObject).additionalProperties).toBe(false);
+        expect(validate({ _option_id: 'xai-grok-image', quality: 'medium', unknown_option: 1 })).toBe(false);
+        expect(
+            validate({
+                _option_id: 'mistral-text',
+                effort: 'high',
+                random_seed: 42,
+                safe_prompt: true,
+                include_thoughts: false,
+            }),
+            JSON.stringify(validate.errors),
+        ).toBe(true);
         expect(validate({ _option_id: 'not-a-driver' })).toBe(false);
     });
+
+    it('allows provider-specific objects only inside OpenAI-compatible extra_body', () => {
+        const validate = compile('ModelOptions');
+        expect(
+            validate({
+                _option_id: 'openai-text',
+                extra_body: {
+                    provider: { sort: 'throughput', allow_fallbacks: false },
+                    baseten: { performance: 'max' },
+                },
+            }),
+            JSON.stringify(validate.errors),
+        ).toBe(true);
+        expect(validate({ _option_id: 'openai-text', extra_body: ['invalid'] })).toBe(false);
+    });
 });
 
 describe('the JSONSchema closure is published open, because a JSON Schema is open', () => {

package/src/api-schemas/oauth-server.ts

@@ -5,9 +5,10 @@ import { z } from 'zod';
  * their users have approved. Vertesia acting as a client of someone else's authorization server is
  * `./oauth.js`.
  *
- * Only the three resources backed by the studio API have slots here. The token server's own surface
- * — authorize, token, device code, consent — is still TypeScript-derived and has not been converted,
- * so the types it uses stay declared in `../oauth-server.ts` rather than moving here.
+ * This module also owns the token server's public authorize, token, device-code, consent, and
+ * discovery wire contracts. Standard OAuth responses remain extensible so clients can ignore
+ * additional response parameters as required by OAuth; Vertesia-specific request and response
+ * objects are strict.
  */
 
 export const OAuthClientTypeSchema = z.enum(['public', 'confidential']).meta({ id: 'OAuthClientType' });
@@ -28,6 +29,14 @@ export const OAuthGrantTypeSchema = z
 
 export const OAuthResponseTypeSchema = z.literal('code').meta({ id: 'OAuthResponseType' });
 
+export const OAuthAuthorizationRequestStatusSchema = z
+    .enum(['pending', 'denied', 'consumed'])
+    .meta({ id: 'OAuthAuthorizationRequestStatus' });
+
+export const OAuthClientRegistrationModeSchema = z
+    .enum(['registered', 'client_id_metadata_document'])
+    .meta({ id: 'OAuthClientRegistrationMode' });
+
 export const OAuthGrantStatusSchema = z.enum(['active', 'revoked', 'expired']).meta({ id: 'OAuthGrantStatus' });
 
 export const OAuthGrantSortFieldSchema = z
@@ -36,6 +45,146 @@ export const OAuthGrantSortFieldSchema = z
 
 export const OAuthGrantSortOrderSchema = z.enum(['asc', 'desc']).meta({ id: 'OAuthGrantSortOrder' });
 
+/** RFC 8414 metadata is extensible; parsing keeps the standardized fields and ignores extensions. */
+export const OAuthAuthorizationServerMetadataSchema = z
+    .object({
+        issuer: z.string(),
+        authorization_endpoint: z.string(),
+        token_endpoint: z.string(),
+        jwks_uri: z.string(),
+        registration_endpoint: z.string().optional(),
+        revocation_endpoint: z.string().optional(),
+        response_types_supported: z.array(z.string()),
+        grant_types_supported: z.array(z.string()),
+        code_challenge_methods_supported: z.array(z.string()),
+        token_endpoint_auth_methods_supported: z.array(z.string()),
+        scopes_supported: z.array(z.string()),
+        client_id_metadata_document_supported: z.boolean().optional(),
+        authorization_response_iss_parameter_supported: z.boolean().optional(),
+        device_authorization_endpoint: z.string().optional(),
+    })
+    .meta({ id: 'OAuthAuthorizationServerMetadata' });
+
+export const OAuthClientDisplayMetadataSchema = z
+    .strictObject({
+        client_uri: z.string().optional(),
+        logo_uri: z.string().optional(),
+        tos_uri: z.string().optional(),
+        policy_uri: z.string().optional(),
+    })
+    .meta({ id: 'OAuthClientDisplayMetadata' });
+
+const oauthAuthorizeQueryFields = {
+    response_type: OAuthResponseTypeSchema,
+    client_id: z.string(),
+    redirect_uri: z.string(),
+    resource: z.string().optional(),
+    scope: z.string().optional(),
+    state: z.string().optional(),
+    code_challenge: z.string(),
+    code_challenge_method: z.literal('S256'),
+    project_id: z.string().optional(),
+};
+
+export const OAuthAuthorizeQuerySchema = z.strictObject(oauthAuthorizeQueryFields).meta({ id: 'OAuthAuthorizeQuery' });
+
+export const CreateOAuthAuthorizationRequestPayloadSchema = z
+    .strictObject(oauthAuthorizeQueryFields)
+    .meta({ id: 'CreateOAuthAuthorizationRequestPayload' });
+
+export const OAuthAuthorizationRequestSchema = z
+    .strictObject({
+        request_id: z.string(),
+        client_id: z.string(),
+        client_name: z.string(),
+        client_metadata: OAuthClientDisplayMetadataSchema.optional(),
+        client_registration_mode: OAuthClientRegistrationModeSchema.optional(),
+        redirect_uri: z.string(),
+        redirect_origin: z.string(),
+        resource: z.string().optional(),
+        requested_scopes: z.array(z.string()),
+        optional_scopes: z.array(z.string()).optional(),
+        requested_project_id: z.string().optional(),
+        project_binding_mode: OAuthProjectBindingModeSchema,
+        fixed_project_id: z.string().optional(),
+        restrict_to_owner_account: z.boolean().optional().meta({
+            description:
+                'When true, consent must be limited to projects in the OAuth client owning account. False allows any project the approving user can access.',
+        }),
+        owner_account_id: z
+            .string()
+            .optional()
+            .meta({ description: 'Owning account enforced when restrict_to_owner_account is true.' }),
+        status: OAuthAuthorizationRequestStatusSchema,
+        created_at: z.string(),
+        expires_at: z.string(),
+    })
+    .meta({ id: 'OAuthAuthorizationRequest' });
+
+export const ApproveOAuthAuthorizationRequestPayloadSchema = z
+    .strictObject({
+        project_id: z.string().optional(),
+        granted_scopes: z.array(z.string()),
+    })
+    .meta({ id: 'ApproveOAuthAuthorizationRequestPayload' });
+
+export const OAuthGrantableScopesResponseSchema = z
+    .strictObject({
+        project_id: z.string(),
+        requested_permission_scopes: z.array(z.string()),
+        grantable_permission_scopes: z.array(z.string()),
+        unavailable_permission_scopes: z.array(z.string()),
+    })
+    .meta({ id: 'OAuthGrantableScopesResponse' });
+
+export const OAuthAuthorizationDecisionResponseSchema = z
+    .strictObject({
+        redirect_url: z.string(),
+    })
+    .meta({ id: 'OAuthAuthorizationDecisionResponse' });
+
+export const OAuthDeviceAuthorizationRequestSchema = z
+    .strictObject({
+        client_id: z.string(),
+        resource: z.string().optional(),
+        scope: z.string().optional(),
+        project_id: z.string().optional(),
+    })
+    .meta({ id: 'OAuthDeviceAuthorizationRequest' });
+
+/** RFC 8628 responses can gain extension parameters; consumers parse the standardized fields. */
+export const OAuthDeviceAuthorizationResponseSchema = z
+    .object({
+        device_code: z.string(),
+        user_code: z.string(),
+        verification_uri: z.string(),
+        verification_uri_complete: z.string(),
+        expires_in: z.number(),
+        interval: z.number(),
+    })
+    .meta({ id: 'OAuthDeviceAuthorizationResponse' });
+
+/** RFC 6749 requires clients to ignore unrecognized token response parameters. */
+export const OAuthTokenResponseSchema = z
+    .object({
+        access_token: z.string(),
+        token_type: z.string().regex(/^bearer$/i),
+        expires_in: z.number(),
+        scope: z.string().optional(),
+        refresh_token: z.string().optional(),
+        /**
+         * Lifetime in seconds of `refresh_token`, from the moment this response was issued.
+         *
+         * Not an RFC 6749 parameter — refresh tokens there are opaque and undated — but clients that
+         * persist the token need it to report when the stored credential dies. Every refresh token
+         * this server returns is newly minted (the refresh grant rotates), so this is always the full
+         * lifetime and never a remaining one.
+         */
+        refresh_token_expires_in: z.number().optional(),
+        id_token: z.string().optional(),
+    })
+    .meta({ id: 'OAuthTokenResponse' });
+
 /**
  * A client's registration, without its issued id.
  *