@illuma-ai/agents 1.0.89 → 1.0.93

package/src/specs/observability.integration.test.js

@@ -0,0 +1,1337 @@
+/**
+ * Integration tests for Illuma Observability SDK integration in agents.
+ *
+ * These tests verify that the ObservabilityCallbackHandler and IllumaSpanProcessor
+ * correctly route LangChain/OTel events to trace payloads with proper structure,
+ * parent-child relationships, and token usage metrics.
+ *
+ * Uses a mock client to capture enqueued events without hitting a real server.
+ */
+import { ObservabilityCallbackHandler } from '@illuma-ai/observability-langchain';
+// ---------------------------------------------------------------------------
+// Mock Client - captures enqueued events for assertions
+// ---------------------------------------------------------------------------
+class MockObservabilityClient {
+    events = [];
+    flushed = false;
+    shutdownCalled = false;
+    enqueue(event) {
+        this.events.push(event);
+    }
+    async flush() {
+        this.flushed = true;
+    }
+    async shutdown() {
+        this.shutdownCalled = true;
+        await this.flush();
+    }
+    /** Get events filtered by type */
+    getByType(type) {
+        return this.events.filter((e) => e.type === type);
+    }
+    /** Get all event types in order */
+    getEventTypes() {
+        return this.events.map((e) => e.type);
+    }
+    /** Pretty-print all events for debugging */
+    printEvents() {
+        for (const event of this.events) {
+            const body = event.body;
+            const usage = body.usage;
+            console.log(`  ${event.type} | name=${body.name ?? '—'} | id=${body.id ?? '—'} | traceId=${body.traceId ?? '—'} | parentObsId=${body.parentObservationId ?? '—'}` +
+                (usage ? ` | usage={prompt:${usage.promptTokens ?? '—'},completion:${usage.completionTokens ?? '—'},total:${usage.totalTokens ?? '—'}}` : '') +
+                (body.model ? ` | model=${body.model}` : '') +
+                (body.provider ? ` | provider=${body.provider}` : '') +
+                (body.level === 'ERROR' ? ` | ERROR: ${body.statusMessage}` : ''));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const serialized = (name) => ({
+    lc: 1,
+    type: 'not_implemented',
+    id: ['langchain', name],
+});
+function makeUUID() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('ObservabilityCallbackHandler integration', () => {
+    let client;
+    let handler;
+    beforeEach(() => {
+        client = new MockObservabilityClient();
+        handler = new ObservabilityCallbackHandler({
+            client,
+            traceName: 'test-agent-run',
+            userId: 'user-42',
+            sessionId: 'session-abc',
+            tags: ['integration-test'],
+            metadata: { messageId: 'msg-001' },
+            environment: 'test',
+            debug: false,
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 1. Root trace creation
+    // -----------------------------------------------------------------------
+    describe('root trace creation', () => {
+        it('should create a trace on the first chain start', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'Hello agent' }, chainRunId);
+            const traceEvents = client.getByType('trace-create');
+            expect(traceEvents).toHaveLength(1);
+            const trace = traceEvents[0].body;
+            expect(trace.name).toBe('test-agent-run');
+            expect(trace.userId).toBe('user-42');
+            expect(trace.sessionId).toBe('session-abc');
+            expect(trace.tags).toEqual(['integration-test']);
+            expect(trace.metadata).toEqual({ messageId: 'msg-001' });
+            expect(trace.environment).toBe('test');
+            expect(trace.input).toEqual({ input: 'Hello agent' });
+        });
+        it('should not create a second trace for nested chains', async () => {
+            const outerRunId = makeUUID();
+            const innerRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'outer' }, outerRunId);
+            await handler.handleChainStart(serialized('ChatPromptTemplate'), { input: 'inner' }, innerRunId, outerRunId);
+            const traceEvents = client.getByType('trace-create');
+            expect(traceEvents).toHaveLength(1); // Only one trace, not two
+        });
+        it('should return the trace ID after creation', async () => {
+            expect(handler.getTraceId()).toBeNull();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, makeUUID());
+            expect(handler.getTraceId()).toBeTruthy();
+            expect(typeof handler.getTraceId()).toBe('string');
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 2. LLM generation events
+    // -----------------------------------------------------------------------
+    describe('LLM generation tracing', () => {
+        it('should create generation-create with input prompts', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('ChatAnthropic'), ['You are a helpful assistant.\n\nHuman: Hello'], llmRunId, chainRunId, undefined, undefined, { ls_model_name: 'claude-sonnet-4-20250514', ls_provider: 'anthropic' });
+            const genEvents = client.getByType('generation-create');
+            expect(genEvents).toHaveLength(1);
+            const gen = genEvents[0].body;
+            expect(gen.name).toBe('ChatAnthropic');
+            expect(gen.model).toBe('claude-sonnet-4-20250514');
+            expect(gen.provider).toBe('anthropic');
+            expect(gen.input).toEqual(['You are a helpful assistant.\n\nHuman: Hello']);
+            expect(gen.traceId).toBe(handler.getTraceId());
+            // Parent should be the chain
+            const chainEvents = client.getByType('chain-create');
+            const chainObsId = chainEvents[0].body.id;
+            expect(gen.parentObservationId).toBe(chainObsId);
+        });
+        it('should create generation-update with token usage on LLM end', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('ChatOpenAI'), ['Hello'], llmRunId, chainRunId);
+            const llmResult = {
+                generations: [[{ text: 'Hi there! How can I help?', generationInfo: {} }]],
+                llmOutput: {
+                    tokenUsage: {
+                        promptTokens: 150,
+                        completionTokens: 42,
+                        totalTokens: 192,
+                    },
+                    modelName: 'gpt-4o',
+                    provider: 'openai',
+                },
+            };
+            await handler.handleLLMEnd(llmResult, llmRunId);
+            const genUpdates = client.getByType('generation-update');
+            expect(genUpdates).toHaveLength(1);
+            const update = genUpdates[0].body;
+            expect(update.output).toBe('Hi there! How can I help?');
+            expect(update.model).toBe('gpt-4o');
+            expect(update.provider).toBe('openai');
+            expect(update.endTime).toBeDefined();
+            const usage = update.usage;
+            expect(usage.promptTokens).toBe(150);
+            expect(usage.completionTokens).toBe(42);
+            expect(usage.totalTokens).toBe(192);
+        });
+        it('should handle LLM errors with ERROR level', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('ChatAnthropic'), ['Hello'], llmRunId, chainRunId);
+            await handler.handleLLMError(new Error('Rate limit exceeded'), llmRunId);
+            const genUpdates = client.getByType('generation-update');
+            expect(genUpdates).toHaveLength(1);
+            const update = genUpdates[0].body;
+            expect(update.level).toBe('ERROR');
+            expect(update.statusMessage).toBe('Rate limit exceeded');
+            expect(update.endTime).toBeDefined();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 3. Chain events
+    // -----------------------------------------------------------------------
+    describe('chain tracing', () => {
+        it('should create chain-create events with input', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { query: 'What is AI?' }, chainRunId);
+            const chainEvents = client.getByType('chain-create');
+            expect(chainEvents).toHaveLength(1);
+            const chain = chainEvents[0].body;
+            expect(chain.name).toBe('RunnableSequence');
+            expect(chain.input).toEqual({ query: 'What is AI?' });
+            expect(chain.traceId).toBe(handler.getTraceId());
+        });
+        it('should create span-update on chain end with output', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleChainEnd({ output: 'AI is artificial intelligence.' }, chainRunId);
+            const spanUpdates = client.getByType('span-update');
+            expect(spanUpdates).toHaveLength(1);
+            const update = spanUpdates[0].body;
+            expect(update.output).toEqual({ output: 'AI is artificial intelligence.' });
+            expect(update.endTime).toBeDefined();
+        });
+        it('should handle chain error with ERROR level', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleChainError(new Error('Chain failed: missing tool'), chainRunId);
+            const spanUpdates = client.getByType('span-update');
+            const errorUpdate = spanUpdates.find((e) => e.body.level === 'ERROR');
+            expect(errorUpdate).toBeDefined();
+            expect(errorUpdate.body.statusMessage).toBe('Chain failed: missing tool');
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 4. Tool events
+    // -----------------------------------------------------------------------
+    describe('tool tracing', () => {
+        it('should create tool-create events', async () => {
+            const chainRunId = makeUUID();
+            const toolRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleToolStart(serialized('web_search'), '{"query": "latest AI news"}', toolRunId, chainRunId);
+            const toolEvents = client.getByType('tool-create');
+            expect(toolEvents).toHaveLength(1);
+            const tool = toolEvents[0].body;
+            expect(tool.name).toBe('Tool: web_search');
+            expect(tool.input).toBe('{"query": "latest AI news"}');
+            expect(tool.traceId).toBe(handler.getTraceId());
+        });
+        it('should create span-update on tool end', async () => {
+            const chainRunId = makeUUID();
+            const toolRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleToolStart(serialized('calculator'), '{"expression": "2+2"}', toolRunId, chainRunId);
+            await handler.handleToolEnd('4', toolRunId);
+            const spanUpdates = client.getByType('span-update');
+            expect(spanUpdates).toHaveLength(1);
+            expect(spanUpdates[0].body.output).toBe('4');
+        });
+        it('should handle tool error', async () => {
+            const chainRunId = makeUUID();
+            const toolRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleToolStart(serialized('api_call'), '{"url": "https://example.com"}', toolRunId, chainRunId);
+            await handler.handleToolError(new Error('Connection timeout'), toolRunId);
+            const spanUpdates = client.getByType('span-update');
+            const errorUpdate = spanUpdates.find((e) => e.body.level === 'ERROR');
+            expect(errorUpdate).toBeDefined();
+            expect(errorUpdate.body.statusMessage).toBe('Connection timeout');
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 5. Retriever events
+    // -----------------------------------------------------------------------
+    describe('retriever tracing', () => {
+        it('should create retriever-create events', async () => {
+            const chainRunId = makeUUID();
+            const retrieverRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleRetrieverStart(serialized('VectorStoreRetriever'), 'How does photosynthesis work?', retrieverRunId, chainRunId);
+            const retrieverEvents = client.getByType('retriever-create');
+            expect(retrieverEvents).toHaveLength(1);
+            const retriever = retrieverEvents[0].body;
+            expect(retriever.name).toBe('Retriever: VectorStoreRetriever');
+            expect(retriever.input).toBe('How does photosynthesis work?');
+        });
+        it('should produce span-update with documents on retriever end', async () => {
+            const chainRunId = makeUUID();
+            const retrieverRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'test' }, chainRunId);
+            await handler.handleRetrieverStart(serialized('VectorStoreRetriever'), 'photosynthesis', retrieverRunId, chainRunId);
+            const documents = [
+                { pageContent: 'Photosynthesis is the process...', metadata: { source: 'wiki', page: 1 } },
+                { pageContent: 'Plants use chlorophyll...', metadata: { source: 'textbook', page: 42 } },
+            ];
+            await handler.handleRetrieverEnd(documents, retrieverRunId);
+            const spanUpdates = client.getByType('span-update');
+            expect(spanUpdates).toHaveLength(1);
+            const update = spanUpdates[0].body;
+            const output = update.output;
+            expect(output).toHaveLength(2);
+            expect(output[0].pageContent).toBe('Photosynthesis is the process...');
+            expect(output[0].metadata).toEqual({ source: 'wiki', page: 1 });
+            const meta = update.metadata;
+            expect(meta.documentCount).toBe(2);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 6. Parent-child hierarchy
+    // -----------------------------------------------------------------------
+    describe('parent-child hierarchy', () => {
+        it('should correctly link nested observations to parent', async () => {
+            const outerChainId = makeUUID();
+            const innerChainId = makeUUID();
+            const llmRunId = makeUUID();
+            const toolRunId = makeUUID();
+            // Outer chain starts
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'orchestrate' }, outerChainId);
+            // Inner chain nested under outer
+            await handler.handleChainStart(serialized('ChatPromptTemplate'), { input: 'format prompt' }, innerChainId, outerChainId);
+            // LLM nested under inner chain
+            await handler.handleLLMStart(serialized('ChatOpenAI'), ['formatted prompt'], llmRunId, innerChainId);
+            // Tool nested under outer chain
+            await handler.handleToolStart(serialized('calculator'), '2+2', toolRunId, outerChainId);
+            // Verify hierarchy
+            const chainCreates = client.getByType('chain-create');
+            const genCreates = client.getByType('generation-create');
+            const toolCreates = client.getByType('tool-create');
+            // All share the same traceId
+            const traceId = handler.getTraceId();
+            expect(chainCreates[0].body.traceId).toBe(traceId);
+            expect(chainCreates[1].body.traceId).toBe(traceId);
+            expect(genCreates[0].body.traceId).toBe(traceId);
+            expect(toolCreates[0].body.traceId).toBe(traceId);
+            // Inner chain -> parent is outer chain's observationId
+            const outerChainObsId = chainCreates[0].body.id;
+            const innerChainObsId = chainCreates[1].body.id;
+            expect(chainCreates[1].body.parentObservationId).toBe(outerChainObsId);
+            // LLM -> parent is inner chain
+            expect(genCreates[0].body.parentObservationId).toBe(innerChainObsId);
+            // Tool -> parent is outer chain
+            expect(toolCreates[0].body.parentObservationId).toBe(outerChainObsId);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 7. Full agent pipeline simulation
+    // -----------------------------------------------------------------------
+    describe('full agent pipeline simulation', () => {
+        it('should produce correct event sequence for a RAG agent with tools', async () => {
+            const chainRunId = makeUUID();
+            const agentChainId = makeUUID();
+            const retrieverRunId = makeUUID();
+            const llmRunId1 = makeUUID();
+            const toolRunId = makeUUID();
+            const llmRunId2 = makeUUID();
+            // 1. Root chain starts (the main graph)
+            await handler.handleChainStart(serialized('CompiledStateGraph'), { messages: [{ role: 'user', content: 'What papers did OpenAI publish in 2024?' }] }, chainRunId);
+            // 2. Agent chain starts (nested)
+            await handler.handleChainStart(serialized('AgentExecutor'), { input: 'What papers did OpenAI publish in 2024?' }, agentChainId, chainRunId);
+            // 3. First LLM call (decides to use tool)
+            await handler.handleLLMStart(serialized('ChatAnthropic'), ['System: You are a research assistant.\nHuman: What papers...'], llmRunId1, agentChainId, undefined, undefined, { ls_model_name: 'claude-sonnet-4-20250514', ls_provider: 'anthropic' });
+            await handler.handleLLMEnd({
+                generations: [[{
+                            text: 'I\'ll search for OpenAI papers from 2024.',
+                            generationInfo: {},
+                        }]],
+                llmOutput: {
+                    tokenUsage: { promptTokens: 200, completionTokens: 30, totalTokens: 230 },
+                    modelName: 'claude-sonnet-4-20250514',
+                    provider: 'anthropic',
+                },
+            }, llmRunId1);
+            // 4. Retriever runs
+            await handler.handleRetrieverStart(serialized('VectorStoreRetriever'), 'OpenAI papers 2024', retrieverRunId, agentChainId);
+            await handler.handleRetrieverEnd([
+                { pageContent: 'GPT-4o: omni-model for text, vision, audio...', metadata: { source: 'arxiv', year: 2024 } },
+                { pageContent: 'Sora: text-to-video generation model...', metadata: { source: 'blog', year: 2024 } },
+            ], retrieverRunId);
+            // 5. Tool call (web search)
+            await handler.handleToolStart(serialized('web_search'), '{"query": "OpenAI 2024 research papers list"}', toolRunId, agentChainId);
+            await handler.handleToolEnd(JSON.stringify([
+                { title: 'GPT-4o Technical Report', url: 'https://arxiv.org/...' },
+                { title: 'Sora', url: 'https://openai.com/sora' },
+            ]), toolRunId);
+            // 6. Second LLM call (final answer)
+            await handler.handleLLMStart(serialized('ChatAnthropic'), ['System: ...\nContext: ...\nHuman: What papers...'], llmRunId2, agentChainId, undefined, undefined, { ls_model_name: 'claude-sonnet-4-20250514', ls_provider: 'anthropic' });
+            await handler.handleLLMEnd({
+                generations: [[{
+                            text: 'OpenAI published several notable papers in 2024 including GPT-4o and Sora...',
+                            generationInfo: {},
+                        }]],
+                llmOutput: {
+                    tokenUsage: { promptTokens: 800, completionTokens: 150, totalTokens: 950 },
+                    modelName: 'claude-sonnet-4-20250514',
+                    provider: 'anthropic',
+                },
+            }, llmRunId2);
+            // 7. Chains end
+            await handler.handleChainEnd({ output: 'OpenAI published several notable papers...' }, agentChainId);
+            await handler.handleChainEnd({ messages: [{ role: 'assistant', content: 'OpenAI published several notable papers...' }] }, chainRunId);
+            // Flush
+            await handler.flushAsync();
+            expect(client.flushed).toBe(true);
+            // --- Assertions ---
+            // Uncomment to debug: client.printEvents();
+            // Verify event counts
+            const eventTypes = client.getEventTypes();
+            const typeCounts = eventTypes.reduce((acc, t) => { acc[t] = (acc[t] || 0) + 1; return acc; }, {});
+            expect(typeCounts['trace-create']).toBe(1); // Root trace
+            expect(typeCounts['chain-create']).toBe(1); // Outer chain only
+            expect(typeCounts['agent-create']).toBe(1); // AgentExecutor detected as agent!
+            expect(typeCounts['generation-create']).toBe(2); // Two LLM calls
+            expect(typeCounts['generation-update']).toBe(2); // Two LLM ends
+            expect(typeCounts['retriever-create']).toBe(1); // One retriever
+            expect(typeCounts['tool-create']).toBe(1); // One tool
+            expect(typeCounts['span-update']).toBe(4); // retriever end + tool end + 2 chain ends
+            // Verify all events share the same traceId
+            const traceId = handler.getTraceId();
+            for (const event of client.events) {
+                const body = event.body;
+                if (body.traceId) {
+                    expect(body.traceId).toBe(traceId);
+                }
+            }
+            // Verify token usage in generation-update events
+            const genUpdates = client.getByType('generation-update');
+            // First LLM call usage
+            const firstLLMUpdate = genUpdates[0].body;
+            const firstUsage = firstLLMUpdate.usage;
+            expect(firstUsage.promptTokens).toBe(200);
+            expect(firstUsage.completionTokens).toBe(30);
+            expect(firstUsage.totalTokens).toBe(230);
+            expect(firstLLMUpdate.model).toBe('claude-sonnet-4-20250514');
+            expect(firstLLMUpdate.provider).toBe('anthropic');
+            // Second LLM call usage
+            const secondLLMUpdate = genUpdates[1].body;
+            const secondUsage = secondLLMUpdate.usage;
+            expect(secondUsage.promptTokens).toBe(800);
+            expect(secondUsage.completionTokens).toBe(150);
+            expect(secondUsage.totalTokens).toBe(950);
+            // Verify total token computation
+            const totalPrompt = 200 + 800;
+            const totalCompletion = 30 + 150;
+            const totalTokens = totalPrompt + totalCompletion;
+            expect(totalPrompt).toBe(1000);
+            expect(totalCompletion).toBe(180);
+            expect(totalTokens).toBe(1180);
+            // Total: 1180 tokens (1000 prompt + 180 completion) across 2 LLM calls
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 8. Token usage edge cases
+    // -----------------------------------------------------------------------
+    describe('token usage edge cases', () => {
+        it('should handle different token usage field names (prompt_tokens vs promptTokens)', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('ChatOpenAI'), ['test'], llmRunId, chainRunId);
+            // OpenAI style: uses prompt_tokens (snake_case)
+            await handler.handleLLMEnd({
+                generations: [[{ text: 'response', generationInfo: {} }]],
+                llmOutput: {
+                    tokenUsage: {
+                        prompt_tokens: 100,
+                        completion_tokens: 50,
+                        total_tokens: 150,
+                    },
+                },
+            }, llmRunId);
+            const updates = client.getByType('generation-update');
+            const usage = updates[0].body.usage;
+            // The handler should normalize both field naming conventions
+            expect(usage.promptTokens ?? usage.prompt_tokens).toBeTruthy();
+        });
+        it('should handle missing token usage gracefully', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('ChatOpenAI'), ['test'], llmRunId, chainRunId);
+            // No llmOutput at all
+            await handler.handleLLMEnd({ generations: [[{ text: 'response', generationInfo: {} }]] }, llmRunId);
+            const updates = client.getByType('generation-update');
+            expect(updates).toHaveLength(1);
+            // Should not crash, usage should be present but with undefined values
+            const usage = updates[0].body.usage;
+            expect(usage).toBeDefined();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 9. Flush and shutdown
+    // -----------------------------------------------------------------------
+    describe('flush and shutdown', () => {
+        it('flushAsync should call client.flush()', async () => {
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, makeUUID());
+            await handler.flushAsync();
+            expect(client.flushed).toBe(true);
+        });
+        it('shutdown should call client.flush() (not shutdown) for external client', async () => {
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, makeUUID());
+            await handler.shutdown();
+            // Since we provided an external client, it should only flush, not shutdown
+            expect(client.flushed).toBe(true);
+            expect(client.shutdownCalled).toBe(false);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 10. Agent detection
+    // -----------------------------------------------------------------------
+    describe('agent detection', () => {
+        it('should emit agent-create for chains with langgraph_node agent= metadata', async () => {
+            const outerChainId = makeUUID();
+            const agentChainId = makeUUID();
+            await handler.handleChainStart(serialized('CompiledStateGraph'), { messages: [{ role: 'user', content: 'Hello' }] }, outerChainId);
+            // Agent chain with langgraph_node metadata
+            // Cast to any to pass tags/metadata params (ts-jest resolves different .d.ts for BaseCallbackHandler)
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'agent task' }, agentChainId, outerChainId, undefined, // tags
+            { langgraph_node: 'agent=research-agent' });
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(1);
+            const agentBody = agentEvents[0].body;
+            expect(agentBody.name).toBe('Agent: research-agent');
+            expect(agentBody.traceId).toBe(handler.getTraceId());
+            const meta = agentBody.metadata;
+            expect(meta.agentId).toBe('research-agent');
+            expect(meta.langchainMetadata).toEqual({ langgraph_node: 'agent=research-agent' });
+        });
+        it('should emit agent-create for AgentExecutor chain name', async () => {
+            const agentRunId = makeUUID();
+            await handler.handleChainStart(serialized('AgentExecutor'), { input: 'do something' }, agentRunId);
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(1);
+            expect(agentEvents[0].body.name).toBe('AgentExecutor');
+            // Should NOT produce a chain-create
+            const chainEvents = client.getByType('chain-create');
+            expect(chainEvents).toHaveLength(0);
+        });
+        it('should emit agent-create for chain names ending in Agent', async () => {
+            const agentRunId = makeUUID();
+            await handler.handleChainStart(serialized('ReactAgent'), { input: 'think and act' }, agentRunId);
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(1);
+            expect(agentEvents[0].body.name).toBe('ReactAgent');
+        });
+        it('should NOT emit agent-create for regular chains', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'regular chain' }, chainRunId);
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(0);
+            const chainEvents = client.getByType('chain-create');
+            expect(chainEvents).toHaveLength(1);
+        });
+        it('should correctly end agent observations with span-update', async () => {
+            const agentRunId = makeUUID();
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'agent task' }, agentRunId, undefined, // parentRunId
+            undefined, // tags
+            { langgraph_node: 'agent=planner' });
+            await handler.handleChainEnd({ output: 'agent completed' }, agentRunId);
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(1);
+            const spanUpdates = client.getByType('span-update');
+            expect(spanUpdates).toHaveLength(1);
+            const update = spanUpdates[0].body;
+            expect(update.output).toEqual({ output: 'agent completed' });
+            expect(update.endTime).toBeDefined();
+            // The span-update should reference the same observation ID as agent-create
+            expect(update.id).toBe(agentEvents[0].body.id);
+        });
+        it('should handle agent error with ERROR level', async () => {
+            const agentRunId = makeUUID();
+            await handler.handleChainStart(serialized('AgentExecutor'), { input: 'fail task' }, agentRunId);
+            await handler.handleChainError(new Error('Agent failed: tool not found'), agentRunId);
+            const agentEvents = client.getByType('agent-create');
+            expect(agentEvents).toHaveLength(1);
+            const spanUpdates = client.getByType('span-update');
+            const errorUpdate = spanUpdates.find((e) => e.body.level === 'ERROR');
+            expect(errorUpdate).toBeDefined();
+            expect(errorUpdate.body.statusMessage).toBe('Agent failed: tool not found');
+        });
+        it('should integrate agent-create in full pipeline with correct counts', async () => {
+            const rootChainId = makeUUID();
+            const agentChainId = makeUUID();
+            const llmRunId = makeUUID();
+            // Root chain
+            await handler.handleChainStart(serialized('CompiledStateGraph'), { messages: [{ role: 'user', content: 'Hello' }] }, rootChainId);
+            // Agent chain (detected via metadata)
+            await handler.handleChainStart(serialized('RunnableSequence'), { input: 'agent work' }, agentChainId, rootChainId, undefined, // tags
+            { langgraph_node: 'agent=qa-agent' });
+            // LLM inside agent
+            await handler.handleLLMStart(serialized('ChatAnthropic'), ['prompt'], llmRunId, agentChainId, undefined, undefined, { ls_model_name: 'claude-sonnet-4-20250514', ls_provider: 'anthropic' });
+            await handler.handleLLMEnd({
+                generations: [[{ text: 'answer', generationInfo: {} }]],
+                llmOutput: {
+                    tokenUsage: { promptTokens: 100, completionTokens: 20, totalTokens: 120 },
+                    modelName: 'claude-sonnet-4-20250514',
+                },
+            }, llmRunId);
+            await handler.handleChainEnd({ output: 'done' }, agentChainId);
+            await handler.handleChainEnd({ output: 'done' }, rootChainId);
+            const typeCounts = client.getEventTypes().reduce((acc, t) => { acc[t] = (acc[t] || 0) + 1; return acc; }, {});
+            expect(typeCounts['trace-create']).toBe(1);
+            expect(typeCounts['chain-create']).toBe(1); // Only root chain
+            expect(typeCounts['agent-create']).toBe(1); // Agent detected!
+            expect(typeCounts['generation-create']).toBe(1);
+            expect(typeCounts['generation-update']).toBe(1);
+            expect(typeCounts['span-update']).toBe(2); // agent end + root chain end
+            // LLM parent should be the agent observation
+            const agentObsId = client.getByType('agent-create')[0].body.id;
+            const genCreate = client.getByType('generation-create')[0].body;
+            expect(genCreate.parentObservationId).toBe(agentObsId);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 11. Event structure validation
+    // -----------------------------------------------------------------------
+    describe('event structure validation', () => {
+        it('every event should have id, type, timestamp, and body', async () => {
+            const chainRunId = makeUUID();
+            const llmRunId = makeUUID();
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, chainRunId);
+            await handler.handleLLMStart(serialized('LLM'), ['test'], llmRunId, chainRunId);
+            await handler.handleLLMEnd({ generations: [[{ text: 'ok', generationInfo: {} }]], llmOutput: { tokenUsage: {} } }, llmRunId);
+            await handler.handleChainEnd({ output: 'done' }, chainRunId);
+            for (const event of client.events) {
+                expect(event.id).toBeDefined();
+                expect(typeof event.id).toBe('string');
+                expect(event.type).toBeDefined();
+                expect(event.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+                expect(event.body).toBeDefined();
+                expect(typeof event.body).toBe('object');
+            }
+        });
+        it('observation events should have traceId and observationId', async () => {
+            const chainRunId = makeUUID();
+            await handler.handleChainStart(serialized('Chain'), { input: 'test' }, chainRunId);
+            await handler.handleChainEnd({ output: 'done' }, chainRunId);
+            const nonTraceEvents = client.events.filter((e) => e.type !== 'trace-create');
+            for (const event of nonTraceEvents) {
+                const body = event.body;
+                expect(body.traceId).toBe(handler.getTraceId());
+                expect(body.id).toBeDefined();
+            }
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// IllumaSpanProcessor unit tests (OTel integration)
+// ---------------------------------------------------------------------------
+describe('IllumaSpanProcessor integration', () => {
+    it('should be importable from @illuma-ai/observability-otel', async () => {
+        const { IllumaSpanProcessor } = await import('@illuma-ai/observability-otel');
+        expect(IllumaSpanProcessor).toBeDefined();
+        expect(typeof IllumaSpanProcessor).toBe('function');
+    });
+});
+// ---------------------------------------------------------------------------
+// Core SDK features: sampling, PII masking, observation types, prompt/dataset
+// ---------------------------------------------------------------------------
+describe('Core SDK features', () => {
+    // Use require to bypass ts-jest module resolution issues with dynamic imports
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { ObservabilityCoreClient, TraceClient, SpanClient, IngestionEventType, } = require('@illuma-ai/observability-core');
+    // Create a concrete subclass at runtime to avoid TS abstract class issues
+    const TestClientClass = class extends ObservabilityCoreClient {
+        async fetchWithRetry() {
+            return { status: 200, statusText: 'OK', ok: true, json: async () => ({}), text: async () => '' };
+        }
+    };
+    function createTestClient(config = {}) {
+        const events = [];
+        const client = new TestClientClass({
+            publicKey: 'pk-test',
+            secretKey: 'sk-test',
+            baseUrl: 'http://localhost:9999',
+            flushInterval: 0,
+            ...config,
+        });
+        // Intercept enqueue to capture events
+        const origEnqueue = client.enqueue.bind(client);
+        client.enqueue = (event) => {
+            origEnqueue(event);
+            events.push(event);
+        };
+        return { client, events };
+    }
+    // -----------------------------------------------------------------------
+    // 12. Sampling rate
+    // -----------------------------------------------------------------------
+    describe('sampling rate', () => {
+        it('should trace everything when sampleRate=1.0 (default)', () => {
+            const { client, events } = createTestClient({ sampleRate: 1.0 });
+            for (let i = 0; i < 20; i++) {
+                client.trace({ name: `trace-${i}` });
+            }
+            // All 20 traces should be created (each produces a trace-create event queued)
+            const traceEvents = events.filter((e) => e.type === 'trace-create');
+            expect(traceEvents.length).toBe(20);
+        });
+        it('should trace nothing when sampleRate=0.0', () => {
+            const { client, events } = createTestClient({ sampleRate: 0.0 });
+            for (let i = 0; i < 20; i++) {
+                const trace = client.trace({ name: `trace-${i}` });
+                // Even child events should be silently dropped
+                trace.generation({ name: 'gen', model: 'gpt-4o' });
+                trace.span({ name: 'span' });
+            }
+            // No events should be enqueued at all
+            expect(events.length).toBe(0);
+        });
+        it('should sample approximately the right percentage', () => {
+            // Use a fixed seed approach: run many traces with 50% sample rate
+            const { client, events } = createTestClient({ sampleRate: 0.5 });
+            const iterations = 1000;
+            for (let i = 0; i < iterations; i++) {
+                client.trace({ name: `trace-${i}` });
+            }
+            const traceEvents = events.filter((e) => e.type === 'trace-create');
+            // With 1000 iterations at 50%, expect roughly 400-600 traces
+            expect(traceEvents.length).toBeGreaterThan(300);
+            expect(traceEvents.length).toBeLessThan(700);
+        });
+        it('should include all children once a trace is sampled in', () => {
+            const { client, events } = createTestClient({ sampleRate: 1.0 });
+            const trace = client.trace({ name: 'sampled-trace' });
+            trace.span({ name: 'child-span' });
+            trace.generation({ name: 'child-gen', model: 'gpt-4o' });
+            trace.agent({ name: 'child-agent' });
+            trace.tool({ name: 'child-tool' });
+            // 1 trace + 4 children = 5 events
+            expect(events.length).toBe(5);
+        });
+        it('should clamp sampleRate to [0, 1] range', () => {
+            // sampleRate > 1 should be clamped to 1 (trace everything)
+            const { events: events1 } = createTestClient({ sampleRate: 5.0 });
+            // sampleRate < 0 should be clamped to 0 (trace nothing)
+            const { client: client2, events: events2 } = createTestClient({ sampleRate: -1 });
+            client2.trace({ name: 'should-not-appear' });
+            expect(events2.length).toBe(0);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 13. PII masking
+    // -----------------------------------------------------------------------
+    describe('PII masking', () => {
+        it('should apply mask function to event bodies', () => {
+            const maskFunction = (body) => {
+                const masked = { ...body };
+                if (typeof masked.input === 'string') {
+                    masked.input = masked.input.replace(/[\w.-]+@[\w.-]+\.\w+/g, '[EMAIL]');
+                }
+                return masked;
+            };
+            const { client } = createTestClient({ maskFunction });
+            const trace = client.trace({ name: 'pii-test' });
+            trace.span({
+                name: 'user-query',
+                input: 'My email is john@example.com and I need help',
+            });
+            // Check the queued events - the span should have masked input
+            const queue = client.getQueue();
+            const spanEvent = [...queue].find((e) => e.type === 'span-create');
+            if (spanEvent) {
+                expect(spanEvent.body.input).toBe('My email is [EMAIL] and I need help');
+                expect(spanEvent.body.input).not.toContain('john@example.com');
+            }
+        });
+        it('should mask multiple PII patterns', () => {
+            const maskFunction = (body) => {
+                const masked = { ...body };
+                const str = JSON.stringify(masked);
+                const redacted = str
+                    .replace(/[\w.-]+@[\w.-]+\.\w+/g, '[EMAIL]')
+                    .replace(/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g, '[PHONE]')
+                    .replace(/\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g, '[CARD]');
+                return JSON.parse(redacted);
+            };
+            const { client } = createTestClient({ maskFunction });
+            const trace = client.trace({
+                name: 'multi-pii',
+                metadata: { userEmail: 'test@corp.com', phone: '555-123-4567' },
+            });
+            const queue = client.getQueue();
+            const traceEvent = [...queue].find((e) => e.type === 'trace-create');
+            if (traceEvent) {
+                const meta = traceEvent.body.metadata;
+                expect(meta.userEmail).toBe('[EMAIL]');
+                expect(meta.phone).toBe('[PHONE]');
+            }
+        });
+        it('should gracefully handle mask function errors', () => {
+            const maskFunction = () => {
+                throw new Error('Mask function exploded');
+            };
+            const { client } = createTestClient({ maskFunction });
+            // Should not throw — falls back to unmasked
+            expect(() => {
+                client.trace({ name: 'should-not-crash' });
+            }).not.toThrow();
+            const queue = client.getQueue();
+            expect(queue.length).toBeGreaterThan(0);
+        });
+        it('should not modify events when no mask function is set', () => {
+            const { client } = createTestClient();
+            client.trace({
+                name: 'no-mask',
+                metadata: { email: 'visible@example.com' },
+            });
+            const queue = client.getQueue();
+            const traceEvent = [...queue].find((e) => e.type === 'trace-create');
+            expect(traceEvent.body.metadata.email).toBe('visible@example.com');
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 14. All observation types (TraceClient + SpanClient)
+    // -----------------------------------------------------------------------
+    describe('observation types completeness', () => {
+        it('TraceClient should have all observation type methods', () => {
+            const enqueue = jest.fn();
+            const trace = new TraceClient('trace-123', enqueue);
+            // All typed observation methods should exist and return SpanClient or GenerationClient
+            expect(typeof trace.span).toBe('function');
+            expect(typeof trace.agent).toBe('function');
+            expect(typeof trace.tool).toBe('function');
+            expect(typeof trace.chain).toBe('function');
+            expect(typeof trace.retriever).toBe('function');
+            expect(typeof trace.guardrail).toBe('function');
+            expect(typeof trace.evaluator).toBe('function');
+            expect(typeof trace.embedding).toBe('function');
+            expect(typeof trace.generation).toBe('function');
+            expect(typeof trace.event).toBe('function');
+            expect(typeof trace.score).toBe('function');
+        });
+        it('SpanClient should have all observation type methods', () => {
+            const enqueue = jest.fn();
+            const span = new SpanClient('span-123', 'trace-123', enqueue);
+            expect(typeof span.span).toBe('function');
+            expect(typeof span.agent).toBe('function');
+            expect(typeof span.tool).toBe('function');
+            expect(typeof span.chain).toBe('function');
+            expect(typeof span.retriever).toBe('function');
+            expect(typeof span.guardrail).toBe('function');
+            expect(typeof span.evaluator).toBe('function');
+            expect(typeof span.embedding).toBe('function');
+            expect(typeof span.generation).toBe('function');
+            expect(typeof span.event).toBe('function');
+            expect(typeof span.score).toBe('function');
+        });
+        it('should emit correct event types for each observation method on TraceClient', () => {
+            const events = [];
+            const enqueue = (event) => events.push(event);
+            const trace = new TraceClient('trace-456', enqueue);
+            trace.span({ name: 'span' });
+            trace.agent({ name: 'agent' });
+            trace.tool({ name: 'tool' });
+            trace.chain({ name: 'chain' });
+            trace.retriever({ name: 'retriever' });
+            trace.guardrail({ name: 'guardrail' });
+            trace.evaluator({ name: 'evaluator' });
+            trace.embedding({ name: 'embedding' });
+            trace.generation({ name: 'generation' });
+            trace.event({ name: 'event' });
+            const types = events.map((e) => e.type);
+            expect(types).toContain('span-create');
+            expect(types).toContain('agent-create');
+            expect(types).toContain('tool-create');
+            expect(types).toContain('chain-create');
+            expect(types).toContain('retriever-create');
+            expect(types).toContain('guardrail-create');
+            expect(types).toContain('evaluator-create');
+            expect(types).toContain('embedding-create');
+            expect(types).toContain('generation-create');
+            expect(types).toContain('event-create');
+        });
+        it('should emit correct event types for each observation method on SpanClient', () => {
+            const events = [];
+            const enqueue = (event) => events.push(event);
+            const span = new SpanClient('span-789', 'trace-789', enqueue);
+            span.span({ name: 'child-span' });
+            span.agent({ name: 'child-agent' });
+            span.tool({ name: 'child-tool' });
+            span.chain({ name: 'child-chain' });
+            span.retriever({ name: 'child-retriever' });
+            span.guardrail({ name: 'child-guardrail' });
+            span.evaluator({ name: 'child-evaluator' });
+            span.embedding({ name: 'child-embedding' });
+            span.generation({ name: 'child-generation' });
+            span.event({ name: 'child-event' });
+            const types = events.map((e) => e.type);
+            expect(types).toContain('span-create');
+            expect(types).toContain('agent-create');
+            expect(types).toContain('tool-create');
+            expect(types).toContain('chain-create');
+            expect(types).toContain('retriever-create');
+            expect(types).toContain('guardrail-create');
+            expect(types).toContain('evaluator-create');
+            expect(types).toContain('embedding-create');
+            expect(types).toContain('generation-create');
+            expect(types).toContain('event-create');
+        });
+        it('SpanClient children should set parentObservationId automatically', () => {
+            const events = [];
+            const enqueue = (event) => events.push(event);
+            const span = new SpanClient('parent-span', 'trace-abc', enqueue);
+            span.guardrail({ name: 'guardrail-check' });
+            span.evaluator({ name: 'eval-run' });
+            span.embedding({ name: 'embed-op' });
+            for (const event of events) {
+                expect(event.body.parentObservationId).toBe('parent-span');
+                expect(event.body.traceId).toBe('trace-abc');
+            }
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 15. Prompt & Dataset SDK methods
+    // -----------------------------------------------------------------------
+    describe('prompt and dataset SDK methods', () => {
+        it('core client should expose getPrompt method', () => {
+            const { client } = createTestClient();
+            expect(typeof client.getPrompt).toBe('function');
+        });
+        it('core client should expose createPrompt method', () => {
+            const { client } = createTestClient();
+            expect(typeof client.createPrompt).toBe('function');
+        });
+        it('core client should expose getDataset method', () => {
+            const { client } = createTestClient();
+            expect(typeof client.getDataset).toBe('function');
+        });
+        it('core client should expose createDataset method', () => {
+            const { client } = createTestClient();
+            expect(typeof client.createDataset).toBe('function');
+        });
+        it('core client should expose createDatasetItem method', () => {
+            const { client } = createTestClient();
+            expect(typeof client.createDatasetItem).toBe('function');
+        });
+        it('getPrompt should return parsed response from server', async () => {
+            const { client } = createTestClient();
+            // Mock fetchWithRetry returns { ok: true, json: async () => ({}) }
+            const result = await client.getPrompt({ name: 'my-prompt' });
+            expect(result).toBeDefined();
+            expect(result).toEqual({});
+        });
+        it('getDataset should return parsed response from server', async () => {
+            const { client } = createTestClient();
+            const result = await client.getDataset({ name: 'my-dataset' });
+            expect(result).toBeDefined();
+            expect(result).toEqual({});
+        });
+        it('prompt/dataset methods should return null when disabled', async () => {
+            const { client } = createTestClient({ enabled: false });
+            expect(await client.getPrompt({ name: 'test' })).toBeNull();
+            expect(await client.createPrompt({ name: 'test', prompt: 'hello' })).toBeNull();
+            expect(await client.getDataset({ name: 'test' })).toBeNull();
+            expect(await client.createDataset({ name: 'test' })).toBeNull();
+            expect(await client.createDatasetItem({ datasetName: 'test', input: 'x' })).toBeNull();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // 16. Node SDK: sampling + PII masking propagation
+    // -----------------------------------------------------------------------
+    describe('node SDK config propagation', () => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Observability } = require('@illuma-ai/observability-node');
+        it('Observability class should accept sampleRate option', async () => {
+            expect(Observability).toBeDefined();
+            const obs = new Observability({
+                publicKey: 'pk-test',
+                secretKey: 'sk-test',
+                baseUrl: 'http://localhost:9999',
+                sampleRate: 0.5,
+                flushInterval: 0,
+            });
+            expect(obs).toBeDefined();
+            await obs.shutdown();
+        });
+        it('Observability class should accept maskFunction option', async () => {
+            const obs = new Observability({
+                publicKey: 'pk-test',
+                secretKey: 'sk-test',
+                baseUrl: 'http://localhost:9999',
+                maskFunction: (body) => ({ ...body, input: '[REDACTED]' }),
+                flushInterval: 0,
+            });
+            expect(obs).toBeDefined();
+            await obs.shutdown();
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// 17. Guardrail tracing via ObservabilityCallbackHandler
+// ---------------------------------------------------------------------------
+/** Re-use MockObservabilityClient shape for guardrail tests (same file, top-level scope) */
+class GuardrailMockClient {
+    events = [];
+    flushed = false;
+    shutdownCalled = false;
+    enqueue(event) { this.events.push(event); }
+    async flush() { this.flushed = true; }
+    async shutdown() { this.shutdownCalled = true; }
+    getByType(type) { return this.events.filter((e) => e.type === type); }
+    getEventTypes() { return this.events.map((e) => e.type); }
+    printEvents() {
+        for (const event of this.events) {
+            const body = event.body;
+            const usage = body.usage;
+            console.log(`  ${event.type} | name=${body.name ?? '—'} | id=${body.id ?? '—'} | traceId=${body.traceId ?? '—'} | parentObsId=${body.parentObservationId ?? '—'}` +
+                (usage ? ` | usage={prompt:${usage.promptTokens ?? '—'},completion:${usage.completionTokens ?? '—'},total:${usage.totalTokens ?? '—'}}` : '') +
+                (body.model ? ` | model=${body.model}` : '') +
+                (body.level === 'ERROR' || body.level === 'WARNING' ? ` | ${body.level}: ${body.statusMessage}` : ''));
+        }
+    }
+}
+const grSerialized = (name) => ({
+    lc: 1,
+    type: 'not_implemented',
+    id: ['langchain', name],
+});
+describe('Guardrail tracing', () => {
+    let grClient;
+    let grHandler; // Use any to bypass ts-jest type resolution for traceGuardrail
+    beforeEach(() => {
+        grClient = new GuardrailMockClient();
+        grHandler = new ObservabilityCallbackHandler({
+            client: grClient,
+        });
+    });
+    it('outcome=passed should create guardrail-create + span-update with DEFAULT level', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'hello' }, chainRunId);
+        const result = grHandler.traceGuardrail({
+            name: 'Output Moderation',
+            guardrailId: 'bedrock-guardrail-123',
+            guardrailVersion: '1',
+            outcome: 'passed',
+            actionApplied: false,
+            action: 'NONE',
+            reason: 'passed',
+            source: 'OUTPUT',
+            input: 'What is the weather?',
+            output: 'The weather is sunny.',
+            violations: [],
+            assessments: [{ contentPolicy: { filters: [] } }],
+        });
+        expect(result).not.toBeNull();
+        const guardrailEvents = grClient.getByType('guardrail-create');
+        expect(guardrailEvents).toHaveLength(1);
+        const grBody = guardrailEvents[0].body;
+        expect(grBody.name).toBe('Output Moderation');
+        expect(grBody.input).toBe('What is the weather?');
+        expect(grBody.metadata.guardrailId).toBe('bedrock-guardrail-123');
+        expect(grBody.metadata.outcome).toBe('passed');
+        expect(grBody.metadata.source).toBe('OUTPUT');
+        // span-update should show PASSED
+        const spanUpdates = grClient.getByType('span-update');
+        const guardrailUpdate = spanUpdates.find((e) => e.body.id === result);
+        expect(guardrailUpdate).toBeDefined();
+        expect(guardrailUpdate.body.output).toBe('The weather is sunny.');
+        expect(guardrailUpdate.body.level).toBe('DEFAULT');
+        expect(guardrailUpdate.body.statusMessage).toBe('PASSED');
+    });
+    it('outcome=blocked should mark with ERROR level when enforced', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'test' }, chainRunId);
+        grHandler.traceGuardrail({
+            name: 'Input Moderation',
+            guardrailId: 'bedrock-guardrail-456',
+            outcome: 'blocked',
+            actionApplied: true,
+            action: 'GUARDRAIL_INTERVENED',
+            reason: 'policy_violation',
+            source: 'INPUT',
+            input: 'How to hack a system?',
+            output: 'Sorry, I cannot help with that.',
+            violations: [{ type: 'CONTENT_POLICY', category: 'VIOLENCE', action: 'BLOCKED' }],
+        });
+        const spanUpdates = grClient.getByType('span-update');
+        const guardrailUpdate = spanUpdates[spanUpdates.length - 1];
+        expect(guardrailUpdate.body.level).toBe('ERROR');
+        expect(guardrailUpdate.body.statusMessage).toBe('BLOCKED: policy_violation');
+        expect(guardrailUpdate.body.metadata.outcome).toBe('blocked');
+        expect(guardrailUpdate.body.metadata.actionApplied).toBe(true);
+        expect(guardrailUpdate.body.metadata.violations).toHaveLength(1);
+    });
+    it('outcome=blocked with actionApplied=false should note "not enforced"', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'test' }, chainRunId);
+        grHandler.traceGuardrail({
+            name: 'Input Moderation',
+            outcome: 'blocked',
+            actionApplied: false,
+            reason: 'policy_violation',
+            source: 'INPUT',
+            input: 'Some flagged content',
+        });
+        const spanUpdates = grClient.getByType('span-update');
+        const guardrailUpdate = spanUpdates[spanUpdates.length - 1];
+        expect(guardrailUpdate.body.level).toBe('ERROR');
+        expect(guardrailUpdate.body.statusMessage).toContain('not enforced');
+        expect(guardrailUpdate.body.metadata.actionApplied).toBe(false);
+    });
+    it('outcome=anonymized should mark with WARNING and include modified content', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'test' }, chainRunId);
+        grHandler.traceGuardrail({
+            name: 'Output Moderation',
+            outcome: 'anonymized',
+            actionApplied: true,
+            action: 'GUARDRAIL_INTERVENED',
+            reason: 'anonymized',
+            source: 'OUTPUT',
+            input: 'My email is john@example.com and SSN is 123-45-6789',
+            originalContent: 'My email is john@example.com and SSN is 123-45-6789',
+            modifiedContent: 'My email is [EMAIL] and SSN is [SSN]',
+            violations: [
+                { type: 'PII_POLICY', category: 'EMAIL', action: 'ANONYMIZED' },
+                { type: 'PII_POLICY', category: 'SSN', action: 'ANONYMIZED' },
+            ],
+        });
+        const spanUpdates = grClient.getByType('span-update');
+        const guardrailUpdate = spanUpdates[spanUpdates.length - 1];
+        expect(guardrailUpdate.body.level).toBe('WARNING');
+        expect(guardrailUpdate.body.statusMessage).toBe('ANONYMIZED: PII detected and masked');
+        // output should be the modified content
+        expect(guardrailUpdate.body.output).toBe('My email is [EMAIL] and SSN is [SSN]');
+        const meta = guardrailUpdate.body.metadata;
+        expect(meta.originalContent).toBe('My email is john@example.com and SSN is 123-45-6789');
+        expect(meta.modifiedContent).toBe('My email is [EMAIL] and SSN is [SSN]');
+        expect(meta.violations).toHaveLength(2);
+    });
+    it('outcome=intervened should mark with WARNING level', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'test' }, chainRunId);
+        grHandler.traceGuardrail({
+            name: 'Output Moderation',
+            outcome: 'intervened',
+            actionApplied: true,
+            action: 'GUARDRAIL_INTERVENED',
+            reason: 'intervened_passthrough',
+            source: 'OUTPUT',
+            input: 'Original response text',
+            modifiedContent: 'Modified response text',
+        });
+        const spanUpdates = grClient.getByType('span-update');
+        const guardrailUpdate = spanUpdates[spanUpdates.length - 1];
+        expect(guardrailUpdate.body.level).toBe('WARNING');
+        expect(guardrailUpdate.body.statusMessage).toBe('INTERVENED: intervened_passthrough');
+    });
+    it('traceGuardrail() should return null when no trace exists', () => {
+        const freshClient = new GuardrailMockClient();
+        const freshHandler = new ObservabilityCallbackHandler({
+            client: freshClient,
+        });
+        const result = freshHandler.traceGuardrail({
+            name: 'Pre-trace Guardrail',
+            outcome: 'passed',
+            actionApplied: false,
+            source: 'INPUT',
+        });
+        expect(result).toBeNull();
+        expect(freshClient.getByType('guardrail-create')).toHaveLength(0);
+    });
+    it('traceGuardrail() should use custom startTime and endTime', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('Chain'), { input: 'test' }, chainRunId);
+        const startTime = '2024-01-01T00:00:00.000Z';
+        const endTime = '2024-01-01T00:00:01.500Z';
+        grHandler.traceGuardrail({
+            name: 'Timed Guardrail',
+            outcome: 'passed',
+            actionApplied: false,
+            source: 'OUTPUT',
+            startTime,
+            endTime,
+        });
+        const guardrailEvents = grClient.getByType('guardrail-create');
+        expect(guardrailEvents[0].body.startTime).toBe(startTime);
+        const spanUpdates = grClient.getByType('span-update');
+        const lastUpdate = spanUpdates[spanUpdates.length - 1];
+        expect(lastUpdate.body.endTime).toBe(endTime);
+    });
+    it('should trace both input and output guardrails on the same trace', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('RunnableSequence'), { input: 'test' }, chainRunId);
+        const inputId = grHandler.traceGuardrail({
+            name: 'Input Moderation',
+            outcome: 'passed',
+            actionApplied: false,
+            source: 'INPUT',
+            input: 'What is 2+2?',
+        });
+        const outputId = grHandler.traceGuardrail({
+            name: 'Output Moderation',
+            outcome: 'passed',
+            actionApplied: false,
+            source: 'OUTPUT',
+            input: 'The answer is 4.',
+        });
+        expect(inputId).not.toBeNull();
+        expect(outputId).not.toBeNull();
+        expect(inputId).not.toBe(outputId);
+        const guardrailEvents = grClient.getByType('guardrail-create');
+        expect(guardrailEvents).toHaveLength(2);
+        const traceId = guardrailEvents[0].body.traceId;
+        expect(guardrailEvents[1].body.traceId).toBe(traceId);
+        expect(guardrailEvents[0].body.metadata.source).toBe('INPUT');
+        expect(guardrailEvents[1].body.metadata.source).toBe('OUTPUT');
+    });
+    it('should include full AWS Bedrock assessments and violations in metadata', async () => {
+        const chainRunId = makeUUID();
+        await grHandler.handleChainStart(grSerialized('Chain'), { input: 'test' }, chainRunId);
+        grHandler.traceGuardrail({
+            name: 'Detailed Guardrail',
+            outcome: 'blocked',
+            actionApplied: true,
+            action: 'GUARDRAIL_INTERVENED',
+            reason: 'policy_violation',
+            source: 'INPUT',
+            violations: [
+                { type: 'CONTENT_POLICY', category: 'VIOLENCE', confidence: 'HIGH', action: 'BLOCKED' },
+                { type: 'PII_POLICY', category: 'SSN', action: 'BLOCKED' },
+            ],
+            assessments: [
+                {
+                    contentPolicy: { filters: [{ type: 'VIOLENCE', confidence: 'HIGH', action: 'BLOCKED' }] },
+                    sensitiveInformationPolicy: { piiEntities: [{ type: 'SSN', action: 'BLOCKED' }] },
+                },
+            ],
+        });
+        const spanUpdates = grClient.getByType('span-update');
+        const lastUpdate = spanUpdates[spanUpdates.length - 1];
+        const meta = lastUpdate.body.metadata;
+        expect(meta.violations).toHaveLength(2);
+        expect(meta.assessments).toHaveLength(1);
+        expect(meta.violations[0]).toEqual({
+            type: 'CONTENT_POLICY', category: 'VIOLENCE', confidence: 'HIGH', action: 'BLOCKED',
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// 18. Guardrail tracing with debug logging — full pipeline with all 4 outcomes
+// ---------------------------------------------------------------------------
+describe('Guardrail tracing with debug output', () => {
+    it('should produce debug-friendly trace output for manual verification', async () => {
+        const debugClient = new GuardrailMockClient();
+        const debugHandler = new ObservabilityCallbackHandler({
+            client: debugClient,
+            traceName: 'guardrail-debug-test',
+            userId: 'user-123',
+            sessionId: 'session-456',
+            debug: true,
+        });
+        // 1. Chain starts (creates trace)
+        const chainRunId = makeUUID();
+        await debugHandler.handleChainStart(grSerialized('RunnableSequence'), { messages: [{ role: 'user', content: 'Explain quantum computing' }] }, chainRunId);
+        // 2. LLM call
+        const llmRunId = makeUUID();
+        await debugHandler.handleLLMStart(grSerialized('ChatOpenAI'), ['Explain quantum computing'], llmRunId, chainRunId);
+        const llmResult = {
+            generations: [[{ text: 'Quantum computing uses qubits...', generationInfo: {} }]],
+            llmOutput: {
+                tokenUsage: { promptTokens: 10, completionTokens: 25, totalTokens: 35 },
+                modelName: 'gpt-4o',
+            },
+        };
+        await debugHandler.handleLLMEnd(llmResult, llmRunId);
+        await debugHandler.handleChainEnd({ output: 'Quantum computing uses qubits...' }, chainRunId);
+        // 3. Input guardrail — passed
+        const inputGuardrailId = debugHandler.traceGuardrail({
+            name: 'Input Moderation (Bedrock)',
+            guardrailId: 'arn:aws:bedrock:us-east-1:123456:guardrail/abc123',
+            guardrailVersion: '3',
+            outcome: 'passed',
+            actionApplied: false,
+            action: 'NONE',
+            reason: 'passed',
+            source: 'INPUT',
+            input: 'Explain quantum computing',
+            startTime: '2024-06-15T10:00:00.000Z',
+            endTime: '2024-06-15T10:00:00.150Z',
+        });
+        // 4. Output guardrail — passed
+        const outputGuardrailId = debugHandler.traceGuardrail({
+            name: 'Output Moderation (Bedrock)',
+            guardrailId: 'arn:aws:bedrock:us-east-1:123456:guardrail/abc123',
+            guardrailVersion: '3',
+            outcome: 'passed',
+            actionApplied: false,
+            action: 'NONE',
+            reason: 'passed',
+            source: 'OUTPUT',
+            input: 'Quantum computing uses qubits...',
+            violations: [],
+            assessments: [{ topicPolicy: { topics: [] }, contentPolicy: { filters: [] } }],
+            startTime: '2024-06-15T10:00:01.000Z',
+            endTime: '2024-06-15T10:00:01.200Z',
+        });
+        expect(inputGuardrailId).not.toBeNull();
+        expect(outputGuardrailId).not.toBeNull();
+        console.log('\n=== SAMPLE GUARDRAIL TRACE OUTPUT ===');
+        debugClient.printEvents();
+        console.log('=== END TRACE ===\n');
+        // Verify complete event sequence
+        const types = debugClient.getEventTypes();
+        expect(types).toEqual([
+            'trace-create',
+            'chain-create',
+            'generation-create',
+            'generation-update',
+            'span-update', // chain end
+            'guardrail-create', // input guardrail
+            'span-update', // input guardrail update
+            'guardrail-create', // output guardrail
+            'span-update', // output guardrail update
+        ]);
+        // Verify trace ID consistency
+        const traceId = debugClient.getByType('trace-create')[0].body.id;
+        for (const evt of debugClient.events) {
+            const body = evt.body;
+            if (evt.type !== 'trace-create') {
+                expect(body.traceId).toBe(traceId);
+            }
+        }
+    });
+    it('should trace all 4 guardrail outcomes with correct levels', async () => {
+        const debugClient = new GuardrailMockClient();
+        const handler = new ObservabilityCallbackHandler({
+            client: debugClient,
+            debug: true,
+        });
+        // Create trace
+        const chainRunId = makeUUID();
+        await handler.handleChainStart(grSerialized('Chain'), { input: 'test' }, chainRunId);
+        // All 4 outcomes
+        handler.traceGuardrail({ name: 'Passed', outcome: 'passed', actionApplied: false, source: 'INPUT' });
+        handler.traceGuardrail({ name: 'Blocked', outcome: 'blocked', actionApplied: true, reason: 'policy_violation', source: 'INPUT' });
+        handler.traceGuardrail({ name: 'Anonymized', outcome: 'anonymized', actionApplied: true, reason: 'anonymized', source: 'OUTPUT', modifiedContent: '[EMAIL]' });
+        handler.traceGuardrail({ name: 'Intervened', outcome: 'intervened', actionApplied: true, reason: 'intervened_passthrough', source: 'OUTPUT' });
+        console.log('\n=== ALL 4 GUARDRAIL OUTCOMES ===');
+        debugClient.printEvents();
+        console.log('=== END ===\n');
+        const guardrailEvents = debugClient.getByType('guardrail-create');
+        expect(guardrailEvents).toHaveLength(4);
+        const spanUpdates = debugClient.getByType('span-update');
+        // 4 guardrail updates (chain not ended in this test)
+        expect(spanUpdates).toHaveLength(4);
+        // Check levels: passed=DEFAULT, blocked=ERROR, anonymized=WARNING, intervened=WARNING
+        const guardrailUpdates = spanUpdates;
+        expect(guardrailUpdates[0].body.level).toBe('DEFAULT');
+        expect(guardrailUpdates[1].body.level).toBe('ERROR');
+        expect(guardrailUpdates[2].body.level).toBe('WARNING');
+        expect(guardrailUpdates[3].body.level).toBe('WARNING');
+    });
+});
+//# sourceMappingURL=observability.integration.test.js.map