@elsium-ai/observe 0.7.0 → 0.9.0

package/README.md

@@ -19,8 +19,10 @@ npm install @elsium-ai/observe @elsium-ai/core
 | **Cost Engine** | `createCostEngine`, `registerModelTier`, `CostEngine`, `CostEngineConfig`, `BudgetConfig`, `LoopDetectionConfig`, `CostAlert`, `CostDimension`, `CostIntelligenceReport`, `ModelSuggestion`, `ModelTierEntry` | Budget enforcement, cost projections, loop detection, and model optimization suggestions |
 | **Tracer** | `observe`, `Tracer`, `TracerConfig`, `TracerOutput`, `TracerExporter`, `CostReport` | High-level tracing with sampling, console output, and custom exporters |
 | **Metrics** | `createMetrics`, `MetricsCollector`, `MetricEntry` | Counters, gauges, and histograms for application-level metrics |
-| **Audit Trail** | `createAuditTrail`, `auditMiddleware`, `AuditEventType`, `AuditEvent`, `AuditStorageAdapter`, `AuditQueryFilter`, `AuditIntegrityResult`, `AuditTrailConfig`, `AuditTrail` | SHA-256 hash-chained audit events with tamper detection and middleware |
+| **Audit Trail** | `createAuditTrail`, `auditMiddleware`, `auditStreamMiddleware`, `AuditEventType`, `AuditEvent`, `AuditStorageAdapter`, `AuditQueryFilter`, `AuditIntegrityResult`, `AuditTrailConfig`, `AuditTrail` | SHA-256 hash-chained audit events with tamper detection, middleware for both completion and streaming calls |
+| **Audit Sinks** | `createSinkManager`, `createWebhookSink`, `createSplunkSink`, `createDatadogSink`, `AuditSink`, `AuditSinkRetryConfig`, `SinkManagerConfig`, `SinkManager`, `WebhookSinkConfig`, `SplunkSinkConfig`, `DatadogSinkConfig` | Export audit events to external systems (webhooks, Splunk, Datadog) with batching, retry, per-sink filtering, and dead letter queue |
 | **Provenance** | `createProvenanceTracker`, `ProvenanceRecord`, `ProvenanceTracker` | Full lineage tracking per output: prompt, model, config, input, output |
+| **Studio Exporter** | `createStudioExporter`, `StudioExporter`, `StudioExporterConfig` | Write traces, X-Ray, and costs to `.elsium/` for the `elsium studio` dashboard |
 | **OpenTelemetry** | `toOTelSpan`, `toOTelExportRequest`, `toTraceparent`, `parseTraceparent`, `injectTraceContext`, `extractTraceContext`, `createOTLPExporter`, `OTelSpan`, `OTelSpanKind`, `OTelStatusCode`, `OTelAttribute`, `OTelAttributeValue`, `OTelEvent`, `OTelResource`, `OTelExportRequest`, `TraceContext`, `OTLPExporterConfig` | W3C Trace Context propagation, OTel span conversion, and OTLP JSON export |
 
 ---
@@ -646,6 +648,8 @@ interface AuditTrailConfig {
   hashChain?: boolean
   maxEvents?: number
   batch?: AuditBatchConfig
+  sinks?: AuditSink[] | SinkManagerConfig
+  context?: Record<string, unknown>
   onError?: (error: unknown) => void
 }
 ```
@@ -663,7 +667,7 @@ interface AuditTrail {
   query(filter: AuditQueryFilter): Promise<AuditEvent[]>
   verifyIntegrity(): Promise<AuditIntegrityResult>
   flush(): Promise<void>
-  dispose(): void
+  dispose(): Promise<void>
   readonly count: number
   readonly pending: number
 }
@@ -676,7 +680,7 @@ interface AuditTrail {
 | `query()` | Query events by type, actor, traceId, or timestamp range. Auto-flushes pending events in batched mode. |
 | `verifyIntegrity()` | Verify the hash chain has not been tampered with. Auto-flushes pending events in batched mode. |
 | `flush()` | Drain all pending events — computes hashes and writes to storage. No-op when not in batched mode. |
-| `dispose()` | Stop the flush timer and drain remaining events. Call this on shutdown. |
+| `dispose()` | Stop the flush timer, drain remaining events, await pending storage writes, and shut down sinks. Returns a promise — await it on shutdown. |
 | `count` | Total events (stored + pending). |
 | `pending` | Number of buffered events not yet flushed (0 when not in batched mode). |
 
@@ -694,6 +698,8 @@ function createAuditTrail(config?: AuditTrailConfig): AuditTrail
 | `config.hashChain` | `boolean` | `true` | Enable SHA-256 hash chaining for tamper detection |
 | `config.maxEvents` | `number` | `10000` | Maximum events retained (ring buffer — O(1) eviction) |
 | `config.batch` | `AuditBatchConfig` | `undefined` | Enable batched mode for high-volume scenarios |
+| `config.sinks` | `AuditSink[] \| SinkManagerConfig` | `undefined` | Export events to external systems (webhooks, SIEM, etc.) |
+| `config.context` | `Record<string, unknown>` | `undefined` | Global fields merged into every event's `data` (e.g. environment, service name, version) |
 | `config.onError` | `(error: unknown) => void` | `undefined` | Error handler for async storage failures |
 
 **Returns:** `AuditTrail`
@@ -748,12 +754,32 @@ audit.log('llm_call', { model: 'gpt-4o', tokens: 100 })
 // Force-flush before reading (query/verifyIntegrity auto-flush)
 await audit.flush()
 
-// Clean up on shutdown
-process.on('SIGTERM', () => audit.dispose())
+// Clean up on shutdown (awaits pending writes and sink delivery)
+process.on('SIGTERM', async () => await audit.dispose())
 ```
 
 Hash chain integrity is fully preserved — events are hashed sequentially during flush, not during `log()`.
 
+#### Context enrichment
+
+Add global fields to every event without repeating them at each call site:
+
+```ts
+const audit = createAuditTrail({
+  context: {
+    env: 'production',
+    service: 'my-ai-service',
+    version: '1.2.0',
+    region: 'us-east-1',
+  },
+})
+
+audit.log('llm_call', { model: 'gpt-4o', tokens: 100 })
+// event.data → { env: 'production', service: 'my-ai-service', version: '1.2.0', region: 'us-east-1', model: 'gpt-4o', tokens: 100 }
+```
+
+Event-specific data always takes precedence over global context fields.
+
 ### `auditMiddleware()`
 
 Creates an ElsiumAI middleware that automatically logs every LLM call (success or failure) to the given audit trail.
@@ -780,6 +806,250 @@ const middleware = auditMiddleware(audit)
 
 The middleware automatically records `llm_call` events containing `provider`, `model`, `inputTokens`, `outputTokens`, `totalTokens`, `cost`, `latencyMs`, and `stopReason`. On errors, it records the error message and `success: false`.
 
+### `auditStreamMiddleware()`
+
+Creates a `StreamMiddleware` that audits streaming LLM calls. Intercepts `message_end` events to capture token usage and latency, and `error` events to capture failures — all without buffering or blocking the stream.
+
+```ts
+function auditStreamMiddleware(auditTrail: AuditTrail): StreamMiddleware
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `auditTrail` | `AuditTrail` | The audit trail instance to log events to |
+
+**Returns:** `StreamMiddleware` (from `@elsium-ai/core`)
+
+```ts
+import { createAuditTrail, auditStreamMiddleware } from '@elsium-ai/observe'
+
+const audit = createAuditTrail({ hashChain: true })
+const streamMw = auditStreamMiddleware(audit)
+
+// Use with an ElsiumAI gateway
+// gateway.use({ streamMiddleware: [streamMw] })
+```
+
+The middleware records `llm_call` events with `provider`, `model`, `inputTokens`, `outputTokens`, `totalTokens`, `latencyMs`, `stopReason`, and `streaming: true`. On errors, it records the error message and `success: false`.
+
+---
+
+## Audit Sinks
+
+Export audit events to external observability and governance systems. Sinks receive finalized `AuditEvent` objects after they are hashed and stored — a sink failure never blocks the audit trail or other sinks.
+
+### `AuditSink`
+
+```ts
+interface AuditSink {
+  name: string
+  filter?: (event: AuditEvent) => boolean
+  send(events: AuditEvent[]): Promise<void>
+  shutdown?(): Promise<void>
+}
+```
+
+The optional `filter` function controls which events a sink receives. When set, only events for which the filter returns `true` are sent to that sink. Sinks without a filter receive all events.
+
+### `SinkManagerConfig`
+
+```ts
+interface SinkManagerConfig {
+  sinks: AuditSink[]
+  batch?: {
+    size?: number          // default: 50
+    intervalMs?: number    // default: 5000
+  }
+  retry?: AuditSinkRetryConfig
+  maxBufferSize?: number   // default: 10000
+  deadLetterSink?: AuditSink
+  onError?: (sinkName: string, error: unknown) => void
+}
+```
+
+The `deadLetterSink` receives events that a sink failed to deliver after all retry attempts. This prevents data loss for compliance-critical audit events.
+
+### `AuditSinkRetryConfig`
+
+```ts
+interface AuditSinkRetryConfig {
+  maxRetries?: number      // default: 3
+  baseDelayMs?: number     // default: 1000
+  maxDelayMs?: number      // default: 30000
+}
+```
+
+### Quick start
+
+Pass sinks directly to `createAuditTrail()`:
+
+```ts
+import { createAuditTrail, createWebhookSink, createSplunkSink } from 'elsium-ai/observe'
+
+const audit = createAuditTrail({
+  sinks: [
+    createWebhookSink({ url: 'https://hooks.example.com/audit' }),
+    createSplunkSink({
+      url: 'https://splunk:8088/services/collector',
+      token: 'your-hec-token',
+    }),
+  ],
+})
+
+audit.log('security_violation', { threat: 'prompt_injection', score: 0.95 })
+```
+
+For advanced configuration, pass a `SinkManagerConfig`:
+
+```ts
+const audit = createAuditTrail({
+  sinks: {
+    sinks: [createWebhookSink({ url: 'https://hooks.example.com/audit' })],
+    batch: { size: 100, intervalMs: 10_000 },
+    retry: { maxRetries: 5, baseDelayMs: 2000 },
+    maxBufferSize: 50_000,
+    onError: (sinkName, error) => {
+      console.error(`Sink ${sinkName} failed:`, error)
+    },
+  },
+})
+```
+
+#### Per-sink filtering
+
+Route different event types to different destinations:
+
+```ts
+import { createAuditTrail, createSplunkSink, createDatadogSink } from 'elsium-ai/observe'
+
+const audit = createAuditTrail({
+  sinks: [
+    {
+      ...createSplunkSink({ url: 'https://splunk:8088/services/collector', token: 'tok' }),
+      filter: (event) => event.type === 'security_violation' || event.type === 'auth_event',
+    },
+    createDatadogSink({ apiKey: process.env.DD_API_KEY! }),
+  ],
+})
+```
+
+The Splunk sink only receives security and auth events; the Datadog sink receives everything.
+
+#### Dead letter queue
+
+Prevent data loss when sinks fail after all retry attempts:
+
+```ts
+const audit = createAuditTrail({
+  sinks: {
+    sinks: [createWebhookSink({ url: 'https://hooks.example.com/audit' })],
+    deadLetterSink: createWebhookSink({ url: 'https://dlq.example.com/audit-dlq' }),
+    retry: { maxRetries: 3 },
+  },
+})
+```
+
+Events that cannot be delivered after exhausting retries are sent to the dead letter sink for later replay.
+
+### `createWebhookSink()`
+
+Generic HTTP webhook sink. Sends `{ events: AuditEvent[] }` as JSON.
+
+```ts
+function createWebhookSink(config: WebhookSinkConfig): AuditSink
+```
+
+```ts
+interface WebhookSinkConfig {
+  url: string
+  headers?: Record<string, string>
+  method?: 'POST' | 'PUT'
+  timeoutMs?: number        // default: 10000
+}
+```
+
+```ts
+createWebhookSink({
+  url: 'https://hooks.example.com/audit',
+  headers: { Authorization: 'Bearer token123' },
+})
+```
+
+### `createSplunkSink()`
+
+Sends events to Splunk HTTP Event Collector (HEC) as newline-delimited JSON.
+
+```ts
+function createSplunkSink(config: SplunkSinkConfig): AuditSink
+```
+
+```ts
+interface SplunkSinkConfig {
+  url: string
+  token: string
+  index?: string
+  source?: string            // default: 'elsium-ai'
+  sourcetype?: string        // default: 'elsium:audit'
+  timeoutMs?: number         // default: 10000
+}
+```
+
+```ts
+createSplunkSink({
+  url: 'https://splunk:8088/services/collector',
+  token: 'your-hec-token',
+  index: 'ai_audit',
+})
+```
+
+### `createDatadogSink()`
+
+Sends events to the Datadog Log Intake API (v2).
+
+```ts
+function createDatadogSink(config: DatadogSinkConfig): AuditSink
+```
+
+```ts
+interface DatadogSinkConfig {
+  apiKey: string
+  site?: string              // default: 'datadoghq.com'
+  service?: string           // default: 'elsium-ai'
+  source?: string            // default: 'elsium-ai-audit'
+  tags?: Record<string, string>
+  timeoutMs?: number         // default: 10000
+}
+```
+
+```ts
+createDatadogSink({
+  apiKey: process.env.DD_API_KEY!,
+  site: 'datadoghq.eu',
+  tags: { env: 'production', team: 'platform' },
+})
+```
+
+### Custom sinks
+
+Implement the `AuditSink` interface to send events anywhere:
+
+```ts
+import type { AuditSink, AuditEvent } from 'elsium-ai/observe'
+
+const kafkaSink: AuditSink = {
+  name: 'kafka',
+  async send(events: AuditEvent[]) {
+    await producer.send({
+      topic: 'audit-events',
+      messages: events.map(e => ({ value: JSON.stringify(e) })),
+    })
+  },
+  async shutdown() {
+    await producer.disconnect()
+  },
+}
+```
+
 ---
 
 ## Provenance
@@ -1279,6 +1549,52 @@ const loaded = await store.load(results.id)
 
 ---
 
+## Studio Exporter
+
+Bridges the observe system to the `.elsium/` directory so the `elsium studio` dashboard can display live traces, X-Ray data, and costs.
+
+### `createStudioExporter()`
+
+```ts
+function createStudioExporter(config?: StudioExporterConfig): StudioExporter
+```
+
+```ts
+interface StudioExporterConfig {
+  dir?: string  // default: '.elsium'
+}
+
+interface StudioExporter extends TracerExporter {
+  writeXRayEntry(entry: Record<string, unknown>): void
+  writeCostReport(report: CostReport): void
+}
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `config.dir` | `string` | `'.elsium'` | Directory where trace, X-Ray, and cost files are written |
+
+**Returns:** `StudioExporter` (implements `TracerExporter` + X-Ray/cost writers)
+
+```ts
+import { observe, createStudioExporter } from '@elsium-ai/observe'
+
+const studio = createStudioExporter()
+
+const tracer = observe({ output: [studio] })
+
+const span = tracer.startSpan('my-operation', 'llm')
+span.end()
+await tracer.flush()
+
+studio.writeXRayEntry({ traceId: 'trc_123', provider: 'anthropic', model: 'claude-sonnet-4-6' })
+studio.writeCostReport(tracer.getCostReport())
+```
+
+Then run `elsium studio` in another terminal to see the data in the web dashboard.
+
+---
+
 ## Auto-Instrumentation
 
 ### `instrumentComplete`

package/dist/audit-sink-datadog.d.ts

@@ -0,0 +1,11 @@
+import type { AuditSink } from './audit-sink';
+export interface DatadogSinkConfig {
+    apiKey: string;
+    site?: string;
+    service?: string;
+    source?: string;
+    tags?: Record<string, string>;
+    timeoutMs?: number;
+}
+export declare function createDatadogSink(config: DatadogSinkConfig): AuditSink;
+//# sourceMappingURL=audit-sink-datadog.d.ts.map

package/dist/audit-sink-datadog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink-datadog.d.ts","sourceRoot":"","sources":["../src/audit-sink-datadog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAmCD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CA+CtE"}

package/dist/audit-sink-splunk.d.ts

@@ -0,0 +1,11 @@
+import type { AuditSink } from './audit-sink';
+export interface SplunkSinkConfig {
+    url: string;
+    token: string;
+    index?: string;
+    source?: string;
+    sourcetype?: string;
+    timeoutMs?: number;
+}
+export declare function createSplunkSink(config: SplunkSinkConfig): AuditSink;
+//# sourceMappingURL=audit-sink-splunk.d.ts.map

package/dist/audit-sink-splunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink-splunk.d.ts","sourceRoot":"","sources":["../src/audit-sink-splunk.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAiBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAoCpE"}

package/dist/audit-sink-webhook.d.ts

@@ -0,0 +1,9 @@
+import type { AuditSink } from './audit-sink';
+export interface WebhookSinkConfig {
+    url: string;
+    headers?: Record<string, string>;
+    method?: 'POST' | 'PUT';
+    timeoutMs?: number;
+}
+export declare function createWebhookSink(config: WebhookSinkConfig): AuditSink;
+//# sourceMappingURL=audit-sink-webhook.d.ts.map

package/dist/audit-sink-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink-webhook.d.ts","sourceRoot":"","sources":["../src/audit-sink-webhook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAkCtE"}

package/dist/audit-sink.d.ts

@@ -0,0 +1,30 @@
+import type { AuditEvent } from './audit';
+export interface AuditSink {
+    name: string;
+    filter?: (event: AuditEvent) => boolean;
+    send(events: AuditEvent[]): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+export interface AuditSinkRetryConfig {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface SinkManagerConfig {
+    sinks: AuditSink[];
+    batch?: {
+        size?: number;
+        intervalMs?: number;
+    };
+    retry?: AuditSinkRetryConfig;
+    maxBufferSize?: number;
+    deadLetterSink?: AuditSink;
+    onError?: (sinkName: string, error: unknown) => void;
+}
+export interface SinkManager {
+    dispatch(event: AuditEvent): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function createSinkManager(config: SinkManagerConfig): SinkManager;
+//# sourceMappingURL=audit-sink.d.ts.map

package/dist/audit-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.d.ts","sourceRoot":"","sources":["../src/audit-sink.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIzC,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;IACvC,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,KAAK,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,UAAU,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,SAAS,CAAA;IAC1B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACpD;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAsDD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAmExE"}

package/dist/audit.d.ts

@@ -1,4 +1,5 @@
-import type { Middleware } from '@elsium-ai/core';
+import type { Middleware, StreamMiddleware } from '@elsium-ai/core';
+import type { AuditSink, SinkManagerConfig } from './audit-sink';
 export type AuditEventType = 'llm_call' | 'tool_execution' | 'security_violation' | 'budget_alert' | 'policy_violation' | 'auth_event' | 'approval_request' | 'approval_decision' | 'config_change' | 'provider_failover' | 'circuit_breaker_state_change';
 export interface AuditEvent {
     id: string;
@@ -42,6 +43,8 @@ export interface AuditTrailConfig {
     hashChain?: boolean;
     maxEvents?: number;
     batch?: AuditBatchConfig;
+    sinks?: AuditSink[] | SinkManagerConfig;
+    context?: Record<string, unknown>;
     onError?: (error: unknown) => void;
 }
 export interface AuditTrail {
@@ -54,10 +57,11 @@ export interface AuditTrail {
     query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
     verifyIntegrity(): Promise<AuditIntegrityResult>;
     flush(): Promise<void>;
-    dispose(): void;
+    dispose(): Promise<void>;
     readonly count: number;
     readonly pending: number;
 }
 export declare function createAuditTrail(config?: AuditTrailConfig): AuditTrail;
 export declare function auditMiddleware(auditTrail: AuditTrail): Middleware;
+export declare function auditStreamMiddleware(auditTrail: AuditTrail): StreamMiddleware;
 //# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,14 +6,24 @@ export { observe } from './tracer';
 export type { Tracer, TracerConfig, TracerOutput, TracerExporter, CostReport } from './tracer';
 export { createMetrics } from './metrics';
 export type { MetricsCollector, MetricEntry } from './metrics';
-export { createAuditTrail, auditMiddleware } from './audit';
+export { createAuditTrail, auditMiddleware, auditStreamMiddleware } from './audit';
 export type { AuditEventType, AuditEvent, AuditStorageAdapter, AuditQueryFilter, AuditIntegrityResult, AuditTrailConfig, AuditBatchConfig, AuditTrail, } from './audit';
+export { createSinkManager } from './audit-sink';
+export type { AuditSink, AuditSinkRetryConfig, SinkManagerConfig, SinkManager } from './audit-sink';
+export { createWebhookSink } from './audit-sink-webhook';
+export type { WebhookSinkConfig } from './audit-sink-webhook';
+export { createSplunkSink } from './audit-sink-splunk';
+export type { SplunkSinkConfig } from './audit-sink-splunk';
+export { createDatadogSink } from './audit-sink-datadog';
+export type { DatadogSinkConfig } from './audit-sink-datadog';
 export { createProvenanceTracker } from './provenance';
 export type { ProvenanceRecord, ProvenanceTracker } from './provenance';
 export { createExperiment, createFileExperimentStore } from './experiment';
 export type { Experiment, ExperimentConfig, ExperimentVariant, ExperimentResults, ExperimentStore, } from './experiment';
 export { instrumentComplete, instrumentAgent } from './instrument';
 export type { InstrumentableAgent } from './instrument';
+export { createStudioExporter } from './studio-exporter';
+export type { StudioExporter, StudioExporterConfig } from './studio-exporter';
 export { toOTelSpan, toOTelExportRequest, toTraceparent, parseTraceparent, injectTraceContext, extractTraceContext, createOTLPExporter, } from './otel';
 export type { OTelSpan, OTelSpanKind, OTelStatusCode, OTelAttribute, OTelAttributeValue, OTelEvent, OTelResource, OTelExportRequest, TraceContext, OTLPExporterConfig, } from './otel';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC3D,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAClF,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAG7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAG7E,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -695,6 +695,110 @@ function createMetrics(options) {
 }
 // src/audit.ts
 import { createHash } from "node:crypto";
+
+// src/audit-sink.ts
+var log4 = createLogger();
+function getRetryDelay(attempt, baseDelayMs, maxDelayMs) {
+  const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+  return delay * (0.5 + Math.random() * 0.5);
+}
+async function sendWithRetry(sink, events, retryConfig) {
+  let lastError;
+  for (let attempt = 0;attempt <= retryConfig.maxRetries; attempt++) {
+    try {
+      await sink.send(events);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < retryConfig.maxRetries) {
+        const delay = getRetryDelay(attempt, retryConfig.baseDelayMs, retryConfig.maxDelayMs);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+async function deliverToSink(sink, events, retryConfig, deadLetterSink, onError) {
+  const filtered = sink.filter ? events.filter(sink.filter) : events;
+  if (filtered.length === 0)
+    return;
+  try {
+    await sendWithRetry(sink, filtered, retryConfig);
+  } catch (error) {
+    log4.error("Audit sink delivery failed", { sink: sink.name });
+    onError?.(sink.name, error);
+    if (!deadLetterSink)
+      return;
+    try {
+      await deadLetterSink.send(filtered);
+    } catch (dlqError) {
+      log4.error("Dead letter sink delivery failed", { sink: deadLetterSink.name });
+      onError?.(deadLetterSink.name, dlqError);
+    }
+  }
+}
+function createSinkManager(config) {
+  const { sinks, onError, deadLetterSink } = config;
+  const batchSize = config.batch?.size ?? 50;
+  const batchIntervalMs = config.batch?.intervalMs ?? 5000;
+  const maxBufferSize = config.maxBufferSize ?? 1e4;
+  const retryConfig = {
+    maxRetries: config.retry?.maxRetries ?? 3,
+    baseDelayMs: config.retry?.baseDelayMs ?? 1000,
+    maxDelayMs: config.retry?.maxDelayMs ?? 30000
+  };
+  const buffer = [];
+  const inFlight = new Set;
+  let flushTimer = null;
+  function dispatchBatch(batch) {
+    if (batch.length === 0 || sinks.length === 0)
+      return;
+    const promises = sinks.map((sink) => deliverToSink(sink, batch, retryConfig, deadLetterSink, onError));
+    const combined = Promise.allSettled(promises).then(() => {
+      inFlight.delete(combined);
+    });
+    inFlight.add(combined);
+  }
+  function drainBuffer() {
+    while (buffer.length > 0) {
+      const batch = buffer.splice(0, batchSize);
+      dispatchBatch(batch);
+    }
+  }
+  flushTimer = setInterval(() => {
+    if (buffer.length > 0)
+      drainBuffer();
+  }, batchIntervalMs);
+  if (typeof flushTimer === "object" && "unref" in flushTimer) {
+    flushTimer.unref();
+  }
+  return {
+    dispatch(event) {
+      if (buffer.length >= maxBufferSize) {
+        buffer.shift();
+        log4.warn("Audit sink buffer full, dropping oldest event");
+      }
+      buffer.push(event);
+      if (buffer.length >= batchSize)
+        drainBuffer();
+    },
+    async flush() {
+      drainBuffer();
+      await Promise.allSettled([...inFlight]);
+    },
+    async shutdown() {
+      if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+      }
+      drainBuffer();
+      await Promise.allSettled([...inFlight]);
+      await Promise.allSettled(sinks.map((sink) => sink.shutdown?.()));
+    }
+  };
+}
+
+// src/audit.ts
 function computeEventHash(event, previousHash) {
   const content = JSON.stringify({
     id: event.id,
@@ -803,16 +907,34 @@ class InMemoryAuditStorage {
     return last ? last.hash : ZERO_HASH;
   }
 }
+function resolveStorage(config) {
+  if (config?.storage && typeof config.storage !== "string")
+    return config.storage;
+  return new InMemoryAuditStorage(config?.maxEvents);
+}
+function resolveSinkManager(config) {
+  if (!config?.sinks)
+    return null;
+  const sinkConfig = Array.isArray(config.sinks) ? { sinks: config.sinks } : config.sinks;
+  return createSinkManager(sinkConfig);
+}
+function resolveLastHash(storage) {
+  if (!storage.getLastHash)
+    return ZERO_HASH;
+  return storage.getLastHash();
+}
 function createAuditTrail(config) {
   const useHashChain = config?.hashChain !== false;
-  const storage = config?.storage && typeof config.storage !== "string" ? config.storage : new InMemoryAuditStorage(config?.maxEvents);
+  const storage = resolveStorage(config);
+  const sinkManager = resolveSinkManager(config);
+  const globalContext = config?.context;
   let sequenceId = 0;
   let idCounter = 0;
   let previousHash = ZERO_HASH;
   let isReady = true;
   let readyPromise = Promise.resolve();
-  if (useHashChain && storage.getLastHash) {
-    const lastHash = storage.getLastHash();
+  if (useHashChain) {
+    const lastHash = resolveLastHash(storage);
     if (typeof lastHash === "string") {
       previousHash = lastHash;
     } else {
@@ -830,10 +952,11 @@ function createAuditTrail(config) {
   const isBatched = !!batchConfig;
   const pendingBuffer = [];
   let flushTimer = null;
-  const flushPromise = Promise.resolve();
+  let flushPromise = Promise.resolve();
   function buildAndAppend(entry) {
     sequenceId++;
     idCounter++;
+    const data = globalContext ? { ...globalContext, ...entry.data } : entry.data;
     const event = {
       id: `audit_${idCounter.toString(36)}_${entry.timestamp.toString(36)}`,
       sequenceId,
@@ -841,7 +964,7 @@ function createAuditTrail(config) {
       timestamp: entry.timestamp,
       actor: entry.actor,
       traceId: entry.traceId,
-      data: entry.data,
+      data,
       previousHash: useHashChain ? previousHash : ZERO_HASH
     };
     const hash = useHashChain ? computeEventHash(event, event.previousHash) : createHash("sha256").update(JSON.stringify(event)).digest("hex");
@@ -850,9 +973,10 @@ function createAuditTrail(config) {
       previousHash = hash;
     }
     const result = storage.append(finalEvent);
-    if (result && typeof result.catch === "function") {
-      result.catch((err2) => config?.onError?.(err2));
+    if (result && typeof result.then === "function") {
+      flushPromise = flushPromise.then(() => result).catch((err2) => config?.onError?.(err2));
     }
+    sinkManager?.dispatch(finalEvent);
   }
   function drainBuffer() {
     let entry = pendingBuffer.shift();
@@ -901,13 +1025,16 @@ function createAuditTrail(config) {
       await readyPromise;
       drainBuffer();
       await flushPromise;
+      await sinkManager?.flush();
     },
-    dispose() {
+    async dispose() {
       if (flushTimer) {
         clearInterval(flushTimer);
         flushTimer = null;
       }
       drainBuffer();
+      await flushPromise;
+      await sinkManager?.shutdown();
     },
     async query(filter) {
       if (isBatched)
@@ -958,6 +1085,203 @@ function auditMiddleware(auditTrail) {
     }
   };
 }
+function emitStreamAudit(auditTrail, ctx, state, latencyMs) {
+  if (state.hasError && !state.hasUsage) {
+    auditTrail.log("llm_call", {
+      provider: ctx.provider,
+      model: ctx.model,
+      error: state.errorMessage,
+      latencyMs,
+      success: false,
+      streaming: true
+    }, { traceId: ctx.traceId });
+  } else if (state.hasUsage) {
+    auditTrail.log("llm_call", {
+      provider: ctx.provider,
+      model: ctx.model,
+      inputTokens: state.inputTokens,
+      outputTokens: state.outputTokens,
+      totalTokens: state.totalTokens,
+      latencyMs,
+      stopReason: state.stopReason,
+      streaming: true
+    }, { traceId: ctx.traceId });
+  }
+}
+function auditStreamMiddleware(auditTrail) {
+  return (ctx, source, next) => {
+    const startTime = performance.now();
+    const processed = next(ctx, source);
+    return async function* () {
+      const state = {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        hasUsage: false,
+        hasError: false
+      };
+      try {
+        for await (const event of processed) {
+          if (event.type === "message_end") {
+            state.inputTokens = event.usage.inputTokens;
+            state.outputTokens = event.usage.outputTokens;
+            state.totalTokens = event.usage.totalTokens;
+            state.stopReason = event.stopReason;
+            state.hasUsage = true;
+          }
+          if (event.type === "error") {
+            state.hasError = true;
+            state.errorMessage = event.error.message;
+          }
+          yield event;
+        }
+      } finally {
+        const latencyMs = Math.round(performance.now() - startTime);
+        emitStreamAudit(auditTrail, ctx, state, latencyMs);
+      }
+    }();
+  };
+}
+// src/audit-sink-webhook.ts
+function createWebhookSink(config) {
+  const { url, headers = {}, method = "POST", timeoutMs = 1e4 } = config;
+  return {
+    name: "webhook",
+    async send(events) {
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            ...headers
+          },
+          body: JSON.stringify({ events }),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Webhook responded with ${response.status} ${response.statusText}`);
+        }
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw new Error(`Webhook request timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+// src/audit-sink-splunk.ts
+function toSplunkEvent(event, index, source, sourcetype) {
+  return JSON.stringify({
+    time: event.timestamp / 1000,
+    source: source ?? "elsium-ai",
+    sourcetype: sourcetype ?? "elsium:audit",
+    ...index && { index },
+    event
+  });
+}
+function createSplunkSink(config) {
+  const { url, token, index, source, sourcetype, timeoutMs = 1e4 } = config;
+  return {
+    name: "splunk",
+    async send(events) {
+      const body = events.map((e) => toSplunkEvent(e, index, source, sourcetype)).join(`
+`);
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            Authorization: `Splunk ${token}`,
+            "Content-Type": "application/json"
+          },
+          body,
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Splunk HEC responded with ${response.status} ${response.statusText}`);
+        }
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw new Error(`Splunk HEC request timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
+// src/audit-sink-datadog.ts
+function formatTags(tags) {
+  return Object.entries(tags).map(([k, v]) => `${k}:${v}`).join(",");
+}
+function toDatadogLog(event, service, source, tags) {
+  return {
+    ddsource: source,
+    ddtags: tags ? formatTags(tags) : undefined,
+    service,
+    hostname: "elsium-ai",
+    message: `[${event.type}] ${JSON.stringify(event.data)}`,
+    status: event.type === "security_violation" ? "error" : "info",
+    timestamp: event.timestamp,
+    audit: {
+      id: event.id,
+      sequenceId: event.sequenceId,
+      type: event.type,
+      actor: event.actor,
+      traceId: event.traceId,
+      data: event.data,
+      hash: event.hash,
+      previousHash: event.previousHash
+    }
+  };
+}
+function createDatadogSink(config) {
+  const {
+    apiKey,
+    site = "datadoghq.com",
+    service = "elsium-ai",
+    source = "elsium-ai-audit",
+    tags,
+    timeoutMs = 1e4
+  } = config;
+  const endpoint = `https://http-intake.logs.${site}/api/v2/logs`;
+  return {
+    name: "datadog",
+    async send(events) {
+      const body = events.map((e) => toDatadogLog(e, service, source, tags));
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "DD-API-KEY": apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Datadog Log Intake responded with ${response.status} ${response.statusText}`);
+        }
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw new Error(`Datadog request timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  };
+}
 // src/provenance.ts
 import { createHash as createHash2 } from "node:crypto";
 function sha256(input) {
@@ -1019,7 +1343,7 @@ function createProvenanceTracker(options) {
 import { createHash as createHash3 } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { join } from "node:path";
-var log4 = createLogger();
+var log5 = createLogger();
 function createFileExperimentStore(dir) {
   return {
     save(name, data) {
@@ -1030,7 +1354,7 @@ function createFileExperimentStore(dir) {
         const filePath = join(dir, `${name}.json`);
         writeFileSync2(filePath, JSON.stringify(data, null, 2));
       } catch (err2) {
-        log4.error("Failed to save experiment", {
+        log5.error("Failed to save experiment", {
           name,
           error: err2 instanceof Error ? err2.message : String(err2)
         });
@@ -1061,7 +1385,7 @@ function loadFromStore(store, name, stats) {
       stats[vName].metrics[key] = { sum: m.sum, count: m.count };
     }
   }
-  log4.debug("Loaded experiment state", { name, totalAssignments: saved.totalAssignments });
+  log5.debug("Loaded experiment state", { name, totalAssignments: saved.totalAssignments });
 }
 function recordMetrics(s, metrics) {
   for (const [key, value] of Object.entries(metrics)) {
@@ -1129,7 +1453,7 @@ function createExperiment(config) {
       const s = stats[variant.name];
       if (s)
         s.assignments++;
-      log4.debug("Experiment assignment", {
+      log5.debug("Experiment assignment", {
         experiment: name,
         variant: variant.name,
         userId
@@ -1197,8 +1521,72 @@ function instrumentAgent(agent, tracer) {
   };
   return instrumented;
 }
+// src/studio-exporter.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join2 } from "node:path";
+var log6 = createLogger();
+function ensureDir(dirPath) {
+  if (!existsSync2(dirPath)) {
+    mkdirSync2(dirPath, { recursive: true });
+  }
+}
+function safeWriteJSON(filePath, data) {
+  try {
+    writeFileSync3(filePath, JSON.stringify(data, null, 2));
+  } catch (err2) {
+    log6.error("Studio exporter write failed", {
+      file: filePath,
+      error: err2 instanceof Error ? err2.message : String(err2)
+    });
+  }
+}
+function safeReadJSON(filePath, fallback) {
+  try {
+    if (!existsSync2(filePath))
+      return fallback;
+    return JSON.parse(readFileSync2(filePath, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function createStudioExporter(config) {
+  const baseDir = config?.dir ?? ".elsium";
+  const tracesDir = join2(baseDir, "traces");
+  const xrayFile = join2(baseDir, "xray-history.json");
+  const costFile = join2(baseDir, "cost-report.json");
+  ensureDir(tracesDir);
+  return {
+    name: "studio",
+    export(spans) {
+      for (const span of spans) {
+        if (!span.traceId)
+          continue;
+        const filePath = join2(tracesDir, `${span.traceId}.json`);
+        safeWriteJSON(filePath, span);
+      }
+    },
+    writeXRayEntry(entry) {
+      const history = safeReadJSON(xrayFile, []);
+      history.unshift(entry);
+      if (history.length > 500)
+        history.length = 500;
+      safeWriteJSON(xrayFile, history);
+    },
+    writeCostReport(report) {
+      safeWriteJSON(costFile, {
+        totalRequests: report.callCount,
+        totalTokens: report.totalTokens,
+        totalCost: report.totalCost,
+        byModel: Object.fromEntries(Object.entries(report.byModel).map(([model, data]) => [
+          model,
+          { requests: data.calls, tokens: data.tokens, cost: data.cost }
+        ]))
+      });
+    }
+  };
+}
 // src/otel.ts
-var log5 = createLogger();
+var log7 = createLogger();
 var SPAN_KIND_MAP = {
   llm: 3,
   tool: 1,
@@ -1339,10 +1727,10 @@ function createOTLPExporter(config) {
         body: JSON.stringify(payload)
       });
       if (!response.ok) {
-        log5.error(`OTLP export failed: ${response.status} ${response.statusText}`);
+        log7.error(`OTLP export failed: ${response.status} ${response.statusText}`);
       }
     } catch (err2) {
-      log5.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
+      log7.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
     }
   }
   function startAutoFlush() {
@@ -1389,13 +1777,19 @@ export {
   instrumentAgent,
   injectTraceContext,
   extractTraceContext,
+  createWebhookSink,
+  createStudioExporter,
+  createSplunkSink,
   createSpan,
+  createSinkManager,
   createProvenanceTracker,
   createOTLPExporter,
   createMetrics,
   createFileExperimentStore,
   createExperiment,
+  createDatadogSink,
   createCostEngine,
   createAuditTrail,
+  auditStreamMiddleware,
   auditMiddleware
 };

package/dist/studio-exporter.d.ts

@@ -0,0 +1,10 @@
+import type { CostReport, TracerExporter } from './tracer';
+export interface StudioExporterConfig {
+    dir?: string;
+}
+export interface StudioExporter extends TracerExporter {
+    writeXRayEntry(entry: Record<string, unknown>): void;
+    writeCostReport(report: CostReport): void;
+}
+export declare function createStudioExporter(config?: StudioExporterConfig): StudioExporter;
+//# sourceMappingURL=studio-exporter.d.ts.map

package/dist/studio-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-exporter.d.ts","sourceRoot":"","sources":["../src/studio-exporter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAI1D,MAAM,WAAW,oBAAoB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc;IACrD,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACpD,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;CACzC;AA4BD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAwClF"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/observe",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "Observability, tracing, and cost tracking for ElsiumAI",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -26,7 +26,7 @@
 		"dev": "bun --watch src/index.ts"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.7.0"
+		"@elsium-ai/core": "^0.9.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"