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

## Summary

- Rename `TraceSession` → `Trace`, `createSession()` → `createTrace()`,
`CreateSessionOptions` → `CreateTraceOptions` for clearer semantics
- Add `inputs` option to `CreateTraceOptions`, allowing callers to
inject user messages into root run's `inputs` field
- Move config fields (tools, model, mcp_servers, agents, slash_commands,
session_id) from `inputs` to `extra`, aligning with LangGraph convention
where `inputs` only contains user business data

## Changes

- `core/agent-tracing/src/types.ts` - Rename type and add `inputs` field
- `core/agent-tracing/src/ClaudeAgentTracer.ts` - Rename class/method,
merge inputs in `handleInit`, move config fields to `extra`
- `core/agent-tracing/claude.ts` - Update export
- `core/agent-tracing/test/ClaudeAgentTracer.test.ts` - Update all
references + 2 new test cases for inputs

## Root Run structure (before → after)

```diff
 // inputs
-  tools, model, session_id, mcp_servers, agents, slash_commands
+  {} (empty by default, populated via CreateTraceOptions.inputs)

 // extra
   metadata: { thread_id },
+  tools, model, session_id, mcp_servers, agents, slash_commands,
   apiKeySource, claude_code_version, output_style, permissionMode
```

## Usage

```typescript
const trace = claudeTracer.createTrace({
  traceId: ctx.tracer.traceId,
  threadId,
  inputs: { messages: [{ role: 'user', content: prompt }] },
});
for await (const msg of query({ prompt, options })) {
  await trace.processMessage(msg);
}
```

## Test plan

- [x] All 56 existing tests pass
- [x] New test: inputs are merged into root run when provided via
`createTrace`
- [x] New test: config fields are in `extra`, not `inputs`
- [x] New test: no extra inputs when not provided

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added support for passing custom inputs during trace initialization to
populate trace configuration.

* **API Changes**
* Renamed `createSession()` method to `createTrace()` for improved
semantic clarity.
  * Renamed `CreateSessionOptions` type to `CreateTraceOptions`.
  * Enhanced trace initialization options with new `inputs` parameter.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

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 } 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.
+ * Manages state for a single agent execution with streaming support.
  * Allows processing messages one-by-one and logging them immediately.
  */
-export class TraceSession {
+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);
@@ -322,7 +332,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Create root run from init message (used by TraceSession)
+   * Create root run from init message (used by Trace)
    */
   createRootRunInternal(initMsg: ClaudeMessage, startTime: number, traceId: string, rootRunId?: string, threadId?: string): Run {
     const runId = rootRunId || initMsg.uuid || randomUUID();
@@ -332,14 +342,7 @@ export class ClaudeAgentTracer {
       id: runId,
       name: this.name,
       run_type: 'chain',
-      inputs: {
-        tools: initMsg.tools || [],
-        model: initMsg.model,
-        session_id: resolvedThreadId,
-        mcp_servers: initMsg.mcp_servers,
-        agents: initMsg.agents,
-        slash_commands: initMsg.slash_commands,
-      },
+      inputs: {},
       outputs: undefined,
       start_time: startTime,
       end_time: undefined,
@@ -354,6 +357,12 @@ export class ClaudeAgentTracer {
         metadata: {
           thread_id: resolvedThreadId,
         },
+        tools: initMsg.tools || [],
+        model: initMsg.model,
+        session_id: resolvedThreadId,
+        mcp_servers: initMsg.mcp_servers,
+        agents: initMsg.agents,
+        slash_commands: initMsg.slash_commands,
         apiKeySource: initMsg.apiKeySource,
         claude_code_version: initMsg.claude_code_version,
         output_style: initMsg.output_style,
@@ -364,7 +373,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Create LLM run from assistant message (used by TraceSession)
+   * Create LLM run from assistant message (used by Trace)
    */
   createLLMRunInternal(
     msg: ClaudeMessage,
@@ -422,7 +431,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Create tool run at start (before result, used by TraceSession)
+   * Create tool run at start (before result, used by Trace)
    */
   createToolRunStartInternal(
     toolUseBlock: ClaudeContentBlock,
@@ -460,7 +469,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Complete tool run with result (used by TraceSession)
+   * Complete tool run with result (used by Trace)
    */
   completeToolRunInternal(toolRun: Run, toolResultBlock: ClaudeContentBlock, startTime: number): void {
     const result = toolResultBlock as any;
@@ -503,7 +512,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Create run cost from result message (used by TraceSession)
+   * Create run cost from result message (used by Trace)
    */
   createRunCostInternal(resultMsg: ClaudeMessage): IRunCost {
     const cost: IRunCost = resultMsg.usage ? this.extractTokenUsage(resultMsg.usage) : {};
@@ -517,7 +526,7 @@ export class ClaudeAgentTracer {
 
   /**
    * @internal
-   * Log trace - delegates to TracingService (used by TraceSession)
+   * Log trace - delegates to TracingService (used by Trace)
    */
   logTrace(run: Run, status: RunStatus): void {
     this.tracingService.logTrace(run, status, this.name, this.agentName);

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() */