@intentface/latch-langfuse 0.9.1

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,63 @@
+# @intentface/latch-langfuse
+
+Langfuse observability for Latch. Implements `@intentface/latch-core`'s
+dependency-free `telemetry` seam so any Latch host gets tracing, online evals,
+and user feedback with one line — and exposes score/trace helpers platforms use
+to read data back.
+
+## Tracing
+
+```ts
+import { createRuntime } from "@intentface/latch-core";
+import { langfuseTelemetry, isLangfuseConfigured } from "@intentface/latch-langfuse";
+
+const runtime = createRuntime({
+  // …storage, agents, etc…
+  telemetry: isLangfuseConfigured()
+    ? langfuseTelemetry({ ownerTag: (p) => ownerKey(p) })
+    : undefined,
+});
+```
+
+Every agent run becomes one Langfuse trace whose id is derived deterministically
+from the run id (`traceIdForRun`), tagged `owner:` / `agent:` / `run:`, with
+`sessionId` = the chat id and `userId` = `ownerTag(principal)`. Reads and scores
+address a trace from the run id alone — no lookup.
+
+Configuration is read from the environment by the Langfuse SDK:
+`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL` (defaults to
+`https://cloud.langfuse.com`). With no keys, `isLangfuseConfigured()` is `false`
+and the seam should be left `undefined` — zero behavior change.
+
+## Scores
+
+```ts
+import { postScore } from "@intentface/latch-langfuse";
+
+// judge verdict or user feedback on a run's trace
+await postScore({ runId, name: "helpfulness", value: 1, comment, dataType: "BOOLEAN" });
+```
+
+## Reading traces (server-side, owner-scoped)
+
+```ts
+import { listOwnerTraces } from "@intentface/latch-langfuse";
+
+// the tenant's recent traces + their scores, newest first
+const traces = await listOwnerTraces({ ownerTag, agent, limit: 50 });
+```
+
+`ownerTag` is the tenancy boundary — the platform proxies all reads and filters
+on it, so end users never receive Langfuse credentials.
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `langfuseTelemetry(opts)` | The `LatchTelemetry` implementation for `RuntimeConfig.telemetry`. |
+| `traceIdForRun(runId)` | Deterministic Langfuse trace id for a run. |
+| `postScore(input)` | Attach a score (judge/feedback) to a run's trace. |
+| `listOwnerTraces(args)` | Owner-scoped trace feed with scores joined in. |
+| `isLangfuseConfigured()` | Whether the env credentials are present. |
+| `getLangfuseClient()` | The shared `LangfuseClient`. |
+| `ensureTracing()` / `flushLangfuse()` | OTEL provider setup + serverless flush. |

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+import { LangfuseClient } from "@langfuse/client";
+/**
+ * True when Langfuse credentials are present (`LANGFUSE_PUBLIC_KEY` +
+ * `LANGFUSE_SECRET_KEY`; `LANGFUSE_BASE_URL` optional, defaults to
+ * cloud.langfuse.com). The telemetry seam should be left undefined otherwise.
+ */
+export declare function isLangfuseConfigured(): boolean;
+/**
+ * Process-wide `LangfuseClient` (reads credentials from env). Cached on
+ * `globalThis` so Vite SSR module reloads don't multiply clients.
+ */
+export declare function getLangfuseClient(): LangfuseClient;
+//# 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":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAI9C;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAIlD"}

package/dist/client.js

@@ -0,0 +1,21 @@
+import { LangfuseClient } from "@langfuse/client";
+/**
+ * True when Langfuse credentials are present (`LANGFUSE_PUBLIC_KEY` +
+ * `LANGFUSE_SECRET_KEY`; `LANGFUSE_BASE_URL` optional, defaults to
+ * cloud.langfuse.com). The telemetry seam should be left undefined otherwise.
+ */
+export function isLangfuseConfigured() {
+    return Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY);
+}
+const CLIENT_KEY = "__latchLangfuseClient";
+/**
+ * Process-wide `LangfuseClient` (reads credentials from env). Cached on
+ * `globalThis` so Vite SSR module reloads don't multiply clients.
+ */
+export function getLangfuseClient() {
+    const g = globalThis;
+    if (!g[CLIENT_KEY])
+        g[CLIENT_KEY] = new LangfuseClient();
+    return g[CLIENT_KEY];
+}
+//# 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,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CACZ,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CACnE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;QAAE,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,cAAc,EAAE,CAAC;IACzD,OAAO,CAAC,CAAC,UAAU,CAAmB,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { isLangfuseConfigured, getLangfuseClient } from "./client.js";
+export { ensureTracing, flushLangfuse } from "./otel.js";
+export { traceIdForRun, scoreIdForRun } from "./trace-id.js";
+export { langfuseTelemetry, type LangfuseTelemetryOptions, } from "./telemetry.js";
+export { postScore, type PostScoreInput } from "./scores.js";
+export { listOwnerTraces, listAdministeredTraces, AGENT_OWNER_TAG, type TraceSummary, type TraceScore, } from "./reads.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,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { isLangfuseConfigured, getLangfuseClient } from "./client.js";
+export { ensureTracing, flushLangfuse } from "./otel.js";
+export { traceIdForRun, scoreIdForRun } from "./trace-id.js";
+export { langfuseTelemetry, } from "./telemetry.js";
+export { postScore } from "./scores.js";
+export { listOwnerTraces, listAdministeredTraces, AGENT_OWNER_TAG, } from "./reads.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,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,iBAAiB,GAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAuB,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,eAAe,GAGhB,MAAM,YAAY,CAAC"}

package/dist/otel.d.ts

@@ -0,0 +1,22 @@
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+/**
+ * Register the global OTEL tracer provider with the Langfuse span processor,
+ * once per process. Guarded on `globalThis` so Vite/Nitro SSR module reloads
+ * (dev HMR) don't register a second provider. Credentials come from env
+ * (`LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` / `LANGFUSE_BASE_URL`).
+ */
+export declare function ensureTracing(opts?: {
+    /** Trace environment shown in Langfuse (e.g. "production" | "development"). */
+    environment?: string;
+}): LangfuseSpanProcessor;
+/**
+ * The environment tracing was set up with (via `ensureTracing`), so out-of-band
+ * score writes can be recorded in the SAME Langfuse environment as their trace
+ * instead of a mismatched one. Undefined until `ensureTracing` has run in this
+ * process (e.g. a cold invocation that only posts a score) — callers fall back
+ * to the env var.
+ */
+export declare function tracingEnvironment(): string | undefined;
+/** Flush pending spans to Langfuse (serverless-safe; no-op if never set up). */
+export declare function flushLangfuse(): 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,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAYvD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE;IACnC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,qBAAqB,CAexB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAGvD;AAED,gFAAgF;AAChF,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAInD"}

package/dist/otel.js

@@ -0,0 +1,43 @@
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+const OTEL_KEY = "__latchLangfuseOtel";
+/**
+ * Register the global OTEL tracer provider with the Langfuse span processor,
+ * once per process. Guarded on `globalThis` so Vite/Nitro SSR module reloads
+ * (dev HMR) don't register a second provider. Credentials come from env
+ * (`LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` / `LANGFUSE_BASE_URL`).
+ */
+export function ensureTracing(opts) {
+    const g = globalThis;
+    if (!g[OTEL_KEY]) {
+        const processor = new LangfuseSpanProcessor({
+            environment: opts?.environment,
+        });
+        const provider = new NodeTracerProvider({ spanProcessors: [processor] });
+        provider.register();
+        g[OTEL_KEY] = {
+            provider,
+            processor,
+            environment: opts?.environment,
+        };
+    }
+    return g[OTEL_KEY].processor;
+}
+/**
+ * The environment tracing was set up with (via `ensureTracing`), so out-of-band
+ * score writes can be recorded in the SAME Langfuse environment as their trace
+ * instead of a mismatched one. Undefined until `ensureTracing` has run in this
+ * process (e.g. a cold invocation that only posts a score) — callers fall back
+ * to the env var.
+ */
+export function tracingEnvironment() {
+    const g = globalThis;
+    return g[OTEL_KEY]?.environment;
+}
+/** Flush pending spans to Langfuse (serverless-safe; no-op if never set up). */
+export async function flushLangfuse() {
+    const g = globalThis;
+    const otel = g[OTEL_KEY];
+    await otel?.processor.forceFlush();
+}
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AASvC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAG7B;IACC,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,IAAI,qBAAqB,CAAC;YAC1C,WAAW,EAAE,IAAI,EAAE,WAAW;SAC/B,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,EAAE,cAAc,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACzE,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACpB,CAAC,CAAC,QAAQ,CAAC,GAAG;YACZ,QAAQ;YACR,SAAS;YACT,WAAW,EAAE,IAAI,EAAE,WAAW;SACP,CAAC;IAC5B,CAAC;IACD,OAAQ,CAAC,CAAC,QAAQ,CAAmB,CAAC,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,OAAQ,CAAC,CAAC,QAAQ,CAA+B,EAAE,WAAW,CAAC;AACjE,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAA8B,CAAC;IACtD,MAAM,IAAI,EAAE,SAAS,CAAC,UAAU,EAAE,CAAC;AACrC,CAAC"}

package/dist/reads.d.ts

@@ -0,0 +1,70 @@
+export interface TraceScore {
+    name: string;
+    value: number | string | null;
+    comment?: string;
+    dataType?: string;
+}
+export interface TraceSummary {
+    /** Langfuse trace id. */
+    id: string;
+    /** The latch run id (parsed from the `run:` tag), if present. */
+    runId?: string;
+    /** Agent name (the trace name / `agent:` tag). */
+    agent?: string;
+    /** The trace's Langfuse `userId` — the owner tag of whoever RAN the turn. */
+    userId?: string;
+    /** The `agent-owner:` tag, when the run's agent had an owner key. */
+    agentOwner?: string;
+    timestamp: string;
+    sessionId?: string;
+    input?: unknown;
+    output?: unknown;
+    /** Latency in seconds. */
+    latency?: number;
+    /** Total cost in USD. */
+    totalCost?: number;
+    /** Deep link into the Langfuse UI. */
+    htmlPath?: string;
+    environment?: string;
+    scores: TraceScore[];
+}
+/** The `agent-owner:` tag prefix — written by telemetry, filtered on here. */
+export declare const AGENT_OWNER_TAG = "agent-owner:";
+/**
+ * Recent traces for one owner (tenant), newest first, with their scores
+ * joined in. Reads are meant to run server-side in the platform — the owner
+ * filter is the tenancy boundary, so never expose this to callers who don't
+ * own `ownerTag`.
+ */
+export declare function listOwnerTraces(args: {
+    ownerTag: string;
+    /** Optional agent-name filter. */
+    agent?: string;
+    limit?: number;
+    page?: number;
+}): Promise<TraceSummary[]>;
+/**
+ * The observability feed for a reader who administers agents: every recent run of
+ * the agents owned by `agentOwnerTags` — INCLUDING runs by other users — unioned
+ * with the reader's own runs (`ownerTag`).
+ *
+ * Two sources, because they answer different questions. The `agent-owner:` tag
+ * finds other people's runs on my agents (the point of this feed). `ownerTag`
+ * keeps my own runs visible on agents I don't administer — code-registry agents
+ * carry no owner tag at all — and covers every trace written before the tag
+ * existed. The API's `tags` filter is conjunctive ("all of these tags"), so each
+ * owner key needs its own query; results are merged and de-duplicated by trace id.
+ *
+ * Tenancy: `agentOwnerTags` and `ownerTag` together ARE the boundary. Pass only
+ * keys the caller provably holds (see `evalOwnerKeysOf`) — never a client value.
+ */
+export declare function listAdministeredTraces(args: {
+    /** Owner keys of the agents the reader administers (personal + org). */
+    agentOwnerTags: string[];
+    /** The reader's own owner tag, so its own runs stay visible. */
+    ownerTag: string;
+    /** Optional agent-name filter. */
+    agent?: string;
+    limit?: number;
+}): Promise<TraceSummary[]>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../src/reads.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAKD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAgF9C;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAY1B;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,wEAAwE;IACxE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA2C1B"}

package/dist/reads.js

@@ -0,0 +1,158 @@
+import { getLangfuseClient } from "./client.js";
+const tagValue = (tags, prefix) => tags.find((t) => t.startsWith(prefix))?.slice(prefix.length);
+/** The `agent-owner:` tag prefix — written by telemetry, filtered on here. */
+export const AGENT_OWNER_TAG = "agent-owner:";
+/**
+ * Scores for exactly these traces via the Scores v3 API (`scores.getMany`/v2 is
+ * deprecated and 404s on Langfuse v4+). The v3 endpoint takes a comma-separated
+ * `traceId` filter and returns the subject trace under `subject` when requested
+ * via `fields`, so scores reliably attach to the traces we asked about instead of
+ * a fixed 100-row owner-wide slice.
+ */
+async function scoresFor(traceIds) {
+    const scoresByTrace = new Map();
+    if (traceIds.length === 0)
+        return scoresByTrace;
+    const client = getLangfuseClient();
+    const traceIdFilter = traceIds.join(",");
+    // `getManyV3` is cursor-paginated (max 100/page). A single page of traces can
+    // carry >100 scores (rubrics + feedback per run), so follow the cursor until
+    // it's absent — otherwise later scores silently drop off the feed.
+    let cursor;
+    do {
+        const scores = await client.api.scoresV3.getManyV3({
+            traceId: traceIdFilter,
+            fields: "details,subject",
+            limit: 100,
+            ...(cursor ? { cursor } : {}),
+        });
+        for (const s of scores.data ?? []) {
+            const subject = s.subject;
+            if (subject?.kind !== "trace" || !subject.id)
+                continue;
+            const list = scoresByTrace.get(subject.id) ?? [];
+            // v3 returns BOOLEAN scores as a JS boolean (v2 returned 1/0). Normalize
+            // to a number so binary and numeric scores share one numeric contract
+            // (aggregates/averaging); categorical scores stay strings.
+            const raw = s.value;
+            const value = typeof raw === "boolean" ? (raw ? 1 : 0) : (raw ?? null);
+            list.push({
+                name: s.name,
+                value,
+                comment: s.comment ?? undefined,
+                dataType: s.dataType,
+            });
+            scoresByTrace.set(subject.id, list);
+        }
+        cursor = scores.meta?.cursor;
+    } while (cursor);
+    return scoresByTrace;
+}
+const toSummary = (t, scores) => ({
+    id: t.id,
+    runId: tagValue(t.tags ?? [], "run:"),
+    agent: t.name ?? tagValue(t.tags ?? [], "agent:"),
+    userId: t.userId ?? undefined,
+    agentOwner: tagValue(t.tags ?? [], AGENT_OWNER_TAG),
+    timestamp: t.timestamp,
+    sessionId: t.sessionId ?? undefined,
+    input: t.input,
+    output: t.output,
+    latency: t.latency ?? undefined,
+    totalCost: t.totalCost ?? undefined,
+    htmlPath: t.htmlPath,
+    environment: t.environment,
+    scores,
+});
+/**
+ * Recent traces for one owner (tenant), newest first, with their scores
+ * joined in. Reads are meant to run server-side in the platform — the owner
+ * filter is the tenancy boundary, so never expose this to callers who don't
+ * own `ownerTag`.
+ */
+export async function listOwnerTraces(args) {
+    const client = getLangfuseClient();
+    const traces = await client.api.trace.list({
+        userId: args.ownerTag,
+        ...(args.agent ? { name: args.agent } : {}),
+        limit: args.limit ?? 50,
+        page: args.page,
+        orderBy: "timestamp.desc",
+    });
+    const rows = (traces.data ?? []);
+    const scores = await scoresFor(rows.map((t) => t.id));
+    return rows.map((t) => toSummary(t, scores.get(t.id) ?? []));
+}
+/**
+ * Newest-first by trace timestamp; unparseable timestamps sort last. Never
+ * returns NaN — a NaN comparator leaves Array#sort's ordering unspecified.
+ */
+const byNewest = (a, b) => {
+    const at = Date.parse(a.timestamp);
+    const bt = Date.parse(b.timestamp);
+    if (Number.isNaN(at) && Number.isNaN(bt))
+        return 0;
+    if (Number.isNaN(at))
+        return 1;
+    if (Number.isNaN(bt))
+        return -1;
+    return bt - at;
+};
+/**
+ * The observability feed for a reader who administers agents: every recent run of
+ * the agents owned by `agentOwnerTags` — INCLUDING runs by other users — unioned
+ * with the reader's own runs (`ownerTag`).
+ *
+ * Two sources, because they answer different questions. The `agent-owner:` tag
+ * finds other people's runs on my agents (the point of this feed). `ownerTag`
+ * keeps my own runs visible on agents I don't administer — code-registry agents
+ * carry no owner tag at all — and covers every trace written before the tag
+ * existed. The API's `tags` filter is conjunctive ("all of these tags"), so each
+ * owner key needs its own query; results are merged and de-duplicated by trace id.
+ *
+ * Tenancy: `agentOwnerTags` and `ownerTag` together ARE the boundary. Pass only
+ * keys the caller provably holds (see `evalOwnerKeysOf`) — never a client value.
+ */
+export async function listAdministeredTraces(args) {
+    const client = getLangfuseClient();
+    const limit = args.limit ?? 50;
+    const common = {
+        ...(args.agent ? { name: args.agent } : {}),
+        limit,
+        orderBy: "timestamp.desc",
+    };
+    // De-duplicate the key list first: for a principal without a userId the
+    // personal and org keys collapse to the same string, which would double the
+    // API calls for identical rows.
+    const ownerTags = [...new Set(args.agentOwnerTags.filter((t) => t.length > 0))];
+    // Sources are independent and best-effort: one failing query (a transient 5xx,
+    // or a deployment whose API rejects the tag filter) degrades the feed to the
+    // other sources rather than emptying the page.
+    const pages = await Promise.allSettled([
+        ...ownerTags.map((tag) => client.api.trace.list({ ...common, tags: [`${AGENT_OWNER_TAG}${tag}`] })),
+        client.api.trace.list({ ...common, userId: args.ownerTag }),
+    ]);
+    const merged = new Map();
+    for (const page of pages) {
+        if (page.status === "rejected") {
+            console.warn("trace list source failed:", page.reason);
+            continue;
+        }
+        for (const t of (page.value.data ?? []))
+            merged.set(t.id, t);
+    }
+    // Partial failure degrades the feed; TOTAL failure must throw. An empty array
+    // is indistinguishable from "this tenant has no traces", so swallowing it would
+    // replace the caller's last good page with a confident "No traces yet".
+    const failure = pages.find((p) => p.status === "rejected");
+    if (failure?.status === "rejected" && pages.every((p) => p.status === "rejected")) {
+        throw failure.reason;
+    }
+    // Each source returned up to `limit` rows; the union can exceed it, so re-sort
+    // across sources and take the newest `limit` — otherwise the cap would depend
+    // on which query a row came from.
+    const rows = [...merged.values()].sort(byNewest).slice(0, limit);
+    const scores = await scoresFor(rows.map((t) => t.id));
+    return rows.map((t) => toSummary(t, scores.get(t.id) ?? []));
+}
+//# sourceMappingURL=reads.js.map

package/dist/reads.js.map

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

package/dist/reads.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reads.test.d.ts.map

package/dist/reads.test.d.ts.map

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

package/dist/reads.test.js

@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+/**
+ * The trace-list calls the reader made, in order, so a test can assert WHICH
+ * queries were issued (one per agent-owner tag, plus the caller's own userId).
+ */
+const calls = [];
+let tracePages;
+let scoreRows;
+/** When set, the trace-list call matching this filter key rejects ("*" = all). */
+let failFor;
+vi.mock("./client.js", () => ({
+    getLangfuseClient: () => ({
+        api: {
+            trace: {
+                list: async (params) => {
+                    calls.push(params);
+                    // Key the canned page by the filter this call used.
+                    const tags = params.tags;
+                    const key = tags?.[0] ?? `user:${String(params.userId)}`;
+                    if (failFor && (failFor === "*" || key === failFor)) {
+                        throw new Error("langfuse unavailable");
+                    }
+                    return { data: tracePages[key] ?? [] };
+                },
+            },
+            scoresV3: {
+                getManyV3: async () => ({ data: scoreRows, meta: {} }),
+            },
+        },
+    }),
+}));
+const { AGENT_OWNER_TAG, listAdministeredTraces } = await import("./reads.js");
+const trace = (id, at, over = {}) => ({
+    id,
+    name: "my-agent",
+    timestamp: at,
+    tags: [`run:run-${id}`, `agent:my-agent`],
+    ...over,
+});
+describe("listAdministeredTraces", () => {
+    beforeEach(() => {
+        calls.length = 0;
+        tracePages = {};
+        scoreRows = [];
+        failFor = undefined;
+    });
+    it("queries once per agent-owner key, plus the reader's own runs", async () => {
+        await listAdministeredTraces({
+            agentOwnerTags: ["org/me", "org"],
+            ownerTag: "org/me",
+            limit: 10,
+        });
+        expect(calls).toHaveLength(3);
+        expect(calls[0]).toMatchObject({ tags: [`${AGENT_OWNER_TAG}org/me`] });
+        expect(calls[1]).toMatchObject({ tags: [`${AGENT_OWNER_TAG}org`] });
+        expect(calls[2]).toMatchObject({ userId: "org/me" });
+    });
+    it("collapses duplicate owner keys into one query", async () => {
+        // An org-only principal's personal and org keys are the same string.
+        await listAdministeredTraces({
+            agentOwnerTags: ["org", "org", ""],
+            ownerTag: "org",
+        });
+        expect(calls).toHaveLength(2); // one tag query + the userId query
+    });
+    it("surfaces another user's run on an agent I administer", async () => {
+        tracePages[`${AGENT_OWNER_TAG}org`] = [
+            trace("t1", "2026-07-31T10:00:00Z", {
+                userId: "org/colleague",
+                tags: ["run:run-t1", "agent:my-agent", `${AGENT_OWNER_TAG}org`],
+            }),
+        ];
+        const rows = await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+        });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            runId: "run-t1",
+            userId: "org/colleague", // attribution: who ran it
+            agentOwner: "org", // whose agent it was
+        });
+    });
+    it("de-duplicates a trace returned by more than one source", async () => {
+        const t = trace("t1", "2026-07-31T10:00:00Z", { userId: "org/me" });
+        tracePages[`${AGENT_OWNER_TAG}org`] = [t];
+        tracePages["user:org/me"] = [t];
+        const rows = await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+        });
+        expect(rows.map((r) => r.id)).toEqual(["t1"]);
+    });
+    it("re-sorts across sources and caps at the limit", async () => {
+        // Each source is newest-first on its own; the union must be too, or the cap
+        // would keep whichever query a row happened to come from.
+        tracePages[`${AGENT_OWNER_TAG}org`] = [
+            trace("old", "2026-07-01T00:00:00Z"),
+            trace("oldest", "2026-06-01T00:00:00Z"),
+        ];
+        tracePages["user:org/me"] = [trace("newest", "2026-07-31T00:00:00Z")];
+        const rows = await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+            limit: 2,
+        });
+        expect(rows.map((r) => r.id)).toEqual(["newest", "old"]);
+    });
+    it("joins scores in and normalizes booleans to numbers", async () => {
+        tracePages[`${AGENT_OWNER_TAG}org`] = [trace("t1", "2026-07-31T10:00:00Z")];
+        scoreRows = [
+            { name: "greets", value: true, subject: { kind: "trace", id: "t1" }, dataType: "BOOLEAN" },
+            { name: "user-feedback", value: 1, subject: { kind: "trace", id: "t1" } },
+            { name: "ignored", value: 1, subject: { kind: "observation", id: "t1" } },
+        ];
+        const rows = await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+        });
+        expect(rows[0].scores).toEqual([
+            { name: "greets", value: 1, comment: undefined, dataType: "BOOLEAN" },
+            { name: "user-feedback", value: 1, comment: undefined, dataType: undefined },
+        ]);
+    });
+    it("degrades to the surviving sources when one query fails", async () => {
+        tracePages["user:org/me"] = [trace("mine", "2026-07-31T10:00:00Z", { userId: "org/me" })];
+        // The tag query throws; the reader's own runs must still render.
+        failFor = `${AGENT_OWNER_TAG}org`;
+        const rows = await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+        });
+        expect(rows.map((r) => r.id)).toEqual(["mine"]);
+    });
+    it("throws when EVERY source fails, so the caller keeps its last good page", async () => {
+        // An empty array would read as "no traces yet" and wipe the feed.
+        failFor = "*";
+        await expect(listAdministeredTraces({ agentOwnerTags: ["org"], ownerTag: "org/me" })).rejects.toThrow("langfuse unavailable");
+    });
+    it("passes the agent filter to every source", async () => {
+        await listAdministeredTraces({
+            agentOwnerTags: ["org"],
+            ownerTag: "org/me",
+            agent: "my-agent",
+        });
+        for (const c of calls)
+            expect(c).toMatchObject({ name: "my-agent" });
+    });
+});
+//# sourceMappingURL=reads.test.js.map

package/dist/reads.test.js.map

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

package/dist/scores.d.ts

@@ -0,0 +1,49 @@
+export interface PostScoreInput {
+    /** The latch run the score belongs to (resolved to its trace id). */
+    runId: string;
+    /** Score name — e.g. a rubric name, or "user-feedback". */
+    name: string;
+    value: number;
+    /** Free-text rationale (judge reason / user comment). */
+    comment?: string;
+    dataType?: "NUMERIC" | "BOOLEAN" | "CATEGORICAL";
+    /** Extra metadata on the score — e.g. a human correction's original AI verdict. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Stable score id. Defaults to a deterministic id derived from (runId, name)
+     * so repeated writes for the same run+name upsert one score rather than
+     * accumulating duplicates (live verdict → human correction overwrites it).
+     * Pass an explicit id only when you deliberately want independent scores.
+     */
+    id?: string;
+    /**
+     * The run's start time (epoch ms) — the stable per-run clock every writer for
+     * a run should pass. Langfuse only treats a write as an upsert when id, name
+     * AND timestamp (at date granularity) all match; the high-level SDK stamps
+     * `now`, so a correction on a later day would create a SECOND score and skew
+     * aggregates. Pinning every write for a run to its start keeps corrections
+     * idempotent across days. Defaults to now (same-day writes still dedupe).
+     */
+    timestamp?: number;
+    /**
+     * Langfuse environment for the score. Defaults to the environment tracing was
+     * set up with (so scores match their trace), then `LANGFUSE_TRACING_ENVIRONMENT`.
+     * Pass explicitly to override.
+     */
+    environment?: string;
+}
+/**
+ * Attach a score to a run's Langfuse trace (judge verdicts, user feedback).
+ * Sent through the raw ingestion endpoint (not the high-level `score.create`)
+ * so the event timestamp can be pinned to the run's clock — the only way to
+ * make cross-day corrections upsert instead of duplicate (see `timestamp`).
+ * Ingests immediately — callers are post-turn/endpoint paths, not hot loops —
+ * with a request-level timeout and no retries so a slow/down Langfuse can't
+ * hang a user-facing request for this non-critical write. Rejects on
+ * timeout/error; callers decide whether to surface or swallow it (the judge
+ * and endpoint callers all swallow).
+ */
+export declare function postScore(input: PostScoreInput & {
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=scores.d.ts.map

package/dist/scores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scores.d.ts","sourceRoot":"","sources":["../src/scores.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;IACjD,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAUD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/scores.js

@@ -0,0 +1,54 @@
+import { getLangfuseClient } from "./client.js";
+import { tracingEnvironment } from "./otel.js";
+import { scoreIdForRun, traceIdForRun } from "./trace-id.js";
+/** Default hard bound on the ingest network call (ms). */
+const INGEST_TIMEOUT_MS = 10_000;
+/**
+ * Attach a score to a run's Langfuse trace (judge verdicts, user feedback).
+ * Sent through the raw ingestion endpoint (not the high-level `score.create`)
+ * so the event timestamp can be pinned to the run's clock — the only way to
+ * make cross-day corrections upsert instead of duplicate (see `timestamp`).
+ * Ingests immediately — callers are post-turn/endpoint paths, not hot loops —
+ * with a request-level timeout and no retries so a slow/down Langfuse can't
+ * hang a user-facing request for this non-critical write. Rejects on
+ * timeout/error; callers decide whether to surface or swallow it (the judge
+ * and endpoint callers all swallow).
+ */
+export async function postScore(input) {
+    const client = getLangfuseClient();
+    const event = {
+        // Event id is unique per write so the ingestion event itself isn't deduped;
+        // the SCORE is deduped by `body.id` (the deterministic per-run+name id).
+        id: crypto.randomUUID(),
+        type: "score-create",
+        timestamp: new Date(input.timestamp ?? Date.now()).toISOString(),
+        body: {
+            id: input.id ?? (await scoreIdForRun(input.runId, input.name)),
+            traceId: await traceIdForRun(input.runId),
+            name: input.name,
+            value: input.value,
+            comment: input.comment,
+            dataType: input.dataType,
+            // Match the trace's environment (from ensureTracing) so scores land
+            // alongside their trace, not in a mismatched Langfuse environment; fall
+            // back to the env var on a cold, score-only invocation.
+            environment: input.environment ??
+                tracingEnvironment() ??
+                process.env.LANGFUSE_TRACING_ENVIRONMENT,
+            ...(input.metadata ? { metadata: input.metadata } : {}),
+        },
+    };
+    // Bound the call at the request level: this cancels the actual HTTP on
+    // timeout (a Promise.race would leave it running) and disables the SDK's
+    // default 2 retries, so the worst-case hang stays at one timeout window.
+    const res = await client.api.ingestion.batch({ batch: [event] }, {
+        timeoutInSeconds: Math.ceil((input.timeoutMs ?? INGEST_TIMEOUT_MS) / 1000),
+        maxRetries: 0,
+    });
+    if (res.errors.length > 0) {
+        throw new Error(`Langfuse score ingest failed: ${res.errors
+            .map((e) => e.message ?? String(e.status))
+            .join("; ")}`);
+    }
+}
+//# sourceMappingURL=scores.js.map

package/dist/scores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scores.js","sourceRoot":"","sources":["../src/scores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAqC7D,0DAA0D;AAC1D,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAOjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAA8C;IAE9C,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAmB;QAC5B,4EAA4E;QAC5E,yEAAyE;QACzE,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,IAAI,EAAE,cAAc;QACpB,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;QAChE,IAAI,EAAE;YACJ,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,MAAM,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9D,OAAO,EAAE,MAAM,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC;YACzC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,oEAAoE;YACpE,wEAAwE;YACxE,wDAAwD;YACxD,WAAW,EACT,KAAK,CAAC,WAAW;gBACjB,kBAAkB,EAAE;gBACpB,OAAO,CAAC,GAAG,CAAC,4BAA4B;YAC1C,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD;KACF,CAAC;IACF,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAC1C,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,EAClB;QACE,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,iBAAiB,CAAC,GAAG,IAAI,CAAC;QAC1E,UAAU,EAAE,CAAC;KACd,CACF,CAAC;IACF,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,iCAAiC,GAAG,CAAC,MAAM;aACxC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;aACzC,IAAI,CAAC,IAAI,CAAC,EAAE,CAChB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/telemetry.d.ts

@@ -0,0 +1,55 @@
+import type { LatchTelemetry, TelemetryRunMeta, TelemetryRunOutcome } from "@intentface/latch-core";
+export interface LangfuseTelemetryOptions<P> {
+    /**
+     * Tenant isolation tag derived from the principal (e.g. the platform's
+     * owner key). Becomes the trace's `userId` and an `owner:` tag — all
+     * platform reads filter on it, so it must be stable per tenant.
+     */
+    ownerTag: (principal: P) => string;
+    /**
+     * The owner key of the AGENT being run, when the host can resolve one — becomes
+     * an `agent-owner:` tag. Distinct from `ownerTag` (who ran the turn): it lets a
+     * reader find every run of the agents it administers, including runs by other
+     * users. Return undefined for agents with no owner (e.g. code-registry ones),
+     * which simply omits the tag. Runs on the turn's hot path, so keep it cheap.
+     */
+    agentOwnerTag?: (run: TelemetryRunMeta<P>) => Promise<string | undefined>;
+    /** Trace environment shown in Langfuse (default "development"). */
+    environment?: string;
+    /**
+     * Post-trace extension point — the platform hangs the online judge here.
+     * Runs after the run's root span is finalized.
+     */
+    afterRun?: (args: {
+        meta: TelemetryRunMeta<P>;
+        outcome: TelemetryRunOutcome;
+        traceId: string;
+    }) => Promise<void>;
+    /**
+     * Serverless background scheduler (e.g. Vercel's `waitUntil`). When set,
+     * `afterRun` is scheduled instead of awaited so it never delays the
+     * response; locally it's awaited inline.
+     */
+    waitUntil?: (p: Promise<unknown>) => void;
+    /** Override enablement (default: keys present in env). */
+    enabled?: boolean;
+}
+/**
+ * The one-liner Langfuse implementation of latch-core's telemetry seam.
+ *
+ * ```ts
+ * const runtime = createRuntime({
+ *   ...,
+ *   telemetry: isLangfuseConfigured()
+ *     ? langfuseTelemetry({ ownerTag: (p) => ownerKey(p) })
+ *     : undefined,
+ * });
+ * ```
+ *
+ * Every run becomes one Langfuse trace with a deterministic id derived from
+ * the runId (`traceIdForRun`), tagged `owner:` / `agent:` / `run:` (plus
+ * `agent-owner:` when `agentOwnerTag` resolves one) and scoped to
+ * `sessionId = chatId`, `userId = ownerTag`.
+ */
+export declare function langfuseTelemetry<P>(opts: LangfuseTelemetryOptions<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,EACV,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAahC,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1E,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAChB,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;QAC1B,OAAO,EAAE,mBAAmB,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC1C,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAChC,cAAc,CAAC,CAAC,CAAC,CAwHnB"}

package/dist/telemetry.js

@@ -0,0 +1,161 @@
+import { LangfuseVercelAiSdkIntegration } from "@langfuse/vercel-ai-sdk";
+import { propagateAttributes, startObservation, } from "@langfuse/tracing";
+import { context as otelContext, trace as otelTrace } from "@opentelemetry/api";
+import { ensureTracing, flushLangfuse } from "./otel.js";
+import { isLangfuseConfigured } from "./client.js";
+import { traceIdForRun } from "./trace-id.js";
+/** A random 16-hex OTEL span id (parent seed for the deterministic trace). */
+function randomSpanId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Text of the last assistant message (for trace-level 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.length > 0 ? text : undefined;
+    }
+    return undefined;
+}
+/**
+ * The one-liner Langfuse implementation of latch-core's telemetry seam.
+ *
+ * ```ts
+ * const runtime = createRuntime({
+ *   ...,
+ *   telemetry: isLangfuseConfigured()
+ *     ? langfuseTelemetry({ ownerTag: (p) => ownerKey(p) })
+ *     : undefined,
+ * });
+ * ```
+ *
+ * Every run becomes one Langfuse trace with a deterministic id derived from
+ * the runId (`traceIdForRun`), tagged `owner:` / `agent:` / `run:` (plus
+ * `agent-owner:` when `agentOwnerTag` resolves one) and scoped to
+ * `sessionId = chatId`, `userId = ownerTag`.
+ */
+export function langfuseTelemetry(opts) {
+    const enabled = opts.enabled ?? isLangfuseConfigured();
+    const integration = new LangfuseVercelAiSdkIntegration();
+    // The run's root span stays open until onRunFinished so the trace gets a
+    // real duration + trace-level input/output. Keyed by runId (one per turn).
+    const openSpans = new Map();
+    return {
+        telemetryFor(run) {
+            if (!enabled)
+                return undefined;
+            return {
+                isEnabled: true,
+                functionId: `agent:${run.agent}`,
+                integrations: [integration],
+            };
+        },
+        async withRunSpan(run, fn) {
+            if (!enabled)
+                return fn();
+            ensureTracing({ environment: opts.environment ?? "development" });
+            const owner = opts.ownerTag(run.principal);
+            // Seed the root span with the deterministic trace id so scores and
+            // feedback can address the trace from the runId alone.
+            const span = startObservation(run.agent, {}, {
+                asType: "agent",
+                parentSpanContext: {
+                    traceId: await traceIdForRun(run.runId),
+                    spanId: randomSpanId(),
+                    traceFlags: 1,
+                },
+            });
+            openSpans.set(run.runId, span);
+            // Run the model call with the root span active: the AI SDK integration
+            // roots its spans in the active context, and propagated attributes
+            // (trace name/session/user/tags) flow to every child span.
+            const ctx = otelTrace.setSpan(otelContext.active(), span.otelSpan);
+            // Group a whole delegation tree under one session: subagent turns run in
+            // their own `sub_…` chat, so keying the session on the ROOT conversation
+            // (threaded down by the runtime) makes the main turn and its helpers show
+            // together in Langfuse. A `parent-run:` tag links each helper to the run
+            // that spawned it; `depth` (0 = top-level) records how deep it nested.
+            const sessionId = run.rootChatId ?? run.chatId;
+            const tags = [`owner:${owner}`, `agent:${run.agent}`, `run:${run.runId}`];
+            if (run.parentRunId)
+                tags.push(`parent-run:${run.parentRunId}`, "subagent");
+            // `agent-owner:` is how the observability feed finds runs of the agents a
+            // reader administers — including runs by OTHER users. Best-effort: a failed
+            // lookup must not cost the turn its trace, it only costs that filter.
+            if (opts.agentOwnerTag) {
+                try {
+                    const agentOwner = await opts.agentOwnerTag(run);
+                    if (agentOwner)
+                        tags.push(`agent-owner:${agentOwner}`);
+                }
+                catch (e) {
+                    console.warn(`agentOwnerTag failed (run ${run.runId}):`, e);
+                }
+            }
+            return otelContext.with(ctx, () => propagateAttributes({
+                traceName: run.agent,
+                sessionId,
+                userId: owner,
+                tags,
+                metadata: {
+                    runId: run.runId,
+                    chatId: run.chatId,
+                    agent: run.agent,
+                    model: run.modelId,
+                    depth: String(run.depth),
+                    ...(run.parentRunId ? { parentRunId: run.parentRunId } : {}),
+                },
+            }, fn));
+        },
+        async onRunFinished(run, outcome) {
+            if (!enabled)
+                return;
+            const span = openSpans.get(run.runId);
+            if (span) {
+                openSpans.delete(run.runId);
+                const input = outcome.inputText;
+                const output = lastAssistantText(outcome.messages);
+                span.update({
+                    input,
+                    output,
+                    level: outcome.status === "errored" ? "ERROR" : "DEFAULT",
+                    statusMessage: outcome.error,
+                });
+                // Trace-level IO (what the trace list/preview shows).
+                span.setTraceIO({ input, output });
+                span.end();
+            }
+            if (opts.afterRun) {
+                const work = (async () => {
+                    await opts.afterRun({
+                        meta: run,
+                        outcome,
+                        traceId: await traceIdForRun(run.runId),
+                    });
+                })();
+                if (opts.waitUntil)
+                    opts.waitUntil(work.catch(() => { }));
+                else
+                    await work;
+            }
+        },
+        async flush() {
+            if (!enabled)
+                return;
+            const p = flushLangfuse();
+            // Keep the flush alive in serverless even when the caller can't await it
+            // (e.g. core's synchronous onError path voids the promise). waitUntil
+            // registers it with the platform; we still await for the normal path.
+            opts.waitUntil?.(p.catch(() => { }));
+            await p;
+        },
+    };
+}
+//# 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,18 @@
+/**
+ * The deterministic Langfuse trace id for a latch run. Both the tracer (span
+ * seeding) and out-of-band writers (judge scores, user feedback) derive the
+ * same id from the runId, so scores land on the run's trace without lookups.
+ */
+export declare function traceIdForRun(runId: string): Promise<string>;
+/**
+ * A deterministic Langfuse score id for a (run, score-name) pair. Langfuse
+ * upserts a score only when its id, name AND timestamp (date granularity) all
+ * match, so deriving the id from run+name is necessary but not sufficient:
+ * writers must ALSO pin the score timestamp to the run's clock (see
+ * `PostScoreInput.timestamp`). Together they make score writes idempotent — the
+ * live judge and a later human correction of the same rubric write the SAME id
+ * and the correction overwrites the original verdict instead of leaving two
+ * scores of the same name on the trace, even across days.
+ */
+export declare function scoreIdForRun(runId: string, name: 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":"AAEA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/trace-id.js

@@ -0,0 +1,23 @@
+import { createTraceId } from "@langfuse/tracing";
+/**
+ * The deterministic Langfuse trace id for a latch run. Both the tracer (span
+ * seeding) and out-of-band writers (judge scores, user feedback) derive the
+ * same id from the runId, so scores land on the run's trace without lookups.
+ */
+export function traceIdForRun(runId) {
+    return createTraceId(`latch-run:${runId}`);
+}
+/**
+ * A deterministic Langfuse score id for a (run, score-name) pair. Langfuse
+ * upserts a score only when its id, name AND timestamp (date granularity) all
+ * match, so deriving the id from run+name is necessary but not sufficient:
+ * writers must ALSO pin the score timestamp to the run's clock (see
+ * `PostScoreInput.timestamp`). Together they make score writes idempotent — the
+ * live judge and a later human correction of the same rubric write the SAME id
+ * and the correction overwrites the original verdict instead of leaving two
+ * scores of the same name on the trace, even across days.
+ */
+export function scoreIdForRun(runId, name) {
+    return createTraceId(`latch-score:${runId}:${name}`);
+}
+//# 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,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,aAAa,CAAC,aAAa,KAAK,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,IAAY;IACvD,OAAO,aAAa,CAAC,eAAe,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@intentface/latch-langfuse",
+  "version": "0.9.1",
+  "description": "Latch observability on Langfuse — one-line tracing for latch runtimes via the AI SDK telemetry integration, plus score and trace-read helpers for platforms.",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "agents",
+    "llm",
+    "langfuse",
+    "opentelemetry",
+    "observability"
+  ],
+  "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"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@langfuse/client": "^5.9.1",
+    "@langfuse/otel": "^5.9.1",
+    "@langfuse/tracing": "^5.9.1",
+    "@langfuse/vercel-ai-sdk": "^5.9.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.0",
+    "@intentface/latch-core": "^0.9.1"
+  },
+  "peerDependencies": {
+    "ai": ">=7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "ai": "^7.0.2",
+    "typescript": "^5.7.0",
+    "vitest": "^4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Intentface/intentface-latch.git",
+    "directory": "packages/langfuse"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}