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 {
	// unique tool call identifier
	CallID string `json:"call_id"`

	// agent/tool/command
	// agent:pack/sub
	// kit:name
	// /bin/comand
	Command string `json:"command"`

	// arguments including name
	Arguments Arguments `json:"arguments"`
}

type ActionRunner interface {
	Run(context.Context, string, map[string]any) (any, error)
}

type AdapterRegistry interface {
	Get(key string) (LLMAdapter, error)
}

type AdviceConfig struct {
	Before []string `yaml:"before" json:"before"`
	Around []string `yaml:"around" json:"around"`
	After  []string `yaml:"after" json:"after"`
}

type Agent struct {
	// Package name
	Pack string `json:"pack"`

	Name        string `json:"name"` // Agent sub name
	Display     string `json:"display"`
	Description string `json:"description"`

	// exported global values
	// Environment map[string]any
	Environment *Environment `json:"environment"`

	// default values
	Arguments Arguments `json:"arguments"`

	// agent as tool
	Parameters Parameters `json:"parameters"`

	// templated values
	// these should not be in the args map
	Instruction string `json:"instruction"`
	Context     string `json:"context"`
	Message     string `json:"message"`

	// The model to be used by the agent
	// TODO map or list for supporting multi features
	Model *Model `json:"model"`

	// Functions that the agent can call
	Tools []*ToolFunc `json:"-"`

	// inheritance
	Embed []*Agent `json:"-"`

	// LLM adapter
	Adapter string `json:"adapter"`

	// assigned at buildtime/runtime
	Parent *Agent `json:"-"`
	//
	Runner   ActionRunner       `json:"-"`
	Shell    ActionRunner       `json:"-"`
	Template *template.Template `json:"-"`

	Config *AppConfig `json:"-"`

	// LLM
	// get api token for LLM model
	Token func() string `json:"-"`

	Prompt  string     `json:"prompt"`
	Query   string     `json:"query"`
	History []*Message `json:"history"`

	//
	Entrypoint []string `json:"entrypoint"`
	// advices
	Before []string `json:"before"`
	Around []string `json:"around"`
	After  []string `json:"after"`

	Models []*Model `json:"models"`
}

type AgentConfig struct {
	Name        string `yaml:"name" json:"name"` // sub name without pack
	Display     string `yaml:"display" json:"display"`
	Description string `yaml:"description" json:"description"`

	Environment map[string]any `yaml:"environment" json:"environment"` // global vars
	Arguments   map[string]any `yaml:"arguments" json:"arguments"`
	Parameters  Parameters     `yaml:"parameters" json:"parameters"` // agent as tool

	//
	Instruction string `yaml:"instruction" json:"instruction"`
	Context     string `yaml:"context" json:"context"`
	Message     string `yaml:"message" json:"message"`

	Model string `yaml:"model" json:"model"`

	Output string `yaml:"output" json:"output"`

	// tools defined in tools config
	// kit:name | agent:pack/sub
	Functions []string `yaml:"functions" json:"functions"`

	//
	MaxTurns   int `yaml:"max_turns" json:"max_turns"`
	MaxTime    int `yaml:"max_time" json:"max_time"`
	MaxHistory int `yaml:"max_history" json:"max_history"`
	MaxSpan    int `yaml:"max_span" json:"max_span"`

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

	// TODO clarify
	// inherit from embedded parent:
	// + environment
	// + instruction
	// + context
	//
	// + model
	// + functions
	// local scope:
	// - arguments
	// - message
	// - parameters
	Embed []string `yaml:"embed" json:"embed"`

	// chat|image|docker
	Adapter string `yaml:"adapter" json:"adapter"`

	//
	Entrypoint []string      `yaml:"entrypoint" json:"entrypoint"`
	Advices    *AdviceConfig `yaml:"advices" json:"advices"`

	Config *AppConfig `json:"-"`
}

type App struct {
	// user id: auth email
	UserID string

	// workspace root. default: $HOME/.ai/
	Base string
}

type AppConfig struct {
	// kit specifies a namespace for the action
	// examples:
	// shell
	// MCP server name
	// file system
	// container name
	// virtual machine name
	// tool/function (Gemini)
	Kit string `yaml:"kit" json:"kit"`

	// action type:
	// func, system, agent...
	Type string `yaml:"type" json:"type"`

	//
	Arguments map[string]any `yaml:"arguments" json:"arguments"`

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

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

	// memory context
	MaxHistory int `yaml:"max_history" json:"max_history"`
	MaxSpan    int `yaml:"max_span" json:"max_span"`

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

	// app level global vars
	Environment map[string]any `yaml:"environment" json:"environment"`

	//
	Pack string `yaml:"pack" json:"pack"`

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

	// tool / model provider
	Provider string `yaml:"provider" json:"provider"`
	BaseUrl  string `yaml:"base_url" json:"base_url"`

	// api token lookup key
	ApiKey string `yaml:"api_key" json:"api_key"`

	// action type:
	// func, system, agent...
	// Type  string        `yaml:"type"`
	Tools []*ToolConfig `yaml:"tools" json:"tools"`

	// modelset name
	Set    string                  `yaml:"set" json:"set"`
	Models map[string]*ModelConfig `yaml:"models" json:"models"`

	// The raw data for this config
	RawContent []byte `yaml:"-" json:"-"`

	// TODO for debugging
	Source string `yaml:"-" json:"-"`

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

type ArgMap map[string]any

type Arguments = ArgMap

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]*AppConfig, error)
	FindAgent(owner, pack string) (*AppConfig, error)
	ListToolkit(owner string) (map[string]*AppConfig, error)
	FindToolkit(owner string, kit string) (*AppConfig, error)
	ListModels(owner string) (map[string]*AppConfig, error)
	FindModels(owner string, alias string) (*AppConfig, 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 CallLogEntry struct {
	// tool call
	Kit       string         `json:"kit"`
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`

	// active agent
	Agent string `json:"agent"`

	// failure
	Error error `json:"error"`

	// success
	Result *Result `json:"result"`

	Started time.Time `json:"started"`
	Ended   time.Time `json:"ended"`
}

type CallLogger interface {
	Base() string
	Save(*CallLogEntry)
}

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

type ConnectorConfig struct {

	// optional as of now
	Provider string `yaml:"provider"`

	BaseUrl string `yaml:"base_url"`
	// name of api lookup key
	ApiKey string `yaml:"api_key"`
}

type ContextKey string

type DHNTConfig struct {
	// base where this config loaded from. default $HOME/.ai/
	// filename: dhnt.json
	Base string `json:"-"`

	// additional work spaces
	Roots *Roots `json:"roots"`

	Blob   *ResourceConfig   `json:"blob"`
	Assets []*ResourceConfig `json:"assets"`
}

type DirEntry = fs.DirEntry

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

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

type Environment struct {
	Env map[string]any `json:"env"`
	// contains filtered or unexported fields
}

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

type FlowType string

type FuncBody struct {
	// A MIME type (now properly called "media type", but also sometimes "content type")
	// is a string sent along with a file indicating the type of the file
	// (describing the content format, for example, a sound file might be labeled audio/ogg,
	// or an image file image/png).
	// https://developer.mozilla.org/en-US/docs/Glossary/MIME_type
	// tpl   text/x-go-template
	// uri   text/uri-list
	// md    text/markdown
	// txt   text/plain
	// go    application/x-go
	// yaml  application/yaml
	// sh    application/x-sh
	// json  application/json
	// js    text/javascript
	MimeType string `yaml:"mime_type" json:"mime_type"`
	Script   string `yaml:"script" json:"script"`
}

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

type HandlerFunc func(req *Request, res *Response) error

type InputConfig struct {
	Message string
	Args    []string

	Clipin     bool
	ClipWait   bool
	Clipout    bool
	ClipAppend bool
	Stdin      bool
}

type InternalServerError struct {
	Message string
}

type Kitname string

type LLMAdapter interface {
	Call(context.Context, *Request) (*Response, error)
}

type Level = string

type LogLevel int

type MemOption struct {
	MaxHistory int
	MaxSpan    int
	Offset     int
	Roles      []string
}

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
	Session SessionID `json:"session"`
	Created time.Time `json:"created"`

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

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

	// user/provider
	Sender string `json:"sender"`

	// active/responsible agent
	Agent Packname `json:"agent"`

	//
	// TODO
	// context of recursive irrelevant historical context messages
	// rot the real intent of user
	// new context messages are created and sent as user role message to LLM but persisteed as "context"
	Context bool `json:"context"`
}

type Middleware func(*Agent, Handler) Handler

type Model struct {
	Set   string `json:"set"`
	Level Level  `json:"level"`

	Description string `json:"description"`

	// 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"`

	// api token lookup key
	ApiKey string `json:"api_key"`
}

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

	// LLM service provider: openai | gemini | anthropic
	Provider string `yaml:"provider" json:"provider"`
	BaseUrl  string `yaml:"base_url" json:"base_url"`

	// name of api key for looking up api access token
	ApiKey string `yaml:"api_key" json:"api_key"`

	Description string `json:"description"`
}

type NotFoundError struct {
	Message string
}

type Output struct {
	// agent emoji and name
	Display string `json:"display"`

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

type Packname string

type Parameters map[string]any

type Record struct {
	ID uuid.UUID

	Owner   string
	Name    string
	Display string
	Content string

	// source
	Store AssetStore
}

type Request struct {
	// parent agent
	Agent *Agent `json:"-"`

	Arguments Arguments `json:"arguments"`

	// LLM
	Model *Model      `json:"model"`
	Tools []*ToolFunc `json:"tools"`

	Messages []*Message `json:"messages"`

	Runner ActionRunner `json:"-"`

	// get api token for LLM model
	Token func() string `json:"-"`

	//
	Prompt  string     `json:"prompt"`
	Query   string     `json:"query"`
	History []*Message `json:"history"`
	// 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 {
	Type  string `json:"type"`
	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 `json:"messages"`

	// The last agent to handle a message
	Agent *Agent `json:"agent"`

	Result *Result `json:"result"`
}

type Result struct {
	// author of the reponse: assistant
	Role string `json:"role"`
	// The result value as a string
	Value string `json:"value"`

	// // media content
	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types
	MimeType string `json:"mime_type"`

	// transition
	// The agent state
	State State `json:"state"`
	// The agent name to transfer to for StateTransfer
	NextAgent string `json:"next_agent"`

	//
	Usage        any   `json:"usage"`
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
	// The total number of tokens used.
	TotalTokens int64 `json:"total_tokens"`
}

type Root struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Scheme      string `json:"scheme"`
	Path string `json:"path"`
}

type Roots struct {
	// primary working directory for the agents
	Workspace *Root `json:"workspace"`

	// Add the current working directory to the root list
	// where ai is started
	Cwd *Root `json:"cwd"`

	// Add system temporary directory to the root list
	Temp *Root `json:"temp"`

	// Additional paths
	Dirs []*Root `json:"dirs"`
	// contains filtered or unexported fields
}

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

type SessionID string

type Setlevel string

type State int

type System = vos.System

type TemplateFuncMap = template.FuncMap

type ToolCall Action

type ToolCallEntry struct {
	ID        string         `json:"id"`
	Kit       string         `json:"kit"`
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`

	Error  error `json:"error"`
	Result any   `json:"result"`

	Timestamp time.Time `json:"timestamp"`
}

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

	Name        string `yaml:"name" json:"name"`
	Display     string `yaml:"display" json:"display"`
	Description string `yaml:"description" json:"description"`

	Parameters Parameters `yaml:"parameters" json:"parameters"`

	Body *FuncBody `yaml:"body" json:"body"`

	Output string `yaml:"output" json:"output"`

	//
	Provider string `yaml:"provider" json:"provider"`
	BaseUrl  string `yaml:"base_url" json:"base_url"`
	// api lookup key
	ApiKey string `yaml:"api_key" json:"api_key"`

	// filter by match key=values (comma, separated)
	// include all tools that match
	Filter map[string]string `yaml:"filter" json:"filter"`

	//
	Config *AppConfig `json:"-"`
}

type ToolFunc struct {
	Type ToolType `json:"type"`

	// 'agent' for all agents as tool
	Kit string `json:"kit"`

	// tool name or pack/sub for agent
	Name string `json:"name"`

	Description string     `json:"description"` // description
	Parameters  Parameters `json:"parameters"`  // parameters

	Body *FuncBody `json:"body"` // body

	// TODO move provider/base_url/api_key to argments
	Provider string `json:"provider"`
	BaseUrl  string `json:"base_url"` // base url
	// name of api key - used to resolve api key/token before tool call
	ApiKey string `json:"api_key"`

	// extra features.
	// e.g labels for mcp for filtering tools
	Extra map[string]any `json:"extra"`

	// default arguments
	Arguments map[string]any `json:"arguments"`

	// Input  string `json:"input"`
	Output string `json:"output"`

	//
	Config *AppConfig `json:"-"`
}

type ToolGuard struct {
	Agent string
}

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

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

type ToolType string

type UnauthorizedError struct {
	Message string
}

type UnsupportedError struct {
	Message string
}

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

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

	Email string `json:"email"`

	// full/first,last
	Name string `json:"name"`

	Avatar string `json:"avatar"`

	Settings map[string]any `json:"settings"`
}

type UserInput struct {
	// cached media contents
	Messages []*Message `json:"-"`

	Message string
}

type Vars struct {
	Global *Environment `json:"global"`

	RootAgent *Agent `json:"root_agent"`

	Base string

	SessionID SessionID
	User      *User

	Roots     *Roots
	Workspace Workspace
	OS        System
	Secrets   SecretStore
	Assets    AssetManager
	Blobs     BlobStore
	Tools     ToolSystem
	Adapters  AdapterRegistry
	History   MemStore
	Log       CallLogger
}

type Workspace = vfs.Workspace