agentharness

package
v0.3.14 Latest Latest
Warning

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

Go to latest
Published: Jun 19, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package agentharness exposes the host/UI durable conversation API.

AgentHarness owns durable threads backed by sessiontree.Repo. Thread.Run, Thread.Retry, Thread.MoveTo, and Thread.Compact are safe to call concurrently across different ThreadIDs, including source and forked threads. A single durable ThreadID admits at most one active turn or mutation at a time; callers that race the same thread receive ErrActiveTurn before new turn entries are appended. This serialization is enforced through the repository turn lease contract when the repo implements sessiontree.TurnLeaseRepo, so two harnesses sharing one durable repo observe the same active-turn invariant.

The lower-level engine remains a turn executor. Harness callers configure engine behavior through TurnPolicy and LoopLimits rather than raw engine.Options so run identity, provider/model identity, and control tool definitions are generated by the harness for the active durable thread.

Thread.Read returns the host-facing snapshot: lifecycle status, appendability, retry availability, and display messages. Thread.Journal is the explicit raw session-tree inspection API for tests, debug consoles, and admin tooling.

Index

Constants

View Source
const ThreadTitleLogicalRequestID = "thread_title"

Variables

View Source
var (
	ErrActiveTurn    = errors.New("thread already has an active turn")
	ErrNoRetryTarget = errors.New("thread has no retryable turn")
)

Functions

This section is empty.

Types

type AgentHarness

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

func New

func New(options Options) *AgentHarness

func (*AgentHarness) ForkThread

func (h *AgentHarness) ForkThread(ctx context.Context, opts ForkOptions) (*Thread, error)

func (*AgentHarness) ResumeThread

func (h *AgentHarness) ResumeThread(ctx context.Context, id string, _ ResumeOptions) (*Thread, error)

func (*AgentHarness) StartThread

func (h *AgentHarness) StartThread(ctx context.Context, opts StartThreadOptions) (*Thread, error)

type ForkOptions

type ForkOptions struct {
	SourceThreadID string
	EntryID        string
	Position       sessiontree.ForkPosition
	NewThreadID    string
}

type HarnessEvent

type HarnessEvent struct {
	Type      HarnessEventType  `json:"type"`
	ThreadID  string            `json:"thread_id,omitempty"`
	TurnID    string            `json:"turn_id,omitempty"`
	EntryID   string            `json:"entry_id,omitempty"`
	ParentID  string            `json:"parent_id,omitempty"`
	Message   string            `json:"message,omitempty"`
	Status    string            `json:"status,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	Timestamp time.Time         `json:"timestamp"`
}

type HarnessEventType

type HarnessEventType string
const (
	EventThreadStarted HarnessEventType = "thread_started"
	EventThreadResumed HarnessEventType = "thread_resumed"
	EventThreadForked  HarnessEventType = "thread_forked"
	EventLeafMoved     HarnessEventType = "leaf_moved"
	EventTurnStarted   HarnessEventType = "turn_started"
	EventTurnCompleted HarnessEventType = "turn_completed"
	EventTurnFailed    HarnessEventType = "turn_failed"
	EventTurnAborted   HarnessEventType = "turn_aborted"
	EventEntryAppended HarnessEventType = "entry_appended"
	EventRetryStarted  HarnessEventType = "retry_started"
	EventTitleUpdated  HarnessEventType = "thread_title_updated"
	EventTitleFailed   HarnessEventType = "thread_title_failed"
)

type HarnessRecorder

type HarnessRecorder struct {
	Events []HarnessEvent
	// contains filtered or unexported fields
}

func (*HarnessRecorder) EmitHarness

func (r *HarnessRecorder) EmitHarness(ev HarnessEvent)

func (*HarnessRecorder) Snapshot

func (r *HarnessRecorder) Snapshot() []HarnessEvent

type HarnessSink

type HarnessSink interface {
	EmitHarness(HarnessEvent)
}

type LoopLimits

type LoopLimits struct {
	MaxEmptyProviderRetries  int
	NoProgressLimit          int
	DuplicateToolLimit       int
	WallTime                 time.Duration
	MaxTotalTokens           int64
	MaxCostUSD               float64
	MaxToolCalls             int
	MaxLengthContinuations   int
	MaxStopHookContinuations int
}

type MoveOptions

type MoveOptions struct {
	Summary string
}

type Options

type Options struct {
	Provider            provider.Provider
	ProviderName        string
	Model               string
	SystemPrompt        string
	Tools               *tools.Registry
	PromptStore         cache.Store
	Repo                sessiontree.Repo
	Sink                event.Sink
	SinkPolicy          event.SinkPolicy
	HarnessSink         HarnessSink
	Approver            tools.Approver
	StopHook            engine.StopHook
	CompactionGenerator compaction.SummaryGenerator
	CompactionPrompt    compaction.PromptOptions
	TitleGenerator      TitleGenerator
	Artifacts           artifact.Store
	TurnPolicy          TurnPolicy
	LoopLimits          LoopLimits
	NewID               func(string) string
	Now                 func() time.Time
}

type PendingToolCompletion added in v0.3.10

type PendingToolCompletion struct {
	TurnID     string
	RunID      string
	ToolCallID string
	ToolName   string
	Handle     string
	Status     PendingToolCompletionStatus
	Summary    string
	Output     string
	Labels     engine.RunLabels
}

type PendingToolCompletionStatus added in v0.3.10

type PendingToolCompletionStatus string
const (
	PendingToolCompleted PendingToolCompletionStatus = "completed"
	PendingToolFailed    PendingToolCompletionStatus = "failed"
	PendingToolCanceled  PendingToolCompletionStatus = "canceled"
)

type ProviderTitleGenerator

type ProviderTitleGenerator struct {
	Provider        provider.Provider
	ProviderName    string
	Model           string
	MaxRunes        int
	MaxOutputTokens int64
}

func (ProviderTitleGenerator) GenerateTitle

func (g ProviderTitleGenerator) GenerateTitle(ctx context.Context, req TitleRequest) (TitleResult, error)

type ResumeOptions

type ResumeOptions struct{}

type RetryOptions

type RetryOptions struct {
	Reason string
	Labels engine.RunLabels
}

type RunOptions

type RunOptions struct {
	TurnID string
	Labels engine.RunLabels
}

type StartThreadOptions

type StartThreadOptions struct {
	ThreadID string
}

type Thread

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

func (*Thread) Compact

func (t *Thread) Compact(ctx context.Context, summary, firstKeptEntryID string) (sessiontree.Entry, error)

func (*Thread) CompletePendingTool added in v0.3.10

func (t *Thread) CompletePendingTool(ctx context.Context, completion PendingToolCompletion) (TurnResult, error)

func (*Thread) ID

func (t *Thread) ID() string

func (*Thread) Journal

func (t *Thread) Journal(ctx context.Context) (ThreadJournalSnapshot, error)

func (*Thread) MoveTo

func (t *Thread) MoveTo(ctx context.Context, entryID string, opts MoveOptions) error

func (*Thread) Read

func (t *Thread) Read(ctx context.Context) (ThreadSnapshot, error)

func (*Thread) Retry

func (t *Thread) Retry(ctx context.Context, opts RetryOptions) (TurnResult, error)

func (*Thread) Run

func (t *Thread) Run(ctx context.Context, input string, opts RunOptions) (TurnResult, error)

type ThreadJournalSnapshot

type ThreadJournalSnapshot struct {
	Meta    sessiontree.ThreadMeta `json:"meta"`
	Path    []sessiontree.Entry    `json:"path"`
	Entries []sessiontree.Entry    `json:"entries"`
	Context []session.Message      `json:"context"`
	Phase   string                 `json:"phase"`
}

type ThreadMessage

type ThreadMessage struct {
	Role      session.Role `json:"role"`
	Content   string       `json:"content"`
	TurnID    string       `json:"turn_id,omitempty"`
	CreatedAt time.Time    `json:"created_at"`
}

type ThreadSnapshot

type ThreadSnapshot struct {
	ID               string          `json:"id"`
	Title            string          `json:"title,omitempty"`
	TitleStatus      string          `json:"title_status,omitempty"`
	TitleSource      string          `json:"title_source,omitempty"`
	TitleUpdatedAt   time.Time       `json:"title_updated_at,omitempty"`
	TitleError       string          `json:"title_error,omitempty"`
	CreatedAt        time.Time       `json:"created_at"`
	UpdatedAt        time.Time       `json:"updated_at"`
	Phase            string          `json:"phase"`
	Status           string          `json:"status"`
	LatestTurnID     string          `json:"latest_turn_id,omitempty"`
	WaitingPrompt    string          `json:"waiting_prompt,omitempty"`
	Recoverable      bool            `json:"recoverable"`
	CanAppendMessage bool            `json:"can_append_message"`
	CanRetry         bool            `json:"can_retry"`
	Messages         []ThreadMessage `json:"messages"`
}

type TitleGenerator

type TitleGenerator interface {
	GenerateTitle(context.Context, TitleRequest) (TitleResult, error)
}

type TitleRequest

type TitleRequest struct {
	ThreadID string
	TurnID   string
	Messages []session.Message
}

type TitleResult

type TitleResult struct {
	Title  string
	Source sessiontree.ThreadTitleSource
}

type TurnPolicy

type TurnPolicy struct {
	ContextPolicy         contextpolicy.Policy
	CacheRetention        cache.Retention
	HostedToolDefinitions []provider.HostedToolDefinition
	CompletionPolicy      engine.CompletionPolicy
}

type TurnResult

type TurnResult struct {
	ID                 string
	Status             engine.Status
	Output             string
	Err                error
	Diagnostics        map[string]string
	Metrics            engine.RunMetrics
	CompletionReason   engine.CompletionReason
	ContinuationReason engine.ContinuationReason
	FinishReason       provider.FinishReason
	RawFinishReason    string
	FinishInferred     bool
}

Jump to

Keyboard shortcuts

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