@nagi-js/otel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lymo, Inc.
+
+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/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { FlowHooks, StepCtx } from '@nagi-js/core';
+import { Span, Tracer, Attributes } from '@opentelemetry/api';
+
+/**
+ * Fan out a single `FlowHooks` call site to multiple subscribers, awaiting each in
+ * declaration order. A throw from one subscriber is logged via `console.error` and
+ * does NOT prevent later subscribers (or the workflow runtime) from running.
+ *
+ * Nagi's runtime accepts a single `hooks` value — this is how users wire
+ * `otelHooks()` alongside their own logger / metrics hooks.
+ */
+declare function composeHooks(...hooks: readonly FlowHooks[]): FlowHooks;
+
+/**
+ * Returns the OTel `Span` tracking the current step attempt, or `undefined` when
+ * no `otelHooks()` is wired or the step is not in-flight (e.g. running under a
+ * different `nagi()` instance, or after the step has completed).
+ *
+ * Useful inside user handlers to add custom attributes or open child spans:
+ *
+ * ```ts
+ * b.task({
+ *   run: async (ctx) => {
+ *     const span = getStepSpan(ctx);
+ *     span?.setAttribute("my.custom.attr", 42);
+ *     ...
+ *   },
+ * });
+ * ```
+ *
+ * Note: this span is NOT installed as the active context — `trace.getActiveSpan()`
+ * inside the handler returns the caller's context, not this span.
+ */
+declare function getStepSpan(ctx: Pick<StepCtx<unknown>, "runId" | "stepId" | "attempt">): Span | undefined;
+
+interface OtelHooksOpts {
+    /**
+     * Custom `Tracer`. Defaults to `trace.getTracer("@nagi-js/otel", "0.0.0")` —
+     * a no-op when no SDK is registered (per the OTel API contract).
+     */
+    readonly tracer?: Tracer;
+    /** Override `"flow"`/`"step"` span-name prefixes (low cardinality; do NOT use IDs). */
+    readonly spanNamePrefix?: {
+        readonly flow?: string;
+        readonly step?: string;
+    };
+    /** Extra attributes stamped on every span (e.g. `deployment.environment`). */
+    readonly defaultAttributes?: Attributes;
+}
+/**
+ * `FlowHooks` adapter that maps Nagi lifecycle events to OpenTelemetry spans.
+ *
+ * Hierarchy: one `flow {flowId}` span per run; per-step-attempt sibling `step
+ * {stepId}` spans underneath. All spans are `INTERNAL` kind. Errors call
+ * `span.recordException` + `setStatus(ERROR)`; success leaves status `UNSET`
+ * per the Tracing API spec recommendation for instrumentation libraries.
+ *
+ * Adapter errors are swallowed: a misconfigured tracer must never crash a
+ * workflow. Throws are logged via `console.error`.
+ */
+declare function otelHooks(opts?: OtelHooksOpts): FlowHooks;
+
+export { type OtelHooksOpts, composeHooks, getStepSpan, otelHooks };

package/dist/index.js

@@ -0,0 +1,203 @@
+import { trace, SpanKind, context, SpanStatusCode } from '@opentelemetry/api';
+
+// src/compose.ts
+function composeHooks(...hooks) {
+  const result = {};
+  const fs = pick(hooks, "onFlowStart");
+  if (fs.length > 0) result.onFlowStart = fanout("onFlowStart", fs);
+  const fc = pick(hooks, "onFlowComplete");
+  if (fc.length > 0) result.onFlowComplete = fanout("onFlowComplete", fc);
+  const fe = pick(hooks, "onFlowError");
+  if (fe.length > 0) result.onFlowError = fanout("onFlowError", fe);
+  const ss = pick(hooks, "onStepStart");
+  if (ss.length > 0) result.onStepStart = fanout("onStepStart", ss);
+  const sc = pick(hooks, "onStepComplete");
+  if (sc.length > 0) result.onStepComplete = fanout("onStepComplete", sc);
+  const se = pick(hooks, "onStepError");
+  if (se.length > 0) result.onStepError = fanout("onStepError", se);
+  const sr = pick(hooks, "onStepRetry");
+  if (sr.length > 0) result.onStepRetry = fanout("onStepRetry", sr);
+  const sigS = pick(hooks, "onSignalSent");
+  if (sigS.length > 0) result.onSignalSent = fanout("onSignalSent", sigS);
+  const sigR = pick(hooks, "onSignalReceived");
+  if (sigR.length > 0)
+    result.onSignalReceived = fanout("onSignalReceived", sigR);
+  return result;
+}
+function pick(hooks, name) {
+  const out = [];
+  for (const h of hooks) {
+    const fn = h[name];
+    if (fn !== void 0) out.push(fn);
+  }
+  return out;
+}
+function fanout(name, subs) {
+  return async (event) => {
+    for (const fn of subs) {
+      try {
+        await fn(event);
+      } catch (err) {
+        console.error(
+          `[@nagi-js/otel] composeHooks: ${name} subscriber threw`,
+          err
+        );
+      }
+    }
+  };
+}
+
+// src/context.ts
+var SEP = "";
+function stepKey(runId, stepId, attempt) {
+  return `${runId}${SEP}${stepId}${SEP}${attempt}`;
+}
+var stepSpanRegistry = /* @__PURE__ */ new Map();
+function getStepSpan(ctx) {
+  return stepSpanRegistry.get(stepKey(ctx.runId, ctx.stepId, ctx.attempt));
+}
+var TRACER_NAME = "@nagi-js/otel";
+var TRACER_VERSION = "0.0.0";
+var DEFAULT_FLOW_PREFIX = "flow";
+var DEFAULT_STEP_PREFIX = "step";
+function otelHooks(opts = {}) {
+  const tracer = opts.tracer ?? trace.getTracer(TRACER_NAME, TRACER_VERSION);
+  const flowPrefix = opts.spanNamePrefix?.flow ?? DEFAULT_FLOW_PREFIX;
+  const stepPrefix = opts.spanNamePrefix?.step ?? DEFAULT_STEP_PREFIX;
+  const baseAttrs = opts.defaultAttributes ?? {};
+  const flowCtxs = /* @__PURE__ */ new Map();
+  const stepStartTimes = /* @__PURE__ */ new Map();
+  function withGuard(name, fn) {
+    return (event) => {
+      try {
+        fn(event);
+      } catch (err) {
+        console.error(`[@nagi-js/otel] ${name} hook failed`, err);
+      }
+    };
+  }
+  function flowAttrs(event) {
+    return {
+      ...baseAttrs,
+      "nagi.flow.id": event.flowId,
+      "nagi.run.id": event.runId
+    };
+  }
+  function stepAttrs(event) {
+    return {
+      ...flowAttrs(event),
+      "nagi.step.id": event.stepId,
+      "nagi.step.attempt": event.attempt,
+      "nagi.step.kind": event.kind
+    };
+  }
+  function startStepSpan(event) {
+    const parentCtx = flowCtxs.get(event.runId) ?? context.active();
+    return tracer.startSpan(
+      `${stepPrefix} ${event.stepId}`,
+      {
+        kind: SpanKind.INTERNAL,
+        startTime: event.at,
+        attributes: stepAttrs(event)
+      },
+      parentCtx
+    );
+  }
+  function endStepSpanOk(event, span) {
+    const k = stepKey(event.runId, event.stepId, event.attempt);
+    const startedAt = stepStartTimes.get(k);
+    const durationMs = event.kind === "match" && startedAt ? event.at.getTime() - startedAt.getTime() : event.durationMs;
+    span.setAttribute("nagi.step.duration_ms", durationMs);
+    span.end(event.at);
+  }
+  function endStepSpanErr(span, error, endAt) {
+    span.recordException(toError(error));
+    span.setAttribute("error.type", error.name);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+    span.end(endAt);
+  }
+  function consumeStepSpan(runId, stepId, attempt) {
+    const k = stepKey(runId, stepId, attempt);
+    const span = stepSpanRegistry.get(k);
+    stepSpanRegistry.delete(k);
+    stepStartTimes.delete(k);
+    return span;
+  }
+  return {
+    onFlowStart: withGuard("onFlowStart", (event) => {
+      const span = tracer.startSpan(`${flowPrefix} ${event.flowId}`, {
+        kind: SpanKind.INTERNAL,
+        startTime: event.at,
+        attributes: flowAttrs(event)
+      });
+      flowCtxs.set(event.runId, trace.setSpan(context.active(), span));
+    }),
+    onFlowComplete: withGuard("onFlowComplete", (event) => {
+      const ctx = flowCtxs.get(event.runId);
+      flowCtxs.delete(event.runId);
+      const span = ctx ? trace.getSpan(ctx) : void 0;
+      span?.end(event.at);
+    }),
+    onFlowError: withGuard("onFlowError", (event) => {
+      const ctx = flowCtxs.get(event.runId);
+      flowCtxs.delete(event.runId);
+      const span = ctx ? trace.getSpan(ctx) : void 0;
+      if (span) endStepSpanErr(span, event.error, event.at);
+    }),
+    onStepStart: withGuard("onStepStart", (event) => {
+      const span = startStepSpan(event);
+      const k = stepKey(event.runId, event.stepId, event.attempt);
+      stepSpanRegistry.set(k, span);
+      stepStartTimes.set(k, event.at);
+    }),
+    onStepComplete: withGuard("onStepComplete", (event) => {
+      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);
+      if (span) endStepSpanOk(event, span);
+    }),
+    onStepError: withGuard("onStepError", (event) => {
+      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);
+      if (span) endStepSpanErr(span, event.error, event.at);
+    }),
+    onStepRetry: withGuard("onStepRetry", (event) => {
+      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);
+      if (span) endStepSpanErr(span, event.error, event.at);
+      const flowCtx = flowCtxs.get(event.runId);
+      const flowSpan = flowCtx ? trace.getSpan(flowCtx) : void 0;
+      flowSpan?.addEvent(
+        "nagi.retry.scheduled",
+        {
+          "nagi.step.id": event.stepId,
+          "nagi.step.attempt": event.attempt,
+          "nagi.next_attempt_at": event.nextAttemptAt.toISOString()
+        },
+        event.at
+      );
+    }),
+    // onSignalSent is declared in core/types.ts but never fired by the runtime;
+    // intentionally omitted until core wires a sender path.
+    onSignalReceived: withGuard(
+      "onSignalReceived",
+      (event) => {
+        const span = consumeStepSpan(event.runId, event.stepId, event.attempt);
+        if (!span) return;
+        span.addEvent(
+          "nagi.signal.received",
+          { "nagi.signal.payload_present": event.payload !== null },
+          event.at
+        );
+        span.setAttribute("nagi.step.duration_ms", 0);
+        span.end(event.at);
+      }
+    )
+  };
+}
+function toError(err) {
+  const e = new Error(err.message);
+  e.name = err.name;
+  if (err.stack !== void 0) e.stack = err.stack;
+  return e;
+}
+
+export { composeHooks, getStepSpan, otelHooks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compose.ts","../src/context.ts","../src/hooks.ts"],"names":[],"mappings":";;;AAqBO,SAAS,gBAAgB,KAAA,EAAwC;AAGtE,EAAA,MAAM,SAUF,EAAC;AAEL,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,aAAa,CAAA;AACpC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,WAAA,GAAc,MAAA,CAAO,eAAe,EAAE,CAAA;AAEhE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,gBAAgB,CAAA;AACvC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,cAAA,GAAiB,MAAA,CAAO,kBAAkB,EAAE,CAAA;AAEtE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,aAAa,CAAA;AACpC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,WAAA,GAAc,MAAA,CAAO,eAAe,EAAE,CAAA;AAEhE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,aAAa,CAAA;AACpC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,WAAA,GAAc,MAAA,CAAO,eAAe,EAAE,CAAA;AAEhE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,gBAAgB,CAAA;AACvC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,cAAA,GAAiB,MAAA,CAAO,kBAAkB,EAAE,CAAA;AAEtE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,aAAa,CAAA;AACpC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,WAAA,GAAc,MAAA,CAAO,eAAe,EAAE,CAAA;AAEhE,EAAA,MAAM,EAAA,GAAK,IAAA,CAAK,KAAA,EAAO,aAAa,CAAA;AACpC,EAAA,IAAI,GAAG,MAAA,GAAS,CAAA,SAAU,WAAA,GAAc,MAAA,CAAO,eAAe,EAAE,CAAA;AAEhE,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,EAAO,cAAc,CAAA;AACvC,EAAA,IAAI,KAAK,MAAA,GAAS,CAAA,SAAU,YAAA,GAAe,MAAA,CAAO,gBAAgB,IAAI,CAAA;AAEtE,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,EAAO,kBAAkB,CAAA;AAC3C,EAAA,IAAI,KAAK,MAAA,GAAS,CAAA;AAChB,IAAA,MAAA,CAAO,gBAAA,GAAmB,MAAA,CAAO,kBAAA,EAAoB,IAAI,CAAA;AAE3D,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,IAAA,CACP,OACA,IAAA,EACkC;AAClC,EAAA,MAAM,MAAwC,EAAC;AAC/C,EAAA,KAAA,MAAW,KAAK,KAAA,EAAO;AACrB,IAAA,MAAM,EAAA,GAAK,EAAE,IAAI,CAAA;AACjB,IAAA,IAAI,EAAA,KAAO,MAAA,EAAW,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA;AAAA,EACnC;AACA,EAAA,OAAO,GAAA;AACT;AAEA,SAAS,MAAA,CACP,MACA,IAAA,EAC6B;AAC7B,EAAA,OAAO,OAAO,KAAA,KAAa;AACzB,IAAA,KAAA,MAAW,MAAM,IAAA,EAAM;AACrB,MAAA,IAAI;AACF,QAAA,MAAM,GAAG,KAAK,CAAA;AAAA,MAChB,SAAS,GAAA,EAAK;AACZ,QAAA,OAAA,CAAQ,KAAA;AAAA,UACN,iCAAiC,IAAI,CAAA,iBAAA,CAAA;AAAA,UACrC;AAAA,SACF;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAA;AACF;;;ACvFA,IAAM,GAAA,GAAM,GAAA;AAEL,SAAS,OAAA,CACd,KAAA,EACA,MAAA,EACA,OAAA,EACQ;AACR,EAAA,OAAO,CAAA,EAAG,KAAK,CAAA,EAAG,GAAG,GAAG,MAAM,CAAA,EAAG,GAAG,CAAA,EAAG,OAAO,CAAA,CAAA;AAChD;AAUO,IAAM,gBAAA,uBAAuB,GAAA,EAAkB;AAsB/C,SAAS,YACd,GAAA,EACkB;AAClB,EAAA,OAAO,gBAAA,CAAiB,IAAI,OAAA,CAAQ,GAAA,CAAI,OAAO,GAAA,CAAI,MAAA,EAAQ,GAAA,CAAI,OAAO,CAAC,CAAA;AACzE;ACxBA,IAAM,WAAA,GAAc,eAAA;AACpB,IAAM,cAAA,GAAiB,OAAA;AAEvB,IAAM,mBAAA,GAAsB,MAAA;AAC5B,IAAM,mBAAA,GAAsB,MAAA;AAyBrB,SAAS,SAAA,CAAU,IAAA,GAAsB,EAAC,EAAc;AAC7D,EAAA,MAAM,SACJ,IAAA,CAAK,MAAA,IAAU,KAAA,CAAM,SAAA,CAAU,aAAa,cAAc,CAAA;AAC5D,EAAA,MAAM,UAAA,GAAa,IAAA,CAAK,cAAA,EAAgB,IAAA,IAAQ,mBAAA;AAChD,EAAA,MAAM,UAAA,GAAa,IAAA,CAAK,cAAA,EAAgB,IAAA,IAAQ,mBAAA;AAChD,EAAA,MAAM,SAAA,GAAwB,IAAA,CAAK,iBAAA,IAAqB,EAAC;AAGzD,EAAA,MAAM,QAAA,uBAAe,GAAA,EAAoB;AAGzC,EAAA,MAAM,cAAA,uBAAqB,GAAA,EAAkB;AAE7C,EAAA,SAAS,SAAA,CACP,MACA,EAAA,EACoB;AACpB,IAAA,OAAO,CAAC,KAAA,KAAa;AACnB,MAAA,IAAI;AACF,QAAA,EAAA,CAAG,KAAK,CAAA;AAAA,MACV,SAAS,GAAA,EAAK;AACZ,QAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,gBAAA,EAAmB,IAAI,CAAA,YAAA,CAAA,EAAgB,GAAG,CAAA;AAAA,MAC1D;AAAA,IACF,CAAA;AAAA,EACF;AAEA,EAAA,SAAS,UAAU,KAAA,EAGJ;AACb,IAAA,OAAO;AAAA,MACL,GAAG,SAAA;AAAA,MACH,gBAAgB,KAAA,CAAM,MAAA;AAAA,MACtB,eAAe,KAAA,CAAM;AAAA,KACvB;AAAA,EACF;AAEA,EAAA,SAAS,UAAU,KAAA,EAA8B;AAC/C,IAAA,OAAO;AAAA,MACL,GAAG,UAAU,KAAK,CAAA;AAAA,MAClB,gBAAgB,KAAA,CAAM,MAAA;AAAA,MACtB,qBAAqB,KAAA,CAAM,OAAA;AAAA,MAC3B,kBAAkB,KAAA,CAAM;AAAA,KAC1B;AAAA,EACF;AAEA,EAAA,SAAS,cAAc,KAAA,EAA6B;AAClD,IAAA,MAAM,YAAY,QAAA,CAAS,GAAA,CAAI,MAAM,KAAK,CAAA,IAAK,QAAQ,MAAA,EAAO;AAC9D,IAAA,OAAO,MAAA,CAAO,SAAA;AAAA,MACZ,CAAA,EAAG,UAAU,CAAA,CAAA,EAAI,KAAA,CAAM,MAAM,CAAA,CAAA;AAAA,MAC7B;AAAA,QACE,MAAM,QAAA,CAAS,QAAA;AAAA,QACf,WAAW,KAAA,CAAM,EAAA;AAAA,QACjB,UAAA,EAAY,UAAU,KAAK;AAAA,OAC7B;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAEA,EAAA,SAAS,aAAA,CAAc,OAA0B,IAAA,EAAkB;AACjE,IAAA,MAAM,IAAI,OAAA,CAAQ,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AAC1D,IAAA,MAAM,SAAA,GAAY,cAAA,CAAe,GAAA,CAAI,CAAC,CAAA;AAGtC,IAAA,MAAM,UAAA,GACJ,KAAA,CAAM,IAAA,KAAS,OAAA,IAAW,SAAA,GACtB,KAAA,CAAM,EAAA,CAAG,OAAA,EAAQ,GAAI,SAAA,CAAU,OAAA,EAAQ,GACvC,KAAA,CAAM,UAAA;AACZ,IAAA,IAAA,CAAK,YAAA,CAAa,yBAAyB,UAAU,CAAA;AACrD,IAAA,IAAA,CAAK,GAAA,CAAI,MAAM,EAAE,CAAA;AAAA,EACnB;AAEA,EAAA,SAAS,cAAA,CACP,IAAA,EACA,KAAA,EACA,KAAA,EACM;AACN,IAAA,IAAA,CAAK,eAAA,CAAgB,OAAA,CAAQ,KAAK,CAAC,CAAA;AACnC,IAAA,IAAA,CAAK,YAAA,CAAa,YAAA,EAAc,KAAA,CAAM,IAAI,CAAA;AAC1C,IAAA,IAAA,CAAK,SAAA,CAAU,EAAE,IAAA,EAAM,cAAA,CAAe,OAAO,OAAA,EAAS,KAAA,CAAM,SAAS,CAAA;AACrE,IAAA,IAAA,CAAK,IAAI,KAAK,CAAA;AAAA,EAChB;AAEA,EAAA,SAAS,eAAA,CACP,KAAA,EACA,MAAA,EACA,OAAA,EACkB;AAClB,IAAA,MAAM,CAAA,GAAI,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,OAAO,CAAA;AACxC,IAAA,MAAM,IAAA,GAAO,gBAAA,CAAiB,GAAA,CAAI,CAAC,CAAA;AACnC,IAAA,gBAAA,CAAiB,OAAO,CAAC,CAAA;AACzB,IAAA,cAAA,CAAe,OAAO,CAAC,CAAA;AACvB,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,OAAO;AAAA,IACL,WAAA,EAAa,SAAA,CAA0B,aAAA,EAAe,CAAC,KAAA,KAAU;AAC/D,MAAA,MAAM,IAAA,GAAO,OAAO,SAAA,CAAU,CAAA,EAAG,UAAU,CAAA,CAAA,EAAI,KAAA,CAAM,MAAM,CAAA,CAAA,EAAI;AAAA,QAC7D,MAAM,QAAA,CAAS,QAAA;AAAA,QACf,WAAW,KAAA,CAAM,EAAA;AAAA,QACjB,UAAA,EAAY,UAAU,KAAK;AAAA,OAC5B,CAAA;AACD,MAAA,QAAA,CAAS,GAAA,CAAI,MAAM,KAAA,EAAO,KAAA,CAAM,QAAQ,OAAA,CAAQ,MAAA,EAAO,EAAG,IAAI,CAAC,CAAA;AAAA,IACjE,CAAC,CAAA;AAAA,IAED,cAAA,EAAgB,SAAA,CAA6B,gBAAA,EAAkB,CAAC,KAAA,KAAU;AACxE,MAAA,MAAM,GAAA,GAAM,QAAA,CAAS,GAAA,CAAI,KAAA,CAAM,KAAK,CAAA;AACpC,MAAA,QAAA,CAAS,MAAA,CAAO,MAAM,KAAK,CAAA;AAC3B,MAAA,MAAM,IAAA,GAAO,GAAA,GAAM,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA,GAAI,KAAA,CAAA;AACxC,MAAA,IAAA,EAAM,GAAA,CAAI,MAAM,EAAE,CAAA;AAAA,IACpB,CAAC,CAAA;AAAA,IAED,WAAA,EAAa,SAAA,CAA0B,aAAA,EAAe,CAAC,KAAA,KAAU;AAC/D,MAAA,MAAM,GAAA,GAAM,QAAA,CAAS,GAAA,CAAI,KAAA,CAAM,KAAK,CAAA;AACpC,MAAA,QAAA,CAAS,MAAA,CAAO,MAAM,KAAK,CAAA;AAC3B,MAAA,MAAM,IAAA,GAAO,GAAA,GAAM,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA,GAAI,KAAA,CAAA;AACxC,MAAA,IAAI,MAAM,cAAA,CAAe,IAAA,EAAM,KAAA,CAAM,KAAA,EAAO,MAAM,EAAE,CAAA;AAAA,IACtD,CAAC,CAAA;AAAA,IAED,WAAA,EAAa,SAAA,CAA0B,aAAA,EAAe,CAAC,KAAA,KAAU;AAC/D,MAAA,MAAM,IAAA,GAAO,cAAc,KAAK,CAAA;AAChC,MAAA,MAAM,IAAI,OAAA,CAAQ,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AAC1D,MAAA,gBAAA,CAAiB,GAAA,CAAI,GAAG,IAAI,CAAA;AAC5B,MAAA,cAAA,CAAe,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,EAAE,CAAA;AAAA,IAChC,CAAC,CAAA;AAAA,IAED,cAAA,EAAgB,SAAA,CAA6B,gBAAA,EAAkB,CAAC,KAAA,KAAU;AACxE,MAAA,MAAM,OAAO,eAAA,CAAgB,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AACrE,MAAA,IAAI,IAAA,EAAM,aAAA,CAAc,KAAA,EAAO,IAAI,CAAA;AAAA,IACrC,CAAC,CAAA;AAAA,IAED,WAAA,EAAa,SAAA,CAA0B,aAAA,EAAe,CAAC,KAAA,KAAU;AAC/D,MAAA,MAAM,OAAO,eAAA,CAAgB,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AACrE,MAAA,IAAI,MAAM,cAAA,CAAe,IAAA,EAAM,KAAA,CAAM,KAAA,EAAO,MAAM,EAAE,CAAA;AAAA,IACtD,CAAC,CAAA;AAAA,IAED,WAAA,EAAa,SAAA,CAA0B,aAAA,EAAe,CAAC,KAAA,KAAU;AAG/D,MAAA,MAAM,OAAO,eAAA,CAAgB,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AACrE,MAAA,IAAI,MAAM,cAAA,CAAe,IAAA,EAAM,KAAA,CAAM,KAAA,EAAO,MAAM,EAAE,CAAA;AAIpD,MAAA,MAAM,OAAA,GAAU,QAAA,CAAS,GAAA,CAAI,KAAA,CAAM,KAAK,CAAA;AACxC,MAAA,MAAM,QAAA,GAAW,OAAA,GAAU,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA,GAAI,KAAA,CAAA;AACpD,MAAA,QAAA,EAAU,QAAA;AAAA,QACR,sBAAA;AAAA,QACA;AAAA,UACE,gBAAgB,KAAA,CAAM,MAAA;AAAA,UACtB,qBAAqB,KAAA,CAAM,OAAA;AAAA,UAC3B,sBAAA,EAAwB,KAAA,CAAM,aAAA,CAAc,WAAA;AAAY,SAC1D;AAAA,QACA,KAAA,CAAM;AAAA,OACR;AAAA,IACF,CAAC,CAAA;AAAA;AAAA;AAAA,IAID,gBAAA,EAAkB,SAAA;AAAA,MAChB,kBAAA;AAAA,MACA,CAAC,KAAA,KAAU;AACT,QAAA,MAAM,OAAO,eAAA,CAAgB,KAAA,CAAM,OAAO,KAAA,CAAM,MAAA,EAAQ,MAAM,OAAO,CAAA;AACrE,QAAA,IAAI,CAAC,IAAA,EAAM;AACX,QAAA,IAAA,CAAK,QAAA;AAAA,UACH,sBAAA;AAAA,UACA,EAAE,6BAAA,EAA+B,KAAA,CAAM,OAAA,KAAY,IAAA,EAAK;AAAA,UACxD,KAAA,CAAM;AAAA,SACR;AACA,QAAA,IAAA,CAAK,YAAA,CAAa,yBAAyB,CAAC,CAAA;AAC5C,QAAA,IAAA,CAAK,GAAA,CAAI,MAAM,EAAE,CAAA;AAAA,MACnB;AAAA;AACF,GACF;AACF;AAEA,SAAS,QAAQ,GAAA,EAA6B;AAI5C,EAAA,MAAM,CAAA,GAAI,IAAI,KAAA,CAAM,GAAA,CAAI,OAAO,CAAA;AAC/B,EAAA,CAAA,CAAE,OAAO,GAAA,CAAI,IAAA;AACb,EAAA,IAAI,GAAA,CAAI,KAAA,KAAU,MAAA,EAAW,CAAA,CAAE,QAAQ,GAAA,CAAI,KAAA;AAC3C,EAAA,OAAO,CAAA;AACT","file":"index.js","sourcesContent":["import type {\n  FlowCompleteEvent,\n  FlowErrorEvent,\n  FlowHooks,\n  FlowStartEvent,\n  SignalReceivedEvent,\n  SignalSentEvent,\n  StepCompleteEvent,\n  StepErrorEvent,\n  StepRetryEvent,\n  StepStartEvent,\n} from \"@nagi-js/core\";\n\n/**\n * Fan out a single `FlowHooks` call site to multiple subscribers, awaiting each in\n * declaration order. A throw from one subscriber is logged via `console.error` and\n * does NOT prevent later subscribers (or the workflow runtime) from running.\n *\n * Nagi's runtime accepts a single `hooks` value — this is how users wire\n * `otelHooks()` alongside their own logger / metrics hooks.\n */\nexport function composeHooks(...hooks: readonly FlowHooks[]): FlowHooks {\n  // Build a local FlowHooks-shaped object. Optional fields are only set when at\n  // least one subscriber provides them — required by `exactOptionalPropertyTypes`.\n  const result: {\n    onFlowStart?: (event: FlowStartEvent) => Promise<void>;\n    onFlowComplete?: (event: FlowCompleteEvent) => Promise<void>;\n    onFlowError?: (event: FlowErrorEvent) => Promise<void>;\n    onStepStart?: (event: StepStartEvent) => Promise<void>;\n    onStepComplete?: (event: StepCompleteEvent) => Promise<void>;\n    onStepError?: (event: StepErrorEvent) => Promise<void>;\n    onStepRetry?: (event: StepRetryEvent) => Promise<void>;\n    onSignalSent?: (event: SignalSentEvent) => Promise<void>;\n    onSignalReceived?: (event: SignalReceivedEvent) => Promise<void>;\n  } = {};\n\n  const fs = pick(hooks, \"onFlowStart\");\n  if (fs.length > 0) result.onFlowStart = fanout(\"onFlowStart\", fs);\n\n  const fc = pick(hooks, \"onFlowComplete\");\n  if (fc.length > 0) result.onFlowComplete = fanout(\"onFlowComplete\", fc);\n\n  const fe = pick(hooks, \"onFlowError\");\n  if (fe.length > 0) result.onFlowError = fanout(\"onFlowError\", fe);\n\n  const ss = pick(hooks, \"onStepStart\");\n  if (ss.length > 0) result.onStepStart = fanout(\"onStepStart\", ss);\n\n  const sc = pick(hooks, \"onStepComplete\");\n  if (sc.length > 0) result.onStepComplete = fanout(\"onStepComplete\", sc);\n\n  const se = pick(hooks, \"onStepError\");\n  if (se.length > 0) result.onStepError = fanout(\"onStepError\", se);\n\n  const sr = pick(hooks, \"onStepRetry\");\n  if (sr.length > 0) result.onStepRetry = fanout(\"onStepRetry\", sr);\n\n  const sigS = pick(hooks, \"onSignalSent\");\n  if (sigS.length > 0) result.onSignalSent = fanout(\"onSignalSent\", sigS);\n\n  const sigR = pick(hooks, \"onSignalReceived\");\n  if (sigR.length > 0)\n    result.onSignalReceived = fanout(\"onSignalReceived\", sigR);\n\n  return result;\n}\n\nfunction pick<K extends keyof FlowHooks>(\n  hooks: readonly FlowHooks[],\n  name: K,\n): Array<NonNullable<FlowHooks[K]>> {\n  const out: Array<NonNullable<FlowHooks[K]>> = [];\n  for (const h of hooks) {\n    const fn = h[name];\n    if (fn !== undefined) out.push(fn);\n  }\n  return out;\n}\n\nfunction fanout<E>(\n  name: string,\n  subs: ReadonlyArray<(event: E) => void | Promise<void>>,\n): (event: E) => Promise<void> {\n  return async (event: E) => {\n    for (const fn of subs) {\n      try {\n        await fn(event);\n      } catch (err) {\n        console.error(\n          `[@nagi-js/otel] composeHooks: ${name} subscriber threw`,\n          err,\n        );\n      }\n    }\n  };\n}\n","import type { AttemptNumber, RunId, StepCtx, StepId } from \"@nagi-js/core\";\nimport type { Span } from \"@opentelemetry/api\";\n\n/**\n * ASCII unit separator. Composite-key delimiter for `(runId, stepId, attempt)`.\n * Unambiguous because `runId` is `run-<uuid>` and `stepId` is a dotted identifier;\n * neither contains control chars.\n */\nconst SEP = \"\\x1f\";\n\nexport function stepKey(\n  runId: RunId,\n  stepId: StepId,\n  attempt: AttemptNumber,\n): string {\n  return `${runId}${SEP}${stepId}${SEP}${attempt}`;\n}\n\n/**\n * Process-global registry of in-flight step spans, keyed by `(runId, stepId, attempt)`.\n * Populated by `otelHooks()` on `onStepStart`; cleared on completion / error / retry.\n *\n * Single-process, single-runtime: Nagi already assumes a runtime per process, so a\n * module-level Map is the right granularity. Bounded by steps-in-flight, which the\n * runtime itself bounds.\n */\nexport const stepSpanRegistry = new Map<string, Span>();\n\n/**\n * Returns the OTel `Span` tracking the current step attempt, or `undefined` when\n * no `otelHooks()` is wired or the step is not in-flight (e.g. running under a\n * different `nagi()` instance, or after the step has completed).\n *\n * Useful inside user handlers to add custom attributes or open child spans:\n *\n * ```ts\n * b.task({\n *   run: async (ctx) => {\n *     const span = getStepSpan(ctx);\n *     span?.setAttribute(\"my.custom.attr\", 42);\n *     ...\n *   },\n * });\n * ```\n *\n * Note: this span is NOT installed as the active context — `trace.getActiveSpan()`\n * inside the handler returns the caller's context, not this span.\n */\nexport function getStepSpan(\n  ctx: Pick<StepCtx<unknown>, \"runId\" | \"stepId\" | \"attempt\">,\n): Span | undefined {\n  return stepSpanRegistry.get(stepKey(ctx.runId, ctx.stepId, ctx.attempt));\n}\n","import type {\n  AttemptNumber,\n  FlowCompleteEvent,\n  FlowErrorEvent,\n  FlowHooks,\n  FlowStartEvent,\n  RunId,\n  SerializedError,\n  SignalReceivedEvent,\n  StepCompleteEvent,\n  StepErrorEvent,\n  StepEvent,\n  StepId,\n  StepRetryEvent,\n  StepStartEvent,\n} from \"@nagi-js/core\";\nimport {\n  type Attributes,\n  type Context,\n  context,\n  type Span,\n  SpanKind,\n  SpanStatusCode,\n  type Tracer,\n  trace,\n} from \"@opentelemetry/api\";\nimport { stepKey, stepSpanRegistry } from \"./context\";\n\nconst TRACER_NAME = \"@nagi-js/otel\";\nconst TRACER_VERSION = \"0.0.0\";\n\nconst DEFAULT_FLOW_PREFIX = \"flow\";\nconst DEFAULT_STEP_PREFIX = \"step\";\n\nexport interface OtelHooksOpts {\n  /**\n   * Custom `Tracer`. Defaults to `trace.getTracer(\"@nagi-js/otel\", \"0.0.0\")` —\n   * a no-op when no SDK is registered (per the OTel API contract).\n   */\n  readonly tracer?: Tracer;\n  /** Override `\"flow\"`/`\"step\"` span-name prefixes (low cardinality; do NOT use IDs). */\n  readonly spanNamePrefix?: { readonly flow?: string; readonly step?: string };\n  /** Extra attributes stamped on every span (e.g. `deployment.environment`). */\n  readonly defaultAttributes?: Attributes;\n}\n\n/**\n * `FlowHooks` adapter that maps Nagi lifecycle events to OpenTelemetry spans.\n *\n * Hierarchy: one `flow {flowId}` span per run; per-step-attempt sibling `step\n * {stepId}` spans underneath. All spans are `INTERNAL` kind. Errors call\n * `span.recordException` + `setStatus(ERROR)`; success leaves status `UNSET`\n * per the Tracing API spec recommendation for instrumentation libraries.\n *\n * Adapter errors are swallowed: a misconfigured tracer must never crash a\n * workflow. Throws are logged via `console.error`.\n */\nexport function otelHooks(opts: OtelHooksOpts = {}): FlowHooks {\n  const tracer: Tracer =\n    opts.tracer ?? trace.getTracer(TRACER_NAME, TRACER_VERSION);\n  const flowPrefix = opts.spanNamePrefix?.flow ?? DEFAULT_FLOW_PREFIX;\n  const stepPrefix = opts.spanNamePrefix?.step ?? DEFAULT_STEP_PREFIX;\n  const baseAttrs: Attributes = opts.defaultAttributes ?? {};\n\n  // Per-run flow-span context. Used as the parent for step spans.\n  const flowCtxs = new Map<RunId, Context>();\n  // Per-step match-duration tracking: dispatch.ts hard-codes durationMs=0 on\n  // match completion, so we compute it ourselves from the stashed start time.\n  const stepStartTimes = new Map<string, Date>();\n\n  function withGuard<E>(\n    name: string,\n    fn: (event: E) => void,\n  ): (event: E) => void {\n    return (event: E) => {\n      try {\n        fn(event);\n      } catch (err) {\n        console.error(`[@nagi-js/otel] ${name} hook failed`, err);\n      }\n    };\n  }\n\n  function flowAttrs(event: {\n    readonly runId: RunId;\n    readonly flowId: string;\n  }): Attributes {\n    return {\n      ...baseAttrs,\n      \"nagi.flow.id\": event.flowId,\n      \"nagi.run.id\": event.runId,\n    };\n  }\n\n  function stepAttrs(event: StepEvent): Attributes {\n    return {\n      ...flowAttrs(event),\n      \"nagi.step.id\": event.stepId,\n      \"nagi.step.attempt\": event.attempt,\n      \"nagi.step.kind\": event.kind,\n    };\n  }\n\n  function startStepSpan(event: StepStartEvent): Span {\n    const parentCtx = flowCtxs.get(event.runId) ?? context.active();\n    return tracer.startSpan(\n      `${stepPrefix} ${event.stepId}`,\n      {\n        kind: SpanKind.INTERNAL,\n        startTime: event.at,\n        attributes: stepAttrs(event),\n      },\n      parentCtx,\n    );\n  }\n\n  function endStepSpanOk(event: StepCompleteEvent, span: Span): void {\n    const k = stepKey(event.runId, event.stepId, event.attempt);\n    const startedAt = stepStartTimes.get(k);\n    // Match steps get a hard-coded durationMs=0 from the runtime; recover the\n    // real value from the stashed start time when available.\n    const durationMs =\n      event.kind === \"match\" && startedAt\n        ? event.at.getTime() - startedAt.getTime()\n        : event.durationMs;\n    span.setAttribute(\"nagi.step.duration_ms\", durationMs);\n    span.end(event.at);\n  }\n\n  function endStepSpanErr(\n    span: Span,\n    error: SerializedError,\n    endAt: Date,\n  ): void {\n    span.recordException(toError(error));\n    span.setAttribute(\"error.type\", error.name);\n    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n    span.end(endAt);\n  }\n\n  function consumeStepSpan(\n    runId: RunId,\n    stepId: StepId,\n    attempt: AttemptNumber,\n  ): Span | undefined {\n    const k = stepKey(runId, stepId, attempt);\n    const span = stepSpanRegistry.get(k);\n    stepSpanRegistry.delete(k);\n    stepStartTimes.delete(k);\n    return span;\n  }\n\n  return {\n    onFlowStart: withGuard<FlowStartEvent>(\"onFlowStart\", (event) => {\n      const span = tracer.startSpan(`${flowPrefix} ${event.flowId}`, {\n        kind: SpanKind.INTERNAL,\n        startTime: event.at,\n        attributes: flowAttrs(event),\n      });\n      flowCtxs.set(event.runId, trace.setSpan(context.active(), span));\n    }),\n\n    onFlowComplete: withGuard<FlowCompleteEvent>(\"onFlowComplete\", (event) => {\n      const ctx = flowCtxs.get(event.runId);\n      flowCtxs.delete(event.runId);\n      const span = ctx ? trace.getSpan(ctx) : undefined;\n      span?.end(event.at);\n    }),\n\n    onFlowError: withGuard<FlowErrorEvent>(\"onFlowError\", (event) => {\n      const ctx = flowCtxs.get(event.runId);\n      flowCtxs.delete(event.runId);\n      const span = ctx ? trace.getSpan(ctx) : undefined;\n      if (span) endStepSpanErr(span, event.error, event.at);\n    }),\n\n    onStepStart: withGuard<StepStartEvent>(\"onStepStart\", (event) => {\n      const span = startStepSpan(event);\n      const k = stepKey(event.runId, event.stepId, event.attempt);\n      stepSpanRegistry.set(k, span);\n      stepStartTimes.set(k, event.at);\n    }),\n\n    onStepComplete: withGuard<StepCompleteEvent>(\"onStepComplete\", (event) => {\n      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);\n      if (span) endStepSpanOk(event, span);\n    }),\n\n    onStepError: withGuard<StepErrorEvent>(\"onStepError\", (event) => {\n      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);\n      if (span) endStepSpanErr(span, event.error, event.at);\n    }),\n\n    onStepRetry: withGuard<StepRetryEvent>(\"onStepRetry\", (event) => {\n      // End the failed attempt's span with ERROR status. The next onStepStart\n      // for attempt+1 opens a fresh sibling span under the same flow span.\n      const span = consumeStepSpan(event.runId, event.stepId, event.attempt);\n      if (span) endStepSpanErr(span, event.error, event.at);\n\n      // Surface the retry on the flow span so users can see retry latency in\n      // the run-level trace without inspecting individual step attempts.\n      const flowCtx = flowCtxs.get(event.runId);\n      const flowSpan = flowCtx ? trace.getSpan(flowCtx) : undefined;\n      flowSpan?.addEvent(\n        \"nagi.retry.scheduled\",\n        {\n          \"nagi.step.id\": event.stepId,\n          \"nagi.step.attempt\": event.attempt,\n          \"nagi.next_attempt_at\": event.nextAttemptAt.toISOString(),\n        },\n        event.at,\n      );\n    }),\n\n    // onSignalSent is declared in core/types.ts but never fired by the runtime;\n    // intentionally omitted until core wires a sender path.\n    onSignalReceived: withGuard<SignalReceivedEvent>(\n      \"onSignalReceived\",\n      (event) => {\n        const span = consumeStepSpan(event.runId, event.stepId, event.attempt);\n        if (!span) return;\n        span.addEvent(\n          \"nagi.signal.received\",\n          { \"nagi.signal.payload_present\": event.payload !== null },\n          event.at,\n        );\n        span.setAttribute(\"nagi.step.duration_ms\", 0);\n        span.end(event.at);\n      },\n    ),\n  };\n}\n\nfunction toError(err: SerializedError): Error {\n  // `recordException` accepts `{ name, message, stack }`. We rebuild a\n  // shape-compatible object rather than a real Error to preserve the original\n  // name/stack exactly.\n  const e = new Error(err.message);\n  e.name = err.name;\n  if (err.stack !== undefined) e.stack = err.stack;\n  return e;\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nagi-js/otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry hooks adapter for nagi.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "nagi",
+    "workflow",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "tracing",
+    "adapter"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@nagi-js/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lymo-inc/nagi.git",
+    "directory": "packages/otel"
+  },
+  "homepage": "https://github.com/lymo-inc/nagi#readme",
+  "bugs": {
+    "url": "https://github.com/lymo-inc/nagi/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "vitest run --typecheck",
+    "typecheck": "tsc --noEmit"
+  }
+}