@struct-ai/sdk 0.4.2 → 0.4.4

package/README.md

@@ -293,6 +293,28 @@ Emits attributes per the OTel GenAI semantic conventions:
 - `gen_ai.tool.{name, call.id, call.arguments, call.result}`
 - `error.type` + `StatusCode.ERROR` on failures
 
+### `error.type` values emitted
+
+The OTel conventions ask instrumentations to document the error values they
+report ("Instrumentations SHOULD document the list of errors they report").
+This SDK emits exactly two kinds of value, both alongside span
+`StatusCode.ERROR`:
+
+| Value | When | Meaning |
+| --- | --- | --- |
+| exception class name (e.g. `TypeError`, `APIConnectionError`) | the instrumented call threw | We failed to execute the request. Also records an OTel exception event. |
+| `tool_error` | an `execute_tool` span whose result signalled failure **in band** — Anthropic `tool_result` blocks with `is_error: true`, MCP `CallToolResult.isError`, or a LangChain `ToolMessage` with `status: "error"` | The tool ran and reported a failure back to the model (bad arguments, a domain "no"), so the model can self-correct. No exception object exists, so no class name is available. |
+
+`tool_error` is a deliberate low-cardinality sentinel, which the `error.type`
+convention explicitly permits ("another low-cardinality error identifier"; a
+custom value MAY be used where no well-known one applies). The same split is
+used by OpenTelemetry's MCP instrumentation in OpenLLMetry, which likewise
+reports `error.type="tool_error"` for the `isError` path and the exception
+class name otherwise. Matches the Python SDK.
+
+The distinction is what lets a monitor page on genuine execution failures
+while excluding failures the model already saw and can recover from.
+
 Note: `gen_ai.usage.input_tokens` for Anthropic is the TRUE total — we add back
 `cache_read_input_tokens + cache_creation_input_tokens` (which Anthropic's raw
 response excludes). Matches the Python SDK.

package/dist/commonjs/integrations/openai.js

@@ -107,8 +107,26 @@ function isAzureHost(host) {
         host.endsWith(".services.ai.azure.us") ||
         host.endsWith(".services.ai.azure.cn"));
 }
+// OpenAI-compatible vendor endpoints served through the openai client. Values
+// are the CURRENT OTel gen_ai.provider.name well-known enum (semconv-genai
+// registry): note "x_ai" (underscored — the deprecated gen_ai.system enum used
+// "xai") and "mistral_ai" (not "mistral"). Fixed API hosts, so exact-match —
+// a lookalike like "api.x.ai.evil.com" must not match.
+// Parity: python openai.py's _OPENAI_COMPATIBLE_HOSTS.
+const OPENAI_COMPATIBLE_HOSTS = new Map([
+    ["api.x.ai", "x_ai"],
+    ["api.groq.com", "groq"],
+    ["api.deepseek.com", "deepseek"],
+    ["api.mistral.ai", "mistral_ai"],
+]);
 const HOST_RULES = [
     [isAzureHost, "azure.ai.openai"],
+    // One (predicate, provider) entry per fixed vendor host — the detector
+    // returns the first matching rule's value.
+    ...[...OPENAI_COMPATIBLE_HOSTS].map(([vendorHost, provider]) => [
+        (host) => host === vendorHost,
+        provider,
+    ]),
 ];
 function detectProvider(resource) {
     return (0, genai_content_js_1.detectProviderFromResource)(resource, CLASS_NAME_RULES, HOST_RULES, "openai");

package/dist/commonjs/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.4.2";
+export declare const SDK_VERSION = "0.4.4";
 //# sourceMappingURL=version.d.ts.map

package/dist/commonjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // Keep in sync with package.json; test/version.test.ts enforces it.
-exports.SDK_VERSION = "0.4.2";
+exports.SDK_VERSION = "0.4.4";
 //# sourceMappingURL=version.js.map

package/dist/esm/integrations/openai.js

@@ -98,8 +98,26 @@ function isAzureHost(host) {
         host.endsWith(".services.ai.azure.us") ||
         host.endsWith(".services.ai.azure.cn"));
 }
+// OpenAI-compatible vendor endpoints served through the openai client. Values
+// are the CURRENT OTel gen_ai.provider.name well-known enum (semconv-genai
+// registry): note "x_ai" (underscored — the deprecated gen_ai.system enum used
+// "xai") and "mistral_ai" (not "mistral"). Fixed API hosts, so exact-match —
+// a lookalike like "api.x.ai.evil.com" must not match.
+// Parity: python openai.py's _OPENAI_COMPATIBLE_HOSTS.
+const OPENAI_COMPATIBLE_HOSTS = new Map([
+    ["api.x.ai", "x_ai"],
+    ["api.groq.com", "groq"],
+    ["api.deepseek.com", "deepseek"],
+    ["api.mistral.ai", "mistral_ai"],
+]);
 const HOST_RULES = [
     [isAzureHost, "azure.ai.openai"],
+    // One (predicate, provider) entry per fixed vendor host — the detector
+    // returns the first matching rule's value.
+    ...[...OPENAI_COMPATIBLE_HOSTS].map(([vendorHost, provider]) => [
+        (host) => host === vendorHost,
+        provider,
+    ]),
 ];
 function detectProvider(resource) {
     return detectProviderFromResource(resource, CLASS_NAME_RULES, HOST_RULES, "openai");

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.4.2";
+export declare const SDK_VERSION = "0.4.4";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Keep in sync with package.json; test/version.test.ts enforces it.
-export const SDK_VERSION = "0.4.2";
+export const SDK_VERSION = "0.4.4";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",