@arnilo/prism 0.1.7 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [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
+- **Release 0.2.0 (plan 020)** is the first cut of the 0.2.x review-remediation line — fail-closed runtime and sandbox security, closing the three blockers from the 2026-08-12 comprehensive review. API surface **additive-only** vs 0.1.7 (plain compat gate at 0.2.0: 0 breaking deltas; no `--allow-break`), three documented security-motivated behavior tightenings in `docs/migration.md` `0.1.7 → 0.2.0`: (1) **durable-resume input validation** (`resume-validation`, core) — `assertValidAgentRunResume` runs once at the top of `prepareAgentRunResume` before any state claim/checkpoint write/tool execution, covering all four public resume entrypoints; unknown legacy decisions (`"sideways"`), malformed batches, oversized reasons/elicitation, and duplicate approval ids fail closed with stable `ERR_PRISM_DECISION_*` codes, version untouched, zero tool calls; the server parser stays defense in depth. (2) **work-tool environment isolation** (`work-tools-env`, `@arnilo/prism-work-tools`) — `createCliRunner` children no longer inherit ambient host env: fixed base allow-list (PATH/LANG/LC_ALL/TZ + Windows system keys), explicit validated `env`, forced HOME/telemetry controls, late-bound per-identity tokens, 64-name/64-KiB caps (`ERR_PRISM_WORK_ENV`), absolute `binary`/`configDir` required, linear output capture (single final `Buffer.concat`). (3) **explicit sandbox capabilities** (`sandbox-capabilities`, `@arnilo/prism-coding-security`) — `SandboxAdapter.capabilities` (`workspaceCoherent`/`filesystemIsolated`/`networkIsolated`/`processIsolated`/`privilegeIsolated`/`egressRestricted`); omission/malformed metadata resolves all isolation `false`; `SandboxCodingComposition.capabilities` resolved from real wiring + validated adapter metadata; `containmentClaim` retained as `@deprecated` conservative projection (`workspaceCoherent && filesystemIsolated && networkIsolated && processIsolated`); Docker reports only verified controls, native reports filesystem/process/privilege `false`; authorization reads individual capabilities (docs/coding-security.md capability table + docs/host-security.md). New regression surface: `scripts/phase20-security.test.mjs` (public built entrypoints, all three blockers + gate accounting, wired into `security:threat-suites`), packed plain-JS consumer regressions in install-smoke, and the sandbox-browser workflow now records Docker/native capability evidence with a fail-loud 0.2.0 blocker gate (never a passing skip). Release graph stays **50** publishable manifests (root + 49 workspace packages) at exact **0.2.0**; zero new runtime dependency names (dependency fingerprint unchanged). Store compatibility with 0.1.7: **compatible, no migration** (no persisted-shape change). Exit gate green (core + script gates incl. phase20-freeze done-phase, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.0, Docker daemon + native netns protected evidence, evidence in `scripts/phase20-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.0 publish handoff` — signed `v0.2.0` tag + npm OIDC).
+
 ## [0.1.7] - 2026-08-12
 
 ### Changed

package/dist/agent-approval.d.ts

@@ -1,8 +1,17 @@
 import type { StoredAgentRunState } from "./agent-run-state.js";
-import { Agent, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
+import { Agent, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
 import type { AgentIdentity } from "./identity.js";
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
 export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly PendingDecision[] | undefined;
+/**
+ * Transport-neutral shape validation for the complete `AgentRunResume` input (plan 020 Task 2).
+ * Runs before any checkpoint read/write, agent resolution, subscription, or tool execution so
+ * untyped callers (plain JavaScript, `as any`) cannot make resume fall through to approval or
+ * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
+ * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
+ * elicitation payloads, credentials, or foreign approval details.
+ */
+export declare function assertValidAgentRunResume(resume: AgentRunResume): void;
 interface ResolvedRunDecisions {
     readonly decisionsById: ReadonlyMap<string, RunDecision>;
     readonly stickyDecisions: readonly StickyDecision[];

package/dist/agent-approval.js

@@ -21,6 +21,87 @@ export function pendingDecisionsOf(state) {
     }
     return undefined;
 }
+/**
+ * Transport-neutral shape validation for the complete `AgentRunResume` input (plan 020 Task 2).
+ * Runs before any checkpoint read/write, agent resolution, subscription, or tool execution so
+ * untyped callers (plain JavaScript, `as any`) cannot make resume fall through to approval or
+ * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
+ * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
+ * elicitation payloads, credentials, or foreign approval details.
+ */
+export function assertValidAgentRunResume(resume) {
+    const invalid = (message) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message);
+    if (resume === null || typeof resume !== "object" || Array.isArray(resume)) {
+        throw invalid("Resume must be a non-null object");
+    }
+    if (!Number.isSafeInteger(resume.expectedVersion) || resume.expectedVersion <= 0) {
+        throw invalid("Resume expectedVersion must be a positive safe integer");
+    }
+    const hasDecision = resume.decision !== undefined;
+    const hasDecisions = resume.decisions !== undefined;
+    if (hasDecision && hasDecisions)
+        throw invalid("Resume accepts exactly one of decision or decisions");
+    if (!hasDecision && !hasDecisions)
+        throw invalid("Resume requires a decision or decisions");
+    if (hasDecision) {
+        if (resume.decision !== "approve" && resume.decision !== "deny") {
+            throw invalid("Unknown legacy decision");
+        }
+        return;
+    }
+    const decisions = resume.decisions;
+    if (!Array.isArray(decisions))
+        throw invalid("Decision batch must be an array");
+    if (decisions.length === 0)
+        throw invalid("Decision batch must not be empty");
+    if (decisions.length > HARD_MAX_PENDING_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision batch exceeds ${HARD_MAX_PENDING_DECISIONS} entries`);
+    }
+    const seen = new Set();
+    for (const decision of decisions) {
+        if (decision === null || typeof decision !== "object" || Array.isArray(decision)) {
+            throw invalid("Decision batch entries must be objects");
+        }
+        if (typeof decision.approvalId !== "string" || decision.approvalId.length === 0 || decision.approvalId.length > 128) {
+            throw invalid("Decision approvalId must be a bounded non-empty string");
+        }
+        if (seen.has(decision.approvalId)) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_DUPLICATE", "Duplicate approval decision in batch");
+        }
+        seen.add(decision.approvalId);
+        if (decision.outcome !== "allow_once" &&
+            decision.outcome !== "allow_for_run" &&
+            decision.outcome !== "reject_once" &&
+            decision.outcome !== "reject_for_run") {
+            throw invalid("Unknown approval outcome");
+        }
+        if (decision.reason !== undefined) {
+            if (typeof decision.reason !== "string")
+                throw invalid("Decision reason must be a string");
+            if (Buffer.byteLength(decision.reason, "utf8") > MAX_DECISION_REASON_BYTES) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision reason exceeds ${MAX_DECISION_REASON_BYTES} bytes`);
+            }
+        }
+        for (const key of ["modifiedArguments", "elicitation"]) {
+            const payload = decision[key];
+            if (payload === undefined)
+                continue;
+            if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+                throw invalid(`Decision ${key} must be a JSON object`);
+            }
+            let text;
+            try {
+                text = JSON.stringify(payload);
+            }
+            catch {
+                throw invalid(`Decision ${key} must be a JSON object`);
+            }
+            if (text === undefined || Buffer.byteLength(text, "utf8") > MAX_ELICITATION_BYTES) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision ${key} exceeds ${MAX_ELICITATION_BYTES} bytes`);
+            }
+        }
+    }
+}
 /**
  * Validate one decision batch against the suspended state. Fail-closed and atomic: any
  * invalid entry rejects the whole batch before any CAS, leaving state and version untouched.

package/dist/agent-run-lifecycle.js

@@ -1,6 +1,6 @@
 import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
-import { AgentDecisionError, AgentRunStateError } from "./contracts.js";
-import { pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
+import { AgentRunStateError } from "./contracts.js";
+import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
@@ -82,6 +82,10 @@ export async function* resumeAgentRunStream(agent, ref, resume, options) {
 }
 async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     throwIfAbortedSignal(signal);
+    // Plan 020 Task 2: one shared shape assertion before any checkpoint read/write, agent
+    // resolution, subscription, or tool execution. Unknown legacy decisions (e.g. "sideways")
+    // and malformed untyped batches fail closed here instead of falling through to approval.
+    assertValidAgentRunResume(resume);
     const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
     if (state.definitionRevision !== options.definitionRevision ||
         state.agentId !== (agent.config.id ?? agent.config.name) ||
@@ -102,9 +106,6 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {
         session.restoreLoadedSkillBodies(state.sessionState.loadedSkillBodies);
     }
-    if (resume.decision !== undefined && resume.decisions !== undefined) {
-        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume accepts exactly one of decision or decisions");
-    }
     const pendingDecisions = pendingDecisionsOf(state);
     // Legacy approve maps to allow-once on every pending decision; legacy deny keeps its
     // terminal-denied behavior. Batch decisions are validated and applied atomically below.
@@ -118,9 +119,6 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
                 signal,
             })
             : undefined;
-    if (resume.decision === undefined && resume.decisions === undefined) {
-        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume requires a decision or decisions");
-    }
     if (resolved && resolved.remaining.length > 0) {
         throwIfAbortedSignal(signal);
         const single = resolved.remaining.length === 1 ? resolved.remaining[0] : undefined;

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/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";
@@ -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.1.7";
+export declare const version = "0.2.1";
 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";
@@ -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.1.7";
+export const version = "0.2.1";
 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

package/dist/pinned-fetch.d.ts

@@ -0,0 +1,25 @@
+import { type MediaHostAddress, type MediaHostnameResolver, type SsrfPolicy } from "./content.js";
+export interface PinnedFetchOptions {
+    /** Prefix for request-level error messages ("redirects are not allowed", "response exceeds", ...). Default "Request". */
+    readonly errorPrefix?: string;
+    /** Prefix for hostname-resolution error messages. Default: `errorPrefix`. */
+    readonly hostnameErrorPrefix?: string;
+    /** Custom resolver; defaults to `node:dns/promises` lookup (all answers, verbatim). */
+    readonly resolver?: MediaHostnameResolver;
+    /** Allow loopback destinations only when the requested hostname is itself loopback AND this is true. */
+    readonly allowLoopback?: boolean;
+    /** SSRF policy applied to the URL precheck and to every resolved candidate. */
+    readonly ssrf?: SsrfPolicy;
+    /** Byte ceiling for the response stream (content-length precheck + streaming bound). */
+    readonly maxResponseBytes?: number;
+}
+/** One DNS-pinned, redirect-free, byte-bounded fetch. See module comment. */
+export declare function pinnedFetch(url: URL, init: RequestInit | undefined, options?: PinnedFetchOptions): Promise<Response>;
+export declare function resolvePinnedAddress(url: URL, resolver: MediaHostnameResolver, signal: AbortSignal | null | undefined, allowLoopback: boolean, ssrf: SsrfPolicy | undefined, hostnameErrorPrefix?: string): Promise<MediaHostAddress>;
+export declare function defaultResolver(hostname: string): Promise<readonly MediaHostAddress[]>;
+export declare function requestPinned(url: URL, address: MediaHostAddress, init: RequestInit | undefined, errorPrefix?: string): Promise<Response>;
+export declare function boundResponse(response: Response, maxBytes: number, errorPrefix?: string): Response;
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | null | undefined): Promise<T>;
+export declare function normalizeHostname(value: string): string;
+export declare function isLoopbackHostname(value: string): boolean;
+export declare function isLoopbackAddress(value: string): boolean;