@struct-ai/sdk 0.2.1 → 0.3.17

package/dist/esm/core.js

@@ -1,8 +1,7 @@
-import { randomUUID } from "node:crypto";
-import { context as otelContext, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context as otelContext, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, } from "@opentelemetry/sdk-logs";
 import { BatchSpanProcessor, NodeTracerProvider, } from "@opentelemetry/sdk-trace-node";
 import { ContentCaptureMode, captureContentFor, emitEventsFor, emitSpanContentFor, } from "./content-capture.js";
@@ -10,6 +9,7 @@ import { getAgentSpan, getSessionId, popPendingToolCallId, runWithContext, } fro
 import { autoInstrument } from "./integrations/index.js";
 import { ERROR_TYPE, GEN_AI, STRUCT, } from "./semconv.js";
 import { safeJsonStringify } from "./truncation.js";
+import { SDK_VERSION } from "./version.js";
 export const DEFAULT_ENDPOINT = "https://ingest.struct.ai";
 const LOG_ENABLED = process.env.STRUCT_SDK_LOG === "1";
 const defaultInternalLogger = {
@@ -33,6 +33,43 @@ const defaultInternalLogger = {
  * so consumers cannot reach it via the package's public API surface.
  */
 export const firstFailureLogged = new Set();
+/**
+ * OTel SDK 2.x providers accept processors only at construction time —
+ * `addSpanProcessor` / `addLogRecordProcessor` no longer exist on the
+ * providers. These fan-outs are registered at construction and delegate to a
+ * mutable list, preserving the SDK's test-only `addSpanProcessor` /
+ * `addLogRecordProcessor` hooks.
+ */
+class FanoutSpanProcessor {
+    delegates = [];
+    onStart(...args) {
+        for (const p of this.delegates)
+            p.onStart(...args);
+    }
+    onEnd(...args) {
+        for (const p of this.delegates)
+            p.onEnd(...args);
+    }
+    forceFlush() {
+        return Promise.all(this.delegates.map((p) => p.forceFlush())).then(() => undefined);
+    }
+    shutdown() {
+        return Promise.all(this.delegates.map((p) => p.shutdown())).then(() => undefined);
+    }
+}
+class FanoutLogRecordProcessor {
+    delegates = [];
+    onEmit(...args) {
+        for (const p of this.delegates)
+            p.onEmit(...args);
+    }
+    forceFlush() {
+        return Promise.all(this.delegates.map((p) => p.forceFlush())).then(() => undefined);
+    }
+    shutdown() {
+        return Promise.all(this.delegates.map((p) => p.shutdown())).then(() => undefined);
+    }
+}
 /**
  * Run `fn`; swallow any exception. The first failure per `site` logs at WARN
  * (with the error attached); subsequent failures at the same site log at
@@ -60,6 +97,8 @@ export class StructSDK {
     _initialized = false;
     _tracerProvider;
     _loggerProvider;
+    _spanFanout;
+    _logFanout;
     _ingestKey = "";
     _endpoint = DEFAULT_ENDPOINT;
     _contentCapture = ContentCaptureMode.EventOnly;
@@ -133,26 +172,31 @@ export class StructSDK {
                 maxExportBatchSize: 100,
                 scheduledDelayMillis: 1000,
             });
-            const resource = new Resource({
+            const resource = resourceFromAttributes({
                 "service.name": serviceName,
                 "service.version": serviceVersion,
                 "deployment.environment": environment,
             });
+            this._spanFanout = new FanoutSpanProcessor();
             this._tracerProvider = new NodeTracerProvider({
                 resource,
-                spanProcessors: [spanProcessor],
+                spanProcessors: [spanProcessor, this._spanFanout],
             });
             const logExporter = new OTLPLogExporter({
                 url: `${this._endpoint}/v1/logs`,
                 headers,
             });
-            const logProcessor = new BatchLogRecordProcessor(logExporter, {
+            const logProcessor = new BatchLogRecordProcessor({
+                exporter: logExporter,
                 maxQueueSize: 10000,
                 maxExportBatchSize: 100,
                 scheduledDelayMillis: 1000,
             });
-            this._loggerProvider = new LoggerProvider({ resource });
-            this._loggerProvider.addLogRecordProcessor(logProcessor);
+            this._logFanout = new FanoutLogRecordProcessor();
+            this._loggerProvider = new LoggerProvider({
+                resource,
+                processors: [logProcessor, this._logFanout],
+            });
             this._initialized = true;
             this._shutdownHook = () => {
                 void this.shutdown();
@@ -172,6 +216,8 @@ export class StructSDK {
             this._initialized = false;
             this._tracerProvider = undefined;
             this._loggerProvider = undefined;
+            this._spanFanout = undefined;
+            this._logFanout = undefined;
             this._shutdownHook = undefined;
             this._readyPromise = Promise.resolve();
             return;
@@ -182,24 +228,24 @@ export 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, 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, SDK_VERSION);
     }
     getInternalLogger() {
         return this._internalLogger;
     }
     /** Test-only: attach a custom span processor to the internal provider. */
     addSpanProcessor(processor) {
-        this._tracerProvider?.addSpanProcessor(processor);
+        this._spanFanout?.delegates.push(processor);
     }
     /** Test-only: attach a custom log record processor. */
     addLogRecordProcessor(processor) {
-        this._loggerProvider?.addLogRecordProcessor(processor);
+        this._logFanout?.delegates.push(processor);
     }
     /**
      * Shut down the SDK and flush pending telemetry.
@@ -256,8 +302,7 @@ export class StructSDK {
             return await fn();
         }
         const agentName = options.name;
-        const sessionId = options.sessionId ?? randomUUID();
-        const parentSessionId = 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
@@ -266,16 +311,68 @@ export 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 = getAgentSpan();
-        const parentCtx = parentSpan
-            ? trace.setSpan(otelContext.active(), parentSpan)
-            : otelContext.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 = getSessionId();
+        const enclosingAgentSpan = 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 = ROOT_CONTEXT;
+        }
+        else {
+            startContext = enclosingAgentSpan
+                ? trace.setSpan(otelContext.active(), enclosingAgentSpan)
+                : otelContext.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: SpanKind.INTERNAL }, parentCtx);
+            span = tracer.startSpan(`invoke_agent ${agentName}`, { kind: SpanKind.INTERNAL, links }, startContext);
         }, "agent.start_span", this._internalLogger);
         if (span === undefined) {
             return await fn();
@@ -296,17 +393,24 @@ export class StructSDK {
                 startedSpan.setAttribute(GEN_AI.AGENT_VERSION, options.version);
             }
             // gen_ai.conversation.id is the spec-blessed name for
-            // session/thread id.
-            startedSpan.setAttribute(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(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(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(STRUCT.AGENT_PARENT_SESSION_ID, enclosingSessionId);
             }
             if (options.metadata) {
                 for (const [key, value] of Object.entries(options.metadata)) {
@@ -319,6 +423,7 @@ export class StructSDK {
             conversationId: sessionId,
             agentSpan: startedSpan,
             pendingToolCalls: {},
+            manualAgentSpan: startedSpan,
         }, async () => {
             const activeCtx = trace.setSpan(otelContext.active(), startedSpan);
             try {

package/dist/esm/events.js

@@ -49,7 +49,7 @@ export function emitAnthropicMessageEvents(logger, messages, system) {
                 parts: truncateParts(parts),
             }),
             extraAttrs: {
-                [GEN_AI.SYSTEM]: "anthropic",
+                [GEN_AI.PROVIDER_NAME]: "anthropic",
                 [GEN_AI.MESSAGE_INDEX]: msgIndex,
             },
         });
@@ -67,7 +67,7 @@ export function emitAnthropicMessageEvents(logger, messages, system) {
             eventName,
             payload: safeJsonStringify({ role, parts: truncateParts(parts) }),
             extraAttrs: {
-                [GEN_AI.SYSTEM]: "anthropic",
+                [GEN_AI.PROVIDER_NAME]: "anthropic",
                 [GEN_AI.MESSAGE_INDEX]: msgIndex,
             },
         });
@@ -92,7 +92,7 @@ export function emitAnthropicChoiceEvent(logger, contentBlocks, stopReason) {
         eventName: EVENT_NAMES.CHOICE,
         payload,
         extraAttrs: {
-            [GEN_AI.SYSTEM]: "anthropic",
+            [GEN_AI.PROVIDER_NAME]: "anthropic",
         },
     });
 }

package/dist/esm/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 */