spec

package
v0.7.48 Latest Latest
Warning

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

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

Documentation

Overview

Package spec defines the run plan — the deterministic artifact the capability compiler produces at install time and the engine executes. A plan is pure data: no secret values, no machine-specific paths (run-scoped locations appear as placeholders), no timestamps. Same package digest + same policy ⇒ byte-identical plan.json, which is what makes the plan hash in every receipt meaningful.

Index

Constants

View Source
const (
	GitHubHost = "github.com"
	GitLabHost = "gitlab.com"
)

GitHubHost and GitLabHost are the hosted services' hosts; another host of their kind is an Enterprise Server or a self-managed instance.

View Source
const (
	// PHWorkspace is the host path of the per-run writable workspace copy.
	PHWorkspace = "@@RUN_WORKSPACE@@"
	// PHOut is the host path of the run's output folder.
	PHOut = "@@RUN_OUT@@"
	// PHCfg is the host path of the per-run rendered gateway config dir.
	PHCfg = "@@RUN_CFG@@"
	// PHSecrets is the host path of the per-run secrets env file.
	PHSecrets = "@@RUN_SECRETS@@"
	// PHRunID is the run identifier (container names, labels).
	PHRunID = "@@RUN_ID@@"
	// PHSecretsAbsent is the list of optional secrets this run was not
	// given, by name ("none" when it was given them all), for the System
	// Prompt: only the run knows which it holds, and the plan stays
	// the same bytes whichever they are. Unlike the others it stands for
	// text, never a path, an id or an address.
	PHSecretsAbsent = "@@RUN_SECRETS_ABSENT@@"
	// PHRunMode is the run's mode, "autonomous" or "interactive", for the
	// System Prompt: a release's two plans carry one instruction, so the text
	// guides both modes and only the run says which one it is. Text, like
	// PHSecretsAbsent.
	PHRunMode = "@@RUN_MODE@@"
	// PHInputs is the host path of the per-run read-only inputs dir —
	// operator-provided files, mounted :ro into the tools container, empty when
	// the run got no --file.
	PHInputs = "@@RUN_INPUTS@@"
	// PHInputsText is the host path of the per-run read-only decoded inputs
	// dir: the decode step's index and texts, mounted :ro into the tools
	// container, empty when the run's inputs were not decoded. Always compiled
	// in, like the inputs.
	PHInputsText = "@@RUN_INPUTS_TEXT@@"
	// PHKnowledge is the host path of the per-run read-only knowledge dir: one
	// subdirectory per attached pack, mounted :ro into the tools container,
	// empty when the run got no --knowledge. Always compiled in, so attaching a
	// pack never moves the plan.
	PHKnowledge = "@@RUN_KNOWLEDGE@@"
	// PHServers is the host path of the signature's installed MCP-server store:
	// profile/servers/, one subdirectory per declared server, mounted :ro into
	// that server's runtime container.
	PHServers = "@@RUN_SERVERS@@"
	// PHSession is the per-run named volume a harness's session store lives
	// in: an interactive session's, or an autonomous plan's whose harness
	// can be resumed (HarnessSpec.Resume).
	PHSession = "@@RUN_SESSION@@"
	// PHConversation is the id of the conversation a resumable autonomous
	// harness keeps in its session store: a new one for each fresh start, the
	// same one for a start that resumes it.
	PHConversation = "@@RUN_CONVERSATION@@"
	// PHShare is the host path of a persistent agent's share folder, the
	// person's own, mounted read-write and live at AgentRoot/AgentShareDir;
	// only a persistent plan whose agent has its share names it.
	PHShare = "@@RUN_SHARE@@"
	// PHShareMirror is the host path of a persistent agent's share mirror:
	// a folder of the agent's own holding a copy of each share file whose
	// bytes the share check passed, mounted read-only at
	// AgentRoot/AgentShareDir into each MCP server the person let see the
	// share (MCPServerSpec.Share); only such a plan names it.
	PHShareMirror = "@@RUN_SHARE_MIRROR@@"
	// PHShareOut is the host path of a segment's share outbox: a folder of
	// the segment's own, beside its cfg, mounted writable at
	// AgentRoot/AgentShareOutDir into each MCP server that sees the share
	// (MCPServerSpec.Share), whose regular files the runner copies into the
	// share after each turn under new names, never over a file; only such
	// a plan names it.
	PHShareOut = "@@RUN_SHARE_OUT@@"
	// PHSkills is the host path of the run's skills, mounted read-only into
	// the tools server alone: for a persistent agent, a folder the
	// supervisor fills with the skills its roster has on, at
	// AgentRoot/AgentSkillsDir; for a release that ships skills, its own
	// verified skills/ folder, at SkillsMount. Only a plan with a skill
	// names it.
	PHSkills = "@@RUN_SKILLS@@"
	// PHDependencyDB is the host path of OSV's databases the Coding agent's
	// dependency scan reads, kept under the runner home and mounted
	// read-only at DependencyDBMount into the tools server alone; only a
	// plan whose Coding agent has its dependency scan on names it.
	PHDependencyDB = "@@RUN_DEPENDENCY_DB@@"
	// PHData is a persistent agent's data volume, by name, mounted at
	// AgentRoot/AgentDataDir; only a persistent plan names it.
	PHData = "@@RUN_DATA@@"
	// PHMemory is a persistent agent's memory volume, by name, mounted at
	// AgentRoot/AgentMemoryDir; only a persistent plan whose agent keeps a
	// memory names it.
	PHMemory = "@@RUN_MEMORY@@"
	// PHAppLink is the host path of the socket a persistent agent's
	// supervisor answers its app link on, bound into the app link's
	// container alone; only a plan with an app link names it.
	PHAppLink = "@@RUN_APPLINK@@"
	// PHAppLinkMount is the app link container's one mount, source and
	// target: the supervisor's socket at the socket's path where the
	// engine's daemon runs on this computer, and the run's relay volume at
	// the socket's folder where it runs in a VM, chosen at run time so the
	// plan does not depend on the engine.
	PHAppLinkMount = "@@RUN_APPLINK_MOUNT@@"
	// PHAppLinkUser is the user the app link runs as: the invoking uid:gid,
	// whose socket it connects to, as the host link runs.
	PHAppLinkUser = "@@RUN_APPLINK_USER@@"
	// PHHostGatewayURL / PHHostProxyURL are the published 127.0.0.1 addresses a
	// host-run harness reaches the gateway and the proxy at; known only once
	// the run's containers are up, so they are rendered into harness files and
	// argv per run.
	PHHostGatewayURL = "@@HOST_GATEWAY_URL@@"
	PHHostProxyURL   = "@@HOST_PROXY_URL@@"
	// PHModelSignIn is the host path of what a model sign-in hands the agent
	// container: the run's own folder holding the one token file the engine
	// writes and rewrites before it expires (ModelSignInToken), or the Claude
	// Code config directory the person's sign-in lives in
	// (ModelSignInConfigDir).
	PHModelSignIn = "@@RUN_MODEL_SIGNIN@@"
	// PHHostLinkUser is the user the host link runs as:
	// the invoking uid:gid, as the files image runs, or "" where the
	// machine has none (Windows), which leaves the image's own. The host
	// link's passwd file names it (ssh refuses a uid it has no entry for),
	// and its credential files stay the person's own, 0600.
	PHHostLinkUser = "@@RUN_HOSTLINK_USER@@"
	// PHBrowserUser is the user the browser server runs as:
	// the invoking uid:gid, as the host link runs, so its output folder and
	// its secrets file stay the person's own, 0700 and 0600; the image's
	// own user where the machine has none (Windows).
	PHBrowserUser = "@@RUN_BROWSER_USER@@"
	// PHDesktopUser is the user each desktop link entry runs as: the
	// invoking uid:gid, as the app link runs, whose relay socket it
	// connects to; "" where the machine has none (Windows).
	PHDesktopUser = "@@RUN_DESKTOP_USER@@"
	// PHDesktopMount is a desktop link entry's one mount, source and
	// target: the run's relay volume at the socket's folder, made at run
	// time, so the plan carries the placeholder and a release without the
	// line compiles as before.
	PHDesktopMount = "@@RUN_DESKTOP_MOUNT@@"
	// PHBrowseProxy is the browse proxy's run-unique container name:
	// the browser server's one allowHosts entry and its
	// --proxy-server, known only to the run.
	PHBrowseProxy = "@@RUN_BROWSE_PROXY@@"
	// PHReviewHost is the review grant's one host, host:port: TypeSafe's
	// API, or the registry when the run asks AI Review through an operation
	// paid with credits, which only the run knows.
	PHReviewHost = "@@RUN_REVIEW_HOST@@"
)

Run-scoped placeholders. Plans and the generated gateway files must not bake in per-run host paths or secrets, or they would stop being deterministic and start being sensitive; the engine substitutes these at execute time. The @@…@@ shape is chosen not to collide with the gateway's own {{server.key}} templating or docker-agent's ${env.VAR}.

View Source
const (
	// ModelSignInToken: a short-lived access token in one file, in a
	// folder of the run's own mounted read-only at ModelSignInMount, so a
	// token rewritten by a rename is seen (a single-file bind would keep
	// the old inode). No refresh token ever enters the run.
	ModelSignInToken = "token-file"
	// ModelSignInConfigDir: the harness's own config directory, which only
	// the harness writes (Claude Code), mounted read-write. The
	// one exception to "no refresh token in a run".
	ModelSignInConfigDir = "config-dir"
	// ModelSignInCallback: the harness asks the session's driver for a token
	// over its own protocol, at the session's start and before the token
	// expires (Copilot CLI's token callback). Nothing is mounted and nothing is
	// in the environment: the access token passes the harness's stdio alone,
	// and no refresh token enters the run.
	ModelSignInCallback = "session-callback"
	// ModelSignInMount is the container folder a token file is in, and
	// ModelSignInTokenFile its name there.
	ModelSignInMount     = "/run/agentry/model-signin"
	ModelSignInTokenFile = "token"
)

The two ways a model sign-in reaches the agent container (ModelSignInSpec.Delivery).

View Source
const (
	ConnectionsDir  = "connections"
	ConnectionMount = "/run/agentry/connection"
	BearerFile      = "bearer"
)

A remote server's credential reaches its bridge as a file: the engine writes it into ConnectionsDir/<server name>/BearerFile under the run's cfg directory, and the compiler mounts that folder, a folder and never the file alone so a value rewritten mid-run is seen, read-only at ConnectionMount. The gateway never holds it: it is not in the gateway's secrets file. A package server's OAuth sign-in uses the same folder at the same mount, holding the files its oauth block declares instead of BearerFile, mounted writable.

View Source
const (
	// WorkspaceMount is where tools see the workspace.
	WorkspaceMount = "/workspace"
	// OutMount is where tools see the output folder.
	OutMount = "/out"
	// InputsMount is where tools see the run-inputs channel.
	InputsMount = "/inputs"
	// InputsTextMount is where tools see the decoded inputs.
	InputsTextMount = "/inputs-text"
	// KnowledgeMount is where tools see the attached knowledge packs, each
	// at KnowledgeMount/<name>.
	KnowledgeMount = "/knowledge"
	// ScratchMount is the run's scratch folder in the tools container: empty at
	// the start, a tmpfs of ToolsTmpfsBytes, gone with the container.
	ScratchMount = "/scratch"
	// SkillsMount is where the skills a release ships (its manifest's
	// capabilities.skills) are in the tools container, read-only: one
	// folder a skill, each with its SKILL.md, read with skill_read.
	SkillsMount = "/skills"
	// ChecklistFile is the file the checklist tool keeps a run's steps in,
	// in the scratch folder (a persistent agent's in its data folder, since
	// its scratch folder lasts one segment).
	ChecklistFile = "checklist.md"
	// ChecklistForHarness is the checklist file as a harness's summary of
	// earlier work names it to the agent (docker-agent's compaction_notes),
	// and AgentChecklistForHarness is a persistent agent's. One line each,
	// with no quote or backslash: the harness config takes it as a plain
	// string, and the harness ends its summary with it.
	ChecklistForHarness      = ChecklistFile + " in your scratch folder, which the checklist tool reads"
	AgentChecklistForHarness = ChecklistFile + " in your data folder, which the checklist tool reads"
	// ToolsTmpMount is the tools container's /tmp, a tmpfs of the same
	// size: the place a declared command may write.
	ToolsTmpMount = "/tmp"
	// AgentRoot is where a persistent agent's tools see its folders,
	// AgentShareDir, AgentDataDir and AgentMemoryDir beneath it: the filesystem tools,
	// grep and glob are rooted here in place of the workspace, which a
	// persistent agent does not have, so one root holds every path they
	// take.
	AgentRoot = "/agent"
	// AgentShareDir is the person's share folder beneath AgentRoot,
	// read-write and live: what either side writes, the other sees.
	AgentShareDir = "share"
	// AgentShareOutDir is where an MCP server that sees the share saves a
	// file for it, beneath AgentRoot: the share outbox (PHShareOut), which
	// only those servers mount. The agent's own tools do not see it.
	AgentShareOutDir = "share-out"
	// AgentShareOutPath is the share outbox's path in a server's container.
	AgentShareOutPath = AgentRoot + "/" + AgentShareOutDir
	// ShareChecksLog is the receipt a persistent agent's segment appends a
	// line to for each file of the share it checks, and for each entry of
	// the share outbox it copies or refuses.
	ShareChecksLog = "share-checks.ndjson"
	// ShareOutMaxFiles, ShareOutFileMax and ShareOutTotalMax bound what the
	// runner copies from the share outbox into the share after one turn:
	// the files, the bytes of each, and the bytes of all of them. What is
	// past them is not copied, and the outbox is emptied all the same.
	ShareOutMaxFiles = 100
	ShareOutFileMax  = 64 << 20
	ShareOutTotalMax = 256 << 20
	// AgentDataDir is the agent's own folder beneath AgentRoot, its data
	// volume, kept between its segments.
	AgentDataDir = "data"
	// AgentSkillsDir is where the agent's skills are beneath AgentRoot,
	// read-only: one Agent Skills folder (a SKILL.md and what it uses) each.
	AgentSkillsDir = "skills"
	// AgentMemoryDir is the agent's memory beneath AgentRoot, a volume of
	// its own kept between its segments: a wiki the agent writes, with the
	// share as its sources.
	AgentMemoryDir = "memory"
	// DependencyDBMount is where the Coding agent's tools server sees
	// OSV's databases (PHDependencyDB), read-only.
	DependencyDBMount = "/run/agentry/osv-db"
	// ShareChecksMount is the folder a persistent agent's tools server
	// reads the share's malware verdicts from, read-only, rewritten by the
	// runner before each turn (ShareChecksFile).
	ShareChecksMount = "/run/agentry/share-checks"
	// ShareChecksFile is the verdicts' file name in that folder.
	ShareChecksFile = "verdicts.json"
	// PlanMount is where the agent container sees its harness files.
	PlanMount = "/plan"
	// TurnsMount is the folder the tools server reads the run's turn count
	// from (TurnsFile). The runner rewrites it at each turn's start and each
	// compaction, and the re-read stub stands only for a read answered
	// earlier in the same turn.
	TurnsMount = "/run/agentry/turns"
	// TurnsFile is the turn count's file name in that folder.
	TurnsFile = "turn"
	// ToolSpecMount is where the tools container sees its spec file.
	ToolSpecMount = "/etc/agentry/toolspec.json"
	// GatewayAlias and GatewayPort locate the MCP gateway on the run
	// network; ProxyAlias/ProxyPort locate the LLM egress proxy.
	GatewayAlias = "gateway"
	GatewayPort  = 8811
	ProxyAlias   = "llm-proxy"
	ProxyPort    = 3128
	// ToolServerName is the gateway catalog name of the companion server.
	ToolServerName = "agentry-tools"
	// GatewayTokenEnv is the env var carrying the per-run Bearer token in
	// the agent container; GatewayAuthTokenEnv is what the gateway itself
	// reads.
	GatewayTokenEnv     = "MCP_GATEWAY_TOKEN"
	GatewayAuthTokenEnv = "MCP_GATEWAY_AUTH_TOKEN"
	// HostGatewayURLEnv / HostProxyURLEnv carry the same published
	// addresses to a host-run harness as environment variables.
	HostGatewayURLEnv = "AGENTRY_GATEWAY_URL"
	HostProxyURLEnv   = "AGENTRY_PROXY_URL"
)

Fixed container-side paths and network names shared by the compiler, the adapters, and the tools server configuration.

View Source
const (
	PersonServersAllowed = "allowed"
	PersonServersUnsafe  = "unsafe"
	PersonServersRefused = "refused"
)

What lets a run bind an application the person set up themself (DesktopCap.PersonServers).

View Source
const (
	ComputerUseApp    = "app"
	ComputerUseScreen = "screen"
)

The computer-use scopes (DesktopCap.ComputerUse): the bound applications' windows, or the whole display.

View Source
const (
	ScreenByPolicy = "policy"
	ScreenByFlag   = "flag"
	ScreenByUnsafe = "unsafe"
)

What allowed a screen scope (DesktopCap.ScreenAllowedBy).

View Source
const (
	RenderDir   = "render"
	RenderMount = "/render"
)

The page renderer's hand-off folder: under the run's cfg on the host, bound read-write into the tools server alone at RenderMount, where web_read leaves a request and the engine its answer.

View Source
const (
	// BrowserOutDir is the browser server's output folder, bound
	// read-write into it alone and read-only into the tools server at
	// BrowserOutMount; the engine copies it into reports/browser/ when the
	// run ends. It is a folder of its own, not reports/browser/ itself:
	// the tools server writes reports/, and the docker filter binds no
	// folder inside one a container writes.
	BrowserOutDir = "browserout"
	// BrowserDir holds the server's config and, for a line that declares
	// browser secrets, the --secrets file (0600), bound read-only into the
	// browser server alone.
	BrowserDir = "browser"
	// BrowserSecretsFile is that file's name in BrowserDir.
	BrowserSecretsFile = "secrets.env"
	// BrowserReports is where the browser's files reach the person, under
	// the run's output folder: reports/browser/.
	BrowserReports = "reports/browser"
)

The run folders the browser server reads and writes, under the run's cfg.

View Source
const (
	// HostsDir holds one folder per target host (credential, known_hosts,
	// target.json) and the passwd file, bound read-only into the host
	// link alone.
	HostsDir = "hosts"
	// HostLogDir holds each target host's call log, which the engine
	// copies into the receipts.
	HostLogDir = "hostlog"
	// HostFilesDir is the folder host_put and host_get copy through,
	// shared with the tools server at /scratch/hosts.
	HostFilesDir = "hostfiles"
)

The run folders the host link reads and writes, under the run's cfg.

View Source
const BrowserOutMount = OutMount + "/" + BrowserReports

BrowserOutMount is where the tools server reads the browser's files: inside its output folder, where reports/browser/ is, so a report can name them and export_pdf can draw them.

View Source
const ChosenForPerson = "an application you choose"

ChosenForPerson is the entry of an application the person chooses, in the words of a message to that person.

View Source
const CoderHome = AgentRoot + "/" + AgentDataDir + "/.home"

CoderHome is HOME for the programs the Coding agent runs: a hidden folder of its data volume, so their caches and settings last between segments.

View Source
const ContextWindowSource = "policy"

ContextWindowSource is ContextWindowSpec.Source for a window the policy file records.

View Source
const DesktopChosenID = "chosen"

DesktopChosenID is the id of the entry of an application the person chooses when the run starts: its entry is agentry-desktop-chosen. No application id may take it.

View Source
const DesktopComputerID = "computer"

DesktopComputerID is the computer-use entry's id in the desktop link: its entry is agentry-desktop-computer.

View Source
const DevHostID = "dev"

DevHostID is the target host id the Coding agent's dev server is readied and reached as.

View Source
const ExecNotInstalledPrefix = "not installed: "

ExecNotInstalledPrefix marks an entry of an exec image build's result that did not install (an Unsafe Mode build goes on without it), so the receipt names it apart from what did.

View Source
const MCPStorePrefix = "/opt/agentry-mcp"

MCPStorePrefix is the fixed in-container prefix a declared server's dependency closure is installed under AND mounted at — the same path in the builder and the runtime container, so interpreter paths (venv shebangs, .bin shims) stay valid.

View Source
const MaxCalendarFeedName = 64

MaxCalendarFeedName bounds a feed's name, in bytes.

View Source
const MaxCalendarFeedURL = 4096

MaxCalendarFeedURL bounds a feed's address, in bytes.

View Source
const MaxCalendarFeeds = 20

MaxCalendarFeeds bounds the Assistant's calendar feeds.

View Source
const MaxCoderAccounts = 8

MaxCoderAccounts bounds the Coding agent's git host accounts.

View Source
const OAuthTokenPlaceholder = "{access_token}"

OAuthTokenPlaceholder is the placeholder an oauth template or env value names the access token with (the manifest's grammar).

View Source
const PlanVersion = "2"

PlanVersion is the current plan schema major. The engine refuses plans with a different version (recompile instead of guessing). PlanVersion changes whenever plan.json's shape changes; installed plans with another version are recompiled. "2": run modes (Modes/Mode replace the v1 kind) and the interactive Session block.

View Source
const SessionMount = "/session"

SessionMount is the container path of the interactive session store.

View Source
const SourceImage = "image"

SourceImage is an image server's Source: a built-in's server run from an image the CLI pins, its Package and Image the image, no version and no store; its Volumes are named volumes of the agent's that reach it alone.

View Source
const SourceURL = "url"

SourceURL is a remote server's Source: no package, no version, no image and no store; the compiler runs the runner image's bridge for it.

View Source
const ToolsTmpfsBytes = 256 << 20

ToolsTmpfsBytes bounds each of the tools container's two tmpfs mounts, /tmp and the scratch folder. Each counts against the container's memory limit, and a write past it fails with ENOSPC.

Variables

This section is empty.

Functions

func AccountTokenEnv added in v0.6.999

func AccountTokenEnv(i int) string

AccountTokenEnv is the tools server's variable for the i-th account's token (from 0). Its prefix is one a stored secret may not take, so no secret the person stores can take its place.

func CalendarFeedAddress added in v0.6.999

func CalendarFeedAddress(raw string) (string, string, error)

CalendarFeedAddress reads the address the person gives: https, or webcal (which calendar apps use for the same https address), with a host name and no user name, password or port but 443. It returns the address as fetched (webcal rewritten to https) and its host in lower case. An error never repeats the address, which is a secret.

func CalendarFeedEnv added in v0.6.999

func CalendarFeedEnv(i int) string

CalendarFeedEnv is the tools server's variable for the i-th feed's address (from 0). Its prefix is one a stored secret may not take.

func CalendarSessionEnv added in v0.6.999

func CalendarSessionEnv(i int) string

CalendarSessionEnv is the tools server's variable for the i-th feed's browser sign-in (from 0).

func CheckCalendarFeedName added in v0.6.999

func CheckCalendarFeedName(name string) error

CheckCalendarFeedName holds a feed's name to printable text the person can tell apart: 1 to 64 bytes, no control or formatting character, no line break, and none of the characters a roster id or a list would read as its own.

func CheckCalendarGrant added in v0.6.999

func CheckCalendarGrant(g *CalendarGrant) error

CheckCalendarGrant holds a grant to well-formed feeds: names, hosts and variables of the feeds' form, none twice.

func CheckCoderAccounts added in v0.6.999

func CheckCoderAccounts(accounts []CoderAccount) error

CheckCoderAccounts refuses accounts the Coding agent's programs cannot be given: one that is not one, two on a host, more than MaxCoderAccounts, and more than one host whose CLI reads a single token (a GitHub Enterprise Server, a GitLab, a Gitea), since that CLI would send the one token to every such host. The tokens' variables are AccountTokenEnv's.

func CheckGitHost added in v0.6.999

func CheckGitHost(host string) error

CheckGitHost refuses a host that is not a host name with an optional port, in lower case: no scheme, no user, no path.

func CheckGitHostKind added in v0.6.999

func CheckGitHostKind(k GitHostKind) error

CheckGitHostKind refuses a kind that is not one.

func CheckGitIdentity added in v0.6.999

func CheckGitIdentity(user, name, email string) error

CheckGitIdentity refuses an account's user name, commit name or commit email that is not one: the user name is the host's (letters, digits, dots, hyphens and underscores), the name one line of at most 100 characters, the email an address.

func CheckStoredSecretName

func CheckStoredSecretName(name string) error

CheckStoredSecretName refuses a name that is not an environment variable's ([A-Z][A-Z0-9_]{0,63}), or one the runner and the programs it runs set themselves.

func CoderExecImageTag

func CoderExecImageTag(runnerImage, base string) string

CoderExecImageTag names the Coding agent's exec image: deterministic in its toolchain image (pinned by digest) and the runner image whose binary it copies, under a "c" tag in the catalogue's exec repository, as Unsafe Mode's is under "u".

func ExecImageTag

func ExecImageTag(runnerImage string, commands, packages []string, apkMirror string) string

ExecImageTag names the per-QuickAgent exec image: the runner image with the catalogued packages installed and minimized to exactly the declared commands. Deterministic in (runner image, sorted commands, sorted packages, mirror) so the compiler can reference it before the install step builds it, and so a changed catalog entry or mirror is a new image. "" when no exec is declared — the shared runner image serves.

func GatewayURL

func GatewayURL() string

GatewayURL is the MCP endpoint agents connect to on the run network.

func HasPackageServers

func HasPackageServers(servers []MCPServerSpec) bool

HasPackageServers reports whether any declared server is a package, installed into the signature's server store.

func PHTargetHost

func PHTargetHost(id string) string

PHTargetHost is a target host's relay target, address:port, by its question's id: the address the person's machine resolved the answer to, which only the run knows, so the plan carries the placeholder and its hash is the release's, not the run's.

func ProxyURL

func ProxyURL() string

ProxyURL is the CONNECT proxy address for the agent container's HTTPS_PROXY.

func SharesAny

func SharesAny(servers []MCPServerSpec) bool

SharesAny reports whether any server sees the share, however: each such server also saves into the share outbox.

func SharesAs

func SharesAs(servers []MCPServerSpec, how ServerShare) bool

SharesAs reports whether any server sees the share as how.

func SingleTokenCLI added in v0.6.999

func SingleTokenCLI(a CoderAccount) string

SingleTokenCLI names the CLI that reads one token for every host of the account's kind, or "" where the account's host has a token of its own (github.com) or no CLI (git).

func ToolsCmd

func ToolsCmd() []string

ToolsCmd is the one command the tools server runs with in its container: the runner image's tools role reading its spec. The compiler writes it into the gateway's catalog, and the docker filter knows the tools server by it (the web network and the bounded tmpfs), so there is one copy.

func UnsafeExecImageTag

func UnsafeExecImageTag(runnerImage string, u UnsafeExecSpec, commands, packages []string) string

UnsafeExecImageTag names an Unsafe Mode exec image: deterministic in the base (pinned by digest), the runner image whose binary it copies, the sorted commands, the sorted packages and the extras, so a re-pin of the base or a changed index or extras list is a new image. It lives in the same repository as the catalogue's exec images (<runner>-exec), under a "u" tag, so the desktop's image removal (internal/dockerimages.Select in agentry-desktop) takes it with them.

Types

type AgentFiles

type AgentFiles struct {
	// Share says the person's share folder is mounted at
	// AgentRoot/AgentShareDir.
	Share bool `json:"share,omitempty"`
	// CheckShare says a file in the share is read only once the runner has
	// checked it: the runner runs what is new or changed in the share
	// through the decode step before each turn and writes the verdicts, and
	// the text read out of each document, that the tools server reads at
	// ShareChecksMount; the tools server refuses a file whose bytes have no
	// verdict, or one ClamAV found, and serves a document by its text.
	// Unset, the share is read as it is.
	CheckShare bool `json:"checkShare,omitempty"`
	// MalwareCheck says that check runs ClamAV over each file: the policy's
	// malwareCheck when the plan was compiled. Unset, the check reads the
	// files without ClamAV and every file is read unchecked.
	MalwareCheck bool `json:"malwareCheck,omitempty"`
	// Skills are the skills the agent has on, by name and description, in
	// the order the System Prompt lists them; their folders are mounted
	// read-only at AgentRoot/AgentSkillsDir.
	Skills []Skill `json:"skills,omitempty"`
	// Memory says the agent's memory volume is mounted read-write at
	// AgentRoot/AgentMemoryDir.
	Memory bool `json:"memory,omitempty"`
}

AgentFiles is a persistent agent's folders (CapSummary.AgentFiles).

func (*AgentFiles) Folders

func (a *AgentFiles) Folders() []string

Folders are the folders beneath AgentRoot the agent's tools read and write, in a fixed order.

func (*AgentFiles) ReadFolders

func (a *AgentFiles) ReadFolders() []string

ReadFolders are the folders beneath AgentRoot the agent's tools read: its folders, and its skills, which are read-only.

type AptPlacement

type AptPlacement struct {
	Command string `json:"command"`
	Package string `json:"package"`
}

AptPlacement is a declared command and the Kali package the index says ships it.

type BrowserCap

type BrowserCap struct {
	Sites   []string `json:"sites,omitempty"`
	Hosts   []string `json:"hosts,omitempty"`
	Public  bool     `json:"public,omitempty"`
	Secrets []string `json:"secrets,omitempty"`
	// Agreed says the scope is the Coding agent's own, which the person
	// agreed to for that agent, not a release's declaration that the
	// machine policy allowed.
	Agreed bool `json:"agreed,omitempty"`
}

BrowserCap is capabilities.browser, normalized: the site questions, the fixed hosts (lower case), whether the scope is any public site, and the declared secrets the browser may type.

type BrowserSpec

type BrowserSpec struct {
	Image string `json:"image"`
}

BrowserSpec is the browser server's image, a digest-pinned reference.

type Budgets

type Budgets struct {
	// TimeoutSeconds kills the run (exit 15).
	TimeoutSeconds int `json:"timeoutSeconds"`
	// MaxTurns kills the run after this many tool-call events (exit 16);
	// 0 = unlimited.
	MaxTurns int `json:"maxTurns"`
	// MaxCostUSD kills the run once the reported running cost exceeds it
	// (exit 16); 0 = unlimited.
	MaxCostUSD float64 `json:"maxCostUsd,omitempty"`
}

Budgets are the hard stops.

type CalendarFeed added in v0.6.999

type CalendarFeed struct {
	Name string `json:"name"`
	// Host is the host the address names, in lower case: the one place the
	// tools server may fetch the feed from.
	Host string `json:"host"`
	// URLEnv is the variable of the tools server's environment that holds
	// the address (CalendarFeedEnv).
	URLEnv string `json:"urlEnv"`
	// SessionEnv, for a feed signed in through a browser, is the variable
	// that holds the sign-in's cookies (CalendarSessionEnv), which the tools
	// server sends to Host alone.
	SessionEnv string `json:"sessionEnv,omitempty"`
}

CalendarFeed is one calendar feed as a plan names it. Its address is the segment's, never the plan's.

type CalendarGrant added in v0.6.999

type CalendarGrant struct {
	Feeds []CalendarFeed `json:"feeds"`
	// TimeZone is the person's IANA zone, in which the tools answer.
	TimeZone string `json:"timeZone,omitempty"`
}

CalendarGrant is a persistent Assistant's calendar feeds that its roster has on (CapSummary.Calendar).

func (*CalendarGrant) Hosts added in v0.6.999

func (g *CalendarGrant) Hosts() []string

Hosts are the feeds' hosts, each once.

type CapSummary

type CapSummary struct {
	// EgressMode is none | hosts | all.
	EgressMode string `json:"egressMode"`
	// EgressHosts is set for mode hosts.
	EgressHosts []string `json:"egressHosts,omitempty"`
	// FSReadMode / FSWriteMode are none | workspace | paths.
	FSReadMode   string   `json:"fsReadMode"`
	FSReadPaths  []string `json:"fsReadPaths,omitempty"`
	FSWriteMode  string   `json:"fsWriteMode"`
	FSWritePaths []string `json:"fsWritePaths,omitempty"`
	// ExecCommands is the exec allowlist (empty = none).
	ExecCommands []string `json:"execCommands,omitempty"`
	// DataAccess is the declared semantic category list.
	DataAccess []string `json:"dataAccess,omitempty"`
	// WebTools is a built-in's grant of the web tools (web_search, web_read),
	// the Drafter's and the Knowledge Creator's. It is never the manifest's:
	// the compiler sets it for a built-in package the CLI grants it to, and
	// refuses it to everything else.
	WebTools bool `json:"webTools,omitempty"`
	// RegistrySearch adds registry_search to WebTools: the Drafter's alone.
	RegistrySearch bool `json:"registrySearch,omitempty"`
	// WebSearchedOnly holds web_read to the addresses a web_search of the
	// run returned: the Knowledge Creator's.
	WebSearchedOnly bool `json:"webSearchedOnly,omitempty"`
	// WebGivenOnly holds web_read to the addresses the person gave the run,
	// with no web_search: the Voice Writer's, reading a person's own pages.
	WebGivenOnly bool `json:"webGivenOnly,omitempty"`
	// WebRender lets web_read render a page in a headless browser the
	// engine runs once a page, behind a proxy that admits public sites
	// alone, and read the text the page draws: the Knowledge Creator's.
	// The model never drives that browser. Only with WebTools.
	WebRender bool `json:"webRender,omitempty"`
	// ReviewTools is a built-in's review grant (ai_review, and read_input
	// answering only what AI Review passed). Like WebTools it is never the
	// manifest's: the compiler sets it for a built-in package the CLI grants it
	// to, and refuses it to everything else.
	ReviewTools bool `json:"reviewTools,omitempty"`
	// DesignTools is the Report Designer's grant (render_preview,
	// check_design and view_reference). Like WebTools it is never the
	// manifest's: the compiler sets it for that built-in alone.
	DesignTools bool `json:"designTools,omitempty"`
	// TargetHosts are the release's target hosts, by the id of the host
	// question that asks for each (capabilities.targetHosts): the host link and
	// its tools, reached through the gateway.
	TargetHosts []string `json:"targetHosts,omitempty"`
	// Browser is the release's browser line (capabilities.browser): the browser
	// server and the browse proxy that holds its scope.
	Browser *BrowserCap `json:"browser,omitempty"`
	// Desktop is the release's desktop line (capabilities.desktop): the
	// applications on the person's computer the run uses through the
	// desktop link, one gateway entry each, answered by Agentry Desktop.
	Desktop *DesktopCap `json:"desktop,omitempty"`
	// Scratch is the runner's grant of the scratch folder (scratch_list,
	// scratch_read, scratch_write over ScratchMount), and of grep and glob, to
	// every run and session, a built-in package's included. It is never the
	// manifest's.
	Scratch bool `json:"scratch,omitempty"`
	// PDF is the runner's grant of export_pdf to every release's run and
	// session. It is never the manifest's, and never a built-in's: what a
	// built-in writes is read by the application, not handed to a person as
	// a document.
	PDF bool `json:"pdf,omitempty"`
	// AgentFiles is a persistent agent's grant of its own folders under
	// AgentRoot: its data volume always, and the person's share folder when
	// the agent has it on. It is never the manifest's: the compiler sets it
	// for a persistent built-in alone, and the filesystem tools, grep and
	// glob are then rooted at AgentRoot in place of the workspace.
	AgentFiles *AgentFiles `json:"agentFiles,omitempty"`
	// ShippedSkills are the skills the release ships, for a release that
	// declares capabilities.skills and runs in any mode but persistent: by
	// name and description, in the order the System Prompt lists them. Their
	// folders are mounted read-only at SkillsMount in the tools container,
	// and skill_read reads them. A persistent agent's skills are
	// AgentFiles.Skills.
	ShippedSkills []Skill `json:"shippedSkills,omitempty"`
	// AppLink is a persistent built-in's app link, by the tool set it lists
	// (runnerimage/applink): the gateway runs it with no network and the
	// supervisor's socket alone. Never the manifest's: the compiler sets it
	// for a persistent built-in alone.
	AppLink string `json:"appLink,omitempty"`
	// Coder is the Coding agent's grant, what its roster has on: any
	// program in its own exec image, open egress, the browser on any public
	// site and the person's dev server. Never the manifest's: the compiler
	// sets it for a persistent built-in the CLI grants it to alone, and the
	// person's agreement to it for this agent is the gate, not the machine
	// policy's allowWildcardEgress or browser.allowPublicWeb.
	Coder *CoderGrant `json:"coder,omitempty"`
	// Calendar is a persistent Assistant's calendar feeds, what its roster
	// has on: the tools server is given each feed's address and reaches the
	// feeds' hosts on 443 alone. Never the manifest's: the compiler sets it
	// for a persistent built-in the CLI grants it to alone.
	Calendar *CalendarGrant `json:"calendar,omitempty"`
}

CapSummary is the manifest capability contract, normalized to closed enums so the engine and receipts never re-parse manifest unions.

func (CapSummary) Fetches

func (c CapSummary) Fetches() bool

Fetches reports whether the contract grants fetch: egress to named hosts, or to any.

func (CapSummary) ToolsReachPastHost

func (c CapSummary) ToolsReachPastHost() bool

ToolsReachPastHost reports whether the tools server reaches past the host on a network of the run's own, with no host list for the gateway to hold it to: for the web tools, whose tools hold their own address rule, or for unrestricted egress, which the operator's policy permitted.

type CaseOnlyMatch added in v0.6.1009

type CaseOnlyMatch struct {
	// Entry is the filter entry as the manifest writes it; Tool is the exact
	// name the server lists, which the filter must use.
	Entry, Tool string
}

CaseOnlyMatch is a tool filter entry that names a real tool only when case is ignored: the gateway compares a server's tool names with its allowlist exactly, so the entry matches nothing and the tool is dropped without a word.

type CoderAccount added in v0.6.999

type CoderAccount struct {
	// Host is the git host, host[:port], in lower case.
	Host string      `json:"host"`
	Kind GitHostKind `json:"kind"`
	// Own says the account is the agent's own, which the person shares
	// repositories with, rather than the person's.
	Own bool `json:"own,omitempty"`
	// User is the account's user name on the host, which git signs in as.
	User string `json:"user"`
	// Name and Email are the commit identity in a repository whose remote
	// is on the host.
	Name  string `json:"name"`
	Email string `json:"email"`
	// TokenEnv is the variable of the tools server's environment that holds
	// the token (AccountTokenEnv).
	TokenEnv string `json:"tokenEnv"`
}

CoderAccount is one of the Coding agent's git host accounts its roster has on (CoderGrant.Accounts). Its token is the segment's, never the plan's: the plan names the variable of the tools server's environment that holds it.

type CoderGrant

type CoderGrant struct {
	// Commands: run_command runs any program in the Coding agent's exec
	// image (ExecImageSpec.Coder), in a folder beneath AgentRoot.
	Commands bool `json:"commands,omitempty"`
	// OpenEgress: the tools server, and the programs it runs, reach any
	// address, from a network of the segment's own.
	OpenEgress bool `json:"openEgress,omitempty"`
	// Browser: the browser server, on any public site.
	Browser bool `json:"browser,omitempty"`
	// DevHost: the person's dev server, as the target host DevHostID.
	DevHost bool `json:"devHost,omitempty"`
	// Ports: the tools server's ports published on the person's computer,
	// each at 127.0.0.1 and the same number, while its entry is on.
	Ports []CoderPort `json:"ports,omitempty"`
	// Secrets: the names of the person's stored secrets its roster has on,
	// set in the environment of the programs run_command runs (with
	// Commands); their values are the segment's, never the plan's.
	Secrets []string `json:"secrets,omitempty"`
	// DependencyScan: dependency_scan, OSV-Scanner offline over OSV's
	// databases on the person's computer (with Commands).
	DependencyScan bool `json:"dependencyScan,omitempty"`
	// Accounts: the person's git host accounts its roster has on, whose
	// tokens the programs run_command runs sign in with (with Commands);
	// the tokens are the segment's, never the plan's.
	Accounts []CoderAccount `json:"accounts,omitempty"`
}

CoderGrant is the Coding agent's grant (CapSummary.Coder), each part one switch of its roster.

type CoderPort

type CoderPort struct {
	Name string `json:"name"`
	Port int    `json:"port"`
}

CoderPort is one of the Coding agent's published ports.

type ContainerSpec

type ContainerSpec struct {
	Image string `json:"image"`
	// Entrypoint replaces the image's entrypoint; empty keeps it. The codex
	// image's runs start a shell that puts the plan's configuration into
	// the harness's writable home before the harness starts.
	Entrypoint string `json:"entrypoint,omitempty"`
	// Argv is the command+args passed after the image (entrypoint's argv).
	Argv []string `json:"argv,omitempty"`
	Env  []EnvVar `json:"env,omitempty"`
	// Mounts are bind mounts (host source may hold placeholders).
	Mounts []Mount `json:"mounts,omitempty"`
	// StdinTask: the engine pipes the task text into stdin.
	StdinTask bool `json:"stdinTask,omitempty"`
	// ReadOnlyRoot runs the container with a read-only root filesystem and
	// Tmpfs as its only writable paths besides its mounts. The adapter sets
	// both, since where a harness writes is the image's to say.
	ReadOnlyRoot bool     `json:"readOnlyRoot,omitempty"`
	Tmpfs        []string `json:"tmpfs,omitempty"`
}

ContainerSpec is a docker container the engine will run. Sources and env values may contain the PH* placeholders.

type ContextWindowSpec added in v0.7.28

type ContextWindowSpec struct {
	// Tokens is the window in tokens.
	Tokens int64 `json:"tokens"`
	// Source is where it came from: ContextWindowSource for the policy's
	// model.contextWindow, else the endpoint URL (scheme, host and path) that
	// reported it when the run asked.
	Source string `json:"source"`
}

ContextWindowSpec is a model's context window as the plan knows it.

func ContextWindowOf added in v0.7.28

func ContextWindowOf(tokens int64, source string) *ContextWindowSpec

ContextWindowOf is the plan's record of a window of tokens that came from source, the policy's when source is empty; nil without a window.

type ConversationArgs

type ConversationArgs struct {
	// New opens a new conversation under an id the engine chooses.
	New string `json:"new"`
	// Continue continues the stored conversation of that id.
	Continue string `json:"continue"`
}

ConversationArgs are the two ways a harness started on its command line is told its conversation: each flag is followed by the conversation's id.

type CredentialKind

type CredentialKind struct {
	Provider string `json:"provider"`
	Kind     string `json:"kind"`
}

CredentialKind names a provider and the kind of credential expected.

type DesktopCap added in v0.7.28

type DesktopCap struct {
	Servers []DesktopServerCap `json:"servers,omitempty"`
	// ComputerUse is "app" or "screen" where the release declares computer
	// use: the agent sees and acts in the bound applications' windows, or
	// on the whole display.
	ComputerUse string `json:"computerUse,omitempty"`
	// ComputerTools are the computer-use entry's tools, with their classes,
	// where the release declares computer use.
	ComputerTools []DesktopTool `json:"computerTools,omitempty"`
	// ScreenAllowedBy says what allowed a screen scope: the policy's
	// desktop.allowScreen, the run's --allow-screen, or Unsafe Mode.
	ScreenAllowedBy string `json:"screenAllowedBy,omitempty"`
	// Windows are the applications, by id, whose windows app-scope computer
	// use reaches, in the release's order.
	Windows []string `json:"windows,omitempty"`
	// ChooseWindows says app-scope computer use reaches the windows of an
	// application the person chooses when the run starts.
	ChooseWindows bool `json:"chooseWindows,omitempty"`
	// PersonServers says whether the run may bind an application the person
	// set up themself, outside Agentry Desktop's library or changed from it:
	// PersonServersAllowed by the policy, PersonServersUnsafe only because
	// Unsafe Mode is on, or PersonServersRefused.
	PersonServers string `json:"personServers,omitempty"`
	// PersonServersRefusal is the sentence that refuses such an application
	// when an organization's managed settings, rather than the policy,
	// refuse it; empty otherwise.
	PersonServersRefusal string `json:"personServersRefusal,omitempty"`
}

DesktopCap is the release's desktop line as the plan carries it: each application whose MCP server the run uses, by its id, with the release's narrowing of its tools; the applications whose windows its computer use reaches; the computer-use scope; and whether an application the person set up themself may be bound.

func (*DesktopCap) Computer added in v0.7.30

func (d *DesktopCap) Computer() (DesktopServerCap, bool)

Computer is the computer-use entry as a desktop link entry, and whether the line has one.

func (*DesktopCap) Entries added in v0.7.30

func (d *DesktopCap) Entries() []DesktopServerCap

Entries are the line's desktop link entries: each application server, then the computer-use entry where the release declares computer use.

func (*DesktopCap) EntryIDs added in v0.7.30

func (d *DesktopCap) EntryIDs() []string

EntryIDs are the ids of the line's desktop link entries, in Entries' order.

func (*DesktopCap) HasComputerUse added in v0.7.30

func (d *DesktopCap) HasComputerUse() bool

HasComputerUse reports whether the line declares computer use.

func (*DesktopCap) IDs added in v0.7.28

func (d *DesktopCap) IDs() []string

IDs are the ids of the line's application entries, in the release's order.

func (*DesktopCap) PersonServersRefusedBecause added in v0.7.42

func (d *DesktopCap) PersonServersRefusedBecause(policyText string) string

PersonServersRefusedBecause is why an application the person set up is refused under d, in the words that follow "this application".

func (*DesktopCap) Server added in v0.7.28

func (d *DesktopCap) Server(id string) (DesktopServerCap, bool)

Server is the line's desktop link entry of this id: an application by its id, the chosen application's entry, or the computer-use entry.

type DesktopServerCap added in v0.7.28

type DesktopServerCap struct {
	// ID is the application's id, and the entry agentry-desktop-<id>; for
	// an application the person chooses it is DesktopChosenID.
	ID string `json:"id"`
	// Application names it in the plan's and the System Prompt's words.
	Application string `json:"application"`
	// Tools are the tools the run has: at compile time the release's
	// narrowing (Narrowed), or none, meaning every tool the server lists;
	// at run time each with the class Agentry Desktop gives it.
	Tools []DesktopTool `json:"tools"`
	// Narrowed says Tools is the release's narrowing of the server's tools.
	Narrowed bool `json:"narrowed,omitempty"`
	// Chosen says the entry is an application the person chooses when the
	// run starts.
	Chosen bool `json:"chosen,omitempty"`
}

DesktopServerCap is one application whose MCP server a run uses on the person's computer. Which server answers for it, and which tools that server lists, are known only to Agentry Desktop, which tells the run when it binds.

func (DesktopServerCap) ForPerson added in v0.7.36

func (s DesktopServerCap) ForPerson() string

ForPerson names the application in a message to the person: its id, or "an application you choose" for the entry the person chooses at the start. Application keeps the agent's and the plan's words.

func (DesktopServerCap) Tool added in v0.7.28

func (s DesktopServerCap) Tool(name string) (DesktopTool, bool)

Tool is the server's tool of this name.

func (DesktopServerCap) ToolNames added in v0.7.28

func (s DesktopServerCap) ToolNames() []string

ToolNames are the server's tools' names: the release's narrowing in its order, or, once the run is bound, Agentry Desktop's list in its order.

type DesktopTool added in v0.7.28

type DesktopTool struct {
	Name  string `json:"name"`
	Class string `json:"class"`
}

DesktopTool is one tool of an application server, with its class: read, act or exec.

type DockerSpec

type DockerSpec struct {
	Runtime string `json:"runtime"`
	// GatewayRuntime is the gateway's own runtime (policy
	// docker.gatewayRuntime); absent, the daemon's default.
	GatewayRuntime string `json:"gatewayRuntime,omitempty"`
	// Resolvers are the name servers the web tools resolve through (policy
	// docker.resolvers), and under Runtime the classes that resolve host names;
	// absent, docker's DNS.
	Resolvers []string `json:"resolvers,omitempty"`
}

DockerSpec is what the engine asks of the daemon for every container of the run beyond the image: the OCI runtime (docker run --runtime).

type EnvVar

type EnvVar struct {
	Name string `json:"name"`
	// Value is a literal (may contain PH* placeholders).
	Value string `json:"value,omitempty"`
	// FromHostEnv resolves from the invoking host's environment at run
	// time (e.g. the operator's model API key).
	FromHostEnv string `json:"fromHostEnv,omitempty"`
	// FromKeyring, beside FromHostEnv, names the OS keychain account read
	// when that variable is not set (policy apiKeySource keyring):
	// the account, never the value.
	FromKeyring string `json:"fromKeyring,omitempty"`
	// FromRunToken injects the per-run gateway Bearer token.
	FromRunToken bool `json:"fromRunToken,omitempty"`
	// FromModelSignIn injects the run's model sign-in access token as it
	// is when the process starts (a host harness on the restart token
	// route, which reads its token from the environment): the access token
	// alone, never the sign-in.
	FromModelSignIn bool `json:"fromModelSignIn,omitempty"`
	// FromInference injects the run's Agentry credits session token (model
	// provider agentry): a token usable only on the registry's model
	// endpoint, which the host opens for the run and renews while it
	// lives. Never the person's registry sign-in.
	FromInference bool `json:"fromInference,omitempty"`
	// ExpectedKind, beside FromHostEnv, is the credential kind the plan was
	// compiled for (policy apiKeyKind): the engine checks the value it resolves
	// against it and refuses a mismatch by name, so a plan rendered for a
	// subscription token never runs with an API key and the reverse — the kind
	// decides the harness's argv and the variable it reads, which the plan
	// fixed at compile time. A consistency check between the policy and the
	// key, not a boundary: plan.json is the operator's own file. Nil when the
	// provider has one kind of key.
	ExpectedKind *CredentialKind `json:"expectedKind,omitempty"`
}

EnvVar is one environment variable. Exactly one of Value / FromHostEnv / FromRunToken is meaningful: literal (possibly placeholder-bearing), resolved from the operator's host environment at run time, or the per-run gateway token. Secret VALUES therefore never appear in a plan.

type ExecImageSpec

type ExecImageSpec struct {
	// Tag is the image name (ExecImageTag).
	Tag string `json:"tag"`
	// Commands are the declared commands the image is minimized to, sorted.
	Commands []string `json:"commands"`
	// Packages are the catalogued apk packages the declared commands map
	// to (optionally pinned "name=version"), sorted, deduplicated.
	Packages []string `json:"packages,omitempty"`
	// APKMirror replaces the image's Alpine repositories at build time;
	// empty means the image's own.
	APKMirror string `json:"apkMirror,omitempty"`
	// Unsafe is set for an Unsafe Mode exec image: built FROM the unsafe
	// base rather than the runner image, with Packages as Kali packages
	// installed one at a time, the extras applied, and no minimize.
	// Nil for the catalogue's exec image, whose plan bytes it leaves
	// unchanged.
	Unsafe *UnsafeExecSpec `json:"unsafe,omitempty"`
	// Coder is set for the Coding agent's exec image: its toolchain image,
	// pinned by digest (policy images.coder), with the runner binary
	// copied in, not minimized, and no command declared or installed.
	Coder string `json:"coder,omitempty"`
}

ExecImageSpec is the per-QuickAgent exec image a plan runs its tools server in when the manifest declares exec: the runner image with the operator's catalogued packages installed, then minimized to exactly the declared commands.

type ExtraKind

type ExtraKind string

ExtraKind is an extras-list recipe's kind; there are exactly two.

const (
	// ExtraPip installs a PyPI name==version into a venv and links its
	// command onto PATH.
	ExtraPip ExtraKind = "pip"
	// ExtraLink links a path inside a Kali package onto PATH.
	ExtraLink ExtraKind = "link"
)

type GatewaySpec

type GatewaySpec struct {
	// Image is the pinned gateway image from policy.
	Image string `json:"image"`
	// Args is the full gateway argv (after the image).
	Args []string `json:"args"`
	// Env is the gateway container environment.
	Env []EnvVar `json:"env"`
	// Mounts includes the rendered config dir and the docker socket.
	Mounts []Mount `json:"mounts"`
	// Servers is the enabled-server list (also in registry.yaml).
	Servers []string `json:"servers"`
}

GatewaySpec is the gateway container launch description. Flags are compiled, not chosen at run time, so tests can assert --block-network is always present.

type GitHostKind added in v0.6.999

type GitHostKind string

GitHostKind is the kind of a git host, which says which CLI is given its token.

const (
	// GitHostGitHub is github.com or a GitHub Enterprise Server host: gh.
	GitHostGitHub GitHostKind = "github"
	// GitHostGitLab is gitlab.com or a self-managed GitLab: glab.
	GitHostGitLab GitHostKind = "gitlab"
	// GitHostGitea is a Gitea, Forgejo or Codeberg host: tea.
	GitHostGitea GitHostKind = "gitea"
	// GitHostGit is any other git host: git alone.
	GitHostGit GitHostKind = "git"
)

The kinds of git host.

func GitHostKindOf added in v0.6.999

func GitHostKindOf(host string) GitHostKind

GitHostKindOf is the kind of a hosted service's host, or "" for a host whose kind the person must say.

type HarnessSpec

type HarnessSpec struct {
	// Adapter is the harness adapter name.
	Adapter string `json:"adapter"`
	// Model is the provider/model string for receipts.
	Model string `json:"model"`
	// SavedModel is the saved model the run is on, by its id and the
	// person's name for it; nil for a plan compiled from a policy with no
	// saved model.
	SavedModel *SavedModelRef `json:"savedModel,omitempty"`
	// Agent is the agent container. Empty (no image) when Host is set.
	Agent ContainerSpec `json:"agent"`
	// Host runs the harness as a process on this machine from the person's own
	// installation instead of a container. Exactly one of Agent.Image and Host
	// is set.
	Host *HostProcessSpec `json:"host,omitempty"`
	// ResultKind hints how the final result is extracted: "text" or
	// "json" (when Output.SchemaFile is set).
	ResultKind string `json:"resultKind"`
	// Session says how the harness is driven when Mode is interactive;
	// nil for an autonomous plan.
	Session *SessionSpec `json:"session,omitempty"`
	// OneTurn, on an autonomous plan, says the harness is driven as one turn of
	// this session protocol rather than read from its stdout: the engine opens
	// the session, sends the task as its one user turn and ends it (the codex
	// adapters on a model sign-in, whose vendor serves app-server's requests
	// and not exec's). Nil for a harness whose autonomous run prints its
	// events.
	OneTurn *SessionSpec `json:"oneTurn,omitempty"`
	// Resume, on an autonomous plan, says the harness keeps its conversation
	// in the run's session store (PHSession, mounted by Agent.Mounts) under
	// the id the engine puts in place of PHConversation, so that the engine
	// can start it again on the same conversation after a transient model
	// failure late in the run. Nil for a harness that keeps none.
	Resume *ResumeSpec `json:"resume,omitempty"`
	// ImagePin is how Agent.Image is pinned; nil for a host
	// harness, which runs no image.
	ImagePin *ImagePin `json:"imagePin,omitempty"`
	// ModelSignIn is set when the run spends a person's plan through a
	// model sign-in instead of a key; nil for a key.
	ModelSignIn *ModelSignInSpec `json:"modelSignIn,omitempty"`
	// ContextWindow is the model's context window the plan was compiled for,
	// and where it came from; nil when the plan was compiled without one.
	ContextWindow *ContextWindowSpec `json:"contextWindow,omitempty"`
}

HarnessSpec names the adapter and carries the agent container spec.

type HostLinkSpec

type HostLinkSpec struct {
	Image string `json:"image"`
	Base  string `json:"base"`
}

HostLinkSpec is the host link's image: the local tag the gateway's catalog names, and the digest-pinned base it is built on.

type HostProcessSpec

type HostProcessSpec struct {
	// Command is the executable name, resolved on PATH at run time (the
	// operator policy's harness.<adapter>.path overrides the lookup); a
	// plan never carries a host path, so it stays deterministic.
	Command string `json:"command"`
	// Argv follows the command; placeholders are rendered per run.
	Argv []string `json:"argv,omitempty"`
	// Env is set on the process; the run token and the model key travel
	// by name exactly as for a container.
	Env []EnvVar `json:"env,omitempty"`
	// InheritEnv names host variables passed through unchanged (HOME,
	// PATH and the like: the harness's own login state lives under them).
	// Everything else in the runner's environment is dropped.
	InheritEnv []string `json:"inheritEnv,omitempty"`
	// VersionArgv, when set, is run once before the harness so the
	// receipts record which release of it ran (for example --version).
	VersionArgv []string `json:"versionArgv,omitempty"`
	// StdinTask feeds the task on stdin (autonomous mode).
	StdinTask bool `json:"stdinTask,omitempty"`
	// RefuseAncestorFiles names files (relative names) that must not
	// exist in any ancestor of the harness's working directory: the
	// engine walks up to the root before starting the process and
	// refuses the run by name if one is there. A harness that reads
	// context from its ancestors (Claude Code without --bare reads
	// CLAUDE.md up the tree) names them here, so "no ambient context" is
	// measured rather than assumed.
	RefuseAncestorFiles []string `json:"refuseAncestorFiles,omitempty"`
}

HostProcessSpec runs the harness as a process of this user from the person's own installation of it. The gateway and the proxy are published on 127.0.0.1 for it; their addresses reach it as HostGatewayURLEnv / HostProxyURLEnv and, in plan files and argv, through the PHHostGatewayURL / PHHostProxyURL placeholders. The process is not inside the run's network boundary: the proxy variables and the gateway's catalog are what bound it, which the plan's Enforcement map says in so many words.

type ImagePin

type ImagePin struct {
	By    string `json:"by"`
	Value string `json:"value,omitempty"`
	// Note is what the pin does not prove, when the build knows: an image
	// built from a download its vendor publishes a checksum of and does
	// not sign is "pinned by checksum, not signed".
	Note string `json:"note,omitempty"`
}

ImagePin says how the harness image that ran was pinned: by "digest" (a published image, Value its sha256 digest), "artifact" (an image built on the machine, Value the vendor artifact's sha256) or "tag" (a policy naming docker-agent's harness image by tag alone, Value empty).

func (*ImagePin) String

func (p *ImagePin) String() string

String is the pin as a receipt line says it.

type InstructionSpec

type InstructionSpec struct {
	// SourcePath is the archive-relative file the instruction came from.
	SourcePath string `json:"sourcePath"`
	// SHA256 is the hash of the fully rendered instruction (the System
	// Prompt, then the body), for receipts.
	SHA256 string `json:"sha256"`
	// BodySHA256 is the hash of the package's own instruction text alone,
	// frontmatter stripped: what ReadInstruction holds the file to.
	BodySHA256 string `json:"bodySha256,omitempty"`
}

InstructionSpec records the instruction's provenance, not its text — the text lives in the adapter's harness file, hashed via Files.

type MCPServerSpec

type MCPServerSpec struct {
	// Name is the gateway catalog name ("mcp-" + sanitized package id).
	Name string `json:"name"`
	// Source is "npm" or "pypi"; Package and Version are the manifest pin. For
	// a remote server Source is SourceURL, Package the server's address, and
	// Version, Integrity, Image, Command and StoreSubdir are empty: the
	// compiler runs the runner image's bridge.
	Source  string `json:"source"`
	Package string `json:"package"`
	Version string `json:"version"`
	// Integrity is the registry-advertised artifact integrity (npm SRI or
	// "sha256:<hex>") recorded at resolve time; receipts disclose it.
	Integrity string `json:"integrity,omitempty"`
	// Image is the pinned runtime image the server runs in.
	Image string `json:"image"`
	// Runtime names the language runtime the image holds for a PyPI server
	// ("Python 3.14.10"), which is the fallback's when RuntimeFallback is
	// set; empty for any other server.
	Runtime string `json:"runtime,omitempty"`
	// RuntimeFallback says the server runs on the policy's fallback Python
	// runtime because its requires_python excludes the default's Python.
	RuntimeFallback bool `json:"runtimeFallback,omitempty"`
	// Command is the argv inside the runtime container (store-relative
	// paths under MCPStorePrefix).
	Command []string `json:"command"`
	// Volumes are an image server's named volumes, each name:target, which
	// the docker filter holds to this server's container alone; empty for
	// any other server.
	Volumes []string `json:"volumes,omitempty"`
	// Args are the manifest's arguments for the server, appended to
	// Command in its catalog entry, each one argument as written: the
	// entry is a list, never a shell line.
	Args []string `json:"args,omitempty"`
	// StoreSubdir is the server's directory name under PHServers.
	StoreSubdir string `json:"storeSubdir"`
	// Tools optionally restricts the server to these tool names.
	Tools []string `json:"tools,omitempty"`
	// Egress is the server's own allowlist ("*" = unrestricted,
	// policy-gated at compile like agent egress).
	Egress []string `json:"egress,omitempty"`
	// Secrets are the env names this server needs (values resolved at run
	// time into the gateway secrets file under this server's keys).
	Secrets []string `json:"secrets,omitempty"`
	// Env is the server's plain configuration from the manifest (name →
	// literal value), rendered into its catalog entry beside — never
	// through — its secrets. Receipts name the keys only.
	Env map[string]string `json:"env,omitempty"`
	// Auth is a remote server's auth kind: "none"; "secret", its one Secrets
	// name sent as the bearer; or "oauth", the person's connection, whose
	// access token the runner hands its bridge at each start. Empty for a
	// package server.
	Auth string `json:"auth,omitempty"`
	// OAuth is a package server's OAuth sign-in: the issuer and scopes its
	// connection is made with, and the files and env the runner renders the
	// connection's access token into. Nil for a remote server and for a package
	// server without one.
	OAuth *OAuthSpec `json:"oauth,omitempty"`
	// Share is how the server sees a persistent agent's share folder, read
	// only, at AgentRoot/AgentShareDir: ServerShareMirror, the copies the
	// share check passed, or ServerShareLive, the folder itself. Empty for
	// a server that does not see it, which is every server but a package
	// server the person let see it, with no network.
	Share ServerShare `json:"share,omitempty"`
	// Account is the account an image server is signed in as, as the
	// server named it at its sign-in: the System Prompt names it, so the
	// agent can say whose mailbox or calendar it read. Empty for every
	// other server.
	Account string `json:"account,omitempty"`
}

MCPServerSpec is one declared MCP server, resolved to its exact artifacts. The store contents live under the signature's profile — per-machine — so the plan carries the RESOLUTION (source, version, digest, launch argv), which is deterministic given the manifest pins, and mounts the store via the PHServers placeholder.

func ImageServers added in v0.6.999

func ImageServers(servers []MCPServerSpec) []MCPServerSpec

ImageServers are the image servers among servers.

func (MCPServerSpec) ConnectionKey

func (s MCPServerSpec) ConnectionKey() string

ConnectionKey is how a run's connections name the server: a remote server's address, or a package server's ecosystem-qualified id ("pypi:workspace-mcp"), as the manifest's MCPServer.SourceID gives it.

func (MCPServerSpec) FromImage added in v0.6.999

func (s MCPServerSpec) FromImage() bool

FromImage reports whether the spec is an image server's: a built-in's server run from an image the CLI pins, with no package and no store.

func (MCPServerSpec) Ref

func (s MCPServerSpec) Ref() string

Ref names the server in messages and receipts: the package pin ("@scope/x@1.2.3"), or a remote server's address.

func (MCPServerSpec) Remote

func (s MCPServerSpec) Remote() bool

Remote reports whether the server is declared by address.

func (MCPServerSpec) RemoteHost

func (s MCPServerSpec) RemoteHost() string

RemoteHost is a remote server's host name, its one egress host; "" for a package server.

func (MCPServerSpec) SendsBearer

func (s MCPServerSpec) SendsBearer() bool

SendsBearer reports whether the server is a remote one whose bridge sends a bearer from its connection folder: auth: secret (its one secret) or auth: oauth (the connection's access token).

func (MCPServerSpec) SignsIn

func (s MCPServerSpec) SignsIn() bool

SignsIn reports whether a run of the server needs the person's OAuth connection: a remote server signed in to by OAuth (manifest.AuthOAuth), or a package server with an oauth block.

func (MCPServerSpec) SourceID

func (s MCPServerSpec) SourceID() string

SourceID is the declared server's ecosystem-qualified id, as the manifest's MCPServer.SourceID gives it ("npm:@scope/x", "url:https://…").

type ManagedSpec added in v0.7.35

type ManagedSpec struct {
	Organization string   `json:"organization"`
	Version      int64    `json:"version"`
	Applied      []string `json:"applied,omitempty"`
}

ManagedSpec is one organization's managed settings document as a plan and a receipt record it: whose, which version, and the ids of the settings that applied. A setting's value is never recorded.

type ModelSignInSpec

type ModelSignInSpec struct {
	// Kind is the policy's apiKeyKind, a model sign-in kind
	// (policy.IsModelSignIn), and Provider the provider it spends.
	Kind     string `json:"kind"`
	Provider string `json:"provider"`
	// Delivery is ModelSignInToken, ModelSignInConfigDir or
	// ModelSignInCallback.
	Delivery string `json:"delivery"`
	// Path is where the harness reads it in the container: the token
	// file's path, or the config directory's; empty for a callback.
	Path string `json:"path,omitempty"`
	// Env, on the restart token route, is the variable the harness is
	// started with the token in, read from that file when it starts
	// (policy signInTokenRoute restart); "" when the harness reads the
	// file itself.
	Env string `json:"env,omitempty"`
}

ModelSignInSpec says how a run spends a person's plan instead of a key: which kind of sign-in the plan was compiled for, which the engine holds the caller's grant to at run start, and how it reaches the agent container. The plan never carries the token, the account or a host path.

type Mount

type Mount struct {
	// Source is the host path (may hold placeholders).
	Source string `json:"source"`
	// Target is the container path.
	Target string `json:"target"`
	// ReadOnly appends :ro.
	ReadOnly bool `json:"readOnly,omitempty"`
}

Mount is one bind mount.

type OAuthFile

type OAuthFile struct {
	Path     string `json:"path"`
	Template string `json:"template"`
}

OAuthFile is one file of a package server's connection folder.

type OAuthSpec

type OAuthSpec struct {
	Issuer string            `json:"issuer"`
	Scopes []string          `json:"scopes,omitempty"`
	Files  []OAuthFile       `json:"files,omitempty"`
	Env    map[string]string `json:"env,omitempty"`
}

OAuthSpec is a package server's oauth block as the plan carries it: the manifest's templates, never a token. The engine renders Files into the server's connection folder (mounted writable at ConnectionMount) and the Env entries holding {access_token} into the gateway's secrets file; an entry naming only {dir} is plain env, rendered by the compiler.

func (*OAuthSpec) TokenEnv

func (o *OAuthSpec) TokenEnv(name string) bool

TokenEnv reports whether an oauth env entry carries the access token, which makes it a secret of the run rather than plain configuration.

type OutputSpec

type OutputSpec struct {
	// SchemaFile is the archive-relative schema path ("" = none).
	SchemaFile string `json:"schemaFile,omitempty"`
	// SchemaSHA256 hashes the schema content for receipts.
	SchemaSHA256 string `json:"schemaSha256,omitempty"`
}

OutputSpec is the optional structured-output convention.

type Plan

type Plan struct {
	// PlanVersion pins the schema.
	PlanVersion string `json:"planVersion"`
	// CompiledBy names the CLI build that compiled the plan. The schema
	// can stay the same while the compiler's output changes, so a plan
	// from another build is recompiled rather than reused.
	CompiledBy string `json:"compiledBy,omitempty"`
	// Ref is the canonical ns/name@version this plan was compiled from.
	Ref string `json:"ref"`
	// Digest is the verified archive digest (sha256:…), or the computed
	// digest of a --local package tree.
	Digest string `json:"digest"`
	// Source is "registry" or "local".
	Source string `json:"source"`
	// Modes are the run modes the release declares (manifest v2 modes; a
	// v1 skill or prompt-agent is [autonomous]).
	Modes []string `json:"modes"`
	// Mode is the run mode this plan was compiled for, one of Modes. A
	// release compiles to one plan per mode (plan/<mode>/); the plans are
	// identical except Harness.Agent.Argv/StdinTask and Harness.Session
	// (pinned by a golden test).
	Mode string `json:"mode"`
	// Summary is the manifest one-liner (harness description field).
	Summary string `json:"summary"`
	// PolicySHA256 fingerprints the operator policy the plan was compiled
	// under; a policy change invalidates installed plans.
	PolicySHA256 string `json:"policySha256"`
	// Instruction records where the harness instruction came from.
	Instruction InstructionSpec `json:"instruction"`
	// Capabilities is the normalized manifest contract.
	Capabilities CapSummary `json:"capabilities"`
	// Tools are the companion-server tools this agent is granted.
	Tools []string `json:"tools"`
	// Enforcement maps each contract line to the mechanism string that
	// lands verbatim in the result envelope (honest-posture rule).
	Enforcement map[string]string `json:"enforcement"`
	// Gateway describes the gateway container launch.
	Gateway GatewaySpec `json:"gateway"`
	// ExecImage is the tools container's image when the manifest declares
	// exec: the runner image plus the operator's catalogued packages,
	// minimized. Nil when no exec is declared.
	ExecImage *ExecImageSpec `json:"execImage,omitempty"`
	// HostLink is the host link's image, where the release declares a
	// target host: built on this machine from the pinned
	// base and the runner image, as the files image is.
	HostLink *HostLinkSpec `json:"hostLink,omitempty"`
	// Browser is the browser server's image, where the release declares
	// capabilities.browser: pulled by digest, never built.
	Browser *BrowserSpec `json:"browser,omitempty"`
	// Render is the page renderer, for a plan with CapSummary.WebRender.
	Render *RenderSpec `json:"render,omitempty"`
	// Harness describes the adapter and the agent container.
	Harness HarnessSpec `json:"harness"`
	// Proxy describes the LLM egress proxy sidecar.
	Proxy ProxySpec `json:"proxy"`
	// Docker is the daemon-facing part of the policy the plan was compiled
	// under; absent when the policy set none, so a plan compiled before the
	// knob and one compiled without it are the same bytes.
	Docker *DockerSpec `json:"docker,omitempty"`
	// Secrets lists the manifest secret env names (values are resolved at
	// run time and never stored).
	Secrets []string `json:"secrets,omitempty"`
	// OptionalSecrets are the declared secrets, the release's own or a
	// declared server's, that its manifest marks optional
	// (capabilities.optionalSecrets): a run starts without
	// one it has no value for and the gateway sets it empty. Absent when the
	// manifest marks none, so such a plan carries no trace of the field.
	OptionalSecrets []string `json:"optionalSecrets,omitempty"`
	// InputView is the view the input tools serve an input in when the model
	// asks for none, from the manifest's inputs.view: "text" or "original".
	// Absent for a release that declares neither, whose inputs keep their own
	// defaults, so such a plan carries no trace of the field.
	InputView string `json:"inputView,omitempty"`
	// MCPServers are the declared, resolved MCP servers this plan loads
	// alongside the tools server. Empty for agents that
	// declare none, whose plans carry no trace of the field.
	MCPServers []MCPServerSpec `json:"mcpServers,omitempty"`
	// Budgets are the compiled defaults; run flags replace them, a
	// built-in package's run on this computer starts from its own
	// (localrun.Builtin.LocalBudgets), and the receipt records what
	// actually applied.
	Budgets Budgets `json:"budgets"`
	// Output describes the optional structured-output convention.
	Output OutputSpec `json:"output"`
	// Managed are the organizations' managed settings the plan was
	// compiled under, one entry a document: a new version is a new plan.
	// Absent when no document applies, so such a plan carries no trace of
	// the field.
	Managed []ManagedSpec `json:"managed,omitempty"`
	// Files maps plan-dir-relative generated file paths to their sha256,
	// so a tampered installed plan is detectable before execution.
	Files map[string]string `json:"files"`
}

Plan is the whole compiled run plan. Every field is exported and JSON-stable; Hash() covers the canonical encoding.

func ParsePlan

func ParsePlan(b []byte) (*Plan, error)

ParsePlan decodes and version-checks a stored plan.json.

func (*Plan) Conversational

func (p *Plan) Conversational() bool

Conversational says the plan runs as a conversation the harness serves on its stdio (Harness.Session): an interactive plan, or a persistent one, whose harness half is the interactive one and whose conversation outlives each start of it.

func (*Plan) GatewayRuntime

func (p *Plan) GatewayRuntime() string

GatewayRuntime is the OCI runtime the plan asks for the gateway, or "" for the daemon's default.

func (*Plan) Hash

func (p *Plan) Hash() (string, error)

Hash returns the sha256 hex of the canonical encoding — the run_plan_sha256 every receipt carries.

func (*Plan) IsOptionalSecret

func (p *Plan) IsOptionalSecret(name string) bool

IsOptionalSecret reports whether the plan's manifest marks the declared secret name optional: a run starts without it.

func (*Plan) MarshalCanonical

func (p *Plan) MarshalCanonical() ([]byte, error)

MarshalCanonical renders the plan as stable, human-diffable JSON. Go's encoding/json emits struct fields in declaration order and sorts map keys, which is exactly the determinism the golden tests pin.

func (*Plan) PaysWithCredits added in v0.6.1005

func (p *Plan) PaysWithCredits() bool

PaysWithCredits says the plan's model is paid for with Agentry credits: its harness reads a credits session token (EnvVar.FromInference), which the host must open before the run starts.

func (*Plan) Runtime

func (p *Plan) Runtime() string

Runtime is the OCI runtime the plan asks for, or "" for the daemon's default.

func (*Plan) SandboxResolvers

func (p *Plan) SandboxResolvers() []string

SandboxResolvers are the name servers the run's containers under its runtime that resolve host names read: the llm-proxy, the MCP server install proxy and the relays. None without a runtime, or without resolvers, and those classes then stay on the daemon's default.

func (*Plan) ToolsImage

func (p *Plan) ToolsImage() string

ToolsImage is the image the plan's tools server runs in: the QuickAgent's exec image when it declares commands, the runner image otherwise. The compiler chooses it; the engine reads it here.

func (*Plan) WebResolvers

func (p *Plan) WebResolvers() []string

WebResolvers are the name servers the plan's tools server resolves through when it reaches past the host (CapSummary.ToolsReachPastHost), or none for docker's embedded DNS: only such a plan reads them here (the compiler also records them under a runtime, for SandboxResolvers).

type ProxySpec

type ProxySpec struct {
	// Image is the locally built runner image tag.
	Image string `json:"image"`
	// Allow is the host:port allowlist (policy model endpoints only).
	Allow []string `json:"allow"`
	// PlainHTTP is the subset of Allow the proxy may forward plain http
	// to: the http model endpoints the operator's policy names. Empty for
	// a run whose model endpoints are all https.
	PlainHTTP []string `json:"plainHttp,omitempty"`
}

ProxySpec is the LLM egress proxy sidecar.

type RenderSpec

type RenderSpec struct {
	Image string `json:"image"`
}

RenderSpec is a run's page renderer (CapSummary.WebRender): the browser image the engine runs once a page, never a server the model can call.

type ResumeSpec added in v0.7.27

type ResumeSpec struct {
	// SessionDB is the container path of the harness's conversation store.
	SessionDB string `json:"sessionDb"`
	// StoreOwner is the user, as the harness image knows it, that must own
	// the store, given to it before the harness starts as a session's is
	// (SessionSpec.StoreOwner). Empty leaves the volume as docker made it.
	StoreOwner string `json:"storeOwner,omitempty"`
}

ResumeSpec is an autonomous harness's resumable conversation.

type SavedModelRef added in v0.7.39

type SavedModelRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

SavedModelRef names a saved model: its id, which never changes, and the person's name for it. Never a credential.

type ServerShare

type ServerShare string

ServerShare is how a server sees a persistent agent's share folder (MCPServerSpec.Share).

const (
	// ServerShareMirror: the share mirror (PHShareMirror), for an agent
	// whose share is checked.
	ServerShareMirror ServerShare = "mirror"
	// ServerShareLive: the share folder itself, read only, for the Coding
	// agent, whose share is read as it is.
	ServerShareLive ServerShare = "live"
)

The ways a server sees the share.

type SessionBudgets

type SessionBudgets struct {
	// IdleTimeoutSeconds is the longest silence from the user.
	IdleTimeoutSeconds int `json:"idleTimeoutSeconds"`
	// MaxWallSeconds is the whole-session deadline.
	MaxWallSeconds int `json:"maxWallSeconds"`
	// MaxUserTurns caps user messages (0 = unlimited).
	MaxUserTurns int `json:"maxUserTurns"`
}

SessionBudgets are the interactive caps: the engine ends the session with a session_end receipt when any is reached, never hangs.

type SessionSpec

type SessionSpec struct {
	// Transport is "acp-stdio".
	Transport string `json:"transport"`
	// ProtocolVersion is the ACP protocol version the client negotiates.
	ProtocolVersion int `json:"protocolVersion"`
	// SessionDB is the container path of the harness's session store.
	SessionDB string `json:"sessionDb"`
	// Mounts are added to the agent container for a session only: the
	// writable session store under PHSession, which the engine resolves to
	// a per-run named volume.
	Mounts []Mount `json:"mounts,omitempty"`
	// StoreOwner is the user, as the harness image knows it, that must
	// own the session store: a fresh volume is root-owned wherever it is
	// mounted, and the harness runs unprivileged, so the engine gives the
	// store to this user once, as root in the harness image on no network,
	// before the harness starts. Empty leaves the volume as docker made
	// it.
	StoreOwner string `json:"storeOwner,omitempty"`
	// Safety is the harness safety mode the generated config declares
	// (the ACP server has no flag): always "autonomous" — the gateway,
	// not in-harness prompting, is the boundary, and the runner answers
	// any permission request with a denial.
	Safety string `json:"safety"`
	// Budgets are the session caps the engine enforces (tightened by the
	// manifest's interactive hints).
	Budgets SessionBudgets `json:"budgets"`
	// RestartOnRenewal says the harness reads its model sign-in's access
	// token once, when it starts: before a turn, when the runner has
	// renewed the token since, the engine starts the harness again and the
	// driver resumes the conversation (policy signInTokenRoute restart).
	RestartOnRenewal bool `json:"restartOnRenewal,omitempty"`
	// ConversationArgs, for a harness told its conversation on its command
	// line, are the flags the engine adds to the agent's argv at each start
	// of a persistent agent's segment. Nil for a harness that names its
	// conversation over the session itself, and for every other plan.
	ConversationArgs *ConversationArgs `json:"conversationArgs,omitempty"`
}

SessionSpec is the interactive drive of the harness: the runner is the Agent Client Protocol client on the agent container's attached stdio. Everything else about the container is the autonomous plan's.

type Skill

type Skill struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

Skill is one skill a persistent agent has: its folder's name beneath AgentRoot/AgentSkillsDir and the description its SKILL.md gives.

type ToolFilterDiff added in v0.6.1009

type ToolFilterDiff struct {
	// CaseOnly are the entries that match a listed tool only ignoring case.
	CaseOnly []CaseOnlyMatch
	// Absent are the entries that match no listed tool even ignoring case.
	Absent []string
}

ToolFilterDiff is how a declared server's tool filter reads against the tool names the server lists.

func DiffToolFilter added in v0.6.1009

func DiffToolFilter(filter, listed []string) ToolFilterDiff

DiffToolFilter reads a tool filter against the names a server lists. An entry equal to a listed name is fine; one equal to a listed name only when case is ignored is a CaseOnly match (naming the first such listed name in sorted order); any other is Absent. Entries come back in sorted order, each once.

func (ToolFilterDiff) CaseMessage added in v0.6.1009

func (d ToolFilterDiff) CaseMessage() string

CaseMessage says, for each case-only entry, which exact name to write. It is "" when there is none.

func (ToolFilterDiff) Empty added in v0.6.1009

func (d ToolFilterDiff) Empty() bool

Empty says every entry names a listed tool exactly.

type UnplacedCommand

type UnplacedCommand struct {
	Command    string   `json:"command"`
	Candidates []string `json:"candidates,omitempty"`
}

UnplacedCommand is a declared command Unsafe Mode's image cannot place, with the packages that ship it when there are several (the base's ambiguous list), so the plan can say why.

type UnsafeExecSpec

type UnsafeExecSpec struct {
	// Base is the unsafe base image, pinned by digest (policy
	// images.unsafe), whose command index and extras list placed the
	// commands.
	Base string `json:"base"`
	// Apt are the declared commands the base's index placed, each with its
	// Kali package, sorted by command: a package that fails to install
	// names the commands it leaves absent.
	Apt []AptPlacement `json:"apt,omitempty"`
	// Extras are the declared commands placed by the base's extras list,
	// sorted by command.
	Extras []UnsafeExtra `json:"extras,omitempty"`
	// Unplaced are the declared commands neither the extras list nor the
	// index could place: the run goes ahead without them, and the
	// plan, the consent and the receipt name them. Sorted by command.
	Unplaced []UnplacedCommand `json:"unplaced,omitempty"`
}

UnsafeExecSpec is what an Unsafe Mode exec image adds to the catalogue's: the base it is built from and how each declared command was placed. This machine's exec catalogue was not consulted.

type UnsafeExtra

type UnsafeExtra struct {
	Command string    `json:"command"`
	Kind    ExtraKind `json:"kind"`
	// Spec is the pip requirement, name==version.
	Spec string `json:"spec,omitempty"`
	// Package and Path are a link's package and its path inside it.
	Package string `json:"package,omitempty"`
	Path    string `json:"path,omitempty"`
}

UnsafeExtra is one extras-list recipe for a declared command.

func (UnsafeExtra) String

func (e UnsafeExtra) String() string

String is the recipe as the plan and the receipt name it.

Jump to

Keyboard shortcuts

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