@nightowlsdev/telemetry-langfuse 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+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 @@
+# @nightowlsdev/telemetry-langfuse
+
+A **Langfuse v5** telemetry exporter for `@nightowlsdev/core`. It maps a swarm run's
+`run`/`generation`/`tool` `SwarmSpan`s to OpenTelemetry spans (via
+`@nightowlsdev/telemetry-core`) and forwards them through Langfuse's OTel-native
+`LangfuseSpanProcessor`. Langfuse's default filter exports any span carrying `gen_ai.*`
+attributes — which `@nightowlsdev/telemetry-core` emits — so each model call lands as a Langfuse
+**generation** with its model, token usage, and cost.
+
+> Langfuse v5 is OTel-native. The old v3 `langfuse.trace()` / `.generation()` API is gone;
+> this package targets `@langfuse/otel`'s `LangfuseSpanProcessor`.
+
+It never imports `@mastra/*` and re-exports no Mastra types (the engine wall, CONTRACTS §1).
+
+## Install
+
+```bash
+pnpm add @nightowlsdev/telemetry-langfuse @nightowlsdev/core
+```
+
+## Factory
+
+```ts
+import { langfuseTelemetry } from "@nightowlsdev/telemetry-langfuse";
+
+const telemetry = langfuseTelemetry({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+  baseUrl: "https://cloud.langfuse.com", // optional
+  exportMode: "immediate",               // default here — flushes per run (serverless-safe)
+  environment: "prod",                   // optional
+  release: "1.4.0",                      // optional
+});
+```
+
+`exportMode: "immediate"` (the default) flushes on each run's export — ideal for
+serverless. Use `"batched"` for long-running hosts. The replayer **awaits `forceFlush()`**
+so spans aren't lost.
+
+## Wiring into a swarm
+
+```ts
+import { defineSwarm } from "@nightowlsdev/core";
+import { langfuseTelemetry } from "@nightowlsdev/telemetry-langfuse";
+
+const swarm = defineSwarm({
+  storage,
+  agents,
+  models: { allow: ["openai/gpt-5.5"] },
+  modelFactory,
+  cost: { maxSteps: 8, maxCostUsd: 1 },
+  telemetry: langfuseTelemetry({ publicKey, secretKey }),
+});
+```
+
+Telemetry is **best-effort**: a throwing or hung exporter never breaks the run (the engine
+exports in a `finally` and swallows export errors). Pass an array of exporters (or
+`compositeTelemetry`) to send to Langfuse and an OTLP backend at once.
+
+## Engine wall
+
+The built `dist/index.d.ts` contains zero `@mastra` references (enforced by
+`test/wall.test.ts`).

package/dist/index.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  langfuseTelemetry: () => langfuseTelemetry,
+  nightOwlsPlugin: () => nightOwlsPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_otel = require("@langfuse/otel");
+var import_telemetry_core = require("@nightowlsdev/telemetry-core");
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "telemetry-langfuse",
+  version: "0.0.0",
+  kind: "telemetry",
+  pkg: "@nightowlsdev/telemetry-langfuse",
+  description: "Langfuse (v5, OTel-native) exporter \u2014 LLM generations with model + token usage + cost.",
+  env: [
+    { key: "LANGFUSE_PUBLIC_KEY", example: "pk-lf-...", comment: "Langfuse public key" },
+    { key: "LANGFUSE_SECRET_KEY", example: "sk-lf-...", comment: "Langfuse secret key (server-side ONLY)" },
+    {
+      key: "LANGFUSE_BASEURL",
+      example: "https://cloud.langfuse.com",
+      comment: "Langfuse host (EU/US cloud or your self-hosted URL)"
+    }
+  ],
+  config: {
+    import: "import { langfuseTelemetry } from '@nightowlsdev/telemetry-langfuse';",
+    snippet: "telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey: env.LANGFUSE_PUBLIC_KEY, secretKey: env.LANGFUSE_SECRET_KEY, baseUrl: env.LANGFUSE_BASEURL })];",
+    marker: "telemetry"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init telemetry-langfuse`. NEVER connects.
+  init: (ctx) => {
+    ctx.log(
+      "Langfuse telemetry wired (composes with any other telemetry adapter) \u2014 set LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY + LANGFUSE_BASEURL."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this telemetry adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASEURL");
+        ctx.log("config: telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey, secretKey, baseUrl })]");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function langfuseTelemetry(opts = {}) {
+  const processor = opts.processor ?? new import_otel.LangfuseSpanProcessor({
+    publicKey: opts.publicKey,
+    secretKey: opts.secretKey,
+    baseUrl: opts.baseUrl,
+    exportMode: opts.exportMode ?? "immediate",
+    environment: opts.environment,
+    release: opts.release
+  });
+  return (0, import_telemetry_core.replayerExporter)({ processor, serviceName: "nightowls" });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  langfuseTelemetry,
+  nightOwlsPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,78 @@
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { TelemetryExporter } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for the Langfuse exporter. `@nightowlsdev/cli` discovers this,
+ * dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:telemetry` marker. Telemetry
+ *                COMPOSES: the snippet pushes this exporter onto the `telemetry` array, so multiple
+ *                telemetry adapters coexist (`telemetry = [...(telemetry ?? []), langfuseTelemetry({...})];`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to Langfuse),
+ *  - `commands`→ `owl telemetry-langfuse <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "telemetry-langfuse";
+    readonly version: "0.0.0";
+    readonly kind: "telemetry";
+    readonly pkg: "@nightowlsdev/telemetry-langfuse";
+    readonly description: "Langfuse (v5, OTel-native) exporter — LLM generations with model + token usage + cost.";
+    readonly env: readonly [{
+        readonly key: "LANGFUSE_PUBLIC_KEY";
+        readonly example: "pk-lf-...";
+        readonly comment: "Langfuse public key";
+    }, {
+        readonly key: "LANGFUSE_SECRET_KEY";
+        readonly example: "sk-lf-...";
+        readonly comment: "Langfuse secret key (server-side ONLY)";
+    }, {
+        readonly key: "LANGFUSE_BASEURL";
+        readonly example: "https://cloud.langfuse.com";
+        readonly comment: "Langfuse host (EU/US cloud or your self-hosted URL)";
+    }];
+    readonly config: {
+        readonly import: "import { langfuseTelemetry } from '@nightowlsdev/telemetry-langfuse';";
+        readonly snippet: "telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey: env.LANGFUSE_PUBLIC_KEY, secretKey: env.LANGFUSE_SECRET_KEY, baseUrl: env.LANGFUSE_BASEURL })];";
+        readonly marker: "telemetry";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this telemetry adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface LangfuseTelemetryOpts {
+    publicKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+    /** 'immediate' (serverless, default here) flushes per export; 'batched' for long-running hosts. */
+    exportMode?: "immediate" | "batched";
+    environment?: string;
+    release?: string;
+    /** Test/advanced override: provide the SpanProcessor directly (skips LangfuseSpanProcessor construction). */
+    processor?: SpanProcessor;
+}
+/**
+ * Map Night Owls SwarmSpans to Langfuse (v5, OTel-native). The LangfuseSpanProcessor's default filter
+ * forwards any span carrying gen_ai.* attributes — which telemetry-core emits — so generations land
+ * as Langfuse generations with model + token usage + cost.
+ */
+declare function langfuseTelemetry(opts?: LangfuseTelemetryOpts): TelemetryExporter;
+
+export { type LangfuseTelemetryOpts, langfuseTelemetry, nightOwlsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { TelemetryExporter } from '@nightowlsdev/core';
+
+/**
+ * The Night Owls adapter plugin manifest for the Langfuse exporter. `@nightowlsdev/cli` discovers this,
+ * dynamic-imports it, and acts on it declaratively:
+ *  - `env`     → merged into `.env.example` (idempotent, only if the KEY is absent),
+ *  - `config`  → the `import` + wiring `snippet` inserted at the `// nightowls:telemetry` marker. Telemetry
+ *                COMPOSES: the snippet pushes this exporter onto the `telemetry` array, so multiple
+ *                telemetry adapters coexist (`telemetry = [...(telemetry ?? []), langfuseTelemetry({...})];`),
+ *  - `init`    → a print-only hook run after the wiring (it NEVER connects to Langfuse),
+ *  - `commands`→ `owl telemetry-langfuse <cmd>` subcommands (e.g. `info` — pure, no network).
+ *
+ * This object STRUCTURALLY matches the CLI's `NightOwlsPlugin` type but does NOT import it (no dependency
+ * cycle): all codegen lives in `@nightowlsdev/cli`; this adapter stays data-only. The `init`/command handler
+ * contexts are typed STRUCTURALLY (local `Ctx`/inline shapes) — never importing `@nightowlsdev/cli`.
+ */
+/** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
+type Ctx = {
+    cwd: string;
+    log: (m: string) => void;
+    args: string[];
+    options: Record<string, unknown>;
+};
+declare const nightOwlsPlugin: {
+    readonly name: "telemetry-langfuse";
+    readonly version: "0.0.0";
+    readonly kind: "telemetry";
+    readonly pkg: "@nightowlsdev/telemetry-langfuse";
+    readonly description: "Langfuse (v5, OTel-native) exporter — LLM generations with model + token usage + cost.";
+    readonly env: readonly [{
+        readonly key: "LANGFUSE_PUBLIC_KEY";
+        readonly example: "pk-lf-...";
+        readonly comment: "Langfuse public key";
+    }, {
+        readonly key: "LANGFUSE_SECRET_KEY";
+        readonly example: "sk-lf-...";
+        readonly comment: "Langfuse secret key (server-side ONLY)";
+    }, {
+        readonly key: "LANGFUSE_BASEURL";
+        readonly example: "https://cloud.langfuse.com";
+        readonly comment: "Langfuse host (EU/US cloud or your self-hosted URL)";
+    }];
+    readonly config: {
+        readonly import: "import { langfuseTelemetry } from '@nightowlsdev/telemetry-langfuse';";
+        readonly snippet: "telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey: env.LANGFUSE_PUBLIC_KEY, secretKey: env.LANGFUSE_SECRET_KEY, baseUrl: env.LANGFUSE_BASEURL })];";
+        readonly marker: "telemetry";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [{
+        readonly name: "info";
+        readonly description: "Show the env + config this telemetry adapter contributes.";
+        readonly run: (ctx: Ctx) => void;
+    }];
+};
+
+interface LangfuseTelemetryOpts {
+    publicKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+    /** 'immediate' (serverless, default here) flushes per export; 'batched' for long-running hosts. */
+    exportMode?: "immediate" | "batched";
+    environment?: string;
+    release?: string;
+    /** Test/advanced override: provide the SpanProcessor directly (skips LangfuseSpanProcessor construction). */
+    processor?: SpanProcessor;
+}
+/**
+ * Map Night Owls SwarmSpans to Langfuse (v5, OTel-native). The LangfuseSpanProcessor's default filter
+ * forwards any span carrying gen_ai.* attributes — which telemetry-core emits — so generations land
+ * as Langfuse generations with model + token usage + cost.
+ */
+declare function langfuseTelemetry(opts?: LangfuseTelemetryOpts): TelemetryExporter;
+
+export { type LangfuseTelemetryOpts, langfuseTelemetry, nightOwlsPlugin };

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/index.ts
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { replayerExporter } from "@nightowlsdev/telemetry-core";
+
+// src/plugin.ts
+var nightOwlsPlugin = {
+  name: "telemetry-langfuse",
+  version: "0.0.0",
+  kind: "telemetry",
+  pkg: "@nightowlsdev/telemetry-langfuse",
+  description: "Langfuse (v5, OTel-native) exporter \u2014 LLM generations with model + token usage + cost.",
+  env: [
+    { key: "LANGFUSE_PUBLIC_KEY", example: "pk-lf-...", comment: "Langfuse public key" },
+    { key: "LANGFUSE_SECRET_KEY", example: "sk-lf-...", comment: "Langfuse secret key (server-side ONLY)" },
+    {
+      key: "LANGFUSE_BASEURL",
+      example: "https://cloud.langfuse.com",
+      comment: "Langfuse host (EU/US cloud or your self-hosted URL)"
+    }
+  ],
+  config: {
+    import: "import { langfuseTelemetry } from '@nightowlsdev/telemetry-langfuse';",
+    snippet: "telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey: env.LANGFUSE_PUBLIC_KEY, secretKey: env.LANGFUSE_SECRET_KEY, baseUrl: env.LANGFUSE_BASEURL })];",
+    marker: "telemetry"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init telemetry-langfuse`. NEVER connects.
+  init: (ctx) => {
+    ctx.log(
+      "Langfuse telemetry wired (composes with any other telemetry adapter) \u2014 set LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY + LANGFUSE_BASEURL."
+    );
+  },
+  commands: [
+    {
+      name: "info",
+      description: "Show the env + config this telemetry adapter contributes.",
+      // PURE — no network. Reads only the static manifest data.
+      run: (ctx) => {
+        ctx.log("env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASEURL");
+        ctx.log("config: telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey, secretKey, baseUrl })]");
+      }
+    }
+  ]
+};
+
+// src/index.ts
+function langfuseTelemetry(opts = {}) {
+  const processor = opts.processor ?? new LangfuseSpanProcessor({
+    publicKey: opts.publicKey,
+    secretKey: opts.secretKey,
+    baseUrl: opts.baseUrl,
+    exportMode: opts.exportMode ?? "immediate",
+    environment: opts.environment,
+    release: opts.release
+  });
+  return replayerExporter({ processor, serviceName: "nightowls" });
+}
+export {
+  langfuseTelemetry,
+  nightOwlsPlugin
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nightowlsdev/telemetry-langfuse",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/telemetry-langfuse"
+  },
+  "homepage": "https://github.com/cueplusplus/corale#readme",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@langfuse/otel": "^5.4.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@nightowlsdev/telemetry-core": "0.1.2"
+  },
+  "peerDependencies": {
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@types/node": "^24.12.4",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/core": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}