agent

type ChatCompletionsModel struct {
	Endpoint       string        // "" uses DefaultChatCompletionsEndpoint
	APIKey         string        // resolved from the vault by the caller
	Model          string        // required; there is no sensible default
	MaxTokens      int           // 0 sends no cap at all
	AnswerVariable string        // "" uses DefaultAnswerVariable
	Auth           string        // "" uses AuthBearer
	Timeout        time.Duration // 0 uses 2 minutes
	Client         *http.Client  // nil uses a client with Timeout
}

type Decision struct {
	ToolCalls []model.ToolCall
	Outputs   []model.VariableValue
}

type HTTPModel struct {
	Endpoint       string        // "" uses DefaultEndpoint
	APIKey         string        // resolved from the vault by the caller
	Model          string        // "" uses DefaultModel
	MaxTokens      int           // 0 uses 4096
	AnswerVariable string        // "" uses DefaultAnswerVariable
	Timeout        time.Duration // 0 uses 2 minutes
	Client         *http.Client  // nil uses a client with Timeout
	// Auth is how the credential is presented: "" or [AuthAPIKey] for Anthropic's own
	// x-api-key header, [AuthBearer] for Authorization: Bearer. It exists because the
	// Messages format and the credential scheme are separate choices — a gateway can
	// speak this wire format and still want a bearer token, which is exactly what
	// OpenRouter's Messages-compatible endpoint does.
	Auth string
	// Thinking is the extended-thinking setting sent with every round: "" keeps the
	// adaptive default, [ThinkingOff] omits the field entirely. Omitting it is what an
	// endpoint that speaks the Messages format without implementing this extension
	// needs — a request it refuses outright is worse than a round without it.
	Thinking string
}

type Model interface {
	Decide(ctx context.Context, req Request) (Decision, error)
}

type ModelChooser interface {
	// ForModel returns this model asked to use the named language model. An empty id
	// means the configured one, so callers need no special case.
	ForModel(id string) Model
}

type Param struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required"`
}

type ProcessLookup func(defKey uint64) *compiler.CompiledProcess

type Request struct {
	Goal    string            `json:"goal"`
	Context map[string]string `json:"context,omitempty"`
	Tools   []Tool            `json:"tools"`
	Results []string          `json:"results,omitempty"`
	Round   int               `json:"round"`
	// System replaces what an adapter would otherwise tell the model about the
	// situation it is in. Empty is the normal case and the one every runtime caller
	// uses: a round and an ai task each have a standing prompt below, written for
	// them.
	//
	// It exists because both of those prompts open by saying the model is one step
	// inside a running business process, and that is not true of every caller any
	// more. Design-time form generation (ADR-0260) asks this same
	// [Model], through this same adapter, from an authoring screen where there is no
	// instance, no token and no variable to answer into — and a model told it is
	// inside a process it is not inside answers as if it were. Overriding the sentence
	// is cheaper and more honest than a second transport that would drift from this
	// one.
	//
	// It is not serialized into a job payload: a round's framing is this package's to
	// state, and a request that travelled from the engine never carries one.
	System string `json:"-"`
}

type Round struct {
	Request
	Connector string
	Model     string
}

type Task struct {
	// Connector names the agent Worker's own configured provider. A name and not an
	// endpoint on purpose: an endpoint would be half a credential.
	Connector string `json:"connector"`
	// Model names the language model to ask, empty when the task named none — in which
	// case whatever the provider is configured for runs.
	Model string `json:"model,omitempty"`
	// Prompt is the question, already evaluated against the variables the task saw.
	Prompt string `json:"prompt"`
	// ResultVariable is where the answer lands. It is required at compile time, so an
	// empty one here means something upstream lost it.
	ResultVariable string `json:"resultVariable"`
	// RequestID is the job key, so a call repeated after a lease elapsed is identifiable
	// as the same one rather than looking like a second question — mail's MessageID
	// exactly, and for its reason.
	RequestID string `json:"requestId,omitempty"`
}

type Tool struct {
	Name        string  `json:"name"`
	Description string  `json:"description"`
	Params      []Param `json:"params"`
}