operations

type Access struct {
	// Role is the caller's workspace role. It filters only when EnforceRole
	// is set, matching the router, which skips role checks otherwise.
	Role        types.TenantRole
	EnforceRole bool
	SystemAdmin bool
	// Level is the user's assistant access level.
	Level types.AssistantAccessLevel
}

type Call struct {
	Method string
	// Path is escaped and ready to use as a request URI path.
	Path  string
	Query url.Values
	// Body is a JSON object, or nil when the operation has no body params.
	Body []byte
}

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

type Dispatcher interface {
	Dispatch(ctx context.Context, identity Identity, call Call) (*Response, error)
}

type Field struct {
	// From is a dotted path inside the source object.
	From string
	// MapKey selects one literal key within From, including keys containing dots.
	// Used for explicitly allow-listed keys of free-form maps.
	MapKey string
	// As is the output key; defaults to the last segment of From. Identifiers
	// should be renamed to the canonical handle keys so the model-context
	// policy turns them into handles.
	As string
	// MaxRunes overrides the projected string length for this field. Zero
	// keeps maxProjectedStringRunes.
	MaxRunes int
	// Items projects each element of a list of objects. Element fields are
	// relative to the element and cannot declare Items themselves.
	Items []Field
}

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

type Identity struct {
	UserID   string
	TenantID uint64
	Language string
	Agent    types.AuditAgentAction
}

type ItemTarget struct {
	// Param is the mutation's list parameter; at most MaxApprovalItems long.
	Param     string
	Operation string
	// As is the target parameter that receives each item.
	As    string
	Label string
}

type Location string

type Operation struct {
	// ID is the stable model-facing name, "<domain>.<verb>".
	ID          string
	Summary     string
	Description string
	Risk        Risk
	Method      string
	// Route is the full path as registered on the router, with :param and
	// *param segments.
	Route  string
	Params []Param
	Result Result
	// Target, for mutating operations, is a read operation that resolves
	// what the call acts on. It runs first, through the same authorization,
	// and its result labels the approval prompt. Its parameters must be a
	// subset of this operation's.
	Target *Target
	// LabelParam, for a creation with nothing existing to act on, names the
	// required string parameter (the new name) that labels the approval in
	// place of a Target.
	LabelParam string
	// Role is the lowest workspace role the route's guards let through;
	// empty takes the default for Risk. It only decides what a caller is
	// offered: the router still authorizes every call, and a router test
	// keeps the two in step.
	Role types.TenantRole
	// SystemAdmin requires the independent platform administrator permission.
	SystemAdmin bool
	// AlwaysConfirm makes a write ask every time, whatever the access level
	// and session grants: installing a skill runs fetched code as root in
	// the image every later session boots, so it is never pre-approved.
	AlwaysConfirm bool
}

type Param struct {
	Name string
	In   Location
	// Key is the wire name: the route segment, query key or body field.
	// Defaults to Name.
	Key      string
	Type     ParamType
	Required bool
	// AllowEmpty separates an agent-required field from an API nonempty constraint.
	AllowEmpty  bool
	Description string
	Enum        []string
	// Minimum and Maximum bound integers when Maximum > 0.
	Minimum int
	Maximum int
	// MaxItems bounds lists; defaults to defaultMaxListItems.
	MaxItems int
	// MaxBytes overrides maxStringParamBytes for this string. Zero keeps the
	// default. It cannot exceed maxAgentStringBytes.
	MaxBytes int
}

type ParamError struct {
	Param   string
	Message string
}

type ParamType string

type Projected struct {
	// Data is an object, or a list of objects for list results.
	Data any `json:"data"`
	// Meta holds Result.Meta fields, when declared.
	Meta map[string]any `json:"meta,omitempty"`
	// Truncated reports any loss of string content or list items in the projection.
	Truncated bool `json:"truncated,omitempty"`
}

type Response struct {
	Status int
	Body   []byte
}

type Result struct {
	// Root is a dotted path to the object or array to project, relative to
	// the response body. Empty means the body itself.
	Root string
	// List projects each element of the array at Root with Fields.
	List bool
	// Fields are relative to the object at Root, or to each element.
	Fields []Field
	// Meta fields are relative to the response body (e.g. a total count).
	Meta []Field
	// MaxItems caps List results; defaults to defaultMaxResultItems.
	MaxItems int
}

type Risk = policy.Risk

type Target struct {
	Operation string
	// Label is the result field shown to the user (e.g. "title").
	Label string
	// Items, for a batch mutation, also resolves every item it acts on.
	Items *ItemTarget
	// RequireComplete blocks a full replacement when the target read loses data.
	RequireComplete bool
}

type Withholding struct {
	// ReadOnly: the user set the assistant to read-only.
	ReadOnly    bool
	SystemAdmin bool
	// Role is the workspace role the operation needs when the caller's falls
	// short.
	Role types.TenantRole
}