maintain-dynamic-plugins

作者： nvidia

维护NeMo Relay动态插件加载器、清单、Rust原生SDK、gRPC工作节点协议、Python工作节点SDK、文档、测试及发布工作流覆盖

npx skills add https://github.com/nvidia/nemo-relay --skill maintain-dynamic-plugins

Maintain Dynamic Plugins

Use this skill for plugin.kind = "rust_dynamic", plugin.kind = "worker", nemo-relay-plugin, nemo-relay-worker, nemo-relay-worker-proto, nemo-relay-types, and the Python nemo-relay-plugin package.

Rules

Keep the stable boundary explicit: native plugins cross a C ABI; worker plugins cross grpc-v1.
Do not pass Rust runtime types, trait objects, futures, or allocator-owned strings across the native dynamic-library boundary.
Typed native middleware futures run on the SDK-owned Tokio executor. Keep subscribers synchronous and preserve raw synchronous ABI registrations.
Define closed worker transport structures in protobuf when generated clients must enforce their fields. Keep open application payloads lossless by using JsonValue or JsonEnvelope rather than google.protobuf.Value.
Keep relay-plugin.toml dynamic records separate from generic runtime components. Enabled dynamic records may synthesize internal component specs; disabled records stay inspectable but unloaded.
Relay 0.8 establishes the native API 1 and grpc-v1 canonical ToolExecutionResult baseline. Require every dynamic plugin to rebuild and declare a compat.relay range that excludes versions before 0.8. Recommend >=0.8.0,<1.0; open-ended or narrower 0.8-or-newer ranges are valid.
Treat compat.relay as the plugin author's compatibility assertion, not proof that an artifact was rebuilt. Do not add a legacy raw-result adapter.
Relay 0.8 retains the grpc-v1 identifier and nemo.relay.worker.v1 package while changing the tool-result protobuf types; every worker must regenerate its bindings and rebuild. Native ABI v4 permits append-only host-table extensions guarded by struct_size; existing fields must remain frozen at their original offsets. Incompatible native JSON, reordered or replaced native fields, or incompatible worker protobuf changes must bump native_api or worker_protocol.
Do not add tests under src; Rust tests belong in crate tests/ trees and Python SDK tests belong under python/tests.
Native and worker plugins are trusted extensions. Document that native plugins are in-process and unsandboxed; worker plugins provide process isolation but not a security sandbox.

Checklist

Manifest validation covers kind, compatibility, load contract, integrity, capability mismatch, and disabled-plugin behavior.
Native loader keeps libraries alive until registered callbacks are cleared and deregisters plugin kinds before unload.
Worker activation covers process launch, token auth, handshake, validation, declarative registration, proxy rollback, cancellation, and shutdown.
Rust and Python SDKs expose every supported registration surface.
Runtime helpers cover marks, scopes, continuations, and isolated scope stacks.
plugins list, plugins inspect, and plugins validate report lifecycle and compatibility status without leaking secret config.
Top-level doctor reports resolved dynamic plugin and host configuration status.
When detailed dynamic plugin guides exist, they keep Rust native, Python worker, and grpc-v1 protocol details on separate pages.
justfile, Codecov, and CI package/test workflows include new plugin crates and packages.

Validation

Choose checks by the changed layer:

Manifest or shared types: test the owning Rust crate.
Native loader or ABI: prepare plugin fixtures and run the focused native plugin integration test.
Worker protocol or host: test the worker crates and regenerate or test the Python worker SDK only when its protocol surface changes.
Shared runtime behavior: run the Rust suite and only binding suites whose observable plugin behavior changes.
Documentation or packaging: run their targeted checks only when changed.

Canonical surface suites prepare plugin fixtures. Before a raw focused native or worker integration test, run just build-test-plugin-fixtures; never compile fixtures inside an individual test case.