installed

package
v0.6.1017-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
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.

func Save

func Save(st State) error

Save writes the manifest (0600: it names local paths).

func StatePath

func StatePath() (string, error)

StatePath returns the install-state path inside the config dir.

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"`
	// 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.

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"`
}

Record is one installed (registry, agent, target, dir) tuple.

func (Record) Local

func (r Record) Local() bool

Local reports whether the record is a local, unpublished install.

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

func Load() (State, error)

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

func (st *State) Find(k Key) *Record

Find returns the record for a key, or nil.

func (*State) MarkLocal

func (st *State) MarkLocal(k Key, digest string)

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

func (st *State) Reconsent(k Key, version string, caps CapSnapshot, digest string) bool

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

func (st *State) Remove(k Key) bool

Remove deletes the record for a key, reporting whether one was present.

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.

Jump to

Keyboard shortcuts

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