Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

security: bound agent metadata without dropping mux sessions

RoversX977e4210a46b
diff --git a/codec/src/lib.rs b/codec/src/lib.rs
index f286bd34..6c4d7c79 100644
--- a/codec/src/lib.rs
+++ b/codec/src/lib.rs
@@ -474,7 +474,7 @@ macro_rules! pdu {
metrics::histogram!("pdu.size.rate", "pdu" => stringify!($name)).record(decoded.data.len() as f64);
Ok(DecodedPdu {
serial: decoded.serial,
- pdu: Pdu::$name(deserialize(decoded.data.as_slice(), decoded.is_compressed)?)
+ pdu: Pdu::$name(deserialize(decoded.data.as_slice(), decoded.is_compressed)?).sanitize_agent_status()
})
}
,)*
@@ -507,7 +507,7 @@ macro_rules! pdu {
metrics::histogram!("pdu.size", "pdu" => stringify!($name)).record(decoded.data.len() as f64);
#[cfg(not(target_family = "wasm"))]
let deserialize_started = std::time::Instant::now();
- let pdu = Pdu::$name(deserialize(decoded.data.as_slice(), decoded.is_compressed)?);
+ let pdu = Pdu::$name(deserialize(decoded.data.as_slice(), decoded.is_compressed)?).sanitize_agent_status();
#[cfg(not(target_family = "wasm"))]
if decoded.data.len() > 64 * 1024 {
log::debug!(
@@ -1252,6 +1252,32 @@ pub enum ThinkTermSessionWorkStatus {
FinishedUnseen,
}
+impl Pdu {
+ /// Discard invalid metadata after consuming its complete frame, so a
+ /// malformed identity cannot terminate unrelated terminal traffic. Actual
+ /// framing/deserialization errors and the decoder allocation limit remain fatal.
+ fn sanitize_agent_status(mut self) -> Self {
+ match &mut self {
+ Self::AgentStatusChanged(update) => {
+ if update
+ .status
+ .as_ref()
+ .is_some_and(|status| !status.within_budget())
+ {
+ update.status = None;
+ }
+ }
+ Self::GetAgentStatusesResponse(response) => {
+ response
+ .statuses
+ .retain(|entry| entry.status.within_budget());
+ }
+ _ => {}
+ }
+ self
+ }
+}
+
/// Ask a mux server for its authoritative ThinkTerm session view.
#[derive(Deserialize, Serialize, PartialEq, Eq, Debug)]
pub struct GetThinkTermSessionState {}
@@ -2951,3 +2977,83 @@ mod image_payload_tests {
}
}
}
+
+#[cfg(test)]
+mod agent_budget_tests {
+ use super::*;
+ use thinkterm_proto::{AgentEvidence, AgentState, AgentStatus};
+
+ fn status(agent_id: String, session_id: Option<String>) -> AgentStatus {
+ AgentStatus {
+ agent_id,
+ session_id,
+ state: AgentState::Idle,
+ evidence: AgentEvidence::Contract,
+ since_unix: 42,
+ ended: false,
+ }
+ }
+ fn assert_stream_survives(message: Pdu, expected: Pdu) {
+ let mut bytes = Vec::new();
+ message.encode(&mut bytes, 1).unwrap();
+ Pdu::Ping(Ping {}).encode(&mut bytes, 2).unwrap();
+ let mut sync = std::io::Cursor::new(&bytes);
+ assert_eq!(Pdu::decode(&mut sync).unwrap().pdu, expected);
+ assert_eq!(Pdu::decode(&mut sync).unwrap().pdu, Pdu::Ping(Ping {}));
+ futures_lite::future::block_on(async {
+ let mut reader = futures_lite::io::Cursor::new(bytes);
+ assert_eq!(
+ Pdu::decode_async(&mut reader, None).await.unwrap().pdu,
+ expected
+ );
+ assert_eq!(
+ Pdu::decode_async(&mut reader, None).await.unwrap().pdu,
+ Pdu::Ping(Ping {})
+ );
+ });
+ }
+ #[test]
+ fn oversized_pushes_clear_status_without_closing_or_corrupting_the_stream() {
+ for (agent, session, accepted) in [
+ ("x".repeat(128), Some("s".repeat(512)), true),
+ ("x".repeat(129), Some("s".into()), false),
+ ("ok".into(), Some("s".repeat(513)), false),
+ ("界".repeat(43), None, false),
+ ("界".repeat(42), None, true),
+ ("ok".into(), Some("界".repeat(171)), false),
+ ] {
+ let value = status(agent, session);
+ let expected = Pdu::AgentStatusChanged(AgentStatusChanged {
+ pane_id: 1,
+ status: accepted.then(|| value.clone()),
+ });
+ assert_stream_survives(
+ Pdu::AgentStatusChanged(AgentStatusChanged {
+ pane_id: 1,
+ status: Some(value),
+ }),
+ expected,
+ );
+ }
+ }
+ #[test]
+ fn mixed_status_snapshots_keep_valid_siblings_unchanged() {
+ let valid = AgentStatusEntry {
+ pane_id: 1,
+ status: status("claude".into(), Some("session".into())),
+ title: "title".into(),
+ workspace: "workspace".into(),
+ };
+ let mut invalid = valid.clone();
+ invalid.pane_id = 2;
+ invalid.status.agent_id = "x".repeat(129);
+ assert_stream_survives(
+ Pdu::GetAgentStatusesResponse(GetAgentStatusesResponse {
+ statuses: vec![invalid.clone(), valid.clone(), invalid],
+ }),
+ Pdu::GetAgentStatusesResponse(GetAgentStatusesResponse {
+ statuses: vec![valid],
+ }),
+ );
+ }
+}
diff --git a/mux/src/agent_status/contract.rs b/mux/src/agent_status/contract.rs
index 89900f79..f51deddf 100644
--- a/mux/src/agent_status/contract.rs
+++ b/mux/src/agent_status/contract.rs
@@ -46,6 +46,9 @@ pub struct AgentContract {
}
pub fn parse(value: &str) -> Option<AgentContract> {
+ if !wezterm_term::agent_contract::agent_contract_within_budget(value) {
+ return None;
+ }
let mut fields = value.split(';');
let version = fields.next()?.trim();
// "v1" or a future minor like "v1.1" stays parseable; any other major
@@ -118,6 +121,16 @@ pub fn state_is_fresh(contract: &AgentContract, now_unix: u64) -> bool {
mod tests {
use super::*;
+ #[test]
+ fn oversized_identity_or_session_is_rejected() {
+ assert!(parse(&format!("v1;agent={};state=idle", "a".repeat(129))).is_none());
+ assert!(parse(&format!(
+ "v1;agent=claude;state=idle;session={}",
+ "s".repeat(513)
+ ))
+ .is_none());
+ }
+
#[test]
fn full_value_parses() {
let parsed =
diff --git a/mux/src/agent_status/mod.rs b/mux/src/agent_status/mod.rs
index f993401e..bc221b36 100644
--- a/mux/src/agent_status/mod.rs
+++ b/mux/src/agent_status/mod.rs
@@ -440,7 +440,10 @@ fn evaluate_pane(pane: &dyn Pane) -> bool {
let pane_id = pane.pane_id();
let user_vars = pane.copy_user_vars();
- let contract_raw = user_vars.get(contract::USER_VAR_NAME).cloned();
+ let contract_raw = user_vars
+ .get(contract::USER_VAR_NAME)
+ .filter(|value| wezterm_term::agent_contract::agent_contract_within_budget(value))
+ .cloned();
let parsed_contract = contract_raw.as_deref().and_then(contract::parse);
let now_unix = SystemTime::now()
@@ -727,7 +730,9 @@ fn evaluate_pane(pane: &dyn Pane) -> bool {
// was premature or belongs to a finished sub-session.
record.ended = c.ended && !process_backed;
}
- _ => {}
+ _ => {
+ record.session_id = None;
+ }
}
// Guarded transitions keep publishing the held state until the raw
// observation proves stable; the first classification is never held.
@@ -1109,6 +1114,31 @@ mod tests {
evict_pane(pane.pane_id());
}
+ #[test]
+ fn an_oversized_contract_clears_a_previously_retained_session() {
+ let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
+ pane.set_contract(&format!(
+ "v1;agent=claude;state=working;session=before;ts={}",
+ now_unix()
+ ));
+ evaluate_pane(pane.as_ref() as &dyn Pane);
+ assert_eq!(
+ status_for_pane(pane.pane_id())
+ .unwrap()
+ .session_id
+ .as_deref(),
+ Some("before")
+ );
+ pane.set_contract(&format!(
+ "v1;agent=claude;state=working;session={};ts={}",
+ "x".repeat(513),
+ now_unix()
+ ));
+ evaluate_pane(pane.as_ref() as &dyn Pane);
+ assert_eq!(status_for_pane(pane.pane_id()).unwrap().session_id, None);
+ evict_pane(pane.pane_id());
+ }
+
#[test]
fn screen_rules_classify_a_process_identified_pane() {
let pane = FakeAgentPane::new(Some("/usr/local/bin/claude"));
diff --git a/term/src/agent_contract.rs b/term/src/agent_contract.rs
new file mode 100644
index 00000000..a1159728
--- /dev/null
+++ b/term/src/agent_contract.rs
@@ -0,0 +1,50 @@
+//! Budgets for the agent user variable, shared by local and mirrored panes.
+//! Check before retaining a value; a rejected update clears the old value.
+pub const AGENT_USER_VAR: &str = "THINKTERM_AGENT";
+pub const MAX_AGENT_CONTRACT_BYTES: usize = 4096;
+pub const MAX_AGENT_ID_BYTES: usize = 128;
+pub const MAX_AGENT_SESSION_BYTES: usize = 512;
+
+pub fn agent_contract_within_budget(value: &str) -> bool {
+ value.len() <= MAX_AGENT_CONTRACT_BYTES
+ && value.split(';').all(|field| match field.split_once('=') {
+ Some((key, val)) => match key.trim() {
+ "agent" => val.trim().len() <= MAX_AGENT_ID_BYTES,
+ "session" => val.trim().len() <= MAX_AGENT_SESSION_BYTES,
+ _ => true,
+ },
+ None => true,
+ })
+}
+
+/// Clear an oversized contract without retaining its allocation. Other user
+/// variables are outside this contract and keep their existing behavior.
+pub fn sanitize_agent_user_var(name: &str, value: &mut String) {
+ if name == AGENT_USER_VAR && !agent_contract_within_budget(value) {
+ *value = String::new();
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[test]
+ fn limits_cover_duplicates_unknown_fields_and_multibyte_ids() {
+ assert!(agent_contract_within_budget(
+ "v1;agent=claude;state=idle;session=abc"
+ ));
+ assert!(!agent_contract_within_budget(&format!(
+ "v1;agent={};agent=ok",
+ "x".repeat(129)
+ )));
+ assert!(!agent_contract_within_budget(&format!(
+ "v1;session={}",
+ "界".repeat(171)
+ )));
+ assert!(!agent_contract_within_budget(&format!(
+ "v1;ignored={}",
+ "x".repeat(4096)
+ )));
+ assert!(agent_contract_within_budget(""));
+ }
+}
diff --git a/term/src/lib.rs b/term/src/lib.rs
index 1fdb38b8..56d68557 100644
--- a/term/src/lib.rs
+++ b/term/src/lib.rs
@@ -23,6 +23,7 @@ use std::str;
use wezterm_dynamic::{FromDynamic, ToDynamic};
use wezterm_surface::SequenceNo;
+pub mod agent_contract;
pub mod config;
pub use config::TerminalConfiguration;
diff --git a/term/src/terminalstate/performer.rs b/term/src/terminalstate/performer.rs
index 744ca592..3c3752bf 100644
--- a/term/src/terminalstate/performer.rs
+++ b/term/src/terminalstate/performer.rs
@@ -862,7 +862,8 @@ impl<'a> Performer<'a> {
self.writer.flush().ok();
}
ITermProprietary::File(image) => self.set_image(*image),
- ITermProprietary::SetUserVar { name, value } => {
+ ITermProprietary::SetUserVar { name, mut value } => {
+ crate::agent_contract::sanitize_agent_user_var(&name, &mut value);
self.user_vars.insert(name.clone(), value.clone());
if let Some(handler) = self.alert_handler.as_mut() {
handler.alert(Alert::SetUserVar { name, value });
diff --git a/term/src/terminalstate/snapshot.rs b/term/src/terminalstate/snapshot.rs
index da92855f..0e398183 100644
--- a/term/src/terminalstate/snapshot.rs
+++ b/term/src/terminalstate/snapshot.rs
@@ -492,7 +492,12 @@ impl TerminalState {
Some(url) => Some(Url::parse(&url)?),
None => None,
};
- self.user_vars = identity.user_vars.into_iter().collect();
+ self.user_vars = identity.user_vars.into_iter()
+ .map(|(name, mut value)| {
+ crate::agent_contract::sanitize_agent_user_var(&name, &mut value);
+ (name, value)
+ })
+ .collect();
self.progress = identity.progress;
self.agent_osc_title = identity.agent_osc_title;
self.agent_osc_progress = identity.agent_osc_progress;
diff --git a/term/src/test/graphics.rs b/term/src/test/graphics.rs
index a5d7981a..d52d78f0 100644
--- a/term/src/test/graphics.rs
+++ b/term/src/test/graphics.rs
@@ -1067,7 +1067,7 @@ fn appended_animation_frames_stay_within_the_image_budget() {
}
/// Standard base64 for test payloads; the crate has no encoder of its own.
-fn base64_of(bytes: &[u8]) -> String {
+pub(super) fn base64_of(bytes: &[u8]) -> String {
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let mut out = String::new();
for chunk in bytes.chunks(3) {
diff --git a/term/src/test/mod.rs b/term/src/test/mod.rs
index c39c9fbf..cacf5171 100644
--- a/term/src/test/mod.rs
+++ b/term/src/test/mod.rs
@@ -1569,3 +1569,29 @@ fn the_writer_handle_keeps_the_terminals_order() {
}
assert_eq!(sink.0.lock().unwrap().clone(), expected);
}
+
+#[test]
+fn oversized_agent_updates_clear_retained_identity_but_normal_updates_survive() {
+ let mut term = TestTerm::new(3, 20, 10);
+ let normal = "v1;agent=soul;state=working;session=test";
+ for value in [
+ normal.to_string(),
+ format!("v1;agent={}", "x".repeat(129)),
+ normal.into(),
+ format!("v1;session={}", "x".repeat(513)),
+ ] {
+ let encoded = graphics::base64_of(value.as_bytes());
+ term.print(format!(
+ "\x1b]1337;SetUserVar=THINKTERM_AGENT={encoded}\x07"
+ ));
+ let expected = if crate::agent_contract::agent_contract_within_budget(&value) {
+ value.as_str()
+ } else {
+ ""
+ };
+ assert_eq!(
+ term.user_vars().get("THINKTERM_AGENT").map(String::as_str),
+ Some(expected)
+ );
+ }
+}
diff --git a/term/src/test/snapshot.rs b/term/src/test/snapshot.rs
index 0fa3d47b..df44d797 100644
--- a/term/src/test/snapshot.rs
+++ b/term/src/test/snapshot.rs
@@ -379,3 +379,40 @@ fn a_snapshot_needs_a_terminal_of_its_size() {
let err = small.restore(snapshot).expect_err("refused");
assert!(format!("{err:#}").contains("80x24"), "{err:#}");
}
+
+#[test]
+fn restore_applies_agent_budgets_without_changing_other_user_variables() {
+ for contract in [
+ format!("v1;agent={}", "x".repeat(129)),
+ format!("v1;session={}", "s".repeat(513)),
+ "x".repeat(1024 * 1024),
+ ] {
+ let mut snapshot = terminal(10).snapshot();
+ snapshot
+ .identity
+ .user_vars
+ .insert("THINKTERM_AGENT".into(), contract);
+ snapshot
+ .identity
+ .user_vars
+ .insert("ordinary".into(), "kept".into());
+ let restored = restored(snapshot, 10);
+ let cleared = restored.user_vars().get("THINKTERM_AGENT").unwrap();
+ assert!(cleared.is_empty());
+ assert_eq!(cleared.capacity(), 0);
+ assert_eq!(restored.user_vars().get("ordinary").unwrap(), "kept");
+ }
+ let mut snapshot = terminal(10).snapshot();
+ let normal = "v1;agent=claude;state=idle;session=abc";
+ snapshot
+ .identity
+ .user_vars
+ .insert("THINKTERM_AGENT".into(), normal.into());
+ assert_eq!(
+ restored(snapshot, 10)
+ .user_vars()
+ .get("THINKTERM_AGENT")
+ .unwrap(),
+ normal
+ );
+}
diff --git a/thinkterm-proto/src/agent.rs b/thinkterm-proto/src/agent.rs
index fd9c235f..17a1386b 100644
--- a/thinkterm-proto/src/agent.rs
+++ b/thinkterm-proto/src/agent.rs
@@ -47,3 +47,14 @@ pub struct AgentStatus {
/// should not rely on ever observing it.
pub ended: bool,
}
+
+impl AgentStatus {
+ /// Metadata budgets do not change identity bytes or the wire layout.
+ pub fn within_budget(&self) -> bool {
+ self.agent_id.len() <= wezterm_term::agent_contract::MAX_AGENT_ID_BYTES
+ && self
+ .session_id
+ .as_ref()
+ .is_none_or(|id| id.len() <= wezterm_term::agent_contract::MAX_AGENT_SESSION_BYTES)
+ }
+}
diff --git a/wezterm-client/src/domain.rs b/wezterm-client/src/domain.rs
index 06568bf7..4fb47f68 100644
--- a/wezterm-client/src/domain.rs
+++ b/wezterm-client/src/domain.rs
@@ -1120,7 +1120,7 @@ impl ClientInner {
status: Option<thinkterm_proto::AgentStatus>,
) {
let mut map = self.remote_agent_statuses.lock().unwrap();
- match status {
+ match status.filter(|s| s.within_budget()) {
Some(status) => {
map.insert(remote_pane_id, status);
}
diff --git a/wezterm-client/src/pane/clientpane.rs b/wezterm-client/src/pane/clientpane.rs
index 5cac9c2a..933b355a 100644
--- a/wezterm-client/src/pane/clientpane.rs
+++ b/wezterm-client/src/pane/clientpane.rs
@@ -85,7 +85,7 @@ impl ClientPane {
/// cold-start fetch on attach/resync). Quiet: the caller decides
/// whether a repaint is warranted.
pub fn set_agent_status(&self, status: Option<thinkterm_proto::AgentStatus>) {
- *self.agent_status.lock() = status;
+ *self.agent_status.lock() = status.filter(|s| s.within_budget());
}
/// Ask the (single) sender worker to bring the server to `palette`.
@@ -326,7 +326,10 @@ impl ClientPane {
.alert(self.local_pane_id, Alert::PaletteChanged);
}
}
- Pdu::NotifyAlert(NotifyAlert { alert, .. }) => {
+ Pdu::NotifyAlert(NotifyAlert { mut alert, .. }) => {
+ if let Alert::SetUserVar { name, value } = &mut alert {
+ wezterm_term::agent_contract::sanitize_agent_user_var(name, value);
+ }
match &alert {
Alert::SetUserVar { name, value } => {
self.user_vars.lock().insert(name.clone(), value.clone());
@@ -348,6 +351,7 @@ impl ClientPane {
self.host.events().alert(self.local_pane_id, alert);
}
Pdu::AgentStatusChanged(codec::AgentStatusChanged { status, .. }) => {
+ let status = status.filter(|s| s.within_budget());
// Read-at-send-time coalescing means a backlog of queued
// notifications all carry the same current value; only a
// real change is worth a re-notify (each one repaints and