@xandreed/plugin-telemetry 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+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,5 @@
+# @xandreed/plugin-telemetry
+
+Efferent composable agent framework, 0.3.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FileLoggerAddLive, FileLoggerLive, TracingLive } from "./telemetry/telemetry.js";
+export { telemetryPlugin, default } from "./plugin.adapter.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FileLoggerAddLive, FileLoggerLive, TracingLive } from "./telemetry/telemetry.js";
+export { telemetryPlugin, default } from "./plugin.adapter.js";

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,2 @@
+export declare const telemetryPlugin: import("@xandreed/core").Plugin;
+export default telemetryPlugin;

package/dist/plugin.adapter.js

@@ -0,0 +1,15 @@
+import { Effect, Layer, Schema } from "effect";
+import { definePlugin, TurnHooks } from "@xandreed/core";
+import { TracingLive } from "./telemetry/telemetry.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;

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,24 @@
+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));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@xandreed/plugin-telemetry",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "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"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}