@grafana/sigil-sdk-js 0.0.1 → 0.2.1

package/README.md

@@ -54,6 +54,42 @@ await client.startGeneration(
 await client.shutdown();
 ```
 
+## Pre-Ingest Redaction
+
+Use `generationSanitizer` when you want to redact substrings from normalized generations before
+validation, span sync, debug snapshots, and export.
+
+```ts
+import {
+  SigilClient,
+  createSecretRedactionSanitizer,
+} from "@grafana/sigil-sdk-js";
+
+const client = new SigilClient({
+  generationSanitizer: createSecretRedactionSanitizer({
+    redactInputMessages: false,
+    redactEmailAddresses: true,
+  }),
+});
+```
+
+The built-in sanitizer:
+
+- redacts high-confidence secret formats in assistant text and thinking
+- redacts secret formats plus env-style secret values in tool call inputs and tool results
+- redacts email addresses by default
+- leaves user input unchanged unless `redactInputMessages: true` is set
+
+To preserve email addresses, opt out explicitly:
+
+```ts
+const client = new SigilClient({
+  generationSanitizer: createSecretRedactionSanitizer({
+    redactEmailAddresses: false,
+  }),
+});
+```
+
 Configure OTEL exporters (traces/metrics) in your application OTEL SDK setup. You can optionally pass `tracer` and `meter` directly to `SigilClient`.
 
 Quick OTEL setup pattern before creating the Sigil client:
@@ -167,12 +203,14 @@ Use module subpath exports for framework callback integrations:
 - LlamaIndex: `@grafana/sigil-sdk-js/llamaindex`
 - Google ADK: `@grafana/sigil-sdk-js/google-adk`
 - Vercel AI SDK: `@grafana/sigil-sdk-js/vercel-ai-sdk`
+- Strands Agents: `@grafana/sigil-sdk-js/strands`
 - LangChain guide: `docs/frameworks/langchain.md`
 - LangGraph guide: `docs/frameworks/langgraph.md`
 - OpenAI Agents guide: `docs/frameworks/openai-agents.md`
 - LlamaIndex guide: `docs/frameworks/llamaindex.md`
 - Google ADK guide: `docs/frameworks/google-adk.md`
 - Vercel AI SDK guide: `docs/frameworks/vercel-ai-sdk.md`
+- Strands Agents guide: `docs/frameworks/strands.md`
 
 ```ts
 import { SigilClient } from "@grafana/sigil-sdk-js";
@@ -182,6 +220,7 @@ import { withSigilOpenAIAgentsHooks } from "@grafana/sigil-sdk-js/openai-agents"
 import { withSigilLlamaIndexCallbacks } from "@grafana/sigil-sdk-js/llamaindex";
 import { withSigilGoogleAdkPlugins } from "@grafana/sigil-sdk-js/google-adk";
 import { createSigilVercelAiSdk } from "@grafana/sigil-sdk-js/vercel-ai-sdk";
+import { withSigilStrandsHooks } from "@grafana/sigil-sdk-js/strands";
 import { Runner } from "@openai/agents";
 import { CallbackManager } from "llamaindex";
 
@@ -194,13 +233,19 @@ const callbackManager = new CallbackManager();
 const llamaIndexConfig = withSigilLlamaIndexCallbacks({ callbackManager }, client, { providerResolver: "auto" });
 const googleAdkRunnerConfig = withSigilGoogleAdkPlugins(undefined, client, { providerResolver: "auto" });
 const vercelAiSdk = createSigilVercelAiSdk(client, { agentName: "vercel-agent" });
+const strandsConfig = withSigilStrandsHooks(undefined, client, { conversationId: "chat-123" });
 ```
 
+Framework handlers use the `SigilClient` instance you pass in. If that client is configured with
+`generationSanitizer`, the same redaction policy applies automatically to generations recorded
+through LangChain, LangGraph, OpenAI Agents, LlamaIndex, Google ADK, and Vercel AI SDK integrations.
+The same redaction policy also applies to Strands Agents generations.
+
 Each framework handler injects:
 
-- `sigil.framework.name` (`langchain`, `langgraph`, `openai-agents`, `llamaindex`, `google-adk`, or `vercel-ai-sdk`)
-- `sigil.framework.source` (`handler` for existing callback handlers, `framework` for Vercel AI SDK hooks)
-- `sigil.framework.language` (`javascript` for existing callback handlers, `typescript` for Vercel AI SDK hooks)
+- `sigil.framework.name` (`langchain`, `langgraph`, `openai-agents`, `llamaindex`, `google-adk`, `vercel-ai-sdk`, or `strands`)
+- `sigil.framework.source` (`handler` for existing callback handlers, `framework` for Vercel AI SDK hooks, `hooks` for Strands)
+- `sigil.framework.language` (`javascript` for existing callback handlers, `typescript` for Vercel AI SDK and Strands hooks)
 - `metadata["sigil.framework.run_id"]`
 - `metadata["sigil.framework.thread_id"]` (when present)
 - `metadata["sigil.framework.parent_run_id"]` (when available)

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type Span } from '@opentelemetry/api';
-import type { ContentCaptureMode, ConversationRatingInput, EmbeddingRecorder, EmbeddingResult, EmbeddingStart, Generation, GenerationMode, GenerationRecorder, GenerationStart, RecorderCallback, SigilDebugSnapshot, SigilSdkConfigInput, SubmitConversationRatingResponse, ToolExecution, ToolExecutionRecorder, ToolExecutionStart } from './types.js';
+import type { ContentCaptureMode, ConversationRatingInput, EmbeddingRecorder, EmbeddingResult, EmbeddingStart, Generation, GenerationMode, GenerationRecorder, GenerationStart, HookEvaluateRequest, HookEvaluateResponse, HooksConfig, RecorderCallback, SigilDebugSnapshot, SigilSdkConfigInput, SubmitConversationRatingResponse, ToolExecution, ToolExecutionRecorder, ToolExecutionStart } from './types.js';
 export declare class SigilClient {
     private readonly config;
     private readonly nowFn;
@@ -63,6 +63,28 @@ export declare class SigilClient {
     startToolExecution<TResult>(start: ToolExecutionStart, callback: RecorderCallback<ToolExecutionRecorder, TResult>): Promise<TResult>;
     /** Submits a user-facing conversation rating through Sigil HTTP API. */
     submitConversationRating(conversationId: string, input: ConversationRatingInput): Promise<SubmitConversationRatingResponse>;
+    /**
+     * Returns the resolved hook configuration. Framework adapters use this to
+     * decide whether to invoke `evaluateHook` and which phases are configured.
+     */
+    get hooksConfig(): HooksConfig;
+    /**
+     * Evaluates synchronous hook rules for the given request.
+     *
+     * Use this to enforce preflight or postflight guardrails (PII, content
+     * policy, etc.) on the LLM call's critical path. The server returns
+     * `{ action: 'deny' }` to block; framework adapters typically translate that
+     * into a `HookDeniedError`.
+     *
+     * When `hooks.enabled` is false, this short-circuits to `allow`. When
+     * `hooks.failOpen` is true (default), network/timeout failures also resolve
+     * to `allow` so the LLM call can proceed.
+     *
+     * Framework adapters can pass `hooksConfigOverride` to override specific
+     * fields of the client's hooks config (e.g., force `enabled: true` when the
+     * adapter has its own `enableHooks` option).
+     */
+    evaluateHook(request: HookEvaluateRequest, hooksConfigOverride?: Partial<HooksConfig>): Promise<HookEvaluateResponse>;
     /** Forces immediate drain of queued generation exports. */
     flush(): Promise<void>;
     /** Flushes pending generations and shuts down the generation exporter. */
@@ -70,12 +92,18 @@ export declare class SigilClient {
     /** Returns a cloned in-memory snapshot for debugging and tests. */
     debugSnapshot(): SigilDebugSnapshot;
     internalNow(): Date;
+    internalAgentName(): string | undefined;
+    internalAgentVersion(): string | undefined;
+    internalUserId(): string | undefined;
+    internalTags(): Record<string, string> | undefined;
     internalRecordGeneration(generation: Generation): void;
     internalRecordToolExecution(toolExecution: ToolExecution): void;
     internalEnqueueGeneration(generation: Generation): void;
     internalLogWarn(message: string, error?: unknown): void;
     internalResolveGenerationContentCaptureMode(seed: GenerationStart): ContentCaptureMode;
     internalResolveToolIncludeContent(seed: ToolExecutionStart): boolean;
+    internalHasGenerationSanitizer(): boolean;
+    internalSanitizeGeneration(generation: Generation): Generation;
     internalStartGenerationSpan(seed: GenerationStart, mode: GenerationMode, startedAt: Date): Span;
     internalStartEmbeddingSpan(seed: EmbeddingStart, startedAt: Date): Span;
     internalStartToolExecutionSpan(seed: ToolExecutionStart, startedAt: Date): Span;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,IAAI,EAKV,MAAM,oBAAoB,CAAC;AAmB5B,OAAO,KAAK,EACV,kBAAkB,EAElB,uBAAuB,EAGvB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,UAAU,EAEV,cAAc,EACd,kBAAkB,EAElB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EAEX,gBAAgB,EAEhB,kBAAkB,EAGlB,mBAAmB,EACnB,gCAAgC,EAChC,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAuGpB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IAEvD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,WAAW,GAAE,mBAAwB;IA+BjD;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB;IAC3D,eAAe,CAAC,OAAO,EACrB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,gBAAgB,CAAC,kBAAkB,EAAE,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;;OAMG;IACH,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB;IACpE,wBAAwB,CAAC,OAAO,EAC9B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,gBAAgB,CAAC,kBAAkB,EAAE,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB;IACxD,cAAc,CAAC,OAAO,EACpB,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,gBAAgB,CAAC,iBAAiB,EAAE,OAAO,CAAC,GACrD,OAAO,CAAC,OAAO,CAAC;IAgCnB;;;;OAIG;IACH,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB;IACpE,kBAAkB,CAAC,OAAO,EACxB,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,gBAAgB,CAAC,qBAAqB,EAAE,OAAO,CAAC,GACzD,OAAO,CAAC,OAAO,CAAC;IAcnB,wEAAwE;IAClE,wBAAwB,CAC5B,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,gCAAgC,CAAC;IA+D5C;;;OAGG;IACH,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED;;;;;;;;;;;;;;;OAeG;IACG,YAAY,CAChB,OAAO,EAAE,mBAAmB,EAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GACzC,OAAO,CAAC,oBAAoB,CAAC;IAahC,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,0EAA0E;IACpE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B/B,mEAAmE;IACnE,aAAa,IAAI,kBAAkB;IAQnC,WAAW,IAAI,IAAI;IAInB,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAIvC,oBAAoB,IAAI,MAAM,GAAG,SAAS;IAI1C,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAIlD,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAItD,2BAA2B,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IAI/D,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IA0BvD,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAIvD,2CAA2C,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB;IAQtF,iCAAiC,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO;IAUpE,8BAA8B,IAAI,OAAO;IAIzC,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU;IAY9D,2BAA2B,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;IA2B/F,0BAA0B,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;IASvE,8BAA8B,CAAC,IAAI,EAAE,kBAAkB,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;IAU/E,iCAAiC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAU3E,0BAA0B,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI;IAIpE,kCAAkC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAIpD,8BAA8B,CAC5B,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,KAAK,GAAG,SAAS,EAClC,YAAY,EAAE,KAAK,GAAG,SAAS,EAC/B,YAAY,EAAE,IAAI,GAAG,SAAS,EAC9B,4BAA4B,CAAC,EAAE,MAAM,GACpC,IAAI;IA0CP,6BAA6B,CAC3B,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,KAAK,GAAG,SAAS,EAC5B,UAAU,EAAE,KAAK,GAAG,SAAS,EAC7B,SAAS,EAAE,IAAI,EACf,WAAW,EAAE,IAAI,GAChB,IAAI;IAmCP,iCAAiC,CAC/B,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,KAAK,GAAG,SAAS,GAC5B,KAAK,GAAG,SAAS;IA0CpB,OAAO,CAAC,uBAAuB;IA8C/B,OAAO,CAAC,sBAAsB;IA6B9B,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,0BAA0B;IAiBlC,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,uBAAuB;IAa/B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,aAAa;YAaP,uBAAuB;YAYvB,eAAe;IAgC7B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,OAAO;CAOhB"}

package/dist/client.js

@@ -3,6 +3,7 @@ import { defaultLogger, mergeConfig } from './config.js';
 import { callContentCaptureResolver, resolveClientContentCaptureMode, resolveContentCaptureMode, shouldIncludeToolContent, stampContentCaptureMetadata, stripContent, } from './content_capture.js';
 import { agentNameFromContext, agentVersionFromContext, conversationIdFromContext, conversationTitleFromContext, userIdFromContext, } from './context.js';
 import { createDefaultGenerationExporter } from './exporters/default.js';
+import { evaluateHook as evaluateHookImpl } from './hooks.js';
 import { asError, cloneArtifact, cloneEmbeddingResult, cloneEmbeddingStart, cloneGeneration, cloneGenerationResult, cloneGenerationStart, cloneMessage, cloneModelRef, cloneToolDefinition, cloneToolExecution, cloneToolExecutionResult, cloneToolExecutionStart, defaultOperationNameForMode, defaultSleep, encodedSizeBytes, maybeUnref, newLocalID, validateEmbeddingResult, validateEmbeddingStart, validateGeneration, validateToolExecution, } from './utils.js';
 const spanAttrGenerationID = 'sigil.generation.id';
 const spanAttrSDKName = 'sigil.sdk.name';
@@ -67,6 +68,12 @@ const metricTokenTypeCacheRead = 'cache_read';
 const metricTokenTypeCacheWrite = 'cache_write';
 const metricTokenTypeCacheCreation = 'cache_creation';
 const metricTokenTypeReasoning = 'reasoning';
+const durationBucketsSeconds = [
+    0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92,
+];
+const tokenUsageBuckets = [
+    1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864,
+];
 const instrumentationName = 'github.com/grafana/sigil/sdks/js';
 const sdkName = 'sdk-js';
 const defaultEmbeddingOperationName = 'embeddings';
@@ -107,9 +114,18 @@ export class SigilClient {
             this.config.generationExporter ?? createDefaultGenerationExporter(this.config.generationExport);
         this.tracer = this.config.tracer ?? trace.getTracer(instrumentationName);
         this.meter = this.config.meter ?? metrics.getMeter(instrumentationName);
-        this.operationDurationHistogram = this.meter.createHistogram(metricOperationDuration, { unit: 's' });
-        this.tokenUsageHistogram = this.meter.createHistogram(metricTokenUsage, { unit: 'token' });
-        this.ttftHistogram = this.meter.createHistogram(metricTimeToFirstToken, { unit: 's' });
+        this.operationDurationHistogram = this.meter.createHistogram(metricOperationDuration, {
+            unit: 's',
+            advice: { explicitBucketBoundaries: durationBucketsSeconds },
+        });
+        this.tokenUsageHistogram = this.meter.createHistogram(metricTokenUsage, {
+            unit: 'token',
+            advice: { explicitBucketBoundaries: tokenUsageBuckets },
+        });
+        this.ttftHistogram = this.meter.createHistogram(metricTimeToFirstToken, {
+            unit: 's',
+            advice: { explicitBucketBoundaries: durationBucketsSeconds },
+        });
         this.toolCallsHistogram = this.meter.createHistogram(metricToolCallsPerOperation, { unit: 'count' });
         if (this.config.generationExport.flushIntervalMs > 0) {
             this.flushTimer = setInterval(() => {
@@ -130,9 +146,21 @@ export class SigilClient {
         if (!notEmpty(seed.agentName)) {
             seed.agentName = agentNameFromContext();
         }
+        if (!notEmpty(seed.agentName)) {
+            const fromConfig = this.internalAgentName();
+            if (fromConfig !== undefined && fromConfig.length > 0) {
+                seed.agentName = fromConfig;
+            }
+        }
         if (!notEmpty(seed.agentVersion)) {
             seed.agentVersion = agentVersionFromContext();
         }
+        if (!notEmpty(seed.agentVersion)) {
+            const fromConfig = this.internalAgentVersion();
+            if (fromConfig !== undefined && fromConfig.length > 0) {
+                seed.agentVersion = fromConfig;
+            }
+        }
         const recorder = new EmbeddingRecorderImpl(this, seed);
         if (callback === undefined) {
             return recorder;
@@ -198,6 +226,40 @@ export class SigilClient {
         }
         return parseSubmitConversationRatingResponse(payload);
     }
+    /**
+     * Returns the resolved hook configuration. Framework adapters use this to
+     * decide whether to invoke `evaluateHook` and which phases are configured.
+     */
+    get hooksConfig() {
+        return this.config.hooks;
+    }
+    /**
+     * Evaluates synchronous hook rules for the given request.
+     *
+     * Use this to enforce preflight or postflight guardrails (PII, content
+     * policy, etc.) on the LLM call's critical path. The server returns
+     * `{ action: 'deny' }` to block; framework adapters typically translate that
+     * into a `HookDeniedError`.
+     *
+     * When `hooks.enabled` is false, this short-circuits to `allow`. When
+     * `hooks.failOpen` is true (default), network/timeout failures also resolve
+     * to `allow` so the LLM call can proceed.
+     *
+     * Framework adapters can pass `hooksConfigOverride` to override specific
+     * fields of the client's hooks config (e.g., force `enabled: true` when the
+     * adapter has its own `enableHooks` option).
+     */
+    async evaluateHook(request, hooksConfigOverride) {
+        this.assertOpen();
+        const effectiveHooks = hooksConfigOverride !== undefined ? { ...this.config.hooks, ...hooksConfigOverride } : this.config.hooks;
+        return evaluateHookImpl({
+            apiEndpoint: this.config.api.endpoint,
+            insecure: this.config.generationExport.insecure,
+            extraHeaders: this.config.generationExport.headers,
+            hooks: effectiveHooks,
+            request,
+        });
+    }
     /** Forces immediate drain of queued generation exports. */
     async flush() {
         this.assertOpen();
@@ -239,6 +301,18 @@ export class SigilClient {
     internalNow() {
         return this.nowFn();
     }
+    internalAgentName() {
+        return this.config.agentName;
+    }
+    internalAgentVersion() {
+        return this.config.agentVersion;
+    }
+    internalUserId() {
+        return this.config.userId;
+    }
+    internalTags() {
+        return this.config.tags;
+    }
     internalRecordGeneration(generation) {
         this.generations.push(cloneGeneration(generation));
     }
@@ -278,6 +352,20 @@ export class SigilClient {
         const resolverMode = callContentCaptureResolver(this.config.contentCaptureResolver, undefined);
         return shouldIncludeToolContent(seed.contentCapture ?? 'default', this.config.contentCapture, resolverMode, seed.includeContent ?? false);
     }
+    internalHasGenerationSanitizer() {
+        return this.config.generationSanitizer !== undefined;
+    }
+    internalSanitizeGeneration(generation) {
+        const sanitizer = this.config.generationSanitizer;
+        if (sanitizer === undefined) {
+            return generation;
+        }
+        const sanitized = sanitizer(cloneGeneration(generation));
+        if (sanitized === undefined) {
+            throw new Error('generation sanitizer must return a generation');
+        }
+        return cloneGeneration(sanitized);
+    }
     internalStartGenerationSpan(seed, mode, startedAt) {
         const operationName = seed.operationName ?? defaultOperationNameForMode(mode);
         const span = this.tracer.startSpan(generationSpanName(operationName, seed.model.name), {
@@ -635,12 +723,34 @@ class GenerationRecorderImpl {
         if (!notEmpty(this.seed.userId)) {
             this.seed.userId = userIdFromContext();
         }
+        if (!notEmpty(this.seed.userId)) {
+            const fromConfig = this.client.internalUserId();
+            if (fromConfig !== undefined && fromConfig.length > 0) {
+                this.seed.userId = fromConfig;
+            }
+        }
         if (!notEmpty(this.seed.agentName)) {
             this.seed.agentName = agentNameFromContext();
         }
+        if (!notEmpty(this.seed.agentName)) {
+            const fromConfig = this.client.internalAgentName();
+            if (fromConfig !== undefined && fromConfig.length > 0) {
+                this.seed.agentName = fromConfig;
+            }
+        }
         if (!notEmpty(this.seed.agentVersion)) {
             this.seed.agentVersion = agentVersionFromContext();
         }
+        if (!notEmpty(this.seed.agentVersion)) {
+            const fromConfig = this.client.internalAgentVersion();
+            if (fromConfig !== undefined && fromConfig.length > 0) {
+                this.seed.agentVersion = fromConfig;
+            }
+        }
+        const tags = this.client.internalTags();
+        if (tags !== undefined && Object.keys(tags).length > 0) {
+            this.seed.tags = { ...tags, ...(this.seed.tags ?? {}) };
+        }
         if (!notEmpty(this.seed.operationName)) {
             this.seed.operationName = defaultOperationNameForMode(this.seed.mode ?? defaultMode);
         }
@@ -675,7 +785,7 @@ class GenerationRecorderImpl {
             return;
         }
         this.ended = true;
-        const generation = {
+        let generation = {
             id: this.seed.id ?? newLocalID('gen'),
             conversationId: firstNonEmptyString(this.result?.conversationId, this.seed.conversationId),
             conversationTitle: firstNonEmptyString(this.result?.conversationTitle, this.seed.conversationTitle),
@@ -734,14 +844,28 @@ class GenerationRecorderImpl {
             generation.metadata = {};
         }
         generation.metadata[spanAttrSDKName] = sdkName;
-        const validationError = validateGeneration(generation);
         const callErrorCategory = errorCategoryFromError(this.callError, false);
+        let effectiveContentCaptureMode = this.contentCaptureMode;
+        let validationTarget = cloneGeneration(generation);
         stampContentCaptureMetadata(generation, this.contentCaptureMode);
         if (this.contentCaptureMode === 'metadata_only') {
             stripContent(generation, callErrorCategory);
         }
+        else if (this.client.internalHasGenerationSanitizer()) {
+            try {
+                generation = this.client.internalSanitizeGeneration(generation);
+                validationTarget = cloneGeneration(generation);
+            }
+            catch (error) {
+                effectiveContentCaptureMode = 'metadata_only';
+                stripContent(generation, callErrorCategory);
+                stampContentCaptureMetadata(generation, effectiveContentCaptureMode);
+                this.client.internalLogWarn('sigil generation sanitization failed; falling back to metadata_only', error);
+            }
+        }
+        const validationError = validateGeneration(validationTarget);
         this.client.internalSyncGenerationSpan(this.span, generation);
-        if (this.contentCaptureMode === 'metadata_only') {
+        if (effectiveContentCaptureMode === 'metadata_only') {
             this.client.internalClearSpanConversationTitle(this.span);
         }
         this.client.internalApplyTraceContextFromSpan(this.span, generation);
@@ -761,7 +885,7 @@ class GenerationRecorderImpl {
                 this.client.internalLogWarn('sigil generation enqueue failed', enqueueError);
             }
         }
-        const finalCallError = this.contentCaptureMode === 'metadata_only' ? generation.callError : this.callError;
+        const finalCallError = effectiveContentCaptureMode === 'metadata_only' ? generation.callError : this.callError;
         this.client.internalFinalizeGenerationSpan(this.span, generation, finalCallError, validationError, enqueueError, this.firstTokenAt, callErrorCategory.length > 0 ? callErrorCategory : undefined);
     }
     getError() {
@@ -837,9 +961,21 @@ class ToolExecutionRecorderImpl {
         if (!notEmpty(this.seed.agentName)) {
             this.seed.agentName = agentNameFromContext();
         }
+        if (!notEmpty(this.seed.agentName)) {
+            const fromConfig = this.client.internalAgentName();
+            if (notEmpty(fromConfig)) {
+                this.seed.agentName = fromConfig;
+            }
+        }
         if (!notEmpty(this.seed.agentVersion)) {
             this.seed.agentVersion = agentVersionFromContext();
         }
+        if (!notEmpty(this.seed.agentVersion)) {
+            const fromConfig = this.client.internalAgentVersion();
+            if (notEmpty(fromConfig)) {
+                this.seed.agentVersion = fromConfig;
+            }
+        }
         this.resolvedIncludeContent = this.client.internalResolveToolIncludeContent(this.seed);
         this.startedAt = this.seed.startedAt ?? this.client.internalNow();
         this.span = this.client.internalStartToolExecutionSpan(this.seed, this.startedAt);