Documentation
¶
Overview ¶
Package engine executes a compiled run plan: render the plan's placeholder-bearing files into a per-run directory, resolve secrets, stand up the run-scoped network + proxy + gateway + agent containers, stream and budget the harness event stream, collect the result envelope, and tear everything down on every exit path. The engine trusts the plan (compile owns policy) and owns exactly the run-scoped values plans must not contain: paths, tokens, secret values.
Knowledge attached to a run. The compiled plan always mounts one read-only /knowledge volume on the tools container, as it mounts /inputs, and grants no knowledge tool: which packs a run reads is the person's choice at run time, like its input files, so it must not move the plan or its hash. The engine copies each attached pack into the run, verifies the copy against the digest its caller checked, and only then grants the three tools — in the run's own copies of the tools spec and the gateway's allowlist, as it stamps the owner — and names what it mounted in the receipt.
The review grant at run time. The compiled plan grants it (spec.CapSummary.ReviewTools, toolsrv.Review.Enabled) and gives the tools container TypeSafe's API as its one host; the run brings the person's key. The engine refuses a run of such a plan without the key before anything starts, writes the key into the run's gateway secrets file for the tools container alone, stamps the ledger into the run's copy of the tools spec, and counts the ledger into the receipt.
What a session's driver permits beyond the run's own grant. A declared MCP server's tools are named by the server at run time unless its manifest filters them, and docker-agent asks the client's permission for every tool not marked read-only, so the session asks the gateway what it serves (the probe's --list-tools, from inside the run network) and permits that too. The gateway's allowlist stays the enforcement; the permit only stops refusing what the gateway routes.
Engine support: run-dir preparation, placeholder rendering, secret and env resolution, teardown. This file owns exactly the run-scoped values the plan must not contain: host paths, the gateway token, and secret values — and the guarantee that the last two die with the run.
A declared server's manifest tool filter becomes the gateway's allowlist (tools.yaml), which the gateway matches against the tool names the server lists exactly, case included. A filter entry that differs from the real name only in case therefore matches nothing, and the tool is dropped without a word. The runner learns a server's real names only from the server, so the check runs when the gateway has started: it reads how many tools the gateway enabled for each filtered server, and for one that enabled fewer than its filter names, it asks the server itself for its tool list (a throwaway container with no network) to say which entry differs only in case, and what to write. A case-only entry stops the run before the agent starts; an entry that matches no tool at all is reported and the run goes on, as it always has.
A Writing Voice attached to a run. It rides on knowledge's path: the compiled plan already mounts one read-only /knowledge volume on the tools container, so the engine writes the voice's VOICE.md under it, at .voice/ — a name no pack can take, since a pack's name starts with a letter or a digit — and grants voice_read in the run's own copies of the tools spec and the gateway's allowlist. Attaching a voice moves neither the plan nor its hash. The run's copy dies with the knowledge directory at teardown.
The built-in Drafter's web tools at run time. The compiled plan grants the tools (spec.CapSummary.WebTools, toolsrv.Web.Enabled); where a run scans and searches is the run's own, since one plan serves a draft made on this computer with the person's keys and one made in Agentry with the job's credential. The engine stamps that half into the run's copy of the tools spec, rebuilds the tools server's line of the gateway allowlist from it, writes the keys into the run's gateway secrets file for the tools container alone, and counts the tools' ledger into the receipt.
Index ¶
- Constants
- Variables
- func DesktopBindRefusal(d *spec.DesktopCap, r *desktop.Refusal) error
- func DesktopBindRequest(d *spec.DesktopCap, run, ref, digest, outDir string) desktop.BindRequest
- func EngineLine(ctx context.Context, d dockerx.Client) (string, error)
- func ExitClassOf(code int) receipt.ExitClass
- func ExportVolume(ctx context.Context, d dockerx.Client, image, volume, runtime string, ...) error
- func ExportVolumePaths(ctx context.Context, d dockerx.Client, image, volume string, paths []string, ...) error
- func HoldWorkDir(dir string) (release func(), err error)
- func HostedDesktopRefusal(ids []string) error
- func HostedSignInRefusal(kind string) error
- func HostedTargetHostRefusal(ids []string) error
- func ImportIntoVolume(ctx context.Context, d dockerx.Client, image, volume, top, sub string, ...) error
- func InferenceReceipt(v inference.View, model string) receipt.Inference
- func IsPackNameTaken(err error) (string, bool)
- func JSONResult(text string, schema *jsonschema.Schema) (json.RawMessage, error)
- func KeyringValue(account string) (string, error)
- func ListCopilotModels(ctx context.Context, d dockerx.Client, p CopilotModelsParams) (models []adapter.CopilotModel, err error)
- func NewRunID() (string, error)
- func NoDesktopRefusal(d *spec.DesktopCap) error
- func OwnSignInDir(home, dir string) bool
- func PersistentVolumeLabels(agent, home string) map[string]string
- func ReadCallsLedger(file string) ([]toolsrv.CallEntry, error)
- func ReadDeliverablesLedger(file string) ([]toolsrv.DeliverableEntry, error)
- func ReadDocumentLedger(p string) ([]toolsrv.DocumentEntry, error)
- func ReadFetchLedger(file string) ([]toolsrv.SaveEntry, error)
- func ReadPDFLedger(file string) ([]toolsrv.PDFEntry, error)
- func ReadPreviewLedger(p string) ([]toolsrv.PreviewEntry, error)
- func ReadReviewLedger(path string) ([]toolsrv.ReviewEntry, int, error)
- func ReadWebLedger(path string) ([]toolsrv.LedgerEntry, int, error)
- func RecoverJSONResult(text string, schema *jsonschema.Schema) (res json.RawMessage, dropped int, err error)
- func Redeliver(ctx context.Context, d dockerx.Client, p RedeliverParams) ([]receipt.Delivery, error)
- func RelaysStartedBy(logs string) []string
- func ReportStage(onStage func(Stage), st Stage)
- func ResolveSecret(name string, overrides map[string]string, src policy.SecretSource) (string, bool)
- func Run(ctx context.Context, d dockerx.Client, p Params) (outEnv *receipt.Envelope, outErr error)
- func RunImageOneShot(ctx context.Context, d dockerx.Client, o ImageOneShot) (stdout, stderr string, code int, err error)
- func RunsInUse(runRoot string) []string
- func SecretResolvable(name string, overrides map[string]string, src policy.SecretSource) bool
- func ShareFolderUsable(dir string) error
- func ShareMirrorBeside(dir string) (staging, index string)
- func StartSession(ctx context.Context, d dockerx.Client, p Params) (session.Session, error)
- func StopLeftPodmanService(dir, runnerHome, runID string)
- func SweepAbandoned(ctx context.Context, d dockerx.Client, stderr io.Writer)
- func SweepWorkDirs(root, prefix string, grace time.Duration, stderr io.Writer) []string
- type AttachedPack
- type AttachedVoice
- type ClassifiedError
- type ConnectionToken
- type ConversationCompactor
- type ConversationRenewer
- type CopilotModelsParams
- type DesktopLink
- type ImageOneShot
- type InferenceGrant
- type MessengerLink
- type MessengerParams
- type ModelSignInGrant
- func CopilotSignIn(ctx context.Context, store *modelsignin.Store) (*ModelSignInGrant, func(context.Context) (ConnectionToken, error), error)
- func ModelSignInFor(ctx context.Context, store *modelsignin.Store, plan *spec.Plan, hosted bool) (*ModelSignInGrant, func(context.Context) (ConnectionToken, error), error)
- type PackNameTaken
- type Params
- type PersistentMemory
- type PersistentSegment
- type PersistentSession
- type RedeliverParams
- type ReportTheme
- type ReviewRun
- type ShippedFrom
- type SourceFetcher
- type Stage
- type ThemeSource
- type WebRun
Constants ¶
const ( PreviewLedgerFile = "previews.ndjson" PreviewsDir = "previews" // DocumentLedgerFile records each image document_pages showed of the // person's document and each crop crop_logo took, from which the CLI // takes the logo it keeps. DocumentLedgerFile = "document.ndjson" )
The Report Designer's previews: render_preview records each in a ledger under the receipts folder and keeps its PNG in a folder beside it, from which the CLI takes the thumbnail of the cover it keeps.
const ( ExitOK = 0 ExitCLI = 1 // ExitUsage: the invocation cannot work as asked (interactive without a // terminal, an output format the mode cannot produce). ExitUsage = 2 ExitVerify = 10 ExitPolicy = 11 ExitCompile = 12 ExitGateway = 13 ExitHarness = 14 ExitTimeout = 15 ExitBudget = 16 ExitOutputSchema = 17 // ExitBlocked: the agent could not do the task with what the run had, // by its own end_blocked or by the runner's evidence (blocked.go). A // release's one-shot run alone. ExitBlocked = 18 )
Exit codes. The distinguishable failure classes are the runner's composability contract: a cron job or pipeline branches on these, so each class has exactly one meaning.
const ( PersistentLabel = "agentry.persistent" PersistentHomeLabel = "agentry.persistent.home" )
PersistentLabel keys a persistent agent's volumes by the agent's name, and PersistentHomeLabel by the runner home they belong to. Neither is the run label: the volumes outlive every segment.
const AppLinkRelayLog = "applink-relay.log"
AppLinkRelayLog is the receipt the relay's own errors go to.
const CallsLedgerFile = "calls.ndjson"
CallsLedgerFile is the calls ledger under the run's receipts.
const CopilotModelsTimeout = 3 * time.Minute
CopilotModelsTimeout bounds one list: the containers' start, Copilot CLI's own start, GitHub's two answers.
const DeliverableMessageFile = "reports/deliverable.md"
DeliverableMessageFile is where the runner writes a run's final message when it is all the run produced.
const DeliverablesLedgerFile = "deliverables.ndjson"
DeliverablesLedgerFile is the deliverables ledger under the run's receipts.
const DesktopLinkRelayLog = "desktop-relay.log"
DesktopLinkRelayLog is the receipt the relay's own errors go to.
const DockerSocket = dockerx.DefaultSocket
DockerSocket is the daemon socket the gateway mounts to launch the tool containers — the one path in a run that belongs to the machine. It is the compiled plan's name for the daemon's socket on every engine; the run maps it to the engine's own (placement.go), so the plan does not depend on the engine.
const EnvDockerFilter = "AGENTRY_DOCKER_FILTER"
EnvDockerFilter overrides the placement rule on a machine it misjudges: "process" or "sidecar".
const FetchLedgerFile = "fetches.ndjson"
FetchLedgerFile is the fetch ledger under the run's receipts.
const MaxBucketStaged int64 = 1 << 30
MaxBucketStaged is the most bytes of deliverables a bucket's step is given copies of in all; a file past what is left is listed as too large.
const MaxInputReviewCalls = 400
MaxInputReviewCalls is the most calls AI Review makes of one run's inputs, a session's added files, the calls asked again and those that name a flagged file included: the registry's cap of scans a run (the runs extension's runInputScans), which refuses a call past it and so the run. reviewRetryBudget of them are kept for asking again, and reviewCalls read the texts and name a flagged file. A file whose texts would take the calls past what is left, keeping room to name a flagged file, is withheld, unasked, as a file past MaxInputReviewText is. Packed as packer packs them, 16 MiB of text takes about 260 to 275 calls whatever the sizes of its texts, so a run meets this only with very many small texts (2,000 small HTML files, read as uploaded, as text and as Markdown, are 375 calls) or a session that adds a great many files.
const MaxInputReviewText = 16 << 20
MaxInputReviewText is the most text AI Review reads of one run's inputs, a session's added files included, so that one credit cannot buy an unbounded number of judge requests. A file whose texts do not fit in what is left is withheld, unasked: no text AI Review has not read reaches the agent. The hosted upload cap is 10 MiB, so only an archive that unpacks to much more, or a session that adds a great deal, meets it.
const MaxObjectBytes = send.DefaultMaxObject
MaxObjectBytes is the most one object sent to a bucket is.
const MaxWebhookBody = send.DefaultMaxBody
MaxWebhookBody is the most a webhook body is, in bytes.
const MemoryCarriedDir = ".carried"
MemoryCarriedDir is the folder of PersistentMemory.Seed whose files are appended to the memory's when PersistentMemory.Carry was copied in.
const PDFLedgerFile = "pdfs.ndjson"
PDFLedgerFile is the PDF ledger under the run's receipts.
const PortRelayLog = "port-relay.log"
PortRelayLog is the receipt of what the relay published and refused.
const RelayLabel = "docker-mcp-proxy=true"
RelayLabel is the label the gateway puts on every relay sidecar. The MCP server survey reads it too (scripts/mcp-server-survey).
const RelayLockFile = "relays.lock"
RelayLockFile is the host-level lock a run whose plan needs relays holds from its relay listing to the end of its teardown. It lives directly under the runner home, which every client on the host shares (the CLI, the desktop, runhost's runner home).
const ReviewLedgerFile = "review.ndjson"
ReviewLedgerFile is the review ledger in the receipts directory.
const RunLockFile = "run.lock"
RunLockFile is the lock a run holds on its own run directory, <RunRoot>/runs/<id>/run.lock, from before anything sensitive is written into the directory to the end of its teardown. The kernel releases it when the process dies however it dies, so a later run that can take the lock knows the directory's run is over: that is how a run killed before its teardown (SIGKILL, an OOM kill, a supervisor's timeout, a power cut) has its secrets file, its connections' tokens and its other sensitive files removed by the next run of the same install. Unlike the owner labels the container sweep judges by, the lock needs no process record, so it holds on every platform and across pid namespaces. It is a lock on the open file (flock, LockFileEx), so two runs of one process exclude each other as two processes do; the runner home is taken to be on a local file system, where that holds.
ShareChecksLog is the receipt each check of the share appends to: one JSON line a file checked.
const StageDetailResume = "resume"
StageDetailResume is the agent step's detail when the harness is continuing the stored conversation.
const StageSignIn = "sign-in"
StageSignIn is the step of a start that readies the model's sign-in: a subscription's sign-in (Claude, ChatGPT, Copilot) taken from the store and renewed when it has to be. The other steps reuse the receipt's names (receipt.Stage*).
const VoiceChannelDir = ".voice"
VoiceChannelDir is the voice's directory in the run's knowledge channel.
const WebLedgerFile = "web.ndjson"
WebLedgerFile is the web ledger in the receipts directory.
const WorkLockFile = "work.lock"
WorkLockFile is the lock a process holds on a work directory of its own, <dir>/work.lock, from just after it makes the directory until it has deleted it. Like a run's lock (RunLockFile) the kernel releases it when the process dies however it dies, so a later process that can take it knows the directory's owner is gone and what it left in the clear, the documents of a knowledge build, their decoded text and its pages, can be removed.
Variables ¶
var ErrNoCompaction = errors.New("the harness cannot compact its conversation on request")
ErrNoCompaction is a CompactConversation refused because the segment's harness cannot compact its conversation on request.
var ErrNoNewConversation = errors.New("the harness cannot start a new conversation while it runs")
ErrNoNewConversation is a NewConversation refused because the segment's harness cannot start a new conversation while it runs: a new segment is the way to one.
var ErrNoReviewKey = errors.New("a review runs only with your own TypeSafe key, and this run has none")
ErrNoReviewKey is the refusal of a review-grant run without the person's key (as a draft on this computer is refused without one).
var ExitClasses = receipt.ExitClasses
ExitClasses is the exit-class table: for each exit code above, its name, its one-phrase meaning and whether a retry with the same inputs is likely to help. The rows live in the receipt package, which renders them into every envelope and which this package depends on; they are reachable here beside the codes they describe, and the test in this package holds the table and the constants to one another so neither gains an entry alone.
var VoiceFile = path.Join(spec.KnowledgeMount, VoiceChannelDir, voice.File)
VoiceFile is the voice's path in the tools container.
var WorkspaceOwnership bool
WorkspaceOwnership says this engine runs as a remote runhost's service account, where every container runs under gVisor and has no Landlock: a command that may write its workspace is then held by file ownership (toolsrv.Spec.WorkspaceOwnership). The runhost's CLI sets it.
Functions ¶
func DesktopBindRefusal ¶ added in v0.7.28
func DesktopBindRefusal(d *spec.DesktopCap, r *desktop.Refusal) error
DesktopBindRefusal is the refusal of a run whose bind the link service refused: exit 11, desktop-refused, with the service's reason.
func DesktopBindRequest ¶ added in v0.7.33
func DesktopBindRequest(d *spec.DesktopCap, run, ref, digest, outDir string) desktop.BindRequest
DesktopBindRequest is the bind of run for desktop line d of release ref: each application server with the tools the release gives it, and computer use in its scope with the folder of outDir where the person's kept screenshots go (none when outDir is empty).
func EngineLine ¶
EngineLine is d's engine and where a run's docker filter would run on it, in the receipt's words, or why a run would be refused.
func ExitClassOf ¶ added in v0.6.1012
ExitClassOf is the table's row for an exit code (receipt.ExitClassOf).
func ExportVolume ¶
func ExportVolume(ctx context.Context, d dockerx.Client, image, volume, runtime string, lim policy.Limits, w io.Writer) error
ExportVolume writes the files of the named volume to w as a tar archive, in a one-shot of image (the runner image): no network, the volume read-only, DAC_READ_SEARCH alone so every file of it is read, under the runtime and the limits a run's containers have. The one-shot carries a run's labels of its own, so a sweep removes it if this process dies.
func ExportVolumePaths ¶ added in v0.7.1
func ExportVolumePaths(ctx context.Context, d dockerx.Client, image, volume string, paths []string, runtime string, lim policy.Limits, w io.Writer) error
ExportVolumePaths is ExportVolume for the named paths of the volume alone, each clean and relative to its root: a path that is a link is written as the link, never followed.
func HoldWorkDir ¶
HoldWorkDir locks the work directory dir, which must exist, and returns the function that lets the lock go. It is called before anything sensitive is written into the directory and again, before the directory is deleted: on Windows an open file cannot be deleted, nor the directory holding it.
func HostedDesktopRefusal ¶ added in v0.7.28
HostedDesktopRefusal is a hosted run's refusal of a release that declares the person's computer: exit 11, desktop-refused, hosted. The CLI refuses with it before anything is installed, and the engine again.
func HostedSignInRefusal ¶
HostedSignInRefusal is the refusal of a model sign-in for a hosted run.
func HostedTargetHostRefusal ¶
HostedTargetHostRefusal is a hosted run's refusal of a release that declares target hosts: exit 11, host-refused, hosted. The CLI refuses with it before anything is installed, and the engine again.
func ImportIntoVolume ¶ added in v0.7.1
func ImportIntoVolume(ctx context.Context, d dockerx.Client, image, volume, top, sub string, r io.Reader, runtime string, lim policy.Limits) error
ImportIntoVolume writes the tar archive r into a new folder, sub, beneath the folder top at the root of the named volume, in a one-shot of image (the runner image): no network, the archive on stdin, and the capabilities the copy needs to write into a folder another user owns and to give what it wrote that user. Top and sub are each one name of letters, digits and hyphens; the archive is the caller's own, holding folders and regular files alone.
func InferenceReceipt ¶ added in v0.6.1005
InferenceReceipt is a session's final view as the receipt records it.
func IsPackNameTaken ¶
IsPackNameTaken reports whether err is WithShipped's refusal, and names the pack.
func JSONResult ¶
func JSONResult(text string, schema *jsonschema.Schema) (json.RawMessage, error)
JSONResult is the output convention for a json-kind result, as the run itself applies it: a host post-step that recovers an answer from a message the run refused holds it to exactly this (the Examiner's).
func KeyringValue ¶ added in v0.7.28
KeyringValue reads a keychain account once for the process, as the run's own resolution does: a caller that needs the model's key before the run (the context-window probe) shares the run's one read, and so its one unlock prompt and its one value.
func ListCopilotModels ¶
func ListCopilotModels(ctx context.Context, d dockerx.Client, p CopilotModelsParams) (models []adapter.CopilotModel, err error)
ListCopilotModels lists the models the signed-in Copilot plan offers, through Copilot CLI in a run's container (see above). The Copilot image must be on the machine already (setup builds it).
func NewRunID ¶
NewRunID mints a run identifier. Exported because the CLI derives the default output folder name from it before handing it to Run.
func NoDesktopRefusal ¶ added in v0.7.28
func NoDesktopRefusal(d *spec.DesktopCap) error
NoDesktopRefusal is the refusal of a run that declares the person's computer where no Agentry Desktop answers: exit 11, desktop-refused, desktop-unavailable, naming the applications.
func OwnSignInDir ¶
OwnSignInDir reports whether dir may hold a config-directory sign-in: a docker volume named agentry-…, or a directory strictly under the runner home's model sign-in store (home empty: volumes only).
func PersistentVolumeLabels ¶
PersistentVolumeLabels are the labels a persistent agent's volumes carry: the agent's name and the runner home's identity.
func ReadCallsLedger ¶
ReadCallsLedger reads a run's calls ledger (receipts/calls.ndjson). A missing ledger is none; a line that does not decode is skipped, as no evidence either way.
func ReadDeliverablesLedger ¶
func ReadDeliverablesLedger(file string) ([]toolsrv.DeliverableEntry, error)
ReadDeliverablesLedger reads a run's deliverables ledger. A missing ledger is none, and so is anything that is not a regular file; a line that does not decode is skipped, and a ledger is read only to its caps.
func ReadDocumentLedger ¶ added in v0.7.26
func ReadDocumentLedger(p string) ([]toolsrv.DocumentEntry, error)
ReadDocumentLedger reads a document ledger, skipping a line that does not decode.
func ReadFetchLedger ¶
ReadFetchLedger reads a run's fetch ledger. A missing ledger is none; a line that does not decode is skipped.
func ReadPDFLedger ¶
ReadPDFLedger reads a run's PDF ledger. A missing ledger is none; a line that does not decode is skipped.
func ReadPreviewLedger ¶ added in v0.7.23
func ReadPreviewLedger(p string) ([]toolsrv.PreviewEntry, error)
ReadPreviewLedger reads a preview ledger, skipping a line that does not decode.
func ReadReviewLedger ¶
func ReadReviewLedger(path string) ([]toolsrv.ReviewEntry, int, error)
ReadReviewLedger reads a run's review ledger (receipts/review.ndjson): its entries, and how many lines did not decode. A missing ledger is none.
func ReadWebLedger ¶
func ReadWebLedger(path string) ([]toolsrv.LedgerEntry, int, error)
ReadWebLedger reads a run's web ledger (receipts/web.ndjson): its entries, and how many lines did not decode. A missing ledger is none.
func RecoverJSONResult ¶
func RecoverJSONResult(text string, schema *jsonschema.Schema) (res json.RawMessage, dropped int, err error)
RecoverJSONResult applies the run's JSON convention to a terminal object in a refused message, for a built-in's post-step. Only a standalone closing fence may follow it. dropped is the byte offset of the object in the trimmed message; the original message stays in the receipts. The run itself still uses the strict JSONResult convention.
func Redeliver ¶
func Redeliver(ctx context.Context, d dockerx.Client, p RedeliverParams) ([]receipt.Delivery, error)
Redeliver sends the result and the deliverables an existing run folder's envelope lists to the destinations, and adds the records to its receipts/ deliveries.ndjson. result.json and every other file of the folder are left as they are. An error is returned only when there is nothing to deliver: a folder that is not a run's, a run that did not succeed.
func RelaysStartedBy ¶
RelaysStartedBy returns the relay sidecars the gateway's log says it started, in log order, each once. Exported for the MCP server survey, which starts the gateway itself and reaps its relays the same way (scripts/mcp-server-survey).
func ReportStage ¶
ReportStage calls onStage with the stage, when there is a hook; a nil hook does nothing. A hook that panics is ignored: a start tears down what it made only on its own failure paths, and a client's report must never skip them and leave the gateway or the harness running.
func ResolveSecret ¶ added in v0.6.1019
func ResolveSecret(name string, overrides map[string]string, src policy.SecretSource) (string, bool)
ResolveSecret is name's value as a run resolves it: the overrides (an MCP profile, the intake's secret answers) first, then the policy source. A device that hands a run to a remote runhost resolves each secret here, so the run there has the values this computer's run would.
func Run ¶
Run executes the plan. The returned envelope is always usable — on failure it carries status "error", the exit class, and whatever was known — and the returned error (nil on success) is already classified.
func RunImageOneShot ¶ added in v0.6.999
func RunImageOneShot(ctx context.Context, d dockerx.Client, o ImageOneShot) (stdout, stderr string, code int, err error)
RunImageOneShot runs o and returns what it wrote to stdout, and its exit code. Every container it starts is hardened as a run's are, with a read-only root and a small /tmp, and is removed, with the proxy's network, whatever the outcome.
func RunsInUse ¶
RunsInUse lists, sorted, the runs under runRoot/runs whose lock a live run holds, in this process or any other: what a client asks before it removes something a run of the same release may be using, such as the release's profile. A directory whose lock is free, or that has none, is not listed.
func SecretResolvable ¶
SecretResolvable reports whether name would resolve at run time: from the overrides (an MCP profile) first, then the policy source — the same order writeSecretsFile uses, exposed so `agentry doctor` can predict an exit-11 refusal without starting anything. Values never leave here.
func ShareFolderUsable ¶
ShareFolderUsable says whether dir can be a share folder as it stands: an absolute path to a folder that is not a link. Where it may be is the caller's to say (the persistent package refuses the runner's own folders and the system's); this is the engine's last look before it binds it.
func ShareMirrorBeside ¶
ShareMirrorBeside are the staging folder and the index the engine keeps beside the share mirror dir (PersistentSegment.ShareMirror).
func StartSession ¶
StartSession does everything Run does up to and including the sandbox, then starts the harness's interactive server on the agent container's attached stdio and returns the session. The plan must be an interactive plan (Mode interactive, Harness.Session set): it is byte-identical to the autonomous plan except the harness argv and that block, so the sandbox — network, proxy, gateway, mounts, secrets — is exactly the autonomous one. The task text, if any, is the opening user turn.
func StopLeftPodmanService ¶
func StopLeftPodmanService(dir, runnerHome, runID string)
StopLeftPodmanService ends the podman API service the run directory dir of run runID names in its record, when the run that started it is gone (the directory's lock proved it, runlock.go), before the directory and the record go. dir is the caller's to trust; the record in it is a file the person can write, and a sweep that signals a process and unlinks a file holds it to the one shape a run's service can have rather than believing it. The socket is removed only at the one path the run gives its service (podmanServiceSocket: under the runner home's s/ directory by the run's id, the short path under the system's temp directory, or the run directory's own when there is no runner home). The process is signalled only when its start time is the recorded one (a reused pid is never signalled), its own command line is a podman binary running the `system service` subcommand, and that command line names the run's own socket, so the service of another run is never ended by a record naming its pid. The record always goes. Off Linux no start time or command line can be read, so no process is touched there. Best effort: nothing here fails the sweep. Exported for the desktop app, whose own sweeps reach a dead run's directory the same way.
func SweepAbandoned ¶
SweepAbandoned removes, before a run builds anything, the containers an earlier run on this host left behind when its process died without tearing down — a SIGKILL, an OOM kill, a power cut: the paths no defer and no recover reaches. A container qualifies only when its owner labels prove its creator gone (owner.Dead): created from this process's boot, pid namespace and uid, by a pid that is no longer the process that started it. A sibling run's containers are never touched, however old; nor is anything created before the owner labels existed, by another user, from another pid namespace, or anywhere off Linux (no labels are written there). For each removed run container the run's networks and volumes go too, after the containers: its session volume by name and every volume carrying its run label, the gateway's /misc among them.
Best effort and bounded: the sweep never fails a run, and it tells the person what it removed and what it could not. Run and StartSession call it, then sweep the dead runs' files (sweepAbandonedRun); exported so `agentry run` can sweep before its MCP server installs, whose fixed container names a leftover installer would collide with. A run network or volume whose containers were already gone when the process died has nothing left here to name it (a labelled volume's owner labels are not read), and off Linux no container is judged here at all; the run's directory lock does both, and the sweep a run or a session starts with (sweepAbandonedRun) removes them by it.
func SweepWorkDirs ¶
SweepWorkDirs removes the work directories under root whose names begin with prefix and whose owner is gone: a directory whose lock can be taken is a dead process's, and one whose lock is held is a live process's and is left alone. A directory with no lock file belongs to a process that died, or is starting, between making it and locking it, and nothing sensitive is written before the lock, so it goes only once it is older than grace.
Best effort: it never fails the caller. It says what it removed on stderr, and names a directory it could not delete, which may hold documents in the clear. It returns the names it removed, sorted.
Types ¶
type AttachedPack ¶
type AttachedPack struct {
// Dir is the pack's directory. The engine copies it; it is never
// mounted itself.
Dir string
// Name is the pack's name, and its mount /knowledge/<Name>.
Name string
// Digest is the tree digest the caller verified ("sha256:<hex>").
Digest string
Pages int
Bytes int64
Scan knowledge.Scan
// Shipped is set for a pack the release ships in its own archive: its
// trust is the release's, the attestation over the archive and the
// scan of the version, not its own manifest's scan record. Nil for a
// pack the person attaches.
Shipped *ShippedFrom
}
AttachedPack is one knowledge pack attached to a run: where its plaintext tree is on the host, and what the caller verified it to be.
func AttachPack ¶
func AttachPack(p *knowledge.Pack) AttachedPack
AttachPack is the attachment of a pack knowledge.Load verified.
func ShippedPacks ¶
func ShippedPacks(workspaceDir string, m *manifest.Manifest, release string) ([]AttachedPack, error)
ShippedPacks loads the knowledge packs a release ships: each knowledge/<name>/ its manifest's knowledge.ships names, from the release's own files in workspaceDir. Those are the files the archive digest and the attestation cover — for a built-in package, its embedded tree, which Materialize holds to its digest — so what the run mounts is what was verified and never re-fetched. Each pack must load as the CLI's format and name itself; one that does not is a verification failure, since the registry refuses such a release at submit (V11). release names the release's bytes for the receipt ("archive sha256:…"). The engine copies each pack into the run and verifies the copy as it does an attached pack.
func WithShipped ¶
func WithShipped(shipped, attached []AttachedPack) ([]AttachedPack, error)
WithShipped puts a release's shipped packs before the attached ones, refusing (ExitCLI, a *PackNameTaken) an attached pack that takes a shipped pack's name.
type AttachedVoice ¶
type AttachedVoice struct {
Text []byte
Digest string
// Origin is the receipt's account of the voice: "kept on this
// computer, made by the Voice Writer, not reviewed", or the account's
// live voice as a hosted run's driver names it.
Origin string
}
AttachedVoice is a Writing Voice attached to a run: its text, held in memory by the caller (it is at most voice.MaxBytes), the digest the caller verified, and how the receipt names where it came from.
func AttachVoice ¶
func AttachVoice(text []byte, origin string) (*AttachedVoice, error)
AttachVoice is the attachment of a voice's text, checked against the format and digested here, so a caller cannot name a digest the text does not have.
type ClassifiedError ¶
ClassifiedError pairs an error with its exit class so main can exit precisely without string-matching.
func Classify ¶
func Classify(code int, err error) *ClassifiedError
Classify wraps err with an exit class.
func (*ClassifiedError) Error ¶
func (e *ClassifiedError) Error() string
func (*ClassifiedError) Unwrap ¶
func (e *ClassifiedError) Unwrap() error
type ConnectionToken ¶
ConnectionToken is the part of a connection a run is given: an access token and when it expires (zero when the vendor did not say).
type ConversationCompactor ¶ added in v0.6.999
type ConversationCompactor interface {
CanCompact() bool
CompactConversation(ctx context.Context) error
}
ConversationCompactor is a PersistentSession whose harness may compact its conversation in place (liveSession's, where the adapter's driver is adapter.Compacting; ErrNoCompaction otherwise). CanCompact says which.
type ConversationRenewer ¶ added in v0.6.999
type ConversationRenewer interface {
NewConversation(ctx context.Context, reason string) (string, error)
}
ConversationRenewer is a PersistentSession that can start a new conversation in its running harness (liveSession's, where the adapter's driver is adapter.Renewing; ErrNoNewConversation otherwise).
type CopilotModelsParams ¶
type CopilotModelsParams struct {
// Policy supplies the Copilot image (images.harness's copilot-image),
// docker.limits, docker.runtime and docker.resolvers.
Policy *policy.Policy
// CopilotPlan is the person's Copilot plan (policy.CopilotPlans), which
// names the Copilot API host the proxy allows.
CopilotPlan string
// RunnerImage is the runner image, which the proxy runs.
RunnerImage string
// SignIn and RenewSignIn are the Copilot sign-in and its renewal, as a
// run's (Params.ModelSignIn, Params.RenewModelSignIn; CopilotSignIn
// reads them from the person's store).
SignIn *ModelSignInGrant
RenewSignIn func(ctx context.Context) (ConnectionToken, error)
// Stderr receives Copilot CLI's own stderr; nil discards it.
Stderr io.Writer
}
CopilotModelsParams is one Copilot model list's.
type DesktopLink ¶ added in v0.7.28
type DesktopLink struct {
// Token is the run token the link service issued at bind; every call
// carries it.
Token string
// Servers are the bound application servers' tools, by catalogue id, as
// the link service listed them from each installed server.
Servers map[string][]desktoplink.Tool
// Call sends one tool call to the link service. A refusal is returned
// as a *desktop.Refusal.
Call func(ctx context.Context, req desktop.CallRequest) (desktoplink.Answer, error)
// Unbind ends the binding at teardown.
Unbind func(ctx context.Context) error
// FarEnd says how the link service is reached, for the receipt.
FarEnd string
// Computer is the computer use the link service bound, where the plan
// declares it.
Computer *desktop.ComputerBound
}
DesktopLink is a run's binding to Agentry Desktop, as the caller hands it to the engine.
func BoundDesktopLink ¶ added in v0.7.28
BoundDesktopLink is a binding over the link service's socket, as a run from the CLI makes it.
func RelayedDesktopLink ¶ added in v0.7.33
func RelayedDesktopLink(r desktop.Relayed) *DesktopLink
RelayedDesktopLink is a binding made on another computer and relayed to this run (a run on a remote runhost, whose device bound it): each call and the unbind name the run the far link service bound, over the relay's socket here.
type ImageOneShot ¶ added in v0.6.999
type ImageOneShot struct {
// Image is the server's pinned image, run by its own entrypoint and as
// its own user.
Image string
Argv []string
// Volume is the server's volume, mounted at Target.
Volume, Target string
// Env is passed by name through the client's environment, never in
// argv (dockerx.RunSpec.Env).
Env map[string]string
Stdin io.Reader
// Egress are the hosts (host:port) the command may reach, through a
// CONNECT proxy of its own that reaches them alone at the addresses this
// machine resolves for them; empty runs it with no network.
Egress []string
// ProxyImage is the runner image, whose proxy role is that proxy.
ProxyImage string
Runtime string
Limits policy.Limits
// Stdout, when set, is also given the command's stdout as it comes, for
// a step that must show something while it runs (a sign-in's code).
Stdout io.Writer
}
ImageOneShot is one command of a persistent built-in's image server, run outside a segment on the server's own volume: its sign-in's steps.
type InferenceGrant ¶ added in v0.6.1005
type InferenceGrant struct {
Session string
Token string
// Model is the model the registry forwards to, for the receipt.
Model string
RenewEvery time.Duration
// Renew, when set, is called every RenewEvery for as long as the run
// lives. Nil leaves renewing to the caller (a persistent agent's
// supervisor, whose session outlives each start of its harness).
Renew func(ctx context.Context) error
// End, when set, ends the session once the run's containers are gone
// and answers its final view for the receipt. Nil leaves ending to the
// caller.
End func(ctx context.Context) (receipt.Inference, error)
}
InferenceGrant is the Agentry credits session a run pays for its model with (model provider agentry): the session's token, which the harness presents to the registry's model endpoint as its key, and how the session is kept alive and ended. The person's registry sign-in is never part of it.
func InferenceFor ¶ added in v0.6.1005
func InferenceFor(ctx context.Context, c *inference.Client, plan *spec.Plan, hosted bool, purpose string, stderr io.Writer) (*InferenceGrant, error)
InferenceFor opens the credits session a plan that pays with Agentry credits needs, for Params.Inference: nil when the plan spends a key or a sign-in. A hosted run is refused before anything is asked: its model is the platform's. Every local client calls it: `agentry run`, a built-in's run (localrun) and the desktop's run path.
type MessengerLink ¶ added in v0.7.12
type MessengerLink struct {
// contains filtered or unexported fields
}
MessengerLink is a running messenger role.
func StartMessenger ¶ added in v0.7.12
func StartMessenger(ctx context.Context, d dockerx.Client, p MessengerParams) (_ *MessengerLink, err error)
StartMessenger starts p's relay and role and returns once the service took the credential (the role's ready line). The containers carry a run's labels and this process's owner labels, so a sweep removes them if this process dies without closing the link.
func (*MessengerLink) Close ¶ added in v0.7.12
func (l *MessengerLink) Close(ctx context.Context)
Close stops the role and removes its containers and networks.
func (*MessengerLink) Frames ¶ added in v0.7.12
func (l *MessengerLink) Frames() <-chan messenger.FromRole
Frames are the role's lines after its ready line; closed when the role ends.
func (*MessengerLink) Ready ¶ added in v0.7.12
func (l *MessengerLink) Ready() messenger.Ready
Ready is the account as the service named it when the role connected.
type MessengerParams ¶ added in v0.7.12
type MessengerParams struct {
// Kind is the messenger, Token the account's credential, and Peer the
// person paired with the agent, if any.
Kind messenger.Kind
Token string
Peer *messenger.Peer
// Server is the account's own server, for a kind whose accounts name
// one (a Matrix homeserver): the one host its relay reaches.
Server string
// Image is the runner image.
Image string
Policy *policy.Policy
// Dir is a folder of the account's own, for the relay's resolv.conf.
Dir string
// Log gets the role's and the relay's own errors: never the
// credential, never a message.
Log io.Writer
}
MessengerParams start one messenger account's role.
type ModelSignInGrant ¶
type ModelSignInGrant struct {
// Kind is the sign-in's kind (policy.IsModelSignIn), which the run
// holds against the kind its plan was compiled for.
Kind string
// Token is the access token of a token-file sign-in: an access token
// alone, never the refresh token or a client secret.
Token ConnectionToken
// ConfigDir is a config-directory sign-in's directory: an absolute
// host path, or the name of a docker volume, which the harness alone
// reads and writes.
ConfigDir string
}
ModelSignInGrant is what a run is given of the person's model sign-in.
func CopilotSignIn ¶
func CopilotSignIn(ctx context.Context, store *modelsignin.Store) (*ModelSignInGrant, func(context.Context) (ConnectionToken, error), error)
CopilotSignIn is the person's Copilot sign-in from their store, for CopilotModelsParams: as a run on a Copilot plan is given it (ModelSignInFor). No sign-in is modelsignin.ErrNoSignIn, wrapped.
func ModelSignInFor ¶
func ModelSignInFor(ctx context.Context, store *modelsignin.Store, plan *spec.Plan, hosted bool) (*ModelSignInGrant, func(context.Context) (ConnectionToken, error), error)
ModelSignInFor is the model sign-in a plan spends, from the person's store, for Params.ModelSignIn and Params.RenewModelSignIn: nil when the plan spends a key. A hosted run is refused before the store is read: a sign-in is the person's own, local only, permanently. No sign-in of the plan's kind is the receipt reason signin-missing.
Every local client calls it: `agentry run`, a built-in's run (localrun), and the desktop's run path.
type PackNameTaken ¶
type PackNameTaken struct{ Name string }
PackNameTaken is an attached pack whose name a shipped pack already takes: a run mounts each pack at /knowledge/<name>, so the two cannot both be mounted. Each caller words the refusal for its own surface.
func (*PackNameTaken) Error ¶
func (e *PackNameTaken) Error() string
type Params ¶
type Params struct {
// Plan is the verified, compiled plan; PlanDir is where it and its
// generated files live (install layout).
Plan *spec.Plan
PlanDir string
// WorkspaceSrc is the pristine verified workspace to copy per run.
WorkspaceSrc string
// CheckWorkspace, when set, is handed the run's copy of WorkspaceSrc
// before anything reads it, and an error refuses the run with the
// verify class: an installed release's copy is held to its integrity
// record there (installdir.CheckCopy), so an edit made to the
// install after the client's own check does not run.
CheckWorkspace func(copyDir string) error
// RunRoot is where runs/<id>/ ephemera live (the install dir).
RunRoot string
// RunnerHome is the runner home, shared by every client on the host.
// A run whose plan needs relays holds its relay lock (RelayLockFile)
// for the whole run. Empty takes no lock, leaving the relay listing
// as the only check.
RunnerHome string
// OutDir is the mounted output folder, already absolute.
OutDir string
// Task is the task input (may be nil for an empty task). An empty
// task on the autonomous path sends the agent's own instruction
// instead.
Task io.Reader
// InputPaths are operator-provided files/directories copied into the
// run's read-only inputs channel.
InputPaths []string
// Knowledge are the knowledge packs attached to the run: each copied
// into the run's read-only /knowledge channel and verified there, the
// three knowledge tools granted and the receipt's knowledge line
// written only when there is one.
Knowledge []AttachedPack
// Voice is the person's Writing Voice when the run attaches it:
// written under the run's /knowledge channel, voice_read granted and
// the receipt's voice line written only then. A built-in's run never
// carries one.
Voice *AttachedVoice
// DeliverTo, when set, is an absolute folder the run copies its
// deliverables to once it has succeeded: <DeliverTo>/<QuickAgent>/<date
// time> <title or run id>/, each file only after its SHA-256 is shown to be
// the one the envelope's deliverables block names. The output folder is
// left as it is; the copies are recorded in the envelope's deliveries
// block and receipts/deliveries.ndjson. Empty delivers nothing.
DeliverTo string
// Destinations are the places the person asked the run to send its
// result and deliverables to, saved by name with their credentials read
// (destination.Resolve). The delivery step runs for each once the run has
// succeeded and its containers are gone; a failed delivery is recorded and
// never changes the run. Nothing but the person's own choice puts a
// destination here: no manifest, plan or QuickAgent names one. Empty runs
// no delivery step.
Destinations []destination.Resolved
// ReportTheme is the report design export_pdf lays the run's PDFs out
// with, and what chose it: a design document, or a built-in theme's id;
// neither is the default, Plain. The type keeps its v1 name so that a
// caller passing a built-in's id (the desktop) still builds. Used only
// when the plan grants export_pdf.
ReportTheme ReportTheme
// Decoded, when set, is the decode step the caller ran on the inputs
// before this run (pkg/runner/decode); the receipt names it.
Decoded *decode.Result
// Enforced are receipt lines the caller adds to CapabilitiesEnforced,
// keyed as the receipt's: a knowledge build's sources, fetched before
// this run by the step a run's own sources take.
Enforced map[string]string
// TextInputs says the caller staged only files it made itself (every
// built-in: localrun.Run sets it): the engine does not decode them.
// Otherwise a run's inputs are decoded before the agent starts.
TextInputs bool
// InputReview, when set, is AI Review of the inputs' text before the
// agent starts (review.go): a hosted run's, through the registry with
// the job's credential. A flagged input refuses the run, and a
// session's added file alone. Nil reviews nothing, as every local run.
InputReview webscan.Scanner
// Hosted says the run is a sandbox host's (its driver marks it: a run
// grant, a job's credential, AGENTRY_HOSTED). A hosted run's browser
// opens public sites only. A run with InputReview set is hosted whatever
// this says.
Hosted bool
// HostedRender lets a sandbox host's run render pages for a rendered
// web_read: its driver dispatched it as a browser job, whose slots count
// the renderer beside the run. A hosted run without it renders nothing.
HostedRender bool
// EndBlocked grants end_blocked and the calls ledger (blocked.go): the
// run ends blocked, not ok, when its agent says it could not do the task
// or the ledger shows the runner's tools failed it. A release's one-shot
// run sets it; a built-in, which has outcomes of its own, does not, and
// a session refuses it.
EndBlocked bool
// Web is the built-in Drafter's web configuration and keys (web.go):
// required for a plan with the web tools, refused for any other.
Web *WebRun
// Review is a review-grant run's key (review.go): required for a plan
// with the review grant, refused for any other.
Review *ReviewRun
// Intake holds the answers to the manifest's up-front questions: staged
// as /inputs/intake.json, file answers staged like inputs, secret
// answers already merged into SecretOverrides by the caller.
Intake *intake.Answers
// Adapter interprets the harness event stream.
Adapter adapter.Adapter
// Policy supplies the secret source.
Policy *policy.Policy
// PolicyFile names the operator policy file Policy was read from and
// how its path was chosen (policy.Resolve); the envelope records it
// with the plan's policySha256 as its digest. Nil leaves the
// envelope's policy block out.
PolicyFile *policy.File
// SecretOverrides resolve declared secrets ahead of the policy source
// — the QuickAgent's MCP profile rides in here; the engine itself
// stays profile-agnostic. A persistent agent's stored secrets that are
// on ride here too, and are the values of the Coding agent's programs'
// secrets (spec.CoderGrant.Secrets).
SecretOverrides map[string]string
// WithheldSecrets are a persistent agent's stored secrets its roster
// has off: a declared secret of one of these names is written empty,
// and the policy source is not asked for it.
WithheldSecrets []string
// AccountTokens are the tokens of the Coding agent's git host accounts
// its plan names (spec.CoderGrant.Accounts), by each one's TokenEnv:
// the tools container's alone, never a server's.
AccountTokens map[string]string
// CalendarURLs are the addresses of the Assistant's calendar feeds its
// plan names (spec.CalendarGrant.Feeds), by each one's URLEnv, and the
// browser sign-ins of those that have one, by each one's SessionEnv:
// the segment's, read from the keychain, for the tools container alone.
CalendarURLs map[string]string
// Connections are the access tokens of the servers that sign in by
// OAuth, keyed by spec.MCPServerSpec.ConnectionKey (a remote server's
// address, a package server's "pypi:name"): the caller refreshed each
// from the person's connection (pkg/runner/connection). An access token
// is all a run is given of one; a server with none here refuses the
// run.
Connections map[string]ConnectionToken
// RenewConnection, when set, is asked for a new access token for a
// server (by its ConnectionKey) before the one the run holds expires:
// the engine rewrites the server's connection folder with it, which a
// bridge and a server that re-reads its token file pick up. Nil leaves
// each token as given for the whole run.
RenewConnection func(ctx context.Context, server string) (ConnectionToken, error)
// ModelSignIn is what the run is given of the person's model sign-in
// when its plan spends one (spec.HarnessSpec.ModelSignIn, signin.go):
// an access token alone, or the harness's own config directory. The
// run refuses one its plan was not compiled for, and a plan that
// spends one refuses to run without it. Never set by a hosted run's
// driver.
ModelSignIn *ModelSignInGrant
// RenewModelSignIn, when set, is asked for a new access token for a
// token-file sign-in before the one the run holds expires; the engine
// rewrites the token file with it. Nil leaves the token as given.
RenewModelSignIn func(ctx context.Context) (ConnectionToken, error)
// Inference is the Agentry credits session the run pays for its model
// with, when its plan names model provider agentry (InferenceFor): the
// session's token alone reaches the harness. The engine renews it and
// ends it when the grant says so. A plan that pays with credits
// refuses to run without it.
Inference *InferenceGrant
// ServersDir is the signature's installed MCP-server store,
// substituted for the PHServers placeholder. Required when the plan
// declares MCP servers; unused otherwise.
ServersDir string
// Budgets are the effective hard stops (plan defaults merged with
// any tighter run flags by the caller).
Budgets spec.Budgets
// Attestation is the verify-gate outcome for the envelope.
Attestation receipt.Attestation
// ExecPackages are the catalogued packages' resolved versions the exec
// image build recorded ("name-version"); appended to the receipt's
// exec line so it names what was installed.
ExecPackages []string
// KeepRunDir preserves runs/<id>/ for debugging (secrets.env is
// still always deleted).
KeepRunDir bool
// RunID names the run; "" mints one. The CLI passes the id it used
// for the default output folder so the two always agree.
RunID string
// Stderr receives progress and diagnostics.
Stderr io.Writer
// OnStage, when set, is called as a session's start reaches each of
// its steps (Stage), so a client can say what it is doing. Nil does
// nothing; a run (Run) reports none.
OnStage func(Stage)
// OnUsage, when set, is called every time the harness reports usage,
// with the run's running totals. It is what lets a driver meter a run
// while it is live: the envelope's usage arrives only at the end, so
// without this nothing could enforce a token cap during the run.
// Called from the stream-consuming goroutine, in order, and never
// after the harness stream closes.
//
// It MUST NOT BLOCK. That goroutine is also what enforces --max-turns
// and --max-cost, and its end is what releases teardown, so a
// callback that waits stops the budgets and leaves containers up. A
// callback that panics is caught and switched off rather than allowed
// to take the teardown down with it.
OnUsage func(receipt.Usage)
// Events, when set, receives the harness event stream as JSON lines
// while the run is live — the same lines the receipt's events.ndjson
// gets, redacted the same way. A driver tails this instead of parsing
// the narration (--events). It must not block, for the same reason
// OnUsage must not: it is written from the same goroutine, on the same
// terms as the receipt's own copy.
Events io.Writer
// OnEvent, when set, receives each normalized harness event of an
// autonomous run while it is live, in order: the tool calls, each
// tool's result, the assistant's text, the usage and the harness's
// errors. An interactive session streams its own events and does not
// call it. A tool result whose harness did not repeat the tool's name
// carries the name of the call it answers, and its text is cut to
// adapter.ToolExcerptMax. The assistant's streamed chunks arrive
// joined, one event per message, when the message ends. Every text is
// masked with the run's secret values before it is cut, so no part of
// one reaches the driver; Raw is left out (Events has the lines). It
// is called on the terms of OnUsage: from the stream-consuming
// goroutine, never after the harness stream closes, and it MUST NOT
// BLOCK; one that panics is switched off and the run goes on.
OnEvent func(adapter.Event)
// Persistent makes a session one segment of a persistent agent: the
// plan must be persistent, and the session store is the agent's own
// volume, which outlives the segment. Nil for every other run.
Persistent *PersistentSegment
// Desktop is the run's binding to Agentry Desktop, for a plan that
// declares the person's computer (spec.CapSummary.Desktop): the caller
// binds before the sandbox starts and hands the result in. Nil for
// every other run, and for one no Agentry Desktop answered, which the
// engine refuses.
Desktop *DesktopLink
// contains filtered or unexported fields
}
Params configures one run.
type PersistentMemory ¶
type PersistentMemory struct {
// Volume is the volume's name.
Volume string
// Seed is what the volume is filled with when it is seeded, by path
// beneath it: a file, its folders made for it, or a folder of its own
// where the path ends in "/". A file beneath MemoryCarriedDir is
// appended to the file of the same path beneath the memory, and only
// when Carry was copied in; that folder itself is not kept.
Seed map[string][]byte
// Carry, when set, is a folder beneath the data volume that the seed
// copies to CarryTo beneath the memory when it holds anything: files
// and folders, never a link. The data volume's folder is left as it is.
Carry, CarryTo string
// Seeded says an earlier start seeded the volume. Unset, a volume
// that exists is seeded too, unless it already holds the seed's
// SCHEMA.md: a start stopped between making the volume and seeding it
// leaves it empty.
Seeded bool
}
PersistentMemory is a persistent agent's memory volume: made, labelled and kept like its other two, mounted read-write into the tools server alone, and seeded once.
func (*PersistentMemory) VolumeName ¶
func (m *PersistentMemory) VolumeName() string
VolumeName is the memory's volume; empty for none.
type PersistentSegment ¶
type PersistentSegment struct {
// Agent is the agent's name (its built-in's name).
Agent string
// Segment numbers this start among the agent's segments, from 1.
Segment int
// SessionVolume and DataVolume are the agent's two volumes. The session
// volume is mounted where the harness keeps its conversation; neither
// carries the run's label, so neither the segment's teardown nor a
// sweep of a dead run removes it.
SessionVolume, DataVolume string
// Home identifies the runner home the agent belongs to: the volumes
// carry it in a label, so what lists or removes them acts on this
// home's alone.
Home string
// LegacySessionVolume and LegacyDataVolume, when set, are the volumes
// named by the agent alone (legacy names), which every runner home on
// the engine could use. Set only for an agent this home has already run:
// when one of the agent's volumes does not exist yet and its legacy
// volume does, the volume is made as a copy of it, so the conversation
// and the files carry over and the legacy volume is left as it is.
LegacySessionVolume, LegacyDataVolume string
// ContinueID is the harness's id for the conversation the agent's last
// segment was in, to continue; empty starts a new one.
ContinueID string
// tools server mounts read-write and live when its plan mounts a share
// (spec.AgentFiles.Share); empty when the agent has its share off.
Share string
// Roster is the agent's roster for the segment, for its envelope.
Roster []receipt.RosterEntry
// AppLink is the socket the agent's supervisor answers its app link on,
// absolute, which the app link's container binds when the plan has one
// (spec.CapSummary.AppLink); empty otherwise.
AppLink string
// kept in between segments, so a file checked in one is not checked
// again in the next while it is unchanged; empty keeps none.
ShareVerdicts string
// of the share's documents is kept between segments, one file for each
// checked digest, beside ShareVerdicts. Empty keeps none, and a
// document whose text was not kept is checked again.
ShareText string
// in, for a plan whose servers see it (spec.ServerShareMirror): before
// each turn it is made to hold a copy of each share file whose bytes the
// share check passed, and nothing else. The engine keeps its index of
// what it copied in ShareMirror + ".json" and stages each copy in
// ShareMirror + ".staging", beside it. Empty for any other plan.
ShareMirror string
// Skills is the folder of the agent's skills for this segment, which
// its supervisor filled with the skills the roster has on, for a plan
// that has any (spec.AgentFiles.Skills); mounted read-only into the
// tools server alone. Empty for any other plan.
Skills string
// DependencyDB is the folder of OSV's databases the Coding agent's
// dependency scan reads, kept under the runner home, for a plan that
// has the scan (spec.CoderGrant.DependencyScan); mounted read-only into
// the tools server alone. Empty for any other plan.
DependencyDB string
// Memory is the agent's memory, for an agent that keeps one
// (spec.AgentFiles.Memory); nil for any other agent.
Memory *PersistentMemory
// ServerVolumes are the named volumes of the plan's image servers
// (spec.MCPServerSpec.Volumes), made with the agent's labels when they
// do not exist and kept between segments, each held by the docker filter
// to the server that mounts it.
ServerVolumes []string
}
PersistentSegment is what a persistent agent's supervisor tells the engine about the segment it starts.
type PersistentSession ¶
type PersistentSession interface {
session.Session
// Conversation is the harness's id for the conversation the segment
// is in, whether it continued the one Params.Persistent.ContinueID
// named, and why not when it did not: what the supervisor keeps for the
// next segment, and what the envelope's persistent block records.
Conversation() (id string, resumed bool, reason string)
// SetResumeReason replaces the envelope's account of a segment that did
// not continue its conversation, with what the supervisor did instead.
SetResumeReason(reason string)
// SendCarrying is Send with earlier context ahead of the person's text:
// the harness is sent both, the user turn records the person's text
// alone, and the events receipt records what was carried.
SendCarrying(ctx context.Context, carried, text string) error
}
PersistentSession is the session a persistent agent's segment returns (StartSession with Params.Persistent).
type RedeliverParams ¶
type RedeliverParams struct {
// RunDir is the run's output folder.
RunDir string
// Destinations are the places to send it, credentials read.
Destinations []destination.Resolved
// Policy is the runner policy (its limits), RunnerImage the runner
// image's tag, present on the machine, and RunRoot the runner home.
Policy *policy.Policy
RunnerImage string
RunRoot string
Stderr io.Writer
}
RedeliverParams is a later delivery of a finished run's folder.
type ReportTheme ¶
type ReportTheme struct {
Name string
// Design is a design document, held to pkg/reportdesign's rules when it
// is stamped; it wins over Name.
Design []byte
From ThemeSource
}
ReportTheme is a run's report design and what chose it: a whole design document (Design, theme document version 3, from the account or a file), or else a built-in theme's id (Name). Neither is the default, Plain.
type ReviewRun ¶
type ReviewRun struct {
JevKey string
}
ReviewRun is a review-grant run's key: the person's own TypeSafe key. It reaches the tools container alone, through the run's gateway secrets file, which is deleted at teardown; the receipts are masked of it.
type ShippedFrom ¶
type ShippedFrom struct {
// InWorkspace is the pack's slash path in the workspace,
// "knowledge/<name>".
InWorkspace string
// Release names the release's bytes: "archive sha256:…" for an
// installed release, "local package tree sha256:…" for --local.
Release string
}
ShippedFrom is where a shipped pack comes from: its directory in the release's workspace, which the engine stages from the run's own copy of the workspace once CheckWorkspace has held that copy to the install record, and how the receipt names the release.
type SourceFetcher ¶
type SourceFetcher struct {
Docker dockerx.Client
// ProxyImage is the runner image, whose proxy role guards the step;
// FilesImage is the files image, whose source role fetches.
ProxyImage, FilesImage string
// Limits bound the step's and the proxy's containers.
Limits policy.Limits
// User is the person's user on this engine (dockerx.PersonUser): the
// files the step writes are theirs, and it runs with no more than they
// have.
User string
// RunID names and labels the step's containers and network, so the
// run's own teardown and the next run's sweep find them.
RunID string
// Work is a folder of the caller's: each source's tree and report live
// under it while the step runs and go when it ends. Receipts, when
// set, takes the proxy's log as source-proxy-<id>.log.
Work, Receipts string
Stderr io.Writer
// Later registers a cleanup with the caller's teardown, for a step the
// process dies in the middle of; Network registers a network the step
// made, for a sweep once every container is gone. Either may be nil:
// the step removes its own containers and network as it ends, and a
// sweep by the run's label removes what a killed process left.
Later func(func(context.Context))
Network func(string)
}
SourceFetcher runs the input-source fetch step: the runner image's `source` role in the files container, on a network of its own whose only route out is a CONNECT proxy to the source's host on port 443, at public addresses alone, with the token, when there is one, on the step's stdin and nowhere else. A run fetches each source the intake answered this way before its decode (fetchSources), and a knowledge build fetches each repository or address it was given the same way before its own (pkg/knowledge/build): one step, one posture, one set of checks on what the step wrote, whoever asked for the fetch.
func BuildSourceFetcher ¶
func BuildSourceFetcher(ctx context.Context, d dockerx.Client, runnerImage, filesImage string, lim policy.Limits, runID, work, receipts string, stderr io.Writer) (SourceFetcher, error)
BuildSourceFetcher is a fetcher for a built-in's build on this computer (a knowledge pack, a Writing Voice): the runner image's proxy and the files image's source role, the person's user on this engine, the build's run id, its work folder for the sources' trees and its receipts folder for each proxy's log.
func (SourceFetcher) Fetch ¶
func (f SourceFetcher) Fetch(ctx context.Context, s sources.Source, caps sources.Caps, dest string) (sources.Fetched, error)
Fetch fetches one source within caps into dest, which must not exist: the tree the step wrote is held to the source's rules (regular files and folders only, no .git, within the caps, the counts the report gives) and moves to dest whole, or nothing is staged. The network and the proxy are the step's own, made for it and removed before Fetch returns.
type Stage ¶
type Stage struct {
// Name is the step: one of the receipt's stage names, or StageSignIn.
Name string `json:"name"`
// Detail qualifies the step: StageDetailResume on the agent step that
// continues the stored conversation; empty otherwise.
Detail string `json:"detail,omitempty"`
// Subject is what the step acts on, for a person: the harness's name
// on the agent step ("Claude Code"; empty for the default harness,
// which a person never chooses), the servers being installed on the
// mcp-servers step; empty when the step has none.
Subject string `json:"subject,omitempty"`
}
Stage is a step a session's start has reached, reported through an OnStage hook so a client can say what the start is doing while it takes minutes (an image build, a server install, a harness's first start). A start reports, in order and each when it is reached:
compile the release materialized and the plan compiled
sign-in the model's sign-in readied (only when the plan has one)
images the runner, gateway and exec images readied
mcp-servers package servers installed (only when one is not yet)
prepare the session's folders, volumes and secrets prepared
infra the proxy, the gateway and the docker filter started
agent the harness started; then, when it is given the stored
conversation to continue, agent again with Detail
"resume" while it loads it (one that cannot opens a new
conversation, and the envelope says why)
type ThemeSource ¶
type ThemeSource string
ThemeSource is what chose a run's report theme, as the receipt says it.
const ( ThemeFromFlag ThemeSource = "the --report-theme flag" ThemeFromDesignFlag ThemeSource = "the --report-design flag, a file" ThemeFromLibraryFlag ThemeSource = "the --report-design flag, a design of the account's library" ThemeFromAccount ThemeSource = "the account's default report design" ThemeFromConfig ThemeSource = "report.theme in the CLI's config" ThemeFromDesignConfig ThemeSource = "report.design in the CLI's config" ThemeFromDefault ThemeSource = "the default" )
What can choose a run's report design.
type WebRun ¶
type WebRun struct {
// Scan is toolsrv.WebScanRegistry (hosted: the registry's route, with
// JobToken) or toolsrv.WebScanJev (local: the person's JevKey).
Scan string
// Search is toolsrv.WebScanRegistry, a provider the person holds
// SearchKey for, or "" (web_search is not granted).
Search string
// Registry is the registry's root, for registry_search and, hosted,
// the model-input routes.
Registry string
// The keys. They reach the tools container alone, through the run's
// gateway secrets file, which is deleted at teardown; the receipts are
// masked of them. None reaches the agent container.
JobToken, JevKey, SearchKey string
// MaxPages, MaxSearches and MaxRegistryCalls, when set, bound the run's
// calls below the tools' defaults.
MaxPages, MaxSearches, MaxRegistryCalls int
// Given are the addresses a plan whose web_read is held to them may
// read: the person's own, from their command. Set only for such a plan.
Given []string
}
WebRun is a web-tools run's configuration and keys.
Source Files
¶
- applink.go
- applinkrelay.go
- blocked.go
- browser.go
- capacity.go
- connections.go
- copilotmodels.go
- credits.go
- deliverables.go
- design.go
- desktop.go
- desktoplinkrelay.go
- destinations.go
- dockerfilter.go
- dropimages.go
- engine.go
- exitclass.go
- fetchsave.go
- filtersidecar.go
- grantpaths.go
- hardening.go
- heldcfg.go
- host.go
- host_unix.go
- imageoneshot.go
- inputreview.go
- inputs.go
- knowledge.go
- messenger.go
- mirror.go
- modelhosts.go
- oneturn.go
- outbox.go
- outbox_unix.go
- pdf.go
- placement.go
- podmanservice.go
- portrelay.go
- recovery.go
- redact.go
- relaylock.go
- relaylock_unix.go
- relays.go
- render.go
- resume.go
- review.go
- runlock.go
- servedtools.go
- session.go
- sessionstore.go
- share.go
- shipped.go
- signin.go
- signin_store.go
- sourcefetch.go
- sourcereview.go
- sources.go
- stage.go
- support.go
- sweep.go
- targethosts.go
- toolcalltext.go
- toolfilter.go
- turns.go
- voice.go
- volumeexport.go
- web.go
- workdirs.go