feat: agent runtime capabilities — cancellation, usage, parallel tools, reasoning levels + docs

[dynamder]

Summary

Agent runtime capabilities batch + full documentation proofread, verified locally with act against the CI workflow.

Highlights

• Cancellation — every entry point (\ire\ → \FireHandle, \ire_stream, \send, \send_stream) carries a per-call \CancellationToken: \cancel()\ or dropping the handle immediately stops receiving output, abandons in-flight tool executions (shared workers survive), and emits \AgentEvent::Cancelled\ through the middleware chain and subscribers — never into session history. Awaiting a cancelled handle yields \OrchestrateError::Cancelled. Cancellation is fully cooperative (\�iased\ selects on stream consumption, the initial provider request, and tool execution) so middleware notification is reliable.
• Token usage tracking — \TokenUsage\ + \TokenEvent::Usage; requests set \stream_options.include_usage; DeepSeek/OpenAI report usage; \ChatResponse.usage. Cost computation left to callers.
• Parallel tool execution — \max_concurrent_tools\ (default 4) workers over the shared tool bus.
• Reasoning levels — \ReasoningLevel\ (Off/Minimal/Low/Medium/High/XHigh/Max) with hot-reload via \AgentRuntime::set_reasoning_level; DeepSeek mirrors the official harness (\ hinking\ +
  easoning_effort\ for high/max), OpenAI maps to
  easoning_effort\ (xhigh/max clamped to high).
• Stable session id — \AgentRuntime::session_id\ reused by \send/\send_stream; \ire\ keeps a fresh one-shot id (fork semantics).
• Message serde gating — new \serde\ feature on \unera-core\ gates Serialize/Deserialize on the chat message types.
• *\Tool::is_shell_tool* — ShellPolicy scrutiny applies by an explicit marker instead of a hard-coded tool-name list.
• Docs — README/docs proofread against the code (incl. fixing the \ ool_policy\ run command), new \cancel\ example, mdBook rebuilt.

Breaking change

\Agent::fire\ now returns a \FireHandle: use \�gent.fire(msg, &runtime).await?.await?\ (all examples/doctests updated).

Verification

• Full test matrix passes: funera-core 104 + 9 doctests, funera-orchestrate 69 + doctests, builtin-tools 59.
• CI validated locally with act on Linux containers: fmt, msrv (Rust 1.88), doc, mdbook, doc-test, clippy (-D warnings), test-core (3 feature sets), test-orchestrate (6 feature sets), feature-matrix (cargo-hack powerset) — all green.
• act surfaced two real issues that were fixed: a cancellation race (unbiased select could consume a chunk before cancelling) and a clippy \clone_on_copy.
• Not run locally: semver / coverage / mutants / test-cross (need release metadata, tokens, or a multi-OS matrix — real CI covers them).

Commits

• feat(core): serde-gated messages, stable session id, usage, parallel tools, reasoning levels, shell marker, cancellable loop
• feat(orchestrate): cancellable handles (FireHandle), usage/reasoning/parallel wiring, cancel example
• feat(builtin-tools): ShellTool opts in via Tool::is_shell_tool
• docs: proofread docs against code, rebuild mdBook, fix tool_policy command