@struct-ai/sdk 0.1.0

package/dist/esm/core.js

@@ -0,0 +1,403 @@
+import { randomUUID } from "node:crypto";
+import { context as otelContext, 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 { BatchLogRecordProcessor, LoggerProvider, } from "@opentelemetry/sdk-logs";
+import { BatchSpanProcessor, NodeTracerProvider, } from "@opentelemetry/sdk-trace-node";
+import { ContentCaptureMode, captureContentFor, emitEventsFor, emitSpanContentFor, } from "./content-capture.js";
+import { getAgentSpan, getSessionId, popPendingToolCallId, runWithContext, } from "./context.js";
+import { autoInstrument } from "./integrations/index.js";
+import { ERROR_TYPE, GEN_AI, STRUCT, } from "./semconv.js";
+import { safeJsonStringify } from "./truncation.js";
+export const DEFAULT_ENDPOINT = "https://ingest.struct.ai";
+const LOG_ENABLED = process.env.STRUCT_SDK_LOG === "1";
+const defaultInternalLogger = {
+    info: (msg, ...args) => {
+        if (LOG_ENABLED)
+            console.info(`[struct-sdk] ${msg}`, ...args);
+    },
+    warn: (msg, ...args) => console.warn(`[struct-sdk] ${msg}`, ...args),
+    debug: (msg, ...args) => {
+        if (LOG_ENABLED)
+            console.debug(`[struct-sdk] ${msg}`, ...args);
+    },
+};
+/**
+ * Sites that have already logged a first-failure WARN; subsequent failures at
+ * the same site log at DEBUG. Mirrors `_first_failure_logged` in the Python
+ * SDK.
+ *
+ * Exported for tests that need to clear the set between runs so log-level
+ * assertions are deterministic. Internal — not re-exported from `index.ts`,
+ * so consumers cannot reach it via the package's public API surface.
+ */
+export const firstFailureLogged = new Set();
+/**
+ * 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
+ * DEBUG. The caller's logger is passed explicitly so this helper stays a free
+ * module-level function — usable from instrumentation modules that don't
+ * carry an SDK reference of their own.
+ *
+ * Mirrors `_safe(fn, *, site)` in the Python SDK.
+ */
+export function safe(fn, site, logger) {
+    try {
+        fn();
+    }
+    catch (err) {
+        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);
+        }
+    }
+}
+export class StructSDK {
+    _initialized = false;
+    _tracerProvider;
+    _loggerProvider;
+    _ingestKey = "";
+    _endpoint = DEFAULT_ENDPOINT;
+    _contentCapture = ContentCaptureMode.EventOnly;
+    _shutdownHook;
+    // Always set so `shutdown()` can read it even when init() was never called
+    // or failed before reaching the assignment in init(). Mirrors the Python
+    // SDK's `_shutdown_timeout_seconds` default in `__init__`.
+    _shutdownTimeoutMs = 5000;
+    _internalLogger = defaultInternalLogger;
+    _readyPromise = Promise.resolve();
+    /** Resolves once auto-instrumentation has attempted to patch every detected library. */
+    get ready() {
+        return this._readyPromise;
+    }
+    get initialized() {
+        return this._initialized;
+    }
+    get endpoint() {
+        return this._endpoint;
+    }
+    get ingestKey() {
+        return this._ingestKey;
+    }
+    get contentCapture() {
+        return this._contentCapture;
+    }
+    get captureContent() {
+        return captureContentFor(this._contentCapture);
+    }
+    get emitEvents() {
+        return emitEventsFor(this._contentCapture);
+    }
+    get emitSpanContent() {
+        return emitSpanContentFor(this._contentCapture);
+    }
+    init(options) {
+        if (this._initialized) {
+            this._internalLogger.warn("struct.init() called multiple times — ignoring");
+            return;
+        }
+        const { ingestKey, serviceName = "default-agent", serviceVersion = "0.0.0", environment = "development", endpoint = DEFAULT_ENDPOINT, captureContent = true, contentCapture, shutdownTimeoutMs = 5000, } = options;
+        this._ingestKey = ingestKey;
+        this._endpoint = endpoint.replace(/\/+$/, "");
+        // Stored before any code that could throw so shutdown() always sees
+        // the user-configured timeout, even on a partially-failed init.
+        this._shutdownTimeoutMs = shutdownTimeoutMs;
+        if (contentCapture !== undefined) {
+            this._contentCapture = contentCapture;
+        }
+        else if (!captureContent) {
+            this._contentCapture = ContentCaptureMode.None;
+        }
+        else {
+            this._contentCapture = ContentCaptureMode.EventOnly;
+        }
+        // Everything from here through autoInstrument() can fail in the wild —
+        // exporter constructors validate URLs, the resource builder may reject
+        // attribute values, processors allocate buffers, etc. The SDK contract
+        // is that init() never raises; on failure we leave the SDK in a clean
+        // disabled state and let the user's app keep running. Decorator-style
+        // calls (`agent`, `tool`) already short-circuit when `_initialized`
+        // is false, so a disabled SDK is a no-op rather than a hazard.
+        try {
+            const headers = { "x-struct-ingest-key": ingestKey };
+            const spanExporter = new OTLPTraceExporter({
+                url: `${this._endpoint}/v1/traces`,
+                headers,
+            });
+            const spanProcessor = new BatchSpanProcessor(spanExporter, {
+                maxQueueSize: 10000,
+                maxExportBatchSize: 100,
+                scheduledDelayMillis: 1000,
+            });
+            const resource = new Resource({
+                "service.name": serviceName,
+                "service.version": serviceVersion,
+                "deployment.environment": environment,
+            });
+            this._tracerProvider = new NodeTracerProvider({
+                resource,
+                spanProcessors: [spanProcessor],
+            });
+            const logExporter = new OTLPLogExporter({
+                url: `${this._endpoint}/v1/logs`,
+                headers,
+            });
+            const logProcessor = new BatchLogRecordProcessor(logExporter, {
+                maxQueueSize: 10000,
+                maxExportBatchSize: 100,
+                scheduledDelayMillis: 1000,
+            });
+            this._loggerProvider = new LoggerProvider({ resource });
+            this._loggerProvider.addLogRecordProcessor(logProcessor);
+            this._initialized = true;
+            this._shutdownHook = () => {
+                void this.shutdown();
+            };
+            process.on("beforeExit", this._shutdownHook);
+            this._readyPromise = autoInstrument(this);
+        }
+        catch (err) {
+            this._internalLogger.warn(`Struct SDK init failed; SDK disabled: service=${serviceName} endpoint=${this._endpoint}`, err);
+            // Tear down anything we may have already wired up. If process.on
+            // succeeded but a later step failed, the beforeExit listener is still
+            // live — unregister it so the disabled SDK doesn't run shutdown logic
+            // against half-built providers at process exit.
+            if (this._shutdownHook) {
+                process.off("beforeExit", this._shutdownHook);
+            }
+            this._initialized = false;
+            this._tracerProvider = undefined;
+            this._loggerProvider = undefined;
+            this._shutdownHook = undefined;
+            this._readyPromise = Promise.resolve();
+            return;
+        }
+        this._internalLogger.info(`Struct SDK initialized: service=${serviceName} endpoint=${this._endpoint} content_capture=${this._contentCapture}`);
+    }
+    getTracer(name = "struct-sdk") {
+        if (!this._tracerProvider) {
+            throw new Error("Call struct.init() before using the SDK");
+        }
+        return this._tracerProvider.getTracer(name);
+    }
+    getLogger(name = "struct-sdk") {
+        if (!this._loggerProvider) {
+            throw new Error("Call struct.init() before using the SDK");
+        }
+        return this._loggerProvider.getLogger(name);
+    }
+    getInternalLogger() {
+        return this._internalLogger;
+    }
+    /** Test-only: attach a custom span processor to the internal provider. */
+    addSpanProcessor(processor) {
+        this._tracerProvider?.addSpanProcessor(processor);
+    }
+    /** Test-only: attach a custom log record processor. */
+    addLogRecordProcessor(processor) {
+        this._loggerProvider?.addLogRecordProcessor(processor);
+    }
+    /**
+     * Shut down the SDK and flush pending telemetry.
+     *
+     * Returns within `timeoutMs` (default: SDK init's `shutdownTimeoutMs`,
+     * fallback 5000ms). If the ingest endpoint is unreachable, in-flight
+     * telemetry may be dropped — the trade-off vs. blocking process exit.
+     *
+     * In serverless / edge runtimes (Lambda, Vercel, etc.), the runtime does
+     * NOT await our `beforeExit` hook. Call `await struct.shutdown()`
+     * explicitly before your function returns or before container freeze.
+     *
+     * Safe to call multiple times. Safe to call on an SDK that failed to init
+     * or was never initialized.
+     *
+     * @param timeoutMs - Override the configured shutdown timeout for this call.
+     */
+    async shutdown(timeoutMs) {
+        const timeout = timeoutMs ?? this._shutdownTimeoutMs;
+        if (this._shutdownHook) {
+            process.off("beforeExit", this._shutdownHook);
+            this._shutdownHook = undefined;
+        }
+        // Order matches the previous behavior (logger first, tracer second) so
+        // any consumer that depended on relative ordering keeps working.
+        const flushAll = async () => {
+            await this._loggerProvider?.shutdown().catch(() => undefined);
+            await this._tracerProvider?.shutdown().catch(() => undefined);
+        };
+        let timedOut = false;
+        const timer = new Promise((resolve) => {
+            const handle = setTimeout(() => {
+                timedOut = true;
+                resolve("timeout");
+            }, timeout);
+            // Don't keep the event loop alive for this timer — once flushAll
+            // resolves, the process is free to exit even though the timer hasn't
+            // fired. `unref` is missing on some non-Node timer shims, hence `?.`.
+            handle.unref?.();
+        });
+        const result = await Promise.race([flushAll(), timer]);
+        if (timedOut || result === "timeout") {
+            // DEBUG-only: atexit context is noisy enough; a WARN here would
+            // clutter user stderr for a fault we already handled.
+            this._internalLogger.debug(`Struct SDK shutdown timed out after ${timeout}ms (ingest may be unreachable)`);
+        }
+    }
+    /**
+     * Run `fn` inside an `invoke_agent` span scope.
+     * Matches Python's _AgentContext behavior.
+     */
+    async agent(options, fn) {
+        if (!this._initialized) {
+            return await fn();
+        }
+        const agentName = options.name;
+        const sessionId = options.sessionId ?? randomUUID();
+        const parentSessionId = getSessionId();
+        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
+        // single trace tree. Falls back to OTel's active context (which may
+        // include the caller's own OTel span), or a fresh trace when there's
+        // 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();
+        // 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);
+        }, "agent.start_span", this._internalLogger);
+        if (span === undefined) {
+            return await fn();
+        }
+        const startedSpan = span;
+        safe(() => {
+            startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "invoke_agent");
+            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            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
+            // not auto-derive it from sessionId (that would conflate agent
+            // identity with invocation).
+            if (options.agentId) {
+                startedSpan.setAttribute(GEN_AI.AGENT_ID, options.agentId);
+            }
+            if (options.version) {
+                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);
+            if (parentSessionId && parentSessionId !== sessionId) {
+                startedSpan.setAttribute(STRUCT.AGENT_PARENT_SESSION_ID, parentSessionId);
+            }
+            if (options.metadata) {
+                for (const [key, value] of Object.entries(options.metadata)) {
+                    startedSpan.setAttribute(`${STRUCT.METADATA_PREFIX}${key}`, value);
+                }
+            }
+        }, "agent.set_attrs", this._internalLogger);
+        return await runWithContext({
+            sessionId,
+            conversationId: sessionId,
+            agentSpan: startedSpan,
+            pendingToolCalls: {},
+        }, async () => {
+            const activeCtx = trace.setSpan(otelContext.active(), startedSpan);
+            try {
+                const result = await otelContext.with(activeCtx, fn);
+                safe(() => startedSpan.setStatus({ code: SpanStatusCode.OK }), "agent.set_ok_status", this._internalLogger);
+                return result;
+            }
+            catch (err) {
+                safe(() => recordError(startedSpan, err), "agent.record_error", this._internalLogger);
+                throw err;
+            }
+            finally {
+                safe(() => startedSpan.end(), "agent.span_end", this._internalLogger);
+            }
+        });
+    }
+    /**
+     * Run `fn` inside an `execute_tool` span scope.
+     * Matches Python's _ToolContext behavior.
+     */
+    async tool(options, fn) {
+        if (!this._initialized) {
+            return await fn();
+        }
+        const toolName = options.name;
+        let toolCallId = options.toolCallId;
+        if (!toolCallId) {
+            toolCallId = popPendingToolCallId(toolName);
+        }
+        const tracer = this.getTracer("struct-sdk");
+        // Parent on the enclosing agent span (StructContext ALS) so tool spans
+        // live under their agent in the same trace. See the comment in
+        // `agent()` — we manage our own parent chain rather than depend on the
+        // global OTel context manager being registered.
+        const parentSpan = getAgentSpan();
+        const parentCtx = parentSpan
+            ? trace.setSpan(otelContext.active(), parentSpan)
+            : otelContext.active();
+        // Span creation itself can fail. Fall through to running `fn` so the
+        // user's tool call always runs uninstrumented rather than failing
+        // because of telemetry.
+        let span;
+        safe(() => {
+            span = tracer.startSpan(`execute_tool ${toolName}`, { kind: SpanKind.INTERNAL }, parentCtx);
+        }, "tool.start_span", this._internalLogger);
+        if (span === undefined) {
+            return await fn();
+        }
+        const startedSpan = span;
+        safe(() => {
+            startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "execute_tool");
+            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            startedSpan.setAttribute(GEN_AI.TOOL_NAME, toolName);
+            if (toolCallId) {
+                startedSpan.setAttribute(GEN_AI.TOOL_CALL_ID, toolCallId);
+            }
+            const sessionId = getSessionId();
+            if (sessionId) {
+                startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            }
+        }, "tool.set_attrs", this._internalLogger);
+        const activeCtx = trace.setSpan(otelContext.active(), startedSpan);
+        try {
+            const result = await otelContext.with(activeCtx, fn);
+            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);
+            return result;
+        }
+        catch (err) {
+            safe(() => recordError(startedSpan, err), "tool.record_error", this._internalLogger);
+            throw err;
+        }
+        finally {
+            safe(() => startedSpan.end(), "tool.span_end", this._internalLogger);
+        }
+    }
+}
+function recordError(span, err) {
+    const errorType = err instanceof Error ? err.constructor.name : typeof err;
+    const message = err instanceof Error ? err.message : String(err);
+    span.setAttribute(ERROR_TYPE, errorType);
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    if (err instanceof Error) {
+        span.recordException(err);
+    }
+}
+//# sourceMappingURL=core.js.map

package/dist/esm/events.d.ts

@@ -0,0 +1,12 @@
+import { type Logger } from "@opentelemetry/api-logs";
+/**
+ * Emit per-message log events for an Anthropic messages.create() call.
+ * Port of _emit_message_events from anthropic.py.
+ */
+export declare function emitAnthropicMessageEvents(logger: Logger, messages: unknown, system: unknown): void;
+/**
+ * Emit a gen_ai.choice LogRecord for an Anthropic response.
+ * Port of _emit_choice_event from anthropic.py.
+ */
+export declare function emitAnthropicChoiceEvent(logger: Logger, contentBlocks: unknown, stopReason: string | null | undefined): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/esm/events.js

@@ -0,0 +1,99 @@
+import { context as otelContext } from "@opentelemetry/api";
+import { SeverityNumber, } from "@opentelemetry/api-logs";
+import { getSessionId } from "./context.js";
+import { ANTHROPIC_FINISH_REASON_MAP, EVENT_NAME, EVENT_NAMES, GEN_AI, ROLE_TO_EVENT_NAME, } from "./semconv.js";
+import { safeJsonStringify, truncateParts } from "./truncation.js";
+import { contentToParts, } from "./integrations/anthropic-content.js";
+/**
+ * Emit a LogRecord with the active span context linked.
+ *
+ * Follows the OTel logs data model convention:
+ * - `body` (log record body) = event tag string (human-readable signal)
+ * - `attributes.body` (log record attribute) = JSON-serialised payload
+ */
+function emitLogRecord({ logger, eventName, payload, extraAttrs = {}, }) {
+    const sessionId = getSessionId();
+    const attributes = {
+        [EVENT_NAME]: eventName,
+        body: payload,
+        ...extraAttrs,
+    };
+    if (sessionId)
+        attributes[GEN_AI.CONVERSATION_ID] = sessionId;
+    logger.emit({
+        body: eventName,
+        severityNumber: SeverityNumber.INFO,
+        attributes,
+        context: otelContext.active(),
+    });
+}
+/**
+ * Emit per-message log events for an Anthropic messages.create() call.
+ * Port of _emit_message_events from anthropic.py.
+ */
+export function emitAnthropicMessageEvents(logger, messages, system) {
+    if (!Array.isArray(messages))
+        return;
+    let msgIndex = 0;
+    if (system) {
+        const parts = typeof system === "string"
+            ? [{ type: "text", content: system }]
+            : Array.isArray(system)
+                ? contentToParts(system)
+                : [{ type: "text", content: String(system) }];
+        emitLogRecord({
+            logger,
+            eventName: EVENT_NAMES.SYSTEM_MESSAGE,
+            payload: safeJsonStringify({
+                role: "system",
+                parts: truncateParts(parts),
+            }),
+            extraAttrs: {
+                [GEN_AI.SYSTEM]: "anthropic",
+                [GEN_AI.MESSAGE_INDEX]: msgIndex,
+            },
+        });
+        msgIndex++;
+    }
+    for (const msg of messages) {
+        if (!msg || typeof msg !== "object")
+            continue;
+        const m = msg;
+        const role = typeof m.role === "string" ? m.role : "user";
+        const parts = contentToParts(m.content);
+        const eventName = ROLE_TO_EVENT_NAME[role] ?? `gen_ai.${role}.message`;
+        emitLogRecord({
+            logger,
+            eventName,
+            payload: safeJsonStringify({ role, parts: truncateParts(parts) }),
+            extraAttrs: {
+                [GEN_AI.SYSTEM]: "anthropic",
+                [GEN_AI.MESSAGE_INDEX]: msgIndex,
+            },
+        });
+        msgIndex++;
+    }
+}
+/**
+ * Emit a gen_ai.choice LogRecord for an Anthropic response.
+ * Port of _emit_choice_event from anthropic.py.
+ */
+export function emitAnthropicChoiceEvent(logger, contentBlocks, stopReason) {
+    const parts = contentToParts(contentBlocks);
+    const mappedReason = (stopReason && (ANTHROPIC_FINISH_REASON_MAP[stopReason] ?? stopReason)) ||
+        "stop";
+    const payload = safeJsonStringify({
+        index: 0,
+        finish_reason: mappedReason,
+        message: { role: "assistant", parts: truncateParts(parts) },
+    });
+    emitLogRecord({
+        logger,
+        eventName: EVENT_NAMES.CHOICE,
+        payload,
+        extraAttrs: {
+            [GEN_AI.SYSTEM]: "anthropic",
+        },
+    });
+}
+//# sourceMappingURL=events.js.map

package/dist/esm/index.d.ts

@@ -0,0 +1,6 @@
+import { StructSDK } from "./core.js";
+export { ContentCaptureMode } from "./content-capture.js";
+export type { AgentScopeOptions, InitOptions, InternalLogger, ToolScopeOptions, } from "./core.js";
+export { StructSDK } from "./core.js";
+export declare const struct: StructSDK;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+import { StructSDK } from "./core.js";
+export { ContentCaptureMode } from "./content-capture.js";
+export { StructSDK } from "./core.js";
+export const struct = new StructSDK();
+//# sourceMappingURL=index.js.map

package/dist/esm/integrations/anthropic-content.d.ts

@@ -0,0 +1,24 @@
+import { truncateField } from "../truncation.js";
+/** Part in the GenAI spec format. */
+export type Part = Record<string, unknown>;
+/**
+ * Walk Anthropic response content blocks, return (name, id) pairs for tool_use blocks.
+ * Port of _iter_tool_uses from anthropic.py.
+ */
+export declare function iterToolUses(blocks: unknown): Array<[string, string]>;
+/**
+ * Convert arbitrary content (string | block[] | unknown) → GenAI parts.
+ * Port of _content_to_parts from anthropic.py.
+ */
+export declare function contentToParts(content: unknown): Part[];
+/** Convert Anthropic message list → GenAI input-messages JSON string. */
+export declare function toInputMessages(messages: unknown): string;
+/** Convert response content blocks → GenAI output-messages JSON string. */
+export declare function toOutputMessages(contentBlocks: unknown, stopReason: string | null | undefined): string;
+/** Convert system prompt (string | block[]) → GenAI system_instructions JSON string. */
+export declare function toSystemInstructions(system: unknown): string;
+export declare function safeJsonForTool(obj: unknown): string;
+/** Extract the last user message's parts for parent-span propagation. */
+export declare function lastUserMessageParts(messages: unknown): Part[] | undefined;
+export { truncateField };
+//# sourceMappingURL=anthropic-content.d.ts.map