The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! The host's per-turn middleware stack, installed on the harness a
//! [`TurnDriver`](tinyagents_runtime::turn_driver::TurnDriver) prepared.
//!
//! The driver owns the generic half of a turn (models, run policy, tool
//! registration, steering, early exit, the cap pause). Everything product-shaped
//! that wraps a model call or a tool call lives here, in the intended order:
//! usage and route capture, time awareness and the repeat/failure breakers,
//! tool exposure, the prompt-cache guard, tool-outcome capture, the context
//! ladder, plan mode, budgets, the tool-boundary gates (approval, CLI/RPC
//! scope, session tool policy, credential scrub) and the final request shaping
//! (argument recovery, embedder hooks, nudges, the memory pack).
use std::collections::HashSet;
use std::sync::Arc;
use async_trait::async_trait;
use tinyagents_harness::cache::InMemoryResponseCache;
use tinyagents_harness::host::security_gate::{GateDecision, SecurityGate, ToolCallRequest};
use tinyagents_harness::middleware::{
install_unmet_deliverable, is_repeat_call_exempt, tool_sets_lookup, ResearchBudgetMiddleware,
ShellTurnBudget, TurnClockMiddleware, DIRECT_WEB_READ_LIMIT,
};
use tinyagents_harness::middleware::{
plan_mode_middleware, ApprovalGateMiddleware, ArgRecoveryMiddleware, BudgetLimits,
BudgetMiddleware, ContextCompressionMiddleware, MiddlewareToolOutcome,
PromptCacheGuardMiddleware, RepeatProgressMiddleware, RunModeHandle, ToolHandler,
ToolMiddleware, ToolPolicyMiddleware as TaToolPolicyMiddleware,
};
use tinyagents_harness::runtime::AgentHarness;
use tinyagents_harness::steering::SteeringHandle;
use tinyagents_harness::turn_outcome::{HaltSummarySlot, ToolOutcomeSink};
use tinyagents_harness::turn_policy::REPEATED_TOOL_FAILURE_THRESHOLD;
use tinyagents_hooks::lifecycle::BudgetParityObserver;
use tinyinference_llm::model::CapabilitySet;
use crate::agent::tinyagents::context_wiring::install_context_ladder;
use crate::agent::tinyagents::host::OpenHumanRunContext;
use crate::agent::tinyagents::host::OpenHumanSecurityGate;
use crate::agent::tinyagents::middleware;
use crate::agent::tinyagents::middleware::turn_context::TurnContextMiddleware;
use crate::agent::tinyagents::observability::{ProviderUsageCarry, SubagentScope, ToolFailureMap};
use crate::agent::tinyagents::verify_before_finish;
use super::ToolPolicyEnforcement;
#[path = "turn_native_security.rs"]
mod native_security;
use native_security::NativeSubagentSecurityMiddleware;
struct OpenHumanCostEstimator;
impl tinyagents_harness::middleware::library::CostEstimator for OpenHumanCostEstimator {
fn estimate(&self, model: &str, usage: &tinyinference_llm::usage::BilledUsage) -> Option<f64> {
crate::agent::cost::estimate_call_cost_usd(model, usage)
}
}
/// What the middleware stack needs to know about the turn.
pub(super) struct TurnMiddlewareInputs {
/// Configured provider id used only when the response has no resolved route.
pub(super) provider_id: String,
/// The turn's primary model name.
pub(super) model: String,
/// The shared tool sets the turn's tools resolve against.
pub(super) tool_sets: Vec<tinyagents_runtime::turn_driver::SharedToolSet>,
/// The allowlist the turn registered under (`None` = every visible tool).
pub(super) allowed: Option<HashSet<String>>,
/// The tool names the registration considered (before the allowlist).
pub(super) candidate_names: Vec<String>,
/// Set for a delegated child run.
pub(super) subagent_scope: Option<SubagentScope>,
pub(super) context_window: Option<u64>,
pub(super) context_mw: TurnContextMiddleware,
/// Stop policies and scoped tool callbacks (registered after the runtime's
/// global ones), from the explicit run context.
pub(super) host_policy: super::host::HarnessHostPolicy,
pub(super) tool_policy: Option<ToolPolicyEnforcement>,
pub(super) required_capabilities: Option<CapabilitySet>,
pub(super) deterministic_cacheable: bool,
/// Whether the run has a cross-route fallback chain.
pub(super) has_route_fallback: bool,
/// The turn's dispatch context (its embedder tool hooks come from it).
pub(super) dispatch: crate::core::runtime::DispatchCtx,
/// Hosted roots authorize tools through `OpenHumanSecurityGate`; installing
/// the legacy approval middleware as well would issue a second approval.
pub(super) hosted_security_gate: bool,
/// Host gate installed at the native child's tool boundary, avoiding a
/// full hosted root invocation while preserving the same authorization.
pub(super) native_security_gate: Option<(Arc<OpenHumanSecurityGate>, String)>,
/// Whether this run pauses gracefully at its model-call cap (issue #6014).
/// Only such a run gets the in-loop conclusion: a run that errors at its cap
/// instead (the channel/CLI path, which maps the stop to
/// `MaxIterationsExceeded`) must keep doing that, and handing it a wrap-up
/// would silently convert a documented error into an answer.
pub(super) pause_at_cap: bool,
/// Live per-thread Plan/Build mode handle; `Some` installs
/// `PlanModeMiddleware`. `None` for a caller with no thread identity.
pub(super) run_mode: Option<RunModeHandle>,
/// This turn's memory binding: the compaction summarizer recalls under it.
pub(super) memory_turn: Option<Arc<crate::memory::lifecycle::hooks::MemoryTurn>>,
/// The context-window summarizer: its model, the id it calls
/// (`[context] summarizer_model`, else the turn's model) and its
/// rendering and output cap.
pub(super) summarizer: super::context_wiring::CompactionSummarizer,
/// Shared `call_id -> (success, failure, elapsed_ms, output_chars)` side
/// channel: middleware records each outcome for the bridge's
/// `ToolCallCompleted`.
pub(super) failure_map: ToolFailureMap,
/// Shared FIFO carry of per-call provider `BilledUsage`; the event bridge
/// reads it when recording usage to preserve charged-USD precedence (#4467).
pub(super) provider_usage_carry: ProviderUsageCarry,
/// Per-call tool success/content capture for honest `ToolCallRecord`s.
pub(super) tool_outcome_sink: ToolOutcomeSink,
/// The store the `todo` tool writes this turn's plan to; `Some` lets the
/// plan-order middleware read it. `None` for a turn with no workspace or
/// without the `todo` tool.
pub(super) todo_store: Option<Arc<dyn tinyagents_harness::store::Store>>,
/// Called when the turn starts summarizing earlier conversation, so the
/// client can show it. `None` for a turn nobody watches.
pub(super) compaction_notice: Option<super::context_wiring::CompactionNotice>,
/// The session store the goal and `todo` tools write, whether or not this
/// turn has the `todo` tool; the run-state block reads it.
/// With the scope the `todo` tool uses on a turn without a thread (the
/// session id), so a headless turn's block still finds its plan.
pub(super) state_store: Option<(Arc<dyn tinyagents_harness::store::Store>, String)>,
/// The turn suppresses the thread goal (`TurnOverrides::suppress_active_goal`).
pub(super) goal_suppressed: bool,
}
/// The handles the run loop reads after the drive returns.
pub(super) struct TurnWiring {
/// Root-cause summary recorded by the repeated-tool-failure breaker.
pub(super) halt_summary: HaltSummarySlot,
/// Set by `FinalCallWrapUpMiddleware` when it turned the last permitted
/// model call into the turn's conclusion (issue #6014). `None` when the
/// middleware is not installed (a run that does not pause at its cap).
pub(super) wrap_up_fired:
Option<Arc<tinyagents_harness::middleware::FinalCallWrapUpMiddleware>>,
/// The installed compression middleware, drained after the run to surface
/// each compaction's provenance.
pub(super) compression_mw: Option<Arc<ContextCompressionMiddleware>>,
/// Records a `CacheLayoutEvent` whenever the cacheable prompt prefix changes
/// across model calls (issue #4249, 03.2).
pub(super) prompt_cache_guard: Arc<PromptCacheGuardMiddleware>,
}
/// Installs the host's middleware stack onto `harness`, whose models, run
/// policy and tools the driver already registered. `steering` is the run's own
/// handle (the breakers, stop hooks and nudges pause through it).
pub(super) fn install_turn_middleware(
harness: &mut AgentHarness<(), OpenHumanRunContext>,
steering: &SteeringHandle,
inputs: TurnMiddlewareInputs,
) -> TurnWiring {
let TurnMiddlewareInputs {
provider_id,
model,
tool_sets,
allowed,
candidate_names,
subagent_scope,
context_window,
context_mw,
host_policy,
tool_policy,
required_capabilities,
deterministic_cacheable,
has_route_fallback,
dispatch,
hosted_security_gate,
native_security_gate,
pause_at_cap,
run_mode,
memory_turn,
summarizer,
failure_map,
provider_usage_carry,
tool_outcome_sink,
todo_store,
compaction_notice,
state_store,
goal_suppressed,
} = inputs;
let super::host::HarnessHostPolicy {
stop_hooks,
tool_hooks: scoped_tool_hooks,
..
} = host_policy;
let model = model.as_str();
crate::tools::timeout::install_harness_tool_timeouts(harness);
// Deterministic internal runs (summarizer/triage/memory-scoring style) may
// reuse a prior identical model response; attach an in-memory response cache
// so the agent loop can short-circuit a recurring provider call and emit
// `CacheHit`/`CacheMiss` (issue #4249, 03.2). NEVER attached for interactive
// chat turns — a live user turn must never be served a cached response.
if deterministic_cacheable {
harness.with_response_cache(Arc::new(InMemoryResponseCache::new()));
tracing::debug!(
model,
"[cache] response cache attached (deterministic internal run)"
);
}
// The run's own steering handle: besides run-queue steering, the early-exit /
// cap / stop-hook pauses, the repeated-tool-failure breaker also pauses
// through it, and it wants to fire on every path.
let handle = Some(steering.clone());
// Cost usage capture (issue #4249, Phase 5): feed the event bridge's usage
// carry from a wrap-model middleware that reads the full `BilledUsage` off each
// response, instead of every `native model adapter` pushing it. Installed
// unconditionally — usage flows on every turn — and shares the same carry the
// bridge drains on `UsageRecorded`.
let usage_carry = provider_usage_carry.clone();
harness.push_model_middleware(Arc::new(
tinyagents_harness::middleware::library::UsageCarryMiddleware::new(move |response| {
if let Some(usage) = tinyinference_llm::usage::usage_info_from_response(response) {
usage_carry
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.push_back(usage);
}
}),
));
// Native route enrichment records the canonical resolved route in this
// run's explicit host carrier; pricing and cost remain host-owned.
harness.push_model_middleware(Arc::new(
tinyagents_harness::middleware::library::ResolvedRouteMiddleware::new(
provider_id,
model,
OpenHumanCostEstimator,
|data: &OpenHumanRunContext, route| {
*data
.resolved_route
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(route);
},
)
.with_pricing_lookup(generation_pricing),
));
// Per-call capability gate (issue #4249, Workstream 02.1): when the turn has
// derivable capability needs (today: vision for a `hint:vision` turn), stamp
// them onto every `ModelRequest` via `with_required_capabilities` so an unfit
// model is rejected pre-dispatch (and, once 02.2 lands, a capable fallback is
// selected) instead of failing at the provider.
if let Some(required) = required_capabilities {
harness.push_model_middleware(Arc::new(
tinyagents_harness::middleware::library::RequiredCapabilitiesMiddleware::new(required),
));
}
// Fallback event parity (issue #4249, Workstream 02.2): the crate's
// registry-backed `RunPolicy.fallback` traversal (wired above) performs the
// cross-route swap silently — it emits no `AgentEvent::FallbackSelected`. Wrap
// the model-resolving core with an observer that surfaces the parity event
// whenever the resolved model differs from the primary, so a fallback is
// visible on the OpenHuman progress/observability bridge (and grep-logged under
// `[fallback]`). Installed only when a fallback chain exists; it never re-issues
// the call, so it adds no provider dispatch (no double-fallback).
if has_route_fallback {
harness.push_model_middleware(Arc::new(
tinyagents_harness::middleware::library::FallbackObserverMiddleware::new(model),
));
}
// Capture context settings before `install` consumes `context_mw`.
let autocompact_enabled = context_mw.autocompact_enabled;
let compaction = context_mw.compaction;
// Captured for the same reason `autocompact_enabled` is — `install` consumes
// `context_mw` — and used to site microcompact below, after compression.
let microcompact_keep_recent = context_mw.microcompact_keep_recent;
// Shared by the two breakers below: whichever halts writes the root cause here.
let halt_summary: HaltSummarySlot = std::sync::Arc::new(std::sync::Mutex::new(None));
// Repeat-progress breaker (#4463, restoring #4088/#4095): the failure
// breaker resets on success, so it misses successful no-op loops and repeated
// narration+call batches. This guard catches identical successful calls or
// outputs, including repeats with other calls between them (#6275). Polling
// tools (`wait_subagent`) stay exempt.
//
// Pushed first / outermost: `after_tool` runs in reverse registration order,
// so this guard fingerprints a result only after every other middleware
// (byte cap, summarizer, memory-protocol note) has finished rewriting it,
// i.e. exactly what the model sees. Registered any later, a result whose
// visible note changed between calls would count as identical.
// Classified read-only tools are the guard's read-only set.
let read_only_tools: HashSet<String> = tool_sets
.iter()
.flat_map(|set| set.iter())
.filter(|t| t.policy().classified && t.policy().side_effects.read_only)
.map(|t| t.name().to_string())
.collect();
let repeat_progress = handle.as_ref().map(|handle| {
Arc::new(
RepeatProgressMiddleware::new(
handle.clone(),
halt_summary.clone(),
Arc::new(is_repeat_call_exempt),
)
.with_read_only(Arc::new(move |name: &str| read_only_tools.contains(name)))
.with_cleared_placeholder(
tinyagents_harness::middleware::library::DEFAULT_CLEARED_PLACEHOLDER,
),
)
});
// Time awareness (#6953); before the repeat guard so its notes land last.
let turn_budget = harness
.policy()
.limits
.max_wall_clock_ms
.map(std::time::Duration::from_millis);
harness.push_middleware(Arc::new(TurnClockMiddleware::new(turn_budget)));
let shell_turn_budget = ShellTurnBudget::with_max_timeout(
turn_budget,
tinyagents_harness_tools::exec::timeout::MAX_TIMEOUT_SECS,
);
harness.push_middleware(Arc::new(shell_turn_budget.notes()));
if let Some(mw) = &repeat_progress {
harness.push_middleware(mw.clone());
}
// Repeated failures stop the run using each tool's declared side effects.
let repeated_failure = handle.as_ref().map(|handle| {
let (t, halt) = (REPEATED_TOOL_FAILURE_THRESHOLD, halt_summary.clone());
let mw = middleware::repeated_failure::RepeatedToolFailureMiddleware::new(
handle.clone(),
t,
halt,
);
Arc::new(mw.with_tool_facts(tool_sets_lookup(tool_sets.clone())))
});
if let Some(mw) = &repeated_failure {
harness.push_middleware(mw.clone());
}
if handle.is_some() && !stop_hooks.is_empty() {
let summary = halt_summary.clone();
harness.push_middleware(Arc::new(
tinyagents_hooks::stop::StopHookMiddleware::new(model, stop_hooks)
.with_metrics_seed(crate::agent::cost::turn_cost())
.with_stop_observer(move |report| {
tracing::warn!(
target: "stop_hooks",
hook = %report.hook,
iteration = report.iteration,
model = %report.model,
"[stop_hooks] hook voted to stop the turn — pausing run: {}",
report.reason
);
record_stop_summary(&summary, report.iteration, &report.reason);
}),
));
}
// SHADOW tool-exposure layer (issue #4249, 01.3 — dynamic exposure). Compose
// the OpenHuman exposure policy as a crate-native selection layer
// (ToolAllowlistMiddleware + a ContextualToolSelectionMiddleware built via
// `inheriting`) and run it in shadow: it emits the exposure decision
// event-native (`AgentEvent::ToolsFiltered`) and logs any divergence between
// the crate layer's decision and the set OpenHuman actually registered as
// callable — WITHOUT changing the callable set (byte-identical to today).
// Folding the remaining host selection policy in `tool_prep.rs` into the
// middleware is gated on `[tool-exposure]` divergence logs showing parity. Tags encode
// the OpenHuman run context (agent id / channel / scope) for the flip; the
// name-based `inheriting` predicate does not consult them yet.
let exposure_tags: Vec<String> = {
let mut tags = vec![if subagent_scope.is_some() {
"scope:subagent".to_string()
} else {
"scope:root".to_string()
}];
if let Some(scope) = &subagent_scope {
tags.push(format!("agent:{}", scope.agent_id));
tags.push(format!("task:{}", scope.task_id));
}
if let Some(enforcement) = &tool_policy {
tags.push(format!("channel:{}", enforcement.channel));
tags.push(format!("agent_def:{}", enforcement.agent_definition_id));
}
tags
};
harness.push_middleware(Arc::new(
tinyagents_harness::middleware::ToolExposureShadowMiddleware::new(
&candidate_names,
allowed.as_ref(),
exposure_tags,
),
));
// Prompt-cache prefix protection (issue #4249, 03.2). The vendor loop owns
// the stable-prefix layout (`PromptSegment`s built from the session's frozen
// system prefix, `frozen_system_prefix_len`); the crate
// `PromptCacheGuardMiddleware` diffs the cacheable prefix across model calls
// and records a `CacheLayoutEvent` when volatile content busts it. The guard
// is returned so the run loop can drain its events into the observability
// bridge.
let prompt_cache_guard = Arc::new(PromptCacheGuardMiddleware::new());
harness.push_middleware(prompt_cache_guard.clone());
// openhuman context concerns as graph middlewares (issue #4249): microcompact
// tool-body clearing and the after-tool byte cap / payload summarizer.
// Installed before the summarization/trim block below so `before_model` hooks
// run microcompact → compress → trim. (KV-cache-prefix drift is handled above
// by the crate `PromptCacheGuardMiddleware`; the warn-only CacheAlign shadow
// was deleted in C3.) Tool-result caps read the SDK registry policy snapshot,
// not the OpenHuman-side tool lookup.
// Capture each tool call's real success + content before the harness folds the
// result into a `Message::tool` that drops the failure flag, so the turn can
// build honest per-call `ToolCallRecord`s (post-turn hooks + cap checkpoint).
//
// REVERSE-ORDER RULE (issue #4464): the crate runs `after_tool` in REVERSE
// registration order, so the LATER a middleware is pushed the EARLIER its
// `after_tool` runs. This capture must observe the FINAL (summarized/capped)
// content, so it is pushed BEFORE `context_mw.install` (which registers the
// handoff + tool-output budget/caps) — that way its `after_tool` runs AFTER
// those caps, not before. Registering it after `install` (the pre-#4464 bug)
// made its `after_tool` run first and record the full raw payload of every
// call, bloating the per-turn sink and feeding failure classification /
// `ToolCallRecord.output_summary` pre-cap content.
harness.push_middleware(Arc::new(
middleware::tool_outcome_capture::ToolOutcomeCaptureMiddleware::new(
tool_outcome_sink.clone(),
failure_map.clone(),
),
));
let tool_policies = harness.tools().policies();
let summary_focus_tools = harness
.tools()
.schemas()
.into_iter()
.chain(harness.tools().deferred_schemas())
.filter(|schema| {
crate::inference::tokenjuice::focus::declares_summary_focus(&schema.parameters)
})
.map(|schema| schema.name)
.collect();
context_mw.install(harness, tool_policies, summary_focus_tools);
// Plan mode (issue: plan-mode approvals). `run_mode` is `Some` only for a
// turn with a thread identity (chat, not a sub-agent child); the
// middleware itself is a no-op whenever the live handle reads
// `RunMode::Build`, so pushing it unconditionally for those turns is
// cheap and lets a mid-run `plan_exit`/`agent.set_run_mode` flip take
// effect on the very next tool exposure or execution check. `.allow(..)`
// keeps plan-mode-specific and session-bookkeeping tools reachable while
// planning even though they are not (or should not be gated as)
// side-effect-free: `plan_exit` (the hand-off signal itself),
// `request_plan_review` (the review gate IS the consent surface), the
// session `todo` list, and the per-thread `goal_*` tools.
if let Some(mode) = run_mode {
harness.push_middleware(Arc::new(
plan_mode_middleware(mode, harness.tools().policies()).allow(
tinyagents_harness::middleware::library::plan_mode_allowlist()
.iter()
.copied(),
),
));
}
// Observe-only crate `BudgetMiddleware`, installed with empty limits so it
// never enforces: it only folds each call's usage into a shared tracker.
// The spend cap is gone; `BudgetParityObserver` below compares that tracker
// against the authoritative `AgentRun.usage` at end of run and logs
// `[budget_parity]` parity or divergence.
let shadow_budget = Arc::new(BudgetMiddleware::new(BudgetLimits::default()));
let shadow_budget_tracker = shadow_budget.tracker();
harness.push_middleware(shadow_budget);
harness.push_middleware(Arc::new(BudgetParityObserver::new(shadow_budget_tracker)));
// The context ladder (compression, microcompact, final-call wrap-up,
// artifact contents list, trim), registered here so each step keeps its
// place in the middleware order. See `context_wiring.rs`.
let (compression_mw, wrap_up_fired) = install_context_ladder(
harness,
model,
context_window,
autocompact_enabled,
compaction.trigger_tokens,
compaction.strategy,
microcompact_keep_recent,
summarizer,
pause_at_cap && subagent_scope.is_none(),
&tool_outcome_sink,
memory_turn,
compaction_notice,
);
let is_subagent = subagent_scope.is_some();
let agent_id = tool_policy.as_ref().map(|p| p.agent_definition_id.as_str());
let turn_wall_clock_ms = harness.policy().limits.max_wall_clock_ms;
verify_before_finish::install(
harness,
is_subagent,
agent_id,
&wrap_up_fired,
turn_wall_clock_ms,
);
// The rungs above all *tell* the turn to produce its deliverable; this one
// looks, on the same scope as the requirements check.
if verify_before_finish::applies(is_subagent, agent_id) {
install_unmet_deliverable(harness);
} else {
tracing::debug!(
is_subagent,
agent = agent_id.unwrap_or("<none>"),
"[unmet_deliverable] not installed for this turn"
);
}
// Plan steps run in order: no work while no step is in progress, a final
// answer is held once while steps are open, a step stuck in progress gets
// one reminder. Same scope as the requirements check, and registered after
// it so its `after_model` runs first and the plan check comes first.
match todo_store {
Some(store) if verify_before_finish::applies(is_subagent, agent_id) => {
// A thread-less turn's plan sits under the session id (the `todo`
// tool's fallback scope); without the same key these rules never
// see it.
let mut sequence = tinyagents_harness_tools::todos::TodoSequenceMiddleware::new(store);
if let Some((_, fallback_thread)) = &state_store {
sequence = sequence.with_fallback_thread(fallback_thread.clone());
}
harness.push_middleware(Arc::new(sequence));
}
_ => tracing::debug!(
is_subagent,
agent = agent_id.unwrap_or("<none>"),
"[todo_sequence] not installed for this turn"
),
}
// The goal, the plan and the turn's tool-call facts on every model call,
// request-only. On these turns the goal is not prepended to the user's
// message (see `state_block`).
super::state_block::install(harness, state_store, is_subagent, agent_id, goal_suppressed);
// Direct web lookup is bounded. Once enough search/fetch results have
// returned, the web tools leave the request so the run works with what it
// has; a run with nothing but web tools answers instead. Sub-agent runs
// keep their own budgets and are not narrowed here.
if subagent_scope.is_none() {
harness.push_middleware(Arc::new(ResearchBudgetMiddleware::with_limit(
DIRECT_WEB_READ_LIMIT,
)));
}
// SDK-owned tool-policy projection (issue #4249 / tinyagents-full-migration
// 01.1). Keep this narrow for now: enforce sandbox requirements declared by
// adapter policies without enabling classification/approval/result-byte
// gates yet. `require_classification(true)` would currently reject an
// unregistered hallucinated tool in `before_tool` before
// `RunPolicy::unknown_tool` can return a recoverable tool error, while
// OpenHuman's existing wrappers still own HITL approval and output caps.
harness.push_middleware(Arc::new(
TaToolPolicyMiddleware::new(harness.tools().policies()).require_sandbox(true),
));
// Human-in-the-loop approval as a named tool middleware (issue #4249,
// Phase 1): an external-effect tool intercepts through the global
// `ApprovalGate`, a denial short-circuits with a model-consumable result, and
// an approved call records a terminal audit row. Replaces the inline approval
// block that used to live in the legacy tool adapter.
let native_security_gate_installed = native_security_gate.is_some();
if let Some((gate, agent_id)) = native_security_gate {
harness.push_tool_middleware(Arc::new(NativeSubagentSecurityMiddleware::new(
gate, agent_id,
)));
}
if !hosted_security_gate {
harness.push_tool_middleware(Arc::new(ApprovalGateMiddleware::new(
"approval_security",
Arc::new(middleware::approval::ApprovalSecurityMiddleware::new(
tool_sets.clone(),
)),
)));
}
// CLI/RPC-only scope gate — a tool restricted to explicit CLI/RPC invocation
// must not run from the model loop. Intrinsic to the tool, so installed on
// every path (channel/session/sub-agent).
harness.push_tool_middleware(Arc::new(
tinyagents_harness::middleware::CliRpcOnlyMiddleware::new(tool_sets.clone()),
));
// Builder-configured tool policy (`.tool_policy()`), enforced at the tool
// boundary. The in-house engine ran this in `agent_tool_exec`; the tinyagents
// path bypassed it, so a deny/require-approval silently no-opped (security
// regression). Installed only when the caller threads an enforcement context
// (the session chat path); channel/CLI + sub-agent paths pass `None`.
// The packed-tool router below gates on the same session, and `None`
// disables it, so take a copy before the enforcement is moved.
let route_session = tool_policy
.as_ref()
.map(|enforcement| enforcement.session.clone());
if let Some(enforcement) = tool_policy {
let middleware = if native_security_gate_installed {
middleware::tool_policy::ToolPolicyMiddleware::new_without_session_ceiling(
enforcement.policy,
enforcement.session,
tool_sets.clone(),
enforcement.channel,
)
} else {
middleware::tool_policy::ToolPolicyMiddleware::new(
enforcement.policy,
enforcement.session,
tool_sets.clone(),
enforcement.channel,
)
};
harness.push_tool_middleware(Arc::new(middleware));
}
// Credential scrubbing (issue #4453): redact credential-shaped secrets out of
// every tool result. The legacy engine ran `scrub_credentials` over every
// tool output before it entered model context; the tinyagents path dropped
// that call site. Installed as the **innermost** tool wrap (pushed last) so
// it scrubs the RAW tool result before any outer wrap, the `after_tool`
// chain (summarization/caps), the transcript push, or the tool-outcome
// capture sink can observe the unredacted content — covering the parent,
// sub-agent, persisted-transcript, and `ToolCallOutcome` surfaces by
// construction since every path shares this seam.
harness.push_tool_middleware(Arc::new(
middleware::credential_scrub::credential_scrub_middleware(),
));
// Malformed-argument recovery (`before_tool`): repair a call's non-object
// arguments before the crate's schema gate — decode JSON-encoded-string args
// (optionally markdown-fenced) to an object, or coerce to `{}` only when the
// tool schema has no required fields (engine parity). A non-object against a
// required-field schema is left untouched so the crate's
// `InvalidArgsPolicy::ReturnToolError` admission path reports the original
// validation error. It never reaches approval/policy wrappers or the tool.
harness.push_middleware(Arc::new(ArgRecoveryMiddleware::new(tool_sets.clone())));
// The model's shell `timeout_secs` is when the call comes back, not a kill:
// move it aside so the clamp below writes the command's deadline there.
let can_follow = harness
.tools()
.names()
.iter()
.any(|name| name == "shell_process");
harness.push_middleware(Arc::new(middleware::shell_yield::ShellYieldMiddleware {
can_follow,
}));
// Clamp shell `timeout_secs` to the turn remainder (#6953), on recovered args.
harness.push_middleware(Arc::new(shell_turn_budget.clamp()));
// Bare packed-tool routing (`before_tool`, #6276): a call that names a
// withheld packed tool directly becomes the `use_skill` call that reaches
// it, ahead of admission, so every gate above still applies. Only when the
// session lets that tool run, and never without a session. After
// `ArgRecoveryMiddleware` so it wraps recovered arguments; before the
// embedder hooks so they observe the call that actually runs.
let registered_tools = harness.tools().names();
harness.push_middleware(Arc::new(
middleware::packed_tool_route::packed_tool_route_middleware(
registered_tools,
route_session,
),
));
// Embedder tool lifecycle hooks. Registered AFTER `ArgRecoveryMiddleware`:
// `before_tool` runs in registration order, so a hook installed earlier would
// observe the provider's raw (possibly JSON-encoded-string / non-object)
// arguments instead of the recovered object that `ToolHookContext` documents.
// The middleware caches the normalized pre-call arguments by `call_id` and
// replays them into the `PostToolUse` context. Its `after_tool` is
// observation-only (never mutates the result), so running first in the
// reverse-order `after_tool` chain is safe — it cannot perturb the
// summarization/cap or tool-outcome capture layers.
let mut embedder_tool_hooks = crate::agent::hooks::embedder_tool_hooks_in(&dispatch);
embedder_tool_hooks.extend(scoped_tool_hooks);
if !embedder_tool_hooks.is_empty() {
harness.push_middleware(Arc::new(tinyagents_hooks::tool::ToolHooksMiddleware::<
super::host::OpenHumanRunContext,
>::new(embedder_tool_hooks)));
}
// Registered last so its `before_model` sees the request after every
// reduction step above (compression, microcompact, trim) has run. A tool
// result they evicted is no longer a repeat the model can see, so the
// repeat-progress recurrence ledger restarts (#6275).
if let Some(mw) = &repeat_progress {
harness.push_middleware(Arc::new(mw.eviction_observer()));
}
// Registered after it: the breaker's corrective nudges ride the next
// request only. Anything earlier (notably the transcript snapshot a failed
// turn persists) must not see them, or they become durable history (#6725).
if let Some(mw) = &repeated_failure {
harness.push_middleware(Arc::new(mw.nudge_injector()));
}
// The turn's memory pack rides every request of the turn, after every
// reduction step and after the transcript snapshot, so it is never
// compacted, trimmed or persisted (`memory::lifecycle::prefetch::pre_turn`).
harness.push_middleware(Arc::new(middleware::memory_pack::memory_pack_middleware()));
TurnWiring {
halt_summary,
wrap_up_fired,
compression_mw,
prompt_cache_guard,
}
}
fn record_stop_summary(summary: &HaltSummarySlot, iteration: u32, reason: &str) {
*summary
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner) = Some(format!(
"Stopping after {iteration} model call(s): {reason}"
));
}
/// The per-token pricing a resolved route's generation is enriched with: a
/// free model is priced at zero, a catalogued one at its list price, and an
/// unknown one is left unpriced.
fn generation_pricing(model: &str) -> Option<tinyagents_harness::events::GenerationPricing> {
if crate::agent::cost::is_free_model(model) {
return Some(tinyagents_harness::events::GenerationPricing {
input_per_mtok_usd: Some(0.0),
cached_input_per_mtok_usd: Some(0.0),
output_per_mtok_usd: Some(0.0),
});
}
tinyagents_registry::pricing::lookup(model).map(|price| {
tinyagents_harness::events::GenerationPricing {
input_per_mtok_usd: Some(price.input_per_mtok_usd),
cached_input_per_mtok_usd: Some(price.cached_input_per_mtok_usd),
output_per_mtok_usd: Some(price.output_per_mtok_usd),
}
})
}
#[cfg(test)]
#[path = "turn_middleware_tests.rs"]
mod tests;