@arnilo/prism 0.0.16 → 0.0.18

package/dist/extensions.js

@@ -45,90 +45,148 @@ export function createExtensionKernel(options = {}) {
     const middleware = options.middleware ?? createMiddlewareRegistry({ ...options, onError: events.emit });
     const errorPolicy = options.errorPolicy ?? "event";
     const secrets = options.secrets ?? [];
-    const api = {
+    // Per-extension tracked API: every registration records an undo so a dispose handle
+    // (or a failed setup) can unwind exactly what that extension added.
+    const createApi = (track) => ({
         registries,
         middleware,
-        on: events.on,
+        on(type, handler) {
+            const off = events.on(type, handler);
+            track?.(off);
+            return off;
+        },
         emit: events.emit,
-        use: middleware.use,
+        use(hook, mw) {
+            const off = middleware.use(hook, mw);
+            track?.(off);
+            return off;
+        },
         registerProvider(provider) {
             registries.providers.register(provider);
+            track?.(() => registries.providers.unregister(provider.id));
         },
         registerModel(model) {
             registries.models.register(model);
+            track?.(() => registries.models.unregister(model.provider, model.model));
         },
         registerTool(tool) {
             registries.tools.register(tool.name, tool);
+            track?.(() => registries.tools.unregister(tool.name));
         },
         registerContextProvider(provider) {
             registries.contextProviders.register(provider.name, provider);
+            track?.(() => registries.contextProviders.unregister(provider.name));
         },
         registerSkill(skill) {
             registries.skills.register(skill.name, skill);
+            track?.(() => registries.skills.unregister(skill.name));
         },
         registerCommand(command) {
             registries.commands.register(command.name, command);
+            track?.(() => registries.commands.unregister(command.name));
         },
         registerAgent(agent) {
             registries.agents.register(agent.name, agent);
+            track?.(() => registries.agents.unregister(agent.name));
         },
         registerInputBuilder(builder) {
             registries.inputBuilders.register(builder.name, builder);
+            track?.(() => registries.inputBuilders.unregister(builder.name));
         },
         registerPromptBuilder(builder) {
             registries.promptBuilders.register(builder.name, builder);
+            track?.(() => registries.promptBuilders.unregister(builder.name));
         },
         registerCompactionStrategy(strategy) {
             registries.compactionStrategies.register(strategy.name, strategy);
+            track?.(() => registries.compactionStrategies.unregister(strategy.name));
         },
         registerRetryPolicy(policy) {
             registries.retryPolicies.register(policy.name, policy);
+            track?.(() => registries.retryPolicies.unregister(policy.name));
         },
         registerStoreFactory(factory) {
             registries.storeFactories.register(factory.name, factory);
+            track?.(() => registries.storeFactories.unregister(factory.name));
         },
         registerResourceLoader(key, loader) {
             registries.resourceLoaders.register(key, loader);
+            track?.(() => registries.resourceLoaders.unregister(key));
         },
         registerSettingsProvider(key, provider) {
             registries.settingsProviders.register(key, provider);
+            track?.(() => registries.settingsProviders.unregister(key));
         },
         registerCredentialResolver(key, resolver) {
             registries.credentialResolvers.register(key, resolver);
+            track?.(() => registries.credentialResolvers.unregister(key));
         },
         registerProviderPackage(providerPackage) {
             registries.providerPackages.register(providerPackage.name, providerPackage);
+            track?.(() => registries.providerPackages.unregister(providerPackage.name));
         },
         registerAuthMethod(method) {
-            registries.authMethods.register(authMethodKey(method), method);
+            const key = authMethodKey(method);
+            registries.authMethods.register(key, method);
+            track?.(() => registries.authMethods.unregister(key));
         },
         registerProviderRequestPolicy(policy) {
             registries.providerRequestPolicies.register(policy.name, policy);
+            track?.(() => registries.providerRequestPolicies.unregister(policy.name));
         },
         registerSystemPromptContribution(contribution) {
-            registries.systemPromptContributions.register(systemPromptContributionKey(contribution), contribution);
+            const key = systemPromptContributionKey(contribution);
+            registries.systemPromptContributions.register(key, contribution);
+            track?.(() => registries.systemPromptContributions.unregister(key));
         },
         registerInstructionInjector(injector) {
             registries.instructionInjectors.register(injector.name, injector);
+            track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+    });
+    const unwind = (undo) => {
+        for (const fn of undo.reverse()) {
+            try {
+                fn();
+            }
+            catch {
+                // best-effort: one stuck undo must not block the rest
+            }
+        }
     };
     return {
         registries,
         middleware,
         events,
         async load(extensions) {
+            const loaded = [];
             for (const extension of extensions) {
+                const undo = [];
                 try {
                     await assertPermission(options.permission, { kind: "extension", action: "setup", target: extension.name });
                     await assertExtensionLoadPolicy(options.loadPolicy, extension);
-                    await extension.setup(api);
+                    await extension.setup(createApi((fn) => undo.push(fn)));
                 }
                 catch (error) {
+                    // A failed setup must not leave partial contributions behind.
+                    unwind(undo);
                     if (errorPolicy === "throw")
                         throw error;
                     await events.emit(extensionError(error, extension.name, secrets));
+                    continue;
                 }
+                let disposed = false;
+                loaded.push({
+                    name: extension.name,
+                    dispose() {
+                        if (disposed)
+                            return;
+                        disposed = true;
+                        unwind(undo);
+                    },
+                });
             }
+            return loaded;
         },
     };
 }

package/dist/feedback.js

@@ -216,7 +216,7 @@ function freezeRecord(record) {
     });
 }
 function cloneFrozenJsonObject(value) {
-    const cloned = JSON.parse(JSON.stringify(value));
+    const cloned = structuredClone(value);
     if (!cloned || typeof cloned !== "object" || Array.isArray(cloned))
         throw new RunFeedbackError("metadata must be a JSON object");
     return deepFreeze(cloned);

package/dist/guardrails.js

@@ -5,7 +5,9 @@ export class GuardrailError extends Error {
     code;
     record;
     constructor(record) {
-        super(record.action === "interrupt" ? "Guardrail interruption is unavailable" : "Guardrail blocked run");
+        super(record.action === "interrupt"
+            ? `Guardrail interruption is unavailable at stage "${record.stage}"; interrupt suspends only at the input stage of durable runs`
+            : "Guardrail blocked run");
         this.name = "GuardrailError";
         this.code = record.action === "interrupt" ? "ERR_PRISM_GUARDRAIL_INTERRUPT_UNAVAILABLE" : "ERR_PRISM_GUARDRAIL_BLOCKED";
         this.record = record;
@@ -88,8 +90,12 @@ async function evaluate(guardrail, options, signal) {
         }
         return record(guardrail.name, options.stage, decision.action, decision.reason, decision.metadata, options.redactor);
     }
-    catch {
-        return record(guardrail.name, options.stage, "tripwire", "guardrail_failed", undefined, options.redactor);
+    catch (error) {
+        // Keep the cause diagnosable without leaking internals: message only, bounded and
+        // passed through the same redact+bound metadata path as guardrail-provided metadata.
+        const message = error instanceof Error ? error.message : String(error);
+        const redacted = options.redactor?.redact(message) ?? message;
+        return record(guardrail.name, options.stage, "tripwire", "guardrail_failed", { error: boundText(redacted, MAX_REASON_BYTES) }, options.redactor);
     }
 }
 function resolveConcurrency(value) {

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, Even
 export { createEventMultiplexer } 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, } from "./extensions.js";
+export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
@@ -94,5 +94,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.0.16";
+export declare const version = "0.0.18";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -51,6 +51,6 @@ export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_L
 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.0.16";
+export const version = "0.0.18";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.js

@@ -9,8 +9,9 @@ export function createDefaultInputBuilder() {
         name: "default-input",
         async build(input, context = {}) {
             const groups = await buildDefaultInputMessageGroups(input, context);
-            const messages = flattenInputGroups(groups, context.inputLayout ?? "legacy");
-            return context.middleware ? context.middleware.run("input_assembly", messages) : messages;
+            // `input_assembly` middleware is applied by assembleProviderInput after build(),
+            // never here: builders must not be a security seam.
+            return flattenInputGroups(groups, context.inputLayout ?? "cache_aware");
         },
     };
 }
@@ -35,7 +36,10 @@ export function createDefaultPromptBuilder() {
     return {
         name: "default-prompt",
         async build(request) {
-            return [...contextMessages(request.context), ...skillMessages(request.skills), ...toolMessages(request.tools), ...request.messages];
+            // Tool-capable models receive schemas via request.tools; the text list only serves
+            // text-only (or unknown-capability) models — duplicating it doubles tool tokens per turn.
+            const tools = request.model?.capabilities?.tools === true ? undefined : request.tools;
+            return [...contextMessages(request.context), ...skillMessages(request.skills), ...toolMessages(tools), ...request.messages];
         },
     };
 }
@@ -76,7 +80,7 @@ export async function assembleProviderInput(options) {
         ? composeSystemPrompt(injectorContribs.instructions, { base: options.systemInstructions })
         : options.systemInstructions;
     const buildContext = { ...options, ...baseContext, systemInstructions };
-    const layout = buildContext.inputLayout ?? "legacy";
+    const layout = buildContext.inputLayout ?? "cache_aware";
     let messages;
     let context;
     let skills = options.skills;
@@ -113,6 +117,9 @@ export async function assembleProviderInput(options) {
     else {
         const inputBuilder = options.inputBuilder ?? createDefaultInputBuilder();
         messages = await inputBuilder.build(options.input, buildContext);
+        // Runtime-owned: input_assembly middleware always runs, regardless of which builder is installed.
+        if (buildContext.middleware)
+            messages = await buildContext.middleware.run("input_assembly", messages);
         context = await resolveContextProviders({
             providers: options.contextProviders,
             messages,
@@ -139,7 +146,7 @@ export async function assembleProviderInput(options) {
             metadata: options.metadata,
             signal: options.signal,
         };
-    const providerMessages = await promptBuilder.build({ ...promptRequest, tools });
+    const providerMessages = await promptBuilder.build({ ...promptRequest, tools, model: options.model });
     assertMessagesSupportModelCapabilities(options.model, providerMessages);
     const metadata = budgetReport ? { ...options.metadata, [CONTEXT_BUDGET_REPORT_METADATA_KEY]: budgetReport } : options.metadata;
     return {

package/dist/middleware.js

@@ -21,10 +21,13 @@ export function createMiddlewareRegistry(options = {}) {
         },
         async run(hook, value) {
             let current = value;
-            for (const middleware of byHook.get(hook) ?? []) {
+            for (const [index, middleware] of (byHook.get(hook) ?? []).entries()) {
                 try {
                     let calledNext = false;
                     const next = async (nextValue) => {
+                        // Double next() forks the chain value nondeterministically — always a bug.
+                        if (calledNext)
+                            throw new Error(`Middleware hook "${hook}" #${index}: next() called more than once`);
                         calledNext = true;
                         current = nextValue;
                         return current;
@@ -32,6 +35,11 @@ export function createMiddlewareRegistry(options = {}) {
                     const result = await middleware(current, next);
                     if (!calledNext)
                         current = result;
+                    else if (result !== undefined && result !== current) {
+                        // next(v) already committed the chain value; a conflicting return is silently
+                        // discarded. Ambiguous rather than certainly-wrong, so diagnose, don't throw.
+                        await options.onError?.(middlewareError(new Error(`Middleware hook "${hook}" #${index}: called next(value) and returned a different value; the next() value wins, the return is discarded`), hook, secrets));
+                    }
                 }
                 catch (error) {
                     if (errorPolicy === "throw")

package/dist/models.d.ts

@@ -2,6 +2,8 @@ import type { ModelConfig } from "./contracts.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
 export interface ModelRegistry {
     register(model: ModelConfig): void;
+    /** Remove a model; returns false when it was not registered. */
+    unregister(provider: string, model: string): boolean;
     get(provider: string, model: string): ModelConfig | undefined;
     resolve(provider: string, model: string): ModelConfig;
     list(): readonly ModelConfig[];

package/dist/models.js

@@ -8,6 +8,9 @@ export function createModelRegistry(models = [], options = {}) {
             assertCanRegister(byId, id, "model", `${model.provider}/${model.model}`, options.duplicate);
             byId.set(id, model);
         },
+        unregister(provider, model) {
+            return byId.delete(key(provider, model));
+        },
         get(provider, model) {
             return byId.get(key(provider, model));
         },

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

@@ -1,4 +1,4 @@
-import type { AIProvider, ProviderRequest } 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;
@@ -9,5 +9,46 @@ export interface OpenAICompatibleProviderOptions {
     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

@@ -2,26 +2,109 @@ import { resolveCredentialValue } from "../credentials.js";
 import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
 import { applyOpenAIChatStructuredOutput, assertOpenAIChatMessage, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
-import { ProviderTransportError, readBoundedResponseText, readSseData } from "./transport.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 url = typeof options.chatCompletionsUrl === "function"
                     ? options.chatCompletionsUrl(request)
-                    : (options.chatCompletionsUrl ?? `${options.baseUrl.replace(/\/$/, "")}/chat/completions`);
+                    : (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")
@@ -31,56 +114,28 @@ export function createOpenAICompatibleProvider(options) {
                 const response = await fetchImpl(url, {
                     method: "POST",
                     headers,
-                    body: JSON.stringify(toOpenAIRequest(request)),
+                    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);
@@ -88,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 ?? {});
         }),
@@ -102,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

package/dist/providers/transport.d.ts

@@ -20,6 +20,12 @@ export declare class ProviderTransportError extends Error {
     readonly limitBytes?: number;
     constructor(code: ProviderTransportErrorCode, message: string, limitBytes?: number);
 }
+/** HTTP failure error carrying the status as numeric `code` plus any `Retry-After`
+ *  hint as `retryAfterMs`, so retry policies classify transience and pace retries
+ *  without parsing message text. Both fields flow into `ErrorInfo` via errorToErrorInfo. */
+export declare function httpStatusError(prefix: string, response: Response, bodyText: string): Error;
+/** Parse a `Retry-After` header (delay-seconds or HTTP-date) into milliseconds. */
+export declare function parseRetryAfterMs(value: string | null, now?: number): number | undefined;
 export interface ReadSseEventsOptions extends BoundedStreamLimits {
     readonly signal?: AbortSignal;
 }

package/dist/providers/transport.js

@@ -13,6 +13,27 @@ export class ProviderTransportError extends Error {
         this.limitBytes = limitBytes;
     }
 }
+/** HTTP failure error carrying the status as numeric `code` plus any `Retry-After`
+ *  hint as `retryAfterMs`, so retry policies classify transience and pace retries
+ *  without parsing message text. Both fields flow into `ErrorInfo` via errorToErrorInfo. */
+export function httpStatusError(prefix, response, bodyText) {
+    const error = new Error(`${prefix}: ${response.status} ${bodyText}`);
+    error.code = response.status;
+    const hint = parseRetryAfterMs(response.headers.get("retry-after"));
+    if (hint !== undefined)
+        error.retryAfterMs = hint;
+    return error;
+}
+/** Parse a `Retry-After` header (delay-seconds or HTTP-date) into milliseconds. */
+export function parseRetryAfterMs(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - now);
+}
 function resolveLimits(options) {
     return {
         maxEventBytes: options?.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES,

package/dist/providers.d.ts

@@ -2,6 +2,8 @@ import type { AIProvider, ModelConfig, ProviderResolver } from "./contracts.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
 export interface ProviderRegistry {
     register(provider: AIProvider): void;
+    /** Remove a provider; returns false when the id was not registered. */
+    unregister(id: string): boolean;
     get(id: string): AIProvider | undefined;
     resolve(model: Pick<ModelConfig, "provider"> | string): AIProvider;
     list(): readonly AIProvider[];

package/dist/providers.js

@@ -6,6 +6,9 @@ export function createProviderRegistry(providers = [], options = {}) {
             assertCanRegister(byId, provider.id, "provider", provider.id, options.duplicate);
             byId.set(provider.id, provider);
         },
+        unregister(id) {
+            return byId.delete(id);
+        },
         get(id) {
             return byId.get(id);
         },