loop

type AfterModeler interface {
	AfterModel(ctx context.Context, run *Run, req *model.Request, resp *model.Response) error
}

type AfterRunner interface {
	AfterRun(ctx context.Context, run *Run, res *Result)
}

type AfterTooler interface {
	AfterTool(ctx context.Context, run *Run, plan *ToolPlan, res *model.ToolResult) error
}

type AnswerHolder interface {
	HoldAnswer() bool
}

type Approval struct {
	Approved bool `json:"approved"`
	// Reason is shown to the model when the call is denied.
	Reason string `json:"reason,omitempty"`
	// UpdatedInput replaces the call arguments when approved.
	UpdatedInput json.RawMessage `json:"updated_input,omitempty"`
	// Remember asks middleware that decides approvals, such as the
	// permission package's Policy, to approve later calls like this one
	// without asking again, for the rest of the run or of the session.
	// Middleware reads it with ToolPlan.Approval.
	Remember RememberScope `json:"remember,omitempty"`
	// RememberRules, if set, lists what to remember instead of what the
	// middleware derives from the call, for example permission rules such
	// as "Bash(npm test *)".
	RememberRules []string `json:"remember_rules,omitempty"`
}

type ApprovalRequest struct {
	Call *model.ToolCall `json:"call"`
	// Reason is the explanation given by the hook that asked, if any.
	Reason string `json:"reason,omitempty"`
	// Agent names the agent whose call this is. Requests of sub-agents
	// reach the parent's interrupt with their own agent name.
	Agent string `json:"agent,omitempty"`
}

type Approver interface {
	Approve(ctx context.Context, req *ApprovalRequest) (Approval, error)
}

type ApproverFunc func(ctx context.Context, req *ApprovalRequest) (Approval, error)

type BeforeFinisher interface {
	BeforeFinish(ctx context.Context, run *Run, msg *model.Message) (bool, error)
}

type BeforeModeler interface {
	BeforeModel(ctx context.Context, run *Run, req *model.Request) error
}

type BeforeRunner interface {
	BeforeRun(ctx context.Context, run *Run, in *RunInput) error
}

type BeforeTooler interface {
	BeforeTool(ctx context.Context, run *Run, plan *ToolPlan) error
}

type BeforeTurner interface {
	BeforeTurn(ctx context.Context, run *Run) error
}

type Checkpointer interface {
	Save(ctx context.Context, st *State) error
	Load(ctx context.Context, runID string) (*State, error)
	Delete(ctx context.Context, runID string) error
}

type Compaction struct {
	// Messages is the conversation after compaction.
	Messages []*model.Message `json:"messages"`
	// Before and After are the estimated input sizes in tokens.
	Before  int    `json:"before"`
	After   int    `json:"after"`
	Summary string `json:"summary,omitempty"`
}

type Config struct {
	Settings
	Tools *tool.Registry
	// Middlewares extend the loop in order. If any is a ToolProvider, its
	// tools are added to a copy of Tools.
	Middlewares []Middleware
}

type ContextWrapper interface {
	WrapContext(ctx context.Context, run *Run) (_ context.Context, release func())
}

type Decision int

type Event struct {
	Type      EventType `json:"type"`
	RunID     string    `json:"run_id,omitempty"`
	SessionID string    `json:"session_id,omitempty"`
	Agent     string    `json:"agent,omitempty"`
	Turn      int       `json:"turn,omitempty"`

	Delta      *model.StreamEvent `json:"delta,omitempty"`
	Message    *model.Message     `json:"message,omitempty"`
	ToolCall   *model.ToolCall    `json:"tool_call,omitempty"`
	ToolResult *model.ToolResult  `json:"tool_result,omitempty"`
	Compaction *Compaction        `json:"compaction,omitempty"`
	// OutputRetry describes the rejected answer for EventOutputRetry.
	OutputRetry *OutputRetry `json:"output_retry,omitempty"`
	Interrupt   *Interrupt   `json:"interrupt,omitempty"`
	// Handoff describes the transfer for EventHandoff.
	Handoff *Handoff `json:"handoff,omitempty"`
	// Usage is the usage of the model call for EventMessage.
	Usage  model.Usage `json:"usage,omitzero"`
	Result *Result     `json:"result,omitempty"`

	// Depth is zero for the events of the run itself. Events of nested runs,
	// such as a sub-agent's, that a tool call forwards with ForwardEvent
	// have the depth of the nested run below this one: 1 for a sub-agent, 2
	// for a sub-agent of a sub-agent. Their RunID, Agent and Turn are those
	// of the nested run, and an EventRunEnd among them ends the nested run,
	// not this one.
	Depth int `json:"depth,omitempty"`
	// ParentCallID is set on forwarded events to the ID of the tool call
	// that started the nested run that emitted them, in the run directly
	// above it.
	ParentCallID string `json:"parent_call_id,omitempty"`
}

type EventType string

type Funcs struct {
	MiddlewareName     string
	WrapContextFunc    func(ctx context.Context, run *Run) (context.Context, func())
	BeforeRunFunc      func(ctx context.Context, run *Run, in *RunInput) error
	BeforeTurnFunc     func(ctx context.Context, run *Run) error
	BeforeModelFunc    func(ctx context.Context, run *Run, req *model.Request) error
	WrapModelFunc      func(run *Run, next model.Model) model.Model
	AfterModelFunc     func(ctx context.Context, run *Run, req *model.Request, resp *model.Response) error
	BeforeToolFunc     func(ctx context.Context, run *Run, plan *ToolPlan) error
	RevalidateToolFunc func(ctx context.Context, run *Run, plan *ToolPlan) error
	WrapToolFunc       func(run *Run, next tool.Invoker) tool.Invoker
	AfterToolFunc      func(ctx context.Context, run *Run, plan *ToolPlan, res *model.ToolResult) error
	BeforeFinishFunc   func(ctx context.Context, run *Run, msg *model.Message) (bool, error)
	AfterRunFunc       func(ctx context.Context, run *Run, res *Result)
}

type Guardrail struct {
	// Name names the guardrail.
	Name string `json:"name"`
	// Kind is where it ran: "input", "output", "tool_input" or
	// "tool_output".
	Kind string `json:"kind,omitempty"`
	// Message explains the trip, for example to show to the user.
	Message string `json:"message,omitempty"`
	// Info is any information the guardrail attached.
	Info any `json:"info,omitempty"`
}

type GuardrailError struct {
	Guardrail Guardrail
	// Usage is the usage of a model call the guardrail cut short or
	// rejected, which a ModelWrapper returning the error reports so the
	// run still counts it.
	Usage model.Usage
}

type Handoff struct {
	// From and To name the agents.
	From string `json:"from"`
	To   string `json:"to"`
	// Tool and CallID identify the tool call that requested the handoff.
	Tool   string `json:"tool,omitempty"`
	CallID string `json:"call_id,omitempty"`
	// Input holds the arguments of the call, for handoffs with a typed
	// input.
	Input json.RawMessage `json:"input,omitempty"`
}

type Interrupt struct {
	RunID    string             `json:"run_id"`
	Requests []*ApprovalRequest `json:"requests"`
	// State is the state of the paused run. It lets ResumeState continue
	// the run without a Checkpointer, as sub-agents do.
	State *State `json:"state,omitempty"`
}

type Limits struct {
	// Requests bounds the model calls.
	Requests int `json:"requests,omitempty"`
	// ToolCalls bounds the executed tool calls. A batch that would exceed
	// it does not start; denied calls do not count.
	ToolCalls int `json:"tool_calls,omitempty"`
	// InputTokens bounds model.Usage.PromptTokens, the input tokens
	// including cache reads and writes.
	InputTokens int `json:"input_tokens,omitempty"`
	// OutputTokens bounds model.Usage.OutputTokens.
	OutputTokens int `json:"output_tokens,omitempty"`
	// TotalTokens bounds model.Usage.TotalTokens.
	TotalTokens int `json:"total_tokens,omitempty"`
}

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

type Middleware interface {
	// Name identifies the middleware. Names must be unique in a Runtime.
	Name() string
}

type ModelWrapper interface {
	WrapModel(run *Run, next model.Model) model.Model
}

type Output struct {
	// Name names the schema for providers. It defaults to "output" and may
	// hold letters, digits, underscores and dashes, up to 64.
	Name string
	// Schema describes the answer. It must be an object schema with
	// properties, such as tool.SchemaOf of a struct type.
	Schema *tool.Schema
	// Retries bounds how often an answer that does not match Schema is sent
	// back to the model. Zero means DefaultOutputRetries; a negative value
	// means none.
	Retries int
}

type OutputError struct {
	// Output is the text of the last answer. It is empty when an
	// AnswerHolder holds answers: it was rejected before answer-holder checks.
	Output string
	// Problems lists what does not match the schema. When an AnswerHolder
	// holds answers, it reports only a generic mismatch, since detailed
	// diagnostics may quote text that has not passed answer-holder checks.
	Problems []string
	// Attempts is the number of answers checked.
	Attempts int
}

type OutputRetry struct {
	// Output is the text of the answer. It is empty when an AnswerHolder
	// holds answers: it was rejected before answer-holder checks.
	Output string `json:"output"`
	// Problems lists what does not match the schema. When an AnswerHolder
	// holds answers, it reports only a generic mismatch; see OutputError.
	Problems []string `json:"problems,omitempty"`
	// Attempt numbers the answer among those the run checked, from 1. The
	// count restarts when a run that failed with an *OutputError is
	// resumed.
	Attempt int `json:"attempt"`
	// Retries is the number of retries allowed; the run fails with an
	// *OutputError if answer Retries+1 does not match either.
	Retries int `json:"retries"`
}

type PendingCall struct {
	Call *model.ToolCall `json:"call"`
	// Denied is set when middleware or the approver rejected the call.
	Denied bool   `json:"denied,omitempty"`
	Reason string `json:"reason,omitempty"`
	// NeedsApproval is set while approval is outstanding.
	NeedsApproval bool `json:"needs_approval,omitempty"`
	ReadOnly      bool `json:"read_only,omitempty"`
	// Concurrent is set for calls of tools marked tool.Concurrent.
	Concurrent bool `json:"concurrent,omitempty"`
	// Values holds middleware state; see ToolPlan.SetValue.
	Values map[string]string `json:"values,omitempty"`
	// ModelArguments holds the arguments the model sent when middleware or
	// an approval changed them; Call holds the arguments that run.
	ModelArguments json.RawMessage `json:"model_arguments,omitempty"`
	// Started is set once the call began executing, and Result once it
	// finished. A resumed run reuses results and does not repeat a call
	// with side effects that may have run.
	Started bool              `json:"started,omitempty"`
	Result  *model.ToolResult `json:"result,omitempty"`
	// Nested is the interrupt the call raised for approvals of a nested
	// run, such as a sub-agent; see InterruptCall. NestedApprovals holds
	// the decisions once they are made.
	Nested          *Interrupt          `json:"nested,omitempty"`
	NestedApprovals map[string]Approval `json:"nested_approvals,omitempty"`
	// Approval is the decision of the approval the call needed, if any,
	// without its UpdatedInput; see ToolPlan.Approval.
	Approval *Approval `json:"approval,omitempty"`
	// Resuming is set while the call is repeated to resume its nested run.
	// If the run stops then, the nested run may have executed approved
	// calls, so a call with side effects is not repeated, like any cut-off
	// call with side effects. A read-only call is repeated with its nested
	// run, like any cut-off read-only call.
	Resuming bool `json:"resuming,omitempty"`
}

type RememberScope string

type Request struct {
	// RunID identifies the run; generated when empty.
	RunID     string
	SessionID string
	// History is the conversation before Input. It is not modified.
	History []*model.Message
	// Input is the new user message.
	Input *model.Message
	// NewSession marks the first run of a session, for example to fire the
	// SessionStart hook.
	NewSession bool
	// MaxTurns, if positive, overrides Config.MaxTurns for this run.
	MaxTurns int
	// Limits, if non-nil, replaces Config.Limits for this run.
	Limits *Limits
	// Values are the initial values of the run, as Run.SetValue stores
	// them, for example the session-scoped values of the session's earlier
	// runs; see SessionValuePrefix. Empty values are ignored.
	Values map[string]string
	// Usage and Turns are the usage and turns of earlier parts of the same
	// run, such as those of an agent that handed the run off to this one.
	// They count toward the limits and are included in the Result.
	Usage model.Usage
	Turns int
}

type Result struct {
	RunID  string `json:"run_id"`
	Status Status `json:"status"`
	// Reason explains a non-completed status.
	Reason string `json:"reason,omitempty"`
	// FinishReason is the finish reason of the last model response, for
	// example model.FinishRefusal when the model declined to answer.
	FinishReason model.FinishReason `json:"finish_reason,omitempty"`
	// Output is the text of the final assistant message, or the result of
	// the tool the run stopped at; see Config.StopAtTools. Decode parses it.
	Output string `json:"output"`
	// Messages is the whole conversation after the run, including history.
	// It may be shorter than history plus new messages after compaction.
	Messages []*model.Message `json:"messages,omitempty"`
	// NewMessages are the messages added by this run.
	NewMessages []*model.Message `json:"new_messages,omitempty"`
	Usage       model.Usage      `json:"usage"`
	Turns       int              `json:"turns"`
	// Interrupt lists the approvals needed to resume.
	Interrupt *Interrupt `json:"interrupt,omitempty"`
	// Err is the error of a failed run. In JSON it is the string "error".
	Err error `json:"-"`
	// Values are the run's values when it ended; see Run.SetValue and
	// SessionValuePrefix.
	Values map[string]string `json:"values,omitempty"`
	// Agent names the agent that ran last, which differs from the agent
	// started when the run was handed off; see EventHandoff.
	Agent string `json:"agent,omitempty"`
	// Guardrail describes the guardrail whose tripwire ended a run with
	// StatusBlocked; see GuardrailError.
	Guardrail *Guardrail `json:"guardrail,omitempty"`
}

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

type RunInput struct {
	NewSession bool
	// Query is the text of the input message before any middleware ran.
	Query string
	// System is the system prompt. It starts as Config.Instructions.
	System string
	// Message is the input message. Middleware may modify it, for example
	// by inserting parts in front of the user's text.
	Message *model.Message
}

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

type Settings struct {
	// Name identifies the agent in events and hooks.
	Name  string
	Model model.Model
	// Instructions is the base system prompt; middleware may extend it.
	Instructions string
	// ToolMiddlewares wrap every tool call inside the ToolWrapper
	// middleware; the first is outermost.
	ToolMiddlewares []tool.Middleware
	Checkpointer    Checkpointer
	// Approver decides calls that need approval. Without one, the run is
	// interrupted and must be resumed with approvals.
	Approver Approver

	MaxTurns       int
	MaxTokens      int
	Temperature    *float64
	TopP           *float64
	Reasoning      *model.Reasoning
	ToolChoice     *model.ToolChoice
	ResponseFormat *model.ResponseFormat
	// Seed is passed to the provider in model.Request.Seed.
	Seed *int
	// ProviderOptions is passed to the provider in
	// model.Request.ProviderOptions.
	ProviderOptions map[string]map[string]any
	// Stream calls Model.Stream and emits delta events.
	Stream bool
	// Parallelism bounds tool calls running concurrently, which are those of
	// read-only and concurrent tools. Defaults to 8.
	Parallelism int
	Logger      *slog.Logger

	// Output asks the model for JSON matching a schema and validates the
	// final answer; see Output.
	Output *Output
	// Limits bounds the usage of each run; Request.Limits overrides it.
	Limits Limits
	// Budget, if set, is called with the run's usage so far before each
	// model call and each batch of tool calls. An error ends the run with
	// StatusLimitExceeded and the error's text as the reason, for example
	// when the usage priced in a currency exceeds a budget.
	Budget func(model.Usage) error
	// StopAtTools ends the run as completed once a tool with one of these
	// names returns a result that is not an error. Result.Output is the
	// content of that result, and the model is not called again.
	StopAtTools []string
	// StopWhen ends the run as completed when any condition holds after a
	// turn's tool calls have run; see StopCondition.
	StopWhen []StopCondition
}

type State struct {
	// Version is the format version; see StateVersion.
	Version   int    `json:"version,omitempty"`
	RunID     string `json:"run_id"`
	SessionID string `json:"session_id,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Turn      int    `json:"turn"`
	// System is the system prompt assembled at the start of the run.
	System string `json:"system,omitempty"`
	// Messages is the whole conversation, including prior history.
	Messages []*model.Message `json:"messages"`
	// Start is the index in Messages where this run's input begins.
	Start  int         `json:"start"`
	Usage  model.Usage `json:"usage"`
	Status Status      `json:"status"`
	Reason string      `json:"reason,omitempty"`
	// FinishReason is the finish reason of the last model response. A run
	// resumed after the model's final answer uses it to handle the answer.
	FinishReason model.FinishReason `json:"finish_reason,omitempty"`
	// Pending holds the planned tool calls of the current turn while they
	// are being approved or executed.
	Pending []*PendingCall `json:"pending,omitempty"`
	// Values holds middleware state; see Run.SetValue.
	Values    map[string]string `json:"values,omitempty"`
	UpdatedAt time.Time         `json:"updated_at"`
	// MaxTurns and Limits are the run's overrides of the configuration,
	// from its Request, kept so that a resumed run applies them too.
	MaxTurns int     `json:"max_turns,omitempty"`
	Limits   *Limits `json:"limits,omitempty"`
	// OutputRetries counts the answers sent back to the model because they
	// did not match Config.Output.
	OutputRetries int `json:"output_retries,omitempty"`
}

type Status string

type Step struct {
	// Turn is the turn number.
	Turn int
	// Message is the model's message of the turn.
	Message *model.Message
	// ToolResults are the results of its tool calls, in call order.
	ToolResults []*model.ToolResult
	// Usage is the run's usage so far.
	Usage model.Usage
}

type StopCondition func(step *Step) bool

type ToolPlan struct {
	// Call is the tool call. BeforeTool may rewrite its arguments.
	Call *model.ToolCall
	// Info describes the tool; Known is false for unknown tools. Its
	// RequiresApproval is that of this call when the tool is a
	// tool.CallApprover.
	Info  tool.Info
	Known bool
	// contains filtered or unexported fields
}

type ToolProvider interface {
	Tools() []tool.Tool
}

type ToolRevalidator interface {
	RevalidateTool(ctx context.Context, run *Run, plan *ToolPlan) error
}

type ToolWrapper interface {
	WrapTool(run *Run, next tool.Invoker) tool.Invoker
}