@oxyhq/core 20.1.0 → 21.0.1

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.auth.js

@@ -1140,6 +1140,23 @@ export function OxyServicesAuthMixin(Base) {
          * response this method used before were an Oxy invention no OAuth library
          * could interoperate with; the endpoint no longer accepts them. The method's
          * OWN signature is unchanged, so callers are unaffected.
+         *
+         * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+         * outcome, not an error. A third-party grant is meant to be isolated from the
+         * browser's shared DeviceSession, so the token endpoint must be free to return
+         * no device credential at all — the guard that used to require the pair made
+         * that omission unshippable, since it turned every third-party sign-in through
+         * the SDK into a silent `exchange-failed`.
+         *
+         * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+         * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+         * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+         * access token itself — nothing persists a restore credential, the cold boot's
+         * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+         * scheduler has nothing to re-mint from. When the token expires the session
+         * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+         * out, so the app can run the OAuth flow again. It never degrades into a
+         * session that looks alive and cannot refresh.
          */
         async exchangeOAuthCode(params) {
             try {
@@ -1161,7 +1178,9 @@ export function OxyServicesAuthMixin(Base) {
                 const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
                 const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
                 const userRaw = record.user;
-                if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
+                // The device pair is NOT part of this guard — see the note above. What is
+                // still mandatory is what identifies the session at all.
+                if (!sessionId || !userRaw || typeof userRaw !== 'object') {
                     throw new Error('auth/oauth/token returned an incomplete session payload');
                 }
                 const userObj = userRaw;
@@ -1174,12 +1193,17 @@ export function OxyServicesAuthMixin(Base) {
                 if (accessToken) {
                     this.setTokens(accessToken);
                 }
+                if (!deviceId || !deviceSecret) {
+                    logger.debug('auth/oauth/token returned no device credential — this session lives only as long as its access token', { component: 'oxy.auth', method: 'exchangeOAuthCode' });
+                }
                 return {
                     sessionId,
-                    deviceId,
                     expiresAt,
                     accessToken,
-                    deviceSecret,
+                    // Omitted rather than set to `undefined` when the server sent no device
+                    // credential, so a device-less grant serializes as the absence it is.
+                    ...(deviceId ? { deviceId } : {}),
+                    ...(deviceSecret ? { deviceSecret } : {}),
                     user: {
                         id: userId,
                         username: typeof userObj.username === 'string' ? userObj.username : undefined,

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;
+        }
+    };
+}

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

@@ -149,7 +149,7 @@ export function OxyServicesUtilityMixin(Base) {
          *   additionally checked for `aud`, `iss`, and `type` claims to prevent
          *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
-         *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
+         *   direct access to `ACCESS_TOKEN_SECRET`.
          *
          * **Why session-less user tokens are refused rather than trusted:**
          * every user access token the Oxy API issues carries a `sessionId` (see
@@ -181,7 +181,7 @@ export function OxyServicesUtilityMixin(Base) {
          * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
          * // Protect all routes under /protected
-         * app.use('/protected', oxy.auth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+         * app.use('/protected', oxy.auth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
          *
          * // Access user in route handler
          * app.get('/protected/me', (req, res) => {
@@ -195,7 +195,7 @@ export function OxyServicesUtilityMixin(Base) {
          * app.use('/public', oxy.auth({ optional: true }));
          *
          * // Require a specific scope on a service-token-protected route
-         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }), oxy.requireScope('files:write'));
+         * app.use('/internal/files', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }), oxy.requireScope('files:write'));
          * ```
          *
          * @param options Optional configuration
@@ -360,13 +360,19 @@ export function OxyServicesUtilityMixin(Base) {
                                 return onError(error);
                             return res.status(401).json(error);
                         }
-                        // Validate required service token fields
+                        // Validate required service token fields. All of them are
+                        // required, `ownerAccountId` included: an optional billing
+                        // principal is one fallback away from being resolved from the
+                        // delegated user, which is the exact confusion ADR 0007 forbids.
                         const appId = decoded.appId;
                         const credentialId = decoded.credentialId;
+                        const ownerAccountId = decoded.ownerAccountId;
                         const environment = decoded.environment;
                         if (!appId ||
                             typeof credentialId !== 'string' ||
                             credentialId.length === 0 ||
+                            typeof ownerAccountId !== 'string' ||
+                            ownerAccountId.length === 0 ||
                             !isOxyServiceEnvironment(environment)) {
                             if (optional) {
                                 req.userId = null;
@@ -405,6 +411,11 @@ export function OxyServicesUtilityMixin(Base) {
                                     return onError(error);
                                 return res.status(403).json(error);
                             }
+                            // ATTRIBUTION ONLY. `req.userId` answers "on whose behalf", never
+                            // "who pays": the billing principal stays `req.serviceApp
+                            // .ownerAccountId`, which this branch does not touch. Read it
+                            // through `getOxyBillingPrincipal` (`@oxyhq/core/server`), whose
+                            // return type a user id cannot satisfy (ADR 0007).
                             req.userId = oxyUserId;
                             req.user = { id: oxyUserId };
                             req.serviceActingAs = { userId: oxyUserId, scopes: grant.scopes };
@@ -419,6 +430,7 @@ export function OxyServicesUtilityMixin(Base) {
                             appId,
                             appName: decoded.appName || 'unknown',
                             credentialId,
+                            ownerAccountId,
                             scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
                             environment,
                         };
@@ -735,7 +747,7 @@ export function OxyServicesUtilityMixin(Base) {
          * @example
          * ```typescript
          * // Protect internal endpoints
-         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }));
+         * app.use('/internal', oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }));
          *
          * app.post('/internal/trigger', (req, res) => {
          *   console.log('Service app:', req.serviceApp);
@@ -773,7 +785,7 @@ export function OxyServicesUtilityMixin(Base) {
          * ```typescript
          * app.use(
          *   '/internal/files',
-         *   oxy.serviceAuth({ jwtSecret: process.env.SERVICE_TOKEN_SECRET }),
+         *   oxy.serviceAuth({ jwtSecret: process.env.ACCESS_TOKEN_SECRET }),
          *   oxy.requireScope('files:write'),
          * );
          * ```

package/dist/esm/mixins/index.js

@@ -32,6 +32,7 @@ import { OxyServicesChainsMixin } from './OxyServices.chains.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph.js';
+import { OxyServicesInferenceMixin } from './OxyServices.inference.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
 /**
@@ -96,6 +97,11 @@ const MIXIN_PIPELINE = [
     // The user-owned follow graph (#809). One relationship per user and target,
     // shared across applications, with per-application context on top.
     OxyServicesFollowGraphMixin,
+    // The inference model catalogue (#972). Reads only, and deliberately no
+    // request/stream/receipt methods — the public inference edge those would
+    // call is workstream 4 and does not exist yet. See
+    // `docs/inference/README.md` for what is and is not built.
+    OxyServicesInferenceMixin,
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,