@arnilo/prism 0.0.96 → 0.1.1

package/dist/persistence-lifecycle.d.ts

@@ -0,0 +1,103 @@
+import type { OwnershipScope, PersistencePage, PersistenceQuery, RetentionPolicy } from "./contracts.js";
+/** Resource classes covered by holds, quotas, and retention sweeps. */
+export type PersistenceResourceKind = "session" | "entry" | "run" | "event" | "tool_call" | "usage" | "checkpoint" | "feedback" | "audit" | "work_artifact" | "connector_operation";
+export declare const DEFAULT_LIFECYCLE_PAGE_SIZE = 100;
+export declare const HARD_LIFECYCLE_PAGE_SIZE = 500;
+export declare const DEFAULT_MAX_HOLD_REASON_BYTES = 1024;
+export declare const HARD_MAX_HOLD_REASON_BYTES: number;
+export declare class PersistenceLifecycleError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export interface LegalHoldRecord extends OwnershipScope {
+    readonly id: string;
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface PutLegalHoldInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly id?: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+export interface ReleaseLegalHoldInput extends OwnershipScope {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+export interface LegalHoldQuery extends PersistenceQuery, OwnershipScope {
+    readonly resourceKind?: PersistenceResourceKind;
+    readonly resourceId?: string;
+    readonly holdId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ApplyRetentionInput extends OwnershipScope {
+    readonly policy: RetentionPolicy;
+    /** When omitted, adapters discover expired/over-limit session ids for this ownership page. */
+    readonly candidates?: readonly string[];
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ApplyRetentionResult {
+    readonly deleted: readonly string[];
+    readonly skippedHeld: readonly string[];
+    readonly nextCursor?: string;
+}
+export interface LegalHoldExportItem {
+    readonly holdId: string;
+    readonly resourceKind: PersistenceResourceKind;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly createdAt: string;
+    readonly redacted: true;
+}
+export interface ExportUnderHoldInput extends OwnershipScope {
+    readonly holdId?: string;
+    readonly resourceKind?: PersistenceResourceKind;
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+export interface TenantQuota extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly limit: number;
+    readonly used: number;
+    readonly updatedAt: string;
+}
+export interface SetTenantQuotaInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    readonly limit: number;
+    readonly signal?: AbortSignal;
+}
+export interface ConsumeTenantQuotaInput extends OwnershipScope {
+    readonly resourceKind: PersistenceResourceKind;
+    /** Units to consume. Default 1. */
+    readonly delta?: number;
+    readonly signal?: AbortSignal;
+}
+/** Optional persistence lifecycle capability (retention / hold / export / quota). */
+export interface PersistenceLifecycleStore {
+    putLegalHold(input: PutLegalHoldInput): Promise<LegalHoldRecord>;
+    releaseLegalHold(input: ReleaseLegalHoldInput): Promise<boolean>;
+    listLegalHolds(query: LegalHoldQuery): Promise<PersistencePage<LegalHoldRecord>>;
+    /** Deletes candidates not under legal hold. Hold always wins over retention. */
+    applyRetention(input: ApplyRetentionInput): Promise<ApplyRetentionResult>;
+    exportUnderHold(input: ExportUnderHoldInput): Promise<PersistencePage<LegalHoldExportItem>>;
+    setTenantQuota(input: SetTenantQuotaInput): Promise<TenantQuota>;
+    getTenantQuota(input: OwnershipScope & {
+        readonly resourceKind: PersistenceResourceKind;
+        readonly signal?: AbortSignal;
+    }): Promise<TenantQuota | null>;
+    /** Fails closed when used + delta would exceed limit. */
+    consumeTenantQuota(input: ConsumeTenantQuotaInput): Promise<TenantQuota>;
+}
+export declare function createMemoryPersistenceLifecycle(): PersistenceLifecycleStore;
+/** True when a session/resource id is under an active legal hold in the page of holds. */
+export declare function isResourceHeld(holds: readonly Pick<LegalHoldRecord, "resourceKind" | "resourceId">[], resourceKind: PersistenceResourceKind, resourceId: string): boolean;

package/dist/persistence-lifecycle.js

@@ -0,0 +1,202 @@
+export const DEFAULT_LIFECYCLE_PAGE_SIZE = 100;
+export const HARD_LIFECYCLE_PAGE_SIZE = 500;
+export const DEFAULT_MAX_HOLD_REASON_BYTES = 1024;
+export const HARD_MAX_HOLD_REASON_BYTES = 8 * 1024;
+export class PersistenceLifecycleError extends Error {
+    code;
+    constructor(message, code = "ERR_PRISM_PERSISTENCE_LIFECYCLE") {
+        super(message);
+        this.code = code;
+        this.name = "PersistenceLifecycleError";
+    }
+}
+export function createMemoryPersistenceLifecycle() {
+    const holds = new Map();
+    const quotas = new Map();
+    const deleted = new Set();
+    return {
+        async putLegalHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const reason = assertReason(input.reason);
+            if (!input.resourceId || !input.resourceKind) {
+                throw new PersistenceLifecycleError("resourceKind and resourceId are required", "ERR_PRISM_LIFECYCLE_HOLD");
+            }
+            const id = input.id ?? crypto.randomUUID();
+            const record = {
+                id,
+                resourceKind: input.resourceKind,
+                resourceId: input.resourceId,
+                reason,
+                createdAt: new Date().toISOString(),
+                ...(input.createdBy === undefined ? {} : { createdBy: input.createdBy }),
+                ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+                ...ownership(input),
+            };
+            holds.set(id, record);
+            return record;
+        },
+        async releaseLegalHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const current = holds.get(input.id);
+            if (!current)
+                return false;
+            assertSameOwnership(input, current);
+            holds.delete(input.id);
+            return true;
+        },
+        async listLegalHolds(query) {
+            throwIfAborted(query.signal);
+            assertOwnership(query);
+            const limit = pageLimit(query.limit);
+            const items = [...holds.values()]
+                .filter((hold) => sameOwnership(query, hold))
+                .filter((hold) => query.holdId === undefined || hold.id === query.holdId)
+                .filter((hold) => query.resourceKind === undefined || hold.resourceKind === query.resourceKind)
+                .filter((hold) => query.resourceId === undefined || hold.resourceId === query.resourceId)
+                .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+            const start = query.cursor ? items.findIndex((item) => item.id === query.cursor) + 1 : 0;
+            const slice = items.slice(Math.max(0, start), Math.max(0, start) + limit);
+            const next = start + limit < items.length ? slice.at(-1)?.id : undefined;
+            return { items: slice, ...(next === undefined ? {} : { nextCursor: next }) };
+        },
+        async applyRetention(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const held = new Set([...holds.values()].filter((hold) => sameOwnership(input, hold) && hold.resourceKind === "session").map((hold) => hold.resourceId));
+            const candidates = input.candidates ?? [];
+            const deletedIds = [];
+            const skippedHeld = [];
+            for (const id of candidates) {
+                if (held.has(id)) {
+                    skippedHeld.push(id);
+                    continue;
+                }
+                deleted.add(id);
+                deletedIds.push(id);
+            }
+            return { deleted: deletedIds, skippedHeld };
+        },
+        async exportUnderHold(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const page = await this.listLegalHolds({
+                ...ownership(input),
+                holdId: input.holdId,
+                resourceKind: input.resourceKind,
+                cursor: input.cursor,
+                limit: input.limit,
+                signal: input.signal,
+            });
+            return {
+                items: page.items.map((hold) => ({
+                    holdId: hold.id,
+                    resourceKind: hold.resourceKind,
+                    resourceId: hold.resourceId,
+                    reason: hold.reason,
+                    createdAt: hold.createdAt,
+                    redacted: true,
+                })),
+                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+            };
+        },
+        async setTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            if (!Number.isSafeInteger(input.limit) || input.limit < 0) {
+                throw new PersistenceLifecycleError("limit must be a non-negative safe integer", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            const key = quotaKey(input, input.resourceKind);
+            const previous = quotas.get(key);
+            const record = {
+                ...ownership(input),
+                resourceKind: input.resourceKind,
+                limit: input.limit,
+                used: previous?.used ?? 0,
+                updatedAt: new Date().toISOString(),
+            };
+            if (record.used > record.limit) {
+                throw new PersistenceLifecycleError("quota already exceeded", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            quotas.set(key, record);
+            return record;
+        },
+        async getTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            return quotas.get(quotaKey(input, input.resourceKind)) ?? null;
+        },
+        async consumeTenantQuota(input) {
+            throwIfAborted(input.signal);
+            assertOwnership(input);
+            const delta = input.delta ?? 1;
+            if (!Number.isSafeInteger(delta) || delta < 1) {
+                throw new PersistenceLifecycleError("delta must be a positive safe integer", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            const key = quotaKey(input, input.resourceKind);
+            const current = quotas.get(key);
+            if (!current) {
+                throw new PersistenceLifecycleError("tenant quota not configured", "ERR_PRISM_LIFECYCLE_QUOTA");
+            }
+            if (current.used + delta > current.limit) {
+                throw new PersistenceLifecycleError(`tenant quota exhausted for ${input.resourceKind}`, "ERR_PRISM_LIFECYCLE_QUOTA_EXHAUSTED");
+            }
+            const next = {
+                ...current,
+                used: current.used + delta,
+                updatedAt: new Date().toISOString(),
+            };
+            quotas.set(key, next);
+            return next;
+        },
+    };
+}
+/** True when a session/resource id is under an active legal hold in the page of holds. */
+export function isResourceHeld(holds, resourceKind, resourceId) {
+    return holds.some((hold) => hold.resourceKind === resourceKind && hold.resourceId === resourceId);
+}
+function ownership(input) {
+    return {
+        ...(input.tenantId === undefined ? {} : { tenantId: input.tenantId }),
+        ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+    };
+}
+function sameOwnership(a, b) {
+    return a.tenantId === b.tenantId && a.accountId === b.accountId && a.userId === b.userId;
+}
+function assertSameOwnership(expected, actual) {
+    if (!sameOwnership(expected, actual)) {
+        throw new PersistenceLifecycleError("ownership mismatch", "ERR_PRISM_LIFECYCLE_OWNERSHIP");
+    }
+}
+function assertOwnership(input) {
+    if (![input.tenantId, input.accountId, input.userId].some((value) => typeof value === "string" && value.length > 0)) {
+        throw new PersistenceLifecycleError("ownership required", "ERR_PRISM_LIFECYCLE_OWNERSHIP");
+    }
+}
+function assertReason(reason) {
+    if (typeof reason !== "string" || !reason.trim()) {
+        throw new PersistenceLifecycleError("reason is required", "ERR_PRISM_LIFECYCLE_HOLD");
+    }
+    if (Buffer.byteLength(reason, "utf8") > HARD_MAX_HOLD_REASON_BYTES) {
+        throw new PersistenceLifecycleError("reason exceeds limit", "ERR_PRISM_LIFECYCLE_HOLD");
+    }
+    return reason;
+}
+function pageLimit(limit) {
+    const resolved = limit ?? DEFAULT_LIFECYCLE_PAGE_SIZE;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > HARD_LIFECYCLE_PAGE_SIZE) {
+        throw new PersistenceLifecycleError(`limit must be 1..${HARD_LIFECYCLE_PAGE_SIZE}`, "ERR_PRISM_LIFECYCLE_LIMITS");
+    }
+    return resolved;
+}
+function quotaKey(ownership, kind) {
+    return `${ownership.tenantId ?? ""}\0${ownership.accountId ?? ""}\0${ownership.userId ?? ""}\0${kind}`;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//# sourceMappingURL=persistence-lifecycle.js.map

package/dist/provider-events.d.ts

@@ -10,6 +10,7 @@ export declare function providerToolCallDelta(delta: {
     readonly argumentsText?: string;
 }): ProviderEvent;
 export declare function providerToolCallDeltaContent(delta: Omit<ToolCallDeltaContent, "type">): ToolCallDeltaContent;
+export declare function providerContinuationRequired(cursor: string, reason?: string): ProviderEvent;
 export declare function reconstructToolCallDeltas(events: readonly ProviderEvent[]): readonly ToolCallContent[];
 export declare function providerUsage(usage: Usage): ProviderEvent;
 export declare function providerDone(usage?: Usage): ProviderEvent;

package/dist/provider-events.js

@@ -18,6 +18,9 @@ export function providerToolCallDelta(delta) {
 export function providerToolCallDeltaContent(delta) {
     return { type: "tool_call_delta", ...delta };
 }
+export function providerContinuationRequired(cursor, reason) {
+    return { type: "continuation_required", cursor, reason };
+}
 export function reconstructToolCallDeltas(events) {
     const partials = new Map();
     for (const event of events) {
@@ -32,7 +35,9 @@ export function reconstructToolCallDeltas(events) {
             partial.argumentsText += event.argumentsText;
         partials.set(event.index, partial);
     }
-    return [...partials.entries()].sort(([a], [b]) => a - b).map(([index, partial]) => {
+    return [...partials.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([index, partial]) => {
         if (!partial.id || !partial.name) {
             throw new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${index}`);
         }

package/dist/provider-request-policy.js

@@ -50,10 +50,9 @@ export function mergeProviderRequestOptions(base, patch) {
         cache: {
             ...base.cache,
             ...patch.cache,
-            breakpoints: base.cache?.breakpoints || patch.cache?.breakpoints ? [
-                ...(base.cache?.breakpoints ?? []),
-                ...(patch.cache?.breakpoints ?? []),
-            ] : undefined,
+            breakpoints: base.cache?.breakpoints || patch.cache?.breakpoints
+                ? [...(base.cache?.breakpoints ?? []), ...(patch.cache?.breakpoints ?? [])]
+                : undefined,
         },
     };
 }

package/dist/providers/media.d.ts

@@ -1,5 +1,5 @@
+import { type MediaContentBlock, type ModelInputCapability, type ResolvedMediaContent, type ResolveMediaContentOptions } from "../content.js";
 import type { AudioContent, ContentBlock, DocumentContent, FileContent, JsonObject, Message, ModelCapabilities, ModelConfig } from "../contracts.js";
-import { type MediaContentBlock, type ModelInputCapability, type ResolveMediaContentOptions, type ResolvedMediaContent } from "../content.js";
 /** Default upload-cache entry cap per provider media session. */
 export declare const DEFAULT_PROVIDER_UPLOAD_CACHE_ENTRIES = 32;
 /** Inline OpenAI file_data ceiling before preferring Files API upload. */

package/dist/providers/openai-compatible.d.ts

@@ -1,9 +1,54 @@
-import type { AIProvider } from "../contracts.js";
+import type { AIProvider, JsonObject, Message, ProviderEvent, ProviderRequest, Usage } from "../contracts.js";
 import { type CredentialValueSource } from "../credentials.js";
 export interface OpenAICompatibleProviderOptions {
     readonly id?: string;
     readonly baseUrl: string;
     readonly apiKey?: CredentialValueSource;
     readonly fetch?: typeof fetch;
+    /** Override chat-completions URL (default `${baseUrl}/chat/completions`). */
+    readonly chatCompletionsUrl?: string | ((request: ProviderRequest) => string);
+    /** Default `bearer`. Azure resource keys use `api-key`; host-signed fetches may use `none`. */
+    readonly authStyle?: "bearer" | "api-key" | "none";
+    /** Extra provider-specific body fields (thinking/reasoning/cache); merged over the base body. */
+    readonly buildBodyExtra?: (request: ProviderRequest) => JsonObject | undefined;
+    /** Transform messages before serialization (e.g. cache-control markers). Defaults to `request.messages`. */
+    readonly mapMessages?: (request: ProviderRequest) => readonly Message[];
+    /** Custom message serializer (e.g. Z.AI `reasoning_content` replay). Defaults to assert + `serializeOpenAIChatMessage`. */
+    readonly serializeMessage?: (message: Message, request: ProviderRequest) => JsonObject;
+    /** Custom usage mapping (e.g. OpenRouter cost fields). Defaults to `mapOpenAIChatUsage`. */
+    readonly mapUsage?: (usage: unknown) => Usage | undefined;
+    /** Extra request headers (merged over caller headers; provider auth/content-type still win). */
+    readonly extraHeaders?: (request: ProviderRequest) => Record<string, string>;
+    /** Final body transform applied last (token limits, compat stripping). Wins over everything. */
+    readonly transformBody?: (body: JsonObject, request: ProviderRequest) => JsonObject;
+    /** Require `[DONE]` and a `finish_reason` before emitting `done`; truncated streams yield an error. `done` then carries the final usage. */
+    readonly strictCompletion?: boolean;
+    /** Emit the final stream usage on the `done` event (without strict completion checks). */
+    readonly doneUsage?: boolean;
+    /** Prefix for HTTP error messages (default `OpenAI-compatible request failed`). */
+    readonly requestFailedPrefix?: string;
+    /** Custom HTTP error mapping (e.g. NeuralWatt retry classification). Receives the response and redacted body text. */
+    readonly mapHttpError?: (response: Response, bodyText: string, secrets: readonly (string | undefined)[]) => Error;
+    /** Handle SSE comment lines in the stream (e.g. NeuralWatt energy/cost telemetry). */
+    readonly onComment?: (text: string) => ProviderEvent | undefined;
 }
+export interface OpenAIChatEventsOptions {
+    readonly signal?: AbortSignal;
+    /** Require `[DONE]` and a `finish_reason`; `done` then carries the final usage. */
+    readonly strictCompletion?: boolean;
+    /** Emit the final stream usage on the `done` event. */
+    readonly doneUsage?: boolean;
+    readonly mapUsage?: (usage: unknown) => Usage | undefined;
+    /** Handle an SSE comment line (text after `:`), e.g. NeuralWatt `: energy` / `: cost` telemetry. Returned events are yielded in stream order before the data of the same SSE event. */
+    readonly onComment?: (text: string) => ProviderEvent | undefined;
+}
+/**
+ * Shared OpenAI Chat Completions SSE stream loop: maps `data:` frames to Prism
+ * `ProviderEvent` values (text/thinking deltas, tool-call fragments, usage, done/error).
+ */
+export declare function openAIChatEvents(body: ReadableStream<Uint8Array>, options?: OpenAIChatEventsOptions): AsyncIterable<ProviderEvent>;
 export declare function createOpenAICompatibleProvider(options: OpenAICompatibleProviderOptions): AIProvider;
+/** Subset of factory options that shape the request body. */
+export type OpenAIChatBodyOptions = Pick<OpenAICompatibleProviderOptions, "mapMessages" | "serializeMessage" | "buildBodyExtra" | "transformBody">;
+/** Base Chat Completions request body builder, exported for provider packages keeping public body helpers. */
+export declare function buildOpenAIChatBody(request: ProviderRequest, options?: OpenAIChatBodyOptions): JsonObject;

package/dist/providers/openai-compatible.js

@@ -1,78 +1,141 @@
 import { resolveCredentialValue } from "../credentials.js";
 import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
-import { assertOpenAIChatMessage, applyOpenAIChatStructuredOutput, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
-import { ProviderTransportError, readBoundedResponseText, readSseData, } from "./transport.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
+import { applyOpenAIChatStructuredOutput, assertOpenAIChatMessage, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
+import { httpStatusError, ProviderTransportError, readBoundedResponseText, readSseEvents } from "./transport.js";
+/**
+ * Shared OpenAI Chat Completions SSE stream loop: maps `data:` frames to Prism
+ * `ProviderEvent` values (text/thinking deltas, tool-call fragments, usage, done/error).
+ */
+export async function* openAIChatEvents(body, options = {}) {
+    const tools = new Map();
+    let usage;
+    let sawDoneMarker = false;
+    let sawFinishReason = false;
+    for await (const sseEvent of readSseEvents(body, { signal: options.signal })) {
+        if (options.onComment && sseEvent.comments?.length) {
+            for (const text of sseEvent.comments) {
+                const commentEvent = options.onComment(text);
+                if (commentEvent)
+                    yield commentEvent;
+            }
+        }
+        const data = sseEvent.data.trim();
+        if (!data)
+            continue;
+        if (data === "[DONE]") {
+            sawDoneMarker = true;
+            break;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch (error) {
+            // Malformed chunks are terminal: yield the error instead of crashing the generator.
+            yield providerError(error, []);
+            return;
+        }
+        const mapped = (options.mapUsage ?? mapOpenAIChatUsage)(parsed.usage);
+        if (mapped) {
+            usage = mapped;
+            yield providerUsage(mapped);
+        }
+        for (const choice of parsed.choices ?? []) {
+            if (choice.finish_reason)
+                sawFinishReason = true;
+            const delta = choice.delta ?? {};
+            if (typeof delta.content === "string" && delta.content)
+                yield providerTextDelta(delta.content);
+            const thinking = delta.reasoning ?? delta.reasoning_content;
+            if (typeof thinking === "string" && thinking) {
+                yield providerThinkingDelta(thinking);
+            }
+            for (const tool of delta.tool_calls ?? []) {
+                const index = tool.index ?? 0;
+                const current = tools.get(index) ?? { argumentsText: "" };
+                current.id = tool.id ?? current.id;
+                current.name = tool.function?.name ?? current.name;
+                current.argumentsText += tool.function?.arguments ?? "";
+                tools.set(index, current);
+                yield providerToolCallDelta({
+                    index,
+                    id: tool.id,
+                    name: tool.function?.name,
+                    argumentsText: tool.function?.arguments,
+                });
+            }
+        }
+    }
+    const incomplete = [...tools.entries()].find(([, call]) => !call.id || !call.name);
+    if (incomplete) {
+        yield providerError(new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${incomplete[0]}`));
+        return;
+    }
+    if (options.strictCompletion && (!sawDoneMarker || !sawFinishReason)) {
+        // Truncated streams must fail loudly — emitting done would mark partial output as succeeded.
+        yield providerError(new Error(`Chat stream ended without completion evidence ` +
+            `([DONE]: ${sawDoneMarker ? "received" : "missing"}, ` +
+            `finish_reason: ${sawFinishReason ? "received" : "missing"})`));
+        return;
+    }
+    for (const call of tools.values()) {
+        yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
+    }
+    yield providerDone(options.strictCompletion || options.doneUsage ? usage : undefined);
+}
 export function createOpenAICompatibleProvider(options) {
     const providerId = options.id ?? "openai-compatible";
     return {
         id: providerId,
         async *generate(request) {
+            if (request.signal?.aborted)
+                throw request.signal.reason ?? new Error("aborted");
             const apiKey = await resolveCredentialValue(options.apiKey, {
                 name: "apiKey",
                 provider: providerId,
             });
             const fetchImpl = options.fetch ?? fetch;
             const secrets = [apiKey];
-            const tools = new Map();
             try {
-                const response = await fetchImpl(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                const url = typeof options.chatCompletionsUrl === "function"
+                    ? options.chatCompletionsUrl(request)
+                    : (options.chatCompletionsUrl ?? `${options.baseUrl.replace(/\/+$/, "")}/chat/completions`);
+                const authStyle = options.authStyle ?? "bearer";
+                const headers = {
+                    ...Object.fromEntries(Object.entries(request.options?.headers ?? {}).filter((entry) => typeof entry[1] === "string")),
+                    ...options.extraHeaders?.(request),
+                    "content-type": "application/json",
+                };
+                if (apiKey && authStyle === "api-key")
+                    headers["api-key"] = apiKey;
+                if (apiKey && authStyle === "bearer")
+                    headers.authorization = `Bearer ${apiKey}`;
+                const response = await fetchImpl(url, {
                     method: "POST",
-                    headers: {
-                        ...request.options?.headers,
-                        "content-type": "application/json",
-                        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
-                    },
-                    body: JSON.stringify(toOpenAIRequest(request)),
+                    headers,
+                    body: JSON.stringify(toOpenAIRequest(request, options)),
                     signal: request.signal,
                 });
                 if (!response.ok) {
-                    yield providerError(new Error(`OpenAI-compatible request failed: ${response.status} ${await readBoundedResponseText(response, { secrets })}`), secrets);
+                    const bodyText = await readBoundedResponseText(response, { secrets });
+                    const error = options.mapHttpError
+                        ? options.mapHttpError(response, bodyText, secrets)
+                        : httpStatusError(options.requestFailedPrefix ?? "OpenAI-compatible request failed", response, bodyText);
+                    yield providerError(error, secrets);
                     return;
                 }
                 if (!response.body) {
                     yield providerError(new Error("OpenAI-compatible response had no body"), secrets);
                     return;
                 }
-                for await (const data of readSseData(response.body, { signal: request.signal })) {
-                    if (data === "[DONE]")
-                        break;
-                    const parsed = JSON.parse(data);
-                    const usage = mapOpenAIChatUsage(parsed.usage);
-                    if (usage)
-                        yield providerUsage(usage);
-                    for (const choice of parsed.choices ?? []) {
-                        const delta = choice.delta ?? {};
-                        if (typeof delta.content === "string" && delta.content)
-                            yield providerTextDelta(delta.content);
-                        if (typeof delta.reasoning_content === "string" && delta.reasoning_content) {
-                            yield providerThinkingDelta(delta.reasoning_content);
-                        }
-                        for (const tool of delta.tool_calls ?? []) {
-                            const index = tool.index ?? 0;
-                            const current = tools.get(index) ?? { argumentsText: "" };
-                            current.id = tool.id ?? current.id;
-                            current.name = tool.function?.name ?? current.name;
-                            current.argumentsText += tool.function?.arguments ?? "";
-                            tools.set(index, current);
-                            yield providerToolCallDelta({
-                                index,
-                                id: tool.id,
-                                name: tool.function?.name,
-                                argumentsText: tool.function?.arguments,
-                            });
-                        }
-                    }
-                }
-                const incomplete = [...tools.entries()].find(([, call]) => !call.id || !call.name);
-                if (incomplete) {
-                    yield providerError(new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${incomplete[0]}`), secrets);
-                    return;
-                }
-                for (const call of tools.values()) {
-                    yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
-                }
-                yield providerDone();
+                yield* openAIChatEvents(response.body, {
+                    signal: request.signal,
+                    strictCompletion: options.strictCompletion,
+                    doneUsage: options.doneUsage,
+                    mapUsage: options.mapUsage,
+                    onComment: options.onComment,
+                });
             }
             catch (error) {
                 yield providerError(error, secrets);
@@ -80,11 +143,13 @@ export function createOpenAICompatibleProvider(options) {
         },
     };
 }
-function toOpenAIRequest(request) {
+function toOpenAIRequest(request, options) {
     assertStructuredOutputRequestSupported(request.model, request.options);
     const body = {
         model: request.model.model,
-        messages: request.messages.map((message, index) => {
+        messages: (options.mapMessages?.(request) ?? request.messages).map((message, index) => {
+            if (options.serializeMessage)
+                return options.serializeMessage(message, request);
             assertOpenAIChatMessage(message, `messages[${index}]`);
             return serializeOpenAIChatMessage(message, request.model.capabilities ?? {});
         }),
@@ -94,6 +159,11 @@ function toOpenAIRequest(request) {
         ...request.model.parameters,
     };
     applyOpenAIChatStructuredOutput(body, request.options?.structuredOutput);
-    return body;
+    const merged = { ...body, ...options.buildBodyExtra?.(request) };
+    return options.transformBody ? options.transformBody(merged, request) : merged;
+}
+/** Base Chat Completions request body builder, exported for provider packages keeping public body helpers. */
+export function buildOpenAIChatBody(request, options = {}) {
+    return toOpenAIRequest(request, options);
 }
 //# sourceMappingURL=openai-compatible.js.map