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
- func IsJSValue(id string) bool
- func IsLazy(entry SessionEntry) bool
- func IsNull(id string) bool
- func IsUndescribed(entry SessionEntry) (bool, error)
- func ReadRaw(entry FileEntry) (json.RawMessage, error)
- func ReadRaws(entries []SessionEntry) ([]json.RawMessage, error)
- func Truthy(id string) bool
- func ValueJSON(id string) (value json.RawMessage, ok bool)
- func WireID(id string) string
- type BashExecutionEntry
- type BashExecutionMessage
- type BranchSummaryEntry
- type CompactionEntry
- type ContextEditEntry
- type ContextEditReplacement
- type ContextEditableContent
- type CustomEntry
- type CustomMessageEntry
- type FileEntry
- type LabelEntry
- type LazyEntry
- type MessageEntry
- type ModelChangeEntry
- type NewSessionOptions
- type ProjectedSessionEntry
- type RawEntry
- type RecordAt
- type RecordChangedError
- type RecordSource
- type SessionContext
- type SessionContextModel
- type SessionEntry
- type SessionEntryBase
- type SessionHeader
- type SessionInfoEntry
- type SessionProjection
- type SessionTreeNode
- type ThinkingLevelEntry
- type UsageEntry
Constants ¶
const CurrentSessionVersion = 3
CurrentSessionVersion is session-manager.ts CURRENT_SESSION_VERSION.
Variables ¶
This section is empty.
Functions ¶
func IsJSValue ¶
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 ¶
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 ¶
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.
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 (e BranchSummaryEntry) Base() SessionEntryBase
func (BranchSummaryEntry) MarshalJSON ¶
func (e BranchSummaryEntry) MarshalJSON() ([]byte, error)
func (BranchSummaryEntry) Raw ¶
func (e BranchSummaryEntry) Raw() json.RawMessage
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"`
// 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 (e CompactionEntry) Base() SessionEntryBase
func (CompactionEntry) MarshalJSON ¶
func (e CompactionEntry) MarshalJSON() ([]byte, error)
func (CompactionEntry) Raw ¶
func (e CompactionEntry) Raw() json.RawMessage
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 (e ContextEditEntry) Base() SessionEntryBase
func (ContextEditEntry) MarshalJSON ¶
func (e ContextEditEntry) MarshalJSON() ([]byte, error)
func (ContextEditEntry) Raw ¶
func (e ContextEditEntry) Raw() json.RawMessage
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 (e CustomMessageEntry) Base() SessionEntryBase
func (CustomMessageEntry) MarshalJSON ¶
func (e CustomMessageEntry) MarshalJSON() ([]byte, error)
func (CustomMessageEntry) Raw ¶
func (e CustomMessageEntry) Raw() json.RawMessage
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 ¶
Indexed reports whether the entry was made by NewLazyEntry, not left zero.
func (*LazyEntry) MarshalJSON ¶
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 (e ModelChangeEntry) Base() SessionEntryBase
func (ModelChangeEntry) MarshalJSON ¶
func (e ModelChangeEntry) MarshalJSON() ([]byte, error)
func (ModelChangeEntry) Raw ¶
func (e ModelChangeEntry) Raw() json.RawMessage
type NewSessionOptions ¶
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 ¶
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 (e SessionInfoEntry) Base() SessionEntryBase
func (SessionInfoEntry) MarshalJSON ¶
func (e SessionInfoEntry) MarshalJSON() ([]byte, error)
func (SessionInfoEntry) Raw ¶
func (e SessionInfoEntry) Raw() json.RawMessage
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 (e ThinkingLevelEntry) Base() SessionEntryBase
func (ThinkingLevelEntry) MarshalJSON ¶
func (e ThinkingLevelEntry) MarshalJSON() ([]byte, error)
func (ThinkingLevelEntry) Raw ¶
func (e ThinkingLevelEntry) Raw() json.RawMessage
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