feat(agent-tracing): rename TraceSession to Trace and support inputs in createTrace

- Rename `TraceSession` → `Trace`, `createSession` → `createTrace`, `CreateSessionOptions` → `CreateTraceOptions`
- Add `inputs` option to `CreateTraceOptions` for injecting user messages into root run inputs
- This aligns Claude tracer with LangGraph tracer which auto-populates `run.inputs.messages`

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jerryliang64

core/agent-tracing/claude.ts

@@ -1,2 +1,2 @@
 export * from './index';
-export { ClaudeAgentTracer, TraceSession } from './src/ClaudeAgentTracer';
+export { ClaudeAgentTracer, Trace } from './src/ClaudeAgentTracer';

core/agent-tracing/src/ClaudeAgentTracer.ts

@@ -12,30 +12,32 @@ import {
   type ClaudeContentBlock,
   type ClaudeTokenUsage,
   type IRunCost,
-  type CreateSessionOptions,
+  type CreateTraceOptions,
   RunStatus,
   type TracerConfig,
   applyTracerConfig,
 } from './types';
 
 /**
- * TraceSession - Manages state for a single agent execution with streaming support.
+ * Trace - Manages state for a single agent execution with streaming support.
  * Allows processing messages one-by-one and logging them immediately.
  */
-export class TraceSession {
+export class Trace {
   private traceId: string;
   private threadId?: string;
+  private inputs?: Record<string, any>;
   private rootRun: Run | null = null;
   private rootRunId: string;
   private startTime: number;
   private executionOrder = 2; // Start at 2, root is 1
   private pendingToolUses = new Map<string, Run>();
   private tracer: ClaudeAgentTracer;
 
-  constructor(tracer: ClaudeAgentTracer, options?: CreateSessionOptions) {
+  constructor(tracer: ClaudeAgentTracer, options?: CreateTraceOptions) {
     this.tracer = tracer;
     this.traceId = options?.traceId || randomUUID();
     this.threadId = options?.threadId;
+    this.inputs = options?.inputs;
     this.rootRunId = randomUUID();
     this.startTime = Date.now();
   }
@@ -69,6 +71,9 @@ export class TraceSession {
       this.threadId = message.session_id;
     }
     this.rootRun = this.tracer.createRootRunInternal(message, this.startTime, this.traceId, this.rootRunId, this.threadId);
+    if (this.inputs) {
+      Object.assign(this.rootRun.inputs, this.inputs);
+    }
     this.tracer.logTrace(this.rootRun, RunStatus.START);
   }
 
@@ -192,7 +197,7 @@ export class TraceSession {
  * ClaudeAgentTracer - Converts Claude SDK messages to LangChain Run format
  * and logs them to the same remote logging system as LangGraphTracer.
  *
- * Supports both batch processing (processMessages) and streaming (createSession).
+ * Supports both batch processing (processMessages) and streaming (createTrace).
  */
 @SingletonProto({
   accessLevel: AccessLevel.PUBLIC,
@@ -216,26 +221,31 @@ export class ClaudeAgentTracer {
   }
 
   /**
-   * Create a new trace session for streaming message processing.
-   * Use this for real-time tracing where messages arrive one-by-one.
+   * Create a new trace for one agent execution.
+   * Returns a Trace object for streaming message processing.
    *
    * @param options.traceId - Server-side trace ID for call chain linking. Defaults to a random UUID.
-   * @param options.threadId - Thread ID (Claude SDK session ID), recorded in metadata.
+   * @param options.threadId - Thread ID (conversation/session identifier), recorded in metadata.
+   * @param options.inputs - Additional inputs to merge into root run's inputs (e.g. user messages).
    *
    * @example
-   * const session = claudeTracer.createSession({ traceId: ctx.tracer.traceId, threadId });
+   * const trace = claudeTracer.createTrace({
+   *   traceId: ctx.tracer.traceId,
+   *   threadId,
+   *   inputs: { messages: [{ role: 'user', content: 'hello' }] },
+   * });
    * for await (const message of agent.run('task')) {
-   *   await session.processMessage(message);
+   *   await trace.processMessage(message);
    * }
    */
-  public createSession(options?: CreateSessionOptions): TraceSession {
-    return new TraceSession(this, options);
+  public createTrace(options?: CreateTraceOptions): Trace {
+    return new Trace(this, options);
   }
 
   /**
    * Main entry point - convert SDK messages to Run trees and log them.
    * Use this when you have all messages collected (batch processing).
-   * For real-time streaming, use createSession() instead.
+   * For real-time streaming, use createTrace() instead.
    *
    * Non-tracing message types (tool_progress, stream_event, status, etc.) are automatically filtered out.
    */
@@ -246,17 +256,17 @@ export class ClaudeAgentTracer {
         return;
       }
 
-      // Pre-validate: ensure there is an init message before creating session
+      // Pre-validate: ensure there is an init message before creating trace
       const hasInit = sdkMessages.some(m => m.type === 'system' && 'subtype' in m && m.subtype === 'init');
       if (!hasInit) {
         this.logger.warn('[ClaudeAgentTracer] No system/init message found');
         return;
       }
 
-      // Delegate to TraceSession for message processing
-      const session = this.createSession();
+      // Delegate to Trace for message processing
+      const trace = this.createTrace();
       for (const msg of sdkMessages) {
-        await session.processMessage(msg);
+        await trace.processMessage(msg);
       }
     } catch (e) {
       this.logger.warn('[ClaudeAgentTracer] processMessages error:', e);

core/agent-tracing/src/types.ts

@@ -132,12 +132,14 @@ export const RunStatus = {
 } as const;
 export type RunStatus = (typeof RunStatus)[keyof typeof RunStatus];
 
-/** Options for creating a new trace session. */
-export interface CreateSessionOptions {
+/** All context needed to create a trace for one agent execution. */
+export interface CreateTraceOptions {
   /** Server-side trace ID for linking to the request call chain. Defaults to a random UUID. */
   traceId?: string;
-  /** Thread ID (Claude SDK session ID), recorded in metadata. */
+  /** Thread ID (conversation/session identifier), recorded in metadata. */
   threadId?: string;
+  /** Additional inputs to merge into root run's inputs (e.g. user messages). */
+  inputs?: Record<string, any>;
 }
 
 /** User-facing config passed to tracer.configure() */

core/agent-tracing/test/ClaudeAgentTracer.test.ts

@@ -173,7 +173,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Streaming mode + tool use', () => {
     it('should trace tool execution with session.processMessage', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       // Feed messages one-by-one, including noise messages that should be filtered
       const messages: SDKMessage[] = [
@@ -186,7 +186,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
       ];
 
       for (const msg of messages) {
-        await session.processMessage(msg);
+        await trace.processMessage(msg);
       }
 
       // Root run start + end
@@ -243,7 +243,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Separate traceId and sessionId', () => {
     it('should use provided traceId and record threadId in metadata', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession({
+      const trace = claudeTracer.createTrace({
         traceId: 'server-trace-abc',
         threadId: 'my-thread-id',
       });
@@ -255,7 +255,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
       ];
 
       for (const msg of messages) {
-        await session.processMessage(msg);
+        await trace.processMessage(msg);
       }
 
       // All runs should use the provided traceId
@@ -272,10 +272,10 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
 
     it('should fallback threadId to init message session_id when not provided', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession({ traceId: 'server-trace-xyz' });
+      const trace = claudeTracer.createTrace({ traceId: 'server-trace-xyz' });
 
-      await session.processMessage(createMockInit());
-      await session.processMessage(createMockResult());
+      await trace.processMessage(createMockInit());
+      await trace.processMessage(createMockResult());
 
       const rootStart = capturedRuns.find(e => !e.run.parent_run_id && e.status === RunStatus.START);
       assert(rootStart);
@@ -287,6 +287,46 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
     });
   });
 
+  describe('Trace inputs in root run', () => {
+    it('should merge inputs into root run inputs when provided via createTrace', async () => {
+      const { claudeTracer, capturedRuns } = createTestEnv();
+      const trace = claudeTracer.createTrace({
+        inputs: { messages: [{ role: 'user', content: 'Hello, what is 1+1?' }] },
+      });
+
+      const messages: SDKMessage[] = [
+        createMockInit(),
+        createMockAssistantTextOnly(),
+        createMockResult(),
+      ];
+
+      for (const msg of messages) {
+        await trace.processMessage(msg);
+      }
+
+      const rootStart = capturedRuns.find(e => !e.run.parent_run_id && e.status === RunStatus.START);
+      assert(rootStart, 'Should have root_run start');
+      assert.deepStrictEqual(
+        (rootStart.run.inputs as any).messages,
+        [{ role: 'user', content: 'Hello, what is 1+1?' }],
+      );
+      // Original init fields should still be present
+      assert.deepStrictEqual((rootStart.run.inputs as any).tools, [ 'Bash', 'Read' ]);
+    });
+
+    it('should not have extra inputs when not provided', async () => {
+      const { claudeTracer, capturedRuns } = createTestEnv();
+      const trace = claudeTracer.createTrace();
+
+      await trace.processMessage(createMockInit());
+      await trace.processMessage(createMockResult());
+
+      const rootStart = capturedRuns.find(e => !e.run.parent_run_id && e.status === RunStatus.START);
+      assert(rootStart, 'Should have root_run start');
+      assert.strictEqual((rootStart.run.inputs as any).messages, undefined);
+    });
+  });
+
   describe('Batch mode + text-only', () => {
     it('should trace a text-only response via processMessages', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
@@ -341,7 +381,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Error scenario', () => {
     it('should trace an error result with ERROR status', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       const messages: SDKMessage[] = [
         createMockInit(),
@@ -370,7 +410,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
       ];
 
       for (const msg of messages) {
-        await session.processMessage(msg);
+        await trace.processMessage(msg);
       }
 
       // Root run should end with ERROR status
@@ -383,21 +423,21 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Guard clauses — messages before init', () => {
     it('should warn and ignore assistant message received before init', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       // Send assistant message without a preceding init
-      await session.processMessage(createMockAssistantWithTool());
+      await trace.processMessage(createMockAssistantWithTool());
 
       // Nothing should have been traced
       assert.strictEqual(capturedRuns.length, 0, 'No runs should be captured before init');
     });
 
     it('should warn and ignore result message received before init', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       // Send result message without a preceding init
-      await session.processMessage(createMockResult());
+      await trace.processMessage(createMockResult());
 
       // Nothing should have been traced
       assert.strictEqual(capturedRuns.length, 0, 'No runs should be captured before init');
@@ -407,7 +447,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Pending tool runs cleanup on result', () => {
     it('should log ERROR for pending tool runs that never received a result', async () => {
       const { claudeTracer, capturedRuns } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       // Init → assistant calls a tool → result arrives WITHOUT the tool_result
       const messages: SDKMessage[] = [
@@ -417,7 +457,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
       ];
 
       for (const msg of messages) {
-        await session.processMessage(msg);
+        await trace.processMessage(msg);
       }
 
       // The pending tool run should have been force-closed with ERROR status
@@ -450,7 +490,7 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
   describe('Internal error handling', () => {
     it('should catch errors thrown inside processMessage without propagating', async () => {
       const { claudeTracer } = createTestEnv();
-      const session = claudeTracer.createSession();
+      const trace = claudeTracer.createTrace();
 
       // Force an error by replacing logTrace with a throwing stub
       (claudeTracer as any).tracingService = {
@@ -461,16 +501,16 @@ describe('test/ClaudeAgentTracer.test.ts', () => {
 
       // Should NOT throw — error is swallowed by the catch block
       await assert.doesNotReject(async () => {
-        await session.processMessage(createMockInit());
+        await trace.processMessage(createMockInit());
       });
     });
 
     it('should catch errors thrown inside processMessages without propagating', async () => {
       const { claudeTracer } = createTestEnv();
 
-      // Replace createSession with a throwing stub to trigger the outer catch
-      (claudeTracer as any).createSession = () => {
-        throw new Error('unexpected createSession error');
+      // Replace createTrace with a throwing stub to trigger the outer catch
+      (claudeTracer as any).createTrace = () => {
+        throw new Error('unexpected createTrace error');
       };
 
       // Should NOT throw — error is swallowed by the catch block