The Agent Package

An agent has an inside and an outside. The inside is what it is made of: skills, the scripts they run, the servers they reach. The outside is what a caller can rely on: what it does, what it refuses, what it needs, what it leaves behind, which is the Descriptor of Section 6. The inside has a portable format of its own, the Agent Plugin, whose standard says in its own words that distribution, installation, and permissions stay under each client's control. This section defines the thing that carries both halves from a description to a running agent with an identity: the Agent Package, what it contains, how the halves are joined, how it is published to and installed from a depot, and how a verifier can check that the agent answering on a network is the package that was built.

It is not a package format: Agent Plugins defines the layout and the manifest, and Agent Skills defines a skill folder; this section adds two files beside the manifest and one namespace inside it, restating neither. It is not a runtime, not a listing, and not a change to any wire.

12.1 Terms#

These are the words this document uses for the things an install joins, and they are used in this sense throughout.

• Host: the machine an agent runs on. One host may hold many agents, each with its own home and its own identity.
• Harness: the program that does the thinking when a message arrives, whether a coding tool driven from a terminal, a model runner, or an agent framework. A harness is not an agent: it is what an agent runs on, and one harness may serve many agents on one host.
• Package: an Agent Plugin directory, or its archive, carrying a draft Descriptor and an install file at the paths in 12.2. A package is not an agent: it carries no subject, and until it is installed nobody can address it.
• Draft Descriptor: a Descriptor without a subject (6.2.1), inside a package. Bound Descriptor: the same document with its subject filled and signed, served by the running agent.
• Install file: the host-facing declaration of 12.4: what an installer must have and do.
• Agent: what exists after an install: a subject with a key and a handle, a home on a host, a harness configured to read the package, and whatever parts the binding requires to receive messages and answer them.
• Bare agent: an agent that carries no package and answers as its harness alone. It has a subject and a Descriptor like any other agent; what it does not have is offerings a package declared.
• Depot: where packages are published to and fetched from, by name, version, and digest. A depot is not a registry of agents (6.7): it holds packages, which contain drafts, and it never serves a draft as any agent's Descriptor.
• Installer: whatever performs 12.7; on a conforming deployment, an agent holding the deployment manager role of the roles registry.
• Image: the package as installed, fixed as bytes and named by a digest, together with the harness and whatever parts the binding requires. An image is not a package: a package is authored and published, and an image is what an install produced from one.

An owner instructs a deploy; the installer installs the package; the result is an agent. The three words are not interchangeable: the deploy is the instruction, the install is the procedure of 12.7, and the agent is what the procedure leaves behind.

12.2 Layout#

A package is an Agent Plugin. Its portable parts are exactly what that standard says: plugin.json, skills/, and optionally mcp.json. Beside the manifest sit the two authored files this section adds, and one namespace directory holds the views generated from them.

<name>/
├── plugin.json                  the Agent Plugins manifest
├── descriptor.json              the draft Descriptor: every caller-facing fact
├── install.json                 the install file: every host-facing fact
├── skills/<job-slug>/           one skill per job, offering or step: SKILL.md, scripts/, references/
├── mcp.json                     servers by system name, no vendor (optional)
└── net.agentdoc.package/        NOT.md, RECORDS.md, SYSTEMS.md, generated

The manifest's extension entry for the namespace net.agentdoc.package carries pointers and digests, never copies:

"extensions": {
  "net.agentdoc.package": {
    "descriptor": { "path": "descriptor.json", "sha256": "<digest>" },
    "install":    { "path": "install.json",    "sha256": "<digest>" },
    "built": true,
    "draft": true
  }
}

A package copied from another carries one more member here, from, naming the packages it descends from; Section 13.5 defines it, because copying is what a repository is for and nothing in an install reads it.

The namespace is the same for every conforming implementation, so any reader that knows this section finds the pointers under one key. A package MUST declare the Agent Plugins schema version that clients read, and an implementation SHOULD validate against a pinned copy of that schema rather than a fetched one, so that a moved or unavailable address cannot make a valid package unverifiable.

12.3 The draft Descriptor#

The draft Descriptor is the only authored spelling of every caller-facing fact in the package. Every rule of Section 6 applies to it unchanged: no subject, shapes only and never an address, credential, or endpoint, an absent member means not stated, versioned by replacement with its digest over exact bytes. Its refusals member is prose, and a builder SHOULD write it as one sentence per line, because an evaluator turns each refusal into a probe and a line is the one boundary it can rely on.

Two members are added to the Descriptor by this section, both optional and both ignored by a consumer that does not know them, as 6.2.4 requires:

• records[]: what the agent must leave behind, each with a name, when (per_task or standing), and an optional file, a pattern relative to the records directory. A record is not an output: outputs are what a caller receives, records are what an operator and an auditor can inspect, and a caller reading outputs would be misled by a spend log listed among deliverables. An audit with the pattern is exact; without it, it falls back to the name.

• escalates[]: what always goes to a person, one sentence each.

• steps[] on an offering: the delivery steps the offering runs, in order, to deliver what it promises. A package's jobs are of two kinds: what a caller orders, which becomes an offering, and what the agent runs to deliver it, which becomes a step listed under that offering in the same shape (id, name, what it does, inputs, outputs). A step is not an offering unless it also stands as one, and a caller MUST NOT be shown a step as something it can order. Steps are one level deep. A builder that marks no job as offered offers them all, which is what every package before this member meant.

• how on a job or a step: how the work is actually done, in four members, each a single word from a fixed set. A job or step that carries none says nothing, which is what every package before this member meant.

  • control: who decides what happens next: script (a program written in advance, the same every time), model (a model decides), or person (a person acts).
  • intelligence: how a model is used: none, called (a program calls a model at a named point and takes its answer back), or open (a model is given the work and chooses its own way through).
  • cost: what running it can spend: none, metered (bounded by a declared ceiling), or unbounded.
  • contract: how much of the method is written down: full (every step of it), ends (what must come out, not how), or goal (only the aim).

  One combination is refused rather than described: control: model with contract: full. A method written down in full and then handed to a model to improvise is the shape that fails, because the model does not follow the written method and nothing checks that it did. Either the method is a program, and control is script, or the contract is loosened to ends. control: script with intelligence: open is refused for the same reason from the other side: a program that hands the work to a model to find its own way is not a program, it is a model with a launcher. A checker MUST refuse a package carrying either, naming the job or step.

  What this is for: a caller is entitled to know whether the step they are buying is a fixed program or a model improvising, an operator needs to know what can spend, and a builder needs to be stopped from writing a procedure in prose and hoping. The first multi-agent run failed three times in exactly one way, a step with a written procedure left to a model to improvise, and nothing in the package said which steps those were.

• run on a job: the exact command the host runs for this job, when there is one. A job MAY carry it only when its how says control: script and intelligence is not open; a job that says a program decides what happens next and then names no command is describing a program nobody can find. It has five members: command, the argument vector, first element the program; per_file, an argument fragment repeated once for each file the message brought, or absent when files are not passed; message_file, where the sender's text is written before the command runs, or absent when it is not needed; reply, either stdout or json:<member>, saying where the words for the sender are in what the command printed; and escalate_when, json:<member>, naming a member of that same output which, when it is present and not false, means the command has decided this turn needs judgment. The host then wakes the model as it would for a job with no command at all, and the command's own reply is not used. A job that never needs judgment omits it.

  Every element may carry placeholders, and the host substitutes exactly these and no others: {home}, {package}, {records}, {work}, {job_dir}, {message_id}, {sender}, {handle}, {in_reply_to}, and, inside per_file only, {file_path} and {file_media_type}. A placeholder the host does not know is an error at install, not at run: a command that silently ran with the literal text {job_dir} in it would be worse than one that refused.

  What this is for. A host that has a command for a job MUST run it and MUST NOT wake a model to decide whether to. The step is the same every time, it costs nothing to decide, and it cannot be improvised into something else. {in_reply_to} is the word none when the message answers nothing, so the command's own argument list never changes shape. A command that names escalate_when is not a model in disguise: the program still decides, every time, and what it decides is whether this one turn is one it can finish. The job's job_seconds still caps it, and a command that fails is a failed turn like any other: the sender is told, and finished work already filed is handed over.

• Named run configs. A package MAY ship named run configs, in the draft Descriptor's run_config.named, beside the settings they set (Section 6.2). They are the author's layer of Section 5.8, and they travel in the package because the builder is the one who has seen which choices produce good work. The settings a job may set are caller-facing and are declared in the draft Descriptor; the install settings of 12.4 section 3 are host-facing and stay in the install file. A run config never reaches an install setting.

A system in systems[] to which the agent sends a caller's material during the work SHOULD say so with leaves: true; a caller deciding whether to engage is entitled to know that their text leaves the agent.

12.4 The install file#

The install file is the host-facing half. Everything in it is something an installer must have or do, and nothing in it is something a caller could act on. It MUST NOT contain a credential value, an address, an account identifier, or a host path outside the package: it names things, and the host resolves the names. Its format is "agent-install-v1", and it has five sections:

1. runtimes[] and binaries[]: what must be present on the host before install proceeds, each with a purpose a person can read. The installer MUST check each and MUST stop and escalate when one is missing, never substitute.
2. dependencies[]: what the skills' scripts need, per skill, as a lockfile with integrity hashes carried under the skill's own folder, and the lockfile's digest. The installer MUST install from the lockfile into the agent's own home, never system-wide, and MUST NOT execute install-time scripts or lifecycle hooks of any kind.
3. systems[]: one entry per system name the Descriptor names, and no others; the two sets MUST be equal. An entry names its system in name, with role accepted as an alias for one revision on the same terms as Section 6.2's, so an installer MUST read either and MUST prefer name where both are present. Each entry says what kind of thing the system is bound to (directory, mcp, or service) and, for a service, the name of the credential the scripts expect, the environment variable they read it from, and whether the service spends and in what unit. Kind mcp binds the system to an entry in mcp.json, which names the server by the same name and carries no vendor address. A service whose scripts also read a non-secret value the host must supply, such as a billing project, lists it under settings by variable name and purpose; the instruction supplies the value at install, and the record names the variable.
4. ceilings[]: which spending systems need a ceiling, per what, and which side applies it. The install file says a ceiling is required; the owner's instruction sets the number. Each entry MUST carry enforced_by, one of two words. runtime: the runtime the agent runs in applies the number and nothing else can, because the package's scripts reach the spending system directly, with the credential this file names, and the call is made before any other party sees it. platform: the spending passes through a party that is not the agent, which can refuse a charge the runtime has already decided to make. The value follows from how the package reaches the system and never from whose machine the agent runs on: a ceiling over a system the scripts reach with a credential named here MUST say runtime, whoever installs the package, and platform is available only where the agent reaches the system through a facility the host supplies. What a reader may conclude: under platform, the ceiling outlives a runtime that ignores it, because a second party is still in the path; under runtime, the ceiling is worth what the party that supplied the runtime is worth, and a number in a record is what that party was asked to apply rather than a limit anybody else can hold it to. A spending system with no ceiling entry does not conform, and neither does an entry with no enforced_by: an unstated enforcing side is read as the weaker one by a careful reader and as the stronger one by a hopeful one, and the hopeful reading is a buyer believing somebody is watching the spend when nobody is. An entry MAY carry suggested, a number in the system's unit that the builder considers reasonable for one task or day; an approver's form MAY offer it as the default, and it binds nothing until the owner's instruction adopts it.
5. directories[]: the working directories the installer creates and binds, including where records land. A directory is bound at install to storage that outlives a single run, and a host that cannot bind one MUST refuse rather than create a directory of the right name that does not survive: a working directory that is discarded between messages looks filed and is lost, which is worse than no directory at all.

Beside the five sections the file carries one number, job_seconds: how long one job may take at most, a whole number of seconds; the host caps each job at it. A package that says nothing gets the host's default, and work that outruns it is stopped, so a package whose job takes minutes MUST say so. It sits beside ceilings[] rather than inside it because it bounds time rather than spending, and the host applies it whoever else applies a ceiling.

Beside them it carries one name, answer: which of the pieces this package files is the reply to the sender, as { "piece": "<name>" }. A package that files a deliverable and does not say which one answers leaves that decision to the host, and the only thing a host has to decide with is what the work printed. For a command whose run declaration already names a reply that is fine. For an agent that wakes a model it is not: a harness prints every assistant text part, so its output is a transcript of thinking rather than a deliverable, and the tail of a transcript is the end of the thinking. A sender given that has been told nothing, and in a process the next agent is handed it as input and produces something that looks like work.

So a host MUST take the named piece as the reply when the package names one and that piece is filed and carries a text media type. A host MUST NOT treat a piece of any other media type as a reply: a reply is words in a message, and a page, a recording or an archive is a piece to fetch. Where a package names no piece, a host SHOULD offer the work somewhere to write its answer and take what is written there in preference to what was printed. What the work printed is the last resort in both cases, and a host SHOULD record which of the three it used, because a sender given the deliverable and a sender given the transcript cannot tell the difference from the outside.

A package that names a piece it does not file has a fault its author needs to hear, and the host MUST say so where an operator will read it. It SHOULD still answer with whatever the work did manage to say: the sender is a third party to that mistake and silence serves them worse.

12.5 Skills and the generated views#

One skill per job, offering or step, named by the job's slug, and no skill without a job. A skill folder is an Agent Skill and MAY carry scripts/ and references/; its instructions are the place for the long-form judgment an agent needs to do the job well, and this section places no limit on their length. A skill MAY ship an acceptance check, a script that reads the skill's declared outputs and answers pass or fail on their form; it judges form, never quality.

NOT.md, RECORDS.md, and SYSTEMS.md exist so that a harness which reads markdown has them, and for no other reason. They are projections of the two authored files, generated by the builder, MUST NOT be edited by hand, and a checker regenerates them and compares bytes.

12.6 The rules#

1. One authored spelling. A caller-facing fact appears in the draft Descriptor and nowhere else in the package; a host-facing fact appears in the install file and nowhere else. The manifest points, the markdown projects, and neither restates.

2. The inside matches the outside. Every offering has exactly one skill and every skill an offering; every system name in the Descriptor has exactly one install entry and every entry a name; every mcp.json server is a declared system name. A script reaches a system under its declared name, through the credential and the variable the install file names for it (12.4 section 3). A script carrying its own endpoint has gone around its own declaration: the system it reaches is in no systems[] entry, nobody bound it at install, no ceiling covers what it spends, and a caller reading the Descriptor cannot see that the work leaves. That is this rule's fault and not rule 3's, and the difference is the fix: rule 3's is deleting an address from a declaration, and this one's is declaring the system a script was already using.

3. Shapes in the Descriptor, names in the install file, values nowhere. No file in a package contains a credential value, whatever kind of file it is: a secret inside a package is a secret published, and rule 7 has the credentials placed at install and nowhere else. Addresses, endpoints, and account identifiers bind the three authored declarations absolutely: the manifest, the draft Descriptor, and the install file MUST NOT contain one, and a depot MUST refuse to publish a package whose declarations do. Those three are where the package says what it is and what it needs, read by a caller deciding and an installer binding, and an address in one of them ties the package to a deployment, which is the one thing a package is not (12.9).

   The addresses excepted are excepted by member and by file, and every one of them is in the manifest: its own $schema, naming the version of the Agent Plugins schema the manifest is written against; homepage and repository, the Agent Plugins members that say where a reader goes to read about this agent and where its source is kept; and the repository of each from entry in the net.agentdoc.package namespace, which says where an ancestor of this package was copied from (13.5). The test they pass is the one $schema passes: each names where a reader goes, and nothing at install or at run fetches any of them. An installer MUST NOT fetch from one, and a harness MUST NOT give one to a script. The install file carries no address of any kind, excepted or not, because it is read while an agent is being bound and run, where an address becomes a place. The Descriptor carries one exception and carries no other: the schema of each can_use entry, which names a published shape a caller may send with a job. It passes the same test the manifest's exceptions pass. A shape identifier is read the way a page reads an itemtype, as a name that is spelled as an address so that anybody may publish a shape without a registry agreeing to it first, and nothing at install or at run fetches it. An agent MUST NOT fetch it and a harness MUST NOT give it to a script: what a job hands an agent is the profile, never the address the profile was shaped by. A checker reads this member structurally and holds every other part of the Descriptor to the rule, because an exception tested by looking for an address anywhere in the file is not an exception but a hole.

   0.16.0-draft and earlier forbade homepage and repository too, on the reasoning that a package with an address in it is tied to a deployment. That reasoning holds for an endpoint and does not hold for a link to the source: the reference client already writes both members from its own spec, and a rule that forbids members of the format this section builds on is a rule against the wrong thing. What a link like that cannot do is prove anything, since anybody may type one; the build record's source (8.2) is where a repository is attested rather than claimed, and a reader who needs to know where bytes came from reads it there.

   A lockfile is exempt, and the exemption is not a hole. 12.4 section 2 requires a lockfile with integrity hashes, and every lockfile names where each dependency's bytes came from, so a rule that forbade addresses everywhere would forbid the thing another rule requires. The addresses in a lockfile are the provenance of bytes a hash already fixes: they say where a byte sequence came from, never where the agent talks, and striking them would delete the record of what was fetched while changing nothing the agent reaches. That is the test, and it is about direction rather than about file type: an address in a declaration is read at install or at run and becomes a place; an address in a lockfile is the history of bytes that are already pinned. An address anywhere the harness reads or a script calls is rule 2's business and never this exemption's, and a checker reports it there rather than passing it as provenance.

4. Nothing commercial. A package carries no price for what it offers, no handling terms, and no claim about who may call the agent or whether a person attends it. Those attach at listing and at install, by whoever makes those decisions.

5. One digest. A package is published and installed as an archive, and its SHA-256 over the archive bytes is the package's digest. Every record that mentions the package names that digest.

6. The bound Descriptor is the draft plus a subject. The Descriptor a running agent serves MUST differ from the draft in its package only by the presence of subject and signatures and by the members the install decides: interaction, shape, and agent_version when the draft leaves it empty (rule 4 keeps those out of the package). The deployment record names which members the binding added or changed. Any other difference means the agent is not the package that was built, and a verifier reports it.

7. Nobody runs a package's code but the agent. The depot executes nothing. The installer executes nothing from the package. The agent's harness runs the skills' scripts, in the agent's own home, with the credentials placed for it and no others.

8. No hidden characters. A depot MUST scan every text file for zero-width characters, bidirectional controls, and the tag block before publishing, and refuse a package carrying one. Agent configuration has no gap between install and execution the way code does, so the check belongs at the door.

The one commercial member a package may carry. An offered job's revisions policy (Section 6.2) travels in the package, including the price of redoing each step, because the builder is the one who knows which steps stand on their own and roughly what each costs to run again; it is a proposal, not a listing. The operator MAY change any of it before the Descriptor is bound at install, and the bound Descriptor, not the package, is what the agent's node applies. Rule 4 is otherwise unchanged: the offering's own price, the handling terms and the door stay outside the package.

12.7 Publish, install, update, remove#

Publish. A package is published to a depot by name and version, signed by its builder. A publish MUST carry the build record (8.2) whose package.sha256 equals the digest of the bytes being published, and a depot MUST refuse a publish without one or with a digest that does not match. A published version is immutable; a version can be withdrawn, which marks it and stops new installs, and is never deleted, because deploy records point at it. A depot serves bytes by digest and indexes the draft Descriptor and the install file, so a search can answer what a package does, refuses, needs, and spends; a package whose install file declares nothing is indexed as "not stated", never as needing nothing. A depot MUST check every named run config in the draft Descriptor against the settings the same block declares, and MUST refuse a publish where a named run config repeats another's name, sets a setting the block does not declare, gives a value outside its setting's allowed or above a numeric rule's ceiling, or carries a digest that does not match its entry. A depot SHOULD expose list-versions, download, and publish over the registry HTTP API that Agent Package Manager clients speak, so the skills in its packages reach any client that installs plugins.

Install, on instruction from an owner and under the deployment manager's contract, in order: fetch by name and version and verify the digest against the build record and the manifest against the pinned schema; check every runtime and binary; create the agent's home and the declared directories; install the dependencies from each lockfile, executing nothing from the package; bind each system, a directory to a path under the home, an mcp entry to the address the instruction supplies, a service to the credential the instruction names, fetched from the owner's store and placed in the agent's environment, and refuse a request that contains a credential value before the value is used; set each required ceiling to the number the instruction gives, and stop when a spending system has none; translate the skills, views, and instructions into the form the target harness reads; mint the subject and bind the draft into the bound Descriptor by adding subject and the operator's signature, placed where the agent serves it; start the agent and check it with the grade stated, smoke or conformance; produce the deployment record (8.3) with the package digest, the bound Descriptor's digest, the credentials placed by name, the ceilings set, and the checks.

Update installs a new version under the same subject: agent_version MUST increase and the subject MUST NOT change; the old version's files are retained until the check passes, and a failed check restores them; the record names both package digests and both Descriptor digests. Rollback is an update to the previous version.

Install alongside installs another version of an installed package under the same subject without replacing the current one, so a job whose run config names that version can be done by it (5.8). The subject MUST NOT change, and no new subject, key or handle is minted. The version MUST differ from the current one and from every version already installed alongside, and MAY be lower or higher. The bound Descriptor stays the current version's, so what the agent declares to the world does not change. The install binds each system as an install does, from the instruction, so each version keeps its own install settings. A version installed alongside is reached only by a job that names it; a job that names no version, or the current one, is done by the current version. An update installs a new current version and leaves every version installed alongside as it was. The deployment record's act is "alongside", and it names the package digest and how the version is reached.

Retire a version removes one version installed alongside and never the current one, which only an update or a removal changes. The deployment record's act is "retire-version", and it lists what was removed and what remains, as a removal does. An installer SHOULD keep a version installed alongside while any run config it knows of names it, and SHOULD tell the owner before it retires one on its own.

Remove lists what was removed and what remains, under remaining, which is empty only when the removal was complete; placed credentials are removed and named. The subject's Descriptor history at the registry is not removed (6.7).

The ledger. An installer MUST record every file it placed and each file's digest, in the deployment record or in a ledger it names, and answer "what is deployed" by rehashing those files and reporting every difference, so a hand edit to a running agent's instructions is detectable rather than invisible.

12.7.1 When the owner runs the agent#

The install above assumes the installer reaches the machine: it places files there, and it can rehash them afterwards. An owner MAY instead run the agent on compute the installer never touches. The procedure does not become optional when that happens. It splits in two, and each side MUST record the half it performed and MUST NOT record the other. The two halves are two kinds of record, not two deployment records: building an image deploys nothing, so the builder's account is a build record naming the image digest (8.2), and the side that starts the agent produces the one deployment record for the deploy.

What the installer still does. Everything that happens before a running machine is involved, in the order above and with the same refusals: fetch by name and version and verify the digest against the build record and the manifest against the pinned schema; satisfy each runtime and binary the install file names by putting it in rather than probing for it, and stop and escalate where one cannot be satisfied; install the dependencies from each lockfile; create the home and the declared directories; translate the skills, views, and instructions into the form the target harness reads. What those steps produce is an image, and the installer records its digest in a build record (8.2). Rule 7 of 12.6 is easiest to break here, because running one of the package's own scripts during a build is a single line and looks like part of building: an image build MUST execute nothing from the package, and an image whose contents were produced by the code under review is an image no digest usefully describes.

What the owner now does. Supply the compute and start the image. Place each credential the install file names, from their own store, under the variable it names; the installer MUST NOT hold a credential for an agent it does not run, and an owner MUST NOT hand one back to it. Bind each directory system to storage that outlives a single run, each service system to its variable, each mcp system to its address. Set every required ceiling to a number, and cap each job at job_seconds. Both of those are now applied on the owner's side and by nothing else, by the runtime or, where a ceiling's entry says platform, by whatever the owner put in the path, so a reader MUST NOT take a ceiling named in a record as one a depot, a builder, or a network applies: the number was set on the side that spends. What the owner does not do is any part of the install. An image the owner rebuilt is a different image, and a deployment record names the digest of the image it started and never one it was handed for an image it did not start, so a rebuild shows up as a digest no build record matches.

Who mints the subject, and who holds the key. Section 4.1 allows a key generated on the host and a key provisioned to it, and running on the owner's compute settles neither, so the record MUST. Where the key is generated inside the owner's runtime at first start, the installer never holds it, and the bound Descriptor cannot exist before then, because the signature 6.6 requires is made with the subject's own key: the binding happens on the owner's side, and the deployment record that names the bound Descriptor's digest is produced after the agent has first answered rather than before it starts. Where the key is minted by the installer and provisioned into the image or its environment, two parties have held it, and everything the subject ever signs is a signature more than one party could have made. A deployment record MUST state which of the two happened and who holds the key now. A record that names the subject's key and stops leaves a reader unable to count the parties who can speak as it. The handle is unaffected either way: it is bound to the key at a registrar (8.6), and where the key was made does not enter.

Who produces the deployment record, and what it can honestly claim. A record carries what its producer observed and nothing else. An installer that built an image and handed it over produces no deployment record: it deployed nothing, and what it built is stated in its build record, which names the package digest, the image digest, each file's digest as built, and the checks it ran against the image. The side that starts the agent produces the one deployment record, and it is the only side that can: it names the image digest it started, the target, the credentials it placed, the ceilings it set and who applies them, the subject and the custody of its key, and the checks it ran after start. What it did not observe is absent (8.3), because a record carrying a ceiling nobody watched anyone set has said the ceiling was set. Where the producer is also the subject, the record is the subject's account of itself. It is a record under 8.1, verified and carried as one, and it moves nothing in an assembled view that the subject's own declaration could not have moved. A check the subject ran on itself is the subject's word, and signing it with the subject's key adds a signature, not a witness.

The ledger, when the files are layers. The ledger answers "what is deployed" by rehashing what was placed. In an image the files are layers, and the answer is the digest the runtime reports for the image it started, which the deployment record names, compared against the image digest in the build record of whoever built it. That is the stronger half of the exchange: one digest covers every file at once, and no file inside can differ from the file that was built without the digest differing. It is also the narrower half, because it covers nothing the runtime laid over the image at start. A mounted directory, a replaced instruction file, a variable holding a prompt: each changes what the agent does while the digest still matches. So every file the harness reads as instruction, meaning the skills, the generated views, and the draft Descriptor, MUST be inside the image, and a deployment that mounts one over the image does not conform. The directories bound at start are for what the agent writes, never for what it is told. An installer MUST still record each file's digest as built, in the build record beside the image digest, so that a reader can ask what is inside a layer without starting it.

12.7.2 The workspace contract#

Some runtimes describe a run rather than a machine: what is mounted, what is in the environment, which directories exist when the process starts. Part of the install file maps onto such a description and part of it cannot, and the split is the reason a package compiles to an image rather than to a workspace description.

What maps. directories[] maps directly, with the standing requirement that the one records land in outlives the run, which an image's own filesystem does not. In systems[], a directory system maps to a mount, a service system to an environment entry under the variable name the install file gives, and an mcp system to whatever the run hands the harness as that server's address. The entries holding credentials are exactly the ones a run MUST NOT leave behind when it ends. What does not survive the mapping is the part of systems[] that is a statement rather than a binding: that a system spends, in what unit, and what the access is for. A workspace description carries the value and drops the reason, so an implementation MUST NOT treat one as a place those facts live.

What cannot map. dependencies[] needs a resolution that happens once, from a lockfile, before the agent answers, and 12.4 forbids satisfying it by executing the package. A description of a starting state has nowhere to put that work, and resolving it at each start is worse than not conforming: two starts produce two insides, and no digest in any record describes either. runtimes[] and binaries[] are a check that stops a deploy, and a starting state cannot stop anything. ceilings[] and job_seconds need a party that can refuse while the work runs, which is the opposite of a starting state: one is applied to spending as it happens, and the other is a clock watched to the end of a job.

Therefore the image. A package declares things that must be made true before the agent answers and things that must be enforced while it does. A workspace description states what a run begins with, and it neither makes nor enforces. So the package compiles to an image, where the resolution happens once and is fixed as bytes a record can name, and the workspace description is what the owner supplies around that image. An implementation MUST NOT present a workspace description as an install: it carries no dependency resolution, no runtime check, and no ceiling, and an agent started from one alone is an agent whose inside nobody established and whose spending nobody capped.

12.8 Provenance#

Three records join by digest. The build record names the package digest, the draft Descriptor's digest, each lockfile's digest, and the checks the builder ran with their grade, unrun or acceptance, with draft always true; where its producer built an image from the package it names that image's digest too, and a package built once and compiled into an image later has two build records, one per thing made. The deployment record names what its producer observed, out of the package digest, the image digest it started, the bound Descriptor's digest, the subject and how its key was minted, the credentials placed by name, the ceilings and who applies them, and the graded checks; a member it does not name is one it did not observe (8.3), so a record of a deploy whose image somebody else built joins on the digests it does carry and is weaker rather than invalid. Where both image digests exist, comparing them is how a reader learns whether the agent was started from what was built, and the answer is the starter's word. The evaluation record (8.4) names the bound Descriptor's digest and the verdict.

A verifier fetches the package by the deployment record's digest and confirms the bytes hash to it; confirms the build record names the same digest and its signature verifies against the builder's key; fetches the draft from the package and the bound Descriptor from the agent and confirms they differ only by subject and signatures; confirms the bound Descriptor's signature verifies against the subject's key; and confirms the evaluation record names that digest. A verifier that completes all five knows what is running and who vouched for each step. It does not know that the work is good, which no document about an agent can say. The evaluation record is optional. A verifier without one knows what is running and who vouched for the build and the deploy, and nothing about whether the work is done; an AgentDoc prints that nothing has been evaluated rather than hiding it. An agent a person attends is not evaluated by probing, because the person would be answering; the deploy's own graded check is the check it carries.

When the producer is the subject. Where the owner runs the agent (12.7.1), the five checks are not equally affected, and a reader is owed the difference rather than the count.

The first two are untouched. They are about bytes and a builder's signature: fetching the package by the digest the deployment record names and confirming the bytes hash to it, and confirming the build record names that digest and verifies against the builder's key. Neither has ever depended on the machine.

The third still runs and means less. Both documents are still fetchable, so the comparison happens as before. What changed is who chose the package to compare against. The deployment record names it, and where that record's producer is the subject, the subject chose its own comparison target: the check then proves that the Descriptor served matches the draft in the package the subject named, which is consistency. It never proved that the code answering was built from that package. It is weaker now only because the second party who used to name the package is gone.

The fourth is unchanged, and was always narrower than it reads. Section 6.6 requires the Descriptor's signature to be made with the subject's own key, so the check confirms that the document was signed by the key it names as subject. It catches substitution between the agent and the reader. It has never caught a subject describing itself generously, and who runs the machine does not touch it either way.

The fifth is untouched and carries more weight here than anywhere else. An evaluator probes the agent at its address, and where the agent runs does not enter. Where the deploy is self-issued, the evaluation record is the only one of the five whose issuer is neither the builder nor the subject and whose evidence is the running agent's own answers. It remains optional, and its absence costs more in this arrangement than in one where a second party performed the deploy.

What none of the five establishes, before this section and after it, is that the process answering was started from the image a record names. A runtime that reports the digest it started can be asked, and the answer is that runtime's word, weighed as its key is worth. Where the owner runs the agent, that key is the owner's, and a verifier who wants better than the owner's word has only the evaluator's probes.

12.9 What stays out of a package#

The agent's identity, handle, admission list, and attendance, which are the owner's decisions at install. Price and handling terms, which attach at listing, and which the Descriptor points at rather than holds. Evidence: the three records are about a package and never inside one. The runtime: a package declares what a host must have and never carries the harness that runs it. The image: a package is what an image is built from, and an image's digest names bytes that did not exist when the package was published, so a package carrying one would be naming its own successor; the build and deployment records carry it instead. Building one is how the harness the previous line keeps out of the package reaches the agent, which is what an image is for. The compute: nothing in a package says whose machine runs the agent, one package serves both answers, and a deployment record says which for one deploy. What a run begins with: the mounts, the variables, and the numbers of 12.7.2 are supplied per deployment and per run by whoever runs the agent.

12.10 Conformance#

A checker verifies a package mechanically: the layout of 12.2; the manifest validates against the pinned schema and carries no address outside the four members 12.6 rule 3 excepts, $schema, homepage, repository, and each from entry's repository; the draft Descriptor conforms to Section 6 and carries no subject; the install file has its five sections with no values, addresses, or paths outside the package; no file anywhere in the package carries a credential value; a lockfile's addresses are the provenance rule 3 exempts and pass, while an address a script calls is reported against rule 2, naming the skill, because a system reached from a script is a system nothing declared; every ceiling entry names the side that enforces it, and an entry over a system the scripts reach with a credential the install file names says runtime; one skill per offering and one offering per skill; the system names in the Descriptor and the install file are the same set, read through the role alias where a package still spells it that way; no job or step declares a how that 12.3 refuses; every run names a command, sits on a job whose how allows one, and uses only the placeholders 12.3 lists; every mcp.json server is a declared system name with no address; every named run config sets only declared settings, with values each setting allows, under a name used once and a digest that matches its entry; the generated views match a fresh generation byte for byte; the manifest's digests match the files; and no text file carries a hidden character. A depot conforms when it refuses a publish without a matching build record, serves immutable versions by digest, marks rather than deletes on withdraw, indexes the two authored files, checks the named run configs as 12.7 says, and scans for hidden characters. An installer conforms when it follows 12.7 in order, stops on a missing runtime, binary, credential, or ceiling, executes nothing from the package, produces a bound Descriptor that differs from the draft only by subject and signatures, keeps the ledger, and states the grade of its check. An installer that produces an image conforms when it executes nothing from the package during the build, resolves each dependency once from its lockfile, places every file the harness reads as instruction inside the image, records the image digest and each file's digest as built in a build record (8.2), and produces no deployment record, because it started nothing. The side that starts the agent produces the one deployment record, and it conforms when it names the image digest it started, states how the subject's key was minted and who holds it in 8.3's key_custody, names each ceiling it set with the side that applies it, and carries nothing its producer did not observe. A deployment record does not conform when it names a target, a placed credential, a ceiling, or a post-start check its producer did not perform, or an image digest for an image it did not start. It conforms with members absent, and a checker that requires a member its producer could not have observed has made the honest record the failing one. An owner-run deployment conforms when every file the harness reads as instruction is the image's rather than mounted over it, when every required ceiling has a number applied by the side its install entry names, and when each job is capped at job_seconds.

Where an agent is kept before it is packaged, and how somebody comes to run a copy of their own, is Section 13 of the specification, the agent repository.