extension

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package extension loads skills, sub-agents, MCP servers and hooks from built-ins, the user, the project and plugins. The project wins name clashes over the user, and the user over built-ins; plugin resources are namespaced, and all hooks run.

Anything that runs code or skips permission prompts needs the user's consent (see Surface and Consents), because a project or a plugin may come from anyone: a project's item by item, since its settings are odds and ends from many hands, and a plugin's as a whole, since its author tested it as one. A project's instructions for the model always load; a plugin not agreed to is off entirely.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AgreeToPlugin

func AgreeToPlugin(src plugin.Source, commit string, surface Surface) error

AgreeToPlugin records the user's agreement to everything the plugin runs, surface, at commit for a git plugin.

func EditConsents

func EditConsents(edit func(*Consents)) error

func LatestCommit

func LatestCommit(ctx context.Context, src plugin.Source) (string, error)

func PluginBase

func PluginBase(scope Scope, root string) string

func ReadPlugin

func ReadPlugin(ctx context.Context, src plugin.Source, commit string) (p *plugin.Plugin, got string, problems []error, err error)

ReadPlugin reads a plugin for the user to review. A git plugin is fetched at commit, or at its ref when commit is "", and the resolved commit is returned.

func SweepCache

func SweepCache() error

SweepCache removes cached commits unread for two weeks.

Types

type Consent struct {
	// Denied means the user distrusts the project and is not asked again.
	Denied bool `json:"denied,omitempty"`
	// Declined items are not asked about again.
	Surface  Surface `json:"surface,omitempty"`
	Declined Surface `json:"declined,omitempty"`
}

Consent is the user's decision on a project, item by item.

func (Consent) Decided

func (c Consent) Decided(surface, shown, agreed Surface) Consent

Decided records a decision on the shown items: agreed is accepted and the rest of shown is declined. Earlier decisions on items still on surface stand; items no longer on surface are forgotten.

func (Consent) Standing

func (c Consent) Standing(surface Surface) Standing

type Consents

type Consents struct {
	Projects map[string]Consent       `json:"projects,omitempty"`
	Plugins  map[string]PluginConsent `json:"plugins,omitempty"`
}

Consents records what the user agreed to run, per project root and per plugin source (plugin.Source.ID). It lives in the user's home so no project can grant itself consent, and only an explicit user decision writes it: reading, fetching or loading never does.

func ReadConsents

func ReadConsents() (Consents, error)

type Hook

type Hook struct {
	Event  string
	Scope  Scope
	Plugin string // "" when configured in settings
	config.HookEntry
}

func (Hook) Detail

func (h Hook) Detail() string

type Item

type Item struct {
	// Kind is "hook", "mcp", "allow", "read", "write", "skill" or "plugin".
	Kind string `json:"kind"`
	// Key is the full content of the item: any change makes it a different
	// item that needs consent again.
	Key string `json:"key"`
	// Detail is the escaped, human-readable form of the item.
	Detail string `json:"-"`
}

func NewItem

func NewItem(kind, s string) Item

type MCPServer

type MCPServer struct {
	Name   string
	Scope  Scope
	Plugin string // "" when configured in settings
	config.MCPServer
}

func (MCPServer) Detail

func (srv MCPServer) Detail() string

Detail omits a plugin's PLUGIN_ROOT and PLUGIN_DATA, which codebot sets.

type Options

type Options struct {
	Cwd      string
	Layers   config.Layers
	Consents Consents
	// PluginDirs are command-line plugins, loaded for this session only with
	// implicit consent.
	PluginDirs []string
	// TrustAll consents, for this session, to everything the project and
	// its declared plugins run.
	TrustAll bool
}

type Plugin

type Plugin struct {
	// Source is as written in settings or on the command line.
	Source string
	Scope  Scope
	// Src is Source parsed relative to the declaring settings file; zero if
	// it does not parse.
	Src plugin.Source
	// Commit is the agreed commit of a git plugin; "" for a local plugin or
	// one not agreed to yet.
	Commit string
	State  PluginState
	// Err is set when State is PluginBroken.
	Err error
	// Surface is everything the plugin runs; New is the part the user has
	// not agreed to, which keeps all of it off.
	Surface, New Surface
	// Plugin is nil unless State is PluginOn, PluginShadowed or
	// PluginWaiting.
	*plugin.Plugin
}

func (Plugin) Is

func (pl Plugin) Is(ref string) bool

func (Plugin) Title

func (pl Plugin) Title() string

type PluginConsent

type PluginConsent struct {
	// Commit pins a git plugin to the commit the user agreed to.
	Commit  string  `json:"commit,omitempty"`
	Surface Surface `json:"surface,omitempty"`
}

PluginConsent is the user's agreement to a plugin as a whole: its author tested it as one, so it runs all of Surface or nothing.

type PluginState

type PluginState string
const (
	PluginOn           PluginState = "on"
	PluginShadowed     PluginState = "shadowed"      // another plugin of the same name won
	PluginUntrusted    PluginState = "untrusted"     // the user has not agreed to the project declaring it
	PluginNotInstalled PluginState = "not installed" // a git plugin the user has not agreed to yet
	PluginNotCached    PluginState = "not cached"    // the agreed commit is no longer cached
	PluginWaiting      PluginState = "waiting"       // it runs something the user has not agreed to, so none of it runs
	PluginBroken       PluginState = "broken"
)

type Scope

type Scope string
const (
	Builtin Scope = "builtin"
	User    Scope = "user"
	Project Scope = "project"
	// Session marks a plugin given on the command line, for this session only.
	Session Scope = "session"
)

type Set

type Set struct {
	// Skills, Agents and MCP hold the winner of each name.
	Skills []skill.Spec
	// Agents excludes the built-in ones; subagent.Definitions layers these
	// over them.
	Agents []subagent.AgentDefinition
	MCP    []MCPServer
	// Hooks are ordered user, project, then plugins.
	Hooks []Hook
	// Plugins lists command-line plugins, then the project's, then the
	// user's, including those not in effect.
	Plugins []Plugin

	Trust Trust
	// Granted holds the project grants the user agreed to. See
	// config.ForProject.
	Granted config.Settings

	Shadowed []Shadow
	// Problems lists what was left out: files that failed to load and
	// project settings only the user may set. They are escaped for the
	// terminal.
	Problems []error
}

func Load

func Load(o Options) *Set

func (*Set) HooksConfig

func (s *Set) HooksConfig() config.HooksConfig

func (*Set) MCPConfig

func (s *Set) MCPConfig() map[string]config.MCPServer

type Shadow

type Shadow struct {
	Kind string // "skill", "agent", "MCP server" or "plugin"
	Name string
	// Lost and Won are the files of the replaced and the winning resource,
	// or "builtin".
	Lost, Won string
}

Shadow is a resource replaced by another of the same name.

type Standing

type Standing struct {
	Surface, Agreed, Declined Surface
}

Standing splits a surface into what the user agreed to and what they declined.

func (Standing) Ask

func (s Standing) Ask() Surface

func (Standing) Held

func (s Standing) Held() Surface

Held returns the items not in effect.

type Surface

type Surface []Item

Surface is the part of a project or plugin that runs code or skips permission prompts, so it needs the user's consent: hooks, MCP servers, allow rules, roots, plugins a project declares, and skill privileges. It stores the items themselves rather than a digest, so the user is asked only about items that are new. Items are sorted.

func PluginSurface

func PluginSurface(p *plugin.Plugin) Surface

PluginSurface lists the plugin's MCP servers, hooks and skill privileges. Paths are written as ${PLUGIN_ROOT} and ${PLUGIN_DATA}, so moving to another commit's directory alone does not need new consent.

func (Surface) Has

func (s Surface) Has(it Item) bool

func (Surface) HasAll

func (s Surface) HasAll(items []Item) bool

func (Surface) Intersect

func (s Surface) Intersect(other Surface) Surface

func (Surface) Missing

func (s Surface) Missing(agreed Surface) Surface

func (Surface) With

func (s Surface) With(items ...Item) Surface

type Trust

type Trust struct {
	// Root is "" outside a project; the home directory never counts as one.
	Root string
	Standing
	// Denied means the user distrusts the project: none of its surface takes
	// effect and they are not asked about it.
	Denied bool
	// ForRun is set by --trust, which overrides the saved decision for this
	// run.
	ForRun bool
}

func (Trust) Ask

func (t Trust) Ask() Surface

Directories

Path Synopsis
Package plugin reads plugins in the Agent Plugins 1.0 format and fetches them from git.
Package plugin reads plugins in the Agent Plugins 1.0 format and fetches them from git.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL