@signalvaultio/node 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,12 +1,17 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SignalVaultClient = void 0;
-const openai_1 = __importDefault(require("openai"));
-const uuid_1 = require("uuid");
+exports.SignalVaultClient = exports.SignalVaultUnavailableError = exports.SignalVaultBlockedError = exports.SDK_VERSION = void 0;
+exports.normalizeBaseUrl = normalizeBaseUrl;
+const crypto_1 = require("crypto");
 const tools_1 = require("./tools");
+/** Kept in sync with package.json by a unit test. */
+exports.SDK_VERSION = '0.5.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
 // ---------------------------------------------------------------------------
@@ -27,6 +32,174 @@ function assertNodeEnvironment() {
             '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));
+/**
+ * The provider SDKs are optional peers, loaded only when their API key is
+ * configured, so installing just the one you use is enough. The requires are
+ * literal strings inside try blocks on purpose: bundlers can only follow a
+ * literal require, and treat one inside a try as optional.
+ */
+function loadOpenAI(apiKey) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('openai');
+    }
+    catch (error) {
+        throw notInstalled(error, 'openai');
+    }
+    return construct(mod, apiKey);
+}
+function loadAnthropic(apiKey) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        mod = require('@anthropic-ai/sdk');
+    }
+    catch (error) {
+        throw notInstalled(error, '@anthropic-ai/sdk');
+    }
+    return construct(mod, apiKey);
+}
+function construct(mod, apiKey) {
+    const Client = mod.default ?? mod;
+    return new Client({ apiKey });
+}
+/**
+ * Only a missing package is reported as "not installed"; anything else (a
+ * broken install, a missing transitive dependency) is returned unchanged.
+ */
+function notInstalled(error, pkg) {
+    // Read fields directly: `instanceof Error` fails across realms (e.g. under Jest).
+    const { code, message } = (error ?? {});
+    if (code === 'MODULE_NOT_FOUND' && String(message).includes(`'${pkg}'`)) {
+        return new Error(`[SignalVault] ${pkg} is not installed. Run: npm install ${pkg}`);
+    }
+    return error;
+}
+/**
+ * Asks OpenAI to report token usage on a stream, unless the caller already
+ * decided either way. OpenAI then sends one extra final chunk with an empty
+ * `choices` array; `injected` tells the stream wrapper to consume that chunk
+ * instead of passing it to a caller who never asked for it.
+ *
+ * `stream_options: null` opts out entirely: the key is removed, for
+ * OpenAI-compatible servers that reject `stream_options`. (The OpenAI API
+ * treats null and absent the same.)
+ */
+function withStreamUsage(params) {
+    if (!params.stream)
+        return { params, injected: false };
+    const options = params.stream_options;
+    if (options === null) {
+        const { stream_options: _omitted, ...rest } = params;
+        return { params: rest, injected: false };
+    }
+    if (options && options.include_usage !== undefined) {
+        return { params, injected: false };
+    }
+    return {
+        params: { ...params, stream_options: { ...(options ?? {}), include_usage: true } },
+        injected: true,
+    };
+}
 // ---------------------------------------------------------------------------
 // SignalVaultClient
 // ---------------------------------------------------------------------------
@@ -38,10 +211,9 @@ function assertNodeEnvironment() {
  * 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
@@ -49,42 +221,81 @@ function assertNodeEnvironment() {
  * 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 ?? {};
-        this.openai = config.openaiApiKey
-            ? new openai_1.default({ apiKey: config.openaiApiKey })
-            : null;
-        if (config.anthropicApiKey) {
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-var-requires
-                const mod = require('@anthropic-ai/sdk');
-                const Anthropic = mod.default ?? mod;
-                this.anthropic = new Anthropic({ apiKey: config.anthropicApiKey });
-            }
-            catch {
-                throw new Error('[SignalVault] @anthropic-ai/sdk is not installed. Run: npm install @anthropic-ai/sdk');
+        this.openai = config.openaiApiKey ? loadOpenAI(config.openaiApiKey) : null;
+        this.anthropic = config.anthropicApiKey ? loadAnthropic(config.anthropicApiKey) : null;
+    }
+    // ---------------------------------------------------------------------------
+    // 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);
         }
-        else {
-            this.anthropic = null;
-        }
+    }
+    /** 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
@@ -110,7 +321,11 @@ class SignalVaultClient {
      */
     tool(name, fn, options) {
         return (0, tools_1.wrapTool)({
-            recordFn: (opts) => this.sendToolCallEvent(opts),
+            recordFn: (opts) => {
+                const promise = this.sendToolCallEvent(opts);
+                this.track(promise);
+                return promise;
+            },
             debug: this.debugMode,
         }, name, fn, options);
     }
@@ -130,7 +345,7 @@ class SignalVaultClient {
      */
     get tools() {
         return {
-            record: (opts) => this.sendToolCallEvent(opts),
+            record: (opts) => this.sendToolCallEvent(opts, false),
         };
     }
     /**
@@ -149,11 +364,12 @@ class SignalVaultClient {
     withContext(ctx, fn) {
         return (0, tools_1.runWithContext)(ctx, fn);
     }
-    async sendToolCallEvent(opts) {
+    async sendToolCallEvent(opts, retry = true) {
         const metadata = { ...this.defaultMetadata, ...(opts.metadata ?? {}) };
-        // Validate + sanitize before constructing the body. validateToolName throws
-        // on missing/empty name; surfacing that to the caller is intentional —
-        // the manual API should refuse malformed input rather than silently fail.
+        // 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,
@@ -174,9 +390,8 @@ class SignalVaultClient {
         };
         if (opts.requestId)
             body.request_id = opts.requestId;
-        let serialized;
         try {
-            serialized = JSON.stringify(body);
+            JSON.stringify(body);
         }
         catch (error) {
             // sanitizePayload should make this impossible, but guard the outer
@@ -184,30 +399,12 @@ class SignalVaultClient {
             console.warn('[SignalVault] tool_call serialization failed, event dropped:', error);
             return;
         }
-        try {
-            const response = await fetch(`${this.svBaseUrl}/v1/events`, {
-                method: 'POST',
-                headers: this.authHeaders(),
-                signal: AbortSignal.timeout(this.bgTimeout),
-                body: serialized,
-            });
+        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. 5xx are noisy
-            // and only logged in debug mode.
-            if (!response.ok) {
-                if (response.status >= 400 && response.status < 500) {
-                    console.warn(`[SignalVault] tool_call rejected with ${response.status}. ` +
-                        `Check your apiKey and event payload.`);
-                }
-                else if (this.debugMode) {
-                    console.error('[SignalVault] tool_call event failed:', response.status);
-                }
-            }
-        }
-        catch (error) {
-            if (this.debugMode) {
-                console.error('[SignalVault] tool_call event error:', error);
-            }
+            // (bad key, malformed payload) the user must know about.
+            console.warn(`[SignalVault] tool_call rejected with ${result.status}. ` +
+                `Check your apiKey and event payload.`);
         }
     }
     // ---------------------------------------------------------------------------
@@ -221,7 +418,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)' : '');
@@ -244,7 +441,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)' : '');
@@ -260,215 +457,341 @@ 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 usage = withStreamUsage(params);
+        const response = await this.openai.chat.completions.create(usage.params);
+        const model = params.model;
+        const messages = params.messages;
+        if (params.stream) {
+            return this.wrapStream(response, usage.injected, (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 usage = withStreamUsage(params);
+        const response = await this.openai.chat.completions.create(usage.params);
+        if (params.stream) {
+            return this.wrapStream(response, usage.injected, (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. When the SDK added
+     * `include_usage` itself (`hideUsageChunk`), the usage-only final chunk is
+     * consumed here rather than passed on.
+     */
+    async *wrapStream(stream, hideUsageChunk, 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;
+                    // Missing or empty `choices`: the usage-only chunk the caller didn't ask for.
+                    if (hideUsageChunk && !chunk.choices?.length)
+                        continue;
+                }
+                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,
@@ -477,32 +800,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;