agent

Documentation

Index

• type AuditEntry
• type AuditHook
  • func NewAuditHook(maxEntries int) *AuditHook
  • func (h *AuditHook) Entries() []AuditEntry
  • func (h *AuditHook) OnEvent(_ context.Context, evt Event)
• type CounterHook
  • func NewCounterHook() *CounterHook
  • func (h *CounterHook) OnEvent(_ context.Context, evt Event)
  • func (h *CounterHook) Snapshot() map[EventType]int
• type Event
• type EventType
• type Hook
• type HookFunc
  • func (f HookFunc) OnEvent(ctx context.Context, evt Event)
• type Loop
  • func NewLoop(client llm.Client, registry *tool.Registry, hooks ...Hook) *Loop
  • func (l *Loop) Run(ctx context.Context, initial []llm.ChatMessage, opts RunOptions) (llm.ChatResponse, error)
• type RunOptions
• type ToolReplayRequest
• type ToolReplayResult

Types

type AuditEntry

type AuditEntry struct {
	Time         time.Time `json:"time"`
	Type         EventType `json:"type"`
	Iteration    int       `json:"iteration,omitempty"`
	MessageCount int       `json:"message_count,omitempty"`
	ToolName     string    `json:"tool_name,omitempty"`
	ToolCallID   string    `json:"tool_call_id,omitempty"`
	Error        string    `json:"error,omitempty"`
}

type AuditHook

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

func NewAuditHook

func NewAuditHook(maxEntries int) *AuditHook

func (*AuditHook) Entries

func (h *AuditHook) Entries() []AuditEntry

func (*AuditHook) OnEvent

func (h *AuditHook) OnEvent(_ context.Context, evt Event)

type CounterHook

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

func NewCounterHook

func NewCounterHook() *CounterHook

func (*CounterHook) OnEvent

func (h *CounterHook) OnEvent(_ context.Context, evt Event)

func (*CounterHook) Snapshot

func (h *CounterHook) Snapshot() map[EventType]int

type Event

type Event struct {
	Type                       EventType
	Iteration                  int
	MessageCount               int
	ToolName                   string
	ToolCallID                 string
	ToolArgs                   string
	ToolResult                 string
	ToolIsError                bool
	ToolEffectClass            string
	ToolIdempotencyKeyArgument string
	ToolReplayed               bool
	ToolReceiptID              string
	SessionID                  string
	Err                        error
}

type EventType

type EventType string

const (
	EventLoopStart  EventType = "loop_start"
	EventBeforeLLM  EventType = "before_llm"
	EventAfterLLM   EventType = "after_llm"
	EventBeforeTool EventType = "before_tool_call"
	EventAfterTool  EventType = "after_tool_call"
	// EventProviderTool fires once for each tool the upstream provider
	// already executed internally (currently only claude-code-cli). It
	// surfaces audit data — ToolName, ToolCallID, ToolArgs — without
	// triggering local execution. Observers (console, ops) treat it as a
	// read-only signal of what the upstream agent did.
	EventProviderTool   EventType = "provider_tool"
	EventLoopEnd        EventType = "loop_end"
	EventLoopError      EventType = "error"
	DefaultMaxLoopIters           = 20
)

type Hook

type Hook interface {
	OnEvent(ctx context.Context, evt Event)
}

type HookFunc

type HookFunc func(ctx context.Context, evt Event)

func (HookFunc) OnEvent

func (f HookFunc) OnEvent(ctx context.Context, evt Event)

type Loop

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

func NewLoop

func NewLoop(client llm.Client, registry *tool.Registry, hooks ...Hook) *Loop

func (*Loop) Run

func (l *Loop) Run(ctx context.Context, initial []llm.ChatMessage, opts RunOptions) (llm.ChatResponse, error)

type RunOptions

type RunOptions struct {
	MaxIterations    int
	OnDelta          func(text string)
	OnReasoningDelta func(text string)
	Tools            []llm.ToolSchema
	BlockedTools     map[string]tool.BlockedToolError
	ToolChoice       *llm.ToolChoice
	ResponseFormat   *llm.ResponseFormat
	AutoExpandOnce   bool
	// OnTurnEnd is invoked when the LLM produces a turn with zero tool calls
	// (i.e. the natural stopping point). It can request another iteration by
	// returning a non-empty `injectInput` string, which will be appended as a
	// user-role message and the loop will continue. Returning an empty
	// `injectInput` lets the loop terminate as usual. Returning an error
	// aborts the loop.
	OnTurnEnd        func(ctx context.Context, lastResp llm.ChatResponse) (injectInput string, err error)
	BeforeTool       func(ctx context.Context, event Event) error
	AfterTool        func(ctx context.Context, event Event) error
	AfterLLM         func(ctx context.Context, event Event) error
	ProviderTool     func(ctx context.Context, event Event) error
	ReplayToolResult func(ctx context.Context, request ToolReplayRequest) (ToolReplayResult, bool)
	// ResumeSessionID seeds the first iteration's ChatOptions.ResumeSessionID
	// so resumable providers (claude-code-cli) continue an existing upstream
	// session rather than starting a new one. Subsequent iterations
	// auto-update from the previous response's SessionID so the whole loop
	// stays attached to the same upstream session.
	ResumeSessionID string
	// ClaudeCodeMCPServers is forwarded to ChatOptions on every iteration so
	// the claude-code-cli provider can inject the same MCP server set per
	// turn. Other providers ignore it.
	ClaudeCodeMCPServers []llm.ClaudeCodeMCPServer
	// ClaudeCodePermissionMode selects --permission-mode for the
	// claude-code-cli provider. Forwarded as-is; invalid values fall back to
	// "auto" inside the provider.
	ClaudeCodePermissionMode string
	// ClaudeCodeSkills is forwarded to ChatOptions on every iteration so the
	// claude-code-cli provider materializes the same session skill catalog
	// as a --plugin-dir per turn. Other providers ignore it.
	ClaudeCodeSkills []llm.ClaudeCodeSkill
	// ClaudeCodePermissionDeny is forwarded to ChatOptions on every iteration
	// so the claude-code-cli provider materializes the same session-scoped
	// permission deny rules as a --settings file per turn. Other providers
	// ignore it.
	ClaudeCodePermissionDeny []string
}

type ToolReplayRequest

type ToolReplayRequest struct {
	ToolName               string
	ToolCallID             string
	ToolArgs               string
	EffectClass            string
	IdempotencyKeyArgument string
}

type ToolReplayResult

type ToolReplayResult struct {
	Result    string
	IsError   bool
	ReceiptID string
}