plugin

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

type BundleFile struct {
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
	Mode   uint32 `json:"mode"`
}

type BundleLimits struct {
	MaxCompressedBytes int64
	MaxExpandedBytes   int64
	MaxFileBytes       int64
	MaxFiles           int
	MaxPathBytes       int
	MaxDepth           int
}

type BundleSpec struct {
	Format       string `json:"format"`
	DigestSHA256 string `json:"digest_sha256"`
}

type CapabilityError struct {
	PluginID   string
	Capability string
}

type CompatibilitySpec struct {
	Server          string `json:"server"`
	DashboardHost   string `json:"dashboard_host"`
	RuntimeProtocol string `json:"runtime_protocol"`
}

type DependencySpec struct {
	ID       string `json:"id"`
	Version  string `json:"version,omitempty"`
	Optional bool   `json:"optional,omitempty"`
}

type ExtractedBundle struct {
	Root        string
	RuntimePath string
	UIRoot      string
	UIEntry     string
	Digest      string
	Inventory   map[string]BundleFile
}

type GenerationCleanupError struct {
	PluginID      string
	Generation    uint64
	Stage         string
	PendingStages []string
	ResidualPGIDs []int
	Transport     error
	Authority     error
	RemoveAll     error
	Err           error
}

type GenerationCleanupResult struct {
	PluginID      string
	Generation    uint64
	Stage         string
	PendingStages []string
	ResidualPGIDs []int
	Transport     error
	Authority     error
	RemoveAll     error
	Err           error
}

type GenerationLeasingRunner interface {
	AcquireInvocation(pluginID string, generation uint64) (InvocationGenerationLease, error)
}

type HTTPHost interface {
	Do(ctx context.Context, req HostHTTPRequest) (HostHTTPResponse, error)
}

type HostAccessSpec struct {
	RPC []RPCDependency `json:"rpc,omitempty"`
}

type HostAudit interface {
	RecordHostCall(ctx context.Context, event HostCallEvent)
}

type HostCallEvent struct {
	PluginID   string
	Action     string
	Capability string
	Decision   string
	Reason     string
}

type HostHTTPRequest struct {
	Method string
	URL    string
	Header map[string]string
	Body   []byte
}

type HostHTTPResponse struct {
	StatusCode int
	Header     map[string]string
	Body       []byte
}

type HostLogEntry struct {
	PluginID string
	Level    string
	Message  string
	Fields   map[string]string
}

type HostServices struct {
	KV KVHost
	// Secret is the encrypted namespaced store (spec §9.4). When nil, a plugin
	// holding secret:read/secret:write gets ErrHostServiceUnavailable rather than
	// silently falling back to plaintext KV.
	Secret SecretHost
	// Task enqueues agent work for an APPROVED operation (spec §9.3). Reachable only
	// with task:run AND a context-bound operation grant, so a plugin cannot touch a
	// node outside a plan an operator read and approved.
	Task         TaskHost
	Notify       NotifyHost
	HTTP         HTTPHost
	OperatorHTTP OperatorHTTPHost
	Log          LogHost
	Audit        HostAudit
	// RPC dispatches inter-plugin calls (design-09 §F). When nil, a plugin with
	// rpc:call gets ErrHostServiceUnavailable rather than a panic.
	RPC RPCHost
	// GuardURL, when set, validates an outbound HTTP target's URL/host BEFORE the
	// broker delegates to HTTP.Do. It makes SSRF/egress guarding structural at the
	// broker boundary rather than relying on every HTTPHost implementation to
	// remember to guard. A non-nil error rejects the request before any dial. When
	// nil, the broker falls back to a built-in guard (see defaultGuardURL) so an
	// HTTPHost is never trusted by convention alone.
	GuardURL         func(url string) error
	GuardOperatorURL func(url string) error
}

type HostTaskRequest struct {
	PluginID    string
	ApprovalID  string
	NodeID      string
	Interpreter string
	Script      string
	TimeoutSec  int
}

type InterfaceContract struct {
	Service string `json:"service"`
	// Methods remains the normalized name list so v1 callers keep their source
	// contract. MethodSpecs carries the signed v2 effect and method-level scopes.
	Methods     []string          `json:"-"`
	MethodSpecs []InterfaceMethod `json:"-"`
	Scopes      []string          `json:"scopes,omitempty"`
	// Backing is empty on manifests signed before the field existed. Empty stays
	// omitted from the signing payload, so those signatures remain byte-identical
	// and valid; the gateway resolves them through a logged legacy path until they
	// are re-signed with an explicit declaration.
	Backing string `json:"backing,omitempty"`
	// contains filtered or unexported fields
}

type InterfaceMethod struct {
	Name                 string            `json:"name"`
	Effect               string            `json:"effect"`
	Scopes               []string          `json:"scopes,omitempty"`
	OperatorTargetFields []string          `json:"operator_target_fields,omitempty"`
	Budget               *InvokeBudgetSpec `json:"budget,omitempty"`
}

type InvocationGenerationLease interface {
	Invoke(ctx context.Context, req InvokeRequest) (InvokeResponse, error)
	Release()
}

type InvokeBudgetSpec struct {
	TimeoutMS   int `json:"timeout_ms"`
	StdoutBytes int `json:"stdout_bytes"`
	StderrBytes int `json:"stderr_bytes"`
	HostCalls   int `json:"host_calls"`
}

type InvokeConstraints struct {
	OperatorTargets []string
	// Budget is the signed method-level runtime budget resolved by the host. Nil
	// is the additive compatibility path for already-signed manifests and resolves
	// to the old global defaults with a host warning.
	Budget *InvokeBudgetSpec
	// BudgetLabel is a stable service/method label used only for host logs.
	BudgetLabel string
	// Operation is the one-time authority for an approved host-risk operation (§9.3).
	// Like OperatorTargets it stays on the host side of the boundary: the plugin never
	// receives it, so it cannot forge or widen one — it can only make a host call that
	// the broker then checks against it.
	Operation *OperationGrant
}

type InvokeRequest struct {
	PluginID    string
	Generation  uint64
	Action      string
	Payload     json.RawMessage
	Constraints InvokeConstraints
}

type InvokeResponse struct {
	OK       bool            `json:"ok"`
	Message  string          `json:"message,omitempty"`
	Result   json.RawMessage `json:"result,omitempty"`
	Warnings []string        `json:"warnings,omitempty"`
}

type Invoker interface {
	Invoke(ctx context.Context, req InvokeRequest) (InvokeResponse, error)
}

type KVHost interface {
	Get(ctx context.Context, key string) ([]byte, bool, error)
	Put(ctx context.Context, key string, value []byte) error
}

type LoadOutcome struct {
	BundlePath string
	PluginID   string
	Loaded     bool
	Reason     string // failure reason when Loaded is false
}

type Loaded struct {
	Manifest       Manifest
	Capabilities   []string
	BundlePath     string
	ArtifactPath   string
	ArtifactDigest string
	ExtractedRoot  string
	RuntimeEntry   string
	RuntimePath    string
	UIRoot         string
	UIEntry        string
	Inventory      map[string]BundleFile
	BundleLimits   BundleLimits
}

type Loader struct {
	Dir      string
	CacheDir string
	Platform string
	Limits   BundleLimits
	Policy   TrustPolicy
}

type LogHost interface {
	Write(ctx context.Context, entry HostLogEntry) error
}

type Manifest struct {
	Schema           string             `json:"schema,omitempty"`
	ID               string             `json:"id"`
	Name             string             `json:"name"`
	Type             string             `json:"type"`
	Capabilities     []string           `json:"capabilities"`
	Version          string             `json:"version,omitempty"`
	Entrypoint       string             `json:"entrypoint,omitempty"`
	Publisher        string             `json:"publisher,omitempty"`
	DigestSHA256     string             `json:"digest_sha256,omitempty"`
	SignatureEd25519 string             `json:"signature_ed25519,omitempty"`
	Bundle           *BundleSpec        `json:"bundle,omitempty"`
	Runtime          *RuntimeSpec       `json:"runtime,omitempty"`
	UIRuntime        *UIRuntimeSpec     `json:"ui_runtime,omitempty"`
	Compatibility    *CompatibilitySpec `json:"compatibility,omitempty"`
	MinServer        string             `json:"min_server,omitempty"`
	HostAccess       *HostAccessSpec    `json:"host_access,omitempty"`
	// UI + Interfaces are the design-10 dashboard contributions: declarative data
	// (nav/views) + the interfaces the plugin exposes. They are covered by the
	// signature (see SigningPayload) so a tampered contribution fails verification.
	UI         *ManifestUI         `json:"ui,omitempty"`
	Interfaces []InterfaceContract `json:"interfaces,omitempty"`
	// Dependencies declares plugin-to-plugin requirements (design-18 D3/E1).
	// Required dependencies gate both load and activation; optional ones are
	// advisory. Covered by the v2 signing payload like every other field.
	Dependencies []DependencySpec `json:"dependencies,omitempty"`
}

type ManifestUI struct {
	Nav   []NavContribution  `json:"nav,omitempty"`
	Views []ViewContribution `json:"views,omitempty"`
}

type NavContribution struct {
	Section      string   `json:"section"`
	SectionTitle string   `json:"section_title,omitempty"`
	Title        string   `json:"title"`
	Route        string   `json:"route"`
	Icon         string   `json:"icon,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
}

type NotifyHost interface {
	Send(ctx context.Context, title, body string) error
}

type OperationExecuteRequest struct {
	ApprovalID string          `json:"approval_id"`
	Targets    []string        `json:"targets"`
	Data       json.RawMessage `json:"data,omitempty"`
}

type OperationGrant struct {
	ApprovalID string
	PluginID   string
	// PlanSHA256 is the hash of the exact approved plan text. Carried for audit so a
	// task can be tied back to the approval it ran under.
	PlanSHA256 string
	// Targets is the approved node set. The broker refuses any task aimed elsewhere, so
	// a plugin holding a legitimate grant still cannot reach an unapproved node.
	Targets []string
	// Remaining bounds how many tasks this single approved operation may enqueue.
	Remaining int
}

type OperatorHTTPHost interface {
	DoOperator(ctx context.Context, req HostHTTPRequest) (HostHTTPResponse, error)
}

type OwnerActiveFunc func(pluginID string) bool

type PluginOperationPlan struct {
	// Summary is the one-line intent an operator sees first.
	Summary string `json:"summary"`
	// Targets are the node IDs this operation would touch. The server authorizes each
	// one against the approving principal and records them as Approval.Targets; a plugin
	// cannot widen its own blast radius by naming extra nodes.
	Targets []string `json:"targets"`
	// Preview is the redacted, human-reviewable body of the change. It is what the
	// operator actually reads, so it must not contain secrets — the plugin redacts it,
	// and the server never reconstructs the unredacted form (§9.4).
	Preview string `json:"preview,omitempty"`
	// Steps are the ordered actions the plugin intends to take.
	Steps []string `json:"steps,omitempty"`
	// Rollback states what undoing this looks like. A plan that cannot say how it is
	// undone is a plan an operator cannot safely approve.
	Rollback string `json:"rollback,omitempty"`
	// Data is opaque plugin-owned state carried through approval back into execute. The
	// server does not interpret it; it hands back exactly what was approved.
	Data json.RawMessage `json:"data,omitempty"`
}

type PoolCleanupResult struct {
	Generation    uint64
	Err           error
	ResidualPGIDs []int
	Stage         string
	PendingStages []string
}

type RPCDependency struct {
	Service string   `json:"service"`
	Methods []string `json:"methods"`
}

type RPCGrant map[string]map[string]struct{}

type RPCGrantedHost interface {
	CallGranted(ctx context.Context, caller string, grant RPCGrant, service, method string, request []byte) ([]byte, error)
}

type RPCHandler func(ctx context.Context, method string, request []byte) ([]byte, error)

type RPCHost interface {
	Call(ctx context.Context, caller, service, method string, request []byte) ([]byte, error)
}

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

type RPCServiceDescriptor struct {
	Service string   `json:"service"`
	Owner   string   `json:"owner"`
	Version string   `json:"version"`
	Methods []string `json:"methods"`
}

type ResolvedInvokeBudget struct {
	Timeout     time.Duration
	StdoutBytes int
	StderrBytes int
	HostCalls   int
	Declared    bool
}

type Runner interface {
	Name() string
	Start(ctx context.Context, req RunnerStartRequest) (RunnerStartResult, error)
	Stop(ctx context.Context, req RunnerStopRequest) error
}

type RunnerCloser interface {
	StopAll(ctx context.Context) error
}

type RunnerStartRequest struct {
	PluginID   string
	Generation uint64
	Loaded     Loaded
	Broker     *Broker
}

type RunnerStartResult struct {
	Message string
}

type RunnerStopRequest struct {
	PluginID   string
	Reason     string
	Generation uint64
}

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

type RuntimeManagerOptions struct {
	Services     HostServices
	Runners      map[string]Runner
	StartTimeout time.Duration
}

type RuntimeShutdownError struct {
	PluginID      string
	Stage         string
	PendingStages []string
	Err           error
}

type RuntimeSpec struct {
	Protocol    string            `json:"protocol"`
	Entrypoints map[string]string `json:"entrypoints"`
}

type RuntimeStatus struct {
	PluginID  string    `json:"plugin_id"`
	State     string    `json:"state"`
	Runner    string    `json:"runner,omitempty"`
	Message   string    `json:"message,omitempty"`
	StartedAt time.Time `json:"started_at,omitempty"`
	StoppedAt time.Time `json:"stopped_at,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

type SecretHost interface {
	Get(ctx context.Context, key string) (string, bool, error)
	Put(ctx context.Context, key, value string) error
	Delete(ctx context.Context, key string) error
}

type SystemPoolCircuitTransition int

type SystemPoolConfig struct {
	Size         int
	MaxOverflow  int
	StartTimeout time.Duration
	MaxUses      int
	MaxAge       time.Duration
}

type SystemPoolDurationPhase int

type SystemPoolLifecycleEvent int

type SystemPoolObserver interface {
	ObserveSystemPoolDuration(phase SystemPoolDurationPhase, d time.Duration)
	ObserveSystemPoolLifecycle(event SystemPoolLifecycleEvent)
	ObserveSystemPoolCircuit(transition SystemPoolCircuitTransition)
	ObserveSystemPoolRetirement(reason SystemPoolRetirementReason)
}

type SystemPoolRetirementReason int

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

type SystemRunnerOptions struct {
	// RuntimeDir is the root under which each plugin gets a confined 0700 working
	// directory (RuntimeDir/<pluginID>) holding a 0700 copy of its verified
	// artifact. Required.
	RuntimeDir string
	// EnvAllowlist names the environment variables forwarded to the plugin. Every
	// other variable is stripped; a fixed safe PATH is always provided.
	EnvAllowlist []string
	// InvokeTimeout bounds one invocation (default 10s).
	InvokeTimeout time.Duration
	// StopGrace is the SIGTERM->SIGKILL window for a timed-out/cancelled process
	// (default 3s).
	StopGrace time.Duration
	// MaxOutputBytes caps captured stdout and (separately) stderr per invocation
	// (default 1 MiB), so a plugin cannot exhaust host memory by flooding output.
	MaxOutputBytes int
	// CrashThreshold trips the circuit breaker after this many consecutive failed
	// invocations (default 5).
	CrashThreshold int
	// MaxHostCalls caps broker calls during one invocation (default 64).
	MaxHostCalls int
	// Logf receives host-visible runtime warnings. Nil disables warning logs.
	Logf func(format string, args ...any)
	// Pool controls stdio-json-v2 worker capacity and retirement. Nil uses safe
	// host defaults; a non-nil value is validated exactly, including zero overflow.
	Pool *SystemPoolConfig
	// PoolObserver receives warm-pool telemetry at the pool's decision points.
	// Nil observes nothing. The observer must be cheap and must not call back
	// into the runner.
	PoolObserver SystemPoolObserver
}

type TaskHost interface {
	Enqueue(ctx context.Context, req HostTaskRequest) (string, error)
}

type TransactionalRunner interface {
	Runner
	Prepare(ctx context.Context, req RunnerStartRequest) (RunnerStartResult, error)
	ActivateGeneration(pluginID string, generation uint64) error
	AbortGeneration(ctx context.Context, pluginID string, generation uint64) error
	RetireGeneration(ctx context.Context, pluginID string, generation uint64) error
}

type TrustPolicy struct {
	TrustedPublishers map[string]ed25519.PublicKey
	// AllowUnsignedHostRisk opts OUT of signature enforcement for host-risk
	// plugins. The zero value is fail-closed: host-risk plugins require a trusted
	// publisher signature unless an operator explicitly sets this true (dev only).
	AllowUnsignedHostRisk bool
}

type UIRuntimeSpec struct {
	Mode          string `json:"mode"`
	Entrypoint    string `json:"entrypoint"`
	BridgeVersion string `json:"bridge_version"`
}

type ViewAction struct {
	Label     string          `json:"label"`
	Interface string          `json:"interface"`
	Method    string          `json:"method"`
	Form      []ViewFormField `json:"form,omitempty"`
	Scopes    []string        `json:"scopes,omitempty"`
}

type ViewColumn struct {
	Key    string `json:"key"`
	Label  string `json:"label"`
	Render string `json:"render,omitempty"`
}

type ViewContribution struct {
	Route   string       `json:"route"`
	Title   string       `json:"title"`
	Kind    string       `json:"kind"`
	Source  *ViewSource  `json:"source,omitempty"`
	Columns []ViewColumn `json:"columns,omitempty"`
	Actions []ViewAction `json:"actions,omitempty"`
}

type ViewFormField struct {
	Key     string   `json:"key"`
	Label   string   `json:"label,omitempty"`
	Kind    string   `json:"kind"`
	Options []string `json:"options,omitempty"`
}

type ViewSource struct {
	Interface string `json:"interface"`
	Method    string `json:"method"`
}