octaflow 0.29.2 → 0.30.0

package/README.md

@@ -198,13 +198,14 @@ next to what your steps actually do.
 | 🧩 | **Typed DAG** — Zod-validated input/output per step; dependency outputs are typed |
 | ⚡ | **Auto-parallelism** — dependency-free steps run concurrently; a step starts when all its deps complete |
 | 🔁 | **Retry & timeout** — per-step `maxAttempts`, fixed/exponential backoff, wall-clock timeout |
+| 🩹 | **Best-effort steps** — `onFailure: { output }` completes a step with a stand-in once its budget is spent, so one analysis that could not run costs a section of the result, not the run |
 | 💤 | **Durable sleep** — hold a step in the queue for N ms (survives restarts) |
 | 🔀 | **Conditional branching** — `when` guards skip a step and its branch; `join: 'any'` converges |
 | 🎯 | **Decisions** — typed choices with a confidence from a swappable decider (a function, a model, your own); below a threshold a person settles it |
 | ⏳ | **Deadlines** — a budget on a suspended step (fail, or continue with a stand-in answer) and on a whole run |
 | ♻️ | **Retry a failed run** — `retryWorkflow` resumes from the failure point; completed steps keep their output |
 | 🧹 | **Delete the runs about a record** — `purgeWorkflows({ entityRef })` cancels and deletes them with their sub-workflow runs and steps, for an erasure or a deleted record; refuses only while a step is executing |
-| 🚦 | **Concurrency & rate limiting** — per-step-type caps and token buckets via a pluggable gate |
+| 🚦 | **Concurrency & rate limiting** — caps and token buckets per step type or per shared resource (`resources: ['llm:local']`), via a pluggable gate |
 | ⏰ | **Cron / scheduled starts** — fire workflows on a schedule (pg-boss) |
 | 🔑 | **Start idempotency** — a dedup key collapses double-clicks / overlapping ticks |
 | 🗺️ | **Dynamic fan-out / map** — spawn one child step per item of a runtime-sized list |
@@ -214,7 +215,7 @@ next to what your steps actually do.
 | 🚑 | **Crash recovery** — a step whose worker died is re-queued while its attempt budget lasts |
 | 💓 | **Heartbeats** — a long step proves it is alive, so a dead one is caught in seconds, not minutes |
 | 🔭 | **Observability** — lifecycle events (run history), per-step spans, and `createMeterObserver` turning the events into OpenTelemetry-style metrics — all pluggable, all structural |
-| 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups |
+| 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups, refusal-aware models, lenient JSON from local models (`withJsonRepair`), a vendor's refusal explained by key and hint (`explainProviderError`), a per-run circuit breaker, a connection test (`testProvider`) |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
 
 ---

package/dist/ai/index.d.ts

@@ -1,9 +1,10 @@
-import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, f as Decider, j as TypedStepContext, vt as FlowErrorShape, yt as Result } from "../index-B8SvtiYn.js";
+import { A as TypedStep, H as RetryPolicy, M as TypedWorkflow, bt as Result, f as Decider, j as TypedStepContext, yt as FlowErrorShape } from "../index-Du05Lnwr.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
-import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BV-Vany9.js";
+import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-mWaAKHqn.js";
 import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-C_mOfdHH.js";
+import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, b as PROVIDER_ERROR_REDACTED, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, g as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as ProbeableProvider, p as CircuitBreakerOptions, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as ProviderProbeFailure, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../provider-probe-l2Jmpuhr.js";
 import { z } from "zod";
-import { EmbeddingModelV4, LanguageModelV4, SharedV4ProviderMetadata } from "@ai-sdk/provider";
+import { EmbeddingModelV4, LanguageModelV4, LanguageModelV4Usage, SharedV4ProviderMetadata } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts
 export interface AccumulatedUsage {
   inputTokens: number;
@@ -134,6 +135,16 @@ interface DefineAiStepConfig<TInput extends Record<string, unknown>, TOutput ext
   timeoutMs?: number;
   /** Optional durable start delay in ms — held in the queue once the step is ready. */
   delayMs?: number;
+  /**
+   * What a terminal failure does — see `defineStep`'s `onFailure`. `{ output }`
+   * completes the step with a stand-in and the DAG carries on; the model's
+   * refusal or outage then costs one section of the result, not the run.
+   */
+  onFailure?: 'fail' | {
+    output: TOutput;
+  };
+  /** Resources the step draws on (the model, a vendor), for the admission gate — see `defineStep`. */
+  resources?: readonly string[];
 }
 /**
  * Define a type-safe AI workflow step. Identical to flow-core's `defineStep`
@@ -576,4 +587,157 @@ export declare function thinkingSettingsFor(providerId: string, modelId: string,
   budgetTokens: number;
 }): ThinkingSettings;
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };
+//#region src/ai/model-json.d.ts
+/** Which step produced the JSON. `retry` and `convert` are `withJsonRepair`'s. */
+export type ModelJsonRepair = 'fence' | 'prose' | 'array_merge' | 'retry' | 'convert';
+/**
+ * The span or metric attribute that names a repair, in the GenAI convention's
+ * namespace so `@octabits-io/telemetry`'s redaction leaves it alone: its last
+ * segment is `repaired`, not a credential or a person's data. Set it on the
+ * step's span from `withJsonRepair`'s `onRepair`, and a dashboard counts
+ * repairs per model.
+ */
+export declare const MODEL_JSON_REPAIRED_ATTRIBUTE = "gen_ai.response.repaired";
+/** Where a repaired answer is also reported: `result.providerMetadata.octaflow.repaired`. */
+export declare const MODEL_JSON_PROVIDER_METADATA_KEY = "octaflow";
+export type ModelJsonErrorKey =
+/** Nothing but whitespace, or an empty fence. */
+'model_json_empty' |
+/** No step produced JSON: not valid as it is, and no outermost object or array parses. */
+'model_json_invalid' |
+/** The JSON is not an object or an array of objects (a scalar, an array of scalars, a mixed array). */
+'model_json_not_object' |
+/** The JSON parsed but the schema refused it; `issues` carries why. */
+'model_json_schema';
+/** The default length of the excerpt a {@link ModelJsonError} keeps. */
+export declare const DEFAULT_MODEL_JSON_EXCERPT_LENGTH = 500;
+/**
+ * The answer could not be read as the JSON that was asked for.
+ *
+ * `message` names the reason and never quotes the answer: it is what lands in
+ * a step's `error` column and in a log line. `excerpt` is the first
+ * `excerptLength` characters (500 by default) for a debug trace that wants to
+ * see what the model said.
+ */
+export declare class ModelJsonError extends Error {
+  readonly name = "ModelJsonError";
+  readonly key: ModelJsonErrorKey;
+  /** The first characters of the answer, cut at the configured length. */
+  readonly excerpt: string;
+  /** The schema's issues, for `model_json_schema`. */
+  readonly issues?: readonly unknown[];
+  /** The step that produced the JSON the schema then refused. */
+  readonly repair?: ModelJsonRepair;
+  constructor(args: {
+    key: ModelJsonErrorKey;
+    excerpt: string;
+    issues?: readonly unknown[];
+    repair?: ModelJsonRepair;
+  });
+}
+/** True when `error` is a {@link ModelJsonError}, or wraps one as its `cause` (`generateObject` re-wraps). */
+export declare function isModelJsonError(error: unknown): error is ModelJsonError;
+export interface ParseModelJsonOptions<T> {
+  /** Validate the value; the issues go on the error. */
+  schema?: z.ZodType<T>;
+  /**
+   * Merge an array of objects into one object: array fields concatenated in
+   * order, the first non-empty scalar kept, `null` never overwriting a value,
+   * nested objects merged the same way. For a model that answered one object
+   * per image when one object was asked for. Off by default: an array answer
+   * is then returned as the array.
+   */
+  merge?: boolean;
+  /** How many characters of the answer the error keeps. Default 500. */
+  excerptLength?: number;
+}
+export interface ModelJsonParsed<T> {
+  value: T;
+  /** The step that produced the JSON; absent when the answer parsed as it was. */
+  repair?: ModelJsonRepair;
+}
+/**
+ * Read a model's answer as JSON, leniently — see the module header for the
+ * steps. Returns the value, and which repair it took, or a {@link ModelJsonError}.
+ */
+export declare function parseModelJson<T = unknown>(text: string, options?: ParseModelJsonOptions<T>): Result<ModelJsonParsed<T>, ModelJsonError>;
+/**
+ * The same recovery as a `repairText` function for the AI SDK's
+ * `generateObject` / `Output.object`: given the raw text the SDK could not
+ * parse, the repaired JSON as a string, or `null` when no step helps (the SDK
+ * then reports its own `NoObjectGeneratedError`).
+ *
+ * ```ts
+ * await generateObject({ model, schema, prompt, repairText: modelJsonRepairText({ merge: true }) });
+ * ```
+ */
+export declare function modelJsonRepairText(options?: {
+  merge?: boolean;
+}): (args: {
+  text: string;
+  error: unknown;
+}) => Promise<string | null>;
+/** Internal: the recovery without the schema, shared with `withJsonRepair`. */
+export type RecoveredModelJson = {
+  ok: true;
+  value: Record<string, unknown> | Record<string, unknown>[];
+  repair?: ModelJsonRepair;
+} | {
+  ok: false;
+  key: Exclude<ModelJsonErrorKey, 'model_json_schema'>;
+};
+/** @internal */
+export declare function recoverModelJson(text: string, options: {
+  merge: boolean;
+}): RecoveredModelJson;
+/**
+ * Merge objects a model answered "per item" into one: array fields are
+ * concatenated in order, nested objects merged the same way, and for a scalar
+ * the first non-empty value is kept — `null` and `''` never overwrite a value.
+ */
+export declare function mergeModelJsonObjects(objects: readonly Record<string, unknown>[]): Record<string, unknown>;
+/** @internal */
+export declare function excerptOf(text: string, length?: number): string;
+//#endregion
+//#region src/ai/json-repair.d.ts
+/** What `onRepair` is told: once per repaired answer, after the answer is final. */
+export interface ModelJsonRepairEvent {
+  /** The wrapped model's id. */
+  modelId: string;
+  /** The step that produced the JSON — the value for `gen_ai.response.repaired`. */
+  repair: ModelJsonRepair;
+  /** Requests made beyond the first: 0 for a parse-level repair, 1 for a retry or a conversion, 2 for both. */
+  extraRequests: number;
+}
+export interface JsonRepairOptions {
+  /** Merge an array of objects into one — see `parseModelJson`. Skipped when the requested schema is itself an array. */
+  merge?: boolean;
+  /** On a parse failure, one more request with the provider's JSON mode off. Default `false`. */
+  retryWithoutJsonMode?: boolean;
+  /**
+   * On a parse failure (after the retry, when both are on), one call that is
+   * handed the schema and the prose and asked for the JSON. `true` uses the
+   * wrapped model; a `LanguageModelV4` uses that one, for a cheaper converter.
+   * Default off.
+   */
+  convertWith?: LanguageModelV4 | true;
+  /** How many characters of the answer the error keeps. Default 500. */
+  excerptLength?: number;
+  /** Told of every repaired answer: set `MODEL_JSON_REPAIRED_ATTRIBUTE` on the step's span, count it on a meter. Must not throw. */
+  onRepair?: (event: ModelJsonRepairEvent) => void;
+}
+/**
+ * Wrap a model so a JSON answer that is nearly JSON is read as the JSON it
+ * meant — see the module header. The result's text becomes the canonical
+ * JSON, and `providerMetadata.octaflow.repaired` names the step taken.
+ */
+export declare function withJsonRepair(model: LanguageModelV4, options?: JsonRepairOptions): LanguageModelV4;
+/**
+ * Two usages added field by field — `inputTokens`, `outputTokens` and
+ * whatever a provider adds — so the instrumented model outside the wrapper
+ * counts every request the repair made. An undefined on one side keeps the
+ * other; `raw` is the last call's.
+ */
+export declare function addUsage(a: LanguageModelV4Usage, b: LanguageModelV4Usage): LanguageModelV4Usage;
+//#endregion
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, CircuitBreaker, CircuitBreakerOptions, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OllamaProbeOptions, OllamaProbeReport, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProbeableProvider, ProviderError, ProviderErrorExplanation, ProviderErrorKey, ProviderErrorPhrase, ProviderErrorPreset, ProviderProbeFailure, ProviderProbeOptions, ProviderProbeReport, createCircuitBreaker, embeddingDimensionsFor, explainProviderError, isFatalProviderError, isProviderError, isSubprocessorResidency, maskKeys, resolveEndpointResidency, testOllamaModel, testProvider, withCircuitBreaker };

package/dist/ai/index.js

@@ -1,5 +1,6 @@
-import { D as ok, E as err, T as noopLogger, _ as defineStep, m as buildWorkflow } from "../core-C9h3-KFr.js";
-import { a as readRefusalDetails, i as isAiRefusalError, n as REFUSAL_FINISH_REASON, r as createRefusalAwareModel, t as AiRefusalError } from "../refusal-BsL2HPDb.js";
+import { n as err, r as ok, t as noopLogger } from "../logger-epkdcXDA.js";
+import { _ as defineStep, m as buildWorkflow } from "../core-DBqxBk3R.js";
+import { S as readRefusalDetails, _ as maskKeys, a as testProvider, b as createRefusalAwareModel, c as DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, d as PROVIDER_ERROR_REDACTED, f as PROVIDER_ERROR_STATUS, g as isProviderError, h as isFatalProviderError, i as testOllamaModel, l as FATAL_PROVIDER_ERROR_KEYS, m as explainProviderError, n as DEFAULT_PROVIDER_PROBE_PROMPT, o as createCircuitBreaker, p as ProviderError, r as DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, s as withCircuitBreaker, t as DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, u as PROVIDER_ERROR_PHRASES, v as AiRefusalError, x as isAiRefusalError, y as REFUSAL_FINISH_REASON } from "../provider-probe-CGN2MpaZ.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, i as DEFAULT_EMBEDDING_PROVIDER, l as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as OPENAI_COMPATIBLE_PROVIDER, t as AI_PROVIDERS, u as isSubprocessorResidency } from "../provider-registry-B91lgOmu.js";
 import { z } from "zod";
 import { Output, generateText, wrapEmbeddingModel, wrapLanguageModel } from "ai";
@@ -754,4 +755,383 @@ function thinkingSettingsFor(providerId, modelId, opts) {
 	return { temperature: opts.temperature };
 }
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, isSubprocessorResidency, readRefusalDetails, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };
+//#region src/ai/model-json.ts
+/**
+* The span or metric attribute that names a repair, in the GenAI convention's
+* namespace so `@octabits-io/telemetry`'s redaction leaves it alone: its last
+* segment is `repaired`, not a credential or a person's data. Set it on the
+* step's span from `withJsonRepair`'s `onRepair`, and a dashboard counts
+* repairs per model.
+*/
+const MODEL_JSON_REPAIRED_ATTRIBUTE = "gen_ai.response.repaired";
+/** Where a repaired answer is also reported: `result.providerMetadata.octaflow.repaired`. */
+const MODEL_JSON_PROVIDER_METADATA_KEY = "octaflow";
+/** The default length of the excerpt a {@link ModelJsonError} keeps. */
+const DEFAULT_MODEL_JSON_EXCERPT_LENGTH = 500;
+/**
+* The answer could not be read as the JSON that was asked for.
+*
+* `message` names the reason and never quotes the answer: it is what lands in
+* a step's `error` column and in a log line. `excerpt` is the first
+* `excerptLength` characters (500 by default) for a debug trace that wants to
+* see what the model said.
+*/
+var ModelJsonError = class extends Error {
+	name = "ModelJsonError";
+	key;
+	/** The first characters of the answer, cut at the configured length. */
+	excerpt;
+	/** The schema's issues, for `model_json_schema`. */
+	issues;
+	/** The step that produced the JSON the schema then refused. */
+	repair;
+	constructor(args) {
+		super(modelJsonMessage(args.key, args.issues));
+		this.key = args.key;
+		this.excerpt = args.excerpt;
+		if (args.issues) this.issues = args.issues;
+		if (args.repair) this.repair = args.repair;
+	}
+};
+function modelJsonMessage(key, issues) {
+	switch (key) {
+		case "model_json_empty": return "The model answered with no JSON.";
+		case "model_json_invalid": return "The model answer is not JSON: no fenced block, outermost object or outermost array parses.";
+		case "model_json_not_object": return "The model answer is JSON but not an object or an array of objects.";
+		case "model_json_schema": {
+			const count = issues?.length ?? 0;
+			return `The model answer is JSON but not the shape asked for (${count} ${count === 1 ? "issue" : "issues"}).`;
+		}
+	}
+}
+/** True when `error` is a {@link ModelJsonError}, or wraps one as its `cause` (`generateObject` re-wraps). */
+function isModelJsonError(error) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	for (let depth = 0; depth < 8; depth++) {
+		if (typeof current !== "object" || current === null || seen.has(current)) return false;
+		if (current instanceof ModelJsonError) return true;
+		seen.add(current);
+		current = current.cause;
+	}
+	return false;
+}
+/**
+* Read a model's answer as JSON, leniently — see the module header for the
+* steps. Returns the value, and which repair it took, or a {@link ModelJsonError}.
+*/
+function parseModelJson(text, options = {}) {
+	const excerpt = excerptOf(text, options.excerptLength);
+	const recovered = recoverModelJson(text, { merge: options.merge ?? false });
+	if (!recovered.ok) return {
+		ok: false,
+		error: new ModelJsonError({
+			key: recovered.key,
+			excerpt
+		})
+	};
+	const repair = recovered.repair;
+	if (!options.schema) return {
+		ok: true,
+		value: repair ? {
+			value: recovered.value,
+			repair
+		} : { value: recovered.value }
+	};
+	const checked = options.schema.safeParse(recovered.value);
+	if (!checked.success) return {
+		ok: false,
+		error: new ModelJsonError({
+			key: "model_json_schema",
+			excerpt,
+			issues: checked.error.issues,
+			...repair ? { repair } : {}
+		})
+	};
+	return {
+		ok: true,
+		value: repair ? {
+			value: checked.data,
+			repair
+		} : { value: checked.data }
+	};
+}
+/**
+* The same recovery as a `repairText` function for the AI SDK's
+* `generateObject` / `Output.object`: given the raw text the SDK could not
+* parse, the repaired JSON as a string, or `null` when no step helps (the SDK
+* then reports its own `NoObjectGeneratedError`).
+*
+* ```ts
+* await generateObject({ model, schema, prompt, repairText: modelJsonRepairText({ merge: true }) });
+* ```
+*/
+function modelJsonRepairText(options = {}) {
+	return async ({ text }) => {
+		const recovered = recoverModelJson(text, { merge: options.merge ?? false });
+		return recovered.ok && recovered.repair ? JSON.stringify(recovered.value) : null;
+	};
+}
+/** @internal */
+function recoverModelJson(text, options) {
+	const trimmed = text.trim();
+	if (!trimmed) return {
+		ok: false,
+		key: "model_json_empty"
+	};
+	let body = trimmed;
+	let repair;
+	const fenced = unfence(trimmed);
+	if (fenced !== void 0) {
+		body = fenced.trim();
+		repair = "fence";
+		if (!body) return {
+			ok: false,
+			key: "model_json_empty"
+		};
+	}
+	let value = tryParse(body);
+	if (value === INVALID) {
+		const cut = outermost(body);
+		if (cut === void 0) return {
+			ok: false,
+			key: "model_json_invalid"
+		};
+		value = cut;
+		repair = "prose";
+	}
+	if (isPlainObject(value)) return repair ? {
+		ok: true,
+		value,
+		repair
+	} : {
+		ok: true,
+		value
+	};
+	if (Array.isArray(value) && value.every(isPlainObject)) {
+		const objects = value;
+		if (!options.merge) return repair ? {
+			ok: true,
+			value: objects,
+			repair
+		} : {
+			ok: true,
+			value: objects
+		};
+		return {
+			ok: true,
+			value: mergeModelJsonObjects(objects),
+			repair: "array_merge"
+		};
+	}
+	return {
+		ok: false,
+		key: "model_json_not_object"
+	};
+}
+const INVALID = Symbol("invalid");
+function tryParse(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return INVALID;
+	}
+}
+const FENCE_RE = /```[A-Za-z0-9_-]*[ \t]*\r?\n?([\s\S]*?)(?:```|$)/;
+/** The content of the first fenced block, or `undefined` when there is none. An unterminated fence runs to the end. */
+function unfence(text) {
+	const match = FENCE_RE.exec(text);
+	return match ? match[1] : void 0;
+}
+/**
+* The outermost `{ … }` or `[ … ]` in the text, by first opener and last
+* closer; whichever opener comes first is tried first, the other after it.
+* Only a candidate that parses *and* has an accepted shape wins, so a stray
+* `[1]` in the prose before the object does not shadow it; a cut that is JSON
+* of another shape (`["paid"]` inside an object the prose broke) is not the
+* answer either, and the whole is refused as invalid.
+*/
+function outermost(text) {
+	const candidates = [["{", "}"], ["[", "]"]];
+	const objectAt = text.indexOf("{");
+	const arrayAt = text.indexOf("[");
+	if (arrayAt !== -1 && (objectAt === -1 || arrayAt < objectAt)) candidates.reverse();
+	for (const [open, close] of candidates) {
+		const start = text.indexOf(open);
+		const end = text.lastIndexOf(close);
+		if (start === -1 || end <= start) continue;
+		const parsed = tryParse(text.slice(start, end + 1));
+		if (parsed === INVALID) continue;
+		if (isPlainObject(parsed) || Array.isArray(parsed) && parsed.every(isPlainObject)) return parsed;
+	}
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEmpty(value) {
+	return value === void 0 || value === null || value === "";
+}
+/**
+* Merge objects a model answered "per item" into one: array fields are
+* concatenated in order, nested objects merged the same way, and for a scalar
+* the first non-empty value is kept — `null` and `''` never overwrite a value.
+*/
+function mergeModelJsonObjects(objects) {
+	const out = {};
+	for (const object of objects) for (const [key, incoming] of Object.entries(object)) {
+		const current = out[key];
+		if (Array.isArray(current) && Array.isArray(incoming)) out[key] = [...current, ...incoming];
+		else if (isPlainObject(current) && isPlainObject(incoming)) out[key] = mergeModelJsonObjects([current, incoming]);
+		else if (!(key in out) || isEmpty(current)) out[key] = incoming;
+	}
+	return out;
+}
+/** @internal */
+function excerptOf(text, length = 500) {
+	return text.length > length ? text.slice(0, length) : text;
+}
+//#endregion
+//#region src/ai/json-repair.ts
+/**
+* Wrap a model so a JSON answer that is nearly JSON is read as the JSON it
+* meant — see the module header. The result's text becomes the canonical
+* JSON, and `providerMetadata.octaflow.repaired` names the step taken.
+*/
+function withJsonRepair(model, options = {}) {
+	return wrapLanguageModel({
+		model,
+		middleware: {
+			specificationVersion: "v4",
+			wrapGenerate: async ({ doGenerate, params, model: inner }) => {
+				const format = params.responseFormat;
+				if (format?.type !== "json") return doGenerate();
+				const merge = (options.merge ?? false) && format.schema?.type !== "array";
+				const first = await doGenerate();
+				const text = textOf(first);
+				if (text === void 0) return first;
+				const read = recoverModelJson(text, { merge });
+				if (read.ok) {
+					if (!read.repair) return first;
+					return repaired(first, read.value, read.repair, 0, inner, options);
+				}
+				let usage = first.usage;
+				let prose = text;
+				let lastKey = read.key;
+				let extraRequests = 0;
+				if (options.retryWithoutJsonMode) {
+					const second = await inner.doGenerate({
+						...params,
+						responseFormat: { type: "text" }
+					});
+					extraRequests += 1;
+					usage = addUsage(usage, second.usage);
+					const retried = textOf(second) ?? "";
+					const again = recoverModelJson(retried, { merge });
+					if (again.ok) return repaired({
+						...second,
+						usage
+					}, again.value, "retry", extraRequests, inner, options);
+					prose = retried;
+					lastKey = again.key;
+				}
+				if (options.convertWith) {
+					const third = await (options.convertWith === true ? inner : options.convertWith).doGenerate(conversionCall(params, prose, format.schema));
+					extraRequests += 1;
+					usage = addUsage(usage, third.usage);
+					const converted = textOf(third) ?? "";
+					const again = recoverModelJson(converted, { merge });
+					if (again.ok) return repaired({
+						...third,
+						usage
+					}, again.value, "convert", extraRequests, inner, options);
+					prose = converted;
+					lastKey = again.key;
+				}
+				throw new ModelJsonError({
+					key: lastKey,
+					excerpt: excerptOf(prose, options.excerptLength)
+				});
+			}
+		}
+	});
+}
+/** The answer's text, all text parts joined; `undefined` when the answer carries no text (tool calls alone). */
+function textOf(result) {
+	const parts = result.content.filter((part) => part.type === "text");
+	if (parts.length === 0) return void 0;
+	return parts.map((part) => part.text).join("");
+}
+function repaired(result, value, repair, extraRequests, inner, options) {
+	options.onRepair?.({
+		modelId: inner.modelId,
+		repair,
+		extraRequests
+	});
+	return {
+		...result,
+		content: [...result.content.filter((part) => part.type !== "text"), {
+			type: "text",
+			text: JSON.stringify(value)
+		}],
+		providerMetadata: {
+			...result.providerMetadata,
+			[MODEL_JSON_PROVIDER_METADATA_KEY]: {
+				...result.providerMetadata?.[MODEL_JSON_PROVIDER_METADATA_KEY],
+				repaired: repair
+			}
+		}
+	};
+}
+/** The conversion request: the schema and the prose, JSON asked for, nothing of the original prompt. */
+function conversionCall(params, prose, schema) {
+	return {
+		prompt: [{
+			role: "user",
+			content: [{
+				type: "text",
+				text: [
+					"Convert the answer below into a single JSON value that matches the schema. Output the JSON only: no fence, no prose.",
+					schema ? `Schema:\n${JSON.stringify(schema)}` : "Shape: one JSON object.",
+					`Answer:\n${prose}`
+				].join("\n\n")
+			}]
+		}],
+		responseFormat: params.responseFormat,
+		temperature: 0,
+		...params.maxOutputTokens !== void 0 ? { maxOutputTokens: params.maxOutputTokens } : {},
+		...params.abortSignal ? { abortSignal: params.abortSignal } : {},
+		...params.headers ? { headers: params.headers } : {}
+	};
+}
+/**
+* Two usages added field by field — `inputTokens`, `outputTokens` and
+* whatever a provider adds — so the instrumented model outside the wrapper
+* counts every request the repair made. An undefined on one side keeps the
+* other; `raw` is the last call's.
+*/
+function addUsage(a, b) {
+	const { raw: _rawA, ...restA } = a;
+	const { raw: rawB, ...restB } = b;
+	const sum = addNumbers(restA, restB);
+	return rawB ? {
+		...sum,
+		raw: rawB
+	} : sum;
+}
+function addNumbers(a, b) {
+	const out = {};
+	for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])) {
+		const x = a[key];
+		const y = b[key];
+		if (typeof x === "number" && typeof y === "number") out[key] = x + y;
+		else if (typeof x === "number" || typeof y === "number") out[key] = typeof x === "number" ? x : y;
+		else if (isRecord(x) && isRecord(y)) out[key] = addNumbers(x, y);
+		else out[key] = x ?? y;
+	}
+	return out;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_JSON_EXCERPT_LENGTH, DEFAULT_MODEL_PRICING, DEFAULT_OLLAMA_PROBE_TIMEOUT_MS, DEFAULT_PROVIDER_ERROR_DETAIL_LENGTH, DEFAULT_PROVIDER_PROBE_PROMPT, DEFAULT_PROVIDER_PROBE_TIMEOUT_MS, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, FATAL_PROVIDER_ERROR_KEYS, MODEL_JSON_PROVIDER_METADATA_KEY, MODEL_JSON_REPAIRED_ATTRIBUTE, ModelJsonError, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_REDACTED, PROVIDER_ERROR_STATUS, ProviderError, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, addUsage, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCircuitBreaker, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createModelDecider, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, excerptOf, explainProviderError, isAiRefusalError, isFatalProviderError, isModelJsonError, isProviderError, isSubprocessorResidency, maskKeys, mergeModelJsonObjects, modelJsonRepairText, parseModelJson, readRefusalDetails, recoverModelJson, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, testOllamaModel, testProvider, thinkingSettingsFor, withCircuitBreaker, withJsonRepair };

package/dist/ai/providers/index.d.ts

@@ -1,4 +1,5 @@
 import { b as OpenAiCompatibleProviderId, g as EmbeddingProviderId, i as AiEndpointResidency, o as AiProviderId } from "../../provider-registry-C_mOfdHH.js";
+import { A as maskKeys, C as ProviderErrorExplanation, D as explainProviderError, E as ProviderErrorPreset, O as isFatalProviderError, S as ProviderError, T as ProviderErrorPhrase, _ as ExplainProviderErrorOptions, a as OllamaProbeReport, c as ProviderProbeOptions, d as testProvider, f as CircuitBreaker, h as withCircuitBreaker, i as OllamaProbeOptions, k as isProviderError, l as ProviderProbeReport, m as createCircuitBreaker, o as ProbeableProvider, p as CircuitBreakerOptions, s as ProviderProbeFailure, u as testOllamaModel, v as FATAL_PROVIDER_ERROR_KEYS, w as ProviderErrorKey, x as PROVIDER_ERROR_STATUS, y as PROVIDER_ERROR_PHRASES } from "../../provider-probe-l2Jmpuhr.js";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;
@@ -205,4 +206,5 @@ export interface OpenAiCompatibleGatewayProvider {
  * in the same review.
  */
 export declare function createOpenAiCompatibleGatewayProvider(config: OpenAiCompatibleGatewayConfig): Promise<OpenAiCompatibleGatewayProvider>;
-//#endregion
+//#endregion
+export { type CircuitBreaker, type CircuitBreakerOptions, type ExplainProviderErrorOptions, FATAL_PROVIDER_ERROR_KEYS, type OllamaProbeOptions, type OllamaProbeReport, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_STATUS, type ProbeableProvider, ProviderError, type ProviderErrorExplanation, type ProviderErrorKey, type ProviderErrorPhrase, type ProviderErrorPreset, type ProviderProbeFailure, type ProviderProbeOptions, type ProviderProbeReport, createCircuitBreaker, explainProviderError, isFatalProviderError, isProviderError, maskKeys, testOllamaModel, testProvider, withCircuitBreaker };

package/dist/ai/providers/index.js

@@ -1,4 +1,4 @@
-import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
+import { _ as maskKeys, a as testProvider, b as createRefusalAwareModel, f as PROVIDER_ERROR_STATUS, g as isProviderError, h as isFatalProviderError, i as testOllamaModel, l as FATAL_PROVIDER_ERROR_KEYS, m as explainProviderError, o as createCircuitBreaker, p as ProviderError, s as withCircuitBreaker, u as PROVIDER_ERROR_PHRASES } from "../../provider-probe-CGN2MpaZ.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-B91lgOmu.js";
 import { wrapLanguageModel } from "ai";
 //#region src/ai/providers/index.ts
@@ -280,4 +280,4 @@ async function createOpenAiCompatibleGatewayProvider(config) {
 	};
 }
 //#endregion
-export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleGatewayProvider, createOpenAiCompatibleModelProvider };
+export { AiProviderConfigError, FATAL_PROVIDER_ERROR_KEYS, PROVIDER_ERROR_PHRASES, PROVIDER_ERROR_STATUS, ProviderError, createCircuitBreaker, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleGatewayProvider, createOpenAiCompatibleModelProvider, explainProviderError, isFatalProviderError, isProviderError, maskKeys, testOllamaModel, testProvider, withCircuitBreaker };