@signalvaultio/node 0.2.0 → 0.4.0

package/dist/index.js

@@ -3,9 +3,137 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SignalVaultClient = void 0;
+exports.SignalVaultClient = exports.SignalVaultUnavailableError = exports.SignalVaultBlockedError = exports.SDK_VERSION = void 0;
+exports.normalizeBaseUrl = normalizeBaseUrl;
+const crypto_1 = require("crypto");
 const openai_1 = __importDefault(require("openai"));
-const uuid_1 = require("uuid");
+const tools_1 = require("./tools");
+/** Kept in sync with package.json by a unit test. */
+exports.SDK_VERSION = '0.4.0';
+const DEFAULT_BASE_URL = 'https://api.signalvault.io';
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/** Longest Retry-After the SDK will wait out before retrying a background event once. */
+const MAX_RETRY_AFTER_MS = 5000;
+/** A repeated warning is printed at most once per this window. */
+const WARN_INTERVAL_MS = 60000;
+// ---------------------------------------------------------------------------
+// Environment guard
+// ---------------------------------------------------------------------------
+/**
+ * Hard-fails if the SDK is loaded in a browser context. The SDK relies on
+ * `async_hooks` (Node-only) and is intended for server-side use; bundling it
+ * for the browser would expose `apiKey`, `openaiApiKey`, and `anthropicApiKey`
+ * to end users — which is exactly the kind of leak this product is meant to
+ * prevent.
+ */
+function assertNodeEnvironment() {
+    // `process` exists on Node and not in plain browsers. `window` is the
+    // canonical browser global. We refuse to run if we look browser-like.
+    const hasProcess = typeof process !== 'undefined' && process?.versions?.node;
+    const hasWindow = typeof globalThis.window !== 'undefined';
+    if (!hasProcess || hasWindow) {
+        throw new Error('[SignalVault] This SDK is server-side only. Do not bundle it for browser use — ' +
+            'it will leak your API keys to end users. Call SignalVault from your backend instead.');
+    }
+}
+/**
+ * Normalizes the base URL and refuses plaintext HTTP to anything but the local
+ * machine. The API key and full prompts travel in every request, so an
+ * `http://` URL would expose both before the server could redirect to HTTPS.
+ */
+function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`[SignalVault] baseUrl is not a valid URL: ${raw}`);
+    }
+    if (url.protocol === 'http:' && !LOCAL_HOSTS.has(url.hostname)) {
+        throw new Error('[SignalVault] baseUrl must use https:// (plain http:// is only allowed for localhost). ' +
+            'Your API key and prompts would otherwise be sent unencrypted.');
+    }
+    if (url.search || url.hash) {
+        throw new Error(`[SignalVault] baseUrl must not contain a query or fragment: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`[SignalVault] baseUrl must be an https:// URL, got ${url.protocol}`);
+    }
+    return raw.replace(/\/+$/, '');
+}
+/** Thrown when a guardrail rule blocks the request. */
+class SignalVaultBlockedError extends Error {
+    constructor(requestId, violations, dashboardUrl) {
+        const types = [...new Set(violations.map((v) => String(v?.type ?? '')).filter(Boolean))].join(', ') || 'policy';
+        super(`[SignalVault] Request blocked by guardrails (${types}).`);
+        this.name = 'SignalVaultBlockedError';
+        this.requestId = requestId;
+        this.violations = violations;
+        this.dashboardUrl = dashboardUrl;
+    }
+}
+exports.SignalVaultBlockedError = SignalVaultBlockedError;
+/** Thrown in `failMode: 'closed'` when no guardrail decision could be obtained. */
+class SignalVaultUnavailableError extends Error {
+    constructor(requestId, reason, status) {
+        super(`[SignalVault] Guardrail check unavailable: ${reason}. Request not sent (failMode: 'closed').`);
+        this.name = 'SignalVaultUnavailableError';
+        this.requestId = requestId;
+        this.status = status;
+    }
+}
+exports.SignalVaultUnavailableError = SignalVaultUnavailableError;
+const ALLOW = { decision: 'allow', violations: [], redactions: [] };
+/**
+ * Set on the decision returned when no pre-flight decision was obtained.
+ * 'record': the server may not have stored the request (network, timeout,
+ * 5xx, invalid response), so it is recorded in the background and the
+ * unchecked call still appears in the audit log. 'skip': the server refused
+ * it (401/402/403/429/3xx), so a response event would be refused too.
+ */
+const PREFLIGHT_FAILED = Symbol('preflightFailed');
+/** Causes where re-sending the ai.request later can succeed. */
+const RECORDABLE_CAUSES = new Set(['timeout', 'network', '5xx', 'invalid-response']);
+const DECISIONS = new Set(['allow', 'warn', 'block', 'redact']);
+/**
+ * Checks the name rather than `instanceof Error`: fetch rejects with a
+ * DOMException, which fails `instanceof` across realms (e.g. under Jest).
+ */
+function isTimeout(error) {
+    const name = error?.name;
+    return name === 'TimeoutError' || name === 'AbortError';
+}
+// ---------------------------------------------------------------------------
+// Payload helpers
+// ---------------------------------------------------------------------------
+/**
+ * Anthropic takes the system prompt as a top-level `system` param. The
+ * server scans `payload.messages`, so it is included there as a system
+ * message — otherwise secrets or PII in the system prompt go unchecked.
+ */
+function anthropicMessagesForAudit(params) {
+    const messages = Array.isArray(params?.messages) ? params.messages : [];
+    if (params?.system === undefined || params?.system === null || params?.system === '') {
+        return messages;
+    }
+    return [{ role: 'system', content: params.system }, ...messages];
+}
+/** Concatenates every text block; `content[0]` alone misses text after a tool_use block. */
+function anthropicOutputText(response) {
+    const blocks = Array.isArray(response?.content) ? response.content : [];
+    return blocks
+        .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('');
+}
+function parseRetryAfterMs(response) {
+    const raw = response?.headers?.get?.('retry-after');
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // ---------------------------------------------------------------------------
 // SignalVaultClient
 // ---------------------------------------------------------------------------
@@ -17,10 +145,9 @@ const uuid_1 = require("uuid");
  * const client = new SignalVaultClient({
  *   apiKey: 'sk_live_...',
  *   openaiApiKey: process.env.OPENAI_API_KEY!,
- *   baseUrl: 'https://api.signalvault.io',
  *   metadata: { user_id: '123' },
  * });
- * const res = await client.chat.completions.create({ model: 'gpt-4', messages: [...] });
+ * const res = await client.chat.completions.create({ model: 'gpt-4o', messages: [...] });
  * ```
  *
  * @example Anthropic
@@ -28,21 +155,27 @@ const uuid_1 = require("uuid");
  * const client = new SignalVaultClient({
  *   apiKey: 'sk_live_...',
  *   anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
- *   baseUrl: 'https://api.signalvault.io',
  * });
- * const res = await client.messages.create({ model: 'claude-3-5-sonnet-20241022', messages: [...], max_tokens: 1024 });
+ * const res = await client.messages.create({ model: 'claude-sonnet-4-5', messages: [...], max_tokens: 1024 });
  * ```
  */
 class SignalVaultClient {
     constructor(config) {
+        this.pending = new Set();
+        this.lastWarned = new Map();
+        assertNodeEnvironment();
         if (!config.openaiApiKey && !config.anthropicApiKey) {
             throw new Error('[SignalVault] At least one of openaiApiKey or anthropicApiKey is required.');
         }
+        if (config.failMode !== undefined && config.failMode !== 'open' && config.failMode !== 'closed') {
+            throw new Error("[SignalVault] failMode must be 'open' or 'closed'.");
+        }
         this.svApiKey = config.apiKey;
-        this.svBaseUrl = (config.baseUrl || 'http://localhost:4000').replace(/\/+$/, '');
+        this.svBaseUrl = normalizeBaseUrl(config.baseUrl || DEFAULT_BASE_URL);
         this.svEnvironment = config.environment || 'production';
         this.debugMode = config.debug || false;
         this.mirrorMode = config.mirrorMode || false;
+        this.failMode = config.failMode ?? 'open';
         this.preflightTimeout = config.preflightTimeout ?? 2000;
         this.bgTimeout = config.timeout ?? 10000;
         this.defaultMetadata = config.metadata ?? {};
@@ -65,6 +198,165 @@ class SignalVaultClient {
         }
     }
     // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Waits for in-flight audit events to finish sending, up to `timeoutMs`.
+     * Call before a short-lived process exits (scripts, serverless handlers),
+     * otherwise queued events are lost.
+     */
+    async flush(timeoutMs = 5000) {
+        const deadline = Date.now() + timeoutMs;
+        while (this.pending.size > 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                this.warn('flush-timeout', `[SignalVault] flush() timed out with ${this.pending.size} event(s) still sending.`);
+                return;
+            }
+            let timer;
+            await Promise.race([
+                Promise.allSettled([...this.pending]),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, remaining);
+                }),
+            ]);
+            clearTimeout(timer);
+        }
+    }
+    /** Flushes pending events. The client can still be used afterwards. */
+    async close(timeoutMs = 5000) {
+        await this.flush(timeoutMs);
+    }
+    /** Tracks a background promise so flush() can wait for it. Never rejects. */
+    track(promise) {
+        const tracked = promise
+            .catch((err) => {
+            if (this.debugMode)
+                console.error('[SignalVault] Background event failed:', err);
+        })
+            .finally(() => this.pending.delete(tracked));
+        this.pending.add(tracked);
+    }
+    /** Prints a warning, at most once per minute per key. Not gated on debug. */
+    warn(key, message) {
+        const now = Date.now();
+        const last = this.lastWarned.get(key);
+        if (last !== undefined && now - last < WARN_INTERVAL_MS)
+            return;
+        this.lastWarned.set(key, now);
+        console.warn(message);
+    }
+    // ---------------------------------------------------------------------------
+    // Agent tool-use capture
+    // ---------------------------------------------------------------------------
+    /**
+     * Wraps a function so every call records an `agent.tool_call` event with
+     * timing, input, output, and any error. The wrapper auto-times, runs the
+     * inner function, fires the audit event in the background, and returns the
+     * inner result (or rethrows the inner error).
+     *
+     * Tool calls invoked inside a `withContext({ requestId })` block auto-pick
+     * up the requestId for correlation with the parent ai.request.
+     *
+     * @example
+     * ```typescript
+     * const fetchWeather = signalvault.tool('fetch_weather', async (city: string) => {
+     *   const res = await fetch(`https://api.example.com/weather?city=${city}`);
+     *   return res.json();
+     * });
+     *
+     * const weather = await fetchWeather('London');
+     * ```
+     */
+    tool(name, fn, options) {
+        return (0, tools_1.wrapTool)({
+            recordFn: (opts) => {
+                const promise = this.sendToolCallEvent(opts);
+                this.track(promise);
+                return promise;
+            },
+            debug: this.debugMode,
+        }, name, fn, options);
+    }
+    /**
+     * Manual tool recording API. Use when the wrapper isn't a fit (streaming
+     * tools, custom timing, post-hoc capture from logs).
+     *
+     * @example
+     * ```typescript
+     * await signalvault.tools.record({
+     *   toolName: 'fetch_weather',
+     *   toolInput: { city: 'London' },
+     *   toolOutput: { temp: 12.3 },
+     *   durationMs: 142,
+     * });
+     * ```
+     */
+    get tools() {
+        return {
+            record: (opts) => this.sendToolCallEvent(opts, false),
+        };
+    }
+    /**
+     * Runs the given async function inside a context where tool calls are
+     * automatically correlated to the provided `requestId`. Useful for grouping
+     * a multi-step agent loop under one logical turn.
+     *
+     * @example
+     * ```typescript
+     * await signalvault.withContext({ requestId: 'agent-turn-abc' }, async () => {
+     *   const llm = await signalvault.chat.completions.create({...});
+     *   await fetchWeather('London'); // tool call auto-linked to 'agent-turn-abc'
+     * });
+     * ```
+     */
+    withContext(ctx, fn) {
+        return (0, tools_1.runWithContext)(ctx, fn);
+    }
+    async sendToolCallEvent(opts, retry = true) {
+        const metadata = { ...this.defaultMetadata, ...(opts.metadata ?? {}) };
+        // Validate + sanitize before the first await, so the payload reflects the
+        // arguments at call time even if the caller mutates them afterwards.
+        // validateToolName throws on missing/empty name; surfacing that to the
+        // caller is intentional — the manual API should refuse malformed input.
+        const safeName = (0, tools_1.validateToolName)(opts.toolName);
+        const payload = {
+            tool_name: safeName,
+            tool_input: (0, tools_1.sanitizePayload)(opts.toolInput),
+            tool_output: (0, tools_1.sanitizePayload)(opts.toolOutput),
+            duration_ms: opts.durationMs,
+        };
+        const safeError = (0, tools_1.sanitizeError)(opts.error);
+        if (safeError !== undefined)
+            payload.error = safeError;
+        if (opts.startedAt)
+            payload.started_at = opts.startedAt;
+        const body = {
+            type: 'agent.tool_call',
+            environment: this.svEnvironment,
+            metadata,
+            payload,
+        };
+        if (opts.requestId)
+            body.request_id = opts.requestId;
+        try {
+            JSON.stringify(body);
+        }
+        catch (error) {
+            // sanitizePayload should make this impossible, but guard the outer
+            // serialize too — we'd rather drop the audit than crash the app.
+            console.warn('[SignalVault] tool_call serialization failed, event dropped:', error);
+            return;
+        }
+        const result = await this.postBackground(body, { retry });
+        if (result && !result.ok && result.status >= 400 && result.status < 500 && result.status !== 429) {
+            // Surface 4xx unconditionally — those are usually misconfigurations
+            // (bad key, malformed payload) the user must know about.
+            console.warn(`[SignalVault] tool_call rejected with ${result.status}. ` +
+                `Check your apiKey and event payload.`);
+        }
+    }
+    // ---------------------------------------------------------------------------
     // OpenAI: chat.completions
     // ---------------------------------------------------------------------------
     get chat() {
@@ -75,7 +367,7 @@ class SignalVaultClient {
         return {
             completions: {
                 async create(params, options) {
-                    const requestId = (0, uuid_1.v4)();
+                    const requestId = (0, crypto_1.randomUUID)();
                     const metadata = { ...self.defaultMetadata, ...(options?.metadata ?? {}) };
                     if (self.debugMode) {
                         console.log('[SignalVault] Processing request:', requestId, self.mirrorMode ? '(MIRROR MODE)' : '', params.stream ? '(STREAMING)' : '');
@@ -98,7 +390,7 @@ class SignalVaultClient {
         const self = this;
         return {
             async create(params, options) {
-                const requestId = (0, uuid_1.v4)();
+                const requestId = (0, crypto_1.randomUUID)();
                 const metadata = { ...self.defaultMetadata, ...(options?.metadata ?? {}) };
                 if (self.debugMode) {
                     console.log('[SignalVault] Anthropic request:', requestId, self.mirrorMode ? '(MIRROR MODE)' : '', params.stream ? '(STREAMING)' : '');
@@ -114,215 +406,334 @@ class SignalVaultClient {
     // OpenAI — mirror mode
     // ---------------------------------------------------------------------------
     async handleOpenAIMirror(requestId, params, metadata) {
-        try {
-            const response = await this.openai.chat.completions.create(params);
-            if (params.stream) {
-                return this.wrapStream(requestId, params.model, params.messages, response, async (output, promptTokens, completionTokens) => {
-                    await this.sendAuditEvents(requestId, params.model, params.messages, output, promptTokens, completionTokens, metadata, 'openai');
-                });
-            }
-            const completion = response;
-            this.sendAuditEvents(requestId, params.model, params.messages, completion.choices[0]?.message?.content || '', completion.usage?.prompt_tokens || 0, completion.usage?.completion_tokens || 0, metadata, 'openai').catch((err) => {
-                if (this.debugMode)
-                    console.error('[SignalVault] Audit failed (non-blocking):', err);
-            });
-            return completion;
-        }
-        catch (error) {
-            if (this.debugMode)
-                console.error('[SignalVault] OpenAI error:', error);
-            throw error;
+        const response = await this.openai.chat.completions.create(params);
+        const model = params.model;
+        const messages = params.messages;
+        if (params.stream) {
+            return this.wrapStream(response, (output, promptTokens, completionTokens) => this.sendAuditEvents(requestId, model, messages, output, promptTokens, completionTokens, metadata, 'openai'));
         }
+        const completion = response;
+        this.track(this.sendAuditEvents(requestId, model, messages, completion.choices[0]?.message?.content || '', completion.usage?.prompt_tokens || 0, completion.usage?.completion_tokens || 0, metadata, 'openai'));
+        return completion;
     }
     // ---------------------------------------------------------------------------
     // OpenAI — normal mode
     // ---------------------------------------------------------------------------
     async handleOpenAINormal(requestId, params, metadata) {
-        try {
-            const decision = await this.sendRequest(requestId, params.model, params.messages, metadata, 'openai');
-            if (decision.decision === 'block') {
-                throw new Error(`[SignalVault] Request blocked: ${JSON.stringify(decision.violations)}`);
-            }
-            if (decision.decision === 'warn' && this.debugMode) {
-                console.warn('[SignalVault] Warnings:', decision.violations);
-            }
-            const response = await this.openai.chat.completions.create(params);
-            if (params.stream) {
-                return this.wrapStream(requestId, params.model, params.messages, response, async (output, promptTokens, completionTokens) => {
-                    await this.sendResponseEvent(requestId, params.model, output, promptTokens, completionTokens, metadata, 'openai');
-                });
-            }
-            const completion = response;
-            await this.sendResponseEvent(requestId, params.model, completion.choices[0]?.message?.content || '', completion.usage?.prompt_tokens || 0, completion.usage?.completion_tokens || 0, metadata, 'openai');
-            return completion;
-        }
-        catch (error) {
-            if (this.debugMode)
-                console.error('[SignalVault] Error:', error);
-            throw error;
+        const model = params.model;
+        const messages = params.messages;
+        const decision = await this.enforce(requestId, model, messages, metadata, 'openai');
+        const fallback = this.fallbackRequest(decision, requestId, model, messages, metadata, 'openai');
+        const response = await this.openai.chat.completions.create(params);
+        if (params.stream) {
+            return this.wrapStream(response, (output, promptTokens, completionTokens) => this.sendResponseEvent(requestId, model, output, promptTokens, completionTokens, metadata, 'openai', fallback));
         }
+        const completion = response;
+        // Background: the audit of the response must not delay returning it.
+        this.track(this.sendResponseEvent(requestId, model, completion.choices[0]?.message?.content || '', completion.usage?.prompt_tokens || 0, completion.usage?.completion_tokens || 0, metadata, 'openai', fallback));
+        return completion;
     }
     // ---------------------------------------------------------------------------
     // Anthropic — mirror mode
     // ---------------------------------------------------------------------------
     async handleAnthropicMirror(requestId, params, metadata) {
-        try {
-            const response = await this.anthropic.messages.create(params);
-            if (params.stream) {
-                return this.wrapAnthropicStream(requestId, params.model, params.messages, response, async (output, inputTokens, outputTokens) => {
-                    await this.sendAuditEvents(requestId, params.model, params.messages, output, inputTokens, outputTokens, metadata, 'anthropic');
-                });
-            }
-            const output = response.content?.[0]?.text || '';
-            this.sendAuditEvents(requestId, params.model, params.messages, output, response.usage?.input_tokens || 0, response.usage?.output_tokens || 0, metadata, 'anthropic').catch((err) => {
-                if (this.debugMode)
-                    console.error('[SignalVault] Anthropic audit failed (non-blocking):', err);
-            });
-            return response;
-        }
-        catch (error) {
-            if (this.debugMode)
-                console.error('[SignalVault] Anthropic error:', error);
-            throw error;
+        const response = await this.anthropic.messages.create(params);
+        const messages = anthropicMessagesForAudit(params);
+        if (params.stream) {
+            return this.wrapAnthropicStream(response, (output, inputTokens, outputTokens) => this.sendAuditEvents(requestId, params.model, messages, output, inputTokens, outputTokens, metadata, 'anthropic'));
         }
+        this.track(this.sendAuditEvents(requestId, params.model, messages, anthropicOutputText(response), response.usage?.input_tokens || 0, response.usage?.output_tokens || 0, metadata, 'anthropic'));
+        return response;
     }
     // ---------------------------------------------------------------------------
     // Anthropic — normal mode
     // ---------------------------------------------------------------------------
     async handleAnthropicNormal(requestId, params, metadata) {
-        try {
-            const decision = await this.sendRequest(requestId, params.model, params.messages, metadata, 'anthropic');
-            if (decision.decision === 'block') {
-                throw new Error(`[SignalVault] Request blocked: ${JSON.stringify(decision.violations)}`);
-            }
-            if (decision.decision === 'warn' && this.debugMode) {
-                console.warn('[SignalVault] Warnings:', decision.violations);
-            }
-            const response = await this.anthropic.messages.create(params);
-            if (params.stream) {
-                return this.wrapAnthropicStream(requestId, params.model, params.messages, response, async (output, inputTokens, outputTokens) => {
-                    await this.sendResponseEvent(requestId, params.model, output, inputTokens, outputTokens, metadata, 'anthropic');
-                });
-            }
-            const output = response.content?.[0]?.text || '';
-            await this.sendResponseEvent(requestId, params.model, output, response.usage?.input_tokens || 0, response.usage?.output_tokens || 0, metadata, 'anthropic');
-            return response;
-        }
-        catch (error) {
-            if (this.debugMode)
-                console.error('[SignalVault] Anthropic error:', error);
-            throw error;
+        const messages = anthropicMessagesForAudit(params);
+        const decision = await this.enforce(requestId, params.model, messages, metadata, 'anthropic');
+        const fallback = this.fallbackRequest(decision, requestId, params.model, messages, metadata, 'anthropic');
+        const response = await this.anthropic.messages.create(params);
+        if (params.stream) {
+            return this.wrapAnthropicStream(response, (output, inputTokens, outputTokens) => this.sendResponseEvent(requestId, params.model, output, inputTokens, outputTokens, metadata, 'anthropic', fallback));
         }
+        this.track(this.sendResponseEvent(requestId, params.model, anthropicOutputText(response), response.usage?.input_tokens || 0, response.usage?.output_tokens || 0, metadata, 'anthropic', fallback));
+        return response;
     }
     // ---------------------------------------------------------------------------
-    // Unified OpenAI stream wrapper
+    // Stream wrappers
     // ---------------------------------------------------------------------------
-    async *wrapStream(requestId, model, messages, stream, onComplete) {
+    /**
+     * Yields chunks through unchanged and records the response when the stream
+     * ends — including when the consumer breaks out early or the stream throws,
+     * in which case the partial output is recorded.
+     */
+    async *wrapStream(stream, onComplete) {
         const chunks = [];
         let promptTokens = 0;
         let completionTokens = 0;
-        for await (const chunk of stream) {
-            const content = chunk.choices[0]?.delta?.content || '';
-            if (content)
-                chunks.push(content);
-            if (chunk.usage) {
-                promptTokens = chunk.usage.prompt_tokens || 0;
-                completionTokens = chunk.usage.completion_tokens || 0;
+        try {
+            for await (const chunk of stream) {
+                const content = chunk.choices?.[0]?.delta?.content || '';
+                if (content)
+                    chunks.push(content);
+                if (chunk.usage) {
+                    promptTokens = chunk.usage.prompt_tokens || 0;
+                    completionTokens = chunk.usage.completion_tokens || 0;
+                }
+                yield chunk;
             }
-            yield chunk;
         }
-        onComplete(chunks.join(''), promptTokens, completionTokens).catch((err) => {
-            if (this.debugMode)
-                console.error('[SignalVault] Post-stream callback failed:', err);
-        });
+        finally {
+            this.track(onComplete(chunks.join(''), promptTokens, completionTokens));
+        }
     }
-    // ---------------------------------------------------------------------------
-    // Anthropic stream wrapper
-    // ---------------------------------------------------------------------------
-    async *wrapAnthropicStream(requestId, model, messages, stream, onComplete) {
+    async *wrapAnthropicStream(stream, onComplete) {
         const chunks = [];
         let inputTokens = 0;
         let outputTokens = 0;
-        for await (const event of stream) {
-            if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
-                chunks.push(event.delta.text || '');
-            }
-            if (event.type === 'message_start' && event.message?.usage) {
-                inputTokens = event.message.usage.input_tokens || 0;
-            }
-            if (event.type === 'message_delta' && event.usage) {
-                outputTokens = event.usage.output_tokens || 0;
+        try {
+            for await (const event of stream) {
+                if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+                    chunks.push(event.delta.text || '');
+                }
+                if (event.type === 'message_start' && event.message?.usage) {
+                    inputTokens = event.message.usage.input_tokens || 0;
+                }
+                if (event.type === 'message_delta' && event.usage) {
+                    outputTokens = event.usage.output_tokens || 0;
+                }
+                yield event;
             }
-            yield event;
         }
-        onComplete(chunks.join(''), inputTokens, outputTokens).catch((err) => {
-            if (this.debugMode)
-                console.error('[SignalVault] Anthropic post-stream callback failed:', err);
-        });
+        finally {
+            this.track(onComplete(chunks.join(''), inputTokens, outputTokens));
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Guardrail enforcement
+    // ---------------------------------------------------------------------------
+    /** Runs the pre-flight check and throws if the request must not proceed. */
+    async enforce(requestId, model, messages, metadata, provider) {
+        const decision = await this.sendRequest(requestId, model, messages, metadata, provider);
+        if (decision.decision === 'block') {
+            throw new SignalVaultBlockedError(requestId, decision.violations, decision.dashboard_url);
+        }
+        if (decision.decision === 'warn' && this.debugMode) {
+            console.warn('[SignalVault] Warnings:', decision.violations);
+        }
+        return decision;
+    }
+    /**
+     * Called when no decision could be obtained. Throws in failMode 'closed';
+     * otherwise warns (never silently) and allows.
+     */
+    unavailable(requestId, key, reason, status) {
+        if (this.failMode === 'closed') {
+            throw new SignalVaultUnavailableError(requestId, reason, status);
+        }
+        this.warn(`preflight:${key}`, `[SignalVault] ${reason}. Guardrails were NOT applied — requests are being sent ` +
+            `to the provider unchecked (failMode: 'open').`);
+        const decision = { ...ALLOW, violations: [], redactions: [] };
+        decision[PREFLIGHT_FAILED] =
+            RECORDABLE_CAUSES.has(key) ? 'record' : 'skip';
+        return decision;
+    }
+    /**
+     * The ai.request body to record in the background when the pre-flight got
+     * no decision, so an unchecked call is still in the audit log. Undefined
+     * when the pre-flight was recorded normally; null when the server refused
+     * it and no audit event should be sent.
+     */
+    fallbackRequest(decision, requestId, model, messages, metadata, provider) {
+        const failed = decision[PREFLIGHT_FAILED];
+        if (failed === undefined)
+            return undefined;
+        if (failed === 'skip')
+            return null;
+        return {
+            ...this.requestBody(requestId, model, messages, metadata, provider),
+            payload: { messages, preflight_unavailable: true },
+        };
+    }
+    requestBody(requestId, model, messages, metadata, provider) {
+        return {
+            type: 'ai.request',
+            request_id: requestId,
+            environment: this.svEnvironment,
+            provider,
+            model,
+            metadata,
+            payload: { messages },
+        };
+    }
+    async describeFailure(status, response) {
+        let body;
+        try {
+            body = await response?.json();
+        }
+        catch {
+            body = undefined;
+        }
+        const errorType = typeof body?.error === 'object' ? body.error?.type : body?.error;
+        switch (status) {
+            case 401:
+                return ['401', 'SignalVault rejected the API key (401: invalid or revoked)'];
+            case 402:
+                return ['402', `SignalVault account is not active (402: ${errorType || 'payment required'})`];
+            case 403:
+                return ['403', `SignalVault denied access (403: ${errorType || 'forbidden'})`];
+            case 429:
+                return errorType === 'trial_limit_exceeded'
+                    ? ['429-trial', 'SignalVault trial limit reached (429)']
+                    : ['429', 'SignalVault rate limit reached (429)'];
+            default:
+                if (status >= 300 && status < 400) {
+                    return ['3xx', `SignalVault API redirected (${status}); check that baseUrl is the https:// API URL`];
+                }
+                return status >= 500
+                    ? ['5xx', `SignalVault API error (${status})`]
+                    : [`${status}`, `SignalVault rejected the pre-flight check (${status})`];
+        }
     }
     // ---------------------------------------------------------------------------
     // API communication
     // ---------------------------------------------------------------------------
-    authHeaders() {
+    headers() {
         return {
             'Content-Type': 'application/json',
+            Accept: 'application/json',
             Authorization: `Bearer ${this.svApiKey}`,
+            'User-Agent': `signalvault-node/${exports.SDK_VERSION} node/${process.versions.node}`,
         };
     }
-    async sendRequest(requestId, model, messages, metadata, provider) {
+    /** Single POST. Never follows redirects, so the API key is never re-sent elsewhere. */
+    async post(body, timeoutMs) {
+        const response = await fetch(`${this.svBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: this.headers(),
+            redirect: 'manual',
+            signal: AbortSignal.timeout(timeoutMs),
+            body: JSON.stringify(body),
+        });
+        return { ok: response.ok, status: response.status, response };
+    }
+    /**
+     * POST for background events. Adds an `event_id` so a retry is never
+     * double-counted, and retries once on connection errors, 5xx, and 429 with a
+     * short Retry-After. Timeouts are not retried: the server may be slow rather
+     * than down, and a retry would double the time the event is held. Returns
+     * the last response, or null if nothing was received.
+     */
+    async postBackground(body, { eventId = true, retry = true } = {}) {
+        const event = eventId ? { event_id: (0, crypto_1.randomUUID)(), ...body } : body;
+        let result = null;
+        let retryDelayMs = null;
         try {
-            const response = await fetch(`${this.svBaseUrl}/v1/events`, {
-                method: 'POST',
-                headers: this.authHeaders(),
-                signal: AbortSignal.timeout(this.preflightTimeout),
-                body: JSON.stringify({
-                    type: 'ai.request',
-                    request_id: requestId,
-                    environment: this.svEnvironment,
-                    provider,
-                    model,
-                    metadata,
-                    payload: { messages },
-                }),
-            });
-            if (!response.ok) {
-                if (this.debugMode)
-                    console.error('[SignalVault] API error:', response.status);
-                return { decision: 'allow', violations: [], redactions: [] };
+            result = await this.post(event, this.bgTimeout);
+            if (result.ok)
+                return result;
+            if (result.status === 429) {
+                const retryAfter = parseRetryAfterMs(result.response);
+                retryDelayMs = retryAfter !== null && retryAfter <= MAX_RETRY_AFTER_MS ? retryAfter : null;
+            }
+            else if (result.status >= 500) {
+                retryDelayMs = 250 + Math.random() * 500;
             }
-            return (await response.json());
         }
         catch (error) {
             if (this.debugMode)
-                console.error('[SignalVault] Pre-flight failed (fail-open):', error);
-            return { decision: 'allow', violations: [], redactions: [] };
+                console.error('[SignalVault] Event send failed:', error);
+            if (!isTimeout(error))
+                retryDelayMs = 250 + Math.random() * 500;
+        }
+        if (retry && retryDelayMs !== null) {
+            await sleep(retryDelayMs);
+            try {
+                result = await this.post(event, this.bgTimeout);
+                if (result.ok)
+                    return result;
+            }
+            catch (error) {
+                if (this.debugMode)
+                    console.error('[SignalVault] Event retry failed:', error);
+            }
+        }
+        this.logUndelivered(result);
+        return result;
+    }
+    logUndelivered(result) {
+        if (result?.status === 429) {
+            this.warn('bg-429', '[SignalVault] Rate limited (429): audit events are being dropped.');
+        }
+        else if (this.debugMode) {
+            console.error('[SignalVault] Event not delivered:', result ? result.status : 'no response');
         }
     }
-    async sendResponseEvent(requestId, model, output, promptTokens, completionTokens, metadata, provider) {
+    async sendRequest(requestId, model, messages, metadata, provider) {
+        let result;
         try {
-            await fetch(`${this.svBaseUrl}/v1/events`, {
-                method: 'POST',
-                headers: this.authHeaders(),
-                signal: AbortSignal.timeout(this.bgTimeout),
-                body: JSON.stringify({
-                    type: 'ai.response',
-                    request_id: requestId,
-                    environment: this.svEnvironment,
-                    provider,
-                    model,
-                    metadata,
-                    payload: {
-                        output,
-                        usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
-                    },
-                }),
-            });
+            result = await this.post(this.requestBody(requestId, model, messages, metadata, provider), this.preflightTimeout);
         }
         catch (error) {
+            const timedOut = isTimeout(error);
             if (this.debugMode)
-                console.error('[SignalVault] Failed to send response event:', error);
+                console.error('[SignalVault] Pre-flight failed:', error);
+            return this.unavailable(requestId, timedOut ? 'timeout' : 'network', timedOut
+                ? `SignalVault pre-flight check timed out after ${this.preflightTimeout}ms`
+                : 'SignalVault API is unreachable');
+        }
+        if (!result.ok) {
+            const [key, reason] = await this.describeFailure(result.status, result.response);
+            return this.unavailable(requestId, key, reason, result.status);
+        }
+        let data;
+        try {
+            data = await result.response.json();
         }
+        catch (error) {
+            if (isTimeout(error)) {
+                return this.unavailable(requestId, 'timeout', `SignalVault pre-flight check timed out after ${this.preflightTimeout}ms`);
+            }
+            return this.unavailable(requestId, 'invalid-response', 'SignalVault returned an invalid response');
+        }
+        if (!data || typeof data !== 'object' || !DECISIONS.has(data.decision)) {
+            return this.unavailable(requestId, 'invalid-response', 'SignalVault returned an invalid decision');
+        }
+        return {
+            decision: data.decision,
+            violations: Array.isArray(data.violations)
+                ? data.violations.filter((v) => v !== null && typeof v === 'object')
+                : [],
+            redactions: Array.isArray(data.redactions) ? data.redactions : [],
+            dashboard_url: typeof data.dashboard_url === 'string' ? data.dashboard_url : undefined,
+        };
+    }
+    async sendResponseEvent(requestId, model, output, promptTokens, completionTokens, metadata, provider, fallbackRequest) {
+        if (fallbackRequest === null)
+            return;
+        if (fallbackRequest) {
+            // Must land before the response: the server rejects an ai.response whose
+            // ai.request it has not stored.
+            await this.postBackground(fallbackRequest, { eventId: false });
+        }
+        await this.postBackground({
+            type: 'ai.response',
+            request_id: requestId,
+            environment: this.svEnvironment,
+            provider,
+            model,
+            metadata,
+            payload: {
+                output,
+                usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
+            },
+        });
     }
+    /**
+     * Mirror mode: records the request, then the response. Sequential on
+     * purpose — the server rejects an ai.response whose ai.request it has not
+     * stored yet, so sending both at once can lose the response.
+     */
     async sendAuditEvents(requestId, model, messages, output, promptTokens, completionTokens, metadata, provider) {
         const base = {
             request_id: requestId,
@@ -331,32 +742,20 @@ class SignalVaultClient {
             model,
             metadata,
         };
-        await Promise.all([
-            fetch(`${this.svBaseUrl}/v1/events`, {
-                method: 'POST',
-                headers: this.authHeaders(),
-                signal: AbortSignal.timeout(this.bgTimeout),
-                body: JSON.stringify({
-                    ...base,
-                    type: 'ai.request',
-                    payload: { messages, monitor_mode: true },
-                }),
-            }),
-            fetch(`${this.svBaseUrl}/v1/events`, {
-                method: 'POST',
-                headers: this.authHeaders(),
-                signal: AbortSignal.timeout(this.bgTimeout),
-                body: JSON.stringify({
-                    ...base,
-                    type: 'ai.response',
-                    payload: {
-                        output,
-                        usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
-                        monitor_mode: true,
-                    },
-                }),
-            }),
-        ]);
+        await this.postBackground({
+            ...base,
+            type: 'ai.request',
+            payload: { messages, monitor_mode: true },
+        });
+        await this.postBackground({
+            ...base,
+            type: 'ai.response',
+            payload: {
+                output,
+                usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
+                monitor_mode: true,
+            },
+        });
     }
 }
 exports.SignalVaultClient = SignalVaultClient;