@oxyhq/core 20.1.0 → 21.0.1

package/dist/types/HttpService.d.ts

@@ -194,6 +194,18 @@ export declare class HttpService {
      * ambiguous with a serialized request body.
      */
     private static readonly CACHE_IDENTITY_DELIM;
+    /**
+     * The keys whose presence beside `data` makes a body a PAGE rather than a
+     * payload — see {@link unwrapResponse} for why this list is narrow.
+     *
+     *  - `pagination` — the offset-paginated house envelope (`sendPaginated`).
+     *  - `nextCursor` — the keyset-paginated one (the account audit trails).
+     *
+     * Membership is decided by key PRESENCE, never by value: the last page sends
+     * `nextCursor: null`, and an envelope that collapsed into a bare payload
+     * exactly when the stream ended would be a worse bug than the one this fixes.
+     */
+    private static readonly PAGE_ENVELOPE_KEYS;
     /**
      * Derive a stable, non-sensitive identity discriminator for cache scoping.
      *
@@ -270,7 +282,33 @@ export declare class HttpService {
      */
     runSingleFlightDeviceSecretMint(mint: () => Promise<DeviceSecretMintOutcome>): Promise<DeviceSecretMintOutcome>;
     /**
-     * Unwrap standardized API response format
+     * Unwrap the standardized API response envelope — EXCEPT when the envelope is
+     * a page, in which case it travels whole.
+     *
+     * `{ data: <payload> }` is the house success envelope (`sendSuccess`), and
+     * reducing it to `<payload>` is what every call site in the SDK expects. But
+     * the reduction DISCARDS every sibling key, silently, and a page's siblings
+     * are the only thing that says where the next page starts. That is how
+     * `GET /accounts/:id/audit` lost its `nextCursor`: the caller received a bare
+     * array, `getNextPageParam` read `undefined`, and pagination was dead past the
+     * first page with nothing to show that it was.
+     *
+     * ## Why the rule is narrow, and not "any sibling key survives"
+     *
+     * "An object carrying `data` plus anything else is not an envelope" is the
+     * tempting general rule, and it is wrong here: this API already answers
+     * `{ data, count }` on ~15 routes, plus `{ data, source }`, `{ data, reason }`
+     * and `{ data, secretDestroyed }`, and a dozen measured Console call sites
+     * type those as the bare payload (`Array<ProviderConnection>`,
+     * `AccountBillingState | null`, …). Preserving those envelopes would hand every
+     * one of them an object where it expects its payload — at runtime only, since
+     * the response type is a call-site assertion. So the rule names PAGINATION
+     * specifically: `data` beside {@link PAGE_ENVELOPE_KEYS} is a page.
+     *
+     * A route whose sibling key genuinely matters to its caller belongs in that
+     * list, or should not be a sibling of `data` at all — the cursor-paginated
+     * surfaces already in the SDK (`{ follows, nextCursor }`,
+     * `{ records, nextCursor }`) sidestep this by never using `data`.
      */
     private unwrapResponse;
     /**

package/dist/types/boot/sessionColdBoot.d.ts

@@ -15,10 +15,17 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
- *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
- *      re-mint from THIS device's primary identity key.
- *   4. Signed out.
+ *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
+ *      of its own but a sibling official app already put one in the shared native
+ *      slot: adopt it and mint. This is how a newly installed official app joins
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
  *
  * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
  *   - `account` (default) — the device's ACTIVE account owns the session. Every
@@ -33,6 +40,7 @@
  */
 import { type ColdBootOutcome } from '../utils/coldBoot';
 import { type IdentityBinding } from '../session/identitySession';
+import { type SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
 /**
@@ -108,6 +116,18 @@ export interface RunSessionColdBootOptions {
      * `sessionMode: 'identity'`. Ignored in `'account'` mode.
      */
     identity?: IdentityBinding;
+    /**
+     * The cross-app native slot holding this device's shared DeviceSession
+     * credential, enabling the `shared-device-adopt` lane. Supplied by
+     * `@oxyhq/services` on native; absent on web, where each origin is its own
+     * device by design.
+     *
+     * IGNORED in `sessionMode: 'identity'`. The shared slot belongs to whichever
+     * principal signed in on this device; an identity-bound client must resolve
+     * its session from the local key alone, and adopting a device credential is
+     * exactly the drift that mode exists to prevent.
+     */
+    sharedDeviceCredential?: SharedDeviceCredentialStore;
 }
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as

package/dist/types/index.d.ts

@@ -25,7 +25,7 @@ export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval';
 export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery';
 export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRoute, } from './utils/commonsDelivery';
-export type { ServiceTokenResponse, OAuthUserInfoResponse } from './mixins/OxyServices.auth';
+export type { ServiceTokenResponse, OAuthUserInfoResponse, OAuthTokenExchangeResult, } from './mixins/OxyServices.auth';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
@@ -40,7 +40,7 @@ export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
 export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
-export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
@@ -116,12 +116,17 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
-export { isSwitchTargetAccount, canSwitchIntoAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
-export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
+export { canActivateContext, directoryDisplayName, directoryHandle, projectDevicePrincipals, resolveActiveContext, resolveDeviceContext, } from './session/deviceDirectory';
+export type { DeviceContext, DeviceContextActor, DeviceContextSubject, DevicePrincipalGroup, } from './session/deviceDirectory';
+export { buildSwitcherRows, showsPrincipalHeaders } from './session/deviceSwitcherRows';
+export type { ResolveAvatarUrl, SwitcherContextRow, SwitcherPrincipalRow, } from './session/deviceSwitcherRows';
+export { isSwitchTargetAccount, canSwitchIntoAccount, } from './session/accountSwitchTargets';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
+export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './session/sharedDeviceCredential';
+export type { SharedDeviceCredential, SharedDeviceCredentialRead, SharedDeviceCredentialStore, SharedDeviceJoinDecision, SharedDeviceJoinSkipReason, SharedDevicePublishDecision, SharedDevicePublishOutcome, SharedDevicePublishSkipReason, } from './session/sharedDeviceCredential';
 export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './session/identityPin';
 export type { IdentityPin, IdentityPinStore } from './session/identityPin';
 export { resolveIdentityPin, establishIdentitySession, } from './session/identitySession';
@@ -129,6 +134,8 @@ export type { IdentityBinding, IdentityRequestOptions, EstablishedIdentitySessio
 export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
+export { OxyInferenceClient, OxyInferenceError, OXY_INFERENCE_BASE_URL, } from './inference/OxyInferenceClient';
+export type { OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyGenerationReceipt, OxyResponsesRequest, } from './inference/OxyInferenceClient';
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type { RunSessionColdBootOptions, SessionMode, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';

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

@@ -0,0 +1,324 @@
+/**
+ * The Oxy inference client — one surface, two credential lanes (issue #972,
+ * workstream 15).
+ *
+ * ```typescript
+ * // An OpenAI-style machine key: one bearer string, no session, no exchange.
+ * const oxy = new OxyInferenceClient({ credential: process.env.OXY_API_KEY });
+ *
+ * // Oxy auth: whatever bearer the session or the service-token mint holds.
+ * const oxy = oxyServices.inference();
+ * ```
+ *
+ * Both lanes reach the SAME endpoints and are told apart only by how the bearer
+ * is produced: a machine key is a constant string, and an Oxy bearer rotates, so
+ * it is a function this client calls on every request rather than a value it
+ * captures once. There is no third lane, and no method behaves differently
+ * depending on which one you used.
+ *
+ * ## What you will observe today
+ *
+ * **Every invoke refuses.** `respond()` reaches the public edge, which
+ * authenticates the credential, resolves attribution, authorizes scopes, pins a
+ * routing policy and reserves spend — and then has no data plane to forward to,
+ * so it releases the hold and answers `service_unavailable`. That surfaces here
+ * as an {@link OxyInferenceError} with `code: 'service_unavailable'`,
+ * `retryable: false` and a `requestId`. It is the correct answer, not a
+ * misconfiguration of yours, and no balance is spent.
+ *
+ * **The catalogue is empty**, so {@link OxyInferenceClient.listModels} answers
+ * `[]` and {@link OxyInferenceClient.getModel} throws for every id. `[]` is a
+ * normal answer to render, not an error to retry.
+ *
+ * `docs/inference/README.md` is the status board; `docs/inference/sdk.md` is
+ * this client's page.
+ *
+ * ## Why this is a client and not more methods on `OxyServices`
+ *
+ * Two reasons, both structural. A machine-key holder has no Oxy session at all,
+ * so a surface reached only through the session client would be unreachable for
+ * exactly the developer this workstream exists to serve. And the `/v1` error
+ * body is the contract's `InferenceError` at the top level rather than the
+ * platform's `{ error, message }` envelope — it carries `requestId`, `retryable`
+ * and `retryAfterMs`, all of which `OxyServices.handleError` would flatten into a
+ * message string. `oxyServices.inference()` binds the session bearer into this
+ * client so a session-holding app writes no plumbing of its own.
+ *
+ * ## Streaming is absent on purpose
+ *
+ * There is no `stream()` method and no `stream` field on a request. The stream
+ * event union exists in `@oxyhq/contracts` and no endpoint emits one — the edge
+ * refuses `stream: true` with `invalid_request`. A method that always failed
+ * would be a worse artefact than an absent one. See
+ * `docs/inference/streaming.md`.
+ *
+ * ## Field names, and the one place they could drift
+ *
+ * Every VALUE type here comes from `@oxyhq/contracts` — messages, tools, tool
+ * choice, response format, usage quantities, unit prices, error codes. The
+ * request FIELD NAMES cannot: they belong to `responsesRequestSchema`, which
+ * lives in the API because it is a public dialect rather than an Oxy↔data-plane
+ * contract. `packages/api/src/schemas/__tests__/sdkRequestCompatibility.test.ts`
+ * is the gate — it parses a value of this module's request type against that
+ * schema, so a rename on either side fails a build rather than a customer's
+ * request.
+ */
+import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxyhq/contracts';
+/** The base URL of the Oxy API, when a caller names none. */
+export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
+/**
+ * How this client gets its bearer.
+ *
+ * A `string` is a static machine credential (`oxy_sk_…`) — presented verbatim,
+ * exactly as a stock OpenAI SDK would present it. A function is the Oxy auth
+ * lane and is called on EVERY request, because a session bearer and a service
+ * token both rotate and a captured one goes stale inside the hour.
+ */
+export type OxyInferenceCredential = string | (() => string | null | Promise<string | null>);
+/**
+ * The `fetch` this client calls.
+ *
+ * The global signature rather than a narrowed one, so any drop-in
+ * implementation — a test double, an instrumented wrapper, a Node agent — is
+ * assignable without a cast at either end.
+ */
+export type OxyInferenceFetch = typeof fetch;
+export interface OxyInferenceClientOptions {
+    readonly credential: OxyInferenceCredential;
+    /** Defaults to {@link OXY_INFERENCE_BASE_URL}. A trailing slash is trimmed. */
+    readonly baseURL?: string;
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: OxyInferenceFetch;
+}
+/**
+ * A request to `POST /v1/responses`.
+ *
+ * `model` and `routingProfile` are mutually exclusive and BOTH are optional: an
+ * application whose routing policy carries a `defaultTarget` may name neither,
+ * which is what "per-application default model or routing profile" means. Naming
+ * both is refused by the edge with `invalid_request`.
+ */
+export interface OxyResponsesRequest {
+    /** `<publisher>/<model>` or `<publisher>/<model>@<revision>`. */
+    readonly model?: string;
+    /** A routing profile slug. Never contains a slash, so it is never a model id. */
+    readonly routingProfile?: string;
+    /** A prompt, or the message list it is shorthand for. */
+    readonly input: string | readonly InferenceMessage[];
+    readonly maxOutputTokens?: number;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+    readonly seed?: number;
+    readonly stopSequences?: readonly string[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly toolChoice?: ToolChoice;
+    readonly responseFormat?: ResponseFormat;
+    /** Cost-attribution tags, echoed back on the receipt. At most 16. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Your own correlation id, echoed on the response. */
+    readonly clientRequestId?: string;
+}
+export interface OxyInferenceRequestOptions {
+    /**
+     * Abort the request. The edge treats a client disconnect as a cancellation:
+     * it settles what was produced and refunds the rest, so a cancelled request
+     * is a normal terminal state rather than an error to clean up after.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * `Idempotency-Key`. A key already bound to a reservation is REFUSED with
+     * `idempotency_conflict` rather than replayed — responses are not retained,
+     * so there is nothing to replay, and refusing is what makes "a retry never
+     * produces a second charge" structural. At most 128 characters.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * `X-Oxy-User-Id` — the end user this request is made on behalf of.
+     * ATTRIBUTION ONLY: it never changes which account is charged.
+     */
+    readonly delegatedUserId?: string;
+}
+/** The body of a successful `POST /v1/responses`. */
+export interface OxyInferenceResponse {
+    readonly schemaVersion: 1;
+    /** Also on `X-Oxy-Request-Id`, on success and on every refusal. */
+    readonly requestId: string;
+    readonly generationId?: string;
+    /** Always revision-pinned, even when you named only the model line. */
+    readonly model: string;
+    readonly servingProvider: string;
+    readonly finishReason: InferenceFinishReason;
+    readonly output: readonly InferenceMessage[];
+    /** Metered quantities. Never money — the charge is on the receipt. */
+    readonly usage: readonly UsageQuantity[];
+    /** The exact policy version this request was admitted under. */
+    readonly routingPolicy: RoutingPolicyReference;
+    /**
+     * How long Oxy took over this request, in whole milliseconds — also on
+     * `X-Oxy-Latency-Ms`.
+     *
+     * Measured from the moment the edge received the request through
+     * authentication, admission, routing, the reservation, the call to the
+     * inference data plane and the settlement of the hold. Most of it is the
+     * upstream generating tokens; it does not separate the two.
+     *
+     * It is NOT the round trip you can measure yourself, which additionally
+     * covers DNS, TLS, both network legs and your own parse. Report them side by
+     * side rather than picking one — this figure has no network in it and yours
+     * cannot be attributed to the model.
+     *
+     * Optional because it is additive: an Oxy deployment older than the field
+     * omits it, and a streamed request never carries it (the head is written
+     * before the first frame arrives, so the number does not exist yet).
+     */
+    readonly latencyMs?: number;
+}
+/**
+ * A settled receipt, as `GET /v1/generations/:id` returns it.
+ *
+ * Carries the price SNAPSHOT rather than a reference to a price version, so the
+ * arithmetic stays checkable after that version has been superseded.
+ */
+export interface OxyGenerationReceipt {
+    readonly schemaVersion: 1;
+    readonly receiptId: string;
+    readonly requestId: string;
+    readonly generationId?: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    /** Attribution only. Never the billing identity. */
+    readonly delegatedUserId?: string;
+    readonly environment: InferenceEnvironment;
+    readonly outcome: InferenceRequestOutcome;
+    readonly usageSource: UsageSource;
+    /** EVERY unit, including the zeros — see `usageSource` for what a zero means. */
+    readonly units: readonly UsageQuantity[];
+    readonly resolvedModelReference: string;
+    readonly servingProvider: string;
+    readonly priceSnapshot: {
+        readonly priceVersionId: string;
+        readonly currency: CurrencyCode;
+        readonly unitPrices: readonly UnitPrice[];
+    };
+    readonly billedAmount: ExactDecimal;
+    readonly currency: CurrencyCode;
+    /** A BYOK route: `billedAmount` is Oxy's fee, not the cost of the tokens. */
+    readonly platformFeeOnly: boolean;
+    readonly settledAt: string;
+}
+/**
+ * Anything the inference API refused.
+ *
+ * `retryable` is asserted by the server and looked up from a total map over the
+ * closed code set — never inferred here from the status. A client that decides
+ * retryability from an HTTP status is exactly what the contract's retryability
+ * rule exists to prevent, so this class carries the server's answer and does not
+ * compute one.
+ */
+export declare class OxyInferenceError extends Error {
+    readonly code: InferenceErrorCode;
+    readonly retryable: boolean;
+    readonly requestId: string;
+    readonly status: number;
+    /** How long to wait. Only ever present when `retryable`. */
+    readonly retryAfterMs?: number;
+    /** The request field at fault, for `invalid_request`. */
+    readonly param?: string;
+    constructor(input: {
+        code: InferenceErrorCode;
+        message: string;
+        retryable: boolean;
+        requestId: string;
+        status: number;
+        retryAfterMs?: number;
+        param?: string;
+    });
+}
+/**
+ * The Oxy inference API.
+ *
+ * Stateless: it holds a base URL, a way to get a bearer and a `fetch`. Nothing
+ * is cached, because the two things worth caching here are a catalogue that is
+ * audience-scoped and a receipt that is immutable but rarely re-read.
+ *
+ * Successful responses are TYPED, not re-parsed. The server validates every one
+ * against its own schema before serving it, and a second client-side parse of a
+ * non-strict shape would silently DROP fields a newer API added — turning
+ * forward compatibility into data loss. Refusals are read defensively, because
+ * two routers answer under `/v1` and an unreadable failure must still reach the
+ * caller as one.
+ */
+export declare class OxyInferenceClient {
+    #private;
+    constructor(options: OxyInferenceClientOptions);
+    /**
+     * The models this caller may use — `GET /v1/models`.
+     *
+     * Audience-scoped server-side. A machine credential and an anonymous caller
+     * both see the PUBLIC catalogue; only an internal/system application's
+     * service token sees internal-only routes.
+     *
+     * **`[]` is a normal answer**, and is the only answer today: the catalogue
+     * is populated by operators, and a route is not publicly exposed until
+     * somebody has reviewed the right to resell it.
+     */
+    listModels(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry[]>;
+    /**
+     * One catalogue entry by its canonical id — `GET /v1/models/:publisher/:model`.
+     *
+     * The id is TWO path segments, because a canonical model id contains a slash
+     * and a single encoded segment would never match the route.
+     *
+     * A model you may not see answers 404 identically to one that does not
+     * exist, deliberately: the catalogue is never an existence oracle for what
+     * Oxy runs internally.
+     *
+     * @param modelId - `<publisher>/<model>`. A revision pin
+     *   (`<publisher>/<model>@<revision>`) names a model REFERENCE rather than a
+     *   model and is rejected here rather than sent, because the catalogue is
+     *   keyed on models and a pinned reference would 404 indistinguishably from
+     *   "no such model".
+     */
+    getModel(modelId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry>;
+    /**
+     * The routing profiles this caller may select — `GET /v1/models/routing-profiles`.
+     *
+     * A profile is a named strategy for CHOOSING among routes, not a model: no
+     * publisher, no revision, no licence, no weights. Like the model list, `[]`
+     * is a normal answer.
+     */
+    listRoutingProfiles(options?: {
+        signal?: AbortSignal;
+    }): Promise<RoutingProfile[]>;
+    /**
+     * Send one non-streaming inference request — `POST /v1/responses`.
+     *
+     * **This refuses in every deployment today** with `service_unavailable`,
+     * because there is no data plane behind the edge. The spend held for the
+     * request is released before the refusal returns, so nothing is charged.
+     *
+     * @throws {OxyInferenceError} for every refusal, carrying the server's own
+     *   `code`, `retryable` and `requestId`.
+     */
+    respond(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): Promise<OxyInferenceResponse>;
+    /**
+     * Read back the settled receipt for one request —
+     * `GET /v1/generations/:id`.
+     *
+     * `id` is the `requestId` you already hold (it is on every response and
+     * every error) or the `generationId`. Requires the `inference:usage:read`
+     * scope; a caller without it, or one whose application did not make the
+     * request, is told the receipt does not exist rather than that it belongs to
+     * somebody else.
+     */
+    getGeneration(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<OxyGenerationReceipt>;
+}