@signalvaultio/node 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,11 @@
 
 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
@@ -86,6 +91,69 @@ for await (const event of stream) {
 }
 ```
 
+## 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:

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();
+        });
+    });
+});

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import OpenAI from 'openai';
+import { ToolsAPI } from './tools';
+export type { ToolRecordOptions, ToolsAPI } from './tools';
 export interface SignalVaultConfig {
     apiKey: string;
     /** Required for OpenAI (chat.completions). */
@@ -81,6 +83,60 @@ export declare class SignalVaultClient {
     private readonly openai;
     private readonly anthropic;
     constructor(config: SignalVaultConfig);
+    /**
+     * 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<TArgs extends readonly unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: {
+        metadata?: Record<string, unknown>;
+    }): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * 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(): ToolsAPI;
+    /**
+     * 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<T>(ctx: {
+        requestId?: string;
+    }, fn: () => Promise<T>): Promise<T>;
+    private sendToolCallEvent;
     get chat(): {
         completions: {
             create(params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming, options?: CreateOptions): Promise<OpenAI.Chat.ChatCompletion>;

package/dist/index.js

@@ -6,6 +6,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SignalVaultClient = void 0;
 const openai_1 = __importDefault(require("openai"));
 const uuid_1 = require("uuid");
+const tools_1 = require("./tools");
+// ---------------------------------------------------------------------------
+// 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.');
+    }
+}
 // ---------------------------------------------------------------------------
 // SignalVaultClient
 // ---------------------------------------------------------------------------
@@ -35,6 +56,7 @@ const uuid_1 = require("uuid");
  */
 class SignalVaultClient {
     constructor(config) {
+        assertNodeEnvironment();
         if (!config.openaiApiKey && !config.anthropicApiKey) {
             throw new Error('[SignalVault] At least one of openaiApiKey or anthropicApiKey is required.');
         }
@@ -65,6 +87,130 @@ class SignalVaultClient {
         }
     }
     // ---------------------------------------------------------------------------
+    // 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) => this.sendToolCallEvent(opts),
+            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),
+        };
+    }
+    /**
+     * 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) {
+        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.
+        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;
+        let serialized;
+        try {
+            serialized = 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;
+        }
+        try {
+            const response = await fetch(`${this.svBaseUrl}/v1/events`, {
+                method: 'POST',
+                headers: this.authHeaders(),
+                signal: AbortSignal.timeout(this.bgTimeout),
+                body: serialized,
+            });
+            // 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);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
     // OpenAI: chat.completions
     // ---------------------------------------------------------------------------
     get chat() {

package/dist/tools.d.ts

@@ -0,0 +1,69 @@
+interface ToolContext {
+    requestId?: string;
+}
+export interface ToolRecordOptions {
+    /** Logical name of the tool. Required. Truncated to 200 bytes. */
+    toolName: string;
+    /** Arguments passed to the tool. Any JSON-serializable value. */
+    toolInput?: unknown;
+    /** What the tool returned. Any JSON-serializable value. */
+    toolOutput?: unknown;
+    /** How long the tool took to run, in milliseconds. */
+    durationMs: number;
+    /** Error message if the tool threw. Truncated to 1900 bytes. */
+    error?: string | null;
+    /**
+     * Optional ISO8601 timestamp of when the tool started.
+     * Falls back to server-side `inserted_at` when omitted.
+     */
+    startedAt?: string;
+    /**
+     * Parent ai.request correlation. If omitted, the SDK uses the requestId from
+     * the surrounding `withContext` block (if any), else null (orphan tool call).
+     */
+    requestId?: string | null;
+    /** Per-call metadata, merged over client-level defaults. */
+    metadata?: Record<string, unknown>;
+}
+export interface ToolsAPI {
+    /**
+     * Records a tool call manually. Use when the wrapper isn't a fit
+     * (streaming tools, custom timing, post-hoc capture).
+     */
+    record(opts: ToolRecordOptions): Promise<void>;
+}
+/** Returns the requestId from the surrounding withContext block, or undefined. */
+export declare function getCurrentRequestId(): string | undefined;
+/** Runs `fn` inside an async context with the given requestId attached. */
+export declare function runWithContext<T>(ctx: ToolContext, fn: () => Promise<T>): Promise<T>;
+export interface ToolWrapperConfig {
+    recordFn: (opts: ToolRecordOptions) => Promise<void>;
+    debug?: boolean;
+}
+/**
+ * Wraps a function so every call records an `agent.tool_call` event with
+ * timing, args, result, and any error.
+ *
+ * The wrapper auto-times, JSON-serializes args/result, and captures the
+ * surrounding `withContext` requestId (if any). Errors propagate to the caller
+ * after recording — wrapping is observation, not error swallowing.
+ */
+export declare function wrapTool<TArgs extends readonly unknown[], TReturn>(config: ToolWrapperConfig, toolName: string, fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: {
+    metadata?: Record<string, unknown>;
+}): (...args: TArgs) => Promise<TReturn>;
+/** Validates and normalizes a tool name. Throws if missing or non-string. */
+export declare function validateToolName(name: unknown): string;
+/** Truncates an error string to the server-accepted byte limit. */
+export declare function sanitizeError(err: unknown): string | undefined;
+/**
+ * Returns a JSON-safe version of `value`, capped at MAX_PAYLOAD_BYTES.
+ *
+ * - Circular references, BigInt, functions, Symbols → replaced with a marker
+ *   object so the audit event is still useful instead of dropped silently.
+ * - Oversized values → truncated; the marker `_signalvault_truncated` is set
+ *   so the receiver can detect partial captures.
+ *
+ * Never throws — sanitization failures degrade gracefully.
+ */
+export declare function sanitizePayload(value: unknown): unknown;
+export {};

package/dist/tools.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentRequestId = getCurrentRequestId;
+exports.runWithContext = runWithContext;
+exports.wrapTool = wrapTool;
+exports.validateToolName = validateToolName;
+exports.sanitizeError = sanitizeError;
+exports.sanitizePayload = sanitizePayload;
+const async_hooks_1 = require("async_hooks");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Hard limit for serialized tool_input/tool_output JSON, in UTF-8 bytes. */
+const MAX_PAYLOAD_BYTES = 256 * 1024; // 256 KB
+/** Hard limit for tool error string, in UTF-8 bytes. */
+const MAX_ERROR_BYTES = 1900;
+/** Hard limit for tool_name, in UTF-8 bytes. */
+const MAX_TOOL_NAME_BYTES = 200;
+const toolContext = new async_hooks_1.AsyncLocalStorage();
+// ---------------------------------------------------------------------------
+// Internal: context-aware request_id resolution
+// ---------------------------------------------------------------------------
+/** Returns the requestId from the surrounding withContext block, or undefined. */
+function getCurrentRequestId() {
+    return toolContext.getStore()?.requestId;
+}
+/** Runs `fn` inside an async context with the given requestId attached. */
+function runWithContext(ctx, fn) {
+    return toolContext.run(ctx, fn);
+}
+/**
+ * Wraps a function so every call records an `agent.tool_call` event with
+ * timing, args, result, and any error.
+ *
+ * The wrapper auto-times, JSON-serializes args/result, and captures the
+ * surrounding `withContext` requestId (if any). Errors propagate to the caller
+ * after recording — wrapping is observation, not error swallowing.
+ */
+function wrapTool(config, toolName, fn, options) {
+    return async (...args) => {
+        const startedAt = new Date().toISOString();
+        const start = Date.now();
+        let result;
+        let error = null;
+        try {
+            result = await Promise.resolve(fn(...args));
+            const durationMs = Date.now() - start;
+            // Fire-and-forget recording so the wrapped function's latency
+            // isn't affected by SignalVault's network call.
+            void config
+                .recordFn({
+                toolName,
+                toolInput: serializeArgs(args),
+                toolOutput: result,
+                durationMs,
+                startedAt,
+                requestId: getCurrentRequestId() ?? null,
+                metadata: options?.metadata,
+            })
+                .catch((err) => {
+                if (config.debug)
+                    console.error('[SignalVault] tool record failed:', err);
+            });
+            return result;
+        }
+        catch (e) {
+            const durationMs = Date.now() - start;
+            error = e instanceof Error ? e.message : String(e);
+            void config
+                .recordFn({
+                toolName,
+                toolInput: serializeArgs(args),
+                toolOutput: null,
+                durationMs,
+                error,
+                startedAt,
+                requestId: getCurrentRequestId() ?? null,
+                metadata: options?.metadata,
+            })
+                .catch((err) => {
+                if (config.debug)
+                    console.error('[SignalVault] tool record failed:', err);
+            });
+            throw e;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Sanitization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns the byte length of a string when encoded as UTF-8.
+ * Used to enforce server-side byte limits accurately on the client.
+ */
+function byteLength(s) {
+    return Buffer.byteLength(s, 'utf8');
+}
+/**
+ * Truncates a string to `max` UTF-8 bytes, preserving multi-byte boundaries.
+ * Appends a "(…N bytes truncated)" marker so the receiver knows truncation
+ * happened rather than seeing a silently shortened string.
+ */
+function truncateString(s, max) {
+    if (byteLength(s) <= max)
+        return s;
+    const marker = (n) => ` …(truncated ${n} bytes)`;
+    // Reserve room for the marker — sized to fit the worst-case marker.
+    const reserve = byteLength(marker(99999999));
+    const buf = Buffer.from(s, 'utf8');
+    const truncatedBytes = buf.byteLength - (max - reserve);
+    const sliced = buf.subarray(0, max - reserve).toString('utf8');
+    // Cleanup: drop a trailing replacement char if we cut a multi-byte sequence.
+    const cleaned = sliced.endsWith('�') ? sliced.slice(0, -1) : sliced;
+    return cleaned + marker(truncatedBytes);
+}
+/** Validates and normalizes a tool name. Throws if missing or non-string. */
+function validateToolName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error('[SignalVault] toolName must be a non-empty string');
+    }
+    return byteLength(name) > MAX_TOOL_NAME_BYTES
+        ? truncateString(name, MAX_TOOL_NAME_BYTES)
+        : name;
+}
+/** Truncates an error string to the server-accepted byte limit. */
+function sanitizeError(err) {
+    if (err === null || err === undefined)
+        return undefined;
+    const s = typeof err === 'string' ? err : String(err);
+    return truncateString(s, MAX_ERROR_BYTES);
+}
+/**
+ * Returns a JSON-safe version of `value`, capped at MAX_PAYLOAD_BYTES.
+ *
+ * - Circular references, BigInt, functions, Symbols → replaced with a marker
+ *   object so the audit event is still useful instead of dropped silently.
+ * - Oversized values → truncated; the marker `_signalvault_truncated` is set
+ *   so the receiver can detect partial captures.
+ *
+ * Never throws — sanitization failures degrade gracefully.
+ */
+function sanitizePayload(value) {
+    if (value === undefined)
+        return null;
+    let serialized;
+    try {
+        serialized = JSON.stringify(value, replacer());
+    }
+    catch (e) {
+        return {
+            _signalvault_serialization_error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    // JSON.stringify returns undefined for top-level functions/Symbols/undefined.
+    if (serialized === undefined) {
+        return { _signalvault_serialization_error: 'value is not JSON-serializable' };
+    }
+    if (byteLength(serialized) <= MAX_PAYLOAD_BYTES) {
+        // Re-parse so the body is sent as a structured value, not a JSON string.
+        try {
+            return JSON.parse(serialized);
+        }
+        catch {
+            return { _signalvault_serialization_error: 're-parse failed' };
+        }
+    }
+    // Oversized: include the original byte size so debugging is possible.
+    return {
+        _signalvault_truncated: true,
+        _signalvault_original_bytes: byteLength(serialized),
+        _signalvault_max_bytes: MAX_PAYLOAD_BYTES,
+        preview: truncateString(serialized, MAX_PAYLOAD_BYTES - 200),
+    };
+}
+/**
+ * JSON.stringify replacer that handles circular refs, BigInts, and other
+ * non-serializable values by substituting markers instead of throwing.
+ */
+function replacer() {
+    const seen = new WeakSet();
+    return function (_key, value) {
+        if (typeof value === 'bigint')
+            return `${value.toString()}n`;
+        if (typeof value === 'function')
+            return '[Function]';
+        if (typeof value === 'symbol')
+            return value.toString();
+        if (value !== null && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        return value;
+    };
+}
+/**
+ * If the wrapped function takes a single argument, store that value directly
+ * (the common case). Otherwise store the whole args array. This avoids storing
+ * `[{...}]` when callers pass a single object — better for dashboard rendering.
+ */
+function serializeArgs(args) {
+    if (args.length === 0)
+        return null;
+    if (args.length === 1)
+        return args[0];
+    return args;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalvaultio/node",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SignalVault SDK - AI audit logs and guardrails for safe production AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,9 @@
   ],
   "author": "SignalVault <support@signalvault.io>",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/signalvaultio/signalvault-node.git"