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, migrations, and admin tooling.
Index ¶
- Variables
- type AgentHarness
- type ForkOptions
- type HarnessEvent
- type HarnessEventType
- type HarnessRecorder
- type HarnessSink
- type LoopLimits
- type MoveOptions
- type Options
- 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) 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 TurnPolicy
- type TurnResult
Constants ¶
This section is empty.
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" )
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
Artifacts artifact.Store
TurnPolicy TurnPolicy
LoopLimits LoopLimits
NewID func(string) string
Now func() time.Time
}
type ResumeOptions ¶
type ResumeOptions struct{}
type RetryOptions ¶
type RetryOptions struct {
Reason string
}
type RunOptions ¶
type RunOptions struct {
TurnID string
}
type StartThreadOptions ¶
type StartThreadOptions struct {
ThreadID string
}
type Thread ¶
type Thread struct {
// contains filtered or unexported fields
}
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"`
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 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
}