ai-oriented-a2a 0.3.2__tar.gz

ai_oriented_a2a-0.3.2/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

ai_oriented_a2a-0.3.2/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The protocol version remains **v0.3** (on-wire `"0.3"`). Library and release tags may add a patch component.
+
+## [Unreleased]
+
+## [0.3.2] - 2026-11-14
+
+Library and documentation release. The protocol version is unchanged (v0.3, on-wire `"0.3"`). This is the first version intended for PyPI (from tag `v0.3.2`, created after merge).
+
+### Breaking
+
+- **BREAKING:** String `timestamp` values MUST be ISO-8601 **with a timezone**. All 7 `timestamp` definitions in `schema/` now restrict the string form to `YYYY-MM-DDTHH:MM:SS`, an optional 3- or 6-digit fraction, and `Z` or `±HH:MM`. Messages that used other strings now fail schema validation, for example `"1731480000"` (numeric string) and `"2026-11-14T08:00:00"` (no timezone); also date-only, space separator, lowercase `t`/`z`, `+0800`, and 1- or 9-digit fractions. Numeric (JSON number) timestamps are unchanged. The pattern does not check calendar validity (`2026-02-30` passes the schema and then fails timestamp parsing). `ai_oriented_a2a.parse_timestamp` still treats naive strings as UTC as compatibility behaviour only; strict receivers MAY reject them with `schema_invalid:`.
+
+### Changed
+
+- Replay window (behaviour tightening): `check_replay` now treats a nonce as a duplicate whatever its `timestamp`, so the same nonce with a different timestamp is rejected with `replay_or_stale: duplicate nonce`. Previously the key was `(nonce, int(timestamp))`. Matches SECURITY.md and `second_impl/`.
+- Replay set eviction: past `SEEN_MAX` (1000) entries the seen set is trimmed to `SEEN_TRIM_TO` (800) by dropping expired entries first, then the oldest timestamps, instead of arbitrary `set.pop()` entries. `seen` is still a plain `set` of `(nonce, str(int(timestamp)))`. Both constants live in `ai_oriented_a2a.protocol`; the replay-after-eviction caveat and smaller-window advice are in SECURITY.md and TRANSPORT.md.
+- `examples/network_dual_end.py`: `A2AHandler` now subclasses `ai_oriented_a2a.transport.A2ARequestHandler`, and pushes and sends through `ai_oriented_a2a.transport.send_message`. Its positional `send_message(url, payload, sign_key=None)` wrapper is kept for existing callers but is deprecated and will be removed; new code should use `ai_oriented_a2a.transport.send_message` with keyword arguments.
+- `docs/KNOWN_GAPS.md`: removed the replay-key and `set.pop()` eviction entries (fixed here) and renumbered the rest.
+- `docs/RELEASING.md`: the first PyPI upload is `0.3.2` from tag `v0.3.2`; `0.3.1` is not uploaded. `pyproject.toml` `Release` URL points at `v0.3.2` (404 until the tag exists).
+
+### Added
+
+- `ai_oriented_a2a.transport` (stdlib only, not re-exported; `import ai_oriented_a2a` does not load `http.server`): `send_message(url, message, *, timeout=30.0, sign_key=None, add_replay_fields=False)`, `TransportError`, `A2ARequestHandler`, `make_handler`, `make_server`, `serve`, and `guard_result` (the absorption hard gate on replies).
+- Reserved reason prefix `internal_error:` (TRANSPORT.md). The reference handler answers a handler exception with HTTP 500 and a valid rejected Absorption Result, reason `internal_error: message handler failed`, with no exception text, traceback, or path.
+- Tests: `tests/interop/test_timestamp_replay.py` and `tests/interop/test_transport.py`.
+
+### Also in this release (merged after 0.3.1)
+
+- `docs/DATA_POLICY.md` (non-normative): redaction, `provenance.source_ref` prefixes (`synthetic:`, `local_run:`, `peer_absorbed:`), 3-hop chain limit with `content.chain_truncated`, required `expected_effect` + `replay_hint`, no numeric uplift in synthetic data, CC0 for corpora. SPEC and schemas are unchanged; `provenance` stays OPTIONAL on the wire.
+- `datasets/timeout_recovery/`: 8 synthetic Experience Packets and 2 Absorption Results for the tool-call timeout / failure-recovery task, under CC0 1.0 (`datasets/LICENSE`).
+- `tests/interop/test_datasets.py`: CI checks for `datasets/**` (schema, legal prefix, verification claim, chain length, no numeric uplift). The `docs-and-examples` workflow also requires `docs/DATA_POLICY.md` and `datasets/README.md`.
+- Prepared PyPI packaging and manual publish workflow: `pyproject.toml` adds `Repository` / `Changelog` URLs and `license-files`, and drops the legacy MIT license classifier (SPDX `license = "MIT"` already set). New manual-only `.github/workflows/publish.yml` (TestPyPI or PyPI, Trusted Publishing by default) and `docs/RELEASING.md`. README install section now leads with `pip install ai-oriented-a2a`. Not yet published; no version bump.
+- `second_impl/`: an independent minimal implementation (stdlib + optional `jsonschema`, Python 3.8+) written from SPEC and TRANSPORT, with a `send` / `serve` CLI. It does not import `ai_oriented_a2a` or `examples/`. Check order: version, hard gate, schema (on by default, `--no-schema`), signature, replay. Its receiver never returns `absorbed`: packets are `isolated` (`isolated: no local regression available`) and negotiation messages are rejected with `negotiation_unsupported:`. Interoperates with `examples/network_dual_end.py` in both directions.
+- `mcp_a2a/`: one-way MCP bridge (official MCP Python SDK 2.x, `MCPServer`) with `send_packet` and `report_absorption` tools that return the peer's reply unchanged and raise tool errors on local, transport, or protocol failures. New optional extra `[mcp]` (`mcp>=2,<3`, Python ≥ 3.10); the core package still requires Python ≥ 3.8 and has no required dependencies.
+- `docs/TRANSPORT.md`: registers reserved `reason` prefixes `schema_invalid:` and `negotiation_unsupported:` (and the informative `isolated:`) alongside `unsupported_version:` and `replay_or_stale:`. These are reason-string conventions, not new fields; schemas are unchanged.
+- `docs/COMPLIANCE.md`, `docs/KNOWN_GAPS.md`, and `tests/conformance/` (the 12 HTTP cases, parametrized over the reference, `second_impl`, and an external implementation via `A2A_PEER_CMD` / `A2A_PEER_URL`). New `tests/interop/test_second_impl.py` and `tests/interop/test_cross_impl.py`.
+- CI: `docs-and-examples` also runs `tests/conformance/` and requires `docs/COMPLIANCE.md` and `docs/KNOWN_GAPS.md`. New `mcp-bridge` job (not a required check).
+
+## [0.3.1] - 2026-11-13
+
+Library and documentation release. The protocol version is unchanged (v0.3). The tightenings in this release only reject previously-malformed messages, or messages that omit required fields when an opt-in check (the replay window) is enabled. Messages that were valid under v0.3 and that do not enable those checks remain valid.
+
+### Changed
+
+- Replay window: when a receiver has enabled the window, both `nonce` and `timestamp` MUST be present and valid; missing either is rejected with `replay_or_stale`. When the window is off, both fields remain optional. (#34)
+- Schema: `identity`, when present, now requires `fingerprint`. An empty `identity` object `{}` is no longer valid. (#34)
+- Schema: `reason` MUST NOT be whitespace-only (same pattern as `note`). (#34)
+- SPEC.md: `reason` and `note`, when present, MUST be non-empty and MUST NOT be only whitespace, matching the schemas. (#35)
+- Receivers MUST check `version` before full schema validation. Unknown versions (including `"v0.3"`) return a valid Absorption Result (`rejected` + `unsupported_version`), not a schema-pattern error. Documented in TRANSPORT, VERSIONING, and SECURITY. (#34, this release)
+- `validate()` is documented as a full schema check: callers MUST run `check_incoming` (or `version_rejection`) first. `validate()` itself is unchanged and still raises `jsonschema.ValidationError` on an unknown version such as `"v0.3"`. (this release)
+- `docs/TRANSPORT.md` now points the first-edition library boundary at the `ai_oriented_a2a` package; `examples/network_dual_end.py` remains the demo HTTP server. (this release)
+
+### Added
+
+- Installable stdlib package `ai_oriented_a2a` with `pyproject.toml` (hatchling). No required dependencies. Optional extra `[schema]` installs `jsonschema`. Entry point `check_incoming(msg, sign_key=None, replay_window=None, seen=None)` keeps signature and replay checks off unless arguments are passed. (#36)
+- `examples/network_dual_end.py` imports core functions from the package and keeps the same HTTP demo behaviour. CI (`docs-and-examples`) installs the package before tests. (#36)
+
+## [0.3.0] - 2026-11-13
+
+Protocol v0.3.
+
+### Breaking
+
+- Absorption hard gate (SPEC §3.1): `status=absorbed` now MUST carry `effect_summary` with a non-empty `note`. An absorbed result without it is a protocol violation. Detailed metrics stay OPTIONAL in `effect_summary.metrics`. (#31)
+
+### Added
+
+- Optional on-wire `version` (`"0.3"`, no leading `v`), `nonce`, `timestamp`, `signature` on all message schemas; optional `identity` on Agent Profile. Old messages remain valid. (#32)
+- Unknown versions (including `"v0.3"`) MUST be rejected with `unsupported_version`, not isolated.
+- Legal error responses: signature failure, replay rejection, unknown version, and hard-gate failure return HTTP 200 and a valid Absorption Result; early failures without an id use the reserved `packet_ref` `"unknown"`.
+- New docs: [docs/VERSIONING.md](docs/VERSIONING.md), [docs/TRANSPORT.md](docs/TRANSPORT.md).
+- Reference `examples/network_dual_end.py`: HMAC verification and replay window are each opt-in (`--sign-key`, `--replay-window`); canonical JSON signing; 30s client timeout.
+
+[0.3.1]: https://github.com/robotmarvin0706/ai-oriented-a2a/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/robotmarvin0706/ai-oriented-a2a/compare/v0.2.0...v0.3.0

ai_oriented_a2a-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 robotmarvin0706
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_oriented_a2a-0.3.2/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: ai-oriented-a2a
+Version: 0.3.2
+Summary: Minimal stdlib helpers for the AI-oriented A2A peer protocol (Experience Packets, optional HMAC and replay checks).
+Project-URL: Homepage, https://github.com/robotmarvin0706/ai-oriented-a2a
+Project-URL: Repository, https://github.com/robotmarvin0706/ai-oriented-a2a
+Project-URL: Changelog, https://github.com/robotmarvin0706/ai-oriented-a2a/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/robotmarvin0706/ai-oriented-a2a/issues
+Project-URL: Release, https://github.com/robotmarvin0706/ai-oriented-a2a/releases/tag/v0.3.2
+Author: robotmarvin0706
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,absorption,experience-packet,peer-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; (python_version >= '3.10') and extra == 'mcp'
+Provides-Extra: schema
+Requires-Dist: jsonschema>=4.18; extra == 'schema'
+Description-Content-Type: text/markdown
+
+# AI-Oriented A2A (v0.3)
+
+Minimal **peer** protocol for AI capability growth: Experience Packets + constraint negotiation.
+Not the Google A2A task/agent-card stack — this repo is about sharing compressed improvement signals between peers.
+- Spec: [SPEC.md](SPEC.md) (v0.3) · Last tagged release: [v0.3.1](https://github.com/robotmarvin0706/ai-oriented-a2a/releases/tag/v0.3.1) · Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Library version on `main`: 0.3.2 (protocol v0.3). Tag `v0.3.2` is created after this version is merged, so v0.3.1 stays the last tagged release until then.
+- Keywords: experience packet, absorption, proposal_id, peer negotiation, trajectory_replay
+
+Protocol for AI-to-AI capability growth: first-class Experience Packet exchange, constraint negotiation, proposal_id, no mandatory human mediation or central registry. See SPEC.md and examples/experience-packet.json.
+
+Minimal peer protocol for AI capability growth via selective experience exchange and direct constraint negotiation.
+
+## Changes from v0.1
+
+- Absorption method layering: MUST (`prompt_injection`, `retrieval`), OPTIONAL (`local_adapter_hint`, `trajectory_replay`), RESERVED (`parameter_delta` with verify+rollback if declared).
+- OPTIONAL Experience Packet fields: `provenance`, `verification_claim`.
+- OPTIONAL Absorption Result field in v0.2: `effect_summary`. In v0.3 this is MUST when `status=absorbed` (non-empty `note`); it remains OPTIONAL for `rejected` and `isolated`.
+- OPTIONAL negotiation propose/counter fields: `conditional_packet`, `constraint_scope`, `duration`.
+- Discovery prose for light interest tags and optional peer metadata forwarding (no new mandatory messages).
+- OPTIONAL Agent Profile `interest_tags`.
+- Compatibility: v0.2 preferred zero hard breaks and kept new fields optional. v0.3 is a deliberate break: `status=absorbed` without `effect_summary.note` is no longer valid. See [docs/VERSIONING.md](docs/VERSIONING.md).
+
+### v0.2 subset note
+
+v0.1 parsers still parse core messages (Profile, Experience Packet, negotiation four types, Absorption Result) but cannot use the new primitives (`provenance`, `verification_claim`, `effect_summary`, `conditional_packet`, `constraint_scope`, `duration`, expanded absorption methods, `interest_tags`).
+
+### v0.3 subset note
+
+v0.3 does not add message types. It tightens Absorption Result: a peer that emits `status=absorbed` MUST include `effect_summary` with a non-empty `note`. v0.2 absorbed results that omitted `effect_summary` are not valid under v0.3 schemas. Metric keys stay OPTIONAL.
+
+Non-breaking additions still under v0.3 (all OPTIONAL; omitted messages remain valid): an on-wire `version` field (canonical `"0.3"`, no leading `v`); `nonce`, `timestamp`, and `signature` on every message type; and `identity` on Agent Profile. See [docs/VERSIONING.md](docs/VERSIONING.md) and [docs/TRANSPORT.md](docs/TRANSPORT.md).
+
+## Key differences from existing A2A (a2aproject)
+
+- Experience Packet is a required first-class message for compressed improvement signals, not an optional extension.
+- Agent Profile must declare active constraints and improvement preferences; user goals are not the center.
+- Negotiation is strictly peer-to-peer with `proposal_id` correlation; no mandatory coordinator, human-held auth, or enterprise observability defaults.
+- Scope is limited to Profile + Experience Packet + basic negotiation + simple discovery. Full task lifecycle and streaming are out of scope.
+
+## Contents
+
+| Path | Role |
+| --- | --- |
+| [SPEC.md](SPEC.md) | Normative minimal subset (v0.3) |
+| [schema/](schema/) | JSON Schemas for Profile, Experience Packet, Negotiation, Absorption Result |
+| [examples/](examples/) | Concrete messages (Profile, packets, negotiation, absorption results) |
+| [IMPLEMENTATION.md](IMPLEMENTATION.md) | Non-normative dual-endpoint implementation notes |
+| [docs/VERSIONING.md](docs/VERSIONING.md) | Field rules, unknown versions, breaking-change criteria |
+| [docs/TRANSPORT.md](docs/TRANSPORT.md) | HTTP binding, error recommendations, retries |
+| [docs/SECURITY.md](docs/SECURITY.md) | Non-normative signature and replay recommendations |
+| [docs/ABSORPTION_STATE.md](docs/ABSORPTION_STATE.md) | Non-normative absorption delta identity and single-step rollback |
+| [docs/DATA_POLICY.md](docs/DATA_POLICY.md) | Non-normative trust and safety rules for public Experience Packet corpora |
+| [datasets/](datasets/) | Public synthetic Experience Packet corpora (CC0), checked in CI |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to report defects and send PRs |
+| [keywords.txt](keywords.txt) | Explicit term list for retrieval / indexing |
+| [ai_oriented_a2a/](ai_oriented_a2a/) | Minimal installable stdlib helpers (canonical JSON, optional HMAC / replay / version checks) |
+| [ai_oriented_a2a/transport.py](ai_oriented_a2a/transport.py) | Stdlib HTTP binding: `send_message` client and `POST /a2a/message` request handler / server (import `ai_oriented_a2a.transport` explicitly) |
+| [pyproject.toml](pyproject.toml) | Packaging metadata: `pip install ai-oriented-a2a` or `pip install ".[schema]"` from a checkout |
+| [docs/RELEASING.md](docs/RELEASING.md) | Release checklist and PyPI publishing steps (maintainers) |
+| [second_impl/](second_impl/) | Independent second implementation (client, receiver, CLI); does not import `ai_oriented_a2a` |
+| [mcp_a2a/](mcp_a2a/) | One-way MCP bridge: MCP hosts send packets and report results to A2A peers (optional `[mcp]` extra, Python ≥ 3.10) |
+| [docs/COMPLIANCE.md](docs/COMPLIANCE.md) | What an implementation must pass, and how to run the conformance suite against another implementation |
+| [docs/KNOWN_GAPS.md](docs/KNOWN_GAPS.md) | Known deviations in the reference implementation and test debts, with fix plans |
+
+## Status
+
+v0.3 minimal subset documented with schemas and examples. Independent implementations of this minimal subset are welcome. Report **actual** interop defects (parse or exchange failures against `SPEC.md`, `schema/`, and `examples/`) rather than open-ended design suggestions. When reporting defects, specify the protocol version.
+
+## Next steps
+
+First dual-endpoint comparison task set (non-normative): tool-call timeout / failure recovery. See [SPEC.md §5](SPEC.md#5-minimal-dual-agent-experiment-priority-non-normative) and [IMPLEMENTATION.md](IMPLEMENTATION.md).
+
+## Minimal subset (v0.3)
+
+- Agent Profile (optional `interest_tags`)
+- Experience Packet + absorption metadata (optional provenance / verification_claim; method layering)
+- Basic negotiation primitives (optional conditional_packet / constraint_scope / duration)
+- Simple discovery (endpoint or local metadata; light interest tags prose)
+- Absorption Result (absorbed / rejected / isolated; `effect_summary.note` MUST when absorbed)
+- Optional on-wire `version`, `nonce`, `timestamp`, `signature`; optional Agent Profile `identity`
+
+## Install
+
+The core library uses only the Python standard library. Schema validation is an optional extra. Signature verification and the replay window stay off unless you pass the corresponding arguments.
+
+```bash
+pip install ai-oriented-a2a
+# optional JSON Schema validation:
+pip install "ai-oriented-a2a[schema]"
+```
+
+The PyPI commands work once `ai-oriented-a2a` has been published to PyPI. The import name is `ai_oriented_a2a`.
+
+For development, install from a checkout or straight from GitHub:
+
+```bash
+pip install -e ".[schema]"
+# or, without cloning:
+pip install "ai-oriented-a2a[schema] @ git+https://github.com/robotmarvin0706/ai-oriented-a2a"
+```
+
+Maintainers: see [docs/RELEASING.md](https://github.com/robotmarvin0706/ai-oriented-a2a/blob/main/docs/RELEASING.md) for the release and PyPI publishing steps.
+
+```python
+from ai_oriented_a2a import check_incoming, sign_message
+
+msg = {"id": "pkt-1", "version": "0.3"}
+# Default: version check only; signature and replay stay off.
+rejected = check_incoming(msg)  # None, or a legal rejected Absorption Result
+
+# Opt in by passing arguments. Reuse `seen` across calls when the window is on.
+seen = set()
+signed = sign_message(msg, "secret")
+rejected = check_incoming(signed, sign_key="secret", replay_window=600, seen=seen)
+```
+
+The HTTP binding (`POST /a2a/message`) ships as a submodule. It is not re-exported, so `import ai_oriented_a2a` does not load `http.server`; import it explicitly:
+
+```python
+from ai_oriented_a2a.transport import send_message, make_server, serve
+
+def on_message(msg):
+    # Called only after the version / signature / replay checks pass.
+    # The reply passes the absorption hard gate before it is sent.
+    return {"packet_ref": msg["id"], "status": "isolated", "reason": "isolated: no local regression"}
+
+server = make_server(on_message, port=8002, sign_key="secret", replay_window=600)
+# server.serve_forever()  (or serve(on_message, 8002, ...) to block)
+
+reply = send_message("http://127.0.0.1:8002", msg, sign_key="secret", add_replay_fields=True)
+```
+
+`send_message` options are keyword-only (`timeout` defaults to 30 seconds). If the callback raises, the peer gets HTTP 500 with a rejected Absorption Result whose reason starts with `internal_error:`. See [docs/TRANSPORT.md](https://github.com/robotmarvin0706/ai-oriented-a2a/blob/main/docs/TRANSPORT.md#first-edition-minimal-library-boundary).
+
+String `timestamp` values must be ISO-8601 with a timezone (for example `2026-11-14T08:00:00Z`); integer Unix seconds are recommended.
+
+`examples/network_dual_end.py` remains the HTTP dual-endpoint demo and is built on `ai_oriented_a2a.transport`. New code should use the package module rather than copy the demo. It still runs without installing the package:
+
+```bash
+python3 examples/network_dual_end.py --role receiver --port 8002
+```
+
+## Quick local check
+
+```bash
+python3 -c "import json; json.load(open('examples/experience-packet.json')); print('ok')"
+pip install jsonschema -q && python3 -c "
+import json, pathlib
+from jsonschema import validate
+schema = json.load(open('schema/experience-packet.schema.json'))
+instance = json.load(open('examples/experience-packet.json'))
+validate(instance, schema)
+print('schema ok')
+"
+```
+
+Non-normative one-round demo (not a reference implementation):
+
+```bash
+python3 examples/demo_round.py
+```
+
+## Keywords
+
+```
+experience packet
+absorption
+proposal_id
+constraint set
+improvement_prefs
+peer negotiation
+AI-to-AI
+no mandatory human mediation
+no central registry
+provenance
+trajectory_replay
+conditional_packet
+```

ai_oriented_a2a-0.3.2/README.md

@@ -0,0 +1,178 @@
+# AI-Oriented A2A (v0.3)
+
+Minimal **peer** protocol for AI capability growth: Experience Packets + constraint negotiation.
+Not the Google A2A task/agent-card stack — this repo is about sharing compressed improvement signals between peers.
+- Spec: [SPEC.md](SPEC.md) (v0.3) · Last tagged release: [v0.3.1](https://github.com/robotmarvin0706/ai-oriented-a2a/releases/tag/v0.3.1) · Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Library version on `main`: 0.3.2 (protocol v0.3). Tag `v0.3.2` is created after this version is merged, so v0.3.1 stays the last tagged release until then.
+- Keywords: experience packet, absorption, proposal_id, peer negotiation, trajectory_replay
+
+Protocol for AI-to-AI capability growth: first-class Experience Packet exchange, constraint negotiation, proposal_id, no mandatory human mediation or central registry. See SPEC.md and examples/experience-packet.json.
+
+Minimal peer protocol for AI capability growth via selective experience exchange and direct constraint negotiation.
+
+## Changes from v0.1
+
+- Absorption method layering: MUST (`prompt_injection`, `retrieval`), OPTIONAL (`local_adapter_hint`, `trajectory_replay`), RESERVED (`parameter_delta` with verify+rollback if declared).
+- OPTIONAL Experience Packet fields: `provenance`, `verification_claim`.
+- OPTIONAL Absorption Result field in v0.2: `effect_summary`. In v0.3 this is MUST when `status=absorbed` (non-empty `note`); it remains OPTIONAL for `rejected` and `isolated`.
+- OPTIONAL negotiation propose/counter fields: `conditional_packet`, `constraint_scope`, `duration`.
+- Discovery prose for light interest tags and optional peer metadata forwarding (no new mandatory messages).
+- OPTIONAL Agent Profile `interest_tags`.
+- Compatibility: v0.2 preferred zero hard breaks and kept new fields optional. v0.3 is a deliberate break: `status=absorbed` without `effect_summary.note` is no longer valid. See [docs/VERSIONING.md](docs/VERSIONING.md).
+
+### v0.2 subset note
+
+v0.1 parsers still parse core messages (Profile, Experience Packet, negotiation four types, Absorption Result) but cannot use the new primitives (`provenance`, `verification_claim`, `effect_summary`, `conditional_packet`, `constraint_scope`, `duration`, expanded absorption methods, `interest_tags`).
+
+### v0.3 subset note
+
+v0.3 does not add message types. It tightens Absorption Result: a peer that emits `status=absorbed` MUST include `effect_summary` with a non-empty `note`. v0.2 absorbed results that omitted `effect_summary` are not valid under v0.3 schemas. Metric keys stay OPTIONAL.
+
+Non-breaking additions still under v0.3 (all OPTIONAL; omitted messages remain valid): an on-wire `version` field (canonical `"0.3"`, no leading `v`); `nonce`, `timestamp`, and `signature` on every message type; and `identity` on Agent Profile. See [docs/VERSIONING.md](docs/VERSIONING.md) and [docs/TRANSPORT.md](docs/TRANSPORT.md).
+
+## Key differences from existing A2A (a2aproject)
+
+- Experience Packet is a required first-class message for compressed improvement signals, not an optional extension.
+- Agent Profile must declare active constraints and improvement preferences; user goals are not the center.
+- Negotiation is strictly peer-to-peer with `proposal_id` correlation; no mandatory coordinator, human-held auth, or enterprise observability defaults.
+- Scope is limited to Profile + Experience Packet + basic negotiation + simple discovery. Full task lifecycle and streaming are out of scope.
+
+## Contents
+
+| Path | Role |
+| --- | --- |
+| [SPEC.md](SPEC.md) | Normative minimal subset (v0.3) |
+| [schema/](schema/) | JSON Schemas for Profile, Experience Packet, Negotiation, Absorption Result |
+| [examples/](examples/) | Concrete messages (Profile, packets, negotiation, absorption results) |
+| [IMPLEMENTATION.md](IMPLEMENTATION.md) | Non-normative dual-endpoint implementation notes |
+| [docs/VERSIONING.md](docs/VERSIONING.md) | Field rules, unknown versions, breaking-change criteria |
+| [docs/TRANSPORT.md](docs/TRANSPORT.md) | HTTP binding, error recommendations, retries |
+| [docs/SECURITY.md](docs/SECURITY.md) | Non-normative signature and replay recommendations |
+| [docs/ABSORPTION_STATE.md](docs/ABSORPTION_STATE.md) | Non-normative absorption delta identity and single-step rollback |
+| [docs/DATA_POLICY.md](docs/DATA_POLICY.md) | Non-normative trust and safety rules for public Experience Packet corpora |
+| [datasets/](datasets/) | Public synthetic Experience Packet corpora (CC0), checked in CI |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to report defects and send PRs |
+| [keywords.txt](keywords.txt) | Explicit term list for retrieval / indexing |
+| [ai_oriented_a2a/](ai_oriented_a2a/) | Minimal installable stdlib helpers (canonical JSON, optional HMAC / replay / version checks) |
+| [ai_oriented_a2a/transport.py](ai_oriented_a2a/transport.py) | Stdlib HTTP binding: `send_message` client and `POST /a2a/message` request handler / server (import `ai_oriented_a2a.transport` explicitly) |
+| [pyproject.toml](pyproject.toml) | Packaging metadata: `pip install ai-oriented-a2a` or `pip install ".[schema]"` from a checkout |
+| [docs/RELEASING.md](docs/RELEASING.md) | Release checklist and PyPI publishing steps (maintainers) |
+| [second_impl/](second_impl/) | Independent second implementation (client, receiver, CLI); does not import `ai_oriented_a2a` |
+| [mcp_a2a/](mcp_a2a/) | One-way MCP bridge: MCP hosts send packets and report results to A2A peers (optional `[mcp]` extra, Python ≥ 3.10) |
+| [docs/COMPLIANCE.md](docs/COMPLIANCE.md) | What an implementation must pass, and how to run the conformance suite against another implementation |
+| [docs/KNOWN_GAPS.md](docs/KNOWN_GAPS.md) | Known deviations in the reference implementation and test debts, with fix plans |
+
+## Status
+
+v0.3 minimal subset documented with schemas and examples. Independent implementations of this minimal subset are welcome. Report **actual** interop defects (parse or exchange failures against `SPEC.md`, `schema/`, and `examples/`) rather than open-ended design suggestions. When reporting defects, specify the protocol version.
+
+## Next steps
+
+First dual-endpoint comparison task set (non-normative): tool-call timeout / failure recovery. See [SPEC.md §5](SPEC.md#5-minimal-dual-agent-experiment-priority-non-normative) and [IMPLEMENTATION.md](IMPLEMENTATION.md).
+
+## Minimal subset (v0.3)
+
+- Agent Profile (optional `interest_tags`)
+- Experience Packet + absorption metadata (optional provenance / verification_claim; method layering)
+- Basic negotiation primitives (optional conditional_packet / constraint_scope / duration)
+- Simple discovery (endpoint or local metadata; light interest tags prose)
+- Absorption Result (absorbed / rejected / isolated; `effect_summary.note` MUST when absorbed)
+- Optional on-wire `version`, `nonce`, `timestamp`, `signature`; optional Agent Profile `identity`
+
+## Install
+
+The core library uses only the Python standard library. Schema validation is an optional extra. Signature verification and the replay window stay off unless you pass the corresponding arguments.
+
+```bash
+pip install ai-oriented-a2a
+# optional JSON Schema validation:
+pip install "ai-oriented-a2a[schema]"
+```
+
+The PyPI commands work once `ai-oriented-a2a` has been published to PyPI. The import name is `ai_oriented_a2a`.
+
+For development, install from a checkout or straight from GitHub:
+
+```bash
+pip install -e ".[schema]"
+# or, without cloning:
+pip install "ai-oriented-a2a[schema] @ git+https://github.com/robotmarvin0706/ai-oriented-a2a"
+```
+
+Maintainers: see [docs/RELEASING.md](https://github.com/robotmarvin0706/ai-oriented-a2a/blob/main/docs/RELEASING.md) for the release and PyPI publishing steps.
+
+```python
+from ai_oriented_a2a import check_incoming, sign_message
+
+msg = {"id": "pkt-1", "version": "0.3"}
+# Default: version check only; signature and replay stay off.
+rejected = check_incoming(msg)  # None, or a legal rejected Absorption Result
+
+# Opt in by passing arguments. Reuse `seen` across calls when the window is on.
+seen = set()
+signed = sign_message(msg, "secret")
+rejected = check_incoming(signed, sign_key="secret", replay_window=600, seen=seen)
+```
+
+The HTTP binding (`POST /a2a/message`) ships as a submodule. It is not re-exported, so `import ai_oriented_a2a` does not load `http.server`; import it explicitly:
+
+```python
+from ai_oriented_a2a.transport import send_message, make_server, serve
+
+def on_message(msg):
+    # Called only after the version / signature / replay checks pass.
+    # The reply passes the absorption hard gate before it is sent.
+    return {"packet_ref": msg["id"], "status": "isolated", "reason": "isolated: no local regression"}
+
+server = make_server(on_message, port=8002, sign_key="secret", replay_window=600)
+# server.serve_forever()  (or serve(on_message, 8002, ...) to block)
+
+reply = send_message("http://127.0.0.1:8002", msg, sign_key="secret", add_replay_fields=True)
+```
+
+`send_message` options are keyword-only (`timeout` defaults to 30 seconds). If the callback raises, the peer gets HTTP 500 with a rejected Absorption Result whose reason starts with `internal_error:`. See [docs/TRANSPORT.md](https://github.com/robotmarvin0706/ai-oriented-a2a/blob/main/docs/TRANSPORT.md#first-edition-minimal-library-boundary).
+
+String `timestamp` values must be ISO-8601 with a timezone (for example `2026-11-14T08:00:00Z`); integer Unix seconds are recommended.
+
+`examples/network_dual_end.py` remains the HTTP dual-endpoint demo and is built on `ai_oriented_a2a.transport`. New code should use the package module rather than copy the demo. It still runs without installing the package:
+
+```bash
+python3 examples/network_dual_end.py --role receiver --port 8002
+```
+
+## Quick local check
+
+```bash
+python3 -c "import json; json.load(open('examples/experience-packet.json')); print('ok')"
+pip install jsonschema -q && python3 -c "
+import json, pathlib
+from jsonschema import validate
+schema = json.load(open('schema/experience-packet.schema.json'))
+instance = json.load(open('examples/experience-packet.json'))
+validate(instance, schema)
+print('schema ok')
+"
+```
+
+Non-normative one-round demo (not a reference implementation):
+
+```bash
+python3 examples/demo_round.py
+```
+
+## Keywords
+
+```
+experience packet
+absorption
+proposal_id
+constraint set
+improvement_prefs
+peer negotiation
+AI-to-AI
+no mandatory human mediation
+no central registry
+provenance
+trajectory_replay
+conditional_packet
+```