api

type Client struct {
	URL   string
	Token string
	Env   string
	// Fingerprint pins a self-signed server certificate (its SHA-256); empty verifies it the usual way.
	Fingerprint string
	// Ask puts a server's question to the user: for a confirm, ok says go ahead; for a reauth,
	// answer is a password or TOTP code. Without it such calls fail.
	Ask func(hint, message string) (answer string, ok bool)
	// contains filtered or unexported fields
}

type Engine interface {
	Catalog(ctx context.Context) (*catalog.Catalog, error)
	Query(ctx context.Context, source string, args protocol.Args) (*protocol.Frame, error)
	// Stream sends batches until one is done; cancel ctx to stop it early.
	Stream(ctx context.Context, source string, args protocol.Args) (<-chan protocol.StreamBatch, error)
	// Run goes through policy (confirm and approval happen here), runs as a job and is audited.
	Run(ctx context.Context, action string, args protocol.Args, o RunOpts) (*jobs.Job, *protocol.RunResult, error)
	Jobs(ctx context.Context) []*jobs.Job
	Events(ctx context.Context, pattern string) (<-chan protocol.Event, error)
	Search(ctx context.Context, query string) ([]protocol.Hit, error)
	Resolve(ctx context.Context, ref string) (*protocol.Resolved, error)
	Complete(ctx context.Context, language, text string, pos int) ([]protocol.Completion, error)
	Session(ctx context.Context) identity.Subject
	// Provides is every source and action the engine serves, with descriptions and argument schemas.
	Provides(ctx context.Context) protocol.Provides
	// Inbox lists writes waiting for approval; Decide approves (running it) or rejects one.
	Inbox(ctx context.Context) []inbox.Item
	Decide(ctx context.Context, id string, approve bool) (*protocol.RunResult, error)
}

type Fake struct {
	Cat     *catalog.Catalog
	Frames  map[string]*protocol.Frame
	Results map[string]*protocol.RunResult
	Errs    map[string]error
	Subject identity.Subject

	Ran []string
	// contains filtered or unexported fields
}

type Job struct {
	ID     string    `json:"id"`
	Label  string    `json:"label"`
	Start  time.Time `json:"start"`
	End    time.Time `json:"end,omitzero"`
	Output []string  `json:"output,omitempty"`
	Error  string    `json:"error,omitempty"`
	// Waiting is the prompt of a running job that waits for its input.
	Waiting string `json:"waiting,omitempty"`
	// Step is the task step running ("3/7").
	Step string `json:"step,omitempty"`
}

type Request struct {
	Source  string            `json:"source,omitempty"`
	Action  string            `json:"action,omitempty"`
	Args    protocol.Args     `json:"args,omitempty"`
	DryRun  bool              `json:"dry_run,omitempty"`
	As      *identity.Subject `json:"as,omitempty"`
	Pattern string            `json:"pattern,omitempty"`
	Query   string            `json:"query,omitempty"`
	Ref     string            `json:"ref,omitempty"`
	ID      string            `json:"id,omitempty"`
	Approve bool              `json:"approve,omitempty"`
	Lang    string            `json:"language,omitempty"`
	Text    string            `json:"text,omitempty"`
	Pos     int               `json:"pos,omitempty"`
}

type RunOpts struct {
	DryRun bool
	// As runs the action for another subject, such as the AI; the session's own when empty.
	As *identity.Subject
}