codextranscript

package
v0.2.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrIncompleteFirstLine = errors.New("incomplete first rollout line")

Functions

func IndexPath 

func IndexPath(rollout string) string

IndexPath is the thread index of the Codex home a rollout file lives in, `<home>/session_index.jsonl` for `<home>/sessions/…/rollout-….jsonl`; empty when the rollout is not under a `sessions` directory.

func ThreadName 

func ThreadName(path, id string) (string, error)

ThreadName is the last name Codex's thread index at path gives the thread id: the name Codex shows for the conversation. Empty, with no error, when the index does not name it. The file is read again only when its size or modification time changed.

Types

type AgentMessage 

type AgentMessage struct {
	ID              string          `json:"id,omitempty"`
	Author          string          `json:"author"`
	Recipient       string          `json:"recipient"`
	OtherRecipients []string        `json:"other_recipients,omitempty"`
	Content         json.RawMessage `json:"content"`
}

type AgentMessageEvent 

type AgentMessageEvent struct {
	Message string  `json:"message"`
	Phase   *string `json:"phase,omitempty"`
}

type AgentReasoningEvent 

type AgentReasoningEvent struct {
	Text string `json:"text"`
}

type Class 

type Class string

Class is the closed outer rollout record class. 

const (
	ClassSessionMeta             Class = "session_meta"
	ClassTurnContext             Class = "turn_context"
	ClassResponseItem            Class = "response_item"
	ClassEventMsg                Class = "event_msg"
	ClassCompacted               Class = "compacted"
	ClassWorldState              Class = "world_state"
	ClassInterAgentMetadata      Class = "inter_agent_communication_metadata"
	ClassInterAgentCommunication Class = "inter_agent_communication"
	ClassTokenUsageRecord        Class = "token_usage_record"
	ClassRealtime                Class = "realtime_item"
)

type ContentItem 

type ContentItem struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

type CustomToolCall 

type CustomToolCall struct {
	ID     string `json:"id,omitempty"`
	CallID string `json:"call_id"`
	Name   string `json:"name"`
	Input  string `json:"input"`
	Status string `json:"status,omitempty"`
}

type CustomToolCallOutput 

type CustomToolCallOutput struct {
	ID     string          `json:"id,omitempty"`
	CallID string          `json:"call_id"`
	Output json.RawMessage `json:"output"`
}

type EventMsg 

type EventMsg struct {
	Type                  string                 `json:"type"`
	Raw                   json.RawMessage        `json:"raw"`
	TaskStarted           *TaskStarted           `json:"task_started,omitempty"`
	TaskComplete          *TaskComplete          `json:"task_complete,omitempty"`
	TurnAborted           *TurnAborted           `json:"turn_aborted,omitempty"`
	UserMessage           *UserMessage           `json:"user_message,omitempty"`
	AgentMessage          *AgentMessageEvent     `json:"agent_message,omitempty"`
	AgentReasoning        *AgentReasoningEvent   `json:"agent_reasoning,omitempty"`
	TokenCount            *TokenCount            `json:"token_count,omitempty"`
	ExecCommandEnd        *ExecCommandEnd        `json:"exec_command_end,omitempty"`
	PatchApplyEnd         *PatchApplyEnd         `json:"patch_apply_end,omitempty"`
	MCPToolCallEnd        *MCPToolCallEnd        `json:"mcp_tool_call_end,omitempty"`
	WebSearchEnd          *WebSearchEnd          `json:"web_search_end,omitempty"`
	SubAgentActivity      *SubAgentActivity      `json:"sub_agent_activity,omitempty"`
	ThreadSettingsApplied *ThreadSettingsApplied `json:"thread_settings_applied,omitempty"`
	ThreadRolledBack      *ThreadRolledBack      `json:"thread_rolled_back,omitempty"`
	ItemCompleted         *ItemCompleted         `json:"item_completed,omitempty"`
	ContextCompacted      bool                   `json:"context_compacted,omitempty"`
	ThreadGoalUpdated     *RawPayload            `json:"thread_goal_updated,omitempty"`
}

EventMsg is a closed saved lifecycle/UI event. Exactly one typed pointer is set.

type ExecCommandEnd 

type ExecCommandEnd struct {
	CallID           string          `json:"call_id"`
	TurnID           string          `json:"turn_id,omitempty"`
	Status           string          `json:"status,omitempty"`
	ExitCode         *int            `json:"exit_code,omitempty"`
	Command          json.RawMessage `json:"command,omitempty"`
	CWD              string          `json:"cwd,omitempty"`
	Stdout           string          `json:"stdout,omitempty"`
	Stderr           string          `json:"stderr,omitempty"`
	AggregatedOutput string          `json:"aggregated_output,omitempty"`
	FormattedOutput  string          `json:"formatted_output,omitempty"`
}

type File 

type File struct {
	Path          string       `json:"path"`
	Meta          *SessionMeta `json:"session_meta"`
	Lines         []Line       `json:"lines"`
	TornFinalLine bool         `json:"torn_final_line"`
}

func Read 

func Read(reader io.Reader, label string) (*File, error)

Read decodes and validates one rollout from a reader.

func ReadFile 

func ReadFile(path string) (*File, error)

type FileSources 

type FileSources = traceprocessing.FileSources

type FunctionCall 

type FunctionCall struct {
	ID        string `json:"id,omitempty"`
	CallID    string `json:"call_id"`
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
	Arguments string `json:"arguments"`
}

type FunctionCallOutput 

type FunctionCallOutput struct {
	ID     string          `json:"id,omitempty"`
	CallID string          `json:"call_id"`
	Output json.RawMessage `json:"output"`
}

type GitInfo 

type GitInfo struct {
	CommitHash    string `json:"commit_hash,omitempty"`
	Branch        string `json:"branch,omitempty"`
	RepositoryURL string `json:"repository_url,omitempty"`
}

type InterAgentCommunication 

type InterAgentCommunication struct {
	Author          string          `json:"author,omitempty"`
	Recipient       string          `json:"recipient,omitempty"`
	OtherRecipients []string        `json:"other_recipients,omitempty"`
	Content         json.RawMessage `json:"content,omitempty"`
	TriggerTurn     *bool           `json:"trigger_turn,omitempty"`
	Raw             json.RawMessage `json:"raw"`
}

type InterAgentMeta 

type InterAgentMeta struct {
	TriggerTurn bool            `json:"trigger_turn"`
	Raw         json.RawMessage `json:"raw"`
}

type ItemCompleted 

type ItemCompleted struct {
	ThreadID string          `json:"thread_id"`
	TurnID   string          `json:"turn_id"`
	Item     json.RawMessage `json:"item"`
}

type Line 

type Line struct {
	Ordinal   int             `json:"ordinal"`
	Timestamp time.Time       `json:"timestamp"`
	Type      string          `json:"type"`
	Class     Class           `json:"class"`
	Raw       json.RawMessage `json:"raw"`
	Payload   json.RawMessage `json:"payload"`

	SessionMeta             *SessionMeta             `json:"session_meta,omitempty"`
	TurnContext             *TurnContext             `json:"turn_context,omitempty"`
	ResponseItem            *ResponseItem            `json:"response_item,omitempty"`
	EventMsg                *EventMsg                `json:"event_msg,omitempty"`
	Compacted               *RawPayload              `json:"compacted,omitempty"`
	WorldState              *RawPayload              `json:"world_state,omitempty"`
	InterAgentMetadata      *InterAgentMeta          `json:"inter_agent_communication_metadata,omitempty"`
	InterAgentCommunication *InterAgentCommunication `json:"inter_agent_communication,omitempty"`
	TokenUsageRecord        *TokenUsageRecord        `json:"token_usage_record,omitempty"`
	Realtime                *RawPayload              `json:"realtime_item,omitempty"`
	Unknown                 bool                     `json:"unknown,omitempty"`
}

Line is one decoded rollout envelope. Exactly one typed payload pointer is set according to Class; Raw and Payload retain the complete source record. A line whose class, response_item type or event_msg type this reader does not know is Unknown: no typed payload is set beyond the item's Type and Raw.

func Decode 

func Decode(r io.Reader) (lines []Line, torn bool, err error)

Decode reads a JSONL rollout.

func DecodeFirst 

func DecodeFirst(r io.Reader) (Line, error)

DecodeFirst decodes only the first non-empty record.

type MCPToolCallEnd 

type MCPToolCallEnd struct {
	CallID     string          `json:"call_id"`
	Invocation json.RawMessage `json:"invocation,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
}

type Message 

type Message struct {
	ID      string          `json:"id,omitempty"`
	Role    string          `json:"role"`
	Content json.RawMessage `json:"content"`
	Phase   *string         `json:"phase,omitempty"`
}

func (*Message) Items 

func (m *Message) Items() ([]ContentItem, error)

type PatchApplyEnd 

type PatchApplyEnd struct {
	CallID  string                 `json:"call_id"`
	TurnID  string                 `json:"turn_id,omitempty"`
	Status  string                 `json:"status,omitempty"`
	Success *bool                  `json:"success,omitempty"`
	Stdout  string                 `json:"stdout,omitempty"`
	Stderr  string                 `json:"stderr,omitempty"`
	Changes map[string]PatchChange `json:"changes,omitempty"`
}

type PatchChange 

type PatchChange struct {
	Type        string  `json:"type"`
	UnifiedDiff string  `json:"unified_diff,omitempty"`
	MovePath    *string `json:"move_path,omitempty"`
}

type RawPayload 

type RawPayload struct {
	Raw json.RawMessage `json:"raw"`
}

RawPayload is a known context-only payload whose vendor fields stay opaque.

type ReadRollout added in v0.2.0 

type ReadRollout func(path string) (*File, error)

ReadRollout reads the rollout at path. Reading.File returns what it must.

type Reading added in v0.2.0 

type Reading struct {
	// contains filtered or unexported fields
}

Reading is one rollout decoded up to a byte offset, kept so that a rollout that grew is read from where the last read stopped rather than from its start. Continue decodes what was appended; File returns the rollout as a whole read of the same bytes would. The envelope ordinal check keeps what the first line said about pagination across reads.

A Reading leaves out the copies of each record that the mapper never reads (Line.Raw, Line.Payload but on event_msg lines, and the Raw of response items, events and turn contexts), so the lines it keeps take a fraction of the memory. A Reading is not safe for concurrent use.

func NewReading added in v0.2.0 

func NewReading(label string) *Reading

NewReading starts reading a rollout, reported as label.

func (*Reading) Bytes added in v0.2.0 

func (r *Reading) Bytes() int64

Bytes estimates the memory the lines read so far take.

func (*Reading) Continue added in v0.2.0 

func (r *Reading) Continue(src io.Reader) (consumed int64, rest []byte, err error)

Continue decodes the lines src holds that end in a newline. src continues the rollout where the previous call's consumed bytes ended. A final line without a newline is not consumed: it is returned as rest, for File, and the next call reads it again from its first byte. After an error the Reading must be dropped.

func (*Reading) File added in v0.2.0 

func (r *Reading) File(rest []byte) (*File, error)

File is the rollout read so far, followed by rest, the final line the last Continue left unread, decoded as Decode decodes a final line. The Reading is unchanged, and the File shares its lines, so neither may be changed. A final line that decodes is added to a copy of the lines: the spare capacity after them is where the next Continue appends, while the File may still be mapped. Codex ends every record it writes with a newline, so rest is normally empty or torn and nothing is copied.

func (*Reading) Lines added in v0.2.0 

func (r *Reading) Lines() int

Lines is the number of lines read so far.

func (*Reading) Sum added in v0.2.0 

func (r *Reading) Sum() uint32

Sum is the CRC-32C (traceprocessing.Castagnoli) of the bytes the lines read so far were decoded from: every byte Continue consumed.

type Reasoning 

type Reasoning struct {
	ID               string          `json:"id,omitempty"`
	Summary          json.RawMessage `json:"summary,omitempty"`
	Content          json.RawMessage `json:"content,omitempty"`
	EncryptedContent string          `json:"encrypted_content,omitempty"`
}

type ResponseItem 

type ResponseItem struct {
	Type             string                `json:"type"`
	Raw              json.RawMessage       `json:"raw"`
	Message          *Message              `json:"message,omitempty"`
	AgentMessage     *AgentMessage         `json:"agent_message,omitempty"`
	Reasoning        *Reasoning            `json:"reasoning,omitempty"`
	FunctionCall     *FunctionCall         `json:"function_call,omitempty"`
	FunctionOutput   *FunctionCallOutput   `json:"function_call_output,omitempty"`
	CustomCall       *CustomToolCall       `json:"custom_tool_call,omitempty"`
	CustomOutput     *CustomToolCallOutput `json:"custom_tool_call_output,omitempty"`
	ToolSearchCall   *ToolSearchCall       `json:"tool_search_call,omitempty"`
	ToolSearchOutput *ToolSearchOutput     `json:"tool_search_output,omitempty"`
	WebSearchCall    *WebSearchCall        `json:"web_search_call,omitempty"`
	Compaction       *RawPayload           `json:"compaction,omitempty"`
	// AdditionalTools are the tools Codex 0.165 offers the model beyond its
	// own, kept as written: they are context, not conversation.
	AdditionalTools *RawPayload `json:"additional_tools,omitempty"`
	// ConfigurationUpdate is a setting, such as the reasoning effort,
	// changed during the session.
	ConfigurationUpdate *RawPayload `json:"configuration_update,omitempty"`
	ImageGeneration     *RawPayload `json:"image_generation_call,omitempty"`
}

ResponseItem is a closed Responses API item. Exactly one typed pointer is set.

type SessionMeta 

type SessionMeta struct {
	ID                          string          `json:"id"`
	SessionID                   string          `json:"session_id"`
	ParentThreadID              string          `json:"parent_thread_id,omitempty"`
	ForkedFromID                string          `json:"forked_from_id,omitempty"`
	Timestamp                   *time.Time      `json:"timestamp,omitempty"`
	CWD                         string          `json:"cwd,omitempty"`
	CLIVersion                  string          `json:"cli_version,omitempty"`
	Source                      Source          `json:"source"`
	ThreadSource                string          `json:"thread_source,omitempty"`
	AgentPath                   string          `json:"agent_path,omitempty"`
	AgentNickname               string          `json:"agent_nickname,omitempty"`
	AgentRole                   string          `json:"agent_role,omitempty"`
	ModelProvider               *string         `json:"model_provider,omitempty"`
	HistoryMode                 string          `json:"history_mode,omitempty"`
	HistoryBase                 json.RawMessage `json:"history_base,omitempty"`
	SubagentHistoryStartOrdinal *int            `json:"subagent_history_start_ordinal,omitempty"`
	MultiAgentVersion           *string         `json:"multi_agent_version,omitempty"`
	Git                         *GitInfo        `json:"git,omitempty"`
	Raw                         json.RawMessage `json:"raw"`
}

type Shape 

type Shape struct {
	CLIVersions traceprocessing.Versions `json:"cli_versions"`
	Subtypes    map[string]int           `json:"subtypes,omitempty"`
	UnreadKeys  map[string]int           `json:"unread_keys,omitempty"`
}

func Survey 

func Survey(files []*File) Shape

type Source 

type Source struct {
	Unit        string          `json:"unit,omitempty"`
	Custom      string          `json:"custom,omitempty"`
	Internal    string          `json:"internal,omitempty"`
	Subagent    string          `json:"subagent,omitempty"`
	Other       string          `json:"other,omitempty"`
	ThreadSpawn *ThreadSpawn    `json:"thread_spawn,omitempty"`
	Raw         json.RawMessage `json:"raw"`
}

type SubAgentActivity 

type SubAgentActivity struct {
	EventID       string `json:"event_id"`
	AgentThreadID string `json:"agent_thread_id"`
	AgentPath     string `json:"agent_path"`
	Kind          string `json:"kind"`
}

type TaskComplete 

type TaskComplete struct {
	TurnID           string  `json:"turn_id"`
	LastAgentMessage *string `json:"last_agent_message,omitempty"`
}

type TaskStarted 

type TaskStarted struct {
	TurnID string `json:"turn_id"`
}

type ThreadClass 

type ThreadClass string

ThreadClass decides whether one rollout enters a session tree. 

const (
	ThreadRoot     ThreadClass = "root"
	ThreadChild    ThreadClass = "child"
	ThreadInternal ThreadClass = "internal"
)

func ClassifyThread 

func ClassifyThread(lines []Line) (ThreadClass, error)

ClassifyThread uses only the first session_meta.

type ThreadRolledBack 

type ThreadRolledBack struct {
	NumTurns int `json:"num_turns"`
}

type ThreadSettingsApplied 

type ThreadSettingsApplied struct {
	ThreadSettings json.RawMessage `json:"thread_settings"`
}

type ThreadSpawn 

type ThreadSpawn struct {
	ParentThreadID string  `json:"parent_thread_id"`
	Depth          int     `json:"depth"`
	AgentPath      *string `json:"agent_path"`
	AgentNickname  *string `json:"agent_nickname"`
	AgentRole      *string `json:"agent_role"`
}

type TokenCount 

type TokenCount struct {
	Info       *TokenInfo      `json:"info"`
	RateLimits json.RawMessage `json:"rate_limits,omitempty"`
}

type TokenInfo 

type TokenInfo struct {
	TotalTokenUsage    Usage  `json:"total_token_usage"`
	LastTokenUsage     Usage  `json:"last_token_usage"`
	ModelContextWindow *int64 `json:"model_context_window,omitempty"`
}

type TokenUsageRecord 

type TokenUsageRecord struct {
	ThreadID         string          `json:"thread_id,omitempty"`
	TurnID           string          `json:"turn_id,omitempty"`
	SessionID        string          `json:"session_id,omitempty"`
	RootTurnID       string          `json:"root_turn_id,omitempty"`
	ResponseID       string          `json:"response_id,omitempty"`
	Usage            Usage           `json:"usage"`
	TurnTokenUsage   Usage           `json:"turn_token_usage"`
	ThreadTokenUsage Usage           `json:"thread_token_usage"`
	Raw              json.RawMessage `json:"raw"`
}

TokenUsageRecord is the top-level per-request usage record newer Codex versions write a few lines before the matching token_count event. Usage is the request's own usage (token_count's last_token_usage) and ThreadTokenUsage is the thread's running total (token_count's total_token_usage).

type ToolSearchCall 

type ToolSearchCall struct {
	ID        string          `json:"id,omitempty"`
	CallID    string          `json:"call_id,omitempty"`
	Arguments json.RawMessage `json:"arguments"`
	Status    string          `json:"status,omitempty"`
	Execution string          `json:"execution,omitempty"`
}

type ToolSearchOutput 

type ToolSearchOutput struct {
	ID        string          `json:"id,omitempty"`
	CallID    string          `json:"call_id,omitempty"`
	Status    string          `json:"status,omitempty"`
	Execution string          `json:"execution,omitempty"`
	Tools     json.RawMessage `json:"tools,omitempty"`
}

type Tree 

type Tree struct {
	Root        *File
	Children    []*File
	ForkSources []*File
	// contains filtered or unexported fields
}

Tree is the explicitly listed, fully decoded rollout set for one session.

func DecodeFiles 

func DecodeFiles[T FileSources](fsys fs.FS, files T) (*Tree, error)

func DecodeFilesWith added in v0.2.0 

func DecodeFilesWith[T FileSources](files T, read ReadRollout) (*Tree, error)

DecodeFilesWith is DecodeFiles with each rollout read by read, which can continue an earlier Reading of it.

func DecodeLocalFiles 

func DecodeLocalFiles[T FileSources](files T) (*Tree, error)

func SingleFileTree 

func SingleFileTree(file *File) (*Tree, error)

func (*Tree) Files 

func (t *Tree) Files() []*File

Files returns the rollouts mapped into sessions, root first. Fork sources supply inherited-history boundaries but are not sessions of this tree.

func (*Tree) Rollout 

func (t *Tree) Rollout(threadID string) *File

type TurnAborted 

type TurnAborted struct {
	TurnID string `json:"turn_id"`
	Reason string `json:"reason,omitempty"`
}

type TurnContext 

type TurnContext struct {
	Fields map[string]json.RawMessage `json:"fields"`
	Raw    json.RawMessage            `json:"raw"`
}

TurnContext retains every top-level setting and provides typed accessors for the fields used while mapping.

func (*TurnContext) AttributeFields 

func (c *TurnContext) AttributeFields() map[string]json.RawMessage

AttributeFields returns the settings snapshot without the turn identity.

func (*TurnContext) CWD 

func (c *TurnContext) CWD() string

func (*TurnContext) Model 

func (c *TurnContext) Model() string

func (*TurnContext) String 

func (c *TurnContext) String(key string) string

func (*TurnContext) TurnID 

func (c *TurnContext) TurnID() string

type Usage 

type Usage struct {
	InputTokens           *int64 `json:"input_tokens,omitempty"`
	CachedInputTokens     *int64 `json:"cached_input_tokens,omitempty"`
	CacheWriteInputTokens *int64 `json:"cache_write_input_tokens,omitempty"`
	OutputTokens          *int64 `json:"output_tokens,omitempty"`
	ReasoningOutputTokens *int64 `json:"reasoning_output_tokens,omitempty"`
	TotalTokens           *int64 `json:"total_tokens,omitempty"`
}

type UserMessage 

type UserMessage struct {
	Message      string          `json:"message"`
	Images       json.RawMessage `json:"images,omitempty"`
	LocalImages  json.RawMessage `json:"local_images,omitempty"`
	Audio        json.RawMessage `json:"audio,omitempty"`
	LocalAudio   json.RawMessage `json:"local_audio,omitempty"`
	TextElements json.RawMessage `json:"text_elements,omitempty"`
}

type WebSearchCall 

type WebSearchCall struct {
	Status string          `json:"status,omitempty"`
	Action json.RawMessage `json:"action,omitempty"`
}

type WebSearchEnd 

type WebSearchEnd struct {
	CallID  string          `json:"call_id,omitempty"`
	Query   string          `json:"query,omitempty"`
	Action  json.RawMessage `json:"action,omitempty"`
	Results json.RawMessage `json:"results,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.