tools

type Audience string

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

type Link struct {
	Label string `json:"label"` // English source; the console translates it
	Route string `json:"route"` // console route, e.g. "/releases/history/42"
}

type Principal struct {
	ViewerID int64
	IsOwner  bool
	// Surface is "console" for Ask Ether, "mcp" for paired MCP clients.
	Surface string
	// Scopes holds grant scopes ("read", "full") for MCP; empty for console.
	Scopes []string
	// Plugin is set when a plugin acts through the catalogue.
	Plugin string
}

type Proposal struct {
	// Category is a short English label for the approval card ("Blocklist a release").
	Category    string           `json:"category"`
	Description string           `json:"description"`
	Details     []ProposalDetail `json:"details,omitempty"`
	// Apply runs the change after approval. It must be idempotent.
	Apply func(ctx context.Context) (Result, error) `json:"-"`
	// Input is the validated input, stored with the approval for audit.
	Input map[string]any `json:"input,omitempty"`
}

type ProposalDetail struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type Result struct {
	// Data is sent to the model. Keep it compact and bounded.
	Data map[string]any `json:"data,omitempty"`
	// Links are offered in the console next to the answer.
	Links []Link `json:"links,omitempty"`
	// Navigate asks the console to open a route (the navigate tool).
	Navigate string `json:"navigate,omitempty"`
	// Proposal, when set, becomes an approval card; nothing has changed yet.
	Proposal *Proposal `json:"proposal,omitempty"`
	// Secret, when set, asks the owner for a credential through a secret
	// card. The value goes straight to sealed storage through Store and is
	// never returned to the tool, the transcript or a model.
	Secret *SecretRequest `json:"secret,omitempty"`
}

type SecretRequest struct {
	ProviderLabel   string `json:"providerLabel"`   // English source, e.g. "Real-Debrid"
	CredentialLabel string `json:"credentialLabel"` // English source, e.g. "API token"
	Purpose         string `json:"purpose"`         // English source, one sentence
	HelpURL         string `json:"helpUrl,omitempty"`
	// Store seals the value into its destination. It runs once, after the
	// owner submits, and must never log or echo the value.
	Store func(ctx context.Context, value string) error `json:"-"`
}

type Tool struct {
	Name        string          // snake_case; plugin tools are "<plugin>__<name>" with dots as _
	Title       string          // English source, translated in the console
	Description string          // for the model
	InputSchema json.RawMessage // JSON Schema (object); Execute re-validates
	ReadOnly    bool
	Destructive bool
	// OpenWorld marks tools that reach external services or return text that
	// third parties control (release names, TMDB overviews, plugin output).
	OpenWorld bool
	Audience  Audience
	// Owner is "builtin" or a plugin id.
	Owner string
	// Visible hides a tool from a principal entirely. Nil means visible.
	Visible   func(ctx context.Context, p Principal) bool
	Execute   func(ctx context.Context, p Principal, input map[string]any) (Result, error)
	Summarize func(Result) string
}

type UserError struct{ Message string }