sessionentry

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package sessionentry holds the session log's entry values (core/session-manager.ts SessionHeader, SessionEntry and the entry types). It imports nothing from the coding-agent packages, so the extension API can type its events with them.

Index

Constants

View Source
const CurrentSessionVersion = 3

CurrentSessionVersion is session-manager.ts CURRENT_SESSION_VERSION.

Variables

This section is empty.

Functions

func IsJSValue

func IsJSValue(id string) bool

IsJSValue reports whether id is the key of a non-string JavaScript value rather than a string.

func IsLazy

func IsLazy(entry SessionEntry) bool

IsLazy reports whether entry is a LazyEntry: a message entry whose base members came from an index and whose record has not been read.

func IsNull

func IsNull(id string) bool

IsNull reports whether id is the key of null: an entry whose id is null leaves Pi's leafId null.

func IsUndescribed

func IsUndescribed(entry SessionEntry) (bool, error)

IsUndescribed reports whether entry is a RawEntry: a record no member of the union describes. A LazyEntry is read and decoded to tell.

func ReadRaw

func ReadRaw(entry FileEntry) (json.RawMessage, error)

ReadRaw is entry's record. It is Raw, with the error of a LazyEntry whose record changed on disk.

func ReadRaws

func ReadRaws(entries []SessionEntry) ([]json.RawMessage, error)

ReadRaws is the record of each entry, reading the records of LazyEntry values of one source together in source order.

func Truthy

func Truthy(id string) bool

Truthy reports whether the value id stands for is truthy, as getBranch's `startId ?` and the walks' `current.parentId ?` test it: the empty string, undefined, null, false and zero are falsy.

func ValueJSON

func ValueJSON(id string) (value json.RawMessage, ok bool)

ValueJSON is what JSON.stringify writes for the value id stands for; ok is false for undefined, whose member JSON.stringify omits.

func WireID

func WireID(id string) string

WireID is id as a host-call string: a string id is itself, an undefined or null one is "", as a null leaf is, and any other value is the text JSON.stringify writes for it.

Types

type BashExecutionEntry

type BashExecutionEntry struct {
	SessionEntryBase
	Role               string `json:"-"` // always "bashExecution"; set on read
	Command            string `json:"-"`
	Output             string `json:"-"`
	ExitCode           *int   `json:"-"`
	Cancelled          bool   `json:"-"`
	Truncated          bool   `json:"-"`
	FullOutputPath     string `json:"-"`
	ExcludeFromContext *bool  `json:"-"` // nil when the record carries no excludeFromContext member (messages.ts:39 optional)
	MessageTimestamp   int64  `json:"-"`
}

BashExecutionEntry persists a user shell invocation as a message with role bashExecution, matching packages/coding-agent/src/core/session-manager.ts:appendMessage. ExcludeFromContext retains the entry in the transcript but excludes it from LLM conversion.

func (BashExecutionEntry) MarshalJSON

func (b BashExecutionEntry) MarshalJSON() ([]byte, error)

MarshalJSON serializes to upstream's wire shape (type:"message" + nested).

func (*BashExecutionEntry) UnmarshalJSON

func (b *BashExecutionEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts BOTH the new wire shape (type:"message" with inner role:"bashExecution") AND the legacy pig shape (type:"bash_execution" with flat top-level fields), so older session files still load.

type BashExecutionMessage

type BashExecutionMessage struct {
	Role               string `json:"role"` // "bashExecution"
	Command            string `json:"command"`
	Output             string `json:"output"`
	ExitCode           *int   `json:"exitCode,omitempty"`
	Cancelled          bool   `json:"cancelled"`
	Truncated          bool   `json:"truncated"`
	FullOutputPath     string `json:"fullOutputPath,omitempty"`
	Timestamp          int64  `json:"timestamp"`
	ExcludeFromContext *bool  `json:"excludeFromContext,omitempty"`
}

BashExecutionMessage is the inner `message` payload upstream uses for bash entries. Mirrors messages.ts:29-43 byte-for-byte.

func (BashExecutionMessage) MessageRole

func (BashExecutionMessage) MessageRole() string

MessageRole is "bashExecution": a BashExecutionMessage is a codingagent.SessionMessage.

type BranchSummaryEntry

type BranchSummaryEntry struct {
	SessionEntryBase
	FromID   string    `json:"fromId"`
	Summary  string    `json:"summary"`
	Details  any       `json:"details,omitempty"`
	Usage    *ai.Usage `json:"usage,omitempty"`
	FromHook bool      `json:"fromHook"`
	// contains filtered or unexported fields
}

BranchSummaryEntry member order matches Pi's branchWithSummary object literal (session-manager.ts:1612-1622); fromHook is always written because navigateTree passes fromExtension as a boolean (agent-session.ts:4110-4114).

func (BranchSummaryEntry) Base

func (BranchSummaryEntry) MarshalJSON

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

func (BranchSummaryEntry) Raw

func (*BranchSummaryEntry) UnmarshalJSON

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

UnmarshalJSON keeps the member order of `details`, the object the summarizer or an extension's session_before_tree result supplied, so a session_tree event re-sends it as written (Pi passes the stored entry object).

type CompactionEntry

type CompactionEntry struct {
	SessionEntryBase
	Summary          string    `json:"summary"`
	FirstKeptEntryID string    `json:"firstKeptEntryId"`
	TokensBefore     int       `json:"tokensBefore"`
	Details          any       `json:"details,omitempty"`
	Usage            *ai.Usage `json:"usage,omitempty"`
	FromHook         bool      `json:"fromHook"`
	// FromHookAbsent leaves the fromHook member out when the entry is written: Pi's `fromHook?: boolean` left undefined by an extension's appendCompaction.
	FromHookAbsent bool `json:"-"`
	// SystemMessage is the complete prompt and tool state at this compaction
	// boundary. It is absent when the projected context has no system state.
	SystemMessage json.RawMessage `json:"systemMessage,omitempty"`
}

CompactionEntry field order matches Pi's appendCompaction object literal so Pig-written entries serialize with the same key order.

func (CompactionEntry) Base

func (CompactionEntry) MarshalJSON

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

func (CompactionEntry) Raw

func (*CompactionEntry) UnmarshalJSON

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

UnmarshalJSON keeps the member order of `details`, the object an extension wrote (session-manager.ts appendCompaction).

func (CompactionEntry) WithoutRecord

func (e CompactionEntry) WithoutRecord() CompactionEntry

WithoutRecord is e without the record it was decoded from: it writes its fields.

type ContextEditEntry

type ContextEditEntry struct {
	SessionEntryBase
	TargetID    string                  `json:"targetId"`
	Replacement *ContextEditReplacement `json:"replacement"`
}

ContextEditEntry is an append-only change to one earlier entry's contribution to model context (session-manager.ts ContextEditEntry). A nil Replacement serializes as null and omits the target from model context; a replacement changes only the target's content. The target entry itself is never rewritten.

func (ContextEditEntry) Base

func (ContextEditEntry) MarshalJSON

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

func (ContextEditEntry) Raw

type ContextEditReplacement

type ContextEditReplacement struct {
	Content ContextEditableContent `json:"content"`
}

ContextEditReplacement is the non-null replacement of a context_edit entry (session-manager.ts ContextEditEntry.replacement). Content is the JSON string or content-block array that replaces the target's content (ContextEditableContent).

type ContextEditableContent

type ContextEditableContent = json.RawMessage

ContextEditableContent is the content a context edit may replace: a user, assistant, tool-result or custom message's content, a JSON string or block array. It stays raw JSON until the projection decodes it for the target's role. upstream: session-manager.ts:168 ContextEditableContent

type CustomEntry

type CustomEntry struct {
	SessionEntryBase
	CustomType string `json:"customType"`
	Data       any    `json:"data,omitempty"`
}

func (CustomEntry) Base

func (e CustomEntry) Base() SessionEntryBase

func (CustomEntry) MarshalJSON

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

func (CustomEntry) Raw

func (e CustomEntry) Raw() json.RawMessage

func (*CustomEntry) UnmarshalJSON

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

UnmarshalJSON keeps the member order of `data`, the object an extension wrote (session-manager.ts appendCustomEntry).

type CustomMessageEntry

type CustomMessageEntry struct {
	SessionEntryBase
	CustomType string `json:"customType"`
	Content    any    `json:"content"` // string | []ContentBlock
	Display    bool   `json:"display"`
	Details    any    `json:"details,omitempty"`
}

func (CustomMessageEntry) Base

func (CustomMessageEntry) MarshalJSON

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

func (CustomMessageEntry) Raw

func (*CustomMessageEntry) UnmarshalJSON

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

UnmarshalJSON keeps the member order of `details`, the object an extension wrote (session-manager.ts appendCustomMessageEntry).

type FileEntry

type FileEntry interface {
	json.Marshaler
	// Raw is the record's JSON.
	Raw() json.RawMessage
	// contains filtered or unexported methods
}

FileEntry is session-manager.ts FileEntry, `SessionHeader | SessionEntry`: one record of a session file. The members are SessionHeader and the members of SessionEntry.

func DecodeFileEntry

func DecodeFileEntry(raw json.RawMessage) FileEntry

DecodeFileEntry reads one record of a session file: the header when it has type "session" and a string id (loadEntriesFromFile checks no more), else the entry DecodeSessionEntry reads.

type LabelEntry

type LabelEntry struct {
	SessionEntryBase
	TargetID string  `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

LabelEntry is upstream's "user-renamed this branch" marker. Carries nil Label to delete a previously-set label.

func (LabelEntry) Base

func (e LabelEntry) Base() SessionEntryBase

func (LabelEntry) MarshalJSON

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

func (LabelEntry) Raw

func (e LabelEntry) Raw() json.RawMessage

type LazyEntry

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

LazyEntry is a message entry whose record stays in its source until it is read: Raw and MarshalJSON read the record, and AsMessage and Materialize decode it into the member DecodeSessionEntry gives it. Its base members are known without the record.

func NewLazyEntry

func NewLazyEntry(id string, parentID *string, timestamp string, src RecordSource, at RecordAt) LazyEntry

NewLazyEntry is the entry of a message record with the given id, parentId and timestamp, read from src at at.

func (*LazyEntry) Base

func (e *LazyEntry) Base() SessionEntryBase

func (*LazyEntry) Indexed

func (e *LazyEntry) Indexed() bool

Indexed reports whether the entry was made by NewLazyEntry, not left zero.

func (*LazyEntry) MarshalJSON

func (e *LazyEntry) MarshalJSON() ([]byte, error)

MarshalJSON writes the record as it was read.

func (*LazyEntry) Raw

func (e *LazyEntry) Raw() json.RawMessage

Raw reads the record. It panics with a *RecordChangedError when the record changed on disk; code that reads entries a session returns uses ReadRaw, AsMessage or Materialize, which return that error.

type MessageEntry

type MessageEntry struct {
	SessionEntryBase
	Message agent.AgentMessage `json:"message"`
}

func AsMessage

func AsMessage(entry SessionEntry) (message MessageEntry, ok bool, err error)

AsMessage is entry as a MessageEntry: ok is false for any other entry and for a message entry whose record does not decode. A LazyEntry is read and decoded; err reports a record that changed on disk.

func NewDecodedMessageEntry

func NewDecodedMessageEntry(base SessionEntryBase, decoded agent.AgentMessage, raw json.RawMessage) (MessageEntry, bool)

NewDecodedMessageEntry is the entry DecodeSessionEntry(raw) returns for the record raw, which encodes base and message, when decoded is the message that record decodes to. The record is not parsed again. It reports false for a base whose id or parent id stands for a JavaScript value, which decoding reads from the record. pig additive (D112): see agent.AgentMessage.DecodedForm.

func WithRecord

func WithRecord(entry MessageEntry, raw json.RawMessage) MessageEntry

WithRecord is entry with raw as its record: the record a session encoded from entry, so the entry stands for it as Pi's appended object does.

func (MessageEntry) AppendStringify

func (e MessageEntry) AppendStringify(dst []byte) ([]byte, error)

AppendStringify appends the JSON.stringify text of MarshalJSON's output to dst (json.StringifyAppender): the message is encoded into dst itself rather than apart.

func (MessageEntry) Base

func (e MessageEntry) Base() SessionEntryBase

func (MessageEntry) MarshalJSON

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

func (MessageEntry) Raw

func (e MessageEntry) Raw() json.RawMessage

type ModelChangeEntry

type ModelChangeEntry struct {
	SessionEntryBase
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

func (ModelChangeEntry) Base

func (ModelChangeEntry) MarshalJSON

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

func (ModelChangeEntry) Raw

type NewSessionOptions

type NewSessionOptions struct {
	ID            *string
	ParentSession string
}

NewSessionOptions are the options of Session.NewSession. A nil ID generates one. Mirrors upstream NewSessionOptions (core/session-manager.ts:52).

type ProjectedSessionEntry

type ProjectedSessionEntry struct {
	SourceEntry SessionEntry
	Messages    []agent.AgentMessage
}

ProjectedSessionEntry pairs a raw append-only entry with the model-visible messages it contributes after context edits (session-manager.ts ProjectedSessionEntry). Messages is empty for state-only entries and omissions.

type RawEntry

type RawEntry struct {
	SessionEntryBase
}

RawEntry is a record of a session file that no member of the union describes: a type this build does not know, a known type whose members do not decode into its entry (Pi casts the parsed JSON and checks no member), or JSON that is not an object. Pi keeps the parsed value whatever it is (session-manager.ts parseSessionEntries, loadEntriesFromFile), and so does the record: Raw is the JSON as read, and the base holds the members of it that decode.

func (RawEntry) Base

func (e RawEntry) Base() SessionEntryBase

func (RawEntry) MarshalJSON

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

MarshalJSON writes the record as it was read.

func (RawEntry) Raw

func (e RawEntry) Raw() json.RawMessage

Raw is the record's JSON as it was read.

type RecordAt

type RecordAt struct {
	// Off and Size are where the record lies in its source, and Hash the source's hash of its bytes.
	Off  int64
	Size int32
	Hash uint64
}

RecordAt locates a record in a RecordSource and identifies its bytes.

type RecordChangedError

type RecordChangedError struct {
	// ID is the entry's id, empty when the error is about no one record.
	ID  string
	Err error
}

RecordChangedError reports a record that cannot be read back as it was indexed: the session file was changed or removed under the session.

func (*RecordChangedError) Error

func (e *RecordChangedError) Error() string

func (*RecordChangedError) Unwrap

func (e *RecordChangedError) Unwrap() error

type RecordSource

type RecordSource interface {
	// ReadRecords sets out[i] to the record at ats[i]; out has the length of ats. On an error, bad is the index of the record it is about, or
	// -1 when it is about none.
	ReadRecords(ats []RecordAt, out []json.RawMessage) (bad int, err error)
}

RecordSource reads records back, verified against the place and hash they were indexed with.

type SessionContext

type SessionContext struct {
	Messages      []agent.AgentMessage `json:"messages"`
	ThinkingLevel string               `json:"thinkingLevel"`
	Model         *SessionContextModel `json:"model"`
}

SessionContext contains model-visible messages and the settings on their full branch path.

type SessionContextModel

type SessionContextModel struct {
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

SessionContextModel is the model identity last selected on a branch.

type SessionEntry

type SessionEntry interface {
	FileEntry
	// Base is the type, id, parentId and timestamp every entry has.
	Base() SessionEntryBase
}

SessionEntry is session-manager.ts SessionEntry, the union of MessageEntry (SessionMessageEntry), ThinkingLevelEntry (ThinkingLevelChangeEntry), ModelChangeEntry, UsageEntry, CompactionEntry, BranchSummaryEntry, CustomEntry, CustomMessageEntry, ContextEditEntry, LabelEntry and SessionInfoEntry. RawEntry is the one more implementation: the record a file holds that none of them describes.

func DecodeSessionEntry

func DecodeSessionEntry(raw json.RawMessage) SessionEntry

DecodeSessionEntry reads one entry record into the member of SessionEntry its type names, keeping the record so the entry writes back as it was read. Pi casts whatever JSON.parse returns and checks no member (session-manager.ts parseSessionEntries), so an id or parentId that is no string keeps its JavaScript value's key (see jsValueMark). A record that is not an object, or whose other members do not decode into the member its type names, is a RawEntry.

func Materialize

func Materialize(entry SessionEntry) (SessionEntry, error)

Materialize is entry with a LazyEntry read and decoded into the member DecodeSessionEntry gives its record (a MessageEntry, or a RawEntry when the message does not decode); any other entry is itself.

func MaterializeAll

func MaterializeAll(entries []SessionEntry) ([]SessionEntry, error)

MaterializeAll is Materialize of each entry, reading the records of LazyEntry values together and decoding a long run of them on several goroutines, joined before it returns; the error is the one of the first entry that fails. It returns entries itself when none is lazy.

type SessionEntryBase

type SessionEntryBase struct {
	Type      string  `json:"type"`
	ID        string  `json:"id"`
	ParentID  *string `json:"parentId"`
	Timestamp string  `json:"timestamp"`
	// contains filtered or unexported fields
}

SessionEntryBase is the common prefix on every non-header entry. `ParentID` is `*string` (not "") so we can distinguish "root entry" (parentId: null) from "missing field". The wire format requires `"parentId": null` literally for roots.

func WithJSValues

func WithJSValues(raw json.RawMessage, base SessionEntryBase) SessionEntryBase

WithJSValues is base, decoded from raw as a string-typed SessionEntryBase, with an absent parentId undefined and an id that is absent or null its JavaScript value's key: the string decode reads both as nil or "".

type SessionHeader

type SessionHeader struct {
	Type      string `json:"type"` // always "session"
	Version   int    `json:"version,omitempty"`
	ID        string `json:"id"`
	Timestamp string `json:"timestamp"`
	CWD       string `json:"cwd"`
	// ParentSession holds the absolute path of the SOURCE jsonl on a
	// clone (separate JSONL with linear path-to-leaf snapshot). Empty
	// on plain Create.
	ParentSession string `json:"parentSession,omitempty"`
	// contains filtered or unexported fields
}

func DecodeSessionHeader

func DecodeSessionHeader(raw json.RawMessage) (SessionHeader, error)

DecodeSessionHeader reads a header record, keeping the record. A version that is not a number is accepted: migrateToCurrentVersion's comparisons are then false, no migration step runs, and the header counts as current.

func (SessionHeader) MarshalJSON

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

func (SessionHeader) Raw

func (e SessionHeader) Raw() json.RawMessage

func (SessionHeader) SameRecord

func (e SessionHeader) SameRecord(other SessionHeader) bool

SameRecord reports whether e and other have equal members and decoded records, so they encode to the same bytes. It does not encode either.

type SessionInfoEntry

type SessionInfoEntry struct {
	SessionEntryBase
	Name string `json:"name"`
}

SessionInfoEntry stores a session-level name (set via `/name`). Persisted as type=session_info so it survives across resumes.

func (SessionInfoEntry) Base

func (SessionInfoEntry) MarshalJSON

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

func (SessionInfoEntry) Raw

type SessionProjection

type SessionProjection struct {
	Entries  []ProjectedSessionEntry
	Messages []agent.AgentMessage
	// ThinkingLevel and Model are the latest settings on the projected branch; ThinkingLevel is "off" and Model nil when the branch has none.
	ThinkingLevel string
	Model         *SessionContextModel
	// HasContextEdits reports that Entries holds a context_edit entry: usage recorded before the edit no longer describes the projected context.
	HasContextEdits bool
}

SessionProjection is the provenance-preserving, compaction-aware model context of one branch (session-manager.ts SessionProjection).

type SessionTreeNode

type SessionTreeNode struct {
	Entry    SessionEntry
	Children []*SessionTreeNode
	Label    string
	// LabelTimestamp is the on-disk timestamp of the LabelEntry that
	// set Label, in upstream's ISO-8601-ish wire format. Empty when
	// no label is set. Used by the /tree picker to render `hh:mm`
	// next to the label when the user toggles label timestamps on
	// (mirrors upstream tree-selector.ts:678-682).
	LabelTimestamp string
}

SessionTreeNode is a defensive copy of the session's branch structure for the /tree overlay (follow-up).

type ThinkingLevelEntry

type ThinkingLevelEntry struct {
	SessionEntryBase
	ThinkingLevel string `json:"thinkingLevel"`
}

ThinkingLevelEntry records a user-initiated thinking level change (Shift+Tab). Mirrors upstream appendThinkingLevelChange in agent-session.ts. Persisted as type="thinking_level_change" so the session tree can display [thinking: level].

func (ThinkingLevelEntry) Base

func (ThinkingLevelEntry) MarshalJSON

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

func (ThinkingLevelEntry) Raw

type UsageEntry

type UsageEntry struct {
	SessionEntryBase
	// Kind is an arbitrary usage category, such as "cache_warm".
	Kind     string   `json:"kind"`
	Provider string   `json:"provider"`
	Model    string   `json:"model"`
	Usage    ai.Usage `json:"usage"`
	// Note is an optional human-readable qualifier for usage notices.
	Note string `json:"note,omitempty"`
}

UsageEntry is model-attributed usage that does not enter LLM context, such as a cache-warming refresh. Mirrors upstream session-manager.ts UsageEntry.

func (UsageEntry) Base

func (e UsageEntry) Base() SessionEntryBase

func (UsageEntry) MarshalJSON

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

func (UsageEntry) Raw

func (e UsageEntry) Raw() json.RawMessage

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL