Documentation
¶
Overview ¶
Package transcript persists a conversation to an append-only JSONL log on disk and reconstructs it for resume. The main session is written to <dir>/<sessionID>.jsonl; each subagent is written to its own sidechain file under <dir>/<sessionID>/subagents/agent-<agentID>.jsonl, so subagent tokens are counted and stored separately (aggregate them offline if needed).
The log is the full-fidelity history: every user/assistant/tool message is recorded as it is born. When compaction inserts a boundary, the post-boundary working set — the boundary marker, the summary, and the kept recent tail — is ALSO persisted as messages, so a cold-start resume restores the COMPACTED view (via llm.MessagesForAPI, which slices from the last boundary) instead of replaying raw history and re-summarizing. The kept tail is re-recorded after the boundary (it also exists earlier as births); only the post-boundary copy reaches the model. Lightweight working-set edits that do not add a boundary (MicroCompact tool-result clearing) stay ephemeral and are not persisted. A separate Type=="boundary" record is written for observability and is skipped during reconstruction.
Index ¶
- func LastUUID(recs []Record) string
- func Messages(recs []Record) ([]llm.Message, llm.Usage)
- func NewAgentID() string
- func NewSessionID() string
- func SessionIDFrom(ctx context.Context) string
- func WithSessionID(ctx context.Context, sessionID string) context.Context
- type Record
- type Store
- func (s *Store) AgentPath(sessionID, agentID string) string
- func (s *Store) Append(path string, recs ...Record) error
- func (s *Store) Load(path string) ([]Record, error)
- func (s *Store) MainPath(sessionID string) string
- func (s *Store) NewWriter(sessionID, agentID string) *Writer
- func (s *Store) ResumeWriter(sessionID, lastUUID string) *Writer
- type Writer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Messages ¶
Messages reconstructs the raw conversation and cumulative usage from records. Boundary records are skipped — the working set is rebuilt by compaction on the next turn, not replayed from disk.
func SessionIDFrom ¶
SessionIDFrom returns the session id carried on ctx, or "" if none.
Types ¶
type Record ¶
type Record struct {
UUID string `json:"uuid"`
ParentUUID string `json:"parent_uuid,omitempty"`
SessionID string `json:"session_id"`
AgentID string `json:"agent_id,omitempty"`
IsSidechain bool `json:"is_sidechain,omitempty"`
Timestamp string `json:"timestamp"`
Type string `json:"type"` // "message" | "boundary"
Message *llm.Message `json:"message,omitempty"`
Usage *llm.Usage `json:"usage,omitempty"` // assistant turns only
Boundary *llm.BoundaryMeta `json:"boundary,omitempty"` // Type=="boundary"
}
Record is one line of a JSONL transcript.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a directory of session transcripts.
func (*Store) Append ¶
Append writes records to path as JSONL, creating parent directories. It is safe for concurrent use within the process.
func (*Store) Load ¶
Load reads all records from a transcript file. A missing file yields no records and no error (a fresh session).
func (*Store) NewWriter ¶
NewWriter returns a Writer for a fresh transcript file. agentID == "" writes the main session file; a non-empty agentID writes a subagent sidechain.
func (*Store) ResumeWriter ¶
ResumeWriter returns a Writer that continues an existing main-session file, chaining new records after lastUUID.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer binds a Store, a file path, and a session/agent identity, assigning a UUID and parent link to each record. It satisfies harness.Recorder. Append errors are retained (see Err) rather than panicking, so a failing disk degrades to in-memory operation instead of crashing the agent loop.
func (*Writer) RecordBoundary ¶
func (w *Writer) RecordBoundary(meta llm.BoundaryMeta)
RecordBoundary persists a compaction boundary for observability.
Source Files