@agentproto/telemetry 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy (agentik.net)
+
+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,71 @@
+# @agentproto/telemetry
+
+Vendor-neutral **Telemetry** port for the agentproto runtime kernel, plus
+reference sinks and an OpenTelemetry adapter.
+
+A runtime emits a stream of structured `TelemetryEvent`s during each cycle —
+every event carries a `cycleId` and an ISO `at` timestamp, so a sink can rebuild
+OTEL-style spans by grouping on `cycleId`. Events are schema
+`agentproto/telemetry/v1`; **sinks must tolerate unknown kinds** (future kernel
+versions may add event types under the same schema).
+
+This package is a **leaf**: it owns the port and depends on no runtime. Runtimes
+depend on it.
+
+## The port
+
+```ts
+import type { Telemetry, TelemetryEvent } from "@agentproto/telemetry"
+
+interface Telemetry {
+  emit(event: TelemetryEvent): void
+}
+```
+
+## Reference sinks
+
+- `noopTelemetry` — drops everything. Same as leaving telemetry unset.
+- `stderrTelemetry(opts?)` — one human-readable line per event, with
+  `include` / `exclude` kind filters and a `prefix`.
+- `arrayTelemetry()` — pushes every event onto `.events`; for tests.
+- `composeTelemetry(...sinks)` — fan-out to many sinks, each isolated (one
+  throwing does not block the others).
+
+```ts
+import { composeTelemetry, stderrTelemetry } from "@agentproto/telemetry"
+
+const telemetry = composeTelemetry(stderrTelemetry({ prefix: "run: " }), otel)
+```
+
+## OpenTelemetry adapter
+
+`otelTelemetry(tracer)` maps the event stream onto OTel spans. It is a **pure
+mapper** — the host supplies the `Tracer` (peer dependency
+`@opentelemetry/api`). No global provider, no exporter wiring.
+
+```ts
+import { trace } from "@opentelemetry/api"
+import { otelTelemetry } from "@agentproto/telemetry"
+
+const tracer = trace.getTracer("my-runtime")
+const telemetry = otelTelemetry(tracer)
+
+// hand `telemetry` to the runtime; each cycle becomes an `agentproto.cycle`
+// span with `agentproto.participant` child spans.
+```
+
+Mapping:
+
+| Event | OTel effect |
+| --- | --- |
+| `cycle.started` | start root span `agentproto.cycle`, held per `cycleId` |
+| `participant.started` | child span `agentproto.participant` (participantId, executorKind) |
+| `participant.finished` | end child span (durationMs, contentLength attrs) |
+| `participant.failed` | `recordException` + `ERROR` status, then end |
+| `substrate.read` / `dispatch.decided` / … | `addEvent` on the cycle span |
+| `cycle.finished` / `cycle.idle` | outcome attrs, end the cycle span |
+| unknown kind | ignored silently (forward-compat) |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+import { Tracer } from '@opentelemetry/api';
+
+/**
+ * Vendor-neutral Telemetry port.
+ *
+ * This package OWNS the telemetry contract so any runtime can depend on a
+ * single interface without pulling in a kernel. It is a LEAF — it imports
+ * nothing from a runtime; runtimes depend on IT.
+ *
+ * The two referenced id types are mirrored locally (plain `string`) so the
+ * port has no upstream dependency. A runtime may use branded ids; they widen
+ * to `string` and remain assignable here.
+ */
+type ParticipantId = string;
+type TurnId = string;
+/**
+ * Discriminated union of every event a kernel emits during a cycle.
+ *
+ * Every event carries `cycleId` (a per-cycle ULID-ish identifier) and
+ * `at` (ISO timestamp), so a sink can rebuild OTEL-style spans by
+ * grouping on cycleId.
+ *
+ * Sinks MUST tolerate unknown kinds — future kernel versions may add
+ * event types under the same `agentproto/telemetry/v1` schema.
+ */
+type TelemetryEvent = {
+    readonly kind: "cycle.started";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly since?: TurnId;
+} | {
+    readonly kind: "substrate.read";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly substrateKind: string;
+    readonly turnCount: number;
+    readonly durationMs: number;
+} | {
+    readonly kind: "dispatch.decided";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly dispatcherKind: string;
+    readonly selected: readonly ParticipantId[];
+    readonly durationMs: number;
+} | {
+    readonly kind: "participant.started";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly participantId: ParticipantId;
+    readonly executorKind: string;
+} | {
+    readonly kind: "participant.finished";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly participantId: ParticipantId;
+    readonly executorKind: string;
+    readonly durationMs: number;
+    readonly contentLength: number;
+} | {
+    readonly kind: "participant.failed";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly participantId: ParticipantId;
+    readonly executorKind: string;
+    readonly error: string;
+} | {
+    readonly kind: "substrate.appended";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly turnId: TurnId;
+    readonly participantId: ParticipantId;
+} | {
+    readonly kind: "state.written";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly participantId: ParticipantId;
+} | {
+    readonly kind: "cycle.idle";
+    readonly cycleId: string;
+    readonly at: string;
+} | {
+    readonly kind: "cycle.finished";
+    readonly cycleId: string;
+    readonly at: string;
+    readonly outcome: "executed" | "idle";
+    readonly turnsAppended: number;
+    readonly durationMs: number;
+};
+/**
+ * Structured-event sink. Wire to log lines, an OTEL exporter, an in-memory
+ * array (tests), or anything else. Implementations MUST tolerate unknown
+ * event kinds (forward-compat under `agentproto/telemetry/v1`).
+ *
+ * The port is generic over the event type `E` so a downstream package can
+ * carry its OWN discriminated union through the same sink contract (e.g.
+ * `Telemetry<EvalEvent>`). The default `E = TelemetryEvent` keeps every
+ * existing usage — `Telemetry` written with no type argument — unchanged.
+ */
+interface Telemetry<E = TelemetryEvent> {
+    emit(event: E): void;
+}
+
+/**
+ * Reference Telemetry adapters.
+ *
+ * Wire `RuntimePorts.telemetry` to one of these (or your own
+ * implementation) to receive structured events from each cycle.
+ * Sinks may also be composed via `composeTelemetry()`.
+ */
+
+/**
+ * No-op sink. Equivalent to leaving `telemetry` undefined on RuntimePorts.
+ *
+ * A factory generic over the event type `E` (default `TelemetryEvent`) so it
+ * satisfies `Telemetry<E>` for any downstream union. `noopTelemetry()` with no
+ * type argument returns the ordinary `Telemetry<TelemetryEvent>` sink.
+ */
+declare function noopTelemetry<E = TelemetryEvent>(): Telemetry<E>;
+interface StderrTelemetryOptions<E = TelemetryEvent> {
+    /** Event kinds to include. Omit to emit all kinds. */
+    readonly include?: ReadonlySet<TelemetryEvent["kind"]>;
+    /** Event kinds to suppress. Wins over `include`. */
+    readonly exclude?: ReadonlySet<TelemetryEvent["kind"]>;
+    /** Prefix prepended to every line. Default "agentproto: ". */
+    readonly prefix?: string;
+    /**
+     * Render a line for an event. Required when `E` is not `TelemetryEvent`
+     * (the built-in formatter only understands the concrete telemetry union).
+     * When omitted, the built-in `TelemetryEvent` formatter is used — valid only
+     * for the default `E = TelemetryEvent`.
+     */
+    readonly format?: (event: E) => string;
+}
+/**
+ * Human-readable stderr sink — one line per event. Cheaper than wiring
+ * a real exporter; good default for `--verbose` mode.
+ *
+ * Generic over the event type `E`. For a custom `E`, pass `format` — the
+ * built-in formatter is `TelemetryEvent`-specific. The `include`/`exclude`
+ * filters key on `event.kind`, which every telemetry-shaped event carries.
+ */
+declare function stderrTelemetry<E = TelemetryEvent>(options?: StderrTelemetryOptions<E>): Telemetry<E>;
+/**
+ * In-memory sink — every event pushed onto an array. Intended for
+ * tests; reach into `events` after `runTurn` to assert. Generic over the
+ * event type `E` so a custom union's events collect with full typing.
+ */
+declare function arrayTelemetry<E = TelemetryEvent>(): Telemetry<E> & {
+    readonly events: readonly E[];
+};
+/**
+ * Fan-out — emits every event to all wrapped sinks in order. Useful
+ * for "log to stderr AND export to OTEL" setups. Generic over the event
+ * type `E`; every wrapped sink shares the same `E`.
+ */
+declare function composeTelemetry<E = TelemetryEvent>(...sinks: readonly Telemetry<E>[]): Telemetry<E>;
+
+/**
+ * OpenTelemetry adapter for the vendor-neutral Telemetry port.
+ *
+ * `otelTelemetry(tracer)` returns a `Telemetry` sink that maps the kernel's
+ * `TelemetryEvent` stream onto OTel spans, grouping on `cycleId`:
+ *
+ *   cycle.started        → root span `agentproto.cycle` (held per cycleId)
+ *   participant.started  → child span `agentproto.participant`
+ *   participant.finished → end child span (durationMs, contentLength attrs)
+ *   participant.failed   → recordException + ERROR status, then end
+ *   substrate.read       → addEvent on the cycle span
+ *   dispatch.decided     → addEvent on the cycle span
+ *   cycle.finished/idle  → outcome attrs, end the cycle span, drop from map
+ *   unknown kind         → ignored silently (forward-compat contract)
+ *
+ * This is a PURE MAPPER: the host supplies the `Tracer`. No global provider,
+ * no exporter, no context propagation beyond parenting child spans under the
+ * cycle span.
+ */
+
+interface OtelTelemetryOptions {
+    /** Span name for the per-cycle root span. Default "agentproto.cycle". */
+    readonly cycleSpanName?: string;
+    /** Span name for each participant child span. Default "agentproto.participant". */
+    readonly participantSpanName?: string;
+}
+/**
+ * Build a `Telemetry` sink that projects events onto OTel spans via the
+ * host-supplied `tracer`.
+ */
+declare function otelTelemetry(tracer: Tracer, options?: OtelTelemetryOptions): Telemetry;
+
+export { type OtelTelemetryOptions, type ParticipantId, type StderrTelemetryOptions, type Telemetry, type TelemetryEvent, type TurnId, arrayTelemetry, composeTelemetry, noopTelemetry, otelTelemetry, stderrTelemetry };

package/dist/index.mjs

@@ -0,0 +1,219 @@
+import { SpanStatusCode, trace, context } from '@opentelemetry/api';
+
+/**
+ * @agentproto/telemetry v0.1.0
+ * Vendor-neutral Telemetry port + reference sinks + OpenTelemetry adapter.
+ */
+
+// src/adapters.ts
+function noopTelemetry() {
+  return {
+    emit() {
+    }
+  };
+}
+function stderrTelemetry(options = {}) {
+  const prefix = options.prefix ?? "agentproto: ";
+  const format = options.format ?? defaultFormat;
+  return {
+    emit(event) {
+      const kind = kindOf(event);
+      if (kind !== void 0 && setHas(options.exclude, kind)) return;
+      if (kind !== void 0 && options.include && !setHas(options.include, kind))
+        return;
+      process.stderr.write(`${prefix}${format(event)}
+`);
+    }
+  };
+}
+function setHas(set, value) {
+  return set !== void 0 && set.has(value);
+}
+function defaultFormat(event) {
+  return isTelemetryEvent(event) ? formatEvent(event) : JSON.stringify(event);
+}
+function kindOf(event) {
+  if (typeof event !== "object" || event === null) return void 0;
+  if (!("kind" in event)) return void 0;
+  const kind = event.kind;
+  return typeof kind === "string" ? kind : void 0;
+}
+function isTelemetryEvent(event) {
+  return kindOf(event) !== void 0;
+}
+function arrayTelemetry() {
+  const events = [];
+  return {
+    events,
+    emit(event) {
+      events.push(event);
+    }
+  };
+}
+function composeTelemetry(...sinks) {
+  return {
+    emit(event) {
+      for (const sink of sinks) {
+        try {
+          sink.emit(event);
+        } catch {
+        }
+      }
+    }
+  };
+}
+function formatEvent(event) {
+  switch (event.kind) {
+    case "cycle.started":
+      return `${event.cycleId} cycle.started${event.since !== void 0 ? ` since=${event.since}` : ""}`;
+    case "substrate.read":
+      return `${event.cycleId} substrate.read ${event.substrateKind} turns=${event.turnCount} ${event.durationMs}ms`;
+    case "dispatch.decided":
+      return `${event.cycleId} dispatch.decided ${event.dispatcherKind} selected=[${event.selected.join(",") || "(none)"}] ${event.durationMs}ms`;
+    case "participant.started":
+      return `${event.cycleId} participant.started ${event.participantId} (${event.executorKind})`;
+    case "participant.finished":
+      return `${event.cycleId} participant.finished ${event.participantId} ${event.durationMs}ms content=${event.contentLength}b`;
+    case "participant.failed":
+      return `${event.cycleId} participant.failed ${event.participantId} \u2014 ${event.error}`;
+    case "substrate.appended":
+      return `${event.cycleId} substrate.appended turn=${event.turnId} by=${event.participantId}`;
+    case "state.written":
+      return `${event.cycleId} state.written ${event.participantId}`;
+    case "cycle.idle":
+      return `${event.cycleId} cycle.idle`;
+    case "cycle.finished":
+      return `${event.cycleId} cycle.finished ${event.outcome} appended=${event.turnsAppended} ${event.durationMs}ms`;
+    default: {
+      const _exhaustive = event;
+      return JSON.stringify(_exhaustive);
+    }
+  }
+}
+function otelTelemetry(tracer, options = {}) {
+  const cycleSpanName = options.cycleSpanName ?? "agentproto.cycle";
+  const participantSpanName = options.participantSpanName ?? "agentproto.participant";
+  const cycleSpans = /* @__PURE__ */ new Map();
+  const participantSpans = /* @__PURE__ */ new Map();
+  const startChild = (parent, name) => {
+    const parentCtx = trace.setSpan(context.active(), parent);
+    return tracer.startSpan(name, void 0, parentCtx);
+  };
+  const dropParticipant = (cycleId, participantId) => {
+    const byParticipant = participantSpans.get(cycleId);
+    const span = byParticipant?.get(participantId);
+    if (byParticipant && span) {
+      byParticipant.delete(participantId);
+      if (byParticipant.size === 0) participantSpans.delete(cycleId);
+    }
+    return span;
+  };
+  const endCycle = (event) => {
+    const span = cycleSpans.get(event.cycleId);
+    if (!span) return;
+    if (event.kind === "cycle.finished") {
+      span.setAttribute("agentproto.cycle.outcome", event.outcome);
+      span.setAttribute("agentproto.cycle.turnsAppended", event.turnsAppended);
+      span.setAttribute("agentproto.cycle.durationMs", event.durationMs);
+    } else {
+      span.setAttribute("agentproto.cycle.outcome", "idle");
+    }
+    const orphans = participantSpans.get(event.cycleId);
+    if (orphans) {
+      for (const child of orphans.values()) child.end();
+      participantSpans.delete(event.cycleId);
+    }
+    span.end();
+    cycleSpans.delete(event.cycleId);
+  };
+  return {
+    emit(event) {
+      switch (event.kind) {
+        case "cycle.started": {
+          const span = tracer.startSpan(cycleSpanName);
+          span.setAttribute("agentproto.cycleId", event.cycleId);
+          if (event.since !== void 0) {
+            span.setAttribute("agentproto.cycle.since", event.since);
+          }
+          cycleSpans.set(event.cycleId, span);
+          return;
+        }
+        case "participant.started": {
+          const cycleSpan = cycleSpans.get(event.cycleId);
+          if (!cycleSpan) return;
+          const span = startChild(cycleSpan, participantSpanName);
+          span.setAttribute("agentproto.participantId", event.participantId);
+          span.setAttribute("agentproto.executorKind", event.executorKind);
+          let byParticipant = participantSpans.get(event.cycleId);
+          if (!byParticipant) {
+            byParticipant = /* @__PURE__ */ new Map();
+            participantSpans.set(event.cycleId, byParticipant);
+          }
+          byParticipant.set(event.participantId, span);
+          return;
+        }
+        case "participant.finished": {
+          const span = dropParticipant(event.cycleId, event.participantId);
+          if (!span) return;
+          span.setAttribute("agentproto.participant.durationMs", event.durationMs);
+          span.setAttribute("agentproto.participant.contentLength", event.contentLength);
+          span.end();
+          return;
+        }
+        case "participant.failed": {
+          const span = dropParticipant(event.cycleId, event.participantId);
+          if (!span) return;
+          span.recordException({ name: "ParticipantExecuteError", message: event.error });
+          span.setStatus({ code: SpanStatusCode.ERROR, message: event.error });
+          span.end();
+          return;
+        }
+        case "substrate.read": {
+          const span = cycleSpans.get(event.cycleId);
+          span?.addEvent("substrate.read", {
+            "agentproto.substrateKind": event.substrateKind,
+            "agentproto.turnCount": event.turnCount,
+            "agentproto.durationMs": event.durationMs
+          });
+          return;
+        }
+        case "dispatch.decided": {
+          const span = cycleSpans.get(event.cycleId);
+          span?.addEvent("dispatch.decided", {
+            "agentproto.dispatcherKind": event.dispatcherKind,
+            "agentproto.selected": event.selected.join(","),
+            "agentproto.durationMs": event.durationMs
+          });
+          return;
+        }
+        case "substrate.appended": {
+          const span = cycleSpans.get(event.cycleId);
+          span?.addEvent("substrate.appended", {
+            "agentproto.turnId": event.turnId,
+            "agentproto.participantId": event.participantId
+          });
+          return;
+        }
+        case "state.written": {
+          const span = cycleSpans.get(event.cycleId);
+          span?.addEvent("state.written", {
+            "agentproto.participantId": event.participantId
+          });
+          return;
+        }
+        case "cycle.finished":
+        case "cycle.idle": {
+          endCycle(event);
+          return;
+        }
+        default: {
+          return;
+        }
+      }
+    }
+  };
+}
+
+export { arrayTelemetry, composeTelemetry, noopTelemetry, otelTelemetry, stderrTelemetry };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters.ts","../src/otel.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Reference Telemetry adapters.\n *\n * Wire `RuntimePorts.telemetry` to one of these (or your own\n * implementation) to receive structured events from each cycle.\n * Sinks may also be composed via `composeTelemetry()`.\n */\n\nimport type { Telemetry, TelemetryEvent } from \"./ports.js\"\n\n/**\n * No-op sink. Equivalent to leaving `telemetry` undefined on RuntimePorts.\n *\n * A factory generic over the event type `E` (default `TelemetryEvent`) so it\n * satisfies `Telemetry<E>` for any downstream union. `noopTelemetry()` with no\n * type argument returns the ordinary `Telemetry<TelemetryEvent>` sink.\n */\nexport function noopTelemetry<E = TelemetryEvent>(): Telemetry<E> {\n  return {\n    emit() {\n      // intentionally blank\n    },\n  }\n}\n\nexport interface StderrTelemetryOptions<E = TelemetryEvent> {\n  /** Event kinds to include. Omit to emit all kinds. */\n  readonly include?: ReadonlySet<TelemetryEvent[\"kind\"]>\n  /** Event kinds to suppress. Wins over `include`. */\n  readonly exclude?: ReadonlySet<TelemetryEvent[\"kind\"]>\n  /** Prefix prepended to every line. Default \"agentproto: \". */\n  readonly prefix?: string\n  /**\n   * Render a line for an event. Required when `E` is not `TelemetryEvent`\n   * (the built-in formatter only understands the concrete telemetry union).\n   * When omitted, the built-in `TelemetryEvent` formatter is used — valid only\n   * for the default `E = TelemetryEvent`.\n   */\n  readonly format?: (event: E) => string\n}\n\n/**\n * Human-readable stderr sink — one line per event. Cheaper than wiring\n * a real exporter; good default for `--verbose` mode.\n *\n * Generic over the event type `E`. For a custom `E`, pass `format` — the\n * built-in formatter is `TelemetryEvent`-specific. The `include`/`exclude`\n * filters key on `event.kind`, which every telemetry-shaped event carries.\n */\nexport function stderrTelemetry<E = TelemetryEvent>(\n  options: StderrTelemetryOptions<E> = {}\n): Telemetry<E> {\n  const prefix = options.prefix ?? \"agentproto: \"\n  const format = options.format ?? defaultFormat\n  return {\n    emit(event) {\n      const kind = kindOf(event)\n      if (kind !== undefined && setHas(options.exclude, kind)) return\n      if (kind !== undefined && options.include && !setHas(options.include, kind))\n        return\n      process.stderr.write(`${prefix}${format(event)}\\n`)\n    },\n  }\n}\n\n/**\n * Membership test that accepts a plain `string` probe against a set of literal\n * kinds — avoids an `as` cast on the discriminant while keeping the public\n * option type (`ReadonlySet<TelemetryEvent[\"kind\"]>`) narrow for callers.\n */\nfunction setHas(\n  set: ReadonlySet<string> | undefined,\n  value: string,\n): boolean {\n  return set !== undefined && set.has(value)\n}\n\n/**\n * The built-in stderr formatter, usable only when `E = TelemetryEvent`.\n * Wrapped so it satisfies the generic `(event: E) => string` default without a\n * cast: it narrows through {@link isTelemetryEvent} and JSON-renders anything\n * else (forward-compat, same contract as {@link formatEvent}'s default arm).\n */\nfunction defaultFormat<E>(event: E): string {\n  return isTelemetryEvent(event) ? formatEvent(event) : JSON.stringify(event)\n}\n\n/** Read a `kind` discriminant off an event, if it carries one. */\nfunction kindOf(event: unknown): string | undefined {\n  if (typeof event !== \"object\" || event === null) return undefined\n  if (!(\"kind\" in event)) return undefined\n  const kind: unknown = event.kind\n  return typeof kind === \"string\" ? kind : undefined\n}\n\n/** Structural guard: is this a concrete {@link TelemetryEvent}? */\nfunction isTelemetryEvent(event: unknown): event is TelemetryEvent {\n  return kindOf(event) !== undefined\n}\n\n/**\n * In-memory sink — every event pushed onto an array. Intended for\n * tests; reach into `events` after `runTurn` to assert. Generic over the\n * event type `E` so a custom union's events collect with full typing.\n */\nexport function arrayTelemetry<E = TelemetryEvent>(): Telemetry<E> & {\n  readonly events: readonly E[]\n} {\n  const events: E[] = []\n  return {\n    events,\n    emit(event) {\n      events.push(event)\n    },\n  }\n}\n\n/**\n * Fan-out — emits every event to all wrapped sinks in order. Useful\n * for \"log to stderr AND export to OTEL\" setups. Generic over the event\n * type `E`; every wrapped sink shares the same `E`.\n */\nexport function composeTelemetry<E = TelemetryEvent>(\n  ...sinks: readonly Telemetry<E>[]\n): Telemetry<E> {\n  return {\n    emit(event) {\n      for (const sink of sinks) {\n        try {\n          sink.emit(event)\n        } catch {\n          // Each sink is independently isolated.\n        }\n      }\n    },\n  }\n}\n\nfunction formatEvent(event: TelemetryEvent): string {\n  switch (event.kind) {\n    case \"cycle.started\":\n      return `${event.cycleId} cycle.started${event.since !== undefined ? ` since=${event.since}` : \"\"}`\n    case \"substrate.read\":\n      return `${event.cycleId} substrate.read ${event.substrateKind} turns=${event.turnCount} ${event.durationMs}ms`\n    case \"dispatch.decided\":\n      return `${event.cycleId} dispatch.decided ${event.dispatcherKind} selected=[${event.selected.join(\",\") || \"(none)\"}] ${event.durationMs}ms`\n    case \"participant.started\":\n      return `${event.cycleId} participant.started ${event.participantId} (${event.executorKind})`\n    case \"participant.finished\":\n      return `${event.cycleId} participant.finished ${event.participantId} ${event.durationMs}ms content=${event.contentLength}b`\n    case \"participant.failed\":\n      return `${event.cycleId} participant.failed ${event.participantId} — ${event.error}`\n    case \"substrate.appended\":\n      return `${event.cycleId} substrate.appended turn=${event.turnId} by=${event.participantId}`\n    case \"state.written\":\n      return `${event.cycleId} state.written ${event.participantId}`\n    case \"cycle.idle\":\n      return `${event.cycleId} cycle.idle`\n    case \"cycle.finished\":\n      return `${event.cycleId} cycle.finished ${event.outcome} appended=${event.turnsAppended} ${event.durationMs}ms`\n    default: {\n      // Forward-compat — render unknown kinds as JSON so a future\n      // kernel version doesn't blank-line the log.\n      const _exhaustive: never = event\n      return JSON.stringify(_exhaustive)\n    }\n  }\n}\n","/**\n * OpenTelemetry adapter for the vendor-neutral Telemetry port.\n *\n * `otelTelemetry(tracer)` returns a `Telemetry` sink that maps the kernel's\n * `TelemetryEvent` stream onto OTel spans, grouping on `cycleId`:\n *\n *   cycle.started        → root span `agentproto.cycle` (held per cycleId)\n *   participant.started  → child span `agentproto.participant`\n *   participant.finished → end child span (durationMs, contentLength attrs)\n *   participant.failed   → recordException + ERROR status, then end\n *   substrate.read       → addEvent on the cycle span\n *   dispatch.decided     → addEvent on the cycle span\n *   cycle.finished/idle  → outcome attrs, end the cycle span, drop from map\n *   unknown kind         → ignored silently (forward-compat contract)\n *\n * This is a PURE MAPPER: the host supplies the `Tracer`. No global provider,\n * no exporter, no context propagation beyond parenting child spans under the\n * cycle span.\n */\n\nimport {\n  context,\n  SpanStatusCode,\n  trace,\n  type Span,\n  type Tracer,\n} from \"@opentelemetry/api\"\n\nimport type { Telemetry, TelemetryEvent } from \"./ports.js\"\n\nexport interface OtelTelemetryOptions {\n  /** Span name for the per-cycle root span. Default \"agentproto.cycle\". */\n  readonly cycleSpanName?: string\n  /** Span name for each participant child span. Default \"agentproto.participant\". */\n  readonly participantSpanName?: string\n}\n\n/**\n * Build a `Telemetry` sink that projects events onto OTel spans via the\n * host-supplied `tracer`.\n */\nexport function otelTelemetry(\n  tracer: Tracer,\n  options: OtelTelemetryOptions = {}\n): Telemetry {\n  const cycleSpanName = options.cycleSpanName ?? \"agentproto.cycle\"\n  const participantSpanName =\n    options.participantSpanName ?? \"agentproto.participant\"\n\n  const cycleSpans = new Map<string, Span>()\n  const participantSpans = new Map<string, Map<string, Span>>()\n\n  const startChild = (parent: Span, name: string): Span => {\n    const parentCtx = trace.setSpan(context.active(), parent)\n    return tracer.startSpan(name, undefined, parentCtx)\n  }\n\n  const dropParticipant = (cycleId: string, participantId: string): Span | undefined => {\n    const byParticipant = participantSpans.get(cycleId)\n    const span = byParticipant?.get(participantId)\n    if (byParticipant && span) {\n      byParticipant.delete(participantId)\n      if (byParticipant.size === 0) participantSpans.delete(cycleId)\n    }\n    return span\n  }\n\n  const endCycle = (event: Extract<TelemetryEvent, { kind: \"cycle.finished\" | \"cycle.idle\" }>): void => {\n    const span = cycleSpans.get(event.cycleId)\n    if (!span) return\n    if (event.kind === \"cycle.finished\") {\n      span.setAttribute(\"agentproto.cycle.outcome\", event.outcome)\n      span.setAttribute(\"agentproto.cycle.turnsAppended\", event.turnsAppended)\n      span.setAttribute(\"agentproto.cycle.durationMs\", event.durationMs)\n    } else {\n      span.setAttribute(\"agentproto.cycle.outcome\", \"idle\")\n    }\n    // Any participant spans still open are orphaned by an incomplete cycle;\n    // end them so the tracer isn't left with dangling spans.\n    const orphans = participantSpans.get(event.cycleId)\n    if (orphans) {\n      for (const child of orphans.values()) child.end()\n      participantSpans.delete(event.cycleId)\n    }\n    span.end()\n    cycleSpans.delete(event.cycleId)\n  }\n\n  return {\n    emit(event: TelemetryEvent): void {\n      switch (event.kind) {\n        case \"cycle.started\": {\n          const span = tracer.startSpan(cycleSpanName)\n          span.setAttribute(\"agentproto.cycleId\", event.cycleId)\n          if (event.since !== undefined) {\n            span.setAttribute(\"agentproto.cycle.since\", event.since)\n          }\n          cycleSpans.set(event.cycleId, span)\n          return\n        }\n        case \"participant.started\": {\n          const cycleSpan = cycleSpans.get(event.cycleId)\n          if (!cycleSpan) return\n          const span = startChild(cycleSpan, participantSpanName)\n          span.setAttribute(\"agentproto.participantId\", event.participantId)\n          span.setAttribute(\"agentproto.executorKind\", event.executorKind)\n          let byParticipant = participantSpans.get(event.cycleId)\n          if (!byParticipant) {\n            byParticipant = new Map<string, Span>()\n            participantSpans.set(event.cycleId, byParticipant)\n          }\n          byParticipant.set(event.participantId, span)\n          return\n        }\n        case \"participant.finished\": {\n          const span = dropParticipant(event.cycleId, event.participantId)\n          if (!span) return\n          span.setAttribute(\"agentproto.participant.durationMs\", event.durationMs)\n          span.setAttribute(\"agentproto.participant.contentLength\", event.contentLength)\n          span.end()\n          return\n        }\n        case \"participant.failed\": {\n          const span = dropParticipant(event.cycleId, event.participantId)\n          if (!span) return\n          span.recordException({ name: \"ParticipantExecuteError\", message: event.error })\n          span.setStatus({ code: SpanStatusCode.ERROR, message: event.error })\n          span.end()\n          return\n        }\n        case \"substrate.read\": {\n          const span = cycleSpans.get(event.cycleId)\n          span?.addEvent(\"substrate.read\", {\n            \"agentproto.substrateKind\": event.substrateKind,\n            \"agentproto.turnCount\": event.turnCount,\n            \"agentproto.durationMs\": event.durationMs,\n          })\n          return\n        }\n        case \"dispatch.decided\": {\n          const span = cycleSpans.get(event.cycleId)\n          span?.addEvent(\"dispatch.decided\", {\n            \"agentproto.dispatcherKind\": event.dispatcherKind,\n            \"agentproto.selected\": event.selected.join(\",\"),\n            \"agentproto.durationMs\": event.durationMs,\n          })\n          return\n        }\n        case \"substrate.appended\": {\n          const span = cycleSpans.get(event.cycleId)\n          span?.addEvent(\"substrate.appended\", {\n            \"agentproto.turnId\": event.turnId,\n            \"agentproto.participantId\": event.participantId,\n          })\n          return\n        }\n        case \"state.written\": {\n          const span = cycleSpans.get(event.cycleId)\n          span?.addEvent(\"state.written\", {\n            \"agentproto.participantId\": event.participantId,\n          })\n          return\n        }\n        case \"cycle.finished\":\n        case \"cycle.idle\": {\n          endCycle(event)\n          return\n        }\n        default: {\n          // Unknown kind — forward-compat contract: ignore silently.\n          return\n        }\n      }\n    },\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@agentproto/telemetry",
+  "version": "0.2.0",
+  "description": "agentproto/telemetry — vendor-neutral Telemetry port + reference sinks (noop, stderr, array, compose) and an OpenTelemetry adapter that maps the kernel's TelemetryEvent stream to OTel spans grouped on cycleId. The adapter takes a host-supplied Tracer; no global provider or exporter wiring.",
+  "keywords": [
+    "agentproto",
+    "telemetry",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "spans",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentik.net/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}