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

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
	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)
	// 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
}