@intentface/latch-otel 0.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @intentface/latch-otel
+
+Tracing for Latch over OpenTelemetry. Implements `@intentface/latch-core`'s
+`telemetry` hook: each run is one trace, the AI SDK's model and tool spans nest
+under it, and everything goes over OTLP to the backend you choose. A preset for
+Langfuse is included.
+
+```bash
+pnpm add @intentface/latch-otel @ai-sdk/otel   # @ai-sdk/otel at the version matching your `ai`
+```
+
+## Langfuse
+
+```ts
+import { createRuntime } from "@intentface/latch-core";
+import { otelTelemetry } from "@intentface/latch-otel";
+import { isLangfuseConfigured, langfuse } from "@intentface/latch-otel/langfuse";
+
+const runtime = createRuntime({
+  // …storage, agents…
+  telemetry: isLangfuseConfigured()
+    ? otelTelemetry({ user: (p) => ownerKey(p), export: langfuse(), environment: "production" })
+    : undefined,
+});
+```
+
+`langfuse()` reads `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and
+`LANGFUSE_BASE_URL` (default `https://cloud.langfuse.com`), and sends to the
+project's OTLP endpoint. Each run shows as one trace named after the agent, in
+the conversation's session, with the user, tags (`owner:`, `agent:`, `run:`,
+`agent-version:`, `parent-run:`, `agent-owner:`) and run metadata. Under it:
+the AI SDK's agent span, each step, each model call as a generation with its
+messages and token usage, and each tool call with its arguments and result.
+
+## Any other backend
+
+```ts
+telemetry: otelTelemetry({ user: (p) => ownerKey(p) }),
+```
+
+With no `export`, spans go over OTLP/HTTP to `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+or `OTEL_EXPORTER_OTLP_ENDPOINT`, with `OTEL_EXPORTER_OTLP_HEADERS`: Grafana,
+Honeycomb, Datadog, Jaeger, a collector. Or pass any `SpanExporter`, or a
+destination of your own (`{ exporter, runAttributes, finishedAttributes }`, the
+shape `langfuse()` returns) to add the attributes your backend wants.
+
+## What's on the spans
+
+- The run's span, `latch.run <agent>`: the whole turn, saving it included.
+  Its trace id is `traceIdForRun(runId)`, so anything that knows a run can link
+  to its trace. When the run ends it gets `input.value`, `output.value`,
+  `latch.run.status`, token usage and `latch.cost`, and an error status if the
+  run failed.
+- On every span of the run: `session.id` (the conversation; a subagent shares
+  its parent's), `user.id`, `gen_ai.agent.name`, `latch.run.id`,
+  `latch.chat.id`, `latch.agent.version`, `latch.parent_run.id`, `latch.depth`,
+  `latch.trigger`, `deployment.environment.name`.
+- The AI SDK's spans, in the GenAI semantic conventions, from `@ai-sdk/otel`
+  (configure it with `aiSdk`).
+
+It runs its own tracer provider and registers an async context manager only if
+the app has none, so it doesn't take over tracing your app already does. On
+serverless, pass `waitUntil` so the flush outlives the response.
+
+Replaces `@intentface/latch-langfuse` (0.21 and earlier), whose trace ids it
+keeps. Reading traces back and writing scores were left out: they belong to
+your app or an evaluation tool.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { otelTelemetry, type OtelTelemetryOptions, type OtelDestination, type OtelRun, } from "./telemetry.js";
+export { traceIdForRun } from "./trace-id.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":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,OAAO,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { otelTelemetry, } from "./telemetry.js";
+export { traceIdForRun } from "./trace-id.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,OAAO,EACL,aAAa,GAId,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/langfuse.d.ts

@@ -0,0 +1,38 @@
+import type { SpanExporter } from "@opentelemetry/sdk-trace-base";
+import type { OtelDestination } from "./telemetry.js";
+export interface LangfuseOptions {
+    /** Default `LANGFUSE_PUBLIC_KEY`. */
+    publicKey?: string;
+    /** Default `LANGFUSE_SECRET_KEY`. */
+    secretKey?: string;
+    /** Default `LANGFUSE_BASE_URL`, else Langfuse Cloud EU (`https://cloud.langfuse.com`). */
+    baseUrl?: string;
+    /** Langfuse's environment for these traces. Default: `otelTelemetry`'s `environment`. */
+    environment?: string;
+    /** Send through this exporter instead of the OTLP one `langfuseOtlp` describes (a proxy, a test). */
+    exporter?: SpanExporter;
+}
+/** Whether the Langfuse keys are in the environment: `langfuse()` with no arguments would work. */
+export declare function isLangfuseConfigured(): boolean;
+/** Langfuse's OTLP endpoint and headers, for an exporter of your own. */
+export declare function langfuseOtlp(opts?: Pick<LangfuseOptions, "publicKey" | "secretKey" | "baseUrl">): {
+    url: string;
+    headers: Record<string, string>;
+};
+/**
+ * Send traces to Langfuse, over its OTLP endpoint. Each run is one trace named
+ * after the agent, in the conversation's session, with the user, tags
+ * (`owner:`, `agent:`, `run:`, `agent-version:`, `parent-run:`,
+ * `agent-owner:`) and run metadata Langfuse filters on. The run's own span is
+ * an agent observation, marked as an error when the run errored.
+ *
+ * ```ts
+ * otelTelemetry({ user: (p) => ownerKey(p), export: langfuse() })
+ * ```
+ *
+ * Reads `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and `LANGFUSE_BASE_URL`;
+ * throws without the keys (check `isLangfuseConfigured()` first if they're
+ * optional).
+ */
+export declare function langfuse(opts?: LangfuseOptions): OtelDestination;
+//# 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":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,gBAAgB,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAID,mGAAmG;AACnG,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,GAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,CAAM,GAAG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAeA;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,eAAe,CAgCpE"}

package/dist/langfuse.js

@@ -0,0 +1,86 @@
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+const env = (name) => (typeof process === "undefined" ? undefined : process.env[name]) || undefined;
+/** Whether the Langfuse keys are in the environment: `langfuse()` with no arguments would work. */
+export function isLangfuseConfigured() {
+    return Boolean(env("LANGFUSE_PUBLIC_KEY") && env("LANGFUSE_SECRET_KEY"));
+}
+/** Langfuse's OTLP endpoint and headers, for an exporter of your own. */
+export function langfuseOtlp(opts = {}) {
+    const publicKey = opts.publicKey ?? env("LANGFUSE_PUBLIC_KEY");
+    const secretKey = opts.secretKey ?? env("LANGFUSE_SECRET_KEY");
+    if (!publicKey || !secretKey) {
+        throw new Error("langfuse(): set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY, or pass publicKey and secretKey");
+    }
+    const baseUrl = (opts.baseUrl ?? env("LANGFUSE_BASE_URL") ?? "https://cloud.langfuse.com").replace(/\/+$/, "");
+    return {
+        url: `${baseUrl}/api/public/otel/v1/traces`,
+        headers: {
+            Authorization: `Basic ${btoa(`${publicKey}:${secretKey}`)}`,
+            // Ingest as spans arrive rather than in Langfuse's batch path.
+            "x-langfuse-ingestion-version": "4",
+        },
+    };
+}
+/** The tags a run's trace gets: what Langfuse's trace list filters on. */
+function tagsOf(run) {
+    const tags = [`agent:${run.agent}`, `run:${run.runId}`];
+    if (run.user)
+        tags.unshift(`owner:${run.user}`);
+    if (run.parentRunId)
+        tags.push(`parent-run:${run.parentRunId}`, "subagent");
+    if (run.agentVersion != null)
+        tags.push(`agent-version:${run.agentVersion}`);
+    if (run.agentOwner)
+        tags.push(`agent-owner:${run.agentOwner}`);
+    return tags;
+}
+/**
+ * Send traces to Langfuse, over its OTLP endpoint. Each run is one trace named
+ * after the agent, in the conversation's session, with the user, tags
+ * (`owner:`, `agent:`, `run:`, `agent-version:`, `parent-run:`,
+ * `agent-owner:`) and run metadata Langfuse filters on. The run's own span is
+ * an agent observation, marked as an error when the run errored.
+ *
+ * ```ts
+ * otelTelemetry({ user: (p) => ownerKey(p), export: langfuse() })
+ * ```
+ *
+ * Reads `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and `LANGFUSE_BASE_URL`;
+ * throws without the keys (check `isLangfuseConfigured()` first if they're
+ * optional).
+ */
+export function langfuse(opts = {}) {
+    const exporter = opts.exporter ?? new OTLPTraceExporter(langfuseOtlp(opts));
+    return {
+        exporter,
+        runAttributes(run) {
+            const environment = opts.environment ?? run.environment;
+            return {
+                everySpan: {
+                    "langfuse.trace.name": run.agent,
+                    "langfuse.session.id": run.sessionId,
+                    ...(run.user ? { "langfuse.user.id": run.user } : {}),
+                    "langfuse.trace.tags": tagsOf(run),
+                    "langfuse.trace.metadata.runId": run.runId,
+                    "langfuse.trace.metadata.chatId": run.chatId,
+                    "langfuse.trace.metadata.agent": run.agent,
+                    "langfuse.trace.metadata.model": run.modelId,
+                    "langfuse.trace.metadata.depth": String(run.depth),
+                    ...(run.agentVersion != null ? { "langfuse.trace.metadata.agentVersion": String(run.agentVersion) } : {}),
+                    ...(run.parentRunId ? { "langfuse.trace.metadata.parentRunId": run.parentRunId } : {}),
+                    ...(environment ? { "langfuse.environment": environment } : {}),
+                },
+                root: { "langfuse.observation.type": "agent" },
+            };
+        },
+        finishedAttributes(_run, outcome) {
+            if (outcome.status !== "errored")
+                return undefined;
+            return {
+                "langfuse.observation.level": "ERROR",
+                ...(outcome.error ? { "langfuse.observation.status_message": outcome.error } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=langfuse.js.map

package/dist/langfuse.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,95 @@
+import type { LatchTelemetry, TelemetryRunMeta, TelemetryRunOutcome, TurnTrigger } from "@intentface/latch-core";
+import { type OpenTelemetryOptions } from "@ai-sdk/otel";
+import { type Attributes } from "@opentelemetry/api";
+import { type SpanExporter } from "@opentelemetry/sdk-trace-base";
+/** What a run's spans are labelled with: what latch knows about the run when it starts. */
+export interface OtelRun {
+    runId: string;
+    chatId: string;
+    /** The top-level conversation: a subagent's run shares it with the run that spawned it. */
+    sessionId: string;
+    agent: string;
+    modelId: string;
+    /** 0 for a top-level turn, more for a subagent. */
+    depth: number;
+    trigger: TurnTrigger;
+    /** The stored agent version behind the run, for agents that come from a store. */
+    agentVersion?: number;
+    /** The run that spawned this one, for a subagent. */
+    parentRunId?: string;
+    /** From `user`. */
+    user?: string;
+    /** From `agentOwner`. */
+    agentOwner?: string;
+    /** From `environment`. */
+    environment?: string;
+}
+/**
+ * Where spans go, and anything that backend wants on them beyond the standard
+ * attributes. `langfuse()` from `@intentface/latch-otel/langfuse` is one.
+ */
+export interface OtelDestination {
+    exporter: SpanExporter;
+    /** Attributes for every span of a run (`everySpan`), and for the run's own span (`root`). */
+    runAttributes?(run: OtelRun): {
+        everySpan?: Attributes;
+        root?: Attributes;
+    };
+    /** Attributes for the run's own span once the run has finished. */
+    finishedAttributes?(run: OtelRun, outcome: TelemetryRunOutcome): Attributes | undefined;
+}
+export interface OtelTelemetryOptions<P> {
+    /**
+     * Where spans go: an exporter, or a destination such as `langfuse()`.
+     * Default: OTLP over HTTP to `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (or
+     * `OTEL_EXPORTER_OTLP_ENDPOINT`), with `OTEL_EXPORTER_OTLP_HEADERS`.
+     */
+    export?: SpanExporter | OtelDestination;
+    /**
+     * Who a run is for, as one stable string (usually the owner key). Becomes
+     * `user.id`. Leave it out to record no user.
+     */
+    user?: (principal: P) => string;
+    /**
+     * Who owns the agent being run, when that's someone other than the user (an
+     * org's shared agent). Becomes `latch.agent_owner`. Runs before every turn,
+     * so keep it cheap; a throw only loses the attribute.
+     */
+    agentOwner?: (run: TelemetryRunMeta<P>) => Promise<string | undefined>;
+    /** `deployment.environment.name`, e.g. "production". */
+    environment?: string;
+    /** More attributes for every span of a run. */
+    attributes?: (run: TelemetryRunMeta<P>) => Attributes | undefined;
+    /** Options for the AI SDK's spans (`@ai-sdk/otel`), e.g. `{ usage: true }`. */
+    aiSdk?: Omit<OpenTelemetryOptions, "tracer">;
+    /**
+     * Keeps the flush alive after the response on serverless (Vercel's
+     * `waitUntil`). Without it, flush is only awaited.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** Default true. False turns every hook into a no-op. */
+    enabled?: boolean;
+}
+/**
+ * Latch's telemetry hook over OpenTelemetry. Each run is one trace, its id
+ * derived from the run id (`traceIdForRun`), rooted in a `latch.run <agent>`
+ * span: the whole turn, saving it included. The AI SDK's own spans (its
+ * `invoke_agent`, each step, each model call and tool call, in the GenAI
+ * semantic conventions, from `@ai-sdk/otel`) nest under it. Every span carries the session, the user and
+ * the run, so a backend can filter on any of them.
+ *
+ * ```ts
+ * import { otelTelemetry } from "@intentface/latch-otel";
+ * import { langfuse } from "@intentface/latch-otel/langfuse";
+ *
+ * createRuntime({
+ *   ...,
+ *   telemetry: otelTelemetry({ user: (p) => ownerKey(p), export: langfuse() }),
+ * });
+ * ```
+ *
+ * It runs its own tracer provider, so it neither needs nor replaces one your
+ * app registered. Add `@ai-sdk/otel` at the version matching your `ai`.
+ */
+export declare function otelTelemetry<P>(opts?: OtelTelemetryOptions<P>): LatchTelemetry<P>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACjH,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAkC,KAAK,UAAU,EAA2B,MAAM,oBAAoB,CAAC;AAG9G,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,+BAA+B,CAAC;AAGvC,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,6FAA6F;IAC7F,aAAa,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG;QAAE,SAAS,CAAC,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IAC5E,mEAAmE;IACnE,kBAAkB,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;CACzF;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAAC;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvE,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,UAAU,GAAG,SAAS,CAAC;IAClE,+EAA+E;IAC/E,KAAK,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;IAC7C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAChD,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA+DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAE,oBAAoB,CAAC,CAAC,CAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAgItF"}

package/dist/telemetry.js

@@ -0,0 +1,214 @@
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BasicTracerProvider, BatchSpanProcessor, RandomIdGenerator, } from "@opentelemetry/sdk-trace-base";
+import { traceIdForRun } from "./trace-id.js";
+/** Run attributes carried in the context, copied onto every span the run starts. */
+const RUN_ATTRIBUTES = Symbol.for("latch-otel.run-attributes");
+let contextManagerSet = false;
+/**
+ * Spans only nest across `await`s with an async context manager. Register one
+ * unless the app already has: `setGlobalContextManager` refuses a second.
+ */
+function ensureContextManager() {
+    if (contextManagerSet)
+        return;
+    contextManagerSet = true;
+    context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+}
+/** Text of the last assistant message: the run's output. */
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role !== "assistant")
+            continue;
+        const text = (m.parts ?? [])
+            .filter((p) => p.type === "text" && typeof p.text === "string")
+            .map((p) => p.text)
+            .join(" ")
+            .trim();
+        return text || undefined;
+    }
+    return undefined;
+}
+/** A host callback's result, or undefined (and a warning) when it throws: telemetry never fails a turn. */
+function guarded(label, runId, f) {
+    try {
+        return f();
+    }
+    catch (e) {
+        console.warn(`latch-otel: ${label} failed (run ${runId}):`, e);
+        return undefined;
+    }
+}
+const defined = (a) => Object.fromEntries(Object.entries(a).filter(([, v]) => v !== undefined));
+/** The standard attributes, on every span of a run. */
+function standardAttributes(run) {
+    return defined({
+        "session.id": run.sessionId,
+        "user.id": run.user,
+        "gen_ai.conversation.id": run.sessionId,
+        "gen_ai.agent.name": run.agent,
+        "deployment.environment.name": run.environment,
+        "latch.run.id": run.runId,
+        "latch.chat.id": run.chatId,
+        "latch.agent": run.agent,
+        "latch.agent.version": run.agentVersion,
+        "latch.agent_owner": run.agentOwner,
+        "latch.parent_run.id": run.parentRunId,
+        "latch.depth": run.depth,
+        "latch.trigger": run.trigger,
+    });
+}
+/**
+ * Latch's telemetry hook over OpenTelemetry. Each run is one trace, its id
+ * derived from the run id (`traceIdForRun`), rooted in a `latch.run <agent>`
+ * span: the whole turn, saving it included. The AI SDK's own spans (its
+ * `invoke_agent`, each step, each model call and tool call, in the GenAI
+ * semantic conventions, from `@ai-sdk/otel`) nest under it. Every span carries the session, the user and
+ * the run, so a backend can filter on any of them.
+ *
+ * ```ts
+ * import { otelTelemetry } from "@intentface/latch-otel";
+ * import { langfuse } from "@intentface/latch-otel/langfuse";
+ *
+ * createRuntime({
+ *   ...,
+ *   telemetry: otelTelemetry({ user: (p) => ownerKey(p), export: langfuse() }),
+ * });
+ * ```
+ *
+ * It runs its own tracer provider, so it neither needs nor replaces one your
+ * app registered. Add `@ai-sdk/otel` at the version matching your `ai`.
+ */
+export function otelTelemetry(opts = {}) {
+    if (opts.enabled === false)
+        return {};
+    const destination = opts.export && "exporter" in opts.export ? opts.export : { exporter: opts.export ?? new OTLPTraceExporter() };
+    // The next root span's trace id. Set right before `startSpan` and consumed by
+    // it, synchronously, so a root span gets the run's id and nothing else does.
+    let nextTraceId;
+    const random = new RandomIdGenerator();
+    const idGenerator = {
+        generateTraceId: () => {
+            const id = nextTraceId ?? random.generateTraceId();
+            nextTraceId = undefined;
+            return id;
+        },
+        generateSpanId: () => random.generateSpanId(),
+    };
+    const propagate = {
+        onStart(span, parent) {
+            const attributes = parent.getValue(RUN_ATTRIBUTES);
+            if (attributes)
+                span.setAttributes(attributes);
+        },
+        onEnd() { },
+        forceFlush: async () => { },
+        shutdown: async () => { },
+    };
+    const provider = new BasicTracerProvider({
+        idGenerator,
+        spanProcessors: [propagate, new BatchSpanProcessor(destination.exporter)],
+    });
+    const tracer = provider.getTracer("@intentface/latch-otel");
+    const aiSdk = new OpenTelemetry({ ...opts.aiSdk, tracer });
+    // The run's span stays open until the run finishes, for a real duration and its output.
+    const open = new Map();
+    return {
+        telemetryFor(run) {
+            return { isEnabled: true, functionId: `agent:${run.agent}`, integrations: [aiSdk] };
+        },
+        async withRunSpan(meta, fn) {
+            // Core awaits this unguarded (it has to run `fn`), so nothing before
+            // `fn` may throw: a failing callback loses its attributes, anything else
+            // loses the span, and the turn runs either way.
+            let ctx;
+            try {
+                ctx = await startRun(meta);
+            }
+            catch (e) {
+                console.warn(`latch-otel: couldn't start the run's span (run ${meta.runId}):`, e);
+            }
+            return ctx ? context.with(ctx, fn) : fn();
+        },
+        async onRunFinished(meta, outcome) {
+            const entry = open.get(meta.runId);
+            if (!entry)
+                return;
+            open.delete(meta.runId);
+            const { span, run } = entry;
+            try {
+                span.setAttributes(defined({
+                    "input.value": outcome.inputText,
+                    "output.value": lastAssistantText(outcome.messages),
+                    "latch.run.status": outcome.status,
+                    "latch.usage.input_tokens": outcome.usage.inputTokens,
+                    "latch.usage.output_tokens": outcome.usage.outputTokens,
+                    "latch.usage.cache_read_tokens": outcome.usage.cacheReadTokens,
+                    "latch.usage.cache_write_tokens": outcome.usage.cacheWriteTokens,
+                    "latch.cost": outcome.cost,
+                }));
+                if (outcome.status === "errored")
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: outcome.error });
+                const finished = guarded("finishedAttributes", meta.runId, () => destination.finishedAttributes?.(run, outcome));
+                if (finished)
+                    span.setAttributes(finished);
+            }
+            finally {
+                span.end();
+            }
+        },
+        async flush() {
+            const done = provider.forceFlush();
+            opts.waitUntil?.(done.catch(() => { }));
+            await done;
+        },
+    };
+    /** Open the run's span; the context the run then runs in. */
+    async function startRun(meta) {
+        ensureContextManager();
+        let agentOwner;
+        try {
+            agentOwner = await opts.agentOwner?.(meta);
+        }
+        catch (e) {
+            console.warn(`latch-otel: agentOwner failed (run ${meta.runId}):`, e);
+        }
+        const run = {
+            runId: meta.runId,
+            chatId: meta.chatId,
+            sessionId: meta.rootChatId ?? meta.chatId,
+            agent: meta.agent,
+            modelId: meta.modelId,
+            depth: meta.depth,
+            trigger: meta.trigger,
+            agentVersion: meta.agentVersion,
+            parentRunId: meta.parentRunId,
+            user: opts.user ? guarded("user", meta.runId, () => opts.user(meta.principal)) : undefined,
+            agentOwner,
+            environment: opts.environment,
+        };
+        const extra = guarded("runAttributes", meta.runId, () => destination.runAttributes?.(run));
+        const everySpan = {
+            ...standardAttributes(run),
+            ...guarded("attributes", meta.runId, () => opts.attributes?.(meta)),
+            ...extra?.everySpan,
+        };
+        nextTraceId = await traceIdForRun(meta.runId);
+        let span;
+        try {
+            span = tracer.startSpan(`latch.run ${meta.agent}`, {
+                root: true,
+                attributes: { ...everySpan, "latch.model": meta.modelId, ...extra?.root },
+            });
+        }
+        finally {
+            nextTraceId = undefined;
+        }
+        open.set(meta.runId, { span, run });
+        return trace.setSpan(context.active().setValue(RUN_ATTRIBUTES, everySpan), span);
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/trace-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The trace id a latch run is recorded under: derived from the run id, so
+ * anything that knows the run (a feedback button, a later score writer, a link
+ * from your own UI) can address its trace without looking it up.
+ *
+ * The first 32 hex characters of SHA-256(`latch-run:<runId>`), the same id
+ * `@intentface/latch-langfuse` produced, so traces recorded before keep
+ * matching.
+ */
+export declare function traceIdForRun(runId: string): Promise<string>;
+//# sourceMappingURL=trace-id.d.ts.map

package/dist/trace-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-id.d.ts","sourceRoot":"","sources":["../src/trace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlE"}

package/dist/trace-id.js

@@ -0,0 +1,16 @@
+/**
+ * The trace id a latch run is recorded under: derived from the run id, so
+ * anything that knows the run (a feedback button, a later score writer, a link
+ * from your own UI) can address its trace without looking it up.
+ *
+ * The first 32 hex characters of SHA-256(`latch-run:<runId>`), the same id
+ * `@intentface/latch-langfuse` produced, so traces recorded before keep
+ * matching.
+ */
+export async function traceIdForRun(runId) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`latch-run:${runId}`));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 32);
+}
+//# sourceMappingURL=trace-id.js.map

package/dist/trace-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-id.js","sourceRoot":"","sources":["../src/trace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa;IAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,KAAK,EAAE,CAAC,CAAC,CAAC;IACrG,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC9E,IAAI,CAAC,EAAE,CAAC;SACR,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@intentface/latch-otel",
+  "version": "0.22.0",
+  "description": "Latch tracing over OpenTelemetry — one trace per run, the AI SDK's GenAI spans under it, sent over OTLP to any backend, with a ready preset for Langfuse.",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "agents",
+    "llm",
+    "opentelemetry",
+    "otlp",
+    "observability",
+    "langfuse"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./langfuse": {
+      "types": "./dist/langfuse.d.ts",
+      "import": "./dist/langfuse.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@intentface/latch-core": "^0.22.0"
+  },
+  "peerDependencies": {
+    "@ai-sdk/otel": ">=1.0.0",
+    "ai": ">=7.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/otel": "1.0.106",
+    "@libsql/client": "^0.15.0",
+    "@types/node": "^22",
+    "ai": "^7.0.106",
+    "drizzle-orm": "^0.45.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4",
+    "zod": "^4.0.0",
+    "@intentface/latch-drizzle": "^0.22.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Intentface/intentface-latch.git",
+    "directory": "packages/otel"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}