extension

type CleanerUpper interface {
	Cleanup() error
}

type Command struct {
	// Use is the command name, optionally followed by its argument sketch
	// ("sync [target]"). The first word must be unique among all extension
	// commands in the build.
	Use string
	// Short is the one-line description shown in the command list.
	Short string
	// Long is the full help text.
	Long string
	// Aliases are alternative names for the command.
	Aliases []string
	// Flags declares the command's flags.
	Flags []Flag
	// Run executes the command. args holds the positional arguments after the
	// command name. Returning an error makes the process exit non-zero with
	// that message.
	Run func(ctx context.Context, args []string, flags Flags) error
	// Subcommands nest below this one. Their Use names must be unique among
	// their siblings.
	Subcommands []Command
}

type CommandProvider interface {
	Extension
	Commands() []Command
}

type ConfigOverlay struct {
	// Values is the overlay document. Its shape mirrors the configuration
	// file: section names at the top level, nested maps below. Keys absent
	// from it are left exactly as the host loaded them.
	//
	// Merge semantics, applied per key:
	//   - a scalar replaces the loaded value;
	//   - a map is merged key by key, recursively;
	//   - a list of objects that all carry an "id" is merged by that id, the
	//     overlay entries first, so an overlay can add or redefine one entry
	//     without restating the rest;
	//   - any other list replaces the loaded list, unless its path is named in
	//     Additive, in which case the two lists are unioned, loaded values
	//     first, duplicates dropped.
	Values map[string]any

	// Locked lists the paths the host must refuse to write locally. A write
	// through any configuration mutator that would change a locked path fails
	// with a typed error, and the surfaces report the key as managed by an
	// extension rather than as a failed save.
	//
	// Locking a path that the overlay does not set is allowed and means
	// "freeze whatever is there": the value stays whatever the files said, but
	// nobody may change it from inside Pando.
	Locked []string

	// Additive lists the list-valued paths that should be unioned with the
	// loaded value rather than replacing it. Use it for lists where local
	// entries are legitimate additions (extra context paths, extra banned
	// commands) rather than a competing choice.
	Additive []string

	// Source is a short human-readable label for where the document came from,
	// used in log lines and in the change event. Optional; the extension ID is
	// used when it is empty.
	Source string
}

type ConfigOverlayController interface {
	// ReapplyOverlays re-runs configuration load, asking every registered
	// provider for its current document. It returns the load error, if any.
	// Calls are serialised by the host; a call made while another is in
	// progress waits for it.
	ReapplyOverlays(ctx context.Context) error

	// RequestReload is the same operation, coalesced. Requests that arrive
	// close together share one reload and all return its outcome, so an
	// extension driven by a stream of remote notifications cannot make the
	// host reload once per notification. Prefer it for anything triggered by
	// an external event; use ReapplyOverlays when the caller needs the reload
	// to have finished by the time the call returns, with no delay.
	//
	// reason is a short label for the host log ("new policy generation"), not
	// something the host interprets.
	//
	// The error returned is the reload's own, so an extension learns that the
	// document it published cannot be loaded. A failed reload leaves the
	// previous configuration in effect. Cancelling ctx abandons the wait, not
	// the reload.
	//
	// Never call it from inside ConfigOverlay: the provider would be waiting
	// for a load that is waiting for the provider.
	RequestReload(ctx context.Context, reason string) error
}

type ConfigOverlayProvider interface {
	Extension
	ConfigOverlay(ctx context.Context) (ConfigOverlay, error)
}

type ConfigView interface {
	// WorkingDir is the project root.
	WorkingDir() string
	// DataDir is the per-project Pando data directory (.pando/data).
	DataDir() string
	// Debug reports whether the host runs in debug mode.
	Debug() bool
	// Lookup resolves a dotted configuration path to a value, for the rare
	// case where an extension must read a core setting. Returns false when the
	// path is unknown. Implementations return copies, never live pointers.
	Lookup(path string) (any, bool)
	// LockedKeys lists the configuration paths currently locked by an overlay
	// (see ConfigOverlay.Locked), sorted and deduplicated. It is the state a
	// panel or a settings surface reads to render a key as managed rather than
	// editable. Empty when no overlay locks anything.
	LockedKeys() []string
}

type Entitlement string

type Entitlements []Entitlement

type Entry struct {
	// Enabled switches the extension on. An extension is also loaded when it
	// has a non-empty Config, so that configuring one is enough to enable it.
	Enabled bool
	// Config is the extension's own configuration subtree.
	Config map[string]any
}

type Event struct {
	// Topic identifies the resource kind (see the Topic constants).
	Topic string
	// Type is what happened.
	Type EventType
	// ID is the resource identifier when the payload carries one.
	ID string
	// SessionID is the session the resource belongs to, when it belongs to one.
	SessionID string
	// Payload is the resource as JSON-decoded values: strings, float64 numbers,
	// bools, maps and slices. One map is shared by every subscriber of the
	// event, so treat it as read-only and copy anything you keep past the call.
	Payload map[string]any
	// Time is when the host observed the event.
	Time time.Time
}

type EventSubscriber interface {
	Extension
	// Topics lists the topics to receive. An empty result means every topic,
	// including topics added in later versions.
	Topics() []string
	// HandleEvent is called from the host's fan-out goroutine and must return
	// promptly: slow work belongs on a queue the extension owns. Events are
	// dropped rather than queued when a subscriber cannot keep up, so an
	// extension that must not lose events has to buffer them itself.
	HandleEvent(ctx context.Context, ev Event)
}

type EventType string

type Extension interface {
	ExtensionInfo() Info
}

type Flag struct {
	// Name is the long flag name, without dashes.
	Name string
	// Shorthand is the optional one-letter form, without the dash.
	Shorthand string
	// Usage is the one-line help text.
	Usage string
	// Value is the default value and, by its dynamic type, the flag type.
	Value any
}

type Flags map[string]any

type FrontendOverlay interface {
	Extension
	// OverlayAssets holds the replacement files, addressed by the same paths
	// they have in the core asset tree ("assets/logo.svg").
	OverlayAssets() fs.FS
	// Overrides lists the core asset paths this extension shadows, without a
	// leading slash. Files present in OverlayAssets but absent here are ignored.
	Overrides() []string
}

type FrontendProvider interface {
	Extension
	// AssetPath is the single path segment this extension owns under /ext/.
	// Same rules as HTTPEndpointProvider.BasePath: lowercase letters, digits,
	// '_' or '-', unique in the build.
	AssetPath() string
	// Assets is the built frontend to serve, typically an //go:embed of the
	// extension's own dist directory. Returning nil contributes no files, which
	// is valid for an extension whose panels live in a shared bundle.
	Assets() fs.FS
	// Panels returns the panels to register. It may return nil: an extension
	// may want to serve assets without declaring a panel.
	Panels() []PanelManifest
}

type FrontendReplacer interface {
	Extension
	// ReplaceFrontend returns the asset root to serve instead of core's.
	// Returning nil declines, which lets configuration decide at run time.
	ReplaceFrontend() fs.FS
}

type HTTPEndpointProvider interface {
	Extension
	// BasePath is the single path segment this extension owns under /api/ext/.
	// It must be a valid ID segment (lowercase letters, digits, '_' or '-') and
	// unique in the build; a collision is refused rather than resolved.
	BasePath() string
	// Routes returns the endpoints to mount. It is called once, when the API
	// server builds its mux, so the extension must already be provisioned —
	// which it is: the server is built after extensions load.
	Routes() []Route
}

type HTTPMiddlewareProvider interface {
	Extension
	// Priority orders middleware. Lower priority sits closer to the routes;
	// the highest priority is outermost and sees the request first. Ties break
	// on extension ID so ordering is stable across builds.
	Priority() int
	// WrapHTTP returns a handler wrapping next. Returning next unchanged is
	// valid and means "no opinion for this configuration".
	WrapHTTP(next http.Handler) http.Handler
}

type HostServices struct {
	// ID is the extension this value was built for. It is what names the
	// extension in log records and in the environment variables that can
	// override its configuration (see the accessors below). Empty in a host
	// that hands the same value to nobody in particular.
	ID ID

	// Raw is this extension's own configuration subtree, as written under
	// [Extensions.Entries."<id>".Config] in pando.toml. Never nil.
	//
	// Its top-level keys are folded to lower case, because that is what the
	// configuration system does to every key it reads: an author who writes
	// baseURL in a file finds baseurl here. Prefer the typed accessors below,
	// which fold the key being asked for as well and so accept any spelling;
	// index Raw directly only for shapes they do not cover, and then with a
	// lower-case key.
	Raw map[string]any

	// EnvPrefix is the environment-variable prefix used by the configuration
	// accessors. Empty means DefaultConfigEnvPrefix.
	EnvPrefix string

	// Config is a read-only view over the host configuration.
	Config ConfigView

	// Logger is scoped to the extension: records already carry its ID.
	Logger *slog.Logger

	// WorkingDir is the absolute path of the project Pando is running against.
	WorkingDir string

	// CoreVersion is the Pando core version this binary was built from.
	CoreVersion string

	// Variant identifies the build variant ("", "enterprise", ...). Extensions
	// should not branch on it; it exists for reporting.
	Variant string

	// ConfigOverlays lets an extension that implements ConfigOverlayProvider
	// tell the host its overlay document has changed. Nil in hosts that do not
	// support configuration overlays, so check before calling.
	ConfigOverlays ConfigOverlayController

	// Prompts runs a non-interactive prompt through the host's agent. Nil in a
	// host that has no agent, so check before calling.
	Prompts PromptRunner
}

type ID string

type Identity struct {
	// UserID is a stable identifier for the user, opaque to the host. It is
	// the only field the host itself consumes: it becomes the user id on the
	// attribution attached to memory events and session index metadata.
	UserID string

	// Email is the user's address, when the provider knows one. The host does
	// not read, log or persist it; it exists so that a capability which needs
	// it (a sink writing to a store that keys on address) can take it from the
	// same place as everything else rather than growing a second channel.
	Email string

	// DeviceID identifies the machine or enrolment the identity was issued
	// for. Same contract as Email: carried, not consumed.
	DeviceID string

	// Groups lists the group or role names the provider associates with the
	// user. Authorisation is never decided by the host from this list: a
	// permission that matters is enforced by the service that owns the
	// resource, not by the process asking.
	Groups []string
}

type IdentityProvider interface {
	Extension
	Identity(ctx context.Context) (Identity, bool)
}

type Info struct {
	// ID is the namespaced identifier. Required, must be Valid.
	ID ID
	// Name is a short human-readable name.
	Name string
	// Description is one line explaining what the extension does.
	Description string
	// Version is the extension's own version, independent of the core.
	Version string
	// Author identifies who ships it.
	Author string
	// License is informational. Defaults to LicenseMIT when empty.
	License License
	// RequiresCore is an optional semver constraint on the Pando core version
	// (for example ">= 0.647.0"). Empty means no constraint. The manager only
	// records it today; enforcement arrives with the licensing work.
	RequiresCore string
	// RequiresExtensions lists other extension IDs that must be loaded before
	// this one. Load order is derived from it.
	RequiresExtensions []ID
	// New builds a fresh instance. Required. The registry stores the factory,
	// never a live instance, so each Manager gets its own instances.
	New func() Extension
}

type License string

type LicenseClaims struct {
	// Customer identifies who the license was issued to. Shown in reporting.
	Customer string `json:"customer"`
	// IssuedAt is when the license was minted.
	IssuedAt time.Time `json:"issuedAt,omitzero"`
	// ExpiresAt is when it stops being valid. The zero value means perpetual.
	ExpiresAt time.Time `json:"expiresAt,omitzero"`
	// Entitlements lists what may load.
	Entitlements Entitlements `json:"entitlements"`
	// Notes is free text for humans (contract reference, support tier).
	Notes string `json:"notes,omitempty"`
}

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

type LicenseProvider interface {
	Extension

	// Entitled reports whether the extension described by info may load. A nil
	// error allows it; any error blocks it and is reported verbatim in that
	// extension's Status.
	Entitled(info Info) error

	// LicenseStatus describes the current license for reporting.
	LicenseStatus() LicenseStatus
}

type LicenseStatus struct {
	// Present is true when a license document was found at all. False with a
	// non-empty Error means "looked, and could not read one".
	Present bool `json:"present"`
	// Valid is true when the license verified and has not expired.
	Valid bool `json:"valid"`
	// Customer is who it was issued to.
	Customer string `json:"customer,omitempty"`
	// ExpiresAt is the expiry; zero means perpetual.
	ExpiresAt time.Time `json:"expiresAt,omitzero"`
	// Entitlements is what the license grants, for display.
	Entitlements []string `json:"entitlements,omitempty"`
	// Source describes where the license was loaded from.
	Source string `json:"source,omitempty"`
	// Error explains why an otherwise present license is not valid.
	Error string `json:"error,omitempty"`
}

type Lifecycle interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

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

type MemoryEvent struct {
	// Kind distinguishes a keyed memory from a KB document.
	Kind MemoryKind
	// Op is what happened.
	Op MemoryOp
	// Scope is the memory scope ("user/", "project/", "session/", ...). Empty
	// for documents that carry no scope. This is the field the per-scope
	// opt-in gate matches on.
	Scope string
	// Key is the memory key for keyed memories, empty otherwise.
	Key string
	// Path is the document path in the knowledge base. Always set: a keyed
	// memory is stored as a document too.
	Path string
	// Content is the record body. Empty on a delete.
	Content string
	// Tags are the record's tags.
	Tags []string
	// Embedding is the document-level embedding when core already computed
	// one, so a sink need not pay for it again. It may be nil even for a
	// content-bearing event, and a sink must cope with that.
	Embedding []float32
	// Metadata is the record's metadata map, JSON-decodable values only. It is
	// shared with other sinks: treat it as read-only.
	Metadata map[string]any
	// ProjectID identifies the project the write belongs to. Attribution, not
	// an isolation key: isolation belongs to the remote store.
	ProjectID string
	// UserID identifies the instance owner, when known.
	UserID string
	// InstanceID identifies this Pando instance, so a remote store can tell
	// two machines belonging to the same user apart.
	InstanceID string
	// Origin says which subsystem produced the write.
	Origin MemoryOrigin
	// Timestamp is when core observed the write.
	Timestamp time.Time
	// DryRun is true when the host is in dry-run mode. A sink must do
	// everything it normally does *except* send, and log what it would have
	// sent. Honouring this is a hard requirement, not a courtesy: dry-run is
	// how an operator audits what a corporate sink would exfiltrate.
	DryRun bool
}

type MemoryKind string

type MemoryOp string

type MemoryOrigin string

type MemorySink interface {
	Extension
	// OnMemoryWrite receives one write. Never called with a nil event.
	OnMemoryWrite(ctx context.Context, ev MemoryEvent) error
}

type MemorySyncReporter interface {
	// MemorySyncStatus returns the sink's current state. Called from HTTP
	// handlers; it must not block.
	MemorySyncStatus() MemorySyncStatus
}

type MemorySyncStatus struct {
	// Active reports whether the sink is currently shipping data.
	Active bool `json:"active"`
	// DryRun reports whether it is only pretending to.
	DryRun bool `json:"dryRun"`
	// Destination is human-readable and must identify where data goes (a host
	// name, not a secret-bearing URL).
	Destination string `json:"destination,omitempty"`
	// Scopes lists the scopes this sink is allowed to ship.
	Scopes []string `json:"scopes,omitempty"`
	// Pending is the number of events waiting to be sent.
	Pending int `json:"pending"`
	// Sent is the number of events shipped since start.
	Sent int64 `json:"sent"`
	// Dropped is the number of events lost, for any reason.
	Dropped int64 `json:"dropped"`
	// LastSyncAt is when the last successful send completed.
	LastSyncAt time.Time `json:"lastSyncAt,omitzero"`
	// LastError is the last failure, empty when healthy.
	LastError string `json:"lastError,omitempty"`
}

type Options struct {
	// Registry to load from. Defaults to the package-level registry.
	Registry *Registry
	// Entries is the per-extension configuration, keyed by ID.
	Entries map[string]Entry
	// Disabled lists IDs that must never load, whatever Entries says. It is the
	// stronger switch: it also turns off extensions that would otherwise load
	// by default.
	Disabled []string
	// Host is the base HostServices handed to each extension. The manager fills
	// in Raw and Logger per extension; the rest is passed through untouched.
	Host HostServices
	// Logger receives manager-level messages. Defaults to slog.Default().
	Logger *slog.Logger
}

type PanelManifest struct {
	// ID is unique within the extension. Core namespaces it with the extension
	// ID before handing it to the shell, so two extensions may use the same one.
	ID string
	// Title is the label shown to the user.
	Title string
	// Slot is where the panel mounts. Use one of the Slot* constants; an
	// unrecognised value is dropped with a log line rather than guessed at.
	Slot string
	// Entry is the ES module entry point, relative to the extension's asset
	// root and without a leading slash: "panels/reports.js". Core turns it into
	// an absolute URL for the shell.
	Entry string
	// Icon is an optional icon name the shell understands.
	Icon string
	// Order sorts panels inside a slot; equal values fall back to extension ID.
	Order int
}

type PromptProgress struct {
	// SessionID is the session the turn runs in.
	SessionID string
	// Delta is newly produced assistant text.
	Delta string
	// ToolName names a tool the turn has just started running.
	ToolName string
	// PromptTokens and CompletionTokens are the turn's running token totals.
	PromptTokens     int64
	CompletionTokens int64
	// CostUSD is the run's cost so far, in US dollars, as the host computed it
	// from the model's published prices. Zero when the host cannot price the
	// model.
	CostUSD float64
}

type PromptRequest struct {
	// Prompt is the user message. Required.
	Prompt string

	// Title names the session created for the run, for the session list and
	// the logs. Defaults to a truncation of the prompt.
	Title string

	// SessionID continues an existing session instead of creating one. Empty
	// starts a fresh session, which is what a one-shot job wants.
	SessionID string

	// AutoApprove answers every permission request for this run with yes.
	//
	// It exists because nobody is watching: a run started by a schedule or a
	// pipeline has no human to answer a prompt, and a turn that blocks forever
	// on an unanswerable question is worse than one that was told in advance
	// what it may do. It applies to this run's session only, never globally,
	// and an extension that leaves it false gets a turn that stops at the
	// first permission request.
	AutoApprove bool

	// OnProgress, when set, is called as the turn produces output. It is
	// called from the host's event goroutine and must return promptly: slow
	// work belongs on a queue the extension owns. A panic in it is contained
	// and the run continues.
	OnProgress func(PromptProgress)
}

type PromptResult struct {
	// SessionID is the session the turn ran in, whether it was created for the
	// run or continued.
	SessionID string
	// Text is the assistant's final answer.
	Text string
	// FinishReason is the host's reason for ending the turn ("end_turn",
	// "max_tokens", "canceled", "permission_denied", ...). It is a string
	// rather than an enumeration because the set grows with the providers.
	FinishReason string
	// PromptTokens and CompletionTokens are the turn's token totals.
	PromptTokens     int64
	CompletionTokens int64
	// CostUSD is what the turn cost, in US dollars, or zero when the host
	// cannot price the model.
	CostUSD float64
}

type PromptRunner interface {
	// RunPrompt sends req and blocks until the turn ends, the context is
	// cancelled, or the agent fails. A cancelled context ends the turn and
	// returns what was produced so far together with ctx.Err().
	RunPrompt(ctx context.Context, req PromptRequest) (PromptResult, error)
}

type ProviderRequest struct {
	// Provider is the provider identifier the host resolved for this call
	// ("anthropic", "openai", "ollama", ...).
	Provider string

	// Model is the API model id the request will name.
	Model string
}

type ProviderRequestDecorator interface {
	Extension
	DecorateProviderRequest(ctx context.Context, req ProviderRequest) (map[string]string, error)
}

type Provisioner interface {
	Provision(ctx context.Context, host HostServices) error
}

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

type Remembrance struct {
	// Path identifies the record.
	Path string
	// Content is the matching text.
	Content string
	// Score is the relevance score, higher is better. Scores from different
	// stores are not comparable; a wrapper that merges two stores is
	// responsible for producing a ranking that makes sense.
	Score float64
	// Tags are the record's tags.
	Tags []string
	// Scope is the record's scope, when it has one.
	Scope string
	// Source names where the hit came from: empty (or "local") for core's own
	// store, otherwise a wrapper-supplied label shown to the user. A merged
	// result set that does not label its remote hits is indistinguishable from
	// a local one, which is exactly what the visibility requirement forbids.
	Source string
	// UpdatedAt is the record's last modification time, when known.
	UpdatedAt time.Time
}

type RemembranceQuery struct {
	// Query is the natural-language search text.
	Query string
	// Limit is the maximum number of results the caller wants.
	Limit int
	// Tags narrows the search to records carrying any of these tags.
	Tags []string
	// Scope narrows the search to one scope prefix. Empty means every scope.
	Scope string
	// ProjectID is the project the search runs in.
	ProjectID string
}

type RemembranceSearchWrapper interface {
	Extension
	// WrapRemembranceSearch is called once, during startup, before any search
	// runs. It must not block.
	WrapRemembranceSearch(next RemembranceSearcher) RemembranceSearcher
}

type RemembranceSearcher interface {
	SearchRemembrances(ctx context.Context, q RemembranceQuery) ([]Remembrance, error)
}

type RemembranceSearcherFunc func(ctx context.Context, q RemembranceQuery) ([]Remembrance, error)

type Route struct {
	// Pattern is a net/http ServeMux pattern *relative to the extension's base
	// path*, without a leading slash: "ping", "reports/{id}", "GET /status".
	// A method prefix is honoured exactly as ServeMux honours it.
	Pattern string
	// Handler serves the route.
	Handler http.Handler
}

type SignedLicense struct {
	// KeyID names the signing key, so keys can be rotated without breaking
	// licenses already issued under the previous one.
	KeyID string `json:"keyId"`
	// Claims is the raw JSON of the LicenseClaims.
	Claims json.RawMessage `json:"claims"`
	// Signature is the base64 (standard encoding) Ed25519 signature over Claims.
	Signature string `json:"signature"`
}

type SlashCommand struct {
	// Name is typed after the slash, lowercase, no spaces. It must not collide
	// with a built-in command; registration rejects the collision rather than
	// letting an extension hijack /compact.
	Name string
	// Description is shown in the command palette and completions.
	Description string
	// AcceptsArgs tells the UI whether to expect text after the name.
	AcceptsArgs bool
}

type SlashCommandProvider interface {
	Extension
	SlashCommands() []SlashCommand
	// RunSlashCommand executes one of the declared commands. args is the raw
	// text after the command name, untrimmed of internal spacing. Returning an
	// error surfaces it to the user; it does not abort the session.
	RunSlashCommand(ctx context.Context, name, args string) (SlashResult, error)
}

type SlashResult struct {
	Prompt string
	Output string
}

type Status struct {
	Info Info
	// Loaded is true once Provision and Validate have both succeeded.
	Loaded bool
	// Disabled is true when configuration switched the extension off; Err is
	// nil in that case.
	Disabled bool
	// Unlicensed is true when the license gate refused the extension. Err then
	// holds the reason. It is kept apart from a plain load failure because the
	// two need different answers: a load failure is a bug report, an
	// unlicensed extension is a question for whoever owns the contract.
	Unlicensed bool
	// Err holds the reason an extension failed to load.
	Err error
}

type Tool interface {
	Info() ToolInfo
	Run(ctx context.Context, call ToolCall) (ToolResponse, error)
}

type ToolCall struct {
	// ID is the provider-assigned call identifier.
	ID string
	// Name is the tool being called.
	Name string
	// Input is the raw JSON argument object.
	Input string
}

type ToolFilter interface {
	ToolMiddleware
	FilterTools(tools []Tool) []Tool
}

type ToolFunc func(ctx context.Context, call ToolCall) (ToolResponse, error)

type ToolInfo struct {
	// Name is the tool name the model calls. Must be unique across all tools in
	// a build; namespace it with a vendor prefix to avoid clashing with core.
	Name string
	// Description tells the model what the tool does and when to use it.
	Description string
	// Parameters is a JSON Schema "properties" object describing the input.
	Parameters map[string]any
	// Required lists the required parameter names.
	Required []string
}

type ToolInterceptor interface {
	ToolMiddleware
	InterceptTool(ctx context.Context, call ToolCall, next ToolFunc) (ToolResponse, error)
}

type ToolMiddleware interface {
	Extension
	// Priority orders middleware. Lower runs closer to the tool: filters with a
	// lower priority run first, and interceptors with a lower priority sit
	// innermost, so a high-priority interceptor observes the calls a
	// low-priority one made. Ties break on extension ID, so ordering is stable
	// across builds.
	Priority() int
}

type ToolProvider interface {
	Extension
	// Tools returns the tools to register. It is called once per agent build,
	// so it may return different tools as configuration changes.
	Tools() []Tool
}

type ToolResponse struct {
	// Content is the textual result.
	Content string
	// Metadata is an optional JSON object carried alongside the content, shown
	// in the UI but not necessarily sent to the model.
	Metadata string
	// IsError marks the call as failed. Prefer returning a ToolResponse with
	// IsError set over returning a Go error: the former is reported to the
	// model, the latter aborts the call.
	IsError bool
}

type UIPolicy struct {
	// HiddenSections lists the paths the surfaces should not render at all. A
	// section whose every field is hidden disappears with them.
	//
	// The host also refuses local writes to a hidden path, so that hiding is
	// not the only thing standing between a client and the value.
	HiddenSections []string

	// ReadOnlySections lists the paths the surfaces should render with their
	// value visible but not editable, marked with ReadOnlyLabel. Writes to
	// them are refused for the same reason as hidden paths.
	//
	// A path that is in both lists is hidden: the stronger statement wins.
	ReadOnlySections []string

	// ReadOnlyLabel is the short caller-supplied text a surface shows on a
	// read-only field, in place of the host's own generic marker ("Managed by
	// the operator", the name of the system that owns the value). Optional;
	// the host uses its default marker when it is empty.
	ReadOnlyLabel string

	// Banner is the notice the surfaces show above the settings, explaining
	// once what the rest of the policy does to individual fields. Optional.
	Banner UIPolicyBanner
}

type UIPolicyBanner struct {
	// Text is the message. Keep it to one line: the terminal renders it as a
	// single row above the sections.
	Text string

	// Link is an optional URL the message refers to, rendered as a plain URL
	// on surfaces that cannot make it clickable.
	Link string
}

type UIPolicyProvider interface {
	Extension
	UIPolicy(ctx context.Context) (UIPolicy, bool)
}

type Validator interface {
	Validate() error
}