/nemo-relay-plugin-build

name: nemo-relay-plugin-build
description: Use this skill when building or packaging reusable NeMo Relay runtime behavior as an embedded configuration component or a manifest-backed `rust_dynamic` native or `worker` gRPC plugin, with deterministic validation and rollback-safe registration.
license: Apache-2.0
metadata:
  author: NVIDIA Corporation and Affiliates

Build a Plugin

Use this skill when a user wants to package reusable NeMo Relay runtime behavior behind plugin configuration. Keep reusable plugin behavior separate from one-off application startup code.

Use This When

Use this skill when the behavior should be activated by shared config and reused across applications, teams, or process startup paths.

Common cases:

• Register subscribers, guardrails, intercepts, or a small bundle of related

runtime behavior.

• Validate operator-supplied config before changing runtime behavior.
• Give reusable behavior a stable plugin `kind` and activation lifecycle.
• Package behavior that should be enabled, disabled, or rolled out through

plugin config rather than repeated application startup code.

Do Not Use This When

Do not build a plugin when a narrower NeMo Relay surface is enough:

• One request or tenant needs temporary behavior -> use scope-local middleware.
• The user only needs first-time scopes, tool calls, or LLM calls ->

`nemo-relay-instrument-calls`.

• The user only needs to choose an exporter path ->

`nemo-relay-plugin-observability`.

• The behavior depends on live callables, provider clients, file handles,

credentials, or framework objects inside config.

Choose A Delivery Model

Choose the delivery model before designing config or registration:

• **Embedded component:** Use the shared plugin document when behavior ships

with the Relay host application. Follow the embedded component model below.

• **Discoverable dynamic package:** Use a `relay-plugin.toml` manifest when the

plugin ships independently of the host. Use `rust_dynamic` for a trusted in-process native Rust library, or `worker` for a local `grpc-v1` worker. Read the public native dynamic-plugin or gRPC worker guide before designing the package boundary. Do not reproduce native ABI or worker-protocol details from memory.

Native plugins are trusted C-ABI extensions that run in the Relay process and are not sandboxed. Worker plugins provide process isolation, not a security sandbox.

Embedded Component Model

• Plugins package reusable process-level behavior.
• A plugin exposes a stable `kind` string and receives component-local config

from a shared plugin document.

• Plugin config must be JSON-compatible across Rust, Python, Node.js, files,

tests, and deployment systems.

• Validation is deterministic and side-effect free. It inspects config and

returns structured diagnostics before runtime behavior changes.

• Registration runs after validation and installs real behavior through

`PluginContext`, such as subscribers, guardrails, request intercepts, execution intercepts, or stream execution intercepts.

• `PluginContext` gives the plugin system enough ownership to qualify runtime

names and roll back partial setup when activation fails.

• Disabled components should still validate when possible so operators can find

config problems before rollout.

Default Path

1. Decide whether a plugin is actually needed. Prefer direct instrumentation or scope-local behavior when the use case is not reusable process-level behavior. 2. Choose an embedded component or a discoverable dynamic package. For a dynamic package, establish the manifest-backed native or worker boundary before implementing behavior. 3. For native dynamic plugins, determine the target Relay version from the package constraint, lockfile, or deployment target before choosing callback APIs. 4. Pick one first runtime surface: subscriber-oriented export, sanitize guardrail, conditional guardrail, request intercept, execution intercept, or stream execution intercept. 5. Choose a stable plugin `kind` and the smallest JSON-compatible config shape. 6. Define diagnostics for missing fields, unsupported values, unknown fields, unsafe config, and invalid field combinations. 7. Validate config before initialization. Validation must not open network connections, create clients, register middleware, or mutate process state. 8. If validation returns error diagnostics, return them and stop without initialization or registration. 9. Register runtime behavior through `PluginContext`, not by hand-registering global behavior inside application startup. 10. Test activation, disabled components, validation failures, and registration failure rollback. 11. Document how to enable the plugin, what config fields are supported, and how to roll back the component. 12. For a dynamic plugin that should provide structured fields in `nemo-relay plugins edit`, declare the `config_schema` capability and reference a local Draft 7 or Draft 2020-12 JSON Schema file from `[config_schema].path` in `relay-plugin.toml`. Schema-less plugins remain editable as raw JSON objects.

Config Shape

The top-level plugin document contains `version`, `components`, and `policy`. Each component supplies the plugin `kind`, `enabled`, and component-local `config`:

{
  "version": 1,
  "components": [
    {
      "kind": "redaction-policy",
      "enabled": true,
      "config": {
        "preset": "strict"
      }
    }
  ],
  "policy": {
    "unknown_component": "warn",
    "unknown_field": "warn",
    "unsupported_value": "error"
  }
}

Keep business logic in plugin code, not in config. Use references to secrets or endpoints rather than embedding sensitive values.

Binding Pointers

• Python: `nemo_relay.plugin`
• Node.js: `nemo-relay-node/plugin`
• Rust: `nemo_relay::plugin`
• Go and raw FFI are source-first or advanced surfaces.

Use the same canonical `snake_case` config keys across b