Source adapters

An adapter teaches AgentSync how to find and parse one agent's native session logs, and how to map them onto the normalized Transcript. Adapters are the pluggable extension point: supporting a new agent means writing one adapter, nothing else.

Interface: packages/core/src/adapter.ts

Contract

interface TranscriptAdapter {
  readonly id: string;            // "claude-code", "codex", …
  readonly displayName: string;
  readonly version: string;

  // 1. find candidate sessions on disk (no parsing yet — cheap)
  detect(ctx: AdapterContext): Promise<DetectedSession[]>;

  // 2. read + parse one session into a faithful, UN-redacted Transcript
  parse(ref: DetectedSession, ctx: AdapterContext): Promise<Transcript>;
}

The split between detect and parse keeps agentsync submit fast: detection just lists sessions (id, path, timestamps, title) so the user can pick one; parsing only happens for the chosen session.

Adapters produce a faithful transcript. They do not apply privacy policy — redaction/anonymization is a separate stage that runs over the adapter's output according to the active profile. This separation keeps "what the agent did" independent from "what we're willing to share."

Lifecycle in the CLI

registry.detectAll()        → DetectedSession[]   (across all adapters)
user picks / --latest
adapter.parse(ref)          → Transcript          (faithful, raw)
privacy.apply(profile, t)   → Transcript          (redacted, anonymized)
preview + confirm
upload

First-party adapters

claude-code

• Source: ~/.claude/projects/**/<session>.jsonl (one JSON object per line).
• Mapping: each line → one or more events; user/assistant turns map directly; tool_use / tool_result blocks become tool_call / tool_result linked by callId; thinking blocks become reasoning events.

codex

• Source: OpenAI Codex CLI session logs.
• Mapping: turns → messages; command executions → tool_call (name: "shell") with tool_result; patches/diffs → tool_call (name: "apply_patch").

Writing a new adapter

1. Implement TranscriptAdapter.
2. Locate the agent's log directory (prefer XDG / documented paths; allow an override via AdapterContext).
3. In detect, return lightweight DetectedSession refs.
4. In parse, emit normalized events with stable seq and callId links.
5. Register it. (A discovery mechanism — built-in registry plus agentsync-adapter-* npm packages — is specified for the CLI but not implemented in this repo yet.)

Mapping guidance

• Preserve ordering with seq even if the native log lacks timestamps.
• Always link a tool_call to its tool_result via the same callId.
• Put model thinking in reasoning events (so a profile can drop it wholesale).
• Don't pre-truncate; the content policy decides truncation, not the adapter.
• Set source.agentVersion when the log exposes it; null is acceptable.