octaflow 0.30.0 → 0.31.0

package/README.md

@@ -215,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, 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`) |
+| 🤖 | **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

@@ -12,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). */
@@ -222,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>>;
@@ -231,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. */

package/dist/ai/index.js

@@ -21,6 +21,7 @@ function createUsageAccumulator() {
 			total.cacheReadTokens += usage.cacheReadTokens;
 			total.cacheWriteTokens += usage.cacheWriteTokens;
 			if (usage.modelId) total.modelId = usage.modelId;
+			if (usage.provider) total.provider = usage.provider;
 			hasAny = true;
 		},
 		get() {
@@ -48,7 +49,8 @@ function createInstrumentedModel(model, accumulator) {
 					outputTokens: usage.outputTokens?.total ?? 0,
 					cacheReadTokens: usage.inputTokens?.cacheRead ?? 0,
 					cacheWriteTokens: usage.inputTokens?.cacheWrite ?? 0,
-					modelId: model.modelId
+					modelId: model.modelId,
+					provider: model.provider
 				});
 				return result;
 			},
@@ -63,7 +65,8 @@ function createInstrumentedModel(model, accumulator) {
 							outputTokens: u.outputTokens?.total ?? 0,
 							cacheReadTokens: u.inputTokens?.cacheRead ?? 0,
 							cacheWriteTokens: u.inputTokens?.cacheWrite ?? 0,
-							modelId: model.modelId
+							modelId: model.modelId,
+							provider: model.provider
 						});
 					}
 				} }));
@@ -440,7 +443,7 @@ function createAiWorkflowHooks(deps) {
 				usage
 			};
 		},
-		async onAfterStep({ workflowId, stepId, context }) {
+		async onAfterStep({ workflowId, stepId, workflow, step, context }) {
 			const acc = context.usage;
 			if (!acc.hasUsage()) return;
 			const usage = acc.get();
@@ -456,6 +459,19 @@ function createAiWorkflowHooks(deps) {
 				usage,
 				costMicros
 			});
+			deps.usage?.record({
+				kind: "model",
+				service: usage.provider ?? "model",
+				model: usage.modelId,
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				cacheReadTokens: usage.cacheReadTokens,
+				cacheWriteTokens: usage.cacheWriteTokens,
+				context: {
+					runId: String(workflowId),
+					feature: workflow?.type ?? step?.key ?? "workflow"
+				}
+			});
 		},
 		async onWorkflowCompleted({ workflowId, workflow }) {
 			if (!deps.usageRecorder.recordWorkflowDaily) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.30.0",
+  "version": "0.31.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",