api

type ATMSupport interface {
	AssetStore
	RetrieveAgent(owner, pack string) (*Record, error)
	ListAgents(owner string) ([]*Record, error)
	SearchAgent(owner, pack string) (*Record, error)
	RetrieveTool(owner, kit string) (*Record, error)
	ListTools(owner string) ([]*Record, error)
	RetrieveModel(owner, alias string) (*Record, error)
	ListModels(owner string) ([]*Record, error)
}

type Action struct {
	Tool *ToolFunc
}

type Agent struct {
	Owner string

	// The name of the agent.
	Name        string
	Display     string
	Description string

	// system prompt
	Instruction *Instruction
	// user query
	Message string

	RawInput *UserInput

	// The model to be used by the agent
	Model *Model
	// Functions that the agent can call
	Tools []*ToolFunc

	Arguments map[string]any

	// LLM adapter
	Adapter string

	//
	Format string

	MaxTurns int
	MaxTime  int

	New        bool
	MaxHistory int
	MaxSpan    int
	Context    string

	LogLevel LogLevel

	//
	Flow *Flow
}

type AgentConfig struct {
	Name        string `yaml:"name"`
	Display     string `yaml:"display"`
	Description string `yaml:"description"`

	//
	Instruction *Instruction `yaml:"instruction"`

	// set/level
	Model string `yaml:"model"`

	// tools defined in tools config
	// kit:name
	Functions []string `yaml:"functions"`

	Flow *FlowConfig `yaml:"flow"`

	// chat|image|docker/aider oh gptr
	Adapter string `yaml:"adapter"`

	//
	MaxTurns int `yaml:"max_turns"`
	MaxTime  int `yaml:"max_time"`

	// user message
	Message string `yaml:"message"`

	// output format: json | text
	Format string `yaml:"format"`

	// memory
	// max history: 0 max span: 0
	New        *bool  `yaml:"new,omitempty"`
	MaxHistory int    `yaml:"max_history"`
	MaxSpan    int    `yaml:"max_span"`
	Context    string `yaml:"context"`

	// logging: quiet | info[rmative] | verbose | trace
	LogLevel string `yaml:"log_level"`

	// agent as tool
	Parameters map[string]any `yaml:"parameters"`

	// default values for parameters
	Arguments map[string]any `yaml:"arguments"`

	// security
	Filters []*IOFilter  `yaml:"filters"`
	Guards  []*ToolGuard `yaml:"guards"`

	//
	Store AssetStore `yaml:"-"`
	// relative to root
	BaseDir string `yaml:"-"`
}

type AgentName string

type AgentsConfig struct {
	// agent app name
	Name string `yaml:"name"`

	// set/level key - not the LLM model
	Model string `yaml:"model"`

	Agents []*AgentConfig `yaml:"agents"`

	//
	MaxTurns int `yaml:"max_turns"`
	MaxTime  int `yaml:"max_time"`

	// user message
	Message string `yaml:"message"`

	// output format: json | text
	Format string `yaml:"format"`

	// memory
	// max history: 0 max span: 0
	New        *bool  `yaml:"new,omitempty"`
	MaxHistory int    `yaml:"max_history"`
	MaxSpan    int    `yaml:"max_span"`
	Context    string `yaml:"context"`

	// logging: quiet | informative | verbose
	LogLevel string `yaml:"log_level"`

	// toolkit
	// kit:any
	Kit   string        `yaml:"kit"`
	Type  string        `yaml:"type"`
	Tools []*ToolConfig `yaml:"tools"`

	// model set
	// set/any
	Set      string                  `yaml:"set"`
	Provider string                  `yaml:"provider"`
	BaseUrl  string                  `yaml:"base_url"`
	ApiKey   string                  `yaml:"api_key"`
	Models   map[string]*ModelConfig `yaml:"models"`
}

type App struct {
	// root agent
	Agent *Agent

	// user
	User *User

	// chat id to continue the conersation
	// <config_base>/chat/<id>.json
	ChatID string

	// history @agent
	Context    string
	MaxHistory int
	MaxSpan    int

	MaxTime  int
	MaxTurns int

	Models string

	//
	LogLevel string

	Unsafe bool

	//
	Workspace string

	//
	Stdin  string
	Stdout string
	Stderr string

	//
	Config *AppConfig
}

type AppConfig struct {
	Version string

	ConfigFile string

	Agent string
	// Command string
	Args []string

	// --message takes precedence, skip stdin
	// command line arguments
	Message string

	// editor binary and args. e.g vim [options]
	Editor string

	Clipin   bool
	ClipWait bool

	Clipout    bool
	ClipAppend bool

	// IsPiped bool
	Stdin bool

	// Output format: raw or markdown
	Format string

	// output file for saving response
	Output string

	// user
	User *User

	// chat id to continue the conersation
	// <config_base>/chat/<id>.json
	ChatID string

	// conversation history
	New        *bool
	MaxHistory int
	MaxSpan    int

	// history @agent
	Context string

	Models string

	//
	LogLevel string

	Unsafe bool

	//
	Base string

	Workspace string

	Interactive bool
	Editing     bool
	Shell       string

	Watch     bool
	ClipWatch bool

	MaxTime  int
	MaxTurns int

	//
	Stdout string
	Stderr string

	// dry run
	DryRun        bool
	DryRunContent string
}

type AssetFS interface {
	AssetStore
	ReadDir(name string) ([]DirEntry, error)
	ReadFile(name string) ([]byte, error)
	Resolve(parent string, name string) string
}

type AssetManager interface {
	// GetStore(key string) (AssetStore, error)
	AddStore(store AssetStore)

	SearchAgent(owner, pack string) (*Record, error)
	ListAgent(owner string) (map[string]*AgentsConfig, error)
	FindAgent(owner, pack string) (*AgentsConfig, error)
	ListToolkit(owner string) (map[string]*ToolsConfig, error)
	FindToolkit(owner string, kit string) (*ToolsConfig, error)
	ListModels(owner string) (map[string]*ModelsConfig, error)
	FindModels(owner string, alias string) (*ModelsConfig, error)
}

type AssetStore any

type BadRequestError struct {
	Message string
}

type Blob struct {
	ID       string         `json:"id"`
	MimeType string         `json:"mime_type"`
	Content  []byte         `json:"content"`
	Meta     map[string]any `json:"meta"`
}

type BlobStore interface {
	Put(ID string, blob *Blob) error
	Get(ID string) (*Blob, error)
	Presign(ID string) (string, error)
}

type Chat struct {
	// uuid
	ID      string    `json:"id"`
	UserID  string    `json:"userId"`
	Created time.Time `json:"created"`

	// data
	Title string `json:"title"`
}

type ClipboardProvider interface {
	Clear() error
	Read() (string, error)
	Get() (string, error)
	Write(string) error
	Append(string) error
}

type ConnectorConfig struct {
	// mcp | ssh ...
	Proto string `yaml:"proto"`

	Provider string `yaml:"provider"`
	BaseUrl  string `yaml:"base_url"`
	// name of api key
	ApiKey string `yaml:"api_key"`

	Extra map[string]string `yaml:"extra"`
}

type DirEntry = fs.DirEntry

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

type EditorProvider interface {
	Launch(string) (string, error)
}

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

type Flow struct {
	Type        FlowType
	Expression  string
	Concurrency int
	Retry       int
	Actions     []*Action
}

type FlowConfig struct {
	Type FlowType `yaml:"type"`

	// go template syntax
	Expression  string   `yaml:"expression"`
	Concurrency int      `yaml:"concurrency"`
	Retry       int      `yaml:"retry"`
	Actions     []string `yaml:"actions"`
}

type FlowType string

type FuncBody struct {
	Language string `yaml:"language"`
	Code     string `yaml:"code"`
	Url      string `yaml:"url"`
}

type Handler interface {
	Serve(*Request, *Response) error
}

type IOFilter struct {
	Agent string
}

type Instruction struct {
	// prefix supported: file: resource:
	// #! [--mime-type=text/x-go-template]
	Content string `yaml:"content"`

	// content type
	// text/x-go-template
	Type string `yaml:"type"`
}

type InternalServerError struct {
	Message string
}

type KitName string

type Level = string

type LogLevel int

type MemOption struct {
	MaxHistory int
	MaxSpan    int
}

type MemStore interface {
	Save([]*Message) error
	Load(*MemOption) ([]*Message, error)
	Get(string) (*Message, error)
}

type Message struct {
	// message id
	ID string `json:"id"`

	// thread id
	ChatID  string    `json:"chat_id"`
	Created time.Time `json:"created"`

	// data
	ContentType string `json:"content_type"`
	Content     string `json:"content"`

	// system | assistant | user
	Role string `json:"role"`

	// user/agent
	Sender string `json:"sender"`
}

type Model struct {
	// model @agent or resolved provider model name
	// example:
	//   @model
	//   gemini-2.0-flash-lite
	Model string `json:"model"`

	Provider string `json:"provider"`
	BaseUrl  string `json:"base_url"`

	// secret key or LLM provider api key/token if resolved
	ApiKey string `json:"api_key"`
}

type ModelConfig struct {
	// LLM model
	Model string `yaml:"model"`

	// LLM service provider: openai | gemini | anthropic
	Provider string `yaml:"provider"`
	BaseUrl  string `yaml:"base_url"`
	// name of api key
	ApiKey string `yaml:"api_key"`
}

type ModelsConfig struct {
	// model set name
	Set string `yaml:"set"`

	// provider
	Provider string `yaml:"provider"`
	BaseUrl  string `yaml:"base_url"`
	// name of api lookup key - never the actual api token
	ApiKey string `yaml:"api_key"`

	Models map[string]*ModelConfig `yaml:"models"`
}

type NotFoundError struct {
	Message string
}

type Output struct {
	// Agent icon and name
	Display string `json:"display"`

	Content     string `json:"content"`
	ContentType string `json:"content_type"`
}

type Record struct {
	ID uuid.UUID

	Owner   string
	Name    string
	Display string
	Content string

	// source
	Store AssetStore
}

type Request struct {
	// parent agent
	Parent *Agent

	// The name/command of the active agent
	Agent string

	Messages []*Message

	RawInput *UserInput

	Arguments map[string]any
	// contains filtered or unexported fields
}

type Resource struct {
	// web resource base url
	// http://localhost:18080/resource
	// https://ai.dhnt.io/resource
	Base string `json:"base"`

	// access token
	Token string `json:"token"`
}

type ResourceConfig struct {
	Base  string `json:"base"`
	Token string `json:"token"`
}

type Response struct {
	// A list of message objects generated during the conversation
	// with a sender field indicating which Agent the message originated from.
	Messages []*Message

	// The last agent to handle a message
	Agent *Agent

	Result *Result
}

type Result struct {
	// The result value as a string
	Value string

	// media content
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types
	MimeType string
	Content  []byte

	// transition
	// The agent state
	State State
	// The agent name to transfer to for StateTransfer
	NextAgent string
}

type SecretStore interface {
	Get(owner, key string) (string, error)
}

type State int

type TemplateFuncMap = template.FuncMap

type ToolCondition struct {
	// required env list
	Env []string `yaml:"env"`

	// found on PATH
	Lookup *string `yaml:"lookup"`

	// shell required
	Shell map[string]any `yaml:"shell"`
}

type ToolConfig struct {
	Type string `yaml:"type"`

	Name string `yaml:"name"`

	Description string         `yaml:"description"`
	Parameters  map[string]any `yaml:"parameters"`

	Body *FuncBody `yaml:"body"`

	Condition *ToolCondition `yaml:"condition"`

	// agent name for agent tool type
	// description/parameters defined here take precedence
	Agent string `yaml:"agent"`

	//
	Provider string `yaml:"provider"`
	BaseUrl  string `yaml:"base_url"`
	// name of api key
	ApiKey string `yaml:"api_key"`

	Extra map[string]string `yaml:"extra"`
}

type ToolEnv struct {
	// User  string
	Owner string
}

type ToolFunc struct {
	Type string

	Kit         string
	Name        string
	Description string
	Parameters  map[string]any

	Body *FuncBody

	// agent name if this tool references an agent
	Agent string

	//
	State State
	//
	Config *ToolsConfig

	//
	Provider string
	BaseUrl  string
	// name of api key - used to resolve api key/token before tool call
	ApiKey string

	Extra map[string]string
}

type ToolGuard struct {
	Agent string
}

type ToolKit interface {
	Call(context.Context, *Vars, *ToolEnv, *ToolFunc, map[string]any) (any, error)
}

type ToolRunner func(context.Context, string, map[string]any) (*Result, error)

type ToolSystem interface {
	GetKit(key any) (ToolKit, error)
	AddKit(key any, kit ToolKit)
}

type ToolsConfig struct {
	// kit name specifies a namespace.
	// e.g. but not limited to:
	// class name
	// MCP server name
	// virtual filesystem name
	// container name
	// virtual machine name
	// tool/function (Gemini)
	Kit string `yaml:"kit"`

	// func (server) | system (client) | remote
	Type string `yaml:"type"`

	// provider
	Provider string `yaml:"provider"`
	BaseUrl  string `yaml:"base_url"`
	// name of api key
	ApiKey string `yaml:"api_key"`

	Connector *ConnectorConfig `yaml:"connector"`

	// system commands used by tools
	Commands []string `yaml:"commands"`

	Tools []*ToolConfig `yaml:"tools"`
}

type UnauthorizedError struct {
	Message string
}

type UnsupportedError struct {
	Message string
}

type User struct {
	// uuid
	ID string `json:"id"`

	//
	// Username string `json:"username"`
	// emoji + nickname
	Display string `json:"display"`

	Email string `json:"email"`
	// full/first,last
	Name   string `json:"name"`
	Avatar string `json:"avatar"`
}

type UserInput struct {

	// query - command line args
	Message string `json:"message"`

	// query - clipboard/stdin/editor
	Content string `json:"content"`

	// cached file contents
	Messages []*Message `json:"-"`
}

type Vars struct {
	LogLevel LogLevel `json:"log_level"`

	ChatID     string `json:"chat_id"`
	MaxTurns   int    `json:"max_turns"`
	MaxTime    int    `json:"max_time"`
	New        *bool  `json:"new"`
	MaxHistory int    `json:"max_history"`
	MaxSpan    int    `json:"max_span"`
	Context    string `json:"context"`
	Format     string `json:"format"`
	Models     string `json:"models"`

	Unsafe    bool   `json:"unsafe"`
	Workspace string `json:"workspace"`

	DryRun        bool   `json:"-"`
	DryRunContent string `json:"-"`

	// conversation history
	History []*Message     `json:"-"`
	Global  map[string]any `json:"-"`
}