[tommasobolis]

Promotion of develop → main for 0.2.0. develop reads __version__ = "0.2.0" (#1521), and main is on 0.1.3.

Included

Everything on develop since the 0.1.3 promotion (#1138): Phase 2 (epic #260) and the 0.2.0 pre-release code review (epic #1414). The release readiness work is tracked in #1435. Per-PR list: main...develop

Still open in the milestone, and closed after the tag: #1435, #1414, #260, and #219 (its demos PR pins the published package).

Breaking changes

From 0.1.3. No name was removed from donkey_kit, and no extra was dropped. These changes can still affect existing code. Each has its own section, with the fix, in MIGRATION.md.

• New refusal types. A CIBA pending 401 is now GatewayApprovalPending, which except AuthError: no longer catches, and a CIBA denial 403 is GatewayApprovalDenied (classify: type the OBO policy's CIBA authorization_pending instead of AuthError #1320). Google Model Armor and CrowdStrike AIDR blocks are ContentSafetyBlocked instead of PolicyViolation(policy="unknown"), and their donkey.policy.type reads content_safety (refusals: type the Google Model Armor Guardrails rejection #1178, refusals: type the CrowdStrike AIDR Guardrails rejection #1176).
• classify is a Classifier object. Calling it works as before, but inspect.isfunction(classify) is False. To type a custom policy, use classify.register() instead of wrapping it (feat(classify): registry so custom gateway policies become typed exceptions #1152).
• Calls that raised NotImplementedError now run. donkey publish and donkey verify are visible and do the work: they exit 0, 1 or 2, and no longer exit 3 (scanner: donkey publish registers the manifest with Exchange / Agent Registry #218, cli: wire donkey verify to Publication.verify() #1352). discover(), donkey.registry.search(), resolve_mcp() / resolve_agent(), explain(), Publication.verify(), the ToolSet bindings and derive_descriptor(mode="auto…") make control-plane calls. An except NotImplementedError: fallback around them is no longer reached. A gateway credential is held back from a base_url set in the project files that isn't a regional Anypoint host (ADR 0019, tools: apply the ADR 0005 endpoint check to the gateway credential on discovered servers #1479).
• donkey.tools.discover() defaults to governed=True. Pass governed=None for the unfiltered list (ADR 0017, tools: confirm or revisit discover()'s unfiltered default before 0.2.0 #1424).
• GovernanceCriteria is imported from donkey_kit again. from donkey_kit.experimental import GovernanceCriteria still works, but it emits a DeprecationWarning (release: settle the stability tier of the new 0.2.0 public surface #1425).
• Install changes. [cli] needs typer>=0.26.0 and rich>=13.8.0, and no longer installs click (Nightly framework matrix failing #1196). [all] adds mcp and a2a, and [adk] installs litellm[mcp] (see Extras changes).
• AgentKilled is terminal for the Donkey that saw it. Build a new Donkey to carry on (killswitch: recognise the kill-switch rejection and stop cleanly #220).
• refusal_translator leaves the __all__ of the Agent Framework and Strands adapters. A direct import still works (adapters: drop internal hooks from __all__ and unify the approval helpers #1422).
• A configured URL with a user name or password is refused with ConfigError before anything is sent. Before, httpx sent those credentials to the host as Authorization: Basic (core: refuse a user name or password in configured endpoint URLs #1478).
• AgentFrameworkAdapter(...).policy_middleware() without agent_framework installed raises the install-hint ImportError instead of NotImplementedError (agent_framework: policy_middleware() raises NotImplementedError instead of the install hint when agent_framework is missing #1503).

From a 0.2.0 pre-release (0.2.0.devN, 0.2.0rc1). These surfaces first shipped in the 0.2.0 pre-releases, and they changed before the final with no deprecation cycle. The full list is in MIGRATION.md. The changes most likely to need a code edit:

• Identity: donkey.as_user(id_token=...) is donkey.as_user(token=...), and token_exchange_path is gone. as_user() refuses an llm_proxy_url from the working-directory config files. Set it in the environment or in code, or set DONKEY_TRUST_PROJECT_CONFIG=1.
• Tools: ToolSet.openai() is ToolSet.openai_agents(). A per-tool binding raises AuthError under a different as_user() user, so bind inside the block that runs the agent. A gateway with a plain http:// public URL is refused unless DONKEY_ALLOW_HTTP=1 is set.
• Approvals: donkey.approvals is per client, and the module-level instance is gone (ADR 0018). An unknown approval id raises ApprovalNotFound, which is still a KeyError. ApprovalRejected and GatewayApprovalDenied share the new ApprovalError base. A resumed approval runs as its requester. The adapter helpers return Approval objects, with the framework object on .native. A Strands approval covers exactly one call. require_approval() on a whole-server binding raises ConfigError.
• CLI and Action: donkey dev --version is --agent-version. The --json documents carry their own format key (publish_format, verify_format, expose_format). A failed publish --json prints its outcome and exits 1. donkey verify exits 2 with no gateway credential. Pass the Action's client-secret from secrets.*; its skipped output is gone.
• Errors: the ADK, LangGraph and Agent Framework helpers raise the install-hint ImportError instead of a bare ModuleNotFoundError.

Notes

donkey-kit 0.2.0: Phase 2, Differentiate, go beyond. This release adds the capabilities a stock OpenAI client with a base_url can't offer, because they depend on the platform behind the gateway. You get governed MCP tool access, publication to Exchange from your code and CI, on-behalf-of user identity, and human-in-the-loop approvals, including the gateway's own CIBA step-up. You also get an A2A server built on the official a2a-sdk, declarative refusal handlers, typed custom policies, and the OpenAI Agents SDK as the second deep adapter.

pip install --upgrade "donkey-kit==0.2.0"
pip install --upgrade "donkey-kit[all]==0.2.0"   # now includes mcp and a2a

Highlights

• Governed MCP tool access: donkey.tools.discover() finds governed MCP servers in Exchange. ToolSet binds them to LangGraph, the OpenAI Agents SDK, ADK, Strands, MS Agent Framework, Anthropic, CrewAI and LlamaIndex through the governed gateway (tools: donkey.tools.discover() returns governed MCP tools as native framework tools #221, feat(tools): donkey.tools.discover() and the ToolSet framework bindings (#221) #1308, feat(tools): bind discovered MCP servers through the live gateway, CrewAI binding (#221) #1310). A server that isn't governed is refused with UngovernedMcpServer (feat(tools): refuse to bind MCP servers that are not governed (#1150) #1199), and the gateway's tool-access denial is typed as ToolNotInProfile (feat(tools): type the gateway's MCP tool-access denial as ToolNotInProfile #1362). donkey.tools.warm() pre-fills the discovery cache (feat(tools): add donkey.tools.warm() to pre-fill the discovery cache #1333), and discovery emits a span with cache hit and miss counters (feat(tools): a discover() span with cache hit/miss counters #1351).
• Publication to Exchange: donkey scan derives a deterministic model of your agents, tools and MCP servers (feat(scan): donkey scan derives a deterministic model of agents, tools and MCP servers (#217) #1192). donkey publish registers MCP servers and agents in Exchange with a full asset page, including a "Changes since" section (feat(cli): donkey publish registers MCP servers in Exchange (#218) #1259, feat(registry): publish MCP metadata and an Exchange page (#1269) #1270, feat(registry): Overview section and tool governance on the Exchange page (#1273) #1277, feat(publish): publish agent assets and unhide donkey publish #1291, feat(publish): the Exchange page lists what changed since the previous version (#1271) #1358). donkey verify checks what you published against the live tools and agent card (feat(cli): donkey verify checks published MCP servers against their live tools (#1352) #1355, feat(registry): verify an A2A agent's published card against its live card (#1354) #1361). The scan-and-publish GitHub Action runs this from CI (feat: the scan-and-publish GitHub Action, and donkey publish --json (#219) #1263).
• On-behalf-of identity: donkey.as_user(token=...) forwards the user's token to the gateway's OBO policy on model calls and MCP bindings. It never falls back to the service identity (feat(identity): donkey.as_user() on-behalf-of token exchange #1290, feat(identity): as_user() fails hard, never as the service identity #1293, feat(identity): as_user() forwards the user token, no SDK exchange (BG §2.4) #1353, feat(identity): carry the donkey.as_user() token on MCP ToolSet bindings (BG §2.4) #1369, feat(identity): give UserScope a sync with, and include mcp in [all] #1472).
• Human in the loop: @donkey.tool(approval="required") and ToolSet.require_approval() pause gated tools with each framework's own mechanism: LangGraph interrupt(), OpenAI Agents needs_approval, ADK tool confirmation and Strands interrupts (feat(hitl): approval-gated tools with @donkey.tool(approval="required") (BG §2.3) #1154, feat(hitl): LangGraph interrupt() and Command(resume=) for approval-gated tools (BG §2.3) #1155, feat(tools): ToolSet.require_approval() gates discovered MCP tools (#1153) #1201, feat(openai_agents): map tool approvals onto needs_approval (BG §2.3) #1233, feat(strands): pause approval-gated tools with Strands' own interrupt (BG §2.3) #1239, feat(adk): pause approval-gated tools with ADK's own tool confirmation (BG §2.3) #1241). The gateway's CIBA step-up arrives as typed, waitable GatewayApprovalPending / GatewayApprovalDenied (feat(core): type the OBO policy's CIBA step-up answers (#1320) #1329, Carry gateway CIBA step-up as typed, waitable approvals #1376).
• A2A: donkey.serve() wraps the official a2a-sdk, with a governed inbound (feat(a2a): donkey.serve() wraps the official a2a-sdk #1212, feat(a2a): governed inbound for donkey.serve() tasks (#225) #1225). donkey dev runs a simulated A2A ingress, and donkey expose / donkey preflight put the gateway instance in front of your agent (feat(a2a): donkey dev with a simulated A2A ingress (BG §2.9.3) #1287, feat(cli): donkey expose and donkey preflight #1330).
• Refusals: declarative refusal handlers (donkey.on(...)) react but never un-refuse (feat(refusals): declarative refusal handlers that react but never un-refuse (BG §2.1) #1146). A classification registry turns custom gateway policies into typed exceptions (feat(classify): registry so custom gateway policies become typed exceptions #1152). The kill switch stops runs cleanly (feat(killswitch): stop cleanly on the Agent Kill Switch (BG §2.6) #1151), and Google Model Armor and CrowdStrike AIDR blocks are typed as ContentSafetyBlocked (feat(refusals): type the Google Model Armor Guardrails rejection (#1178) #1180, fix(refusals): type CrowdStrike AIDR from its policy source (ADR 0016) (#1429) #1461).
• A second deep adapter: the OpenAI Agents SDK joins LangGraph as a conformance-gated adapter (feat(adapters): OpenAI Agents SDK becomes the second deep adapter (BG §1.8) #1164).
• Around them: an inbound correlation ID is carried across MCP and A2A hops (Adopt an inbound correlation ID and hand it to MCP/A2A hops #1258), and donkey.run() keeps a run ledger (feat(telemetry): run ledger for donkey.run() (#613) #1379). You can set the business group per request (feat(attribution): set the business group per request (#310) #1190) and send a provider key for Dynamic-key routes (feat(config): send the provider key in a configurable header for Dynamic-key routes (BG §1.1) #1253). The budget has a stated concurrency contract (fix(budget): state and enforce the concurrency contract for Budget and correlation (#311) #1189) and reads the upstream provider's rate-limit window (feat(budget): read the upstream provider's rate-limit window as its own source (BG §1.3) #1246).
• Hardening from the 0.2.0 code review:
  • Credentials are stripped on cross-origin MCP redirects (fix(tools): strip credentials on cross-origin MCP redirects (#1415) #1459).
  • donkey dev, serve() and scanned endpoints are hardened for non-loopback use (Harden donkey dev, serve() and scanned endpoints for non-loopback use #1458).
  • An out-of-range budget reset header no longer crashes send() (fix(budget): ignore an out-of-range reset header instead of crashing send() #1456).
  • The 0.2.0 API stability tiers are settled, with a snapshot of the stable surface (chore(api): settle the 0.2.0 stability tiers and snapshot the stable surface (#1425) #1460).

Extras changes (§8.4)

• mcp is back (mcp>=1.24) for ToolSet binding. It was dropped in 0.1.2 and last shipped as mcp>=1.2.
• a2a is back (a2a-sdk[http-server]>=1.2.0, uvicorn>=0.30) for donkey.serve(). It was dropped in 0.1.2 and last shipped as a2a-sdk>=0.1.
• all now installs llm, langgraph, otel, cli, local, a2a, mcp, so it adds mcp and a2a (identity: give UserScope a sync with, and include mcp in [all] #1436).
• adk: litellm>=1.84 becomes litellm[mcp]>=1.84. From litellm 1.106, model() with tools needs mcp (fix(adk): install litellm's mcp extra so tool-bearing model() runs work (#1267) #1289).
• cli: typer>=0.15.4 becomes typer>=0.26.0, and rich>=13.0 becomes rich>=13.8.0 (fix(cli): raise the typer floor to 0.26.0 so argument help survives click 8.5 #1200).
• The base dependencies, the Python floor (3.10), the donkey console script and the pytest plugin entry point are unchanged. Extras stay floors only, with no upper pins.

Verification-status changes (§0.3)

In docs/verified-apis.md:

• MCP discovery and binding. Discovery and ToolSet binding through the governed gateway move from blocked to VERIFIED (LIVE), 2026-10-28 (§9, tools: donkey.tools.discover() returns governed MCP tools as native framework tools #221). They run over framework binding classes that are VERIFIED (local round-trip) (verify(adk): installed constructor, MCP binding and descriptor APIs (§§8–10) #636–verify(agent-framework): MCP binding and descriptor APIs (§§9–10) #652). The tool-access denial shape is VERIFIED (LIVE) (docs(verified-apis): live-verify the MCP tool-access denial shape (BG §2.7) #1359).
• MCP and A2A resolution. Endpoint resolution and the governed-state reads behind explain() are VERIFIED (LIVE) (§6, verify: resolve an Exchange MCP asset to its governed gateway endpoint #1297, verify: read an MCP instance's governed state so registry.explain() reports real checks #1298, verify: read back a published A2A agent's card and its live card through the gateway #1354).
• Publication. Exchange search, and the publication of scanned MCP servers and agents, move from blocked to VERIFIED (LIVE) (§7, Verify the Exchange asset search API and whether wildcard query is server-side #53, scanner: donkey publish registers the manifest with Exchange / Agent Registry #218, scanner: donkey publish publishes agent assets to Exchange #1260).
• donkey verify. The read-back of a published version's MCP tools and agent card, which donkey verify compares against, is VERIFIED (LIVE), 2026-10-29 (§7, test(conformance): restore the 13 retired scenarios once their surfaces are verified #991, verify: read back a published A2A agent's card and its live card through the gateway #1354).
• as_user() header. The user-token header is VERIFIED (LIVE), 2026-10-29: Authorization: Bearer <token>, on model calls and MCP bindings (§13, verify: the Trusted Agent Identity token-exchange endpoint and header #255).
• CIBA step-up. The pending (401), denied (403) and initiation-failure (502) shapes are VERIFIED (LIVE), 2026-10-28 and 2026-10-29, on model and MCP tools/call traffic (§4, classify: type the OBO policy's CIBA authorization_pending instead of AuthError #1320, Flip CIBA tools/call and 502 rows to VERIFIED (LIVE) in verified-apis.md #1380).
• Content safety. The Google Model Armor rejection is VERIFIED (LIVE), 2026-10-19 (§4, refusals: type the Google Model Armor Guardrails rejection #1178).
• CrowdStrike AIDR. The AIDR rejection is VERIFIED (POLICY SOURCE), a new evidence class (ADR 0016). Its shape is read from crowdstrike-aidr-guardrails-policy 1.0.0, not captured live, because no proxy runs it. classify() types it as ContentSafetyBlocked(provider="crowdstrike-aidr"). The live capture is still open (verify: capture the CrowdStrike AIDR Guardrails rejection live #1184), and a capture replaces the derived shape if they differ (§4, refusals: type the CrowdStrike AIDR Guardrails rejection #1176, refusals: stop typing CrowdStrike AIDR until its shape is captured live #1429).
• Still blocked, behind a NotImplementedError("blocked on verification: …"):
  • the lockfile (donkey.tools.lock(), discover(locked=True));
  • the governed-state search filters (search(governed=, environment=, domain=));
  • Publication.preview() / export();
  • the hidden donkey status.
• No row moved from verified to blocked.

Acceptance

donkey-kit==0.2.0 from TestPyPI: passed. This was a live run of all seven groups (./run.sh --version 0.2.0 --index testpypi) on Python 3.12, against the artifact this Release publishes.

• Proxies: all 24 declared proxies were configured, and none was skipped for missing credentials.
• Results: 559 passed, 33 skipped, 0 failed.

Session	Passed	Skipped
[all] + langchain-mcp-adapters (data plane, governance, public surface, blocked, telemetry, frameworks)	415	27
[all,adk]	21	1
[all,strands]	22	1
[all,agent_framework]	12	1
[all,openai-agents]	27	1
[all,anthropic]	11	0
[all,crewai] + crewai-tools[mcp]	12	1
[all,llamaindex] + llama-index-tools-mcp	9	0
packaging	30	1

• Coverage map: consistent. 108 features are mapped, and 321 of 330 collected tests are claimed by a feature.
• Offline published gate (groups 3, 4 and 5): passed in the TestPyPI publish run for 0.2.0.
• Release candidate: 0.2.0rc1 also passed the live run (546 passed, 33 skipped, 0 failed).

[tommasobolis]

Held as draft: this is the develop → main promotion. It merges only with the maintainer's explicit approval, as a no-ff merge commit (gh pr merge --merge), never squash. Auto-mergers: please skip.