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 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)
}

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 {
	// Raw is this extension's own configuration subtree, as written under
	// [Extensions.Entries."<id>".Config] in pando.toml. Never nil.
	Raw map[string]any

	// 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
}

type ID string

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 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 Validator interface {
	Validate() error
}