Add guardrail scope emission

Author: yczhang-nv

crates/core/src/api/llm.rs

@@ -523,11 +523,19 @@ pub async fn llm_call_execute(params: LlmCallExecuteParams) -> Result<Json> {
         let scope_locals = scope_guard.collect_scope_local_registries(|registries| {
             &registries.llm_conditional_execution_guardrails
         });
+        let scope_subscribers = scope_guard.collect_scope_local_subscribers();
         let context = global_context();
         let state = context
             .read()
             .map_err(|error| FlowError::Internal(error.to_string()))?;
-        if let Some(error) = state.llm_conditional_execution_chain(&request, &scope_locals)? {
+        let subscribers = state.collect_event_subscribers(&scope_subscribers);
+        if let Some(error) = state.llm_conditional_execution_chain(
+            &request,
+            &scope_locals,
+            &subscribers,
+            resolve_parent_uuid(parent.as_ref()),
+            metadata.clone(),
+        )? {
             drop(state);
             drop(scope_guard);
             let mut rejection_data = json!({});
@@ -680,11 +688,19 @@ pub async fn llm_stream_call_execute(params: LlmStreamCallExecuteParams) -> Resu
         let scope_locals = scope_guard.collect_scope_local_registries(|registries| {
             &registries.llm_conditional_execution_guardrails
         });
+        let scope_subscribers = scope_guard.collect_scope_local_subscribers();
         let context = global_context();
         let state = context
             .read()
             .map_err(|error| FlowError::Internal(error.to_string()))?;
-        if let Some(error) = state.llm_conditional_execution_chain(&request, &scope_locals)? {
+        let subscribers = state.collect_event_subscribers(&scope_subscribers);
+        if let Some(error) = state.llm_conditional_execution_chain(
+            &request,
+            &scope_locals,
+            &subscribers,
+            resolve_parent_uuid(parent.as_ref()),
+            metadata.clone(),
+        )? {
             drop(state);
             drop(scope_guard);
             let mut rejection_data = json!({});
@@ -814,7 +830,8 @@ pub fn llm_request_intercepts(name: &str, request: LlmRequest) -> Result<LlmRequ
 /// Run only the LLM conditional-execution guardrail chain.
 ///
 /// This evaluates whether an LLM call should be allowed to proceed without
-/// emitting lifecycle events or invoking request intercepts or execution.
+/// invoking request intercepts or execution. Each evaluated guardrail emits an
+/// automatic guardrail scope start/end pair for observability.
 ///
 /// # Parameters
 /// - `request`: Raw [`LlmRequest`] to validate.
@@ -828,19 +845,28 @@ pub fn llm_request_intercepts(name: &str, request: LlmRequest) -> Result<LlmRequ
 ///
 /// # Notes
 /// This helper is useful for preflight checks when the caller needs the
-/// rejection result without starting an LLM span.
+/// rejection result without starting an LLM span. Guardrail scopes are still
+/// emitted for the conditional checks themselves.
 pub fn llm_conditional_execution(request: &LlmRequest) -> Result<()> {
     ensure_runtime_owner()?;
     let scope_stack = current_scope_stack();
     let scope_guard = scope_stack.read().expect("scope stack lock poisoned");
     let scope_locals = scope_guard.collect_scope_local_registries(|registries| {
         &registries.llm_conditional_execution_guardrails
     });
+    let scope_subscribers = scope_guard.collect_scope_local_subscribers();
     let context = global_context();
     let state = context
         .read()
         .map_err(|error| FlowError::Internal(error.to_string()))?;
-    if let Some(error) = state.llm_conditional_execution_chain(request, &scope_locals)? {
+    let subscribers = state.collect_event_subscribers(&scope_subscribers);
+    if let Some(error) = state.llm_conditional_execution_chain(
+        request,
+        &scope_locals,
+        &subscribers,
+        resolve_parent_uuid(None),
+        None,
+    )? {
         return Err(FlowError::GuardrailRejected(error));
     }
     Ok(())

crates/core/src/api/registry.rs

@@ -33,6 +33,8 @@ pub struct ExecutionIntercept<F> {
 
 /// A priority-ordered guardrail registration entry.
 pub struct GuardrailEntry<F> {
+    /// Caller-provided guardrail registration name.
+    pub name: String,
     /// Lower values run earlier in the chain.
     pub priority: i32,
     /// The caller-provided guardrail callback.
@@ -69,7 +71,14 @@ macro_rules! global_guardrail_registry_api {
                 .map_err(|error| FlowError::Internal(error.to_string()))?;
             state
                 .$field
-                .register(name.to_string(), GuardrailEntry { priority, guardrail })
+                .register(
+                    name.to_string(),
+                    GuardrailEntry {
+                        name: name.to_string(),
+                        priority,
+                        guardrail,
+                    },
+                )
                 .map_err(FlowError::AlreadyExists)
         }
 
@@ -259,7 +268,14 @@ macro_rules! scope_guardrail_registry_api {
                 .ok_or_else(|| FlowError::NotFound(format!("scope {scope_uuid} not found")))?;
             registries
                 .$field
-                .register(name.to_string(), GuardrailEntry { priority, guardrail })
+                .register(
+                    name.to_string(),
+                    GuardrailEntry {
+                        name: name.to_string(),
+                        priority,
+                        guardrail,
+                    },
+                )
                 .map_err(FlowError::AlreadyExists)
         }
 

crates/core/src/api/runtime/state.rs

@@ -25,7 +25,7 @@ use crate::api::runtime::callbacks::{
     LlmStreamExecutionRegistryRefs, ToolConditionalFn, ToolExecutionFn, ToolExecutionNextFn,
     ToolInterceptFn, ToolSanitizeFn,
 };
-use crate::api::scope::{CreateScopeHandleParams, EndScopeHandleParams, ScopeHandle};
+use crate::api::scope::{CreateScopeHandleParams, EndScopeHandleParams, ScopeHandle, ScopeType};
 use crate::api::tool::ToolHandle;
 use crate::api::tool::{CreateToolHandleParams, EndToolHandleParams};
 use crate::codec::request::AnnotatedLlmRequest;
@@ -36,6 +36,8 @@ use crate::context::registries::{
 use crate::json::{Json, merge_json};
 use crate::registry::SortedRegistry;
 use chrono::{Duration, Utc};
+use serde_json::json;
+use uuid::Uuid;
 
 /// Process-global runtime state backing middleware and event emission.
 ///
@@ -527,6 +529,42 @@ impl NemoFlowContextState {
         ))
     }
 
+    fn emit_guardrail_scope_start(
+        &self,
+        name: &str,
+        parent_uuid: Option<Uuid>,
+        metadata: Option<Json>,
+        input: Json,
+        subscribers: &[EventSubscriberFn],
+    ) -> ScopeHandle {
+        let handle = self.create_scope_handle(
+            CreateScopeHandleParams::builder()
+                .name(name)
+                .parent_uuid_opt(parent_uuid)
+                .scope_type(ScopeType::Guardrail)
+                .metadata_opt(metadata)
+                .build(),
+        );
+        let event = self.build_scope_start_event(&handle, Some(input));
+        Self::emit_event(&event, subscribers);
+        handle
+    }
+
+    fn emit_guardrail_scope_end(
+        &self,
+        handle: &ScopeHandle,
+        output: Json,
+        subscribers: &[EventSubscriberFn],
+    ) {
+        let event = self.build_scope_end_event(
+            EndScopeHandleParams::builder()
+                .handle(handle)
+                .data(output)
+                .build(),
+        );
+        Self::emit_event(&event, subscribers);
+    }
+
     /// Run tool request sanitizers across global and scope-local registries.
     ///
     /// # Parameters
@@ -595,11 +633,42 @@ impl NemoFlowContextState {
         name: &str,
         args: &Json,
         scope_locals: &[&SortedRegistry<GuardrailEntry<ToolConditionalFn>>],
+        subscribers: &[EventSubscriberFn],
+        parent_uuid: Option<Uuid>,
+        metadata: Option<Json>,
     ) -> crate::error::Result<Option<String>> {
         let entries =
             merge_guardrail_entries(&self.tool_conditional_execution_guardrails, scope_locals);
         for entry in entries {
-            if let Some(error) = (entry.guardrail)(name, args)? {
+            let handle = self.emit_guardrail_scope_start(
+                &entry.name,
+                parent_uuid,
+                metadata.clone(),
+                json!({
+                    "kind": "tool_conditional_execution",
+                    "target_name": name,
+                    "input": args,
+                }),
+                subscribers,
+            );
+            let result = (entry.guardrail)(name, args);
+            let output = match &result {
+                Ok(Some(reason)) => json!({
+                    "allowed": false,
+                    "rejected": true,
+                    "rejection_reason": reason,
+                }),
+                Ok(None) => json!({
+                    "allowed": true,
+                    "rejected": false,
+                }),
+                Err(error) => json!({
+                    "allowed": false,
+                    "error": error.to_string(),
+                }),
+            };
+            self.emit_guardrail_scope_end(&handle, output, subscribers);
+            if let Some(error) = result? {
                 return Ok(Some(error));
             }
         }
@@ -730,11 +799,41 @@ impl NemoFlowContextState {
         &self,
         request: &LlmRequest,
         scope_locals: &[&SortedRegistry<GuardrailEntry<LlmConditionalFn>>],
+        subscribers: &[EventSubscriberFn],
+        parent_uuid: Option<Uuid>,
+        metadata: Option<Json>,
     ) -> crate::error::Result<Option<String>> {
         let entries =
             merge_guardrail_entries(&self.llm_conditional_execution_guardrails, scope_locals);
         for entry in entries {
-            if let Some(error) = (entry.guardrail)(request)? {
+            let handle = self.emit_guardrail_scope_start(
+                &entry.name,
+                parent_uuid,
+                metadata.clone(),
+                json!({
+                    "kind": "llm_conditional_execution",
+                    "input": request,
+                }),
+                subscribers,
+            );
+            let result = (entry.guardrail)(request);
+            let output = match &result {
+                Ok(Some(reason)) => json!({
+                    "allowed": false,
+                    "rejected": true,
+                    "rejection_reason": reason,
+                }),
+                Ok(None) => json!({
+                    "allowed": true,
+                    "rejected": false,
+                }),
+                Err(error) => json!({
+                    "allowed": false,
+                    "error": error.to_string(),
+                }),
+            };
+            self.emit_guardrail_scope_end(&handle, output, subscribers);
+            if let Some(error) = result? {
                 return Ok(Some(error));
             }
         }

crates/core/src/api/tool.rs

@@ -368,11 +368,20 @@ pub async fn tool_call_execute(params: ToolCallExecuteParams) -> Result<Json> {
         let scope_locals = scope_guard.collect_scope_local_registries(|registries| {
             &registries.tool_conditional_execution_guardrails
         });
+        let scope_subscribers = scope_guard.collect_scope_local_subscribers();
         let context = global_context();
         let state = context
             .read()
             .map_err(|error| FlowError::Internal(error.to_string()))?;
-        if let Some(error) = state.tool_conditional_execution_chain(&name, &args, &scope_locals)? {
+        let subscribers = state.collect_event_subscribers(&scope_subscribers);
+        if let Some(error) = state.tool_conditional_execution_chain(
+            &name,
+            &args,
+            &scope_locals,
+            &subscribers,
+            resolve_parent_uuid(parent.as_ref()),
+            metadata.clone(),
+        )? {
             drop(state);
             drop(scope_guard);
             let mut rejection_data = json!({});
@@ -479,7 +488,8 @@ pub fn tool_request_intercepts(name: &str, args: Json) -> Result<Json> {
 /// Run only the tool conditional-execution guardrail chain.
 ///
 /// This evaluates whether a tool call should be allowed to proceed without
-/// emitting lifecycle events or invoking request intercepts or execution.
+/// invoking request intercepts or execution. Each evaluated guardrail emits an
+/// automatic guardrail scope start/end pair for observability.
 ///
 /// # Parameters
 /// - `name`: Tool name used when resolving the guardrail chain.
@@ -494,19 +504,29 @@ pub fn tool_request_intercepts(name: &str, args: Json) -> Result<Json> {
 ///
 /// # Notes
 /// This helper is useful for preflight checks when the caller needs the
-/// rejection result without starting a tool span.
+/// rejection result without starting a tool span. Guardrail scopes are still
+/// emitted for the conditional checks themselves.
 pub fn tool_conditional_execution(name: &str, args: &Json) -> Result<()> {
     ensure_runtime_owner()?;
     let scope_stack = current_scope_stack();
     let scope_guard = scope_stack.read().expect("scope stack lock poisoned");
     let scope_locals = scope_guard.collect_scope_local_registries(|registries| {
         &registries.tool_conditional_execution_guardrails
     });
+    let scope_subscribers = scope_guard.collect_scope_local_subscribers();
     let context = global_context();
     let state = context
         .read()
         .map_err(|error| FlowError::Internal(error.to_string()))?;
-    if let Some(error) = state.tool_conditional_execution_chain(name, args, &scope_locals)? {
+    let subscribers = state.collect_event_subscribers(&scope_subscribers);
+    if let Some(error) = state.tool_conditional_execution_chain(
+        name,
+        args,
+        &scope_locals,
+        &subscribers,
+        resolve_parent_uuid(None),
+        None,
+    )? {
         return Err(FlowError::GuardrailRejected(error));
     }
     Ok(())