agent

Documentation

Overview

Package agent implements ub's headless provider/tool loop.

Index

• Variables
• func SummarizeToolInput(name string, raw json.RawMessage) string
• type ActivityKind
• type Agent
  • func New(opts Options) (*Agent, error)
  • func (a *Agent) Compact(ctx context.Context, req CompactRequest) (CompactResult, error)
  • func (a *Agent) Run(ctx context.Context, req Request) (Result, error)
• type CompactRequest
• type CompactResult
• type Event
• type EventSink
• type EventType
• type LimitAsker
• type LimitExtensionRequest
• type LimitExtensionResponse
• type Options
• type Request
• type Result
• type RuntimeContext

Variables

var ErrMaxTurns = errors.New("agent: max turns reached")

ErrMaxTurns is returned when a run exceeds its provider/tool loop limit.

Functions

func SummarizeToolInput

func SummarizeToolInput(name string, raw json.RawMessage) string

Types

type ActivityKind

type ActivityKind string

ActivityKind identifies a structured Agent activity event.

const (
	ActivityThinking   ActivityKind = "thinking"
	ActivityTool       ActivityKind = "tool"
	ActivityPermission ActivityKind = "permission"
	ActivityNotice     ActivityKind = "notice"
)

type Agent

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

Agent runs a single headless agent loop.

func New

func New(opts Options) (*Agent, error)

New constructs an Agent.

func (*Agent) Compact

func (a *Agent) Compact(ctx context.Context, req CompactRequest) (CompactResult, error)

Compact manually summarizes earlier history without checking the automatic trigger threshold.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, req Request) (Result, error)

Run executes one user prompt.

type CompactRequest

type CompactRequest struct {
	SessionID string
	Turn      int
	History   []message.Message
}

CompactRequest is one manual context compact request.

type CompactResult

type CompactResult struct {
	Messages          []message.Message
	Summary           string
	CompactedMessages int
	KeptMessages      int
	EstimatedTokens   int
	Noop              bool
	Reason            string
}

CompactResult reports the result of a manual context compact request.

type Event

type Event struct {
	Type         EventType
	Text         string
	ToolUseID    string
	ToolName     string
	Content      string
	ActivityKind ActivityKind
	Status       string
	Summary      string
	Decision     string
	Source       string
	Reason       string
	Allowed      bool
	IsError      bool
	Err          error

	ContextUsedTokens int
	ContextMaxTokens  int
	ContextRatio      float64
	ContextReset      bool
	ContextKind       string
}

Event reports Agent progress to interactive callers such as the TUI.

type EventSink

type EventSink func(Event)

EventSink receives Agent runtime events in emission order.

type EventType

type EventType string

EventType identifies an Agent runtime event.

const (
	EventDeltaText     EventType = "delta_text"
	EventActivity      EventType = "activity"
	EventContext       EventType = "context"
	EventToolCallStart EventType = "tool_call_start"
	EventToolCallEnd   EventType = "tool_call_end"
	EventPermission    EventType = "permission"
	EventDone          EventType = "done"
	EventError         EventType = "error"
)

type LimitAsker

type LimitAsker interface {
	// AskExtension blocks until the host responds. Return ExtraTurns > 0 to
	// extend the loop; return 0 (or zero-value response) to fall through to
	// the no-tool finalize path. An error aborts the run.
	AskExtension(ctx context.Context, req LimitExtensionRequest) (LimitExtensionResponse, error)
}

LimitAsker lets the agent pause when a tool-loop run hits the max-turns cap and ask the host for permission to keep going. Without it the loop silently falls through to finalizeWithoutTools, which is awkward for reasoning models that still want to call tools.

type LimitExtensionRequest

type LimitExtensionRequest struct {
	SessionID string
	UserTurn  int
	UsedTurns int
}

LimitExtensionRequest describes the limit-extension prompt.

type LimitExtensionResponse

type LimitExtensionResponse struct {
	ExtraTurns int
}

LimitExtensionResponse carries the host's decision.

type Options

type Options struct {
	Provider         provider.Provider
	Tools            *tool.Registry
	Permission       *permission.Manager
	Rollout          rollout.Writer
	Model            string
	Mode             execution.Mode
	ModeFunc         func() execution.Mode
	MaxTurns         int
	LimitAsker       LimitAsker
	Events           EventSink
	Reasoning        *reasoning.Config
	MaxContextTokens int
	SummaryProvider  provider.Provider
	SummaryModel     string
	Context          config.ContextConfig
	Runtime          RuntimeContext
	ToolOutputState  string
}

Options configures an Agent.

type Request

type Request struct {
	SessionID string
	Turn      int
	History   []message.Message
	Prompt    string
}

Request is one Agent run input.

type Result

type Result struct {
	Text     string
	Messages []message.Message
}

Result is the final Agent run output.

type RuntimeContext

type RuntimeContext struct {
	Workspace string
	Shell     string
	OS        string
}

RuntimeContext describes the local execution environment for one agent run. It is sent to providers on every request but is not persisted in rollout history.