ai-oriented-a2a 0.3.2__py3-none-any.whl

ai_oriented_a2a/__init__.py

@@ -0,0 +1,51 @@
+"""Minimal stdlib library for the AI-oriented A2A peer protocol (v0.3).
+
+Required dependencies: none (Python standard library only). Schema
+validation is an optional extra: ``pip install 'ai-oriented-a2a[schema]'``.
+
+Signature verification and the replay window stay off unless the
+caller passes ``sign_key`` or ``replay_window``. There is no HTTP
+server and no central component in this package.
+"""
+
+from .protocol import (
+    RESERVED_PACKET_REF,
+    SUPPORTED_MAJOR_MINOR,
+    VERSION_PATTERN,
+    canonical,
+    check_incoming,
+    check_replay,
+    new_id,
+    packet_ref_of,
+    parse_timestamp,
+    reject_result,
+    sign_message,
+    supported_version,
+    verify_message,
+    version_rejection,
+)
+from .validate import SchemaDependencyError, SCHEMA_KINDS, schema_dir, validate
+
+__version__ = "0.3.2"
+
+__all__ = [
+    "RESERVED_PACKET_REF",
+    "SCHEMA_KINDS",
+    "SUPPORTED_MAJOR_MINOR",
+    "VERSION_PATTERN",
+    "SchemaDependencyError",
+    "__version__",
+    "canonical",
+    "check_incoming",
+    "check_replay",
+    "new_id",
+    "packet_ref_of",
+    "parse_timestamp",
+    "reject_result",
+    "schema_dir",
+    "sign_message",
+    "supported_version",
+    "validate",
+    "verify_message",
+    "version_rejection",
+]

ai_oriented_a2a/protocol.py

@@ -0,0 +1,232 @@
+"""Stdlib helpers for the AI-oriented A2A peer protocol (v0.3).
+
+No mandatory signature or replay checks, no HTTP server, and no
+central components. Signature and replay stay off unless the caller
+passes ``sign_key`` or ``replay_window``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Set, Tuple
+
+RESERVED_PACKET_REF = "unknown"
+VERSION_PATTERN = re.compile(r"^\d+\.\d+(\.\d+)?$")
+SUPPORTED_MAJOR_MINOR = (0, 3)
+
+
+def new_id(prefix: str = "pkt") -> str:
+    return f"{prefix}-{uuid.uuid4().hex[:8]}"
+
+
+def canonical(obj: Dict[str, Any]) -> bytes:
+    """Return canonical JSON bytes used for HMAC-SHA256 signatures.
+
+    The canonical form is the UTF-8 encoding of
+    ``json.dumps(obj, separators=(",", ":"), sort_keys=True, ensure_ascii=False)``.
+    The caller MUST pass an object that already excludes the ``signature``
+    field; other fields (including ``version``, ``nonce``, and ``timestamp``)
+    are included. ``sort_keys=True`` applies recursively. Integer Unix
+    seconds are recommended for ``timestamp`` so float formatting does not
+    affect the digest.
+    """
+    return json.dumps(
+        obj, separators=(",", ":"), sort_keys=True, ensure_ascii=False
+    ).encode("utf-8")
+
+
+def sign_message(msg: Dict[str, Any], key: str) -> Dict[str, Any]:
+    body = {k: v for k, v in msg.items() if k != "signature"}
+    sig = hmac.new(key.encode(), canonical(body), hashlib.sha256).hexdigest()
+    out = dict(msg)
+    out["signature"] = {"alg": "hmac-sha256", "value": sig}
+    return out
+
+
+def verify_message(msg: Dict[str, Any], key: str) -> bool:
+    sig_obj = msg.get("signature")
+    if not isinstance(sig_obj, dict) or sig_obj.get("alg") != "hmac-sha256":
+        return False
+    body = {k: v for k, v in msg.items() if k != "signature"}
+    expected = hmac.new(key.encode(), canonical(body), hashlib.sha256).hexdigest()
+    value = sig_obj.get("value", "")
+    if not isinstance(value, str):
+        return False
+    return hmac.compare_digest(expected, value)
+
+
+def packet_ref_of(msg: Optional[Dict[str, Any]]) -> str:
+    """Usable packet_ref for an Absorption Result, or the reserved literal."""
+    if not msg:
+        return RESERVED_PACKET_REF
+    for key in ("id", "packet_ref"):
+        val = msg.get(key)
+        if isinstance(val, str) and val.strip():
+            return val
+    return RESERVED_PACKET_REF
+
+
+def reject_result(msg: Optional[Dict[str, Any]], reason: str) -> Dict[str, Any]:
+    return {
+        "packet_ref": packet_ref_of(msg),
+        "status": "rejected",
+        "reason": reason,
+    }
+
+
+def parse_timestamp(ts: Any) -> Optional[float]:
+    """Parse a unix-seconds number or an ISO-8601 string into epoch seconds.
+
+    Naive (no timezone) strings are treated as UTC. This is compatibility
+    behaviour only: the published schemas require a timezone, and strict
+    receivers MAY reject such strings with ``schema_invalid:``. A trailing
+    ``Z`` is accepted. Returns None if the value cannot be parsed.
+    """
+    if isinstance(ts, bool):
+        return None
+    if isinstance(ts, (int, float)):
+        return float(ts)
+    if isinstance(ts, str) and ts.strip():
+        text = ts.strip()
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(text)
+        except ValueError:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    return None
+
+
+def supported_version(value: str) -> bool:
+    """True if an on-wire version string is the current 0.3 minor line."""
+    if not VERSION_PATTERN.match(value):
+        return False
+    parts = value.split(".")
+    return (int(parts[0]), int(parts[1])) == SUPPORTED_MAJOR_MINOR
+
+
+def version_rejection(msg: Dict[str, Any]) -> Optional[str]:
+    """Return an unsupported_version reason, or None if the message is fine.
+
+    Omitted version is treated as the current normative version (0.3).
+    A leading ``v`` or any other pattern failure, and any recognized-pattern
+    value that is not the 0.3 line, MUST be rejected.
+    """
+    if "version" not in msg:
+        return None
+    raw = msg["version"]
+    display = raw if isinstance(raw, str) else repr(raw)
+    if not isinstance(raw, str) or not supported_version(raw):
+        return f"unsupported_version: received {display}"
+    return None
+
+
+# Replay cache bounds. ``seen`` stays a plain ``set`` of ``(nonce, str(int(ts)))``
+# keys; when it grows past SEEN_MAX it is trimmed to SEEN_TRIM_TO, dropping
+# expired keys first and then the oldest timestamps (never arbitrary keys).
+SEEN_MAX = 1000
+SEEN_TRIM_TO = 800
+
+
+def _key_ts(key: Tuple[str, str]) -> float:
+    try:
+        return float(key[1])
+    except (TypeError, ValueError, IndexError):
+        return float("-inf")
+
+
+def _evict(seen: Set[Tuple[str, str]], now: float, window_seconds: float) -> None:
+    """Trim ``seen`` to SEEN_TRIM_TO: expired keys first, then oldest timestamp.
+
+    Expired keys can never be accepted again (the timestamp check runs
+    first), so dropping them is free. Dropping a key that is still inside
+    the window means that nonce could be replayed; keep the window short
+    if that matters (docs/SECURITY.md).
+    """
+    for key in [k for k in seen if abs(now - _key_ts(k)) > window_seconds]:
+        seen.discard(key)
+    excess = len(seen) - SEEN_TRIM_TO
+    if excess > 0:
+        for key in sorted(seen, key=lambda k: (_key_ts(k), k))[:excess]:
+            seen.discard(key)
+
+
+def check_replay(
+    msg: Dict[str, Any],
+    seen: Set[Tuple[str, str]],
+    window_seconds: float,
+) -> Optional[str]:
+    """Return reason string if replay/stale, else None. Mutates seen on accept.
+
+    Called only when a replay window has been enabled.
+    Both nonce and timestamp are required when the window is on.
+
+    A nonce is a duplicate if it is already in ``seen``, whatever its
+    timestamp (the same nonce with a different timestamp is rejected).
+    ``seen`` is a plain set of ``(nonce, str(int(timestamp)))`` keys; when it
+    exceeds SEEN_MAX it is trimmed to SEEN_TRIM_TO by dropping expired keys
+    first and then the oldest timestamps.
+    """
+    nonce = msg.get("nonce")
+    ts = msg.get("timestamp")
+    if nonce is None or ts is None:
+        return "replay_or_stale: nonce and timestamp required when replay window is enabled"
+    if not isinstance(nonce, str) or not nonce:
+        return "replay_or_stale: missing or empty nonce"
+    parsed = parse_timestamp(ts)
+    if parsed is None:
+        return "replay_or_stale: missing or unparsable timestamp"
+    now = time.time()
+    if abs(now - parsed) > window_seconds:
+        return "replay_or_stale: timestamp outside window"
+    if any(key[0] == nonce for key in seen):
+        return "replay_or_stale: duplicate nonce"
+    seen.add((nonce, str(int(parsed))))
+    if len(seen) > SEEN_MAX:
+        _evict(seen, now, window_seconds)
+    return None
+
+
+def check_incoming(
+    msg: Dict[str, Any],
+    sign_key: Optional[str] = None,
+    replay_window: Optional[float] = None,
+    seen: Optional[Set[Tuple[str, str]]] = None,
+) -> Optional[Dict[str, Any]]:
+    """Return a rejected Absorption Result if checks fail, else None.
+
+    Check order is fixed: version first, then signature (only if
+    ``sign_key`` is passed), then replay (only if ``replay_window`` is
+    passed). Default leaves signature and replay off. When a replay
+    window is enabled, both ``nonce`` and ``timestamp`` are required.
+    The reserved packet_ref ``"unknown"`` is used for early failures
+    that have no usable id; it MUST NOT be used for a successful
+    absorption.
+
+    ``seen`` is the sliding window of ``(nonce, timestamp)`` keys. The
+    caller MUST pass and reuse the same set across calls when replay
+    is on; if it is omitted, a fresh empty set is used for this call
+    only (duplicate detection will not persist).
+    """
+    version_reason = version_rejection(msg)
+    if version_reason:
+        return reject_result(msg, version_reason)
+    if sign_key:
+        if not verify_message(msg, sign_key):
+            return reject_result(msg, "signature verification failed")
+    if replay_window is not None:
+        if seen is None:
+            seen = set()
+        replay_reason = check_replay(msg, seen, replay_window)
+        if replay_reason:
+            return reject_result(msg, replay_reason)
+    return None

ai_oriented_a2a/schema/absorption-result.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-oriented-a2a.local/schema/absorption-result.schema.json",
+  "title": "AbsorptionResult",
+  "type": "object",
+  "required": ["packet_ref", "status"],
+  "properties": {
+    "packet_ref": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["absorbed", "rejected", "isolated"] },
+    "reason": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
+    "effect_summary": {
+      "type": "object",
+      "required": ["note"],
+      "properties": {
+        "note": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
+        "metrics": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["number", "string", "boolean"]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+      "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+    },
+    "nonce": { "type": "string", "minLength": 1 },
+    "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+    "signature": {
+      "type": "object",
+      "required": ["alg", "value"],
+      "properties": {
+        "alg": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "status": { "const": "absorbed" } },
+        "required": ["status"]
+      },
+      "then": { "required": ["effect_summary"] }
+    },
+    {
+      "if": {
+        "properties": { "status": { "enum": ["rejected", "isolated"] } },
+        "required": ["status"]
+      },
+      "then": { "required": ["reason"] }
+    }
+  ],
+  "additionalProperties": false
+}

ai_oriented_a2a/schema/agent-profile.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-oriented-a2a.local/schema/agent-profile.schema.json",
+  "title": "AgentProfile",
+  "type": "object",
+  "required": ["constraints", "improvement_prefs", "shareable_types"],
+  "properties": {
+    "constraints": { "type": "array", "items": { "type": "string" } },
+    "improvement_prefs": { "type": "array", "items": { "type": "string" } },
+    "shareable_types": { "type": "array", "items": { "type": "string" } },
+    "interest_tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional light broadcast interest tags for discovery; peers MAY ignore unknown tags."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+      "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+    },
+    "nonce": { "type": "string", "minLength": 1 },
+    "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+    "signature": {
+      "type": "object",
+      "required": ["alg", "value"],
+      "properties": {
+        "alg": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "identity": {
+      "type": "object",
+      "required": ["fingerprint"],
+      "properties": {
+        "fingerprint": { "type": "string", "minLength": 1 },
+        "alg": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "description": "Optional identity binding (public-key fingerprint or opaque identifier). When present, fingerprint is required."
+    }
+  },
+  "additionalProperties": false
+}

ai_oriented_a2a/schema/experience-packet.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-oriented-a2a.local/schema/experience-packet.schema.json",
+  "title": "ExperiencePacket",
+  "type": "object",
+  "required": ["id", "type", "content", "absorption"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "type": { "enum": ["failure_mode", "strategy_fragment", "tool_trajectory", "other"] },
+    "content": { "type": "object" },
+    "absorption": {
+      "type": "object",
+      "required": ["method"],
+      "properties": {
+        "method": {
+          "enum": [
+            "prompt_injection",
+            "retrieval",
+            "local_adapter_hint",
+            "trajectory_replay",
+            "parameter_delta",
+            "other"
+          ],
+          "description": "MUST support prompt_injection and retrieval. OPTIONAL: local_adapter_hint, trajectory_replay. RESERVED/optional: parameter_delta (receivers without support MUST reject)."
+        },
+        "target": { "type": "string" },
+        "hint": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "expiry": { "type": "object" },
+    "prior_outcomes": {
+      "type": "object",
+      "properties": {
+        "absorbed_count": { "type": "integer", "minimum": 0 },
+        "rejected_count": { "type": "integer", "minimum": 0 },
+        "last_status": { "enum": ["absorbed", "rejected", "isolated", "none"] }
+      },
+      "additionalProperties": false
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["source_ref"],
+      "properties": {
+        "source_ref": { "type": "string", "minLength": 1 },
+        "chain": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "verification_claim": {
+      "type": "object",
+      "required": ["expected_effect"],
+      "properties": {
+        "expected_effect": { "type": "string", "minLength": 1 },
+        "replay_hint": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+      "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+    },
+    "nonce": { "type": "string", "minLength": 1 },
+    "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+    "signature": {
+      "type": "object",
+      "required": ["alg", "value"],
+      "properties": {
+        "alg": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

ai_oriented_a2a/schema/negotiation.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ai-oriented-a2a.local/schema/negotiation.schema.json",
+  "title": "NegotiationMessage",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["proposal_id", "target_constraint", "proposed_change"],
+      "properties": {
+        "proposal_id": { "type": "string", "minLength": 1 },
+        "target_constraint": { "type": "string" },
+        "proposed_change": { "type": "string" },
+        "offered_packet": { "$ref": "experience-packet.schema.json" },
+        "conditional_packet": { "$ref": "experience-packet.schema.json" },
+        "constraint_scope": { "type": "string" },
+        "duration": { "type": "string" },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+          "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+        },
+        "nonce": { "type": "string", "minLength": 1 },
+        "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+        "signature": {
+          "type": "object",
+          "required": ["alg", "value"],
+          "properties": {
+            "alg": { "type": "string", "minLength": 1 },
+            "value": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["proposal_id"],
+      "properties": {
+        "proposal_id": { "type": "string" },
+        "status": { "const": "accept" },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+          "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+        },
+        "nonce": { "type": "string", "minLength": 1 },
+        "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+        "signature": {
+          "type": "object",
+          "required": ["alg", "value"],
+          "properties": {
+            "alg": { "type": "string", "minLength": 1 },
+            "value": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["proposal_id"],
+      "properties": {
+        "proposal_id": { "type": "string" },
+        "status": { "const": "reject" },
+        "reason": { "type": "string" },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+          "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+        },
+        "nonce": { "type": "string", "minLength": 1 },
+        "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+        "signature": {
+          "type": "object",
+          "required": ["alg", "value"],
+          "properties": {
+            "alg": { "type": "string", "minLength": 1 },
+            "value": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "required": ["proposal_id", "revised_change"],
+      "properties": {
+        "proposal_id": { "type": "string" },
+        "status": { "const": "counter" },
+        "revised_change": { "type": "string" },
+        "offered_packet": { "$ref": "experience-packet.schema.json" },
+        "conditional_packet": { "$ref": "experience-packet.schema.json" },
+        "constraint_scope": { "type": "string" },
+        "duration": { "type": "string" },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+          "description": "Optional on-wire protocol version. Canonical value is \"0.3\". Values with a leading v (e.g. \"v0.3\") are treated as unknown and MUST be rejected."
+        },
+        "nonce": { "type": "string", "minLength": 1 },
+        "timestamp": { "oneOf": [{ "type": "number" }, { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]{3}|\\.[0-9]{6})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$" }] },
+        "signature": {
+          "type": "object",
+          "required": ["alg", "value"],
+          "properties": {
+            "alg": { "type": "string", "minLength": 1 },
+            "value": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

ai_oriented_a2a/transport.py

@@ -0,0 +1,273 @@
+"""Minimal HTTP binding for AI-oriented A2A v0.3 (standard library only).
+
+Import it explicitly; it is not re-exported from the top-level package, so
+``import ai_oriented_a2a`` does not load ``http.server`` or ``urllib``::
+
+    from ai_oriented_a2a.transport import send_message, make_server, serve
+
+Client: ``send_message(url, message, *, timeout=30.0, sign_key=None,
+add_replay_fields=False)`` POSTs one message to ``url + "/a2a/message"`` and
+returns the peer's JSON reply.
+
+Server: subclass ``A2ARequestHandler`` and override ``handle_message``, or
+pass a callback to ``make_handler`` / ``make_server`` / ``serve``. The
+handler does everything docs/TRANSPORT.md requires before your code runs:
+404 for other paths, HTTP 400 + a legal Absorption Result for invalid JSON,
+then ``check_incoming`` (version first, optional signature and replay
+window). Your callback only sees messages that passed. Its result is passed
+through the hard gate (``guard_result``) before it is sent. If the callback
+raises, the peer gets HTTP 500 and a legal rejected Absorption Result with
+the reason ``internal_error: message handler failed`` (no exception text).
+
+The package does not decide absorption: the host's callback does.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable, Dict, Optional, Set, Tuple
+
+from .protocol import (
+    RESERVED_PACKET_REF,
+    check_incoming,
+    new_id,
+    reject_result,
+    sign_message,
+)
+
+ENDPOINT = "/a2a/message"
+DEFAULT_TIMEOUT = 30.0  # docs/TRANSPORT.md: clients SHOULD use >= 30 s
+INTERNAL_ERROR_REASON = "internal_error: message handler failed"
+INVALID_JSON_REASON = "invalid json"
+
+Message = Dict[str, Any]
+MessageHandler = Callable[[Message], Message]
+
+log = logging.getLogger(__name__)
+
+
+class TransportError(Exception):
+    """Network failure, timeout, or a reply body that is not a JSON object."""
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+def send_message(
+    url: str,
+    message: Message,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    sign_key: Optional[str] = None,
+    add_replay_fields: bool = False,
+) -> Message:
+    """POST ``message`` to ``url`` + ``/a2a/message`` and return the JSON reply.
+
+    ``add_replay_fields`` attaches a fresh ``nonce`` and the current integer
+    ``timestamp`` (needed when the peer has a replay window enabled).
+    ``sign_key`` signs the message last (HMAC-SHA256 over canonical JSON).
+
+    An HTTP error status whose body is a JSON object (for example the 400
+    ``invalid json`` Absorption Result) is returned like a normal reply.
+    Raises TransportError on network errors, timeouts, or a non-JSON body.
+    The reply is not validated; a peer's ``rejected`` result is a normal
+    return value.
+    """
+    if add_replay_fields:
+        message = dict(message)
+        message["nonce"] = new_id("nonce")
+        message["timestamp"] = int(time.time())
+    if sign_key:
+        message = sign_message(message, sign_key)
+    data = json.dumps(message).encode("utf-8")
+    request = urllib.request.Request(
+        url.rstrip("/") + ENDPOINT,
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        raw = exc.read()
+    except (urllib.error.URLError, OSError) as exc:
+        raise TransportError(f"cannot reach {url}: {exc}") from exc
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise TransportError("reply body is not JSON") from exc
+    if not isinstance(body, dict):
+        raise TransportError("reply body is not a JSON object")
+    return body
+
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+
+
+def guard_result(result: Message) -> Message:
+    """Apply the SPEC §3.1 hard gate to a reply before it is sent.
+
+    ``status=absorbed`` without a non-empty ``effect_summary.note``, or with
+    the reserved ``packet_ref`` ``unknown``, becomes a rejected result.
+    Anything else (other statuses, acks) is returned unchanged.
+    """
+    if not isinstance(result, dict) or result.get("status") != "absorbed":
+        return result
+    if result.get("packet_ref") == RESERVED_PACKET_REF:
+        return reject_result(
+            result, "reserved packet_ref 'unknown' cannot be used for successful absorption"
+        )
+    summary = result.get("effect_summary")
+    note = summary.get("note") if isinstance(summary, dict) else None
+    if not (isinstance(note, str) and note.strip()):
+        return reject_result(
+            result, "hard-gate violation: absorbed result missing non-empty effect_summary.note"
+        )
+    return result
+
+
+class A2ARequestHandler(BaseHTTPRequestHandler):
+    """``POST /a2a/message`` handler. Override ``handle_message``.
+
+    Configuration is read from class attributes so a subclass (or
+    ``make_handler``) can set it: ``sign_key`` enables signature
+    verification and signed replies, ``replay_window`` (seconds) enables the
+    replay window, and ``seen_nonces`` is the shared replay set.
+    """
+
+    sign_key: Optional[str] = None
+    replay_window: Optional[float] = None
+    seen_nonces: Set[Tuple[str, str]] = set()
+
+    def handle_message(self, msg: Message) -> Message:
+        """Return the reply for a message that passed ``check_incoming``."""
+        raise NotImplementedError("override handle_message or use make_handler(on_message)")
+
+    def do_POST(self) -> None:  # noqa: N802 (http.server API)
+        if self.path != ENDPOINT:
+            self.send_error(404)
+            return
+        length = int(self.headers.get("Content-Length", 0) or 0)
+        body = self.rfile.read(length)
+        try:
+            msg = json.loads(body.decode())
+            if not isinstance(msg, dict):
+                raise ValueError("message must be a JSON object")
+        except Exception:
+            self._reply(reject_result(None, INVALID_JSON_REASON), status=400)
+            return
+
+        rejected = check_incoming(
+            msg,
+            sign_key=self.sign_key,
+            replay_window=self.replay_window,
+            seen=self.seen_nonces,
+        )
+        if rejected:
+            self._reply(rejected)
+            return
+
+        try:
+            reply = guard_result(self.handle_message(msg))
+        except Exception:
+            # Log locally; never send exception text, paths, or tracebacks.
+            log.exception("A2A message handler failed")
+            self._reply(reject_result(msg, INTERNAL_ERROR_REASON), status=500)
+            return
+        self._reply(reply)
+
+    def _reply(self, payload: Message, status: int = 200) -> None:
+        if self.sign_key:
+            payload = sign_message(payload, self.sign_key)
+        data = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+def make_handler(
+    on_message: MessageHandler,
+    *,
+    sign_key: Optional[str] = None,
+    replay_window: Optional[float] = None,
+) -> type:
+    """Return an ``A2ARequestHandler`` subclass that calls ``on_message``.
+
+    Each returned class has its own replay set.
+    """
+    callback = on_message
+
+    class _Handler(A2ARequestHandler):
+        def handle_message(self, msg: Message) -> Message:
+            return callback(msg)
+
+        def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+            log.debug("%s - %s", self.address_string(), format % args)
+
+    _Handler.sign_key = sign_key
+    _Handler.replay_window = replay_window
+    _Handler.seen_nonces = set()
+    return _Handler
+
+
+def make_server(
+    on_message: MessageHandler,
+    port: int = 0,
+    host: str = "127.0.0.1",
+    *,
+    sign_key: Optional[str] = None,
+    replay_window: Optional[float] = None,
+) -> ThreadingHTTPServer:
+    """Build (but do not start) a threaded server; ``port=0`` picks a free port.
+
+    Start it with ``server.serve_forever()`` (for example in a thread) and
+    stop it with ``server.shutdown()`` and ``server.server_close()``.
+    """
+    handler = make_handler(on_message, sign_key=sign_key, replay_window=replay_window)
+    server = ThreadingHTTPServer((host, port), handler)
+    server.daemon_threads = True
+    return server
+
+
+def serve(
+    on_message: MessageHandler,
+    port: int,
+    host: str = "127.0.0.1",
+    *,
+    sign_key: Optional[str] = None,
+    replay_window: Optional[float] = None,
+) -> None:
+    """Serve ``POST /a2a/message`` until interrupted (blocks)."""
+    server = make_server(on_message, port, host, sign_key=sign_key, replay_window=replay_window)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+__all__ = [
+    "A2ARequestHandler",
+    "DEFAULT_TIMEOUT",
+    "ENDPOINT",
+    "INTERNAL_ERROR_REASON",
+    "TransportError",
+    "guard_result",
+    "make_handler",
+    "make_server",
+    "send_message",
+    "serve",
+]

ai_oriented_a2a/validate.py

@@ -0,0 +1,93 @@
+"""Optional JSON Schema validation. Requires the ``schema`` extra."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+SCHEMA_KINDS = {
+    "absorption-result": "absorption-result.schema.json",
+    "agent-profile": "agent-profile.schema.json",
+    "experience-packet": "experience-packet.schema.json",
+    "negotiation": "negotiation.schema.json",
+}
+
+
+class SchemaDependencyError(ImportError):
+    """Raised when validate() is called but jsonschema is not installed."""
+
+
+def schema_dir() -> Path:
+    """Return the directory that holds the published ``*.schema.json`` files.
+
+    Prefers package data (a built wheel or ``pip install .``). Falls back to
+    the repository's top-level ``schema/`` directory for an editable or
+    source checkout where the files were not copied into the package.
+    """
+    here = Path(__file__).resolve().parent
+    bundled = here / "schema"
+    if bundled.is_dir() and any(bundled.glob("*.schema.json")):
+        return bundled
+    repo = here.parent / "schema"
+    if repo.is_dir() and any(repo.glob("*.schema.json")):
+        return repo
+    raise FileNotFoundError(
+        "Could not find schema JSON files (looked in package data and "
+        "the repository schema/ directory)."
+    )
+
+
+def validate(msg: Mapping[str, Any], kind: str) -> None:
+    """Validate ``msg`` against a published schema.
+
+    ``kind`` is one of: absorption-result, agent-profile,
+    experience-packet, negotiation.
+
+    This function performs full schema validation only. It does not
+    implement the protocol version check, and its behaviour is
+    unchanged: an unknown version such as ``"v0.3"`` fails the schema
+    ``version`` pattern and raises ``jsonschema.ValidationError``. It
+    does not return a rejected Absorption Result.
+
+    Receivers MUST call ``check_incoming`` (or ``version_rejection``)
+    first and, on an unknown version, return that rejected Absorption
+    Result (``status=rejected``, ``reason`` containing
+    ``unsupported_version``). Call ``validate`` only for messages that
+    have already passed the version check. See docs/TRANSPORT.md
+    ("Version check before schema validation").
+
+    Requires ``pip install 'ai-oriented-a2a[schema]'``. Raises
+    ``SchemaDependencyError`` if jsonschema is not installed,
+    ``ValueError`` for an unknown kind, and
+    ``jsonschema.ValidationError`` if the message is invalid.
+    """
+    try:
+        from jsonschema import Draft202012Validator
+        from referencing import Registry, Resource
+    except ImportError as exc:
+        raise SchemaDependencyError(
+            "Schema validation requires the optional extra: "
+            "pip install 'ai-oriented-a2a[schema]'"
+        ) from exc
+
+    if kind not in SCHEMA_KINDS:
+        raise ValueError(
+            f"Unknown schema kind {kind!r}. Expected one of: "
+            f"{', '.join(sorted(SCHEMA_KINDS))}"
+        )
+
+    directory = schema_dir()
+    resources = []
+    for path in directory.glob("*.schema.json"):
+        contents = json.loads(path.read_text(encoding="utf-8"))
+        resource = Resource.from_contents(contents)
+        resources.append((path.name, resource))
+        schema_id = contents.get("$id")
+        if schema_id:
+            resources.append((schema_id, resource))
+    registry = Registry().with_resources(resources)
+
+    schema_path = directory / SCHEMA_KINDS[kind]
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    Draft202012Validator(schema, registry=registry).validate(msg)

ai_oriented_a2a-0.3.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+ai_oriented_a2a/__init__.py,sha256=eikRpbIL4RsmiWP3FuE90LQ3m9sbU2O_0J0qVqEzlVo,1238
+ai_oriented_a2a/protocol.py,sha256=7sRCF8iexMvBocFQhz32IChva9MwP7boWf-9vpEWX2s,8512
+ai_oriented_a2a/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ai_oriented_a2a/transport.py,sha256=Hzyi2O-7UsPr_kjWe-b1Bz_ObI7G-_kk3dKc06wAMNg,9492
+ai_oriented_a2a/validate.py,sha256=FsJiNHduKLC98GqzYXV50zQatElmf91hmhaAaq91cvA,3538
+ai_oriented_a2a/schema/absorption-result.schema.json,sha256=M7QVnms3R7C-Q4agLafXBlECeIym35FkGzjHXEY6w3Y,2087
+ai_oriented_a2a/schema/agent-profile.schema.json,sha256=wfKu46jKKk8e4Thkejy71WWMxC8-uY1LjwB3ksT_ZMk,1960
+ai_oriented_a2a/schema/experience-packet.schema.json,sha256=k70rVp20BOWlhrQCXvIewx877jJzIsZecc1-I_rVTgg,2930
+ai_oriented_a2a/schema/negotiation.schema.json,sha256=DI2auYlUD4UpQf6TR3Db7BvkOkc25yj8lZXM9qvsQF0,5409
+ai_oriented_a2a-0.3.2.dist-info/METADATA,sha256=REP_nrAe-irzQvjJ_Iry2LaeW5h8QaC46_uDZqtASLg,11870
+ai_oriented_a2a-0.3.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ai_oriented_a2a-0.3.2.dist-info/licenses/LICENSE,sha256=FeprKLCdcmoSMntfQoHoHvKyatQb6kDsZN2KdWKddYo,1072
+ai_oriented_a2a-0.3.2.dist-info/RECORD,,

ai_oriented_a2a-0.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_oriented_a2a-0.3.2.dist-info/licenses/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.