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
//! Builds and fingerprints the cached session `Agent`: target agent
//! resolution, model-override normalization, locale reply directive, and the
//! `SessionCacheFingerprint` that decides whether a cached agent can be
//! reused for the next turn on a thread.
use crate::agent::OpenHumanSessionHost;
use crate::config::Config;
use serde_json::json;
use super::types::{SessionCacheFingerprint, SessionEntry};
pub(super) fn autonomy_signature(config: &Config) -> String {
serde_json::to_string(&config.autonomy).unwrap_or_default()
}
/// Signature of `config.model_registry` for the session-cache fingerprint.
/// Captures every per-model `vision` flag so toggling one in Settings forces a
/// rebuild (picking up the new build-time `model_vision`). Mirrors
/// [`autonomy_signature`].
pub(super) fn model_registry_signature(config: &Config) -> String {
serde_json::to_string(&config.model_registry).unwrap_or_default()
}
/// The agent a web-chat turn runs as: `[agent] chat_agent_id` when an operator
/// set one, `orchestrator` otherwise.
///
/// The parameter was threaded in and ignored, so this path was pinned to the
/// orchestrator and its definition's `max_iterations` — no config could move
/// it, because a definition cap *overwrites* `agent.max_tool_iterations` rather
/// than being bounded by it (`session_host::builder::factory`). An unknown or
/// blank id falls back rather than failing the turn: the registry answers for
/// `orchestrator` on every install, and a typo in an optional setting should
/// not take chat down.
pub(crate) fn pick_target_agent_id(config: &Config) -> String {
const DEFAULT_CHAT_AGENT_ID: &str = "orchestrator";
let selected = config
.agent
.chat_agent_id
.as_deref()
.map(str::trim)
.filter(|id| !id.is_empty())
.unwrap_or(DEFAULT_CHAT_AGENT_ID);
if OpenHumanSessionHost::is_runnable_agent_id(config, selected) {
return selected.to_string();
}
log::warn!(
"[web-channel] configured chat_agent_id={selected:?} is not a runnable definition; falling back to {DEFAULT_CHAT_AGENT_ID}"
);
DEFAULT_CHAT_AGENT_ID.to_string()
}
pub(crate) fn normalize_model_override(model_override: Option<String>) -> Option<String> {
model_override
.map(|model| model.trim().to_string())
.filter(|model| !model.is_empty())
}
pub(crate) fn provider_role_for_model_override(model_override: Option<&str>) -> &'static str {
// A role alias (`hint:coding`) or a retired tier slug (`hint:coding`) picks
// that workload's route; a concrete model id rides the chat route.
match model_override.map(str::trim) {
Some(value)
if crate::inference::provider_model::is_abstract_model(
crate::inference::provider::factory::PROVIDER_OPENHUMAN,
value,
) =>
{
match crate::inference::provider_model::role_for_provider_model(
crate::inference::provider::factory::PROVIDER_OPENHUMAN,
value,
) {
role @ ("agentic" | "coding" | "summarization" | "reasoning") => role,
_ => "chat",
}
}
_ => "chat",
}
}
/// Build the in-memory config for one web-chat turn. Concrete picker values
/// may include their provider (`ollama:model`, `huggingface:org/model`) while
/// managed catalog ids use OpenRouter's `openrouter/...` form. The selected
/// route belongs only to this clone; saved chat settings and sibling workload
/// roles remain untouched.
fn effective_session_config(
config: &Config,
model_override: Option<&str>,
temperature: Option<f64>,
) -> Config {
let mut effective = config.clone();
if let Some(model) = model_override
.map(str::trim)
.filter(|model| !model.is_empty())
{
effective.default_model = Some(model.to_string());
}
// Resolve the effective model even when there was no per-turn override:
// persisted defaults must restore their provider after a restart too.
if let Some(model) = effective
.default_model
.as_deref()
.map(str::trim)
.filter(|model| {
crate::inference::provider_model::is_raw_model(
crate::inference::provider::factory::PROVIDER_OPENHUMAN,
model,
)
})
{
if model.starts_with("openrouter/") {
// The managed backend accepts catalog ids verbatim. This also
// clears a stale local/BYOK chat route from the effective clone.
effective.chat_provider = Some("openhuman".to_string());
} else if let Some((provider, model_suffix)) = model.split_once(':') {
let provider = provider.trim();
let local_route = tinyinference_local::profile::is_local_provider_string(model);
let built_in_route = matches!(provider, "claude-code" | "claude_agent_sdk");
if local_route || built_in_route {
// Keep the complete selected value for local and built-in routes.
effective.chat_provider = Some(model.to_string());
} else if let Some(entry) = effective
.cloud_providers
.iter()
.find(|entry| entry.slug.eq_ignore_ascii_case(provider))
{
// The factory matches configured slugs exactly; preserve its canonical slug
// while keeping the full selected model suffix, including extra colons.
effective.chat_provider = Some(format!("{}:{model_suffix}", entry.slug));
} else {
// Keep an unknown qualified selection on an invalid route so
// factory construction fails explicitly instead of silently
// using the previous chat provider.
effective.chat_provider = Some(model.to_string());
}
}
}
if let Some(temp) = temperature {
effective.default_temperature = temp;
}
effective
}
pub(super) fn build_session_agent(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
client_id: &str,
thread_id: &str,
target_agent_id: &str,
model_override: Option<String>,
temperature: Option<f64>,
) -> Result<OpenHumanSessionHost, String> {
let effective = effective_session_config(config, model_override.as_deref(), temperature);
let provider_role = provider_role_for_model_override(effective.default_model.as_deref());
log::info!(
"[web-channel] routing chat turn to '{}' provider_role='{}' (client_id={}, thread_id={})",
target_agent_id,
provider_role,
client_id,
thread_id
);
let agent_result = OpenHumanSessionHost::from_config_for_agent_session(
ctx,
&effective,
target_agent_id,
Some(thread_id),
);
agent_result
.map(|mut agent| {
agent.set_event_context(
json!({"client_id": client_id, "thread_id": thread_id}).to_string(),
"web_channel",
);
let short_thread: String = thread_id.chars().take(12).collect();
agent.set_agent_definition_name(format!("{target_agent_id}_{short_thread}"));
// Bind the conversation's durable identity here, not after
// checkout: everything downstream — resume, transcript binding,
// the `_meta` this session writes — is addressed by it, and a host
// that forgot to bind it would fall back to resuming whichever
// transcript for this agent happened to be newest.
agent.set_thread_id(Some(thread_id));
agent
})
.map_err(|e| e.to_string())
}
pub(crate) fn locale_reply_directive(locale: &str) -> Option<String> {
let language = match locale.trim() {
"ar" => "Arabic",
"bn" => "Bengali",
"de" => "German",
"es" => "Spanish",
"fr" => "French",
"hi" => "Hindi",
"id" => "Indonesian",
"it" => "Italian",
"ja" => "Japanese",
"ko" => "Korean",
"pl" => "Polish",
"pt" => "Portuguese",
"ru" => "Russian",
"tr" => "Turkish",
"zh-CN" | "zh" => "Simplified Chinese",
_ => return None,
};
Some(reply_directive_for(language))
}
/// The reply-language instruction for `language`.
fn reply_directive_for(language: &str) -> String {
format!(
"User language: the user's interface is set to {language}. \
Respond in {language} unless the user explicitly asks for a different language. \
Keep proper nouns, code, and command names untranslated."
)
}
/// Byte offset of the first difference between two signature strings, or
/// `None` when one is a prefix of the other (then the length difference is the
/// whole story).
fn first_difference_at(prior: &str, next: &str) -> Option<usize> {
prior
.as_bytes()
.iter()
.zip(next.as_bytes())
.position(|(a, b)| a != b)
}
/// Summarise a differing signature field without printing it.
///
/// `autonomy_signature` and `model_registry_signature` are whole JSON subtrees
/// of `Config` — `config.autonomy` carries the user's `action_dir` and other
/// filesystem paths, and the registry is long. Logging either raw would be both
/// a log bomb on the chat hot path and a needless disclosure, so the log names
/// the field and gives the reader enough to find the change in their own config:
/// the two lengths and where the strings first diverge.
fn describe_signature_change(field: &str, prior: &str, next: &str) -> String {
match first_difference_at(prior, next) {
Some(offset) => format!(
"{field}: differs at byte {offset} (prior {} bytes, now {} bytes)",
prior.len(),
next.len()
),
// No differing byte in the overlap: one is a prefix of the other, i.e.
// something was appended to or removed from the end of the subtree.
None => format!(
"{field}: length changed (prior {} bytes, now {} bytes)",
prior.len(),
next.len()
),
}
}
/// The fingerprint fields that actually differ between the thread's cached
/// entry and this turn.
///
/// The cache-miss log used to print two hand-picked fields, `target_agent_id`
/// and `provider_binding`. When those two matched — which is the common case,
/// since the target agent is hard-coded to `"orchestrator"`
/// ([`pick_target_agent_id`]) — the log reported a miss while showing nothing
/// that had missed, so the warning could not be acted on. Four of the six
/// fields were invisible. This names the ones that differ instead of guessing
/// which two are interesting.
///
/// Returns an empty vector when the fingerprints are equal, which the caller
/// treats as a bug worth saying so in the log rather than silently omitting:
/// reaching the miss arm with no differing field would mean `PartialEq` and
/// this function disagree.
pub(super) fn fingerprint_diff(
prior: &SessionCacheFingerprint,
next: &SessionCacheFingerprint,
) -> Vec<String> {
let mut diff = Vec::new();
if prior.model_override != next.model_override {
diff.push(format!(
"model_override: {:?} -> {:?}",
prior.model_override, next.model_override
));
}
if prior.effective_model != next.effective_model {
diff.push(format!(
"effective_model: {} -> {}",
prior.effective_model, next.effective_model
));
}
if prior.temperature != next.temperature {
diff.push(format!(
"temperature: {:?} -> {:?}",
prior.temperature, next.temperature
));
}
if prior.target_agent_id != next.target_agent_id {
diff.push(format!(
"target_agent_id: {} -> {}",
prior.target_agent_id, next.target_agent_id
));
}
if prior.provider_binding != next.provider_binding {
diff.push(format!(
"provider_binding: {} -> {}",
prior.provider_binding, next.provider_binding
));
}
if prior.autonomy_signature != next.autonomy_signature {
diff.push(describe_signature_change(
"autonomy_signature",
&prior.autonomy_signature,
&next.autonomy_signature,
));
}
if prior.workspace_dir != next.workspace_dir {
// Paths can carry usernames or tenant ids; log only that it moved.
diff.push("workspace_dir changed".to_string());
}
if prior.model_registry_signature != next.model_registry_signature {
diff.push(describe_signature_change(
"model_registry_signature",
&prior.model_registry_signature,
&next.model_registry_signature,
));
}
diff
}
pub(super) fn build_session_fingerprint(
config: &Config,
model_override: Option<String>,
temperature: Option<f64>,
target_agent_id: String,
provider_role: &str,
) -> SessionCacheFingerprint {
let effective = effective_session_config(config, model_override.as_deref(), temperature);
SessionCacheFingerprint {
model_override,
effective_model: crate::inference::provider_model::resolve_provider_model_hint(
crate::inference::provider::factory::PROVIDER_OPENHUMAN,
&format!("hint:{provider_role}"),
&effective,
),
temperature,
provider_binding: crate::inference::provider::provider_for_role(provider_role, &effective),
target_agent_id,
autonomy_signature: autonomy_signature(config),
model_registry_signature: model_registry_signature(config),
workspace_dir: config.workspace_dir.clone(),
}
}
/// How `checkout_session_agent` treats the thread's cached entry.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum CheckoutPolicy {
/// A user turn: reuse the cached agent only when its
/// `SessionCacheFingerprint` matches this turn's model/temperature/agent,
/// otherwise rebuild (and cold-boot resume) with the new settings.
Exact,
/// A host-authored turn: reuse whatever agent the thread has, under the
/// settings the user's last turn chose, and hand it back with that same
/// fingerprint. The turn has no settings of its own, and rebuilding on a
/// mismatch would evict the warm session for nothing.
AdoptCached,
/// A parallel fork: never take or return the cached agent; build fresh from
/// the thread's durable history.
Fork,
}
/// A session agent checked out of the per-thread cache for exactly one turn.
///
/// Every turn that runs on a conversation thread — a user turn, a
/// background-delivery turn, a goal continuation — must go through the same
/// checkout so it appends to the thread's live history and its transcript.
/// A turn run on a throwaway `OpenHumanSessionHost` bound to the thread writes
/// a *second* root transcript for that thread with a newer `created`, which the
/// next cold-boot resume then prefers over the real one — dropping every turn
/// the user had with the cached session (the "20–30 days" amnesia).
pub(crate) struct CheckedOutSession {
pub(crate) agent: OpenHumanSessionHost,
pub(crate) fingerprint: SessionCacheFingerprint,
}
/// Take the thread's cached session agent, or build one and cold-boot resume
/// it from the thread's durable history.
///
/// The entry is *removed* from the cache for the duration of the turn so two
/// turns can never drive one agent; `checkin_session_agent` /
/// `checkin_session_agent_if_vacant` put it back.
pub(crate) async fn checkout_session_agent(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
client_id: &str,
thread_id: &str,
model_override: Option<String>,
temperature: Option<f64>,
locale: Option<&str>,
policy: CheckoutPolicy,
) -> Result<CheckedOutSession, String> {
let map_key = super::ops::key_for(ctx, thread_id);
let target_agent_id = pick_target_agent_id(config);
let effective = effective_session_config(config, model_override.as_deref(), temperature);
let provider_role = provider_role_for_model_override(effective.default_model.as_deref());
let fingerprint = build_session_fingerprint(
config,
model_override.clone(),
temperature,
target_agent_id.clone(),
provider_role,
);
// A forked (parallel) turn never reuses or evicts the shared cached agent —
// it always builds fresh from the history snapshot below.
let prior = if policy == CheckoutPolicy::Fork {
None
} else {
let mut sessions = super::ops::thread_sessions(ctx).lock_owned().await;
sessions.remove(&map_key)
};
let (agent, fingerprint) = match prior {
// `AdoptCached` takes the thread's agent whatever settings it was
// built with, but never one built for another workspace.
Some(entry)
if entry.fingerprint == fingerprint
|| (policy == CheckoutPolicy::AdoptCached
&& entry.fingerprint.workspace_dir == fingerprint.workspace_dir) =>
{
log::info!(
"[web-channel] reusing cached session agent id={} for client={} thread={}",
entry.fingerprint.target_agent_id,
client_id,
thread_id
);
(entry.agent, entry.fingerprint)
}
Some(prior_entry) => {
// Name the field(s) that actually differ. The previous log printed
// `target_agent_id` and `provider_binding` only, and both match on
// the common path, so a miss was reported with no visible cause
// (openhuman#6414).
let changed = fingerprint_diff(&prior_entry.fingerprint, &fingerprint);
let reason = if changed.is_empty() {
// Unreachable via `PartialEq` — reaching the miss arm with no
// differing field would mean the derived equality and
// `fingerprint_diff` disagree. Say so rather than log nothing.
"no field differs (fingerprint_diff disagrees with PartialEq)".to_string()
} else {
changed.join("; ")
};
log::info!(
"[web-channel] cache miss — rebuilding session agent \
(changed: {}) for client={} thread={} id={}",
reason,
client_id,
thread_id,
target_agent_id
);
(
build_session_agent(
ctx,
config,
client_id,
thread_id,
&target_agent_id,
model_override,
temperature,
)?,
fingerprint,
)
}
None => (
build_session_agent(
ctx,
config,
client_id,
thread_id,
&target_agent_id,
model_override,
temperature,
)?,
fingerprint,
),
};
// Every checkout re-arms the reply language from this turn's locale: a
// reused agent may have been built under a different one, and `None`
// (English, or no locale sent) must clear a stale instruction.
let mut agent = agent;
bind_transcript_store(
ctx,
config,
thread_id,
&fingerprint.target_agent_id,
&mut agent,
)
.await;
let directive = match locale.and_then(locale_reply_directive) {
Some(directive) => Some(directive),
// Messages this session already sent carry another language's
// directive; an explicit English one supersedes them rather than
// leaving the last of them standing in the history.
None if locale.map(str::trim) == Some("en")
&& agent.reply_language_directive().is_some() =>
{
Some(reply_directive_for("English"))
}
None => None,
};
if directive.is_some() {
log::info!(
"[web-channel] reply language directive armed client={} thread={} locale={}",
client_id,
thread_id,
locale.unwrap_or("")
);
}
agent.set_reply_language_directive(directive);
// Re-read per message too, so a zone changed in Settings applies to the
// next message of an open conversation.
agent.set_time_zone(Some(config.time_zone()));
// Cold-boot resume needs no seeding here. `set_thread_id` binds the
// session's durable identity and the turn resumes by it, reading the one
// transcript this conversation has ever had — tool calls, tool results and
// reasoning included. The old path seeded by hand from whichever root
// transcript matched the thread and newest, and fell back to the
// conversation log's prose pairs when that failed; the prose fallback also
// carried no system message, so such a turn reached the provider with no
// system prompt and no prompt-cache key at all.
Ok(CheckedOutSession { agent, fingerprint })
}
/// Pin the thread's transcripts to the store key they were first written under.
///
/// The key follows `[agent] chat_agent_id`, so after the operator changes it a
/// session that re-derived the key would write the thread's next turns to a
/// different store than the one holding its earlier turns, and the readers
/// (which use the thread's recorded key) would lose them. The first session
/// bound to a thread records its key; every later one writes there.
async fn bind_transcript_store(
ctx: &crate::core::runtime::DispatchCtx,
config: &Config,
thread_id: &str,
target_agent_id: &str,
agent: &mut OpenHumanSessionHost,
) {
let tenant = match crate::core::runtime::tenant::tenant_in(
crate::core::runtime::is_saas(),
ctx.resolved().as_deref(),
) {
Ok(tenant) => tenant,
Err(no_tenant) => {
log::warn!("[web-channel] transcript key not bound thread={thread_id}: {no_tenant}");
return;
}
};
let rule_key = crate::storage::sessions::agent_key_for(&tenant, target_agent_id);
let key = crate::threads::store::bind_transcript_key(
ctx,
&config.workspace_dir,
thread_id,
rule_key.clone(),
)
.await;
if key != rule_key {
log::info!(
"[web-channel] thread={thread_id} keeps its recorded transcript store (chat agent changed since it was written)"
);
agent.set_session_history_locator(crate::storage::sessions::transcripts_or_files(
&key,
&config.workspace_dir,
));
}
}
/// Return a checked-out agent to the thread cache, replacing whatever is there.
/// The primary user-turn path: it owns the thread's `IN_FLIGHT` slot, so any
/// entry it finds was left by a turn that ran concurrently and is now stale.
pub(crate) async fn checkin_session_agent(
ctx: &crate::core::runtime::DispatchCtx,
thread_id: &str,
agent: OpenHumanSessionHost,
fingerprint: SessionCacheFingerprint,
) {
let mut sessions = super::ops::thread_sessions(ctx).lock_owned().await;
sessions.insert(
super::ops::key_for(ctx, thread_id),
SessionEntry { agent, fingerprint },
);
}
/// Return a checked-out agent to the thread cache only when the slot is still
/// empty. Host-authored turns (background delivery, goal continuation) do not
/// hold `IN_FLIGHT`, so a user turn that started while they ran built its own
/// agent and cached it; that one carries the user's newer turn and must win.
/// Both turns appended to the thread's durable transcript regardless.
pub(crate) async fn checkin_session_agent_if_vacant(
ctx: &crate::core::runtime::DispatchCtx,
thread_id: &str,
agent: OpenHumanSessionHost,
fingerprint: SessionCacheFingerprint,
) -> bool {
let mut sessions = super::ops::thread_sessions(ctx).lock_owned().await;
match sessions.entry(super::ops::key_for(ctx, thread_id)) {
std::collections::hash_map::Entry::Occupied(_) => {
log::info!(
"[web-channel] system turn finished after a newer turn re-cached thread={} — \
dropping the system turn's agent",
thread_id
);
false
}
std::collections::hash_map::Entry::Vacant(slot) => {
slot.insert(SessionEntry { agent, fingerprint });
true
}
}
}
#[cfg(test)]
#[path = "session_checkout_tests.rs"]
mod session_checkout_tests;
#[cfg(test)]
#[path = "session_checkout_agents_tests.rs"]
mod session_checkout_agents_tests;
#[cfg(test)]
#[path = "session_routing_tests.rs"]
mod session_routing_tests;