asop

The ASOP contract — a versioned, verified, self-revising procedure standard for agentic work.

This repository is the normative specification (ASOP.md) and its reference implementation. It is deliberately standalone: it depends on nothing, and nothing in it imports a coordination plane or a runtime.

Two implementations speak it today — the AgentCo Hub (coordination) and the AgentCo Harness (execution). They are independent of each other, and both are mine: the standard has not yet been implemented by anyone who did not also write it, which is the honest status and the thing I would most like to change.

What exists to make that possible: a normative schema as JSON Schema in YAML, and 39 conformance vectors as data, so an implementation in any language can prove it conforms without depending on this package or reading a line of Python.

The ASOP contract, as code. A procedure that is versioned, verified, and self-revising is only useful if two independently-owned pieces of software — a coordination plane and the harness actually running the work — agree on what a gate, an attestation, and a procedure record are, without either importing the other. This package is that agreement.

Who imports this

• The AgentCo Hub (agentco/gates.py, agentco/errors.py, agentco/sop.py and agentco/policy.py are thin shims over this package, keeping every existing caller and test unchanged).
• The AgentCo Harness, the standalone execution runtime, from its P2 (adopting this schema in place of its own VERIFY_KEYS/validate_verify).
• Anyone else building a plane or a harness that wants to speak the same gate shape as either, without depending on the code that runs either one.

What's here

The gate schema

One canonical field decides the shape: kind (deterministic \| judged \| human). class is accepted as a read alias — the Harness's historical name for the same field — and normalised output always uses kind. Sending both, disagreeing, is refused.

Three field groups:

• core (always required) — kind, and exactly one of check (one command) or checks (an ordered, staged list; a one-element checks normalises into check).
• clock (the plane's park clock) — max_park_seconds, on_timeout, escalate_to (only with on_timeout: escalate), verifier (required for human, refused for deterministic, optional for judged). Declared as a whole or not at all — a gate carrying some of these fields but not both max_park_seconds and on_timeout is always refused, regardless of whether a caller requires the clock at all.
• execution (the Harness's runtime hints) — cwd, timeout_s, rubric (judged only), judge_route (judged only).

Whether the clock group is mandatory is the one thing that differs by caller, and the one knob validate_gate exposes: require=("clock",) is the plane's convention today; require=() is a caller with no park-clock concept, such as the Harness before it adopts one. The 30-day park-clock ceiling is not a package constant — it is the plane's own decision about its own registry, passed in as max_park_seconds_ceiling. A caller with no ceiling passes None.

Output is always fully normalised: every known field present (None where absent), plus "schema_version": 1.

Versioning

asop.SCHEMA_VERSION covers the gate schema's normalised shape. It bumps only on a breaking change — a new required field, a renamed one, a changed type. An additive optional field or a new refusal code does not bump it, because existing readers already tolerate both. See asop/__init__.py.

Install

pip install asop-spec      # or: uv add asop-spec

The distribution is asop-spec; the import is asop:

from asop import validate_gate, Refusal

(The bare asop name on PyPI was taken by an unrelated placeholder before this package existed.)

Standard library only, and that is a rule rather than a coincidence. This package is imported by every side of the contract, so a dependency taken here is forced on everyone who speaks it. A standard that drags a dependency tree behind it is a framework wearing a standard's clothes.

Testing

uv run --extra dev pytest -q                                         # 150 tests
uv run --with pyyaml python conformance/runner/python.py --verbose   # 61 vectors

pytest is a dev dependency, not a default one — a bare uv run pytest fails with "Failed to spawn: pytest" because nothing is installed to spawn; --extra dev is what pulls it in. The conformance runner takes PyYAML the same way, inline rather than as a dependency, for the reason given above: asop itself has none. See conformance/README.md for what a vector is, how counts are recomputed rather than typed by hand, and what the suite does not yet prove.

Licence

Apache License 2.0. The patent grant is the point: this package is the contract other people's harnesses are asked to depend on, and a contract adopted across organisations needs the grant stated in the file rather than implied.

Copyright 2026 Marcelo Bidoli Fernandes and the ASOP Authors.