@struct-ai/sdk 0.4.2 → 0.4.3

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/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.4.2";
+export declare const SDK_VERSION = "0.4.3";
 //# 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.3";
 //# sourceMappingURL=version.js.map

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.3";
 //# 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.3";
 //# sourceMappingURL=version.js.map

package/package.json

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