Metadata-Version: 2.5
Name: agent-approval-interchange
Version: 0.2.0
Summary: Python support library for the Agent Approval Interchange Specification
Project-URL: Homepage, https://github.com/alexmerced-oss/agent-approval-interchange-spec
Project-URL: Specification, https://github.com/alexmerced-oss/agent-approval-interchange-spec/blob/main/spec/v1/SPEC.md
Author: Alex Merced
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,approval,human-in-the-loop,specification
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.18
Requires-Dist: rfc8785<0.2,>=0.1.4
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Description-Content-Type: text/markdown

# Agent Approval Interchange Specification (AAIS)

**A transport-neutral contract for asking a human to authorize an exact agent action.**

Specification `1.0` release candidate · support libraries `0.1.0` · Released · Python library `0.2.0` released

[Specification](spec/v1/SPEC.md) · [Security](spec/v1/security.md) · [Conformance](spec/v1/conformance.md) · [Integration guide](docs/integration.md) · [WebMCP mapping](docs/webmcp.md)

AAIS lets a harness pause any chat, bot, subagent, or graph node and hand a
portable approval request to a CLI, web UI, desktop app, policy service, or
other trusted decision surface. The response is cryptographically bound to the
exact action shown to the user, is idempotent, expires predictably, and cannot
grant a broader scope than the harness offered.

```json
{
  "aais": "1.0",
  "type": "approval.requested",
  "id": "evt_01JQ8QH80E4M7KJ6J7J7Y2RKSC",
  "occurred_at": "2026-08-30T18:00:00Z",
  "sequence": 41,
  "request": {
    "id": "apr_01JQ8QH80E4M7KJ6J7J7Y2RKSC",
    "created_at": "2026-08-30T18:00:00Z",
    "expires_at": "2026-08-30T18:10:00Z",
    "status": "pending",
    "origin": {"harness": "example", "session_id": "s-1", "run_id": "r-7"},
    "action": {
      "kind": "tool.call",
      "name": "shell.exec",
      "summary": "Run the JavaScript syntax check",
      "arguments": {"command": "node --check script.js"}
    },
    "action_digest": "sha256:...",
    "risk": {"level": "medium", "reasons": ["executes a local process"]},
    "choices": [
      {"decision": "approve", "scope": "once", "label": "Allow once"},
      {"decision": "approve", "scope": "session", "label": "Allow for this session",
       "scope_constraints": {"action_name": "shell.exec"}},
      {"decision": "deny", "scope": "once", "label": "Deny"}
    ]
  }
}
```

## Scope

AAIS standardizes the authority-bearing boundary only:

- exact-action requests, human-readable presentation, risk, and provenance;
- explicit approve, deny, and cancel decisions with bounded scopes;
- action digests, expiry, idempotency, stale-decision rejection, and receipts;
- durable snapshots and ordered events for reconnecting clients;
- adapter mappings for AG-UI interrupts, MCP hosts, HTTP/SSE, WebSocket, and stdio.

It does **not** define chat messages, model reasoning, tool discovery, agent
profiles, workflow graphs, authentication, or a network transport. Those remain
the responsibility of AG-UI, MCP, OAP, AGS, the host application, or another
runtime protocol.

## Support libraries

The repository contains release-candidate libraries with a shared API and
conformance corpus for Python, TypeScript, Go, Rust, and Java. Each library can:

- validate AAIS envelopes;
- compute RFC 8785 / SHA-256 action digests;
- create approval requests and decisions;
- maintain a fail-closed, replay-safe pending-approval store;
- emit and restore durable snapshots.

The Python library adds `aais.store.FileApprovalStore` in 0.2.0.
It is a stdlib-only approval authority that several processes can share
through one JSON file. It locks whole transactions across processes, writes
atomically with fsync, quarantines corrupt state instead of reading it as
empty, compacts resolved history with an explicit replay-gap signal, and
tracks owners by PID, start time, and host so that PID reuse cannot keep a
stopped owner alive. Storage is pluggable: `ApprovalAuthority` accepts any
backend that implements the `aais.backends` protocols, and `aais.testing`
provides a conformance kit for third-party backends. See the
[Python durable file store](docs/python-file-store.md) guide.

Published packages:

- [PyPI](https://pypi.org/project/agent-approval-interchange/0.1.0/)
- [npm](https://www.npmjs.com/package/agent-approval-interchange/v/0.1.0)
- [Go module](https://pkg.go.dev/github.com/alexmerced-oss/agent-approval-interchange-spec/go@v0.1.0)
- [crates.io](https://crates.io/crates/agent-approval-interchange/0.1.0)
- [Maven Central](https://central.sonatype.com/artifact/io.github.alexmercedcoder/agent-approval-interchange/0.1.0)

See [release preparation](docs/release.md) for coordinates and verification.

## Repository layout

| Path | Contents |
| --- | --- |
| `spec/v1/` | Normative specification, security, and conformance rules |
| `schema/v1/` | JSON Schema Draft 2020-12 envelope schema |
| `conformance/` | Shared valid and invalid fixtures |
| `python/` | Python 3.10+ support package |
| `typescript/` | Node.js 20+ TypeScript package |
| `go/` | Go 1.23+ module |
| `rust/` | Rust 1.85+ crate |
| `java/` | Java 17+ Maven library |

## Design principles

1. **The harness remains the authority.** A UI conveys a decision; the harness
   revalidates it against current policy and current action state.
2. **Approval is exact by default.** Every approval carries the digest of the
   canonical action reviewed by the user.
3. **Scopes are offered, never invented.** A client may select only a choice
   present in the request.
4. **Reconnect is normal.** Pending approvals are durable state, not a terminal
   prompt waiting on stdin.
5. **No hidden reasoning is required.** AAIS carries concise activity,
   provenance, and risk explanations—not private chain-of-thought.

## License

Apache License 2.0. See [LICENSE](LICENSE).
