@oxy.so/contracts 1.0.0

package/dist/types/inference/streamEvents.d.ts

@@ -0,0 +1,950 @@
+/**
+ * Normalized stream events — what the data plane emits and the Oxy edge
+ * forwards as SSE.
+ *
+ * One discriminated union, seven shapes, all carrying `requestId` and a
+ * monotonic `sequence`. `requestId` is on EVERY event rather than only the
+ * first because a proxy that re-frames or a client that reconnects would
+ * otherwise be holding events it cannot attribute; `sequence` is what makes a
+ * redelivered event detectable as a duplicate rather than as new output.
+ *
+ * The events are versioned INDIVIDUALLY (see `version.ts`): a stream is a long
+ * sequence of small messages from a producer that may be redeployed mid-stream,
+ * so the alternative — one version for the whole union — would force every
+ * event to move whenever any one of them changed.
+ *
+ * `route_switch` is the customer-visible receipt for an allowed re-route, and
+ * its shape carries the invariant: a switch to a DIFFERENT model can only be
+ * expressed with `authorizedByPolicy: true`, so an unauthorized substitution is
+ * not a thing the contract can say.
+ *
+ * Decided in: docs/adr/0010-public-api-compatibility.md, docs/adr/0008-catalogue-concept-separation.md.
+ */
+import { z } from 'zod';
+/**
+ * The first event of every stream: what was actually resolved.
+ *
+ * Names the revision-pinned model and the serving provider, so a customer who
+ * asked for `<publisher>/<model>` learns which revision answered without having
+ * to wait for the receipt. Carries no deployment health, no route id and no
+ * upstream cost.
+ */
+export declare const inferenceStreamStartEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"start">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    generationId: z.ZodOptional<z.ZodString>;
+    /** Always revision-pinned, even when the request named only the model. */
+    resolvedModelReference: z.ZodString;
+    servingProvider: z.ZodString;
+    startedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "start";
+    schemaVersion: 1;
+    requestId: string;
+    resolvedModelReference: string;
+    servingProvider: string;
+    sequence: number;
+    startedAt: string;
+    generationId?: string | undefined;
+}, {
+    type: "start";
+    schemaVersion: 1;
+    requestId: string;
+    resolvedModelReference: string;
+    servingProvider: string;
+    sequence: number;
+    startedAt: string;
+    generationId?: string | undefined;
+}>;
+/**
+ * A chunk of output.
+ *
+ * `channel` separates visible output from reasoning and refusals, because a
+ * client that renders reasoning as answer text is a product bug, not a display
+ * preference.
+ */
+export declare const inferenceStreamDeltaEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"delta">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Which output of a multi-output response this chunk belongs to. */
+    outputIndex: z.ZodNumber;
+    channel: z.ZodEnum<["output_text", "reasoning", "refusal"]>;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    channel: "reasoning" | "refusal" | "output_text";
+    type: "delta";
+    schemaVersion: 1;
+    requestId: string;
+    text: string;
+    sequence: number;
+    outputIndex: number;
+}, {
+    channel: "reasoning" | "refusal" | "output_text";
+    type: "delta";
+    schemaVersion: 1;
+    requestId: string;
+    text: string;
+    sequence: number;
+    outputIndex: number;
+}>;
+/**
+ * A tool call being streamed.
+ *
+ * `argumentsDelta` accumulates; `complete` marks the call finished so a client
+ * knows when the accumulated JSON text is worth parsing.
+ */
+export declare const inferenceStreamToolCallEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"tool_call">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    toolCallId: z.ZodString;
+    /** Present on the first event of a call. */
+    name: z.ZodOptional<z.ZodString>;
+    argumentsDelta: z.ZodOptional<z.ZodString>;
+    complete: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_call";
+    schemaVersion: 1;
+    requestId: string;
+    toolCallId: string;
+    sequence: number;
+    complete: boolean;
+    name?: string | undefined;
+    argumentsDelta?: string | undefined;
+}, {
+    type: "tool_call";
+    schemaVersion: 1;
+    requestId: string;
+    toolCallId: string;
+    sequence: number;
+    complete: boolean;
+    name?: string | undefined;
+    argumentsDelta?: string | undefined;
+}>;
+/**
+ * Metered units for the request so far.
+ *
+ * Units only — no money. What a customer is charged is the ledger's answer,
+ * derived from these units and a price version at settlement; a cost quoted by
+ * the data plane would be a second, unauthoritative answer to the same
+ * question.
+ *
+ * ## This event is MEASUREMENT EVIDENCE, never a settleable record
+ *
+ * `normalizedUsageReportSchema` is the only shape a settlement is written from,
+ * and this event is deliberately NOT a subset of it that could be widened into
+ * one. It carries units and a source; a report additionally carries the
+ * attribution block, the outcome, the resolved route, the route-switch count and
+ * the two timestamps. Every one of those is knowable only by one END of the
+ * request rather than by the frame: the outcome only by the edge, which is the
+ * only party that knows whether the CLIENT cancelled, and the route record only
+ * by the data plane.
+ *
+ * So the event is not widened, and that is a decision rather than an omission.
+ * Adding the route record and the attribution block here would repeat both on
+ * EVERY usage frame of every stream, and each repetition is one more place two
+ * frames of one stream could disagree about which route served it — a second
+ * source of truth per frame, for fields no consumer of a progress signal reads.
+ *
+ * **What the edge may do with it, and what it may not.** The units are exact and
+ * may be settled; the record around them may not be inferred. When no terminal
+ * report arrives — the ordinary case for a client disconnect, since the report
+ * frame can no longer be delivered to a connection that is gone — the edge
+ * settles the units from the last such event and takes the OUTCOME from itself,
+ * never from the event. Its outcome is then `cancelled`, `partial` or `failed`;
+ * it is never `completed`, because nothing here can witness that the customer
+ * received the whole answer. Zero units marked `estimated` is the arm for no
+ * evidence at ALL, not for a disconnect that reported some.
+ */
+export declare const inferenceStreamUsageEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<2>;
+    type: z.ZodLiteral<"usage">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Exact deployment whose metering produced these partial units. */
+    deploymentId: z.ZodString;
+    units: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        quantity: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }>, "many">;
+    usageSource: z.ZodEnum<["provider_reported", "oxy_measured", "estimated"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "usage";
+    schemaVersion: 2;
+    requestId: string;
+    deploymentId: string;
+    sequence: number;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+}, {
+    type: "usage";
+    schemaVersion: 2;
+    requestId: string;
+    deploymentId: string;
+    sequence: number;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+}>;
+/**
+ * What kind of re-route happened.
+ *
+ * `deployment` is same-model failover: the same revision, served somewhere else.
+ * `model` is a substitution, and is expressible ONLY with
+ * `authorizedByPolicy: true` — the routing policy's `authorizedCrossModel` list
+ * is the only thing that can produce one, so "a concrete model was silently
+ * replaced" has no representation in this contract.
+ */
+export declare const inferenceRouteSwitchDetailSchema: z.ZodDiscriminatedUnion<"scope", [z.ZodObject<{
+    scope: z.ZodLiteral<"deployment">;
+    modelReference: z.ZodString;
+    toProvider: z.ZodString;
+    toDeploymentId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    scope: "deployment";
+    modelReference: string;
+    toProvider: string;
+    toDeploymentId?: string | undefined;
+}, {
+    scope: "deployment";
+    modelReference: string;
+    toProvider: string;
+    toDeploymentId?: string | undefined;
+}>, z.ZodObject<{
+    scope: z.ZodLiteral<"model">;
+    /**
+     * The UNPINNED model line the customer asked for (`<publisher>/<model>`,
+     * never `@revision`). A request that pinned a revision asked for exactly
+     * those weights and is served or refused, never substituted — so for such
+     * a request there is no value that satisfies this field, and the event
+     * cannot be constructed at all.
+     */
+    requestedModelId: z.ZodString;
+    fromModelReference: z.ZodString;
+    toModelReference: z.ZodString;
+    toProvider: z.ZodString;
+    /** Literal `true`: an unauthorized cross-model switch cannot be reported. */
+    authorizedByPolicy: z.ZodLiteral<true>;
+}, "strict", z.ZodTypeAny, {
+    scope: "model";
+    authorizedByPolicy: true;
+    toProvider: string;
+    requestedModelId: string;
+    fromModelReference: string;
+    toModelReference: string;
+}, {
+    scope: "model";
+    authorizedByPolicy: true;
+    toProvider: string;
+    requestedModelId: string;
+    fromModelReference: string;
+    toModelReference: string;
+}>]>;
+/** Why a route changed mid-request. */
+export declare const inferenceRouteSwitchReasonSchema: z.ZodEnum<["deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "rate_limited", "capacity", "policy_preference"]>;
+/**
+ * The customer-visible notice that an allowed route switch occurred.
+ *
+ * Emitted in-stream rather than only recorded on the receipt, because a
+ * customer comparing two answers needs to know that the second one came from
+ * somewhere else while they are reading it.
+ */
+export declare const inferenceStreamRouteSwitchEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"route_switch">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    reason: z.ZodEnum<["deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "rate_limited", "capacity", "policy_preference"]>;
+    detail: z.ZodDiscriminatedUnion<"scope", [z.ZodObject<{
+        scope: z.ZodLiteral<"deployment">;
+        modelReference: z.ZodString;
+        toProvider: z.ZodString;
+        toDeploymentId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    }, {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    }>, z.ZodObject<{
+        scope: z.ZodLiteral<"model">;
+        /**
+         * The UNPINNED model line the customer asked for (`<publisher>/<model>`,
+         * never `@revision`). A request that pinned a revision asked for exactly
+         * those weights and is served or refused, never substituted — so for such
+         * a request there is no value that satisfies this field, and the event
+         * cannot be constructed at all.
+         */
+        requestedModelId: z.ZodString;
+        fromModelReference: z.ZodString;
+        toModelReference: z.ZodString;
+        toProvider: z.ZodString;
+        /** Literal `true`: an unauthorized cross-model switch cannot be reported. */
+        authorizedByPolicy: z.ZodLiteral<true>;
+    }, "strict", z.ZodTypeAny, {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    }, {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    }>]>;
+    occurredAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "route_switch";
+    reason: "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "capacity" | "policy_preference";
+    occurredAt: string;
+    schemaVersion: 1;
+    requestId: string;
+    detail: {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    } | {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    };
+    sequence: number;
+}, {
+    type: "route_switch";
+    reason: "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "capacity" | "policy_preference";
+    occurredAt: string;
+    schemaVersion: 1;
+    requestId: string;
+    detail: {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    } | {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    };
+    sequence: number;
+}>;
+/**
+ * A terminal error. The stream ends here; no `done` follows, so a client that
+ * saw an error never also has to reconcile a success.
+ */
+export declare const inferenceStreamErrorEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"error">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
+    error: z.ZodEffects<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "provider_credential_invalid", "provider_billing_refused", "service_unavailable", "internal_error"]>;
+        message: z.ZodEffects<z.ZodString, string, string>;
+        retryable: z.ZodBoolean;
+        requestId: z.ZodString;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        param: z.ZodOptional<z.ZodString>;
+        upstreamCategory: z.ZodOptional<z.ZodEnum<["rate_limit", "quota", "timeout", "overloaded", "server_error", "content_filter", "invalid_request", "authentication", "unknown"]>>;
+        providerError: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            status: z.ZodOptional<z.ZodNumber>;
+            code: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        }, "strict", z.ZodTypeAny, {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        }, {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }>, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "error";
+    schemaVersion: 1;
+    requestId: string;
+    sequence: number;
+    error: {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    };
+}, {
+    type: "error";
+    schemaVersion: 1;
+    requestId: string;
+    sequence: number;
+    error: {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    };
+}>;
+/**
+ * Why generation stopped.
+ *
+ * `refusal` and `content_filter` are separate members because they are separate
+ * events: the MODEL declining to answer is a property of the answer, while a
+ * filter is an upstream system removing one. The delta channels already carry
+ * that distinction (`channel: 'refusal'` beside the filter's own error code),
+ * so collapsing it here would have made the terminal event less specific than
+ * the stream that produced it.
+ */
+export declare const inferenceFinishReasonSchema: z.ZodEnum<["stop", "length", "tool_calls", "content_filter", "refusal", "cancelled"]>;
+/**
+ * The successful terminal event.
+ *
+ * `receiptId` is present once settlement has produced one, giving a customer a
+ * direct handle on the exact amount charged rather than a telemetry estimate.
+ */
+export declare const inferenceStreamDoneEventSchema: z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"done">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    generationId: z.ZodOptional<z.ZodString>;
+    finishReason: z.ZodEnum<["stop", "length", "tool_calls", "content_filter", "refusal", "cancelled"]>;
+    receiptId: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "done";
+    schemaVersion: 1;
+    requestId: string;
+    completedAt: string;
+    sequence: number;
+    finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
+    receiptId?: string | undefined;
+    generationId?: string | undefined;
+}, {
+    type: "done";
+    schemaVersion: 1;
+    requestId: string;
+    completedAt: string;
+    sequence: number;
+    finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
+    receiptId?: string | undefined;
+    generationId?: string | undefined;
+}>;
+/**
+ * Every event a normalized stream can carry.
+ *
+ * Discriminated on `type`, so a consumer that meets an unknown event fails at
+ * the parse instead of falling into a default branch that treats it as output.
+ */
+export declare const inferenceStreamEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"start">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    generationId: z.ZodOptional<z.ZodString>;
+    /** Always revision-pinned, even when the request named only the model. */
+    resolvedModelReference: z.ZodString;
+    servingProvider: z.ZodString;
+    startedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "start";
+    schemaVersion: 1;
+    requestId: string;
+    resolvedModelReference: string;
+    servingProvider: string;
+    sequence: number;
+    startedAt: string;
+    generationId?: string | undefined;
+}, {
+    type: "start";
+    schemaVersion: 1;
+    requestId: string;
+    resolvedModelReference: string;
+    servingProvider: string;
+    sequence: number;
+    startedAt: string;
+    generationId?: string | undefined;
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"delta">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Which output of a multi-output response this chunk belongs to. */
+    outputIndex: z.ZodNumber;
+    channel: z.ZodEnum<["output_text", "reasoning", "refusal"]>;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    channel: "reasoning" | "refusal" | "output_text";
+    type: "delta";
+    schemaVersion: 1;
+    requestId: string;
+    text: string;
+    sequence: number;
+    outputIndex: number;
+}, {
+    channel: "reasoning" | "refusal" | "output_text";
+    type: "delta";
+    schemaVersion: 1;
+    requestId: string;
+    text: string;
+    sequence: number;
+    outputIndex: number;
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"tool_call">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    toolCallId: z.ZodString;
+    /** Present on the first event of a call. */
+    name: z.ZodOptional<z.ZodString>;
+    argumentsDelta: z.ZodOptional<z.ZodString>;
+    complete: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "tool_call";
+    schemaVersion: 1;
+    requestId: string;
+    toolCallId: string;
+    sequence: number;
+    complete: boolean;
+    name?: string | undefined;
+    argumentsDelta?: string | undefined;
+}, {
+    type: "tool_call";
+    schemaVersion: 1;
+    requestId: string;
+    toolCallId: string;
+    sequence: number;
+    complete: boolean;
+    name?: string | undefined;
+    argumentsDelta?: string | undefined;
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<2>;
+    type: z.ZodLiteral<"usage">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Exact deployment whose metering produced these partial units. */
+    deploymentId: z.ZodString;
+    units: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_tokens", "requests", "images", "audio_input_milliseconds", "audio_output_milliseconds", "video_milliseconds", "characters", "embeddings"]>;
+        quantity: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }, {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }>, "many">;
+    usageSource: z.ZodEnum<["provider_reported", "oxy_measured", "estimated"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "usage";
+    schemaVersion: 2;
+    requestId: string;
+    deploymentId: string;
+    sequence: number;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+}, {
+    type: "usage";
+    schemaVersion: 2;
+    requestId: string;
+    deploymentId: string;
+    sequence: number;
+    units: {
+        unit: "input_tokens" | "cached_input_tokens" | "output_tokens" | "reasoning_tokens" | "requests" | "images" | "audio_input_milliseconds" | "audio_output_milliseconds" | "video_milliseconds" | "characters" | "embeddings";
+        quantity: number;
+    }[];
+    usageSource: "provider_reported" | "oxy_measured" | "estimated";
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"route_switch">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    reason: z.ZodEnum<["deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "rate_limited", "capacity", "policy_preference"]>;
+    detail: z.ZodDiscriminatedUnion<"scope", [z.ZodObject<{
+        scope: z.ZodLiteral<"deployment">;
+        modelReference: z.ZodString;
+        toProvider: z.ZodString;
+        toDeploymentId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    }, {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    }>, z.ZodObject<{
+        scope: z.ZodLiteral<"model">;
+        /**
+         * The UNPINNED model line the customer asked for (`<publisher>/<model>`,
+         * never `@revision`). A request that pinned a revision asked for exactly
+         * those weights and is served or refused, never substituted — so for such
+         * a request there is no value that satisfies this field, and the event
+         * cannot be constructed at all.
+         */
+        requestedModelId: z.ZodString;
+        fromModelReference: z.ZodString;
+        toModelReference: z.ZodString;
+        toProvider: z.ZodString;
+        /** Literal `true`: an unauthorized cross-model switch cannot be reported. */
+        authorizedByPolicy: z.ZodLiteral<true>;
+    }, "strict", z.ZodTypeAny, {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    }, {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    }>]>;
+    occurredAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "route_switch";
+    reason: "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "capacity" | "policy_preference";
+    occurredAt: string;
+    schemaVersion: 1;
+    requestId: string;
+    detail: {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    } | {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    };
+    sequence: number;
+}, {
+    type: "route_switch";
+    reason: "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "capacity" | "policy_preference";
+    occurredAt: string;
+    schemaVersion: 1;
+    requestId: string;
+    detail: {
+        scope: "deployment";
+        modelReference: string;
+        toProvider: string;
+        toDeploymentId?: string | undefined;
+    } | {
+        scope: "model";
+        authorizedByPolicy: true;
+        toProvider: string;
+        requestedModelId: string;
+        fromModelReference: string;
+        toModelReference: string;
+    };
+    sequence: number;
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"error">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
+    error: z.ZodEffects<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        code: z.ZodEnum<["invalid_request", "authentication_failed", "permission_denied", "insufficient_scope", "model_not_found", "unsupported_modality", "context_length_exceeded", "request_too_large", "output_limit_exceeded", "idempotency_conflict", "insufficient_balance", "spending_limit_exceeded", "quota_exceeded", "byok_credential_invalid", "policy_violation", "commercial_permission_denied", "no_route_available", "upstream_content_filtered", "cancelled", "rate_limited", "deployment_unavailable", "provider_error", "provider_timeout", "provider_overloaded", "provider_credential_invalid", "provider_billing_refused", "service_unavailable", "internal_error"]>;
+        message: z.ZodEffects<z.ZodString, string, string>;
+        retryable: z.ZodBoolean;
+        requestId: z.ZodString;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        param: z.ZodOptional<z.ZodString>;
+        upstreamCategory: z.ZodOptional<z.ZodEnum<["rate_limit", "quota", "timeout", "overloaded", "server_error", "content_filter", "invalid_request", "authentication", "unknown"]>>;
+        providerError: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            status: z.ZodOptional<z.ZodNumber>;
+            code: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        }, "strict", z.ZodTypeAny, {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        }, {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }>, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }, {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "error";
+    schemaVersion: 1;
+    requestId: string;
+    sequence: number;
+    error: {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    };
+}, {
+    type: "error";
+    schemaVersion: 1;
+    requestId: string;
+    sequence: number;
+    error: {
+        code: "invalid_request" | "authentication_failed" | "permission_denied" | "insufficient_scope" | "model_not_found" | "unsupported_modality" | "context_length_exceeded" | "request_too_large" | "output_limit_exceeded" | "idempotency_conflict" | "insufficient_balance" | "spending_limit_exceeded" | "quota_exceeded" | "byok_credential_invalid" | "policy_violation" | "commercial_permission_denied" | "no_route_available" | "upstream_content_filtered" | "cancelled" | "rate_limited" | "deployment_unavailable" | "provider_error" | "provider_timeout" | "provider_overloaded" | "provider_credential_invalid" | "provider_billing_refused" | "service_unavailable" | "internal_error";
+        message: string;
+        schemaVersion: 1;
+        requestId: string;
+        retryable: boolean;
+        retryAfterMs?: number | undefined;
+        param?: string | undefined;
+        upstreamCategory?: "unknown" | "authentication" | "invalid_request" | "rate_limit" | "quota" | "timeout" | "overloaded" | "server_error" | "content_filter" | undefined;
+        providerError?: {
+            provider: string;
+            code?: string | undefined;
+            message?: string | undefined;
+            status?: number | undefined;
+        } | undefined;
+    };
+}>, z.ZodObject<{
+    /** See `version.ts`: each stream event is a whole message on the wire. */
+    schemaVersion: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"done">;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    generationId: z.ZodOptional<z.ZodString>;
+    finishReason: z.ZodEnum<["stop", "length", "tool_calls", "content_filter", "refusal", "cancelled"]>;
+    receiptId: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "done";
+    schemaVersion: 1;
+    requestId: string;
+    completedAt: string;
+    sequence: number;
+    finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
+    receiptId?: string | undefined;
+    generationId?: string | undefined;
+}, {
+    type: "done";
+    schemaVersion: 1;
+    requestId: string;
+    completedAt: string;
+    sequence: number;
+    finishReason: "length" | "cancelled" | "content_filter" | "refusal" | "stop" | "tool_calls";
+    receiptId?: string | undefined;
+    generationId?: string | undefined;
+}>]>;
+export type InferenceStreamStartEvent = z.infer<typeof inferenceStreamStartEventSchema>;
+export type InferenceStreamDeltaEvent = z.infer<typeof inferenceStreamDeltaEventSchema>;
+export type InferenceStreamToolCallEvent = z.infer<typeof inferenceStreamToolCallEventSchema>;
+export type InferenceStreamUsageEvent = z.infer<typeof inferenceStreamUsageEventSchema>;
+export type InferenceRouteSwitchDetail = z.infer<typeof inferenceRouteSwitchDetailSchema>;
+export type InferenceRouteSwitchReason = z.infer<typeof inferenceRouteSwitchReasonSchema>;
+export type InferenceStreamRouteSwitchEvent = z.infer<typeof inferenceStreamRouteSwitchEventSchema>;
+export type InferenceStreamErrorEvent = z.infer<typeof inferenceStreamErrorEventSchema>;
+export type InferenceFinishReason = z.infer<typeof inferenceFinishReasonSchema>;
+export type InferenceStreamDoneEvent = z.infer<typeof inferenceStreamDoneEventSchema>;
+export type InferenceStreamEvent = z.infer<typeof inferenceStreamEventSchema>;