@xandreed/plugin-telemetry 0.3.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-telemetry
 
-Efferent composable agent framework, 0.3.0. Bun on Linux.
+Efferent composable agent framework, 0.14.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -1,2 +1,8 @@
-export { FileLoggerAddLive, FileLoggerLive, TracingLive } from "./telemetry/telemetry.js";
-export { telemetryPlugin, default } from "./plugin.adapter.js";
+export { flushTelemetry, OtlpTelemetryFromEnv, OtlpTelemetryHttpFromEnv, OtlpTelemetryHttpLive, OtlpTelemetryLive } from "./otlp-telemetry.adapter.js";
+export { OtlpCompression, OtlpProtocol, OtlpTemporality } from "./otlp-telemetry.entity.js";
+export type { OtlpTelemetryOptions } from "./otlp-telemetry.entity.js";
+export { telemetryPlugin, TelemetryPluginLive } from "./plugin.adapter.js";
+export { TelemetryMetrics } from "./telemetry-metrics.js";
+export { telemetryDefaults, TelemetryOptions, TokenKind } from "./telemetry.entity.js";
+export { tokenCounts } from "./telemetry.entity.functions.js";
+export { TurnTelemetryLive } from "./turn-telemetry.adapter.js";

package/dist/index.js

@@ -1,2 +1,7 @@
-export { FileLoggerAddLive, FileLoggerLive, TracingLive } from "./telemetry/telemetry.js";
-export { telemetryPlugin, default } from "./plugin.adapter.js";
+export { flushTelemetry, OtlpTelemetryFromEnv, OtlpTelemetryHttpFromEnv, OtlpTelemetryHttpLive, OtlpTelemetryLive } from "./otlp-telemetry.adapter.js";
+export { OtlpCompression, OtlpProtocol, OtlpTemporality } from "./otlp-telemetry.entity.js";
+export { telemetryPlugin, TelemetryPluginLive } from "./plugin.adapter.js";
+export { TelemetryMetrics } from "./telemetry-metrics.js";
+export { telemetryDefaults, TelemetryOptions, TokenKind } from "./telemetry.entity.js";
+export { tokenCounts } from "./telemetry.entity.functions.js";
+export { TurnTelemetryLive } from "./turn-telemetry.adapter.js";

package/dist/otlp-telemetry.adapter.d.ts

@@ -0,0 +1,41 @@
+import { Effect, Layer } from "effect";
+import type { Config } from "effect";
+import type { HttpClient } from "effect/http";
+import { OtlpExporter } from "effect/observability";
+import type { OtlpTelemetryOptions } from "./otlp-telemetry.entity.js";
+/**
+ * Export the program's spans and metrics over OTLP/HTTP with the host's
+ * `HttpClient` (one that goes through a proxy, say): Effect's own
+ * `OtlpTracer` and `OtlpMetrics` (`effect/observability`), configured by
+ * `options` (`OtlpTelemetryOptions`). Provide it around the program that
+ * defines the agent and runs its turns; it is the `Tracer` and the metrics
+ * exporter of everything inside. Spans are batched and posted every
+ * `exportInterval`; the metrics registry (every `Metric` the program
+ * updated: the telemetry plugin's, the step loop's, the models plugin's,
+ * `Agent.turn`'s) is posted whole each interval. Closing the layer posts
+ * what is left, waiting up to `shutdownTimeout`; a serverless host flushes
+ * before it responds (`flushTelemetry`). A failed export is retried and
+ * then turns that signal off for 60 seconds; it never fails the program.
+ */
+export declare const OtlpTelemetryHttpLive: (options: OtlpTelemetryOptions) => Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient>;
+/** `OtlpTelemetryHttpLive` over the global `fetch` (`FetchHttpClient`), on Node 24 and Bun. */
+export declare const OtlpTelemetryLive: (options: OtlpTelemetryOptions) => Layer.Layer<OtlpExporter.Flusher>;
+/**
+ * OTLP export configured by the standard OpenTelemetry environment
+ * (`OTEL_EXPORTER_OTLP_ENDPOINT`, the per-signal endpoints, headers,
+ * compression and protocol, `OTEL_SERVICE_NAME`, `OTEL_SDK_DISABLED`, …;
+ * see `otlpExportFromEnv`), over `defaults` for what it leaves unsaid,
+ * with the host's `HttpClient`. With no endpoint, or with
+ * `OTEL_SDK_DISABLED=true`, it exports nothing and reads nothing further,
+ * so a host can always provide it. A variable it reads that is set to an
+ * invalid value fails the layer with its `ConfigError`.
+ */
+export declare const OtlpTelemetryHttpFromEnv: (defaults?: OtlpTelemetryOptions) => Layer.Layer<OtlpExporter.Flusher, Config.ConfigError, HttpClient.HttpClient>;
+/** `OtlpTelemetryHttpFromEnv` over the global `fetch` (`FetchHttpClient`), on Node 24 and Bun. */
+export declare const OtlpTelemetryFromEnv: (defaults?: OtlpTelemetryOptions) => Layer.Layer<OtlpExporter.Flusher, Config.ConfigError>;
+/**
+ * Post every signal's pending batch now and wait for those posts (not for
+ * one already in flight). It cannot fail; bound it with
+ * `Effect.timeoutOption` where the host has a deadline.
+ */
+export declare const flushTelemetry: Effect.Effect<void, never, OtlpExporter.Flusher>;

package/dist/otlp-telemetry.adapter.js

@@ -0,0 +1,28 @@
+import { Effect, Layer, Option } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { OtlpExporter, OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/observability";
+import { otlpExportFromEnv, otlpExportOf } from "./otlp-telemetry.entity.functions.js";
+const serialization = (protocol) => protocol === "http/json" ? OtlpSerialization.layerJson : OtlpSerialization.layerProtobuf, exportLayer = (target) => {
+  const resource = {
+    serviceName: target.serviceName,
+    serviceVersion: Option.getOrUndefined(target.serviceVersion),
+    attributes: target.resourceAttributes
+  }, shutdownTimeout = Option.getOrUndefined(target.shutdownTimeout), traces = Option.map(target.traces, (signal) => OtlpTracer.layer({
+    url: signal.url,
+    resource,
+    headers: signal.headers,
+    compression: signal.compression,
+    exportInterval: Option.getOrUndefined(signal.exportInterval),
+    shutdownTimeout
+  }).pipe(Layer.provide(serialization(signal.protocol)))), metrics = Option.map(target.metrics, (signal) => OtlpMetrics.layer({
+    url: signal.url,
+    resource,
+    headers: signal.headers,
+    compression: signal.compression,
+    exportInterval: Option.getOrUndefined(signal.exportInterval),
+    shutdownTimeout,
+    temporality: target.metricsTemporality
+  }).pipe(Layer.provide(serialization(signal.protocol))));
+  return [traces, metrics].flatMap(Option.toArray).reduce((merged, signal) => Layer.merge(merged, signal), OtlpExporter.layerFlusher);
+};
+export const OtlpTelemetryHttpLive = (options) => exportLayer(otlpExportOf(options)), OtlpTelemetryLive = (options) => OtlpTelemetryHttpLive(options).pipe(Layer.provide(FetchHttpClient.layer)), OtlpTelemetryHttpFromEnv = (defaults = {}) => Layer.unwrap(otlpExportFromEnv(defaults).pipe(Effect.map(exportLayer))), OtlpTelemetryFromEnv = (defaults = {}) => OtlpTelemetryHttpFromEnv(defaults).pipe(Layer.provide(FetchHttpClient.layer)), flushTelemetry = OtlpExporter.Flusher.pipe(Effect.flatMap((flusher) => flusher.flush));

package/dist/otlp-telemetry.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/otlp-telemetry.entity.d.ts

@@ -0,0 +1,74 @@
+import { Schema } from "effect";
+import type { Duration, Option } from "effect";
+/** How a signal's batches are encoded: OTLP/HTTP protobuf (the OpenTelemetry default) or JSON. gRPC is not supported. */
+export declare const OtlpProtocol: Schema.Literals<readonly ["http/protobuf", "http/json"]>;
+export type OtlpProtocol = typeof OtlpProtocol.Type;
+/** Request compression; gzip leaves a batch under 1 KB uncompressed. */
+export declare const OtlpCompression: Schema.Literals<readonly ["gzip", "none"]>;
+export type OtlpCompression = typeof OtlpCompression.Type;
+/** How counters and histograms are reported: totals since the start (`cumulative`) or since the last export (`delta`). */
+export declare const OtlpTemporality: Schema.Literals<readonly ["cumulative", "delta"]>;
+export type OtlpTemporality = typeof OtlpTemporality.Type;
+/** The signals the layers export; logs are left to the host. */
+export type OtlpSignal = "traces" | "metrics";
+/**
+ * Where and how `OtlpTelemetryLive` exports traces and metrics over
+ * OTLP/HTTP. A signal goes to its own URL (`tracesUrl`, `metricsUrl`, used
+ * as given) or else to `baseUrl` plus `/v1/traces` or `/v1/metrics`; a
+ * signal with neither, or turned off (`traces: false`, `metrics: false`),
+ * is not exported.
+ * - `serviceName`: the resource's `service.name`; else
+ *   `resourceAttributes["service.name"]`, else `"efferent"`. It always
+ *   wins over `OTEL_SERVICE_NAME` and the `service.name` of
+ *   `OTEL_RESOURCE_ATTRIBUTES` (`OtlpTelemetryFromEnv` reads those).
+ *   `serviceVersion` (else `resourceAttributes["service.version"]`) and
+ *   `resourceAttributes` join the resource, over any other
+ *   `OTEL_RESOURCE_ATTRIBUTES` Effect's exporter still merges in; with no
+ *   `serviceVersion` at all, Effect's exporter reads `OTEL_SERVICE_VERSION`.
+ * - `headers`: sent with every request (an API key, a tenant), both
+ *   signals; `tracesHeaders` and `metricsHeaders` go to one signal only,
+ *   over `headers` (a signal at another vendor, with its own key).
+ * - `compression`: `"none"` by default; `protocol`: `"http/protobuf"` by default.
+ * - `exportInterval`: how often batches are sent (Effect's defaults: 5 s for
+ *   traces, 10 s for metrics); `shutdownTimeout`: how long closing the layer
+ *   waits for the last export (3 s).
+ * - `metricsTemporality`: `"cumulative"` by default.
+ */
+export interface OtlpTelemetryOptions {
+    readonly baseUrl?: string;
+    readonly tracesUrl?: string;
+    readonly metricsUrl?: string;
+    readonly traces?: boolean;
+    readonly metrics?: boolean;
+    readonly serviceName?: string;
+    readonly serviceVersion?: string;
+    readonly resourceAttributes?: Readonly<Record<string, string>>;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly tracesHeaders?: Readonly<Record<string, string>>;
+    readonly metricsHeaders?: Readonly<Record<string, string>>;
+    readonly compression?: OtlpCompression;
+    readonly protocol?: OtlpProtocol;
+    readonly exportInterval?: Duration.Input;
+    readonly shutdownTimeout?: Duration.Input;
+    readonly metricsTemporality?: OtlpTemporality;
+}
+/** One signal's export, resolved: the URL it is posted to and how. */
+export interface OtlpSignalExport {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly compression: OtlpCompression;
+    readonly protocol: OtlpProtocol;
+    readonly exportInterval: Option.Option<Duration.Input>;
+}
+/** The export the layers build, resolved from options or the environment: a signal that is `None` is not exported. */
+export interface OtlpExport {
+    readonly serviceName: string;
+    readonly serviceVersion: Option.Option<string>;
+    readonly resourceAttributes: Readonly<Record<string, string>>;
+    readonly traces: Option.Option<OtlpSignalExport>;
+    readonly metrics: Option.Option<OtlpSignalExport>;
+    readonly metricsTemporality: OtlpTemporality;
+    readonly shutdownTimeout: Option.Option<Duration.Input>;
+}
+/** The service name a resource gets when nothing names one. */
+export declare const DEFAULT_SERVICE_NAME = "efferent";

package/dist/otlp-telemetry.entity.functions.d.ts

@@ -0,0 +1,43 @@
+import { Config, Effect } from "effect";
+import type { OtlpExport, OtlpSignal, OtlpTelemetryOptions } from "./otlp-telemetry.entity.js";
+/**
+ * A signal's URL under a collector's base URL: its path plus `/v1/traces`
+ * or `/v1/metrics` (one slash between), the query string kept.
+ */
+export declare const signalUrl: (base: string, signal: OtlpSignal) => string;
+/** The export `OtlpTelemetryLive` builds from its options (see `OtlpTelemetryOptions` for the defaults). */
+export declare const otlpExportOf: (options: OtlpTelemetryOptions) => OtlpExport;
+/**
+ * The export the standard OpenTelemetry environment describes, over
+ * `defaults` for what it leaves unsaid (read from the current
+ * `ConfigProvider`, the process environment by default):
+ * - `OTEL_SDK_DISABLED=true` exports nothing, and `OTEL_TRACES_EXPORTER` /
+ *   `OTEL_METRICS_EXPORTER` export that signal only when they list `otlp`
+ *   (`none` turns it off; unset leaves `defaults.traces`/`metrics`, on);
+ * - a signal's endpoint is `OTEL_EXPORTER_OTLP_{TRACES,METRICS}_ENDPOINT`
+ *   as given, else `OTEL_EXPORTER_OTLP_ENDPOINT` plus `/v1/<signal>`, else
+ *   the defaults' URLs; a signal with no endpoint is not exported, so an
+ *   empty environment exports nothing;
+ * - headers are `OTEL_EXPORTER_OTLP_HEADERS` with the signal's own
+ *   `..._{TRACES,METRICS}_HEADERS` over them, over the defaults' headers;
+ *   compression and protocol are the signal's own variable, else the
+ *   shared one, else the defaults (`none`, `http/protobuf`; `grpc` fails);
+ * - `service.name` is `OTEL_SERVICE_NAME`, else `OTEL_RESOURCE_ATTRIBUTES`'
+ *   `service.name`, else `defaults.serviceName`, else the defaults'
+ *   `resourceAttributes["service.name"]`, else `"efferent"`;
+ *   `service.version` likewise from `OTEL_SERVICE_VERSION`;
+ *   `OTEL_RESOURCE_ATTRIBUTES` win over `defaults.resourceAttributes`;
+ * - the export intervals are `OTEL_BSP_SCHEDULE_DELAY` (traces) and
+ *   `OTEL_METRIC_EXPORT_INTERVAL` (metrics), in milliseconds, and the
+ *   temporality `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`;
+ *   `OTEL_EXPORTER_OTLP_TIMEOUT` is not read (`shutdownTimeout` is the
+ *   defaults').
+ * A variable is read only when it can matter: nothing past
+ * `OTEL_SDK_DISABLED` when it is set, nothing about a signal past its
+ * exporter list when that turns it off, and nothing past the endpoints
+ * when no signal has one; a signal's own endpoint, compression and
+ * protocol are read before the shared ones, which are not read when the
+ * signal's are set (headers merge, so both are read). A variable that
+ * is read and set to a value it cannot use fails with its `ConfigError`.
+ */
+export declare const otlpExportFromEnv: (defaults?: OtlpTelemetryOptions) => Effect.Effect<OtlpExport, Config.ConfigError>;

package/dist/otlp-telemetry.entity.functions.js

@@ -0,0 +1,66 @@
+import { Config, Duration, Effect, Option, Schema } from "effect";
+import { DEFAULT_SERVICE_NAME, OtlpCompression, OtlpProtocol } from "./otlp-telemetry.entity.js";
+export const signalUrl = (base, signal) => Option.match(Option.fromNullishOr(URL.parse(base)), {
+  onNone: () => `${base.replace(/\/+$/, "")}/v1/${signal}`,
+  onSome: (url) => {
+    const target = new URL(url);
+    target.pathname = `${target.pathname.replace(/\/+$/, "")}/v1/${signal}`;
+    return target.toString();
+  }
+});
+const signalOptions = (options, signal) => signal === "traces" ? { enabled: options.traces, url: options.tracesUrl, headers: options.tracesHeaders } : { enabled: options.metrics, url: options.metricsUrl, headers: options.metricsHeaders }, optionsUrl = (options, signal) => Option.firstSomeOf([
+  Option.fromNullishOr(signalOptions(options, signal).url),
+  Option.map(Option.fromNullishOr(options.baseUrl), (base) => signalUrl(base, signal))
+]), optionsHeaders = (options, signal) => ({ ...options.headers, ...signalOptions(options, signal).headers }), optionsResource = (options) => {
+  const attributes = options.resourceAttributes ?? {};
+  return {
+    serviceName: options.serviceName ?? attributes["service.name"] ?? DEFAULT_SERVICE_NAME,
+    serviceVersion: Option.fromNullishOr(options.serviceVersion ?? attributes["service.version"]),
+    resourceAttributes: attributes
+  };
+};
+export const otlpExportOf = (options) => {
+  const signal = (name) => signalOptions(options, name).enabled === !1 ? Option.none() : Option.map(optionsUrl(options, name), (url) => ({
+    url,
+    headers: optionsHeaders(options, name),
+    compression: options.compression ?? "none",
+    protocol: options.protocol ?? "http/protobuf",
+    exportInterval: Option.fromNullishOr(options.exportInterval)
+  }));
+  return {
+    ...optionsResource(options),
+    traces: signal("traces"),
+    metrics: signal("metrics"),
+    metricsTemporality: options.metricsTemporality ?? "cumulative",
+    shutdownTimeout: Option.fromNullishOr(options.shutdownTimeout)
+  };
+};
+const keyValues = (name, decodeKeys = !1) => Config.option(Config.Record(decodeKeys ? Schema.StringFromUriComponent : Schema.String, Schema.StringFromUriComponent, name)).pipe(Config.map(Option.map((record) => Object.fromEntries(Object.entries(record).map(([key, value]) => [key.trim(), value.trim()]).filter(([key]) => key.length > 0))))), firstSet = (configs) => configs.reduce((found, next) => Effect.flatMap(found, (value) => Option.isSome(value) ? Effect.succeed(value) : next), Effect.succeed(Option.none())), temporalityPreference = Config.option(Config.Literals(["cumulative", "delta", "lowmemory"], "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE")).pipe(Config.map(Option.map((value) => value === "cumulative" ? "cumulative" : "delta"))), intervalVariable = { traces: "OTEL_BSP_SCHEDULE_DELAY", metrics: "OTEL_METRIC_EXPORT_INTERVAL" }, signalFromEnv = (name, defaults) => Effect.gen(function* () {
+  const upper = name.toUpperCase(), own = `OTEL_EXPORTER_OTLP_${upper}_`, exporters = (yield* Config.Array(Schema.String, `OTEL_${upper}_EXPORTER`).pipe(Config.withDefault([]))).map((exporter) => exporter.trim().toLowerCase()).filter((exporter) => exporter.length > 0), url = (exporters.length > 0 ? exporters.includes("otlp") : signalOptions(defaults, name).enabled !== !1) ? Option.orElse(yield* firstSet([
+    Config.option(Config.URL(`${own}ENDPOINT`)).pipe(Config.map(Option.map((endpoint) => endpoint.toString()))),
+    Config.option(Config.URL("OTEL_EXPORTER_OTLP_ENDPOINT")).pipe(Config.map(Option.map((endpoint) => signalUrl(endpoint.toString(), name))))
+  ]), () => optionsUrl(defaults, name)) : Option.none();
+  return Option.isNone(url) ? Option.none() : Option.some({
+    url: url.value,
+    headers: {
+      ...optionsHeaders(defaults, name),
+      ...Option.getOrElse(yield* keyValues("OTEL_EXPORTER_OTLP_HEADERS"), () => ({})),
+      ...Option.getOrElse(yield* keyValues(`${own}HEADERS`), () => ({}))
+    },
+    compression: Option.getOrElse(yield* firstSet([Config.option(Config.schema(OtlpCompression, `${own}COMPRESSION`)), Config.option(Config.schema(OtlpCompression, "OTEL_EXPORTER_OTLP_COMPRESSION"))]), () => defaults.compression ?? "none"),
+    protocol: Option.getOrElse(yield* firstSet([Config.option(Config.schema(OtlpProtocol, `${own}PROTOCOL`)), Config.option(Config.schema(OtlpProtocol, "OTEL_EXPORTER_OTLP_PROTOCOL"))]), () => defaults.protocol ?? "http/protobuf"),
+    exportInterval: Option.orElse(Option.map(yield* Config.option(Config.Int(intervalVariable[name])), Duration.millis), () => Option.fromNullishOr(defaults.exportInterval))
+  });
+});
+export const otlpExportFromEnv = (defaults = {}) => Effect.gen(function* () {
+  const disabled = yield* Config.Boolean("OTEL_SDK_DISABLED").pipe(Config.withDefault(!1)), traces = disabled ? Option.none() : yield* signalFromEnv("traces", defaults), metrics = disabled ? Option.none() : yield* signalFromEnv("metrics", defaults), base = optionsResource(defaults), exporting = Option.isSome(traces) || Option.isSome(metrics), resource = exporting ? Option.getOrElse(yield* keyValues("OTEL_RESOURCE_ATTRIBUTES", !0), () => ({})) : {}, serviceName = exporting ? yield* Config.option(Config.String("OTEL_SERVICE_NAME")) : Option.none(), serviceVersion = exporting ? yield* Config.option(Config.String("OTEL_SERVICE_VERSION")) : Option.none(), temporality = Option.isSome(metrics) ? yield* temporalityPreference : Option.none();
+  return {
+    serviceName: Option.getOrElse(Option.firstSomeOf([serviceName, Option.fromNullishOr(resource["service.name"])]), () => base.serviceName),
+    serviceVersion: Option.firstSomeOf([serviceVersion, Option.fromNullishOr(resource["service.version"]), base.serviceVersion]),
+    resourceAttributes: { ...base.resourceAttributes, ...resource },
+    traces,
+    metrics,
+    metricsTemporality: Option.getOrElse(temporality, () => defaults.metricsTemporality ?? "cumulative"),
+    shutdownTimeout: Option.fromNullishOr(defaults.shutdownTimeout)
+  };
+});

package/dist/otlp-telemetry.entity.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/otlp-telemetry.entity.js

@@ -0,0 +1,2 @@
+import { Schema } from "effect";
+export const OtlpProtocol = Schema.Literals(["http/protobuf", "http/json"]), OtlpCompression = Schema.Literals(["gzip", "none"]), OtlpTemporality = Schema.Literals(["cumulative", "delta"]), DEFAULT_SERVICE_NAME = "efferent";

package/dist/plugin.adapter.d.ts

@@ -1,2 +1,56 @@
-export declare const telemetryPlugin: import("@xandreed/core").Plugin;
-export default telemetryPlugin;
+import { RunContext, TurnEvents } from "@xandreed/core";
+/**
+ * Usage, cost and tool telemetry for every turn (`TurnTelemetryLive`):
+ * session-scoped, built per turn over the turn's `RunContext` and
+ * `TurnEvents`, so under `Agent.turn` it is built inside the turn's
+ * `agent.turn` span and closed before the turn's reply is recorded. It
+ * provides nothing and exports nothing: the host provides an exporter
+ * around its program (`OtlpTelemetryLive`). It keeps the id of the plugin
+ * this package shipped before 0.11.0, whose options (`enabled`,
+ * `serviceName`) it refuses.
+ */
+export declare const telemetryPlugin: import("@xandreed/core").TypedPlugin<{
+    readonly prices: {
+        readonly [x: string]: {
+            readonly input: number;
+            readonly cacheRead: number;
+            readonly cacheWrite: number;
+            readonly output: number;
+            readonly reasoning?: number;
+        };
+    };
+    readonly metricAttributes: {
+        readonly [x: string]: string;
+    };
+    readonly spanEvents: boolean;
+}, {
+    readonly prices: {
+        readonly [x: string]: {
+            readonly input: number;
+            readonly cacheRead: number;
+            readonly cacheWrite: number;
+            readonly output: number;
+            readonly reasoning?: number;
+        };
+    };
+    readonly metricAttributes: {
+        readonly [x: string]: string;
+    };
+    readonly spanEvents: boolean;
+}, never, never, TurnEvents | RunContext>;
+/** The telemetry plugin as a typed layer: requires the turn's RunContext and TurnEvents; provides nothing. */
+export declare const TelemetryPluginLive: (options?: Partial<{
+    readonly prices: {
+        readonly [x: string]: {
+            readonly input: number;
+            readonly cacheRead: number;
+            readonly cacheWrite: number;
+            readonly output: number;
+            readonly reasoning?: number;
+        };
+    };
+    readonly metricAttributes: {
+        readonly [x: string]: string;
+    };
+    readonly spanEvents: boolean;
+}> | undefined) => import("effect/Layer").Layer<never, import("@xandreed/core").HarnessError, TurnEvents | RunContext>;

package/dist/plugin.adapter.js

@@ -1,15 +1,13 @@
-import { Effect, Layer, Schema } from "effect";
-import { definePlugin, TurnHooks } from "@xandreed/core";
-import { TracingLive } from "./telemetry/telemetry.js";
+import { definePlugin, RunContext, TurnEvents } from "@xandreed/core";
+import { TelemetryOptions, telemetryDefaults } from "./telemetry.entity.js";
+import { TurnTelemetryLive } from "./turn-telemetry.adapter.js";
 export const telemetryPlugin = definePlugin({
   id: "@xandreed/plugin-telemetry",
-  version: "0.3.0",
-  config: Schema.Struct({ enabled: Schema.Boolean, serviceName: Schema.String }),
-  defaults: { enabled: !1, serviceName: "efferent" },
-  provides: [TurnHooks],
-  layer: ({ enabled, serviceName }) => Layer.succeed(TurnHooks, {
-    before: (input) => Effect.succeed(input),
-    after: (input) => Effect.annotateCurrentSpan({ "session.id": input.session.id, "run.id": input.runId })
-  }).pipe(Layer.provide(enabled ? TracingLive(serviceName) : Layer.empty))
-});
-export default telemetryPlugin;
+  version: "0.14.0",
+  scope: "session",
+  config: TelemetryOptions,
+  defaults: telemetryDefaults,
+  requires: [RunContext, TurnEvents],
+  provides: [],
+  layer: (config) => TurnTelemetryLive(config)
+}), TelemetryPluginLive = telemetryPlugin.live;

package/dist/plugin.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripted-turn.testing.d.ts

@@ -0,0 +1,30 @@
+import { Effect, Metric, Tracer } from "effect";
+import type { HarnessError, ModelPrice, TurnResult } from "@xandreed/core";
+import type { TelemetryOptions } from "./telemetry.entity.js";
+/**
+ * A key-free turn for the telemetry tests: a host whose `lookup` runs and
+ * whose `archive` may run once per turn, and a scripted model that looks
+ * alpha up, archives it twice in one response (the second call is refused,
+ * `tool-call-limit`) and answers. Every response bills the same usage,
+ * stamped with `MODEL` as the models plugin stamps its selection.
+ */
+export declare const MODEL = "scripted:telemetry-1";
+export declare const PRICE: ModelPrice;
+export declare const conversation: string & import("effect/Brand").Brand<"ConversationId">;
+export declare const RESPONSES: number;
+/** A tracer keeping every span it starts. */
+export declare const capturingTracer: (spans: Array<Tracer.NativeSpan>) => Tracer.Tracer;
+/**
+ * Define an agent with the telemetry plugin (`options`) and run the
+ * scripted turn, its metrics in `registry` (else the ambient one). With `streaming`, every model
+ * call is first streamed and falls back. The turn runs under the ambient
+ * tracer (an exporter's), or `tracer` when given.
+ */
+export declare const scriptedTurn: (options: {
+    readonly registry?: Metric.MetricRegistry;
+    readonly telemetry?: Partial<TelemetryOptions> & Readonly<Record<string, unknown>>;
+    readonly streaming?: boolean;
+    readonly tracer?: Tracer.Tracer;
+}) => Effect.Effect<TurnResult, HarnessError>;
+/** A metric's value in `registry`. */
+export declare const valueIn: <Input, State>(registry: Metric.MetricRegistry, metric: Metric.Metric<Input, State>, attributes: Readonly<Record<string, string>>) => Effect.Effect<State>;

package/dist/telemetry-metrics.d.ts

@@ -0,0 +1,27 @@
+import { Metric } from "effect";
+/**
+ * The metrics the telemetry plugin records, as Effect `Metric`s (a metric's
+ * name, description and attributes are its identity in the registry, so a
+ * dashboard or test reads them through these definitions). Every one also
+ * carries the plugin's `metricAttributes`; none carries a session, run or
+ * turn id.
+ *
+ * | Metric | Attributes | Counts |
+ * |---|---|---|
+ * | `efferent.llm.tokens` | `efferent.model`, `efferent.token.kind` | tokens of each response, by billed kind (`input`, `cache_read`, `cache_write`, `reasoning`, `output`; they sum to the response's total) |
+ * | `efferent.llm.cost` | `efferent.model` | what each priced response cost, in the prices' currency |
+ * | `efferent.steps` | `efferent.step.status` | steps of the step loop, by how they ended (`completed`, `failed`, `cancelled`) |
+ * | `efferent.tool.calls` | `efferent.tool`, `efferent.ok` | tool calls whose handler ran, by result |
+ * | `efferent.tool.duration` | `efferent.tool`, `efferent.ok` | those calls' time in milliseconds, from `tool.started` to the handler's exit |
+ * | `efferent.tool.refused` | `efferent.tool`, `efferent.refusal.reason` | calls the tool registry refused before the handler ran |
+ * | `efferent.stream.fallbacks` | — | streamed model calls that failed before their first part and were answered by a non-streamed call |
+ */
+export declare const TelemetryMetrics: {
+    readonly tokens: Metric.Counter<number>;
+    readonly cost: Metric.Counter<number>;
+    readonly steps: Metric.Counter<number>;
+    readonly toolCalls: Metric.Counter<number>;
+    readonly toolDuration: Metric.Histogram<import("effect/Duration").Duration>;
+    readonly toolRefused: Metric.Counter<number>;
+    readonly streamFallbacks: Metric.Counter<number>;
+};

package/dist/telemetry-metrics.js

@@ -0,0 +1,31 @@
+import { Metric } from "effect";
+export const TelemetryMetrics = {
+  tokens: Metric.counter("efferent.llm.tokens", {
+    description: "tokens of each model response, by billed kind",
+    incremental: !0
+  }),
+  cost: Metric.counter("efferent.llm.cost", {
+    description: "cost of each priced model response, in the prices' currency",
+    incremental: !0
+  }),
+  steps: Metric.counter("efferent.steps", {
+    description: "steps of the step loop, by how they ended",
+    incremental: !0
+  }),
+  toolCalls: Metric.counter("efferent.tool.calls", {
+    description: "tool calls whose handler ran, by result",
+    incremental: !0
+  }),
+  toolDuration: Metric.timer("efferent.tool.duration", {
+    description: "time of each tool call whose handler ran, in milliseconds",
+    boundaries: [10, 50, 100, 250, 500, 1000, 2500, 5000, 1e4, 30000, 60000, 120000, 300000]
+  }),
+  toolRefused: Metric.counter("efferent.tool.refused", {
+    description: "tool calls the registry refused before the handler ran, by reason",
+    incremental: !0
+  }),
+  streamFallbacks: Metric.counter("efferent.stream.fallbacks", {
+    description: "streamed model calls that fell back to a non-streamed call",
+    incremental: !0
+  })
+};

package/dist/telemetry.entity.d.ts

@@ -0,0 +1,50 @@
+import { Schema } from "effect";
+/**
+ * What the telemetry plugin records for each turn it sees.
+ * - `prices`: a model's prices (per million tokens, in the host's currency,
+ *   usually USD), keyed by the model as each response names it: the
+ *   models plugin's `"<provider>:<modelId>"` selection (`assistant.message`
+ *   `model`). A response from an unpriced model, or with no model (a
+ *   `LanguageModel` the models plugin did not route), has no cost.
+ * - `metricAttributes`: constant attributes added to every metric the
+ *   plugin records, such as `deployment.environment`. Keep them few and
+ *   bounded: each distinct value is a new series. Never put a session, run
+ *   or user id here (those are on the spans).
+ * - `spanEvents`: whether the plugin also writes to the span current where
+ *   it is built (the turn's `agent.turn` under `Agent.turn`): the turn's ids
+ *   as attributes, an event per response, refusal and stream fallback, and
+ *   the running cost.
+ *
+ * Flat: the plugin's defaults merge one level deep. The options of the
+ * plugin this package shipped before 0.11.0 (`enabled`, `serviceName`) are
+ * refused; export is the host's `OtlpTelemetryLive` now.
+ */
+export declare const TelemetryOptions: Schema.Struct<{
+    readonly prices: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly input: Schema.Finite;
+        readonly output: Schema.Finite;
+        readonly cacheRead: Schema.Finite;
+        readonly cacheWrite: Schema.Finite;
+        readonly reasoning: Schema.optionalKey<Schema.Finite>;
+    }>>;
+    readonly metricAttributes: Schema.$Record<Schema.String, Schema.String>;
+    readonly spanEvents: Schema.Boolean;
+}>;
+export type TelemetryOptions = typeof TelemetryOptions.Type;
+export declare const telemetryDefaults: TelemetryOptions;
+/**
+ * The five kinds a response's tokens are billed by, as `efferent.token.kind`
+ * names them (core's `usageBreakdown`): uncached input, cache reads, cache
+ * writes, reasoning, and output without its reasoning. For one response
+ * they sum to its `totalTokens`.
+ */
+export declare const TokenKind: Schema.Literals<readonly ["input", "cache_read", "cache_write", "reasoning", "output"]>;
+export type TokenKind = typeof TokenKind.Type;
+/** A response's tokens of one kind (`count > 0` only: a kind the response did not bill is left out). */
+export declare const TokenCount: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["input", "cache_read", "cache_write", "reasoning", "output"]>;
+    readonly count: Schema.Number;
+}>;
+export type TokenCount = typeof TokenCount.Type;
+/** The model attribute of a response with no model (a host's own `LanguageModel`, a planned step). */
+export declare const UNKNOWN_MODEL = "unknown";

package/dist/telemetry.entity.functions.d.ts

@@ -0,0 +1,22 @@
+import { Option } from "effect";
+import type { ModelPrice, TokenUsage } from "@xandreed/core";
+import type { TokenCount } from "./telemetry.entity.js";
+/**
+ * A response's tokens by billed kind (`usageBreakdown`), the kinds it billed
+ * only, in a fixed order: input, cache_read, cache_write, reasoning, output.
+ * For a usage that holds core's invariants the counts sum to `totalTokens`.
+ */
+export declare const tokenCounts: (usage: TokenUsage) => ReadonlyArray<TokenCount>;
+/** The model attribute of a response: its model, or `"unknown"` when it names none. */
+export declare const modelAttribute: (model: Option.Option<string>) => string;
+/** A model's price, when the host gave one for it. */
+export declare const priceOf: (prices: Readonly<Record<string, ModelPrice>>, model: Option.Option<string>) => Option.Option<ModelPrice>;
+/** What a response cost at the host's prices, when its model has one. */
+export declare const responseCost: (prices: Readonly<Record<string, ModelPrice>>, model: Option.Option<string>, usage: TokenUsage) => Option.Option<number>;
+/**
+ * A metric's attributes: the host's constant ones, then the metric's own
+ * (which win, so a host attribute never renames what a series counts).
+ */
+export declare const metricAttributesOf: (host: Readonly<Record<string, string>>, own: Readonly<Record<string, string>>) => Readonly<Record<string, string>>;
+/** A response's usage as span event attributes: the counts under efferent's names, by kind. */
+export declare const usageEventAttributes: (usage: TokenUsage) => Record<string, number>;

package/dist/telemetry.entity.functions.js

@@ -0,0 +1,20 @@
+import { Option } from "effect";
+import { costOf, usageBreakdown } from "@xandreed/core";
+import { UNKNOWN_MODEL } from "./telemetry.entity.js";
+export const tokenCounts = (usage) => {
+  const kinds = usageBreakdown(usage);
+  return [
+    ["input", kinds.input],
+    ["cache_read", kinds.cacheRead],
+    ["cache_write", kinds.cacheWrite],
+    ["reasoning", kinds.reasoning],
+    ["output", kinds.output]
+  ].filter(([, count]) => count > 0).map(([kind, count]) => ({ kind, count }));
+}, modelAttribute = (model) => Option.getOrElse(model, () => UNKNOWN_MODEL), priceOf = (prices, model) => Option.flatMap(model, (name) => Object.hasOwn(prices, name) ? Option.fromNullishOr(prices[name]) : Option.none()), responseCost = (prices, model, usage) => Option.map(priceOf(prices, model), (price) => costOf(usage, price)), metricAttributesOf = (host, own) => ({ ...host, ...own }), usageEventAttributes = (usage) => ({
+  "efferent.usage.input_tokens": usage.inputTokens,
+  "efferent.usage.output_tokens": usage.outputTokens,
+  "efferent.usage.cache_read_tokens": usage.cacheReadTokens,
+  "efferent.usage.cache_write_tokens": usage.cacheWriteTokens,
+  "efferent.usage.reasoning_tokens": usage.reasoningTokens,
+  "efferent.usage.total_tokens": usage.totalTokens
+});

package/dist/telemetry.entity.functions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/telemetry.entity.js

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+import { ModelPrice } from "@xandreed/core";
+export const TelemetryOptions = Schema.Struct({
+  prices: Schema.Record(Schema.String, ModelPrice),
+  metricAttributes: Schema.Record(Schema.String, Schema.String),
+  spanEvents: Schema.Boolean
+}), telemetryDefaults = { prices: {}, metricAttributes: {}, spanEvents: !0 }, TokenKind = Schema.Literals(["input", "cache_read", "cache_write", "reasoning", "output"]), TokenCount = Schema.Struct({
+  kind: TokenKind,
+  count: Schema.Number
+}), UNKNOWN_MODEL = "unknown";

package/dist/turn-telemetry.adapter.d.ts

@@ -0,0 +1,20 @@
+import { Layer } from "effect";
+import { RunContext, TurnEvents } from "@xandreed/core";
+import type { TelemetryOptions } from "./telemetry.entity.js";
+/**
+ * The turn's telemetry: one inline subscription to the turn's events that
+ * records the plugin's metrics (`TelemetryMetrics`) from them, and, with
+ * `spanEvents`, writes to the span current where the layer is built. Under
+ * `Agent.turn` that span is the turn's `agent.turn` (the turn-dependent
+ * plugins are built inside it); in a host's own composition it is whatever
+ * span encloses the build, `traceTurn`'s when the host uses it (it must
+ * stay open while the turn runs: a tracer drops what is written to a span
+ * that ended). Whatever span publishes an event, it lands there. On that span
+ * it sets `efferent.session.id`, `efferent.run.id` and `efferent.turn` when
+ * built, adds an event per response with usage (`efferent.step.usage`), per
+ * refused call (`efferent.tool.refused`) and per stream fallback
+ * (`efferent.stream.fallback`), and keeps the turn's running cost in
+ * `efferent.cost` (priced responses only). A response with no usage (a
+ * host-planned step 0) records nothing. Recording never fails the turn.
+ */
+export declare const TurnTelemetryLive: (options?: Partial<TelemetryOptions>) => Layer.Layer<never, never, RunContext | TurnEvents>;

package/dist/turn-telemetry.adapter.js

@@ -0,0 +1,53 @@
+import { Clock, Duration, Effect, Layer, Match, Metric, Option, Ref } from "effect";
+import { RunContext, TurnEvents } from "@xandreed/core";
+import { TelemetryMetrics } from "./telemetry-metrics.js";
+import { telemetryDefaults } from "./telemetry.entity.js";
+import { metricAttributesOf, modelAttribute, responseCost, tokenCounts, usageEventAttributes } from "./telemetry.entity.functions.js";
+const RECORDED = ["assistant.message", "tool.completed", "tool.refused", "step.ended", "stream.fallback"], isRecorded = (event) => RECORDED.includes(event._tag);
+export const TurnTelemetryLive = (options = {}) => Layer.effectDiscard(Effect.gen(function* () {
+  const config = { ...telemetryDefaults, ...options }, run = yield* RunContext, events = yield* TurnEvents, span = config.spanEvents ? yield* Effect.option(Effect.currentSpan) : Option.none(), spent = yield* Ref.make(0), onSpan = (write) => Option.match(span, {
+    onNone: () => Effect.void,
+    onSome: (target) => Clock.currentTimeNanos.pipe(Effect.map((now) => write(target, now)))
+  }), count = (metric, own, input) => Metric.update(Metric.withAttributes(metric, metricAttributesOf(config.metricAttributes, own)), input), record = (event) => Match.valueTags(event, {
+    "assistant.message": (message) => message.usage.totalTokens === 0 ? Effect.void : Effect.gen(function* () {
+      const model = modelAttribute(message.model);
+      yield* Effect.forEach(tokenCounts(message.usage), (tokens) => count(TelemetryMetrics.tokens, { "efferent.model": model, "efferent.token.kind": tokens.kind }, tokens.count), { discard: !0 });
+      const cost = responseCost(config.prices, message.model, message.usage), total = yield* Option.match(cost, {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (amount) => count(TelemetryMetrics.cost, { "efferent.model": model }, amount).pipe(Effect.andThen(Ref.updateAndGet(spent, (sum) => sum + amount)), Effect.map(Option.some))
+      });
+      yield* onSpan((target, now) => {
+        target.event("efferent.step.usage", now, {
+          "efferent.step": message.step,
+          "efferent.model": model,
+          ...usageEventAttributes(message.usage),
+          ...Option.match(cost, { onNone: () => ({}), onSome: (amount) => ({ "efferent.cost": amount }) })
+        });
+        Option.match(total, { onNone: () => {
+          return;
+        }, onSome: (sum) => target.attribute("efferent.cost", sum) });
+      });
+    }),
+    "tool.completed": (completed) => {
+      const own = { "efferent.tool": completed.tool, "efferent.ok": String(completed.ok) };
+      return count(TelemetryMetrics.toolCalls, own, 1).pipe(Effect.andThen(count(TelemetryMetrics.toolDuration, own, Duration.millis(completed.durationMs))));
+    },
+    "tool.refused": (refused) => count(TelemetryMetrics.toolRefused, { "efferent.tool": refused.tool, "efferent.refusal.reason": refused.reason }, 1).pipe(Effect.andThen(onSpan((target, now) => target.event("efferent.tool.refused", now, {
+      "efferent.step": refused.step,
+      "efferent.tool": refused.tool,
+      "efferent.tool.invocation_id": refused.invocationId,
+      "efferent.refusal.reason": refused.reason
+    })))),
+    "step.ended": (ended) => count(TelemetryMetrics.steps, { "efferent.step.status": ended.status }, 1),
+    "stream.fallback": (fallback) => count(TelemetryMetrics.streamFallbacks, {}, 1).pipe(Effect.andThen(onSpan((target, now) => target.event("efferent.stream.fallback", now, {
+      "efferent.step": fallback.step,
+      "efferent.stream.fallback.message": fallback.message
+    }))))
+  });
+  yield* onSpan((target) => {
+    target.attribute("efferent.session.id", run.session.id);
+    target.attribute("efferent.run.id", run.runId);
+    target.attribute("efferent.turn", run.admitted.turn);
+  });
+  yield* events.subscribe((event) => isRecorded(event) ? Option.some(event) : Option.none(), record);
+}));

package/dist/turn-telemetry.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@xandreed/plugin-telemetry",
-  "version": "0.3.0",
+  "version": "0.14.0",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3.0"
+  },
   "type": "module",
+  "description": "Usage, cost and tool telemetry for efferent turns, and OTLP/HTTP export of traces and metrics over Effect's own exporters (Node 24 and Bun).",
   "main": "./dist/index.js",
   "exports": {
     ".": {
@@ -10,15 +15,8 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.3.0",
-    "effect": "3.21.4",
-    "@effect/opentelemetry": "^0.63.0",
-    "@effect/platform": "0.96.1",
-    "@effect/platform-bun": "^0.89.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.219.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
-    "@opentelemetry/sdk-metrics": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0"
+    "@xandreed/core": "0.14.0",
+    "effect": "4.0.7"
   },
   "private": false,
   "types": "./dist/index.d.ts",
@@ -29,8 +27,5 @@
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "bun": ">=1.3.0"
-  },
   "license": "MIT"
 }

package/dist/telemetry/telemetry.d.ts

@@ -1,21 +0,0 @@
-import { Layer } from "effect";
-/**
- * The observability edge — two layers every agent main composes:
- *
- * - `TracingLive(serviceName)` exports the spans the kernel already emits
- *   (`engine.run` / `engine.turn` / `providers.generate`) over OTLP HTTP to
- *   the local stack (`bun run obs:up`, grafana on :3000). The exporter reads
- *   the standard `OTEL_EXPORTER_OTLP_ENDPOINT` env itself and defaults to
- *   `http://localhost:4318`; when no collector is listening, batch exports
- *   fail SILENTLY (no diag logger is registered) — always-on costs nothing.
- *
- * - `FileLoggerLive(path)` routes Effect's logger to an append-only logfmt
- *   file. The TUI previously SILENCED all logs (any console write corrupts
- *   the alt screen), which meant a mid-run failure left no trace anywhere —
- *   a session that "just died" was undiagnosable. Now it's on disk.
- */
-export declare const TracingLive: (serviceName: string) => Layer.Layer<never>;
-export declare const FileLoggerLive: (path: string) => Layer.Layer<never>;
-/** Add the file sink while retaining the driver's console logger (headless
- *  mode needs both a live stderr narrative and crash-forensics on disk). */
-export declare const FileLoggerAddLive: (path: string) => Layer.Layer<never>;

package/dist/telemetry/telemetry.js

@@ -1,24 +0,0 @@
-import { dirname } from "node:path";
-import { NodeSdk } from "@effect/opentelemetry";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { FileSystem, PlatformLogger } from "@effect/platform";
-import { BunFileSystem } from "@effect/platform-bun";
-import { Effect, Layer, Logger } from "effect";
-export const TracingLive = (serviceName) => NodeSdk.layer(() => ({
-  resource: { serviceName },
-  spanProcessor: [new BatchSpanProcessor(new OTLPTraceExporter)],
-  metricReader: new PeriodicExportingMetricReader({
-    exporter: new OTLPMetricExporter,
-    exportIntervalMillis: 5000
-  })
-}));
-const fileLogger = (path) => Effect.gen(function* () {
-  yield* (yield* FileSystem.FileSystem).makeDirectory(dirname(path), { recursive: !0 }).pipe(Effect.orElseSucceed(() => {
-    return;
-  }));
-  return yield* PlatformLogger.toFile(Logger.logfmtLogger, path, { flag: "a" });
-}).pipe(Effect.orElseSucceed(() => Logger.none));
-export const FileLoggerLive = (path) => Logger.replaceScoped(Logger.defaultLogger, fileLogger(path)).pipe(Layer.provide(BunFileSystem.layer)), FileLoggerAddLive = (path) => Logger.addScoped(fileLogger(path)).pipe(Layer.provide(BunFileSystem.layer));