agent

Documentation

Index

• type Agent
  • func NewAgent(p provider.Provider, tools *tool.Registry, systemPrompt string, maxIter int) *Agent
  • func (a *Agent) AddMessage(msg provider.Message)
  • func (a *Agent) CancelPreCompact()
  • func (a *Agent) CheckpointManager() *checkpoint.Manager
  • func (a *Agent) Clear()
  • func (a *Agent) Close()
  • func (a *Agent) ContextManager() ctxpkg.ContextManager
  • func (a *Agent) Messages() []provider.Message
  • func (a *Agent) PermissionPolicy() permission.PermissionPolicy
  • func (a *Agent) PreCompactStatus() PreCompactStatus
  • func (a *Agent) ProjectMemoryFiles() []string
  • func (a *Agent) Provider() provider.Provider
  • func (a *Agent) RunStream(ctx context.Context, userMsg string, onEvent func(provider.StreamEvent)) error
  • func (a *Agent) RunStreamWithContent(ctx context.Context, content []provider.ContentBlock, ...) (err error)
  • func (a *Agent) SetApprovalHandler(fn ApprovalFunc)
  • func (a *Agent) SetCheckpointHandler(fn func(messages []provider.Message, tokenCount int))
  • func (a *Agent) SetCheckpointManager(m *checkpoint.Manager)
  • func (a *Agent) SetContextManager(cm ctxpkg.ContextManager)
  • func (a *Agent) SetDiffConfirm(fn DiffConfirmFunc)
  • func (a *Agent) SetHookConfig(cfg hooks.HookConfig)
  • func (a *Agent) SetInterruptionHandler(fn func() string)
  • func (a *Agent) SetPermissionPolicy(policy permission.PermissionPolicy)
  • func (a *Agent) SetProbeKey(key string)
  • func (a *Agent) SetProjectMemoryFiles(files []string)
  • func (a *Agent) SetProvider(p provider.Provider)
  • func (a *Agent) SetRunResultHandler(fn func(error))
  • func (a *Agent) SetRunResultWithContentHandler(fn func([]provider.ContentBlock, error))
  • func (a *Agent) SetSupportsVision(v bool)
  • func (a *Agent) SetUsageHandler(fn func(usage provider.TokenUsage))
  • func (a *Agent) SetWorkingDir(dir string)
  • func (a *Agent) StartPreCompact()
  • func (a *Agent) SupportsVision() bool
  • func (a *Agent) SystemPrompt() string
  • func (a *Agent) ToolRegistry() *tool.Registry
  • func (a *Agent) UpdateSystemPrompt(text string)
  • func (a *Agent) WorkingDir() string
• type ApprovalFunc
• type DiffConfirmFunc
• type PreCompactStatus

Types

type Agent

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

Agent orchestrates the agentic loop: send messages to LLM, execute tool calls, loop.

func NewAgent

func NewAgent(p provider.Provider, tools *tool.Registry, systemPrompt string, maxIter int) *Agent

NewAgent creates a new agent with optional permission policy.

func (*Agent) AddMessage

func (a *Agent) AddMessage(msg provider.Message)

AddMessage appends a message to the conversation context.

func (*Agent) CancelPreCompact

func (a *Agent) CancelPreCompact()

CancelPreCompact aborts any in-flight pre-compact. Safe to call from session-clear, /clear, /compact, SetContextManager or app shutdown.

The goroutine sees its bgCtx cancelled, marks the state as cancelled, then closes done. A later consumeReadyPreCompact will discard the result.

func (*Agent) CheckpointManager

func (a *Agent) CheckpointManager() *checkpoint.Manager

CheckpointManager returns the checkpoint manager.

func (*Agent) Clear

func (a *Agent) Clear()

Clear resets the conversation (keeps system prompt).

func (*Agent) Close

func (a *Agent) Close()

Close releases resources held by the agent, including cancelling any in-flight pre-compact operations. Should be called on shutdown.

func (*Agent) ContextManager

func (a *Agent) ContextManager() ctxpkg.ContextManager

func (*Agent) Messages

func (a *Agent) Messages() []provider.Message

Messages returns the current conversation messages.

func (*Agent) PermissionPolicy

func (a *Agent) PermissionPolicy() permission.PermissionPolicy

PermissionPolicy returns the current policy.

func (*Agent) PreCompactStatus

func (a *Agent) PreCompactStatus() PreCompactStatus

PreCompactStatus reports the current background pre-compact status, or a zero value if none is running. Used by the TUI status panel to surface a "compacting…" indicator instead of leaving the user wondering why tokens are at the threshold.

func (*Agent) ProjectMemoryFiles

func (a *Agent) ProjectMemoryFiles() []string

func (*Agent) Provider

func (a *Agent) Provider() provider.Provider

func (*Agent) RunStream

func (a *Agent) RunStream(ctx context.Context, userMsg string, onEvent func(provider.StreamEvent)) error

RunStream runs the agent loop with streaming, sending events to the callback.

func (*Agent) RunStreamWithContent

func (a *Agent) RunStreamWithContent(ctx context.Context, content []provider.ContentBlock, onEvent func(provider.StreamEvent)) (err error)

RunStreamWithContent runs the agent loop and emits UI events for complete model turns.

func (*Agent) SetApprovalHandler

func (a *Agent) SetApprovalHandler(fn ApprovalFunc)

SetApprovalHandler sets a callback for interactive approval (Ask → Deny by default). If nil, Ask decisions are treated as Deny. The callback receives the per-run context so it can abort cleanly if the agent is cancelled while waiting.

func (*Agent) SetCheckpointHandler

func (a *Agent) SetCheckpointHandler(fn func(messages []provider.Message, tokenCount int))

SetCheckpointHandler sets a callback invoked after summarize compaction to persist the compacted message state.

func (*Agent) SetCheckpointManager

func (a *Agent) SetCheckpointManager(m *checkpoint.Manager)

SetCheckpointManager sets the checkpoint manager for undo support.

func (*Agent) SetContextManager

func (a *Agent) SetContextManager(cm ctxpkg.ContextManager)

SetContextManager replaces the default context manager.

func (*Agent) SetDiffConfirm

func (a *Agent) SetDiffConfirm(fn DiffConfirmFunc)

SetDiffConfirm sets the diff confirmation callback.

func (*Agent) SetHookConfig

func (a *Agent) SetHookConfig(cfg hooks.HookConfig)

SetHookConfig sets the hooks configuration.

func (*Agent) SetInterruptionHandler

func (a *Agent) SetInterruptionHandler(fn func() string)

SetInterruptionHandler sets a callback that drains user guidance arriving mid-run.

func (*Agent) SetPermissionPolicy

func (a *Agent) SetPermissionPolicy(policy permission.PermissionPolicy)

SetPermissionPolicy sets the permission policy for tool checks.

func (*Agent) SetProbeKey

func (a *Agent) SetProbeKey(key string)

SetProbeKey sets the probe cache key ("vendor|baseURL|model") used for context window auto-detection from overflow errors.

func (*Agent) SetProjectMemoryFiles

func (a *Agent) SetProjectMemoryFiles(files []string)

SetProjectMemoryFiles seeds the set of already-loaded project memory files so path-triggered dynamic loading can avoid reinjecting startup guidance.

func (*Agent) SetProvider

func (a *Agent) SetProvider(p provider.Provider)

ContextManager returns the context manager for external inspection.

func (*Agent) SetRunResultHandler

func (a *Agent) SetRunResultHandler(fn func(error))

SetRunResultHandler sets a callback invoked after each RunStreamWithContent call completes. The callback receives the final error, if any.

func (*Agent) SetRunResultWithContentHandler

func (a *Agent) SetRunResultWithContentHandler(fn func([]provider.ContentBlock, error))

SetRunResultWithContentHandler sets a callback invoked after each RunStreamWithContent call completes. The callback receives the original user content and the final error, if any.

func (*Agent) SetSupportsVision

func (a *Agent) SetSupportsVision(v bool)

SetSupportsVision controls whether tool_result images are included in messages sent to the provider. When false, image data is stripped from tool results and only the text placeholder is sent.

func (*Agent) SetUsageHandler

func (a *Agent) SetUsageHandler(fn func(usage provider.TokenUsage))

SetUsageHandler sets a callback invoked after each API call with token usage.

func (*Agent) SetWorkingDir

func (a *Agent) SetWorkingDir(dir string)

SetWorkingDir sets the working directory for hooks.

func (*Agent) StartPreCompact

func (a *Agent) StartPreCompact()

StartPreCompact initiates a background compaction if conditions warrant it. Returns immediately. Safe to call after every agent run; it self-skips when tokens are below threshold or a compact is already in flight.

The background goroutine compacts an immutable snapshot with its own context.WithTimeout(60s). It never mutates the live context directly; the result is applied later by consumeReadyPreCompact only if it has already finished at a safe run boundary.

func (*Agent) SupportsVision

func (a *Agent) SupportsVision() bool

func (*Agent) SystemPrompt

func (a *Agent) SystemPrompt() string

SystemPrompt returns the current system prompt (from the first system message).

func (*Agent) ToolRegistry

func (a *Agent) ToolRegistry() *tool.Registry

ToolRegistry returns the tool registry used by this agent.

func (*Agent) UpdateSystemPrompt

func (a *Agent) UpdateSystemPrompt(text string)

UpdateSystemPrompt replaces the first system message in the context. If no system message exists, it adds one.

func (*Agent) WorkingDir

func (a *Agent) WorkingDir() string

type ApprovalFunc

type ApprovalFunc func(ctx context.Context, toolName string, input string) permission.Decision

ApprovalFunc is called when a tool requires interactive approval. It MUST honor ctx.Done() to avoid a goroutine leak if the TUI exits while a permission prompt is awaiting user input.

type DiffConfirmFunc

type DiffConfirmFunc func(ctx context.Context, filePath, diffText string) bool

DiffConfirmFunc is called before a file write to request user confirmation. It receives a context, the file path and unified diff string, and returns true if approved. Implementations MUST honor ctx.Done() so the agent goroutine doesn't leak when the TUI shuts down while a confirmation is in flight.

type PreCompactStatus

type PreCompactStatus struct {
	Running   bool
	StartedAt time.Time
	StartTok  int
}

PreCompactStatus is a UI-friendly snapshot of any in-flight pre-compact. Returned by Agent.PreCompactStatus(). All fields are zero-valued when none is running.