installdir

package
v0.7.11-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 20 Imported by: 0

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

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

View Source
const RecordFile = "integrity.json"

RecordFile is the integrity record's name beside install.json.

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

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

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

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

func AgentDir(home, namespace, name string) string

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

func AgentsRoot(home string) string

AgentsRoot is the directory every agent's directory sits directly under.

func CheckCopy

func CheckCopy(releaseDir, copyDir string) error

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

func ConsentKey(home, namespace, name string) installed.Key

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

func DigestSuffix(digest string) string

DigestSuffix shortens sha256:… for directory names.

func HomeOf

func HomeOf(releaseDir string) (string, error)

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

func Install(releaseDir, srcTree string, m *manifest.Manifest, meta *Meta, style string) error

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

func ReleaseDir(home, namespace, name, version, digest string) string

ReleaseDir is one release's directory under AgentDir.

func ReleaseName

func ReleaseName(version, digest string) string

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

func RemoveOtherVersions(agentDir, keep string) error

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

func Repair(releaseDir, srcTree string, m *manifest.Manifest, meta *Meta, style string) error

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

func Replace(dir, srcTree string, meta *Meta) error

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

func StyleFor(pol *policy.Policy) string

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

func StyleForHome(home string) (style, warning string)

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

func Write(dir, srcTree string, meta *Meta) error

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

func Inspect(dir, wantDigest string) (*Meta, error)

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

func Load(dir, wantDigest string) (*Meta, bool)

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

Jump to

Keyboard shortcuts

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