Add rfc22 + rfc23 support

.gitignore

@@ -1,6 +1,6 @@
 # Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[codz]
+*.py[cod]
 *$py.class
 
 # C extensions
@@ -20,15 +20,11 @@ parts/
 sdist/
 var/
 wheels/
-share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
 
 # PyInstaller
-#   Usually these files are written by a python script from a template
-#   before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
 
@@ -46,173 +42,37 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *.cover
-*.py.cover
+*.py,cover
 .hypothesis/
 .pytest_cache/
-cover/
 
 # Translations
 *.mo
 *.pot
 
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-# Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-# uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-# poetry.lock
-# poetry.toml
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
-# pdm.lock
-# pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-# pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# Redis
-*.rdb
-*.aof
-*.pid
-
-# RabbitMQ
-mnesia/
-rabbitmq/
-rabbitmq-data/
-
-# ActiveMQ
-activemq-data/
-
-# SageMath parsed files
-*.sage.py
-
 # Environments
 .env
-.envrc
 .venv
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/
 
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
 
 # mypy
 .mypy_cache/
 .dmypy.json
 dmypy.json
 
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#   and can be added to the global gitignore or merged into this file.  For a more nuclear
-#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
-# .idea/
-
-# Abstra
-#   Abstra is an AI-powered process automation framework.
-#   Ignore directories containing user credentials, local state, and settings.
-#   Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#   you could uncomment the following to ignore the entire vscode folder
-# .vscode/
-
-# Ruff stuff:
+# ruff
 .ruff_cache/
 
-# PyPI configuration file
-.pypirc
-
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
-
-# Streamlit
-.streamlit/secrets.toml
-
+# OS
 .DS_Store
+Thumbs.db

CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to the OpenIntent SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-02-25
+
+### Added
+
+- **RFC-0022: Federation Protocol** — Complete federation contract specification for cross-server agent coordination. Defines: federation envelope format, agent visibility (public/unlisted/private), peer relationships (peer/upstream/downstream), callbacks with at-least-once delivery, intent authority model, delegation scope with UCAN-style attenuation, governance propagation (strictest-wins), federation attestation (OpenTelemetry conventions), discovery via `/.well-known/openintent-federation.json`, federation-aware leasing, and transport bindings (HTTP REST primary, NATS/gRPC alternatives).
+- **RFC-0023: Federation Security** — Authentication, authorization, and verification layer for federation. Defines: server identity via did:web, signed envelopes (HTTP Message Signatures, RFC 9421), delegation tokens (UCAN with attenuation), trust policies (open/allowlist/trustless), agent access policies, signed attestations, and cross-server event log reconciliation via RFC-0019 Merkle primitives.
+- **Python SDK Federation Implementation (RFC-0022 & RFC-0023)** — Full 5-layer federation support:
+  - **Layer 1 — Models** (`openintent/federation/models.py`): `FederationEnvelope`, `FederationCallback`, `FederationPolicy`, `FederationAttestation`, `DelegationScope`, `FederationManifest`, `FederationStatus`, `DispatchResult`, `ReceiveResult`, `FederatedAgent`, `PeerInfo`. Enums: `AgentVisibility`, `PeerRelationship`, `TrustPolicy`, `CallbackEventType`, `DispatchStatus`. All with `to_dict()`/`from_dict()` serialization.
+  - **Layer 2 — Client methods** (`openintent/client.py`): `federation_status()`, `list_federated_agents()`, `federation_dispatch()`, `federation_receive()`, `send_federation_callback()`, `federation_discover()`. Both sync (`OpenIntentClient`) and async (`AsyncOpenIntentClient`) variants.
+  - **Layer 3 — Server endpoints** (`openintent/server/federation.py`): FastAPI router with `GET /api/v1/federation/status`, `GET /api/v1/federation/agents`, `POST /api/v1/federation/dispatch`, `POST /api/v1/federation/receive`, `GET /.well-known/openintent-federation.json`, `GET /.well-known/did.json`. SSRF validation on outbound URLs, callback delivery with retry, governance enforcement, idempotency key handling.
+  - **Layer 4 — Security** (`openintent/federation/security.py`): `ServerIdentity` (Ed25519 key pairs, did:web identifiers, DID document generation), `sign_envelope()`/`verify_envelope_signature()`, `MessageSignature` (RFC 9421 HTTP Message Signatures), `TrustEnforcer` (open/allowlist/trustless policy enforcement), `UCANToken` (delegation token creation, encoding, decoding, attenuation, expiry checks), `resolve_did_web()`, `validate_ssrf()`.
+  - **Layer 5 — Decorators** (`openintent/federation/decorators.py`): `@Federation` class decorator for server configuration (identity, trust_policy, peers, visibility_default). `federation_visibility` parameter on `@Agent`. `federation_policy` parameter on `@Coordinator`. Lifecycle hooks: `@on_federation_received`, `@on_federation_callback`, `@on_budget_warning`.
+- **Federation Dispatch (Express.js)** — 4 REST endpoints for cross-server intent dispatch: `GET /api/v1/federation/status`, `GET /api/v1/federation/agents`, `POST /api/v1/federation/dispatch`, `POST /api/v1/federation/receive`. Federation audit trail with dispatch IDs, provenance in `state._federation`, and RFC-0020 trace propagation.
+- **Federation MCP Tools** — 4 new MCP tools: `federation_status` (read), `list_federated_agents` (read), `federation_dispatch` (admin), `federation_receive` (admin). MCP tool surface expanded from 62 to 66 tools; RBAC counts: reader=23, operator=40, admin=66.
+- **Agent Lifecycle (RFC-0016)** — Registration with atomic upsert, heartbeat protocol, graceful drain, and status management across 5 REST endpoints.
+- **Federation event types** in `EventType` enum: `FEDERATION_DISPATCHED`, `FEDERATION_RECEIVED`, `FEDERATION_CALLBACK`, `FEDERATION_BUDGET_WARNING`, `FEDERATION_COMPLETED`, `FEDERATION_FAILED`.
+- **DelegationScope.attenuate()** — Scope narrowing per hop: intersection of permissions, union of denied operations, minimum delegation depth.
+- **FederationPolicy.compose_strictest()** — Strictest-wins governance composition: minimum for numerics, OR for booleans, merge for observability.
+- **Discovery endpoints** updated: `/.well-known/openintent.json` includes `federation` capability and RFC-0022/0023 in `rfcUrls`. `/.well-known/openintent-compat.json` includes RFC-0022 (full) and RFC-0023 (partial) compliance.
+- **Schema: `origin_server_url`** — New field on `agent_records` table marking federated agents.
+- **82 federation tests** covering models serialization, security (sign/verify, UCAN, SSRF, trust enforcement), server endpoints, decorators, and integration flows.
+
+### Fixed
+
+- **Agent Registration Race Condition** — Replaced two-step check-then-insert with atomic `INSERT ... ON CONFLICT DO UPDATE`. Version increments atomically via SQL expression.
+- **Response Field Naming** — All agent endpoints now return `metadata` (not `agent_metadata`) for consistency with the Python SDK.
+
+### Security
+
+- **SSRF Protection on Federation** — `origin_server_url` validated at registration and dispatch. Blocks private IPs, metadata endpoints, internal hostnames, and non-HTTP schemes.
+- **Federation Timeout** — 10-second timeout on remote dispatch calls. Returns 502 on failure.
+- **Loop Prevention** — Cannot dispatch to local agents or receive for federated agents.
+
+### Changed
+
+- RFC count increased from 22 to 23.
+- All version references updated to 0.14.0 across Python SDK, MCP server, and documentation.
+
+---
+
 ## [0.13.5] - 2026-02-14
 
 ### Added
@@ -18,6 +58,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Anthropic Streaming Usage (Round 2)** — Fixed `_resolve_usage()` in the Anthropic adapter which short-circuited via `if self._usage is not None: return` when `_consume_events` captured partial usage (e.g. `input_tokens` from `message_start` but `output_tokens` stuck at 0 due to early generator exit before `message_delta`). Now always calls `get_final_message()` on the underlying Anthropic `MessageStream` as the primary authoritative source, falling back to event-captured data only if `get_final_message()` fails. Also calls the raw SDK stream directly to avoid duplicate tool-block processing.
+- **LLM Engine Streaming Usage** — Added `_last_stream_usage` to `LLMEngine` and wired usage capture into both `_iter_anthropic_stream` and `_stream_raw_provider` for Anthropic. After text iteration completes, calls `get_final_message()` on the underlying stream to populate usage data, making token counts available even when streaming without the adapter wrapper.
 - **MCP Startup Tool Count** — Fixed tool count mismatch where RBAC security tiers listed 62 tools but only 58 tool definitions existed. Startup log now correctly reports `tools=62/62` for admin role.
 - **RBAC Tier Correction** — `operator` role count corrected from 37 to 38 across changelog entries and documentation.