@struct-ai/sdk 0.3.0 → 0.4.2

package/dist/commonjs/integrations/langchain-content.js

@@ -15,7 +15,7 @@ const truncation_js_1 = require("../truncation.js");
 const semconv_js_1 = require("../semconv.js");
 exports.PROVIDER_MAP = {
     ChatOpenAI: "openai",
-    AzureChatOpenAI: "azure.openai",
+    AzureChatOpenAI: "azure.ai.openai",
     ChatAnthropic: "anthropic",
     ChatGoogleGenerativeAI: "gcp.generative_ai",
     ChatVertexAI: "gcp.vertex_ai",

package/dist/commonjs/integrations/langchain.d.ts

@@ -1,4 +1,5 @@
 import type { StructSDK } from "../core.js";
+import { getStore } from "../context.js";
 import { StructCallbackHandler } from "./langchain-callback.js";
 /**
  * Export the handler so callers can register it explicitly
@@ -8,4 +9,6 @@ import { StructCallbackHandler } from "./langchain-callback.js";
 export declare function getLangchainHandler(): StructCallbackHandler | undefined;
 export declare function patch(sdk: StructSDK): Promise<void>;
 export declare function unpatch(): Promise<void>;
+/** @internal */
+export declare function _wrapIteratorWithSuppressionForTest(streamLike: unknown, suppressedSnapshot: ReturnType<typeof getStore>): void;
 //# sourceMappingURL=langchain.d.ts.map

package/dist/commonjs/integrations/langchain.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLangchainHandler = getLangchainHandler;
 exports.patch = patch;
 exports.unpatch = unpatch;
+exports._wrapIteratorWithSuppressionForTest = _wrapIteratorWithSuppressionForTest;
+const context_js_1 = require("../context.js");
 const langchain_callback_js_1 = require("./langchain-callback.js");
 /**
  * LangChain.js integration — registers a BaseCallbackHandler subclass with
@@ -15,6 +17,7 @@ const langchain_callback_js_1 = require("./langchain-callback.js");
  * async microtask shuffling (which otherwise drops OTel's active context).
  */
 const STRUCT_WRAPPED = Symbol.for("struct.wrapped");
+const SUPPRESS_ORIGINAL = Symbol.for("struct.suppress.original");
 const state = {};
 /**
  * Export the handler so callers can register it explicitly
@@ -46,8 +49,26 @@ async function patch(sdk) {
         state.cfg.originalConfigure = originalConfigure;
         const wrappedConfigure = function (...args) {
             const active = state.handler;
-            if (active)
-                args[0] = injectHandler(args[0], active);
+            if (active) {
+                // Self-audit round 5 (FIX D): resolveConfigureHandlerArgs invokes
+                // FALLIBLE methods on a CUSTOMER-supplied callback manager
+                // (mgr.addHandler / mgr.removeHandler, reading mgr.handlers) —
+                // operations vanilla LangChain's own configure() never makes on
+                // these exact caller-supplied objects. A throwing/exotic manager
+                // (broken subclass, hostile proxy) must not turn an otherwise
+                // successful invoke/stream/batch call into a thrown exception.
+                // Degrade: fall through to the ORIGINAL configure with the
+                // customer's UNMODIFIED args (args[0]/[1] are only reassigned AFTER
+                // resolveConfigureHandlerArgs returns, so a throw here leaves them
+                // untouched) — maybe no struct handler gets injected for this call,
+                // but the customer's call never breaks.
+                try {
+                    [args[0], args[1]] = resolveConfigureHandlerArgs(args[0], args[1], active);
+                }
+                catch {
+                    return originalConfigure.apply(cm, args);
+                }
+            }
             return originalConfigure.apply(cm, args);
         };
         wrappedConfigure[STRUCT_WRAPPED] = true;
@@ -58,13 +79,234 @@ async function patch(sdk) {
         state.cfg.originalConfigureSync = originalSync;
         const wrappedSync = function (...args) {
             const active = state.handler;
-            if (active)
-                args[0] = injectHandler(args[0], active);
+            if (active) {
+                // Same hazard as wrappedConfigure above — see its comment.
+                try {
+                    [args[0], args[1]] = resolveConfigureHandlerArgs(args[0], args[1], active);
+                }
+                catch {
+                    return originalSync.apply(cm, args);
+                }
+            }
             return originalSync.apply(cm, args);
         };
         wrappedSync[STRUCT_WRAPPED] = true;
         cm._configureSync = wrappedSync;
     }
+    await patchChatModelSuppression();
+}
+/**
+ * Chat-suppression handshake: wrap the base-class methods that every
+ * BaseChatModel subclass routes through (subclasses override `_generate` /
+ * `_streamResponseChunks`, never `generate` / `stream` directly) in an ALS
+ * scope with `suppressGenAi: true`. The provider-SDK patch (anthropic.ts)
+ * checks `isGenAiSuppressed()` inside that scope and skips emitting its own
+ * chat span, since the LangChain callback handler already owns it.
+ *
+ * `generate` lives directly on `BaseChatModel.prototype`. `stream` does NOT
+ * — LangChain's `BaseChatModel` inherits it, unmodified, from
+ * `Runnable.prototype` (in `@langchain/core/runnables`); subclasses hook
+ * streaming via `_streamResponseChunks`, which `Runnable.stream()` reaches
+ * through `_streamIterator` — verified against the installed @langchain/core
+ * (0.3.80) via `Object.getPrototypeOf` walk + `hasOwnProperty` checks.
+ *
+ * Critically, `Runnable` is also the base class of chains, tools, AND
+ * compiled LangGraph graphs (`CompiledStateGraph` / `Pregel`), and
+ * `Pregel.invoke()` delegates internally to `this.stream()`. Wrapping
+ * `Runnable.prototype.stream` directly would therefore suppress GenAI spans
+ * for the ENTIRE graph run, not just one LLM call — a direct
+ * `@anthropic-ai/sdk` call made from inside a tool/node body during
+ * `graph.stream()`/`graph.invoke()` would incorrectly see
+ * `isGenAiSuppressed() === true` and drop its chat span.
+ *
+ * So `stream` is SHADOWED on `BaseChatModel.prototype` instead of patched on
+ * `Runnable.prototype`: we read the inherited `Runnable.prototype.stream`
+ * (property lookup walks the prototype chain) and assign the wrapped
+ * version as an OWN property of `BaseChatModel.prototype` (assignment never
+ * walks the chain — it always creates/overwrites an own property). Chat
+ * model subclasses (`ChatAnthropic`, `ChatOpenAI`, etc.) resolve `stream` to
+ * this new own property and get the suppression scope; plain Runnables,
+ * tools, and compiled graphs never had an own `stream` and keep resolving to
+ * the untouched `Runnable.prototype.stream`.
+ *
+ * Execution-scoped via AsyncLocalStorage (JS has no imperative
+ * context.attach/detach), so this is parallel-safe: concurrent
+ * `model.generate()` calls each get their own ALS frame.
+ */
+async function patchChatModelSuppression() {
+    const targets = [];
+    let chatProto;
+    try {
+        const chatModelsMod = (await import("@langchain/core/language_models/chat_models"));
+        chatProto = chatModelsMod.BaseChatModel?.prototype;
+        if (chatProto) {
+            const hadOwnProperty = Object.prototype.hasOwnProperty.call(chatProto, "generate");
+            wrapSuppressedGenerate(chatProto, "generate");
+            targets.push({
+                proto: chatProto,
+                method: "generate",
+                createdOwnProperty: !hadOwnProperty,
+            });
+        }
+    }
+    catch {
+        /* @langchain/core/language_models/chat_models not installed — skip */
+    }
+    try {
+        if (chatProto) {
+            const createdOwnProperty = wrapSuppressedStreamShadow(chatProto, "stream");
+            if (createdOwnProperty !== undefined) {
+                targets.push({ proto: chatProto, method: "stream", createdOwnProperty });
+            }
+        }
+    }
+    catch {
+        /* stream is read off the already-resolved chatProto above (no separate
+           import here) — guards defensively against an unexpected shape change
+           in the installed @langchain/core, not a missing package. */
+    }
+    // Merge with any targets from a prior patch() call so unpatch() can still
+    // restore everything (mirrors the CallbackManager prev-state preservation
+    // above — a second patch() call must not strand the original refs).
+    const prevTargets = state.suppressionTargets ?? [];
+    const merged = [...prevTargets];
+    for (const t of targets) {
+        if (!merged.some((m) => m.proto === t.proto && m.method === t.method)) {
+            merged.push(t);
+        }
+    }
+    state.suppressionTargets = merged;
+}
+/** Wrap `proto[method]` (BaseChatModel.generate) in an ALS-suppressed scope. */
+function wrapSuppressedGenerate(proto, method) {
+    const original = proto[method];
+    if (typeof original !== "function" || original[STRUCT_WRAPPED])
+        return;
+    const wrapped = function (...args) {
+        return (0, context_js_1.runWithContext)({ suppressGenAi: true }, () => original.apply(this, args));
+    };
+    wrapped[STRUCT_WRAPPED] = true;
+    wrapped[SUPPRESS_ORIGINAL] = original;
+    proto[method] = wrapped;
+}
+/**
+ * Shadow `proto[method]` (BaseChatModel.prototype.stream) with an
+ * ALS-suppressed wrapper around the INHERITED implementation
+ * (Runnable.prototype.stream), without ever touching Runnable.prototype
+ * itself.
+ *
+ * Reading `proto[method]` resolves up the prototype chain to
+ * `Runnable.prototype.stream` (BaseChatModel has no own `stream`).
+ * Assigning `proto[method] = wrapped` then creates a NEW OWN property on
+ * `BaseChatModel.prototype` that shadows the inherited one — subclasses of
+ * BaseChatModel resolve to this own property; plain Runnables (chains,
+ * tools, compiled LangGraph graphs), which don't inherit from
+ * BaseChatModel, are completely unaffected.
+ *
+ * `stream()` is async but returns an `IterableReadableStream` whose
+ * underlying provider call happens lazily on first pull — the `await
+ * original.apply(...)` below only awaits the initial buffering (see
+ * `AsyncGeneratorWithSetup` in @langchain/core), not the full generation. So
+ * the suppression scope must also wrap the returned stream's
+ * `Symbol.asyncIterator` and re-enter a suppressed store snapshot on every
+ * `next()/return()/throw()` — same pattern as the iterator wrap in
+ * anthropic.ts's `wrapStream` (lines ~414-437).
+ *
+ * Returns whether this call created a new own property (true), found one
+ * already shadowed by a prior patch (false — idempotent no-op), or could
+ * not proceed because there's no inherited method to wrap (undefined).
+ */
+function wrapSuppressedStreamShadow(proto, method) {
+    const hadOwnProperty = Object.prototype.hasOwnProperty.call(proto, method);
+    const original = proto[method];
+    if (typeof original !== "function")
+        return undefined;
+    if (original[STRUCT_WRAPPED])
+        return false;
+    const wrapped = function (...args) {
+        return (0, context_js_1.runWithContext)({ suppressGenAi: true }, async () => {
+            const result = await original.apply(this, args);
+            const suppressedSnapshot = { ...((0, context_js_1.getStore)() ?? {}), suppressGenAi: true };
+            wrapIteratorWithSuppression(result, suppressedSnapshot);
+            return result;
+        });
+    };
+    wrapped[STRUCT_WRAPPED] = true;
+    wrapped[SUPPRESS_ORIGINAL] = original;
+    proto[method] = wrapped;
+    // If BaseChatModel.prototype already had its own `stream` (unexpected on
+    // current @langchain/core, but defensive against future versions), this
+    // wrap only reassigned an existing own property — restoring on unpatch()
+    // must reassign the original back, not delete.
+    return !hadOwnProperty;
+}
+function wrapIteratorWithSuppression(streamLike, suppressedSnapshot) {
+    const it = streamLike;
+    try {
+        // Read + bind are INSIDE the guard: a hostile/proxy Symbol.asyncIterator
+        // getter throws on the property READ (not just the assignment), and this
+        // runs synchronously right after `await original.stream()` resolves — an
+        // escaped throw would reject the customer's successful call.
+        if (!it || typeof it[Symbol.asyncIterator] !== "function")
+            return;
+        const originalIter = it[Symbol.asyncIterator].bind(it);
+        it[Symbol.asyncIterator] = () => {
+            const inner = originalIter();
+            const wrappedIterator = {
+                next() {
+                    return (0, context_js_1.runWithStore)(suppressedSnapshot, () => inner.next());
+                },
+                return(value) {
+                    return (0, context_js_1.runWithStore)(suppressedSnapshot, () => inner.return ? inner.return(value) : Promise.resolve({ value, done: true }));
+                },
+                throw(err) {
+                    return (0, context_js_1.runWithStore)(suppressedSnapshot, () => inner.throw ? inner.throw(err) : Promise.reject(err));
+                },
+            };
+            return wrappedIterator;
+        };
+    }
+    catch {
+        // Same hazard class as anthropic.ts's instrumentRawStream /
+        // instrumentSyncIterable (Task-10 review fix): the LangChain-created
+        // stream returned by `Runnable.prototype.stream` (a host-owned
+        // IterableReadableStream-like object) may be frozen/sealed, or otherwise
+        // have a non-writable/non-configurable Symbol.asyncIterator — assigning
+        // to it throws a TypeError in strict mode. This call happens
+        // synchronously inside `wrapSuppressedStreamShadow`'s async body, right
+        // after `await original.apply(...)` resolves — an uncaught throw here
+        // would turn the customer's SUCCESSFUL `.stream()` call into a rejected
+        // promise purely because OUR suppression instrumentation couldn't
+        // attach. Degrade gracefully instead: leave the stream's own iterator
+        // untouched (the failed assignment never took effect) and let the
+        // caller return the original object unchanged. Consequence: a raw
+        // provider-SDK call made while consuming this stream won't see
+        // `suppressGenAi` and may emit a duplicate chat span — acceptable;
+        // breaking the host is not.
+    }
+}
+function unpatchChatModelSuppression() {
+    const targets = state.suppressionTargets;
+    if (!targets)
+        return;
+    for (const { proto, method, createdOwnProperty } of targets) {
+        const current = proto[method];
+        if (!current?.[STRUCT_WRAPPED])
+            continue;
+        if (createdOwnProperty) {
+            // The wrap created this as a new own property (e.g. shadowing
+            // BaseChatModel.prototype.stream over the inherited
+            // Runnable.prototype.stream) — delete it to restore inheritance
+            // rather than reassigning the original function onto the prototype,
+            // which would leave a stray own property and change prototype
+            // semantics (hasOwnProperty, for..in, etc.) even after "restore".
+            delete proto[method];
+        }
+        else if (current[SUPPRESS_ORIGINAL]) {
+            proto[method] = current[SUPPRESS_ORIGINAL];
+        }
+    }
+    state.suppressionTargets = undefined;
 }
 async function unpatch() {
     if (state.cfg?.mod) {
@@ -77,24 +319,128 @@ async function unpatch() {
             cm._configureSync = state.cfg.originalConfigureSync;
         }
     }
+    unpatchChatModelSuppression();
     state.handler = undefined;
     state.cfg = undefined;
 }
+/**
+ * Decide the (inheritable, local) pair to hand to the original
+ * `configure`/`_configureSync` so our handler fires EXACTLY ONCE per run,
+ * no matter how the caller already arranged their `inheritableHandlers` /
+ * `localHandlers` (LangChain's `configure(inheritable, local, ...)`
+ * parameter order — `args[0]`/`args[1]` at the call sites above).
+ *
+ * Dedup is by IDENTITY against `handler` (`state.handler`, our own exact
+ * instance) — never by `name === "struct"`. A caller-supplied handler that
+ * merely happens to be named "struct" (but isn't ours) must survive
+ * untouched; matching by name would incorrectly strip or remove it.
+ *
+ * `existing`/`local` can each be `undefined`, a plain array of handlers, or
+ * a `BaseCallbackManager` instance (has `.handlers`/`.addHandler`/
+ * `.removeHandler`) — LangChain accepts both shapes for either parameter.
+ *
+ * Three cases, checked by identity via `containsHandler`:
+ *   1. Not present in `local` at all — inject into `inheritable`
+ *      (idempotent: `injectHandler` no-ops if it's already there, e.g. via
+ *      legitimate inheritance from a parent run's already-configured
+ *      inheritable list). This is the common case.
+ *   2. Present in `local` only (not yet in `inheritable`) — do NOT inject.
+ *      The local copy alone will fire once for this run; injecting a
+ *      second (inheritable) copy would double-fire it, and there's no need
+ *      to mutate the caller's local value to avoid that — simply not
+ *      adding it to `inheritable` is enough.
+ *   3. Present in BOTH already (e.g. the caller wired the exact same
+ *      instance into both parameters themselves) — leaving both would
+ *      double-fire regardless of what we do to `inheritable`, so as a
+ *      narrow, targeted fallback we remove ONLY our exact instance from
+ *      `local` (array: pure filter, no mutation of caller state; manager:
+ *      its own sanctioned `removeHandler` API) and keep the inheritable
+ *      copy, which is the one that also propagates to descendant runs.
+ *
+ *      EXCEPTION — aliased MANAGER (`inheritable === local`, the exact same
+ *      `BaseCallbackManager` instance passed as BOTH configure args): that
+ *      object has only ONE `.handlers` array and ONE `.inheritableHandlers`
+ *      array. Calling `mgr.removeHandler(handler)` on it removes our handler
+ *      from BOTH, on the ONE shared object — since `inheritable` and `local`
+ *      are the same reference, that strips it from the "inheritable" side
+ *      too, and struct fires ZERO times instead of once. In this case, do
+ *      NOT call `removeHandler` at all: keep the shared manager instance on
+ *      the inheritable side (unmodified — it still carries our handler and
+ *      still propagates to descendant runs) and hand back an empty array for
+ *      `local` so nothing double-delivers. This exception is manager-only:
+ *      array aliasing (the same array reference passed as both parameters)
+ *      has no such hazard — `removeHandlerFromLocal`'s array branch is a
+ *      pure `.filter` that returns a new array without mutating the shared
+ *      one `inheritable` still points at, so the general case below already
+ *      handles it correctly (and preserves any other handlers on that array,
+ *      which blanket-emptying to `[]` would incorrectly drop).
+ */
+function resolveConfigureHandlerArgs(inheritable, local, handler) {
+    const localHasIt = containsHandler(local, handler);
+    if (!localHasIt) {
+        return [injectHandler(inheritable, handler), local];
+    }
+    if (containsHandler(inheritable, handler)) {
+        if (inheritable === local && !Array.isArray(local)) {
+            // Aliased manager instance on both sides — see the EXCEPTION note
+            // above. Keep it on the inheritable side and supply an empty local
+            // value instead of calling removeHandler, which would mutate the one
+            // shared object out from under both parameters.
+            return [inheritable, []];
+        }
+        return [inheritable, removeHandlerFromLocal(local, handler)];
+    }
+    return [inheritable, local];
+}
+/** Identity check: does `v` (array or BaseCallbackManager-shaped) already
+ *  contain our EXACT `handler` instance? */
+function containsHandler(v, handler) {
+    if (Array.isArray(v))
+        return v.some((h) => h === handler);
+    const mgr = v;
+    return !!mgr && Array.isArray(mgr.handlers) && mgr.handlers.some((h) => h === handler);
+}
+/**
+ * Remove our exact `handler` instance from a LOCAL value — used only for
+ * the narrow "present on both sides already" fallback in
+ * `resolveConfigureHandlerArgs`. Array form is a pure filter (returns a new
+ * array; the caller's array is never mutated). Manager form calls the
+ * manager's own `removeHandler` (BaseCallbackManager's sanctioned API,
+ * removes from both `.handlers` and `.inheritableHandlers`) — a targeted,
+ * supported mutation, not raw array splicing.
+ */
+function removeHandlerFromLocal(v, handler) {
+    if (Array.isArray(v))
+        return v.filter((h) => h !== handler);
+    const mgr = v;
+    if (mgr && typeof mgr.removeHandler === "function")
+        mgr.removeHandler(handler);
+    return v;
+}
 function injectHandler(existing, handler) {
     if (existing == null)
         return [handler];
     if (Array.isArray(existing)) {
-        if (existing.some((h) => h?.name === "struct")) {
+        if (existing.some((h) => h === handler))
             return existing;
-        }
         return [...existing, handler];
     }
     // BaseCallbackManager instance: addHandler on it.
     const mgr = existing;
     if (typeof mgr.addHandler === "function" &&
-        !mgr.handlers?.some((h) => h?.name === "struct")) {
+        !mgr.handlers?.some((h) => h === handler)) {
         mgr.addHandler(handler, true);
     }
     return existing;
 }
+// ---------------------------------------------------------------------------
+// Test-only export — mirrors anthropic.ts's `_wrapStreamForTest` pattern.
+// Lets the mutation-guard test drive `wrapIteratorWithSuppression` directly
+// against a synthetic (possibly frozen) stream-like object without needing
+// to mock `@langchain/core`'s BaseChatModel prototype chain.
+// ---------------------------------------------------------------------------
+/** @internal */
+function _wrapIteratorWithSuppressionForTest(streamLike, suppressedSnapshot) {
+    wrapIteratorWithSuppression(streamLike, suppressedSnapshot);
+}
 //# sourceMappingURL=langchain.js.map

package/dist/commonjs/integrations/openai-content.d.ts

@@ -0,0 +1,34 @@
+import type { Part } from "../genai-content.js";
+/** Map a Responses `message.content` (string or list) to spec parts. */
+export declare function messageContentToParts(content: unknown): Part[];
+/** Map ONE Responses `input` item to `[eventName, role, parts]`, or null. */
+export declare function inputItemToEvent(item: unknown): [string, string, Part[]] | null;
+/** Map ONE `response.output` item to the assistant's choice parts. */
+export declare function outputItemToChoiceParts(item: unknown): Part[];
+/** Normalize the `input` kwarg to a list of items (bare string → one user message). */
+export declare function normalizeInput(input: unknown): unknown[];
+/** Spec parts of the LAST `user` message in `input` (for parent propagation). */
+export declare function lastUserParts(input: unknown): Part[] | undefined;
+/** Every function_call `(name, call_id)` from a response.output (for tool linkage). */
+export declare function iterFunctionCalls(output: unknown): Array<[string, string]>;
+/** Derive a raw finish-reason string from a Responses response. */
+export declare function deriveFinishReason(response: unknown): string | undefined;
+/**
+ * True when a Responses response is in a terminal state (generation finished).
+ * A `background: true` request can return non-terminal (`"queued"` /
+ * `"in_progress"`) with no assistant message yet — we must NOT emit a terminal
+ * `gen_ai.choice` / finish reason for those. A response with no status is
+ * treated as terminal so we never silently drop telemetry for the common
+ * synchronous call (or minimal mocks).
+ */
+export declare function isTerminalResponse(response: unknown): boolean;
+/** Map a raw Responses status/derived reason to a spec choice finish reason. */
+export declare function mapChoiceFinishReason(raw: string | undefined): string;
+/** Serialize `input` → spec `gen_ai.input.messages` JSON string. */
+export declare function toInputMessages(input: unknown): string;
+/** Serialize Responses `instructions` → spec `system_instructions` JSON string. */
+export declare function toSystemInstructions(instructions: unknown): string;
+/** Serialize `response.output` → spec `gen_ai.output.messages` JSON string. */
+export declare function toOutputMessages(output: unknown, finishReason: string | undefined): string;
+export declare function safeJsonForTool(obj: unknown): string;
+//# sourceMappingURL=openai-content.d.ts.map