@noetaris/harness-otel 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @noetaris/harness-otel
+
+OpenTelemetry observer bridge for [@noetaris/harness](../core).
+
+> **Status:** not yet released. Implementation tracked in F23.
+
+## Overview
+
+`@noetaris/harness-otel` bridges the harness `Observer` telemetry API to OpenTelemetry. It translates harness lifecycle events into OTel spans and metrics, giving you distributed tracing and token usage metrics with zero changes to your agent code.
+
+Takes `@opentelemetry/api` as a peer dependency — works with any OTel SDK implementation (Node SDK, collector exporters, etc.).
+
+## Installation
+
+```sh
+pnpm add @noetaris/harness-otel
+```
+
+Peer dependencies:
+
+```sh
+pnpm add @noetaris/harness @opentelemetry/api
+```
+
+Requires Node.js ≥ 22.
+
+## Usage
+
+```ts
+import { createOtelObserver } from '@noetaris/harness-otel'
+import { trace, metrics } from '@opentelemetry/api'
+
+const observer = createOtelObserver(
+  trace.getTracer('my-agent'),
+  { meterProvider: metrics.getMeterProvider() },
+)
+
+h.observe(observer)
+```
+
+## API
+
+### `createOtelObserver(tracer, options?)`
+
+Returns an `Observer` that maps harness events to OTel spans and metrics.
+
+**Span hierarchy:**
+
+| Harness event | OTel action |
+|---------------|-------------|
+| `onRunStart` | Creates root span `"agent.run"` with `agent.id` and `session.id` attributes |
+| `onStepStart` | Creates child span `"agent.step"` with `step.name` attribute |
+| `onStepEnd` | Closes the step span with `durationMs` |
+| `onStepError` | Sets step span status to error |
+| `onRunEnd` | Closes the root span |
+
+**Metrics** (requires `options.meterProvider`):
+
+| Harness event | OTel metric |
+|---------------|-------------|
+| `onEvent("llm.response", { tokens })` | Increments token counter (input and output) |
+| `onStepEnd` | Records step duration to a histogram |
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `parentContext` | `Context` | OTel context for the root span. Defaults to `context.active()`. |
+| `meterProvider` | `MeterProvider` | Enables metrics. Omit to skip metric recording. |
+
+## Related Packages
+
+- [`@noetaris/harness`](https://github.com/noetaris-lab/harness) — core execution engine
+- [`@noetaris/harness-anthropic`](https://github.com/noetaris-lab/harness-anthropic) — Anthropic Claude adapter (emits `"llm.response"` events)
+- [`@noetaris/harness-openai`](https://github.com/noetaris-lab/harness-openai) — OpenAI adapter (emits `"llm.response"` events)
+- [`@noetaris/harness-google`](https://github.com/noetaris-lab/harness-google) — Google Gemini adapter (emits `"llm.response"` events)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { MeterProvider, Context, Attributes, Tracer } from '@opentelemetry/api';
+import { Observer } from '@noetaris/harness';
+
+/**
+ * Options for {@link createOtelObserver}.
+ */
+interface OtelObserverOptions {
+    /** OTel MeterProvider to use for metrics. If absent, metrics are skipped. */
+    meterProvider?: MeterProvider;
+    /**
+     * Explicit parent context for the root span. When provided, the root
+     * `agent.run` span is created as a child of the span in this context.
+     * When absent, `context.active()` is used (ambient context from OTel middleware).
+     */
+    parentContext?: Context;
+    /**
+     * Extra attributes merged onto the root `agent.run` span at start time.
+     * These are merged with the built-in attributes (`agent.id`, `session.id`);
+     * if a key conflicts, the built-in attribute takes precedence.
+     */
+    attributes?: Attributes;
+}
+/**
+ * Create an {@link Observer} that records traces and metrics via OpenTelemetry.
+ *
+ * **Spans produced:**
+ * - `agent.run` — root span, one per `agent.run()` invocation.
+ * - `agent.step` — child span, one per step execution.
+ *
+ * **Metrics produced** (requires `options.meterProvider`):
+ * - `agent.llm.tokens` (counter) — input/output tokens, tagged by `token.type`.
+ * - `agent.step.duration` (histogram, ms) — step duration, tagged by `step.name`.
+ *
+ * @param tracer - An OTel `Tracer` instance from your SDK.
+ * @param options - Optional meter provider, parent context, and extra span attributes.
+ *
+ * @example
+ * ```ts
+ * const observer = createOtelObserver(trace.getTracer('my-agent'), {
+ *   meterProvider: metrics.getMeterProvider(),
+ * })
+ * agent.run({}, { llm, observer })
+ * ```
+ */
+declare function createOtelObserver(tracer: Tracer, options?: OtelObserverOptions): Observer;
+
+export { type OtelObserverOptions, createOtelObserver };

package/dist/index.js

@@ -0,0 +1,67 @@
+// src/observer/otel-observer.ts
+import { SpanStatusCode, context, trace } from "@opentelemetry/api";
+function createOtelObserver(tracer, options) {
+  let rootSpan;
+  let stepSpan;
+  let counter;
+  let histogram;
+  if (options?.meterProvider) {
+    const meter = options.meterProvider.getMeter("@noetaris/harness-otel", "0.1.0");
+    counter = meter.createCounter("agent.llm.tokens");
+    histogram = meter.createHistogram("agent.step.duration", { unit: "ms" });
+  }
+  return {
+    onRunStart(ctx) {
+      const builtIn = {
+        "agent.id": ctx.agentId,
+        "session.id": ctx.sessionId
+      };
+      const merged = { ...options?.attributes, ...builtIn };
+      const parentCtx = options?.parentContext ?? context.active();
+      rootSpan = tracer.startSpan("agent.run", { attributes: merged }, parentCtx);
+    },
+    onRunEnd(_ctx, _event) {
+      if (!rootSpan) return;
+      rootSpan.end();
+      rootSpan = void 0;
+    },
+    onStepStart(ctx) {
+      if (!rootSpan) return;
+      const childCtx = trace.setSpan(context.active(), rootSpan);
+      stepSpan = tracer.startSpan("agent.step", { attributes: { "step.name": ctx.stepName } }, childCtx);
+    },
+    onStepEnd(ctx, event) {
+      if (!stepSpan) return;
+      const span = stepSpan;
+      stepSpan = void 0;
+      histogram?.record(event.durationMs, { "step.name": ctx.stepName });
+      span.end();
+    },
+    onStepError(ctx, event) {
+      if (!stepSpan) return;
+      const span = stepSpan;
+      stepSpan = void 0;
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(event.error) });
+      histogram?.record(event.durationMs, { "step.name": ctx.stepName });
+      span.end();
+    },
+    onEvent(_ctx, type, payload) {
+      if (type === "llm.response") {
+        if (counter) {
+          const shaped = payload;
+          if (typeof shaped?.tokens?.input === "number" && typeof shaped?.tokens?.output === "number") {
+            counter.add(shaped.tokens.input, { "token.type": "input" });
+            counter.add(shaped.tokens.output, { "token.type": "output" });
+          }
+        }
+        return;
+      }
+      const activeSpan = stepSpan ?? rootSpan;
+      activeSpan?.addEvent(type);
+    }
+  };
+}
+export {
+  createOtelObserver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/observer/otel-observer.ts"],"sourcesContent":["import type { Tracer, MeterProvider, Context, Attributes, Span, Counter, Histogram } from '@opentelemetry/api'\nimport { SpanStatusCode, context, trace } from '@opentelemetry/api'\nimport type { Observer, RunContext, StepContext } from '@noetaris/harness'\n\n/**\n * Options for {@link createOtelObserver}.\n */\nexport interface OtelObserverOptions {\n  /** OTel MeterProvider to use for metrics. If absent, metrics are skipped. */\n  meterProvider?: MeterProvider\n  /**\n   * Explicit parent context for the root span. When provided, the root\n   * `agent.run` span is created as a child of the span in this context.\n   * When absent, `context.active()` is used (ambient context from OTel middleware).\n   */\n  parentContext?: Context\n  /**\n   * Extra attributes merged onto the root `agent.run` span at start time.\n   * These are merged with the built-in attributes (`agent.id`, `session.id`);\n   * if a key conflicts, the built-in attribute takes precedence.\n   */\n  attributes?: Attributes\n}\n\n// Local shape guard — avoids importing @noetaris/harness-types\ntype LLMUsageShape = { tokens?: { input?: unknown; output?: unknown } | null }\n\n/**\n * Create an {@link Observer} that records traces and metrics via OpenTelemetry.\n *\n * **Spans produced:**\n * - `agent.run` — root span, one per `agent.run()` invocation.\n * - `agent.step` — child span, one per step execution.\n *\n * **Metrics produced** (requires `options.meterProvider`):\n * - `agent.llm.tokens` (counter) — input/output tokens, tagged by `token.type`.\n * - `agent.step.duration` (histogram, ms) — step duration, tagged by `step.name`.\n *\n * @param tracer - An OTel `Tracer` instance from your SDK.\n * @param options - Optional meter provider, parent context, and extra span attributes.\n *\n * @example\n * ```ts\n * const observer = createOtelObserver(trace.getTracer('my-agent'), {\n *   meterProvider: metrics.getMeterProvider(),\n * })\n * agent.run({}, { llm, observer })\n * ```\n */\nexport function createOtelObserver(tracer: Tracer, options?: OtelObserverOptions): Observer {\n  let rootSpan: Span | undefined\n  let stepSpan: Span | undefined\n\n  let counter: Counter | undefined\n  let histogram: Histogram | undefined\n\n  if (options?.meterProvider) {\n    const meter = options.meterProvider.getMeter('@noetaris/harness-otel', '0.1.0')\n    counter = meter.createCounter('agent.llm.tokens')\n    histogram = meter.createHistogram('agent.step.duration', { unit: 'ms' })\n  }\n\n  return {\n    onRunStart(ctx: RunContext): void {\n      const builtIn: Attributes = {\n        'agent.id': ctx.agentId,\n        'session.id': ctx.sessionId,\n      }\n      const merged: Attributes = { ...options?.attributes, ...builtIn }\n      const parentCtx = options?.parentContext ?? context.active()\n      rootSpan = tracer.startSpan('agent.run', { attributes: merged }, parentCtx)\n    },\n\n    onRunEnd(_ctx: RunContext, _event: { signal: string; durationMs: number }): void {\n      if (!rootSpan) return\n      rootSpan.end()\n      rootSpan = undefined\n    },\n\n    onStepStart(ctx: StepContext): void {\n      if (!rootSpan) return\n      const childCtx = trace.setSpan(context.active(), rootSpan)\n      stepSpan = tracer.startSpan('agent.step', { attributes: { 'step.name': ctx.stepName } }, childCtx)\n    },\n\n    onStepEnd(ctx: StepContext, event: { durationMs: number }): void {\n      if (!stepSpan) return\n      const span = stepSpan\n      stepSpan = undefined\n      histogram?.record(event.durationMs, { 'step.name': ctx.stepName })\n      span.end()\n    },\n\n    onStepError(ctx: StepContext, event: { error: unknown; durationMs: number }): void {\n      if (!stepSpan) return\n      const span = stepSpan\n      stepSpan = undefined\n      span.setStatus({ code: SpanStatusCode.ERROR, message: String(event.error) })\n      histogram?.record(event.durationMs, { 'step.name': ctx.stepName })\n      span.end()\n    },\n\n    onEvent(_ctx: StepContext, type: string, payload: unknown): void {\n      if (type === 'llm.response') {\n        if (counter) {\n          const shaped = payload as LLMUsageShape // as: payload is unknown; guard below validates the shape before use\n          if (typeof shaped?.tokens?.input === 'number' && typeof shaped?.tokens?.output === 'number') {\n            counter.add(shaped.tokens.input, { 'token.type': 'input' })\n            counter.add(shaped.tokens.output, { 'token.type': 'output' })\n          }\n        }\n        return\n      }\n\n      const activeSpan = stepSpan ?? rootSpan\n      activeSpan?.addEvent(type)\n    },\n  }\n}\n"],"mappings":";AACA,SAAS,gBAAgB,SAAS,aAAa;AAgDxC,SAAS,mBAAmB,QAAgB,SAAyC;AAC1F,MAAI;AACJ,MAAI;AAEJ,MAAI;AACJ,MAAI;AAEJ,MAAI,SAAS,eAAe;AAC1B,UAAM,QAAQ,QAAQ,cAAc,SAAS,0BAA0B,OAAO;AAC9E,cAAU,MAAM,cAAc,kBAAkB;AAChD,gBAAY,MAAM,gBAAgB,uBAAuB,EAAE,MAAM,KAAK,CAAC;AAAA,EACzE;AAEA,SAAO;AAAA,IACL,WAAW,KAAuB;AAChC,YAAM,UAAsB;AAAA,QAC1B,YAAY,IAAI;AAAA,QAChB,cAAc,IAAI;AAAA,MACpB;AACA,YAAM,SAAqB,EAAE,GAAG,SAAS,YAAY,GAAG,QAAQ;AAChE,YAAM,YAAY,SAAS,iBAAiB,QAAQ,OAAO;AAC3D,iBAAW,OAAO,UAAU,aAAa,EAAE,YAAY,OAAO,GAAG,SAAS;AAAA,IAC5E;AAAA,IAEA,SAAS,MAAkB,QAAsD;AAC/E,UAAI,CAAC,SAAU;AACf,eAAS,IAAI;AACb,iBAAW;AAAA,IACb;AAAA,IAEA,YAAY,KAAwB;AAClC,UAAI,CAAC,SAAU;AACf,YAAM,WAAW,MAAM,QAAQ,QAAQ,OAAO,GAAG,QAAQ;AACzD,iBAAW,OAAO,UAAU,cAAc,EAAE,YAAY,EAAE,aAAa,IAAI,SAAS,EAAE,GAAG,QAAQ;AAAA,IACnG;AAAA,IAEA,UAAU,KAAkB,OAAqC;AAC/D,UAAI,CAAC,SAAU;AACf,YAAM,OAAO;AACb,iBAAW;AACX,iBAAW,OAAO,MAAM,YAAY,EAAE,aAAa,IAAI,SAAS,CAAC;AACjE,WAAK,IAAI;AAAA,IACX;AAAA,IAEA,YAAY,KAAkB,OAAqD;AACjF,UAAI,CAAC,SAAU;AACf,YAAM,OAAO;AACb,iBAAW;AACX,WAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,OAAO,MAAM,KAAK,EAAE,CAAC;AAC3E,iBAAW,OAAO,MAAM,YAAY,EAAE,aAAa,IAAI,SAAS,CAAC;AACjE,WAAK,IAAI;AAAA,IACX;AAAA,IAEA,QAAQ,MAAmB,MAAc,SAAwB;AAC/D,UAAI,SAAS,gBAAgB;AAC3B,YAAI,SAAS;AACX,gBAAM,SAAS;AACf,cAAI,OAAO,QAAQ,QAAQ,UAAU,YAAY,OAAO,QAAQ,QAAQ,WAAW,UAAU;AAC3F,oBAAQ,IAAI,OAAO,OAAO,OAAO,EAAE,cAAc,QAAQ,CAAC;AAC1D,oBAAQ,IAAI,OAAO,OAAO,QAAQ,EAAE,cAAc,SAAS,CAAC;AAAA,UAC9D;AAAA,QACF;AACA;AAAA,MACF;AAEA,YAAM,aAAa,YAAY;AAC/B,kBAAY,SAAS,IAAI;AAAA,IAC3B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@noetaris/harness-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry observer bridge for @noetaris/harness",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noetaris-lab/harness-otel.git"
+  },
+  "homepage": "https://github.com/noetaris-lab/harness-otel#readme",
+  "bugs": {
+    "url": "https://github.com/noetaris-lab/harness-otel/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "publish:npm": "pnpm publish --access public --no-git-checks"
+  },
+  "files": [
+    "dist"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "peerDependencies": {
+    "@noetaris/harness": ">=0.1.0",
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@noetaris/harness": "^0.2.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@types/node": "^25.8.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "dependencies": null
+}