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
- Variables
- type AgentHarness
- type ForkOptions
- type HarnessEvent
- type HarnessEventType
- type HarnessRecorder
- type HarnessSink
- type LoopLimits
- type MoveOptions
- type Options
- type PendingToolCompletion
- type PendingToolCompletionStatus
- type ProviderTitleGenerator
- type ResumeOptions
- type RetryOptions
- type RunOptions
- type StartThreadOptions
- type Thread
- func (t *Thread) Compact(ctx context.Context, summary, firstKeptEntryID string) (sessiontree.Entry, error)
- func (t *Thread) CompletePendingTool(ctx context.Context, completion PendingToolCompletion) (TurnResult, error)
- func (t *Thread) ID() string
- func (t *Thread) Journal(ctx context.Context) (ThreadJournalSnapshot, error)
- func (t *Thread) MoveTo(ctx context.Context, entryID string, opts MoveOptions) error
- func (t *Thread) Read(ctx context.Context) (ThreadSnapshot, error)
- func (t *Thread) Retry(ctx context.Context, opts RetryOptions) (TurnResult, error)
- func (t *Thread) Run(ctx context.Context, input string, opts RunOptions) (TurnResult, error)
- type ThreadJournalSnapshot
- type ThreadMessage
- type ThreadSnapshot
- type TitleGenerator
- type TitleRequest
- type TitleResult
- type TurnPolicy
- type TurnResult
Constants ¶
const ThreadTitleLogicalRequestID = "thread_title"
Variables ¶
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 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 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 RunOptions ¶
type StartThreadOptions ¶
type StartThreadOptions struct {
ThreadID string
}
type Thread ¶
type Thread struct {
// contains filtered or unexported fields
}
func (*Thread) CompletePendingTool ¶ added in v0.3.10
func (t *Thread) CompletePendingTool(ctx context.Context, completion PendingToolCompletion) (TurnResult, error)
func (*Thread) Journal ¶
func (t *Thread) Journal(ctx context.Context) (ThreadJournalSnapshot, 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 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 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
}