[Enhancement]: add an optional neutral inspection adapter surface for OpenShell interoperability

[afourniernv]

[Enhancement]: add an optional neutral inspection adapter surface for OpenShell interoperability

Related references:

• OpenShell RFC 0005 PR: https://github.com/NVIDIA/OpenShell/pull/1738
• Companion OpenShell RFC PR: https://github.com/NVIDIA/OpenShell/pull/1930

Affected area

• Rust core runtime
• Middleware or guardrails
• Plugins
• Observability or exporters

Problem or opportunity

NeMo Relay and OpenShell overlap around request inspection, mutation, and denial, but they operate at different layers.

NeMo Relay already owns semantic managed execution for LLM and tool calls through request intercepts, conditional execution guardrails, sanitize request/response guardrails, and execution intercepts. OpenShell instead owns the sandbox runtime boundary, protocol relay path, network policy, and pre-credential outbound request path.

OpenShell RFC 0005 proposes an OpenShell-owned egress middleware subsystem. That may make sense for OpenShell, but it assumes OpenShell should also own the middleware contract, registration model, and control-plane configuration surface.

There is an opportunity to support a looser integration shape instead:

• keep NeMo Relay responsible for semantic request inspection and guardrail logic
• let OpenShell expose a narrow runtime enforcement seam at the sandbox boundary
• avoid making Relay an OpenShell plugin or adding a direct SDK dependency in either direction

This matters because Relay already has the semantic surfaces that OpenShell does not, and OpenShell already has the sandbox-boundary enforcement point that Relay does not. A loose adapter boundary could let each system contribute at its natural layer without forcing either repo to absorb the other's architecture.

Proposed enhancement

Investigate and prototype an optional Relay-side adapter that can map existing Relay interception surfaces into a small neutral inspection contract suitable for external runtime-boundary enforcement systems such as OpenShell.

The core boundary should be:

• Relay owns semantic LLM and tool inspection
• Relay does not own OpenShell proxy enforcement
• Relay does not become an OpenShell plugin
• Relay does not take a hard dependency on OpenShell

The likely Relay-side adapter points are:

• crates/core/src/api/llm.rs
  • llm_request_intercepts
• crates/core/src/api/tool.rs
  • tool_request_intercepts
• crates/core/src/api/shared.rs
  • request-intercept execution with codec handling
• crates/core/src/plugin.rs
  • optional plugin/registration context for installing the adapter

The minimum decision model should stay narrow:

• target
• context
• findings
• allow | deny | mutate

The adapter should be thin. It should map existing Relay-managed semantic request shapes into that contract rather than introducing a second semantic policy engine inside Relay.

This issue is intentionally scoped as a Relay-side enhancement proposal, not as an attempt to implement OpenShell RFC 0005 from the Relay repo.

Runtime contract and binding impact

Relay runtime behavior should remain the source of truth.

Expected contract impact:

• Rust core gains an optional adapter surface that can be installed without changing the default managed execution path.
• Python and Node.js should not require new semantics in phase 1, but any public plugin or adapter surface eventually exposed there should preserve the same request/decision model.
• Existing request intercepts, guardrails, and execution intercepts must retain current ordering and behavior.
• The enhancement should not introduce a mandatory OpenShell-aware dependency or configuration requirement into any binding.

The existing managed execution model remains intact:

• conditional guardrails
• request intercepts
• sanitize-request guardrails for start events
• execution intercepts
• callback execution
• sanitize-response guardrails for end events

The adapter should only reuse that model, not redefine it.

Alternatives considered

Implement OpenShell RFC 0005 assumptions directly in Relay

This would incorrectly center the design around an OpenShell-owned middleware framework and risks forcing Relay to conform to an external control-plane model that it does not own.

Make Relay a plugin inside OpenShell

This would create tight product coupling and blur ownership boundaries. Relay already has its own plugin/runtime model and should remain independently useful.

Keep everything application-only inside Relay

This is the cleanest option if application-managed enforcement is enough. It gives up the chance to participate in an independent sandbox-boundary enforcement point when operators want runtime defense in depth.

Build a broad neutral framework immediately

This would be too early. The better path is to prove a thin adapter shape first and only generalize after repeated use across more than one integration.

Acceptance criteria

• The issue clearly states that Relay should not take a direct dependency on OpenShell.
• The issue documents the concrete Relay seams that a thin adapter would target.
• The issue references the companion OpenShell RFC and RFC 0005 as relevant context.
• The proposal preserves Relay's existing managed execution ordering and semantics.
• The proposal defines a minimum viable neutral decision vocabulary instead of a broad new framework.
• The proposal explicitly leaves platform wiring and inspector implementation outside both SDKs.