compile

package
v0.7.14-dev.4 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 41 Imported by: 0

Documentation

Overview

Package compile is the capability compiler: it turns manifest + operator policy into the run plan — generated gateway file set, tools-server spec, harness definition, and container topology. This is the layer that makes the registry's declared contract mean something at run time, so its two properties are non-negotiable: deterministic output (golden tests pin plan bytes) and one testable control per contract line (the Enforcement map states each mechanism).

YAML node construction for the generated gateway files. Built on yaml.Node rather than Go maps for one reason: plan bytes must be deterministic, and explicit node trees make key order a decision, not an iteration-order accident.

Index

Constants

View Source
const GatewayConfigDir = "/root/.docker/mcp/catalogs"

GatewayConfigDir is where the rendered gateway files are mounted inside the gateway container. It must be the gateway's own catalogs directory: since v0.43 a local --catalog path "must resolve within Docker MCP catalogs directory" (pkg/catalog, errUntrustedLocalPath) and the gateway exits at startup otherwise. HOME is pinned to /root in the container env so the directory is the same on every host.

View Source
const IntegrityFile = "plan.json.hmac"

IntegrityFile is the record's name beside plan.json.

View Source
const IntegrityKeyFile = integritykey.File

IntegrityKeyFile is the key's name directly under the runner home.

View Source
const LoopbackAlias = hostpin.LoopbackAlias

LoopbackAlias is the name a model endpoint on this computer's loopback (localhost, 127.0.0.1, ::1) is given in the plan of a harness that runs in a container. An HTTP client never sends a request for localhost or a loopback address through its proxy, and the harnesses' NO_PROXY names localhost and so every name under it, so the harness would dial its own container's loopback and find nothing. The alias is proxied like any other name, and the engine pins it to the container engine's host gateway for a run on this computer. The proxy's allowlist names the alias in place of the loopback host, with the same port.

View Source
const MaxSkills = 100

MaxSkills is how many skills a persistent agent's plan carries.

View Source
const OutputSchemaFile = "output.schema.json"

OutputSchemaFile is the structured-output convention.

Variables

View Source
var ErrNoIntegrityRecord = errors.New("installed plan has no integrity record from this runner home")

ErrNoIntegrityRecord reports an installed plan with no record this runner home can check: missing, unreadable, malformed, or made under another key. The caller recompiles.

View Source
var MemorySkills = []string{"memory-compact", "memory-consolidate", "memory-ingest", "memory-query"}

MemorySkills are the skills the memory capability brings, which its compaction and consolidation turns name: given to any agent that declares capabilities.persistent.memory, whether or not it declares skills.

Functions

func AppLinkCommand

func AppLinkCommand(set string) []string

AppLinkCommand is the app link's command in its catalog entry, which the run's docker filter knows its container by.

func AppLinkSet added in v0.6.1017

func AppLinkSet(p *manifest.Persistent) string

AppLinkSet is the app link tool set a persistent agent's declared capabilities give it: the parts of the keys p declares; "" for none.

func Compile

func Compile(in Inputs, planDir string) (*spec.Plan, error)

Compile builds the plan and writes the generated file set under planDir:

planDir/plan.json
planDir/gateway/{catalog,registry,config,tools}.yaml + toolspec.json
planDir/harness/<adapter files>

The returned plan's Files map hashes every generated file, so a tampered installed plan is detectable before execution. planDir is replaced whole: whatever it held before is gone once Compile returns.

func CompileOutputSchema

func CompileOutputSchema(raw []byte) (*jsonschema.Schema, error)

CompileOutputSchema compiles output.schema.json bytes (draft 2020-12 by default, whatever $schema names otherwise) into a validator the engine runs the final message through.

func ConnectionFolder

func ConnectionFolder(serverName string) string

ConnectionFolder is a remote server's connection folder, in plan placeholders: under the run's cfg directory, never under cfg/gateway, which is the gateway's own mount.

func DeclaredImageServers added in v0.6.1018

func DeclaredImageServers(p *manifest.Persistent) []string

DeclaredImageServers are the keys of the image servers p declares.

func DeclaredServerGatewayFiles

func DeclaredServerGatewayFiles(servers []spec.MCPServerSpec) (map[string][]byte, error)

DeclaredServerGatewayFiles renders the gateway's catalog.yaml, registry.yaml, config.yaml and tools.yaml for declared MCP servers alone, each catalog entry exactly as a run renders it (mcpServerEntry), keyed by file name. It is for a tool that launches declared servers the way a run does with no QuickAgent around them: the MCP server survey (scripts/mcp-server-survey). The volume still names spec.PHServers; the caller substitutes its server store, as the engine does.

func GatewayGuardFlags

func GatewayGuardFlags() []string

GatewayGuardFlags are the guards every gateway a run starts is given, after its transport and files: --block-network, without which allowHosts is advisory, then the guards the gateway defaults on, passed explicitly so a run never inherits one it depends on from a version's default. --block-secrets is default true in the pinned gateway and passed anyway: the refusal of a secret-looking tool result is in the enforcement table the receipts answer to, and a version whose default flipped would drop the guard while the receipt still claimed it. The MCP server survey starts its gateway with them too (scripts/mcp-server-survey).

func IntegrityKey

func IntegrityKey(home string) ([]byte, error)

IntegrityKey returns the runner home's integrity key, creating it on first use (integritykey.Load; the installed-release record uses the same key).

func PersistentImageServer added in v0.6.1018

func PersistentImageServer(name string) (string, bool)

PersistentImageServer is the key of the image server this build runs for name, an entry of capabilities.persistent.imageServers; false for a name it does not carry.

func ReadInstalledPlan

func ReadInstalledPlan(key []byte, planDir string) ([]byte, error)

ReadInstalledPlan returns planDir/plan.json's bytes only after checking them against the integrity record: fs.ErrNotExist when there is no plan, ErrNoIntegrityRecord when the record cannot vouch for it (the caller recompiles), *TamperedPlanError when it vouches against it (the caller refuses). Every read of an installed plan for execution goes through here.

Another process may recompile the same plan directory while this one reads it (two runs of one release and mode started together; the CLI and the desktop recompile each other's plans). A plan read from one compile and a record from the next disagree although nothing was edited, and would be refused as tampering. Compile publishes a whole directory in one rename and the reads go through one handle on the directory, so they see one compile; an older client may still write the files in place. So the record is also read on both sides of the plan, and a pair is judged only when the two record reads agree: a record that changed, vanished or appeared meanwhile means a recompile was in flight, and the reads are taken again. A mismatch between a steady record and the plan is re-read too, after a pause, and only a mismatch that persists through every attempt is reported as tampering.

func ReadInstruction

func ReadInstruction(workspace string, in spec.InstructionSpec) (string, error)

ReadInstruction reads the instruction a plan was compiled from out of a workspace and returns its prose as the compile read it: frontmatter stripped, without the System Prompt. The text is held to the body's digest the plan records, so what it returns is the instruction the plan was built on, whichever client ran it and whether or not that client checked the workspace. The engine sends it as the task of a run given none. A plan with no body digest was compiled before the System Prompt and is refused: it is recompiled, never reinterpreted.

func Seal

func Seal(key []byte, planDir string) error

Seal records planDir/plan.json, as it is now, as this home's compile. Compile does this itself when given the key; Seal is for a plan.json rewritten by the runner's own code.

func SecretKey

func SecretKey(envName string) string

SecretKey is the gateway secrets-file key for a declared env name. One definition shared by the catalog entry and the engine's secrets.env writer, so they cannot drift.

func ServerSecretKey

func ServerSecretKey(serverName, envName string) string

ServerSecretKey is the gateway secrets-file key for a declared server's env name — server-scoped, so a value reaches its own server and nothing else. Shared with the engine's secrets.env writer.

func ShareChecksFolder

func ShareChecksFolder() string

ShareChecksFolder is the run's folder of the share's malware verdicts, under its cfg directory: the engine writes it, the tools server reads it.

func TurnsFolder added in v0.6.999

func TurnsFolder() string

TurnsFolder is the run's turn count folder, under its rendered config.

func VerifyFiles

func VerifyFiles(p *spec.Plan, planDir string) error

VerifyFiles re-hashes an installed plan's generated files, refusing a tampered plan dir before anything runs.

Types

type Inputs

type Inputs struct {
	// CompiledBy is the CLI build recorded in the plan (see
	// spec.Plan.CompiledBy); empty in tests and goldens.
	CompiledBy string
	// Manifest is the verified package manifest.
	Manifest *manifest.Manifest
	// Mode is the run mode to compile for; empty means autonomous. A mode
	// the manifest does not declare is refused (exit 12: not runnable
	// this way).
	Mode manifest.Mode
	// Digest is the verified archive digest (or local-tree digest).
	Digest string
	// Source is "registry", "local", or "builtin" for a package this binary
	// embeds (pkg/runner/localrun).
	Source string
	// WorkspaceDir is the extracted, verified archive (read-only here:
	// the compiler reads prompt files and the optional output schema).
	WorkspaceDir string
	// Policy is the validated operator policy; PolicySHA fingerprints
	// the exact bytes it was loaded from.
	Policy    *policy.Policy
	PolicySHA string
	// AdapterName selects the harness adapter ("" = default).
	AdapterName string
	// RunnerImage is the local runner image tag.
	RunnerImage string
	// MCPServers are the declared servers, already resolved against the
	// trusted registries. Resolution happens in the install step, not here:
	// the compiler stays offline and deterministic over its inputs.
	MCPServers []spec.MCPServerSpec
	// Web grants a built-in the web tools, web_search and web_read (the
	// Drafter's and the Knowledge Creator's). Only a built-in package may
	// be granted them (Source "builtin", set by pkg/runner/localrun for the
	// Drafter and the Knowledge Creator alone), and only one that declares
	// no egress, exec, filesystem write, secret or MCP server: their
	// container has no network allowlist of its own, so nothing else may
	// run beside them. Anything else asking is refused by policy (exit 11).
	Web bool
	// RegistrySearch adds registry_search to the web tools: the Drafter's
	// alone. It is compiled, never the run's, so a run that hands the tools
	// a registry for its scans (a hosted build) does not get the tool with
	// it. Only with Web.
	RegistrySearch bool
	// WebSearchedOnly holds web_read to the addresses a web_search of the
	// run returned (toolsrv.Web.SearchedOnly): the Knowledge Creator's,
	// whose model reads documents no one scanned. Only with Web.
	WebSearchedOnly bool
	// WebGivenOnly holds web_read to the addresses the person gave the run
	// (toolsrv.Web.GivenOnly): the Voice Writer's. Never with
	// WebSearchedOnly.
	WebGivenOnly bool
	// WebRender lets web_read render a thin page in a one-shot browser
	// the engine runs (spec.CapSummary.WebRender): the Knowledge Creator's.
	// Only with Web.
	WebRender bool
	// Review grants a built-in the review grant: ai_review and scanned
	// reads of its inputs, with the person's own TypeSafe key in the tools
	// container alone, whose network reaches TypeSafe's API and nothing
	// else. As with Web, only a built-in package may be granted it, and
	// only one that declares no egress, exec, filesystem write, secret or
	// MCP server; never beside the web tools, whose container reaches any
	// public address. Anything else asking is refused by policy.
	Review bool
	// IntegrityKey is the runner home's plan-integrity key (IntegrityKey).
	// It is not part of the plan: when set, the compile also writes
	// plan.json.hmac, so a later run can reuse the plan only as compiled
	// (ReadInstalledPlan). Nil writes no record, and a reader then
	// recompiles rather than trust the plan.
	IntegrityKey []byte
	// Unsafe turns on Unsafe Mode for this compile: the declared exec
	// commands are placed through the unsafe base's extras list and command
	// index (unsafeexec.Load) instead of the policy's exec catalogue, which
	// is not consulted; a command neither places is named, never refused.
	// Only a client passes it — the desktop, for runs on this computer,
	// when the person has turned Unsafe Mode on — and no policy key or CLI
	// flag sets it. Nil compiles without Unsafe Mode.
	Unsafe *unsafeexec.Data
	// AgentFiles grants a persistent built-in its own folders: its data
	// volume, and the person's share folder when the agent has it on. The
	// filesystem tools, grep and glob are rooted at spec.AgentRoot then.
	// Only a persistent plan of a built-in that declares no filesystem
	// access of its own is granted them; anything else asking is refused by
	// policy.
	AgentFiles *spec.AgentFiles
	// AppLink grants a persistent built-in its app link, by the tool set it
	// lists (runnerimage/applink): a server of the gateway's with no
	// network, bound to the supervisor's socket alone. Like AgentFiles it is
	// a persistent built-in's alone, refused to anything else.
	AppLink string
	// Subagents says the agent's roster names subagents, whose tools its
	// app link may then list (applink.PartSubagents): the subagents its
	// release pins or the person added. An author's folder has none.
	Subagents bool
	// Coder grants the Coding agent what its roster has on (spec.CoderGrant):
	// any program in its own exec image, open egress, the browser on any
	// public site, the person's dev server. Its gate is the person's
	// agreement for that agent, not the machine policy's
	// allowWildcardEgress or browser.allowPublicWeb, so like AgentFiles it is
	// a persistent built-in's alone, beside its folders, and refused to
	// anything else.
	Coder *spec.CoderGrant
	// Calendar grants a persistent Assistant the calendar feeds its roster
	// has on (spec.CalendarGrant): the calendar tools, each feed's address
	// in the tools container alone, whose network reaches the feeds' hosts
	// on 443 and nothing else. A persistent built-in's alone, beside its
	// folders, which declares no egress of its own; refused to anything
	// else.
	Calendar *spec.CalendarGrant
	// ShareServers are the declared MCP servers, by source id
	// (MCPServerSpec.SourceID), that see a persistent agent's share folder,
	// read only: the copies the share check passed where the share is
	// checked, the folder itself for the Coding agent. Only a package
	// server with no network, of a persistent built-in that has its share,
	// may be given it; anything else asking is refused by policy.
	ShareServers []string
}

Inputs is everything a compile consumes. No run-scoped values belong here (determinism); the engine substitutes those at execute time.

type PolicyRefusal

type PolicyRefusal struct{ Reason string }

PolicyRefusal is a run refused by operator policy — the exit-11 class, distinct from a malformed package (exit 12).

func (*PolicyRefusal) Error

func (e *PolicyRefusal) Error() string

type TamperedPlanError

type TamperedPlanError struct{ PlanDir string }

TamperedPlanError reports a plan.json that does not match the record this runner home wrote for it.

func (*TamperedPlanError) Error

func (e *TamperedPlanError) Error() string

Jump to

Keyboard shortcuts

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