@hydraharness/harness-session-telemetry-otel 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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,54 @@
+# @hydraharness/harness-session-telemetry-otel
+
+The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam follows session events live, replays the canonical log only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@hydraharness/harness-session-sessionTelemetry-otel`, operational records on `@hydraharness/harness-session-sessionTelemetry-otel/ops`. Resource identity contains `service.name`/`service.version` from `@hydraharness/harness-llm`'s `APP_IDENTITY` plus this package's anonymous `user.id` (`$HYDRA_HOME/.anonymous-user-id`, a random UUID created on first use and reset by deleting the file), carried once per export batch rather than per record.
+
+## Config
+
+```yaml
+- id: sessionTelemetry-otel
+  name: '@hydraharness/harness-session-sessionTelemetry-otel'
+  config:
+    mode: FULL                # explicit opt-in; default: DISABLED
+    shutdownTimeoutMillis: 3000 # optional; defaults to 3000
+    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
+      url: https://collector.example.com/v1/logs
+      headers:
+        authorization: !!js `Bearer ${process.env.OTLP_TOKEN}`
+    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
+```
+
+| `mode` | Behavior |
+|---|---|
+| `FULL` | Each projected record, including lifecycle ops records, is handed to the OTel SDK immediately. |
+| `FEEDBACK_ONLY` | Each `feedback/record` replays, projects, and redacts the canonical session-log suffix through that event. Later records wait for another feedback event and remain local if none arrives. |
+| `DISABLED` | Default. No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session sessionTelemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
+
+Programmatic TypeScript configuration uses the exported `SessionTelemetryMode` enum (`SessionTelemetryMode.FULL`, `SessionTelemetryMode.FEEDBACK_ONLY`, or `SessionTelemetryMode.DISABLED`); raw string literals are not assignable. Serialized Cordis configuration continues to use the string values shown above.
+
+Upload authorization is positive and fail-closed. An unknown direct-construction mode fails before transport configuration is read. Only `FULL` accepts direct `ctx.sessionTelemetry.emit()` calls. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability and treats only the exact `feedback/record` object already stored at `session.events[event.seq]` as consent; an independently emitted bus value is ignored. `DISABLED` never constructs the SDK pipeline, even when exporter options are present.
+
+The mounted service discloses the resolved mode through the seam's [`SessionTelemetrySharingStatus`](../session-telemetry/README.md#the-sharing-disclosure) `sharing` property (`full` / `feedback-only` / `disabled`), so the `/feedback` acknowledgement can report whether and how the session is shared. The disclosure is set in the constructor and is independent of capture: even `DISABLED` discloses `disabled`.
+
+`exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. In uploading modes, `shutdownTimeoutMillis` is a positive finite Hydra-owned outer deadline that defaults to 3000 ms, and a non-positive-integer `processor.maxExportBatchSize` also fails at plugin load because the SDK accepts it but then hangs on shutdown. Both SDK blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are SDK behavior tuned through `processor`. The backend implements no `flush()`: the batch processor owns ordinary flushing. During shutdown, OTel awaits `exporter.forceFlush()` before the processor's `exportTimeoutMillis`-bounded completion promise; if that transport promise never settles, this package abandons the wait at `shutdownTimeoutMillis`, logs the contained shutdown failure through the coordinator, and lets application teardown continue. The deadline cannot cancel the SDK transport, so records still pending then may be lost at process exit.
+
+## What leaves the machine
+
+In uploading modes, records carry the complete `event.data` as the seam's `sessionTelemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `sessionTelemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). `FULL` runs redaction at append time; `FEEDBACK_ONLY` retains no telemetry copy and runs the currently mounted rules when feedback triggers canonical-log replay. Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.
+
+## Field mapping
+
+Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)` and alert on severity. In `FULL`, they may also detect crashes by `shutdown`-record absence: the marker is emitted at the session's own disposal or application teardown, and a marker followed by more events is a telemetry reload. In `FEEDBACK_ONLY`, a released prefix normally has no later `shutdown` marker, so its absence is not a crash signal. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. A resumed local log may contain synthetic closers that were never exported; the wire stream stays faithful to records actually handed to the SDK.
+
+## Model Experience
+
+None, as the backend only forwards the seam's redacted records into the OTel SDK pipeline; it never contributes to a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Upstream experimental tree** — `@opentelemetry/sdk-logs` is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
+- **Live-collector behavior belongs to the SDK exporter** — authentication, TLS, throttling, and other real OTLP deployment behavior follow the upstream SDK rather than a package-owned compatibility layer.
+- **Feedback-time snapshot** — `FEEDBACK_ONLY` retains no telemetry-owned copy before feedback. It reads and redacts the current canonical log when feedback is recorded; a crash before feedback uploads nothing, and policy changes before feedback affect what that replay exports.

package/lib/index.js

@@ -0,0 +1,210 @@
+import { createRequire } from "node:module";
+import z from "@hydraharness/schemastery";
+import { SessionTelemetryBackend, SessionTelemetryCoordinator } from "@hydraharness/harness-session-telemetry";
+import { APP_IDENTITY } from "@hydraharness/harness-llm";
+import { getOrCreateAnonymousUserId } from "@hydraharness/harness-anonymous-user-id";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+//#region lib/types/index.js
+/**
+* OpenTelemetry Service Provider for the Hydra harness telemetry capability.
+*
+* Composes the OTel JS SDK as-is — a `LoggerProvider` with a
+* `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
+* record handed over by the capture coordinator onto `logger.emit()`. After that call,
+* batching, retry, queueing, and loss policy use the SDK's documented behavior, configured
+* verbatim through the `exporter`/`processor` passthroughs. This package owns
+* capture mode and an outer shutdown deadline: the SDK's export timeout does
+* not bound its preceding `forceFlush()` wait.
+*
+* @module @hydraharness/harness-session-telemetry-otel
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+/** Session-sharing policy selected by {@link Config.mode}. */
+var SessionTelemetryMode;
+(function(SessionTelemetryMode) {
+	SessionTelemetryMode["FULL"] = "FULL";
+	SessionTelemetryMode["FEEDBACK_ONLY"] = "FEEDBACK_ONLY";
+	SessionTelemetryMode["DISABLED"] = "DISABLED";
+})(SessionTelemetryMode || (SessionTelemetryMode = {}));
+/** Default session-sharing policy for schema and direct construction. */
+const DEFAULT_TELEMETRY_MODE = SessionTelemetryMode.DISABLED;
+const DISABLED_FEEDBACK_WARNING = "session telemetry is DISABLED; nothing will be shared and this feedback remains local";
+const NON_CANONICAL_FEEDBACK_WARNING = "session telemetry ignored a feedback event absent from the canonical session log";
+const DROP_RECORD = () => {};
+/** Resolve the default and reject unknown runtime values before transport setup. */
+function resolveMode(mode) {
+	const resolved = mode ?? DEFAULT_TELEMETRY_MODE;
+	switch (resolved) {
+		case SessionTelemetryMode.FULL:
+		case SessionTelemetryMode.FEEDBACK_ONLY:
+		case SessionTelemetryMode.DISABLED: return resolved;
+		default: return assertNever(resolved);
+	}
+}
+/** Fail closed when direct construction bypasses the runtime config schema. */
+function assertNever(value) {
+	throw new Error(`session-telemetry-otel: unsupported mode ${JSON.stringify(value)}`);
+}
+/** Map the serialized mode onto the seam's backend-independent sharing vocabulary. */
+function sharingStatusFor(mode) {
+	switch (mode) {
+		case SessionTelemetryMode.FULL: return "full";
+		case SessionTelemetryMode.FEEDBACK_ONLY: return "feedback-only";
+		case SessionTelemetryMode.DISABLED: return "disabled";
+		/* v8 ignore next 2 -- resolveMode already rejected unknown values before this switch; the closed enum cannot reach the default. */
+		default: return assertNever(mode);
+	}
+}
+/**
+* Schemastery validator for {@link Config}; cordis runs it before the plugin
+* starts. It checks only the top-level fields; value checks live in the constructor
+* so their errors name the fields. Both SDK option objects pass through unchanged:
+* the SDK defines and validates their fields. Re-declaring them here would
+* silently drop every field this plugin did not repeat.
+*/
+const Config = z.object({
+	mode: z.union(Object.values(SessionTelemetryMode)).default(DEFAULT_TELEMETRY_MODE),
+	exporter: z.any(),
+	processor: z.any(),
+	shutdownTimeoutMillis: z.number()
+});
+/** Default outer allowance for the SDK's complete shutdown sequence. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3e3;
+const MAX_TIMER_DELAY_MILLIS = 2147483647;
+/** Severity mapping from the Service Definition's three-level vocabulary to OTel severity numbers. */
+const SEVERITY = {
+	info: {
+		severityNumber: SeverityNumber.INFO,
+		severityText: "INFO"
+	},
+	warn: {
+		severityNumber: SeverityNumber.WARN,
+		severityText: "WARN"
+	},
+	error: {
+		severityNumber: SeverityNumber.ERROR,
+		severityText: "ERROR"
+	}
+};
+/**
+* The backend plugin — the only entry a deployment loads. It always registers
+* the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+* pipeline and compose {@link SessionTelemetryCoordinator}; `DISABLED` constructs no
+* SDK state and listens only to warn when recorded feedback stays local.
+*/
+var OpenTelemetrySessionBackend = class extends SessionTelemetryBackend {
+	static inject = ["sessions"];
+	static Config = Config;
+	directEmit;
+	provider;
+	shutdownTimeoutMillis;
+	sharing;
+	constructor(ctx, config) {
+		const mode = resolveMode(config.mode);
+		super(ctx);
+		this.sharing = sharingStatusFor(mode);
+		if (mode === SessionTelemetryMode.DISABLED) {
+			this.directEmit = DROP_RECORD;
+			this.provider = void 0;
+			this.shutdownTimeoutMillis = DEFAULT_SHUTDOWN_TIMEOUT_MILLIS;
+			ctx.on("session/event", (_session, event) => {
+				if (event.type === "feedback/record") ctx.logger.warn(DISABLED_FEEDBACK_WARNING);
+			});
+			return;
+		}
+		const url = config.exporter?.url;
+		if (url === void 0 || url.length === 0) throw new Error("session-telemetry-otel: exporter.url is required (the full OTLP logs endpoint)");
+		let parsed;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new Error(`session-telemetry-otel: exporter.url is not a valid URL: ${JSON.stringify(url)}`);
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`session-telemetry-otel: exporter.url must be http(s), got ${parsed.protocol}`);
+		const batchSize = config.processor?.maxExportBatchSize;
+		if (batchSize !== void 0 && (!Number.isInteger(batchSize) || batchSize < 1)) throw new Error(`session-telemetry-otel: processor.maxExportBatchSize must be a positive integer, got ${String(batchSize)}`);
+		const shutdownTimeoutMillis = config.shutdownTimeoutMillis ?? 3e3;
+		if (!Number.isFinite(shutdownTimeoutMillis) || shutdownTimeoutMillis <= 0 || shutdownTimeoutMillis > MAX_TIMER_DELAY_MILLIS) throw new Error(`session-telemetry-otel: shutdownTimeoutMillis must be a positive finite number no greater than ${MAX_TIMER_DELAY_MILLIS}, got ${String(shutdownTimeoutMillis)}`);
+		this.shutdownTimeoutMillis = shutdownTimeoutMillis;
+		this.provider = new LoggerProvider({
+			resource: resourceFromAttributes({
+				"service.name": APP_IDENTITY.product,
+				"service.version": APP_IDENTITY.version,
+				"user.id": getOrCreateAnonymousUserId()
+			}),
+			processors: [new BatchLogRecordProcessor({
+				...config.processor,
+				exporter: new OTLPLogExporter(config.exporter)
+			})]
+		});
+		const ledger = this.provider.getLogger("@hydraharness/harness-session-telemetry-otel", version);
+		const ops = this.provider.getLogger("@hydraharness/harness-session-telemetry-otel/ops", version);
+		const enqueue = (record) => {
+			(record.channel === "ops" ? ops : ledger).emit({
+				timestamp: record.time,
+				observedTimestamp: record.time,
+				...SEVERITY[record.severity],
+				body: record.body,
+				attributes: record.attributes
+			});
+		};
+		const backend = {
+			emit: enqueue,
+			shutdown: () => this.shutdown()
+		};
+		if (mode === SessionTelemetryMode.FULL) {
+			this.directEmit = enqueue;
+			new SessionTelemetryCoordinator(ctx, backend, "live");
+			return;
+		}
+		this.directEmit = DROP_RECORD;
+		const coordinator = new SessionTelemetryCoordinator(ctx, backend, "on-demand");
+		ctx.on("session/event", (session, event) => {
+			if (event.type !== "feedback/record") return;
+			if (session.events[event.seq] !== event) {
+				ctx.logger.warn(NON_CANONICAL_FEEDBACK_WARNING);
+				return;
+			}
+			coordinator.captureSession(session, event.seq);
+		});
+	}
+	/**
+	* Hand a direct service record to the SDK only in `FULL`. Direct calls are
+	* no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+	* backend capability created only for the canonical feedback listener.
+	* @param record - the logical record offered directly to the service.
+	*/
+	emit(record) {
+		this.directEmit(record);
+	}
+	/**
+	* Ask the SDK to drain and quiesce, but reject after the backend-owned
+	* deadline. OTel's processor export timeout wraps `exportCompleted` only;
+	* shutdown awaits `exporter.forceFlush()` first, which can remain pending
+	* when the transport never obtains a socket. The provider promise remains
+	* observed after the deadline so a later rejection cannot become unhandled.
+	* `DISABLED` has no provider and resolves immediately.
+	* @returns resolves when the SDK pipeline quiesces or is disabled, or rejects at the configured deadline.
+	*/
+	async shutdown() {
+		if (this.provider === void 0) return;
+		const providerShutdown = this.provider.shutdown();
+		let timer;
+		const deadline = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`session-telemetry-otel: provider shutdown exceeded ${this.shutdownTimeoutMillis}ms`));
+			}, this.shutdownTimeoutMillis);
+		});
+		try {
+			await Promise.race([providerShutdown, deadline]);
+		} finally {
+			/* v8 ignore else -- the Promise executor assigns timer synchronously before this race starts. */
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	}
+};
+//#endregion
+export { Config, DEFAULT_SHUTDOWN_TIMEOUT_MILLIS, DEFAULT_TELEMETRY_MODE, OpenTelemetrySessionBackend, OpenTelemetrySessionBackend as default, SessionTelemetryMode };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-session-telemetry-otel`.
+* @module @hydraharness/harness-session-telemetry-otel/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-session-telemetry-otel";
+/** Cordis companion plugin name. */
+const name = "session-telemetry-otel-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: mode selection changes capture handoff, SDK setup, and
+* local diagnostics without mutating session or service state an independent
+* companion can compare. Export remains inside the SDK past the backend boundary.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * OpenTelemetry Service Provider for the Hydra harness telemetry capability.
+ *
+ * Composes the OTel JS SDK as-is — a `LoggerProvider` with a
+ * `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
+ * record handed over by the capture coordinator onto `logger.emit()`. After that call,
+ * batching, retry, queueing, and loss policy use the SDK's documented behavior, configured
+ * verbatim through the `exporter`/`processor` passthroughs. This package owns
+ * capture mode and an outer shutdown deadline: the SDK's export timeout does
+ * not bound its preceding `forceFlush()` wait.
+ *
+ * @module @hydraharness/harness-session-telemetry-otel
+ */
+import z from '@hydraharness/schemastery';
+import type { Context } from '@hydraharness/cordis';
+import { SessionTelemetryBackend, type SessionTelemetryRecord, type SessionTelemetrySharingStatus } from '@hydraharness/harness-session-telemetry';
+import { type BatchLogRecordProcessorOptions } from '@opentelemetry/sdk-logs';
+import type { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
+/** Session-sharing policy selected by {@link Config.mode}. */
+export declare enum SessionTelemetryMode {
+    FULL = "FULL",
+    FEEDBACK_ONLY = "FEEDBACK_ONLY",
+    DISABLED = "DISABLED"
+}
+/** Default session-sharing policy for schema and direct construction. */
+export declare const DEFAULT_TELEMETRY_MODE = SessionTelemetryMode.DISABLED;
+/**
+ * Plugin configuration: one sharing policy, two verbatim SDK option objects,
+ * and one Hydra-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
+ */
+export interface Config {
+    /** Sharing policy; defaults to local-only `DISABLED` behavior. */
+    mode?: SessionTelemetryMode;
+    /**
+     * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
+     * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
+     * `compression`, `keepAlive`, …), owned and documented by the SDK. `url`
+     * is the one field this package requires and validates itself.
+     */
+    exporter?: OTLPExporterNodeConfigBase & {
+        /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
+        url?: string;
+    };
+    /**
+     * Passed verbatim to `BatchLogRecordProcessor` (minus the exporter slot,
+     * which this plugin fills); the SDK owns and documents these knobs.
+     */
+    processor?: Omit<BatchLogRecordProcessorOptions, 'exporter'>;
+    /** Maximum time spent awaiting the SDK provider's complete shutdown path. */
+    shutdownTimeoutMillis?: number;
+}
+/**
+ * Schemastery validator for {@link Config}; cordis runs it before the plugin
+ * starts. It checks only the top-level fields; value checks live in the constructor
+ * so their errors name the fields. Both SDK option objects pass through unchanged:
+ * the SDK defines and validates their fields. Re-declaring them here would
+ * silently drop every field this plugin did not repeat.
+ */
+export declare const Config: z<Config>;
+/** Default outer allowance for the SDK's complete shutdown sequence. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3000;
+/**
+ * The backend plugin — the only entry a deployment loads. It always registers
+ * the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+ * pipeline and compose {@link SessionTelemetryCoordinator}; `DISABLED` constructs no
+ * SDK state and listens only to warn when recorded feedback stays local.
+ */
+export declare class OpenTelemetrySessionBackend extends SessionTelemetryBackend {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly directEmit;
+    private readonly provider;
+    private readonly shutdownTimeoutMillis;
+    readonly sharing: SessionTelemetrySharingStatus;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Hand a direct service record to the SDK only in `FULL`. Direct calls are
+     * no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+     * backend capability created only for the canonical feedback listener.
+     * @param record - the logical record offered directly to the service.
+     */
+    emit(record: SessionTelemetryRecord): void;
+    /**
+     * Ask the SDK to drain and quiesce, but reject after the backend-owned
+     * deadline. OTel's processor export timeout wraps `exportCompleted` only;
+     * shutdown awaits `exporter.forceFlush()` first, which can remain pending
+     * when the transport never obtains a socket. The provider promise remains
+     * observed after the deadline so a later rejection cannot become unhandled.
+     * `DISABLED` has no provider and resolves immediately.
+     * @returns resolves when the SDK pipeline quiesces or is disabled, or rejects at the configured deadline.
+     */
+    shutdown(): Promise<void>;
+}
+export default OpenTelemetrySessionBackend;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-session-telemetry-otel`.
+ * @module @hydraharness/harness-session-telemetry-otel/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-telemetry-otel-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hydraharness/harness-session-telemetry-otel",
+  "description": "OpenTelemetry backend for the Hydra harness telemetry seam: hands captured session records to the OTel JS SDK's log pipeline",
+  "hydra": {
+    "plugin": {
+      "application": "Send captured session telemetry to the configured OpenTelemetry reporting backend."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/session/session-telemetry-otel"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.220.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
+    "@opentelemetry/otlp-exporter-base": "^0.220.0",
+    "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-logs": "^0.220.0",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-command-feedback": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-anonymous-user-id": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-telemetry": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-command-feedback": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-anonymous-user-id": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-session-telemetry": "^0.1.1-rc.6"
+  }
+}