@struct-ai/sdk 0.1.0

package/dist/commonjs/truncation.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRUNCATION_MARKER = exports.MAX_FIELD_SIZE = exports.MAX_CONTENT_SIZE = void 0;
+exports.truncateField = truncateField;
+exports.truncateParts = truncateParts;
+exports.truncateAndSerialize = truncateAndSerialize;
+exports.safeJsonStringify = safeJsonStringify;
+exports.MAX_CONTENT_SIZE = 128 * 1024;
+exports.MAX_FIELD_SIZE = 16384;
+exports.TRUNCATION_MARKER = "… [truncated]";
+function truncateField(value, maxLen = exports.MAX_FIELD_SIZE) {
+    if (typeof value === "string" && value.length > maxLen) {
+        return value.slice(0, maxLen) + exports.TRUNCATION_MARKER;
+    }
+    return value;
+}
+function truncateParts(parts) {
+    const result = [];
+    for (const original of parts) {
+        const part = { ...original };
+        if (typeof part.content === "string") {
+            part.content = truncateField(part.content);
+        }
+        if ("arguments" in part) {
+            const arg = part.arguments;
+            if (typeof arg === "string") {
+                part.arguments = truncateField(arg);
+            }
+            else if (arg && typeof arg === "object") {
+                const serialized = safeJsonStringify(arg);
+                if (serialized.length > exports.MAX_FIELD_SIZE) {
+                    part.arguments = serialized.slice(0, exports.MAX_FIELD_SIZE) + exports.TRUNCATION_MARKER;
+                }
+            }
+        }
+        if ("response" in part) {
+            const resp = part.response;
+            if (typeof resp === "string") {
+                part.response = truncateField(resp);
+            }
+            else if (resp && typeof resp === "object") {
+                const serialized = safeJsonStringify(resp);
+                if (serialized.length > exports.MAX_FIELD_SIZE) {
+                    part.response = serialized.slice(0, exports.MAX_FIELD_SIZE) + exports.TRUNCATION_MARKER;
+                }
+            }
+        }
+        result.push(part);
+    }
+    return result;
+}
+function truncateAndSerialize(obj, maxSize = exports.MAX_CONTENT_SIZE) {
+    let result;
+    if (Array.isArray(obj)) {
+        const truncated = obj.map((item) => {
+            if (!item || typeof item !== "object")
+                return item;
+            const copy = { ...item };
+            if (Array.isArray(copy.parts)) {
+                copy.parts = truncateParts(copy.parts);
+            }
+            else if (typeof copy.content === "string") {
+                copy.content = truncateField(copy.content);
+            }
+            return copy;
+        });
+        result = safeJsonStringify(truncated);
+    }
+    else {
+        result = safeJsonStringify(obj);
+    }
+    if (result.length > maxSize) {
+        const cut = result.slice(0, maxSize - 50);
+        const lastBrace = cut.lastIndexOf("}");
+        if (lastBrace > 0) {
+            result = cut.slice(0, lastBrace + 1) + "]";
+        }
+        else {
+            result = "[]";
+        }
+    }
+    return result;
+}
+function safeJsonStringify(obj) {
+    try {
+        return JSON.stringify(obj, defaultReplacer);
+    }
+    catch {
+        return JSON.stringify(String(obj));
+    }
+}
+function defaultReplacer(_key, value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}`;
+    if (value instanceof Map)
+        return Object.fromEntries(value.entries());
+    if (value instanceof Set)
+        return Array.from(value);
+    return value;
+}
+//# sourceMappingURL=truncation.js.map

package/dist/esm/content-capture.d.ts

@@ -0,0 +1,10 @@
+export declare enum ContentCaptureMode {
+    None = "none",
+    EventOnly = "event_only",
+    SpanOnly = "span_only",
+    SpanAndEvent = "span_and_event"
+}
+export declare function emitEventsFor(mode: ContentCaptureMode): boolean;
+export declare function emitSpanContentFor(mode: ContentCaptureMode): boolean;
+export declare function captureContentFor(mode: ContentCaptureMode): boolean;
+//# sourceMappingURL=content-capture.d.ts.map

package/dist/esm/content-capture.js

@@ -0,0 +1,17 @@
+export var ContentCaptureMode;
+(function (ContentCaptureMode) {
+    ContentCaptureMode["None"] = "none";
+    ContentCaptureMode["EventOnly"] = "event_only";
+    ContentCaptureMode["SpanOnly"] = "span_only";
+    ContentCaptureMode["SpanAndEvent"] = "span_and_event";
+})(ContentCaptureMode || (ContentCaptureMode = {}));
+export function emitEventsFor(mode) {
+    return mode === ContentCaptureMode.EventOnly || mode === ContentCaptureMode.SpanAndEvent;
+}
+export function emitSpanContentFor(mode) {
+    return mode === ContentCaptureMode.SpanOnly || mode === ContentCaptureMode.SpanAndEvent;
+}
+export function captureContentFor(mode) {
+    return mode !== ContentCaptureMode.None;
+}
+//# sourceMappingURL=content-capture.js.map

package/dist/esm/context.d.ts

@@ -0,0 +1,30 @@
+import type { Span } from "@opentelemetry/api";
+export interface StructContext {
+    sessionId?: string;
+    conversationId?: string;
+    agentSpan?: Span;
+    pendingToolCalls?: Record<string, string[]>;
+}
+export declare function getStore(): StructContext | undefined;
+export declare function getSessionId(): string | undefined;
+export declare function getConversationId(): string | undefined;
+export declare function getAgentSpan(): Span | undefined;
+export declare function getPendingToolCalls(): Record<string, string[]> | undefined;
+export declare function runWithContext<T>(patch: Partial<StructContext>, fn: () => T): T;
+export declare function ensurePendingToolCallsSlot(): Record<string, string[]>;
+/**
+ * Pop the first pending tool_use id matching `name`, or undefined.
+ * FIFO semantics match Python struct-sdk-python.
+ */
+export declare function popPendingToolCallId(name: string): string | undefined;
+/**
+ * Push (name, id) pairs into the active pending-tool-calls slot.
+ * Initializes a transient dict if no active agent scope.
+ */
+export declare function pushPendingToolCalls(pairs: readonly [string, string][]): void;
+/** Snapshot the store for wrapping async iterators. */
+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;
+//# sourceMappingURL=context.d.ts.map

package/dist/esm/context.js

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const als = new AsyncLocalStorage();
+export function getStore() {
+    return als.getStore();
+}
+export function getSessionId() {
+    return als.getStore()?.sessionId;
+}
+export function getConversationId() {
+    return als.getStore()?.conversationId;
+}
+export function getAgentSpan() {
+    return als.getStore()?.agentSpan;
+}
+export function getPendingToolCalls() {
+    return als.getStore()?.pendingToolCalls;
+}
+export function runWithContext(patch, fn) {
+    const current = als.getStore() ?? {};
+    const next = { ...current, ...patch };
+    return als.run(next, fn);
+}
+export function ensurePendingToolCallsSlot() {
+    const store = als.getStore();
+    if (store) {
+        if (!store.pendingToolCalls) {
+            store.pendingToolCalls = {};
+        }
+        return store.pendingToolCalls;
+    }
+    // No active store — nothing to attach to. Caller is expected to handle this.
+    return {};
+}
+/**
+ * Pop the first pending tool_use id matching `name`, or undefined.
+ * FIFO semantics match Python struct-sdk-python.
+ */
+export function popPendingToolCallId(name) {
+    const pending = getPendingToolCalls();
+    if (!pending)
+        return undefined;
+    const ids = pending[name];
+    if (!ids || ids.length === 0)
+        return undefined;
+    return ids.shift();
+}
+/**
+ * Push (name, id) pairs into the active pending-tool-calls slot.
+ * Initializes a transient dict if no active agent scope.
+ */
+export function pushPendingToolCalls(pairs) {
+    if (pairs.length === 0)
+        return;
+    const store = als.getStore();
+    if (!store)
+        return;
+    if (!store.pendingToolCalls) {
+        store.pendingToolCalls = {};
+    }
+    for (const [name, id] of pairs) {
+        if (!store.pendingToolCalls[name])
+            store.pendingToolCalls[name] = [];
+        store.pendingToolCalls[name].push(id);
+    }
+}
+/** Snapshot the store for wrapping async iterators. */
+export function snapshotStore() {
+    const store = als.getStore();
+    return store ? { ...store } : undefined;
+}
+export function runWithStore(store, fn) {
+    if (!store)
+        return fn();
+    return als.run(store, fn);
+}
+/** Test-only: run `fn` inside a completely fresh context (no parent store). */
+export function runInFreshContext(fn) {
+    return als.run({}, fn);
+}
+//# sourceMappingURL=context.js.map

package/dist/esm/core.d.ts

@@ -0,0 +1,120 @@
+import { type Tracer } from "@opentelemetry/api";
+import { type Logger } from "@opentelemetry/api-logs";
+import { type LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { ContentCaptureMode } from "./content-capture.js";
+export declare const DEFAULT_ENDPOINT = "https://ingest.struct.ai";
+export interface InitOptions {
+    ingestKey: string;
+    serviceName?: string;
+    serviceVersion?: string;
+    environment?: string;
+    endpoint?: string;
+    captureContent?: boolean;
+    contentCapture?: ContentCaptureMode;
+    /**
+     * Maximum time `shutdown()` is allowed to spend flushing telemetry providers
+     * before returning. If the ingest endpoint is dead or slow, shutdown returns
+     * within this budget rather than hanging the host process exit. Defaults to
+     * 5000ms. Can be overridden per call via `shutdown(timeoutMs)`.
+     */
+    shutdownTimeoutMs?: number;
+}
+export interface AgentScopeOptions {
+    name: string;
+    sessionId?: string;
+    /**
+     * Stable identifier for the agent DEFINITION — `gen_ai.agent.id` per the OTel
+     * GenAI spec. Not the same as sessionId (which identifies a single
+     * invocation / conversation). Omit if you don't have a stable ID.
+     */
+    agentId?: string;
+    version?: string;
+    metadata?: Record<string, string>;
+}
+export interface ToolScopeOptions {
+    name: string;
+    toolCallId?: string;
+}
+export interface InternalLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+/**
+ * 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 declare const firstFailureLogged: Set<string>;
+/**
+ * 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 declare function safe(fn: () => void, site: string, logger: InternalLogger): void;
+export declare class StructSDK {
+    private _initialized;
+    private _tracerProvider;
+    private _loggerProvider;
+    private _ingestKey;
+    private _endpoint;
+    private _contentCapture;
+    private _shutdownHook;
+    private _shutdownTimeoutMs;
+    private _internalLogger;
+    private _readyPromise;
+    /** Resolves once auto-instrumentation has attempted to patch every detected library. */
+    get ready(): Promise<void>;
+    get initialized(): boolean;
+    get endpoint(): string;
+    get ingestKey(): string;
+    get contentCapture(): ContentCaptureMode;
+    get captureContent(): boolean;
+    get emitEvents(): boolean;
+    get emitSpanContent(): boolean;
+    init(options: InitOptions): void;
+    getTracer(name?: string): Tracer;
+    getLogger(name?: string): Logger;
+    getInternalLogger(): InternalLogger;
+    /** Test-only: attach a custom span processor to the internal provider. */
+    addSpanProcessor(processor: SpanProcessor): void;
+    /** Test-only: attach a custom log record processor. */
+    addLogRecordProcessor(processor: LogRecordProcessor): void;
+    /**
+     * 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.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Run `fn` inside an `invoke_agent` span scope.
+     * Matches Python's _AgentContext behavior.
+     */
+    agent<T>(options: AgentScopeOptions, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Run `fn` inside an `execute_tool` span scope.
+     * Matches Python's _ToolContext behavior.
+     */
+    tool<T>(options: ToolScopeOptions, fn: () => Promise<T> | T): Promise<T>;
+}
+//# sourceMappingURL=core.d.ts.map