darwin-langgraph 0.2.0-alpha.1 → 0.4.0-alpha.1

package/dist/index.js

@@ -41,12 +41,20 @@ export { createDarwinNode, } from "./create-darwin-node.js";
 export { darwinAnnotation, getDarwinChannelSpec, lastWriteWinsTrajectoryReducer, } from "./darwin-annotation.js";
 export { withDarwinEvolution, } from "./with-darwin-evolution.js";
 // V0.2 — LangChain-native callback handler (preferred over `withDarwinEvolution`)
-export { DarwinCallbackHandler } from "./darwin-callback-handler.js";
+// V0.4 — extended with onToolEvent + maxTrajectoryBytes + MAX_KNOWN_TRACE_VERSION
+export { DarwinCallbackHandler, MAX_KNOWN_TRACE_VERSION, } from "./darwin-callback-handler.js";
 // V0.2 — OTEL GenAI Semantic Conventions mapping
+// V0.4 — extended with langGraphNode / langGraphStep / userId / requestId
 export { toOtelAttributes, toolCallToOtelAttributes, } from "./to-otel-attributes.js";
 // V0.2 — MessagesAnnotation interop for graphs mixing createReactAgent + createDarwinNode
 export { darwinMessagesAnnotation, getMessagesChannelSpec, } from "./darwin-messages-annotation.js";
-export { DarwinNodeError, DarwinEvolutionHookError } from "./errors.js";
+// V0.4 — accumulating annotation for graphs that fan-out multiple Darwin nodes
+export { darwinAccumulatingAnnotation, getDarwinAccumulatingChannelSpec, darwinTrajectoryAccumulatorReducer, } from "./darwin-accumulating-annotation.js";
+// V0.4 — token-budget callbacks (production guard against runaway agents)
+export { TokenBudgetCallbackHandler, createTokenBudgetCallbacks, } from "./token-budget.js";
+// V0.4 — W3C Trace Context mapper for cross-process span correlation
+export { toW3CTraceContext, } from "./to-w3c-trace-context.js";
+export { DarwinNodeError, DarwinEvolutionHookError, DarwinTokenBudgetExceededError, } from "./errors.js";
 /** Adapter version — sync with `package.json` on every release. */
-export const VERSION = "0.2.0-alpha.1";
+export const VERSION = "0.4.0-alpha.1";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,GAIpB,MAAM,4BAA4B,CAAC;AAEpC,kFAAkF;AAClF,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,iDAAiD;AACjD,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAIzB,MAAM,yBAAyB,CAAC;AAEjC,0FAA0F;AAC1F,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAaxE,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,GAIpB,MAAM,4BAA4B,CAAC;AAEpC,kFAAkF;AAClF,kFAAkF;AAClF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GAGxB,MAAM,8BAA8B,CAAC;AAEtC,iDAAiD;AACjD,0EAA0E;AAC1E,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAIzB,MAAM,yBAAyB,CAAC;AAEjC,0FAA0F;AAC1F,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,+EAA+E;AAC/E,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,kCAAkC,GACnC,MAAM,qCAAqC,CAAC;AAE7C,0EAA0E;AAC1E,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAI3B,MAAM,mBAAmB,CAAC;AAE3B,qEAAqE;AACrE,OAAO,EACL,iBAAiB,GAGlB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AAarB,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC"}

package/dist/to-otel-attributes.d.ts

@@ -51,6 +51,55 @@ export interface ToOtelAttributesOptions {
      * Override for organisation-wide naming conventions (e.g. `"company.darwin"`).
      */
     customNamespace?: string;
+    /**
+     * V0.4 — LangGraph node name. Emits `gen_ai.langgraph.node` per the
+     * Coralogix / Last9 / Honeycomb convention for LangGraph instrumentation.
+     *
+     * Pass `event.nodeName` from {@link DarwinTrajectoryEvent} to populate.
+     *
+     * NEW V0.4 (S1235).
+     */
+    langGraphNode?: string;
+    /**
+     * V0.4 — LangGraph step counter for this node execution. Emits
+     * `gen_ai.langgraph.step`. Optional — LangGraph does not always surface
+     * the step counter through callbacks; consumers who track it can
+     * forward it here.
+     *
+     * NEW V0.4 (S1235).
+     */
+    langGraphStep?: number;
+    /**
+     * V0.4 — End-user id (the authenticated user the request was made on
+     * behalf of). Emits the OTel cross-cutting `enduser.id` attribute
+     * (the canonical OTel general-semconv attribute for end-user identity)
+     * AND the historical alias `gen_ai.request.user` that older Coralogix /
+     * Last9 dashboards key off.
+     *
+     * R1 Research Finding 1 (S1235): the GenAI semconv registry does NOT
+     * define `gen_ai.request.user` or `gen_ai.user.id` — `enduser.id` from
+     * the cross-cutting attributes is the spec-correct key. We emit both
+     * so users on either dashboard convention keep working.
+     *
+     * NEW V0.4 (S1235).
+     */
+    userId?: string;
+    /**
+     * V0.4 — Conversation / thread id (typically the LangGraph
+     * `thread_id` from `config.configurable`). Emits the OTel
+     * `gen_ai.conversation.id` attribute (canonical spec key for grouping
+     * spans into one logical conversation in Langfuse / Honeycomb).
+     *
+     * NEW V0.4 (S1235).
+     */
+    conversationId?: string;
+    /**
+     * V0.4 — Custom request id (correlates with upstream HTTP request
+     * tracing). Emits `gen_ai.request.id`. Optional.
+     *
+     * NEW V0.4 (S1235).
+     */
+    requestId?: string;
 }
 /** Flat attribute bag matching OTEL's primitive-only attribute types. */
 export type OtelAttributes = Record<string, string | number | boolean>;

package/dist/to-otel-attributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-otel-attributes.d.ts","sourceRoot":"","sources":["../src/to-otel-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,EAC1B,IAAI,GAAE,uBAA4B,GACjC,cAAc,CAmEhB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EACzC,IAAI,GAAE,mBAAwB,GAC7B,cAAc,CAoDhB"}
+{"version":3,"file":"to-otel-attributes.d.ts","sourceRoot":"","sources":["../src/to-otel-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,EAC1B,IAAI,GAAE,uBAA4B,GACjC,cAAc,CA8GhB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EACzC,IAAI,GAAE,mBAAwB,GAC7B,cAAc,CAoDhB"}

package/dist/to-otel-attributes.js

@@ -68,8 +68,17 @@
  * ```
  */
 export function toOtelAttributes(trajectory, opts = {}) {
-    if (!trajectory || typeof trajectory !== "object" || trajectory.version !== 1) {
-        throw new TypeError(`toOtelAttributes: trajectory must be an ExecutionTrace with version=1, got ${trajectory === null ? "null" : typeof trajectory}`);
+    // R2 MUST-FIX (S1235): forward-compat — accept `version >= 1` to
+    // match the R1 P0-2 widening in `isExecutionTrace` and the
+    // accumulator reducer. A v=2 trajectory that passed both upstream
+    // gates would otherwise crash here. Same structural guard as
+    // `isExecutionTrace`.
+    if (!trajectory ||
+        typeof trajectory !== "object" ||
+        typeof trajectory.version !== "number" ||
+        !Number.isFinite(trajectory.version) ||
+        trajectory.version < 1) {
+        throw new TypeError(`toOtelAttributes: trajectory must be an ExecutionTrace with version>=1, got ${trajectory === null ? "null" : typeof trajectory}`);
     }
     const ns = opts.customNamespace ?? "darwin";
     const attrs = {
@@ -80,6 +89,33 @@ export function toOtelAttributes(trajectory, opts = {}) {
         attrs["gen_ai.agent.name"] = opts.agentName;
     if (opts.agentId)
         attrs["gen_ai.agent.id"] = opts.agentId;
+    // V0.4 (S1235): LangGraph-specific attributes per Coralogix / Last9 /
+    // Honeycomb 2026 convention for LangGraph instrumentation. Emitted
+    // alongside the canonical gen_ai attrs so dashboards that filter by
+    // `gen_ai.langgraph.node` (one bar per node) work out-of-box.
+    if (typeof opts.langGraphNode === "string" && opts.langGraphNode.length > 0) {
+        attrs["gen_ai.langgraph.node"] = opts.langGraphNode;
+    }
+    if (typeof opts.langGraphStep === "number" &&
+        Number.isFinite(opts.langGraphStep) &&
+        opts.langGraphStep >= 0) {
+        attrs["gen_ai.langgraph.step"] = opts.langGraphStep;
+    }
+    if (typeof opts.userId === "string" && opts.userId.length > 0) {
+        // R1 Research 1 fix (S1235): emit the OTel-spec-canonical
+        // `enduser.id` AND the historical alias `gen_ai.request.user` that
+        // older Coralogix / Last9 dashboards key off, so both consumer
+        // conventions keep working.
+        attrs["enduser.id"] = opts.userId;
+        attrs["gen_ai.request.user"] = opts.userId;
+    }
+    if (typeof opts.conversationId === "string" &&
+        opts.conversationId.length > 0) {
+        attrs["gen_ai.conversation.id"] = opts.conversationId;
+    }
+    if (typeof opts.requestId === "string" && opts.requestId.length > 0) {
+        attrs["gen_ai.request.id"] = opts.requestId;
+    }
     // Token usage — only emit when provider reported FINITE numbers. NaN
     // and Infinity pass `typeof === "number"` but OTEL exporters drop
     // spans with non-finite numeric attrs silently (R1 V0.2 Critic

package/dist/to-otel-attributes.js.map

@@ -1 +1 @@
-{"version":3,"file":"to-otel-attributes.js","sourceRoot":"","sources":["../src/to-otel-attributes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"to-otel-attributes.js","sourceRoot":"","sources":["../src/to-otel-attributes.ts"],"names":[],"mappings":"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"}

package/dist/to-w3c-trace-context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Surface 11 (V0.4) — `toW3CTraceContext(event, opts?)`.
+ *
+ * Pure mapper from a {@link DarwinTrajectoryEvent} to the
+ * [W3C Trace Context](https://www.w3.org/TR/trace-context/) `traceparent`
+ * header format so consumers can propagate Darwin trajectories into
+ * external systems (Langfuse, Honeycomb, Datadog APM, Tempo) without
+ * pulling in `@opentelemetry/api` as a dependency.
+ *
+ * Format reference (spec §3.2.2):
+ *
+ *   traceparent = version "-" trace-id "-" parent-id "-" trace-flags
+ *
+ * - `version` = `"00"` (we emit only the current spec version).
+ * - `trace-id` = 32 hex chars. We map LangChain's UUID `parentRunId` (if
+ *   present) by stripping dashes — UUID is 32 hex chars + 4 dashes — so
+ *   the strip yields exactly 32 chars. If `parentRunId` is undefined we
+ *   fall back to `runId` (top-level invokes form their own trace).
+ * - `parent-id` = 16 hex chars. We map LangChain's UUID `runId` by
+ *   stripping dashes and TAKING THE FIRST 16 chars (parent-id is shorter
+ *   than trace-id by spec design — first 16 chars of a UUID are random
+ *   enough that collision probability per-trace is negligible).
+ * - `trace-flags` = `"01"` (sampled). We always emit sampled — consumers
+ *   that want head-based sampling should drop the entire event upstream
+ *   rather than fiddle with the flag.
+ *
+ * The W3C spec forbids `trace-id == "00000000000000000000000000000000"`
+ * and `parent-id == "0000000000000000"`. If either UUID strips to those
+ * all-zero strings we return `undefined` rather than emit an invalid
+ * header that downstream parsers reject.
+ *
+ * **Pure, no I/O, no allocation surprises.** The function builds a single
+ * string. Safe to call inside `onTrajectory` hot paths.
+ *
+ * NEW V0.4 (S1235).
+ */
+import type { DarwinTrajectoryEvent } from "./with-darwin-evolution.js";
+/** Options accepted by {@link toW3CTraceContext}. */
+export interface ToW3CTraceContextOptions {
+    /**
+     * Override the trace-flags byte. Default `"01"` (sampled). Set `"00"`
+     * for not-sampled — consumers can use this to mark trajectories that
+     * would otherwise be sampled out before they reach the W3C-aware
+     * exporter.
+     */
+    traceFlags?: "00" | "01";
+}
+/** Return shape: a single W3C-compliant `traceparent` header value. */
+export interface W3CTraceContext {
+    /** Full `traceparent` header value (spec §3.2). */
+    traceparent: string;
+    /** 32-hex trace ID — convenience accessor. */
+    traceId: string;
+    /** 16-hex span ID (the W3C `parent-id` slot) — convenience accessor. */
+    spanId: string;
+}
+/**
+ * Convert a {@link DarwinTrajectoryEvent} into a W3C `traceparent` header
+ * value. Returns `undefined` when no usable runId is present or when the
+ * stripped UUIDs collapse to the all-zero strings the spec forbids.
+ *
+ * @example
+ * ```ts
+ * import { toW3CTraceContext, DarwinCallbackHandler } from "darwin-langgraph";
+ *
+ * const handler = new DarwinCallbackHandler({
+ *   nodeMap: { research: "researcher" },
+ *   onTrajectory: async (event) => {
+ *     const ctx = toW3CTraceContext(event);
+ *     if (!ctx) return;
+ *     await fetch("https://langfuse.example/api/traces", {
+ *       method: "POST",
+ *       headers: { traceparent: ctx.traceparent },
+ *       body: JSON.stringify({ trace: event.trajectory }),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export declare function toW3CTraceContext(event: DarwinTrajectoryEvent, opts?: ToW3CTraceContextOptions): W3CTraceContext | undefined;
+//# sourceMappingURL=to-w3c-trace-context.d.ts.map

package/dist/to-w3c-trace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-w3c-trace-context.d.ts","sourceRoot":"","sources":["../src/to-w3c-trace-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,qBAAqB,EAC5B,IAAI,GAAE,wBAA6B,GAClC,eAAe,GAAG,SAAS,CAwD7B"}

package/dist/to-w3c-trace-context.js

@@ -0,0 +1,134 @@
+/**
+ * Surface 11 (V0.4) — `toW3CTraceContext(event, opts?)`.
+ *
+ * Pure mapper from a {@link DarwinTrajectoryEvent} to the
+ * [W3C Trace Context](https://www.w3.org/TR/trace-context/) `traceparent`
+ * header format so consumers can propagate Darwin trajectories into
+ * external systems (Langfuse, Honeycomb, Datadog APM, Tempo) without
+ * pulling in `@opentelemetry/api` as a dependency.
+ *
+ * Format reference (spec §3.2.2):
+ *
+ *   traceparent = version "-" trace-id "-" parent-id "-" trace-flags
+ *
+ * - `version` = `"00"` (we emit only the current spec version).
+ * - `trace-id` = 32 hex chars. We map LangChain's UUID `parentRunId` (if
+ *   present) by stripping dashes — UUID is 32 hex chars + 4 dashes — so
+ *   the strip yields exactly 32 chars. If `parentRunId` is undefined we
+ *   fall back to `runId` (top-level invokes form their own trace).
+ * - `parent-id` = 16 hex chars. We map LangChain's UUID `runId` by
+ *   stripping dashes and TAKING THE FIRST 16 chars (parent-id is shorter
+ *   than trace-id by spec design — first 16 chars of a UUID are random
+ *   enough that collision probability per-trace is negligible).
+ * - `trace-flags` = `"01"` (sampled). We always emit sampled — consumers
+ *   that want head-based sampling should drop the entire event upstream
+ *   rather than fiddle with the flag.
+ *
+ * The W3C spec forbids `trace-id == "00000000000000000000000000000000"`
+ * and `parent-id == "0000000000000000"`. If either UUID strips to those
+ * all-zero strings we return `undefined` rather than emit an invalid
+ * header that downstream parsers reject.
+ *
+ * **Pure, no I/O, no allocation surprises.** The function builds a single
+ * string. Safe to call inside `onTrajectory` hot paths.
+ *
+ * NEW V0.4 (S1235).
+ */
+const ZERO_TRACE_ID = "00000000000000000000000000000000";
+const ZERO_SPAN_ID = "0000000000000000";
+function uuidToHex(uuid) {
+    // UUIDs are case-insensitive hex; lowercase to match the W3C spec.
+    return uuid.replace(/-/g, "").toLowerCase();
+}
+function isPureHex(s) {
+    // Cheap test — characters 0-9, a-f. ASCII range check is faster than
+    // a regex on hot paths.
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        const isDigit = c >= 48 && c <= 57; // 0-9
+        const isLowerHex = c >= 97 && c <= 102; // a-f
+        if (!isDigit && !isLowerHex)
+            return false;
+    }
+    return true;
+}
+/**
+ * Convert a {@link DarwinTrajectoryEvent} into a W3C `traceparent` header
+ * value. Returns `undefined` when no usable runId is present or when the
+ * stripped UUIDs collapse to the all-zero strings the spec forbids.
+ *
+ * @example
+ * ```ts
+ * import { toW3CTraceContext, DarwinCallbackHandler } from "darwin-langgraph";
+ *
+ * const handler = new DarwinCallbackHandler({
+ *   nodeMap: { research: "researcher" },
+ *   onTrajectory: async (event) => {
+ *     const ctx = toW3CTraceContext(event);
+ *     if (!ctx) return;
+ *     await fetch("https://langfuse.example/api/traces", {
+ *       method: "POST",
+ *       headers: { traceparent: ctx.traceparent },
+ *       body: JSON.stringify({ trace: event.trajectory }),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export function toW3CTraceContext(event, opts = {}) {
+    if (!event.runId)
+        return undefined;
+    const runHex = uuidToHex(event.runId);
+    // The W3C spec is strict about character set and length. If callers
+    // pass a non-UUID runId (e.g. from a custom run identifier scheme)
+    // bail out rather than emit a malformed header.
+    if (runHex.length < 32 || !isPureHex(runHex))
+        return undefined;
+    let traceIdSource;
+    let spanFromFirstHalf;
+    if (event.parentRunId) {
+        const parentHex = uuidToHex(event.parentRunId);
+        if (parentHex.length < 32 || !isPureHex(parentHex)) {
+            // Parent is malformed — fall through to runId-only trace. In that
+            // case we MUST domain-separate the spanId from the traceId; see
+            // the no-parent branch comment below.
+            traceIdSource = runHex;
+            spanFromFirstHalf = false;
+        }
+        else {
+            // Hierarchical: trace-id from parent, span-id from runId. The
+            // first 16 hex of the runId are random in v4 / v7 UUIDs (variant
+            // bits live at char 16+), so collision probability per trace is
+            // negligible.
+            traceIdSource = parentHex;
+            spanFromFirstHalf = true;
+        }
+    }
+    else {
+        // Top-level invoke: when there is no separate parentRunId, deriving
+        // BOTH traceId AND spanId from the FIRST 16 chars of the same UUID
+        // produces a `traceparent` where the spanId is a prefix of the
+        // traceId. Several OTEL backends (Datadog APM, Honeycomb classic)
+        // reject or misroute such spans because they look like self-parents.
+        // R1 P0-1 fix (S1235): take the SECOND half of the run hex for the
+        // spanId so the two slots are domain-separated even when sourced
+        // from the same UUID.
+        traceIdSource = runHex;
+        spanFromFirstHalf = false;
+    }
+    const traceId = traceIdSource.slice(0, 32);
+    const spanId = spanFromFirstHalf
+        ? runHex.slice(0, 16)
+        : runHex.slice(16, 32);
+    // Spec §3.2.2.2: trace-id == 0...0 is invalid. Same for parent-id.
+    if (traceId === ZERO_TRACE_ID || spanId === ZERO_SPAN_ID) {
+        return undefined;
+    }
+    const traceFlags = opts.traceFlags ?? "01";
+    return {
+        traceparent: `00-${traceId}-${spanId}-${traceFlags}`,
+        traceId,
+        spanId,
+    };
+}
+//# sourceMappingURL=to-w3c-trace-context.js.map

package/dist/to-w3c-trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-w3c-trace-context.js","sourceRoot":"","sources":["../src/to-w3c-trace-context.ts"],"names":[],"mappings":"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"}

package/dist/token-budget.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Surface 10 (V0.4) — `createTokenBudgetCallbacks(budget, onExceed)`.
+ *
+ * Production-pattern from the LangGraph TypeScript Production Guide
+ * (langgraphjs.guide/production): a token budget enforced per-invocation
+ * across ALL LLM calls inside a graph, throwing when the budget is
+ * exceeded. Mirrors the canonical example with two differences:
+ *
+ *   1. Returned as a `BaseCallbackHandler` subclass so it composes with
+ *      {@link DarwinCallbackHandler} via the standard `{ callbacks: [...] }`
+ *      option — no model-side patching required, works against any
+ *      LangChain provider that emits `handleLLMEnd`.
+ *   2. Throws a typed {@link DarwinTokenBudgetExceededError} so consumers
+ *      can `instanceof`-check without parsing message text.
+ *
+ * The handler tracks BOTH the LangChain-canonical `output.llmOutput.tokenUsage`
+ * shape (used by `ChatOpenAI`, `ChatAnthropic`, etc.) AND the per-message
+ * usage shape (`generations[0][0].message.usage_metadata`) some providers
+ * emit. The total is monotonically non-decreasing across `handleLLMEnd`
+ * events; once the budget is crossed the throw happens INSIDE
+ * `handleLLMEnd`, which LangChain surfaces back to the caller of
+ * `graph.invoke` / `graph.stream`.
+ *
+ * IMPORTANT: the throw is the only reliable abort signal — LangGraph's
+ * node-level retry policy may still re-fire the budget-exceeded path.
+ * The `onExceed` callback fires once per handler instance regardless of
+ * how many times the throw is observed (use it for logging / alerting,
+ * not retry).
+ *
+ * NEW V0.4 (S1235).
+ */
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import type { LLMResult } from "@langchain/core/outputs";
+/**
+ * Options accepted by {@link createTokenBudgetCallbacks}.
+ */
+export interface TokenBudgetOptions {
+    /**
+     * Per-handler-instance token ceiling. Counts the SUM of input + output
+     * tokens across every `handleLLMEnd` event. Must be a finite positive
+     * integer; invalid values throw `DarwinTokenBudgetExceededError`
+     * eagerly on construction so misconfigured deployments fail loud.
+     */
+    budget: number;
+    /**
+     * Fire-and-forget side-effect when the budget is exceeded. Receives the
+     * cumulative total at the moment of breach, the configured budget, and
+     * an optional `providerHint` extracted from the LLMResult (e.g. the
+     * model name when emitted). Errors thrown inside this callback are
+     * swallowed with a single warn so they cannot mask the budget throw.
+     *
+     * Use this for logging / metrics / alerting — not for retry.
+     */
+    onExceed?: (info: TokenBudgetExceedInfo) => void;
+    /**
+     * Fire on every `handleLLMEnd` event with the running total. Useful for
+     * dashboards or step-by-step budget consumption traces. Optional.
+     */
+    onTick?: (info: TokenBudgetTickInfo) => void;
+}
+export interface TokenBudgetExceedInfo {
+    budget: number;
+    totalTokens: number;
+    providerHint: string | undefined;
+}
+export interface TokenBudgetTickInfo {
+    budget: number;
+    totalTokens: number;
+    deltaTokens: number;
+    remainingTokens: number;
+    providerHint: string | undefined;
+}
+/**
+ * LangChain `BaseCallbackHandler` that enforces a hard token budget
+ * across all LLM calls observed during its lifetime.
+ *
+ * Construct once per `graph.invoke` call (do NOT reuse across requests —
+ * the running total is per-handler-instance). The
+ * {@link createTokenBudgetCallbacks} factory makes the per-invocation
+ * shape ergonomic.
+ */
+export declare class TokenBudgetCallbackHandler extends BaseCallbackHandler {
+    readonly name = "DarwinTokenBudgetHandler";
+    /**
+     * V0.4 R1 P2-3 fix (S1235): `awaitHandlers = true` is required so
+     * LangChain's callback manager AWAITS this handler before continuing
+     * — the synchronous `throw` from `handleLLMEnd` MUST reach the
+     * `graph.invoke` caller. With `awaitHandlers = false` the throw may
+     * surface as an unhandled rejection in some LangChain versions
+     * rather than aborting the graph, which is the entire point of a
+     * token budget.
+     */
+    readonly awaitHandlers = true;
+    private readonly budget;
+    private readonly onExceed;
+    private readonly onTick;
+    private totalTokens;
+    private exceedWarned;
+    private exceedFired;
+    private tickErrorWarned;
+    constructor(opts: TokenBudgetOptions);
+    handleLLMEnd(output: LLMResult): void;
+    private warnTick;
+    /** Helper for tests + debug introspection. */
+    getTotalTokens(): number;
+}
+/**
+ * Factory that returns a single-element `BaseCallbackHandler[]` ready to
+ * be passed via the standard LangGraph `{ callbacks: [...] }` option.
+ * Returning an array is the ergonomic shape — most consumers spread it
+ * into a larger callbacks array next to {@link DarwinCallbackHandler}.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   DarwinCallbackHandler,
+ *   createTokenBudgetCallbacks,
+ *   DarwinTokenBudgetExceededError,
+ * } from "darwin-langgraph";
+ *
+ * try {
+ *   const result = await graph.invoke({ task: "..." }, {
+ *     callbacks: [
+ *       new DarwinCallbackHandler({ nodeMap, onTrajectory }),
+ *       ...createTokenBudgetCallbacks({
+ *         budget: 20_000,
+ *         onExceed: ({ totalTokens, providerHint }) => {
+ *           console.error(`Budget breach: ${totalTokens} tok (${providerHint})`);
+ *         },
+ *       }),
+ *     ],
+ *   });
+ * } catch (err) {
+ *   if (err instanceof DarwinTokenBudgetExceededError) {
+ *     // ... graceful degradation, fallback model, etc.
+ *   }
+ * }
+ * ```
+ */
+export declare function createTokenBudgetCallbacks(opts: TokenBudgetOptions): [TokenBudgetCallbackHandler];
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../src/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAIzD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACjD;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AA8DD;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,SAAQ,mBAAmB;IACjE,SAAyB,IAAI,8BAA8B;IAC3D;;;;;;;;OAQG;IACH,SAAyB,aAAa,QAAQ;IAE9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAS;gBAEpB,IAAI,EAAE,kBAAkB;IAyB3B,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAoD9C,OAAO,CAAC,QAAQ;IAUhB,8CAA8C;IACvC,cAAc,IAAI,MAAM;CAGhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,GACvB,CAAC,0BAA0B,CAAC,CAE9B"}