@struct-ai/sdk 0.3.0 → 0.4.2

package/dist/esm/integrations/index.js

@@ -11,6 +11,14 @@ const INTEGRATIONS = [
             await mod.patch(sdk);
         },
     },
+    {
+        name: "openai",
+        probe: () => import("openai"),
+        apply: async (sdk) => {
+            const mod = await import("./openai.js");
+            await mod.patch(sdk);
+        },
+    },
     {
         name: "langchain",
         probe: () => import("@langchain/core/language_models/chat_models"),

package/dist/esm/integrations/langchain-callback.d.ts

@@ -36,29 +36,37 @@ interface LLMResultLike {
  *
  * - `gen_ai.conversation.id` is the OTel GenAI-spec conversation identifier
  *   and Struct's UI grouping unit — one value = one entry in the sessions
- *   list. For the top-level agent we auto-derive it from thread_id, so a
- *   stable thread_id across multi-turn chats collapses into one session.
+ *   list. It is one id per run: every span belonging to a top-level agent
+ *   invocation AND any subagents it spawns shares the SAME
+ *   `gen_ai.conversation.id`, so the whole call tree collapses into one
+ *   session (OTel's `conversation.id` models "the thread", not "the
+ *   agent").
  *
- * For SUBAGENTS (an agent invoked from inside another's tool body) we
- * deliberately assign a DIFFERENT conversation.id — either from the subagent's
- * own thread_id if supplied, or a fresh UUID. The resulting session is
- * linked back to the outer agent's session via the
- * `struct.agent.parent_session_id` span attribute (what powers "Spawned
- * by" / subagent navigation in the UI). Without this split the subagent's
- * spans would collapse into the outer session, burying delegation.
+ * SUBAGENTS (an agent invoked from inside another's tool body) therefore
+ * INHERIT the parent run's `gen_ai.conversation.id` rather than minting
+ * their own. Structural linkage — "this invoke_agent span was spawned by
+ * that one" — is carried separately via the `struct.agent.parent_session_id`
+ * span attribute (what powers "Spawned by" / subagent navigation in the
+ * UI), not by giving the subagent a different session id.
  *
- * LangChain quirk (handled automatically): when `agent.invoke(...)` runs
- * nested inside a parent call, LangChain's config-merge inherits the
- * parent's `metadata.thread_id` onto the child even if its config provided
- * a different one. We detect that by comparing against the nearest agent
- * ancestor's session; if they match, treat it as "inherited, not
- * user-intended" and assign a fresh UUID to the subagent.
+ * A subagent MAY still be started with its own explicit thread_id (e.g. a
+ * LangGraph checkpoint key distinct from the parent's). When that happens
+ * we preserve it as `struct.agent.thread_id` for observability, but it does
+ * NOT split the session — `gen_ai.conversation.id` still follows the
+ * parent, because the grouping unit is the run, not the checkpoint.
+ *
+ * Chat / tool / retriever spans NEVER fabricate a conversation id. If no
+ * ancestor run, metadata thread_id, or ambient session supplies one, the
+ * span (and any log events it emits) simply omits `gen_ai.conversation.id`
+ * — an orphan span with no session is preferable to a fake one that can
+ * never be joined to anything else.
  *
  * End-user guidance:
  *   - Use thread_id per conversation; multi-turn chats reuse it.
- *   - For a subagent call, pass a DIFFERENT thread_id (or omit it and let
- *     LangGraph generate one). Each subagent then surfaces as its own
- *     session in the UI, linked back via parent_session_id.
+ *   - Subagents inherit the enclosing run's session automatically; you
+ *     don't need to (and shouldn't) pass a different thread_id purely to
+ *     separate them — use `struct.agent.parent_session_id` /
+ *     "Spawned by" navigation in the UI instead.
  */
 export declare class StructCallbackHandler {
     private readonly sdk;
@@ -83,6 +91,54 @@ export declare class StructCallbackHandler {
     readonly raiseError = false;
     private readonly runs;
     private readonly internalLogger;
+    /**
+     * Index of live `execute_tool` spans by their `langgraph_checkpoint_ns`,
+     * keyed to an ARRAY of currently-live spans rather than a single span.
+     *
+     * The re-parenting trick this supports: LangGraph stamps a namespace
+     * (`tools:<uuid>`) on a tool-call branch AND the same value on the
+     * sub-agent graph that tool triggers, so a sub-agent's chain-start (whose
+     * `parentRunId` points at the parent GRAPH — a sibling of the tool in the
+     * run tree, not the tool itself) can look itself up by ns and re-parent
+     * under its triggering tool call instead of landing as a sibling.
+     *
+     * That assumption — "ns is unique even across parallel same-named tool
+     * calls" — is FALSE on every `@langchain/langgraph` release checked, up
+     * to and including the latest published as of this writing (`1.4.7`, and
+     * confirmed byte-identical on `main` at HEAD): `ToolNode.run()`
+     * (`0.2.x`: `dist/prebuilt/tool_node.js`; `1.x`: moved to
+     * `libs/langgraph-core/src/prebuilt/tool_node.ts`) invokes every parallel
+     * `tool_call` within one step (`Promise.all(...map(call => this.runTool(
+     * call, config, input)))`) with the exact SAME `config` object reference
+     * — no per-call config cloning, no call-index-derived namespace — so
+     * `config.metadata.langgraph_checkpoint_ns` collides across parallel
+     * same-named tool calls in that step on every version, not just 0.2.x.
+     * (One opt-in exception: routing tool calls through LangGraph `Send`
+     * objects, added ~PR #1498, gets Pregel's normal per-task namespacing —
+     * but `createReactAgent`/`ToolNode`'s default path does not use it.) If a
+     * future release fixes this, update this comment with the version and
+     * consider re-enabling direct pairing unconditionally on it. (Python's
+     * `langgraph.prebuilt.tool_node.ToolNode._afunc` does not have this
+     * problem: it calls `get_config_list(config, len(tool_calls))` to build a
+     * genuinely per-call config before fanning out.)
+     *
+     * An array-per-ns (instead of one span per ns) makes the collision
+     * DETECTABLE instead of silently last-write-wins: at consume time
+     * (`handleChainStart`'s sub-agent lookup), exactly one live candidate for
+     * the ns is an unambiguous pair (re-parent as before); zero or more than
+     * one live candidates means we cannot tell which tool call the sub-agent
+     * actually belongs to, so we deliberately do NOT re-parent — the
+     * sub-agent falls back to the normal `resolveParent` chain (renders as a
+     * graph sibling: degraded, but never wrong). Cross-wiring two unrelated
+     * spans is worse than under-wiring one. Entries are evicted (their
+     * specific span removed, not the whole ns bucket) in
+     * `handleToolEnd`/`handleToolError` so the map never grows unboundedly and
+     * so a tool call that finishes frees its slot for ambiguity resolution.
+     * Parity: python `_tool_spans_by_ns` / `_checkpoint_ns` (python's
+     * `langgraph` >= 1.2.0 does not need this same guard, since its ns values
+     * never collide — see above).
+     */
+    private readonly checkpointNsToolSpans;
     constructor(sdk: StructSDK, tracer: Tracer, logger: Logger | undefined);
     handleChainStart: (chain: Serialized, inputs: unknown, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string) => void;
     handleChainEnd: (_outputs: unknown, runId: string) => void;
@@ -92,6 +148,14 @@ export declare class StructCallbackHandler {
     handleLLMEnd: (output: LLMResultLike, runId: string) => void;
     handleLLMError: (err: Error, runId: string) => void;
     handleToolStart: (tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
+    /**
+     * Remove one specific span from its checkpoint-ns bucket (not the whole
+     * bucket) — a sibling parallel tool call under the same colliding ns may
+     * still be live and must keep its own candidate-list membership. Deletes
+     * the ns key entirely once its bucket is empty so the map never grows
+     * unboundedly.
+     */
+    private evictCheckpointNsSpan;
     handleToolEnd: (output: unknown, runId: string) => void;
     handleToolError: (err: Error, runId: string) => void;
     handleRetrieverStart: (retriever: Serialized, query: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
@@ -100,7 +164,11 @@ export declare class StructCallbackHandler {
     private resolveParent;
     /**
      * Conversation-id resolution for chat/tool/retriever spans — INHERIT from
-     * the parent agent so everything rolls up under one gen_ai.conversation.id.
+     * the parent run so everything rolls up under one gen_ai.conversation.id.
+     * Returns `undefined` (never fabricates a UUID) when no ancestor run,
+     * metadata thread_id, or ambient session supplies one — an orphan span
+     * with no conversation.id is preferable to a fake one that can never be
+     * joined to anything else (parity: python `_resolve_session_id`).
      */
     private resolveSessionId;
     /**
@@ -117,18 +185,105 @@ export declare class StructCallbackHandler {
      */
     private inheritedAgentSessionId;
     /**
-     * Conversation-id resolution for AGENT spans — each agent invocation gets
-     * its own gen_ai.conversation.id. We deliberately do NOT inherit from the
-     * parent run, so subagents surface as separate entries in the sessions
-     * list. Parent linkage is preserved via `struct.agent.parent_session_id`.
+     * Nearest ``invoke_agent`` ancestor SPAN — O(1) lookup, mirrors
+     * ``inheritedAgentSessionId`` for the span pointer itself. Cached at every
+     * RunState creation so descendants (and prompt propagation) can reach the
+     * ancestor without walking a parent chain we don't retain.
      *
-     * LangChain inherits `metadata.thread_id` from the parent invoke's config
-     * when a nested invoke runs inside it (even if the child config supplied
-     * its own). We detect that inheritance by comparing against the parent's
-     * resolved session and ignore the inherited value.
+     * Unlike ``inheritedAgentSessionId``, a missing ``parentRunId`` falls back
+     * to the ambient `getAgentSpan()` (matching `resolveParent`'s top-level
+     * fallback) rather than `undefined` — a run with no LangChain parent may
+     * still be nested inside a manually-created `struct.agent()` span.
+     * Parity: python `_inherited_agent_span`.
+     */
+    private inheritedAgentSpan;
+    /**
+     * Resolve the pending-tool-call queue OBJECT a run should push/pop
+     * against for `gen_ai.tool.call.id` autofill, per `RunState.toolCallQueue`'s
+     * doc comment.
+     *
+     * PINNED AT THE RUN-TREE ROOT, INHERITED DOWN AS THE SAME OBJECT
+     * REFERENCE — this is the crux of the design, and it is the OBJECT that
+     * must be pinned, not merely a manual-vs-bare boolean. Whenever a parent
+     * run is known (`parentRunId` resolves to a live `RunState`), we copy its
+     * `toolCallQueue` reference VERBATIM rather than re-deriving anything from
+     * the live ALS frame. Only a run with no resolvable parent (a genuine
+     * root, or an orphaned `parentRunId` whose `RunState` was never
+     * registered) consults the live `getManualAgentSpan()` signal — and even
+     * then, only ONCE, at that run's creation.
+     *
+     * Why the OBJECT, not just a boolean: a descendant run's OWN callback can
+     * fire in a lost or foreign ALS frame — the LangChain FRAMEWORK layer
+     * (`langchain.ts`'s `BaseChatModel.generate`/`.stream` patch) opens its
+     * own short-lived ALS scope (`runWithContext({ suppressGenAi: true },
+     * fn)`) around each chat completion, entirely independent of any customer
+     * `struct.agent()` call; more generally, LangGraph's internal scheduling
+     * can run a node's callback outside the async context that originally
+     * held the manual scope. A design that pins only a manual-vs-bare
+     * ownership BOOLEAN but still routes the actual push (`handleLLMEnd`) and
+     * pop (`handleToolStart`) through the ALS-reading
+     * `pushPendingToolCalls`/`popPendingToolCallId` helpers (context.ts) is
+     * still broken: those helpers read whatever `pendingToolCalls` object is
+     * on the CURRENT frame, so a push in one lost/foreign frame and a pop in a
+     * DIFFERENT lost/foreign frame silently disagree, even though both frames
+     * correctly resolved the same boolean. Operating directly on the
+     * RunState-pinned `toolCallQueue` object sidesteps the ALS frame entirely
+     * for both operations: whatever object the root observed is what the
+     * whole run tree pushes into and pops from, regardless of ALS frame state
+     * at either callback.
+     *
+     * Three cases:
+     *   1. `parentRunId` resolves to a registered parent `RunState` — inherit
+     *      `toolCallQueue` from it verbatim (decided once at the tree root) —
+     *      UNLESS a NEW manual scope began mid-tree (see FIX F below).
+     *   2. No parent (root, or an orphaned `parentRunId`) AND a MANUAL
+     *      `struct.agent()` scope is live right now (`getManualAgentSpan()`
+     *      set) — capture `getPendingToolCalls()`, the SAME object
+     *      `struct.agent()` seeded onto the ALS store and that manual
+     *      `struct.tool()` calls pop from via `popPendingToolCallId`
+     *      (context.ts). Captured IN-FRAME here (this callback necessarily
+     *      runs inside the live manual scope), so the RunState-pinned
+     *      reference and the ALS store's `pendingToolCalls` stay identical.
+     *   3. No parent AND no manual scope — this run IS the top of a bare run
+     *      tree; mint a fresh queue `{}`.
+     *
+     * Self-audit round 5 (FIX F): case 1's "inherit verbatim" is only correct
+     * when the parent's queue was captured under the SAME manual ownership
+     * that is live right now. A NESTED manual `struct.agent()` — opened from
+     * inside a tool body, whose own LangChain graph LangChain threads as a
+     * CHILD of the outer run tree, parented on a REAL tool span rather than
+     * reaching the manual span through skipped chains (so it never reaches
+     * the suppressed-twin branch in `handleChainStart`) — would otherwise
+     * silently inherit the OUTER run's
+     * queue object, even though the CURRENT ambient `getManualAgentSpan()` is
+     * the INNER agent's own (different) span and the inner agent's own
+     * `pendingToolCalls` (a fresh object seeded by that inner `struct.agent()`
+     * call) is what its descendants actually push/pop against. Detect this by
+     * comparing the live `getManualAgentSpan()` against the PARENT run's
+     * `queueManualSpan` (the manual span that owned the parent's queue): if
+     * they differ and the live one is truthy, a new manual scope has begun —
+     * re-capture `getPendingToolCalls()` fresh, exactly like case 2. When they
+     * match (including both `undefined`, i.e. bare on both sides — preserves
+     * the F2 frame-independence fix, where a merely lost/foreign ALS frame
+     * reads as `undefined` and must NOT trigger a spurious re-capture),
+     * inherit verbatim as before.
+     */
+    private resolveQueueOwnership;
+    /**
+     * Conversation-id resolution for AGENT spans — INHERIT from the parent
+     * run first, so a subagent shares its outer agent's gen_ai.conversation.id
+     * (one id per run; parity: python `_resolve_agent_session_id`). Only when
+     * there's no parent session do we fall back to metadata.thread_id, the
+     * ambient session, or — as a last resort, since agent spans should always
+     * have a coherent id — a fresh UUID. A subagent's own divergent thread_id
+     * (if any) is preserved separately as `struct.agent.thread_id`; see the
+     * caller in `handleChainStart`.
      */
     private resolveAgentSessionId;
     private propagateUserPrompt;
 }
+declare function detectProviderFromSerialized(llm: Serialized): string;
+/** @internal */
+export declare const _detectProviderFromSerializedForTest: typeof detectProviderFromSerialized;
 export {};
 //# sourceMappingURL=langchain-callback.d.ts.map