octaflow 0.29.2 → 0.31.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, a `usage` sink that books each step into `@octabits-io/metering` (the paid APIs around the model in the same table, priced at read time), 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;
@@ -11,6 +12,8 @@ export interface AccumulatedUsage {
   cacheReadTokens: number;
   cacheWriteTokens: number;
   modelId: string;
+  /** The provider the model belongs to (`model.provider`), when the call reported it. */
+  provider?: string;
 }
 export interface UsageAccumulator {
   /** Record usage from a single LLM call (additive — supports multiple calls per step). */
@@ -134,6 +137,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`
@@ -211,6 +224,32 @@ export interface AiUsageRecorder {
     date: string;
   }): Promise<void>;
 }
+/**
+ * What one step's model usage looks like to a metering sink: the booking
+ * `@octabits-io/metering`'s `record` takes, by shape — tokens as the vendor
+ * reported them, the provider as the service, and the attribution octaflow
+ * knows (the run, the workflow type as the feature, the step). A sink that
+ * runs inside `withUsage` adds the paying account from the ambient context.
+ */
+export interface AiModelUsageEvent {
+  kind: 'model';
+  /** The provider (`model.provider`), or `'model'` when the call did not report one. */
+  service: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  context: {
+    runId: string;
+    feature: string;
+    correlationId?: string;
+  };
+}
+/** Where a step's model usage is booked — `@octabits-io/metering`'s `Metering` satisfies it. Optional: without one nothing is booked. */
+export interface AiUsageSink {
+  record(event: AiModelUsageEvent): unknown;
+}
 export interface AiQuotaPolicy {
   /** Return an error (e.g. `ai_quota_exceeded`) to reject a workflow start. */
   checkQuota(): Promise<Result<void, FlowErrorShape>>;
@@ -220,6 +259,12 @@ export interface CreateAiWorkflowHooksDeps<THost = unknown> {
   usageRecorder: AiUsageRecorder;
   /** Optional quota guard. BYOK exemption etc. is the policy's concern. */
   quotaPolicy?: AiQuotaPolicy;
+  /**
+   * Optional metering sink: every step's model usage is booked here as well,
+   * unpriced, attributed to the run and the workflow type — so a model call
+   * and the paid API calls around it land in one table with one context.
+   */
+  usage?: AiUsageSink;
   /** Defaults to `createCostEstimator()` (the built-in pricing table). */
   costEstimator?: CostEstimator;
   /** Clock injection for tests. */
@@ -576,4 +621,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 };