@backendkit-labs/agent-otel 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @backendkit-labs/agent-otel
+
+OpenTelemetry export for the traces of [`@backendkit-labs/agent-core`](../core). Pick the exporter that fits
+how you run telemetry:
+
+| You have | Use |
+|---|---|
+| A collector or backend that speaks OTLP/HTTP (Jaeger, Tempo, Langfuse, Datadog, the OpenTelemetry Collector…) and **no** OpenTelemetry SDK | `otlpHttpSpanExporter` |
+| An OpenTelemetry SDK already registered in the process (auto-instrumentation, your own processors/exporters) | `otelApiSpanExporter` |
+
+```ts
+import { createBaseEngine } from '@backendkit-labs/agent-core';
+import { otlpHttpSpanExporter } from '@backendkit-labs/agent-otel';
+
+const exporter = otlpHttpSpanExporter({ endpoint: 'http://localhost:4318', serviceName: 'support-agent' });
+
+const engine = createBaseEngine({
+  // ...
+  observability: { tracing: { exporter } },
+});
+
+// on shutdown
+await exporter.shutdown();
+```
+
+```ts
+import { otelApiSpanExporter } from '@backendkit-labs/agent-otel';   // needs @opentelemetry/api
+observability: { tracing: { exporter: otelApiSpanExporter() } }
+```
+
+## What you get
+
+One trace per `engine.run()`:
+
+```
+agent.run
+└─ invoke_agent Main
+   ├─ chat deepseek-chat          (tokens, model, provider, cost, cache tokens)
+   ├─ execute_tool read_file      (success, duration — parallel tools overlap in time)
+   └─ chat deepseek-chat
+```
+
+Attributes follow the OpenTelemetry **GenAI semantic conventions**: `gen_ai.operation.name`
+(`invoke_agent` / `chat` / `execute_tool`), `gen_ai.request.model`, `gen_ai.provider.name`,
+`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_read.input_tokens`,
+`gen_ai.usage.cache_creation.input_tokens`, `gen_ai.agent.id/name`, `gen_ai.tool.name`. Anything specific to
+agent-core (cost in USD, the original trace id, guardrail actions, why an extra LLM call was made) lives under
+`bk.*`, e.g. `bk.cost_usd`, `bk.llm.purpose` (`context_summary`, `structured_output`), `bk.guardrail.<name>.<action>`.
+
+**Conversation content is never exported.** Spans carry names, durations, token counts and ids only: no
+prompts, answers, tool arguments or tool results.
+
+Requires `@backendkit-labs/agent-core` with `llm_call` / `tool_call` spans (0.28+). With 0.27 you only get
+`agent.run` and `invoke_agent`.
+
+## `otlpHttpSpanExporter(options)`
+
+Sends OTLP/JSON to `<endpoint>/v1/traces`. No SDK, no dependencies.
+
+| Option | Default | |
+|---|---|---|
+| `endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` or `http://localhost:4318` | `/v1/traces` is appended unless already there |
+| `headers` | – | e.g. `{ Authorization: 'Basic …' }` |
+| `serviceName` | `agent` | `service.name` resource attribute |
+| `resourceAttributes` | – | `deployment.environment`, `service.version`… |
+| `batchSize` | 64 | spans buffered before sending |
+| `flushIntervalMs` | 2000 | a partial batch is sent after this long (timer is `unref`'d) |
+| `timeoutMs` | 10000 | per request |
+| `onError` | – | a failed send is reported here and **that batch is dropped**; it never reaches the agent |
+| `fetch` | global `fetch` | for tests or custom transports |
+
+Returns a function with `flush()` and `shutdown()`. Sends are serialized, never overlapping.
+Ids are derived deterministically from agent-core's ids, so parent/child links are preserved.
+
+## `otelApiSpanExporter(options)`
+
+Re-creates the spans through `@opentelemetry/api` (`options.tracer`, default
+`trace.getTracer('@backendkit-labs/agent-core')`), so they reach whatever your SDK exports to.
+
+The OpenTelemetry API cannot choose a span's id, and a child must be created from its parent's real span.
+agent-core exports spans as they end (children first), so this adapter holds a trace's spans until the root
+`agent.run` ends and then creates the tree parents-first with the original start/end times. Consequences:
+
+- Spans of a run appear in your backend when the run finishes, not while it runs.
+- A run that never ends (crash) leaves its spans buffered: call `exporter.flush()` on shutdown (spans whose
+  parent never arrived become roots). `maxBufferedSpans` (default 5000) bounds memory.
+- `@opentelemetry/api` is an optional peer dependency; without it the exporter throws a clear error at creation.
+
+## Verified
+
+Unit tests plus a run of a real engine through both exporters. The API adapter was also checked against a real
+`@opentelemetry/sdk-trace-base` provider: one trace, correct hierarchy, parallel tool spans overlapping in time.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { otlpHttpSpanExporter, toOtlpSpan } from './otlpHttpExporter';
+export type { OtlpHttpExporterOptions, OtlpHttpSpanExporter } from './otlpHttpExporter';
+export { otelApiSpanExporter } from './otelApiExporter';
+export type { OtelApiExporterOptions, OtelApiSpanExporter } from './otelApiExporter';
+export { mapSpan, toTraceId, toSpanId } from './mapping';
+export type { MappedSpan, OtelAttributes } from './mapping';
+//# 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,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACtE,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSpanId = exports.toTraceId = exports.mapSpan = exports.otelApiSpanExporter = exports.toOtlpSpan = exports.otlpHttpSpanExporter = void 0;
+var otlpHttpExporter_1 = require("./otlpHttpExporter");
+Object.defineProperty(exports, "otlpHttpSpanExporter", { enumerable: true, get: function () { return otlpHttpExporter_1.otlpHttpSpanExporter; } });
+Object.defineProperty(exports, "toOtlpSpan", { enumerable: true, get: function () { return otlpHttpExporter_1.toOtlpSpan; } });
+var otelApiExporter_1 = require("./otelApiExporter");
+Object.defineProperty(exports, "otelApiSpanExporter", { enumerable: true, get: function () { return otelApiExporter_1.otelApiSpanExporter; } });
+var mapping_1 = require("./mapping");
+Object.defineProperty(exports, "mapSpan", { enumerable: true, get: function () { return mapping_1.mapSpan; } });
+Object.defineProperty(exports, "toTraceId", { enumerable: true, get: function () { return mapping_1.toTraceId; } });
+Object.defineProperty(exports, "toSpanId", { enumerable: true, get: function () { return mapping_1.toSpanId; } });
+//# 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,uDAAsE;AAA7D,wHAAA,oBAAoB,OAAA;AAAE,8GAAA,UAAU,OAAA;AAEzC,qDAAwD;AAA/C,sHAAA,mBAAmB,OAAA;AAE5B,qCAAyD;AAAhD,kGAAA,OAAO,OAAA;AAAE,oGAAA,SAAS,OAAA;AAAE,mGAAA,QAAQ,OAAA"}

package/dist/mapping.d.ts

@@ -0,0 +1,20 @@
+import type { Span } from '@backendkit-labs/agent-core';
+export type OtelAttributes = Record<string, string | number | boolean>;
+export interface MappedSpan {
+    name: string;
+    kind: 'internal' | 'client';
+    attributes: OtelAttributes;
+    /** Set when the span ended in error. */
+    errorMessage?: string;
+    isError: boolean;
+}
+/** Deterministic OTel-shaped ids (32 / 16 hex chars) from whatever id format the tracer used. */
+export declare function toTraceId(id: string): string;
+export declare function toSpanId(id: string): string;
+/**
+ * Translates an agent-core span into OpenTelemetry names and attributes following the GenAI semantic
+ * conventions (`invoke_agent`, `chat`, `execute_tool`). Prompts, answers and tool arguments are never
+ * part of a span, so nothing here can export conversation content.
+ */
+export declare function mapSpan(span: Span): MappedSpan;
+//# sourceMappingURL=mapping.d.ts.map

package/dist/mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEvE,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,cAAc,CAAC;IAC3B,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAiBD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CAgE9C"}

package/dist/mapping.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTraceId = toTraceId;
+exports.toSpanId = toSpanId;
+exports.mapSpan = mapSpan;
+const crypto_1 = require("crypto");
+/** Deterministic OTel-shaped ids (32 / 16 hex chars) from whatever id format the tracer used. */
+function toTraceId(id) {
+    return (0, crypto_1.createHash)('sha256').update(`trace:${id}`).digest('hex').slice(0, 32);
+}
+function toSpanId(id) {
+    return (0, crypto_1.createHash)('sha256').update(`span:${id}`).digest('hex').slice(0, 16);
+}
+/** `cost_usd` and similar keys keep their meaning under a vendor prefix. */
+const VENDOR = 'bk.';
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function rest(tags, consumed) {
+    const out = {};
+    for (const [k, v] of Object.entries(tags)) {
+        if (!consumed.includes(k))
+            out[`${VENDOR}${k}`] = v;
+    }
+    return out;
+}
+/**
+ * Translates an agent-core span into OpenTelemetry names and attributes following the GenAI semantic
+ * conventions (`invoke_agent`, `chat`, `execute_tool`). Prompts, answers and tool arguments are never
+ * part of a span, so nothing here can export conversation content.
+ */
+function mapSpan(span) {
+    const t = span.tags;
+    const isError = span.status === 'error';
+    switch (span.name) {
+        case 'run': {
+            const message = str(t.error);
+            return {
+                name: 'agent.run', kind: 'internal', isError, ...(message ? { errorMessage: message } : {}),
+                attributes: { 'bk.trace_id': span.traceId, ...rest(t, ['error']) },
+            };
+        }
+        case 'agent_block': {
+            const id = str(t.agent_id);
+            const name = str(t.agent_name);
+            return {
+                name: `invoke_agent ${name ?? id ?? 'agent'}`, kind: 'internal', isError,
+                attributes: {
+                    'gen_ai.operation.name': 'invoke_agent',
+                    ...(id ? { 'gen_ai.agent.id': id } : {}),
+                    ...(name ? { 'gen_ai.agent.name': name } : {}),
+                    ...rest(t, ['agent_id', 'agent_name']),
+                },
+            };
+        }
+        case 'llm_call': {
+            const model = str(t.model);
+            const provider = str(t.provider);
+            const agent = str(t.agent_id);
+            const attributes = { 'gen_ai.operation.name': 'chat' };
+            if (model)
+                attributes['gen_ai.request.model'] = model;
+            if (provider) {
+                attributes['gen_ai.provider.name'] = provider;
+                attributes['gen_ai.system'] = provider;
+            }
+            if (agent)
+                attributes['gen_ai.agent.id'] = agent;
+            if (typeof t.input_tokens === 'number')
+                attributes['gen_ai.usage.input_tokens'] = t.input_tokens;
+            if (typeof t.output_tokens === 'number')
+                attributes['gen_ai.usage.output_tokens'] = t.output_tokens;
+            if (typeof t.cache_read_tokens === 'number')
+                attributes['gen_ai.usage.cache_read.input_tokens'] = t.cache_read_tokens;
+            if (typeof t.cache_write_tokens === 'number')
+                attributes['gen_ai.usage.cache_creation.input_tokens'] = t.cache_write_tokens;
+            if (typeof t.cost_usd === 'number')
+                attributes['bk.cost_usd'] = t.cost_usd;
+            if (str(t.purpose))
+                attributes['bk.llm.purpose'] = String(t.purpose);
+            Object.assign(attributes, rest(t, [
+                'agent_id', 'provider', 'model', 'input_tokens', 'output_tokens',
+                'cache_read_tokens', 'cache_write_tokens', 'cost_usd', 'purpose',
+            ]));
+            return {
+                name: `chat ${model ?? 'unknown'}`, kind: 'client', isError, attributes,
+            };
+        }
+        case 'tool_call': {
+            const tool = str(t['tool.name']);
+            const agent = str(t.agent_id);
+            return {
+                name: `execute_tool ${tool ?? 'unknown'}`, kind: 'internal', isError,
+                attributes: {
+                    'gen_ai.operation.name': 'execute_tool',
+                    'gen_ai.tool.type': 'function',
+                    ...(tool ? { 'gen_ai.tool.name': tool } : {}),
+                    ...(agent ? { 'gen_ai.agent.id': agent } : {}),
+                    ...rest(t, ['tool.name', 'agent_id']),
+                },
+            };
+        }
+        default:
+            return { name: span.name, kind: 'internal', isError, attributes: rest(t, []) };
+    }
+}
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

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

package/dist/otelApiExporter.d.ts

@@ -0,0 +1,26 @@
+import type { SpanExporter } from '@backendkit-labs/agent-core';
+import type { Tracer as OtelTracer } from '@opentelemetry/api';
+export interface OtelApiExporterOptions {
+    /** Tracer to create spans with. Default: `trace.getTracer('@backendkit-labs/agent-core')`. */
+    tracer?: OtelTracer;
+    /**
+     * Spans held while waiting for their root to end. Past this, everything pending is flushed with
+     * orphans promoted to roots. Default 5000.
+     */
+    maxBufferedSpans?: number;
+}
+export type OtelApiSpanExporter = SpanExporter & {
+    /** Emits spans still waiting for a root (e.g. a run that never finished). */
+    flush(): void;
+};
+/**
+ * Re-creates agent-core spans through the OpenTelemetry API, so they flow to whatever SDK, processor and
+ * exporter the host application already configured.
+ *
+ * The OpenTelemetry API cannot choose a span's id, so a child must be created from its parent's real
+ * OTel span. agent-core exports spans when they end (children first), therefore this adapter holds a
+ * trace's spans until its root `run` span ends and then creates the tree parents-first, keeping the
+ * original start and end times. Use `otlpHttpSpanExporter` when you do not run the SDK.
+ */
+export declare function otelApiSpanExporter(options?: OtelApiExporterOptions): OtelApiSpanExporter;
+//# sourceMappingURL=otelApiExporter.d.ts.map

package/dist/otelApiExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otelApiExporter.d.ts","sourceRoot":"","sources":["../src/otelApiExporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAA6B,MAAM,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAG1F,MAAM,WAAW,sBAAsB;IACnC,8FAA8F;IAC9F,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG;IAC7C,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAC;CACjB,CAAC;AAgBF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CA4D7F"}

package/dist/otelApiExporter.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.otelApiSpanExporter = otelApiSpanExporter;
+const mapping_1 = require("./mapping");
+function loadApi() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('@opentelemetry/api');
+    }
+    catch {
+        throw new Error('otelApiSpanExporter needs "@opentelemetry/api" (npm i @opentelemetry/api) and an OpenTelemetry SDK ' +
+            'registered in the process. Use otlpHttpSpanExporter() to export without the SDK.');
+    }
+}
+/**
+ * Re-creates agent-core spans through the OpenTelemetry API, so they flow to whatever SDK, processor and
+ * exporter the host application already configured.
+ *
+ * The OpenTelemetry API cannot choose a span's id, so a child must be created from its parent's real
+ * OTel span. agent-core exports spans when they end (children first), therefore this adapter holds a
+ * trace's spans until its root `run` span ends and then creates the tree parents-first, keeping the
+ * original start and end times. Use `otlpHttpSpanExporter` when you do not run the SDK.
+ */
+function otelApiSpanExporter(options = {}) {
+    const api = loadApi();
+    const tracer = options.tracer ?? api.trace.getTracer('@backendkit-labs/agent-core');
+    const maxBuffered = options.maxBufferedSpans ?? 5000;
+    const pending = new Map(); // by core traceId
+    let buffered = 0;
+    const create = (span, parent) => {
+        const mapped = (0, mapping_1.mapSpan)(span);
+        const ctx = parent ? api.trace.setSpan(api.ROOT_CONTEXT, parent) : api.ROOT_CONTEXT;
+        const otel = tracer.startSpan(mapped.name, {
+            kind: mapped.kind === 'client' ? api.SpanKind.CLIENT : api.SpanKind.INTERNAL,
+            startTime: span.startedAt,
+            attributes: mapped.attributes,
+        }, ctx);
+        if (mapped.isError) {
+            otel.setStatus({ code: api.SpanStatusCode.ERROR, ...(mapped.errorMessage ? { message: mapped.errorMessage } : {}) });
+        }
+        otel.end(span.endedAt);
+        return otel;
+    };
+    // Creates `roots` and all their descendants, parents before children, and drops them from the buffer.
+    const emit = (traceId, rootIds) => {
+        const list = pending.get(traceId) ?? [];
+        const children = new Map();
+        for (const s of list) {
+            if (s.parentSpanId)
+                children.set(s.parentSpanId, [...(children.get(s.parentSpanId) ?? []), s]);
+        }
+        const used = new Set();
+        const walk = (span, parent) => {
+            used.add(span);
+            const otel = create(span, parent);
+            for (const child of (children.get(span.spanId) ?? []).sort((a, b) => a.startedAt.getTime() - b.startedAt.getTime())) {
+                walk(child, otel);
+            }
+        };
+        for (const root of list.filter(s => rootIds.has(s.spanId)))
+            walk(root, undefined);
+        const left = list.filter(s => !used.has(s));
+        buffered -= used.size;
+        if (left.length > 0)
+            pending.set(traceId, left);
+        else
+            pending.delete(traceId);
+    };
+    const flush = () => {
+        for (const [traceId, list] of [...pending]) {
+            const ids = new Set(list.map(s => s.spanId));
+            // Whatever has no pending parent starts a tree: real roots and spans whose parent never arrived.
+            emit(traceId, new Set(list.filter(s => !s.parentSpanId || !ids.has(s.parentSpanId)).map(s => s.spanId)));
+        }
+    };
+    const exporter = ((span) => {
+        pending.set(span.traceId, [...(pending.get(span.traceId) ?? []), span]);
+        buffered++;
+        if (!span.parentSpanId)
+            emit(span.traceId, new Set([span.spanId]));
+        else if (buffered > maxBuffered)
+            flush();
+    });
+    exporter.flush = flush;
+    return exporter;
+}
+//# sourceMappingURL=otelApiExporter.js.map

package/dist/otelApiExporter.js.map

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

package/dist/otlpHttpExporter.d.ts

@@ -0,0 +1,43 @@
+import type { Span, SpanExporter } from '@backendkit-labs/agent-core';
+import type { OtelAttributes } from './mapping';
+export interface OtlpHttpExporterOptions {
+    /**
+     * Base URL of the collector or backend. Default: `OTEL_EXPORTER_OTLP_ENDPOINT` or
+     * `http://localhost:4318`. `/v1/traces` is appended unless the URL already ends with it.
+     */
+    endpoint?: string;
+    /** Extra HTTP headers, e.g. `{ Authorization: 'Basic …' }` for Langfuse or a hosted backend. */
+    headers?: Record<string, string>;
+    /** Value of the `service.name` resource attribute. Default `agent`. */
+    serviceName?: string;
+    /** Additional resource attributes (deployment.environment, service.version, …). */
+    resourceAttributes?: OtelAttributes;
+    /** Spans buffered before a send is triggered. Default 64. */
+    batchSize?: number;
+    /** A partial batch is sent after this long. Default 2000 ms. */
+    flushIntervalMs?: number;
+    /** Request timeout. Default 10000 ms. */
+    timeoutMs?: number;
+    /** Called when a send fails (the spans of that batch are dropped). Never thrown. */
+    onError?: (error: Error) => void;
+    /** Override for tests or custom transports. Default: global `fetch`. */
+    fetch?: typeof fetch;
+}
+export type OtlpHttpSpanExporter = SpanExporter & {
+    /** Sends everything buffered and resolves when the collector answered. */
+    flush(): Promise<void>;
+    /** Flushes and stops the timer. Call it on process shutdown. */
+    shutdown(): Promise<void>;
+};
+/** OTLP/JSON form of one span. */
+export declare function toOtlpSpan(span: Span): Record<string, unknown>;
+/**
+ * Sends agent-core spans to any OTLP/HTTP collector or backend (Jaeger, Tempo, Langfuse, Datadog, the
+ * OpenTelemetry Collector…) without the OpenTelemetry SDK. Spans are batched; a failing send never reaches
+ * the agent: it is reported through `onError` and that batch is dropped.
+ *
+ * @example
+ * observability: { tracing: { exporter: otlpHttpSpanExporter({ endpoint: 'http://localhost:4318', serviceName: 'support-agent' }) } }
+ */
+export declare function otlpHttpSpanExporter(options?: OtlpHttpExporterOptions): OtlpHttpSpanExporter;
+//# sourceMappingURL=otlpHttpExporter.d.ts.map

package/dist/otlpHttpExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlpHttpExporter.d.ts","sourceRoot":"","sources":["../src/otlpHttpExporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,cAAc,CAAC;IACpC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG;IAC9C,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,gEAAgE;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAmBF,kCAAkC;AAClC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa9D;AAOD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,uBAA4B,GAAG,oBAAoB,CAwDhG"}

package/dist/otlpHttpExporter.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOtlpSpan = toOtlpSpan;
+exports.otlpHttpSpanExporter = otlpHttpSpanExporter;
+const mapping_1 = require("./mapping");
+const KIND = { internal: 1, client: 3 };
+const SCOPE = { name: '@backendkit-labs/agent-otel', version: '0.1.0' };
+function attrValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'boolean')
+        return { boolValue: v };
+    return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+}
+function attributes(attrs) {
+    return Object.entries(attrs).map(([key, value]) => ({ key, value: attrValue(value) }));
+}
+function nanos(d) {
+    return (BigInt(d.getTime()) * 1000000n).toString();
+}
+/** OTLP/JSON form of one span. */
+function toOtlpSpan(span) {
+    const m = (0, mapping_1.mapSpan)(span);
+    return {
+        traceId: (0, mapping_1.toTraceId)(span.traceId),
+        spanId: (0, mapping_1.toSpanId)(span.spanId),
+        ...(span.parentSpanId ? { parentSpanId: (0, mapping_1.toSpanId)(span.parentSpanId) } : {}),
+        name: m.name,
+        kind: KIND[m.kind],
+        startTimeUnixNano: nanos(span.startedAt),
+        endTimeUnixNano: nanos(span.endedAt),
+        attributes: attributes(m.attributes),
+        status: m.isError ? { code: 2, ...(m.errorMessage ? { message: m.errorMessage } : {}) } : { code: 1 },
+    };
+}
+function resolveUrl(endpoint) {
+    const base = endpoint.replace(/\/+$/, '');
+    return base.endsWith('/v1/traces') ? base : `${base}/v1/traces`;
+}
+/**
+ * Sends agent-core spans to any OTLP/HTTP collector or backend (Jaeger, Tempo, Langfuse, Datadog, the
+ * OpenTelemetry Collector…) without the OpenTelemetry SDK. Spans are batched; a failing send never reaches
+ * the agent: it is reported through `onError` and that batch is dropped.
+ *
+ * @example
+ * observability: { tracing: { exporter: otlpHttpSpanExporter({ endpoint: 'http://localhost:4318', serviceName: 'support-agent' }) } }
+ */
+function otlpHttpSpanExporter(options = {}) {
+    const url = resolveUrl(options.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318');
+    const batchSize = Math.max(1, options.batchSize ?? 64);
+    const intervalMs = options.flushIntervalMs ?? 2000;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const resourceAttrs = { 'service.name': options.serviceName ?? 'agent', ...(options.resourceAttributes ?? {}) };
+    let queue = [];
+    let timer;
+    // Sends run one after another so a slow collector never gets overlapping requests.
+    let chain = Promise.resolve();
+    const send = async (spans) => {
+        try {
+            const res = await doFetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...(options.headers ?? {}) },
+                body: JSON.stringify({
+                    resourceSpans: [{
+                            resource: { attributes: attributes(resourceAttrs) },
+                            scopeSpans: [{ scope: SCOPE, spans }],
+                        }],
+                }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!res.ok)
+                throw new Error(`OTLP export failed: HTTP ${res.status}`);
+        }
+        catch (err) {
+            options.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+    };
+    const flush = () => {
+        if (queue.length > 0) {
+            const batch = queue;
+            queue = [];
+            chain = chain.then(() => send(batch));
+        }
+        return chain;
+    };
+    const exporter = ((span) => {
+        queue.push(toOtlpSpan(span));
+        if (queue.length >= batchSize) {
+            void flush();
+            return;
+        }
+        if (!timer && intervalMs > 0) {
+            timer = setInterval(() => { void flush(); }, intervalMs);
+            timer.unref?.();
+        }
+    });
+    exporter.flush = flush;
+    exporter.shutdown = async () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+        await flush();
+    };
+    return exporter;
+}
+//# sourceMappingURL=otlpHttpExporter.js.map

package/dist/otlpHttpExporter.js.map

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

package/package.json

@@ -1,6 +1,53 @@
-{
-  "name": "@backendkit-labs/agent-otel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@backendkit-labs/agent-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry export for @backendkit-labs/agent-core traces: OTLP/HTTP exporter (no SDK needed) and an adapter for the OpenTelemetry API, with GenAI semantic conventions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "peerDependencies": {
+    "@backendkit-labs/agent-core": ">=0.27.0 <0.29.0",
+    "@opentelemetry/api": ">=1.4.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BackendKit-labs/backendkit-agent-framework.git",
+    "directory": "packages/otel"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}