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
• Variables
• func BuildContext(entries []Entry) ([]agent.AgentMessage, error)
• func Messages(entries []Entry) []agent.AgentMessage
• func NewID() string
• func SecurePrivatePermissions(dir string) error
• type Compaction
• type ContextAttachment
• type Entry
  • func Fork(entries []Entry, messageID string, mode ForkMode, replacementText string) ([]Entry, error)
  • func NewCompaction(compact Compaction) Entry
  • func NewContext(context ContextAttachment) Entry
  • func NewMessage(message agent.AgentMessage) Entry
  • func NewRun(firstEntryID string, startedAt, completedAt time.Time) Entry
  • func NewToolOutcome(outcome ToolOutcome) Entry
  • func (e Entry) MarshalJSON() ([]byte, error)
  • func (e *Entry) UnmarshalJSON(data []byte) error
  • func (e Entry) Validate() error
• type EntryType
• type ForkMode
• 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)
  • func (s *JSONL) Replace(_ context.Context, entries []Entry) error
• type Memory
  • func (m *Memory) Append(_ context.Context, entries ...Entry) error
  • func (m *Memory) Load(context.Context) ([]Entry, error)
• type Run
• type Store
• type ToolOutcome

Constants

const CurrentVersion = 3

Variables

var (
	// ErrForkMessageNotFound means the requested message ID is not in the transcript.
	ErrForkMessageNotFound = errors.New("transcript: fork message not found")
	// ErrInvalidForkBoundary means the requested fork would produce invalid context.
	ErrInvalidForkBoundary = errors.New("transcript: invalid fork boundary")
)

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

func SecurePrivatePermissions

func SecurePrivatePermissions(dir string) error

SecurePrivatePermissions enforces private modes for every transcript JSONL file in dir, including files that remain lazily unloaded.

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 Entry

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

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

func Fork

func Fork(entries []Entry, messageID string, mode ForkMode, replacementText string) ([]Entry, error)

Fork returns a transcript prefix at a visible message boundary without modifying the source entries. Editing replaces the selected user message with a newly identified message; branching after an assistant preserves the selected completed response.

func NewCompaction

func NewCompaction(compact Compaction) Entry

func NewContext

func NewContext(context ContextAttachment) Entry

func NewMessage

func NewMessage(message agent.AgentMessage) Entry

func NewRun

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

func NewToolOutcome

func NewToolOutcome(outcome ToolOutcome) 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"
	ToolOutcomeEntry EntryType = "tool_outcome"
	ContextEntry     EntryType = "context"
	CompactionEntry  EntryType = "compaction"
	RunEntry         EntryType = "run"
)

type ForkMode

type ForkMode string

ForkMode selects the visible message boundary retained in a fork.

const (
	// ForkBeforeUser replaces the selected user message and drops later entries.
	ForkBeforeUser ForkMode = "before_user"
	// ForkAfterAssistant keeps the selected completed assistant response.
	ForkAfterAssistant ForkMode = "after_assistant"
)

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)

func (*JSONL) Replace

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

Replace atomically installs entries as the complete session log. It is used for explicit history rewrites while the owning session is idle.

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 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.

type ToolOutcome

type ToolOutcome struct {
	ToolCallID string                  `json:"toolCallId"`
	Status     agent.ToolOutcomeStatus `json:"status"`
	ErrorCode  string                  `json:"errorCode,omitempty"`
	ExitCode   *int                    `json:"exitCode,omitempty"`
	DataKind   string                  `json:"dataKind,omitempty"`
	Data       json.RawMessage         `json:"data,omitempty"`
}

ToolOutcome records the product-facing result associated with one model- visible tool result. Data stays provider-neutral and is decoded by the engine according to DataKind.