@signalvaultio/node 0.1.0 → 0.3.0

package/README.md

@@ -1,26 +1,38 @@
 # @signalvaultio/node
 
-AI audit logs and guardrails for your OpenAI applications.
+AI audit logs and guardrails for your OpenAI and Anthropic applications.
+
+> **Server-side only.** This SDK uses Node APIs (`async_hooks`, `fetch`) and
+> requires Node.js **18+**. Do **not** bundle it for the browser — your
+> `apiKey`, `openaiApiKey`, and `anthropicApiKey` would be exposed to end
+> users. Always call SignalVault from your backend.
 
 ## Installation
 
 ```bash
+# OpenAI only
 npm install @signalvaultio/node openai
+
+# Anthropic only
+npm install @signalvaultio/node @anthropic-ai/sdk
+
+# Both
+npm install @signalvaultio/node openai @anthropic-ai/sdk
 ```
 
-## Quick Start
+## Quick Start — OpenAI
 
 ```typescript
 import SignalVaultClient from '@signalvaultio/node';
 
 const client = new SignalVaultClient({
-  apiKey: 'sk_live_your_signalvault_key',    // Your SignalVault API key
-  openaiApiKey: process.env.OPENAI_API_KEY!, // Your OpenAI API key
-  baseUrl: 'https://api.signalvault.io',     // SignalVault API URL
+  apiKey: 'sk_live_your_signalvault_key',
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  baseUrl: 'https://api.signalvault.io',
   environment: 'production',
 });
 
-// Use exactly like OpenAI SDK — all calls are logged and guarded
+// Use exactly like OpenAI SDK
 const response = await client.chat.completions.create({
   model: 'gpt-4',
   messages: [{ role: 'user', content: 'Hello!' }],
@@ -29,11 +41,31 @@ const response = await client.chat.completions.create({
 console.log(response.choices[0].message.content);
 ```
 
+## Quick Start — Anthropic
+
+```typescript
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_your_signalvault_key',
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
+  baseUrl: 'https://api.signalvault.io',
+});
+
+// Use exactly like Anthropic SDK
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  max_tokens: 1024,
+});
+
+console.log(response.content[0].text);
+```
+
 ## Streaming
 
-Streaming responses are fully supported. SignalVault logs the complete response once the stream finishes:
+Streaming is fully supported for both providers. SignalVault logs the complete response once the stream finishes:
 
 ```typescript
+// OpenAI streaming
 const stream = await client.chat.completions.create({
   model: 'gpt-4',
   messages: [{ role: 'user', content: 'Write a poem' }],
@@ -43,48 +75,161 @@ const stream = await client.chat.completions.create({
 for await (const chunk of stream) {
   process.stdout.write(chunk.choices[0]?.delta?.content || '');
 }
+
+// Anthropic streaming
+const stream = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  messages: [{ role: 'user', content: 'Write a poem' }],
+  max_tokens: 1024,
+  stream: true,
+});
+
+for await (const event of stream) {
+  if (event.type === 'content_block_delta') {
+    process.stdout.write(event.delta.text || '');
+  }
+}
+```
+
+## Agent Tool-Use Capture
+
+Log every tool invocation made by your agents — name, input, output, duration, and any error — as auditable events alongside your LLM calls.
+
+### Wrapper API (recommended)
+
+```typescript
+const fetchWeather = client.tool('fetch_weather', async (city: string) => {
+  const res = await fetch(`https://api.example.com/weather?city=${city}`);
+  return res.json();
+});
+
+// Call it like the original — SignalVault auto-times and audits
+const weather = await fetchWeather('London');
+```
+
+The wrapper records the call asynchronously (no impact on your tool's latency) and passes the result through unchanged. Errors are recorded and rethrown.
+
+### Manual API
+
+```typescript
+await client.tools.record({
+  toolName: 'fetch_weather',
+  toolInput: { city: 'London' },
+  toolOutput: { temp: 12.3 },
+  durationMs: 142,
+});
+```
+
+### What gets captured (and what to keep out)
+
+When you wrap a tool or call `tools.record()`, SignalVault captures:
+
+- `tool_name` (truncated to 200 bytes)
+- `tool_input` — the function arguments, JSON-serialized (capped at 256 KB; oversize values are truncated with a marker)
+- `tool_output` — the function return value, JSON-serialized (same 256 KB cap)
+- `error.message` if the tool throws (truncated to 1900 bytes)
+- `duration_ms`, `started_at`, and any `metadata` you attach
+
+These fields are stored encrypted at rest server-side, but they go on the wire
+to SignalVault's API. **If you pass user PII, secrets, or API keys as tool
+arguments, those values will leave your process and be stored in SignalVault.**
+Recommendations:
+
+- Sanitize sensitive arguments before invoking the wrapped tool, or use the
+  manual `tools.record()` API and pass a redacted copy.
+- Don't put secrets in error messages — they end up in `error` verbatim.
+- Use `metadata` for non-sensitive identifiers (`user_id`, `feature`,
+  `workspace_id`); avoid putting raw user content in metadata.
+
+### Linking tool calls to a parent LLM turn
+
+Wrap your agent loop in `withContext` and tool calls inside auto-correlate to the given `requestId`:
+
+```typescript
+await client.withContext({ requestId: 'agent-turn-abc' }, async () => {
+  const llmResponse = await client.chat.completions.create({...});
+  await fetchWeather('London'); // auto-linked to 'agent-turn-abc'
+});
+```
+
+Without `withContext`, tool calls are recorded as orphans (no parent request).
+
+## Metadata
+
+Attach contextual metadata to every event — perfect for audit trails, user attribution, and analytics:
+
+```typescript
+// Set defaults at client level
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_...',
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  metadata: { workspace_id: 'ws_abc', environment: 'production' },
+});
+
+// Override per-call
+const response = await client.chat.completions.create(
+  { model: 'gpt-4', messages: [...] },
+  { metadata: { user_id: 'u_123', feature: 'support-chat' } }
+);
+```
+
+## Timeout Configuration
+
+The pre-flight guardrail check is in your request's critical path. SignalVaultClient uses a short timeout and **fails open** — your request always goes through even if the SignalVault API is slow or unreachable:
+
+```typescript
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_...',
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  preflightTimeout: 2000,  // ms — pre-flight check timeout (fails open). Default: 2000
+  timeout: 10000,          // ms — background/post-flight calls. Default: 10000
+});
 ```
 
 ## Mirror Mode
 
-In mirror mode, requests go directly to OpenAI first and SignalVault audits them asynchronously — no latency added, never blocks:
+In mirror mode, requests go directly to the AI provider first and SignalVault audits them asynchronously — no latency added, never blocks:
 
 ```typescript
 const client = new SignalVaultClient({
   apiKey: 'sk_live_...',
   openaiApiKey: process.env.OPENAI_API_KEY!,
-  mirrorMode: true,   // Monitor only, never block
+  mirrorMode: true,
 });
 ```
 
 ## Features
 
 - **Automatic Logging** — Every request and response is recorded in your SignalVault dashboard
-- **Pre-flight Guardrails** — Block or redact requests before they reach OpenAI
+- **Pre-flight Guardrails** — Block or redact requests before they reach the AI provider
 - **PII Detection** — Automatically detect emails, phone numbers, SSNs in prompts
 - **Secret Detection** — Block API keys and tokens in prompts
 - **Token Limits** — Enforce cost controls per request
 - **Model Allowlists** — Restrict which AI models can be used
-- **Streaming Support** — Full support for streaming completions
+- **Streaming Support** — Full support for streaming completions (OpenAI + Anthropic)
 - **Mirror Mode** — Observe without blocking (zero added latency)
+- **Metadata** — Tag every event with user_id, feature, workspace_id, etc.
+- **Multi-provider** — OpenAI and Anthropic/Claude support
 
 ## Configuration
 
 ```typescript
 const client = new SignalVaultClient({
-  apiKey: 'sk_live_...',          // Your SignalVault API key
-  openaiApiKey: 'sk-...',         // Your OpenAI API key
-  baseUrl: 'https://api.signalvault.io', // SignalVault API URL
-  environment: 'production',      // 'development' | 'staging' | 'production'
-  debug: false,                   // Enable debug logging
-  mirrorMode: false,              // Monitor-only mode
+  apiKey: 'sk_live_...',            // Your SignalVault API key (required)
+  openaiApiKey: 'sk-...',           // OpenAI API key (required for chat.completions)
+  anthropicApiKey: 'sk-ant-...',    // Anthropic API key (required for messages)
+  baseUrl: 'https://api.signalvault.io',
+  environment: 'production',        // 'development' | 'staging' | 'production'
+  debug: false,
+  mirrorMode: false,
+  preflightTimeout: 2000,           // ms
+  timeout: 10000,                   // ms
+  metadata: {},                     // Default metadata for all events
 });
 ```
 
 ## Error Handling
 
-If a request is blocked by a guardrail, an error will be thrown:
-
 ```typescript
 try {
   const response = await client.chat.completions.create({

package/dist/__tests__/index.test.js

@@ -1,49 +1,99 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../index");
-// Minimal unit tests for the SDK (no network calls)
 describe('SignalVaultClient', () => {
-    it('should construct with required config', () => {
-        const client = new index_1.SignalVaultClient({
-            apiKey: 'sk_test_abc',
-            openaiApiKey: 'sk-fake',
-        });
-        expect(client).toBeDefined();
-        expect(client.chat).toBeDefined();
-        expect(client.chat.completions).toBeDefined();
-        expect(typeof client.chat.completions.create).toBe('function');
+    describe('construction', () => {
+        it('constructs with openaiApiKey', () => {
+            const client = new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', openaiApiKey: 'sk-fake' });
+            expect(client).toBeDefined();
+            expect(client.chat).toBeDefined();
+            expect(client.chat.completions).toBeDefined();
+            expect(typeof client.chat.completions.create).toBe('function');
+        });
+        it('throws when neither openaiApiKey nor anthropicApiKey is provided', () => {
+            expect(() => new index_1.SignalVaultClient({ apiKey: 'sk_test_abc' })).toThrow('At least one of openaiApiKey or anthropicApiKey is required');
+        });
+        it('defaults to localhost and production', () => {
+            const client = new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', openaiApiKey: 'sk-fake' });
+            expect(client.svBaseUrl).toBe('http://localhost:4000');
+            expect(client.svEnvironment).toBe('production');
+            expect(client.debugMode).toBe(false);
+            expect(client.mirrorMode).toBe(false);
+        });
+        it('accepts custom config', () => {
+            const client = new index_1.SignalVaultClient({
+                apiKey: 'sk_test_abc',
+                openaiApiKey: 'sk-fake',
+                baseUrl: 'https://api.signalvault.io/',
+                environment: 'staging',
+                debug: true,
+                mirrorMode: true,
+            });
+            expect(client.svBaseUrl).toBe('https://api.signalvault.io');
+            expect(client.svEnvironment).toBe('staging');
+            expect(client.debugMode).toBe(true);
+            expect(client.mirrorMode).toBe(true);
+        });
+        it('strips trailing slashes from baseUrl', () => {
+            const client = new index_1.SignalVaultClient({
+                apiKey: 'sk_test_abc',
+                openaiApiKey: 'sk-fake',
+                baseUrl: 'https://example.com///',
+            });
+            expect(client.svBaseUrl).toBe('https://example.com');
+        });
+    });
+    describe('timeout configuration', () => {
+        it('defaults to 2000ms preflight and 10000ms background', () => {
+            const client = new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', openaiApiKey: 'sk-fake' });
+            expect(client.preflightTimeout).toBe(2000);
+            expect(client.bgTimeout).toBe(10000);
+        });
+        it('accepts custom timeouts', () => {
+            const client = new index_1.SignalVaultClient({
+                apiKey: 'sk_test_abc',
+                openaiApiKey: 'sk-fake',
+                preflightTimeout: 500,
+                timeout: 5000,
+            });
+            expect(client.preflightTimeout).toBe(500);
+            expect(client.bgTimeout).toBe(5000);
+        });
     });
-    it('should default to localhost and production', () => {
-        const client = new index_1.SignalVaultClient({
-            apiKey: 'sk_test_abc',
-            openaiApiKey: 'sk-fake',
-        });
-        // Access private fields via bracket notation for testing
-        expect(client.signalvaultBaseUrl).toBe('http://localhost:4000');
-        expect(client.signalvaultEnvironment).toBe('production');
-        expect(client.debugMode).toBe(false);
-        expect(client.mirrorMode).toBe(false);
+    describe('metadata', () => {
+        it('defaults to empty metadata', () => {
+            const client = new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', openaiApiKey: 'sk-fake' });
+            expect(client.defaultMetadata).toEqual({});
+        });
+        it('accepts metadata in config', () => {
+            const client = new index_1.SignalVaultClient({
+                apiKey: 'sk_test_abc',
+                openaiApiKey: 'sk-fake',
+                metadata: { user_id: 'u_123', feature: 'chat' },
+            });
+            expect(client.defaultMetadata).toEqual({ user_id: 'u_123', feature: 'chat' });
+        });
     });
-    it('should accept custom baseUrl and environment', () => {
-        const client = new index_1.SignalVaultClient({
-            apiKey: 'sk_test_abc',
-            openaiApiKey: 'sk-fake',
-            baseUrl: 'https://api.signalvault.io/',
-            environment: 'staging',
-            debug: true,
-            mirrorMode: true,
-        });
-        expect(client.signalvaultBaseUrl).toBe('https://api.signalvault.io');
-        expect(client.signalvaultEnvironment).toBe('staging');
-        expect(client.debugMode).toBe(true);
-        expect(client.mirrorMode).toBe(true);
+    describe('Anthropic', () => {
+        it('throws on messages access when anthropicApiKey not provided', () => {
+            const client = new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', openaiApiKey: 'sk-fake' });
+            expect(() => client.messages).toThrow('anthropicApiKey not provided');
+        });
+        it('throws when @anthropic-ai/sdk is not installed', () => {
+            expect(() => new index_1.SignalVaultClient({ apiKey: 'sk_test_abc', anthropicApiKey: 'sk-ant-fake' })).toThrow('@anthropic-ai/sdk is not installed');
+        });
     });
-    it('should strip trailing slashes from baseUrl', () => {
-        const client = new index_1.SignalVaultClient({
-            apiKey: 'sk_test_abc',
-            openaiApiKey: 'sk-fake',
-            baseUrl: 'https://example.com///',
+    describe('fail-open on preflight timeout', () => {
+        it('sendRequest returns allow decision on fetch error', async () => {
+            const client = new index_1.SignalVaultClient({
+                apiKey: 'sk_test_abc',
+                openaiApiKey: 'sk-fake',
+                baseUrl: 'http://127.0.0.1:1', // unreachable
+                preflightTimeout: 100,
+            });
+            const decision = await client.sendRequest('req-1', 'gpt-4', [], {}, 'openai');
+            expect(decision.decision).toBe('allow');
+            expect(decision.violations).toEqual([]);
         });
-        expect(client.signalvaultBaseUrl).toBe('https://example.com');
     });
 });

package/dist/__tests__/tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tools.test.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe('Agent tool-use capture', () => {
+    let fetchMock;
+    let client;
+    beforeEach(() => {
+        fetchMock = jest.spyOn(global, 'fetch').mockResolvedValue(new Response(JSON.stringify({ event_id: 'evt_123' }), { status: 200 }));
+        client = new index_1.SignalVaultClient({
+            apiKey: 'sk_test_abc',
+            openaiApiKey: 'sk-fake',
+            baseUrl: 'https://api.example.com',
+        });
+    });
+    afterEach(() => {
+        fetchMock.mockRestore();
+    });
+    // Helper: lets the fire-and-forget tool record promise settle.
+    const flushAsync = () => new Promise((resolve) => setImmediate(resolve));
+    describe('client.tool() wrapper', () => {
+        it('records a successful tool invocation with input/output and timing', async () => {
+            const fetchWeather = client.tool('fetch_weather', async (city) => {
+                return { temp: 12.3, conditions: 'rain', for: city };
+            });
+            const result = await fetchWeather('London');
+            expect(result).toEqual({ temp: 12.3, conditions: 'rain', for: 'London' });
+            await flushAsync();
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const [url, init] = fetchMock.mock.calls[0];
+            expect(url).toBe('https://api.example.com/v1/events');
+            const body = JSON.parse(init.body);
+            expect(body.type).toBe('agent.tool_call');
+            expect(body.payload.tool_name).toBe('fetch_weather');
+            expect(body.payload.tool_input).toBe('London');
+            expect(body.payload.tool_output).toEqual({ temp: 12.3, conditions: 'rain', for: 'London' });
+            expect(body.payload.duration_ms).toBeGreaterThanOrEqual(0);
+            expect(body.payload.started_at).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+        });
+        it('records an errored invocation and rethrows', async () => {
+            const failingTool = client.tool('fetch_external', async () => {
+                throw new Error('connection refused');
+            });
+            await expect(failingTool()).rejects.toThrow('connection refused');
+            await flushAsync();
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.error).toBe('connection refused');
+            expect(body.payload.tool_output).toBeNull();
+        });
+        it('serializes a single object arg as the value, not as an array', async () => {
+            const search = client.tool('search', async (query) => ({ matches: query.k }));
+            await search({ q: 'embeddings', k: 5 });
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_input).toEqual({ q: 'embeddings', k: 5 });
+        });
+        it('serializes multiple args as an array', async () => {
+            const add = client.tool('add', async (a, b) => a + b);
+            await add(2, 3);
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_input).toEqual([2, 3]);
+        });
+        it('does not block on the audit network call (fire-and-forget)', async () => {
+            // Make fetch hang so we can verify the wrapper returns before the audit completes
+            fetchMock.mockImplementation(() => new Promise((resolve) => setTimeout(() => resolve(new Response('{}', { status: 200 })), 5000)));
+            const start = Date.now();
+            const tool = client.tool('fast_tool', async () => 42);
+            const result = await tool();
+            const elapsed = Date.now() - start;
+            expect(result).toBe(42);
+            expect(elapsed).toBeLessThan(100); // should NOT wait the 5s audit timeout
+        });
+        it('supports synchronous functions', async () => {
+            const sum = client.tool('sum', (a, b) => a + b);
+            const result = await sum(2, 3);
+            expect(result).toBe(5);
+        });
+    });
+    describe('client.tools.record() manual API', () => {
+        it('posts a tool_call event with the given fields', async () => {
+            await client.tools.record({
+                toolName: 'manual_tool',
+                toolInput: { x: 1 },
+                toolOutput: { y: 2 },
+                durationMs: 50,
+                requestId: 'req-explicit',
+            });
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.type).toBe('agent.tool_call');
+            expect(body.request_id).toBe('req-explicit');
+            expect(body.payload.tool_name).toBe('manual_tool');
+            expect(body.payload.duration_ms).toBe(50);
+        });
+        it('omits request_id when not provided (orphan tool call)', async () => {
+            await client.tools.record({
+                toolName: 'orphan',
+                durationMs: 10,
+            });
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.request_id).toBeUndefined();
+        });
+    });
+    describe('input sanitization', () => {
+        it('replaces circular references with a marker instead of throwing', async () => {
+            const circular = { name: 'root' };
+            circular.self = circular;
+            const tool = client.tool('circular_tool', async (_arg) => 'ok');
+            await tool(circular);
+            await flushAsync();
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_input).toEqual({ name: 'root', self: '[Circular]' });
+        });
+        it('serializes BigInt arguments as a string with n suffix', async () => {
+            const tool = client.tool('bigint_tool', async (_n) => 'ok');
+            await tool(BigInt(42));
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_input).toBe('42n');
+        });
+        it('truncates oversized tool_output with a marker', async () => {
+            // ~300 KB — over the 256 KB cap.
+            const big = 'x'.repeat(300 * 1024);
+            const tool = client.tool('big_output', async () => ({ blob: big }));
+            await tool();
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_output._signalvault_truncated).toBe(true);
+            expect(body.payload.tool_output._signalvault_original_bytes).toBeGreaterThan(256 * 1024);
+            expect(typeof body.payload.tool_output.preview).toBe('string');
+        });
+        it('truncates a long error message to ~1900 bytes', async () => {
+            const longMsg = 'a'.repeat(5000);
+            const failing = client.tool('long_error', async () => {
+                throw new Error(longMsg);
+            });
+            await expect(failing()).rejects.toThrow();
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            const err = body.payload.error;
+            // Allow a generous upper bound to account for the truncation marker.
+            expect(Buffer.byteLength(err, 'utf8')).toBeLessThanOrEqual(1900);
+            expect(err).toMatch(/truncated/);
+        });
+        it('truncates an oversized tool_name and still records the call', async () => {
+            const longName = 'n'.repeat(500);
+            await client.tools.record({
+                toolName: longName,
+                durationMs: 1,
+            });
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(Buffer.byteLength(body.payload.tool_name, 'utf8')).toBeLessThanOrEqual(200);
+            expect(body.payload.tool_name).toMatch(/truncated/);
+        });
+        it('rejects an empty tool name from the manual API', async () => {
+            await expect(client.tools.record({ toolName: '', durationMs: 1 })).rejects.toThrow(/non-empty string/);
+            expect(fetchMock).not.toHaveBeenCalled();
+        });
+        it('replaces undefined tool_output with null in the body', async () => {
+            const tool = client.tool('void_tool', async () => undefined);
+            await tool();
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_output).toBeNull();
+        });
+        it('replaces a function value with a [Function] marker (not a crash)', async () => {
+            const tool = client.tool('weird_input', async (_fn) => 'ok');
+            await tool(() => 'hello');
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.payload.tool_input).toBe('[Function]');
+        });
+        it('falls back to the serialization-error envelope for top-level undefined', async () => {
+            // A bare `undefined` is JSON-serializable as nothing — the replacer leaves
+            // it alone and JSON.stringify returns undefined. We expose this as a
+            // marker so the audit isn't silently dropped.
+            await client.tools.record({
+                toolName: 'undef',
+                toolInput: undefined,
+                durationMs: 1,
+            });
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            // sanitizePayload(undefined) returns null per the function contract.
+            expect(body.payload.tool_input).toBeNull();
+        });
+    });
+    describe('error logging', () => {
+        let warnSpy;
+        let errorSpy;
+        beforeEach(() => {
+            warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+            errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        });
+        afterEach(() => {
+            warnSpy.mockRestore();
+            errorSpy.mockRestore();
+        });
+        it('surfaces 4xx responses to console.warn even with debug=false', async () => {
+            fetchMock.mockResolvedValue(new Response('bad request', { status: 422 }));
+            await client.tools.record({ toolName: 'will_fail', durationMs: 1 });
+            expect(warnSpy).toHaveBeenCalledTimes(1);
+            expect(warnSpy.mock.calls[0][0]).toMatch(/422/);
+            expect(warnSpy.mock.calls[0][0]).toMatch(/Check your apiKey/);
+        });
+        it('does NOT log 5xx responses unless debug is true', async () => {
+            fetchMock.mockResolvedValue(new Response('boom', { status: 503 }));
+            await client.tools.record({ toolName: 'svc_down', durationMs: 1 });
+            expect(warnSpy).not.toHaveBeenCalled();
+            expect(errorSpy).not.toHaveBeenCalled();
+        });
+    });
+    describe('client.withContext() correlation', () => {
+        it('auto-links wrapped tool calls to the surrounding requestId', async () => {
+            const tool = client.tool('search', async (q) => ({ q }));
+            await client.withContext({ requestId: 'turn-abc' }, async () => {
+                await tool('embeddings');
+            });
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.request_id).toBe('turn-abc');
+        });
+        it('explicit requestId on record() overrides context', async () => {
+            await client.withContext({ requestId: 'context-id' }, async () => {
+                await client.tools.record({
+                    toolName: 'override',
+                    durationMs: 1,
+                    requestId: 'explicit-id',
+                });
+            });
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.request_id).toBe('explicit-id');
+        });
+        it('tools called outside any context are orphans', async () => {
+            const tool = client.tool('orphan_tool', async () => 'ok');
+            await tool();
+            await flushAsync();
+            const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+            expect(body.request_id).toBeUndefined();
+        });
+    });
+});