agents

type ActionPreview struct {
	// Operation is the kind of change, for the reviewer's mental model: create, update, delete, action (a named operation like `issue` or `close`) or read.
	Operation string `json:"operation"`
	// Title names the operation the way the API does (the endpoint's display name, e.g. "Update Customer Price").
	Title string `json:"title"`
	// Resource identifies what is being changed. Absent on a create, which has no target yet.
	Resource *PreviewResource `json:"resource,omitempty"`
	// Fields are the values the call sets, in schema order, each with its current value where one could be read.
	Fields []PreviewField `json:"fields"`
	// Identifiers are the path parameters that select the target rather than change it, so the reviewer sees what was addressed without them cluttering the change list.
	Identifiers []PreviewField `json:"identifiers,omitempty"`
	Method      string         `json:"method"`
	Path        string         `json:"path"`
	// BeforeState reports whether current values were readable. False means the rows carry only new values — the reviewer must not read "no current value" as "this field is empty today".
	BeforeState bool `json:"before_state"`
	// Truncated is set when the call sets more fields than the preview carries.
	Truncated bool `json:"truncated,omitempty"`
}

type BuiltinToolDescriptor struct {
	Slug                constants.Tool
	DisplayName         string
	Description         string
	InputSchema         string
	Group               BuiltinToolGroup
	RequiredPermissions []string
	// Mutating reports whether invoking this tool takes an externally-visible or otherwise irreversible action (e.g. send_email puts mail in front of a customer). Mutating built-in tools default to requiring human review and that gate cannot be turned off per-agent — the run pauses in awaiting_approval whenever the agent calls one. Read-only tools and tools that only stage something for a human to approve (e.g. draft_reply) are non-mutating.
	Mutating bool
}

type BuiltinToolGroup struct {
	ID        string
	Name      string
	Slug      string
	Icon      string
	SortOrder int32
}

type EndpointToolDescriptor struct {
	Slug          string
	DisplayName   string
	Description   string
	Method        string
	RouteTemplate string
	// InputSchema is the self-contained JSON Schema shown to the LLM.
	InputSchema string
	Params      []EndpointToolParam
	// RequiredPermissions are the "<domain>:<action>" permissions this operation needs (from the endpoint's declaration). Surfaced in the tool-selection UI.
	RequiredPermissions []string
	// RequiredRoleType, when non-empty, is the role type the caller must have (e.g. "admin"). Surfaced in the tool-selection UI.
	RequiredRoleType string
	// Group is the display group for the tool-selection UI (e.g. "Customers").
	Group string
	// ReadOnly mirrors the endpoint's own declaration that it computes an answer without changing anything despite not being a GET (a quote, a preview, an analytics query). Generated from the endpoint, never inferred here.
	ReadOnly bool
}

type EndpointToolParam struct {
	Name  string
	In    EndpointToolParamLocation
	Array bool
}

type EndpointToolParamLocation string

type PreviewField struct {
	// Key is the dotted input path (`freight.carrier_id`), kept so a reviewer can tie a row back to the API field.
	Key string `json:"key"`
	// Label is the field's human name, including its parent group ("Freight › Carrier").
	Label string `json:"label"`
	// After is the value the call sets, and Before the value it replaces (absent when unread or unset).
	After  any `json:"after"`
	Before any `json:"before,omitempty"`
	// Changed is false when the call sets a field to the value it already holds — worth showing, but not as a change.
	Changed bool `json:"changed"`
	// Format hints at rendering (`decimal`, `date`, `date-time`, `id`, `enum`, `bool`).
	Format string `json:"format,omitempty"`
	// Description is the field's API documentation, for a reviewer who needs to know what the field means.
	Description string `json:"description,omitempty"`
}

type PreviewResource struct {
	Object string `json:"object,omitempty"`
	ID     string `json:"id,omitempty"`
	// Label is the record's human name or number, read from the record itself.
	Label string `json:"label,omitempty"`
	// Linkable reports whether the frontend has a detail page for this object type.
	Linkable bool `json:"linkable"`
}

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