Documentation
¶
Overview ¶
Package installdir is the runner home's per-release directory: where a verified release is laid down for runs, and where `agentry install` and the desktop put a QuickAgent by default. One layout, one metadata file, one copy of the code — a run finds an installed release by its digest and skips the fetch; an install is what a run's first fetch would have left behind, plus the export a coding agent would read.
<runner home>/agents/<ns>/<name>/ the agent's directory (installed.yaml's dir)
<version>-<12 of the digest>/ one release
install.json Meta: what was verified, once
integrity.json the record that install.json and workspace/ are as laid down (integrity.go)
workspace/ the release's files, pristine
export/ the coding-agent shape (writeExport)
plan/ runs/ the run's own, ephemeral
Index ¶
- Constants
- Variables
- func AgentDir(home, namespace, name string) string
- func AgentsRoot(home string) string
- func CheckCopy(releaseDir, copyDir string) error
- func ConsentKey(home, namespace, name string) installed.Key
- func DigestSuffix(digest string) string
- func HomeOf(releaseDir string) (string, error)
- func Install(releaseDir, srcTree string, m *manifest.Manifest, meta *Meta, style string) error
- func ReleaseDir(home, namespace, name, version, digest string) string
- func ReleaseName(version, digest string) string
- func RemoveOtherVersions(agentDir, keep string) error
- func Repair(releaseDir, srcTree string, m *manifest.Manifest, meta *Meta, style string) error
- func Replace(dir, srcTree string, meta *Meta) error
- func StyleFor(pol *policy.Policy) string
- func StyleForHome(home string) (style, warning string)
- func Write(dir, srcTree string, meta *Meta) error
- type ChangedError
- type Meta
- type RecordFailure
Constants ¶
const ConsentRegistry = "runner"
ConsentRegistry is what the runner's record carries in installed.yaml's registry column: a run resolves through the configured registry and its record names none, so the sentinel is the target's own name — the key reads runner/runner. `list --check` asks the configured registry for such a record.
const RecordFile = "integrity.json"
RecordFile is the integrity record's name beside install.json.
const Target = "runner"
Target is the install target that names this directory, beside the two coding-agent exports in installed.yaml's target column.
Variables ¶
var ErrNoRecord = errors.New("installed release has no integrity record from this runner home")
ErrNoRecord reports an installed release with no integrity record this runner home can check: missing, unreadable, malformed, or made under another key. The caller lays it down again from the registry.
var ErrNotARelease = errors.New("not a release of this agent")
ErrNotARelease is RemoveOtherVersions' refusal of a keep that is not a release directly under the agent's directory: a path the caller built wrong, never an older version that would not go, so a caller that says a failed replace as a warning still stops on it.
var ErrNotInstalled = errors.New("release not installed")
ErrNotInstalled reports that the release is not installed at the directory: no install.json, another release's, or no workspace.
Functions ¶
func AgentDir ¶
AgentDir is the agent's directory under the runner home, stable across versions: the one installed.yaml records, and the one an uninstall removes.
func AgentsRoot ¶
AgentsRoot is the directory every agent's directory sits directly under.
func CheckCopy ¶
CheckCopy holds a copy of an installed release's files (a run's per-run workspace, made after Inspect) to the release's integrity record, so an edit made to the install between the check and the copy does not run. A copy is made by reading through symlinks and writing under the process umask, so it is compared on content alone: a symlink planted in the install after the check arrives in the copy as the content of what it points at, which the record does not hold. releaseDir is the installed release, copyDir the copy of its workspace/.
func ConsentKey ¶
ConsentKey is the installed.yaml key the runner's record lives under — the run's consent record and the install's record too, so a consent given by either covers the other and there is one record per QuickAgent.
func DigestSuffix ¶
DigestSuffix shortens sha256:… for directory names.
func HomeOf ¶
HomeOf is the runner home a release directory sits in: every release is laid down at <home>/agents/<ns>/<name>/<release> (ReleaseDir), and its integrity record is made under that home's key.
func Install ¶
Install is the one lay-down both clients call for the runner target: the verified release written as Write does, with the coding-agent shape in the given style (writeExport) inside it, published as one tree. It is called only once the digest, the attestation and the consent have been judged — it checks none of them. It refuses a Meta that carries a consent: the cache holds the verdict and never the consent, which lives in installed.yaml, so a run cannot read one out of install.json.
func ReleaseDir ¶
ReleaseDir is one release's directory under AgentDir.
func ReleaseName ¶
ReleaseName is a release directory's name, <version>-<12 of the digest>: one spelling for every client, so a run finds what an install laid down.
func RemoveOtherVersions ¶
RemoveOtherVersions removes every entry of agentDir but keep — the replace rule of an update: one release per QuickAgent, the older one's directory gone once the new one is verified and recorded, while a staging or retired sibling another process is still using is left to it. Runs keep their receipts in the person's output folder, not here. keep must sit directly under agentDir, or nothing is removed: the caller's slip must not turn into a sweep of some other directory.
func Repair ¶
Repair is Install on the person's word that an installed release which changed after it was laid down is to be replaced (`agentry install --repair`): the release, fetched and verified again by the caller, is laid down in place of whatever is at releaseDir, whether or not it changed, and sealed afresh. style is the export to write beside it, or empty for none (a release a run laid down, which has none).
func Replace ¶
Replace is Write for a tree whose source is on this machine and is the truth (a --local directory, a built-in package): an installed copy that changed is replaced rather than refused, since there is no signed release for it to be faithful to, only the source it is copied from.
func StyleFor ¶
StyleFor is the export shape an install writes beside the release: the coding agent the policy names (claude before codex when both are), else the provider — Anthropic's keys drive Claude Code, the rest are OpenAI-compatible or generic — else AGENTS.md, the shape any coding agent reads.
func StyleForHome ¶
StyleForHome is StyleFor applied to the runner home's policy, with the one honest outcome for each case: no policy yet is the generic shape and nothing to say (an install must not create one, that is setup's and a run's); a policy that cannot be read is the generic shape too, and the warning says so, so an install goes on rather than stopping on a file it does not need. Both clients show the warning the same way.
func Write ¶
Write lands workspace/ and install.json under dir, sealed with the integrity record (integrity.go). A half-written install must not look installed, and two first installs of one release at once (a CLI run and a desktop run on a fresh runner home) must not share a half-built tree: the tree is built aside and published by rename (dirpublish). dir is named for the release's digest, so a whole install of that digest already there that its record vouches for, whoever laid it down, is the same release: it is kept, with any run's plan inside it, and this copy discarded. An install that changed after it was laid down is refused (*ChangedError), never replaced: that is Repair's, on the person's word. Anything else at dir, an install without a record included, is replaced. A local tree's .git and agentry-out are not part of the release and are skipped.
Types ¶
type ChangedError ¶
type ChangedError struct {
// Ref names the release. Inspect reads it from install.json, which is
// untrusted once the record has failed: a caller that resolved the
// release sets it from what it resolved. Dir is the release directory.
Ref, Dir string
// Changed, Added and Removed are sorted.
Changed, Added, Removed []string
// Record is set when the record or install.json itself failed.
Record RecordFailure
// Repair, when set, is the command that lays the release down again in
// place of `agentry install --repair <ref>`: a local install is laid down
// again from its folder, since no registry holds it.
Repair string
}
ChangedError reports an installed release whose files, or whose install.json, changed after it was laid down. Paths are relative to the release's own files (workspace/), in the form the archive carries them.
func (*ChangedError) Error ¶
func (e *ChangedError) Error() string
func (*ChangedError) RepairCommand ¶
func (e *ChangedError) RepairCommand() string
RepairCommand is the command that lays the release down again.
type Meta ¶
type Meta struct {
Ref string `json:"ref"`
Namespace string `json:"namespace"`
Name string `json:"name"`
Version string `json:"version"`
Digest string `json:"digest"`
Source string `json:"source"`
Attestation receipt.Attestation `json:"attestation"`
// Export is the coding-agent shape written under export/ by an
// install ("claude-skill" or "agents-md"); empty for a run's own
// fetch, which writes none.
Export string `json:"export,omitempty"`
}
Meta is <release dir>/install.json: what was verified, once, so repeat runs of the same digest skip the network without skipping the truth about how it was admitted. Export is the one field a run does not read.
func Inspect ¶
Inspect reads the release installed at dir and holds it to its integrity record before anything trusts it: the Meta and nil when the release with wantDigest is installed there and is what was laid down; ErrNotInstalled when it is not installed there; the Meta and ErrNoRecord when it is installed but carries no record this runner home's key made; *ChangedError when it changed after it was laid down. The record is checked before install.json is believed, so an edited install.json is reported as changed, not as another release.
func Load ¶
Load reuses a verified install iff its recorded digest matches what the registry (or the tree hash) says now, its workspace is there, and its integrity record vouches for the tree (Inspect). Anything else is not an install to reuse: a caller that lays the release down again meets a changed install as Write's refusal. A caller that must tell the cases apart (refuse a changed install before fetching anything) uses Inspect.
type RecordFailure ¶
type RecordFailure string
RecordFailure names what failed when the record or install.json itself is what changed, rather than a file of the release.
const ( // InstallJSONChanged: install.json is not the one laid down. InstallJSONChanged RecordFailure = "install-json-changed" // RecordInvalid: the record names this home's key and does not verify // under it, so it was edited; its file list is no evidence of anything. RecordInvalid RecordFailure = "record-invalid" )