loop

type Budget struct {
	MaxModelResponses    int
	MaxConsecutiveErrors int
	MaxPhysicalAttempts  int
}

type BudgetUsage struct {
	ModelResponses    int
	ConsecutiveErrors int
}

type Config struct {
	Tools  []Tool
	Budget Budget
	// RequireTerminalTool makes plain assistant text private: only a
	// Host-accepted terminal decision ends the wake (see AcceptFinalText).
	RequireTerminalTool bool
	// RequireNativeToolCall asks the provider for a tool call without
	// choosing which one (tool_choice "required").
	RequireNativeToolCall bool
	// AcceptFinalText lets a FinalTextHost accept a first plain answer of up
	// to FinalTextLimit bytes (default 8000) when RequireTerminalTool is set.
	AcceptFinalText bool
	FinalTextLimit  int
	// TurnTools narrows the tools offered to the next model call (call
	// counts from 1) given the outcomes so far; nil offers every tool. Calls
	// to a tool that was not offered are rejected like unknown tools.
	TurnTools func(call int, outcomes []ToolOutcome) []string
	// Locale selects the built-in repair texts (en, zh-CN).
	Locale string
	// RepairText replaces the built-in instruction appended after a rejected
	// response or provider error.
	RepairText func(err error) string
	// ValidateBatch and ValidateText add Host rules to the built-in batch
	// validation (unknown tools, exclusivity, terminal conflicts, argument
	// schemas) and to public text (plain replies and "reply" arguments).
	ValidateBatch func([]ToolCall) error
	ValidateText  func(string) error
	// Permanent classifies provider errors that end the wake at once.
	Permanent func(error) bool
	// Hooks observe the wake; they never change it and must not block.
	OnModelCall     func(context.Context, ModelCall)
	OnToolCall      func(context.Context, ToolCall, ToolResult, error, time.Duration)
	OnBatchRejected func([]ToolCall, error)
	OnModelFailure  func(error)
}

type Decision struct {
	Kind  Disposition
	Reply string
}

type Disposition string

type FinalTextHost interface {
	AcceptFinalText(context.Context, Identity, string) (ToolResult, error)
}

type Host interface {
	Execute(context.Context, Identity, ToolCall) (ToolResult, error)
}

type HostFunc func(context.Context, Identity, ToolCall) (ToolResult, error)

type Identity struct {
	Tenant   string
	Employee string
	Scene    string
	Receipt  string
}

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

type ModelCall struct {
	Attempt  int
	Request  []*schema.Message
	Response *schema.Message
	Err      error
	Elapsed  time.Duration
}

type Outcome struct {
	Decision
	// ModelCalls counts provider requests (physical attempts).
	ModelCalls   int
	Receipts     []Receipt
	ToolOutcomes []ToolOutcome
	BudgetUsage  BudgetUsage
	Usage        Usage
	// Transcript is the accepted conversation: the wake's messages, accepted
	// responses and their tool results. Rejected output is never kept.
	Transcript []*schema.Message
}

type Receipt struct {
	NativeToolCallID string
	ToolName         string
	ID               string
}

type Tool struct {
	Name        string
	Description string
	// Schema is the JSON Schema of the arguments, sent to the model and used
	// for validation before any call runs.
	Schema map[string]any
	// Effect tools change the world; a successful call must return a Host
	// receipt.
	Effect bool
	// Terminal declares the disposition the tool always ends with, so a
	// batch mixing dispositions is rejected before any effect.
	Terminal Disposition
	// Exclusive tools must be the only call of their batch.
	Exclusive bool
	// Timeout bounds one call; zero leaves it to the wake context.
	Timeout time.Duration
}

type ToolCall struct {
	// Origin marks calls the loop made on the Host's behalf (FinalTextOrigin).
	Origin           string         `json:"origin,omitempty"`
	NativeToolCallID string         `json:"native_tool_call_id"`
	Name             string         `json:"name"`
	Arguments        map[string]any `json:"arguments"`
}

type ToolOutcome struct {
	Origin           string
	NativeToolCallID string
	ToolName         string
	Result           ToolResult
	Error            string
}

type ToolResult struct {
	Content  string
	Receipt  string
	Terminal *Decision
}

type Usage struct {
	PromptTokens     int
	CompletionTokens int
}

type Wake struct {
	Identity Identity
	Messages []*schema.Message
}