@arnilo/prism 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.2] - 2026-08-13
+
+### Changed
+- **Release 0.2.2 (plan 022)** is the concurrent-state-and-durability-integrity cut on the 0.2.x review-remediation line. API surface **additive-only** vs 0.2.1 (plain reviewed compat gate at 0.2.2: deltas are the version literal plus `ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget`, `ModelRouterReservation`, `ModelRouterBudgets.reservationTtlMs`, `ModelRouterLimits.maxRateKeys`/`maxBudgetKeys`, `SessionRecord.version` with `appendSession` `expectedVersion`, `EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER`, and the `@arnilo/prism/testing/state-concurrency-conformance` subpath; no removal; no `--allow-break`), four behavior tightenings documented in `docs/migration.md` `0.2.1 → 0.2.2`: (1) **atomic model-budget reservation** (`budget-reservation`, `@arnilo/prism-model-router` + `@arnilo/prism-enterprise-postgres`) — admission now runs `reserveBudget` (used + reserved + requested <= window max, `{reservationId, fencingToken, admitted, retryAfterMs?}`) and outcomes run `commitBudget` (actuals; a TTL-expired late commit charges the reserved amount with `unknownUsage: true`) or `releaseBudget`; reservations expire after `reservationTtlMs` (default 60 s, bounded to 31 days) so a crashed request never holds capacity forever; 0.2.1 `readBudget`/`addUsage` remain for cap-less requests and retrospective accounting, no longer admission authority; rate/budget key maps are capped (`maxRateKeys`/`maxBudgetKeys` 4,096 default / 65,536 hard; circuits unchanged) with LRU eviction that never drops a held-reservation row (capacity-exhausted fail-closed otherwise); durable store keeps reservations in a `reservations` JSONB column (enterprise migration 003, forward-only, checksummed). (2) **atomic conversation metadata** (`conversation-metadata-cas`, `@arnilo/prism-session-store-postgres` + `@arnilo/prism-session-store-sqlite`) — `SessionRecord.version` (fresh rows start at 1; migration 008 backfills legacy rows) and `appendSession` `expectedVersion` (`0` create-only, `N>0` exact-CAS update-only, omitted = 0.2.1 last-write-wins); stale writes throw `SessionMetadataConflictError` `metadata_conflict` carrying only `{id, expectedVersion, currentVersion}` (never metadata content), HTTP 409; concurrent create/branch/archive are single-statement with branch caps enforced inside the CAS write, archive wins over stale writers, retention-deleted rows are never resurrected. (3) **single-consumer EventMultiplexer** (`single-consumer`, core) — a second concurrent `subscribe()` throws `EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silently sharing one queue and losing events; slot frees on completion/return-at-yield/close; in-repo consumers (workflow bus, supervisor) already single-subscriber. (4) **restart-stable NATS durable identity + bounded non-durable active-run registries** (`nats-durable`, `@arnilo/prism-session-store-nats`; `active-runs`, `@arnilo/prism-workflows`) — the durable consumer name is exactly `prism_<hmac16 of tenantId|sessionId|runId>` (random suffix removed) so a crash-resumed subscribe continues from the last ack; clean stops delete the consumer (cursor resume), orphaned 0.2.1 `prism_<digest>_<random>` consumers are reclaimed by the existing cleanup; the workflow active-run registry sweeps aborted/leaked entries on register and fails closed at the 512 cap (`ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`), documented non-durable. New regression surface: `scripts/phase22-security.test.mjs` (5 tests: 4 blockers + gate accounting, built public entrypoints, wired into `security:threat-suites`), the packed plain-JS `security22.mjs` consumer in install-smoke, the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes — approval, cursor, checkpoint CAS, idempotency, router reservation, conversation metadata, unknown-outcome — memory leg in npm test, durable legs in `test:postgres`/NATS seam, zero timing-only sleeps), and the `scripts/phase22-conformance.test.mjs` gate in the `test:postgres` chain; phase-22 evidence in `scripts/phase22-baseline.json` + `scripts/phase22-freeze-manifest.json`. Release graph stays **50** publishable manifests at exact **0.2.2**; zero new runtime dependency names (core remains dependency-free). Store compatibility with 0.2.1: **forward-only migrations** (`prism_sessions.version` migration 008, `prism_model_router_budgets.reservations` enterprise migration 003; 0.2.1 databases migrate in place, 0.2.1 binaries read 0.2.2 databases but ignore the new columns — see `docs/migration.md` rollback-risk). Exit gate green (core + script gates incl. phase21-freeze + phase22 conformance, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.2, protected OIDC/OPA + durable state-concurrency evidence, evidence in `scripts/phase22-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.2 publish handoff` — signed `v0.2.2` tag + npm OIDC).
+
+## [0.2.1] - 2026-08-13
+
+### Changed
+- **Release 0.2.1 (plan 021)** is the provider-completion and outbound-trust-boundaries cut on the 0.2.x review-remediation line. API surface **additive-only** vs 0.2.0 (plain reviewed compat gate at 0.2.1: deltas are the version literal plus `@arnilo/prism-mcp` transport helpers re-exported from the lifted core primitives — same names/signatures, no removal; no `--allow-break`), five documented security-motivated behavior tightenings in `docs/migration.md` `0.2.0 → 0.2.1`: (1) **strict stream completion is the shared default** (`strict-completion`, core `createOpenAICompatibleProvider`) — `strictCompletion` defaults to `true` (explicit `false` stays the documented opt-out): a stream ending without `[DONE]` plus a choice-level `finish_reason` now fails with `ProviderTransportError` `incomplete_delta` instead of a successful `providerDone`, and done events carry usage only with completion evidence; applies to Azure, Bedrock, Vertex, OpenRouter, ZAI, NeuralWatt (Alibaba/Kimi/Ollama/OpenCode-go had already opted in). (2) **bounded success bodies** (`bounded-bodies`, core `@arnilo/prism/providers/transport`) — additive `readBoundedResponseJson` (65,536-byte UTF-8 ceiling, max JSON depth 32, max properties 4096, caller shape gate, abort, redacted errors, new `ProviderTransportError` code `response_body_shape`) replaces unbounded `response.json()` at all ten model-discovery sites plus NeuralWatt quota, Alibaba embeddings, OpenAI uploads, and both OAuth success paths. (3) **DNS-pinned OIDC/OPA/content fetch, redirects rejected** (`dns-pinning`, core `src/pinned-fetch.ts` + `@arnilo/prism-credentials-node`, `@arnilo/prism-policy`, `@arnilo/prism-mcp`) — `pinnedFetch`/`resolvePinnedAddress`/`requestPinned` lift the MCP pinning algorithm (one resolve, 1–32 bound, family check, loopback confinement, per-candidate `assertSsrfAllowedUrl`, pinned-lookup socket) into core; default JWKS, OPA decision, and content/media fetches route through it and **reject 3xx redirects outright** (`MediaContentError` code `redirect`); private/metadata/loopback answers fail closed `ssrf_denied`; MCP re-exports the lifted helpers with byte-identical behavior; egress `dns-pin.ts` deliberately NOT converged (0.3.x candidate). (4) **shared bounded OAuth device/token polling** (`oauth-consolidation`, core `src/oauth-device-code.ts`) — `pollDeviceCodeToken` serves both `@arnilo/prism-provider-openai` and `@arnilo/prism-credentials-node` device flows (RFC 8628 poll, `slow_down` +5 s, expiry deadline, cancellation, bounded reads, fail-closed token shape, `[REDACTED]` redaction); adapter fields stay plain options; behavior equivalent. (5) **edge fixes** (`edge-fixes`) — Azure/Vertex resolve rotating credentials **once per request** (inner provider re-created with the resolved token; never consumed twice); Bedrock SigV4 merges duplicate-case headers last-wins and sorts query params by encoded key then value (malformed duplicate-case signatures eliminated, single-case byte-identical); OpenAI upload cleanup retains file ids until their `DELETE` succeeds (no remote-file leak on failed cleanup); cache-telemetry `__overflow__` never carries cost (requests + token totals only). New regression surface: `scripts/phase21-security.test.mjs` (10 conformance tests over built public entrypoints covering all five items, wired into `security:threat-suites`) plus a packed plain-JS `security21.mjs` consumer in install-smoke; phase-21 freeze manifest `scripts/phase21-freeze-manifest.json` machine-checks each task's diff (preserved surface: egress dns-pin primitives, OAuth connector consumers, strictCompletion opt-in adapters, native streaming adapters). Release graph stays **50** publishable manifests (root + 49 workspace packages) at exact **0.2.1**; zero new runtime dependency names (core remains dependency-free). Store compatibility with 0.2.0: **compatible, no migration** (no persisted-shape change). Exit gate green (core + script gates incl. phase21-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.1, live OIDC JWKS protected evidence + live OPA fail-closed evidence, evidence in `scripts/phase21-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.1 publish handoff` — signed `v0.2.1` tag + npm OIDC).
+
 ## [0.2.0] - 2026-08-13
 
 ### Changed

package/dist/cache-telemetry.js

@@ -72,7 +72,10 @@ export function createCacheTelemetry(options = {}) {
                 cacheReadTokens: sample.cacheReadTokens,
                 inputTokens: sample.inputTokens,
             });
-            if (model?.cost) {
+            // The __overflow__ bucket aggregates mixed provider/model tokens, so it
+            // never carries cost: one model's cost metadata must not be applied to
+            // other models' tokens. It reports requests and token totals only.
+            if (model?.cost && sample !== overflowSample) {
                 // cacheSavings depends only on read tokens + cost metadata, so the
                 // aggregate equals the sum of per-call savings; feed it the totals
                 // to reuse the exact cache-helpers math rather than reimplementing it.

package/dist/content.d.ts

@@ -104,8 +104,8 @@ export declare class UnsupportedModalityError extends Error {
     constructor(modality: ModelInputCapability, model: ModelConfig);
 }
 export declare class MediaContentError extends Error {
-    readonly code: "ambiguous_source" | "missing_source" | "item_too_large" | "request_too_large" | "too_many_items" | "audio_too_long" | "invalid_base64" | "ssrf_denied" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
-    constructor(code: MediaContentError["code"], message: string);
+    readonly code: "ambiguous_source" | "missing_source" | "item_too_large" | "request_too_large" | "too_many_items" | "audio_too_long" | "invalid_base64" | "ssrf_denied" | "redirect" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
+    constructor(code: MediaContentError["code"], message: string, options?: ErrorOptions);
 }
 export declare function contentBlockInputModality(block: ContentBlock): ModelInputCapability | undefined;
 export declare function collectMessageContentBlocks(messages: readonly Message[]): ContentBlock[];

package/dist/content.js

@@ -1,7 +1,6 @@
 import { lookup as dnsLookup } from "node:dns/promises";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
+import { pinnedFetch } from "./pinned-fetch.js";
 import { assertPermission } from "./security.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
 export const MODEL_INPUT_CAPABILITIES = ["text", "image", "audio", "file", "document"];
@@ -29,8 +28,8 @@ export class UnsupportedModalityError extends Error {
 }
 export class MediaContentError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, options) {
+        super(message, options);
         this.name = "MediaContentError";
         this.code = code;
     }
@@ -310,22 +309,34 @@ async function fetchBoundedMediaUrl(url, options) {
     try {
         if (options.fetch)
             return await readFetchResponse(await options.fetch(url, { signal, redirect: "error" }), options.maxBytes);
-        const parsed = new URL(url);
-        const hostname = normalizeHostname(parsed.hostname);
-        const family = isIP(hostname);
-        const address = family
-            ? { address: hostname, family: family }
-            : await resolvePublicAddress(hostname, options.resolveHostname ?? defaultMediaHostnameResolver, signal, options.ssrf);
-        const bytes = await (options.requestUrl ?? requestPinnedMediaUrl)({
-            url: parsed,
-            address,
-            maxBytes: options.maxBytes,
-            signal,
-        });
-        if (bytes.byteLength > options.maxBytes) {
-            throw new MediaContentError("item_too_large", `Fetched media exceeded ${options.maxBytes} bytes`);
+        if (options.requestUrl) {
+            // Test/custom seam: explicit resolve + caller-provided requester. The default
+            // path below routes through the shared pinnedFetch primitive instead.
+            const parsed = new URL(url);
+            const hostname = normalizeHostname(parsed.hostname);
+            const family = isIP(hostname);
+            const address = family
+                ? { address: hostname, family: family }
+                : await resolvePublicAddress(hostname, options.resolveHostname ?? defaultMediaHostnameResolver, signal, options.ssrf);
+            const bytes = await options.requestUrl({
+                url: parsed,
+                address,
+                maxBytes: options.maxBytes,
+                signal,
+            });
+            if (bytes.byteLength > options.maxBytes) {
+                throw new MediaContentError("item_too_large", `Fetched media exceeded ${options.maxBytes} bytes`);
+            }
+            return bytes;
         }
-        return bytes;
+        // Default: one DNS-pinned, redirect-free, byte-bounded fetch (task 4).
+        const response = await pinnedFetch(new URL(url), { signal, redirect: "manual" }, {
+            errorPrefix: "Media",
+            hostnameErrorPrefix: "Media",
+            resolver: options.resolveHostname ?? defaultMediaHostnameResolver,
+            ssrf: options.ssrf,
+        });
+        return await readFetchResponse(response, options.maxBytes);
     }
     catch (error) {
         if (error instanceof MediaContentError)
@@ -411,37 +422,6 @@ async function readFetchResponse(response, maxBytes) {
     }
     return joinChunks(chunks, total);
 }
-function requestPinnedMediaUrl({ url, address, maxBytes, signal }) {
-    return new Promise((resolve, reject) => {
-        const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
-            agent: false,
-            family: address.family,
-            signal,
-            lookup: (_hostname, _options, callback) => callback(null, address.address, address.family),
-        }, (response) => readIncomingMessage(response, maxBytes).then(resolve, reject));
-        request.on("error", reject);
-        request.end();
-    });
-}
-async function readIncomingMessage(response, maxBytes) {
-    const status = response.statusCode ?? 0;
-    if (status < 200 || status >= 300) {
-        response.resume();
-        throw new MediaContentError("fetch_failed", `Media fetch failed with status ${status}`);
-    }
-    const chunks = [];
-    let total = 0;
-    for await (const chunk of response) {
-        const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk);
-        total += bytes.byteLength;
-        if (total > maxBytes) {
-            response.destroy();
-            throw new MediaContentError("item_too_large", `Fetched media exceeded ${maxBytes} bytes`);
-        }
-        chunks.push(bytes);
-    }
-    return joinChunks(chunks, total);
-}
 function joinChunks(chunks, total) {
     const bytes = new Uint8Array(total);
     let offset = 0;

package/dist/contracts-core.d.ts

@@ -823,6 +823,27 @@ export interface SessionBranchHandle {
 }
 /** Stable error code carried by `SessionAppendConflictError`. */
 export declare const SESSION_APPEND_CONFLICT_CODE: "session_append_conflict";
+/** CAS conflict code for `appendSession` metadata writes. Stable and message-independent. */
+export declare const SESSION_METADATA_CONFLICT_CODE: "metadata_conflict";
+/** Conflict details carried by `SessionMetadataConflictError`. Versions only; never metadata content. */
+export interface SessionMetadataConflict {
+    readonly code: typeof SESSION_METADATA_CONFLICT_CODE;
+    readonly id: string;
+    readonly expectedVersion: number;
+    readonly currentVersion: number;
+}
+/**
+ * Thrown when `appendSession` is called with an `expectedVersion` CAS guard and the
+ * stored session's version no longer matches (concurrent create/branch/archive, or a
+ * delete raced the write). Recognize via the stable `code` or `isSessionMetadataConflict`.
+ */
+export declare class SessionMetadataConflictError extends Error {
+    readonly conflict: SessionMetadataConflict;
+    readonly code: "metadata_conflict";
+    constructor(conflict: SessionMetadataConflict);
+}
+/** Type guard keyed off the stable `code` (works across bundles; not message text). */
+export declare function isSessionMetadataConflict(error: unknown): error is SessionMetadataConflictError;
 /** Conflict details carried by `SessionAppendConflictError`. Carries no secrets. */
 export interface SessionAppendConflict {
     readonly code: typeof SESSION_APPEND_CONFLICT_CODE;
@@ -954,6 +975,8 @@ export interface SessionRecord extends OwnershipScope {
     readonly expiresAt?: string;
     readonly retentionPolicyId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Write version for optimistic metadata CAS; undefined on legacy/never-written rows. */
+    readonly version?: number;
 }
 /** Stored branch handle / leaf pointer. The leaf is the current entry id for the branch. */
 export interface BranchRecord {
@@ -1182,8 +1205,15 @@ export interface ProductionPersistenceStore {
     queryRetentionPolicies(query: RetentionPolicyQuery): Promise<PersistencePage<RetentionPolicy>>;
     queryMigrations(query: MigrationQuery): Promise<PersistencePage<MigrationRecord>>;
     /** Optional session-record write capability (conversation threads, host-managed sessions).
-     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update. */
-    appendSession?(record: SessionRecord): Promise<void>;
+     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update.
+     *  Additive CAS: pass `expectedVersion` to require the stored version to match before the
+     *  write (0 = create-only, a positive number = exact current version); omit it for legacy
+     *  last-write-wins. Returns the new `version` when the underlying store supports it. */
+    appendSession?(record: SessionRecord & {
+        readonly expectedVersion?: number;
+    }): Promise<{
+        readonly version: number;
+    } | void>;
     /** DB-friendly branch read (mirrors `SessionStore.readBranchPath`): one ancestor-chain
      *  query instead of `queryEntries({ sessionId })` + in-memory walk. Optional. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;

package/dist/contracts-core.js

@@ -84,6 +84,26 @@ export function isSessionSearchUnsupported(error) {
 }
 /** Stable error code carried by `SessionAppendConflictError`. */
 export const SESSION_APPEND_CONFLICT_CODE = "session_append_conflict";
+/** CAS conflict code for `appendSession` metadata writes. Stable and message-independent. */
+export const SESSION_METADATA_CONFLICT_CODE = "metadata_conflict";
+/**
+ * Thrown when `appendSession` is called with an `expectedVersion` CAS guard and the
+ * stored session's version no longer matches (concurrent create/branch/archive, or a
+ * delete raced the write). Recognize via the stable `code` or `isSessionMetadataConflict`.
+ */
+export class SessionMetadataConflictError extends Error {
+    conflict;
+    code = SESSION_METADATA_CONFLICT_CODE;
+    constructor(conflict) {
+        super(`session metadata conflict: expected version ${conflict.expectedVersion}, current ${conflict.currentVersion}`);
+        this.conflict = conflict;
+        this.name = "SessionMetadataConflictError";
+    }
+}
+/** Type guard keyed off the stable `code` (works across bundles; not message text). */
+export function isSessionMetadataConflict(error) {
+    return error instanceof Error && error.code === SESSION_METADATA_CONFLICT_CODE;
+}
 /**
  * Thrown when `SessionStore.append` rejects an entry under `SessionAppendOptions`
  * (dangling/stale `expectedParentId`, stricter adapter CAS failure, or duplicate

package/dist/conversations.d.ts

@@ -21,6 +21,8 @@ export interface ConversationThread extends OwnershipScope {
     readonly updatedAt: string;
     /** Branch leaves recorded by the conversation service; the entry tree remains the content source of truth. */
     readonly branches: readonly ConversationBranchRef[];
+    /** CAS write version (stored `SessionRecord.version`); undefined on legacy rows. */
+    readonly version?: number;
     /** Host-supplied create metadata; never credentials or raw transcripts. */
     readonly metadata?: Readonly<Record<string, unknown>>;
 }

package/dist/conversations.js

@@ -80,6 +80,7 @@ export function conversationThreadFromRecord(record) {
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         branches: Object.freeze(branches),
+        version: record.version ?? 0,
         ...(metadata === undefined ? {} : { metadata }),
     };
 }

package/dist/event-multiplexer.d.ts

@@ -1,4 +1,10 @@
 export type EventOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
+export declare const EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+/** Thrown when a second consumer subscribes while one is active (single-consumer contract). */
+export declare class EventMultiplexerError extends Error {
+    readonly code = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+    constructor(message?: string);
+}
 export interface EventOverflowInfo {
     readonly droppedEvents: number;
     readonly maxQueuedEvents: number;
@@ -14,6 +20,13 @@ export interface EventMultiplexerOptions<T> {
 export interface EventMultiplexer<T> {
     publish(event: T): void;
     observe<S>(source: AsyncIterable<S>, map: (event: S) => T): () => void;
+    /**
+     * Single-consumer subscription. A second concurrent subscriber is rejected with
+     * `EventMultiplexerError` (ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER); the slot
+     * frees when the active consumer's iterator completes or is `return()`ed at a
+     * yield, or when the multiplexer closes. A consumer parked awaiting an event is
+     * released by the next `publish`/`close` — `return()` while parked waits for it.
+     */
     subscribe(): AsyncIterable<T>;
     close(): void;
     readonly droppedEvents: number;

package/dist/event-multiplexer.js

@@ -1,3 +1,12 @@
+export const EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+/** Thrown when a second consumer subscribes while one is active (single-consumer contract). */
+export class EventMultiplexerError extends Error {
+    code = EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE;
+    constructor(message = "Event multiplexer already has an active subscriber") {
+        super(message);
+        this.name = "EventMultiplexerError";
+    }
+}
 /** Bounded single-consumer fan-in for arbitrary async event sources. */
 export function createEventMultiplexer(options = {}) {
     const maxQueuedEvents = Math.max(1, options.maxQueuedEvents ?? 1024);
@@ -8,6 +17,9 @@ export function createEventMultiplexer(options = {}) {
     let isClosed = false;
     let droppedEvents = 0;
     let overflowNotified = false;
+    // Single-consumer contract: the parked-waiter design corrupts the queue when two
+    // consumers iterate concurrently, so a second active consumer is rejected instead.
+    let activeConsumer = false;
     const abort = () => close();
     if (options.signal?.aborted)
         isClosed = true;
@@ -108,6 +120,9 @@ export function createEventMultiplexer(options = {}) {
         options.signal?.removeEventListener("abort", abort);
         finishSources();
         queue.length = 0;
+        // Free the single-consumer slot: a consumer suspended at a yield may never pull
+        // again, and after close a fresh subscriber terminates immediately anyway.
+        activeConsumer = false;
         if (waiter) {
             const resolve = waiter;
             waiter = undefined;
@@ -115,23 +130,31 @@ export function createEventMultiplexer(options = {}) {
         }
     }
     async function* subscribe() {
-        while (true) {
-            if (queue.length > 0) {
-                if (options.compare)
-                    queue.sort(options.compare);
-                yield queue.shift();
-                continue;
+        if (activeConsumer)
+            throw new EventMultiplexerError();
+        activeConsumer = true;
+        try {
+            while (true) {
+                if (queue.length > 0) {
+                    if (options.compare)
+                        queue.sort(options.compare);
+                    yield queue.shift();
+                    continue;
+                }
+                if (isClosed)
+                    return;
+                const next = await new Promise((resolve) => {
+                    waiter = resolve;
+                });
+                if (next.done)
+                    return;
+                if (next.value === WAKE)
+                    continue;
+                yield next.value;
             }
-            if (isClosed)
-                return;
-            const next = await new Promise((resolve) => {
-                waiter = resolve;
-            });
-            if (next.done)
-                return;
-            if (next.value === WAKE)
-                continue;
-            yield next.value;
+        }
+        finally {
+            activeConsumer = false;
         }
     }
     return {

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { resolveAgentDefinition } from "./agent-definitions.js";
+export { abortableSleep, pollDeviceCodeToken, redactOAuthError, throwIfAborted, type OAuthTokenSuccessPayload, type PollDeviceCodeTokenOptions, } from "./oauth-device-code.js";
+export { boundResponse, defaultResolver, isLoopbackAddress, isLoopbackHostname, normalizeHostname, pinnedFetch, raceAbort, requestPinned, resolvePinnedAddress, type PinnedFetchOptions, } from "./pinned-fetch.js";
 export type { AgentEventSourceErrorCode } from "./agent-event-source.js";
 export { AgentEventSourceError, createMemoryAgentEventSource } from "./agent-event-source.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
@@ -25,7 +27,7 @@ export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission,
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
 export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, ResumeNestedRun, RunDecision, RunLimitCounters, RunLimitName, SecureAgentOptions, StickyDecision, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -36,7 +38,7 @@ export { createChainedCredentialResolver, createEnvCredentialResolver, createExp
 export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConformanceResult, DeviceKind, DevicePolicyErrorCode, DevicePolicyOptions, DeviceStreamLimits, ResolvedDevicePolicy, } from "./devices.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, EventOverflowPolicy } from "./event-multiplexer.js";
-export { createEventMultiplexer } from "./event-multiplexer.js";
+export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
@@ -107,5 +109,5 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.2.0";
+export declare const version = "0.2.2";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -1,4 +1,6 @@
 export { resolveAgentDefinition } from "./agent-definitions.js";
+export { abortableSleep, pollDeviceCodeToken, redactOAuthError, throwIfAborted, } from "./oauth-device-code.js";
+export { boundResponse, defaultResolver, isLoopbackAddress, isLoopbackHostname, normalizeHostname, pinnedFetch, raceAbort, requestPinned, resolvePinnedAddress, } from "./pinned-fetch.js";
 export { AgentEventSourceError, createMemoryAgentEventSource } from "./agent-event-source.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
@@ -12,13 +14,13 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
-export { createEventMultiplexer } from "./event-multiplexer.js";
+export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
@@ -58,6 +60,6 @@ export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MI
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.2.0";
+export const version = "0.2.2";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/oauth-device-code.d.ts

@@ -0,0 +1,58 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./contracts-core.js";
+/**
+ * Shared RFC 8628 device-code flow used by both the OpenAI Codex OAuth provider
+ * (provider-openai) and the generic OAuth 2.0 provider (credentials-node).
+ * Owns the device-code request, the poll loop (authorization_pending continue,
+ * slow_down backoff, expiry deadline), cancellation, bounded success/error
+ * body reads, secret redaction, and token-shape parsing. Adapter-specific
+ * fields are parameters/callbacks, not subclasses.
+ */
+export declare const REDACTED = "[REDACTED]";
+export declare const DEFAULT_DEVICE_POLL_INTERVAL_MS = 5000;
+export declare const SLOW_DOWN_INCREMENT_MS = 5000;
+export interface OAuthDeviceCodePayload {
+    readonly device_code: string;
+    readonly user_code: string;
+    readonly verification_uri: string;
+    readonly expires_in?: number;
+    readonly interval?: number;
+}
+export interface OAuthTokenSuccessPayload {
+    readonly access_token?: string;
+    readonly refresh_token?: string;
+    readonly expires_in?: number;
+    readonly account_id?: string;
+}
+export interface OAuthTokenErrorPayload {
+    readonly error?: string;
+    readonly error_description?: string;
+}
+export interface PollDeviceCodeTokenOptions {
+    readonly fetchImpl: typeof fetch;
+    readonly deviceCodeUrl: string;
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    readonly scope?: string;
+    /** Extra token-request params merged into every poll body (e.g. client_secret, audience). Never logged. */
+    readonly extraTokenParams?: Readonly<Record<string, string>>;
+    readonly callbacks?: Pick<OAuthLoginCallbacks, "onDeviceCode" | "signal">;
+    /** Message prefix, e.g. "OpenAI" or the adapter id. */
+    readonly errorPrefix: string;
+    /** Test seam: override wall clock for device-code expiry. */
+    readonly now?: () => number;
+    /** Test seam: override poll delay between device-code token requests. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Token-shape parsing; adapter-specific fields (e.g. accountId fallback) applied here. */
+    readonly parseTokenCredentials: (json: OAuthTokenSuccessPayload) => OAuthCredentials;
+}
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function redactOAuthError(error: Error, secrets: readonly (string | undefined)[]): Error;
+/**
+ * Request a device code, surface it through `onDeviceCode`, then poll the token
+ * endpoint until success, expiry, a terminal OAuth error, or abort. All response
+ * bodies are read under the shared byte ceiling; success bodies must be bounded
+ * JSON with an `access_token` string (fail closed otherwise); error bodies are
+ * bounded text parsed as JSON with a redacted-text fallback.
+ */
+export declare function pollDeviceCodeToken(options: PollDeviceCodeTokenOptions): Promise<OAuthCredentials>;

package/dist/oauth-device-code.js

@@ -0,0 +1,119 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { readBoundedResponseJson, readBoundedResponseText } from "./providers/transport.js";
+/**
+ * Shared RFC 8628 device-code flow used by both the OpenAI Codex OAuth provider
+ * (provider-openai) and the generic OAuth 2.0 provider (credentials-node).
+ * Owns the device-code request, the poll loop (authorization_pending continue,
+ * slow_down backoff, expiry deadline), cancellation, bounded success/error
+ * body reads, secret redaction, and token-shape parsing. Adapter-specific
+ * fields are parameters/callbacks, not subclasses.
+ */
+export const REDACTED = "[REDACTED]";
+export const DEFAULT_DEVICE_POLL_INTERVAL_MS = 5_000;
+export const SLOW_DOWN_INCREMENT_MS = 5_000;
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error("OAuth login aborted");
+}
+export async function abortableSleep(ms, signal) {
+    if (ms <= 0)
+        return;
+    throwIfAborted(signal);
+    await delay(ms, undefined, { signal });
+}
+export function redactOAuthError(error, secrets) {
+    let message = error.message;
+    for (const secret of secrets) {
+        if (secret)
+            message = message.split(secret).join(REDACTED);
+    }
+    return new Error(message);
+}
+const isDeviceCodePayload = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.device_code === "string" &&
+        candidate.device_code.length > 0 &&
+        typeof candidate.user_code === "string" &&
+        candidate.user_code.length > 0 &&
+        typeof candidate.verification_uri === "string" &&
+        candidate.verification_uri.length > 0);
+};
+const isTokenSuccessPayload = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return typeof value.access_token === "string";
+};
+/**
+ * Request a device code, surface it through `onDeviceCode`, then poll the token
+ * endpoint until success, expiry, a terminal OAuth error, or abort. All response
+ * bodies are read under the shared byte ceiling; success bodies must be bounded
+ * JSON with an `access_token` string (fail closed otherwise); error bodies are
+ * bounded text parsed as JSON with a redacted-text fallback.
+ */
+export async function pollDeviceCodeToken(options) {
+    const { fetchImpl, deviceCodeUrl, tokenUrl, clientId, scope, extraTokenParams, callbacks, errorPrefix, parseTokenCredentials } = options;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? abortableSleep;
+    const requestBody = { client_id: clientId };
+    if (scope)
+        requestBody.scope = scope;
+    const response = await fetchImpl(deviceCodeUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(requestBody),
+        signal: callbacks?.signal,
+    });
+    if (!response.ok) {
+        const detail = await readBoundedResponseText(response);
+        throw redactOAuthError(new Error(`${errorPrefix} device code failed: ${response.status}${detail ? ` ${detail}` : ""}`), []);
+    }
+    const json = await readBoundedResponseJson(response, { shape: isDeviceCodePayload });
+    const secrets = [json.device_code, json.user_code];
+    const expiresAtMs = now() + (json.expires_in ?? 0) * 1_000;
+    await callbacks?.onDeviceCode?.({
+        userCode: json.user_code,
+        verificationUri: json.verification_uri,
+        expiresAt: json.expires_in ? new Date(expiresAtMs).toISOString() : undefined,
+    });
+    let intervalMs = Math.max(1, (json.interval ?? DEFAULT_DEVICE_POLL_INTERVAL_MS / 1_000) * 1_000);
+    while (now() < expiresAtMs) {
+        throwIfAborted(callbacks?.signal);
+        await sleep(intervalMs, callbacks?.signal);
+        throwIfAborted(callbacks?.signal);
+        const tokenResponse = await fetchImpl(tokenUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                client_id: clientId,
+                device_code: json.device_code,
+                ...extraTokenParams,
+            }),
+            signal: callbacks?.signal,
+        });
+        if (tokenResponse.ok) {
+            const payload = await readBoundedResponseJson(tokenResponse, { shape: isTokenSuccessPayload });
+            return parseTokenCredentials(payload);
+        }
+        const errorText = await readBoundedResponseText(tokenResponse, { secrets });
+        let errorPayload;
+        try {
+            errorPayload = JSON.parse(errorText);
+        }
+        catch {
+            errorPayload = { error: "invalid_token_response", error_description: errorText };
+        }
+        const code = errorPayload.error ?? "unknown_error";
+        if (code === "authorization_pending")
+            continue;
+        if (code === "slow_down") {
+            intervalMs += SLOW_DOWN_INCREMENT_MS;
+            continue;
+        }
+        throw redactOAuthError(new Error(`${errorPrefix} device code login failed: ${code}${errorPayload.error_description ? ` ${errorPayload.error_description}` : ""}`), secrets);
+    }
+    throw redactOAuthError(new Error(`${errorPrefix} device code login expired before authorization completed`), secrets);
+}
+//# sourceMappingURL=oauth-device-code.js.map