[Feature] agents: orchestration — agent-as-tool, handoff, sharded agents, typed facade

[pathosDev]

Part of the agents epic #421.

Rationale

Multi-agent systems should be patterns over existing primitives — not new machinery. Supervision trees, routers, pub-sub and sharding already answer "who coordinates whom, who restarts whom, where does a session live".

Scope

• Agent-as-tool (askAgentTool adapter): a supervisor agent delegates to child agents through the tool interface, so the supervision tree and the delegation graph coincide.
• Handoff: source persists handed-off, target receives adopt-conversation (summary or full transcript). Correlation machinery defers to [Feature] Conversation primitive for multi-turn ask #224 (Conversation primitive) when it lands.
• Sharded agents: startShardedAgents(cluster, { typeName, optionsFor }) — sessionId = entityId, persistenceId derived; passivation + remember-entities work unchanged; scheduled wake-ups later via [Feature] Grain Reminders (persistent timers that survive deactivation) #168 (Reminders).
• Typed facade: agentBehavior(options) for the Behaviors DSL (same engine as the class API).
• Docs for router/pub-sub group patterns (fan-out to an agent pool, broadcast notifications).

const region = startShardedAgents(cluster, {
  typeName: 'support-agent',
  optionsFor: entityId => AgentOptions.create()
    .withAgentId(entityId)
    .withModel('default')
    .withSystemPrompt(SUPPORT_PROMPT),
});
region.tell({ entityId: 'user-17', kind: 'user-turn', content: 'Where is my order?' });

Documentation

"Multi-agent patterns" docs page (EN + DE); JSDoc; CHANGELOG; feeds the examples/agents app.

Acceptance

• MultiNodeSpec test: sharded agents survive rebalance with session continuity; handoff transfers a conversation; agent-as-tool delegation covered under ScriptedChatModel.

Non-goals

Saga machinery (#179/#88); the Conversation primitive itself (#224).

Relates

Epic #421; depends on #424 (AgentActor). #168, #224.