feat: agent discovery (calf.agents) + caller-side Ask adapter

[ryan-yuuu]

Summary

Agent-to-agent discovery (calf.agents) and the caller-side Ask (request/reply) mode, built on the substrate primitive. Phase 2 — after the Phase 1 substrate + capability migration.

Spec: docs/designs/agent-discovery-and-ask-spec.md

Blocked by: #239 (substrate — provides ControlPlaneView / ControlPlanePublisher).

Key design finding

A peer agent needs no new callee-side handler — invoked over the standard call path (a seeded sub-conversation State sent to its dispatch topic with a callback_topic), it processes the request through its existing run and replies through the existing reply slot. The only genuinely new code is the caller-side peer-as-tool adapter.

Scope / work breakdown

• AgentCard (extends ControlPlaneRecord) + calf.agents, published via ControlPlanePublisher only when discoverable=True (opt-in)
• Static peer wiring: peers=[...] resolved against the agents view (the include-list is the trust boundary)
• Caller-side Ask adapter: seed a sub-conversation State from the tool args; Call the peer with tag = tool_call_id + the caller's return slot; translate the peer's ReturnMessage.parts → ToolReturn folded into state.tool_results
• Node-side State-seeding helper (today State-seeding lives only in Client)
• Dynamic discovery: find_agents(query) tool (default-closed), filtered to live ∩ allowed
• Caller-side trust: opt-in advertise + scoped consume
• Tests: A asks peer B over the standard path; reply folds into A's tool result; non-discoverable agent absent from calf.agents; stale peer excluded from selection

Out of scope (deferred)

• All error handling — deadlines, timeouts, dangling-call recovery, recursion/depth budgets — inherited from the SDK-wide error-propagation work (Reliability successor to the fault rail: retry, redelivery, timeouts, DLT #222 family). (A true per-call deadline is impossible in the suspend-to-Kafka re-entry model; reply_ttl is a client-only in-process timer.)
• Enlist mode (multiple agents sharing one live conversation — needs concurrent-history merge, unsolved).
• Callee-side admission / operator ACL → feat: per-node access-policy control plane (compacted, node_id-keyed ACL) for tool & peer allow-lists #231 (needs caller-identity-on-the-wire; the Ask adapter only reserves a seam).

Related

• Substrate umbrella: feat: node presence control plane — substrate & shared control-plane primitive (umbrella) #239
• Callee-side trust deferred to: feat: per-node access-policy control plane (compacted, node_id-keyed ACL) for tool & peer allow-lists #231

[ryan-yuuu]

Closing — implemented by the agent-mesh work (#279 discovery/addressing substrate, #281 messaging). Agents advertise an AgentCard to calf.agents; the caller-side Ask adapter is the runtime message_agent tool (seeds a sub-State, Calls the resolved peer, folds the reply back into the tool result). Static peers=[Messaging(...)] wiring + discover=True dynamic discovery both land. (Advertising is always-on rather than gated by a discoverable= flag, and dynamic discovery is the discover=True handle mode rather than a find_agents() tool.)