@agentproto/telemetry-langfuse 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy (agentik.net)
+
+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,35 @@
+# `@agentproto/telemetry-langfuse`
+
+A dependency-free sink that forwards agentproto eval events to the [Langfuse](https://langfuse.com) public ingestion REST API. No Langfuse SDK is required — the implementation uses `fetch` directly.
+
+## Usage
+
+```ts
+import { langfuseTelemetry } from "@agentproto/telemetry-langfuse"
+
+const sink = langfuseTelemetry({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+  secretKey: process.env.LANGFUSE_SECRET_KEY,
+  baseUrl: "https://cloud.langfuse.com",
+  environment: "production",
+})
+
+runEval({ suite, sink })
+
+await sink.flush()
+```
+
+## Event mapping
+
+| EvalEvent kind | Langfuse action | Notes |
+|---|---|---|
+| `eval.started` | `trace-create` | One trace per `runId`; name is `eval:${suiteId}`. |
+| `eval.case.scored` | `score-create` | One score per case/scorer tuple. |
+| `eval.finished` | `score-create` | Two scores: `eval.meanValue` and `eval.passRate`. |
+| unknown | ignored | Forward compatibility. |
+
+Events are buffered in memory until `flush()` POSTs them as a single batch to `POST ${baseUrl}/api/public/ingestion` with Basic auth.
+
+## Security
+
+Credentials are used only for Basic auth headers. They are never logged or returned from `flush()`.

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { EvalEvent } from '@agentproto/eval';
+import { Telemetry } from '@agentproto/telemetry';
+
+/**
+ * Shared Langfuse ingestion transport — auth, a batch buffer, and a flush that
+ * POSTs to `${baseUrl}/api/public/ingestion` with Basic auth. Both the eval
+ * sink (`langfuseTelemetry`) and the agent-session tracer map their own domain
+ * events into Langfuse batch items and hand them to this client; the client
+ * owns nothing domain-specific — just the wire.
+ */
+/** Credentials + endpoint for a Langfuse ingestion client. */
+interface IngestionConfig {
+    /** Langfuse public key (Basic auth username). */
+    readonly publicKey: string;
+    /** Langfuse secret key (Basic auth password). */
+    readonly secretKey: string;
+    /** Langfuse base URL, e.g. `https://cloud.langfuse.com`. */
+    readonly baseUrl: string;
+    /** Optional fetch implementation (defaults to `globalThis.fetch`). */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Result of a {@link IngestionClient.flush}. */
+interface FlushResult {
+    /** HTTP status, or `0` when the batch was empty and no request was made. */
+    readonly status: number;
+    /** Number of batch items actually sent. */
+    readonly sent: number;
+    /** Parsed JSON response body (or the raw text if it wasn't JSON), `null` on an empty flush. */
+    readonly body: unknown;
+}
+/**
+ * One Langfuse ingestion batch item. `id` is the batch-envelope id — Langfuse's
+ * idempotency/dedup key, which MUST be a unique string per operation (a create
+ * and a later update of the same object share a body id but need distinct
+ * envelope ids). `body` is any JSON object (a `trace-create`, `generation-create`,
+ * `span-update`, `score-create`, … payload).
+ */
+interface IngestionItem {
+    readonly id: string;
+    readonly type: string;
+    readonly timestamp: string;
+    readonly body: object;
+}
+/** A batching Langfuse ingestion transport. */
+interface IngestionClient {
+    /** Buffer one item for the next flush. */
+    enqueue(item: IngestionItem): void;
+    /** Number of buffered items not yet flushed. */
+    size(): number;
+    /** Drain the buffer and POST it. Atomic: items enqueued during the in-flight
+     *  request stay buffered for the next flush rather than being dropped. */
+    flush(): Promise<FlushResult>;
+}
+/** Build a batching Langfuse ingestion client. */
+declare function createIngestionClient(cfg: IngestionConfig): IngestionClient;
+
+/**
+ * Dependency-free Langfuse ingestion REST API sink.
+ *
+ * Maps the agentproto {@link EvalEvent} stream into Langfuse `trace-create`
+ * and `score-create` objects and batches them for the public ingestion
+ * endpoint (`POST /api/public/ingestion`). No Langfuse SDK is used.
+ */
+
+/** Configuration for the Langfuse telemetry sink. */
+interface LangfuseTelemetryConfig {
+    /** Langfuse public key (used as the Basic auth username). */
+    readonly publicKey: string;
+    /** Langfuse secret key (used as the Basic auth password). */
+    readonly secretKey: string;
+    /** Langfuse base URL, e.g. `https://cloud.langfuse.com`. */
+    readonly baseUrl: string;
+    /** Optional environment label forwarded to Langfuse objects. */
+    readonly environment?: string;
+    /** Optional fetch implementation (defaults to `globalThis.fetch`). */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Public type of the sink returned by {@link langfuseTelemetry}. */
+type LangfuseTelemetrySink = Telemetry<EvalEvent> & {
+    flush(): Promise<FlushResult>;
+};
+/**
+ * Build a Langfuse ingestion sink for {@link EvalEvent}s.
+ *
+ * `emit()` buffers events into a batch. `flush()` POSTs the batch to
+ * `${cfg.baseUrl}/api/public/ingestion` with Basic auth and returns the
+ * HTTP status plus parsed response body.
+ */
+declare function langfuseTelemetry(cfg: LangfuseTelemetryConfig): LangfuseTelemetrySink;
+
+export { type FlushResult, type IngestionClient, type IngestionConfig, type IngestionItem, type LangfuseTelemetryConfig, type LangfuseTelemetrySink, createIngestionClient, langfuseTelemetry };

package/dist/index.mjs

@@ -0,0 +1,157 @@
+/**
+ * @agentproto/telemetry-langfuse v0.1.0
+ * Dependency-free Langfuse ingestion REST API sink for agentproto eval events.
+ */
+
+// src/ingestion.ts
+function createIngestionClient(cfg) {
+  const fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+  const auth = `Basic ${Buffer.from(`${cfg.publicKey}:${cfg.secretKey}`).toString("base64")}`;
+  const url = `${cfg.baseUrl}/api/public/ingestion`;
+  const batch = [];
+  return {
+    enqueue(item) {
+      batch.push(item);
+    },
+    size() {
+      return batch.length;
+    },
+    async flush() {
+      const items = batch.splice(0, batch.length);
+      if (items.length === 0) {
+        return { status: 0, sent: 0, body: null };
+      }
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: auth
+        },
+        body: JSON.stringify({ batch: items })
+      });
+      const text = await response.text();
+      let body;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+      return { status: response.status, sent: items.length, body };
+    }
+  };
+}
+
+// src/langfuse.ts
+function langfuseTelemetry(cfg) {
+  const client = createIngestionClient(cfg);
+  const tracedRuns = /* @__PURE__ */ new Set();
+  const caseSpanId = (runId, caseId) => `${runId}:case:${caseId}`;
+  function withEnv(body) {
+    if (cfg.environment !== void 0) return { ...body, environment: cfg.environment };
+    return body;
+  }
+  function pushTrace(op, timestamp, body) {
+    client.enqueue({ id: `${body.id}#${op}`, type: "trace-create", timestamp, body: withEnv(body) });
+  }
+  function pushScore(timestamp, body) {
+    client.enqueue({ id: `${body.id}#score`, type: "score-create", timestamp, body: withEnv(body) });
+  }
+  function pushSpanCreate(timestamp, body) {
+    client.enqueue({ id: `${body.id}#span-create`, type: "span-create", timestamp, body: withEnv(body) });
+  }
+  function pushSpanUpdate(timestamp, body) {
+    client.enqueue({ id: `${body.id}#span-update`, type: "span-update", timestamp, body: withEnv(body) });
+  }
+  return {
+    emit(event) {
+      switch (event.kind) {
+        case "eval.started": {
+          if (tracedRuns.has(event.runId)) return;
+          tracedRuns.add(event.runId);
+          pushTrace("create", event.at, {
+            id: event.runId,
+            name: `eval:${event.suiteId}`,
+            timestamp: event.at,
+            input: {
+              suiteId: event.suiteId,
+              caseCount: event.caseCount,
+              scorerCount: event.scorerCount
+            },
+            metadata: {
+              caseCount: event.caseCount,
+              scorerCount: event.scorerCount
+            }
+          });
+          break;
+        }
+        case "eval.case.started": {
+          pushSpanCreate(event.at, {
+            id: caseSpanId(event.runId, event.caseId),
+            traceId: event.runId,
+            name: `case:${event.caseId}`,
+            startTime: event.at,
+            input: { caseId: event.caseId }
+          });
+          break;
+        }
+        case "eval.case.scored": {
+          pushScore(event.at, {
+            id: `${event.runId}:${event.caseId}:${event.scorerId}`,
+            traceId: event.runId,
+            name: event.scorerId,
+            value: event.value,
+            dataType: "NUMERIC",
+            comment: `case=${event.caseId} passed=${event.passed}`,
+            observationId: caseSpanId(event.runId, event.caseId),
+            timestamp: event.at
+          });
+          break;
+        }
+        case "eval.case.finished": {
+          pushSpanUpdate(event.at, {
+            id: caseSpanId(event.runId, event.caseId),
+            traceId: event.runId,
+            endTime: event.at,
+            output: { passed: event.passed }
+          });
+          break;
+        }
+        case "eval.finished": {
+          const passRate = event.total > 0 ? event.passedCount / event.total : 0;
+          pushTrace("output", event.at, {
+            id: event.runId,
+            name: `eval:${event.suiteId}`,
+            timestamp: event.at,
+            output: {
+              total: event.total,
+              passedCount: event.passedCount,
+              failedCount: event.total - event.passedCount,
+              meanValue: event.meanValue,
+              passRate,
+              durationMs: event.durationMs
+            }
+          });
+          for (const name of ["eval.meanValue", "eval.passRate"]) {
+            const value = name === "eval.meanValue" ? event.meanValue : passRate;
+            pushScore(event.at, {
+              id: `${event.runId}:${name}`,
+              traceId: event.runId,
+              name,
+              value,
+              dataType: "NUMERIC",
+              timestamp: event.at
+            });
+          }
+          break;
+        }
+      }
+    },
+    flush() {
+      return client.flush();
+    }
+  };
+}
+
+export { createIngestionClient, langfuseTelemetry };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ingestion.ts","../src/langfuse.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Shared Langfuse ingestion transport — auth, a batch buffer, and a flush that\n * POSTs to `${baseUrl}/api/public/ingestion` with Basic auth. Both the eval\n * sink (`langfuseTelemetry`) and the agent-session tracer map their own domain\n * events into Langfuse batch items and hand them to this client; the client\n * owns nothing domain-specific — just the wire.\n */\n\n/** Credentials + endpoint for a Langfuse ingestion client. */\nexport interface IngestionConfig {\n  /** Langfuse public key (Basic auth username). */\n  readonly publicKey: string\n  /** Langfuse secret key (Basic auth password). */\n  readonly secretKey: string\n  /** Langfuse base URL, e.g. `https://cloud.langfuse.com`. */\n  readonly baseUrl: string\n  /** Optional fetch implementation (defaults to `globalThis.fetch`). */\n  readonly fetchImpl?: typeof fetch\n}\n\n/** Result of a {@link IngestionClient.flush}. */\nexport interface FlushResult {\n  /** HTTP status, or `0` when the batch was empty and no request was made. */\n  readonly status: number\n  /** Number of batch items actually sent. */\n  readonly sent: number\n  /** Parsed JSON response body (or the raw text if it wasn't JSON), `null` on an empty flush. */\n  readonly body: unknown\n}\n\n/**\n * One Langfuse ingestion batch item. `id` is the batch-envelope id — Langfuse's\n * idempotency/dedup key, which MUST be a unique string per operation (a create\n * and a later update of the same object share a body id but need distinct\n * envelope ids). `body` is any JSON object (a `trace-create`, `generation-create`,\n * `span-update`, `score-create`, … payload).\n */\nexport interface IngestionItem {\n  readonly id: string\n  readonly type: string\n  readonly timestamp: string\n  readonly body: object\n}\n\n/** A batching Langfuse ingestion transport. */\nexport interface IngestionClient {\n  /** Buffer one item for the next flush. */\n  enqueue(item: IngestionItem): void\n  /** Number of buffered items not yet flushed. */\n  size(): number\n  /** Drain the buffer and POST it. Atomic: items enqueued during the in-flight\n   *  request stay buffered for the next flush rather than being dropped. */\n  flush(): Promise<FlushResult>\n}\n\n/** Build a batching Langfuse ingestion client. */\nexport function createIngestionClient(cfg: IngestionConfig): IngestionClient {\n  const fetchImpl = cfg.fetchImpl ?? globalThis.fetch\n  const auth = `Basic ${Buffer.from(`${cfg.publicKey}:${cfg.secretKey}`).toString(\"base64\")}`\n  const url = `${cfg.baseUrl}/api/public/ingestion`\n  const batch: IngestionItem[] = []\n\n  return {\n    enqueue(item: IngestionItem): void {\n      batch.push(item)\n    },\n    size(): number {\n      return batch.length\n    },\n    async flush(): Promise<FlushResult> {\n      // Take the current buffer up front so anything enqueued while the POST is\n      // in flight is preserved for the next flush (a naive clear-after-await\n      // would drop those). Empty batch → no request.\n      const items = batch.splice(0, batch.length)\n      if (items.length === 0) {\n        return { status: 0, sent: 0, body: null }\n      }\n      const response = await fetchImpl(url, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: auth,\n        },\n        body: JSON.stringify({ batch: items }),\n      })\n      const text = await response.text()\n      let body: unknown\n      try {\n        body = JSON.parse(text)\n      } catch {\n        body = text\n      }\n      return { status: response.status, sent: items.length, body }\n    },\n  }\n}\n","/**\n * Dependency-free Langfuse ingestion REST API sink.\n *\n * Maps the agentproto {@link EvalEvent} stream into Langfuse `trace-create`\n * and `score-create` objects and batches them for the public ingestion\n * endpoint (`POST /api/public/ingestion`). No Langfuse SDK is used.\n */\n\nimport type { EvalEvent } from \"@agentproto/eval\"\nimport type { Telemetry } from \"@agentproto/telemetry\"\nimport { createIngestionClient, type FlushResult } from \"./ingestion.js\"\n\nexport type { FlushResult } from \"./ingestion.js\"\n\n/** Configuration for the Langfuse telemetry sink. */\nexport interface LangfuseTelemetryConfig {\n  /** Langfuse public key (used as the Basic auth username). */\n  readonly publicKey: string\n  /** Langfuse secret key (used as the Basic auth password). */\n  readonly secretKey: string\n  /** Langfuse base URL, e.g. `https://cloud.langfuse.com`. */\n  readonly baseUrl: string\n  /** Optional environment label forwarded to Langfuse objects. */\n  readonly environment?: string\n  /** Optional fetch implementation (defaults to `globalThis.fetch`). */\n  readonly fetchImpl?: typeof fetch\n}\n\n/** Public type of the sink returned by {@link langfuseTelemetry}. */\nexport type LangfuseTelemetrySink = Telemetry<EvalEvent> & {\n  flush(): Promise<FlushResult>\n}\n\n/** A JSON-serializable value — Langfuse `input`/`output`/`metadata` payloads. */\ntype JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | { readonly [key: string]: JsonValue }\n  | readonly JsonValue[]\n\ntype TraceCreateBody = {\n  readonly id: string\n  readonly name: string\n  readonly timestamp: string\n  readonly environment?: string\n  /** Suite descriptor, set on `eval.started`. */\n  readonly input?: JsonValue\n  /** Aggregate result, upserted on `eval.finished`. */\n  readonly output?: JsonValue\n  readonly metadata?: {\n    readonly caseCount: number\n    readonly scorerCount: number\n  }\n}\n\ntype ScoreCreateBody = {\n  readonly id: string\n  readonly traceId: string\n  readonly name: string\n  readonly value: number\n  readonly dataType: \"NUMERIC\"\n  readonly comment?: string\n  /** Nests per-case scores under their case span (see {@link SpanCreateBody}). */\n  readonly observationId?: string\n  readonly timestamp: string\n  readonly environment?: string\n}\n\ntype SpanCreateBody = {\n  readonly id: string\n  readonly traceId: string\n  readonly name: string\n  readonly startTime: string\n  readonly input?: JsonValue\n  readonly environment?: string\n}\n\ntype SpanUpdateBody = {\n  readonly id: string\n  readonly traceId: string\n  readonly endTime: string\n  readonly output?: JsonValue\n  readonly environment?: string\n}\n\n// Envelope ids are derived `${bodyId}#${operation}` (see the push helpers): a\n// unique string per operation so Langfuse's dedup doesn't collapse a create and\n// a later upsert/update of the same object. Items are transported by\n// `createIngestionClient` (see ./ingestion.ts).\n\n/**\n * Build a Langfuse ingestion sink for {@link EvalEvent}s.\n *\n * `emit()` buffers events into a batch. `flush()` POSTs the batch to\n * `${cfg.baseUrl}/api/public/ingestion` with Basic auth and returns the\n * HTTP status plus parsed response body.\n */\nexport function langfuseTelemetry(cfg: LangfuseTelemetryConfig): LangfuseTelemetrySink {\n  const client = createIngestionClient(cfg)\n  const tracedRuns = new Set<string>()\n\n  /** Stable observation id for a case's span (scores nest under it). */\n  const caseSpanId = (runId: string, caseId: string): string => `${runId}:case:${caseId}`\n\n  /** Add the optional `environment` label to any body without an `as` cast. */\n  function withEnv<T extends { readonly environment?: string }>(body: T): T {\n    if (cfg.environment !== undefined) return { ...body, environment: cfg.environment }\n    return body\n  }\n\n  function pushTrace(op: string, timestamp: string, body: TraceCreateBody): void {\n    client.enqueue({ id: `${body.id}#${op}`, type: \"trace-create\", timestamp, body: withEnv(body) })\n  }\n\n  function pushScore(timestamp: string, body: ScoreCreateBody): void {\n    client.enqueue({ id: `${body.id}#score`, type: \"score-create\", timestamp, body: withEnv(body) })\n  }\n\n  function pushSpanCreate(timestamp: string, body: SpanCreateBody): void {\n    client.enqueue({ id: `${body.id}#span-create`, type: \"span-create\", timestamp, body: withEnv(body) })\n  }\n\n  function pushSpanUpdate(timestamp: string, body: SpanUpdateBody): void {\n    client.enqueue({ id: `${body.id}#span-update`, type: \"span-update\", timestamp, body: withEnv(body) })\n  }\n\n  return {\n    emit(event: EvalEvent): void {\n      switch (event.kind) {\n        case \"eval.started\": {\n          if (tracedRuns.has(event.runId)) return\n          tracedRuns.add(event.runId)\n          pushTrace(\"create\", event.at, {\n            id: event.runId,\n            name: `eval:${event.suiteId}`,\n            timestamp: event.at,\n            input: {\n              suiteId: event.suiteId,\n              caseCount: event.caseCount,\n              scorerCount: event.scorerCount,\n            },\n            metadata: {\n              caseCount: event.caseCount,\n              scorerCount: event.scorerCount,\n            },\n          })\n          break\n        }\n        case \"eval.case.started\": {\n          // Open a per-case span so the trace has a nested tree and each case's\n          // scores hang under their own observation.\n          pushSpanCreate(event.at, {\n            id: caseSpanId(event.runId, event.caseId),\n            traceId: event.runId,\n            name: `case:${event.caseId}`,\n            startTime: event.at,\n            input: { caseId: event.caseId },\n          })\n          break\n        }\n        case \"eval.case.scored\": {\n          pushScore(event.at, {\n            id: `${event.runId}:${event.caseId}:${event.scorerId}`,\n            traceId: event.runId,\n            name: event.scorerId,\n            value: event.value,\n            dataType: \"NUMERIC\",\n            comment: `case=${event.caseId} passed=${event.passed}`,\n            observationId: caseSpanId(event.runId, event.caseId),\n            timestamp: event.at,\n          })\n          break\n        }\n        case \"eval.case.finished\": {\n          // Close the case span with its pass/fail outcome.\n          pushSpanUpdate(event.at, {\n            id: caseSpanId(event.runId, event.caseId),\n            traceId: event.runId,\n            endTime: event.at,\n            output: { passed: event.passed },\n          })\n          break\n        }\n        case \"eval.finished\": {\n          const passRate = event.total > 0 ? event.passedCount / event.total : 0\n          // Upsert the trace with its aggregate outcome (same body id, distinct\n          // envelope op so it is not deduped against the `create`).\n          pushTrace(\"output\", event.at, {\n            id: event.runId,\n            name: `eval:${event.suiteId}`,\n            timestamp: event.at,\n            output: {\n              total: event.total,\n              passedCount: event.passedCount,\n              failedCount: event.total - event.passedCount,\n              meanValue: event.meanValue,\n              passRate,\n              durationMs: event.durationMs,\n            },\n          })\n          for (const name of [\"eval.meanValue\", \"eval.passRate\"] as const) {\n            const value = name === \"eval.meanValue\" ? event.meanValue : passRate\n            pushScore(event.at, {\n              id: `${event.runId}:${name}`,\n              traceId: event.runId,\n              name,\n              value,\n              dataType: \"NUMERIC\",\n              timestamp: event.at,\n            })\n          }\n          break\n        }\n        default: {\n          // Forward-compat: ignore unknown event kinds.\n          const _exhaustive: never = event\n          void _exhaustive\n        }\n      }\n    },\n\n    flush(): Promise<FlushResult> {\n      return client.flush()\n    },\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@agentproto/telemetry-langfuse",
+  "version": "0.2.0",
+  "description": "Langfuse ingestion REST API sink for @agentproto/telemetry. Dependency-free: maps EvalEvent batches to Langfuse trace-create and score-create objects over fetch.",
+  "keywords": [
+    "agentproto",
+    "telemetry",
+    "langfuse",
+    "eval",
+    "observability",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/telemetry-langfuse"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentproto/eval": "0.2.0",
+    "@agentproto/telemetry": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}