agenthandler 0.93.0__tar.gz → 0.94.0__tar.gz

agenthandler-0.94.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python -m pip install -e '.[dev,server]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy agenthandler/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev,server]'
+      - run: python -m pytest -q --tb=short --cov=agenthandler --cov-report=term-missing --cov-fail-under=75
+
+  build:
+    name: Package build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Smoke test the wheel without optional dependencies
+        run: |
+          python -m venv "$RUNNER_TEMP/wheel-test"
+          "$RUNNER_TEMP/wheel-test/bin/python" -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/wheel-test/bin/python" -c "import agenthandler; from importlib.resources import files; assert files('agenthandler').joinpath('py.typed').is_file(); print(agenthandler.__version__)"
+      - name: Check the npm placeholder package
+        working-directory: npm
+        run: npm pack --dry-run

agenthandler-0.94.0/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish
+
+# Publishes to PyPI and npm when a GitHub release is published, using trusted
+# publishing (OIDC): no API tokens are stored in the repository.
+#
+# One-time setup:
+#   PyPI: pypi.org > agenthandler > Settings > Publishing > add a GitHub publisher
+#         owner arunvenkatadri, repo agenthandler, workflow publish.yml, environment pypi.
+#   npm:  npmjs.com > agenthandler > Settings > Trusted publishing > GitHub Actions,
+#         same owner/repo, workflow publish.yml.
+#   GitHub: Settings > Environments > create "pypi" and "npm" (optionally with required reviewers).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+      - name: Check the tag matches the version
+        if: github.event_name == 'release'
+        run: |
+          v=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "${GITHUB_REF_NAME#v}" = "$v" || { echo "tag $GITHUB_REF_NAME != version $v"; exit 1; }
+          test "$(node -p "require('./npm/package.json').version")" = "$v"
+      - run: python -m pip install build twine && python -m build && twine check dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          skip-existing: true
+
+  npm:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+      - name: Publish (skipped when this version is already on npm)
+        working-directory: npm
+        run: |
+          npm install -g npm@latest
+          v=$(node -p "require('./package.json').version")
+          if npm view "agenthandler@$v" version >/dev/null 2>&1; then echo "agenthandler@$v already published"; exit 0; fi
+          npm publish --provenance --access public

{agenthandler-0.93.0 → agenthandler-0.94.0}/.gitignore

@@ -23,16 +23,12 @@ htmlcov/
 *.swo
 .DS_Store
 
-# Node (for openclaw-plugin)
+# Node
 node_modules/
-openclaw-plugin/dist/
 
 # Environment
 .env
 .env.*
 
-# Internal docs (not for public repos)
-ROADMAP.internal.md
-
-# SQLite databases (created by clawboss sessions)
+# SQLite databases (created by local sessions)
 *.db

{agenthandler-0.93.0 → agenthandler-0.94.0}/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 All notable changes to AgentHandler are documented here.
 
+## Unreleased
+
+## [0.94.0] — 2026-11-11
+
+The open-source relaunch of the AgentHandler governance library, published from a
+new repository with fresh history. Everything shipped in 0.93.0 is still here; the
+entries below cover what changed in the library since then.
+
+### Breaking
+- **OAuth requires an explicit allow-list.** `add_oauth_routes()` now takes
+  `allowed_subjects` and raises at startup when it is empty; the REST control plane
+  reads `AGENTHANDLER_OAUTH_ALLOWED_SUBJECTS`. Previously any identity that completed
+  the provider flow was admitted — authentication was treated as authorization.
+  Deployments that relied on that must list the provider user IDs allowed in, or the
+  server will refuse to start. Failing closed here is deliberate.
+
+### Added
+- **Durable tasks**: `DurableTaskRunner` with `SqliteTaskStore`, `Milestone`,
+  `TaskLimits`, `CallBudget` and `TaskContext` persist milestone progress, operation
+  IDs, verification evidence and lifetime budget reservations, so a restartable job
+  resumes without repeating side effects (`docs/durable-tasks.md`).
+- **Verification gates**: `VerificationGate` requires named validators to pass before
+  an agent's proposal counts as verified; `CompletionStatus` and `VerificationResult`
+  for reflection loops (`docs/verification-gates.md`).
+- **Model routing**: `ModelRouter`, `RoutingRule` and `RoutingDecision` route each
+  query to a model by keywords, patterns or a default.
+- **Context compression** (optional, `pip install agenthandler[compression]`):
+  `CompressedSupervisor`, `compress_output` and `compress_messages`.
+- **Local/cloud routing** (optional): `EdgeReduceLLM` runs LLM calls routed by
+  edge-reduce-llm under supervision.
+- **Approvals**: expiry (`Policy.approval_ttl_s`, per-tool `approval_ttls`) and
+  `ApprovalQueue.revoke()`; `Supervisor.call_approved()` dispatches a call against a
+  specific approval.
+- **Supervisor**: `preflight()`, `call_with_breaker()`, `reset_circuit_breaker()`,
+  `restore_rate_history()` and `begin_request()`.
+- **Atomic checkpoints**: the `AtomicCheckpointStore` protocol; the SQLite store
+  writes the supervisor checkpoint and session state in one transaction.
+- **Cost attribution**: prompt-cache read and write rates and batch discounts in
+  `ModelPricing` and `PricingTable.set_model()`.
+- `Redactor.redact_value()` redacts nested JSON-like values.
+
+### Changed
+- `SessionManager` binds a running session to its supervisor generation, so a stale
+  process cannot overwrite a resumed session.
+- REST control-plane request models bound the size of every string field.
+
+### Fixed
+- **Dashboard XSS**: `esc()` escaped only `&`, `<` and `>` by way of
+  `textContent`/`innerHTML`, leaving quotes intact while six `onclick=` attributes
+  interpolated its output — a `'` escaped into the handler. It now escapes quotes,
+  and `jsArg()` encodes a JavaScript string argument for that attribute context.
+- **Stream message loss**: a failed handler dropped its message. The Kafka connector
+  committed the consumer's current position rather than the handled offset, so the
+  next success committed past the failure; the Redis connector skipped `XACK` but
+  nothing reclaimed the pending entry. Deliveries now retry before advancing.
+- **Connectors**: read-only enforcement and transaction handling.
+- **Triggers**: recurring cron steps (`*/N`), webhook enable/disable, and scheduler
+  shutdown through a FastAPI `lifespan`.
+- **Routing, pipeline approval and cancellation** regressions.
+
+### Security
+- `require_auth=True` no longer accepts a placeholder key; OAuth login states are
+  single-use, expire and are bound to the browser; OAuth sessions are scoped per app;
+  WebSocket connections authenticate with API keys and OAuth sessions alike.
+- `OpenClawBridge` takes `allowed_origins`; the A2A client takes an `auth_token`.
+
+## [0.93.0] — 2026-07-11
+
+### Added
+- **MCP server mode**: `SupervisedMCPServer` exposes supervised tools over the Model
+  Context Protocol (`pip install agenthandler[mcp]`).
+- **A2A protocol**: supervised agent-to-agent calls and agent cards.
+- **SDK adapters** for the OpenAI Agents SDK and the Claude Agent SDK.
+
 ## [0.92.0] — 2026-07-11
 
 ### Added

{agenthandler-0.93.0 → agenthandler-0.94.0}/CONTRIBUTING.md

@@ -5,9 +5,9 @@ Thanks for your interest in contributing.
 ## Setup
 
 ```bash
-git clone https://github.com/arunvenkatadri/AgentHandler.git
-cd AgentHandler
-pip install -e ".[dev]"
+git clone https://github.com/arunvenkatadri/agenthandler.git
+cd agenthandler
+pip install -e ".[dev,server]"
 ```
 
 ## Running checks
@@ -16,6 +16,9 @@ pip install -e ".[dev]"
 # Tests
 pytest tests/ -v
 
+# Include the coverage check used in CI
+pytest tests/ --cov=agenthandler --cov-fail-under=75
+
 # Lint
 ruff check .
 ruff format --check .
@@ -33,19 +36,31 @@ All three must pass before submitting a PR.
 3. Make sure all checks pass.
 4. Open a PR with a clear description of what changed and why.
 
+### Changelog
+
+Add an entry under `## Unreleased` in `CHANGELOG.md` for any user-visible change.
+Call out breaking changes to public APIs (anything exported from `agenthandler`,
+the REST control plane, policy keys) explicitly.
+
+## Review and merging
+
+PRs need passing CI (tests on Python 3.10–3.13, lint, formatting, type checking
+and the package build) and a maintainer's approval. Resolve review conversations
+before merging.
+
 ## Project structure
 
 ```
-agenthandler/           Python library (zero dependencies)
+agenthandler/       Python library (zero dependencies)
 tests/              Test suite (pytest)
 examples/           Runnable examples
+docs/               Guides and design notes
 dashboard.html      Agent management UI (single-file, no build step)
-openclaw-plugin/    TypeScript plugin template for OpenClaw
+npm/                npm placeholder that points to the Python package
 ```
 
 - **`agenthandler/`** — the core library. Skills are capabilities (tool collections). Agents use skills and are supervised by policies.
 - **`dashboard.html`** — standalone UI for managing agents, skills, and conversations. Pure HTML/CSS/JS, no build tools. Open directly in a browser.
-- **`openclaw-plugin/`** — TypeScript plugin that bridges agenthandler to OpenClaw.
 
 ## Design principles
 

agenthandler-0.93.0/README.md → agenthandler-0.94.0/PKG-INFO

@@ -1,17 +1,63 @@
-# AgentHandler 
-
-
-
-
-<img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/162a4e5e-ccdd-4152-b7e4-4addd2ef5743" />
-
+Metadata-Version: 2.5
+Name: agenthandler
+Version: 0.94.0
+Summary: A way of controlling deployed agents to keep your (and their) sanity.
+Project-URL: Homepage, https://github.com/arunvenkatadri/agenthandler
+Project-URL: Repository, https://github.com/arunvenkatadri/agenthandler
+Project-URL: Issues, https://github.com/arunvenkatadri/agenthandler/issues
+Author: Arun Venkatadri
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,audit,budget,circuit-breaker,supervision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: compression
+Requires-Dist: headroom-ai>=0.20; extra == 'compression'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.16.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: kafka
+Requires-Dist: aiokafka>=0.10; extra == 'kafka'
+Provides-Extra: kinesis
+Requires-Dist: aioboto3>=12.0; extra == 'kinesis'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: server
+Requires-Dist: aiosqlite>=0.19; extra == 'server'
+Requires-Dist: fastapi>=0.100; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.20; extra == 'server'
+Provides-Extra: streams
+Requires-Dist: aioboto3>=12.0; extra == 'streams'
+Requires-Dist: aiokafka>=0.10; extra == 'streams'
+Requires-Dist: redis>=5.0; extra == 'streams'
+Description-Content-Type: text/markdown
+
+# AgentHandler
 
+<p align="center">
+  <img alt="AgentHandler banner" src="docs/banner.png" width="900" />
+</p>
 
-[![CI](https://github.com/arunvenkatadri/AgentHandler/actions/workflows/ci.yml/badge.svg)](https://github.com/arunvenkatadri/AgentHandler/actions/workflows/ci.yml)
+[![CI](https://github.com/arunvenkatadri/agenthandler/actions/workflows/ci.yml/badge.svg)](https://github.com/arunvenkatadri/agenthandler/actions/workflows/ci.yml)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
-[![Tests](https://img.shields.io/badge/tests-658-brightgreen.svg)]()
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](pyproject.toml)
 
 *Every agent needs a handler.*
 
@@ -66,6 +112,9 @@ async def web_search(query: str) -> str:
     return f"Results for: {query}"
 
 async def main():
+    # Count this round against max_iterations (raises when the limit is hit)
+    supervisor.record_iteration()
+
     # Supervise a tool call
     result = await supervisor.call("web_search", web_search, query="python async")
 
@@ -84,6 +133,12 @@ async def main():
 asyncio.run(main())
 ```
 
+`record_iteration()` and `record_tokens()` are explicit because AgentHandler
+does not run your loop — it supervises the calls your loop makes. One
+`supervisor.call()` is not necessarily one iteration, and only you know how many
+tokens your LLM call actually spent. Both raise when they cross a policy limit,
+so the loop stops at the boundary rather than after it.
+
 ## Dashboard
 
 Open `dashboard.html` in a browser for a full management UI:
@@ -100,10 +155,10 @@ Open `dashboard.html` in a browser for a full management UI:
 - **Costs** — track spend, set budgets with hard stops, view usage over time
 - **Policies** — see all active supervision rules at a glance
 
-The Sessions tab connects to the REST control plane (`uvicorn agenthandler.server:app`) and shows real-time session data. Agent cards show live status and controls work against the real API. The LLM features (prompt generation, chat, pipeline generation) require a backend with an LLM API key — use [Artemis](https://github.com/arunvenkatadri/artemis) or provide your own `/chat` and `/generate-prompt` endpoints.
+The Sessions tab connects to the REST control plane (`uvicorn agenthandler.server:app`) and shows real-time session data. Agent cards show live status and controls work against the real API. The LLM features (prompt generation, chat, pipeline generation) require a backend with an LLM API key: provide your own `/chat` and `/generate-prompt` endpoints.
 
 
-<img width="1383" height="1270" alt="Sdd" src="https://github.com/user-attachments/assets/b4fec9fa-59d4-4476-93ac-19684c835ab0" />
+<img width="1383" height="1270" alt="AgentHandler dashboard — agents, skills, sessions, approvals and costs in one view" src="https://github.com/user-attachments/assets/b4fec9fa-59d4-4476-93ac-19684c835ab0" />
 
 
 
@@ -127,6 +182,11 @@ The Sessions tab connects to the REST control plane (`uvicorn agenthandler.serve
 | **16 guardrails** | No layered safety — rule-based + LLM-backed checks for every tool call |
 | **Reflection loops** | Agents looping without thinking about whether they're making progress |
 | **Session replay** | No way to reconstruct what an agent did after the fact |
+| **Model routing** | Paying frontier prices for simple queries — route to cheap models automatically |
+| **Context compression** | Sending 10x more tokens than needed — compress tool outputs before they hit the LLM |
+| **MCP server mode** | No standard way to expose supervised tools to any MCP client |
+| **A2A protocol** | No supervision on inter-agent communication |
+| **SDK adapters** | No way to add guardrails to OpenAI/Claude SDK tools without rewriting |
 | **Streaming inputs** | No way to react to real-time events (Kafka/Kinesis/Redis) |
 | **Triggers & scheduling** | No way to run agents on schedule or on data events |
 | **Pipeline orchestration** | No structured way to chain tool calls |
@@ -372,7 +432,7 @@ The REST endpoint `GET /pipelines/schema` returns the schema for all registered
 
 ## Reflection loops (agents that actually think)
 
-Long-duration agents don't just loop `run()` forever. They think → act → observe → reflect → think again. Each phase is its own LLM call, each phase is audited, and the reflection output feeds into the next think phase.
+Long-duration agents don't just loop `run()` forever. They think → act → observe → reflect → think again. Think, observe, and reflect use your LLM callback; tool execution is supervised and audited. Reflections feed into the next think phase.
 
 ```python
 from agenthandler import ReflectionLoop, SessionManager, MemoryStore
@@ -394,7 +454,9 @@ for c in result.cycles:
     print(f"  {c.thought} → {c.tool_called} → {c.reflection}")
 ```
 
-Each cycle is fully supervised. Guardrails apply. Crashes are recoverable. Every reflection is in the audit log. This is what distinguishes "agent ran for 72 hours doing useful work" from "agent ran in circles for 72 hours."
+A model completion claim produces `status="proposed"` and `completed=False`. Supply a trusted async `verifier` returning `VerificationResult` to certify completion with acceptance evidence. Malformed responses are invalid; blocked work remains incomplete. Reflection history is local to this run.
+
+For restartable jobs, use the optional `DurableTaskRunner` with `SqliteTaskStore`. It persists milestone progress, operation IDs, verification evidence, and lifetime budget reservations. Uncertain external operations require reconciliation before replay. See [durable tasks and completion semantics](docs/durable-tasks.md) for the API, migration notes, and adapter requirements.
 
 See `examples/long_running_agent.py` for a full reference implementation.
 
@@ -503,13 +565,31 @@ Three streaming backends — install only what you need:
 
 | Connector | Install | Use for |
 |-----------|---------|---------|
-| `KafkaStreamConnector` | `pip install agenthandler[kafka]` | Self-hosted, enterprise, replay, consumer groups |
-| `KinesisStreamConnector` | `pip install agenthandler[kinesis]` | AWS-native event streams |
+| `KafkaStreamConnector` | `pip install agenthandler[kafka]` | Self-hosted, enterprise, replay, consumer groups. **Recommended for long-running agents.** |
 | `RedisStreamConnector` | `pip install agenthandler[redis]` | Simpler deployments, already-have-Redis |
+| `KinesisStreamConnector` | `pip install agenthandler[kinesis]` | AWS-native event streams. Live-tail only — see the caveat below. |
 
 Or install all three: `pip install agenthandler[streams]`
 
-All three use at-least-once delivery — messages are acknowledged only after the handler completes successfully. If the agent crashes mid-processing, the message is redelivered.
+**Delivery semantics.** A message is acknowledged only after its handler
+succeeds, and a failed handler is retried rather than skipped — the connector
+does not advance past a record it could not process.
+
+- **Kafka** commits the handled offset to the consumer group, so a restart
+  resumes where it left off.
+- **Redis Streams** acknowledges through the consumer group with `XACK`. A
+  handler that fails leaves the entry pending; nothing reclaims it
+  automatically yet, so recovery is manual.
+- **Kinesis** retries within the running process, but **keeps no durable
+  position**. It enumerates shards once at startup and resumes from
+  `shard_iterator_type` on restart — so a redeploy skips whatever arrived while
+  it was down, and a reshard is never noticed. Use it for live tailing, not for
+  anything that must not miss a record. Checkpointing and reshard discovery are
+  not implemented.
+
+A failed handler currently retries indefinitely with no attempt ceiling and no
+dead-letter queue, so a message that always fails will stall its partition
+([#4](https://github.com/arunvenkatadri/agenthandler/issues/4)).
 
 ## Triggers and scheduling
 
@@ -688,9 +768,19 @@ For production deployments, configure OAuth2 via environment variables:
 AGENTHANDLER_OAUTH_PROVIDER=github \
 AGENTHANDLER_OAUTH_CLIENT_ID=your-client-id \
 AGENTHANDLER_OAUTH_CLIENT_SECRET=your-client-secret \
+AGENTHANDLER_OAUTH_ALLOWED_SUBJECTS=1234567,7654321 \
 uvicorn agenthandler.server:app
 ```
 
+`AGENTHANDLER_OAUTH_ALLOWED_SUBJECTS` is **required** — a comma-separated list of
+the provider user IDs allowed in (GitHub or Google numeric account IDs, not
+usernames or email addresses). The server refuses to start without it.
+
+That is deliberate. Completing an OAuth flow proves who someone is, not that
+they should be allowed to drive your agents; without an allow-list, anyone with
+a GitHub account would qualify. Authentication is not authorization, so the
+allow-list has no default.
+
 This adds `/auth/login` (get the OAuth redirect URL), `/auth/callback` (exchange code for session token), and `/auth/me` (current user info). Session tokens are Bearer tokens — use them the same way as API keys. Supported providers: `github`, `google`.
 
 Endpoints:
@@ -789,6 +879,131 @@ Every tool call through MCP goes through the Supervisor — timeouts, budgets, c
 
 See `examples/mcp_server.py` for a full working example.
 
+## Model routing (cost optimization)
+
+Route queries to different models based on complexity. Simple queries go to cheap models; complex queries go to expensive ones. Configure rules in code or via the dashboard.
+
+```python
+from agenthandler import ModelRouter, RoutingRule, Supervisor, Policy
+
+supervisor = Supervisor(Policy(token_budget=100000))
+
+router = ModelRouter(
+    api_key="sk-ant-...",
+    rules=[
+        RoutingRule(name="simple", match_default=True, model="claude-haiku-4-5"),
+        RoutingRule(name="complex", keywords=["analyze", "compare", "architecture"],
+                    model="claude-sonnet-4-6"),
+        RoutingRule(name="critical", keywords=["audit", "security", "legal"],
+                    model="claude-opus-4-6"),
+    ],
+    supervisor=supervisor,
+)
+
+await router("What is 2+2?")          # → Haiku ($0.25/M input)
+await router("Analyze this codebase") # → Sonnet ($3/M input)
+await router("Audit the security")    # → Opus ($15/M input)
+```
+
+Rules are evaluated top-down (first match wins). Each rule supports keyword matching, regex patterns, or a default fallback. The dashboard **Routing** tab provides a visual editor with model dropdowns, drag-to-reorder, test queries, and YAML export.
+
+For local/cloud hybrid routing (run a local model and only escalate to cloud when needed), see the [edge-reduce integration](https://github.com/arunvenkatadri/edge-reduce-llm).
+
+## Context compression (Headroom)
+
+Compress tool outputs before they reach the LLM — 60-95% fewer tokens for JSON, 15-20% for code. Powered by [Headroom](https://github.com/chopratejas/headroom) (Netflix).
+
+```bash
+pip install agenthandler[compression]
+```
+
+```python
+from agenthandler import CompressedSupervisor, Policy
+
+sv = CompressedSupervisor(
+    Policy(token_budget=50000),
+    compression="auto",       # "auto", "always", or "off"
+    target_model="claude-sonnet-4-6",
+)
+
+result = await sv.call("search", search_fn, query="quantum computing")
+# result.output is compressed — same information, fewer tokens
+```
+
+Or compress individual outputs:
+
+```python
+from agenthandler import compress_output
+
+raw_data = {"rows": [{"id": i, "name": f"item_{i}"} for i in range(1000)]}
+compressed = compress_output(raw_data, model="claude-sonnet-4-6")
+# 60-95% smaller for JSON payloads
+```
+
+Compression is lossless and reversible — Headroom caches originals locally. If the LLM needs full detail, it retrieves via the `headroom_retrieve` tool. Combine with model routing for maximum cost reduction.
+
+## SDK adapters
+
+Wrap tools from any agent SDK with AgentHandler supervision — no rewrite needed.
+
+```python
+from agenthandler import supervised_tool_registry, SessionManager, MemoryStore
+
+# Bulk-wrap a dict of tools — creates a supervised session automatically
+supervised = supervised_tool_registry(
+    {"search": search_fn, "write": write_fn},
+    SessionManager(MemoryStore()),
+    policy={"tool_timeout": 30, "token_budget": 50000},
+)
+
+# Use supervised["search"] in your OpenAI/Claude/Mastra agent
+```
+
+Individual wrapping for finer control:
+
+```python
+from agenthandler import wrap_openai_tool, wrap_claude_tool
+
+# For OpenAI Agents SDK
+supervised_search = wrap_openai_tool(search_fn, supervisor, tool_name="search")
+
+# For Claude Agent SDK
+supervised_write = wrap_claude_tool(write_fn, supervisor, tool_name="write")
+```
+
+Convert AgentHandler guardrails to OpenAI format:
+
+```python
+from agenthandler import openai_guardrail_adapter, UrlGuard, RecursionDetector
+
+oai_guardrails = openai_guardrail_adapter([
+    UrlGuard(allowlist=["*.example.com"]),
+    RecursionDetector(max_repeats=3),
+])
+```
+
+## A2A protocol (agent-to-agent)
+
+Supervise inter-agent communication via Google's Agent2Agent protocol. Every outbound call goes through the Supervisor.
+
+```python
+from agenthandler import A2AClient, A2AAgentCard, Supervisor, Policy
+
+supervisor = Supervisor(Policy(tool_timeout=30, token_budget=50000))
+client = A2AClient(supervisor=supervisor)
+
+# Call another agent
+result = await client.send_task(
+    agent_url="https://other-agent.example.com",
+    task={"skill": "research", "input": "quantum computing"},
+)
+
+# Make your agent discoverable
+card = A2AAgentCard.from_supervisor(
+    supervisor, name="my-agent", url="https://my-agent.example.com"
+)
+```
+
 ## Policy from config
 
 Load policy from a dictionary (YAML, JSON, database — whatever you use):
@@ -1289,11 +1504,19 @@ obs = Observer(otlp_endpoint="http://localhost:4317")
 # Spans and metrics exported automatically to your collector
 ```
 
+## Independent acceptance checks
+
+Use `VerificationGate` to require named application validators before treating an
+agent proposal as verified. Missing validators, empty evidence, rejected checks,
+exceptions, and timeouts cannot produce success. Every attempt executes fresh
+checks. See [verification gates](docs/verification-gates.md) for artifact binding,
+restart handling, and an independent regression-test example.
+
 ## Contributing
 
 ```bash
 # Install dev dependencies
-pip install -e ".[dev]"
+pip install -e ".[dev,server]"
 
 # Run tests
 pytest tests/ -v