@metaobjectsdev/ai-runtime 0.10.0

package/dist/call-loop.d.ts

@@ -0,0 +1,43 @@
+import { type LlmRecorder, type LlmCallInput, type LlmCallRow, type RecordLlmCallResult } from "@metaobjectsdev/runtime-ts";
+import { type Clock, type IdGen, type LlmClient, type LlmRequest, type LlmCompletion } from "./client.js";
+import type { CostFn } from "./cost.js";
+export interface RunLlmCallInput {
+    /** Discriminator / call identity. */
+    callType: string;
+    /** Already-rendered request sent to the client. */
+    request: LlmRequest;
+    /** Existing trace to attach to; a new trace id is generated when absent. */
+    traceId?: string;
+    parentSpanId?: string;
+    sessionId?: string;
+}
+export interface RunLlmCallDeps {
+    client: LlmClient;
+    cost?: CostFn;
+    clock?: Clock;
+    ids?: IdGen;
+}
+export interface RunLlmCallResult {
+    /** Ready-to-persist BASE recorder input (envelope + raw I/O + status). */
+    input: LlmCallInput;
+    /** Provider completion, or undefined if the client threw. */
+    completion?: LlmCompletion;
+}
+/**
+ * Perform the LLM CALL: generate ids, time it, call the client (never-throw),
+ * compute cost. Returns a ready base LlmCallInput + the completion. Does NOT
+ * persist and does NOT extract — callers do that (callLlm persists the base row;
+ * the generated call<Entity> additionally extracts + writes typed voRequest/voResponse).
+ */
+export declare function runLlmCall(input: RunLlmCallInput, deps: RunLlmCallDeps): Promise<RunLlmCallResult>;
+export interface CallLlmDeps extends RunLlmCallDeps {
+    recorder: LlmRecorder;
+    redact?: (row: LlmCallRow) => LlmCallRow;
+}
+/**
+ * Generic loop: CALL (runLlmCall) → persist the BASE row. No extract, no typed
+ * voRequest/voResponse (that's the generated call<Entity>). Finally-style: a
+ * client throw still persists an error row and never rethrows.
+ */
+export declare function callLlm(input: RunLlmCallInput, deps: CallLlmDeps): Promise<RecordLlmCallResult>;
+//# sourceMappingURL=call-loop.d.ts.map

package/dist/call-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-loop.d.ts","sourceRoot":"","sources":["../src/call-loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,GAAG,CAAC,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,KAAK,EAAE,YAAY,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,aAAa,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA8C3B;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,UAAU,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,mBAAmB,CAAC,CAQ9B"}

package/dist/call-loop.js

@@ -0,0 +1,71 @@
+import { buildLlmCallRow, persistLlmCallRow, } from "@metaobjectsdev/runtime-ts";
+import { systemClock, uuidIds, } from "./client.js";
+/**
+ * Perform the LLM CALL: generate ids, time it, call the client (never-throw),
+ * compute cost. Returns a ready base LlmCallInput + the completion. Does NOT
+ * persist and does NOT extract — callers do that (callLlm persists the base row;
+ * the generated call<Entity> additionally extracts + writes typed voRequest/voResponse).
+ */
+export async function runLlmCall(input, deps) {
+    const clock = deps.clock ?? systemClock;
+    const ids = deps.ids ?? uuidIds;
+    const spanId = ids.next();
+    const traceId = input.traceId ?? ids.next();
+    const t0 = clock.now();
+    const startedAt = new Date(t0).toISOString();
+    let completion;
+    let status = "ok";
+    let errorDetail = null;
+    try {
+        completion = await deps.client.complete(input.request);
+    }
+    catch (err) {
+        status = "error";
+        errorDetail = err instanceof Error ? err.message : String(err);
+    }
+    const latencyMs = clock.now() - t0;
+    // exactOptionalPropertyTypes: assign optionals only when defined.
+    const recInput = {
+        spanId,
+        traceId,
+        callType: input.callType,
+        startedAt,
+        latencyMs,
+        requestModel: input.request.model,
+        llmRequest: completion?.request ?? input.request,
+        llmResponseText: completion?.body ?? "",
+        status,
+        errorDetail,
+    };
+    if (input.request.system !== undefined)
+        recInput.system = input.request.system;
+    if (input.parentSpanId !== undefined)
+        recInput.parentSpanId = input.parentSpanId;
+    if (input.sessionId !== undefined)
+        recInput.sessionId = input.sessionId;
+    if (completion?.model !== undefined)
+        recInput.responseModel = completion.model;
+    if (completion?.usage?.inputTokens !== undefined)
+        recInput.inputTokens = completion.usage.inputTokens;
+    if (completion?.usage?.outputTokens !== undefined)
+        recInput.outputTokens = completion.usage.outputTokens;
+    if (completion?.finishReason !== undefined)
+        recInput.finishReason = completion.finishReason;
+    if (completion !== undefined && deps.cost !== undefined) {
+        const c = deps.cost(completion.model ?? input.request.model, completion.usage);
+        if (c !== null)
+            recInput.costMinor = c;
+    }
+    return completion !== undefined ? { input: recInput, completion } : { input: recInput };
+}
+/**
+ * Generic loop: CALL (runLlmCall) → persist the BASE row. No extract, no typed
+ * voRequest/voResponse (that's the generated call<Entity>). Finally-style: a
+ * client throw still persists an error row and never rethrows.
+ */
+export async function callLlm(input, deps) {
+    const { input: recInput } = await runLlmCall(input, deps);
+    await persistLlmCallRow(deps.recorder, buildLlmCallRow(recInput), deps.redact ? { redact: deps.redact } : undefined);
+    return { status: recInput.status, errorDetail: recInput.errorDetail };
+}
+//# sourceMappingURL=call-loop.js.map

package/dist/call-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-loop.js","sourceRoot":"","sources":["../src/call-loop.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+export interface LlmRequest {
+    /** The rendered prompt text (the GENERATE step's output). */
+    prompt: string;
+    /** gen_ai.request.model */
+    model: string;
+    /** Optional system prompt text (gen_ai.system / system message). */
+    system?: string;
+    /** Provider params: temperature, max_tokens, top_p, ... */
+    params?: Record<string, unknown>;
+}
+export interface LlmUsage {
+    /** gen_ai.usage.input_tokens */
+    inputTokens?: number;
+    /** gen_ai.usage.output_tokens */
+    outputTokens?: number;
+}
+export interface LlmCompletion {
+    /** Raw completion text — fed to extract/record. */
+    body: string;
+    usage?: LlmUsage;
+    /** gen_ai.response.model (may differ from request.model). */
+    model?: string;
+    /** Full wire request → llmRequest column (falls back to LlmRequest). */
+    request?: unknown;
+    /** gen_ai.response.finish_reasons */
+    finishReason?: string;
+}
+/** The single-method, provider-neutral CALL seam. */
+export interface LlmClient {
+    complete(req: LlmRequest): Promise<LlmCompletion>;
+}
+/** Injectable wall clock (ms since epoch). Injected so tests are deterministic. */
+export interface Clock {
+    now(): number;
+}
+/** Injectable id generator (span/trace ids). Injected so tests are deterministic. */
+export interface IdGen {
+    next(): string;
+}
+export declare const systemClock: Clock;
+export declare const uuidIds: IdGen;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnD;AAED,mFAAmF;AACnF,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,KAAK;IACpB,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,WAAW,EAAE,KAEzB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}

package/dist/client.js

@@ -0,0 +1,9 @@
+// The CALL seam. Named LlmClient to avoid collision with render's Provider
+// (which resolves prompt-TEXT references, not LLM calls).
+export const systemClock = {
+    now: () => Date.now(),
+};
+export const uuidIds = {
+    next: () => crypto.randomUUID(),
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0DAA0D;AA+C1D,MAAM,CAAC,MAAM,WAAW,GAAU;IAChC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAU;IAC5B,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;CAChC,CAAC"}

package/dist/composite.d.ts

@@ -0,0 +1,14 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+export interface CompositeRecorderOpts {
+    /** Called once per sink that rejects. Default: swallow. Telemetry must never
+     * break the call path, so record() always resolves. */
+    onError?: (error: unknown, index: number) => void;
+}
+/** Fans a row out to several sinks; a sink that rejects is isolated. */
+export declare class CompositeRecorder implements LlmRecorder {
+    private readonly recorders;
+    private readonly onError;
+    constructor(recorders: readonly LlmRecorder[], opts?: CompositeRecorderOpts);
+    record(call: LlmCallRow): Promise<void>;
+}
+//# sourceMappingURL=composite.d.ts.map

package/dist/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../src/composite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC;2DACuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED,wEAAwE;AACxE,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;gBAEtD,SAAS,EAAE,SAAS,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,qBAAqB;IAKrE,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ9C"}

package/dist/composite.js

@@ -0,0 +1,17 @@
+/** Fans a row out to several sinks; a sink that rejects is isolated. */
+export class CompositeRecorder {
+    recorders;
+    onError;
+    constructor(recorders, opts) {
+        this.recorders = recorders;
+        this.onError = opts?.onError ?? (() => { });
+    }
+    async record(call) {
+        const results = await Promise.allSettled(this.recorders.map((r) => r.record(call)));
+        results.forEach((res, i) => {
+            if (res.status === "rejected")
+                this.onError(res.reason, i);
+        });
+    }
+}
+//# sourceMappingURL=composite.js.map

package/dist/composite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.js","sourceRoot":"","sources":["../src/composite.ts"],"names":[],"mappings":"AAQA,wEAAwE;AACxE,MAAM,OAAO,iBAAiB;IACX,SAAS,CAAyB;IAClC,OAAO,CAA0C;IAElE,YAAY,SAAiC,EAAE,IAA4B;QACzE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAgB;QAC3B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAC1C,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACzB,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/cost.d.ts

@@ -0,0 +1,9 @@
+import type { LlmUsage } from "./client.js";
+/**
+ * Maps (model, usage) to a cost in integer USD minor units (cents), per the
+ * field.currency wire contract. Returns null when unknown — never throws. The
+ * library ships NO rate table (ADR-0024); adopters supply their own CostFn
+ * (from their LLM library's usage + their own rates) via `deps.cost`.
+ */
+export type CostFn = (model: string, usage: LlmUsage | undefined) => number | null;
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,KAAK,MAAM,GAAG,IAAI,CAAC"}

package/dist/cost.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export declare const AI_RUNTIME_PACKAGE = "@metaobjectsdev/ai-runtime";
+export { systemClock, uuidIds, type LlmClient, type LlmRequest, type LlmCompletion, type LlmUsage, type Clock, type IdGen, } from "./client.js";
+export type { CostFn } from "./cost.js";
+export { callLlm, runLlmCall, type CallLlmDeps, type RunLlmCallInput, type RunLlmCallDeps, type RunLlmCallResult, } from "./call-loop.js";
+export { CompositeRecorder, type CompositeRecorderOpts } from "./composite.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D,OAAO,EACL,WAAW,EACX,OAAO,EACP,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,KAAK,EACV,KAAK,KAAK,GACX,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EACL,OAAO,EACP,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// @metaobjectsdev/ai-runtime — LLM call loop + typed-trace recorder adapters.
+export const AI_RUNTIME_PACKAGE = "@metaobjectsdev/ai-runtime";
+export { systemClock, uuidIds, } from "./client.js";
+export { callLlm, runLlmCall, } from "./call-loop.js";
+export { CompositeRecorder } from "./composite.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAE/D,OAAO,EACL,WAAW,EACX,OAAO,GAOR,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,OAAO,EACP,UAAU,GAKX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAA8B,MAAM,gBAAgB,CAAC"}

package/dist/langfuse.d.ts

@@ -0,0 +1,32 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+/** The shape we post to Langfuse — a generation/observation. */
+export interface LangfuseTracePayload {
+    id: string;
+    traceId: string;
+    name: string;
+    model?: string;
+    input?: unknown;
+    output?: unknown;
+    usage?: {
+        input?: number;
+        output?: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** Injected sink — implemented over the real langfuse SDK by the adopter, or a
+ * fake in tests. Keeps the langfuse SDK an optional dep (never imported here). */
+export interface LangfuseSink {
+    trace(payload: LangfuseTracePayload): Promise<void> | void;
+}
+export interface LangfuseRecorderOpts {
+    sink: LangfuseSink;
+    /** Called when the sink rejects. Default: swallow (telemetry never breaks the call). */
+    onError?: (error: unknown) => void;
+}
+export declare class LangfuseRecorder implements LlmRecorder {
+    private readonly sink;
+    private readonly onError;
+    constructor(opts: LangfuseRecorderOpts);
+    record(call: LlmCallRow): Promise<void>;
+}
+//# sourceMappingURL=langfuse.d.ts.map

package/dist/langfuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langfuse.d.ts","sourceRoot":"","sources":["../src/langfuse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE1E,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;kFACkF;AAClF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,CAAC;IACnB,wFAAwF;IACxF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAOD,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,IAAI,EAAE,oBAAoB;IAKhC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAwC9C"}

package/dist/langfuse.js

@@ -0,0 +1,52 @@
+const numOrUndef = (v) => typeof v === "number" ? v : undefined;
+const strOrUndef = (v) => typeof v === "string" ? v : undefined;
+export class LangfuseRecorder {
+    sink;
+    onError;
+    constructor(opts) {
+        this.sink = opts.sink;
+        this.onError = opts.onError ?? (() => { });
+    }
+    async record(call) {
+        // Build the payload incrementally to satisfy exactOptionalPropertyTypes:
+        // never assign `T | undefined` to an optional `T?` property.
+        const payload = {
+            id: String(call["spanId"] ?? ""),
+            traceId: String(call["traceId"] ?? ""),
+            name: String(call["callType"] ?? "llm-call"),
+            metadata: {
+                status: call["status"],
+                finishReason: call["finishReason"],
+                latencyMs: call["latencyMs"],
+                costMinor: call["costMinor"],
+            },
+        };
+        // Optional scalar fields — only set when defined.
+        const model = strOrUndef(call["requestModel"]);
+        if (model !== undefined)
+            payload.model = model;
+        if (call["llmRequest"] !== undefined)
+            payload.input = call["llmRequest"];
+        const output = call["voResponse"] ?? call["llmResponse"];
+        if (output !== undefined)
+            payload.output = output;
+        // usage — only populate keys that have a value.
+        const inTok = numOrUndef(call["inputTokens"]);
+        const outTok = numOrUndef(call["outputTokens"]);
+        if (inTok !== undefined || outTok !== undefined) {
+            const usage = {};
+            if (inTok !== undefined)
+                usage.input = inTok;
+            if (outTok !== undefined)
+                usage.output = outTok;
+            payload.usage = usage;
+        }
+        try {
+            await this.sink.trace(payload);
+        }
+        catch (err) {
+            this.onError(err);
+        }
+    }
+}
+//# sourceMappingURL=langfuse.js.map

package/dist/langfuse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langfuse.js","sourceRoot":"","sources":["../src/langfuse.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,GAAG,CAAC,CAAU,EAAsB,EAAE,CACpD,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxC,MAAM,UAAU,GAAG,CAAC,CAAU,EAAsB,EAAE,CACpD,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAExC,MAAM,OAAO,gBAAgB;IACV,IAAI,CAAe;IACnB,OAAO,CAA2B;IAEnD,YAAY,IAA0B;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAgB;QAC3B,yEAAyE;QACzE,6DAA6D;QAC7D,MAAM,OAAO,GAAyB;YACpC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;YAC5C,QAAQ,EAAE;gBACR,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;gBACtB,YAAY,EAAE,IAAI,CAAC,cAAc,CAAC;gBAClC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC;gBAC5B,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC;aAC7B;SACF,CAAC;QAEF,kDAAkD;QAClD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;QAE/C,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;QAElD,gDAAgD;QAChD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAChD,MAAM,KAAK,GAAwC,EAAE,CAAC;YACtD,IAAI,KAAK,KAAK,SAAS;gBAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;YAC7C,IAAI,MAAM,KAAK,SAAS;gBAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YAChD,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;QACxB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/otel.d.ts

@@ -0,0 +1,23 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+/** Minimal structural subset of an OTel span. Avoids a hard @opentelemetry/api dep. */
+export interface OtelSpan {
+    setAttributes(attrs: Record<string, unknown>): void;
+    end(): void;
+}
+/** Minimal structural subset of an OTel tracer. */
+export interface OtelTracer {
+    startSpan(name: string): OtelSpan;
+}
+export interface OtelRecorderOpts {
+    tracer: OtelTracer;
+    onError?: (error: unknown) => void;
+}
+/** Maps a trace row → a span with gen_ai.* attributes. The internal→gen_ai.*
+ * mapping lives here (stable internal names, canonicalize at the edge). */
+export declare class OtelRecorder implements LlmRecorder {
+    private readonly tracer;
+    private readonly onError;
+    constructor(opts: OtelRecorderOpts);
+    record(call: LlmCallRow): Promise<void>;
+}
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE1E,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACvB,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACpD,GAAG,IAAI,IAAI,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;2EAC2E;AAC3E,qBAAa,YAAa,YAAW,WAAW;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,IAAI,EAAE,gBAAgB;IAK5B,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB9C"}

package/dist/otel.js

@@ -0,0 +1,35 @@
+/** Maps a trace row → a span with gen_ai.* attributes. The internal→gen_ai.*
+ * mapping lives here (stable internal names, canonicalize at the edge). */
+export class OtelRecorder {
+    tracer;
+    onError;
+    constructor(opts) {
+        this.tracer = opts.tracer;
+        this.onError = opts.onError ?? (() => { });
+    }
+    async record(call) {
+        try {
+            const span = this.tracer.startSpan(String(call.callType ?? "llm-call"));
+            const attrs = {};
+            const put = (key, v) => {
+                if (v !== undefined && v !== null)
+                    attrs[key] = v;
+            };
+            put("gen_ai.system", call.system);
+            put("gen_ai.request.model", call.requestModel);
+            put("gen_ai.response.model", call.responseModel);
+            put("gen_ai.usage.input_tokens", call.inputTokens);
+            put("gen_ai.usage.output_tokens", call.outputTokens);
+            put("gen_ai.response.finish_reasons", call.finishReason);
+            put("metaobjects.trace_id", call.traceId);
+            put("metaobjects.span_id", call.spanId);
+            put("metaobjects.status", call.status);
+            span.setAttributes(attrs);
+            span.end();
+        }
+        catch (err) {
+            this.onError(err);
+        }
+    }
+}
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAkBA;2EAC2E;AAC3E,MAAM,OAAO,YAAY;IACN,MAAM,CAAa;IACnB,OAAO,CAA2B;IAEnD,YAAY,IAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAgB;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC,CAAC,CAAC;YACxE,MAAM,KAAK,GAA4B,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,CAAU,EAAE,EAAE;gBACtC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;oBAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpD,CAAC,CAAC;YACF,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAClC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YAC/C,GAAG,CAAC,uBAAuB,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,2BAA2B,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YACnD,GAAG,CAAC,4BAA4B,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACrD,GAAG,CAAC,gCAAgC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACzD,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1C,GAAG,CAAC,qBAAqB,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACxC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@metaobjectsdev/ai-runtime",
+  "version": "0.10.0",
+  "description": "LLM call loop + typed-trace recorder adapters for MetaObjects: provider-neutral LlmClient seam, callLlm bridge, Composite/Langfuse/OTel recorders.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./langfuse": {
+      "bun": "./src/langfuse.ts",
+      "types": "./dist/langfuse.d.ts",
+      "default": "./dist/langfuse.js"
+    },
+    "./otel": {
+      "bun": "./src/otel.ts",
+      "types": "./dist/otel.d.ts",
+      "default": "./dist/otel.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
+  },
+  "license": "Apache-2.0",
+  "author": "Doug Mealing <doug@dougmealing.com>",
+  "homepage": "https://metaobjects.dev",
+  "bugs": {
+    "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metaobjectsdev/metaobjects.git",
+    "directory": "server/typescript/packages/ai-runtime"
+  },
+  "keywords": [
+    "metaobjects",
+    "llm",
+    "ai",
+    "trace",
+    "langfuse",
+    "opentelemetry"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@metaobjectsdev/metadata": "0.10.0",
+    "@metaobjectsdev/render": "0.10.0",
+    "@metaobjectsdev/runtime-ts": "0.10.0"
+  },
+  "peerDependencies": {
+    "langfuse": ">=3.0.0",
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "langfuse": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.6.0"
+  }
+}

package/src/call-loop.ts

@@ -0,0 +1,123 @@
+import {
+  buildLlmCallRow,
+  persistLlmCallRow,
+  type LlmRecorder,
+  type LlmCallInput,
+  type LlmCallRow,
+  type RecordLlmCallResult,
+} from "@metaobjectsdev/runtime-ts";
+import {
+  systemClock,
+  uuidIds,
+  type Clock,
+  type IdGen,
+  type LlmClient,
+  type LlmRequest,
+  type LlmCompletion,
+} from "./client.js";
+import type { CostFn } from "./cost.js";
+
+export interface RunLlmCallInput {
+  /** Discriminator / call identity. */
+  callType: string;
+  /** Already-rendered request sent to the client. */
+  request: LlmRequest;
+  /** Existing trace to attach to; a new trace id is generated when absent. */
+  traceId?: string;
+  parentSpanId?: string;
+  sessionId?: string;
+}
+
+export interface RunLlmCallDeps {
+  client: LlmClient;
+  cost?: CostFn;
+  clock?: Clock;
+  ids?: IdGen;
+}
+
+export interface RunLlmCallResult {
+  /** Ready-to-persist BASE recorder input (envelope + raw I/O + status). */
+  input: LlmCallInput;
+  /** Provider completion, or undefined if the client threw. */
+  completion?: LlmCompletion;
+}
+
+/**
+ * Perform the LLM CALL: generate ids, time it, call the client (never-throw),
+ * compute cost. Returns a ready base LlmCallInput + the completion. Does NOT
+ * persist and does NOT extract — callers do that (callLlm persists the base row;
+ * the generated call<Entity> additionally extracts + writes typed voRequest/voResponse).
+ */
+export async function runLlmCall(
+  input: RunLlmCallInput,
+  deps: RunLlmCallDeps,
+): Promise<RunLlmCallResult> {
+  const clock = deps.clock ?? systemClock;
+  const ids = deps.ids ?? uuidIds;
+
+  const spanId = ids.next();
+  const traceId = input.traceId ?? ids.next();
+  const t0 = clock.now();
+  const startedAt = new Date(t0).toISOString();
+
+  let completion: LlmCompletion | undefined;
+  let status: "ok" | "error" = "ok";
+  let errorDetail: string | null = null;
+  try {
+    completion = await deps.client.complete(input.request);
+  } catch (err) {
+    status = "error";
+    errorDetail = err instanceof Error ? err.message : String(err);
+  }
+  const latencyMs = clock.now() - t0;
+
+  // exactOptionalPropertyTypes: assign optionals only when defined.
+  const recInput: LlmCallInput = {
+    spanId,
+    traceId,
+    callType: input.callType,
+    startedAt,
+    latencyMs,
+    requestModel: input.request.model,
+    llmRequest: completion?.request ?? input.request,
+    llmResponseText: completion?.body ?? "",
+    status,
+    errorDetail,
+  };
+  if (input.request.system !== undefined) recInput.system = input.request.system;
+  if (input.parentSpanId !== undefined) recInput.parentSpanId = input.parentSpanId;
+  if (input.sessionId !== undefined) recInput.sessionId = input.sessionId;
+  if (completion?.model !== undefined) recInput.responseModel = completion.model;
+  if (completion?.usage?.inputTokens !== undefined) recInput.inputTokens = completion.usage.inputTokens;
+  if (completion?.usage?.outputTokens !== undefined) recInput.outputTokens = completion.usage.outputTokens;
+  if (completion?.finishReason !== undefined) recInput.finishReason = completion.finishReason;
+  if (completion !== undefined && deps.cost !== undefined) {
+    const c = deps.cost(completion.model ?? input.request.model, completion.usage);
+    if (c !== null) recInput.costMinor = c;
+  }
+
+  return completion !== undefined ? { input: recInput, completion } : { input: recInput };
+}
+
+export interface CallLlmDeps extends RunLlmCallDeps {
+  recorder: LlmRecorder;
+  redact?: (row: LlmCallRow) => LlmCallRow;
+}
+
+/**
+ * Generic loop: CALL (runLlmCall) → persist the BASE row. No extract, no typed
+ * voRequest/voResponse (that's the generated call<Entity>). Finally-style: a
+ * client throw still persists an error row and never rethrows.
+ */
+export async function callLlm(
+  input: RunLlmCallInput,
+  deps: CallLlmDeps,
+): Promise<RecordLlmCallResult> {
+  const { input: recInput } = await runLlmCall(input, deps);
+  await persistLlmCallRow(
+    deps.recorder,
+    buildLlmCallRow(recInput),
+    deps.redact ? { redact: deps.redact } : undefined,
+  );
+  return { status: recInput.status, errorDetail: recInput.errorDetail };
+}

package/src/client.ts

@@ -0,0 +1,55 @@
+// The CALL seam. Named LlmClient to avoid collision with render's Provider
+// (which resolves prompt-TEXT references, not LLM calls).
+
+export interface LlmRequest {
+  /** The rendered prompt text (the GENERATE step's output). */
+  prompt: string;
+  /** gen_ai.request.model */
+  model: string;
+  /** Optional system prompt text (gen_ai.system / system message). */
+  system?: string;
+  /** Provider params: temperature, max_tokens, top_p, ... */
+  params?: Record<string, unknown>;
+}
+
+export interface LlmUsage {
+  /** gen_ai.usage.input_tokens */
+  inputTokens?: number;
+  /** gen_ai.usage.output_tokens */
+  outputTokens?: number;
+}
+
+export interface LlmCompletion {
+  /** Raw completion text — fed to extract/record. */
+  body: string;
+  usage?: LlmUsage;
+  /** gen_ai.response.model (may differ from request.model). */
+  model?: string;
+  /** Full wire request → llmRequest column (falls back to LlmRequest). */
+  request?: unknown;
+  /** gen_ai.response.finish_reasons */
+  finishReason?: string;
+}
+
+/** The single-method, provider-neutral CALL seam. */
+export interface LlmClient {
+  complete(req: LlmRequest): Promise<LlmCompletion>;
+}
+
+/** Injectable wall clock (ms since epoch). Injected so tests are deterministic. */
+export interface Clock {
+  now(): number;
+}
+
+/** Injectable id generator (span/trace ids). Injected so tests are deterministic. */
+export interface IdGen {
+  next(): string;
+}
+
+export const systemClock: Clock = {
+  now: () => Date.now(),
+};
+
+export const uuidIds: IdGen = {
+  next: () => crypto.randomUUID(),
+};

package/src/composite.ts

@@ -0,0 +1,27 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+
+export interface CompositeRecorderOpts {
+  /** Called once per sink that rejects. Default: swallow. Telemetry must never
+   * break the call path, so record() always resolves. */
+  onError?: (error: unknown, index: number) => void;
+}
+
+/** Fans a row out to several sinks; a sink that rejects is isolated. */
+export class CompositeRecorder implements LlmRecorder {
+  private readonly recorders: readonly LlmRecorder[];
+  private readonly onError: (error: unknown, index: number) => void;
+
+  constructor(recorders: readonly LlmRecorder[], opts?: CompositeRecorderOpts) {
+    this.recorders = recorders;
+    this.onError = opts?.onError ?? (() => {});
+  }
+
+  async record(call: LlmCallRow): Promise<void> {
+    const results = await Promise.allSettled(
+      this.recorders.map((r) => r.record(call)),
+    );
+    results.forEach((res, i) => {
+      if (res.status === "rejected") this.onError(res.reason, i);
+    });
+  }
+}

package/src/cost.ts

@@ -0,0 +1,9 @@
+import type { LlmUsage } from "./client.js";
+
+/**
+ * Maps (model, usage) to a cost in integer USD minor units (cents), per the
+ * field.currency wire contract. Returns null when unknown — never throws. The
+ * library ships NO rate table (ADR-0024); adopters supply their own CostFn
+ * (from their LLM library's usage + their own rates) via `deps.cost`.
+ */
+export type CostFn = (model: string, usage: LlmUsage | undefined) => number | null;

package/src/index.ts

@@ -0,0 +1,26 @@
+// @metaobjectsdev/ai-runtime — LLM call loop + typed-trace recorder adapters.
+export const AI_RUNTIME_PACKAGE = "@metaobjectsdev/ai-runtime";
+
+export {
+  systemClock,
+  uuidIds,
+  type LlmClient,
+  type LlmRequest,
+  type LlmCompletion,
+  type LlmUsage,
+  type Clock,
+  type IdGen,
+} from "./client.js";
+
+export type { CostFn } from "./cost.js";
+
+export {
+  callLlm,
+  runLlmCall,
+  type CallLlmDeps,
+  type RunLlmCallInput,
+  type RunLlmCallDeps,
+  type RunLlmCallResult,
+} from "./call-loop.js";
+
+export { CompositeRecorder, type CompositeRecorderOpts } from "./composite.js";

package/src/langfuse.ts

@@ -0,0 +1,81 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+
+/** The shape we post to Langfuse — a generation/observation. */
+export interface LangfuseTracePayload {
+  id: string;
+  traceId: string;
+  name: string;
+  model?: string;
+  input?: unknown;
+  output?: unknown;
+  usage?: { input?: number; output?: number };
+  metadata?: Record<string, unknown>;
+}
+
+/** Injected sink — implemented over the real langfuse SDK by the adopter, or a
+ * fake in tests. Keeps the langfuse SDK an optional dep (never imported here). */
+export interface LangfuseSink {
+  trace(payload: LangfuseTracePayload): Promise<void> | void;
+}
+
+export interface LangfuseRecorderOpts {
+  sink: LangfuseSink;
+  /** Called when the sink rejects. Default: swallow (telemetry never breaks the call). */
+  onError?: (error: unknown) => void;
+}
+
+const numOrUndef = (v: unknown): number | undefined =>
+  typeof v === "number" ? v : undefined;
+const strOrUndef = (v: unknown): string | undefined =>
+  typeof v === "string" ? v : undefined;
+
+export class LangfuseRecorder implements LlmRecorder {
+  private readonly sink: LangfuseSink;
+  private readonly onError: (error: unknown) => void;
+
+  constructor(opts: LangfuseRecorderOpts) {
+    this.sink = opts.sink;
+    this.onError = opts.onError ?? (() => {});
+  }
+
+  async record(call: LlmCallRow): Promise<void> {
+    // Build the payload incrementally to satisfy exactOptionalPropertyTypes:
+    // never assign `T | undefined` to an optional `T?` property.
+    const payload: LangfuseTracePayload = {
+      id: String(call["spanId"] ?? ""),
+      traceId: String(call["traceId"] ?? ""),
+      name: String(call["callType"] ?? "llm-call"),
+      metadata: {
+        status: call["status"],
+        finishReason: call["finishReason"],
+        latencyMs: call["latencyMs"],
+        costMinor: call["costMinor"],
+      },
+    };
+
+    // Optional scalar fields — only set when defined.
+    const model = strOrUndef(call["requestModel"]);
+    if (model !== undefined) payload.model = model;
+
+    if (call["llmRequest"] !== undefined) payload.input = call["llmRequest"];
+
+    const output = call["voResponse"] ?? call["llmResponse"];
+    if (output !== undefined) payload.output = output;
+
+    // usage — only populate keys that have a value.
+    const inTok = numOrUndef(call["inputTokens"]);
+    const outTok = numOrUndef(call["outputTokens"]);
+    if (inTok !== undefined || outTok !== undefined) {
+      const usage: { input?: number; output?: number } = {};
+      if (inTok !== undefined) usage.input = inTok;
+      if (outTok !== undefined) usage.output = outTok;
+      payload.usage = usage;
+    }
+
+    try {
+      await this.sink.trace(payload);
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+}

package/src/otel.ts

@@ -0,0 +1,52 @@
+import type { LlmRecorder, LlmCallRow } from "@metaobjectsdev/runtime-ts";
+
+/** Minimal structural subset of an OTel span. Avoids a hard @opentelemetry/api dep. */
+export interface OtelSpan {
+  setAttributes(attrs: Record<string, unknown>): void;
+  end(): void;
+}
+
+/** Minimal structural subset of an OTel tracer. */
+export interface OtelTracer {
+  startSpan(name: string): OtelSpan;
+}
+
+export interface OtelRecorderOpts {
+  tracer: OtelTracer;
+  onError?: (error: unknown) => void;
+}
+
+/** Maps a trace row → a span with gen_ai.* attributes. The internal→gen_ai.*
+ * mapping lives here (stable internal names, canonicalize at the edge). */
+export class OtelRecorder implements LlmRecorder {
+  private readonly tracer: OtelTracer;
+  private readonly onError: (error: unknown) => void;
+
+  constructor(opts: OtelRecorderOpts) {
+    this.tracer = opts.tracer;
+    this.onError = opts.onError ?? (() => {});
+  }
+
+  async record(call: LlmCallRow): Promise<void> {
+    try {
+      const span = this.tracer.startSpan(String(call.callType ?? "llm-call"));
+      const attrs: Record<string, unknown> = {};
+      const put = (key: string, v: unknown) => {
+        if (v !== undefined && v !== null) attrs[key] = v;
+      };
+      put("gen_ai.system", call.system);
+      put("gen_ai.request.model", call.requestModel);
+      put("gen_ai.response.model", call.responseModel);
+      put("gen_ai.usage.input_tokens", call.inputTokens);
+      put("gen_ai.usage.output_tokens", call.outputTokens);
+      put("gen_ai.response.finish_reasons", call.finishReason);
+      put("metaobjects.trace_id", call.traceId);
+      put("metaobjects.span_id", call.spanId);
+      put("metaobjects.status", call.status);
+      span.setAttributes(attrs);
+      span.end();
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+}