steerable-agent-runtime-native 0.6.32__tar.gz → 0.6.33__tar.gz

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/Cargo.lock

@@ -955,7 +955,7 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "steerable-agent-runtime"
-version = "0.6.32"
+version = "0.6.33"
 dependencies = [
  "async-stream",
  "async-trait",

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "steerable-agent-runtime"
-version = "0.6.32"
+version = "0.6.33"
 edition = "2021"
 description = "Steerable CoreLoop in Rust: think → act → observe, yielding LoopEvents."
 license = "MIT"

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/PKG-INFO

@@ -1,5 +1,5 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime-native
-Version: 0.6.32
+Version: 0.6.33
 Summary: PyO3 bindings for the Rust CoreLoop.
 Requires-Python: >=3.10

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "steerable-agent-runtime-native"
-version = "0.6.32"
+version = "0.6.33"
 description = "PyO3 bindings for the Rust CoreLoop."
 requires-python = ">=3.10"
 

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/src/engine.rs

@@ -387,60 +387,79 @@ impl<P: LLMProvider, E: ToolExecutor, H: LoopHooks> CoreLoop<P, E, H> {
                 }
             }
 
-            let step_tool_choice;
-            match self.hooks.pre_step(&history).await {
-                PreStepOutcome::Reject { reason } => {
-                    emit(completion_event(
-                        round_index,
-                        "stop",
-                        "",
-                        &[],
-                        ctx.consecutive_tool_errors,
-                        "failed",
-                        reason,
-                        1.0,
-                        &ctx,
-                    ));
-                    break;
-                }
-                PreStepOutcome::Proceed {
-                    appends,
-                    rewrite,
-                    reason,
-                    action,
-                    pre_tokens,
-                    post_tokens,
-                    tool_choice,
-                } => {
-                    if let Some(replacement) = rewrite {
-                        history = replacement;
-                        emit(LoopEvent::new(
-                            "hook_action",
-                            json!({
-                                "hook": "pre_step",
-                                "action": action.clone(),
-                                "reason": reason.clone(),
-                                "round": round_index,
-                                "pre_tokens": pre_tokens,
-                                "post_tokens": post_tokens,
-                            }),
+            let (step_tool_choice, step_tool_choice_honored) =
+                match self.hooks.pre_step(&history).await {
+                    PreStepOutcome::Reject { reason } => {
+                        emit(completion_event(
+                            round_index,
+                            "stop",
+                            "",
+                            &[],
+                            ctx.consecutive_tool_errors,
+                            "failed",
+                            reason,
+                            1.0,
+                            &ctx,
                         ));
+                        break;
                     }
-                    for message in appends {
-                        history.push(message);
-                        emit(LoopEvent::new(
-                            "hook_action",
-                            json!({
-                                "hook": "pre_step",
-                                "action": action.clone(),
-                                "reason": reason.clone(),
-                                "round": round_index,
-                            }),
-                        ));
+                    PreStepOutcome::Proceed {
+                        appends,
+                        rewrite,
+                        reason,
+                        action,
+                        pre_tokens,
+                        post_tokens,
+                        tool_choice,
+                        tool_choice_honored,
+                        notes,
+                    } => {
+                        if let Some(replacement) = rewrite {
+                            history = replacement;
+                            emit(LoopEvent::new(
+                                "hook_action",
+                                json!({
+                                    "hook": "pre_step",
+                                    "action": action.clone(),
+                                    "reason": reason.clone(),
+                                    "round": round_index,
+                                    "pre_tokens": pre_tokens,
+                                    "post_tokens": post_tokens,
+                                }),
+                            ));
+                        }
+                        for message in appends {
+                            history.push(message);
+                            emit(LoopEvent::new(
+                                "hook_action",
+                                json!({
+                                    "hook": "pre_step",
+                                    "action": action.clone(),
+                                    "reason": reason.clone(),
+                                    "round": round_index,
+                                }),
+                            ));
+                        }
+                        // Verdicts that took no action. Without these a trace
+                        // shows only the rounds a hook intervened in, which is a
+                        // numerator with no denominator — "routing allowed a
+                        // no-tool turn" and "routing never ran" look identical.
+                        for note in notes {
+                            emit(LoopEvent::new(
+                                "hook_action",
+                                json!({
+                                    "hook": "pre_step",
+                                    "action": note.action,
+                                    "reason": note.reason,
+                                    "value": note.value,
+                                    "probability": note.probability,
+                                    "round": round_index,
+                                }),
+                            ));
+                        }
+                        (tool_choice, tool_choice_honored)
                     }
-                    step_tool_choice = tool_choice;
-                }
-            }
+                };
 
             if let Some(tool_choice) = &step_tool_choice {
                 emit(LoopEvent::new(
@@ -448,7 +467,12 @@ impl<P: LLMProvider, E: ToolExecutor, H: LoopHooks> CoreLoop<P, E, H> {
                     json!({
                         "hook": "pre_step",
                         "action": "tool_choice",
-                        "toolChoice": tool_choice,
+                        "value": tool_choice,
+                        // Several vendors downgrade `required` to `auto` on the
+                        // wire. Logging the hook without this reads as a gate
+                        // that held, so measurements over forced turns
+                        // silently mix the models where the gate is a no-op.
+                        "honored": step_tool_choice_honored.unwrap_or(true),
                         "round": round_index,
                     }),
                 ));

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/src/hooks.rs

@@ -21,6 +21,22 @@ pub enum HookAction {
     Narrate { message: String, reason: String },
 }
 
+/// A hook verdict the engine records even though it changed nothing about the
+/// step.
+///
+/// Verdicts that act are already visible as `hook_action` (a rewrite, an
+/// append, a `tool_choice`). The verdict that declined to act leaves no trace,
+/// so a trajectory cannot distinguish "the data-need router allowed a no-tool
+/// turn" from "routing never ran" — the denominator a routing-variance
+/// measurement needs.
+#[derive(Clone, Debug, PartialEq)]
+pub struct DecisionNote {
+    pub action: String,
+    pub reason: String,
+    pub value: Option<String>,
+    pub probability: Option<f64>,
+}
+
 #[derive(Clone, Debug, PartialEq)]
 pub enum PreStepOutcome {
     Proceed {
@@ -31,6 +47,11 @@ pub enum PreStepOutcome {
         pre_tokens: Option<i64>,
         post_tokens: Option<i64>,
         tool_choice: Option<String>,
+        /// Whether `tool_choice` survives to the wire, when the hook's host
+        /// could answer. `None` means unknown and is recorded as honored:
+        /// only the provider adapter knows about vendor downgrades.
+        tool_choice_honored: Option<bool>,
+        notes: Vec<DecisionNote>,
     },
     Reject {
         reason: String,
@@ -59,6 +80,8 @@ impl Default for PreStepOutcome {
             pre_tokens: None,
             post_tokens: None,
             tool_choice: None,
+            tool_choice_honored: None,
+            notes: Vec::new(),
         }
     }
 }

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/src/lib.rs

@@ -52,7 +52,8 @@ pub use gemini_wire::{
     encode_gemini_contents, parse_gemini_chunk, parse_gemini_usage, GoogleGenAIProvider,
 };
 pub use hooks::{
-    CompletionDraft, HookAction, LoopHooks, NoopHooks, PreStepOutcome, RequestErrorAction,
+    CompletionDraft, DecisionNote, HookAction, LoopHooks, NoopHooks, PreStepOutcome,
+    RequestErrorAction,
 };
 pub use model_resolve::{
     catalog_provider_for_base_url, describe_catalog_providers, resolve_in_catalog,

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/src/python.rs

@@ -10,7 +10,9 @@ use serde_json::Value;
 use crate::engine::{CoreLoop, LoopConfig, RoundControl};
 use crate::errors::{LLMError, LLMErrorKind};
 use crate::executor::ToolExecutor;
-use crate::hooks::{CompletionDraft, HookAction, LoopHooks, PreStepOutcome, RequestErrorAction};
+use crate::hooks::{
+    CompletionDraft, DecisionNote, HookAction, LoopHooks, PreStepOutcome, RequestErrorAction,
+};
 use crate::provider::{LLMChunkStream, LLMProvider};
 use crate::types::{LLMMessage, LoopContext, LoopEvent, ToolCall, ToolResult};
 use crate::wire::{
@@ -25,6 +27,33 @@ struct CallbackProvider {
     next_stream_chunk: Py<PyAny>,
 }
 
+/// Decode the pre_step payload's `notes`. A malformed entry is skipped rather
+/// than failing the step: these describe a decision that already happened, so
+/// losing one costs a trace line and nothing else.
+fn decision_notes_from_value(raw: Option<&Value>) -> Vec<DecisionNote> {
+    let Some(items) = raw.and_then(Value::as_array) else {
+        return Vec::new();
+    };
+    items
+        .iter()
+        .filter_map(|item| {
+            Some(DecisionNote {
+                action: item.get("action").and_then(Value::as_str)?.to_string(),
+                reason: item
+                    .get("reason")
+                    .and_then(Value::as_str)
+                    .unwrap_or_default()
+                    .to_string(),
+                value: item
+                    .get("value")
+                    .and_then(Value::as_str)
+                    .map(str::to_string),
+                probability: item.get("probability").and_then(Value::as_f64),
+            })
+        })
+        .collect()
+}
+
 fn callback_llm_error(value: &Value, default_message: &str) -> LLMError {
     let kind = match value
         .get("error_kind")
@@ -335,6 +364,8 @@ impl LoopHooks for CallbackHooks {
                 .get("tool_choice")
                 .and_then(Value::as_str)
                 .map(str::to_string),
+            tool_choice_honored: value.get("tool_choice_honored").and_then(Value::as_bool),
+            notes: decision_notes_from_value(value.get("notes")),
         }
     }
 

{steerable_agent_runtime_native-0.6.32 → steerable_agent_runtime_native-0.6.33}/tests/test_loop.rs

@@ -4,10 +4,11 @@ use async_trait::async_trait;
 use pretty_assertions::assert_eq;
 use serde_json::{json, Value};
 use steerable_agent_runtime::{
-    chunk_stream, BudgetLimit, CompletionDraft, ContentPart, CoreLoop, HookAction, LLMChunkStream,
-    LLMError, LLMErrorKind, LLMMessage, LLMProvider, LLMStreamChunk, LLMUsage, LoopConfig,
-    LoopContext, LoopEvent, LoopHooks, RequestErrorAction, RoundControl, RouterToolExecutor,
-    ScriptedProvider, ScriptedTurn, ToolCall, ToolExecutor, ToolResult, ToolRouter,
+    chunk_stream, BudgetLimit, CompletionDraft, ContentPart, CoreLoop, DecisionNote, HookAction,
+    LLMChunkStream, LLMError, LLMErrorKind, LLMMessage, LLMProvider, LLMStreamChunk, LLMUsage,
+    LoopConfig, LoopContext, LoopEvent, LoopHooks, PreStepOutcome, RequestErrorAction,
+    RoundControl, RouterToolExecutor, ScriptedProvider, ScriptedTurn, ToolCall, ToolExecutor,
+    ToolResult, ToolRouter,
 };
 
 fn provider(scripts: Vec<ScriptedTurn>) -> ScriptedProvider {
@@ -930,6 +931,88 @@ async fn test_dedup_ignores_argument_key_order_and_carries_guidance() {
         .contains("do not repeat the same call"));
 }
 
+struct RouteVerdict {
+    verdict: &'static str,
+    honored: Option<bool>,
+}
+
+#[async_trait]
+impl LoopHooks for RouteVerdict {
+    async fn pre_step(&self, _transcript: &[LLMMessage]) -> PreStepOutcome {
+        let forcing = self.verdict == "require_tool";
+        PreStepOutcome::Proceed {
+            appends: Vec::new(),
+            rewrite: None,
+            reason: None,
+            action: "append".into(),
+            pre_tokens: None,
+            post_tokens: None,
+            tool_choice: forcing.then(|| "required".to_string()),
+            tool_choice_honored: self.honored,
+            notes: vec![DecisionNote {
+                action: "data_need_route".into(),
+                reason: "anti-hallucination data-need routing".into(),
+                value: Some(self.verdict.into()),
+                probability: None,
+            }],
+        }
+    }
+}
+
+#[tokio::test]
+async fn test_pre_step_notes_record_a_verdict_that_changed_nothing() {
+    let mut agent = CoreLoop::new(
+        provider(vec![text_turn("boiling point is 100C")]),
+        RouterToolExecutor::new(ToolRouter::new()),
+    )
+    .with_hooks(RouteVerdict {
+        verdict: "allow_no_tool",
+        honored: None,
+    });
+
+    let events = agent
+        .run(vec![LLMMessage::text("user", "boiling point?")])
+        .await;
+
+    let note = events
+        .iter()
+        .find(|event| event.kind == "hook_action" && event.data["action"] == "data_need_route")
+        .expect("a verdict that took no action must still be recorded");
+    assert_eq!(note.data["value"], json!("allow_no_tool"));
+    assert_eq!(note.data["hook"], json!("pre_step"));
+    // Nothing was forced, so there is no tool_choice event to confuse it with.
+    assert!(!events
+        .iter()
+        .any(|event| event.kind == "hook_action" && event.data["action"] == "tool_choice"));
+}
+
+#[tokio::test]
+async fn test_tool_choice_event_reports_a_vendor_downgrade() {
+    let mut router = ToolRouter::new();
+    router.register("get_data", |_| async {
+        Ok(ToolResult::ok(json!({ "value": 42 })))
+    });
+    let mut agent = CoreLoop::new(
+        provider(vec![text_turn("42")]),
+        RouterToolExecutor::new(router),
+    )
+    .with_hooks(RouteVerdict {
+        verdict: "require_tool",
+        honored: Some(false),
+    });
+
+    let events = agent.run(vec![LLMMessage::text("user", "fetch it")]).await;
+
+    let forced = events
+        .iter()
+        .find(|event| event.kind == "hook_action" && event.data["action"] == "tool_choice")
+        .expect("a forced step must record its gate");
+    assert_eq!(forced.data["value"], json!("required"));
+    // The gate never reached the wire; recording it as honored would make every
+    // measurement over forced turns silently mix in models that ignore it.
+    assert_eq!(forced.data["honored"], json!(false));
+}
+
 struct NarrateOnFailure;
 
 #[async_trait]