Documentation
¶
Overview ¶
Package localrun holds what a run needs besides the registry: the plan's reuse or compile for any run, a release's or not (EnsurePlan); the manifest and the tree digest a local package is read and keyed by; and the built-in run — a package this binary embeds, run with the attestation state builtin, no registry resolve and no consent prompt for a contract the application declares itself. The CLI's commands, the desktop and the enterprise build share it.
Index ¶
- func CheckFolder(ctx context.Context, d dockerx.Client, pol *policy.Policy, home, dir string, ...) (clamav bool, err error)
- func CheckPersistentNames(p *manifest.Persistent) error
- func EnsurePlan(in PlanInputs) (*spec.Plan, string, error)
- func ImageAdapter(name string) string
- func InstallServer(ctx context.Context, d dockerx.Client, pol *policy.Policy, storeDir string, ...) error
- func InstallServers(ctx context.Context, d dockerx.Client, in PlanInputs, plan *spec.Plan, ...) (*spec.Plan, string, error)
- func LocalMeta(dir string) (*installdir.Meta, error)
- func ManifestFrom(dir string) (*manifest.Manifest, error)
- func MemorySeedOf(fsys fs.FS, ref string) (map[string][]byte, error)
- func PackWorkspace(dir string, m *manifest.Manifest, w io.Writer) (pkgarchive.ArchiveInfo, error)
- func PersistentImageServer(name string) (string, bool)
- func PersistentMailProvider(name string) (string, bool)
- func PlanVersionOf(b []byte) string
- func TreeDigest(dir string) (string, error)
- type Account
- type Builtin
- func (b Builtin) AppLink() string
- func (b Builtin) ArchiveDigest() (string, error)
- func (b Builtin) ArmsMeetings() bool
- func (b Builtin) ChecksShare() bool
- func (b Builtin) Codes() bool
- func (b Builtin) Declared() *manifest.Persistent
- func (b Builtin) ImageServers(images policy.Images) []offer.ImageServer
- func (b Builtin) KeepsMemory() bool
- func (b Builtin) KeepsSecrets() bool
- func (b Builtin) KeepsTime() bool
- func (b Builtin) LocalBudgets(p policy.Budgets) spec.Budgets
- func (b Builtin) MailProviders() []offer.MailProvider
- func (b Builtin) Materialize(home, build string) (*installdir.Meta, string, error)
- func (b Builtin) MemorySeed() (map[string][]byte, error)
- func (b Builtin) Name() string
- func (b Builtin) Namespace() string
- func (b Builtin) OfferedServers(hosts []offer.GitHost) []offer.Server
- func (b Builtin) Persistent() bool
- func (b Builtin) ReadsCalendars() bool
- func (b Builtin) Ref() string
- func (b Builtin) ResetsInParts() bool
- func (b Builtin) Runnable() bool
- func (b Builtin) Skills() []BuiltinSkill
- func (b Builtin) Stage(dir string) error
- func (b Builtin) SuggestedServers() []offer.Suggestion
- func (b Builtin) Version() string
- func (b Builtin) WithoutRender() Builtin
- func (b Builtin) WithoutWebTools() Builtin
- type BuiltinSkill
- type CalendarFeed
- type Grants
- type ImageGrant
- type Installed
- type PlanInputs
- type Run
- type Segment
- type SegmentPlan
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckFolder ¶
func CheckFolder(ctx context.Context, d dockerx.Client, pol *policy.Policy, home, dir string, logw io.Writer) (clamav bool, err error)
CheckFolder runs the decode step over the files of dir, a copy the caller made, as the share's check runs over a share file: with ClamAV when the policy's malwareCheck is on. A file ClamAV found refuses the folder, naming it and its signature. clamav says ClamAV checked every file and found nothing; false when the check is off, or when a file could not be checked (no signatures, past ClamAV's limits).
func CheckPersistentNames ¶ added in v0.6.1015
func CheckPersistentNames(p *manifest.Persistent) error
CheckPersistentNames refuses a capabilities.persistent block that names an image server or a mail provider this build does not carry: a release written for a newer Agentry is refused, never run without what it asks.
func EnsurePlan ¶
func EnsurePlan(in PlanInputs) (*spec.Plan, string, error)
EnsurePlan reuses the installed plan when nothing it depends on changed, otherwise recompiles. A reused plan.json is first checked against the integrity record its compile wrote under the runner home's key: a plan with no record this home can check is recompiled, and one that does not match its record — changed after it was compiled — refuses the run (exit 10).
func ImageAdapter ¶
ImageAdapter is the adapter a persistent agent runs on for the machine's adapter: the same harness in a container, for one that would run it on the host.
func InstallServer ¶
func InstallServer(ctx context.Context, d dockerx.Client, pol *policy.Policy, storeDir string, srv manifest.MCPServer, logw io.Writer) error
InstallServer installs one package server into a persistent agent's store outside any segment's start: resolved from the store when it already holds the pin, else from the policy's registries, then installed as a segment's start installs it (mcpinstall.EnsureInstalled), whose record carries the command the install found for the next segment's plan. The runner image must be built, as a segment's start leaves it; the caller holds the server's store lock.
func InstallServers ¶
func InstallServers(ctx context.Context, d dockerx.Client, in PlanInputs, plan *spec.Plan, planDir string, resolved []mcpinstall.Resolved, storeDir string, ) (*spec.Plan, string, error)
InstallServers installs the resolved package servers into storeDir and returns the plan to run, compiled from in. A PyPI server's console script is known only once its distribution is installed (the registry's metadata does not name it), so a plan compiled before a server's first install names the resolution's guess at its command. When the install changed what a server launches, the plan is compiled again from the servers as the store now holds them, which is also what the next run resolves from the store, so that run reuses the plan; otherwise plan and planDir themselves are returned, so a caller tells a recompile by the pointer. A failed install is classified as the gateway's (exit 13), a failed compile as EnsurePlan classifies it.
func LocalMeta ¶
func LocalMeta(dir string) (*installdir.Meta, error)
LocalMeta is the install record of a directory package run with --local: unsigned by definition, attestation state local. It is computed, never read from a cached install, so no record on disk can give a directory another state.
func ManifestFrom ¶
ManifestFrom parses agent.yaml at a package tree's root.
func MemorySeedOf ¶ added in v0.6.1017
MemorySeedOf is the memory seed in a package's tree: the files beneath its memory/ folder, by path beneath it; none when it has no such folder.
func PackWorkspace ¶
func PackWorkspace(dir string, m *manifest.Manifest, w io.Writer) (pkgarchive.ArchiveInfo, error)
PackWorkspace writes the deterministic archive of a package directory to w, filtered by the manifest's publish.include, and returns its identity. `agentry publish` uploads exactly this, and a built-in's ArchiveDigest is this over its embedded tree, so the two cannot pack differently.
func PersistentImageServer ¶ added in v0.6.1015
PersistentImageServer is the key of the image server this build runs for name, an entry of capabilities.persistent.imageServers; false for a name it does not carry.
func PersistentMailProvider ¶ added in v0.6.1015
PersistentMailProvider is the key of the mail provider this build reaches for name, an entry of capabilities.persistent.mail; false for a name it does not carry.
func PlanVersionOf ¶
PlanVersionOf reads just the planVersion of a stored plan.json, so a plan the current schema cannot parse still names the version it has.
func TreeDigest ¶
TreeDigest hashes a package directory deterministically (sorted relative paths, sizes and content, .git and agentry-out left out) so a local or a built-in package is cache-keyed and receipted like an archive, with "sha256:" kept for shape parity.
Types ¶
type Account ¶ added in v0.6.999
type Account struct {
spec.CoderAccount
Token string
}
Account is one of the Coding agent's git host accounts, as a segment is given it: the account (its TokenEnv is the segment's to set) and the token read from the keychain.
type Builtin ¶
type Builtin struct {
// contains filtered or unexported fields
}
Builtin is a package this binary embeds. Its fields are unexported, so a Builtin is only ever one of Builtins(): nothing else — a directory, a release, a record on disk — can run with the attestation state builtin, and nothing else can be granted the web tools, which ride on the Builtin value itself, as does the review grant.
func Assistant ¶
func Assistant() Builtin
Assistant is the Assistant (pkg/persistent/assistant), the first built-in that runs as a persistent agent. A file in its share is read only once ClamAV has checked it. Its manifest declares what else it has: the time and its tasks, a memory, skills, stored secrets, its own name and persona, Agentry's helper tools and the meeting tools. It resets in parts: its history alone, or everything but the credentials it was given. It reads the calendar feeds the person gives it.
func Coder ¶
func Coder() Builtin
Coder is the Coding agent (pkg/persistent/coder): its programs run in its own toolchain image, it may reach the internet, a browser and the person's dev server, each as its roster has them on, and it reads its share as it is: it builds and runs software. Its manifest declares skills and stored secrets, which reach its programs and the servers that declare them.
func Drafter ¶
func Drafter() Builtin
Drafter is the Drafter (pkg/drafter), the second built-in package, granted the web tools and registry_search, which is its alone.
func Examiner ¶
func Examiner() Builtin
Examiner is the Examiner (pkg/examiner), the fourth built-in package, and the one granted the review grant.
func KnowledgeCreator ¶
func KnowledgeCreator() Builtin
KnowledgeCreator is the Knowledge Creator (pkg/knowledge/creator), granted web_search and web_read, whose web_read renders a thin page: a build that does not search the web runs it WithoutWebTools.
func Main ¶
func Main() Builtin
Main is Agentry Helper (pkg/persistent/main), the persistent agent of Agentry Desktop's Home: a file in its share is read only once ClamAV has checked it, and its manifest declares Agentry's helper tools and skills.
func PersistentBuiltins ¶
func PersistentBuiltins() []Builtin
PersistentBuiltins are the built-ins that run as persistent agents.
func VoiceWriter ¶
func VoiceWriter() Builtin
VoiceWriter is the Voice Writer (pkg/voice/writer), the third built-in package, granted web_read alone, held to the addresses the person gave and rendering a thin page: a build given no address to read runs it WithoutWebTools.
func (Builtin) ArchiveDigest ¶
ArchiveDigest is the digest of the archive PackWorkspace makes of the embedded tree: the release identity the registry holds for this package, since the registry publishes every built-in from these bytes and its own build must equal the digest the upload claims. It is not the tree digest Materialize keys the runner home and the receipt by.
func (Builtin) ArmsMeetings ¶ added in v0.6.999
func (Builtin) ChecksShare ¶
ChecksShare says a file in the persistent built-in's share folder is read only once ClamAV has checked it; otherwise the share is read as it is.
func (Builtin) Codes ¶
Codes says the persistent built-in is given the Coding agent's grant (Grants.Coder).
func (Builtin) Declared ¶ added in v0.6.1017
func (b Builtin) Declared() *manifest.Persistent
Declared is what the built-in declares under capabilities.persistent in its own manifest, read once; nil for none, and for the zero Builtin. A built-in's manifest that does not parse fails the build's tests, never a start.
func (Builtin) ImageServers ¶ added in v0.6.999
func (b Builtin) ImageServers(images policy.Images) []offer.ImageServer
ImageServers are the servers the persistent agent comes with that run from an image the CLI pins (images, the policy's), each an entry of its roster; a built-in's alone.
func (Builtin) KeepsMemory ¶
func (Builtin) KeepsSecrets ¶
func (Builtin) KeepsTime ¶
KeepsTime, KeepsMemory, KeepsSecrets and ArmsMeetings say the built-in declares clock, memory, secrets and meetings; AppLink is the app link tool set its declared keys compose. A published agent's are its release's (persistent.Agent).
func (Builtin) LocalBudgets ¶
LocalBudgets are the budgets a run of the package on this computer starts from: the runner policy's, with a timeout no shorter than the package's own floor. This is the one place a run is given longer than the policy's run timeout without the person naming it: that timeout is sized for an agent answering a task, and a draft or a pack build outruns it. A caller lays whatever was named for this run over them. The floor is on the timeout alone: the tool-call and cost caps are the policy's, and no budget of a run on this computer counts tokens. It is exported so that the desktop can start a draft or a build from the same budgets.
func (Builtin) MailProviders ¶ added in v0.6.999
func (b Builtin) MailProviders() []offer.MailProvider
MailProviders are the services whose mail and calendar the persistent agent reaches through its image servers; a built-in's alone.
func (Builtin) Materialize ¶
Materialize lays the embedded tree down in the runner home's release directory, keyed by its digest, and returns the record of it with the attestation state builtin and the build that carries it. The record is made in memory on every call and never read back; an installed copy whose tree is not the embedded one is replaced.
func (Builtin) MemorySeed ¶
MemorySeed is what the persistent built-in's memory volume starts with: the files beneath its tree's memory/ folder, by path beneath it; none for a built-in that declares no memory.
func (Builtin) OfferedServers ¶ added in v0.6.999
OfferedServers are the MCP servers the persistent agent comes with, each an entry of its roster: its package's own (offer.Server), some drawn for the agent's git host accounts (hosts).
func (Builtin) Persistent ¶
Persistent says the built-in runs as a persistent agent: only a Segment starts it, and Execute refuses it.
func (Builtin) ReadsCalendars ¶ added in v0.6.999
ReadsCalendars says the persistent agent reads the calendar feeds the person gives it (Grants.CalendarFeeds).
func (Builtin) ResetsInParts ¶ added in v0.6.999
ResetsInParts says the persistent agent has Reset history and Reset agent beside its Reset.
func (Builtin) Runnable ¶
Runnable says a persistent built-in runs as an agent; one that is not is published for reading alone.
func (Builtin) Skills ¶
func (b Builtin) Skills() []BuiltinSkill
Skills are the persistent built-in's own skills, each folder beneath its tree's skills/, in name order; none for a built-in without one. A folder that is not a skill fails the build's tests, never a start.
func (Builtin) Stage ¶
Stage copies the embedded tree into dir, which must not hold any of its files: the workspace `agentry builtins publish` uploads.
func (Builtin) SuggestedServers ¶ added in v0.6.999
func (b Builtin) SuggestedServers() []offer.Suggestion
SuggestedServers are the MCP servers the persistent agent suggests: not on its roster until the person adds one as their own.
func (Builtin) WithoutRender ¶
WithoutRender is the same package whose web_read never renders a page: a build on a sandbox host, whose slots count no browser beside it. A grant can only be taken away here, never given.
func (Builtin) WithoutWebTools ¶
WithoutWebTools is the same package with no web tools: the Drafter's repair turn, which reads nothing from the web, and a knowledge build that does not search the web. A grant can only be taken away here, never given.
type BuiltinSkill ¶
BuiltinSkill is one of a persistent built-in's own skills: its meta and its folder in the built-in's tree.
func SkillsOf ¶ added in v0.6.1017
func SkillsOf(fsys fs.FS) []BuiltinSkill
SkillsOf are the skills in a package's tree: each folder beneath its skills/ that is a skill of its folder's name, in name order. A folder that is not one is left out.
type CalendarFeed ¶ added in v0.6.999
type CalendarFeed struct {
Name, Host, URL string
// Session is the feed's browser sign-in, or empty.
Session string
}
CalendarFeed is one of the Assistant's calendar feeds, as a segment is given it: its name and host, and the address read from the keychain, with its browser sign-in when it has one.
type Grants ¶
type Grants struct {
Share string
// Knowledge are the packs attached to the segment, opened by the
// caller.
Knowledge []engine.AttachedPack
// Servers are the MCP servers the person added and has on, in the
// manifest's shape.
Servers []manifest.MCPServer
// (manifest.MCPServer.SourceID), that the person let see the share
// folder: read only, through its mirror where the share is checked.
// Only with Share.
ShareServers []string
// ServersDir is the agent's own store a package server is installed
// into, as a release's declared server is into its profile's.
ServersDir string
// Skills are the skills the roster has on, by name and description,
// and SkillsDir the folder holding exactly them, filled by the caller;
// both empty for none.
Skills []spec.Skill
SkillsDir string
// AppLink is the socket the supervisor answers the agent's app link on;
// empty gives the segment no app link.
AppLink string
// Coder is what the Coding agent's roster has on of its grant; nil for
// any other agent, which is refused it.
Coder *spec.CoderGrant
// DevHost is the Coding agent's dev server, readied (its address, its
// pinned host key, its sign-in): set exactly when Coder.DevHost is.
DevHost *targethost.Host
// Secrets are the person's stored secrets the roster has on, by name:
// each is given to the servers that declare it and, for the Coding
// agent with its commands on, to its programs' environment.
// WithheldSecrets are those it has off: a server that declares one is
// given an empty value, never one from the policy's secret source.
Secrets map[string]string
WithheldSecrets []string
// ServerSecrets fill the secret slots of the offered servers that sign
// in with a git host account, by the slot's name: given to those
// servers alone, never to the Coding agent's programs.
ServerSecrets map[string]string
// Accounts are the Coding agent's git host accounts the roster has on,
// each with its token, given to its programs with its commands on.
Accounts []Account
// ImageServers are the built-in's image servers the roster has on and
// the person signed in, each with the switches it has on and its
// volume; their secret slots are among ServerSecrets.
ImageServers []ImageGrant
// CalendarFeeds are the Assistant's calendar feeds the roster has on,
// each with its address, given to its tools server alone; CalendarZone
// is the person's IANA zone, in which the calendar tools answer.
CalendarFeeds []CalendarFeed
CalendarZone string
// Voice is the person's Writing Voice, when the roster has it on: read
// through voice_read as a run's is (engine.Params.Voice). The engine
// refuses it to a built-in.
Voice *engine.AttachedVoice
}
Grants are what a persistent agent's roster turns on for one segment, beside what its built-in declares: the person's share folder, the knowledge packs it searches, and the MCP servers the person added. The persistent package's Apply is the one function that makes them.
type ImageGrant ¶ added in v0.6.999
type ImageGrant struct {
Key string
Switches []string
Volume string
// Account is the signed-in account, given to the server in its
// AccountEnv.
Account string
// Env is what the server is told of its sign-in (its client and
// tenant), beside its plain env; Args are added after its command (the
// person's signoff). Neither holds a secret.
Env map[string]string
Args []string
// AgentryApp says the server was signed in with Agentry's own app,
// which is given only to the build's own image of the server.
AgentryApp bool
}
ImageGrant is one image server a segment is given: the built-in's server by its key (Builtin.ImageServers), the keys of its switches that are on, and the agent's volume it keeps its state on.
type Installed ¶ added in v0.6.1015
type Installed struct {
Meta *installdir.Meta
Dir string
}
Installed is a persistent release installed in the runner home, from the registry or from an author's folder: the record it was laid down with and its release folder. A segment runs it under the attestation its install recorded and its integrity record vouches for, never as built in, and with none of a built-in's grants.
type PlanInputs ¶
type PlanInputs struct {
Home string
Manifest *manifest.Manifest
Meta *installdir.Meta
InstallDir string
WorkspaceDir string
Policy *policy.Policy
PolicySHA string
Adapter string
Servers []spec.MCPServerSpec
Mode manifest.Mode
// CompiledBy is the build identity of the client compiling: a plan
// another build compiled is recompiled.
CompiledBy string
// Web grants the web tools (compile.Inputs.Web), and RegistrySearch
// registry_search with them: set from a Builtin that carries them,
// never from anything a caller passes in.
Web, RegistrySearch bool
// WebSearchedOnly holds web_read to the run's search results
// (compile.Inputs.WebSearchedOnly), likewise.
WebSearchedOnly bool
// WebGivenOnly holds web_read to the addresses the person gave
// (compile.Inputs.WebGivenOnly), likewise.
WebGivenOnly bool
// WebRender lets web_read render a thin page (compile.Inputs.WebRender).
WebRender bool
// Review grants the review grant (compile.Inputs.Review), likewise.
Review bool
// AgentFiles grants a persistent built-in its folders
// (compile.Inputs.AgentFiles), and AppLink its app link
// (compile.Inputs.AppLink): set by a Segment alone.
AgentFiles *spec.AgentFiles
AppLink string
// Coder grants the Coding agent what its roster has on
// (compile.Inputs.Coder): set by a Segment of the Coding agent alone.
Coder *spec.CoderGrant
// Calendar grants the Assistant its calendar feeds
// (compile.Inputs.Calendar): set by a Segment of the Assistant alone.
Calendar *spec.CalendarGrant
// ShareServers are the declared servers, by source id, that see the
// agent's share folder (compile.Inputs.ShareServers): set by a Segment
// alone.
Log io.Writer
}
PlanInputs are what EnsurePlan compiles from.
type Run ¶
type Run struct {
Builtin Builtin
Home string
Policy *policy.Policy
PolicySHA string
PolicyFile *policy.File
// Build is the client's build identity, recorded in the receipt's
// attestation and the plan.
Build string
Task io.Reader
// Inputs are paths staged read-only under /inputs.
Inputs []string
Knowledge []engine.AttachedPack
// Decoded is the decode step the caller ran on the inputs, for the
// receipt.
Decoded *decode.Result
// Enforced are receipt lines the caller adds beside the decode's: a
// knowledge build's sources.
Enforced map[string]string
OutDir string
// Budgets, when set, replace the plan's.
Budgets *spec.Budgets
// Adapter names the harness adapter; empty takes the default.
Adapter string
RunID string
KeepRunDir bool
Stderr io.Writer
OnUsage func(receipt.Usage)
// Web is the web tools' configuration and keys, for a Builtin granted
// them (the Drafter); the engine refuses to run one without it.
Web *engine.WebRun
// Review is the person's own TypeSafe key, for a Builtin granted the
// review grant; Execute refuses to start one without it.
Review *engine.ReviewRun
// Hosted is a sandbox host's run (a hosted draft, build or review): it
// never spends a model sign-in, and a plan that names one is
// refused.
Hosted bool
// HostedRender lets a hosted run render pages: its host dispatched it
// as a browser job (engine.Params.HostedRender).
HostedRender bool
// Credits is the credits-session client of the registry this computer
// is signed in to, for a policy that pays with Agentry credits (model
// provider agentry): the run opens its session with it. Nil refuses
// such a run as signed out.
Credits *inference.Client
}
Run is one run of a built-in package.
func RepairRun ¶
func RepairRun(first Run, t drafter.RepairTurn) Run
RepairRun is the Drafter's one repair turn after first (drafter.PostStep): the same package without its web tools and with no web configuration, so it holds no key and reads nothing from the web, given the turn's task, folder, budgets, run id and usage reporter. It pays for its model as the first run does: the same credits client, for a policy that pays with Agentry credits. It is given none of the person's packs; the pack the Drafter ships reaches it as it reaches every run of the package (withShippedPacks). Both clients run the turn this way.
type Segment ¶
type Segment struct {
Builtin Builtin
// Release is the installed release the segment runs in place of a
// built-in; nil for a built-in. Builtin is then the zero value, which
// carries none of a built-in's grants.
Release *Installed
Home string
Policy *policy.Policy
PolicySHA string
PolicyFile *policy.File
// Build is the client's build identity, recorded in the receipt's
// attestation and the plan.
Build string
// OutDir is the segment's folder (its receipts and envelope), absolute.
OutDir string
RunID string
Stderr io.Writer
// OnStage, when set, is called as the start reaches each of its steps
// (engine.Stage), here and in the engine; nil does nothing.
OnStage func(engine.Stage)
// Persistent is the agent's part of the engine's parameters: its name,
// the segment's number, its volumes and the conversation to continue.
Persistent engine.PersistentSegment
// Grants are what the agent's roster turns on (Apply).
Grants Grants
// Inference is the agent's Agentry credits session, when its policy
// pays with credits (model provider agentry): the supervisor opens it
// once for the agent's life and renews and ends it itself, so the
// grant carries no Renew or End.
Inference *engine.InferenceGrant
}
Segment is one start of a persistent agent: the session a persistent agent's supervisor owns until it stops it. It runs either a persistent built-in (Builtin) or an installed release (Release), never both.
func (Segment) Plan ¶
Plan materializes the built-in and compiles the segment's plan from it and the roster's grants: the servers the person has on are declared beside the built-in's own, and its folders are mounted, the share when it is on. It touches no container engine; a package server is resolved from the agent's store, or from the registries when the store does not hold its pin.
func (Segment) Start ¶
Start starts the segment: materialize, validate, plan the persistent mode, ensure the images, start the session. A persistent agent always runs its harness in a container: a host adapter is replaced by its image counterpart, and a plan that would run the harness on the host is refused. It has no session caps and no tool-call or cost budget: the person stops it.
type SegmentPlan ¶
type SegmentPlan struct {
Plan *spec.Plan
// Dir is the plan's folder: its gateway and harness files.
Dir string
// contains filtered or unexported fields
}
SegmentPlan is a segment's compiled plan and what starting it needs.