@oxy.so/core 1.0.0

package/dist/esm/inference/OxyInferenceClient.js

@@ -0,0 +1,538 @@
+/**
+ * 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.
+ *
+ * `respond()` returns one completed response. `stream()` reads the same
+ * `/v1/responses` endpoint without buffering and validates every SSE event
+ * against `inferenceStreamEventSchema` before exposing it to the caller.
+ *
+ * ## 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 an explicit method
+ *
+ * `stream()` injects `stream: true` on the wire. The request type deliberately
+ * has no `stream` field, so `respond({ stream: true })` cannot promise a JSON
+ * response while the server sends SSE, and `stream({ stream: false })` cannot
+ * silently buffer. The method is the transport choice.
+ *
+ * ## Field names, and the one place they could drift
+ *
+ * Every VALUE type here comes from `@oxy.so/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_headers, _OxyInferenceClient_request;
+import { INFERENCE_ERROR_CODES, inferenceStreamEventSchema, modelIdSchema } from '@oxy.so/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 edge opened an SSE response but its framing or one of its events violated
+ * the published inference stream contract.
+ *
+ * This is distinct from {@link OxyInferenceError}: the latter is a refusal the
+ * server deliberately returned, while this error means the client could not
+ * safely interpret a nominally successful stream.
+ */
+export class OxyInferenceProtocolError extends Error {
+    constructor(message, requestId) {
+        super(message);
+        this.name = 'OxyInferenceProtocolError';
+        if (requestId !== undefined)
+            this.requestId = requestId;
+    }
+}
+/**
+ * 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.
+ *
+ * Completed JSON 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. Stream events are different: each is a
+ * versioned wire message and is parsed against the shared contract before it is
+ * yielded. 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`.
+     *
+     * @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 }),
+        });
+    }
+    /**
+     * Stream one inference request from `POST /v1/responses`.
+     *
+     * The transport choice is method-level: this method adds `stream: true` and
+     * requests SSE, while {@link respond} never does. Every yielded value has
+     * already passed `inferenceStreamEventSchema`, belongs to the request id in
+     * the response header and advances the stream sequence. A terminal `error`
+     * event is yielded as part of the published union; an HTTP refusal before
+     * the stream opens throws {@link OxyInferenceError}.
+     *
+     * Breaking out of the iterator cancels the response body. Passing an abort
+     * signal additionally lets the caller cancel while waiting for the first or
+     * any later event.
+     *
+     * @throws {OxyInferenceError} when the edge refuses before opening SSE.
+     * @throws {OxyInferenceProtocolError} when a successful SSE response cannot
+     *   be interpreted under the published stream contract.
+     */
+    async *stream(request, options = {}) {
+        const response = await __classPrivateFieldGet(this, _OxyInferenceClient_fetch, "f").call(this, `${__classPrivateFieldGet(this, _OxyInferenceClient_baseURL, "f")}/v1/responses`, {
+            method: 'POST',
+            headers: await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_headers).call(this, 'text/event-stream', {
+                hasBody: true,
+                ...(options.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: options.idempotencyKey }),
+                ...(options.delegatedUserId === undefined
+                    ? {}
+                    : { delegatedUserId: options.delegatedUserId }),
+            }),
+            body: JSON.stringify({ ...request, stream: true }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        if (!response.ok) {
+            const payload = await response.json().catch(() => undefined);
+            throw toInferenceError(payload, response.status, response.headers.get('X-Oxy-Request-Id'));
+        }
+        const requestId = response.headers.get('X-Oxy-Request-Id') ?? undefined;
+        const mediaType = response.headers
+            .get('Content-Type')
+            ?.split(';', 1)[0]
+            ?.trim()
+            .toLowerCase();
+        if (mediaType !== 'text/event-stream') {
+            await cancelUnreadResponse(response);
+            throw protocolError(`The inference API answered a streaming request with ${mediaType ?? 'no Content-Type'} instead of text/event-stream.`, requestId);
+        }
+        if (requestId === undefined || requestId.length === 0) {
+            await cancelUnreadResponse(response);
+            throw protocolError('The inference API opened a stream without X-Oxy-Request-Id.', requestId);
+        }
+        if (response.body === null) {
+            throw protocolError('The inference API opened a stream with no response body.', requestId);
+        }
+        let lastSequence = -1;
+        let terminal = false;
+        for await (const frame of decodeEventStream(response.body, requestId)) {
+            if (terminal) {
+                throw protocolError('The inference API sent an event after a terminal event.', requestId);
+            }
+            let payload;
+            try {
+                payload = JSON.parse(frame.data);
+            }
+            catch (_error) {
+                throw protocolError(`The inference API sent a ${frame.name || 'unnamed'} SSE event that is not JSON.`, requestId);
+            }
+            const parsed = inferenceStreamEventSchema.safeParse(payload);
+            if (!parsed.success) {
+                const path = parsed.error.issues[0]?.path;
+                throw protocolError(`The inference API sent an event outside the published stream contract at ${path === undefined || path.length === 0 ? 'an unknown field' : path.join('.')}.`, requestId);
+            }
+            const event = parsed.data;
+            if (frame.name !== event.type) {
+                throw protocolError(`The inference API framed a ${event.type} event as ${frame.name || 'unnamed'}.`, requestId);
+            }
+            if (event.requestId !== requestId) {
+                throw protocolError('The inference API sent an event for a different request id.', requestId);
+            }
+            if (event.sequence <= lastSequence) {
+                throw protocolError('The inference API sent a stream sequence that did not advance.', requestId);
+            }
+            lastSequence = event.sequence;
+            terminal = event.type === 'done' || event.type === 'error';
+            yield event;
+        }
+        if (!terminal) {
+            throw protocolError('The inference API closed the stream before a terminal done or error event.', requestId);
+        }
+    }
+    /**
+     * 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_headers = 
+/** Build the authenticated headers for one request, re-reading its bearer. */
+async function _OxyInferenceClient_headers(accept, options) {
+    const headers = {
+        Authorization: `Bearer ${await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_bearer).call(this)}`,
+        Accept: accept,
+    };
+    if (options.hasBody)
+        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;
+    }
+    return headers;
+}, _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 response = await __classPrivateFieldGet(this, _OxyInferenceClient_fetch, "f").call(this, `${__classPrivateFieldGet(this, _OxyInferenceClient_baseURL, "f")}${path}`, {
+        method,
+        headers: await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_headers).call(this, 'application/json', {
+            hasBody: options.body !== undefined,
+            ...(options.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: options.idempotencyKey }),
+            ...(options.delegatedUserId === undefined
+                ? {}
+                : { delegatedUserId: options.delegatedUserId }),
+        }),
+        ...(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;
+};
+/** Bound one public SSE event before parsing it as JSON. */
+const MAX_INFERENCE_STREAM_EVENT_CHARACTERS = 8 * 1024 * 1024;
+/** Bound the `data:` array too; empty lines consume memory without characters. */
+const MAX_INFERENCE_STREAM_EVENT_DATA_LINES = 4096;
+function protocolError(message, requestId) {
+    return new OxyInferenceProtocolError(message, requestId);
+}
+/** Cancel a nominally successful response whose stream contract is unreadable. */
+async function cancelUnreadResponse(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+/**
+ * Decode SSE incrementally, preserving chunk boundaries only until a complete
+ * line is available.
+ *
+ * Multiple `data:` lines join with a newline, comments are ignored and a final
+ * frame does not need a trailing blank line. Cancelling the iterator cancels the
+ * body reader, which is how breaking out of `for await` closes the HTTP request
+ * instead of leaving generation running upstream.
+ */
+async function* decodeEventStream(body, requestId) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    let pending = '';
+    let name = '';
+    let data = [];
+    let accumulated = 0;
+    let dataLines = 0;
+    let reachedEnd = false;
+    const decode = (chunk, options) => {
+        try {
+            return decoder.decode(chunk, options);
+        }
+        catch (_error) {
+            throw protocolError('The inference API sent an SSE stream that is not valid UTF-8.', requestId);
+        }
+    };
+    const dispatch = () => {
+        if (data.length === 0 && name.length === 0)
+            return undefined;
+        const frame = { name, data: data.join('\n') };
+        name = '';
+        data = [];
+        accumulated = 0;
+        dataLines = 0;
+        return frame;
+    };
+    const consume = (raw) => {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.length === 0)
+            return dispatch();
+        if (line.startsWith(':'))
+            return undefined;
+        const separator = line.indexOf(':');
+        const field = separator === -1 ? line : line.slice(0, separator);
+        const rawValue = separator === -1 ? '' : line.slice(separator + 1);
+        const value = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue;
+        if (field === 'data') {
+            dataLines += 1;
+            if (dataLines > MAX_INFERENCE_STREAM_EVENT_DATA_LINES) {
+                throw protocolError(`The inference API sent an SSE event with over ${MAX_INFERENCE_STREAM_EVENT_DATA_LINES} data lines.`, requestId);
+            }
+            accumulated += value.length;
+            if (accumulated > MAX_INFERENCE_STREAM_EVENT_CHARACTERS) {
+                throw protocolError(`The inference API sent an SSE event over ${MAX_INFERENCE_STREAM_EVENT_CHARACTERS} characters.`, requestId);
+            }
+            data.push(value);
+        }
+        else if (field === 'event') {
+            name = value.trim();
+        }
+        return undefined;
+    };
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                reachedEnd = true;
+                break;
+            }
+            pending += decode(chunk.value, { stream: true });
+            if (pending.length > MAX_INFERENCE_STREAM_EVENT_CHARACTERS) {
+                throw protocolError(`The inference API sent an SSE line over ${MAX_INFERENCE_STREAM_EVENT_CHARACTERS} characters with no boundary.`, requestId);
+            }
+            let newline = pending.indexOf('\n');
+            while (newline !== -1) {
+                const frame = consume(pending.slice(0, newline));
+                pending = pending.slice(newline + 1);
+                if (frame !== undefined)
+                    yield frame;
+                newline = pending.indexOf('\n');
+            }
+        }
+        pending += decode();
+        if (pending.length > 0) {
+            const frame = consume(pending);
+            if (frame !== undefined)
+                yield frame;
+        }
+        const trailing = dispatch();
+        if (trailing !== undefined)
+            yield trailing;
+    }
+    finally {
+        if (!reachedEnd) {
+            // Preserve the original parse/abort error if transport cancellation
+            // itself also refuses: cancellation is cleanup, never the diagnosis.
+            await reader.cancel().catch(() => undefined);
+        }
+        reader.releaseLock();
+    }
+}
+/**
+ * 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/logger/index.js

@@ -0,0 +1,140 @@
+/**
+ * @oxy.so/core/logger — the ecosystem-wide logging chokepoint.
+ *
+ * A tiny, dependency-free, universal logger that works unchanged in React
+ * Native, browsers, Node, and Bun. Every Oxy app and package should log
+ * through here instead of calling `console.*` directly, so that level,
+ * formatting, and transport are controlled in ONE place.
+ *
+ * Design goals:
+ *  - Zero dependencies. No Node-only imports, no `process.stdout` assumptions.
+ *  - Four levels (`debug` | `info` | `warn` | `error`) plus `silent`.
+ *  - Namespaced child loggers via `createLogger('mention:feed')` / `.child()`.
+ *  - Structured context objects carried through to the sink.
+ *  - A single pluggable sink so backends can pipe to pino / CloudWatch / etc.
+ *    without touching any call site.
+ *  - Debug is off in production by default (`__DEV__` on RN, `NODE_ENV`
+ *    elsewhere); override globally with `configureLogger({ level })`.
+ *
+ * @module logger
+ */
+const LEVEL_WEIGHT = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+/**
+ * True in development. Uses React Native's `__DEV__` when present, otherwise
+ * falls back to `process.env.NODE_ENV === 'development'`. Never throws.
+ */
+export function isDev() {
+    if (typeof __DEV__ !== 'undefined')
+        return __DEV__ === true;
+    try {
+        return typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
+    }
+    catch {
+        return false;
+    }
+}
+function formatPrefix(entry) {
+    const parts = [entry.timestamp, entry.level.toUpperCase()];
+    if (entry.namespace)
+        parts.push(`[${entry.namespace}]`);
+    return parts.join(' ');
+}
+/**
+ * Default sink: routes each entry to the matching `console` method. `info` and
+ * `debug` go to `console.log` (RN/browser-safe — `console.debug`/`console.info`
+ * are inconsistently surfaced across runtimes).
+ */
+export const consoleSink = (entry) => {
+    const extras = [];
+    if (entry.context && Object.keys(entry.context).length > 0)
+        extras.push(entry.context);
+    if (entry.error !== undefined)
+        extras.push(entry.error);
+    if (entry.args.length > 0)
+        extras.push(...entry.args);
+    const line = `${formatPrefix(entry)} ${entry.message}`;
+    if (entry.level === 'error')
+        console.error(line, ...extras);
+    else if (entry.level === 'warn')
+        console.warn(line, ...extras);
+    else
+        console.log(line, ...extras);
+};
+function defaultLevel() {
+    return isDev() ? 'debug' : 'info';
+}
+const config = {
+    level: defaultLevel(),
+    sink: consoleSink,
+};
+/**
+ * Update the global logger configuration. Affects every logger instance
+ * (root and children) immediately. Pass `{ level }` to gate output and/or
+ * `{ sink }` to redirect transport (pino, CloudWatch, a test capture, …).
+ */
+export function configureLogger(partial) {
+    if (partial.level !== undefined)
+        config.level = partial.level;
+    if (partial.sink !== undefined)
+        config.sink = partial.sink;
+}
+/** Read a snapshot of the current global configuration. */
+export function getLoggerConfig() {
+    return { level: config.level, sink: config.sink };
+}
+/** Restore the default level (env-derived) and the console sink. */
+export function resetLoggerConfig() {
+    config.level = defaultLevel();
+    config.sink = consoleSink;
+}
+function mergeContext(base, extra) {
+    if (!base)
+        return extra;
+    if (!extra)
+        return base;
+    return { ...base, ...extra };
+}
+function emit(level, namespace, baseContext, message, error, context, args) {
+    if (LEVEL_WEIGHT[level] > LEVEL_WEIGHT[config.level])
+        return;
+    config.sink({
+        level,
+        message,
+        namespace,
+        context: mergeContext(baseContext, context),
+        error,
+        args,
+        timestamp: new Date().toISOString(),
+    });
+}
+function makeLogger(namespace, baseContext) {
+    return {
+        namespace,
+        debug: (message, context, ...args) => emit('debug', namespace, baseContext, message, undefined, context, args),
+        info: (message, context, ...args) => emit('info', namespace, baseContext, message, undefined, context, args),
+        warn: (message, context, ...args) => emit('warn', namespace, baseContext, message, undefined, context, args),
+        error: (message, error, context, ...args) => emit('error', namespace, baseContext, message, error, context, args),
+        child: (childNamespace, childContext) => makeLogger(namespace ? `${namespace}:${childNamespace}` : childNamespace, mergeContext(baseContext, childContext)),
+    };
+}
+/** The shared root logger. Prefer a namespaced `createLogger(...)` in modules. */
+export const logger = makeLogger(undefined, undefined);
+/**
+ * Create a namespaced logger.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger('mention:feed');
+ * log.info('loaded', { count: 20 });
+ * const sub = log.child('prefetch'); // namespace → 'mention:feed:prefetch'
+ * ```
+ */
+export function createLogger(namespace, context) {
+    return makeLogger(namespace, context);
+}