agent

package
v0.0.0-...-f56615f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package agent orchestrates model turns, tool approvals, and tool results.

Index

Constants

View Source 
const (
	// The nominal context window describes the model capability. SuperCode
	// starts compaction at 90% and never builds a request beyond 95%, leaving
	// the final 5% for system instructions, tool schemas, and model output.
	DefaultContextWindowTokens = 272_000
	DefaultAutoCompactTokens   = 244_800
	DefaultUsableContextTokens = 258_400
	DefaultToolOutputTokens    = 12_000
)

Variables

This section is empty.

Functions

func CompactHistory 

func CompactHistory(history []provider.Message, targetTokens int) ([]provider.Message, bool)

CompactHistory replaces older complete turns with a bounded structural summary while preserving a recent suffix that begins at a user boundary. It is deterministic so it remains available for custom/local providers.

func EstimateMessagesTokens 

func EstimateMessagesTokens(messages []provider.Message) int

func EstimateTextTokens 

func EstimateTextTokens(value string) int

EstimateTextTokens intentionally uses a conservative, provider-neutral approximation. It handles English code and CJK text more safely than a byte/4 estimate without coupling the agent layer to a model tokenizer.

Types

type ApprovalDecision 

type ApprovalDecision string

ApprovalDecision records both whether a call is allowed and how long that decision should remain effective. 

const (
	ApprovalDeny                  ApprovalDecision = "deny"
	ApprovalAllowOnce             ApprovalDecision = "allow_once"
	ApprovalAllowSession          ApprovalDecision = "allow_session"
	ApprovalAllowPrefix           ApprovalDecision = "allow_prefix"
	ApprovalAllowPersistentPrefix ApprovalDecision = "allow_persistent_prefix"
)

type ApprovalMode 

type ApprovalMode string
const (
	ApprovalOnRequest ApprovalMode = "on-request"
	ApprovalAlways    ApprovalMode = "always"
	ApprovalNever     ApprovalMode = "never"
	ApprovalGranular  ApprovalMode = "granular"
)

func ParseApprovalMode 

func ParseApprovalMode(value string) (ApprovalMode, error)

type ApprovalRequest 

type ApprovalRequest struct {
	Call        provider.ToolCall
	Risk        tool.Risk
	Category    tool.Category
	Summary     string
	Permissions *permission.Request
	Prefix      string
	PolicyPath  string
	// contains filtered or unexported fields
}

ApprovalRequest is resolved exactly once by the UI or non-interactive host.

func (*ApprovalRequest) Decide 

func (r *ApprovalRequest) Decide(approved bool)

Decide preserves the original boolean API for non-interactive hosts.

func (*ApprovalRequest) DecideWithScope 

func (r *ApprovalRequest) DecideWithScope(decision ApprovalDecision)

type Event 

type Event struct {
	Type         EventType
	Delta        string
	Call         *provider.ToolCall
	Risk         tool.Risk
	Category     tool.Category
	Summary      string
	Result       *tool.Result
	Approval     *ApprovalRequest
	Response     *provider.Response
	History      []provider.Message
	Err          error
	Queued       []string
	BeforeTokens int
	AfterTokens  int
	SessionID    int64
}

type EventType 

type EventType string
const (
	EventTextDelta        EventType = "text_delta"
	EventToolStarted      EventType = "tool_started"
	EventToolOutputDelta  EventType = "tool_output_delta"
	EventApprovalRequired EventType = "approval_required"
	EventToolFinished     EventType = "tool_finished"
	EventCompleted        EventType = "completed"
	EventQueuedCommitted  EventType = "queued_committed"
	EventContextCompacted EventType = "context_compacted"
	EventError            EventType = "error"
)

type Hook 

type Hook func(context.Context, HookEvent, HookInput) (HookOutput, error)

type HookEvent 

type HookEvent string
const (
	HookUserPromptSubmit HookEvent = "user_prompt_submit"
	HookPreToolUse       HookEvent = "pre_tool_use"
	HookPostToolUse      HookEvent = "post_tool_use"
	HookPermission       HookEvent = "permission_request"
	HookPreCompact       HookEvent = "pre_compact"
	HookPostCompact      HookEvent = "post_compact"
	HookSubagentStart    HookEvent = "subagent_start"
	HookSubagentStop     HookEvent = "subagent_stop"
)

type HookInput 

type HookInput struct {
	Prompt       string             `json:"prompt,omitempty"`
	Call         *provider.ToolCall `json:"call,omitempty"`
	Risk         tool.Risk          `json:"risk,omitempty"`
	Category     tool.Category      `json:"category,omitempty"`
	Result       *tool.Result       `json:"result,omitempty"`
	BeforeTokens int                `json:"before_tokens,omitempty"`
	AfterTokens  int                `json:"after_tokens,omitempty"`
}

type HookOutput 

type HookOutput struct {
	Allow             *bool  `json:"allow,omitempty"`
	Message           string `json:"message,omitempty"`
	Prompt            string `json:"prompt,omitempty"`
	Arguments         string `json:"arguments,omitempty"`
	AdditionalContext string `json:"additional_context,omitempty"`
}

type Input 

type Input struct {
	Prompt       string
	History      []provider.Message
	Instructions string
	Images       []provider.Image
}

type Options 

type Options struct {
	Model               string
	Instructions        string
	Stream              bool
	MaxTurns            int
	Approval            ApprovalMode
	ContextWindowTokens int
	AutoCompactTokens   int
	UsableContextTokens int
	ToolOutputTokens    int
	OnUsage             func(provider.Usage)
	Hook                Hook
	FallbackModels      []string
	RequestTimeout      time.Duration
	Policy              *policy.Store
	ReasoningEffort     string
	ServiceTier         string
	OnEvent             func(Event)
	OnMemoryCitation    func([]string)
	Permissions         *permission.Manager
	ApprovalCategories  map[tool.Category]bool
	ModelCatalog        *modelcatalog.Catalog
}

type RunHandle 

type RunHandle struct {
	Events <-chan Event
	// contains filtered or unexported fields
}

RunHandle permits user messages to steer an active turn at the next tool boundary while events continue streaming independently.

func (*RunHandle) Queue 

func (h *RunHandle) Queue(message string) bool

type Runner 

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

func New 

func New(modelProvider provider.Provider, registry *tool.Registry, options Options) (*Runner, error)

func (*Runner) ContextLimits 

func (r *Runner) ContextLimits() (int, int, int)

func (*Runner) Fork 

func (r *Runner) Fork(model string, approval ApprovalMode) (*Runner, error)

Fork creates an isolated runner with the same provider, tools, context limits, and hooks. It lets sub-agents select another compatible model without mutating the parent runner.

func (*Runner) ForkConfigured 

func (r *Runner) ForkConfigured(model string, approval ApprovalMode, reasoningEffort string) (*Runner, error)

ForkConfigured creates a child runner while applying model-specific reasoning configuration. Child runs share the parent's global read-tool budget, but do not expire grants owned by the parent user turn.

func (*Runner) Model 

func (r *Runner) Model() string

func (*Runner) ModelCapabilities 

func (r *Runner) ModelCapabilities(model string) (modelcatalog.Capabilities, bool)

func (*Runner) NotifyHook 

func (r *Runner) NotifyHook(ctx context.Context, event HookEvent, input HookInput) error

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, input Input) <-chan Event

Run returns an event stream and performs the agent loop in a cancellable goroutine. The caller must keep consuming events until the channel closes.

func (*Runner) SetApproval 

func (r *Runner) SetApproval(mode ApprovalMode) error

func (*Runner) SetModel 

func (r *Runner) SetModel(model string) error

SetModel and SetApproval are used by interactive slash commands between turns. The TUI never mutates these settings while a run is active.

func (*Runner) SetReasoningEffort 

func (r *Runner) SetReasoningEffort(value string)

func (*Runner) SetServiceTier 

func (r *Runner) SetServiceTier(value string)

func (*Runner) Start 

func (r *Runner) Start(ctx context.Context, input Input) *RunHandle

func (*Runner) ToolNames 

func (r *Runner) ToolNames() []string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.