octaflow 0.25.0 → 0.26.0

package/README.md

@@ -295,6 +295,10 @@ export const flowStepLease = pgTable('flow_step_lease', flowStepLeaseColumns, (t
 ]);
 ```
 
+The names are yours: the store's `ON CONFLICT` clauses target column lists, never a
+constraint by name, so what must match is each index's columns and its partial `WHERE`,
+not what you call it.
+
 The store stays plain SQL, bound to the `schema` you hand `createPgWorkflowStore`,
 `createPgStepGate` and `createPgEventSink` — and, for the gate, to the `tables` names — so
 declare the tables under the same schema and names. A test in the package holds every column

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

@@ -66,7 +66,7 @@ export interface LazyEmbeddingModelMeta {
  * next call rather than cached.
  */
 export declare function createLazyEmbeddingModel(meta: LazyEmbeddingModelMeta, load: () => Promise<EmbeddingModelV4>): EmbeddingModelV4;
-export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_embedding_dimensions_invalid';
+export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_model_undeclared' | 'ai_embedding_dimensions_invalid';
 /**
  * A provider configuration that cannot work. Thrown before any SDK is loaded
  * or any request is made: it is a deployment mistake, found at wiring time.
@@ -143,4 +143,66 @@ export interface OpenAiCompatibleEmbeddingProvider {
 export declare function createOpenAiCompatibleModelProvider(config: OpenAiCompatibleModelProviderConfig): Promise<OpenAiCompatibleModelProvider>;
 /** An embedding model on an OpenAI-compatible endpoint, with its declared width. */
 export declare function createOpenAiCompatibleEmbeddingProvider(config: OpenAiCompatibleEmbeddingProviderConfig): Promise<OpenAiCompatibleEmbeddingProvider>;
+export interface OpenAiCompatibleGatewayModel {
+  /** Where the gateway sends this alias. Validated like an endpoint's residency. */
+  residency: AiEndpointResidency;
+}
+/**
+ * `residency` is where the gateway itself runs, usually `{ region: 'self-hosted' }`.
+ * It decides whether plain http is acceptable for the hop to the gateway; where a
+ * call ends up is the alias's residency in `models`.
+ */
+export interface OpenAiCompatibleGatewayConfig extends OpenAiCompatibleEndpointConfig {
+  /** Every alias this deployment may call, keyed by the model name the gateway knows. */
+  models: Record<string, OpenAiCompatibleGatewayModel>;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.structuredOutputs}. */
+  structuredOutputs?: boolean;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.includeUsage}. */
+  includeUsage?: boolean;
+}
+export interface GatewayCallOptions {
+  /**
+   * Sent as the request body's `metadata`, which LiteLLM keeps in its spend log,
+   * so a call there can be matched to the host's own record: a workflow id, a
+   * scope key. It leaves the house as written and is never redacted: put ids
+   * here, never content. Added innermost, so a disclosure gate wrapped around the
+   * model neither digests nor redacts it.
+   */
+  metadata?: Record<string, string>;
+}
+export interface OpenAiCompatibleGatewayProvider {
+  providerId: OpenAiCompatibleProviderId;
+  /** Where the gateway itself runs. */
+  residency: AiEndpointResidency;
+  /** Every declared alias with its validated residency: what a settings page or a subprocessor annex lists. */
+  models: Readonly<Record<string, AiEndpointResidency>>;
+  /** The residency of one alias. Throws `ai_model_undeclared` for an alias the declaration does not name. */
+  residencyOf(alias: string): AiEndpointResidency;
+  /** A Chat Completions model for a declared alias, wrapped for refusal detection. */
+  languageModel(alias: string, options?: GatewayCallOptions): LanguageModelV4;
+}
+/**
+ * A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+ * refusal-aware models, one per declared alias, each with the residency of
+ * where the gateway sends it.
+ *
+ * ```ts
+ * const gateway = await createOpenAiCompatibleGatewayProvider({
+ *   baseUrl: 'http://litellm.ai.svc:4000/v1',
+ *   apiKey: process.env.LITELLM_KEY,
+ *   residency: { region: 'self-hosted' },
+ *   models: {
+ *     'approval-confidential': { residency: { region: 'self-hosted' } },
+ *     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+ *   },
+ * });
+ * const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+ * ```
+ *
+ * The declaration is what the gateway is configured to do, stated by the
+ * deployment: this provider cannot see the gateway's routing, and a fallback
+ * the gateway adds on its own breaks the declaration silently. Keep the two
+ * in the same review.
+ */
+export declare function createOpenAiCompatibleGatewayProvider(config: OpenAiCompatibleGatewayConfig): Promise<OpenAiCompatibleGatewayProvider>;
 //#endregion

package/dist/ai/providers/index.js

@@ -1,5 +1,6 @@
 import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-BRwjC6_3.js";
+import { wrapLanguageModel } from "ai";
 //#region src/ai/providers/index.ts
 const LLM_LOADERS = {
 	anthropic: async (apiKey, baseURL) => {
@@ -186,5 +187,90 @@ async function createOpenAiCompatibleEmbeddingProvider(config) {
 		embeddingModel: () => provider.embeddingModel(modelId)
 	};
 }
+/** Puts `metadata` into the request body under the provider's own options key, merged over any the call carries. */
+function withGatewayMetadata(model, optionsKey, metadata) {
+	const fixed = { ...metadata };
+	return wrapLanguageModel({
+		model,
+		middleware: {
+			specificationVersion: "v4",
+			transformParams: async ({ params }) => {
+				const own = params.providerOptions?.[optionsKey] ?? {};
+				const existing = own.metadata !== null && typeof own.metadata === "object" && !Array.isArray(own.metadata) ? own.metadata : {};
+				const merged = {
+					...own,
+					metadata: {
+						...existing,
+						...fixed
+					}
+				};
+				return {
+					...params,
+					providerOptions: {
+						...params.providerOptions,
+						[optionsKey]: merged
+					}
+				};
+			}
+		}
+	});
+}
+/**
+* A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+* refusal-aware models, one per declared alias, each with the residency of
+* where the gateway sends it.
+*
+* ```ts
+* const gateway = await createOpenAiCompatibleGatewayProvider({
+*   baseUrl: 'http://litellm.ai.svc:4000/v1',
+*   apiKey: process.env.LITELLM_KEY,
+*   residency: { region: 'self-hosted' },
+*   models: {
+*     'approval-confidential': { residency: { region: 'self-hosted' } },
+*     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+*   },
+* });
+* const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+* ```
+*
+* The declaration is what the gateway is configured to do, stated by the
+* deployment: this provider cannot see the gateway's routing, and a fallback
+* the gateway adds on its own breaks the declaration silently. Keep the two
+* in the same review.
+*/
+async function createOpenAiCompatibleGatewayProvider(config) {
+	const residency = checkEndpoint(config);
+	const declared = config.models;
+	if (declared === null || typeof declared !== "object" || Object.keys(declared).length === 0) throw new AiProviderConfigError("ai_model_required", "a gateway needs at least one declared model alias in models");
+	const models = {};
+	for (const [alias, model] of Object.entries(declared)) {
+		requireModel(alias, "a model alias");
+		const resolved = resolveEndpointResidency(model?.residency);
+		if (!resolved.ok) throw new AiProviderConfigError(resolved.error.key, `model ${JSON.stringify(alias)}: ${resolved.error.message}`);
+		models[alias] = resolved.value;
+	}
+	Object.freeze(models);
+	const provider = await loadOpenAiCompatible(config, {
+		structuredOutputs: config.structuredOutputs,
+		includeUsage: config.includeUsage
+	});
+	const optionsKey = config.name ?? "openai-compatible";
+	const residencyOf = (alias) => {
+		const found = Object.hasOwn(models, alias) ? models[alias] : void 0;
+		if (found === void 0) throw new AiProviderConfigError("ai_model_undeclared", `model ${JSON.stringify(alias)} is not declared for this gateway; declared: ${Object.keys(models).join(", ")}`);
+		return found;
+	};
+	return {
+		providerId: OPENAI_COMPATIBLE_PROVIDER_ID,
+		residency,
+		models,
+		residencyOf,
+		languageModel: (alias, options) => {
+			residencyOf(alias);
+			const chat = provider.chatModel(alias);
+			return createRefusalAwareModel(options?.metadata ? withGatewayMetadata(chat, optionsKey, options.metadata) : chat);
+		}
+	};
+}
 //#endregion
-export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleModelProvider };
+export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleGatewayProvider, createOpenAiCompatibleModelProvider };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { $ as computeReadiness, A as StepConditionHandler, B as StepStatus, C as defineWaitStep, D as StartOptions, E as RetryPolicy, F as StepHandlerNotFoundError, G as WorkflowNotFoundError, H as WorkflowCreatedResult, I as StepHandlerRegistry, J as WorkflowStatus, K as WorkflowNotRetryableError, L as StepId, M as StepError, N as StepExecutionContext, O as StepCompensateHandler, P as StepHandler, Q as ReadinessPlan, R as StepRecord, S as defineSubWorkflowStep, T as InvalidWorkflowDefinitionError, U as WorkflowDefinition, V as WaitTimeoutPolicy, W as WorkflowId, X as JoinRule, Y as WorkflowWithSteps, Z as PlannedSkip, _ as WorkflowOutput, a as STEP_DISPLAY_STATUS, b as defineSleepStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, et as isTerminalStepStatus, f as StepDeps, g as TypedWorkflow, h as TypedStepContext, i as PublicWorkflowStep, it as ok, j as StepDefinition, k as StepCompensationContext, l as toDisplayStepStatus, m as TypedStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as Result, o as STEP_DISPLAY_STATUS_SCHEMA, p as StepOutput, q as WorkflowRecord, r as PublicWorkflow, rt as err, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, tt as FlowErrorShape, u as toPublicStep, v as buildWorkflow, w as FlowError, x as defineStep, y as defineMapStep, z as StepRegistration } from "./index-BURAYZui.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
-import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, S as createInMemoryStepGate, T as CreateWorkflowParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ReopenWorkflowParams, k as FinishWorkflowParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as CompleteStepParams, x as StepGateRequest, y as StepGate } from "./observability-CR9dEdLW.js";
+import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, S as createInMemoryStepGate, T as CreateWorkflowParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ReopenWorkflowParams, k as FinishWorkflowParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as CompleteStepParams, x as StepGateRequest, y as StepGate } from "./observability-3wVqt3tZ.js";
 import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-g7Ct0J6w.js";
 import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BdxIcc92.js";
 //#region src/core/registry.d.ts

package/dist/{observability-CR9dEdLW.d.ts → observability-3wVqt3tZ.d.ts}

@@ -320,7 +320,7 @@ declare function createRecordingObserver(): RecordingObserver;
  * The slice of a metrics API the engine's meter observer needs. Structural:
  * `@octabits-io/telemetry`'s meter and an OpenTelemetry `Meter`
  * both fit (the SDK's `createCounter`/`createHistogram` need a two-line
- * adapter, the framework's meter none).
+ * adapter).
  */
 interface FlowMeter {
   counter(name: string, options?: {

package/dist/postgres/index.d.ts

@@ -1,5 +1,5 @@
 import { W as WorkflowId } from "../index-BURAYZui.js";
-import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-CR9dEdLW.js";
+import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-3wVqt3tZ.js";
 import { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",
@@ -116,23 +116,23 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.52",
-    "@ai-sdk/mistral": "^4.0.42",
-    "@ai-sdk/openai": "^4.0.65",
-    "@ai-sdk/openai-compatible": "^3.0.48",
-    "@ai-sdk/provider": "^4.0.13",
-    "@testcontainers/postgresql": "^12.1.0",
-    "@types/node": "^26.5.1",
+    "@ai-sdk/anthropic": "^4.0.69",
+    "@ai-sdk/mistral": "^4.0.55",
+    "@ai-sdk/openai": "^4.0.82",
+    "@ai-sdk/openai-compatible": "^3.0.60",
+    "@ai-sdk/provider": "^4.0.20",
+    "@testcontainers/postgresql": "^12.2.0",
+    "@types/node": "^26.6.3",
     "@types/pg": "^8.23.1",
-    "ai": "^7.0.97",
-    "drizzle-orm": "^0.45.2",
-    "pg": "^8.23.0",
-    "pg-boss": "^12.30.0",
-    "testcontainers": "^12.1.0",
+    "ai": "^7.0.123",
+    "drizzle-orm": "^0.45.3",
+    "pg": "^8.23.1",
+    "pg-boss": "^12.35.0",
+    "testcontainers": "^12.2.0",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "zod": "^4.6.0"
+    "vitest": "^5.0.3",
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "tsdown",