docs(adr): define OAB delegation adapter

[chaodu-obk]

What problem does this solve?

A running OAB agent currently has no first-class way to delegate a bounded task to another remote OAB agent and wait for the result. Forwarding a prompt through Discord or exposing ACP directly would lose task identity, lifecycle control, capability boundaries, cancellation, reconnect, and provenance.

Discord Discussion URL: https://discord.com/channels/1490282656913559673/1529261985881919529

Review Contract

Goal

Define the delegation adapter architecture for inter-OAB remote tasks: Agent A asks OAB B to perform a bounded task, observes progress, receives one structured terminal result, and continues its original work. The ADR must also define the depth-one read-only MVP and the Codex multi-agent v2 semantics OAB should adopt or deliberately reject.

Non-goals

This PR does not implement the adapter or runtime protocol. It does not define recursive delegation, arbitrary workflow DAGs, dynamic peer discovery, federation, shared writable worktrees, credential forwarding, direct ACP exposure, chat-platform delegation, or a Cloudflare-specific relay.

Accepted Residual Risks

The MVP requires preconfigured trusted peers and an authenticated A2A binding. A
worker crash during an external side effect can produce an unknown outcome,
so callers must reconcile status rather than blindly retry. The A2A decision is
subject to a time-bounded replay, relay, and profile gate; a failed gate falls
back to the custom OAB protocol. Read-only work is the default; write
coordination and durable workflow recovery remain deferred.

Acceptance Criteria

• The ADR starts from the concrete inter-OAB user story and distinguishes the delegation adapter from ChatAdapter and ACP.
• The ADR defines the MVP task lifecycle, task identity, reconnect, cancellation, budgets, concurrency limits, and read-only default.
• The ADR explains which Codex multi-agent v2 lessons OAB adopts: task identity/path separation, mailbox events, distinct lifecycle operations, explicit context, bounded concurrency, and auditability.
• The ADR preserves fail-closed authority attenuation, no credential/session forwarding, no recursive delegation, and signed result provenance.
• The ADR records A2A 1.0 as the wire candidate, the mandatory OAB Delegation Profile, three implementation gates, and custom fallback behavior.
• Local documentation validation passes: required headings, local links, ASCII/trailing-whitespace checks, and git diff --check.

Follow-ups

Implement the backend-neutral coordinator, run the time-bounded A2A HTTP/JSON-RPC + SSE and WSS baseline spike, define the normative OAB Profile extensions,
execute replay/relay/profile conformance tests, and then select the binding only
if all gates pass. Evaluate follow-up/message operations, federation, and write
leases only after the depth-one read-only MVP is stable.

At a Glance

Agent A -> OAB A DelegationAdapter -> A2A HTTP/JSON-RPC + SSE -> OAB B -> local ACP -> Agent B
                                      progress/events/result <-----------------------------
                         WSS is optional custom binding; failed gate -> custom OAB protocol

Prior Art & Industry Research

Codex multi-agent v2:

Codex v2 provides the closest orchestration lessons: canonical task paths, separate lifecycle operations, mailbox/event wake-ups, explicit context inheritance, bounded concurrency, and structured collaboration events. OAB adopts these semantics without copying the experimental Codex wire schema.

• https://developers.openai.com/codex/concepts/subagents
• https://github.com/openai/codex/tree/main/codex-rs/core/src/tools/handlers/multi_agents_v2
• https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/multi_agents_spec.rs
• Regression: encrypted MultiAgentV2 messages remove readable task audit trail openai/codex#28058

A2A Protocol v1.0:

A2A is the selected inter-OAB wire candidate, subject to a time-bounded
implementation gate. Its Agent Card, Task, Message, Artifact, cancellation,
streaming, asynchronous update, and standard HTTP/JSON-RPC bindings overlap
with the delegation adapter user story. OAB still requires a mandatory
Delegation Profile for authority attenuation, durable cursor replay, signed
provenance, artifact ownership, depth-one policy, credential isolation, and
unknown/expired outcomes.

The gate has three conclusive parts: Replay, Relay, and Profile. Replay must
cover disconnect/reconnect without missing terminal events, restarting ACP, or
repeating side effects. Relay must compare direct and dual-outbound topology,
including reconnect, cancellation races, backpressure, latency, firewall/load
balancer compatibility, monitoring, and key rotation. Profile must remain a
thin, explicitly negotiable and rejectable extension that does not redefine A2A
core lifecycle or artifact semantics. Any failed gate falls back to the custom
OAB protocol and must not claim standard A2A interoperability.

• https://a2a-protocol.org/latest/specification/
• https://a2a-protocol.org/latest/topics/streaming-and-async/
• https://a2a-protocol.org/latest/definitions/
• https://github.com/a2aproject/A2A

OpenClaw:

OpenClaw demonstrates explicit per-agent routing, separate state/workspace boundaries, and opt-in agent-to-agent messaging. OAB adopts the separation and monotonic policy ideas while adding a remote protocol and signed provenance.

• https://github.com/openclaw/openclaw/blob/main/docs/concepts/multi-agent.md

Hermes Agent:

Hermes demonstrates fresh child conversations, bounded concurrency, cancellation/background completion, and explicit unknown handling when a worker may have had side effects.

• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/delegation.md

Proposed Solution

Add a dedicated delegation adapter with an A2A client side in OAB A and an A2A
server side in OAB B. The selected standard binding is HTTP/JSON or JSON-RPC
over HTTP with SSE; WSS is optional only as an explicitly declared A2A custom
binding. The adapter remains transport-neutral until the Replay, Relay, and
Profile gates pass, and falls back to the custom OAB protocol if any gate fails.
OAB B executes through its local ACP/session lifecycle and never exposes its
local credentials, environment, session, or tool handles.

The task model uses request_id -> A2A taskId -> turn_id -> event sequence/cursor.
A request is idempotent, a task is reconnectable, events are durably replayable
under the OAB Profile, and a terminal result distinguishes completed, failed,
cancelled, expired, and unknown outcomes. The default policy is depth-one,
read-only, bounded, and deny-by-default for peers and capabilities.

The authority model remains capability attenuation:

effective_authority = caller grants intersection OAB A policy intersection OAB B policy intersection request capabilities intersection deployment limits

Results bind request and result digests, executor identity, effective
capabilities, and artifact/side-effect provenance in a callee-signed envelope.

Why this approach?

The adapter boundary matches the user story: one OAB agent delegates to another
OAB, rather than pretending that a remote worker is a chat participant or
exposing a local ACP implementation. A2A provides the shared task, artifact,
Agent Card, cancellation, and streaming vocabulary; the OAB Profile adds the
fail-closed authority, durable observation, and provenance contract. A bounded
spike prevents the project from mistaking an A2A-shaped wrapper for genuine
interoperability or accepting a relay topology that cannot meet OAB's safety
requirements.

Alternatives Considered

• Chat-platform forwarding: rejected because it cannot reliably provide task lifecycle, replay, cancellation, peer authentication, or provenance.
• Direct ACP exposure: rejected because ACP is the callee's local runtime boundary, not the inter-OAB contract.
• MCP as the outer protocol: rejected because MCP models agent-to-tool/resource access, while this feature models remote OAB task ownership and lifecycle.
• Local-only subagents: rejected because the user story explicitly requires remote inter-OAB execution.
• Stateless HTTP only: not sufficient by itself, but A2A HTTP/JSON or JSON-RPC plus SSE is the preferred candidate and must pass the durable replay and relay gates.
• Cloudflare Worker/Durable Object as a core dependency: rejected because a relay is a deployment option, not a protocol invariant.

Validation

• ADR headings, local links, ASCII content, and trailing whitespace were checked locally.
• git diff --check passes for the documentation change.
• The ADR records A2A 1.0 intent, mandatory OAB Profile requirements, Replay/Relay/Profile gates, and custom fallback behavior.
• No runtime code, dependency, or configuration behavior changes are included; the rebased PR diff is the ADR file only.