@autter/runtime-node 0.1.0 → 1.1.0

package/dist/index.d.cts

@@ -43,13 +43,52 @@ declare function createBrowserRelayHandler(opts: RelayOptions): (req: IncomingMe
     body?: unknown;
 }, res: ServerResponse) => void;
 
+interface RedactOptions {
+    /**
+     * Extra patterns matched against lower-cased attribute KEYS; a match
+     * masks the whole value. Strings become case-insensitive substring
+     * patterns. Extends the built-in list.
+     */
+    additionalKeyPatterns?: (RegExp | string)[];
+    /**
+     * Extra patterns scrubbed inside string VALUES (same semantics as the
+     * built-in email/token patterns). Extends the built-in list.
+     */
+    additionalValuePatterns?: (RegExp | string)[];
+    /** Replacement token. Default "[redacted]". */
+    mask?: string;
+    /**
+     * Scrub email-shaped substrings from ALL string values, not just
+     * sensitive keys. Default true.
+     */
+    scrubEmailValues?: boolean;
+}
+/**
+ * Return a copy of `attributes` with PII/secrets masked. Never mutates the
+ * input; non-string primitives pass through untouched; `undefined` values
+ * are dropped (OpenTelemetry rejects them).
+ */
+declare function redactAttributes(attributes?: Attributes | null, options?: RedactOptions): Attributes;
+
 /**
  * Curated OpenTelemetry setup for Autter Runtime — deliberately NOT the
  * auto-instrumentation metapackage. Default data-volume policy:
  *
  *   errors / captured exceptions : 100%  (dedicated always-on error tracer)
+ *   traces containing an error   : 100%  (tail retention — the full trace is
+ *                                         exported when any of its spans
+ *                                         errors, so a retained error keeps
+ *                                         the trace that explains it)
+ *   named process spans          : 100%  (withProcessSpan, always-on tracer)
+ *   LLM / GenAI call spans       : 100%  (withLlmCall/trackLlmCall/
+ *                                         instrumentLlmClient + an LLM-aware
+ *                                         sampler that keeps GenAI/Vercel-AI
+ *                                         spans — cost tracking needs every
+ *                                         call)
  *   successful traces            : 1%    (head sampling, configurable)
- *   request metrics              : aggregated every 60 s
+ *   request metrics              : aggregated every 60 s, keyed by route
+ *                                  template (Express routes detected
+ *                                  out of the box — see captureExpressRoute)
  *   logs                         : not collected
  *
  * Exports OTLP/HTTP JSON to the Autter ingester (`/v1/traces`,
@@ -66,14 +105,97 @@ interface AutterServerOptions {
     release?: string;
     /** Head-sampling ratio for regular traces. Default 0.01 (1%). */
     traceSampleRate?: number;
+    /**
+     * Keep the FULL trace whenever it contains an error: an ERROR-status
+     * span (e.g. a 5xx request), a recorded exception, or a
+     * `captureException` / error-severity `captureMessage` call made inside
+     * it. Head sampling still decides what is exported for healthy traffic;
+     * erroring traces are rescued from the unsampled pool by a bounded
+     * in-process buffer — without this, errors are retained at 100% while
+     * the trace explaining them survives only `traceSampleRate` of the time.
+     * Default true.
+     */
+    retainTracesOnError?: boolean;
     /** Metric export interval. Default 60_000 ms. */
     metricIntervalMs?: number;
     /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
     captureGlobalErrors?: boolean;
+    /**
+     * Flush all exporters when the process exits (`beforeExit`, SIGINT,
+     * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
+     * telemetry. If your code also handles the signal, Autter only flushes
+     * alongside it and never changes your exit path. Default true.
+     */
+    autoFlush?: boolean;
+    /**
+     * Mask PII/secrets in custom attributes before they leave the process:
+     * emails, tokens (JWT, sk-, gh_, AWS, Slack), bearer headers,
+     * `scheme://user:pass@` URLs, and anything whose attribute KEY looks
+     * sensitive (password/token/secret/cookie/…). Mirrors the browser
+     * relay's whitelist sanitiser. `true`/undefined = defaults; pass a
+     * RedactOptions object to extend the patterns; `false` disables.
+     * Default true.
+     */
+    redactAttributes?: boolean | RedactOptions;
+    /**
+     * Verbose lifecycle logging to stderr: "exported N spans", flushes and
+     * auto-flush activity — handy while wiring the SDK up. Also enabled by
+     * the AUTTER_DEBUG=1 environment variable. Default false.
+     */
+    debug?: boolean;
+    /**
+     * Record LLM/GenAI spans (`gen_ai.*` semconv, Vercel AI SDK `ai.*`,
+     * `withLlmCall`) at 100% regardless of `traceSampleRate`, so every model
+     * call is tracked with tokens/cost (default true).
+     */
+    llmTracing?: boolean;
     /** Extra instrumentations (e.g. `new ExpressInstrumentation()`). */
     instrumentations?: unknown[];
 }
 type AutterSeverity = "fatal" | "error" | "warning" | "info";
+/** Token usage (and optionally exact cost) of one LLM call. */
+interface LlmUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    /**
+     * Exact cost in USD, if the provider reports it. Overrides Autter's
+     * built-in per-model price estimate.
+     */
+    costUsd?: number;
+}
+interface LlmCallInfo {
+    /** Provider system: "openai", "anthropic", "google", "mistral_ai", … */
+    provider: string;
+    /** Requested model id, e.g. "gpt-5-mini" or "claude-sonnet-4". */
+    model: string;
+    /** "chat" (default), "embeddings", "text_completion", … */
+    operation?: string;
+    /** Opaque end-user id for per-user cost attribution — never an email. */
+    userId?: string;
+    sessionId?: string;
+    /** Extra span attributes (kept under the gen_ai./autter.llm. families). */
+    attributes?: Attributes;
+}
+/** Reporting surface handed to the `withLlmCall` callback. */
+interface LlmCallHandle {
+    /** Report token usage / exact cost from the provider response. */
+    setUsage(usage: LlmUsage): void;
+    /** Exact cost in USD; without it the ingester estimates from its price table. */
+    setCost(usd: number): void;
+    /** Record the model the provider actually served (gen_ai.response.model). */
+    setResponseModel(model: string): void;
+    /** Alias of setResponseModel. */
+    setModel(model: string): void;
+    /** Extra span attributes reported mid-call. */
+    setAttributes(attributes: Attributes): void;
+}
+/** A completed LLM call reported after the fact via `trackLlmCall`. */
+interface TrackedLlmCall extends LlmCallInfo, LlmUsage {
+    /** Wall-clock duration of the call, if measured. */
+    durationMs?: number;
+    /** Pass the thrown error to record the call as failed. */
+    error?: unknown;
+}
 interface AutterServer {
     /** Report a handled exception. Always recorded (never sampled out). */
     captureException(error: unknown, attributes?: Attributes): void;
@@ -83,6 +205,41 @@ interface AutterServer {
      * errors with a lower severity so aggregations can slice one dataset.
      */
     captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /**
+     * Wrap a named unit of work — a background job, queue consumer, cron
+     * tick, or DB-heavy call — in an always-recorded span. Unlike regular
+     * traces these are never head-sampled, so Autter's slow-process monitor
+     * sees accurate run counts and durations for non-HTTP work. Nested
+     * instrumented calls run inside the span's context, so slow traces show
+     * where the time went. Rethrows whatever `fn` throws.
+     */
+    withProcessSpan<T>(name: string, fn: () => T | Promise<T>, attributes?: Attributes): Promise<T>;
+    /**
+     * Wrap one LLM provider call. Always recorded (never head-sampled), so
+     * Autter's LLM usage/cost dashboards and anomaly monitor see every call.
+     * Report tokens via the handle once the response arrives; cost is
+     * estimated from the model id unless `setCost(usd)` (or
+     * `setUsage({ costUsd })`) reports the exact figure. Rethrows whatever
+     * `fn` throws (failed calls are recorded with the error attached).
+     *
+     *   const reply = await autter.withLlmCall(
+     *     { provider: "openai", model: "gpt-5-mini", userId: user.id },
+     *     async (llm) => {
+     *       const res = await openai.chat.completions.create({ ... });
+     *       llm.setUsage({
+     *         inputTokens: res.usage?.prompt_tokens,
+     *         outputTokens: res.usage?.completion_tokens,
+     *       });
+     *       return res;
+     *     },
+     *   );
+     */
+    withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T | Promise<T>): Promise<T>;
+    /**
+     * Report an already-completed LLM call — for codepaths where wrapping is
+     * awkward (queues, callbacks, batch results). Fire-and-forget.
+     */
+    trackLlmCall(call: TrackedLlmCall): void;
     /** Flush and stop all exporters. Call on graceful shutdown. */
     shutdown(): Promise<void>;
 }
@@ -90,7 +247,131 @@ declare function initAutterServer(options: AutterServerOptions): AutterServer;
 /** Module-level convenience — routes to the active server, or degrades to a
  * span on the global tracer so libraries can call it unconditionally. */
 declare function captureException(error: unknown, attributes?: Attributes): void;
+/**
+ * Module-level convenience — see AutterServer.withProcessSpan. Before
+ * initAutterServer runs it degrades to the global tracer, where the span is
+ * subject to that provider's own sampling instead of the always-on pipe.
+ */
+declare function withProcessSpan<T>(name: string, fn: () => T | Promise<T>, attributes?: Attributes): Promise<T>;
+/**
+ * Module-level convenience — see AutterServer.withLlmCall. Before
+ * initAutterServer runs it degrades to the global tracer, where the span is
+ * subject to that provider's own sampling instead of the always-on pipe.
+ */
+declare function withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T | Promise<T>): Promise<T>;
+/** Module-level convenience — see AutterServer.trackLlmCall. */
+declare function trackLlmCall(call: TrackedLlmCall): void;
 /** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
 declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+/** Capture surface with guaranteed redaction, regardless of how the host app
+ * configured initAutterServer — for library authors whose calls must never
+ * forward PII even when the host disabled it. Routes to the active server
+ * (or degrades to the global tracer exactly like captureException). */
+interface SafeCapture {
+    captureException(error: unknown, attributes?: Attributes): void;
+    captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+}
+/**
+ * Build a redacting capture wrapper:
+ *
+ *   const safe = makeSafeCapture();
+ *   safe.captureException(err, { "user.email": email }); // masked before export
+ *
+ * The returned functions have the same signatures as their plain twins;
+ * every attribute passes through redactAttributes() first. Note that when
+ * the host has NOT disabled redaction this is belt-and-braces (already on by
+ * default) — its value is enforcing privacy inside libraries and wrappers.
+ */
+declare function makeSafeCapture(options?: RedactOptions): SafeCapture;
+/**
+ * Emit one clearly-named fake LLM call (provider/model "autter-selftest",
+ * 1 input + 1 output token, cost 0) and force-flush it, returning the
+ * traceId — proves LLM traces reach the ingester without calling any real
+ * model. For setup verification only; requires initAutterServer.
+ */
+declare function emitLlmSelftestTrace(): Promise<{
+    traceId: string;
+}>;
+
+interface AutterLogger {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface FlushTarget {
+    forceFlush(): Promise<unknown> | unknown;
+}
+interface AutoFlushOptions {
+    /**
+     * Targets to flush. Defaults to whatever initAutterServer has registered;
+     * pass your own for custom pipelines.
+     */
+    targets?: FlushTarget[];
+    /** Where lifecycle messages go. Default console. */
+    logger?: AutterLogger;
+    /** Log each successful flush ("flushed telemetry (SIGTERM)"). Default true. */
+    log?: boolean;
+    /**
+     * Warn on stderr when the process exits with captures that were never
+     * confirmed exported. Default true.
+     */
+    warnOnUnflushedExit?: boolean;
+    /**
+     * Max wall-clock time a single flush may take before giving up (and, on
+     * signals, proceeding to exit anyway). Default 3000 ms.
+     */
+    timeoutMs?: number;
+    /** Signals handled besides the defaults. Default ["SIGINT", "SIGTERM"]. */
+    signals?: string[];
+}
+interface AutoFlushHandle {
+    /** Force-flush now. Safe to call repeatedly; concurrent calls coalesce. */
+    flush(reason?: string): Promise<boolean>;
+    /** Remove every listener this install added. */
+    dispose(): void;
+}
+/**
+ * Flush all exporters when the process is going away:
+ *
+ *   - `beforeExit` — event-loop drained naturally: force-flush, then hand the
+ *     loop back (a kept-alive timer makes sure the async flush finishes
+ *     inside the beforeExit window).
+ *   - SIGINT / SIGTERM — flush, then exit with the conventional code (130 /
+ *     143). If YOUR code also listens to the signal, we only flush
+ *     concurrently and let your handler decide the exit — installing this
+ *     never changes an existing graceful-shutdown path. A second signal
+ *     always exits immediately.
+ *
+ * Idempotent per options object; `initAutterServer` installs it by default
+ * (`autoFlush: false` opts out).
+ */
+declare function installAutterAutoFlush(options?: AutoFlushOptions): AutoFlushHandle;
+
+/**
+ * One-line LLM client auto-instrumentation:
+ *
+ *   const openai = instrumentLlmClient(new OpenAI());
+ *
+ * Wraps a provider SDK instance (OpenAI, Anthropic, Google GenAI, or any
+ * client with the same call shapes) in a deep proxy. Every model invocation —
+ * a method like `create`/`stream`/`generateContent` called with an object
+ * argument carrying a `model` — is recorded as a gen_ai span on the
+ * always-recorded pipe: model, tokens, latency, errors, and (ingester-side)
+ * USD cost. Streaming responses are supported: the span stays open until the
+ * stream is consumed, picking up usage from the final chunks.
+ *
+ * Nothing about the client's behaviour changes; methods run with the
+ * original `this` (SDK private fields keep working) and results pass
+ * through untouched apart from the stream wrapper.
+ */
+interface InstrumentLlmOptions {
+    /** Provider id ("openai", "anthropic", …). Default: detected from the client. */
+    provider?: string;
+    /** Opaque end-user id (never an email) — static or resolved per call. */
+    userId?: string | (() => string | undefined);
+    /** Extra attributes for every span from this client. */
+    attributes?: Attributes;
+}
+declare function instrumentLlmClient<T extends object>(client: T, options?: InstrumentLlmOptions): T;
 
-export { type AutterServer, type AutterServerOptions, type AutterSeverity, type RelayOptions, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, initAutterServer, sanitizeBrowserPayload };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, sanitizeBrowserPayload, trackLlmCall, withLlmCall, withProcessSpan };

package/dist/index.d.ts

@@ -43,13 +43,52 @@ declare function createBrowserRelayHandler(opts: RelayOptions): (req: IncomingMe
     body?: unknown;
 }, res: ServerResponse) => void;
 
+interface RedactOptions {
+    /**
+     * Extra patterns matched against lower-cased attribute KEYS; a match
+     * masks the whole value. Strings become case-insensitive substring
+     * patterns. Extends the built-in list.
+     */
+    additionalKeyPatterns?: (RegExp | string)[];
+    /**
+     * Extra patterns scrubbed inside string VALUES (same semantics as the
+     * built-in email/token patterns). Extends the built-in list.
+     */
+    additionalValuePatterns?: (RegExp | string)[];
+    /** Replacement token. Default "[redacted]". */
+    mask?: string;
+    /**
+     * Scrub email-shaped substrings from ALL string values, not just
+     * sensitive keys. Default true.
+     */
+    scrubEmailValues?: boolean;
+}
+/**
+ * Return a copy of `attributes` with PII/secrets masked. Never mutates the
+ * input; non-string primitives pass through untouched; `undefined` values
+ * are dropped (OpenTelemetry rejects them).
+ */
+declare function redactAttributes(attributes?: Attributes | null, options?: RedactOptions): Attributes;
+
 /**
  * Curated OpenTelemetry setup for Autter Runtime — deliberately NOT the
  * auto-instrumentation metapackage. Default data-volume policy:
  *
  *   errors / captured exceptions : 100%  (dedicated always-on error tracer)
+ *   traces containing an error   : 100%  (tail retention — the full trace is
+ *                                         exported when any of its spans
+ *                                         errors, so a retained error keeps
+ *                                         the trace that explains it)
+ *   named process spans          : 100%  (withProcessSpan, always-on tracer)
+ *   LLM / GenAI call spans       : 100%  (withLlmCall/trackLlmCall/
+ *                                         instrumentLlmClient + an LLM-aware
+ *                                         sampler that keeps GenAI/Vercel-AI
+ *                                         spans — cost tracking needs every
+ *                                         call)
  *   successful traces            : 1%    (head sampling, configurable)
- *   request metrics              : aggregated every 60 s
+ *   request metrics              : aggregated every 60 s, keyed by route
+ *                                  template (Express routes detected
+ *                                  out of the box — see captureExpressRoute)
  *   logs                         : not collected
  *
  * Exports OTLP/HTTP JSON to the Autter ingester (`/v1/traces`,
@@ -66,14 +105,97 @@ interface AutterServerOptions {
     release?: string;
     /** Head-sampling ratio for regular traces. Default 0.01 (1%). */
     traceSampleRate?: number;
+    /**
+     * Keep the FULL trace whenever it contains an error: an ERROR-status
+     * span (e.g. a 5xx request), a recorded exception, or a
+     * `captureException` / error-severity `captureMessage` call made inside
+     * it. Head sampling still decides what is exported for healthy traffic;
+     * erroring traces are rescued from the unsampled pool by a bounded
+     * in-process buffer — without this, errors are retained at 100% while
+     * the trace explaining them survives only `traceSampleRate` of the time.
+     * Default true.
+     */
+    retainTracesOnError?: boolean;
     /** Metric export interval. Default 60_000 ms. */
     metricIntervalMs?: number;
     /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
     captureGlobalErrors?: boolean;
+    /**
+     * Flush all exporters when the process exits (`beforeExit`, SIGINT,
+     * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
+     * telemetry. If your code also handles the signal, Autter only flushes
+     * alongside it and never changes your exit path. Default true.
+     */
+    autoFlush?: boolean;
+    /**
+     * Mask PII/secrets in custom attributes before they leave the process:
+     * emails, tokens (JWT, sk-, gh_, AWS, Slack), bearer headers,
+     * `scheme://user:pass@` URLs, and anything whose attribute KEY looks
+     * sensitive (password/token/secret/cookie/…). Mirrors the browser
+     * relay's whitelist sanitiser. `true`/undefined = defaults; pass a
+     * RedactOptions object to extend the patterns; `false` disables.
+     * Default true.
+     */
+    redactAttributes?: boolean | RedactOptions;
+    /**
+     * Verbose lifecycle logging to stderr: "exported N spans", flushes and
+     * auto-flush activity — handy while wiring the SDK up. Also enabled by
+     * the AUTTER_DEBUG=1 environment variable. Default false.
+     */
+    debug?: boolean;
+    /**
+     * Record LLM/GenAI spans (`gen_ai.*` semconv, Vercel AI SDK `ai.*`,
+     * `withLlmCall`) at 100% regardless of `traceSampleRate`, so every model
+     * call is tracked with tokens/cost (default true).
+     */
+    llmTracing?: boolean;
     /** Extra instrumentations (e.g. `new ExpressInstrumentation()`). */
     instrumentations?: unknown[];
 }
 type AutterSeverity = "fatal" | "error" | "warning" | "info";
+/** Token usage (and optionally exact cost) of one LLM call. */
+interface LlmUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    /**
+     * Exact cost in USD, if the provider reports it. Overrides Autter's
+     * built-in per-model price estimate.
+     */
+    costUsd?: number;
+}
+interface LlmCallInfo {
+    /** Provider system: "openai", "anthropic", "google", "mistral_ai", … */
+    provider: string;
+    /** Requested model id, e.g. "gpt-5-mini" or "claude-sonnet-4". */
+    model: string;
+    /** "chat" (default), "embeddings", "text_completion", … */
+    operation?: string;
+    /** Opaque end-user id for per-user cost attribution — never an email. */
+    userId?: string;
+    sessionId?: string;
+    /** Extra span attributes (kept under the gen_ai./autter.llm. families). */
+    attributes?: Attributes;
+}
+/** Reporting surface handed to the `withLlmCall` callback. */
+interface LlmCallHandle {
+    /** Report token usage / exact cost from the provider response. */
+    setUsage(usage: LlmUsage): void;
+    /** Exact cost in USD; without it the ingester estimates from its price table. */
+    setCost(usd: number): void;
+    /** Record the model the provider actually served (gen_ai.response.model). */
+    setResponseModel(model: string): void;
+    /** Alias of setResponseModel. */
+    setModel(model: string): void;
+    /** Extra span attributes reported mid-call. */
+    setAttributes(attributes: Attributes): void;
+}
+/** A completed LLM call reported after the fact via `trackLlmCall`. */
+interface TrackedLlmCall extends LlmCallInfo, LlmUsage {
+    /** Wall-clock duration of the call, if measured. */
+    durationMs?: number;
+    /** Pass the thrown error to record the call as failed. */
+    error?: unknown;
+}
 interface AutterServer {
     /** Report a handled exception. Always recorded (never sampled out). */
     captureException(error: unknown, attributes?: Attributes): void;
@@ -83,6 +205,41 @@ interface AutterServer {
      * errors with a lower severity so aggregations can slice one dataset.
      */
     captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /**
+     * Wrap a named unit of work — a background job, queue consumer, cron
+     * tick, or DB-heavy call — in an always-recorded span. Unlike regular
+     * traces these are never head-sampled, so Autter's slow-process monitor
+     * sees accurate run counts and durations for non-HTTP work. Nested
+     * instrumented calls run inside the span's context, so slow traces show
+     * where the time went. Rethrows whatever `fn` throws.
+     */
+    withProcessSpan<T>(name: string, fn: () => T | Promise<T>, attributes?: Attributes): Promise<T>;
+    /**
+     * Wrap one LLM provider call. Always recorded (never head-sampled), so
+     * Autter's LLM usage/cost dashboards and anomaly monitor see every call.
+     * Report tokens via the handle once the response arrives; cost is
+     * estimated from the model id unless `setCost(usd)` (or
+     * `setUsage({ costUsd })`) reports the exact figure. Rethrows whatever
+     * `fn` throws (failed calls are recorded with the error attached).
+     *
+     *   const reply = await autter.withLlmCall(
+     *     { provider: "openai", model: "gpt-5-mini", userId: user.id },
+     *     async (llm) => {
+     *       const res = await openai.chat.completions.create({ ... });
+     *       llm.setUsage({
+     *         inputTokens: res.usage?.prompt_tokens,
+     *         outputTokens: res.usage?.completion_tokens,
+     *       });
+     *       return res;
+     *     },
+     *   );
+     */
+    withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T | Promise<T>): Promise<T>;
+    /**
+     * Report an already-completed LLM call — for codepaths where wrapping is
+     * awkward (queues, callbacks, batch results). Fire-and-forget.
+     */
+    trackLlmCall(call: TrackedLlmCall): void;
     /** Flush and stop all exporters. Call on graceful shutdown. */
     shutdown(): Promise<void>;
 }
@@ -90,7 +247,131 @@ declare function initAutterServer(options: AutterServerOptions): AutterServer;
 /** Module-level convenience — routes to the active server, or degrades to a
  * span on the global tracer so libraries can call it unconditionally. */
 declare function captureException(error: unknown, attributes?: Attributes): void;
+/**
+ * Module-level convenience — see AutterServer.withProcessSpan. Before
+ * initAutterServer runs it degrades to the global tracer, where the span is
+ * subject to that provider's own sampling instead of the always-on pipe.
+ */
+declare function withProcessSpan<T>(name: string, fn: () => T | Promise<T>, attributes?: Attributes): Promise<T>;
+/**
+ * Module-level convenience — see AutterServer.withLlmCall. Before
+ * initAutterServer runs it degrades to the global tracer, where the span is
+ * subject to that provider's own sampling instead of the always-on pipe.
+ */
+declare function withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T | Promise<T>): Promise<T>;
+/** Module-level convenience — see AutterServer.trackLlmCall. */
+declare function trackLlmCall(call: TrackedLlmCall): void;
 /** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
 declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+/** Capture surface with guaranteed redaction, regardless of how the host app
+ * configured initAutterServer — for library authors whose calls must never
+ * forward PII even when the host disabled it. Routes to the active server
+ * (or degrades to the global tracer exactly like captureException). */
+interface SafeCapture {
+    captureException(error: unknown, attributes?: Attributes): void;
+    captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+}
+/**
+ * Build a redacting capture wrapper:
+ *
+ *   const safe = makeSafeCapture();
+ *   safe.captureException(err, { "user.email": email }); // masked before export
+ *
+ * The returned functions have the same signatures as their plain twins;
+ * every attribute passes through redactAttributes() first. Note that when
+ * the host has NOT disabled redaction this is belt-and-braces (already on by
+ * default) — its value is enforcing privacy inside libraries and wrappers.
+ */
+declare function makeSafeCapture(options?: RedactOptions): SafeCapture;
+/**
+ * Emit one clearly-named fake LLM call (provider/model "autter-selftest",
+ * 1 input + 1 output token, cost 0) and force-flush it, returning the
+ * traceId — proves LLM traces reach the ingester without calling any real
+ * model. For setup verification only; requires initAutterServer.
+ */
+declare function emitLlmSelftestTrace(): Promise<{
+    traceId: string;
+}>;
+
+interface AutterLogger {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface FlushTarget {
+    forceFlush(): Promise<unknown> | unknown;
+}
+interface AutoFlushOptions {
+    /**
+     * Targets to flush. Defaults to whatever initAutterServer has registered;
+     * pass your own for custom pipelines.
+     */
+    targets?: FlushTarget[];
+    /** Where lifecycle messages go. Default console. */
+    logger?: AutterLogger;
+    /** Log each successful flush ("flushed telemetry (SIGTERM)"). Default true. */
+    log?: boolean;
+    /**
+     * Warn on stderr when the process exits with captures that were never
+     * confirmed exported. Default true.
+     */
+    warnOnUnflushedExit?: boolean;
+    /**
+     * Max wall-clock time a single flush may take before giving up (and, on
+     * signals, proceeding to exit anyway). Default 3000 ms.
+     */
+    timeoutMs?: number;
+    /** Signals handled besides the defaults. Default ["SIGINT", "SIGTERM"]. */
+    signals?: string[];
+}
+interface AutoFlushHandle {
+    /** Force-flush now. Safe to call repeatedly; concurrent calls coalesce. */
+    flush(reason?: string): Promise<boolean>;
+    /** Remove every listener this install added. */
+    dispose(): void;
+}
+/**
+ * Flush all exporters when the process is going away:
+ *
+ *   - `beforeExit` — event-loop drained naturally: force-flush, then hand the
+ *     loop back (a kept-alive timer makes sure the async flush finishes
+ *     inside the beforeExit window).
+ *   - SIGINT / SIGTERM — flush, then exit with the conventional code (130 /
+ *     143). If YOUR code also listens to the signal, we only flush
+ *     concurrently and let your handler decide the exit — installing this
+ *     never changes an existing graceful-shutdown path. A second signal
+ *     always exits immediately.
+ *
+ * Idempotent per options object; `initAutterServer` installs it by default
+ * (`autoFlush: false` opts out).
+ */
+declare function installAutterAutoFlush(options?: AutoFlushOptions): AutoFlushHandle;
+
+/**
+ * One-line LLM client auto-instrumentation:
+ *
+ *   const openai = instrumentLlmClient(new OpenAI());
+ *
+ * Wraps a provider SDK instance (OpenAI, Anthropic, Google GenAI, or any
+ * client with the same call shapes) in a deep proxy. Every model invocation —
+ * a method like `create`/`stream`/`generateContent` called with an object
+ * argument carrying a `model` — is recorded as a gen_ai span on the
+ * always-recorded pipe: model, tokens, latency, errors, and (ingester-side)
+ * USD cost. Streaming responses are supported: the span stays open until the
+ * stream is consumed, picking up usage from the final chunks.
+ *
+ * Nothing about the client's behaviour changes; methods run with the
+ * original `this` (SDK private fields keep working) and results pass
+ * through untouched apart from the stream wrapper.
+ */
+interface InstrumentLlmOptions {
+    /** Provider id ("openai", "anthropic", …). Default: detected from the client. */
+    provider?: string;
+    /** Opaque end-user id (never an email) — static or resolved per call. */
+    userId?: string | (() => string | undefined);
+    /** Extra attributes for every span from this client. */
+    attributes?: Attributes;
+}
+declare function instrumentLlmClient<T extends object>(client: T, options?: InstrumentLlmOptions): T;
 
-export { type AutterServer, type AutterServerOptions, type AutterSeverity, type RelayOptions, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, initAutterServer, sanitizeBrowserPayload };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, sanitizeBrowserPayload, trackLlmCall, withLlmCall, withProcessSpan };