@oxyhq/core 21.0.0 → 21.0.2

package/dist/esm/HttpService.js

@@ -962,19 +962,46 @@ export class HttpService {
         return this.deviceSecretMintInFlight;
     }
     /**
-     * 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`.
      */
     unwrapResponse(responseData) {
-        // Handle paginated responses: { data: [...], pagination: {...} }
-        if (responseData && typeof responseData === 'object' && 'data' in responseData && 'pagination' in responseData) {
+        if (!responseData || typeof responseData !== 'object' || !('data' in responseData)) {
+            // Not the success envelope (or not an object at all) — as-is.
             return responseData;
         }
-        // Handle regular success responses: { data: ... }
-        if (responseData && typeof responseData === 'object' && 'data' in responseData && !Array.isArray(responseData)) {
-            return responseData.data;
+        // A page travels whole: its cursor/pagination sibling is unrecoverable
+        // information, not decoration.
+        if (HttpService.PAGE_ENVELOPE_KEYS.some((key) => key in responseData)) {
+            return responseData;
         }
-        // Return as-is for responses that don't use sendSuccess wrapper
-        return responseData;
+        // Regular success envelope: `{ data: ... }` -> the payload.
+        return Array.isArray(responseData) ? responseData : responseData.data;
     }
     /**
      * Update request metrics
@@ -1151,3 +1178,15 @@ export class HttpService {
  * ambiguous with a serialized request body.
  */
 HttpService.CACHE_IDENTITY_DELIM = ' id=';
+/**
+ * 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.
+ */
+HttpService.PAGE_ENVELOPE_KEYS = ['pagination', 'nextCursor'];

package/dist/esm/i18n/locales/en-US.json

@@ -2136,8 +2136,13 @@
             "filesWrite": "Upload and modify your files",
             "filesDelete": "Delete your files",
             "webhooksReceive": "Receive webhooks",
-            "chatCompletions": "Use AI chat on your behalf",
-            "modelsRead": "List available AI models",
+            "inferenceInvoke": "Run AI requests on your behalf",
+            "inferenceModelsRead": "List available AI models",
+            "inferenceUsageRead": "Read its AI usage and costs",
+            "inferenceRoutingRead": "Read how AI requests are routed",
+            "inferenceRoutingWrite": "Change how AI requests are routed",
+            "inferenceProvidersRead": "Read its connected AI providers",
+            "inferenceProvidersWrite": "Manage its connected AI providers",
             "federationWrite": "Act across federated services"
         },
         "account": {

package/dist/esm/i18n/locales/es-ES.json

@@ -2136,8 +2136,13 @@
             "filesWrite": "Subir y modificar tus archivos",
             "filesDelete": "Eliminar tus archivos",
             "webhooksReceive": "Recibir webhooks",
-            "chatCompletions": "Usar el chat con IA en tu nombre",
-            "modelsRead": "Ver los modelos de IA disponibles",
+            "inferenceInvoke": "Ejecutar peticiones de IA en tu nombre",
+            "inferenceModelsRead": "Ver los modelos de IA disponibles",
+            "inferenceUsageRead": "Ver su consumo y costes de IA",
+            "inferenceRoutingRead": "Ver cómo se enrutan las peticiones de IA",
+            "inferenceRoutingWrite": "Cambiar cómo se enrutan las peticiones de IA",
+            "inferenceProvidersRead": "Ver sus proveedores de IA conectados",
+            "inferenceProvidersWrite": "Gestionar sus proveedores de IA conectados",
             "federationWrite": "Actuar en servicios federados"
         },
         "account": {

package/dist/esm/i18n/locales/locales/en-US.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Upload and modify your files",
       "filesDelete": "Delete your files",
       "webhooksReceive": "Receive webhooks",
-      "chatCompletions": "Use AI chat on your behalf",
-      "modelsRead": "List available AI models",
+      "inferenceInvoke": "Run AI requests on your behalf",
+      "inferenceModelsRead": "List available AI models",
+      "inferenceUsageRead": "Read its AI usage and costs",
+      "inferenceRoutingRead": "Read how AI requests are routed",
+      "inferenceRoutingWrite": "Change how AI requests are routed",
+      "inferenceProvidersRead": "Read its connected AI providers",
+      "inferenceProvidersWrite": "Manage its connected AI providers",
       "federationWrite": "Act across federated services"
     },
     "account": {

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Subir y modificar tus archivos",
       "filesDelete": "Eliminar tus archivos",
       "webhooksReceive": "Recibir webhooks",
-      "chatCompletions": "Usar el chat con IA en tu nombre",
-      "modelsRead": "Ver los modelos de IA disponibles",
+      "inferenceInvoke": "Ejecutar peticiones de IA en tu nombre",
+      "inferenceModelsRead": "Ver los modelos de IA disponibles",
+      "inferenceUsageRead": "Ver su consumo y costes de IA",
+      "inferenceRoutingRead": "Ver cómo se enrutan las peticiones de IA",
+      "inferenceRoutingWrite": "Cambiar cómo se enrutan las peticiones de IA",
+      "inferenceProvidersRead": "Ver sus proveedores de IA conectados",
+      "inferenceProvidersWrite": "Gestionar sus proveedores de IA conectados",
       "federationWrite": "Actuar en servicios federados"
     },
     "account": {

package/dist/esm/index.js

@@ -231,6 +231,10 @@ export { resolveIdentityPin, establishIdentitySession, } from './session/identit
 // the identity session instead of dropping a healthy device credential.
 export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot.js';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
+// The inference API. `oxyServices.inference()` binds the session bearer into
+// the same client an external developer constructs with an `oxy_sk_…` machine
+// key — one surface, two credential lanes. See `docs/inference/sdk.md`.
+export { OxyInferenceClient, OxyInferenceError, OXY_INFERENCE_BASE_URL, } from './inference/OxyInferenceClient.js';
 export { runSessionColdBoot } from './boot/sessionColdBoot.js';
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

package/dist/esm/inference/OxyInferenceClient.js

@@ -0,0 +1,325 @@
+/**
+ * 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.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _OxyInferenceClient_instances, _OxyInferenceClient_baseURL, _OxyInferenceClient_credential, _OxyInferenceClient_fetch, _OxyInferenceClient_bearer, _OxyInferenceClient_request;
+import { INFERENCE_ERROR_CODES, modelIdSchema } from '@oxyhq/contracts';
+/** The base URL of the Oxy API, when a caller names none. */
+export const OXY_INFERENCE_BASE_URL = 'https://api.oxy.so';
+/**
+ * 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 class OxyInferenceError extends Error {
+    constructor(input) {
+        super(input.message);
+        this.name = 'OxyInferenceError';
+        this.code = input.code;
+        this.retryable = input.retryable;
+        this.requestId = input.requestId;
+        this.status = input.status;
+        if (input.retryAfterMs !== undefined)
+            this.retryAfterMs = input.retryAfterMs;
+        if (input.param !== undefined)
+            this.param = input.param;
+    }
+}
+/**
+ * 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 class OxyInferenceClient {
+    constructor(options) {
+        _OxyInferenceClient_instances.add(this);
+        _OxyInferenceClient_baseURL.set(this, void 0);
+        _OxyInferenceClient_credential.set(this, void 0);
+        _OxyInferenceClient_fetch.set(this, void 0);
+        const baseURL = options.baseURL ?? OXY_INFERENCE_BASE_URL;
+        __classPrivateFieldSet(this, _OxyInferenceClient_baseURL, baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL, "f");
+        __classPrivateFieldSet(this, _OxyInferenceClient_credential, options.credential, "f");
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (fetchImpl === undefined) {
+            throw new Error('OxyInferenceClient needs a fetch implementation: this runtime has no global fetch, so pass one as `fetch`.');
+        }
+        __classPrivateFieldSet(this, _OxyInferenceClient_fetch, fetchImpl, "f");
+    }
+    /**
+     * 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.
+     */
+    async listModels(options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', '/v1/models', { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * 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".
+     */
+    async getModel(modelId, options = {}) {
+        const parsed = modelIdSchema.safeParse(modelId);
+        if (!parsed.success) {
+            throw new Error(`Not a canonical model id: ${modelId}. Expected <publisher>/<model>, e.g. acme/some-model.`);
+        }
+        const [publisher, model] = parsed.data.split('/');
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', `/v1/models/${encodeURIComponent(publisher)}/${encodeURIComponent(model)}`, { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * 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.
+     */
+    async listRoutingProfiles(options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', '/v1/models/routing-profiles', { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * 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`.
+     */
+    async respond(request, options = {}) {
+        return __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'POST', '/v1/responses', {
+            body: request,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: options.idempotencyKey }),
+            ...(options.delegatedUserId === undefined
+                ? {}
+                : { delegatedUserId: options.delegatedUserId }),
+        });
+    }
+    /**
+     * 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.
+     */
+    async getGeneration(id, options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', `/v1/generations/${encodeURIComponent(id)}`, { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+}
+_OxyInferenceClient_baseURL = new WeakMap(), _OxyInferenceClient_credential = new WeakMap(), _OxyInferenceClient_fetch = new WeakMap(), _OxyInferenceClient_instances = new WeakSet(), _OxyInferenceClient_bearer = 
+/** The bearer for this request, from whichever lane was configured. */
+async function _OxyInferenceClient_bearer() {
+    const value = typeof __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f") === 'string'
+        ? __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f")
+        : await __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f").call(this);
+    if (value === null || value === undefined || value.length === 0) {
+        throw new Error('OxyInferenceClient has no bearer: the configured credential resolved to nothing. On the Oxy auth lane this usually means the session is not restored yet.');
+    }
+    return value;
+}, _OxyInferenceClient_request = 
+/**
+ * One request, and the one place a refusal becomes an
+ * {@link OxyInferenceError}.
+ *
+ * Two error shapes arrive here, because two routers serve `/v1`. The edge
+ * returns the contract error at the top level; the catalogue returns the
+ * platform's `{ error, message }` envelope. Both are read, and a body that
+ * is neither still produces an `OxyInferenceError` — with the code the
+ * status maps to — rather than a bare `Error`, so a caller's `catch` never
+ * has to branch on which router answered.
+ */
+async function _OxyInferenceClient_request(method, path, options) {
+    const headers = {
+        Authorization: `Bearer ${await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_bearer).call(this)}`,
+        Accept: 'application/json',
+    };
+    if (options.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    if (options.idempotencyKey !== undefined) {
+        headers['Idempotency-Key'] = options.idempotencyKey;
+    }
+    if (options.delegatedUserId !== undefined) {
+        headers['X-Oxy-User-Id'] = options.delegatedUserId;
+    }
+    const response = await __classPrivateFieldGet(this, _OxyInferenceClient_fetch, "f").call(this, `${__classPrivateFieldGet(this, _OxyInferenceClient_baseURL, "f")}${path}`, {
+        method,
+        headers,
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        throw toInferenceError(payload, response.status, response.headers.get('X-Oxy-Request-Id'));
+    }
+    return payload;
+};
+/**
+ * Which code a status means when the body did not name one.
+ *
+ * Deliberately partial: only the statuses whose meaning is unambiguous without a
+ * body. Everything else becomes `internal_error`, which is non-retryable — the
+ * safe direction, since inventing a retryable code for an unreadable failure is
+ * how one outage becomes a retry storm.
+ */
+const STATUS_FALLBACK_CODE = {
+    400: 'invalid_request',
+    401: 'authentication_failed',
+    403: 'permission_denied',
+    404: 'model_not_found',
+    409: 'idempotency_conflict',
+    413: 'request_too_large',
+    429: 'rate_limited',
+    502: 'provider_error',
+    503: 'service_unavailable',
+    504: 'provider_timeout',
+};
+/**
+ * The closed set the contract defines, as a lookup.
+ *
+ * A `code` outside it is a contract violation rather than a code this client
+ * has not caught up with — `INFERENCE_ERROR_CODES` and the version header move
+ * together — so an unrecognised one falls back to the status map instead of
+ * being asserted into the type.
+ */
+const INFERENCE_ERROR_CODE_SET = new Set(INFERENCE_ERROR_CODES);
+/** Read whichever error shape arrived into the one this client throws. */
+function toInferenceError(payload, status, requestIdHeader) {
+    const body = (payload ?? {});
+    // The edge's own shape is the contract error at the top level; the
+    // catalogue's is the platform envelope, whose `error` is a string.
+    const code = typeof body.code === 'string' && INFERENCE_ERROR_CODE_SET.has(body.code)
+        ? body.code
+        : (STATUS_FALLBACK_CODE[status] ?? 'internal_error');
+    const message = typeof body.message === 'string' && body.message.length > 0
+        ? body.message
+        : typeof body.error === 'string' && body.error.length > 0
+            ? body.error
+            : `The inference API answered ${status}.`;
+    return new OxyInferenceError({
+        code,
+        message,
+        // A body that did not assert retryability is not retryable: the server
+        // is the only thing that may say a retry could succeed.
+        retryable: body.retryable === true,
+        requestId: typeof body.requestId === 'string' && body.requestId.length > 0
+            ? body.requestId
+            : (requestIdHeader ?? ''),
+        status,
+        ...(body.retryable === true && typeof body.retryAfterMs === 'number'
+            ? { retryAfterMs: body.retryAfterMs }
+            : {}),
+        ...(typeof body.param === 'string' ? { param: body.param } : {}),
+    });
+}

package/dist/esm/mixins/OxyServices.accounts.js

@@ -330,76 +330,6 @@ export function OxyServicesAccountsMixin(Base) {
             }
         }
         // =========================================================================
-        // Bot (account) service credentials  —  /accounts/:id/credentials
-        // =========================================================================
-        /**
-         * List a bot account's service credentials. The response NEVER includes
-         * secrets.
-         * @param accountId - The account's Mongo `_id`.
-         */
-        async listAccountCredentials(accountId) {
-            try {
-                const res = await this.makeRequest('GET', `/accounts/${encodeURIComponent(accountId)}/credentials`, undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
-                return res.credentials ?? [];
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Create a service credential for a bot account. The plaintext `secret` is
-         * returned exactly ONCE; the server stores only a hash and will never return
-         * it again.
-         * @param accountId - The account's Mongo `_id`.
-         * @param data - Credential configuration (`type` is always `service`).
-         */
-        async createAccountCredential(accountId, data) {
-            try {
-                const result = await this.makeRequest('POST', `/accounts/${encodeURIComponent(accountId)}/credentials`, data, { cache: false });
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Rotate a bot credential's secret. The new plaintext `secret` is returned
-         * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
-         * credentialId) and `graceExpiresAt` (ISO string for the grace window during
-         * which the old credential is still honoured).
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        async rotateAccountCredential(accountId, credentialId) {
-            try {
-                const result = await this.makeRequest('POST', `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, undefined, { cache: false });
-                // Rotation changes credential status/audit fields surfaced by the list.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Revoke a bot credential (`status='revoked'`). Revoked credentials can no
-         * longer authenticate.
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        async revokeAccountCredential(accountId, credentialId) {
-            try {
-                const result = await this.makeRequest('DELETE', `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}`, undefined, { cache: false });
-                // Revocation flips the credential's status in the cached list.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
         // Applications owned by an account  —  /applications
         // =========================================================================
         /**
@@ -520,10 +450,13 @@ export function OxyServicesAccountsMixin(Base) {
          * which the old credential is still honoured).
          * @param applicationId - The application's Mongo `_id`.
          * @param credentialId - The credential's Mongo `_id`.
+         * @param options - `graceSeconds` keeps a superseded `machine` token working
+         *   for that long. Omitted, the previous token dies the moment the
+         *   replacement is minted.
          */
-        async rotateAppCredential(applicationId, credentialId) {
+        async rotateAppCredential(applicationId, credentialId, options) {
             try {
-                const result = await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, undefined, { cache: false });
+                const result = await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, options, { cache: false });
                 // Rotation changes credential status/audit fields surfaced by the list.
                 this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
                 return result;

package/dist/esm/mixins/OxyServices.inference.js

@@ -0,0 +1,56 @@
+/**
+ * The inference API, reached with whatever bearer this session already holds
+ * (issue #972, workstream 15).
+ *
+ * ```typescript
+ * const models = await oxyServices.inference().listModels();
+ * ```
+ *
+ * One method, and it is a FACTORY rather than a set of inference methods on
+ * `OxyServices`. The calls themselves live once, in
+ * {@link OxyInferenceClient} — which an external developer holding only an
+ * `oxy_sk_…` machine key constructs directly, with no Oxy session anywhere in
+ * the picture. Declaring the same calls a second time here would give the
+ * ecosystem two spellings of one request, and only one of them would stay
+ * correct.
+ *
+ * This is the reasoning `createLinkedClient` is already built on: the plumbing
+ * that binds an Oxy bearer to a client belongs in core, once, rather than in
+ * each app.
+ *
+ * The credential is a FUNCTION, not the current token: a session bearer rotates
+ * on refresh and on account switch, and a client that captured one at
+ * construction would start answering 401 an hour into the process's life.
+ */
+import { OxyInferenceClient } from '../inference/OxyInferenceClient.js';
+export function OxyServicesInferenceMixin(Base) {
+    return class extends Base {
+        constructor() {
+            super(...arguments);
+            /** @internal Memoized so repeated calls return one object identity. */
+            this._inferenceClient = null;
+        }
+        /**
+         * The inference client for this session.
+         *
+         * Bound to this instance's base URL and to `getAccessToken()`, so it
+         * follows every refresh, sign-in and account switch without being
+         * rebuilt.
+         *
+         * A service-authenticated process wants a different credential and
+         * builds {@link OxyInferenceClient} directly:
+         * `new OxyInferenceClient({ credential: () => oxy.getServiceToken() })`.
+         * The mint is asynchronous and cached, which is exactly what a
+         * credential function is for.
+         */
+        inference() {
+            if (this._inferenceClient === null) {
+                this._inferenceClient = new OxyInferenceClient({
+                    baseURL: this.getBaseURL(),
+                    credential: () => this.getAccessToken(),
+                });
+            }
+            return this._inferenceClient;
+        }
+    };
+}