feat(api): global LLM usage observer hook

Hosts (wilds-ai foundation_usage_events, billing dashboards, BI
pipelines) previously had to wrap every agentos LLM callsite in their
own emitter to get per-call cost telemetry. wilds-ai had ~50+
callsites and the duplication was already biting.

New module observers.ts exposes setGlobalLlmObserver(callback). Hosts
register once at boot:

  setGlobalLlmObserver((event) => {
    recordFoundationUsageEvent({
      meterKey: event.source ?? 'llm.call',
      providerKey: event.provider,
      modelKey: event.model,
      quantity: event.usage.costUSD ?? 0,
      unit: 'usd',
    });
  });

generateText + streamText now fire fireLlmUsageObserver on every
successful return / stream finalize. Payload carries resolved
provider, model, full TokenUsage (including costUSD + cache tokens),
caller-supplied source label, finishReason, and surface so the host
can route by meter / disambiguate streaming vs non-streaming.

Fire-and-forget: synchronous + async observer errors are swallowed
so a misbehaving observer can never crash the LLM call path.

New source?: string option on GenerateTextOptions lets callers tag
each call with a meter label (narrator_turn, companion_reply,
world_compile_job, etc.) without threading their own context.

10 unit tests on observers.ts pass. generateText + streamText return
paths instrumented at every success exit.

Author: jddunn

src/api/agency-provenance.test.ts …/api/__tests__/agency-provenance.test.tssrc/api/agency-provenance.test.ts renamed to src/api/__tests__/agency-provenance.test.ts src/api/agency-provenance.test.ts renamed to src/api/__tests__/agency-provenance.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Tests for the global LLM usage observer registration and dispatch.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import {
+  setGlobalLlmObserver,
+  getGlobalLlmObserver,
+  fireLlmUsageObserver,
+} from '../observers.js';
+import type { LlmUsageEvent } from '../observers.js';
+
+function makeEvent(overrides?: Partial<LlmUsageEvent>): LlmUsageEvent {
+  return {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-6',
+    usage: {
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      costUSD: 0.012,
+    },
+    source: 'unit-test',
+    finishReason: 'stop',
+    surface: 'generateText',
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  setGlobalLlmObserver(null);
+});
+
+afterEach(() => {
+  setGlobalLlmObserver(null);
+});
+
+describe('setGlobalLlmObserver / getGlobalLlmObserver', () => {
+  it('returns null when no observer is registered', () => {
+    expect(getGlobalLlmObserver()).toBeNull();
+  });
+
+  it('registers and retrieves the observer', () => {
+    const obs = vi.fn();
+    setGlobalLlmObserver(obs);
+    expect(getGlobalLlmObserver()).toBe(obs);
+  });
+
+  it('clears the observer when null is passed', () => {
+    setGlobalLlmObserver(vi.fn());
+    setGlobalLlmObserver(null);
+    expect(getGlobalLlmObserver()).toBeNull();
+  });
+
+  it('replaces an existing observer (last writer wins)', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    setGlobalLlmObserver(first);
+    setGlobalLlmObserver(second);
+    expect(getGlobalLlmObserver()).toBe(second);
+  });
+});
+
+describe('fireLlmUsageObserver', () => {
+  it('no-ops when no observer is registered (does not throw)', () => {
+    expect(() => fireLlmUsageObserver(makeEvent())).not.toThrow();
+  });
+
+  it('passes the full event payload to the observer', () => {
+    const obs = vi.fn();
+    setGlobalLlmObserver(obs);
+    const event = makeEvent({ source: 'narrator_turn' });
+    fireLlmUsageObserver(event);
+    expect(obs).toHaveBeenCalledTimes(1);
+    expect(obs).toHaveBeenCalledWith(event);
+  });
+
+  it('swallows synchronous errors from the observer', () => {
+    setGlobalLlmObserver(() => {
+      throw new Error('observer crash');
+    });
+    expect(() => fireLlmUsageObserver(makeEvent())).not.toThrow();
+  });
+
+  it('swallows promise rejections from async observers', async () => {
+    setGlobalLlmObserver(async () => {
+      throw new Error('async observer crash');
+    });
+    expect(() => fireLlmUsageObserver(makeEvent())).not.toThrow();
+    // Yield to the microtask queue so the rejection lands + gets swallowed.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it('forwards source label and surface so hosts can route by meter', () => {
+    const obs = vi.fn();
+    setGlobalLlmObserver(obs);
+    fireLlmUsageObserver(makeEvent({ source: 'companion_reply', surface: 'streamText' }));
+    expect(obs.mock.calls[0][0].source).toBe('companion_reply');
+    expect(obs.mock.calls[0][0].surface).toBe('streamText');
+  });
+
+  it('forwards cache-token fields when present on usage', () => {
+    const obs = vi.fn();
+    setGlobalLlmObserver(obs);
+    fireLlmUsageObserver(
+      makeEvent({
+        usage: {
+          promptTokens: 1000,
+          completionTokens: 50,
+          totalTokens: 1050,
+          costUSD: 0.005,
+          cacheReadTokens: 800,
+          cacheCreationTokens: 200,
+        },
+      }),
+    );
+    expect(obs.mock.calls[0][0].usage.cacheReadTokens).toBe(800);
+    expect(obs.mock.calls[0][0].usage.cacheCreationTokens).toBe(200);
+  });
+});

src/api/__tests__/observers.test.ts

@@ -14,6 +14,7 @@
 import { randomUUID } from 'node:crypto';
 import { resolveModelOption, resolveProvider, createProviderManager } from './model.js';
 import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { fireLlmUsageObserver } from './observers.js';
 import {
   hostPolicyToRouteParams,
   mergeRequiredCapabilities,
@@ -346,6 +347,15 @@ export interface GenerateTextOptions {
    * @param fallbackProvider - The provider identifier being tried next.
    */
   onFallback?: (error: Error, fallbackProvider: string) => void;
+  /**
+   * Optional source label forwarded to the global LLM usage observer
+   * registered via {@link setGlobalLlmObserver}. Hosts use this to
+   * tag the emitted telemetry row with a caller-defined meter key
+   * (e.g. 'narrator_turn', 'companion_reply', 'world_compile_job').
+   *
+   * Has no effect when no observer is registered.
+   */
+  source?: string;
   /**
    * Optional model router for intelligent provider/model selection.
    * When provided, the router's `selectModel()` is called before provider
@@ -1304,6 +1314,18 @@ export async function generateText(opts: GenerateTextOptions): Promise<GenerateT
           span?.setAttribute('agentos.api.finish_reason', choice.finishReason ?? 'stop');
           span?.setAttribute('agentos.api.tool_calls', allToolCalls.length);
           attachUsageAttributes(span, totalUsage);
+          // 2026-05-29 — fire the global LLM usage observer so hosts
+          // (wilds-ai foundation_usage_events, billing dashboards) get
+          // the resolved provider + model + cost without wrapping every
+          // callsite. No-op when no observer is registered.
+          fireLlmUsageObserver({
+            provider: resolved.providerId,
+            model: resolved.modelId,
+            usage: totalUsage,
+            source: opts.source,
+            finishReason: choice.finishReason ?? 'stop',
+            surface: 'generateText',
+          });
           return {
             provider: resolved.providerId,
             model: resolved.modelId,
@@ -1417,6 +1439,14 @@ export async function generateText(opts: GenerateTextOptions): Promise<GenerateT
         span?.setAttribute('agentos.api.finish_reason', choice.finishReason ?? 'stop');
         span?.setAttribute('agentos.api.tool_calls', allToolCalls.length);
         attachUsageAttributes(span, totalUsage);
+        fireLlmUsageObserver({
+          provider: resolved.providerId,
+          model: resolved.modelId,
+          usage: totalUsage,
+          source: opts.source,
+          finishReason: choice.finishReason ?? 'stop',
+          surface: 'generateText',
+        });
         return {
           provider: resolved.providerId,
           model: resolved.modelId,
@@ -1433,6 +1463,14 @@ export async function generateText(opts: GenerateTextOptions): Promise<GenerateT
       span?.setAttribute('agentos.api.finish_reason', 'tool-calls');
       span?.setAttribute('agentos.api.tool_calls', allToolCalls.length);
       attachUsageAttributes(span, totalUsage);
+      fireLlmUsageObserver({
+        provider: resolved.providerId,
+        model: resolved.modelId,
+        usage: totalUsage,
+        source: opts.source,
+        finishReason: 'tool-calls',
+        surface: 'generateText',
+      });
       return {
         provider: resolved.providerId,
         model: resolved.modelId,

src/api/generateText.ts

@@ -38,6 +38,13 @@ export { embedText } from './embedText.js';
 export { generateImage } from './generateImage.js';
 export { transferStyle } from './transferStyle.js';
 
+// --- LLM usage observer (global cost / telemetry hook) ---
+export {
+  setGlobalLlmObserver,
+  type LlmUsageEvent,
+  type LlmUsageObserver,
+} from './observers.js';
+
 // --- Global default provider config ---
 export {
   setDefaultProvider,

src/api/index.ts

@@ -0,0 +1,151 @@
+/**
+ * @file observers.ts
+ * @description Global observer registration for AgentOS LLM usage events.
+ *
+ * Hosts (Next.js apps, CLI tools, long-running services) register a
+ * single callback at boot time. Every {@link generateText} /
+ * {@link generateObject} / streamText / streamObject completion fires
+ * the callback with the resolved provider, model, usage metrics, and
+ * caller-supplied source label.
+ *
+ * Rationale: pre-2026-05-29, every host that wanted per-call cost
+ * telemetry had to wrap each LLM callsite in its own emitter. wilds-ai
+ * (50+ callsites across narrator / companion / world-compile / asset
+ * judge / etc.) was the canonical example of this duplication. The
+ * global observer pattern lets the host register once:
+ *
+ *   import { setGlobalLlmObserver } from '@framers/agentos';
+ *   setGlobalLlmObserver((event) => {
+ *     recordFoundationUsageEvent({
+ *       meterKey: event.source ?? 'llm.call',
+ *       providerKey: event.provider,
+ *       modelKey: event.model,
+ *       quantity: event.usage.costUSD ?? 0,
+ *       unit: 'usd',
+ *       ...
+ *     });
+ *   });
+ *
+ * And every downstream agentos call automatically flows through. No
+ * per-callsite wrappers required.
+ *
+ * Observer call is fire-and-forget: errors thrown by the host callback
+ * are swallowed so telemetry never crashes the LLM call path.
+ *
+ * @module agentos/api/observers
+ */
+import type { TokenUsage } from './generateText.js';
+
+/**
+ * Payload delivered to a registered usage observer once an LLM call
+ * resolves. Mirrors the agentos-side fields that downstream cost /
+ * billing systems care about.
+ */
+export interface LlmUsageEvent {
+  /** Resolved provider id (e.g. 'openai', 'anthropic', 'openrouter'). */
+  provider: string;
+  /** Resolved model id (e.g. 'gpt-4o', 'claude-sonnet-4-6'). */
+  model: string;
+  /**
+   * Aggregated token usage for the call — promptTokens, completionTokens,
+   * totalTokens, costUSD, cacheReadTokens, cacheCreationTokens.
+   * Mirrors the `usage` field on the GenerateText/Object result.
+   */
+  usage: TokenUsage;
+  /**
+   * Opt-in source label set by the caller via the `source` option
+   * (e.g. 'narrator_turn', 'companion_reply', 'world_compile_job').
+   * Hosts use this to tag emitted rows with their own meter_key.
+   */
+  source?: string;
+  /**
+   * Mirrors the `finishReason` on the GenerateText result so observers
+   * can distinguish a clean stop from a token-cap truncation.
+   */
+  finishReason?: string;
+  /**
+   * Which agentos surface fired the event. Lets a single observer
+   * route generateText, generateObject, generateImage, embedText, etc.
+   * into different meters when needed.
+   */
+  surface:
+    | 'generateText'
+    | 'generateObject'
+    | 'streamText'
+    | 'streamObject'
+    | 'embedText'
+    | 'generateImage';
+}
+
+/**
+ * Observer callback signature. May return a promise; agentos waits on
+ * it only with `void` (no backpressure on the LLM call path).
+ */
+export type LlmUsageObserver = (event: LlmUsageEvent) => void | Promise<void>;
+
+let globalObserver: LlmUsageObserver | null = null;
+
+/**
+ * Register (or clear) the process-wide LLM usage observer.
+ *
+ * Hosts typically call this once at app boot:
+ *
+ *   ```ts
+ *   setGlobalLlmObserver((event) => {
+ *     recordFoundationUsageEvent({
+ *       meterKey: event.source ?? 'llm.call',
+ *       providerKey: event.provider,
+ *       modelKey: event.model,
+ *       quantity: event.usage.costUSD ?? 0,
+ *       unit: 'usd',
+ *     });
+ *   });
+ *   ```
+ *
+ * Passing `null` clears the observer (useful in tests).
+ *
+ * @param observer - The observer callback, or null to clear.
+ */
+export function setGlobalLlmObserver(observer: LlmUsageObserver | null): void {
+  globalObserver = observer;
+}
+
+/**
+ * Returns the currently-registered global observer, or null when
+ * unregistered. Exposed so internal agentos code can short-circuit
+ * the dispatcher when nothing is wired (saves the allocation +
+ * try/catch on every LLM call).
+ *
+ * @internal
+ */
+export function getGlobalLlmObserver(): LlmUsageObserver | null {
+  return globalObserver;
+}
+
+/**
+ * Internal dispatcher called by every agentos LLM-resolving surface
+ * (generateText/generateObject/etc.) immediately before returning to
+ * the caller. Fire-and-forget — errors thrown by the host observer
+ * are caught + logged to stderr so a misbehaving observer can never
+ * crash the LLM call path.
+ *
+ * No-op when no observer is registered.
+ *
+ * @internal
+ */
+export function fireLlmUsageObserver(event: LlmUsageEvent): void {
+  const cb = globalObserver;
+  if (!cb) return;
+  try {
+    const result = cb(event);
+    if (result && typeof (result as Promise<void>).then === 'function') {
+      void (result as Promise<void>).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn('[agentos.onUsage] observer promise rejected:', err);
+      });
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('[agentos.onUsage] observer threw synchronously:', err);
+  }
+}

src/api/observers.ts

@@ -10,6 +10,7 @@
 import { randomUUID } from 'node:crypto';
 import { resolveModelOption, resolveProvider, createProviderManager } from './model.js';
 import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { fireLlmUsageObserver } from './observers.js';
 import { hostPolicyToRouteParams, mergeRequiredCapabilities } from './runtime/hostPolicy.js';
 import { adaptTools } from './runtime/toolAdapter.js';
 import {
@@ -832,6 +833,22 @@ export function streamText(opts: GenerateTextOptions): StreamTextResult {
         status: metricStatus,
         usage: toTurnMetricUsage(usage),
       });
+      // 2026-05-29 — fire the global LLM usage observer with the
+      // finalized stream usage. Same hook generateText fires; hosts
+      // (wilds-ai foundation_usage_events, billing dashboards) get
+      // one consistent stream of events whether the caller used
+      // generateText or streamText. No-op when no observer is
+      // registered.
+      if (metricStatus !== 'error') {
+        fireLlmUsageObserver({
+          provider: recordedProviderId ?? '',
+          model: recordedModelId ?? '',
+          usage,
+          source: opts.source,
+          finishReason: allToolCalls.length > 0 && !finalText ? 'tool-calls' : 'stop',
+          surface: 'streamText',
+        });
+      }
     }
   }