langwatch 0.1.7 → 0.3.0-prerelease.1

package/src/observability/__tests__/trace.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getLangWatchTracer } from '../trace';
+import type { Tracer, Span, SpanOptions, Context } from '@opentelemetry/api';
+
+// Mock createLangWatchSpan to just tag the span for test visibility
+vi.mock('../span', () => ({
+  createLangWatchSpan: (span: Span) => ({
+    __isLangWatch: true,
+    ...span,
+    end: vi.fn(),
+    setStatus: vi.fn(),
+    recordException: vi.fn(),
+  }),
+}));
+
+// Helper to create a mock Tracer
+function makeMockTracer() {
+  return {
+    startSpan: vi.fn((name, options, context) => ({ name, options, context })),
+    startActiveSpan: vi.fn((...args: any[]) => {
+      // OpenTelemetry's startActiveSpan calls the callback with the span
+      const fn = args[args.length - 1];
+      const span = { name: args[0], options: args[1], context: args[2] };
+      return fn(span);
+    }),
+    someOtherMethod: vi.fn(() => 'other'),
+  } as unknown as Tracer;
+}
+
+describe('getTracer', () => {
+  const origGetTracer = vi.hoisted(() => vi.fn());
+  let otelTrace: { getTracer: typeof origGetTracer };
+
+  beforeEach(() => {
+    otelTrace = require('@opentelemetry/api').trace;
+    otelTrace.getTracer = vi.fn(() => makeMockTracer());
+  });
+
+  it('returns a proxy with startSpan wrapping the span', () => {
+    const tracer = getLangWatchTracer('test');
+    const span = tracer.startSpan('my-span', { foo: 'bar' } as SpanOptions, {} as Context);
+    expect(span).toMatchObject({ __isLangWatch: true, name: 'my-span', options: { foo: 'bar' } });
+  });
+
+  it('returns a proxy with startActiveSpan wrapping the span in the callback', () => {
+    const tracer = getLangWatchTracer('test');
+    const result = tracer.startActiveSpan('active-span', (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'active-span' });
+      return 'done';
+    });
+    expect(result).toBe('done');
+  });
+
+  it('supports startActiveSpan with options and context overloads', () => {
+    const tracer = getLangWatchTracer('test');
+    let called = 0;
+    tracer.startActiveSpan('span1', { foo: 1 } as SpanOptions, (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'span1', options: { foo: 1 } });
+      called++;
+    });
+    tracer.startActiveSpan('span2', { foo: 2 } as SpanOptions, {} as Context, (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'span2', options: { foo: 2 }, context: {} });
+      called++;
+    });
+    expect(called).toBe(2);
+  });
+
+  it('supports startActiveSpan with a callback that returns a Promise', async () => {
+    const tracer = getLangWatchTracer('test');
+    const result = await tracer.startActiveSpan('promise-span', async (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'promise-span' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return 'async-done';
+    });
+    expect(result).toBe('async-done');
+  });
+
+  it('supports startActiveSpan with a callback that returns a thenable (Promise-like)', async () => {
+    const tracer = getLangWatchTracer('test');
+    const thenable = {
+      then: (resolve: (v: string) => void) => setTimeout(() => resolve('thenable-done'), 10),
+    };
+    const result = await tracer.startActiveSpan('thenable-span', (_span: any) => thenable);
+    expect(result).toBe('thenable-done');
+  });
+
+  it('forwards unknown methods to the underlying tracer', () => {
+    const tracer = getLangWatchTracer('test');
+    // @ts-expect-error
+    expect(tracer.someOtherMethod()).toBe('other');
+  });
+
+  it('throws if startActiveSpan is called without a function', () => {
+    const tracer = getLangWatchTracer('test');
+    // @ts-expect-error
+    expect(() => tracer.startActiveSpan('no-fn')).toThrow(/function as the last argument/);
+  });
+});
+
+describe('getTracer (withActiveSpan)', () => {
+  let tracer: ReturnType<typeof getLangWatchTracer>;
+  beforeEach(() => {
+    tracer = getLangWatchTracer('test');
+  });
+
+  it('returns a proxy with withActiveSpan wrapping the span', async () => {
+    const result = await tracer.withActiveSpan('my-span', (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'my-span' });
+      return 'done';
+    });
+    expect(result).toBe('done');
+  });
+
+  it('supports withActiveSpan with options and context overloads', async () => {
+    let called = 0;
+    await tracer.withActiveSpan('span1', { foo: 1 } as SpanOptions, (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'span1', options: { foo: 1 } });
+      called++;
+    });
+    await tracer.withActiveSpan('span2', { foo: 2 } as SpanOptions, {} as Context, (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'span2', options: { foo: 2 }, context: {} });
+      called++;
+    });
+    expect(called).toBe(2);
+  });
+
+  it('supports withActiveSpan with a callback that returns a Promise', async () => {
+    const result = await tracer.withActiveSpan('promise-span', async (span: any) => {
+      expect(span).toMatchObject({ __isLangWatch: true, name: 'promise-span' });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return 'async-done';
+    });
+    expect(result).toBe('async-done');
+  });
+
+  it('supports withActiveSpan with a callback that returns a thenable (Promise-like)', async () => {
+    const thenable = {
+      then: (resolve: (v: string) => void) => setTimeout(() => resolve('thenable-done'), 10),
+    };
+    const result = await tracer.withActiveSpan('thenable-span', (_span: any) => thenable as any);
+    expect(result).toBe('thenable-done');
+  });
+
+  it('calls setStatus and recordException on error', async () => {
+    const error = new Error('fail!');
+    let spanRef: any = null;
+    const resultPromise = tracer.withActiveSpan('err-span', (span: any) => {
+      span.setStatus = vi.fn();
+      span.recordException = vi.fn();
+      spanRef = span;
+      throw error;
+    });
+    await expect(resultPromise).rejects.toThrow('fail!');
+    expect(spanRef.setStatus).toHaveBeenCalledWith({ code: expect.any(Number), message: 'fail!' });
+    expect(spanRef.recordException).toHaveBeenCalledWith(error);
+  });
+
+  it('throws if withActiveSpan is called without a function', async () => {
+    // @ts-expect-error
+    await expect(tracer.withActiveSpan('no-fn')).rejects.toThrow(/function as the last argument/);
+  });
+
+  it('ensures nested withActiveSpan calls propagate context (parent-child)', async () => {
+    const tracer = getLangWatchTracer('test');
+    let parentSpanRef: any = null;
+    let childSpanRef: any = null;
+    await tracer.withActiveSpan('parent-span', (parentSpan: any) => {
+      parentSpanRef = parentSpan;
+      return tracer.withActiveSpan('child-span', (childSpan: any) => {
+        childSpanRef = childSpan;
+        return 'nested';
+      });
+    });
+    // In the mock, context is just passed through, so we can check the parent/child linkage
+    expect(childSpanRef.context).toBe(parentSpanRef.context);
+    // Removed assertion on childSpanRef.options, as the mock does not reflect real OTel behavior
+    expect(childSpanRef.name).toBe('child-span');
+    expect(parentSpanRef.name).toBe('parent-span');
+  });
+});

package/src/observability/exporters/index.ts

@@ -0,0 +1 @@
+export * from "./langwatch-exporter";

package/src/observability/exporters/langwatch-exporter.ts

@@ -0,0 +1,53 @@
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { version } from "../../../package.json";
+import { getApiKey, getEndpoint } from "../../client";
+
+/**
+ * LangWatchExporter extends the OpenTelemetry OTLP HTTP trace exporter
+ * to send trace data to LangWatch with proper authentication and metadata headers.
+ *
+ * This exporter automatically configures:
+ * - Authorization headers using the provided API key or environment variables/fallback
+ * - SDK version and language identification headers
+ * - Proper endpoint configuration for LangWatch ingestion using provided URL or environment variables/fallback
+ *
+ * @example
+ * ```typescript
+ * import { LangWatchExporter } from '@langwatch/observability';
+ *
+ * // Using environment variables/fallback configuration
+ * const exporter = new LangWatchExporter();
+ *
+ * // Using custom API key and endpoint
+ *
+ * // With environment variables/fallback configuration
+ * const exporter = new LangWatchExporter();
+ *
+ * // With custom API key and endpoint
+ * const exporter = new LangWatchExporter('api-key', 'https://custom.langwatch.com');
+ * ```
+ */
+export class LangWatchExporter extends OTLPTraceExporter {
+    /**
+   * Creates a new LangWatchExporter instance.
+   *
+   * @param apiKey - Optional API key for LangWatch authentication. If not provided,
+   *                 will use environment variables or fallback configuration.
+   * @param endpointURL - Optional custom endpoint URL for LangWatch ingestion.
+   *                     If not provided, will use environment variables or fallback configuration.
+   */
+  constructor(apiKey?: string, endpointURL?: string) {
+    const setApiKey = apiKey ?? getApiKey();
+    const setEndpoint = endpointURL ?? getEndpoint();
+
+    super({
+      headers: {
+        "Authorization": `Bearer ${setApiKey}`,
+        "X-LangWatch-SDK-Version": version,
+        "X-LangWatch-SDK-Language": `typescript-${typeof process !== "undefined" ? "node" : "browser"}`,
+        "X-LangWatch-SDK-Name": "langwatch-observability-sdk",
+      },
+      url: setEndpoint,
+    });
+  }
+}

package/src/observability/index.ts

@@ -0,0 +1,4 @@
+export * from "./span";
+export * from "./trace";
+export * from "./processors";
+export * as semconv from "./semconv";

package/src/observability/instrumentation/langchain/__tests__/integration/langchain-chatbot.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { ChatOpenAI } from "@langchain/openai";
+import { LangWatchCallbackHandler } from "../../../langchain";
+import { setupLangWatch } from "../../../../../client-node";
+import { DynamicTool } from "@langchain/core/tools";
+import { AgentExecutor, createToolCallingAgent, initializeAgentExecutorWithOptions } from "langchain/agents";
+import { getLangWatchTracer } from "../../../../trace";
+import { ChatPromptTemplate } from "@langchain/core/prompts";
+import { beforeEach } from "node:test";
+
+beforeEach(async () => {
+  await setupLangWatch();
+});
+
+describe("langchain chatbots", () => {
+  it("it should be able to do a simple question/response", async () => {
+    const tracer = getLangWatchTracer("langchain-chatbot.test");
+    await tracer.withActiveSpan("simple question/response", { root: true }, async () => {
+      const llm = new ChatOpenAI({
+        model: "gpt-4o-mini",
+        temperature: 0,
+      });
+
+      const result = await llm.invoke([
+        { role: "user", content: "Hi im Bob" },
+      ], { callbacks: [new LangWatchCallbackHandler()] });
+      expect(result.content).toContain("Bob");
+    });
+  });
+
+  it("it should be able to handle tool calls", async () => {
+    const tools = [
+      new DynamicTool({
+        name: "get_current_time",
+        description: "Returns the current time in ISO-8601 format.",
+        func: async () => new Date().toISOString(),
+      }),
+
+      new DynamicTool({
+        name: "multiply",
+        description: 'Multiply two numbers, provide input like "a,b".',
+        func: async (input: string) => {
+          const [a, b] = input.split(",").map(Number);
+
+          if (a === void 0 || b === void 0) {
+            throw new Error("Invalid input");
+          }
+
+          return String(a * b);
+        },
+      }),
+    ];
+
+    const tracer = getLangWatchTracer("langchain-chatbot.test");
+    await tracer.withActiveSpan(
+      "langchain tool call",
+      { root: true },
+      async () => {
+        const llm = new ChatOpenAI({
+          model: "gpt-4.1-mini",
+          temperature: 0,
+        });
+
+        const prompt = ChatPromptTemplate.fromMessages([
+          ["system", "You are a helpful assistant"],
+          ["placeholder", "{chat_history}"],
+          ["human", "{input}"],
+          ["placeholder", "{agent_scratchpad}"],
+        ]);
+
+        const agent = createToolCallingAgent({
+          llm,
+          tools,
+          prompt,
+        });
+        const agentExecutor = new AgentExecutor({
+          agent,
+          tools,
+        });
+
+        const tracingCallback = new LangWatchCallbackHandler();
+        const result = await agentExecutor.invoke({ input: "What time is it and what is 12 times 8?" }, { callbacks: [tracingCallback] });
+        expect(result.output).toContain("96");
+      },
+    );
+  });
+
+  it("should understand context grouping", async () => {
+    const tracer = getLangWatchTracer("langchain-chatbot.test");
+    await tracer.withActiveSpan(
+      "context grouping",
+      { root: true },
+      async () => {
+        const llm = new ChatOpenAI({
+          model: "gpt-4o-mini",
+          temperature: 0,
+        });
+
+        const tracingCallback = new LangWatchCallbackHandler();
+        const result1 = await llm.invoke([
+          { role: "user", content: "Hi im Alice" },
+        ], { callbacks: [tracingCallback] });
+        const result2 = await llm.invoke([
+          { role: "user", content: "Hi im Bob" },
+        ], { callbacks: [tracingCallback] });
+
+        expect(result1.content).toContain("Alice");
+        expect(result2.content).toContain("Bob");
+      },
+    );
+  });
+});

package/src/observability/instrumentation/langchain/__tests__/langchain.test.ts

@@ -0,0 +1,284 @@
+// --- Mock setup (must be at the top for Vitest hoisting) ---
+const { mockSpan, mockTracer } = vi.hoisted(() => {
+  const calls: any = { setType: [], setInput: [], setOutput: [], setAttributes: [], setRequestModel: [], setOutputString: [], setInputString: [], addEvent: [], recordException: [], setStatus: [], end: 0 };
+  const span = {
+    setType: vi.fn(function (this: any, ...args) { calls.setType.push(args); return this; }),
+    setInput: vi.fn(function (this: any, ...args) { calls.setInput.push(args); return this; }),
+    setOutput: vi.fn(function (this: any, ...args) { calls.setOutput.push(args); return this; }),
+    setAttributes: vi.fn(function (this: any, ...args) { calls.setAttributes.push(args); return this; }),
+    setRequestModel: vi.fn(function (this: any, ...args) { calls.setRequestModel.push(args); return this; }),
+    setOutputString: vi.fn(function (this: any, ...args) { calls.setOutputString.push(args); return this; }),
+    setInputString: vi.fn(function (this: any, ...args) { calls.setInputString.push(args); return this; }),
+    addEvent: vi.fn(function (this: any, ...args) { calls.addEvent.push(args); return this; }),
+    recordException: vi.fn((...args) => { calls.recordException.push(args); }),
+    setStatus: vi.fn(function (this: any, ...args) { calls.setStatus.push(args); return this; }),
+    setSelectedPrompt: vi.fn(function (this: any, ...args) { calls.setSelectedPrompt.push(args); return this; }),
+    end: vi.fn(() => { calls.end++; }),
+    setRAGContexts: vi.fn(function (this: any, ...args) { return this; }),
+    setRAGContext: vi.fn(function (this: any, ...args) { return this; }),
+    setResponseModel: vi.fn(function (this: any, ...args) { return this; }),
+    setMetrics: vi.fn(function (this: any, ...args) { return this; }),
+    setOutputEvaluation: vi.fn(function (this: any, ...args) { return this; }),
+    recordEvaluation: vi.fn(function (this: any, ...args) { return this; }),
+    addGenAISystemMessageEvent: vi.fn(function (this: any, ...args) { return this; }),
+    addGenAIUserMessageEvent: vi.fn(function (this: any, ...args) { return this; }),
+    addGenAIAssistantMessageEvent: vi.fn(function (this: any, ...args) { return this; }),
+    addGenAIToolMessageEvent: vi.fn(function (this: any, ...args) { return this; }),
+    addGenAIChoiceEvent: vi.fn(function (this: any, ...args) { return this; }),
+    spanContext: vi.fn(() => ({ traceId: 'trace', spanId: 'span', traceFlags: 1 })),
+    setAttribute: vi.fn(function (this: any, ...args) { return this; }),
+    addLink: vi.fn(function (this: any, ...args) { return this; }),
+    addLinks: vi.fn(function (this: any, ...args) { return this; }),
+    updateName: vi.fn(function (this: any, ...args) { return this; }),
+    isRecording: vi.fn(),
+    calls,
+  };
+  const tracer = {
+    startSpan: vi.fn(() => span),
+    startActiveSpan: vi.fn(() => span),
+    withActiveSpan: vi.fn(async (...args: any[]) => {
+      // Find the function argument (should be the last argument)
+      const fnIndex = args.findIndex((arg) => typeof arg === "function");
+      if (fnIndex === -1) {
+        throw new Error("withActiveSpan requires a function as the last argument");
+      }
+      const userFn = args[fnIndex] as (span: any) => any;
+      return await userFn(span);
+    }) as any,
+  };
+  return { mockSpan: span, mockTracer: tracer };
+});
+
+vi.mock('../../../trace', () => ({
+  getLangWatchTracer: vi.fn(() => mockTracer),
+}));
+
+vi.mock('@opentelemetry/api', async () => {
+  const actual = await vi.importActual<any>('@opentelemetry/api');
+  return {
+    ...actual,
+    context: {
+      ...actual.context,
+      active: vi.fn(() => ({})),
+    },
+    trace: {
+      ...actual.trace,
+      setSpan: vi.fn((_ctx, span) => span),
+    },
+    SpanStatusCode: { ERROR: 'ERROR' },
+  };
+});
+
+vi.mock('../../../client', () => ({
+  canAutomaticallyCaptureInput: () => true,
+  canAutomaticallyCaptureOutput: () => true,
+}));
+
+// --- Imports (must be after mocks for Vitest hoisting) ---
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { LangWatchCallbackHandler, convertFromLangChainMessages } from '..';
+
+// --- Tests ---
+describe('LangWatchCallbackHandler', () => {
+  let handler: LangWatchCallbackHandler;
+
+  beforeEach(() => {
+    handler = new LangWatchCallbackHandler();
+    handler.tracer = mockTracer;
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('can be constructed', () => {
+    expect(handler).toBeInstanceOf(LangWatchCallbackHandler);
+  });
+
+  it('handleLLMStart creates a span and sets input/attributes', async () => {
+    const serializedMock = { lc: 1, type: 'constructor', id: ['llm', 'test'], kwargs: {} } as import('@langchain/core/load/serializable').SerializedConstructor;
+    await handler.handleLLMStart(
+      serializedMock,
+      ['prompt1', 'prompt2'],
+      'run1',
+      undefined,
+      { temperature: 0.7 },
+      ['tag1'],
+      { ls_model_name: 'gpt-4', foo: 'bar' },
+      'llmName',
+    );
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('llmName', {}, expect.anything());
+    expect(mockSpan.setType).toHaveBeenCalledWith('llm');
+    expect(mockSpan.setInput).toHaveBeenCalledWith(['prompt1', 'prompt2']);
+    expect(mockSpan.setRequestModel).toHaveBeenCalledWith('gpt-4');
+    expect(mockSpan.setAttributes).toHaveBeenCalled();
+    expect(handler.spans['run1']).toBe(mockSpan);
+  });
+
+  it('handleLLMEnd sets output and ends span', async () => {
+    handler.spans['run2'] = mockSpan;
+    await handler.handleLLMEnd(
+      { generations: [[{ text: 'output1' }], [{ text: 'output2' }]] },
+      'run2',
+    );
+    expect(mockSpan.setOutput).toHaveBeenCalled();
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['run2']).toBeUndefined();
+  });
+
+  it('handleLLMError records exception, sets error status, and ends span', async () => {
+    handler.spans['run3'] = mockSpan;
+    const error = new Error('fail');
+    await handler.handleLLMError(error, 'run3');
+    expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+    expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 'ERROR', message: 'fail' });
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['run3']).toBeUndefined();
+  });
+
+  it('handleChainStart creates a span and sets input', async () => {
+    const serializedMock = { lc: 1, type: 'constructor', id: ['chain', 'test'], kwargs: {} } as import('@langchain/core/load/serializable').SerializedConstructor;
+    const inputs = { foo: 'bar' };
+    await handler.handleChainStart(
+      serializedMock,
+      inputs,
+      'chainRun1',
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      'chainName',
+    );
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('chainName', {}, expect.anything());
+    expect(mockSpan.setType).toHaveBeenCalledWith('chain');
+    expect(mockSpan.setInput).toHaveBeenCalledWith(inputs);
+    expect(handler.spans['chainRun1']).toBe(mockSpan);
+  });
+
+  it('handleChainEnd sets output and ends span', async () => {
+    handler.spans['chainRun2'] = mockSpan;
+    const output = { result: 'done' };
+    await handler.handleChainEnd(output, 'chainRun2');
+    expect(mockSpan.setOutput).toHaveBeenCalledWith(output);
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['chainRun2']).toBeUndefined();
+  });
+
+  it('handleChainError records exception, sets error status, and ends span', async () => {
+    handler.spans['chainRun3'] = mockSpan;
+    const error = new Error('chain fail');
+    await handler.handleChainError(error, 'chainRun3');
+    expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+    expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 'ERROR', message: 'chain fail' });
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['chainRun3']).toBeUndefined();
+  });
+
+  it('handleToolStart creates a span and sets input string', async () => {
+    const serializedMock = { lc: 1, type: 'constructor', id: ['tool', 'test'], kwargs: {} } as import('@langchain/core/load/serializable').SerializedConstructor;
+    await handler.handleToolStart(
+      serializedMock,
+      'tool input',
+      'toolRun1',
+      undefined,
+      ['tag1'],
+      { meta: 'data' },
+      'toolName',
+    );
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('toolName', {}, expect.anything());
+    expect(mockSpan.setType).toHaveBeenCalledWith('tool');
+    expect(mockSpan.setInputString).toHaveBeenCalledWith('tool input');
+    expect(mockSpan.setAttributes).toHaveBeenCalled();
+    expect(handler.spans['toolRun1']).toBe(mockSpan);
+  });
+
+  it('handleToolEnd sets output string and ends span', async () => {
+    handler.spans['toolRun2'] = mockSpan;
+    await handler.handleToolEnd('tool output', 'toolRun2');
+    expect(mockSpan.setOutputString).toHaveBeenCalledWith('tool output');
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['toolRun2']).toBeUndefined();
+  });
+
+  it('handleToolError records exception, sets error status, and ends span', async () => {
+    handler.spans['toolRun3'] = mockSpan;
+    const error = new Error('tool fail');
+    await handler.handleToolError(error, 'toolRun3');
+    expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+    expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 'ERROR', message: 'tool fail' });
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['toolRun3']).toBeUndefined();
+  });
+
+  it('handleRetrieverStart creates a span and sets input string', async () => {
+    const serializedMock = { lc: 1, type: 'constructor', id: ['retriever', 'test'], kwargs: {} } as import('@langchain/core/load/serializable').SerializedConstructor;
+    await handler.handleRetrieverStart(
+      serializedMock,
+      'retriever query',
+      'retrieverRun1',
+      undefined,
+      ['tag1'],
+      { meta: 'data' },
+      'retrieverName',
+    );
+    expect(mockTracer.startSpan).toHaveBeenCalledWith('retrieverName', {}, expect.anything());
+    expect(mockSpan.setType).toHaveBeenCalledWith('rag');
+    expect(mockSpan.setInputString).toHaveBeenCalledWith('retriever query');
+    expect(mockSpan.setAttributes).toHaveBeenCalled();
+    expect(handler.spans['retrieverRun1']).toBe(mockSpan);
+  });
+
+  it('handleRetrieverEnd sets output, RAG contexts, and ends span', async () => {
+    handler.spans['retrieverRun2'] = mockSpan;
+    const docs = [
+      { metadata: { id: 'doc1', chunk_id: 'chunk1' }, pageContent: 'content1' },
+      { metadata: { id: 'doc2', chunk_id: 'chunk2' }, pageContent: 'content2' },
+    ];
+    await handler.handleRetrieverEnd(docs as any, 'retrieverRun2');
+    expect(mockSpan.setOutput).toHaveBeenCalledWith(docs);
+    expect(mockSpan.setRAGContexts).toHaveBeenCalledWith([
+      { document_id: 'doc1', chunk_id: 'chunk1', content: 'content1' },
+      { document_id: 'doc2', chunk_id: 'chunk2', content: 'content2' },
+    ]);
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['retrieverRun2']).toBeUndefined();
+  });
+
+  it('handleRetrieverError records exception, sets error status, and ends span', async () => {
+    handler.spans['retrieverRun3'] = mockSpan;
+    const error = new Error('retriever fail');
+    await handler.handleRetrieverError(error, 'retrieverRun3');
+    expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+    expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 'ERROR', message: 'retriever fail' });
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['retrieverRun3']).toBeUndefined();
+  });
+
+  it('handleAgentAction adds event and sets type', async () => {
+    handler.spans['agentRun1'] = mockSpan;
+    await handler.handleAgentAction({} as any, 'agentRun1');
+    expect(mockSpan.setType).toHaveBeenCalledWith('agent');
+  });
+
+  it('handleAgentEnd sets output, ends span, and cleans up', async () => {
+    handler.spans['agentRun2'] = mockSpan;
+    const action = { returnValues: { foo: 'bar' } };
+    await handler.handleAgentEnd(action as any, 'agentRun2');
+    expect(mockSpan.setOutput).toHaveBeenCalledWith(action.returnValues);
+    expect(mockSpan.end).toHaveBeenCalled();
+    expect(handler.spans['agentRun2']).toBeUndefined();
+  });
+
+  it('convertFromLangChainMessages converts messages to expected format', () => {
+    const messages = [
+      { content: 'hi', type: 'human', lc_serializable: false },
+      { content: 'hello', type: 'ai', lc_serializable: false },
+    ];
+    const result = convertFromLangChainMessages(messages as any);
+    expect(result[0].role).toBe('user');
+    expect(result[1].role).toBe('assistant');
+    expect(result[0].content).toBe('hi');
+    expect(result[1].content).toBe('hello');
+  });
+});