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 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 PackWorkspace(dir string, m *manifest.Manifest, w io.Writer) (pkgarchive.ArchiveInfo, error)
- func PlanVersionOf(b []byte) string
- func TreeDigest(dir string) (string, error)
- type Builtin
- func (b Builtin) AppLink() string
- func (b Builtin) ArchiveDigest() (string, error)
- func (b Builtin) ChecksShare() bool
- func (b Builtin) Codes() bool
- 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) 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) Persistent() bool
- func (b Builtin) Ref() string
- func (b Builtin) Runnable() bool
- func (b Builtin) Skills() []BuiltinSkill
- func (b Builtin) Stage(dir string) error
- func (b Builtin) Version() string
- func (b Builtin) WithoutRender() Builtin
- func (b Builtin) WithoutWebTools() Builtin
- type BuiltinSkill
- type Grants
- 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 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 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 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 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 app link is its own name, personality and tasks, and it keeps time: each turn tells it the time, and its heartbeat fires its tasks. It keeps a memory of its own, and the secrets the person stores for it, which reach the servers that declare them.
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. The secrets the person stores for it 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: its app link is the application's own operations, and a file in its share is read only once ClamAV has checked it.
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) 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) KeepsMemory ¶
KeepsMemory says the persistent agent has a memory volume of its own, mounted read-write at spec.AgentRoot/spec.AgentMemoryDir.
func (Builtin) KeepsSecrets ¶
KeepsSecrets says the persistent agent keeps secrets the person stores for it (Grants.Secrets).
func (Builtin) KeepsTime ¶
KeepsTime says the persistent agent is told the time at each turn and keeps a heartbeat that fires the tasks it registers.
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) 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 keeps no memory.
func (Builtin) Persistent ¶
Persistent says the built-in runs as a persistent agent: only a Segment starts it, and Execute refuses it.
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) 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.
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
}
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 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
// 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
}
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 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
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
}
Segment is one start of a persistent built-in: the session a persistent agent's supervisor owns until it stops it.
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.