@struct-ai/sdk 0.3.0 → 0.4.2

package/README.md

@@ -1,8 +1,9 @@
 # @struct-ai/sdk
 
 Struct agent observability SDK for TypeScript/Node.js. Auto-instruments AI agent
-frameworks — the Anthropic SDK and LangChain.js — and emits OpenTelemetry
-traces + logs to [struct.ai](https://struct.ai) with zero config.
+frameworks and LLM SDKs — the Anthropic SDK, the OpenAI SDK (Responses API),
+and LangChain.js — and emits OpenTelemetry traces + logs to
+[struct.ai](https://struct.ai) with zero config.
 
 This is the TypeScript port of [`struct-sdk`](https://pypi.org/project/struct-sdk/)
 (Python). Span names, attribute keys, and log event shapes are identical across
@@ -13,7 +14,7 @@ the two SDKs so the server processes both uniformly.
 ```bash
 npm install @struct-ai/sdk
 # optional — the SDK auto-instruments these if present
-npm install @anthropic-ai/sdk @langchain/core @langchain/langgraph
+npm install @anthropic-ai/sdk openai @langchain/core @langchain/langgraph
 ```
 
 Requires Node 18+.
@@ -55,9 +56,10 @@ 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) |
+| `openai` | `Responses.prototype.create` | `chat {model}` | **Responses API, non-streaming calls only** — `responses.create({stream: true})` and `responses.stream()` pass through untouched (no span), and `chat.completions` is not instrumented. Cache-read/cache-write/reasoning token accounting; `function_call` → `struct.tool()` id auto-linkage. Requires an openai release with the Responses API (v4 releases without it are a graceful no-op). Defers to a LangChain call in progress, same as Anthropic |
+| `@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)`. |
@@ -166,6 +168,37 @@ await struct.agent({ name: "checkout" }, async () => {
 `@anthropic-ai/sdk`, `@anthropic-ai/bedrock-sdk`, and `@anthropic-ai/vertex-sdk`
 are all auto-instrumented for chat spans.
 
+#### OpenAI SDK (raw, Responses API)
+
+Same rule as raw Anthropic — chat spans emit automatically; wrap your agent
+loop and tools yourself:
+
+```ts
+import { struct } from "@struct-ai/sdk";
+struct.init({ ingestKey: "pk-...", serviceName: "support-agent" });
+
+import OpenAI from "openai";
+const client = new OpenAI();
+
+await struct.agent({ name: "support" }, async () => {
+  const resp = await client.responses.create({
+    model: "gpt-5.5",
+    input: "triage this ticket",
+  });
+
+  // tool_call_id is auto-filled from the preceding response's function_call.
+  await struct.tool({ name: "lookup_order" }, async () => {
+    return await lookupOrder(resp);
+  });
+});
+```
+
+**Scope:** the OpenAI integration covers **non-streaming `responses.create()`**
+only. Streaming calls (`stream: true` / `responses.stream()`) run unmodified and
+emit no span, and `chat.completions` is not instrumented. Azure OpenAI clients
+(`AzureOpenAI`) share the same `Responses` class and are covered by the same
+patch.
+
 #### LangChain `BaseChatModel` (no agent/graph)
 
 If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)
@@ -189,8 +222,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
 
@@ -206,13 +239,13 @@ struct.init({
 ```
 
 - **`EventOnly`** (default): per-message content lands on OTel log records
-  (`gen_ai.{user,assistant,system,tool}.message`, `gen_ai.choice`). Spans carry
-  metadata only.
+  (`gen_ai.{user,assistant,system,tool}.message`, `gen_ai.choice`).
 - **`SpanOnly`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SpanAndEvent`**: both.
-- **`None`**: no content captured. Token counts, tool call IDs, finish reasons,
-  and other metadata still flow.
+- **`None`**: no content captured, anywhere — no log events, no span content
+  attributes. Token counts, tool call IDs, finish reasons, and other metadata
+  still flow.
 
 Set `captureContent: false` for the legacy bool API (equivalent to
 `ContentCaptureMode.None`).
@@ -252,7 +285,7 @@ the troubleshooting section below for the workaround.
 Emits attributes per the OTel GenAI semantic conventions:
 
 - `gen_ai.operation.name` — `chat`, `execute_tool`, `invoke_agent`, `retrieval`
-- `gen_ai.provider.name` — `anthropic`, `openai`, `langchain`, `struct`, …
+- `gen_ai.provider.name` — the GenAI provider on inference spans (`anthropic`, `openai`, …); platform-routed calls report the platform value (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`) when detectable from the client. `invoke_agent` spans inherit the provider from their first child inference call (omitted when no model is reached); `execute_tool`/`retrieval` spans carry no provider.
 - `gen_ai.request.{model, max_tokens, temperature, top_p, top_k, stop_sequences}`
 - `gen_ai.response.{model, id, finish_reasons}`
 - `gen_ai.usage.{input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens}`
@@ -264,6 +297,48 @@ 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 provider SDKs
+  (`@anthropic-ai/sdk`, `openai`) and frameworks (`@langchain/*`) against the
+  real Anthropic / OpenAI APIs, verifying the emitted spans + log events
+  **in-memory** (no ingester needed). Each gated block skips cleanly (exit 0)
+  when its API key is absent — safe to leave in normal CI.
+
+  To run it, point `STRUCT_LIVE_ENV_FILE` at a file with the keys you want to
+  exercise (`ANTHROPIC_API_KEY=...` and/or `OPENAI_API_KEY=...`; dotenv-style
+  `KEY=value` lines, quotes optional). The path is never committed — it's
+  supplied per-invocation:
+
+  ```bash
+  STRUCT_LIVE_ENV_FILE=/path/to/your/.env pnpm test:live
+  ```
+
+  Only blocks whose key is present run, so a file with both keys runs both the
+  Anthropic and OpenAI suites (a handful of small real calls each — cheap model
+  aliases, small token budgets).
+
+  **Full-pipeline e2e** (`test/live/openai-ingest-e2e.live.test.ts`)
+  additionally ships the emitted telemetry to a *real* ingest endpoint and
+  flushes it, so you can confirm a change travels the whole path
+  (SDK → OTLP export → your Struct instance). It's gated on `STRUCT_INGEST_URL`
+  + `STRUCT_INGEST_KEY` (on top of `OPENAI_API_KEY`), so it stays skipped unless
+  you deliberately supply real ingest credentials. It still self-asserts the
+  span shape in-memory; confirming the span actually *landed* means querying
+  your Struct instance's telemetry — see [AGENTS.md](./AGENTS.md).
+- `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 +348,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[]>;
 /**
@@ -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/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;
@@ -12,6 +14,8 @@ exports.pushPendingToolCalls = pushPendingToolCalls;
 exports.snapshotStore = snapshotStore;
 exports.runWithStore = runWithStore;
 exports.runInFreshContext = runInFreshContext;
+exports.stampProviderOnce = stampProviderOnce;
+exports.propagateProviderToParent = propagateProviderToParent;
 const node_async_hooks_1 = require("node:async_hooks");
 const als = new node_async_hooks_1.AsyncLocalStorage();
 function getStore() {
@@ -26,9 +30,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 +97,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)
@@ -91,4 +112,60 @@ function runWithStore(store, fn) {
 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`.
+ */
+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). */
+function propagateProviderToParent(provider) {
+    try {
+        stampProviderOnce(getAgentSpan(), provider);
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
 //# sourceMappingURL=context.js.map