@struct-ai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Struct
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,168 @@
+# @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.
+
+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
+the two SDKs so the server processes both uniformly.
+
+## Install
+
+```bash
+npm install @struct-ai/sdk
+# optional — the SDK auto-instruments these if present
+npm install @anthropic-ai/sdk @langchain/core @langchain/langgraph
+```
+
+Requires Node 18+.
+
+## Quickstart
+
+```ts
+import { struct } from "@struct-ai/sdk";
+// Initialize once, as early as possible in your process
+struct.init({
+  ingestKey: process.env.STRUCT_INGEST_KEY!,
+  serviceName: "my-agent",
+  environment: "production",
+});
+
+// Use your agent code as normal — spans + log events are emitted automatically.
+import Anthropic from "@anthropic-ai/sdk";
+const client = new Anthropic();
+
+await struct.agent({ name: "checkout" }, async () => {
+  const msg = await client.messages.create({
+    model: "claude-3-5-sonnet-20241022",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: "plan my checkout flow" }],
+  });
+
+  // tool_call_id is auto-filled from the preceding Anthropic response
+  await struct.tool({ name: "search" }, async () => {
+    return await search(msg);
+  });
+});
+```
+
+## What gets instrumented
+
+| Library | Hook | Span type | Notes |
+|---|---|---|---|
+| `@anthropic-ai/sdk` | `Messages.prototype.create`, `.stream` | `chat {model}` | Cache-token accounting, streaming with tool-use reconstruction |
+| `@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) |
+| `@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`, custom graphs. `thread_id` → `gen_ai.conversation.id` |
+
+## Content capture
+
+The SDK supports four capture modes controlling how prompt/response content is emitted.
+
+```ts
+import { struct, ContentCaptureMode } from "@struct-ai/sdk";
+struct.init({
+  ingestKey: ...,
+  contentCapture: ContentCaptureMode.EventOnly, // default
+  // or ContentCaptureMode.None, SpanOnly, SpanAndEvent
+});
+```
+
+- **`EventOnly`** (default): per-message content lands on OTel log records
+  (`gen_ai.{user,assistant,system,tool}.message`, `gen_ai.choice`). Spans carry
+  metadata only.
+- **`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.
+
+Set `captureContent: false` for the legacy bool API (equivalent to
+`ContentCaptureMode.None`).
+
+## Manual scopes
+
+`struct.agent()` and `struct.tool()` create `invoke_agent` and `execute_tool`
+spans. These are optional — LangChain's Pregel patch creates agent spans
+automatically when your graph has a `thread_id` in the config.
+
+```ts
+await struct.agent(
+  { name: "onboarding", sessionId: conversationId, metadata: { tenant: "acme" } },
+  async () => {
+    await struct.tool({ name: "fetch-profile" }, async () => {
+      return fetchProfile();
+    });
+  }
+);
+```
+
+Nested agents set `struct.agent.parent_session_id` on the inner span, linking
+subagents back to the parent.
+
+## Semantic conventions
+
+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.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}`
+- `gen_ai.conversation.id`
+- `gen_ai.tool.{name, call.id, call.arguments, call.result}`
+- `error.type` + `StatusCode.ERROR` on failures
+
+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.
+
+## Troubleshooting
+
+- **Spans missing after instrumenting:** Import `@struct-ai/sdk` (or `struct.init()`)
+  *before* the instrumented libraries, so their class prototypes are patched
+  before any instance is constructed. In most Node setups this is automatic, but
+  some bundlers tree-shake aggressively.
+- **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`).
+- **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
+  `@langchain/core/tools` — not `new DynamicTool({...})`. The `tool()` factory
+  wraps your function in `AsyncLocalStorageProviderSingleton.runWithConfig(...)`,
+  which is what lets the nested invoke inherit the tool's callback chain and
+  share the parent's trace_id. `DynamicTool` skips that wrap, so the subagent
+  starts a new trace and parent↔subagent linkage breaks. The `struct.agent.parent_session_id`
+  attribute is still set, so "Spawned by" on the child side still renders —
+  but the parent's forward link to the subagent won't appear.
+
+## Parity with the Python SDK
+
+Span names, attribute keys, and log event shapes match `struct-sdk-python`
+byte-for-byte. Running the same agent logic in both SDKs against the same
+tenant produces structurally identical traces in the Struct UI.
+
+One deliberate divergence: the TS SDK finalizes streaming chat spans via the
+`finalMessage` event, closing a known gap in the Python SDK where
+`messages.stream()` didn't populate the pending-tool-call queue.
+
+## Development
+
+```bash
+pnpm install
+pnpm -F @struct-ai/sdk typecheck
+pnpm -F @struct-ai/sdk test
+pnpm -F @struct-ai/sdk build
+```
+
+## License
+
+Apache-2.0

package/dist/commonjs/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/commonjs/content-capture.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentCaptureMode = void 0;
+exports.emitEventsFor = emitEventsFor;
+exports.emitSpanContentFor = emitSpanContentFor;
+exports.captureContentFor = captureContentFor;
+var ContentCaptureMode;
+(function (ContentCaptureMode) {
+    ContentCaptureMode["None"] = "none";
+    ContentCaptureMode["EventOnly"] = "event_only";
+    ContentCaptureMode["SpanOnly"] = "span_only";
+    ContentCaptureMode["SpanAndEvent"] = "span_and_event";
+})(ContentCaptureMode || (exports.ContentCaptureMode = ContentCaptureMode = {}));
+function emitEventsFor(mode) {
+    return mode === ContentCaptureMode.EventOnly || mode === ContentCaptureMode.SpanAndEvent;
+}
+function emitSpanContentFor(mode) {
+    return mode === ContentCaptureMode.SpanOnly || mode === ContentCaptureMode.SpanAndEvent;
+}
+function captureContentFor(mode) {
+    return mode !== ContentCaptureMode.None;
+}
+//# sourceMappingURL=content-capture.js.map

package/dist/commonjs/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/commonjs/context.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStore = getStore;
+exports.getSessionId = getSessionId;
+exports.getConversationId = getConversationId;
+exports.getAgentSpan = getAgentSpan;
+exports.getPendingToolCalls = getPendingToolCalls;
+exports.runWithContext = runWithContext;
+exports.ensurePendingToolCallsSlot = ensurePendingToolCallsSlot;
+exports.popPendingToolCallId = popPendingToolCallId;
+exports.pushPendingToolCalls = pushPendingToolCalls;
+exports.snapshotStore = snapshotStore;
+exports.runWithStore = runWithStore;
+exports.runInFreshContext = runInFreshContext;
+const node_async_hooks_1 = require("node:async_hooks");
+const als = new node_async_hooks_1.AsyncLocalStorage();
+function getStore() {
+    return als.getStore();
+}
+function getSessionId() {
+    return als.getStore()?.sessionId;
+}
+function getConversationId() {
+    return als.getStore()?.conversationId;
+}
+function getAgentSpan() {
+    return als.getStore()?.agentSpan;
+}
+function getPendingToolCalls() {
+    return als.getStore()?.pendingToolCalls;
+}
+function runWithContext(patch, fn) {
+    const current = als.getStore() ?? {};
+    const next = { ...current, ...patch };
+    return als.run(next, fn);
+}
+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.
+ */
+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.
+ */
+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. */
+function snapshotStore() {
+    const store = als.getStore();
+    return store ? { ...store } : undefined;
+}
+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). */
+function runInFreshContext(fn) {
+    return als.run({}, fn);
+}
+//# sourceMappingURL=context.js.map

package/dist/commonjs/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