@ultimat3/ai 30.9.0 → 31.0.0

package/src/gateway-providers.ts

@@ -3,7 +3,7 @@
 // core `breaker()` per provider: a provider down for an hour cost `attempts` calls plus backoff on
 // EVERY call; behind its breaker it costs `attempts × failures` per cooldown, then none.
 
-import type { Breaker, BreakerTicket, Random } from '@ultimat3/core';
+import type { Breaker, BreakerTicket, Random, RetryPolicy } from '@ultimat3/core';
 import {
   backoffDelay,
   breaker,
@@ -12,10 +12,10 @@ import {
   renderThrowable,
   settleWith,
   stringField,
+  systemClock,
   tryUseContext,
 } from '@ultimat3/core';
 import { AiProviderUnavailableError } from './errors';
-import type { RetryPolicy } from './gateway';
 import type { ModelId } from './models';
 import type { GenerateResult, Provider } from './provider';
 
@@ -33,17 +33,18 @@ export const DEFAULT_GATEWAY_BREAKER = Object.freeze({ failures: 5, cooldownMs:
 const PROVIDER_UNAVAILABLE = 'X_AI_PROVIDER_UNAVAILABLE';
 
 /**
- * Full jitter: a uniform pick from [0, exponential], capped BEFORE the roll — core's
- * `backoffDelay` with the gateway's own field names mapped onto it, and nothing else.
- * `gateway-backoff.test.ts` pins the refusal of a non-finite bound and the clamped negative base.
+ * The wait before `attempt + 1`: core's `backoffDelay` over core's `RetryPolicy`, every curve field
+ * the policy's own (`DEFAULT_GATEWAY_RETRY` is full jitter). `gateway-backoff.test.ts` pins the
+ * refusal of a non-finite bound and the clamped negative base.
  */
 export function backoffMs(policy: RetryPolicy, attempt: number, random?: Random): number {
   return backoffDelay({
     attempt,
-    base: policy.baseDelayMs,
-    max: policy.maxDelayMs,
-    curve: 'exponential',
-    jitter: 'full',
+    base: policy.base,
+    max: policy.max,
+    factor: policy.factor,
+    curve: policy.curve,
+    jitter: policy.jitter,
     random,
   });
 }
@@ -122,6 +123,12 @@ export interface AttemptInput {
 export async function attemptProviders(input: AttemptInput): Promise<GenerateResult> {
   const { model, retry } = input;
   const failures: string[] = [];
+  // Read once, and only compared when a budget is set: core's `retryLoop` rule — a wait that would
+  // end past `timeBudgetMs` is never started, across every provider of this call.
+  const startedAt = systemClock.monotonic();
+  const overruns = (delayMs: number): boolean =>
+    retry.timeBudgetMs !== undefined &&
+    systemClock.monotonic() - startedAt + delayMs > retry.timeBudgetMs;
   if (input.candidates.length === 0) {
     throw new AiProviderUnavailableError({
       model,
@@ -164,7 +171,12 @@ export async function attemptProviders(input: AttemptInput): Promise<GenerateRes
           exhausted(gate, ticket);
           break;
         }
-        await input.sleep(backoffMs(retry, attempt, input.random));
+        const delayMs = backoffMs(retry, attempt, input.random);
+        if (overruns(delayMs)) {
+          exhausted(gate, ticket);
+          throw new AiProviderUnavailableError({ model, attempts: failures });
+        }
+        await input.sleep(delayMs);
       }
     }
   }

package/src/gateway.ts

@@ -4,8 +4,8 @@
 // budgeted, and cost-accounted in integer minor units. Everything an app does with a model
 // goes through here, so budgets and accounting cannot be bypassed by a stray fetch.
 
-import type { Breaker, Random } from '@ultimat3/core';
-import { fingerprint, finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import type { Breaker, Random, RetryPolicy } from '@ultimat3/core';
+import { fingerprint, finiteCount, finiteOption, logger, renderThrowable } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { billedOf } from './billed';
 import type { BudgetKeys, BudgetLimits, BudgetReservation, BudgetStore } from './budget';
@@ -39,24 +39,15 @@ export interface GatewayCache {
 }
 
 /**
- * A gateway's retry budget. NOT core's `RetryPolicy`, and deliberately still its own declaration:
- * these three field names are what an app writes in `providerGateway({ retry })`, so renaming them
- * onto `base`/`max`/`jitter` would break every caller for no behaviour. What WAS a duplicate is the
- * arithmetic, and that is gone — `backoffMs` is core's `backoffDelay` with this shape mapped onto
- * it, so there is one curve in the framework and one place a jitter bug can live.
+ * The gateway's retry when `providerGateway({ retry })` names none. Core's `RetryPolicy`, the one
+ * retry shape in the framework since 31.0.0: full jitter, because N workers backing off a rate limit
+ * in step reproduce it.
  */
-export interface RetryPolicy {
-  /** Total attempts including the first. */
-  readonly attempts: number;
-  /** First backoff in ms; doubled per attempt with full jitter. */
-  readonly baseDelayMs: number;
-  readonly maxDelayMs: number;
-}
-
 export const DEFAULT_GATEWAY_RETRY: RetryPolicy = {
   attempts: 3,
-  baseDelayMs: 500,
-  maxDelayMs: 8_000,
+  base: 500,
+  max: 8_000,
+  jitter: 'full',
 };
 
 export type { GatewayBreakerOption } from './gateway-providers';
@@ -68,6 +59,10 @@ export interface ProviderGatewayInput {
   readonly budget?: BudgetLimits;
   readonly budgetStore?: BudgetStore;
   readonly cache?: GatewayCache;
+  /**
+   * Core's `RetryPolicy`, read per provider: `attempts` each, `base`/`max`/`curve`/`factor`/`jitter`
+   * for the wait, and `timeBudgetMs` across the whole call, every provider included.
+   */
   readonly retry?: RetryPolicy;
   readonly defaultModel?: ModelId;
   /** Overridable so a test can run backoff without waiting. */
@@ -88,7 +83,7 @@ export interface ProviderGatewayInput {
 }
 
 export interface Gateway {
-  /** The wire formats of the providers serving `model` — what `llm.sampling.ignored` is read from. */
+  /** The wire formats of the providers serving `model` — what `ultimate.llm.sampling.ignored` is read from. */
   samplingWires?(model: ModelId): readonly SamplingWire[];
   /**
    * Whether a provider serving `model` would send a hinted request with a cache mark — so its
@@ -142,10 +137,14 @@ class GatewayImpl implements Gateway {
     // `X_AI_PROVIDER_UNAVAILABLE` with an EMPTY attempt list — measured, "no provider could serve
     // model <id> ()" for a provider that was never asked. A floor of 1 because the field
     // is documented as total attempts INCLUDING the first, so zero of them is not a policy.
-    // `baseDelayMs` and `maxDelayMs` are deliberately not screened here: `backoffDelay` refuses a
-    // non-finite one already, and a NEGATIVE base is clamped to a zero wait on purpose
-    // (`gateway-backoff.test.ts` pins it), which a count check here would start refusing.
+    // `base` and `max` are deliberately not screened here: `backoffDelay` refuses a non-finite one
+    // already, and a NEGATIVE base is clamped to a zero wait on purpose (`gateway-backoff.test.ts`
+    // pins it), which a count check here would start refusing. The budget IS screened: a NaN one
+    // compares false against every elapsed time, so it would never stop anything.
     finiteCount('gateway', 'retry.attempts', this.retry.attempts, 1);
+    if (this.retry.timeBudgetMs !== undefined) {
+      finiteOption('gateway', 'retry.timeBudgetMs', this.retry.timeBudgetMs);
+    }
     // Screened here, under the config's own key, rather than by the ledger `callLedger` builds:
     // that refused on the first CALL and named `the AI budget`, not the `gateway` to edit.
     if (config.budget !== undefined) assertFiniteLimits(config.budget, 'gateway', 'budget.');

package/src/index.ts

@@ -46,7 +46,7 @@ export {
   LlmTruncatedError,
 } from './answer-errors';
 export type { Billed } from './billed';
-export { BILLED_META, billedOf } from './billed';
+export { billedOf } from './billed';
 export type {
   BudgetKeys,
   BudgetLedger,
@@ -65,21 +65,6 @@ export {
   memoryBudgetStore,
   withBudget,
 } from './budget';
-export type {
-  AiDocumentBlock,
-  AiDocumentSource,
-  AiImageBlock,
-  AiImageSource,
-  AiMediaBlock,
-  ImageMediaType,
-} from './content-blocks';
-export {
-  IMAGE_MEDIA_TYPES,
-  IMAGE_TOKEN_ESTIMATE,
-  isMediaBlock,
-  MAX_DOCUMENT_BASE64_CHARS,
-  MAX_IMAGE_BASE64_CHARS,
-} from './content-blocks';
 export type { ContentRefusal } from './content-errors';
 export { AiContentUnsupportedError } from './content-errors';
 export { AiContextOverflowError } from './context-overflow';
@@ -101,12 +86,6 @@ export {
   AgentMaxTurnsError,
   AgentToolUnexposedError,
   AiBudgetExceededError,
-  AiGatewayMissingError,
-  AiKeyMissingError,
-  AiModelUnknownError,
-  AiPromptRenderError,
-  AiPromptSecretError,
-  AiPromptVersionError,
   AiProviderUnavailableError,
   AiRequestInvalidError,
   AiTransportError,
@@ -119,17 +98,8 @@ export {
 } from './errors';
 export { AI_ERROR_RETRY } from './errors-retry';
 export type { EvalBaseline, Regression } from './eval-baseline';
+export { baselinePath, RECORD_ENV, readBaseline, recordingBaselines } from './eval-baseline';
 export {
-  baselinePath,
-  describeRegression,
-  RECORD_ENV,
-  readBaseline,
-  recordingBaselines,
-  regressionsAgainst,
-  writeBaseline,
-} from './eval-baseline';
-export {
-  EvalBaselineInvalidError,
   EvalBaselineMissingError,
   EvalMissingError,
   EvalRecordingError,
@@ -148,24 +118,16 @@ export type {
   EvaluatedAgent,
   PromptEvalInput,
 } from './evals';
-export {
-  baselineFrom,
-  defineEval,
-  describeEvals,
-  promptsWithoutEvals,
-  resetEvals,
-} from './evals';
+export { defineEval, describeEvals, promptsWithoutEvals, resetEvals } from './evals';
 export type { AiFetch } from './fetch-seam';
 export type {
   Gateway,
   GatewayBreakerOption,
   GatewayCache,
   ProviderGatewayInput,
-  RetryPolicy,
 } from './gateway';
 export {
   backoffMs,
-  DEFAULT_GATEWAY_BREAKER,
   DEFAULT_GATEWAY_RETRY,
   isRetryable,
   promptCacheKey,
@@ -173,7 +135,6 @@ export {
 } from './gateway';
 export type { HiveDef, HiveSplitArgs } from './hive';
 export { hive } from './hive';
-export { HiveEmptyError } from './hive-errors';
 export type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
 export type { InProcessToolDef } from './in-process-tool';
 export { inProcessTool } from './in-process-tool';
@@ -182,7 +143,6 @@ export { LlmTextChunk, llm } from './llm';
 export type { LlmCache, LlmScopeArgs, LlmSemanticCache } from './llm-cache';
 export type { LlmStreamChunk } from './llm-stream';
 export type { ModelSource } from './model-resolve';
-export { AiModelUnresolvedError } from './model-resolve';
 export type {
   ContentKind,
   DeclaredReasoning,
@@ -193,10 +153,7 @@ export type {
   ThinkingMode,
 } from './models';
 export {
-  assertModel,
-  EFFORTS,
   isModelRegistered,
-  modelIds,
   modelSpec,
   moreCapableThan,
   registeredModels,
@@ -207,12 +164,7 @@ export type { OpenAiProviderInput } from './openai-provider';
 export { openAiProvider } from './openai-provider';
 export type { PostgresVectorStore, PostgresVectorStoreInput } from './pg-vector';
 export { postgresVectorStore } from './pg-vector';
-export type {
-  PgHybridArgs,
-  PgSearchArgs,
-  PgVectorRowInput,
-  PgVectorTable,
-} from './pg-vector-sql';
+export type { PgSearchArgs, PgVectorTable } from './pg-vector-sql';
 export {
   conditionsSql,
   ddlSql,
@@ -220,14 +172,7 @@ export {
   searchSql,
 } from './pg-vector-sql';
 export type { DefinePromptInput, Prompt, PromptVars } from './prompt';
-export {
-  definePrompt,
-  describePrompts,
-  getPrompt,
-  promptHash,
-  promptVersions,
-  resetPrompts,
-} from './prompt';
+export { definePrompt, describePrompts, promptHash, resetPrompts } from './prompt';
 export type {
   CacheWire,
   PromptCacheHint,
@@ -264,14 +209,11 @@ export {
   costOf,
   estimateCost,
   estimateInputTokens,
-  estimateTextTokens,
   estimateTokens,
   isTruncated,
   messageText,
   parseMessage,
-  requiresStreaming,
   STREAM_ONLY_MAX_TOKENS,
-  totalTokens,
 } from './provider';
 export type {
   AssembledContext,
@@ -280,13 +222,7 @@ export type {
   Reranker,
   RetrieveInput,
 } from './rag';
-export {
-  assembleContext,
-  chunkDocument,
-  indexDocument,
-  passthroughReranker,
-  retrieve,
-} from './rag';
+export { assembleContext, chunkDocument, indexDocument, retrieve } from './rag';
 export { assertNoSecrets } from './redaction';
 export type { RemoteEmbedder, RemoteEmbedderInput } from './remote-embedder';
 export { remoteEmbedder } from './remote-embedder';
@@ -339,4 +275,3 @@ export type {
 export { fuse, memoryVectorStore } from './vector';
 export type { VectorScope } from './vector-scope';
 export { NO_VECTOR_TENANT, tenantOf, UNSCOPED, VectorUnscopedError } from './vector-scope';
-export type { StreamState } from './wire';

package/src/llm-answer.ts

@@ -0,0 +1,125 @@
+// Single responsibility: what one answered `llm()` turn amounts to — its span attributes, its
+// `onCall` report, whether a value fits the declared `output`, and the one streamed turn's answer
+// under the same rules. Split from ./llm at its line ceiling.
+
+import type { Span, SpanAttributes } from '@ultimat3/core';
+import { SEMCONV } from '@ultimat3/core';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
+import { runTotal } from './agent-usage';
+import { LlmTruncatedError } from './answer-errors';
+import { LlmRefusedError, LlmStreamInvalidError } from './errors';
+import type { Gateway } from './gateway';
+import type { LlmDef } from './llm-def';
+import type { LlmSink } from './llm-stream';
+import { streamOneTurn } from './llm-stream';
+import { moreCapableThan } from './models';
+import type { PromptVars } from './prompt';
+import type { GenerateRequest, GenerateResult } from './provider';
+import { isTruncated } from './provider';
+import { parseJsonish } from './respond';
+import type { RunMeter } from './run-meter';
+
+/**
+ * What one answered turn puts on the span. The provider that answered is the half the LLM-gateway
+ * table called "a fallback is recorded in the span, never silent": fallback in this framework is
+ * across PROVIDERS serving one model, never across models, and until the gateway stamped the
+ * provider that answered, a fallback was exactly as silent as no fallback at all. It lands as
+ * semconv's `gen_ai.provider.name`, with the token usage, when the call settles (`llm-instrument.ts`).
+ */
+export function answerAttributes(result: GenerateResult): SpanAttributes {
+  return {
+    'ultimate.llm.stop': result.stopReason,
+    'ultimate.llm.cost.minor': result.cost.minor,
+    [SEMCONV.genAiProviderName]: result.provider ?? 'unknown',
+    [SEMCONV.genAiResponseModel]: result.model,
+  };
+}
+
+/**
+ * One streamed turn, from the same declaration and under the same rules — with one difference
+ * that is forced rather than chosen: no repair turn. The tokens are already on the consumer's
+ * screen, so a second answer would be two answers to one question; a stream gets one attempt and
+ * `X_LLM_STREAM_INVALID` names the non-streaming call as the fix.
+ *
+ * The stop reason is still read BEFORE the answer, for the reason it always was: a refusal
+ * carries empty or partial content and parsing it first reports a schema disagreement that is not
+ * one. Truncation is the same call it is on the non-streaming path.
+ */
+export async function streamedAnswer<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: LlmDef<TInput, TOutput, V>,
+  name: string,
+  gateway: Gateway,
+  request: GenerateRequest,
+  sink: LlmSink,
+  span: Span,
+  meter: RunMeter,
+): Promise<InferOutput<TOutput>> {
+  const { output } = def;
+  const result = await meter.call(streamOneTurn(gateway, request, sink));
+  span.setAttributes({ 'ultimate.llm.attempts': 1, ...answerAttributes(result) });
+  await observeCall(def, meter, result, 1, undefined);
+  if (result.stopReason === 'refusal') {
+    throw new LlmRefusedError({
+      prompt: name,
+      model: result.model,
+      alternative: moreCapableThan(result.model, request),
+      category: result.stopDetails?.category,
+      explanation: result.stopDetails?.explanation,
+    });
+  }
+  if (isTruncated(result.stopReason)) {
+    throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
+  }
+  // Prose, and its JSON parse when it has one. Both, because a stream carries no `respond` tool
+  // to tell them apart: `output: t.string` is satisfied by the text itself, and an object schema
+  // by what the text parses to — trying only one of the two makes a legal declaration unusable.
+  const parsed = await accept(output, parseJsonish(result.text));
+  if (parsed !== undefined) return parsed.value;
+  const fallback = await validateAsync(output, result.text);
+  if (fallback.issues === undefined) return fallback.value;
+  throw new LlmStreamInvalidError({
+    prompt: name,
+    issues: formatIssues(fallback.issues).join('; '),
+  });
+}
+
+/** One provider call, reported to the declaration's `onCall`. Awaited; a throw fails the call. */
+export async function observeCall<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: LlmDef<TInput, TOutput, V>,
+  meter: RunMeter,
+  result: GenerateResult,
+  attempt: number,
+  repairOf: readonly string[] | undefined,
+): Promise<void> {
+  if (def.onCall === undefined) return;
+  await def.onCall({
+    attempt,
+    model: result.model,
+    provider: result.provider,
+    stopReason: result.stopReason,
+    usage: result.usage,
+    cost: result.cost,
+    ...(result.costExact === undefined ? {} : { costExact: result.costExact }),
+    ...(repairOf === undefined ? {} : { repairOf }),
+    run: runTotal(result.model, undefined, meter.total()),
+  });
+}
+
+/** `undefined` for "does not fit". Wrapped so a legitimately falsy value is still a hit. */
+export async function accept<TOutput extends StandardSchemaV1>(
+  schema: TOutput,
+  value: unknown,
+): Promise<{ readonly value: InferOutput<TOutput> } | undefined> {
+  if (value === undefined) return undefined;
+  const parsed = await validateAsync(schema, value);
+  return parsed.issues === undefined ? { value: parsed.value } : undefined;
+}

package/src/llm-cache.ts

@@ -66,7 +66,9 @@ export interface PromptCache {
 
 /**
  * The partition a declaration that named none gets: the narrowest key this call can prove, which
- * is the actor itself. Verbatim the shape `@ultimat3/query`'s `actorAuthority` builds, for the
+ * is the actor itself AND its grant set — one id is not one grant set (a role revoked inside the
+ * `ttl`, one identity holding two role sets), and `vars()` may read `ctx.actor.roles`, so an
+ * id-only key handed a member an admin's answer. Verbatim the shape `@ultimat3/query`'s `actorAuthority` builds, for the
  * same reason it is JSON rather than a joined string — an actor id is app data and may carry any
  * separator, and a value that can spell a boundary can spell somebody else's.
  *
@@ -79,9 +81,21 @@ export interface PromptCache {
  * everywhere else in the framework.
  */
 function actorScope(ctx: Ctx): string {
-  return JSON.stringify([ctx.actor.kind, ctx.actor.id, ctx.actor.orgId ?? null]);
+  const { actor } = ctx;
+  return JSON.stringify([
+    actor.kind,
+    actor.id,
+    actor.orgId ?? null,
+    grantSet(actor.roles),
+    grantSet(actor.scopes),
+    grantSet(actor.permissions),
+    actor.onBehalfOf === undefined ? null : [actor.onBehalfOf.actorKind, actor.onBehalfOf.actorId],
+  ]);
 }
 
+/** Sorted, de-duplicated: a set, so two orderings of one grant are one partition. */
+const grantSet = (values: readonly string[]): readonly string[] => [...new Set(values)].sort();
+
 /**
  * The semantic cache for one declaration, or `undefined` when none was declared. The instance
  * is partitioned by prompt VERSION as well as scope, which is what makes "editing a prompt

package/src/llm-def.ts

@@ -61,7 +61,7 @@ export interface LlmDef<
    * `temperature` (0 to 2) and `seed` (a whole number), for a call that should answer the same way
    * twice — a verifier, a classifier. Sent only to a model whose row takes them
    * (`registerModel({ sampling })`); to any other they are NOT sent, because a reasoning model
-   * answers one with a 400 — the `llm.sampling.ignored` span attribute names what was left out.
+   * answers one with a 400 — the `ultimate.llm.sampling.ignored` span attribute names what was left out.
    * `seed` exists on the chat-completions wire only, and is best effort where it exists.
    */
   readonly temperature?: number;

package/src/llm-instrument.ts

@@ -0,0 +1,100 @@
+// Single responsibility: what one `llm()` call reports when it settles — the `ai.llm` event on
+// core's instrumentation bus and the OpenTelemetry gen_ai usage on its span — on BOTH paths, a
+// cache hit included. Split from ./llm at its line ceiling; the meter is the one place every
+// provider call passes, so it is where the answering provider and model are read.
+
+import type { Span } from '@ultimat3/core';
+import { instrument, SEMCONV, subscribed } from '@ultimat3/core';
+import type { GenerateResult } from './provider';
+import type { RunMeter } from './run-meter';
+
+/** What a cache hit, or a call no provider ever answered, reports as its provider. */
+export const NO_PROVIDER = 'unknown';
+
+export interface LlmReport {
+  /** The run's meter, watched: hand THIS to every provider call so the answerer is seen. */
+  readonly meter: RunMeter;
+  /** Settle the call: usage onto the span, `ai.llm` onto the bus. Never throws of its own. */
+  settle(outcome: { readonly cacheHit: boolean; readonly error?: unknown }): void;
+}
+
+/** Start reporting one `llm()` call, requested of `model`, under `span`. */
+export function llmReport(span: Span, model: string, meter: RunMeter): LlmReport {
+  const startedAt = performance.now();
+  let provider = NO_PROVIDER;
+  let answeredBy = model;
+  const watched: RunMeter = {
+    ...meter,
+    call: async (work: Promise<GenerateResult>): Promise<GenerateResult> => {
+      const result = await meter.call(work);
+      provider = result.provider ?? NO_PROVIDER;
+      answeredBy = result.model;
+      return result;
+    },
+  };
+  return {
+    meter: watched,
+    settle({ cacheHit, error }) {
+      // The RUN's usage — every attempt, repair turns included — not the last answer's.
+      const usage = meter.total()?.usage;
+      const inputTokens = usage?.inputTokens ?? 0;
+      const outputTokens = usage?.outputTokens ?? 0;
+      span.setAttributes({
+        [SEMCONV.genAiProviderName]: provider,
+        [SEMCONV.genAiResponseModel]: answeredBy,
+        [SEMCONV.genAiUsageInputTokens]: inputTokens,
+        [SEMCONV.genAiUsageOutputTokens]: outputTokens,
+      });
+      if (!subscribed('ai.llm')) return;
+      instrument('ai.llm', {
+        provider,
+        model: answeredBy,
+        inputTokens,
+        outputTokens,
+        cacheHit,
+        durationMs: performance.now() - startedAt,
+        ...(error === undefined ? {} : { error }),
+      });
+    },
+  };
+}
+
+/**
+ * ONE model call an `agent()` makes — a turn, or a compaction's summary — as `ai.llm`: the token
+ * metric is per call, and an agent's spend would otherwise reach no subscriber. Emitted on both
+ * paths; a failed call reports the model it ASKED for, no provider, and no tokens.
+ */
+export async function reportedCall(
+  model: string,
+  call: Promise<GenerateResult>,
+): Promise<GenerateResult> {
+  const startedAt = performance.now();
+  let result: GenerateResult;
+  try {
+    result = await call;
+  } catch (error) {
+    if (subscribed('ai.llm')) {
+      instrument('ai.llm', {
+        provider: NO_PROVIDER,
+        model,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheHit: false,
+        durationMs: performance.now() - startedAt,
+        error,
+      });
+    }
+    throw error;
+  }
+  if (subscribed('ai.llm')) {
+    instrument('ai.llm', {
+      provider: result.provider ?? NO_PROVIDER,
+      model: result.model,
+      inputTokens: result.usage.inputTokens,
+      outputTokens: result.usage.outputTokens,
+      cacheHit: false,
+      durationMs: performance.now() - startedAt,
+    });
+  }
+  return result;
+}