@glasstrace/sdk 1.3.9 → 1.5.0

package/README.md

@@ -98,6 +98,62 @@ total cap). HTTP 4xx/5xx and malformed responses are surfaced
 immediately. Set `GLASSTRACE_SKIP_INIT_VERIFY=1` to skip verification
 for offline installs.
 
+## Refreshing agent instruction guidance
+
+`glasstrace init` and `glasstrace mcp add` write a managed Glasstrace
+MCP section into your project's agent instruction file (CLAUDE.md /
+codex.md / .cursorrules). The section opens with a cost-aware
+cross-tool decision paragraph telling your AI agent **when** Glasstrace
+MCP is worth calling and **which** tool is the cheapest first call for
+each symptom class.
+
+The managed section's start marker carries an SDK version stamp, e.g.
+`<!-- glasstrace:mcp:start v=1.5.0 -->`. When you upgrade
+`@glasstrace/sdk`, run:
+
+```bash
+npx glasstrace upgrade-instructions
+```
+
+The command refreshes every detected agent instruction file in one
+run. Files outside the markers are untouched; files without a
+Glasstrace managed section are left alone. The command is idempotent
+— re-running produces byte-for-byte identical output.
+
+`npx glasstrace mcp add` performs the same managed-section refresh
+when run with `--force` (or against a project whose marker file has
+shifted credentials), so either command is a valid upgrade path.
+
+### Stale-section warning at SDK init
+
+When the running SDK detects that an agent instruction file's stamp
+is strictly older than the running version, it writes a single
+stderr line at `registerGlasstrace()` time pointing at the upgrade
+command. Constraints:
+
+- Stderr only, never stdout. Tracing behaviour is unaffected.
+- At most one warning per process boot, even when multiple
+  `registerGlasstrace()` calls happen (test runners, hot reload).
+- Node-only — no-op on Edge / browser runtimes. Never throws.
+- Does not mutate any file at runtime; the user opts in by running
+  the upgrade command.
+- Suppressed by setting one of:
+
+  ```bash
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=1
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=true
+  GLASSTRACE_DISABLE_UPGRADE_NOTICE=yes
+  ```
+
+  (case-insensitive). Any other value, including unset, leaves the
+  warning enabled.
+
+Legacy unstamped managed sections (written by `@glasstrace/sdk`
+versions before 1.5.0) trigger no warning — those projects receive
+the refreshed text on their next `mcp add` or
+`upgrade-instructions` run, and the upgrade replaces the legacy
+block in place rather than appending a duplicate.
+
 ## Server Action detection (Next.js)
 
 Next.js does not emit a dedicated OTel span for Server Actions. The SDK
@@ -293,6 +349,74 @@ body data. If your account enables the flag but a span never carries
 the internal attribute (no adapter set it), the public attribute is
 still absent. The default is "off, twice".
 
+## Capturing side-effect evidence
+
+When debugging a bug whose root cause is which side-effect operation
+ran with which non-sensitive semantic value — "the cancellation email
+used the wrong locale", "the wrong invite role was sent" — the agent
+needs to know template key, role, locale, timezone, status, and phase,
+but never the recipient, the rendered subject or body, the calendar
+link, or any token that flowed through the operation. The SDK can
+record allowlisted side-effect evidence on the active trace via
+`recordSideEffect()`, gated by the `sideEffectEvidence` capture-config
+flag.
+
+What the SDK captures: a compact, normalized operation label, the
+operation kind (`email`, `calendar_link`, `webhook`, `external_api`,
+`queue`, `after_callback`), an optional lifecycle status
+(`scheduled`, `started`, `succeeded`, `failed`, `unknown`), an
+optional execution phase (`request`, `post_response`, `background`,
+`unknown`), and a small set of allowlisted semantic fields:
+`templateKey`, `providerOperation`, `role`, `locale`, `timezone`,
+`status`, `phase`. Each value is bounded to compact tokens — IANA
+timezones, BCP-47 locales, identifier-shaped enum tokens. The
+per-trace operation budget is five.
+
+What the SDK does not capture: recipient email addresses, sender or
+recipient names, rendered email subjects or bodies, calendar links,
+invite links, any URL with a query string or fragment, any
+`Authorization`/`Cookie`/bearer-shaped value, any
+password/token/api_key key-value pair, any UUID, any Glasstrace API
+key, any free-form prose, and any structured payload. Values matching
+those shapes are silently dropped and replaced with an integer count
+under the matching omission attribute. The dropped value never
+appears on the span, in any log line, or in any export.
+
+Behavior-neutrality: `recordSideEffect()` is an observer.  It does
+not send, retry, duplicate, schedule, or delay any side effect. It
+never throws. If no recording span is active, the call is a silent
+no-op.
+
+Account opt-in: the capture is gated on the `sideEffectEvidence` flag
+in your account's capture configuration, which the SDK fetches at
+init time. The flag defaults to `false`, so no side-effect attribute
+is ever attached unless your account has explicitly enabled it.
+
+```ts
+import { recordSideEffect } from "@glasstrace/sdk";
+
+await mailer.send({ to: recipient, template: "EventCanceledEmail" });
+recordSideEffect({
+  kind: "email",
+  operation: "email.send",
+  status: "succeeded",
+  phase: "request",
+  fields: {
+    templateKey: "EventCanceledEmail",
+    role: "invitee",
+    locale: "en-US",
+    timezone: "Europe/Paris",
+  },
+});
+```
+
+The SDK guard protects only callers of `recordSideEffect()`; user
+code that bypasses the SDK and writes directly to the OTel span will
+still hit the wire as-is and is filtered by the glasstrace-product
+ingestion service before persistence. This is intentional
+defense-in-depth: the SDK is the first gate; the product receiver
+is the second.
+
 ## Source maps
 
 Glasstrace uploads server-side source maps at build time and resolves

package/dist/capture-error-BmQz7xF6.d.cts

@@ -0,0 +1,455 @@
+import { G as GlasstraceEnvVars, f as GlasstraceOptions, A as AnonApiKey, g as SdkInitResponse, C as CaptureConfig, h as SdkHealthReport, I as ImportGraphPayload, i as SdkDiagnosticCode } from './index.d-Dq33YwFT.cjs';
+import { ReadableSpan } from './export/ReadableSpan';
+import { SpanExporter } from './export/SpanExporter';
+import { ExportResult } from './ExportResult';
+import { a as SessionManager } from './edge-entry-DaeG7D7S.cjs';
+import { SpanProcessor } from './SpanProcessor';
+
+/**
+ * Resolved configuration after merging explicit options with environment variables.
+ */
+interface ResolvedConfig {
+    apiKey: string | undefined;
+    endpoint: string;
+    forceEnable: boolean;
+    verbose: boolean;
+    environment: string | undefined;
+    coverageMapEnabled: boolean;
+    nodeEnv: string | undefined;
+    vercelEnv: string | undefined;
+}
+/**
+ * Reads all recognized Glasstrace environment variables from process.env.
+ * Returns undefined for any variable not set. Never throws.
+ */
+declare function readEnvVars(): GlasstraceEnvVars;
+/**
+ * Merges explicit GlasstraceOptions with environment variables.
+ * Explicit options take precedence over environment variables.
+ */
+declare function resolveConfig(options?: GlasstraceOptions): ResolvedConfig;
+/**
+ * Returns true when the SDK should be inactive (production detected without force-enable).
+ * Logic order:
+ *   1. forceEnable === true → return false (override)
+ *   2. NODE_ENV === 'production' → return true
+ *   3. VERCEL_ENV === 'production' → return true
+ *   4. Otherwise → return false
+ */
+declare function isProductionDisabled(config: ResolvedConfig): boolean;
+/**
+ * Returns true when no API key is configured (anonymous mode).
+ * Treats undefined, empty string, whitespace-only, and gt_anon_* keys as anonymous.
+ */
+declare function isAnonymousMode(config: ResolvedConfig): boolean;
+
+/**
+ * The set of recognized fetch target categories.
+ */
+type FetchTarget = "supabase" | "stripe" | "internal" | "unknown";
+/**
+ * Classifies an outbound fetch target URL into a known category.
+ * Classification is case-insensitive and based on the URL hostname.
+ * Uses dot-boundary matching to avoid false positives (e.g. evilstripe.com).
+ *
+ * Returns one of: 'supabase', 'stripe', 'internal', or 'unknown'.
+ */
+declare function classifyFetchTarget(url: string): FetchTarget;
+
+/**
+ * Reads an existing anonymous key from the filesystem.
+ * Returns the key if valid, or null if:
+ * - The file does not exist
+ * - The file content is invalid
+ * - An I/O error occurs
+ * - `node:fs` is unavailable (non-Node environment)
+ */
+declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
+/**
+ * Gets an existing anonymous key from the filesystem, or creates a new one.
+ *
+ * - If file exists and contains a valid key, returns it
+ * - If file does not exist or content is invalid, generates a new key via createAnonApiKey()
+ * - Writes the new key to `.glasstrace/anon_key`, creating the directory if needed
+ * - On file write failure: logs a warning, caches an ephemeral in-memory key so
+ *   repeated calls in the same process return the same key
+ * - In non-Node environments: returns an ephemeral in-memory key
+ */
+declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
+
+/**
+ * Reads and validates a cached config file from `.glasstrace/config`.
+ * Returns the parsed `SdkInitResponse` or `null` on any failure,
+ * including when `node:fs` is unavailable (non-Node environments).
+ */
+declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
+/**
+ * Persists the init response to `.glasstrace/config` using the SDK 2.0
+ * atomic-write protocol (`tmp + fsync(tmp) + rename + fsync(parent)`).
+ * Silently skipped when `node:fs` is unavailable (non-Node environments).
+ * On I/O failure, logs a warning.
+ *
+ * Atomicity: the payload is written to `.glasstrace/config.tmp`, fsynced
+ * to durable storage, then renamed into place; the parent directory is
+ * fsynced last so the rename survives an immediate crash. `rename` is
+ * atomic on POSIX filesystems, so readers either see the previous valid
+ * config or the new valid config — never a truncated or partially-written
+ * file (DISC-1247 Scenario 5). If any step fails, the temp file is
+ * cleaned up on a best-effort basis.
+ */
+declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
+/**
+ * Sends a POST request to `/v1/sdk/init`.
+ * Validates the response against `SdkInitResponseSchema`.
+ *
+ * Uses `node:https` via {@link httpsPostJson} rather than the global
+ * `fetch` because Next.js 16 patches `fetch` for caching/revalidation
+ * and can cause the init request to silently hang (DISC-493 Issue 3).
+ * Retries transport-level failures (DNS, TCP, TLS) twice with 500ms +
+ * 1500ms backoff, capped at a 20-second total deadline. Server responses
+ * (HTTP 4xx/5xx) are never retried and are surfaced immediately.
+ */
+declare function sendInitRequest(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string, importGraph?: ImportGraphPayload, healthReport?: SdkHealthReport, diagnostics?: Array<{
+    code: SdkDiagnosticCode;
+    message: string;
+    timestamp: number;
+}>, signal?: AbortSignal): Promise<SdkInitResponse>;
+/**
+ * Result returned by {@link performInit} when the backend reports an
+ * account claim transition. `null` means no claim was present.
+ */
+interface InitClaimResult {
+    claimResult: NonNullable<SdkInitResponse["claimResult"]>;
+}
+/**
+ * Orchestrates the full init flow: send request, update config, cache result.
+ * This function MUST NOT throw.
+ *
+ * Returns the claim result when the backend reports an account claim
+ * transition, or `null` when no claim result is available (including
+ * when init is skipped due to rate-limit backoff, missing API key,
+ * or request failure). Callers that do not need claim information
+ * can safely ignore the return value.
+ */
+declare function performInit(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string, healthReport?: SdkHealthReport | null): Promise<InitClaimResult | null>;
+/**
+ * Returns the current capture config from the three-tier fallback chain:
+ * 1. In-memory config from latest init response
+ * 2. File cache (read at most once per process lifetime)
+ * 3. DEFAULT_CAPTURE_CONFIG
+ *
+ * The disk read is cached via `configCacheChecked` to avoid repeated
+ * synchronous I/O on the hot path (called by GlasstraceExporter on
+ * every span export batch).
+ */
+declare function getActiveConfig(): CaptureConfig;
+/**
+ * Returns the `linkedAccountId` from the current in-memory init response,
+ * or `undefined` if no init response is available or no account is linked.
+ *
+ * Used by the discovery endpoint to determine whether `claimed: true`
+ * should be included in the response.
+ */
+declare function getLinkedAccountId(): string | undefined;
+
+/**
+ * Options for constructing a {@link GlasstraceExporter}.
+ */
+interface GlasstraceExporterOptions {
+    getApiKey: () => string;
+    sessionManager: SessionManager;
+    getConfig: () => CaptureConfig;
+    environment: string | undefined;
+    endpointUrl: string;
+    createDelegate: ((url: string, headers: Record<string, string>) => SpanExporter) | null;
+    /** When true, logs diagnostic details about enrichment decisions via sdkLog. */
+    verbose?: boolean;
+}
+/**
+ * A SpanExporter that enriches spans with glasstrace.* attributes at export
+ * time, then delegates to a real OTLP exporter.
+ *
+ * This design resolves three issues:
+ * - Spans emitted before the API key resolves are buffered (not dropped)
+ *   and flushed once the key is available.
+ * - Enrichment happens in the exporter (not onEnding), so it works
+ *   on Vercel where CompositeSpanProcessor does not forward onEnding().
+ * - Session ID is computed at export time using the resolved API key,
+ *   not the "pending" placeholder.
+ */
+declare class GlasstraceExporter implements SpanExporter {
+    private readonly getApiKey;
+    private readonly sessionManager;
+    private readonly getConfig;
+    private readonly environment;
+    private readonly endpointUrl;
+    private readonly createDelegateFn;
+    private readonly verbose;
+    private delegate;
+    private delegateKey;
+    private pendingBatches;
+    private pendingSpanCount;
+    private overflowLogged;
+    constructor(options: GlasstraceExporterOptions);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Called when the API key transitions from "pending" to a resolved value.
+     * Creates the delegate exporter and flushes all buffered spans.
+     */
+    notifyKeyResolved(): void;
+    shutdown(): Promise<void>;
+    /**
+     * Flushes any pending buffered spans (if the API key has resolved) and
+     * delegates to the underlying exporter's forceFlush to drain its queue.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Enriches a ReadableSpan with all glasstrace.* attributes.
+     * Returns a new ReadableSpan wrapper; the original span is not mutated.
+     *
+     * Only {@link SessionManager.getSessionId} is individually guarded because
+     * it calls into crypto and schema validation — a session ID failure should
+     * not prevent the rest of enrichment. The other helper calls
+     * ({@link deriveErrorCategory}, {@link deriveOrmProvider},
+     * {@link classifyFetchTarget}) are pure functions on typed string inputs
+     * and rely on the outer catch for any unexpected failure.
+     *
+     * On total failure, returns the original span unchanged.
+     */
+    private enrichSpan;
+    /**
+     * Lazily creates the delegate OTLP exporter once the API key is resolved.
+     * Recreates the delegate if the key has changed (e.g., after key rotation)
+     * so the Authorization header stays current.
+     */
+    private ensureDelegate;
+    /**
+     * Buffers raw (unenriched) spans while the API key is pending.
+     * Evicts oldest batches if the buffer exceeds MAX_PENDING_SPANS.
+     * Re-checks the key after buffering to close the race window where
+     * the key resolves between the caller's check and this buffer call.
+     */
+    private bufferSpans;
+    /**
+     * Flushes all buffered spans through the delegate exporter.
+     * Enriches spans at flush time (not buffer time) so that session IDs
+     * are computed with the resolved API key instead of the "pending" sentinel.
+     */
+    private flushPending;
+}
+
+/**
+ * The primary SDK entry point called by developers in their `instrumentation.ts`.
+ * Orchestrates OTel setup, span processor, init client, anon key, and discovery endpoint.
+ *
+ * This function is synchronous and MUST NOT throw. The developer's server is never blocked.
+ * Background work (key resolution, init call) happens via fire-and-forget promises.
+ *
+ * @param options - Optional SDK configuration. Environment variables are used as fallbacks.
+ *
+ * @example
+ * ```ts
+ * // instrumentation.ts
+ * import { registerGlasstrace } from "@glasstrace/sdk";
+ * registerGlasstrace(); // uses env vars
+ * ```
+ */
+declare function registerGlasstrace(options?: GlasstraceOptions): void;
+/**
+ * Returns the registered discovery handler, or null if not registered.
+ */
+declare function getDiscoveryHandler(): ((request: Request) => Promise<Response | null>) | null;
+
+/**
+ * Structural view of Next.js's `NextConfig`. The SDK does not import Next's
+ * type directly because Next is not a peer dependency — this wrapper must
+ * type-check regardless of which Next.js version the consumer has installed.
+ *
+ * The constraint is `object` rather than `Record<string, unknown>` because
+ * Next's actual `NextConfig` is an interface *without* a string index
+ * signature. Requiring `[key: string]: unknown` would fail the assignability
+ * check that caused DISC-1256, reported by Next 16 consumers as:
+ *   > Argument of type 'NextConfig' is not assignable to parameter of type
+ *   > 'NextConfig'. Index signature for type 'string' is missing in type
+ *   > 'NextConfig'.
+ *
+ * `object` accepts every non-primitive value, which is what the wrapper
+ * actually handles at runtime (it shallow-copies the input and reads a few
+ * known properties defensively). Combined with the generic signature on
+ * `withGlasstraceConfig`, callers preserve their exact config subtype.
+ */
+type NextConfig = object;
+/**
+ * Wraps the developer's Next.js config to enable source map generation
+ * and upload .map files to the ingestion API at build time.
+ *
+ * The build NEVER fails because of Glasstrace — all errors are caught
+ * and logged as warnings.
+ *
+ * ## What the wrapper configures for you
+ *
+ * - `experimental.serverSourceMaps: true` — enables server-side source maps
+ *   so Glasstrace can resolve stack traces back to your source.
+ * - `serverExternalPackages: ["@glasstrace/sdk"]` — tells Next to load the
+ *   SDK via Node's `require()` at runtime instead of bundling it through
+ *   webpack or Turbopack on the RSC / Route Handler paths. This is the same
+ *   pattern Prisma, `@vercel/otel`, Sentry, `sharp`, and `bcrypt` ship with.
+ * - A webpack `externals` entry that marks every Node.js built-in import
+ *   (both `node:*` and bare forms like `zlib` or `stream`) as a runtime
+ *   `commonjs` require. `serverExternalPackages` does not apply to the
+ *   instrumentation path under `next dev --webpack`
+ *   (vercel/next.js#58003, #28774), so any bundled SDK chunk that imports
+ *   `node:child_process` or the bare `zlib` specifier used by
+ *   `@opentelemetry/otlp-exporter-base` would otherwise crash with
+ *   `UnhandledSchemeError` or `Can't resolve 'zlib'`. This entry is the
+ *   actual DISC-1257 fix for the dev-webpack path. Turbopack is
+ *   unaffected — it ignores `config.webpack` and resolves Node built-ins
+ *   natively.
+ * - An empty `turbopack: {}` when none is set, so Next 16 does not reject
+ *   the config for setting `webpack` without a companion `turbopack` key
+ *   (DISC-1256).
+ * - A `webpack` hook that collects and uploads `.map` files on client-side
+ *   production builds.
+ *
+ * ## Turbopack
+ *
+ * Next.js 16 made Turbopack the default bundler for `next build`, and Next
+ * rejects configs that set `webpack` without also setting `turbopack`. This
+ * wrapper therefore seeds an empty `turbopack: {}` when the user has not set
+ * one themselves, preserving existing behaviour for explicit Turbopack configs.
+ *
+ * **Source-map upload is currently webpack-only.** Under Turbopack the build
+ * succeeds, but the afterEmit hook that collects and uploads `.map` files does
+ * not fire. Run `next build --webpack` to get source-map uploads, or wait for
+ * a follow-up release that ports the plugin to Turbopack.
+ *
+ * @param nextConfig - The developer's existing Next.js configuration object.
+ * @returns A new config object with source map generation and upload enabled.
+ *   The return type mirrors the input type so that caller-side config
+ *   properties are preserved. The `object` constraint (rather than
+ *   `Record<string, unknown>`) is what makes the wrapper accept Next's
+ *   real `NextConfig` interface (DISC-1256).
+ */
+declare function withGlasstraceConfig<T extends NextConfig>(nextConfig: T): T;
+
+/**
+ * Returns true when the SDK is in ACTIVE or ACTIVE_DEGRADED state.
+ */
+declare function isReady(): boolean;
+/**
+ * Resolves when the SDK reaches ACTIVE or ACTIVE_DEGRADED.
+ * Rejects on PRODUCTION_DISABLED, REGISTRATION_FAILED, or timeout.
+ *
+ * Checks current state synchronously first — resolves/rejects immediately
+ * if the SDK has already reached a terminal or ready state.
+ */
+declare function waitForReady(timeoutMs?: number): Promise<void>;
+/**
+ * Simplified public state query for external consumers.
+ * Hides implementation details like coexistence scenarios.
+ *
+ * The returned `tracing` field is the canonical user-observable signal
+ * for OTel coexistence outcomes:
+ *
+ * - `"active"` — the SDK owns the OTel provider and is exporting spans.
+ * - `"coexistence"` — another OTel provider was detected and the SDK
+ *   either auto-attached its span processor or found one already
+ *   present. Spans are exported through the existing pipeline.
+ * - `"degraded"` — the SDK is exporting but the core lifecycle entered
+ *   `ACTIVE_DEGRADED` (e.g., a non-fatal export failure).
+ * - `"not-configured"` — the SDK could not configure tracing. Covers
+ *   `OtelState.UNCONFIGURED`, `OtelState.CONFIGURING`, and
+ *   `OtelState.COEXISTENCE_FAILED` (the DISC-1556 Next 16 production
+ *   "auto-attach returned null" path). When the value is
+ *   `"not-configured"` after `registerGlasstrace()` has resolved,
+ *   spans are NOT reaching the Glasstrace exporter and the manual
+ *   `createGlasstraceSpanProcessor()` workaround should be applied.
+ *   See `runtime-state.json`'s `lastError` field for the structured
+ *   failure record.
+ */
+declare function getStatus(): {
+    ready: boolean;
+    mode: "anonymous" | "authenticated" | "claiming" | "disabled";
+    tracing: "active" | "degraded" | "not-configured" | "coexistence";
+};
+
+/**
+ * OTel Coexistence Public API
+ *
+ * Provides createGlasstraceSpanProcessor() for developers who want to
+ * manually integrate Glasstrace with their existing OTel provider
+ * (e.g., Sentry's openTelemetrySpanProcessors config option).
+ *
+ * Also provides the auto-attach path (tryAutoAttachGlasstraceProcessor)
+ * that configureOtel() uses when it detects a pre-registered provider
+ * at runtime (Next.js 16 production, Sentry, Datadog, New Relic). Both
+ * entry points reuse the same span-processor factory so the manual and
+ * automatic paths stay in lockstep.
+ *
+ * Design: sdk-otel-coexistence.md Sections 3, 4, 5, 6
+ */
+
+/**
+ * Creates a Glasstrace span processor for manual integration with an
+ * existing OTel provider.
+ *
+ * Use this when another tool (e.g., Sentry) owns the OTel provider and
+ * you want to add Glasstrace to their processor list:
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/nextjs";
+ * import { createGlasstraceSpanProcessor } from "@glasstrace/sdk";
+ *
+ * Sentry.init({
+ *   dsn: "...",
+ *   openTelemetrySpanProcessors: [createGlasstraceSpanProcessor()],
+ * });
+ * ```
+ *
+ * **Important:** `registerGlasstrace()` is still required even when using
+ * this function. The processor handles span transport (enrichment and
+ * export). `registerGlasstrace()` handles everything else: init calls,
+ * config sync, session management, anonymous key generation, discovery
+ * endpoint, and health reporting.
+ *
+ * @param options - Optional SDK configuration. If omitted, uses the same
+ *   config as registerGlasstrace() (environment variables).
+ * @returns A BatchSpanProcessor wrapping a GlasstraceExporter with the
+ *   branded Symbol.for('glasstrace.exporter') for coexistence detection.
+ */
+declare function createGlasstraceSpanProcessor(options?: GlasstraceOptions): SpanProcessor;
+
+/**
+ * Manual error capture API.
+ *
+ * Provides a simple function for developers to manually record errors
+ * as span events, independent of the `consoleErrors` config flag.
+ */
+/**
+ * Records an error as a span event on the currently active OTel span.
+ *
+ * Works regardless of the `consoleErrors` configuration — this is an
+ * explicit, opt-in API for manual error reporting. If no span is active
+ * or OTel is not available, the call is silently ignored.
+ *
+ * On the first captured error, may display a one-time diagnostic nudge
+ * to stderr if the MCP connection marker is absent (dev environments only).
+ *
+ * @param error - The error to capture. Accepts `Error` objects, strings, or any value.
+ *
+ * @example
+ * ```ts
+ * import { captureError } from "@glasstrace/sdk";
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   captureError(err);
+ *   // handle error normally...
+ * }
+ * ```
+ */
+declare function captureError(error: unknown): void;
+
+export { type FetchTarget as F, GlasstraceExporter as G, type InitClaimResult as I, type ResolvedConfig as R, type GlasstraceExporterOptions as a, classifyFetchTarget as b, captureError as c, createGlasstraceSpanProcessor as d, getDiscoveryHandler as e, getLinkedAccountId as f, getActiveConfig as g, getOrCreateAnonKey as h, getStatus as i, isAnonymousMode as j, isProductionDisabled as k, isReady as l, loadCachedConfig as m, readEnvVars as n, registerGlasstrace as o, performInit as p, resolveConfig as q, readAnonKey as r, saveCachedConfig as s, sendInitRequest as t, withGlasstraceConfig as u, waitForReady as w };