Skip to content

adapter-guide.md

Latest commit

 

History

History
116 lines (82 loc) · 4.88 KB

adapter-guide.md

File metadata and controls

116 lines (82 loc) · 4.88 KB

Adapter Guide

Adapters translate runtime-specific trace records into TraceCC canonical events.

When tracecc has central config in ~/.TraceCC/config.toml, adapter selection can be guided by configured trace roots before content probing runs.

Current MVP adapter

The current implementation ships three adapters:

  • claude
  • codex
  • hermes

It parses current Claude Code JSONL traces incrementally and emits canonical events into the compile pipeline.

Adapter contract

An adapter must be able to:

  • identify whether it can parse a source
  • parse input incrementally
  • emit canonical events in source order
  • expose a rule version for bundle provenance

Claude adapter behavior

The Claude adapter currently handles:

  • line-by-line JSONL parsing
  • auto-detection based on current Claude Code record fields such as sessionId, message.content, and permissionMode
  • dropped/noise record filtering
  • hidden preservation of startup metadata such as permission mode and attachments
  • assistant message.content[] lowering into thinking, assistant text, tool calls, and artifacts
  • XML-ish harness markup stripping
  • ANSI/control character stripping
  • readable tool input normalization
  • compaction boundary recognition
  • pairing tool_use blocks with later tool_result wrappers
  • artifact reference extraction for base64-backed document and image records

Codex adapter behavior

The Codex adapter currently handles:

  • current Codex desktop session JSONL detection via session_meta / response_item records
  • session metadata capture from session_meta and turn_context
  • project stamping from Codex session cwd, since Codex stores sessions in date buckets instead of project-specific directories
  • project-aware filtering when a configured Codex trace root is compiled from inside a known project root, so mixed same-day sessions do not bleed across projects
  • user message extraction from response_item.message
  • assistant commentary/final message extraction from event_msg.agent_message
  • tool-call lowering from response_item.function_call
  • tool-result pairing by call_id
  • exec_command result extraction from event_msg.exec_command_end
  • generic tool output extraction from response_item.function_call_output
  • noisy duplicate suppression where Codex logs both an event stream and a response-item mirror

Hermes adapter behavior

The Hermes adapter handles traces from the Hermes Agent, stored in ~/.hermes/sessions/ as JSONL files:

  • auto-detection via session_meta records with platform and tools fields (distinguishing from Codex which uses originator instead)
  • session metadata capture from session_meta including platform and model
  • user message extraction from role: "user" records
  • assistant text and reasoning extraction from role: "assistant" records, with reasoning emitted as thinking events
  • tool-call lowering from the tool_calls array on assistant records (OpenAI function-calling format with id, function.name, function.arguments)
  • tool-result pairing by tool_call_id from role: "tool" records
  • tool error detection for results containing "error", "failed", or "permission denied"

Hermes sessions are flat (not organized by project directory), so the trace root uses no project_mode.

Shared adapter utilities

internal/adapter/util.go provides common helpers used by all adapters:

  • SanitizeText — strips control characters and normalizes line endings
  • ParseTimestamp — parses RFC3339, RFC3339Nano, and YYYY-MM-DD HH:MM:SS strings, or Unix epoch floats
  • MergeAttrs — merges two attribute maps
  • CloneEvent — shallow-copies a canonical event with a fresh attribute map
  • ReadableParts — sanitizes text and wraps it as a single TextPart
  • FirstString — returns the first non-empty value from a record for a list of keys
  • ValueMap, ValueSlice, ValueString — safe type assertions for parsed JSON values
  • Coalesce — returns the first non-empty string

Adapters that need additional sanitization (e.g. ANSI or XML stripping) layer their own transforms on top of SanitizeText.

Noise filtering

internal/policy/noise/noise.go provides a single IsDropped function used during adapter parsing to skip records that carry no semantic content. A record is dropped if:

  • it has a dropped: true attribute, or
  • its record type is one of: ping, heartbeat, noop, debug, trace

Canonical event goals

Adapters should normalize into a shape that is stable for:

  • IR construction
  • line assignment
  • search
  • cross-runtime rendering

That means runtime-specific quirks should stay in the adapter layer whenever possible.

Future adapters

The package layout is designed to support additional adapters later, such as:

  • Responses-style traces
  • OTEL-derived traces

Those should target the same canonical event model instead of introducing renderer-specific branches.