@arnilo/prism 0.0.16 → 0.0.17

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.17";
 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.17";
 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 ?? "legacy");
         },
     };
 }
@@ -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];
         },
     };
 }
@@ -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);
         },

package/dist/redaction.js

@@ -1,4 +1,7 @@
 const REDACTED = "[REDACTED]";
+// Depth bound matching agent-run-state.ts; hostile deep structures yield a placeholder
+// instead of a stack overflow.
+const MAX_REDACT_DEPTH = 32;
 export function createSecretRedactor(secrets) {
     return { redact: (value) => redactSecrets(value, secrets) };
 }
@@ -43,11 +46,13 @@ export function redactSecrets(value, secrets) {
     // ponytail: active-path WeakSet marks only ancestor cycles as [Circular]; shared
     // references (diamonds) are visited again on separate branches. Map/Set normalize
     // to JSON-shaped output; string keys are redacted like values.
-    const redact = (input, active = new WeakSet()) => {
+    const redact = (input, active = new WeakSet(), depth = 0) => {
         if (typeof input === "string")
             return redactString(input);
         if (input === null || typeof input !== "object")
             return input;
+        if (depth >= MAX_REDACT_DEPTH)
+            return "[MaxDepth]";
         if (input instanceof Date || input instanceof RegExp)
             return input;
         if (ArrayBuffer.isView(input) || input instanceof ArrayBuffer)
@@ -57,18 +62,18 @@ export function redactSecrets(value, secrets) {
         active.add(input);
         try {
             if (Array.isArray(input))
-                return input.map((item) => redact(item, active));
+                return input.map((item) => redact(item, active, depth + 1));
             if (input instanceof Map) {
                 const out = {};
                 for (const [key, item] of input)
-                    assignKey(out, redactKey(key), redact(item, active));
+                    assignKey(out, redactKey(key), redact(item, active, depth + 1));
                 return out;
             }
             if (input instanceof Set)
-                return [...input].map((item) => redact(item, active));
+                return [...input].map((item) => redact(item, active, depth + 1));
             const out = {};
             for (const [key, item] of Object.entries(input))
-                assignKey(out, redactKey(key), redact(item, active));
+                assignKey(out, redactKey(key), redact(item, active, depth + 1));
             return out;
         }
         finally {
@@ -79,18 +84,21 @@ export function redactSecrets(value, secrets) {
 }
 export function errorToErrorInfo(error, secrets = []) {
     const code = readErrorCode(error);
+    const retry = readRetryAfterMs(error);
+    const retryAfter = retry !== undefined ? { retryAfterMs: retry } : {};
     if (error instanceof Error) {
         return {
             name: error.name,
             message: redactSecrets(error.message, secrets),
             code,
+            ...retryAfter,
             cause: error.cause ? redactSecrets(String(error.cause), secrets) : undefined,
         };
     }
     if (error && typeof error === "object" && "message" in error) {
-        return { message: redactSecrets(String(error.message), secrets), code };
+        return { message: redactSecrets(String(error.message), secrets), code, ...retryAfter };
     }
-    return { message: redactSecrets(String(error), secrets), code };
+    return { message: redactSecrets(String(error), secrets), code, ...retryAfter };
 }
 function readErrorCode(error) {
     if (!error || typeof error !== "object" || !("code" in error))
@@ -98,4 +106,10 @@ function readErrorCode(error) {
     const code = error.code;
     return typeof code === "string" || typeof code === "number" ? code : undefined;
 }
+function readRetryAfterMs(error) {
+    if (!error || typeof error !== "object" || !("retryAfterMs" in error))
+        return undefined;
+    const value = error.retryAfterMs;
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
 //# sourceMappingURL=redaction.js.map

package/dist/retry.d.ts

@@ -5,6 +5,11 @@ export interface DefaultRetryPolicyOptions {
     readonly baseDelayMs?: number;
     readonly maxDelayMs?: number;
     readonly transientCodes?: readonly (string | number)[];
+    /** Symmetric jitter fraction applied to computed delays (default 0.25 → ±25%).
+     *  Prevents thundering-herd retries under a shared outage. Set 0 to disable. */
+    readonly jitter?: number;
+    /** Random source for jitter (tests); defaults to Math.random. */
+    readonly random?: () => number;
 }
 export declare function createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): RetryPolicy;
 export declare function isTransientErrorInfo(error: ErrorInfo, transientCodes?: ReadonlySet<string | number>): boolean;

package/dist/retry.js

@@ -22,13 +22,20 @@ export function createDefaultRetryPolicy(options = {}) {
     const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
     const baseDelayMs = Math.max(0, options.baseDelayMs ?? 100);
     const maxDelayMs = Math.max(baseDelayMs, options.maxDelayMs ?? 1000);
+    const jitter = Math.min(1, Math.max(0, options.jitter ?? 0.25));
+    const random = options.random ?? Math.random;
     const transientCodes = new Set([...TRANSIENT_CODES, ...(options.transientCodes ?? [])]);
     return {
         name: options.name ?? "default-retry",
         decide(context) {
             if (context.signal?.aborted || context.attempt >= maxAttempts || !isTransientErrorInfo(context.error, transientCodes))
                 return { retry: false };
-            return { retry: true, delayMs: Math.min(maxDelayMs, baseDelayMs * 2 ** Math.max(0, context.attempt - 1)) };
+            // Provider backpressure hint (Retry-After) wins over computed backoff, always
+            // capped at maxDelayMs so a hostile/huge hint cannot pin a run.
+            const hint = context.error.retryAfterMs;
+            const base = Math.min(hint !== undefined && Number.isFinite(hint) && hint >= 0 ? hint : baseDelayMs * 2 ** Math.max(0, context.attempt - 1), maxDelayMs);
+            const delayMs = jitter > 0 ? Math.round(base * (1 - jitter + random() * 2 * jitter)) : base;
+            return { retry: true, delayMs };
         },
     };
 }

package/dist/run-ledger.d.ts

@@ -6,9 +6,15 @@ export declare const HARD_LEDGER_BATCH_BYTES: number;
 export declare const DEFAULT_LEDGER_BATCH_DELAY_MS = 25;
 export declare const HARD_LEDGER_BATCH_DELAY_MS = 60000;
 export interface BatchedRunLedgerOptions {
+    /** Flush triggers, not write grouping: a pending flush fires once the buffer reaches
+     *  this many entries. Writes still go to the target one at a time (RunLedger has no
+     *  batch append); these bounds shape flush *timing*, not per-write coalescing. */
     readonly maxBatchEntries?: number;
+    /** Flush trigger: pending flush fires once buffered bytes reach this bound. */
     readonly maxBatchBytes?: number;
+    /** Backpressure bound: enqueue flushes synchronously before exceeding this. */
     readonly maxBufferedEntries?: number;
+    /** Backpressure bound (bytes): enqueue flushes synchronously before exceeding this. */
     readonly maxBufferedBytes?: number;
     readonly maxDelayMs?: number;
     readonly durability?: RunLedgerDurability;

package/dist/run-ledger.js

@@ -58,20 +58,14 @@ export function createBatchedRunLedger(target, options = {}) {
     const flush = () => {
         cancelTimer();
         const operation = flushChain.then(async () => {
-            let entries = 0;
-            let bytes = 0;
+            // One write per record — RunLedger has no batch append API. maxBatchEntries/
+            // maxBatchBytes only decide when a flush fires (see enqueue), never how writes group.
             while (queue.length) {
                 const item = queue[0];
-                if (entries && (entries >= maxBatchEntries || bytes + item.bytes > maxBatchBytes)) {
-                    entries = 0;
-                    bytes = 0;
-                }
-                await write(item);
+                await write(item); // shifts only after success — a failed write stays buffered for retry
                 queue.shift();
                 bufferedBytes -= item.bytes;
                 flushed += 1;
-                entries += 1;
-                bytes += item.bytes;
             }
             return status();
         });