@struct-ai/sdk 0.3.0 → 0.4.2

package/dist/esm/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[]>;
 /**
@@ -27,4 +53,23 @@ export declare function snapshotStore(): StructContext | undefined;
 export declare function runWithStore<T>(store: StructContext | undefined, fn: () => T): T;
 /** Test-only: run `fn` inside a completely fresh context (no parent store). */
 export declare function runInFreshContext<T>(fn: () => T): T;
+/**
+ * Write-once `gen_ai.provider.name` on an invoke_agent span.
+ *
+ * CONTRACT: `agentSpan` is always an SDK-OWNED span — created by our own
+ * tracer in `struct.agent()` or the LangChain handler and delivered via the
+ * ALS store / run map, which nothing else writes. Never a host object. So
+ * the industry-standard owned-object pattern applies (state lives ON the
+ * object — Sentry/dd-trace private span fields, OTel JS symbol markers): a
+ * private Symbol sentinel set after a successful write. No registries or
+ * lifecycle bookkeeping — those are for FOREIGN objects.
+ *
+ * Semantics: "a real child provider" — racing children with different
+ * providers may pick either; the sentinel is set only after a successful
+ * write so a transient failure can be retried. Parity: python
+ * `stamp_provider_once`.
+ */
+export declare function stampProviderOnce(agentSpan: Span | undefined, provider: string | undefined): void;
+/** Stamp the ambient agent span with the child call's provider (write-once). */
+export declare function propagateProviderToParent(provider: string | undefined): void;
 //# sourceMappingURL=context.d.ts.map

package/dist/esm/context.js

@@ -12,9 +12,22 @@ export function getConversationId() {
 export 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.
+ */
+export function getManualAgentSpan() {
+    return als.getStore()?.manualAgentSpan;
+}
 export function getPendingToolCalls() {
     return als.getStore()?.pendingToolCalls;
 }
+/** True when a framework layer (e.g. LangChain) already owns the chat span. */
+export function isGenAiSuppressed() {
+    return als.getStore()?.suppressGenAi === true;
+}
 export function runWithContext(patch, fn) {
     const current = als.getStore() ?? {};
     const next = { ...current, ...patch };
@@ -66,7 +79,11 @@ export function pushPendingToolCalls(pairs) {
 /** Snapshot the store for wrapping async iterators. */
 export 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 };
 }
 export function runWithStore(store, fn) {
     if (!store)
@@ -77,4 +94,60 @@ export function runWithStore(store, fn) {
 export function runInFreshContext(fn) {
     return als.run({}, fn);
 }
+/**
+ * Write-once `gen_ai.provider.name` on an invoke_agent span.
+ *
+ * The GenAI spec puts `gen_ai.provider.name` on invoke_agent spans, but the
+ * layer that CREATES those spans (`struct.agent()`, the LangChain handler) is
+ * provider-agnostic and can't know the value yet — only the child inference
+ * call can. The first chat call within the agent scope stamps it (best
+ * knowledge; first one wins); an agent that never reaches a model omits the
+ * attribute rather than carrying a framework name. Parity: python
+ * `_genai_content.stamp_provider_once`.
+ */
+const PROVIDER_STAMPED = Symbol("struct.providerStamped");
+/**
+ * Write-once `gen_ai.provider.name` on an invoke_agent span.
+ *
+ * CONTRACT: `agentSpan` is always an SDK-OWNED span — created by our own
+ * tracer in `struct.agent()` or the LangChain handler and delivered via the
+ * ALS store / run map, which nothing else writes. Never a host object. So
+ * the industry-standard owned-object pattern applies (state lives ON the
+ * object — Sentry/dd-trace private span fields, OTel JS symbol markers): a
+ * private Symbol sentinel set after a successful write. No registries or
+ * lifecycle bookkeeping — those are for FOREIGN objects.
+ *
+ * Semantics: "a real child provider" — racing children with different
+ * providers may pick either; the sentinel is set only after a successful
+ * write so a transient failure can be retried. Parity: python
+ * `stamp_provider_once`.
+ */
+export function stampProviderOnce(agentSpan, provider) {
+    try {
+        if (!agentSpan || !provider)
+            return;
+        const marked = agentSpan;
+        if (marked[PROVIDER_STAMPED])
+            return;
+        agentSpan.setAttribute("gen_ai.provider.name", provider);
+        try {
+            marked[PROVIDER_STAMPED] = true;
+        }
+        catch {
+            /* frozen span — worst case a later child re-stamps a real provider */
+        }
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
+/** Stamp the ambient agent span with the child call's provider (write-once). */
+export function propagateProviderToParent(provider) {
+    try {
+        stampProviderOnce(getAgentSpan(), provider);
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
 //# sourceMappingURL=context.js.map

package/dist/esm/core.js

@@ -1,5 +1,4 @@
-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 { resourceFromAttributes } from "@opentelemetry/resources";
@@ -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 = {
@@ -84,12 +84,22 @@ export function safe(fn, site, logger) {
         fn();
     }
     catch (err) {
-        if (firstFailureLogged.has(site)) {
-            logger.debug(`Struct SDK suppressed exception at ${site}`, err);
+        // The diagnostic log MUST NOT itself throw into the host: the default
+        // logger reaches `console.warn`, which a host may have replaced with a
+        // throwing implementation, and callers pass custom loggers. A throw here
+        // would escape `safe()` and defeat its whole purpose (e.g. block the host
+        // call when span creation fails). Guard the logging too.
+        try {
+            if (firstFailureLogged.has(site)) {
+                logger.debug(`Struct SDK suppressed exception at ${site}`, err);
+            }
+            else {
+                firstFailureLogged.add(site);
+                logger.warn(`Struct SDK suppressed exception at ${site}`, err);
+            }
         }
-        else {
-            firstFailureLogged.add(site);
-            logger.warn(`Struct SDK suppressed exception at ${site}`, err);
+        catch {
+            /* diagnostic logging failed — never propagate into the host path */
         }
     }
 }
@@ -228,13 +238,13 @@ 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;
@@ -302,8 +312,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
@@ -312,16 +321,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();
@@ -329,7 +390,10 @@ export class StructSDK {
         const startedSpan = span;
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "invoke_agent");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            // gen_ai.provider.name is NOT set here: this layer is
+            // provider-agnostic, and a framework name ("struct") isn't a
+            // provider. The first child inference call stamps the real one via
+            // propagateProviderToParent (write-once, best knowledge).
             startedSpan.setAttribute(GEN_AI.AGENT_NAME, agentName);
             // gen_ai.agent.id is the stable identifier of the agent
             // DEFINITION. Only set it when the caller provides one — we do
@@ -342,17 +406,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)) {
@@ -365,6 +436,7 @@ export class StructSDK {
             conversationId: sessionId,
             agentSpan: startedSpan,
             pendingToolCalls: {},
+            manualAgentSpan: startedSpan,
         }, async () => {
             const activeCtx = trace.setSpan(otelContext.active(), startedSpan);
             try {
@@ -416,7 +488,8 @@ export class StructSDK {
         const startedSpan = span;
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "execute_tool");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            // No gen_ai.provider.name: the spec's execute_tool span does not
+            // define that attribute.
             startedSpan.setAttribute(GEN_AI.TOOL_NAME, toolName);
             if (toolCallId) {
                 startedSpan.setAttribute(GEN_AI.TOOL_CALL_ID, toolCallId);
@@ -432,7 +505,28 @@ export class StructSDK {
             if (this.captureContent && result !== undefined && result !== null) {
                 safe(() => startedSpan.setAttribute(GEN_AI.TOOL_CALL_RESULT, safeJsonStringify(result).slice(0, 8192)), "tool.set_result_attr", this._internalLogger);
             }
-            safe(() => startedSpan.setStatus({ code: SpanStatusCode.OK }), "tool.set_ok_status", this._internalLogger);
+            if (toolResultSignalsError(result)) {
+                safe(() => {
+                    startedSpan.setAttribute(ERROR_TYPE, "tool_error");
+                    // The status message is content placed on a SPAN — it follows
+                    // the span-content routing gate (emitSpanContent), not merely
+                    // "any capture on": under EventOnly (the default) content
+                    // routes to log events, so span text gets the fixed literal.
+                    // Deliberate boundary: gen_ai.tool.call.result above stays on
+                    // captureContent — tool spans have no log-event equivalent for
+                    // results, so the attribute is the sanctioned tool-content
+                    // channel in every non-None mode. Mirrors python _note_result.
+                    startedSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: this.emitSpanContent
+                            ? toolErrorStatusMessage(result)
+                            : "tool returned is_error=true",
+                    });
+                }, "tool.set_tool_error_status", this._internalLogger);
+            }
+            else {
+                safe(() => startedSpan.setStatus({ code: SpanStatusCode.OK }), "tool.set_ok_status", this._internalLogger);
+            }
             return result;
         }
         catch (err) {
@@ -453,4 +547,65 @@ function recordError(span, err) {
         span.recordException(err);
     }
 }
+/**
+ * Read one property from untrusted host data, isolating the read in its
+ * own try — a hostile getter/Proxy trap on ONE key must never throw into
+ * tool()'s try block (rejecting the host's successful call) nor mask a
+ * readable value on a SIBLING key (callers probe each supported alias
+ * independently). Mirrors python `_safe_probe` — keep in lockstep.
+ */
+function safeProbe(obj, key) {
+    if (typeof obj !== "object" || obj === null)
+        return undefined;
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a tool's RETURN VALUE signals in-band failure (MCP
+ * CallToolResult.isError / Anthropic tool_result.is_error). Strictly
+ * boolean `true` on the top-level object — truthy strings/numbers and
+ * nested flags do not trigger (host data is untrusted; be conservative).
+ * Each alias is probed independently so a hostile getter on one cannot
+ * mask the other. Mirrors python `_tool_result_signals_error`.
+ */
+function toolResultSignalsError(result) {
+    return (safeProbe(result, "isError") === true ||
+        safeProbe(result, "is_error") === true);
+}
+/** Short status message from an error result's content, else a fixed one.
+ *
+ * TOTAL FUNCTION: never throws and does bounded work. It runs inside the
+ * safe() closure that also sets span status — a hostile Proxy whose
+ * `length`/index traps throw must not abort that closure (which would
+ * leave the span UNSET instead of ERROR). Two layers: per-key safeProbe
+ * isolation (one hostile item cannot mask a later readable one) INSIDE a
+ * whole-body catch (collection machinery itself is untrusted), index
+ * loop instead of for..of (iterator protocol is trappable), traversal
+ * capped at 20 items. Mirrors python `_tool_error_status_message`. */
+function toolErrorStatusMessage(result) {
+    try {
+        const content = safeProbe(result, "content");
+        if (typeof content === "string" && content)
+            return content.slice(0, 256);
+        if (Array.isArray(content)) {
+            const len = Math.min(content.length, 20);
+            for (let i = 0; i < len; i++) {
+                const item = safeProbe(content, String(i));
+                const text = safeProbe(item, "text");
+                // Truthiness (not just typeof) matches the python twin: empty-string
+                // text items are skipped, falling through to the fixed message.
+                if (typeof text === "string" && text)
+                    return text.slice(0, 256);
+            }
+        }
+    }
+    catch {
+        // Hostile collection — fall through to the fixed message.
+    }
+    return "tool returned is_error=true";
+}
 //# sourceMappingURL=core.js.map

package/dist/esm/events.d.ts

@@ -1,12 +1,23 @@
-import { type Logger } from "@opentelemetry/api-logs";
+import type { Logger } from "@opentelemetry/api-logs";
+import type { Span } from "@opentelemetry/api";
 /**
  * Emit per-message log events for an Anthropic messages.create() call.
- * Port of _emit_message_events from anthropic.py.
+ * Delegates the LogRecord wiring to the shared genai-content emitters; this
+ * function is only the Anthropic message → parts mapping + ordering.
  */
-export declare function emitAnthropicMessageEvents(logger: Logger, messages: unknown, system: unknown): void;
+export declare function emitAnthropicMessageEvents(logger: Logger, messages: unknown, system: unknown, span?: Span, provider?: string): void;
+/** Emit a gen_ai.choice LogRecord for an Anthropic response. */
+export declare function emitAnthropicChoiceEvent(logger: Logger, contentBlocks: unknown, stopReason: string | null | undefined, span?: Span, provider?: string): void;
 /**
- * Emit a gen_ai.choice LogRecord for an Anthropic response.
- * Port of _emit_choice_event from anthropic.py.
+ * Emit per-message log events for an OpenAI responses.create() call.
+ * `instructions` (the Responses system prompt) is emitted FIRST at index 0.
+ * Delegates LogRecord wiring to the shared emitters; only the Responses
+ * item → event mapping + ordering lives here.
  */
-export declare function emitAnthropicChoiceEvent(logger: Logger, contentBlocks: unknown, stopReason: string | null | undefined): void;
+export declare function emitOpenAIInputMessageEvents(logger: Logger, input: unknown, instructions: unknown, span?: Span, provider?: string): void;
+/**
+ * Emit the gen_ai.choice LogRecord from an OpenAI response.output.
+ * `finishReason` is mapped inside this emitter using mapChoiceFinishReason.
+ */
+export declare function emitOpenAIChoiceEvent(logger: Logger, output: unknown, finishReason: string | undefined, span?: Span, provider?: string): void;
 //# sourceMappingURL=events.d.ts.map