transcript

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 {
	Seq         int64
	ID          string
	Timestamp   time.Time
	Type        EntryType
	Message     agent.AgentMessage
	ToolCall    *ToolCall
	ToolOutcome *ToolOutcome
	Context     *ContextAttachment
	Compaction  *Compaction
	Lifecycle   *Lifecycle
}

Entry is one item in the session's linear, append-only history. Seq is -1 while an entry is being prepared and becomes contiguous when it commits.

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 NewRunEnd(runID string, status LifecycleStatus, reason string) Entry

func NewRunStart(runID string) Entry

func NewStepEnd(
	runID, turnID, stepID string,
	status LifecycleStatus,
	reason string,
) Entry

func NewStepStart(runID, turnID, stepID string) Entry

func NewToolCall(call ToolCall) Entry

func NewToolOutcome(outcome ToolOutcome) Entry

func NewTurnEnd(runID, turnID string, status LifecycleStatus, reason string) Entry

func NewTurnStart(runID, turnID string) Entry

func SequenceEntries(entries []Entry, firstSeq int64) ([]Entry, error)

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

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

func (e Entry) Validate() error

type EntryType ¶

type EntryType string

const (
	MessageEntry     EntryType = "message"
	ToolCallEntry    EntryType = "tool_call"
	ToolOutcomeEntry EntryType = "tool_outcome"
	ContextEntry     EntryType = "context"
	CompactionEntry  EntryType = "compaction"
	RunStartEntry    EntryType = "run/start"
	RunEndEntry      EntryType = "run/end"
	TurnStartEntry   EntryType = "turn/start"
	TurnEndEntry     EntryType = "turn/end"
	StepStartEntry   EntryType = "step/start"
	StepEndEntry     EntryType = "step/end"
)

type ForkMode ¶ added in v0.6.11

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() 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(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 Lifecycle ¶ added in v0.6.14

type Lifecycle struct {
	RunID  string          `json:"runId"`
	TurnID string          `json:"turnId,omitempty"`
	StepID string          `json:"stepId,omitempty"`
	Status LifecycleStatus `json:"status,omitempty"`
	Reason string          `json:"reason,omitempty"`
}

Lifecycle identifies one durable Run, Turn, or Step boundary. Entry.Type supplies the boundary kind; parent IDs make ownership explicit and stable.

type LifecycleStatus ¶ added in v0.6.14

type LifecycleStatus string

const (
	LifecycleCompleted   LifecycleStatus = "completed"
	LifecycleFailed      LifecycleStatus = "failed"
	LifecycleCancelled   LifecycleStatus = "cancelled"
	LifecycleInterrupted LifecycleStatus = "interrupted"
)

type Memory ¶

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

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

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

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

type PreparedAppend ¶ added in v0.6.14

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

PreparedAppend is a validated batch-local reducer delta. Commit installs it into its originating SessionValidator and must be called at most once.

func (p *PreparedAppend) Commit()

type ProjectedCompaction ¶ added in v0.6.14

type ProjectedCompaction struct {
	EntryID    string
	EntryIndex int
	RunID      string
	TurnID     string
	StepID     string
	Compaction Compaction
}

ProjectedCompaction records a durable summary boundary and its lifecycle ownership without applying model-context presentation rules.

type ProjectedContext ¶ added in v0.6.14

type ProjectedContext struct {
	EntryID    string
	EntryIndex int
	RunID      string
	TurnID     string
	StepID     string
	Attachment ContextAttachment
}

ProjectedContext associates one durable hidden context attachment with the lifecycle boundaries open when it was committed.

type ProjectedLifecycle ¶ added in v0.6.14

type ProjectedLifecycle struct {
	RunID  string
	TurnID string
	StepID string
}

ProjectedLifecycle identifies the currently open durable boundaries. An empty value means the committed prefix is at a clean session boundary.

type ProjectedMessage ¶ added in v0.6.14

type ProjectedMessage struct {
	EntryID    string
	EntryIndex int
	Timestamp  time.Time
	RunID      string
	TurnID     string
	StepID     string
	Message    agent.AgentMessage
}

ProjectedMessage associates a durable model message with the lifecycle boundaries open at its position. User and steering messages may have no StepID.

type ProjectedRun ¶ added in v0.6.14

type ProjectedRun struct {
	ID              string
	StartEntryID    string
	EndEntryID      string
	StartEntryIndex int
	EndEntryIndex   int
	StartedAt       time.Time
	CompletedAt     time.Time
	Status          LifecycleStatus
	Reason          string
	Turns           []ProjectedTurn
}

ProjectedRun is one run reconstructed from explicit lifecycle boundaries.

type ProjectedStep ¶ added in v0.6.14

type ProjectedStep struct {
	ID              string
	RunID           string
	TurnID          string
	StartEntryID    string
	EndEntryID      string
	StartEntryIndex int
	EndEntryIndex   int
	StartedAt       time.Time
	CompletedAt     time.Time
	Status          LifecycleStatus
	Reason          string
}

ProjectedStep is one assistant request-and-tools cycle inside a turn.

type ProjectedToolCall ¶ added in v0.6.14

type ProjectedToolCall struct {
	ToolCallID string
	ToolName   string
	Arguments  json.RawMessage
	RunID      string
	TurnID     string
	StepID     string

	AssistantMessageEntryID    string
	AssistantMessageEntryIndex int
	DispatchEntryID            string
	DispatchEntryIndex         int
	ResultMessageEntryID       string
	ResultEntryIndex           int
	OutcomeEntryID             string
	OutcomeEntryIndex          int
	Outcome                    *ToolOutcome
}

ProjectedToolCall joins the assistant request, optional durable dispatch intent, model-facing result, and optional product-facing outcome.

type ProjectedTurn ¶ added in v0.6.14

type ProjectedTurn struct {
	ID              string
	RunID           string
	StartEntryID    string
	EndEntryID      string
	StartEntryIndex int
	EndEntryIndex   int
	StartedAt       time.Time
	CompletedAt     time.Time
	Status          LifecycleStatus
	Reason          string
	Steps           []ProjectedStep
}

ProjectedTurn is one claimed unit of user or follow-up intent inside a run.

type ProjectionEvent ¶ added in v0.6.14

type ProjectionEvent struct {
	Entry      Entry
	EntryIndex int
	Scope      ProjectedLifecycle
	// contains filtered or unexported fields
}

ProjectionEvent is one validated event at its committed transcript position. Entry and Scope are immutable inputs to registered projections.

type ProjectionRegistry ¶ added in v0.6.14

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

ProjectionRegistry eagerly drives registered units over committed events. It is intentionally lock-free; the owning session journal serializes commit and snapshot access.

func NewProjectionRegistry() *ProjectionRegistry

func (r *ProjectionRegistry) Register(unit ProjectionUnit) error

func (r *ProjectionRegistry) Snapshot() (ProjectionSnapshot, error)

type ProjectionSnapshot ¶ added in v0.6.14

type ProjectionSnapshot struct {
	AsOfSeq int64
	Values  map[string]any
}

ProjectionSnapshot is one consistent read cut across all registered units.

type ProjectionUnit ¶ added in v0.6.14

type ProjectionUnit interface {
	ProjectionKey() string
	ApplyProjection(ProjectionEvent)
	SnapshotProjection() (any, error)
}

ProjectionUnit is one synchronous read model driven by every committed session event. ApplyProjection must be total: all fallible preparation is completed before persistence and the commit boundary. SnapshotProjection must return a value detached from the unit's live state.

type SessionProjection ¶ added in v0.6.14

type SessionProjection struct {
	AppliedEntries int
	AsOfSeq        int64
	Runs           []ProjectedRun
	Messages       []ProjectedMessage
	ToolCalls      []ProjectedToolCall
	Contexts       []ProjectedContext
	Compactions    []ProjectedCompaction
	Open           ProjectedLifecycle
}

SessionProjection is a deterministic snapshot of one committed transcript prefix. AsOfSeq identifies the last event included in the view.

func ProjectSession(entries []Entry) (*SessionProjection, error)

type SessionProjectionUnit ¶ added in v0.6.14

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

SessionProjectionUnit is the registered, incrementally maintained session read model.

func NewSessionProjectionUnit() *SessionProjectionUnit

func (u *SessionProjectionUnit) ApplyProjection(event ProjectionEvent)

func (*SessionProjectionUnit) ProjectionKey() string

func (u *SessionProjectionUnit) Snapshot() (*SessionProjection, error)

func (u *SessionProjectionUnit) SnapshotProjection() (any, error)

type SessionValidator ¶ added in v0.6.14

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

SessionValidator owns the canonical reducer for one committed event prefix. PrepareAppend validates against a batch-local delta that callers commit only after the same entries are durable.

func ValidateSession(entries []Entry) (*SessionValidator, error)

func (v *SessionValidator) NextSeq() int64

func (v *SessionValidator) PrepareAppend(entries []Entry) (*PreparedAppend, error)

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 ToolCall ¶ added in v0.6.14

type ToolCall struct {
	ToolCallID string          `json:"toolCallId"`
	ToolName   string          `json:"toolName"`
	Arguments  json.RawMessage `json:"arguments"`
}

ToolCall is a durable dispatch intent. Its presence means validation and authorization completed and the tool body may have started. Arguments are the normalized JSON value passed to the tool, not a presentation summary.

type ToolOutcome ¶ added in v0.6.8

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.