feat(plugin): add Future-returning typed LLM intercepts

[afourniernv]

Overview

Add Future-returning typed registration methods for native API v2 buffered and streaming LLM execution intercepts.

This is the 0.8-oriented Future lane discussed alongside #730. It is intentionally stacked on #594 and reuses that PR's cooperative host polling, cancellation, panic isolation, continuation ownership, bounded stream backpressure, and unload safety. It does not replace the completion-based 0.7 option in #730.

• I confirm this contribution is my own work, or I have the right to submit it under this project's license.
• I searched existing issues and open pull requests, and this does not duplicate existing work.

Details

• Add PluginContext::register_async_llm_execution_intercept, whose callback returns a Future<Output = Result<Json>>.
• Add PluginContext::register_async_llm_stream_execution_intercept, whose callback returns a Future<Output = Result<LlmStreamExecutionOutcomeV2>>.
• Delegate both methods to feat(plugin): add targeted LLM continuations to native API v2 #594's existing native API v2 implementation. This PR adds no executor, polling loop, ABI table, completion state, or stream queue.
• Preserve the existing synchronous typed methods and the versioned register_async_llm_*_v2 methods unchanged. This PR is additive and does not change the native ABI.
• Update the Rust SDK and native-plugin documentation to make the Future-returning names the normal native API v2 authoring surface.

The two lanes have different ownership:

• feat(plugin)!: expose typed async middleware in Rust dynamic plugins #730 exposes safe completion handles. The plugin owns async execution and explicitly resolves or rejects each invocation. That is the smaller release/0.7 change and works with Switchyard's current FFI workaround.
• This PR accepts a Future directly. Relay polls it through feat(plugin): add targeted LLM continuations to native API v2 #594 and maps its result into completion, cancellation, stream backpressure, and handle-release behavior. That removes lifecycle bookkeeping from plugin authors but depends on the larger native API v2 design intended for 0.8.

Validation:

• cargo fmt --all
• cargo clippy --workspace --all-targets -- -D warnings
• just test-rust
• cargo test -p nemo-relay-plugin
• just docs (passes; authenticated Fern redirect check skipped because FERN_TOKEN is not configured)
• uv run pre-commit run --all-files
• Switchyard test: validate OpenClaw hook-only fallback exports #220 adapted to the new method names: 19 plugin tests, Clippy, and release build passed.
• Switchyard real-process E2E passed with a compiled Relay host and native plugin. It covered buffered and streaming OpenAI Chat, OpenAI Responses, and Anthropic Messages; 12 concurrent random-router calls; six concurrent classifier calls; retries, fallback, pass-through, late stream failure, and credential isolation.

Where should the reviewer start?

Start with crates/plugin/src/native_v2.rs. The main design question is whether these additive Future-returning names are the preferred safe SDK surface over exposing completion ownership directly in #730. The implementation itself is a thin adapter over #594.

This draft is stacked on #594, so GitHub will show that PR's commits until it merges or this branch is rebased onto main.

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

• Relates to [Enhancement]: Expose safe typed asynchronous callbacks in the Rust native-plugin SDK #716
• Depends on feat(plugin): add targeted LLM continuations to native API v2 #594
• Alternative release/0.7 implementation: feat(plugin)!: expose typed async middleware in Rust dynamic plugins #730
• Downstream Future consumer and validation: feat(plugin): add Relay random and LLM-classifier routing NVIDIA-NeMo/Switchyard#220
• Current Switchyard completion workaround: feat(relay): add Switchyard-owned HTTP dynamic plugin NVIDIA-NeMo/Switchyard#270

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: d60c92ba-5c11-4f6e-bff7-f681e7c161a3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}