Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

refactor(tokenjuice): remove unused focus and generate helpers

Steven Enamakel1e5c05e8ea16
diff --git a/crates/openhuman-core/src/inference/tokenjuice/focus.rs b/crates/openhuman-core/src/inference/tokenjuice/focus.rs
deleted file mode 100644
index 636669d56b..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/focus.rs
+++ /dev/null
@@ -1,35 +0,0 @@
-//! `summary_focus`: the argument a tool opts into so its caller can steer the
-//! summary of a large result.
-//!
-//! A tool opts in by adding [`summary_focus_property`] to its schema's
-//! `properties`. `ToolOutputMiddleware` takes the value out of the call in
-//! `before_tool` — before schema validation and before the tool runs, so the
-//! tool body never sees it — and hands it to TinyJuice with the result.
-
-use serde_json::Value;
-
-use tinyjuice_bus::tools::{summary_focus_property, SUMMARY_FOCUS_ARG};
-
-/// Whether a tool's parameter schema declares TinyJuice's `summary_focus`,
-/// as opposed to a parameter of its own that happens to share the name.
-pub fn declares_summary_focus(parameters: &Value) -> bool {
- parameters
- .get("properties")
- .and_then(|properties| properties.get(SUMMARY_FOCUS_ARG))
- == Some(&summary_focus_property())
-}
-
-/// Remove `summary_focus` from a call's arguments, returning it when it holds
-/// non-blank text.
-pub fn take_summary_focus(arguments: &mut Value) -> Option<String> {
- let removed = arguments.as_object_mut()?.remove(SUMMARY_FOCUS_ARG)?;
- removed
- .as_str()
- .map(str::trim)
- .filter(|focus| !focus.is_empty())
- .map(str::to_string)
-}
-
-#[cfg(test)]
-#[path = "focus_tests.rs"]
-mod tests;
diff --git a/crates/openhuman-core/src/inference/tokenjuice/focus_tests.rs b/crates/openhuman-core/src/inference/tokenjuice/focus_tests.rs
deleted file mode 100644
index 33180e7a1c..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/focus_tests.rs
+++ /dev/null
@@ -1,66 +0,0 @@
-use super::*;
-use serde_json::json;
-
-#[test]
-fn the_focus_is_taken_out_of_the_arguments() {
- let mut args = json!({ "url": "https://example.com", "summary_focus": " the pricing " });
- assert_eq!(
- take_summary_focus(&mut args).as_deref(),
- Some("the pricing")
- );
- assert_eq!(args, json!({ "url": "https://example.com" }));
-}
-
-#[test]
-fn a_blank_or_non_string_focus_is_dropped_and_still_removed() {
- for value in [json!(" "), json!(42), json!(null)] {
- let mut args = json!({ "url": "u", "summary_focus": value });
- assert_eq!(take_summary_focus(&mut args), None);
- assert_eq!(args, json!({ "url": "u" }));
- }
-}
-
-#[test]
-fn arguments_without_a_focus_are_untouched() {
- let mut args = json!({ "url": "u" });
- assert_eq!(take_summary_focus(&mut args), None);
- assert_eq!(args, json!({ "url": "u" }));
- let mut not_an_object = json!("raw");
- assert_eq!(take_summary_focus(&mut not_an_object), None);
-}
-
-#[test]
-fn the_property_is_an_optional_string() {
- let property = summary_focus_property();
- assert_eq!(property["type"], "string");
- assert!(property["description"]
- .as_str()
- .unwrap()
- .contains("summarized"));
-}
-
-#[test]
-fn only_the_shared_property_counts_as_declaring_the_focus() {
- let declared =
- json!({ "properties": { "url": {}, "summary_focus": summary_focus_property() } });
- assert!(declares_summary_focus(&declared));
-
- let own_parameter = json!({ "properties": { "summary_focus": { "type": "integer" } } });
- assert!(!declares_summary_focus(&own_parameter));
- assert!(!declares_summary_focus(
- &json!({ "properties": { "url": {} } })
- ));
- assert!(!declares_summary_focus(&json!({})));
-}
-
-#[test]
-fn the_property_schema_is_pinned_literally() {
- assert_eq!(
- summary_focus_property(),
- json!({
- "type": "string",
- "description": "What you need from this result. A large result is summarized around this; the full output stays retrievable."
- })
- );
- assert_eq!(SUMMARY_FOCUS_ARG, "summary_focus");
-}
diff --git a/crates/openhuman-core/src/inference/tokenjuice/generate.rs b/crates/openhuman-core/src/inference/tokenjuice/generate.rs
deleted file mode 100644
index 9a001547a9..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/generate.rs
+++ /dev/null
@@ -1,99 +0,0 @@
-//! OpenHuman's turn-bound callbacks for the TinyJuice module's `MlHost.Generate`.
-//!
-//! TinyJuice writes the summary prompt and decides when one is worth writing;
-//! the model call is ours, because only the host knows which model the turn
-//! runs on, and the call must inherit that turn's cancellation, thread and
-//! lineage. None of that crosses the bus, and task-local state does not cross
-//! a module boundary either, so the turn is passed by reference instead:
-//!
-//! 1. before `CompactWith`, the caller [`register`]s a [`PreparedGenerate`] —
-//! a closure already bound to its turn — and sends the returned ticket's
-//! token as `context_token`;
-//! 2. if the module asks for a summary, `MlHost.Generate` arrives with that
-//! token and [`serve`] runs the closure;
-//! 3. the ticket removes the entry when dropped, whether or not it was used.
-//!
-//! An unknown token (expired, never registered, or already used) is a decline,
-//! not an error: the module then falls back to its deterministic compressors.
-
-use std::collections::HashMap;
-use std::future::Future;
-use std::pin::Pin;
-use std::sync::{LazyLock, Mutex};
-
-use tinyjuice_bus::wire::GenerateRequest;
-
-/// One model call, bound to the turn that will pay for it.
-pub type PreparedGenerate = Box<
- dyn FnOnce(GenerateRequest) -> Pin<Box<dyn Future<Output = anyhow::Result<String>> + Send>>
- + Send,
->;
-
-static PENDING: LazyLock<Mutex<HashMap<String, PreparedGenerate>>> =
- LazyLock::new(Default::default);
-
-/// Holds one registered call. Dropping it withdraws the call.
-#[must_use = "dropping the ticket withdraws the registered call"]
-pub struct GenerateTicket {
- token: String,
-}
-
-impl GenerateTicket {
- /// The value to send as `CompactRequest::context_token`.
- pub fn token(&self) -> &str {
- &self.token
- }
-}
-
-impl Drop for GenerateTicket {
- fn drop(&mut self) {
- if let Ok(mut pending) = PENDING.lock() {
- pending.remove(&self.token);
- }
- }
-}
-
-/// Register a call and get the ticket that names it.
-pub fn register(prepared: PreparedGenerate) -> GenerateTicket {
- let token = uuid::Uuid::new_v4().to_string();
- if let Ok(mut pending) = PENDING.lock() {
- pending.insert(token.clone(), prepared);
- }
- log::debug!("[tokenjuice::generate] registered context_token={token}");
- GenerateTicket { token }
-}
-
-/// Answer one `MlHost.Generate` call. `Ok(None)` declines.
-pub async fn serve(request: GenerateRequest) -> Result<Option<String>, String> {
- let token = request.context_token.clone();
- let prepared = PENDING.lock().ok().and_then(|mut p| p.remove(&token));
- let Some(prepared) = prepared else {
- log::debug!("[tokenjuice::generate] no registered call, declining context_token={token}");
- return Ok(None);
- };
- let prompt_bytes = request.prompt.len();
- let purpose = request.purpose.clone();
- let started = std::time::Instant::now();
- match prepared(request).await {
- Ok(text) => {
- log::info!(
- "[tokenjuice::generate] served context_token={token} purpose={purpose} \
- prompt_bytes={prompt_bytes} reply_bytes={} elapsed_ms={}",
- text.len(),
- started.elapsed().as_millis()
- );
- Ok(Some(text))
- }
- Err(error) => {
- log::warn!(
- "[tokenjuice::generate] model call failed context_token={token} purpose={purpose} \
- error={error}"
- );
- Err(error.to_string())
- }
- }
-}
-
-#[cfg(test)]
-#[path = "generate_tests.rs"]
-mod tests;
diff --git a/crates/openhuman-core/src/inference/tokenjuice/generate_tests.rs b/crates/openhuman-core/src/inference/tokenjuice/generate_tests.rs
deleted file mode 100644
index c6e30ba570..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/generate_tests.rs
+++ /dev/null
@@ -1,52 +0,0 @@
-use super::*;
-
-fn request(token: &str) -> GenerateRequest {
- GenerateRequest {
- context_token: token.to_string(),
- purpose: "tool_output_summary".into(),
- system: "system".into(),
- prompt: "prompt".into(),
- max_output_tokens: 16,
- }
-}
-
-#[tokio::test]
-async fn an_unknown_token_declines() {
- assert_eq!(serve(request("never-registered")).await, Ok(None));
-}
-
-#[tokio::test]
-async fn a_registered_call_runs_once_with_the_request() {
- let ticket = register(Box::new(|request: GenerateRequest| {
- Box::pin(async move { Ok(format!("{} / {}", request.system, request.prompt)) })
- }));
- let token = ticket.token().to_string();
- assert_eq!(
- serve(request(&token)).await,
- Ok(Some("system / prompt".to_string()))
- );
- // Used up: a second call for the same token declines.
- assert_eq!(serve(request(&token)).await, Ok(None));
-}
-
-#[tokio::test]
-async fn a_dropped_ticket_withdraws_its_call() {
- let ticket = register(Box::new(|_| {
- Box::pin(async { panic!("a withdrawn call must not run") })
- }));
- let token = ticket.token().to_string();
- drop(ticket);
- assert_eq!(serve(request(&token)).await, Ok(None));
-}
-
-#[tokio::test]
-async fn a_failed_model_call_is_an_error() {
- let ticket = register(Box::new(|_| {
- Box::pin(async { Err(anyhow::anyhow!("provider offline")) })
- }));
- let token = ticket.token().to_string();
- assert_eq!(
- serve(request(&token)).await,
- Err("provider offline".to_string())
- );
-}
diff --git a/crates/openhuman-core/src/inference/tokenjuice/mod.rs b/crates/openhuman-core/src/inference/tokenjuice/mod.rs
index 0bc44cd09a..9133612719 100644
--- a/crates/openhuman-core/src/inference/tokenjuice/mod.rs
+++ b/crates/openhuman-core/src/inference/tokenjuice/mod.rs
@@ -61,33 +61,12 @@ impl tinytools::Tool for TokenjuiceRetrieveTool {
use tinyjuice_bus::wire::InstallRequest;
-use tinyjuice_bus::tools::{LEGACY_RETRIEVE, REPL_TOOLS, RETRIEVE};
+use tinyjuice_bus::tools::REPL_TOOLS;
+pub use tinyjuice_host::recovery::{
+ is_recovery_tool, summary_failed_notice, CompactedToolOutput, RECOVERY_TOOL_NAMES,
+ RECOVERY_TOOL_VISIBLE,
+};
pub const LEGACY_RETRIEVE_TOOL_NAME: &str = "retrieve_tool_output";
-/// Every name the recovery surface answers to: the live tool plus the two
-/// migration aliases a replayed transcript may still call.
-pub const RECOVERY_TOOL_NAMES: &[&str] = &[
- RETRIEVE,
- LEGACY_RETRIEVE,
- "tokenjuice_retrieve",
- LEGACY_RETRIEVE_TOOL_NAME,
-];
-
-/// The recovery tool a curated (`ToolScope::Named`) belt is guaranteed to
-/// advertise. Only the live tool: the aliases stay registered so an old
-/// transcript replays, but putting all three on the wire charged every
-/// Named agent for three copies of one schema.
-pub const RECOVERY_TOOL_VISIBLE: &[&str] = &[RETRIEVE];
-
-pub fn is_recovery_tool(name: &str) -> bool {
- RECOVERY_TOOL_NAMES.contains(&name)
-}
-
-/// Build TinyJuice's retrieval adapter over the OpenHuman module lookup.
-pub fn retrieve_tool() -> TokenjuiceRetrieveTool {
- TokenjuiceRetrieveTool::new(std::sync::Arc::new(|token, range| {
- Box::pin(async move { retrieve(token, range).await })
- }))
-}
/// Whether the `[components] juice` switch is on. Off means turns truncate
/// tool output only: no compaction, no summary, no `juice_*` / recovery tools,
@@ -259,42 +238,6 @@ pub struct ToolOutputCompaction<'a> {
}
/// What came back for one tool result.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CompactedToolOutput {
- pub text: String,
- /// Prefix after the host's caps: the summary stage ran and wrote nothing.
- pub notice: Option<String>,
- /// Set when `text` is a model-written summary of this many bytes.
- pub summarized_from_bytes: Option<usize>,
-}
-
-impl CompactedToolOutput {
- fn unchanged(text: String) -> Self {
- Self {
- text,
- notice: None,
- summarized_from_bytes: None,
- }
- }
-
- /// The content untouched, disclosing the summary that did not happen when
- /// one was wanted.
- fn passthrough(text: String, wants_summary: bool) -> Self {
- Self {
- notice: wants_summary.then(summary_failed_notice),
- ..Self::unchanged(text)
- }
- }
-}
-
-/// TinyJuice's own notice for a summary that was attempted and not produced,
-/// so a host-side failure reads the same as a module-side one.
-pub fn summary_failed_notice() -> String {
- tinyjuice_bus::summary::UnavailableReason::Failed
- .notice()
- .to_string()
-}
-
/// Deadline for `CompactWith`. It may wait on a summary model call, which the
/// module itself bounds at 300s; this sits just past that so the module's own
/// timeout is the one that fires.
diff --git a/crates/openhuman-core/src/inference/tokenjuice/tools.rs b/crates/openhuman-core/src/inference/tokenjuice/tools.rs
deleted file mode 100644
index c9de658558..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/tools.rs
+++ /dev/null
@@ -1,146 +0,0 @@
-//! Agent tool: `juice_retrieve` — fetch the original of a compacted result.
-//!
-//! The content router may replace a large tool result with a compacted view and
-//! a `⟦tj:<hash>⟧` marker, stashing the original in the CCR store
-//! ([`crate::inference::tokenjuice::store`]). This tool hands the
-//! original back on demand — fully or by a byte/line range — so even lossy
-//! compaction stays reversible.
-//!
-//! Read-only, no side effects, no path/network access.
-
-use async_trait::async_trait;
-use serde_json::{json, Value};
-
-use tinytools::{PermissionLevel, Tool, ToolResult};
-use {tinyjuice_bus::wire::RangeUnit, tinyjuice_bus::wire::RetrieveRange};
-
-pub struct TokenjuiceRetrieveTool;
-
-impl TokenjuiceRetrieveTool {
- pub fn new() -> Self {
- Self
- }
-}
-
-impl Default for TokenjuiceRetrieveTool {
- fn default() -> Self {
- Self::new()
- }
-}
-
-#[async_trait]
-impl Tool for TokenjuiceRetrieveTool {
- fn name(&self) -> &str {
- tinyjuice_bus::tools::RETRIEVE
- }
-
- fn description(&self) -> &str {
- "Return the whole original of a compacted or stored tool output, or a `range` \
- of its lines or bytes. Pass the token its footer names (or the hash in a \
- `⟦tj:…⟧` marker). To read or search only part of it, use juice_find with \
- the same value as `handle` when that tool is offered."
- }
-
- fn parameters_schema(&self) -> Value {
- json!({
- "type": "object",
- "properties": {
- "token": {
- "type": "string",
- "description": "The token named in the output's footer (or a ⟦tj:…⟧ marker's hash)."
- },
- "range": {
- "type": "object",
- "description": "Optional slice of the original to return.",
- "properties": {
- "start": { "type": "integer", "minimum": 0 },
- "end": { "type": "integer", "minimum": 0 },
- "unit": { "type": "string", "enum": ["bytes", "lines"] }
- },
- "required": ["start", "end"]
- }
- },
- "required": ["token"]
- })
- }
-
- fn permission_level(&self) -> PermissionLevel {
- PermissionLevel::ReadOnly
- }
-
- async fn execute(&self, args: Value) -> anyhow::Result<ToolResult> {
- // Accept `token` (canonical) or `hash` (legacy arg name).
- let token = args
- .get("token")
- .or_else(|| args.get("hash"))
- .and_then(|v| v.as_str())
- .map(str::trim)
- .filter(|s| !s.is_empty());
- let Some(token) = token else {
- return Ok(ToolResult::error(format!(
- "{}: missing required 'token' argument",
- tinyjuice_bus::tools::RETRIEVE
- )));
- };
-
- // Optional range.
- if let Some(range) = args.get("range").filter(|v| v.is_object()) {
- let start = range.get("start").and_then(Value::as_u64).unwrap_or(0) as usize;
- let end = range.get("end").and_then(Value::as_u64).unwrap_or(u64::MAX) as usize;
- let unit = match range.get("unit").and_then(Value::as_str) {
- Some("bytes") => RangeUnit::Bytes,
- _ => RangeUnit::Lines,
- };
- return match super::retrieve(
- token.to_string(),
- Some(RetrieveRange { start, end, unit }),
- )
- .await
- {
- Ok(Some(slice)) => {
- log::debug!(
- "[tokenjuice][ccr] retrieved range token={token} {start}..{end} {} bytes",
- slice.len()
- );
- Ok(ToolResult::success(slice))
- }
- Ok(None) => Ok(ToolResult::error(miss_message(token))),
- Err(error) => Ok(ToolResult::error(error)),
- };
- }
-
- match super::retrieve(token.to_string(), None).await {
- Ok(Some(original)) => {
- log::debug!(
- "[tokenjuice][ccr] retrieved token={token} bytes={}",
- original.len()
- );
- Ok(ToolResult::success(original))
- }
- Ok(None) => Ok(ToolResult::error(miss_message(token))),
- Err(error) => Ok(ToolResult::error(error)),
- }
- }
-}
-
-fn miss_message(token: &str) -> String {
- // Deliberately does NOT say "re-run the tool". Re-running regenerates the
- // same oversized result, which is compacted and offloaded again under a new
- // token that can be evicted just as fast — so a blind re-run turns one cache
- // miss into an unbounded compact→retrieve→re-run loop (observed live: a
- // parent agent re-delegated forever on an evicted subagent result). Tell the
- // model to proceed with the compacted summary it already has instead.
- format!(
- "{tool}: the full original for token '{token}' is no longer cached \
- (evicted, or from an earlier session). Do NOT re-run the same tool call to \
- regenerate it — that will produce the same oversized result and be compacted \
- again. Proceed using the compacted summary already shown above; only if a \
- specific missing detail is essential, retry with narrower arguments (a tighter \
- query, filter, or smaller limit) so the result is small enough to keep in full.",
- tool = tinyjuice_bus::tools::RETRIEVE
- )
-}
-
-#[cfg(test)]
-#[path = "tools_tests.rs"]
-mod tests;
diff --git a/crates/openhuman-core/src/inference/tokenjuice/tools_tests.rs b/crates/openhuman-core/src/inference/tokenjuice/tools_tests.rs
deleted file mode 100644
index 5d6657a44a..0000000000
--- a/crates/openhuman-core/src/inference/tokenjuice/tools_tests.rs
+++ /dev/null
@@ -1,58 +0,0 @@
-use super::*;
-
-#[tokio::test]
-async fn missing_token_is_error() {
- let tool = TokenjuiceRetrieveTool::new();
- let res = tool
- .execute(json!({ "token": "deadbeefcafe" }))
- .await
- .unwrap();
- assert!(res.is_error);
- let res2 = tool.execute(json!({})).await.unwrap();
- assert!(res2.is_error);
-}
-
-#[test]
-fn miss_message_does_not_instruct_a_blind_re_run() {
- // See `miss_message` — "re-run the tool" here is what turned a single
- // eviction into an unbounded compact→retrieve→re-run loop.
- let msg = miss_message("deadbeefcafe").to_lowercase();
- assert!(
- msg.contains("do not re-run"),
- "must discourage re-running: {msg}"
- );
- // And must not also say the opposite. The loop this fixes came from an
- // affirmative instruction, so a message carrying both would read as
- // permission to re-run while the assertion above still passed. Every
- // mention of re-running has to be the negated one.
- let mut cursor = 0;
- while let Some(found) = msg[cursor..].find("re-run") {
- let at = cursor + found;
- assert!(
- msg[..at].trim_end().ends_with("do not"),
- "every mention of re-running must be negated, found a bare one at {at}: {msg}"
- );
- cursor = at + "re-run".len();
- }
- assert!(
- msg.contains("compacted summary"),
- "must point at the summary: {msg}"
- );
-}
-
-#[tokio::test]
-async fn retrieve_messages_name_only_the_tool_the_model_can_call() {
- // `tokenjuice_retrieve` / `tinyjuice_retrieve` are dispatch aliases for old
- // transcripts, not tools a model is offered. A message naming them sends the
- // model after a tool it cannot see ("unknown tool").
- let missing = TokenjuiceRetrieveTool::new()
- .execute(json!({}))
- .await
- .unwrap()
- .output();
- for msg in [missing, miss_message("deadbeefcafe")] {
- assert!(msg.contains(tinyjuice_bus::tools::RETRIEVE), "{msg}");
- assert!(!msg.contains("tokenjuice_retrieve"), "{msg}");
- assert!(!msg.contains("tinyjuice_retrieve"), "{msg}");
- }
-}