transcript

Documentation

Overview

Package transcript defines the durable, append-only history of a coding session. The model-facing message list is a projection of these entries.

Index

• Constants
• func BuildContext(entries []Entry) ([]agent.AgentMessage, error)
• func Messages(entries []Entry) []agent.AgentMessage
• func NewID() string
• type Compaction
• type ContextAttachment
• type DetailsStore
• type Entry
  • func NewCompaction(compact Compaction) Entry
  • func NewContext(context ContextAttachment) Entry
  • func NewMessage(message agent.AgentMessage) Entry
  • func NewMessageWithInvocation(message agent.AgentMessage, invoked *invocation.Record) Entry
  • func NewRun(firstEntryID string, startedAt, completedAt time.Time) Entry
  • func (e Entry) MarshalJSON() ([]byte, error)
  • func (e *Entry) UnmarshalJSON(data []byte) error
  • func (e Entry) Validate() error
• type EntryType
• type Header
  • func NewHeader() Header
• type JSONL
  • func NewJSONL(path string) *JSONL
  • func (s *JSONL) Append(_ context.Context, entries ...Entry) error
  • func (s *JSONL) Load(_ context.Context) ([]Entry, error)
• type JSONLDetails
  • func NewJSONLDetails(path string) *JSONLDetails
  • func (s *JSONLDetails) Load(_ context.Context) (map[string]json.RawMessage, error)
  • func (s *JSONLDetails) Put(_ context.Context, callID string, payload json.RawMessage) error
• type Memory
  • func (m *Memory) Append(_ context.Context, entries ...Entry) error
  • func (m *Memory) Load(context.Context) ([]Entry, error)
• type MemoryDetails
  • func NewMemoryDetails() *MemoryDetails
  • func (m *MemoryDetails) Load(context.Context) (map[string]json.RawMessage, error)
  • func (m *MemoryDetails) Put(_ context.Context, callID string, payload json.RawMessage) error
• type Run
• type Store

Constants

const CurrentVersion = 3

Functions

func BuildContext

func BuildContext(entries []Entry) ([]agent.AgentMessage, error)

BuildContext projects the linear log into the messages sent to the model. Only the newest compaction boundary applies: its summary replaces the old prefix while original messages at and after FirstKeptEntryID remain verbatim.

func Messages

func Messages(entries []Entry) []agent.AgentMessage

Messages returns every original model message in the log. It omits compaction metadata and never exposes the synthetic summary message.

func NewID

func NewID() string

Types

type Compaction

type Compaction struct {
	Summary           string    `json:"summary"`
	FirstKeptEntryID  string    `json:"firstKeptEntryId"`
	TokensBefore      int64     `json:"tokensBefore"`
	TokensAfter       int64     `json:"tokensAfter"`
	ReadFiles         []string  `json:"readFiles,omitempty"`
	ModifiedFiles     []string  `json:"modifiedFiles,omitempty"`
	Provider          string    `json:"provider,omitempty"`
	Model             string    `json:"model,omitempty"`
	ResponseModel     string    `json:"responseModel,omitempty"`
	ResponseID        string    `json:"responseId,omitempty"`
	Usage             llm.Usage `json:"usage,omitempty"`
	ResponseTimestamp time.Time `json:"responseTimestamp,omitempty"`
}

Compaction records a summary boundary without deleting the entries it summarizes. FirstKeptEntryID points at the first original message retained in the active model context.

type ContextAttachment

type ContextAttachment struct {
	AttachmentID string `json:"attachmentId"`
	Epoch        uint64 `json:"epoch"`
	Kind         string `json:"kind"`
	Placement    string `json:"placement"`
	Path         string `json:"path,omitempty"`
	Revision     string `json:"revision"`
	Rendered     string `json:"rendered"`
}

ContextAttachment records one product-generated model-context block without representing it as a user-authored conversation message. Epoch increments when a session process rebuilds its context snapshot. Placement describes how the model-input projector positions the rendered block.

type DetailsStore

type DetailsStore interface {
	// Load returns every stored payload keyed by tool-call ID.
	Load(ctx context.Context) (map[string]json.RawMessage, error)
	// Put records one tool call's payload. A later Put for the same ID wins.
	Put(ctx context.Context, callID string, payload json.RawMessage) error
}

DetailsStore persists machine-readable tool outcomes out of band from the transcript, keyed by tool-call ID. The transcript itself carries only the model-facing result and legacy IsError bit; status, error metadata, exit code, and structured data live here so a reloaded session restores the same state it showed live. The name is retained because existing sessions use a .details.jsonl sidecar. A nil DetailsStore makes history derive status from the transcript and replay without structured data.

type Entry

type Entry struct {
	ID         string
	Timestamp  time.Time
	Type       EntryType
	Message    agent.AgentMessage
	Invocation *invocation.Record
	Context    *ContextAttachment
	Compaction *Compaction
	Run        *Run
}

Entry is one item in the session's linear, append-only history.

func NewCompaction

func NewCompaction(compact Compaction) Entry

func NewContext

func NewContext(context ContextAttachment) Entry

func NewMessage

func NewMessage(message agent.AgentMessage) Entry

func NewMessageWithInvocation

func NewMessageWithInvocation(
	message agent.AgentMessage,
	invoked *invocation.Record,
) Entry

func NewRun

func NewRun(firstEntryID string, startedAt, completedAt time.Time) Entry

func (Entry) MarshalJSON

func (e Entry) MarshalJSON() ([]byte, error)

func (*Entry) UnmarshalJSON

func (e *Entry) UnmarshalJSON(data []byte) error

func (Entry) Validate

func (e Entry) Validate() error

type EntryType

type EntryType string

const (
	MessageEntry    EntryType = "message"
	ContextEntry    EntryType = "context"
	CompactionEntry EntryType = "compaction"
	RunEntry        EntryType = "run"
)

type Header

type Header struct {
	Type    string `json:"type"`
	Version int    `json:"version"`
}

Header is the first line of a session log.

func NewHeader

func NewHeader() Header

type JSONL

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

JSONL persists a session log: one header followed by typed append-only entries.

func NewJSONL

func NewJSONL(path string) *JSONL

func (*JSONL) Append

func (s *JSONL) Append(_ context.Context, entries ...Entry) error

func (*JSONL) Load

func (s *JSONL) Load(_ context.Context) ([]Entry, error)

type JSONLDetails

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

JSONLDetails persists tool-call payloads as JSON Lines, one record per line, appended as tools finish. On Load the last record for an ID wins, so a re-emitted result supersedes an earlier one. It is safe for concurrent use.

func NewJSONLDetails

func NewJSONLDetails(path string) *JSONLDetails

NewJSONLDetails returns a DetailsStore backed by the file at path. The file is created on first write and need not exist yet.

func (*JSONLDetails) Load

func (s *JSONLDetails) Load(_ context.Context) (map[string]json.RawMessage, error)

Load reads all persisted payloads. A missing file is an empty map, not an error.

func (*JSONLDetails) Put

func (s *JSONLDetails) Put(_ context.Context, callID string, payload json.RawMessage) error

Put appends one payload record to the file.

type Memory

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

Memory is an in-process Store useful for tests and ephemeral sessions.

func (*Memory) Append

func (m *Memory) Append(_ context.Context, entries ...Entry) error

func (*Memory) Load

func (m *Memory) Load(context.Context) ([]Entry, error)

type MemoryDetails

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

MemoryDetails is an in-process DetailsStore for tests and ephemeral sessions.

func NewMemoryDetails

func NewMemoryDetails() *MemoryDetails

NewMemoryDetails returns an empty in-memory DetailsStore.

func (*MemoryDetails) Load

func (m *MemoryDetails) Load(context.Context) (map[string]json.RawMessage, error)

func (*MemoryDetails) Put

func (m *MemoryDetails) Put(_ context.Context, callID string, payload json.RawMessage) error

type Run

type Run struct {
	FirstEntryID string    `json:"firstEntryId,omitempty"`
	StartedAt    time.Time `json:"startedAt"`
	CompletedAt  time.Time `json:"completedAt"`
}

Run records the wall-clock interval for one agent invocation. FirstEntryID associates the timing with the messages appended by that run without adding product-only metadata to the model messages themselves.

type Store

type Store interface {
	Load(ctx context.Context) ([]Entry, error)
	Append(ctx context.Context, entries ...Entry) error
}

Store persists typed transcript entries. Compaction is an appended entry; it never replaces or removes original messages. A nil Store disables persistence.