sebbi 1.2.1 → 1.3.0

package/README.md

@@ -64,6 +64,25 @@ await r.wait();   // optional
 console.log(r.url, r.sealed, r.blockIndex);
 ```
 
+## OpenTelemetry
+
+Already tracing? Add the processor and every agent run and tool call you trace gets a receipt, with the link written onto the span (`sebbi.receipt.id`, `sebbi.receipt.url`).
+
+```js
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { SebbiSpanProcessor } from "sebbi/otel";
+
+new NodeSDK({ spanProcessors: [new SebbiSpanProcessor(), /* your exporter's processor */] }).start();
+```
+
+**Vercel AI SDK:** turn on telemetry and every `ai.toolCall` and `ai.generateText` span is sealed:
+
+```js
+await generateText({ model, tools, prompt, experimental_telemetry: { isEnabled: true } });
+```
+
+Also recognised: OpenTelemetry GenAI conventions (`gen_ai.operation.name`), OpenInference (`openinference.span.kind`) and any span with `sebbi.seal = true`. Options: `{ llm, allSpans, filter, prefix, onReceipt }`. `SebbiSpanExporter` does the same inside an existing `BatchSpanProcessor`. Only two fingerprints per span leave your process. Fingerprints match the Python client exactly, so `sebbi verify-otlp traces.json` checks spans from either.
+
 ## Reversing an action
 
 ```js

package/index.cjs

@@ -15,7 +15,7 @@
  * Zero dependencies. Node 18+, Deno, Bun, edge runtimes and browsers.
  */
 
-const VERSION = "1.2.1";
+const VERSION = "1.3.0";
 const SITE = "https://sebbi.pro";
 const env = (k) => (typeof process !== "undefined" && process.env ? process.env[k] || "" : "");
 
@@ -205,6 +205,14 @@ function seal(input, output, label = "", outcome = "ok") {
   return p;
 }
 
+/** Internal: seal already-computed fingerprints, optionally under a chosen id (used by sebbi/otel). */
+function _sealHashes(inputHash, outputHash, label = "", outcome = "ok", id = null) {
+  const r = new Receipt(label, inputHash, outputHash, outcome);
+  if (id) r.id = id;
+  lastP = Promise.resolve(r);
+  return enqueue(r);
+}
+
 /**
  * Reverse an action you sealed earlier. Nothing is deleted: the original stays
  * sealed and is shown as REVERSED, linked to the new reversal receipt. The
@@ -290,4 +298,4 @@ if (typeof process !== "undefined" && typeof process.on === "function") {
   process.on("beforeExit", () => { if (queue.length) kick(); });
 }
 
-module.exports = { receipt, seal, reverse, wrapTools, last, flush, configure, stats, fingerprint, check, Receipt, VERSION };
+module.exports = { receipt, seal, reverse, wrapTools, last, flush, configure, stats, fingerprint, check, Receipt, VERSION, _sealHashes };

package/otel.cjs

@@ -0,0 +1,198 @@
+"use strict";
+/*
+ * sebbi for OpenTelemetry: a sealed receipt for every agent and tool span you
+ * already trace, with the receipt link written onto the span itself.
+ *
+ *   const { SebbiSpanProcessor } = require("sebbi/otel");
+ *   new NodeSDK({ spanProcessors: [new SebbiSpanProcessor(), ...yourProcessors] }).start();
+ *
+ * Vercel AI SDK: turn on experimental_telemetry: { isEnabled: true } and every
+ * ai.toolCall / ai.generateText span gets a receipt. Also recognised: the
+ * OpenTelemetry GenAI conventions (gen_ai.operation.name), OpenInference
+ * (openinference.span.kind) and any span with attribute sebbi.seal = true.
+ *
+ * Only two SHA-256 fingerprints, a short label and a timestamp leave your
+ * process. Fingerprints follow the same rules as the Python client, so
+ * `sebbi verify-otlp traces.json` checks spans from either.
+ */
+const core = require("./index.cjs");
+
+const ATTR_ID = "sebbi.receipt.id";
+const ATTR_URL = "sebbi.receipt.url";
+const ATTR_MARK = "sebbi.seal";
+const SPEC = "sebbi-otel-span/1";
+const SITE = "https://sebbi.pro";
+
+const OUTPUT_PREFIXES = [
+  "gen_ai.output.", "gen_ai.completion", "gen_ai.response.", "gen_ai.usage.", "gen_ai.tool.call.result",
+  "output.", "llm.output_messages", "llm.token_count.",
+  "ai.response.", "ai.toolCall.result", "ai.result.", "ai.usage.",
+];
+const GENAI = { execute_tool: "tool", invoke_agent: "agent", create_agent: "agent", chat: "llm", text_completion: "llm", generate_content: "llm" };
+const OPENINF = { TOOL: "tool", AGENT: "agent", LLM: "llm" };
+const VERCEL_AGENT = ["ai.generateText", "ai.streamText", "ai.generateObject", "ai.streamObject"];
+
+function spanKind(name, attributes) {
+  const a = attributes || {};
+  if ([true, "true", "1", 1].includes(a[ATTR_MARK])) return "marked";
+  const op = a["gen_ai.operation.name"];
+  if (typeof op === "string" && GENAI[op]) return GENAI[op];
+  const oi = a["openinference.span.kind"];
+  if (typeof oi === "string" && OPENINF[oi.toUpperCase()]) return OPENINF[oi.toUpperCase()];
+  const vid = a["ai.operationId"] || name || "";
+  if (vid === "ai.toolCall") return "tool";
+  if (VERCEL_AGENT.includes(vid)) return "agent";
+  if (vid.startsWith("ai.") && (vid.endsWith(".doGenerate") || vid.endsWith(".doStream"))) return "llm";
+  return null;
+}
+
+function spanLabel(name, attributes, kind, prefix = "") {
+  const a = attributes || {};
+  const first = (...keys) => { for (const k of keys) if (typeof a[k] === "string" && a[k]) return a[k]; return name || "span"; };
+  let s;
+  if (kind === "tool") s = "tool:" + first("gen_ai.tool.name", "tool.name", "ai.toolCall.name");
+  else if (kind === "agent") s = "agent:" + first("gen_ai.agent.name", "agent.name", "ai.telemetry.functionId");
+  else if (kind === "llm") s = "llm:" + first("gen_ai.request.model", "llm.model_name", "ai.model.id");
+  else s = name || "span";
+  return (prefix + s).slice(0, 80);
+}
+
+// Numbers, written the same way in Python and JavaScript.
+function num(x) {
+  if (!Number.isFinite(x)) return Number.isNaN(x) ? "NaN" : x > 0 ? "Infinity" : "-Infinity";
+  if (Number.isInteger(x)) return Math.abs(x) < 2 ** 53 ? (x === 0 ? 0 : x) : String(x);
+  return String(x);
+}
+function val(v) {
+  if (Array.isArray(v)) return v.map(val);
+  if (typeof v === "number") return num(v);
+  if (v === undefined || v === null) return null;
+  if (typeof v === "string" || typeof v === "boolean") return v;
+  return String(v);
+}
+function attrs(a, wantOutput) {
+  const out = {};
+  for (const k of Object.keys(a || {})) {
+    if (k.startsWith("sebbi.")) continue;
+    if (OUTPUT_PREFIXES.some((p) => k.startsWith(p)) === wantOutput) out[k] = val(a[k]);
+  }
+  return out;
+}
+function nanos(t) {
+  if (Array.isArray(t)) return (BigInt(t[0]) * 1000000000n + BigInt(t[1])).toString();
+  if (typeof t === "bigint") return t.toString();
+  if (typeof t === "string") return BigInt(t || "0").toString();
+  return BigInt(Math.trunc(Number(t) || 0)).toString();
+}
+const statusName = (c) => (typeof c === "number" ? { 0: "UNSET", 1: "OK", 2: "ERROR" }[c] || "UNSET"
+  : (["UNSET", "OK", "ERROR"].includes(String(c || "").toUpperCase().replace("STATUS_CODE_", "")) ? String(c).toUpperCase().replace("STATUS_CODE_", "") : "UNSET"));
+
+/** The two documents a span's receipt fingerprints. Same rules in every sebbi client. */
+function buildPayload(p) {
+  const input = {
+    spec: SPEC,
+    name: p.name || "",
+    trace_id: String(p.traceId || "").toLowerCase(),
+    span_id: String(p.spanId || "").toLowerCase(),
+    parent_span_id: String(p.parentSpanId || "").toLowerCase() || null,
+    start_time_unix_nano: nanos(p.start || 0),
+    attributes: attrs(p.attributes, false),
+  };
+  const output = {
+    end_time_unix_nano: nanos(p.end || 0),
+    status: statusName(p.statusCode || 0),
+    status_message: p.statusMessage || "",
+    attributes: attrs(p.attributes, true),
+    events: (p.events || []).map((e) => ({ name: e.name || "", time_unix_nano: nanos(e.time || 0),
+      attributes: Object.assign(attrs(e.attributes, false), attrs(e.attributes, true)) })),
+  };
+  return { input, output };
+}
+
+/** { input, output } documents for a finished OpenTelemetry JS span. */
+function spanPayload(span) {
+  const ctx = typeof span.spanContext === "function" ? span.spanContext() : span._spanContext || {};
+  const parent = (span.parentSpanContext && span.parentSpanContext.spanId) || span.parentSpanId || null;
+  return buildPayload({
+    name: span.name, traceId: ctx.traceId, spanId: ctx.spanId, parentSpanId: parent,
+    start: span.startTime, end: span.endTime, attributes: span.attributes,
+    statusCode: span.status ? span.status.code : 0, statusMessage: span.status ? span.status.message : "",
+    events: (span.events || []).map((e) => ({ name: e.name, time: e.time, attributes: e.attributes })),
+  });
+}
+
+async function spanFingerprints(span) {
+  const { input, output } = spanPayload(span);
+  return { inputHash: await core.fingerprint(input), outputHash: await core.fingerprint(output) };
+}
+
+function policy(o = {}) {
+  return (span) => {
+    const kind = spanKind(span.name, span.attributes);
+    if (typeof o.filter === "function") { try { return o.filter(span) ? kind || "span" : null; } catch (_) { return null; } }
+    if (o.allSpans) return kind || "span";
+    if (kind === "tool" || kind === "agent" || kind === "marked" || (kind === "llm" && o.llm)) return kind;
+    return null;
+  };
+}
+
+const newId = () => {
+  const b = globalThis.crypto ? globalThis.crypto.getRandomValues(new Uint8Array(12)) : require("node:crypto").randomBytes(12);
+  return "r" + Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("").slice(0, 23);
+};
+
+/**
+ * Seals agent and tool spans as they end, and stamps each with its receipt
+ * link (sebbi.receipt.id / sebbi.receipt.url) when it starts.
+ * Options: { llm, allSpans, filter(span), prefix, onReceipt(span, receipt) }
+ */
+class SebbiSpanProcessor {
+  constructor(options = {}) {
+    this._o = options;
+    this._wants = policy(options);
+    this._pending = new Set();
+  }
+  onStart(span) {
+    try {
+      if (this._wants(span)) {
+        const id = newId();
+        span.setAttribute(ATTR_ID, id);
+        span.setAttribute(ATTR_URL, SITE + "/r/" + id);
+      }
+    } catch (_) {}
+  }
+  onEnd(span) {
+    let kind;
+    try { kind = this._wants(span); } catch (_) { return; }
+    if (!kind) return;
+    const p = (async () => {
+      const { inputHash, outputHash } = await spanFingerprints(span);
+      const id = span.attributes && typeof span.attributes[ATTR_ID] === "string" ? span.attributes[ATTR_ID] : null;
+      const outcome = statusName(span.status ? span.status.code : 0) === "ERROR" ? "error" : "ok";
+      const r = core._sealHashes(inputHash, outputHash, spanLabel(span.name, span.attributes, kind, this._o.prefix || ""), outcome, id);
+      if (typeof this._o.onReceipt === "function") this._o.onReceipt(span, r);
+      return r;
+    })().catch(() => null).finally(() => this._pending.delete(p));
+    this._pending.add(p);
+  }
+  async forceFlush() { await Promise.all([...this._pending]); await core.flush(30000); }
+  async shutdown() { await this.forceFlush(); }
+}
+
+/**
+ * The same sealing as a SpanExporter, for pipelines that already batch spans:
+ *   new BatchSpanProcessor(new SebbiSpanExporter())
+ * Exporters see spans after they end, so the link is not written onto the
+ * span; use SebbiSpanProcessor for that. Always reports success.
+ */
+class SebbiSpanExporter {
+  constructor(options = {}) { this._proc = new SebbiSpanProcessor(options); }
+  export(spans, resultCallback) {
+    for (const s of spans || []) this._proc.onEnd(s);
+    resultCallback({ code: 0 });
+  }
+  forceFlush() { return this._proc.forceFlush(); }
+  shutdown() { return this._proc.shutdown(); }
+}
+
+module.exports = { SebbiSpanProcessor, SebbiSpanExporter, spanKind, spanLabel, spanPayload, spanFingerprints, buildPayload, ATTR_ID, ATTR_URL };

package/otel.d.ts

@@ -0,0 +1,35 @@
+import type { Receipt } from "./index";
+export interface SebbiOtelOptions {
+  /** Also seal every model call (chat / doGenerate spans). */
+  llm?: boolean;
+  /** Seal every span. Watch your daily volume. */
+  allSpans?: boolean;
+  /** Your own rule, asked at span start and end; the answer at end decides. */
+  filter?: (span: any) => boolean;
+  /** Put in front of every receipt label. */
+  prefix?: string;
+  /** Called after each span is queued for sealing. */
+  onReceipt?: (span: any, receipt: Receipt) => void;
+}
+/** OpenTelemetry SpanProcessor: seals agent and tool spans and writes sebbi.receipt.id / sebbi.receipt.url onto them. */
+export declare class SebbiSpanProcessor {
+  constructor(options?: SebbiOtelOptions);
+  onStart(span: any, parentContext?: any): void;
+  onEnd(span: any): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+/** OpenTelemetry SpanExporter with the same sealing (no link written onto the span). */
+export declare class SebbiSpanExporter {
+  constructor(options?: SebbiOtelOptions);
+  export(spans: any[], resultCallback: (result: { code: number }) => void): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+export declare function spanKind(name: string, attributes?: Record<string, unknown>): "tool" | "agent" | "llm" | "marked" | null;
+export declare function spanLabel(name: string, attributes: Record<string, unknown> | undefined, kind: string | null, prefix?: string): string;
+export declare function spanPayload(span: any): { input: Record<string, unknown>; output: Record<string, unknown> };
+export declare function spanFingerprints(span: any): Promise<{ inputHash: string; outputHash: string }>;
+export declare function buildPayload(p: Record<string, unknown>): { input: Record<string, unknown>; output: Record<string, unknown> };
+export declare const ATTR_ID: "sebbi.receipt.id";
+export declare const ATTR_URL: "sebbi.receipt.url";

package/otel.mjs

@@ -0,0 +1,4 @@
+// sebbi for OpenTelemetry (ESM). See otel.cjs for the full notes.
+import m from "./otel.cjs";
+export const { SebbiSpanProcessor, SebbiSpanExporter, spanKind, spanLabel, spanPayload, spanFingerprints, buildPayload, ATTR_ID, ATTR_URL } = m;
+export default m;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sebbi",
-  "version": "1.2.1",
-  "description": "A receipt for every AI agent action. One line: every tool call gets a sealed, publicly checkable receipt. Vercel AI SDK, LangChain.js, Mastra, MCP.",
+  "version": "1.3.0",
+  "description": "A receipt for every AI agent action. One line: every tool call gets a sealed, publicly checkable receipt. Vercel AI SDK, OpenTelemetry, LangChain.js, Mastra, MCP.",
   "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -14,6 +14,11 @@
     "./ai-sdk": {
       "types": "./ai-sdk.d.ts",
       "import": "./ai-sdk.mjs"
+    },
+    "./otel": {
+      "types": "./otel.d.ts",
+      "import": "./otel.mjs",
+      "require": "./otel.cjs"
     }
   },
   "files": [
@@ -22,6 +27,9 @@
     "index.d.ts",
     "ai-sdk.mjs",
     "ai-sdk.d.ts",
+    "otel.cjs",
+    "otel.mjs",
+    "otel.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -43,7 +51,11 @@
     "eu-ai-act",
     "compliance",
     "provenance",
-    "merkle"
+    "merkle",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "observability"
   ],
   "homepage": "https://sebbi.pro/receipts",
   "author": "Monop Content <justrightdecorators@gmail.com>",
@@ -63,5 +75,8 @@
   },
   "bugs": {
     "url": "https://github.com/justrightdecorators-ops/sebbi-sdk/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs"
   }
 }