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 independent implementations speak it today — the AgentCo Hub (coordination) and the AgentCo Harness (execution). Others are welcome; that is the point of writing it down.

v3 (2026-09-04). The record contract now carries ASOP — a versioned, ordered sequence of Steps for one type of task, with the gate on the step — alongside the legacy single-record SOP, which stays importable only until the plane's store migrates and is then deleted. validate_asop / validate_step are the v3 entry points; validate_fields is v2's. The definition, verbs and the seven decisions behind v3 are in ASOP.md.

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.

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.