Documentation
¶
Overview ¶
Package installed is the shared install-state record and the capability diff: an install shows the capability summary and the diff against the currently installed version, and requires confirmation when a capability is widened.
The registry knows what an agent declares; only the machine knows what it previously ACCEPTED. Without a local record, every reinstall re-asks the same question from scratch and an upgrade that quietly adds egress to a new host looks exactly like the install the user already approved. This file is that record.
Location: ~/.config/agentry/installed.yaml — alongside config.yaml rather than under ~/.local/state. AGENTRY_CONFIG_DIR already relocates everything an agentry client keeps on disk (config, pinned signing keys, cached rule bundles); a second root would be a second thing to point at a container volume, and nothing here is large or high-churn enough to earn that.
EVERY client (CLI, desktop) must read and write this same file, so a capability diff on upgrade works regardless of which client did the original install. The same clients hold a downloaded archive's own manifest to the contract they asked consent on (ArchiveWidenings), so the rule for that lives here too.
Index ¶
- Constants
- func ArchiveWidenings(consented, archive manifest.Capabilities) []string
- func Save(st State) error
- func StatePath() (string, error)
- type CapSnapshot
- type Diff
- type Key
- type Record
- type RemoteSnapshot
- type ServerCapsSnapshot
- type State
- func (st *State) Find(k Key) *Record
- func (st *State) MarkLocal(k Key, digest string)
- func (st *State) Reconsent(k Key, version string, caps CapSnapshot, digest string) bool
- func (st *State) Remove(k Key) bool
- func (st *State) Upsert(k Key, version string, caps CapSnapshot, managed bool)
- func (st *State) UpsertAssigned(k Key, version string, managed bool, org string)
Constants ¶
const SourceLocal = "local"
SourceLocal marks a record installed from a local folder.
Variables ¶
This section is empty.
Functions ¶
func ArchiveWidenings ¶
func ArchiveWidenings(consented, archive manifest.Capabilities) []string
ArchiveWidenings reports what an archive's own manifest declares beyond the contract the person consented to, the resolve manifest's, on which the prompt and the diff were raised. The digest and the attestation cover the archive, so a widening means the registry's resolve answer diverged from the bytes it served, and an install refuses it rather than reconciling. It is the core's rule, manifest.DiffCapabilities, on the two full contracts, a declared MCP server's own egress, secrets and tools included.
Types ¶
type CapSnapshot ¶
type CapSnapshot struct {
// EgressHosts lists declared egress hosts; empty means none/undeclared.
EgressHosts []string `yaml:"egressHosts,omitempty" json:"egressHosts,omitempty"`
// EgressNone records an explicit `egress: none` (vs. not declared).
EgressNone bool `yaml:"egressNone,omitempty" json:"egressNone,omitempty"`
// FSRead/FSWrite are the declared modes ("", none, workspace, paths).
FSRead string `yaml:"fsRead,omitempty" json:"fsRead,omitempty"`
FSReadPaths []string `yaml:"fsReadPaths,omitempty" json:"fsReadPaths,omitempty"`
FSWrite string `yaml:"fsWrite,omitempty" json:"fsWrite,omitempty"`
FSWritePaths []string `yaml:"fsWritePaths,omitempty" json:"fsWritePaths,omitempty"`
// ExecCommands lists declared subprocess commands.
ExecCommands []string `yaml:"execCommands,omitempty" json:"execCommands,omitempty"`
// Secrets lists declared environment-variable NAMES (never values).
Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
// DataAccess lists declared semantic data categories.
DataAccess []string `yaml:"dataAccess,omitempty" json:"dataAccess,omitempty"`
// MCPServers lists declared MCP servers as "source:package@version"
// (RUNNER-PLAN-3) — a new or changed server is a widening the consent
// gate must re-ask about.
MCPServers []string `yaml:"mcpServers,omitempty" json:"mcpServers,omitempty"`
// MCPServerEnv is each declared server's plain env (name → literal
// value), keyed like MCPServers. Values are configuration, not
// secrets, so they are stored and shown: a changed value is a change
// to what the server receives and re-asks for consent. Absent in
// records written before env existed, which reads as "no env".
MCPServerEnv map[string]map[string]string `yaml:"mcpServerEnv,omitempty" json:"mcpServerEnv,omitempty"`
// MCPRemote is each declared remote server's sign-in and reach, keyed
// like MCPServers ("url:<address>"): the core's diff compares a remote
// server's auth, scopes, tool allowlist and bearer secret, so a record
// without them would read every run as a widening. Absent in records
// written before remote servers existed.
MCPRemote map[string]RemoteSnapshot `yaml:"mcpRemote,omitempty" json:"mcpRemote,omitempty"`
// MCPServerOAuth is each package server's OAuth sign-in, keyed like
// MCPServers, for the same reason.
MCPServerOAuth map[string]*manifest.MCPOAuth `yaml:"mcpServerOAuth,omitempty" json:"mcpServerOAuth,omitempty"`
// MCPServerCaps is what each declared package server's own container
// is given, keyed like MCPServers: the hosts it may reach, the secrets
// it receives and the tools the model may call on it. The runner builds
// the server's grants from these, so the core's diff compares them for
// a server kept at the same pin. Every package server has an entry,
// empty when it declares none of them; a server the record names with
// no entry has unknown grants (see DiffCapabilities).
MCPServerCaps map[string]ServerCapsSnapshot `yaml:"mcpServerCaps,omitempty" json:"mcpServerCaps,omitempty"`
// Knowledge lists the knowledge packs the release ships in its archive
// (the manifest's knowledge.ships, as manifest.Contract carries them):
// a new one is text entering the agent's context, a widening the
// consent gate re-asks about. Absent in records written before shipped
// knowledge existed, which reads as "ships none".
Knowledge []string `yaml:"knowledge,omitempty" json:"knowledge,omitempty"`
// TargetHosts lists the intake questions that ask for a target host
// (capabilities.targetHosts): one more is one more machine the agent
// may run any command on, a widening the consent gate re-asks about.
// Absent in records written before target hosts were recorded (CLI
// v0.6.108 and older), which reads as "none", so a release that
// already declared one is asked about once more.
TargetHosts []string `yaml:"targetHosts,omitempty" json:"targetHosts,omitempty"`
// Browser is the release's browser line (capabilities.browser): a new
// site, host or secret it may type, or site scope to public, is a
// widening the consent gate re-asks about. Absent in records written
// before the browser existed, which reads as "no browser".
Browser *manifest.Browser `yaml:"browser,omitempty" json:"browser,omitempty"`
// Desktop is the release's desktop line (capabilities.desktop): a new
// application on the person's computer, a tool added to one, or
// computer use, is a widening the consent gate re-asks about. Absent
// in records written before the line existed, which reads as "none".
Desktop *manifest.Desktop `yaml:"desktop,omitempty" json:"desktop,omitempty"`
// Persistent is a persistent release's capabilities.persistent: a key
// newly declared, or a name added to one of its lists, is a widening
// the consent gate re-asks about. Absent in records written before the
// block existed, which reads as "declares none".
Persistent *manifest.Persistent `yaml:"persistent,omitempty" json:"persistent,omitempty"`
// Subagents are a persistent release's subagents, each with its
// constraint and its reason: a new one, or a changed constraint, is a
// widening the consent gate re-asks about. Absent in records written
// before subagents existed, which reads as "none".
Subagents []manifest.AgentDependency `yaml:"subagents,omitempty" json:"subagents,omitempty"`
}
CapSnapshot is the on-disk form of a capability contract.
It is deliberately NOT manifest.Capabilities: that type's union fields (Egress, FSAccess) carry their shape in unexported-by-tag form with custom JSON codecs, so persisting it as YAML would silently drop the very fields the diff turns on. A flat, explicit record is also a format this file owns and can keep stable while the manifest evolves.
func Snapshot ¶
func Snapshot(c manifest.Capabilities) CapSnapshot
Snapshot flattens a manifest capability block for storage.
func (CapSnapshot) Empty ¶ added in v0.7.49
func (c CapSnapshot) Empty() bool
Empty says the snapshot records no contract at all.
type Diff ¶
type Diff = manifest.CapabilityDiff
Diff is the comparison between an installed contract and a new one: the core's manifest.CapabilityDiff, one type for the CLI, the desktop and the registry's account install.
func DiffCapabilities ¶
func DiffCapabilities(old, next CapSnapshot) Diff
DiffCapabilities compares the previously installed contract with the new one. The rule is the core's manifest.DiffCapabilities — the registry re-asks for an account install's acceptance by it — so the promise that the CLI, the desktop and the site ask again on the same widening is kept by construction, not by two copies staying in step. Everything it reports is phrased as a plain statement of the change: "this update adds network egress to evil.example".
A package server the old record names without its own grants (an older record) has unknown grants, not empty ones: reading it as empty would let a same-pin server's tool allowlist be lifted unasked, and reading it as the new release's would accept whatever it now declares. It widens once, with a line that says what the server is given, and the consent that follows records its grants.
type Key ¶
type Key struct {
Registry string `json:"registry" yaml:"registry"`
Namespace string `json:"namespace" yaml:"namespace"`
Name string `json:"name" yaml:"name"`
Target string `json:"target" yaml:"target"`
Dir string `json:"dir" yaml:"dir"`
}
Key identifies one installation. The DIRECTORY is part of the key: the same agent installed as a claude-skill in ~/.claude/skills and as an mcp server in a project are two independent installations with independent capability histories, and a diff that conflated them would ask the wrong question about the wrong files.
type Record ¶
type Record struct {
Registry string `yaml:"registry" json:"registry"`
Namespace string `yaml:"namespace" json:"namespace"`
Name string `yaml:"name" json:"name"`
Target string `yaml:"target" json:"target"`
Dir string `yaml:"dir" json:"dir"`
Version string `yaml:"version" json:"version"`
InstalledAt time.Time `yaml:"installedAt" json:"installedAt"`
Capabilities CapSnapshot `yaml:"capabilities" json:"capabilities"`
// Managed is true when the CLIENT chose Dir from the target's default.
// Only a managed directory may be deleted on uninstall or cleared on
// reinstall — a directory the user named is theirs and may hold files no
// agentry client put there. Optional so files written before this field
// existed still load; absent means NOT managed (the safe reading).
Managed bool `yaml:"managed,omitempty" json:"managed,omitempty"`
// Source is SourceLocal for a QuickAgent installed from a folder on
// this machine and never published, empty for a registry release. A
// local record names no registry to ask for an update, and a run of
// it by name reads the release Digest names from the runner home
// instead of resolving it.
Source string `yaml:"source,omitempty" json:"source,omitempty"`
// Digest is a local install's archive digest: which release directory
// holds it. Empty for a registry release, which a run resolves.
Digest string `yaml:"digest,omitempty" json:"digest,omitempty"`
// AssignedBy is the handle of the organization whose managed settings
// required this release, set when the client installed it on their
// behalf. Such a record carries no capabilities until the person
// consents in a run, so it is never a consent; the person's consent
// (Upsert, Reconsent) replaces the record and clears the field.
AssignedBy string `yaml:"assignedBy,omitempty" json:"assignedBy,omitempty"`
}
Record is one installed (registry, agent, target, dir) tuple.
func (Record) AwaitsConsent ¶ added in v0.7.49
AwaitsConsent says an organization installed the release for the person and no contract of it has been accepted yet: the next run asks.
type RemoteSnapshot ¶
type RemoteSnapshot struct {
Auth string `yaml:"auth" json:"auth"`
Scopes []string `yaml:"scopes,omitempty" json:"scopes,omitempty"`
Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`
Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
}
RemoteSnapshot is what a consent recorded of one remote server beside its address.
type ServerCapsSnapshot ¶
type ServerCapsSnapshot struct {
Egress []string `yaml:"egress,omitempty" json:"egress,omitempty"`
Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`
// Args are the words its command starts with: a change to them starts
// a different command, which the diff asks about again.
Args []string `yaml:"args,omitempty" json:"args,omitempty"`
}
ServerCapsSnapshot is what a consent recorded of one package server's own grants. Secrets are names, never values; a secret's optional marking is not recorded, as it is not a capability.
type State ¶
type State struct {
Records []Record `yaml:"records,omitempty"`
}
State is ~/.config/agentry/installed.yaml.
func Load ¶
Load reads the install manifest; a missing file is empty state.
A CORRUPT file is reported as an error so the caller can decide: the CLI warns and treats it as empty, because refusing to install over a truncated bookkeeping file would turn a cosmetic problem into an outage, and the worst case is one extra confirmation prompt.
func (*State) MarkLocal ¶
MarkLocal marks the key's record as a local install of the release with this archive digest. Upsert writes a registry record, as an install from a registry does; a local install calls this after it.
func (*State) Reconsent ¶
Reconsent records a run's consent to the contract of the release with this digest, keeping what an install recorded: whether the client chose the directory, and a local install's mark. A run of another tree than the agent's local install (a --local folder, a registry release by range) records nothing, so the local install stays what `run ns/name` finds; the consent was still asked and given for the run, and a later run asks it again. It reports whether it recorded. Every client's run records its consent through this, never Upsert.
func (*State) Upsert ¶
func (st *State) Upsert(k Key, version string, caps CapSnapshot, managed bool)
Upsert records an installation. managed says whether the client (not the user) chose the directory; see Record.Managed.
func (*State) UpsertAssigned ¶ added in v0.7.49
UpsertAssigned records an install the client made for the organization's managed settings. It never records consent: the capabilities kept are those the person already accepted for an earlier version of this release, and none when there is no earlier record, so the next run asks (and asks again for whatever the new version widens).