@oxy.so/contracts 4.4.0 → 4.6.0

package/dist/esm/index.js

@@ -134,11 +134,11 @@ export {
 priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
 export { 
 // The six distinct catalogue objects + the customer-safe projection.
-inferenceModalitySchema, reasoningEffortSchema, inferenceApiFormatSchema, realtimeSessionKindSchema, realtimeSessionTransportSchema, modelRealtimeCapabilitiesSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+inferenceModalitySchema, reasoningEffortSchema, powerLevelSchema, modelPowerClassSchema, inferenceApiFormatSchema, realtimeSessionKindSchema, realtimeSessionTransportSchema, modelRealtimeCapabilitiesSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
-routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, 
+routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, effectiveSameModelDeployment, 
 // What the data plane actually receives: the routes the policy authorized.
 authorizedRouteSchema, } from './inference/routingPolicy.js';
 export { 

package/dist/esm/inference/catalogue.js

@@ -49,6 +49,38 @@ export const inferenceModalitySchema = z.enum([
  * effort the resolved model does not advertise rather than dropping it.
  */
 export const reasoningEffortSchema = z.enum(['low', 'medium', 'high']);
+/**
+ * A POWER LEVEL: the public name of a product-preset routing profile that asks
+ * Oxy to choose a model by capability tier instead of naming one (contract set
+ * 3.4.0). Ordered cheapest first; `auto` asks Oxy to pick the cheapest level
+ * that suffices for the request.
+ *
+ * - `instant` — very cheap, fast small models; no reasoning effort requested
+ * - `medium` — mid-size models, low reasoning effort
+ * - `high` — strong models, medium reasoning effort
+ * - `xhigh` — strong models, high reasoning effort
+ * - `pro` — frontier models, high reasoning effort
+ * - `ultra` — the heaviest frontier models, maximum reasoning effort
+ *
+ * A power level is a routing profile, never a model: its slug has no `/`, and
+ * the response always reports the concrete model that ran.
+ */
+export const powerLevelSchema = z.enum([
+    'auto',
+    'instant',
+    'medium',
+    'high',
+    'xhigh',
+    'pro',
+    'ultra',
+]);
+/**
+ * The reviewed capability tier of one MODEL, which power levels choose from.
+ * `xhigh` and `auto` are not classes: `xhigh` runs `high`-class models at a
+ * higher effort, and `auto` chooses a level. Reviewed catalogue data with a
+ * cited public benchmark source — never inferred from a model's name.
+ */
+export const modelPowerClassSchema = z.enum(['instant', 'medium', 'high', 'pro', 'ultra']);
 /**
  * The public dialects a request can arrive in — `client.apiFormat` on the
  * envelope, and the list a deployment declares it can execute.
@@ -539,6 +571,18 @@ export const routingProfileSchema = z.object({
     candidates: z.array(routingProfileCandidateSchema).min(1),
     /** A product preset (Alia's "fast" toggle) rather than a customer's own profile. */
     isProductPreset: z.boolean(),
+    /**
+     * Present when this profile IS a power level (contract set 3.4.0). Its
+     * `candidates` are then the currently servable models of the level's class,
+     * and may change between reads; cross-model failover among them is
+     * authorized by the profile and reported with a `route_switch` event.
+     */
+    powerLevel: powerLevelSchema.optional(),
+    /**
+     * The reasoning effort a power level asks for when the request names none,
+     * applied only on a model that advertises it. Absent: none is requested.
+     */
+    reasoningEffort: reasoningEffortSchema.optional(),
 });
 /* -------------------------------------------------------------------------- */
 /*  Customer-safe catalogue projection                                        */
@@ -607,4 +651,10 @@ export const modelCatalogueEntrySchema = z.object({
     evaluations: z.array(modelEvaluationResultSchema).default([]),
     safety: modelSafetyMetadataSchema.optional(),
     modelCardUrl: inferenceHttpsUrlSchema.optional(),
+    /**
+     * The reviewed power class this model serves in, when one has been reviewed
+     * (contract set 3.4.0). Absent means the model is callable by name only and
+     * no power level chooses it.
+     */
+    powerClass: modelPowerClassSchema.optional(),
 });

package/dist/esm/inference/money.js

@@ -132,6 +132,18 @@ export const moneySchema = z
  * reported as tokens and as milliseconds is the double charge this rule exists
  * to prevent.
  *
+ * **`session_milliseconds` is session wall-clock time** (added in contract set
+ * 3.3.0): wall-clock milliseconds a realtime session was open with the upstream
+ * provider; reported only by a provider that bills session time, and never
+ * together with a per-audio reading of the same span. xAI's Voice Agent API
+ * bills a session using server-side voice activity detection for its whole
+ * duration, speech or silence, which is neither audio sent nor audio received:
+ * reporting that clock as `audio_input_milliseconds` would misdescribe the
+ * charge, and reporting both would bill the same span twice. It is measured by
+ * the data plane from the upstream session's open to its close, never
+ * estimated from the audio, and a provider billed by the audio it carries (or
+ * by tokens) never reports it.
+ *
  * No refinement in this package can enforce it, and saying so is part of the
  * rule: a nested report and a disjoint one are the same four non-negative
  * integers, so no predicate over a single report can tell them apart. The two
@@ -168,6 +180,7 @@ export const USAGE_UNITS = [
     'audio_input_tokens',
     'cached_audio_input_tokens',
     'audio_output_tokens',
+    'session_milliseconds',
 ];
 export const usageUnitSchema = z.enum(USAGE_UNITS);
 /**

package/dist/esm/inference/routingPolicy.js

@@ -85,10 +85,26 @@ export const routingPolicyScopeSchema = z.discriminatedUnion("kind", [
 export const routingFallbackPolicySchema = z
     .object({
     disabled: z.boolean(),
-    sameModelDeployment: z.boolean(),
+    /**
+     * Same-model deployment failover. OPTIONAL since contract set 3.4.0, and
+     * absent means ON unless `disabled` is set: serving the same weights from
+     * another deployment of the same revision is an availability decision, not
+     * a substitution. A policy opts out with an explicit `false` (or
+     * `disabled: true`). See `effectiveSameModelDeployment`.
+     */
+    sameModelDeployment: z.boolean().optional(),
     authorizedCrossModel: z.array(modelReferenceSchema).default([]),
 })
     .strict();
+/**
+ * Whether a fallback block authorizes same-model deployment failover: an
+ * explicit `sameModelDeployment` wins; absent means on unless `disabled`.
+ */
+export function effectiveSameModelDeployment(fallback) {
+    if (fallback.disabled)
+        return false;
+    return fallback.sameModelDeployment ?? true;
+}
 /**
  * A versioned routing policy.
  *
@@ -128,6 +144,14 @@ export const routingPolicySchema = z
     allowedLicenseIds: z.array(z.string().min(1).max(128)).default([]),
     requireCommercialUseRights: z.boolean(),
     fallback: routingFallbackPolicySchema,
+    /**
+     * The routing profiles (power levels) this scope may target, by exact id
+     * (contract set 3.4.0). Empty means no restriction. A request naming a
+     * profile outside a non-empty list is refused with `policy_violation`, and
+     * `auto` only climbs to levels on the list. Concrete model targets are
+     * governed by the other controls, not by this list.
+     */
+    allowedRoutingProfileIds: z.array(routingProfileIdSchema).default([]),
     /** Whether the customer's own provider credentials may or must be used. */
     byokPreference: z.enum(["disabled", "prefer", "require"]),
     /** Enterprise reserved capacity rather than shared endpoints. */
@@ -207,6 +231,25 @@ export const routingPolicySchema = z
             }
         }
     }
+    const allowedProfiles = policy.allowedRoutingProfileIds;
+    if (new Set(allowedProfiles).size !== allowedProfiles.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["allowedRoutingProfileIds"],
+            message: "each routing profile is allowed at most once",
+        });
+    }
+    // A default the policy itself forbids would refuse every request that
+    // names no model — a policy that cannot serve its own default.
+    if (allowedProfiles.length > 0 &&
+        policy.defaultTarget?.kind === "routing_profile_id" &&
+        !allowedProfiles.includes(policy.defaultTarget.routingProfileId)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["defaultTarget", "routingProfileId"],
+            message: "the default routing profile must be one of allowedRoutingProfileIds",
+        });
+    }
 });
 /**
  * The reference a request records: which policy, at which of the customer's own

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '3.2.0';
+export const INFERENCE_CONTRACT_VERSION = '3.4.0';