@struct-ai/sdk 0.3.0 → 0.3.17

package/README.md

@@ -55,9 +55,9 @@ await struct.agent({ name: "checkout" }, async () => {
 
 | Library | Hook | Span type | Notes |
 |---|---|---|---|
-| `@anthropic-ai/sdk` | `Messages.prototype.create`, `.stream` | `chat {model}` | Cache-token accounting, streaming with tool-use reconstruction |
+| `@anthropic-ai/sdk` | `Messages.prototype.create`, `.stream` | `chat {model}` | Cache-token accounting, streaming with tool-use reconstruction. Defers to a LangChain `BaseChatModel` call already in progress (e.g. `ChatAnthropic`) so the two integrations don't double-emit — see ownership order below |
 | `@anthropic-ai/bedrock-sdk`, `@anthropic-ai/vertex-sdk` | `Messages.prototype.*` | `chat {model}` | Best-effort, if installed |
-| `@langchain/core` `BaseChatModel` | `.invoke`, `.stream` | `chat {model}` | Skipped when a provider-direct instrumentor is active (e.g. ChatAnthropic + Anthropic patch → single span) |
+| `@langchain/core` `BaseChatModel` | `.invoke`, `.stream` | `chat {model}` | Always owns the `chat` span for `ChatAnthropic`/etc. calls, even when a provider-direct instrumentor (e.g. the Anthropic patch) is also active — the framework layer outranks the provider layer (single span; see [AGENTS.md](./AGENTS.md) §5) |
 | `@langchain/core` `StructuredTool` | `.invoke` | `execute_tool {name}` | Extracts `tool_call_id` from LangChain ToolCall input or pending queue |
 | `@langchain/core` `BaseRetriever` | `.invoke` | `retrieval {name}` | |
 | `@langchain/langgraph` `Pregel` | `.invoke`, `.stream` | `invoke_agent {name}` | Covers `createReactAgent` and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent({ sessionId: convId }, ...)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — the struct-native replacement for LangSmith's `tracing_context(parent=run_tree)`. |
@@ -189,8 +189,8 @@ await struct.agent({ name: "my-agent" }, async () => {
 ```
 
 When you do use `ChatAnthropic` *and* have `@anthropic-ai/sdk` installed,
-the chat span comes from the Anthropic patch (single span); the LangChain
-layer suppresses its duplicate.
+the chat span comes from the LangChain layer (single span); the Anthropic
+patch detects the framework already owns the call and defers.
 
 ## Content capture
 
@@ -264,6 +264,36 @@ Note: `gen_ai.usage.input_tokens` for Anthropic is the TRUE total — we add bac
 `cache_read_input_tokens + cache_creation_input_tokens` (which Anthropic's raw
 response excludes). Matches the Python SDK.
 
+## Development
+
+- `pnpm test` — unit + e2e tests (mocked, no network, no API keys). Excludes
+  `test/live/**`.
+- `pnpm typecheck` — `tsc --noEmit`.
+- `pnpm build` — `tshy`, producing the dual ESM/CJS `dist/`.
+- `pnpm test:live` — the live real-model suite: real `@langchain/anthropic` +
+  real Anthropic API + real `@langchain/langgraph`, verifying emitted spans
+  in-memory (no ingester needed). Skips cleanly (exit 0, all tests skipped)
+  when no API key is present — safe to leave in normal CI.
+
+  To actually run it, point `STRUCT_LIVE_ENV_FILE` at a file containing
+  `ANTHROPIC_API_KEY=...` (dotenv-style `KEY=value` lines; quotes optional).
+  The path is never committed to the repo — it's supplied per-invocation:
+
+  ```bash
+  STRUCT_LIVE_ENV_FILE=/path/to/your/.env pnpm test:live
+  ```
+
+  Uses the cheapest current Anthropic model alias with small `max_tokens`
+  budgets — a handful of real API calls per run, not dozens.
+- `pnpm test:parity` — the cross-language conformance harness: drives the
+  same canonical agent topology through both this SDK and `struct-sdk-python`
+  and diffs their normalized span shapes, failing (non-zero exit) on any
+  divergence. No network calls or API keys required.
+
+See [AGENTS.md](./AGENTS.md) for the full set of governance rules (fault
+isolation, OTel citizenship, semconv conformance, the release-version-bump
+gate) that apply to any change in this package.
+
 ## Troubleshooting
 
 - **Spans missing after instrumenting:** Import `@struct-ai/sdk` (or `struct.init()`)
@@ -273,10 +303,20 @@ response excludes). Matches the Python SDK.
 - **No logs appearing:** `LogRecord`s only emit when `sdk.emitEvents` is true
   (`EventOnly` or `SpanAndEvent` capture mode, which is the default). If you set
   `captureContent: false` you disable them.
-- **Duplicate chat spans:** The LangChain integration suppresses its own chat
-  span when a provider-direct patch is active (e.g. ChatAnthropic calls through
-  to `@anthropic-ai/sdk`, which emits its own `chat` span). If you see doubles,
-  confirm both integrations are auto-instrumenting (check `struct.initialized`).
+- **Duplicate chat spans:** Ownership of the `chat` span is fixed (manual >
+  framework > provider — see [AGENTS.md](./AGENTS.md) §5): when you call
+  `ChatAnthropic.invoke()`/`.stream()`, the LangChain integration always owns
+  the `chat` span (`handleChatModelStart` in `langchain-callback.ts`). It runs
+  the underlying provider call inside an internal scope
+  (`suppressGenAi: true`) that the direct `@anthropic-ai/sdk` patch checks via
+  `isGenAiSuppressed()` — when set, the provider patch defers and emits
+  nothing, so only the LangChain-owned span is produced. If you see doubles,
+  the two integrations are likely observing different `@anthropic-ai/sdk`
+  module instances (common with pnpm hoisting a nested copy under
+  `@langchain/anthropic`), so the provider patch never sees the suppression
+  scope set by the framework layer; confirm both integrations are
+  auto-instrumenting the SAME module instance (check `struct.initialized` and
+  your lockfile's dedupe of `@anthropic-ai/sdk`).
 - **Subagent in a different trace / missing from parent's "Subagents" list:**
   If you invoke a nested agent (`subagent.invoke(...)`) from inside a tool body,
   define the outer tool with `tool(func, { name, description, schema })` from

package/dist/commonjs/context.d.ts

@@ -4,12 +4,38 @@ export interface StructContext {
     conversationId?: string;
     agentSpan?: Span;
     pendingToolCalls?: Record<string, string[]>;
+    /**
+     * When true, a framework-layer integration (e.g. LangChain's
+     * BaseChatModel.generate/.stream) already owns the chat span for the call
+     * in progress. Provider-SDK patches (anthropic.ts) check this and skip
+     * emitting their own chat span to avoid a duplicate.
+     */
+    suppressGenAi?: boolean;
+    /**
+     * Set by `struct.agent()` while its body is running. Signals ownership:
+     * when the LangChain callback handler sees a TOP-LEVEL chain start (no
+     * parentRunId) while this is set, the manual `struct.agent()` call already
+     * owns the `invoke_agent` span for this run — the handler must not emit a
+     * duplicate ("twin") span, only register the run so descendants parent
+     * under the manual span. Parity: python `_manual_agent_active` contextvar
+     * (core.py:64-68).
+     */
+    manualAgentSpan?: Span;
 }
 export declare function getStore(): StructContext | undefined;
 export declare function getSessionId(): string | undefined;
 export declare function getConversationId(): string | undefined;
 export declare function getAgentSpan(): Span | undefined;
+/**
+ * The manually-created `struct.agent()` span for the currently-running
+ * scope, if any. Read by the LangChain callback handler to detect
+ * "manual struct.agent() wraps a top-level LangChain chain" and suppress
+ * the twin `invoke_agent` span it would otherwise emit.
+ */
+export declare function getManualAgentSpan(): Span | undefined;
 export declare function getPendingToolCalls(): Record<string, string[]> | undefined;
+/** True when a framework layer (e.g. LangChain) already owns the chat span. */
+export declare function isGenAiSuppressed(): boolean;
 export declare function runWithContext<T>(patch: Partial<StructContext>, fn: () => T): T;
 export declare function ensurePendingToolCallsSlot(): Record<string, string[]>;
 /**

package/dist/commonjs/context.js

@@ -4,7 +4,9 @@ exports.getStore = getStore;
 exports.getSessionId = getSessionId;
 exports.getConversationId = getConversationId;
 exports.getAgentSpan = getAgentSpan;
+exports.getManualAgentSpan = getManualAgentSpan;
 exports.getPendingToolCalls = getPendingToolCalls;
+exports.isGenAiSuppressed = isGenAiSuppressed;
 exports.runWithContext = runWithContext;
 exports.ensurePendingToolCallsSlot = ensurePendingToolCallsSlot;
 exports.popPendingToolCallId = popPendingToolCallId;
@@ -26,9 +28,22 @@ function getConversationId() {
 function getAgentSpan() {
     return als.getStore()?.agentSpan;
 }
+/**
+ * The manually-created `struct.agent()` span for the currently-running
+ * scope, if any. Read by the LangChain callback handler to detect
+ * "manual struct.agent() wraps a top-level LangChain chain" and suppress
+ * the twin `invoke_agent` span it would otherwise emit.
+ */
+function getManualAgentSpan() {
+    return als.getStore()?.manualAgentSpan;
+}
 function getPendingToolCalls() {
     return als.getStore()?.pendingToolCalls;
 }
+/** True when a framework layer (e.g. LangChain) already owns the chat span. */
+function isGenAiSuppressed() {
+    return als.getStore()?.suppressGenAi === true;
+}
 function runWithContext(patch, fn) {
     const current = als.getStore() ?? {};
     const next = { ...current, ...patch };
@@ -80,7 +95,11 @@ function pushPendingToolCalls(pairs) {
 /** Snapshot the store for wrapping async iterators. */
 function snapshotStore() {
     const store = als.getStore();
-    return store ? { ...store } : undefined;
+    if (!store)
+        return undefined;
+    if (!store.pendingToolCalls)
+        store.pendingToolCalls = {}; // materialize BEFORE copying so the queue object is shared by reference
+    return { ...store };
 }
 function runWithStore(store, fn) {
     if (!store)

package/dist/commonjs/core.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StructSDK = exports.firstFailureLogged = exports.DEFAULT_ENDPOINT = void 0;
 exports.safe = safe;
-const node_crypto_1 = require("node:crypto");
 const api_1 = require("@opentelemetry/api");
 const exporter_logs_otlp_proto_1 = require("@opentelemetry/exporter-logs-otlp-proto");
 const exporter_trace_otlp_proto_1 = require("@opentelemetry/exporter-trace-otlp-proto");
@@ -14,6 +13,7 @@ const context_js_1 = require("./context.js");
 const index_js_1 = require("./integrations/index.js");
 const semconv_js_1 = require("./semconv.js");
 const truncation_js_1 = require("./truncation.js");
+const version_js_1 = require("./version.js");
 exports.DEFAULT_ENDPOINT = "https://ingest.struct.ai";
 const LOG_ENABLED = process.env.STRUCT_SDK_LOG === "1";
 const defaultInternalLogger = {
@@ -232,13 +232,13 @@ class StructSDK {
         if (!this._tracerProvider) {
             throw new Error("Call struct.init() before using the SDK");
         }
-        return this._tracerProvider.getTracer(name);
+        return this._tracerProvider.getTracer(name, version_js_1.SDK_VERSION);
     }
     getLogger(name = "struct-sdk") {
         if (!this._loggerProvider) {
             throw new Error("Call struct.init() before using the SDK");
         }
-        return this._loggerProvider.getLogger(name);
+        return this._loggerProvider.getLogger(name, version_js_1.SDK_VERSION);
     }
     getInternalLogger() {
         return this._internalLogger;
@@ -306,8 +306,7 @@ class StructSDK {
             return await fn();
         }
         const agentName = options.name;
-        const sessionId = options.sessionId ?? (0, node_crypto_1.randomUUID)();
-        const parentSessionId = (0, context_js_1.getSessionId)();
+        const explicitSessionId = options.sessionId;
         const tracer = this.getTracer("struct-sdk");
         // Parent the new agent span on the nearest enclosing agent span (if
         // any) so nested `struct.agent()` / `struct.tool()` calls build a
@@ -316,16 +315,68 @@ class StructSDK {
         // nothing to hang off. We do NOT rely on the global OTel context
         // manager being installed — the SDK manages its own parent chain via
         // StructContext ALS to stay neutral in multi-tenant OTel setups.
-        const parentSpan = (0, context_js_1.getAgentSpan)();
-        const parentCtx = parentSpan
-            ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
-            : api_1.context.active();
+        //
+        // Captured BEFORE we resolve/overwrite anything below — mirrors
+        // python's `enclosing_session_id` / `enclosing_agent_span` capture at
+        // core.py:625-626. Used to (1) resolve this agent's own session id via
+        // ambient inheritance, (2) detect break-out, and (3) decide whether to
+        // stamp `struct.agent.parent_session_id`.
+        const enclosingSessionId = (0, context_js_1.getSessionId)();
+        const enclosingAgentSpan = (0, context_js_1.getAgentSpan)();
+        // ── Resolve sessionId (REVISION R1 grouping model) ──────────────────
+        // Resolution order: explicit caller arg > ambient (enclosing agent) >
+        // session-less. We never fabricate a uuid — a caller that omits
+        // sessionId with no enclosing agent gets a SESSION-LESS run (no
+        // `gen_ai.conversation.id` attribute at all). Ports core.py:628-644
+        // exactly (`self._session_id = ""` there is `undefined` here).
+        const sessionId = explicitSessionId !== undefined
+            ? explicitSessionId
+            : enclosingSessionId !== undefined
+                ? enclosingSessionId
+                : undefined;
+        // ── Break-out detection (spawned-by Link) ───────────────────────────
+        // Caller supplied an EXPLICIT session id that differs from the
+        // enclosing agent's session AND there IS an enclosing Struct agent
+        // span in scope. This agent starts a fresh ROOT trace (no OTel
+        // parent) and carries a causal Link back to the enclosing agent's
+        // span context. Ports struct_sdk.core._AgentContext._start_span's
+        // `break_out` branch (struct-sdk-python/src/struct_sdk/core.py:651-656)
+        // exactly.
+        const breakOut = explicitSessionId !== undefined &&
+            enclosingSessionId !== undefined &&
+            explicitSessionId !== enclosingSessionId &&
+            enclosingAgentSpan !== undefined;
+        // ── Parentage: PURE NEST (Option D) ─────────────────────────────────
+        // A non-break-out agent nests under whatever OTel span is active — the
+        // host's ambient context — like every peer LLM/agent SDK. We do NOT
+        // second-guess the active span or unilaterally re-root: the old
+        // `foreignRoot` heuristic detached from ANY active span and so ripped
+        // agents out of legitimate host request traces. Cross-conversation
+        // grouping is carried by gen_ai.conversation.id, never by trace
+        // parentage. A runtime that propagates a stale/unwanted span across a
+        // boundary (e.g. our own persistent_agent Temporal workflow span) clears
+        // it at the SOURCE, never here. (A provenance-gated detach — re-root only
+        // a leaked Struct-OWNED span — is a documented, deferred follow-up.)
+        let startContext;
+        let links;
+        if (breakOut) {
+            // Explicit different session under another Struct agent: fresh ROOT
+            // trace + a spawned-by Link. The one deliberate, opt-in re-root.
+            // enclosingAgentSpan is guaranteed defined by the breakOut guard above.
+            links = [{ context: enclosingAgentSpan.spanContext() }];
+            startContext = api_1.ROOT_CONTEXT;
+        }
+        else {
+            startContext = enclosingAgentSpan
+                ? api_1.trace.setSpan(api_1.context.active(), enclosingAgentSpan)
+                : api_1.context.active();
+        }
         // Span creation itself can fail (custom tracer, broken context). If it
         // does, fall through to running `fn` directly so the user's call
         // always runs uninstrumented rather than blowing up on telemetry.
         let span;
         safe(() => {
-            span = tracer.startSpan(`invoke_agent ${agentName}`, { kind: api_1.SpanKind.INTERNAL }, parentCtx);
+            span = tracer.startSpan(`invoke_agent ${agentName}`, { kind: api_1.SpanKind.INTERNAL, links }, startContext);
         }, "agent.start_span", this._internalLogger);
         if (span === undefined) {
             return await fn();
@@ -346,17 +397,24 @@ class StructSDK {
                 startedSpan.setAttribute(semconv_js_1.GEN_AI.AGENT_VERSION, options.version);
             }
             // gen_ai.conversation.id is the spec-blessed name for
-            // session/thread id.
-            startedSpan.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
-            // Always set parent_session_id when there's a parent agent — even
-            // when the value matches sessionId (which happens when a nested
-            // ``struct.agent()`` inherits ambient session). The attribute is
-            // structural ("this agent has a parent agent"), not a uniqueness
-            // marker. The UI uses it to render an inline subagent expansion
-            // under the triggering call (vs the drill-in flow used when
-            // sessionIds differ).
-            if (parentSessionId) {
-                startedSpan.setAttribute(semconv_js_1.STRUCT.AGENT_PARENT_SESSION_ID, parentSessionId);
+            // session/thread id. Omitted when session-less (never fabricated).
+            // Ports core.py:723-725 (`if self._session_id:`) exactly.
+            if (sessionId) {
+                startedSpan.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+            }
+            // ``struct.agent.parent_session_id`` is a SPAWNED-BY marker — set it
+            // ONLY when this agent has an enclosing session that DIFFERS from
+            // its own resolved session id. An inline nested agent (same session
+            // as the enclosing agent, whether by explicit same id or ambient
+            // inheritance) already has its parent relationship encoded by the
+            // OTel span tree (ParentSpanId) — stamping
+            // parent_session_id === own sessionId would be self-referential
+            // noise. Structure comes from the tree/Link, not this attr
+            // (Link-canonical decision). Ports core.py:736-745 exactly (both
+            // the break-out and the "legacy" differing-id-no-span branches
+            // collapse to this one condition).
+            if (enclosingSessionId !== undefined && enclosingSessionId !== sessionId) {
+                startedSpan.setAttribute(semconv_js_1.STRUCT.AGENT_PARENT_SESSION_ID, enclosingSessionId);
             }
             if (options.metadata) {
                 for (const [key, value] of Object.entries(options.metadata)) {
@@ -369,6 +427,7 @@ class StructSDK {
             conversationId: sessionId,
             agentSpan: startedSpan,
             pendingToolCalls: {},
+            manualAgentSpan: startedSpan,
         }, async () => {
             const activeCtx = api_1.trace.setSpan(api_1.context.active(), startedSpan);
             try {

package/dist/commonjs/events.js

@@ -53,7 +53,7 @@ function emitAnthropicMessageEvents(logger, messages, system) {
                 parts: (0, truncation_js_1.truncateParts)(parts),
             }),
             extraAttrs: {
-                [semconv_js_1.GEN_AI.SYSTEM]: "anthropic",
+                [semconv_js_1.GEN_AI.PROVIDER_NAME]: "anthropic",
                 [semconv_js_1.GEN_AI.MESSAGE_INDEX]: msgIndex,
             },
         });
@@ -71,7 +71,7 @@ function emitAnthropicMessageEvents(logger, messages, system) {
             eventName,
             payload: (0, truncation_js_1.safeJsonStringify)({ role, parts: (0, truncation_js_1.truncateParts)(parts) }),
             extraAttrs: {
-                [semconv_js_1.GEN_AI.SYSTEM]: "anthropic",
+                [semconv_js_1.GEN_AI.PROVIDER_NAME]: "anthropic",
                 [semconv_js_1.GEN_AI.MESSAGE_INDEX]: msgIndex,
             },
         });
@@ -96,7 +96,7 @@ function emitAnthropicChoiceEvent(logger, contentBlocks, stopReason) {
         eventName: semconv_js_1.EVENT_NAMES.CHOICE,
         payload,
         extraAttrs: {
-            [semconv_js_1.GEN_AI.SYSTEM]: "anthropic",
+            [semconv_js_1.GEN_AI.PROVIDER_NAME]: "anthropic",
         },
     });
 }

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

@@ -22,6 +22,8 @@ export declare function patch(sdk: StructSDK): Promise<void>;
 export declare function unpatch(): Promise<void>;
 type CreateMethod = (this: unknown, params: CreateParams, opts?: unknown) => unknown;
 type StreamMethod = (this: unknown, params: CreateParams, opts?: unknown) => unknown;
+export declare function wrapCreate(original: CreateMethod): CreateMethod;
+export declare function wrapStream(original: StreamMethod): StreamMethod;
 /** @internal */
 export type _PatchContextForTest = PatchContext;
 /** @internal */