agent

type EndReason string

type Event struct {
	Kind       EventKind
	Text       string
	ToolCall   *llm.ToolCall
	ToolResult *ToolResult
	Image      *llm.ImagePart
	Usage      *llm.Usage
	Err        error
	EndReason  EndReason
}

type EventKind string

type History interface {
	Append(ctx context.Context, sessionID string, messages ...llm.Message) error
	Read(ctx context.Context, sessionID string) ([]llm.Message, error)
}

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

type Locker interface {
	Lock(ctx context.Context, sessionID string) (unlock func(), err error)
}

type RunOptions struct {
	// SystemSuffix is appended to SessionOptions.SystemPrompt for this run
	// only, e.g. a reply-style instruction for a spoken answer. It is never
	// written to History.
	SystemSuffix string
	// Thinking replaces SessionOptions.Thinking for this run's model calls.
	// Nil keeps the session's setting.
	Thinking *llm.ThinkingConfiguration
}

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

type SessionOptions struct {
	// ID keys the session's History and Locker entries. Required.
	ID string
	// Client is the model client every turn streams from. Required.
	Client llm.Client
	// Tools are offered to the model and dispatched when it calls them. Nil
	// offers no tools; a tool call then fails with tools.ErrUnknownTool.
	Tools *tools.Registry
	// History stores the conversation Run continues. Required.
	History History
	// Locker serializes runs of the same session ID. Required.
	Locker Locker
	// Model is the provider's model ID. Required.
	Model string
	// SystemPrompt is sent as the first message of every model call. Empty
	// sends none. It is never written to History.
	SystemPrompt string

	// MaximumTurns caps the model calls of one run; zero or negative means 20.
	MaximumTurns int
	// RunTimeout caps one whole run; zero means 10 minutes, negative is an
	// error.
	RunTimeout time.Duration
	// LLMCallTimeout caps one model call; zero means 180 seconds, negative is
	// an error.
	LLMCallTimeout time.Duration
	// MaximumTokens caps the tokens of one model reply; zero means 16384.
	MaximumTokens int
	// Temperature is the sampling temperature; nil leaves the model default.
	Temperature *float32
	// Thinking sets the reasoning effort or budget of every model call, e.g.
	// llm.ThinkingByEffort(llm.ThinkingEffortLow). Nil leaves the model default.
	Thinking *llm.ThinkingConfiguration

	// ToolCallTimeout caps one tool call; zero means 2 minutes, negative
	// means no cap. A call that fails after its deadline passed is reported
	// to the model as timed out and the run continues. The cap reaches the
	// handler as its context's deadline, so it binds only handlers that
	// honour ctx.
	ToolCallTimeout time.Duration
	// MaximumToolResultBytes caps the JSON of one tool result the model sees
	// (and History stores); zero means 64 KiB, negative means no cap. A
	// longer result is replaced by {"truncated":true,"total_bytes":N,
	// "notice":"...","content":"<prefix of the JSON>"}, itself within the cap
	// unless the cap is too small for the notice. EventToolResult always
	// carries the full result.
	MaximumToolResultBytes int
	// DisablePromptCaching stops the run from setting prompt-cache
	// breakpoints. By default every model request marks the system prompt
	// and its last message (if that has content) with llm.CacheBreakpoint
	// (5 minute TTL), at most 2 of the 4 breakpoints Anthropic allows. A
	// request whose messages already carry a breakpoint is sent unchanged,
	// so a History that sets its own keeps control. Breakpoints are added to
	// the request only, never to History. Providers that cache on their own
	// or not at all (OpenAI, most open models) ignore them; the Anthropic
	// and Gemini models on OpenRouter honour them.
	DisablePromptCaching bool
}

type ToolResult struct {
	// CallID is the llm.ToolCall ID this result answers.
	CallID string
	// Name is the called tool's name.
	Name string
	// OK is false when the tool failed; Error then holds its message.
	OK bool
	// Content is the tool's full result when OK. The model gets it as JSON,
	// cut at SessionOptions.MaximumToolResultBytes.
	Content any
	// Error is the failure message when not OK.
	Error string
	// ModelContent is the tool message content the model received: the JSON
	// of Content or Error, cut at SessionOptions.MaximumToolResultBytes. Drain
	// stores this copy, so a history rebuilt from events matches what the
	// model saw.
	ModelContent string
}

type VFSToolOptions struct {
	// Storage is the file store the tools work on. Required; multi-tenant
	// callers pass a store already bound to the tenant's scope.
	Storage vfs.Storage
	// HideHiddenPaths hides paths with a segment beginning with "_" or "."
	// from listings and rejects them as tool arguments.
	HideHiddenPaths bool
	// AllowedExtensions limits the tools to files with these extensions
	// (".md", compared case-insensitively). Nil allows every file.
	AllowedExtensions []string
	// MaximumFileBytes caps the size of a file the tools write; zero or
	// negative means 1 MiB.
	MaximumFileBytes int64

	// ReadOnly disables registration of write_file, delete_file, edit_file,
	// multi_edit and move_file. Use this for fixed-corpus deployments (e.g.
	// an embedded knowledge base over vfs/embedfs). Search and list/read
	// remain registered.
	ReadOnly bool

	// DisableExtended skips registration of grep, glob, edit_file,
	// multi_edit and move_file, leaving the original
	// read_file/write_file/list_files/delete_file/search set.
	DisableExtended bool
}