Marketplaces / vanillagreencom/kendex / agent-runtime
agent-runtime
Load to launch, inspect, deliver to or stop one coding-harness session through the agent-runtime CLI or Rust library.
skill · automation · @ 9574cc8
Supported tools: all tools
Install in kendex: kendex add --skill agent-runtime after subscribing to vanillagreencom/kendex.
No app yet? Download kendex.
Agent Runtime
.agents/skills/agent-runtime/scripts/setup # once per source revision, into the user cache
.agents/skills/agent-runtime/scripts/setup --detach --hold PATH # from a caller that must answer while it builds
.agents/skills/agent-runtime/scripts/agent-runtime <verb> --help
This package owns launch, account selection under the caller's policy, session identity, delivery, handoff and stop for one harness session. It holds no GitHub policy, issue classification, report format, personal task or fleet schedule. A caller supplies its intent and policy and reads typed results.
Rules
- Start, read, hand work to and stop a session through
launch,inspect,deliverandstop.probe,judge,session-file,rowsandprocessare the reads behind them.accountsholds the account judge,controllerthe controller's hand-over,sessionthe calling session's own record, andsubagentthe subagent spawns. Write no harness flag, process classifier or stop sequence of your own. - Every verb prints one JSON reply on stdout. Its
protocolisagent-runtime-v1.okis true with aresult, or false with arefusalofkey,fieldsandtext. A refusal also printsagent-runtime: <key> field=value ...on stderr and exits 1. A malformed command line printsagent-runtime: usageand exits 2. Route on the key, never the text. Refuse a reply whose protocol you do not know. - An effect reports one outcome:
not-started,confirmed,failedorunconfirmed. Reconcile anunconfirmedeffect before you ask for the same effect again. delivertypes text only where the judge reads the paneidle. It presses a--keyonly where the judge reads a dialog,askingorrate-limit-switch.- A
deliverreceipt confirms only equal text after the cursor. Any other new row answersunconfirmed. deliver --no-pastetypes nothing. It checks--line,--fileor the--line-digestchecksum of the normalized text after--turns-before. With no text, it reads the state and the turn count.deliver --forceis for a probe that knows better, never for a workflow.- Stop a session by its recorded identity.
stopsignals the pid and start time the launch record holds, and the harness processes below it, each only while its start time still matches. Never stop a session by process name or by a pid alone. launchwrites the launch record, a locked, revisioned JSON file.inspectheals the record as the harness comes up. Pass the same file to every later verb. Every write keeps the fields the runtime does not know.- Charge a worker that runs outside an orch lane to its account. Start it with no controlling terminal:
agent-runtime process lead --file <root>/workers/<name> --account <config dir> -- <program>.<root>is the account records root,AGENT_RUNTIME_ACCOUNT_STATE_DIR. While the worker's group runs, every account pick charges that account. A file outsideworkers/is refused. The caller owns the file: lead again under the same name, or remove the file after the worker ends.
Confinement
A launch intent that names grants runs the harness inside a kernel boundary. On Linux the runtime runs it under bwrap: the whole tree read-only, a private /tmp, the user's runtime folder hidden, and only the granted paths bound back writable. Every process the harness starts runs inside too. A controller's intent names no grants, so a controller runs unconfined.
Inside, TMPDIR and each harness's own temporary-folder variable name the private /tmp, whatever the pane inherited (TEMP_VARS in runtime/src/confine.rs).
The account seat a confined lane runs on is read-only, except the session folders its harness writes. Harness::home_writes in runtime/src/harness.rs names those folders per harness. The runtime grants a folder that is a link where the link leads, and refuses the launch for a link that leads nowhere. A Codex home and a Pi root are granted whole, with the settings file read-only. Each of Pi's extensions/, hooks/, packages/, kendex/hooks.json and kendex/hooks/, and each of Codex's hooks.json, hooks/, AGENTS.md and rules/, stays read-only where it exists. Pi's kendex/ is bound writable in place, and a link there refuses the launch grant-link-unheld. The launch writes an absent hook registration, Codex's hooks.json or Pi's kendex/hooks.json, in its empty form, and makes an absent Codex rules/ or Pi kendex/hooks/ empty. It creates no other absent entry, so the lane can create one.
- Copilot CLI runs unconfined on every host.
- A launch whose grants name an
unconfinedcause runs unconfined under it. - Every harness runs unconfined on a host other than Linux.
- The launch record names the answer and its cause. No setting changes it.
Inside the boundary:
AGENT_RUNTIME_CONFINEDis1, andAGENT_RUNTIME_GRANTSnames the grants file. Read that file before you write outside the working tree: the kernel refuses a write outside the grants.- The tmux and session-bus sockets are out of reach.
GH_TOKENis set where the grants hand over a token file.- A job the runtime starts from inside runs under
setsid, never a systemd unit, so it stays inside.
Build and run
scripts/setup builds the runtime with cargo build --release --locked into the user cache, under a key over its sources. setup --help names the cache, the key's inputs and the binary's path. A dirty tree builds under its own key. A key already built builds nothing. Setup builds nothing into the installed files.
- Offline, pass
--offline. The build then needs every locked dependency in the cargo cache. setup --runtime DIR --name NAMEbuilds another skill's runtime crate that depends on this one. That skill's wrapper computes the key throughscripts/lib/key.sh. orch'sscripts/setupandscripts/orch-runtimeare that pair.- Inside a confined orch lane,
AGENT_RUNTIME_CACHEnames the lane's own cache, and the shared cache is read-only.
scripts/agent-runtime runs the binary built from the sources beside it. Without that binary it builds nothing. It prints agent-runtime: setup-required key=<key> run=<path to scripts/setup> on stderr and exits 69. Run setup before a hook or caller needs the binary.
A caller that must answer while the binary is missing, such as a harness hook, runs setup --detach. --detach starts at most one build per key and answers at once. It does not start a key that ended unbuilt again; run setup without --detach for that key. setup --help states every answer and cause, and the exits --hold PATH gives while PATH exists.
Reading routes
- A person installing or choosing the package: README.md.
- A maintainer building, testing or probing it: the package's
DEVELOPMENT.mdin the catalog. - Flags, defaults and each verb:
agent-runtime <verb> --help.