harness

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const BranchSummaryPreamble = `The user explored a different conversation branch before returning here.
Summary of that exploration:

`
View Source 
const BranchSummaryPrompt = `` /* 689-byte string literal not displayed */
View Source 
const SummarizationPrompt = `` /* 879-byte string literal not displayed */
View Source 
const SummarizationSystemPrompt = `` /* 310-byte string literal not displayed */
View Source 
const TurnPrefixSummarizationPrompt = `` /* 440-byte string literal not displayed */
View Source 
const UpdateSummarizationPrompt = `` /* 1257-byte string literal not displayed */

Variables

View Source 
var DefaultCompactionSettings = CompactionSettings{
	Enabled:          true,
	ReserveTokens:    16384,
	KeepRecentTokens: 20000,
}

Functions

func CalculateContextTokens 

func CalculateContextTokens(usage ai.Usage) int64

func CompleteSimpleWithRetries 

func CompleteSimpleWithRetries(
	ctx context.Context,
	complete CompleteFunc,
	model *ai.Model,
	request ai.Context,
	options *ai.SimpleStreamOptions,
	retry *ai.RetryPolicy,
	callbacks *ai.RetryCallbacks,
) (*ai.AssistantMessage, error)

CompleteSimpleWithRetries applies the shared assistant retry policy to one harness completion request.

func ContextMessages 

func ContextMessages(entries []SessionEntry) engine.AgentMessages

func DecodeSessionV4Header 

func DecodeSessionV4Header(line []byte) (SessionV4Header, *SessionV4DecodeError)

DecodeSessionV4Header decodes and validates a v4 header line, mirroring upstream parseHeader: failures carry no file or line context.

func DecodeSessionV4Mutation 

func DecodeSessionV4Mutation(line []byte) (SessionV4Mutation, *SessionV4DecodeError)

DecodeSessionV4Mutation decodes one v4 mutation line, mirroring upstream parseMutation: failures carry no file or line context.

func EstimateTokens 

func EstimateTokens(message engine.AgentMessage) int64

func FindTurnStartIndex 

func FindTurnStartIndex(entries []SessionEntry, entryIndex, startIndex int) int

func FormatFileOperations 

func FormatFileOperations(readFiles, modifiedFiles []string) string

func FormatPromptTemplateInvocation 

func FormatPromptTemplateInvocation(template PromptTemplate, args []string) string

FormatPromptTemplateInvocation follows the harness's sequential replacement passes; unlike coding-agent templates, the harness treats default syntax as literal text and later passes can expand placeholders introduced earlier.

func FormatSkillInvocation 

func FormatSkillInvocation(skill Skill, additionalInstructions string) string

FormatSkillInvocation embeds a loaded skill and optional explicit instructions.

func GenerateSummary 

func GenerateSummary(
	ctx context.Context,
	messages engine.AgentMessages,
	model *ai.Model,
	complete CompleteFunc,
	reserveTokens int64,
	customInstructions string,
	previousSummary *string,
	thinkingLevel ai.ModelThinkingLevel,
) (string, error)

func LoadSourcedPromptTemplates 

func LoadSourcedPromptTemplates[T any](env ResourceFileSystem, inputs []SourcedPromptTemplateInput[T], mapTemplate ...func(PromptTemplate, T) PromptTemplate) ([]SourcedPromptTemplate[T], []SourcedPromptTemplateDiagnostic[T])

func LoadSourcedSkills 

func LoadSourcedSkills[T any](env ResourceFileSystem, inputs []SourcedSkillInput[T], mapSkill ...func(Skill, T) Skill) ([]SourcedSkill[T], []SourcedSkillDiagnostic[T])

func MarshalSessionJSONL 

func MarshalSessionJSONL(storage SessionStorage, cwd string) ([]byte, error)

MarshalSessionJSONL serializes a non-byte-backed session using the harness object insertion order. cwd supplies the coding-session context omitted by generic in-memory harness metadata.

func MarshalSessionTreeEntry 

func MarshalSessionTreeEntry(entry SessionTreeEntry) ([]byte, error)

MarshalSessionTreeEntry serializes one entry with upstream field order. Exported for module embedders; not referenced inside this repo.

func MarshalSessionV4Header 

func MarshalSessionV4Header(header SessionV4Header) ([]byte, error)

MarshalSessionV4Header serializes a header with upstream's member order.

func MarshalSessionV4Mutation 

func MarshalSessionV4Mutation(mutation SessionV4Mutation) ([]byte, error)

MarshalSessionV4Mutation serializes one mutation with upstream member order.

func SerializeConversation 

func SerializeConversation(messages engine.AgentMessages) string

func ShouldCompact 

func ShouldCompact(contextTokens int64, contextWindow float64, settings CompactionSettings) bool

Types

type BashExecutionMessage 

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

type BranchPreparation 

type BranchPreparation struct {
	Messages    engine.AgentMessages
	FileOps     FileOperations
	TotalTokens int64
}

func PrepareBranchEntries 

func PrepareBranchEntries(entries []SessionEntry, tokenBudget float64) BranchPreparation

type BranchSummary 

type BranchSummary struct {
	Summary  string
	Details  any
	Usage    *ai.Usage
	FromHook *bool
}

type BranchSummaryDetails 

type BranchSummaryDetails struct {
	ReadFiles     []string `json:"readFiles"`
	ModifiedFiles []string `json:"modifiedFiles"`
}

type BranchSummaryResult 

type BranchSummaryResult struct {
	Summary       string
	Usage         *ai.Usage
	ReadFiles     []string
	ModifiedFiles []string
}

func GenerateBranchSummary 

func GenerateBranchSummary(ctx context.Context, entries []SessionEntry, options GenerateBranchSummaryOptions) (*BranchSummaryResult, error)

type ByteSessionStorage 

type ByteSessionStorage interface {
	SessionStorage
	Bytes() ([]byte, error)
	HeaderJSON() []byte
}

ByteSessionStorage exposes the exact serialized representation of a byte-backed session.

type CollectEntriesResult 

type CollectEntriesResult struct {
	Entries          []SessionEntry
	CommonAncestorID *string
}

func CollectEntriesForBranchSummary 

func CollectEntriesForBranchSummary(entries []SessionEntry, oldLeafID *string, targetID string) (CollectEntriesResult, error)

type CompactionDetails 

type CompactionDetails struct {
	ReadFiles     []string `json:"readFiles"`
	ModifiedFiles []string `json:"modifiedFiles"`
}

type CompactionPreparation 

type CompactionPreparation struct {
	FirstKeptEntryID    string
	MessagesToSummarize engine.AgentMessages
	TurnPrefixMessages  engine.AgentMessages
	RetainedTail        engine.AgentMessages
	IsSplitTurn         bool
	TokensBefore        int64
	PreviousSummary     *string
	FileOps             FileOperations
	Settings            CompactionSettings
}

func PrepareCompaction 

func PrepareCompaction(pathEntries []SessionEntry, settings CompactionSettings) (*CompactionPreparation, error)

func PrepareLegacyCompaction 

func PrepareLegacyCompaction(pathEntries []SessionEntry, settings CompactionSettings) (*CompactionPreparation, error)

PrepareLegacyCompaction retains the coding-agent compaction behavior, whose persisted session format has not adopted harness retained-tail checkpoints.

func PrepareTreeCompaction 

func PrepareTreeCompaction(pathEntries []SessionTreeEntry, settings CompactionSettings) (*CompactionPreparation, error)

PrepareTreeCompaction prepares the canonical persisted session entries.

type CompactionResult 

type CompactionResult struct {
	Summary          string
	FirstKeptEntryID string
	TokensBefore     int64
	Usage            *ai.Usage
	RetainedTail     engine.AgentMessages
	Details          any
}

func Compact 

func Compact(
	ctx context.Context,
	preparation *CompactionPreparation,
	model *ai.Model,
	complete CompleteFunc,
	customInstructions string,
	thinkingLevel ai.ModelThinkingLevel,
) (*CompactionResult, error)

func (CompactionResult) MarshalJSON 

func (result CompactionResult) MarshalJSON() ([]byte, error)

type CompactionSettings 

type CompactionSettings struct {
	Enabled          bool  `json:"enabled"`
	ReserveTokens    int64 `json:"reserveTokens"`
	KeepRecentTokens int64 `json:"keepRecentTokens"`
}

type CompleteFunc 

type CompleteFunc func(
	context.Context,
	*ai.Model,
	ai.Context,
	*ai.SimpleStreamOptions,
) (*ai.AssistantMessage, error)

func RetryingCompleteFunc 

func RetryingCompleteFunc(complete CompleteFunc, retry *ai.RetryPolicy, callbacks *ai.RetryCallbacks) CompleteFunc

RetryingCompleteFunc decorates the existing compaction completion seam. It lets compaction retry each generated summary without changing its core API.

type ContextEntryTransform 

type ContextEntryTransform func([]SessionTreeEntry) []SessionTreeEntry

type ContextUsage 

type ContextUsage struct {
	Tokens        *int64   `json:"tokens"`
	ContextWindow float64  `json:"contextWindow"`
	Percent       *float64 `json:"percent"`
}

type ContextUsageEstimate 

type ContextUsageEstimate struct {
	Tokens         int64 `json:"tokens"`
	UsageTokens    int64 `json:"usageTokens"`
	TrailingTokens int64 `json:"trailingTokens"`
	LastUsageIndex *int  `json:"lastUsageIndex"`
}

func EstimateContextTokens 

func EstimateContextTokens(messages engine.AgentMessages) ContextUsageEstimate

type CustomEntryContextMessageProjector 

type CustomEntryContextMessageProjector func(SessionTreeEntry, int, []SessionTreeEntry) engine.AgentMessages

type CustomMessage 

type CustomMessage struct {
	Role       string `json:"role"`
	CustomType string `json:"customType"`
	Content    any    `json:"content"`
	Display    bool   `json:"display"`
	Details    any    `json:"details,omitempty"`
	Timestamp  int64  `json:"timestamp"`
}

type CutPointResult 

type CutPointResult struct {
	FirstKeptEntryIndex int  `json:"firstKeptEntryIndex"`
	TurnStartIndex      int  `json:"turnStartIndex"`
	IsSplitTurn         bool `json:"isSplitTurn"`
}

func FindCutPoint 

func FindCutPoint(entries []SessionEntry, startIndex, endIndex int, keepRecentTokens int64) CutPointResult

type Events 

type Events interface {
	On(eventType HarnessEventType, listener HarnessEventListener) (unsubscribe func())
}

Events is the passive subscription seam: future events only. Earlier events are not replayed and no current-state snapshot is provided; a watch gives both.

type ExecOptions 

type ExecOptions struct {
	CWD string
	// Env overrides inherited defaults when the environment is inherited, and
	// is the entire child environment otherwise.
	Env map[string]string
	// InheritEnv controls whether the execution environment's default
	// variables are inherited. Nil defaults to true.
	InheritEnv     *bool
	TimeoutSeconds *float64
	OnStdout       func(string) error
	OnStderr       func(string) error
}

type ExecResult 

type ExecResult struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exitCode"`
}

type ExecutionEnv 

type ExecutionEnv interface {
	FileSystem
	Shell
}

type ExecutionError 

type ExecutionError struct {
	Code ExecutionErrorCode
	Err  error
}

ExecutionError keeps expected shell failures stable across execution backends.

func (*ExecutionError) Error 

func (err *ExecutionError) Error() string

func (*ExecutionError) Unwrap 

func (err *ExecutionError) Unwrap() error

type ExecutionErrorCode 

type ExecutionErrorCode string
const (
	ExecutionErrorAborted          ExecutionErrorCode = "aborted"
	ExecutionErrorTimeout          ExecutionErrorCode = "timeout"
	ExecutionErrorShellUnavailable ExecutionErrorCode = "shell_unavailable"
	ExecutionErrorSpawn            ExecutionErrorCode = "spawn_error"
	ExecutionErrorCallback         ExecutionErrorCode = "callback_error"
	ExecutionErrorUnknown          ExecutionErrorCode = "unknown"
)

type FileError 

type FileError struct {
	Code FileErrorCode
	Path string
	Err  error
}

FileError keeps expected filesystem failures typed across local and remote environments.

func (*FileError) Error 

func (err *FileError) Error() string

func (*FileError) Unwrap 

func (err *FileError) Unwrap() error

type FileErrorCode 

type FileErrorCode string
const (
	FileErrorAborted          FileErrorCode = "aborted"
	FileErrorNotFound         FileErrorCode = "not_found"
	FileErrorPermissionDenied FileErrorCode = "permission_denied"
	FileErrorNotDirectory     FileErrorCode = "not_directory"
	FileErrorIsDirectory      FileErrorCode = "is_directory"
	FileErrorInvalid          FileErrorCode = "invalid"
	FileErrorNotSupported     FileErrorCode = "not_supported"
	FileErrorUnknown          FileErrorCode = "unknown"
)

type FileInfo 

type FileInfo struct {
	Name    string
	Path    string
	Kind    FileKind
	Size    int64
	MTimeMS float64
}

type FileKind 

type FileKind string
const (
	FileKindFile      FileKind = "file"
	FileKindDirectory FileKind = "directory"
	FileKindSymlink   FileKind = "symlink"
)

type FileOperations 

type FileOperations struct {
	Read    map[string]struct{}
	Written map[string]struct{}
	Edited  map[string]struct{}
}

type FileSystem 

type FileSystem interface {
	WorkingDirectory() string
	AbsolutePath(context.Context, string) (string, error)
	JoinPath(context.Context, ...string) (string, error)
	ReadTextFile(context.Context, string) (string, error)
	ReadTextLines(context.Context, string, int) ([]string, error)
	ReadBinaryFile(context.Context, string) ([]byte, error)
	WriteFile(context.Context, string, []byte) error
	AppendFile(context.Context, string, []byte) error
	RenameFile(context.Context, string, string) error
	FileInfo(context.Context, string) (FileInfo, error)
	ListDir(context.Context, string) ([]FileInfo, error)
	CanonicalPath(context.Context, string) (string, error)
	Exists(context.Context, string) (bool, error)
	CreateDir(context.Context, string, bool) error
	Remove(context.Context, string, bool, bool) error
	CreateTempDir(context.Context, string) (string, error)
	CreateTempFile(context.Context, string, string) (string, error)
	Cleanup() error
}

FileSystem is the harness filesystem seam. Context cancellation maps to FileErrorAborted.

type ForkPosition 

type ForkPosition string
const (
	ForkBefore ForkPosition = "before"
	ForkAt     ForkPosition = "at"
)

type GenerateBranchSummaryOptions 

type GenerateBranchSummaryOptions struct {
	Model               *ai.Model
	Complete            CompleteFunc
	CustomInstructions  string
	ReplaceInstructions bool
	ReserveTokens       *int64
	Retry               *ai.RetryPolicy
	Callbacks           *ai.RetryCallbacks
}

type HarnessEvent 

type HarnessEvent struct {
	Type  HarnessEventType `json:"type"`
	Lane  string           `json:"lane"`
	RunID string           `json:"runId"`

	// Outcome and LeafID are carried by run_end only.
	Outcome RunOutcome `json:"outcome,omitempty"`
	LeafID  string     `json:"leafId,omitempty"`
}

HarnessEvent is one run lifecycle event.

type HarnessEventBus 

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

HarnessEventBus fans events out to per-type listeners and to watches. Listeners run outside the bus lock, so they may subscribe or emit reentrantly.

func (*HarnessEventBus) Emit 

func (bus *HarnessEventBus) Emit(event HarnessEvent)

Emit publishes to this type's listeners and to every watch.

func (*HarnessEventBus) On 

func (bus *HarnessEventBus) On(eventType HarnessEventType, listener HarnessEventListener) func()

On registers a listener for future events of one type and returns its unsubscribe.

type HarnessEventListener 

type HarnessEventListener func(HarnessEvent)

type HarnessEventType 

type HarnessEventType string
const (
	HarnessEventRunStart HarnessEventType = "run_start"
	HarnessEventRunEnd   HarnessEventType = "run_end"
)

type HarnessEventWatch 

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

HarnessEventWatch buffers events until Start hands them to a listener.

func WatchHarnessEvents 

func WatchHarnessEvents[TSnapshot any](bus *HarnessEventBus, capture func() TSnapshot) (TSnapshot, *HarnessEventWatch)

WatchHarnessEvents captures a snapshot with no event gap: everything emitted from capture onward — including reentrant emissions from capture itself — is buffered until Start.

func (*HarnessEventWatch) Start 

func (watch *HarnessEventWatch) Start(listener HarnessEventListener)

Start drains the buffer and then delivers live events. Buffering stays on while draining so reentrant emissions keep their order.

func (*HarnessEventWatch) Unsubscribe 

func (watch *HarnessEventWatch) Unsubscribe()

type HarnessPromptTemplatesResult 

type HarnessPromptTemplatesResult struct {
	PromptTemplates []PromptTemplate
	Diagnostics     []PromptTemplateDiagnostic
}

func LoadPromptTemplates 

func LoadPromptTemplates(env ResourceFileSystem, paths ...string) HarnessPromptTemplatesResult

LoadPromptTemplates loads explicit files or direct markdown children through the execution environment.

type HarnessSkillsResult 

type HarnessSkillsResult struct {
	Skills      []Skill
	Diagnostics []SkillDiagnostic
}

func LoadSkills 

func LoadSkills(env ResourceFileSystem, dirs ...string) HarnessSkillsResult

LoadSkills traverses one or more roots with upstream's SKILL.md stopping rule.

type InMemorySessionRepo 

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

InMemorySessionRepo retains insertion ordering, matching upstream's Map.

func NewInMemorySessionRepo 

func NewInMemorySessionRepo() *InMemorySessionRepo

func (*InMemorySessionRepo) Create 

func (repo *InMemorySessionRepo) Create(_ context.Context, options SessionCreateOptions) (*Session, error)

func (*InMemorySessionRepo) Delete 

func (repo *InMemorySessionRepo) Delete(_ context.Context, metadata SessionMetadata) error

func (*InMemorySessionRepo) Fork 

func (repo *InMemorySessionRepo) Fork(ctx context.Context, sourceMetadata SessionMetadata, options SessionForkOptions) (*Session, error)

func (*InMemorySessionRepo) List 

func (repo *InMemorySessionRepo) List(context.Context, SessionListOptions) ([]SessionMetadata, error)

func (*InMemorySessionRepo) Open 

func (repo *InMemorySessionRepo) Open(_ context.Context, metadata SessionMetadata) (*Session, error)

type InMemorySessionStorage 

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

InMemorySessionStorage stores the complete physical entry log in memory.

func NewInMemorySessionStorage 

func NewInMemorySessionStorage(entries []SessionTreeEntry, metadata SessionMetadata) (*InMemorySessionStorage, error)

func (*InMemorySessionStorage) AppendEntry 

func (storage *InMemorySessionStorage) AppendEntry(entry SessionTreeEntry) error

func (*InMemorySessionStorage) CreateEntryID 

func (storage *InMemorySessionStorage) CreateEntryID() (string, error)

func (*InMemorySessionStorage) Entries 

func (storage *InMemorySessionStorage) Entries(options ...SessionEntryCursorOptions) []SessionTreeEntry

func (*InMemorySessionStorage) EntriesByType 

func (storage *InMemorySessionStorage) EntriesByType(entryType string) []SessionTreeEntry

func (*InMemorySessionStorage) Entry 

func (storage *InMemorySessionStorage) Entry(id string) (*SessionTreeEntry, bool)

func (*InMemorySessionStorage) Label 

func (storage *InMemorySessionStorage) Label(id string) (string, bool)

func (*InMemorySessionStorage) LeafID 

func (storage *InMemorySessionStorage) LeafID() (*string, error)

func (*InMemorySessionStorage) Metadata 

func (storage *InMemorySessionStorage) Metadata() SessionMetadata

func (*InMemorySessionStorage) PathToRootOrCompaction 

func (storage *InMemorySessionStorage) PathToRootOrCompaction(leafID *string) ([]SessionTreeEntry, error)

func (*InMemorySessionStorage) SessionName 

func (storage *InMemorySessionStorage) SessionName() (string, bool)

func (*InMemorySessionStorage) SessionStats 

func (storage *InMemorySessionStorage) SessionStats() SessionStats

func (*InMemorySessionStorage) SetLeafID 

func (storage *InMemorySessionStorage) SetLeafID(leafID *string) error

type InMemorySessionV4Repo 

type InMemorySessionV4Repo struct {

	// Now overrides the created-at clock (epoch milliseconds).
	Now func() int64
	// contains filtered or unexported fields
}

InMemorySessionV4Repo keeps v4 sessions keyed by id in process memory.

func NewInMemorySessionV4Repo 

func NewInMemorySessionV4Repo() *InMemorySessionV4Repo

func (*InMemorySessionV4Repo) Create 

func (repo *InMemorySessionV4Repo) Create(options SessionV4CreateOptions) (*InMemorySessionV4Storage, error)

func (*InMemorySessionV4Repo) Delete 

func (repo *InMemorySessionV4Repo) Delete(metadata SessionV4Metadata)

func (*InMemorySessionV4Repo) Fork 

func (repo *InMemorySessionV4Repo) Fork(source SessionV4Metadata, options SessionV4RepoForkOptions) (*InMemorySessionV4Storage, error)

func (*InMemorySessionV4Repo) List 

func (repo *InMemorySessionV4Repo) List() []SessionV4Metadata

func (*InMemorySessionV4Repo) Open 

func (repo *InMemorySessionV4Repo) Open(metadata SessionV4Metadata) (*InMemorySessionV4Storage, error)

type InMemorySessionV4Storage 

type InMemorySessionV4Storage struct {

	// Now overrides the append timestamp clock (epoch milliseconds).
	Now func() int64
	// contains filtered or unexported fields
}

InMemorySessionV4Storage keeps the whole mutation log in memory.

func NewInMemorySessionV4Storage 

func NewInMemorySessionV4Storage(metadata SessionV4Metadata) *InMemorySessionV4Storage

func (*InMemorySessionV4Storage) AppendEntry 

func (storage *InMemorySessionV4Storage) AppendEntry(payload json.RawMessage, lane string) (SessionV4Entry, error)

func (*InMemorySessionV4Storage) AppendRecord 

func (storage *InMemorySessionV4Storage) AppendRecord(payload json.RawMessage) (SessionV4Record, error)

func (*InMemorySessionV4Storage) ClearName 

func (storage *InMemorySessionV4Storage) ClearName() error

ClearName records upstream's `setName(undefined)`: the session name is dropped durably, and forks of this session start unnamed.

func (*InMemorySessionV4Storage) CreateLane 

func (storage *InMemorySessionV4Storage) CreateLane(lane string, at *string) error

func (*InMemorySessionV4Storage) Entry 

func (storage *InMemorySessionV4Storage) Entry(id string) (SessionV4Entry, bool)

func (*InMemorySessionV4Storage) FindEntries 

func (storage *InMemorySessionV4Storage) FindEntries(query SessionV4EntryQuery) ([]SessionV4Entry, error)

func (*InMemorySessionV4Storage) FindEntriesOnBranch 

func (storage *InMemorySessionV4Storage) FindEntriesOnBranch(query SessionV4BranchQuery) ([]SessionV4Entry, error)

func (*InMemorySessionV4Storage) FindOpenOperations 

func (storage *InMemorySessionV4Storage) FindOpenOperations(lane string, limit *int) ([]SessionV4Record, error)

func (*InMemorySessionV4Storage) FindRecords 

func (storage *InMemorySessionV4Storage) FindRecords(query SessionV4RecordQuery) ([]SessionV4Record, error)

func (*InMemorySessionV4Storage) Label 

func (storage *InMemorySessionV4Storage) Label(id string) (string, bool)

func (*InMemorySessionV4Storage) Lanes 

func (storage *InMemorySessionV4Storage) Lanes() []SessionV4LanePointer

func (*InMemorySessionV4Storage) Log 

func (storage *InMemorySessionV4Storage) Log(options SessionV4LogOptions) ([]SessionV4LogItem, error)

func (*InMemorySessionV4Storage) Metadata 

func (storage *InMemorySessionV4Storage) Metadata() SessionV4Metadata

func (*InMemorySessionV4Storage) MoveLane 

func (storage *InMemorySessionV4Storage) MoveLane(lane string, to *string) error

func (*InMemorySessionV4Storage) Name 

func (storage *InMemorySessionV4Storage) Name() (string, bool)

func (*InMemorySessionV4Storage) SetLabel 

func (storage *InMemorySessionV4Storage) SetLabel(id string, label *string) error

func (*InMemorySessionV4Storage) SetName 

func (storage *InMemorySessionV4Storage) SetName(name string) error

func (*InMemorySessionV4Storage) Stats 

func (storage *InMemorySessionV4Storage) Stats() SessionStats

type JSONLSessionRepo 

type JSONLSessionRepo struct {
	FS           FileSystem
	SessionsRoot string
	// contains filtered or unexported fields
}

func NewJSONLSessionRepo 

func NewJSONLSessionRepo(fileSystem FileSystem, sessionsRoot string) *JSONLSessionRepo

func (*JSONLSessionRepo) Create 

func (repo *JSONLSessionRepo) Create(ctx context.Context, options SessionCreateOptions) (*Session, error)

func (*JSONLSessionRepo) Delete 

func (repo *JSONLSessionRepo) Delete(ctx context.Context, metadata SessionMetadata) error

func (*JSONLSessionRepo) Fork 

func (repo *JSONLSessionRepo) Fork(ctx context.Context, sourceMetadata SessionMetadata, options SessionForkOptions) (*Session, error)

func (*JSONLSessionRepo) ImportJSONL 

func (repo *JSONLSessionRepo) ImportJSONL(ctx context.Context, content []byte) (*Session, error)

ImportJSONL installs exact upstream bytes into this repository and returns a storage whose later appends remain durable.

func (*JSONLSessionRepo) ImportJSONLAt 

func (repo *JSONLSessionRepo) ImportJSONLAt(ctx context.Context, content []byte, path string) (*Session, error)

ImportJSONLAt installs exact upstream bytes at the runtime-selected import destination and keeps later appends bound to that file.

func (*JSONLSessionRepo) List 

func (repo *JSONLSessionRepo) List(ctx context.Context, options SessionListOptions) ([]SessionMetadata, error)

func (*JSONLSessionRepo) Open 

func (repo *JSONLSessionRepo) Open(ctx context.Context, metadata SessionMetadata) (*Session, error)

func (*JSONLSessionRepo) OpenPath 

func (repo *JSONLSessionRepo) OpenPath(ctx context.Context, path string) (*Session, error)

OpenPath resolves and opens one explicit JSONL path without filtering it through List, so malformed sessions remain observable to callers.

func (*JSONLSessionRepo) OpenRuntimeBytes 

func (repo *JSONLSessionRepo) OpenRuntimeBytes(ctx context.Context, path string, content []byte) (*Session, error)

OpenRuntimeBytes binds an unmaterialized coding-session snapshot to a path. The bytes remain pending until the first assistant message, matching the coding runtime's delayed persistence.

func (*JSONLSessionRepo) OpenRuntimePath 

func (repo *JSONLSessionRepo) OpenRuntimePath(ctx context.Context, path, cwd string) (*Session, error)

OpenRuntimePath composes the harness repository with coding-session resume semantics for missing and zero-byte explicit files.

type JSONLSessionStorage 

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

JSONLSessionStorage retains the exact input bytes until a mutation appends the same JSON line that upstream would append.

func RehydrateJSONLSession 

func RehydrateJSONLSession(content []byte, filePath string) (*JSONLSessionStorage, error)

RehydrateJSONLSession opens an upstream v3 JSONL session directly from bytes without first materializing a temporary file.

func (*JSONLSessionStorage) AppendEntry 

func (storage *JSONLSessionStorage) AppendEntry(entry SessionTreeEntry) error

func (*JSONLSessionStorage) Bytes 

func (storage *JSONLSessionStorage) Bytes() ([]byte, error)

func (*JSONLSessionStorage) CreateEntryID 

func (storage *JSONLSessionStorage) CreateEntryID() (string, error)

func (*JSONLSessionStorage) Entries 

func (storage *JSONLSessionStorage) Entries(options ...SessionEntryCursorOptions) []SessionTreeEntry

func (*JSONLSessionStorage) EntriesByType 

func (storage *JSONLSessionStorage) EntriesByType(entryType string) []SessionTreeEntry

func (*JSONLSessionStorage) Entry 

func (storage *JSONLSessionStorage) Entry(id string) (*SessionTreeEntry, bool)

func (*JSONLSessionStorage) HeaderJSON 

func (storage *JSONLSessionStorage) HeaderJSON() []byte

func (*JSONLSessionStorage) IsPersistent 

func (storage *JSONLSessionStorage) IsPersistent() bool

func (*JSONLSessionStorage) Label 

func (storage *JSONLSessionStorage) Label(id string) (string, bool)

func (*JSONLSessionStorage) LeafID 

func (storage *JSONLSessionStorage) LeafID() (*string, error)

func (*JSONLSessionStorage) Metadata 

func (storage *JSONLSessionStorage) Metadata() SessionMetadata

func (*JSONLSessionStorage) PathToRootOrCompaction 

func (storage *JSONLSessionStorage) PathToRootOrCompaction(leafID *string) ([]SessionTreeEntry, error)

func (*JSONLSessionStorage) SessionName 

func (storage *JSONLSessionStorage) SessionName() (string, bool)

func (*JSONLSessionStorage) SessionStats 

func (storage *JSONLSessionStorage) SessionStats() SessionStats

func (*JSONLSessionStorage) SessionVersion 

func (storage *JSONLSessionStorage) SessionVersion() float64

SessionVersion exposes the original byte-backed header version to adapters.

func (*JSONLSessionStorage) SetLeafID 

func (storage *JSONLSessionStorage) SetLeafID(leafID *string) error

type JSONLSessionV4CreateOptions 

type JSONLSessionV4CreateOptions struct {
	SessionV4CreateOptions
	CWD      string
	Metadata json.RawMessage
}

JSONLSessionV4CreateOptions mirrors upstream JsonlSessionCreateOptions.

type JSONLSessionV4ForkOptions 

type JSONLSessionV4ForkOptions struct {
	SessionV4ForkOptions
	JSONLSessionV4CreateOptions
}

JSONLSessionV4ForkOptions combines fork selection with new-session identity.

type JSONLSessionV4Metadata 

type JSONLSessionV4Metadata struct {
	ID                      string          `json:"id"`
	CreatedAt               int64           `json:"createdAt"`
	CWD                     string          `json:"cwd"`
	Path                    string          `json:"path"`
	ModifiedAt              float64         `json:"modifiedAt"`
	SourceFormat            int             `json:"sourceFormat"`
	ParentSessionID         *string         `json:"parentSessionId,omitempty"`
	LegacyParentSessionPath *string         `json:"legacyParentSessionPath,omitempty"`
	Metadata                json.RawMessage `json:"metadata,omitempty"`
}

JSONLSessionV4Metadata identifies a JSONL-backed v4 session.

func ListJSONLSessionV4Metadata 

func ListJSONLSessionV4Metadata(ctx context.Context, fs FileSystem, sessionsRoot string, cwd *string) ([]JSONLSessionV4Metadata, error)

ListJSONLSessionV4Metadata lists v4 sessions below a sessions root without opening them: only each file's header line is read, and a file whose header is missing or undecodable is skipped instead of failing the listing.

type JSONLSessionV4Repo 

type JSONLSessionV4Repo struct {

	// Now overrides the created-at clock (epoch milliseconds).
	Now func() int64
	// contains filtered or unexported fields
}

JSONLSessionV4Repo stores v4 sessions in coding-agent-compatible cwd-encoded directories below one sessions root.

func NewJSONLSessionV4Repo 

func NewJSONLSessionV4Repo(fs FileSystem, sessionsRoot string) *JSONLSessionV4Repo

func (*JSONLSessionV4Repo) Create 

func (repo *JSONLSessionV4Repo) Create(ctx context.Context, options JSONLSessionV4CreateOptions) (*JSONLSessionV4Storage, error)

func (*JSONLSessionV4Repo) Delete 

func (repo *JSONLSessionV4Repo) Delete(ctx context.Context, metadata JSONLSessionV4Metadata) error

func (*JSONLSessionV4Repo) Fork 

func (repo *JSONLSessionV4Repo) Fork(ctx context.Context, source JSONLSessionV4Metadata, options JSONLSessionV4ForkOptions) (*JSONLSessionV4Storage, error)

func (*JSONLSessionV4Repo) List 

func (repo *JSONLSessionV4Repo) List(ctx context.Context, cwd *string) ([]JSONLSessionV4Metadata, error)

func (*JSONLSessionV4Repo) Open 

func (repo *JSONLSessionV4Repo) Open(ctx context.Context, metadata JSONLSessionV4Metadata) (*JSONLSessionV4Storage, error)

type JSONLSessionV4Storage 

type JSONLSessionV4Storage struct {

	// Now overrides the append timestamp clock (epoch milliseconds).
	Now func() int64
	// contains filtered or unexported fields
}

JSONLSessionV4Storage appends every mutation to one v4 JSONL file.

func CreateJSONLSessionV4Storage 

func CreateJSONLSessionV4Storage(ctx context.Context, fs FileSystem, path string, header SessionV4Header) (*JSONLSessionV4Storage, error)

CreateJSONLSessionV4Storage initializes a new session file holding only the header.

func LoadJSONLSessionV4Storage 

func LoadJSONLSessionV4Storage(ctx context.Context, fs FileSystem, path string) (*JSONLSessionV4Storage, error)

LoadJSONLSessionV4Storage replays an existing session file, repairing a torn or unterminated trailing line in place.

func OpenJSONLSessionV4Storage 

func OpenJSONLSessionV4Storage(ctx context.Context, fs FileSystem, sessionsRoot string, metadata JSONLSessionV4Metadata) (*JSONLSessionV4Storage, error)

OpenJSONLSessionV4Storage loads one listed v4 session, rejecting metadata whose id no longer matches the file header.

func (*JSONLSessionV4Storage) AppendEntry 

func (storage *JSONLSessionV4Storage) AppendEntry(payload json.RawMessage, lane string) (SessionV4Entry, error)

func (*JSONLSessionV4Storage) AppendRecord 

func (storage *JSONLSessionV4Storage) AppendRecord(payload json.RawMessage) (SessionV4Record, error)

func (*JSONLSessionV4Storage) ClearName 

func (storage *JSONLSessionV4Storage) ClearName() error

ClearName records upstream's `setName(undefined)`: the session name is dropped durably, and forks of this session start unnamed.

func (*JSONLSessionV4Storage) CreateLane 

func (storage *JSONLSessionV4Storage) CreateLane(lane string, at *string) error

func (*JSONLSessionV4Storage) Entry 

func (storage *JSONLSessionV4Storage) Entry(id string) (SessionV4Entry, bool)

func (*JSONLSessionV4Storage) FindEntries 

func (storage *JSONLSessionV4Storage) FindEntries(query SessionV4EntryQuery) ([]SessionV4Entry, error)

func (*JSONLSessionV4Storage) FindEntriesOnBranch 

func (storage *JSONLSessionV4Storage) FindEntriesOnBranch(query SessionV4BranchQuery) ([]SessionV4Entry, error)

func (*JSONLSessionV4Storage) FindOpenOperations 

func (storage *JSONLSessionV4Storage) FindOpenOperations(lane string, limit *int) ([]SessionV4Record, error)

func (*JSONLSessionV4Storage) FindRecords 

func (storage *JSONLSessionV4Storage) FindRecords(query SessionV4RecordQuery) ([]SessionV4Record, error)

func (*JSONLSessionV4Storage) Fork 

func (storage *JSONLSessionV4Storage) Fork(ctx context.Context, path string, header SessionV4Header, options SessionV4ForkOptions) (*JSONLSessionV4Storage, error)

Fork copies the selected slice of this session into a new session file.

func (*JSONLSessionV4Storage) Label 

func (storage *JSONLSessionV4Storage) Label(id string) (string, bool)

func (*JSONLSessionV4Storage) Lanes 

func (storage *JSONLSessionV4Storage) Lanes() []SessionV4LanePointer

func (*JSONLSessionV4Storage) Log 

func (storage *JSONLSessionV4Storage) Log(options SessionV4LogOptions) ([]SessionV4LogItem, error)

func (*JSONLSessionV4Storage) Metadata 

func (storage *JSONLSessionV4Storage) Metadata() JSONLSessionV4Metadata

func (*JSONLSessionV4Storage) MoveLane 

func (storage *JSONLSessionV4Storage) MoveLane(lane string, to *string) error

func (*JSONLSessionV4Storage) Name 

func (storage *JSONLSessionV4Storage) Name() (string, bool)

func (*JSONLSessionV4Storage) SetLabel 

func (storage *JSONLSessionV4Storage) SetLabel(id string, label *string) error

func (*JSONLSessionV4Storage) SetName 

func (storage *JSONLSessionV4Storage) SetName(name string) error

func (*JSONLSessionV4Storage) Stats 

func (storage *JSONLSessionV4Storage) Stats() SessionStats

type LocalExecutionEnv 

type LocalExecutionEnv = NodeExecutionEnv

LocalExecutionEnv is the platform-neutral Go name for NodeExecutionEnv.

type NodeExecutionEnv 

type NodeExecutionEnv struct {
	CWD       string
	ShellPath string
	ShellEnv  map[string]string
	// contains filtered or unexported fields
}

NodeExecutionEnv is the pure-Go local filesystem and shell backend.

func (*NodeExecutionEnv) AbsolutePath 

func (env *NodeExecutionEnv) AbsolutePath(ctx context.Context, path string) (string, error)

func (*NodeExecutionEnv) AppendFile 

func (env *NodeExecutionEnv) AppendFile(ctx context.Context, path string, content []byte) error

func (*NodeExecutionEnv) CanonicalPath 

func (env *NodeExecutionEnv) CanonicalPath(ctx context.Context, path string) (string, error)

func (*NodeExecutionEnv) Cleanup 

func (env *NodeExecutionEnv) Cleanup() error

func (*NodeExecutionEnv) CreateDir 

func (env *NodeExecutionEnv) CreateDir(ctx context.Context, path string, recursive bool) error

func (*NodeExecutionEnv) CreateTempDir 

func (env *NodeExecutionEnv) CreateTempDir(ctx context.Context, prefix string) (string, error)

func (*NodeExecutionEnv) CreateTempFile 

func (env *NodeExecutionEnv) CreateTempFile(ctx context.Context, prefix, suffix string) (string, error)

func (*NodeExecutionEnv) Exec 

func (env *NodeExecutionEnv) Exec(ctx context.Context, command string, options ExecOptions) (ExecResult, error)

func (*NodeExecutionEnv) Exists 

func (env *NodeExecutionEnv) Exists(ctx context.Context, path string) (bool, error)

func (*NodeExecutionEnv) FileInfo 

func (env *NodeExecutionEnv) FileInfo(ctx context.Context, path string) (FileInfo, error)

func (*NodeExecutionEnv) JoinPath 

func (env *NodeExecutionEnv) JoinPath(ctx context.Context, parts ...string) (string, error)

func (*NodeExecutionEnv) ListDir 

func (env *NodeExecutionEnv) ListDir(ctx context.Context, path string) ([]FileInfo, error)

func (*NodeExecutionEnv) ReadBinaryFile 

func (env *NodeExecutionEnv) ReadBinaryFile(ctx context.Context, path string) ([]byte, error)

func (*NodeExecutionEnv) ReadTextFile 

func (env *NodeExecutionEnv) ReadTextFile(ctx context.Context, path string) (string, error)

func (*NodeExecutionEnv) ReadTextLines 

func (env *NodeExecutionEnv) ReadTextLines(ctx context.Context, path string, maxLines int) ([]string, error)

func (*NodeExecutionEnv) Remove 

func (env *NodeExecutionEnv) Remove(ctx context.Context, path string, recursive, force bool) error

func (*NodeExecutionEnv) RenameFile 

func (env *NodeExecutionEnv) RenameFile(ctx context.Context, from, to string) error

func (*NodeExecutionEnv) ResourceCanonicalPath 

func (env *NodeExecutionEnv) ResourceCanonicalPath(path string) (string, error)

func (*NodeExecutionEnv) ResourceFileInfo 

func (env *NodeExecutionEnv) ResourceFileInfo(path string) (FileInfo, error)

func (*NodeExecutionEnv) ResourceListDir 

func (env *NodeExecutionEnv) ResourceListDir(path string) ([]FileInfo, error)

func (*NodeExecutionEnv) ResourceReadTextFile 

func (env *NodeExecutionEnv) ResourceReadTextFile(path string) (string, error)

func (*NodeExecutionEnv) WorkingDirectory 

func (env *NodeExecutionEnv) WorkingDirectory() string

func (*NodeExecutionEnv) WriteFile 

func (env *NodeExecutionEnv) WriteFile(ctx context.Context, path string, content []byte) error

func (*NodeExecutionEnv) WriteFileExclusive 

func (env *NodeExecutionEnv) WriteFileExclusive(ctx context.Context, path string, content []byte) error

WriteFileExclusive creates a new file without replacing a concurrent writer.

type PromptTemplate 

type PromptTemplate struct {
	Name        string
	Description string
	Content     string
}

PromptTemplate is the harness-level explicit prompt expansion resource.

type PromptTemplateDiagnostic 

type PromptTemplateDiagnostic struct {
	Type    string
	Code    PromptTemplateDiagnosticCode
	Message string
	Path    string
}

type PromptTemplateDiagnosticCode 

type PromptTemplateDiagnosticCode string
const (
	PromptTemplateDiagnosticFileInfoFailed PromptTemplateDiagnosticCode = "file_info_failed"
	PromptTemplateDiagnosticListFailed     PromptTemplateDiagnosticCode = "list_failed"
	PromptTemplateDiagnosticReadFailed     PromptTemplateDiagnosticCode = "read_failed"
	PromptTemplateDiagnosticParseFailed    PromptTemplateDiagnosticCode = "parse_failed"
)

type ResourceFileSystem 

type ResourceFileSystem interface {
	ResourceFileInfo(path string) (FileInfo, error)
	ResourceListDir(path string) ([]FileInfo, error)
	ResourceReadTextFile(path string) (string, error)
	ResourceCanonicalPath(path string) (string, error)
}

ResourceFileSystem is the read-only filesystem slice used by resource discovery.

type RunOutcome 

type RunOutcome string

RunOutcome is how a run reached its end. 

const (
	RunCompleted RunOutcome = "completed"
	RunAborted   RunOutcome = "aborted"
	RunFailed    RunOutcome = "failed"
)

type Session 

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

Session is the storage-backed facade used by embedders and repositories.

func NewSession 

func NewSession(storage SessionStorage, options ...SessionContextBuildOptions) *Session

func (*Session) AppendActiveToolsChange 

func (session *Session) AppendActiveToolsChange(toolNames []string) (string, error)

func (*Session) AppendCompaction 

func (session *Session) AppendCompaction(summary, firstKeptEntryID string, tokensBefore float64, details any, fromHook *bool, usage ...*ai.Usage) (string, error)

func (*Session) AppendCompactionWithTail 

func (session *Session) AppendCompactionWithTail(
	summary, firstKeptEntryID string,
	tokensBefore float64,
	details any,
	fromHook *bool,
	usage *ai.Usage,
	retainedTail engine.AgentMessages,
) (string, error)

AppendCompactionWithTail persists the v0.81 checkpoint form. A non-nil retained tail, including an empty one, marks the compaction as a complete ancestry checkpoint.

func (*Session) AppendCustom 

func (session *Session) AppendCustom(customType string, data ...any) (string, error)

func (*Session) AppendCustomMessage 

func (session *Session) AppendCustomMessage(customType string, content any, display bool, details ...any) (string, error)

func (*Session) AppendLabel 

func (session *Session) AppendLabel(targetID string, label *string) (string, error)

func (*Session) AppendMessage 

func (session *Session) AppendMessage(message any) (string, error)

func (*Session) AppendModelChange 

func (session *Session) AppendModelChange(provider, modelID string) (string, error)

func (*Session) AppendName 

func (session *Session) AppendName(name string) (string, error)

func (*Session) AppendThinkingLevelChange 

func (session *Session) AppendThinkingLevelChange(level string) (string, error)

func (*Session) Branch 

func (session *Session) Branch(fromID ...string) ([]SessionTreeEntry, error)

func (*Session) Context 

func (session *Session) Context(options ...SessionContextBuildOptions) (SessionContext, error)

func (*Session) ContextEntries 

func (session *Session) ContextEntries(options ...SessionContextBuildOptions) ([]SessionTreeEntry, error)

func (*Session) Entries 

func (session *Session) Entries(options ...SessionEntryCursorOptions) []SessionTreeEntry

func (*Session) Entry 

func (session *Session) Entry(id string) (*SessionTreeEntry, bool)

func (*Session) Label 

func (session *Session) Label(id string) (string, bool)

func (*Session) LeafID 

func (session *Session) LeafID() (*string, error)

func (*Session) Metadata 

func (session *Session) Metadata() SessionMetadata

func (*Session) MoveTo 

func (session *Session) MoveTo(entryID *string, summary *BranchSummary) (string, error)

func (*Session) Name 

func (session *Session) Name() (string, bool, error)

func (*Session) Stats 

func (session *Session) Stats() SessionStats

func (*Session) Storage 

func (session *Session) Storage() SessionStorage

type SessionContext 

type SessionContext struct {
	ThinkingLevel   string        `json:"thinkingLevel"`
	Model           *SessionModel `json:"model"`
	ActiveToolNames []string      `json:"activeToolNames"`
	Messages        []any         `json:"messages"`
}

func BuildSessionContext 

func BuildSessionContext(entries []SessionTreeEntry, options ...SessionContextBuildOptions) SessionContext

BuildSessionContext reduces one active path using the same state and latest compaction rules as upstream's harness Session.

func BuildSessionV4Context 

func BuildSessionV4Context(pathEntries []SessionV4Entry, options ...SessionV4ContextOptions) SessionContext

BuildSessionV4Context reduces one root-to-leaf entry path into the model context, mirroring packages/agent/src/harness/session/context.ts.

type SessionContextBuildOptions 

type SessionContextBuildOptions struct {
	EntryTransforms []ContextEntryTransform
	EntryProjectors map[string]CustomEntryContextMessageProjector
}

type SessionCreateOptions 

type SessionCreateOptions struct {
	ID                string
	CWD               string
	ParentSessionPath *string
	Metadata          json.RawMessage
}

type SessionEntry 

type SessionEntry struct {
	Type             string
	ID               string
	ParentID         *string
	Timestamp        string
	Message          engine.AgentMessage
	Summary          string
	FirstKeptEntryID string
	RetainedTail     engine.AgentMessages
	TokensBefore     float64
	Details          any
	Usage            *ai.Usage
	FromHook         bool
	FromID           string
	CustomType       string
	Content          any
	Display          bool
}

SessionEntry is the compaction-facing projection of a v3 session entry. Harness storage owns generic session persistence; agent/session remains an upper-layer wire manager.

type SessionEntryCursorOptions 

type SessionEntryCursorOptions struct {
	AfterEntrySeq int
	Limit         *int
}

SessionEntryCursorOptions follows Array.slice semantics for the ordinary non-negative cursors emitted by upstream consumers.

type SessionError 

type SessionError struct {
	Code SessionErrorCode
	Err  error
}

SessionError preserves upstream's machine-readable error code.

func (*SessionError) Error 

func (failure *SessionError) Error() string

func (*SessionError) Unwrap 

func (failure *SessionError) Unwrap() error

type SessionErrorCode 

type SessionErrorCode string

SessionErrorCode is the stable failure classification used by harness storage, repositories, and tree operations. 

const (
	SessionErrorNotFound       SessionErrorCode = "not_found"
	SessionErrorInvalidSession SessionErrorCode = "invalid_session"
	SessionErrorInvalidEntry   SessionErrorCode = "invalid_entry"
	SessionErrorInvalidFork    SessionErrorCode = "invalid_fork_target"
	SessionErrorStorage        SessionErrorCode = "storage"
	SessionErrorUnknown        SessionErrorCode = "unknown"
	SessionErrorAlreadyExists  SessionErrorCode = "already_exists"
	SessionErrorInvalidPayload SessionErrorCode = "invalid_payload"
	SessionErrorInvalidLane    SessionErrorCode = "invalid_lane"
	SessionErrorInvalidQuery   SessionErrorCode = "invalid_query"
)

type SessionForkOptions 

type SessionForkOptions struct {
	SessionCreateOptions
	EntryID  string
	Position ForkPosition
}

type SessionListOptions 

type SessionListOptions struct {
	CWD string
}

type SessionMetadata 

type SessionMetadata struct {
	ID                string          `json:"id"`
	CreatedAt         string          `json:"createdAt"`
	CWD               string          `json:"cwd,omitempty"`
	Path              string          `json:"path,omitempty"`
	ParentSessionPath *string         `json:"parentSessionPath,omitempty"`
	Metadata          json.RawMessage `json:"metadata,omitempty"`
}

SessionMetadata is shared by memory and JSONL repositories. JSONL-only fields are omitted for memory sessions.

type SessionModel 

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

type SessionRepo 

type SessionRepo interface {
	Create(context.Context, SessionCreateOptions) (*Session, error)
	Open(context.Context, SessionMetadata) (*Session, error)
	List(context.Context, SessionListOptions) ([]SessionMetadata, error)
	Delete(context.Context, SessionMetadata) error
	Fork(context.Context, SessionMetadata, SessionForkOptions) (*Session, error)
}

type SessionStats 

type SessionStats struct {
	MessageCount   int     `json:"messageCount"`
	CachedTokens   float64 `json:"cachedTokens"`
	UncachedTokens float64 `json:"uncachedTokens"`
	TotalTokens    float64 `json:"totalTokens"`
	CostTotal      float64 `json:"costTotal"`
}

SessionStats accounts for all physical session entries, including summary entries outside the active branch.

type SessionStorage 

type SessionStorage interface {
	Metadata() SessionMetadata
	LeafID() (*string, error)
	SetLeafID(*string) error
	CreateEntryID() (string, error)
	AppendEntry(SessionTreeEntry) error
	Entry(string) (*SessionTreeEntry, bool)
	EntriesByType(string) []SessionTreeEntry
	Label(string) (string, bool)
	SessionName() (string, bool)
	SessionStats() SessionStats
	PathToRootOrCompaction(*string) ([]SessionTreeEntry, error)
	Entries(...SessionEntryCursorOptions) []SessionTreeEntry
}

SessionStorage is the backend-neutral session tree contract.

type SessionTreeEntry 

type SessionTreeEntry struct {
	Type      string
	ID        string
	ParentID  *string
	Timestamp string

	Message          json.RawMessage
	ThinkingLevel    string
	Provider         string
	ModelID          string
	ActiveToolNames  []string
	Summary          string
	FirstKeptEntryID string
	RetainedTail     []json.RawMessage
	TokensBefore     float64
	Details          json.RawMessage
	Usage            *ai.Usage
	FromHook         *bool
	FromID           string
	CustomType       string
	Data             json.RawMessage
	Content          json.RawMessage
	Display          bool
	TargetID         *string
	HasTargetID      bool
	Label            *string
	Name             string
	// contains filtered or unexported fields
}

SessionTreeEntry is the v3 harness session union. Raw JSON members stay opaque so unknown application data can round-trip without coercion.

func BuildContextEntries 

func BuildContextEntries(entries []SessionTreeEntry, options ...SessionContextBuildOptions) []SessionTreeEntry

func DefaultContextEntryTransform 

func DefaultContextEntryTransform(entries []SessionTreeEntry) []SessionTreeEntry

func EntriesToFork 

func EntriesToFork(storage SessionStorage, entryID string, position ForkPosition) ([]SessionTreeEntry, error)

EntriesToFork selects the source entries copied by repository fork.

func ParseSessionTreeEntry 

func ParseSessionTreeEntry(data []byte) (SessionTreeEntry, error)

ParseSessionTreeEntry decodes one upstream session entry while retaining unknown members for a later wire-compatible marshal. Exported for module embedders with external session stores; not referenced inside this repo.

func (SessionTreeEntry) RawJSON 

func (entry SessionTreeEntry) RawJSON() json.RawMessage

RawJSON returns the original object for entries rehydrated from JSONL.

type SessionV4 

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

SessionV4 is the thin tree facade over a v4 storage, mirroring upstream's Session class for the main lane plus per-lane views.

func NewSessionV4 

func NewSessionV4(storage SessionV4Storage, nextID ...func() string) *SessionV4

func (*SessionV4) AppendCustomEntry 

func (session *SessionV4) AppendCustomEntry(customType string, data json.RawMessage, lane ...string) (string, error)

func (*SessionV4) AppendMessage 

func (session *SessionV4) AppendMessage(message json.RawMessage) (string, error)

func (*SessionV4) FindEntryOnBranch 

func (session *SessionV4) FindEntryOnBranch(query SessionV4BranchQuery, lane ...string) (*SessionV4Entry, error)

func (*SessionV4) LeafID 

func (session *SessionV4) LeafID(lane ...string) (*string, error)

func (*SessionV4) Stats 

func (session *SessionV4) Stats() SessionStats

type SessionV4BranchQuery 

type SessionV4BranchQuery struct {
	SessionV4EntryQuery
	Start string
	// StopAtType and StopAtID end the scan after the first match, inclusive.
	StopAtType string
	StopAtID   string
}

SessionV4BranchQuery bounds a branch walk from Start toward the root. Unbounded, it covers the whole path from leaf to root.

type SessionV4ContextOptions 

type SessionV4ContextOptions struct {
	EntryTransforms []SessionV4ContextTransform
	EntryProjectors map[string]SessionV4ContextProjector
}

SessionV4ContextOptions mirrors upstream SessionContextBuildOptions.

type SessionV4ContextProjector 

type SessionV4ContextProjector func(SessionV4Entry, int, []SessionV4Entry) engine.AgentMessages

SessionV4ContextProjector maps one custom entry to context messages.

type SessionV4ContextTransform 

type SessionV4ContextTransform func([]SessionV4Entry) []SessionV4Entry

SessionV4ContextTransform rewrites the entry slice a context is built from.

type SessionV4CreateOptions 

type SessionV4CreateOptions struct {
	ID              *string
	ParentSessionID *string
}

SessionV4CreateOptions mirrors upstream SessionCreateOptions.

type SessionV4DecodeError 

type SessionV4DecodeError struct {
	Kind    SessionV4DecodeErrorKind
	Message string
}

SessionV4DecodeError is a line-local decode failure carrying no file or line context of its own, mirroring upstream JsonlDecodeError.

func (*SessionV4DecodeError) Error 

func (failure *SessionV4DecodeError) Error() string

type SessionV4DecodeErrorKind 

type SessionV4DecodeErrorKind string

SessionV4DecodeErrorKind separates malformed JSON from well-formed JSON that violates the v4 schema. Only a syntax failure on the final line is a torn append and gets repaired. 

const (
	SessionV4DecodeSyntax SessionV4DecodeErrorKind = "syntax"
	SessionV4DecodeSchema SessionV4DecodeErrorKind = "schema"
)

type SessionV4Entry 

type SessionV4Entry struct {
	Type      string
	ID        string
	ParentID  *string
	Seq       int
	Timestamp int64

	Message         json.RawMessage
	ThinkingLevel   string
	Provider        string
	ModelID         string
	ActiveToolNames []string
	Summary         string
	FromID          string
	TokensBefore    float64
	RetainedTail    []json.RawMessage
	CustomType      string
	Data            json.RawMessage
	Details         json.RawMessage
	// contains filtered or unexported fields
}

SessionV4Entry is one immutable tree entry of a v4 session. Its serialized member order is retained for wire-compatible re-encoding. ParentID (the appending lane's leaf), Seq (the session-wide sequence), and Timestamp (Unix ms) are storage-assigned.

func DefaultSessionV4ContextTransform 

func DefaultSessionV4ContextTransform(pathEntries []SessionV4Entry) []SessionV4Entry

DefaultSessionV4ContextTransform keeps only the latest compaction and the entries after it.

func ParseSessionV4Entry 

func ParseSessionV4Entry(data []byte) (SessionV4Entry, error)

ParseSessionV4Entry decodes one bare entry object (no kind/lane wrapper), as used for context-building inputs.

func (SessionV4Entry) MarshalJSON 

func (entry SessionV4Entry) MarshalJSON() ([]byte, error)

type SessionV4EntryQuery 

type SessionV4EntryQuery struct {
	Type       string
	CustomType string // for Type "custom"
	Order      string // "" is newestFirst
	Limit      *int
	AfterSeq   *int
}

SessionV4EntryQuery mirrors upstream EntryQuery. A nil Limit means unlimited; zero and negative limits are invalid.

type SessionV4ForkOptions 

type SessionV4ForkOptions struct {
	Scope    string
	EntryID  *string
	Position ForkPosition
}

SessionV4ForkOptions selects what a fork copies: the main branch up to a message entry, or the whole tree.

type SessionV4Header 

type SessionV4Header struct {
	ID                      string
	CreatedAt               int64
	CWD                     string
	ParentSessionID         *string
	LegacyParentSessionPath *string
	Metadata                json.RawMessage
}

SessionV4Header mirrors upstream JsonlV4Header.

func ParseSessionV4Header 

func ParseSessionV4Header(line []byte, path string) (SessionV4Header, error)

ParseSessionV4Header decodes and validates the first line of a v4 session, reporting failures with the session file context upstream's invalidFile adds.

type SessionV4LanePointer 

type SessionV4LanePointer struct {
	Lane   string  `json:"lane"`
	LeafID *string `json:"leafId"`
}

SessionV4LanePointer names one lane and its current leaf entry.

type SessionV4LogItem 

type SessionV4LogItem struct {
	Kind string
	Seq  int

	Entry  *SessionV4Entry
	Record *SessionV4Record

	Lane   string
	LeafID *string

	Fact     string
	Name     string
	TargetID string
	Label    *string

	// NameCleared marks a `fact:"name"` item that cleared the session name
	// (upstream `name: undefined`); the `name` member is then omitted.
	NameCleared bool
}

SessionV4LogItem is one replayed mutation of the session log.

func (SessionV4LogItem) MarshalJSON 

func (item SessionV4LogItem) MarshalJSON() ([]byte, error)

type SessionV4LogOptions 

type SessionV4LogOptions struct {
	AfterSeq *int
	Limit    *int
}

SessionV4LogOptions pages the replayed mutation log.

type SessionV4Metadata 

type SessionV4Metadata struct {
	ID              string  `json:"id"`
	CreatedAt       int64   `json:"createdAt"`
	ParentSessionID *string `json:"parentSessionId,omitempty"`
}

SessionV4Metadata identifies an in-memory v4 session.

type SessionV4Mutation 

type SessionV4Mutation struct {
	Kind string

	EntryLane *string
	Entry     *SessionV4Entry

	Record *SessionV4Record

	Seq    int
	Lane   string
	LeafID *string

	Fact     string
	Name     string
	TargetID string
	Label    *string

	// NameCleared marks a `fact:"name"` mutation that clears the session name
	// (upstream `name: undefined`); the `name` member is then omitted on the wire.
	NameCleared bool
}

SessionV4Mutation is one decoded JSONL mutation line.

func ParseSessionV4Mutation 

func ParseSessionV4Mutation(line []byte, path string, lineNumber int) (SessionV4Mutation, error)

ParseSessionV4Mutation decodes one v4 mutation line, reporting failures with the session file context upstream's invalidFile adds.

type SessionV4NameClearer 

type SessionV4NameClearer interface {
	ClearName() error
}

SessionV4NameClearer is upstream's `setName(undefined)` half of the storage contract. It stays a separate interface so SessionV4Storage keeps its published method set for existing implementations.

type SessionV4Record 

type SessionV4Record struct {
	Type      string
	ID        string
	Lane      string
	Seq       int
	Timestamp int64

	RunID      string
	IntentKind string
	Usage      *SessionV4Usage
	// contains filtered or unexported fields
}

SessionV4Record is one lane record (operation, queue, usage, ...) of a v4 session log.

func (SessionV4Record) MarshalJSON 

func (record SessionV4Record) MarshalJSON() ([]byte, error)

type SessionV4RecordQuery 

type SessionV4RecordQuery struct {
	Lane string
	Type string
	// RunID is operation identity: it matches an operation_started record's own
	// id and the RunID of operation-owned records. Records without an operation
	// identity never match.
	RunID string
	// OperationKind is valid only with Type "operation_started".
	OperationKind string
	// AfterSeq is an exclusive chronological lower bound regardless of Order.
	AfterSeq *int
	Order    string // "" is newestFirst
	Limit    *int
}

SessionV4RecordQuery mirrors upstream RecordQuery. Empty string fields match every value.

type SessionV4RepoForkOptions 

type SessionV4RepoForkOptions struct {
	SessionV4ForkOptions
	SessionV4CreateOptions
}

SessionV4RepoForkOptions combines fork selection with new-session identity.

type SessionV4Storage 

type SessionV4Storage interface {
	Lanes() []SessionV4LanePointer
	CreateLane(lane string, at *string) error
	MoveLane(lane string, to *string) error
	AppendEntry(payload json.RawMessage, lane string) (SessionV4Entry, error)
	AppendRecord(payload json.RawMessage) (SessionV4Record, error)
	Entry(id string) (SessionV4Entry, bool)
	FindEntries(query SessionV4EntryQuery) ([]SessionV4Entry, error)
	FindEntriesOnBranch(query SessionV4BranchQuery) ([]SessionV4Entry, error)
	FindRecords(query SessionV4RecordQuery) ([]SessionV4Record, error)
	FindOpenOperations(lane string, limit *int) ([]SessionV4Record, error)
	Log(options SessionV4LogOptions) ([]SessionV4LogItem, error)
	Name() (string, bool)
	SetName(name string) error
	Label(id string) (string, bool)
	SetLabel(id string, label *string) error
	Stats() SessionStats
}

SessionV4Storage is the backend-neutral v4 session log contract.

type SessionV4Usage 

type SessionV4Usage struct {
	Input       float64
	Output      float64
	CacheRead   float64
	CacheWrite  float64
	TotalTokens float64
	CostTotal   float64
}

SessionV4Usage carries the token accounting consumed by session stats.

type Shell 

type Shell interface {
	Exec(context.Context, string, ExecOptions) (ExecResult, error)
	Cleanup() error
}

type Skill 

type Skill struct {
	Name                   string
	Description            string
	Content                string
	FilePath               string
	DisableModelInvocation bool
}

Skill is the harness-level, execution-environment-neutral Agent Skills shape.

type SkillDiagnostic 

type SkillDiagnostic struct {
	Type    string
	Code    SkillDiagnosticCode
	Message string
	Path    string
}

type SkillDiagnosticCode 

type SkillDiagnosticCode string
const (
	SkillDiagnosticFileInfoFailed SkillDiagnosticCode = "file_info_failed"
	SkillDiagnosticListFailed     SkillDiagnosticCode = "list_failed"
	SkillDiagnosticReadFailed     SkillDiagnosticCode = "read_failed"
	SkillDiagnosticParseFailed    SkillDiagnosticCode = "parse_failed"
	SkillDiagnosticInvalidMeta    SkillDiagnosticCode = "invalid_metadata"
)

type SourcedPromptTemplate 

type SourcedPromptTemplate[T any] struct {
	PromptTemplate PromptTemplate
	Source         T
}

type SourcedPromptTemplateDiagnostic 

type SourcedPromptTemplateDiagnostic[T any] struct {
	PromptTemplateDiagnostic
	Source T
}

type SourcedPromptTemplateInput 

type SourcedPromptTemplateInput[T any] struct {
	Path   string
	Source T
}

type SourcedSkill 

type SourcedSkill[T any] struct {
	Skill  Skill
	Source T
}

type SourcedSkillDiagnostic 

type SourcedSkillDiagnostic[T any] struct {
	SkillDiagnostic
	Source T
}

type SourcedSkillInput 

type SourcedSkillInput[T any] struct {
	Path   string
	Source T
}

type SummaryMessage 

type SummaryMessage struct {
	Role         string  `json:"role"`
	Summary      string  `json:"summary"`
	FromID       string  `json:"fromId,omitempty"`
	TokensBefore float64 `json:"tokensBefore,omitempty"`
	Timestamp    int64   `json:"timestamp"`
}

type SummaryResult 

type SummaryResult struct {
	Text  string
	Usage ai.Usage
}

func GenerateSummaryWithUsage 

func GenerateSummaryWithUsage(
	ctx context.Context,
	messages engine.AgentMessages,
	model *ai.Model,
	complete CompleteFunc,
	reserveTokens int64,
	customInstructions string,
	previousSummary *string,
	thinkingLevel ai.ModelThinkingLevel,
) (*SummaryResult, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.