web-cortex-framework 2.6.0__tar.gz → 2.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/Cargo.lock +4 -4
  2. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/Cargo.toml +1 -1
  3. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/PKG-INFO +2 -2
  4. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/README.md +1 -1
  5. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/agent/session.rs +76 -5
  6. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/agent.rs +92 -4
  7. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/app.rs +81 -6
  8. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/errors.rs +6 -0
  9. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/http.rs +55 -8
  10. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/manifest.rs +17 -0
  11. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/mcp.rs +9 -0
  12. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/server.rs +121 -5
  13. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/ws.rs +139 -16
  14. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/tests/diagnostics.rs +3 -1
  15. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-py/src/lib.rs +3 -0
  16. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/pyproject.toml +1 -1
  17. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/__init__.py +1 -1
  18. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/_bridge.py +173 -16
  19. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/app.py +47 -3
  20. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/LICENSE +0 -0
  21. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/Cargo.toml +0 -0
  22. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/agent/provider.rs +0 -0
  23. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/agent/registry.rs +0 -0
  24. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/agent/vision.rs +0 -0
  25. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/audit.rs +0 -0
  26. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/auth.rs +0 -0
  27. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/bridge.rs +0 -0
  28. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/context.rs +0 -0
  29. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/db.rs +0 -0
  30. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/devices.rs +0 -0
  31. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/files.rs +0 -0
  32. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/flow.rs +0 -0
  33. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/ledger.rs +0 -0
  34. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/lib.rs +0 -0
  35. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/middleware.rs +0 -0
  36. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/openapi.rs +0 -0
  37. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/router.rs +0 -0
  38. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/status.rs +0 -0
  39. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/templates.rs +0 -0
  40. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-core/src/typegen.rs +0 -0
  41. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-py/Cargo.toml +0 -0
  42. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/crates/webcortex-py/src/behaviour.rs +0 -0
  43. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/cli.py +0 -0
  44. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/client.py +0 -0
  45. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/contextpack.py +0 -0
  46. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/diagnostics.py +0 -0
  47. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/errors.py +0 -0
  48. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/media.py +0 -0
  49. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/schema.py +0 -0
  50. {web_cortex_framework-2.6.0 → web_cortex_framework-2.7.0}/python/webcortex/starters.py +0 -0
@@ -252,9 +252,9 @@ dependencies = [
252
252
 
253
253
  [[package]]
254
254
  name = "ctutils"
255
- version = "0.4.2"
255
+ version = "0.4.6"
256
256
  source = "registry+https://github.com/rust-lang/crates.io-index"
257
- checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
257
+ checksum = "fe3e9d21d39e6f39ff46e03d5b621424f88ee23d8a1672c6bfc9ccc7f2da4f6a"
258
258
  dependencies = [
259
259
  "cmov",
260
260
  ]
@@ -2662,7 +2662,7 @@ dependencies = [
2662
2662
 
2663
2663
  [[package]]
2664
2664
  name = "webcortex-core"
2665
- version = "2.6.0"
2665
+ version = "2.7.0"
2666
2666
  dependencies = [
2667
2667
  "base64 0.23.1",
2668
2668
  "bytes",
@@ -2690,7 +2690,7 @@ dependencies = [
2690
2690
 
2691
2691
  [[package]]
2692
2692
  name = "webcortex-py"
2693
- version = "2.6.0"
2693
+ version = "2.7.0"
2694
2694
  dependencies = [
2695
2695
  "bytes",
2696
2696
  "futures",
@@ -3,7 +3,7 @@ members = ["crates/webcortex-core", "crates/webcortex-py"]
3
3
  resolver = "3"
4
4
 
5
5
  [workspace.package]
6
- version = "2.6.0"
6
+ version = "2.7.0"
7
7
  edition = "2024"
8
8
  license = "Apache-2.0"
9
9
  rust-version = "1.88"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: web-cortex-framework
3
- Version: 2.6.0
3
+ Version: 2.7.0
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: Apache Software License
@@ -527,7 +527,7 @@ tested, the known limits, and what v2 added to the surface.
527
527
 
528
528
  ## Status
529
529
 
530
- v2.6.0. Working and tested: the manifest IR, router, native ops (static /
530
+ v2.7.0. Working and tested: the manifest IR, router, native ops (static /
531
531
  query / proxy / page / files / flow), the free-threaded Python bridge,
532
532
  authentication and scopes, rate limiting, CORS, security headers, graceful
533
533
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -499,7 +499,7 @@ tested, the known limits, and what v2 added to the surface.
499
499
 
500
500
  ## Status
501
501
 
502
- v2.6.0. Working and tested: the manifest IR, router, native ops (static /
502
+ v2.7.0. Working and tested: the manifest IR, router, native ops (static /
503
503
  query / proxy / page / files / flow), the free-threaded Python bridge,
504
504
  authentication and scopes, rate limiting, CORS, security headers, graceful
505
505
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -12,7 +12,8 @@
12
12
  use super::{Conversation, Message};
13
13
  use serde_json::Value;
14
14
  use std::collections::HashMap;
15
- use std::sync::Mutex;
15
+ use std::sync::atomic::{AtomicU64, Ordering};
16
+ use std::sync::{Arc, Mutex};
16
17
  use std::time::{Duration, Instant};
17
18
 
18
19
  /// Most messages one session keeps. The store is capped by count, but each
@@ -72,6 +73,13 @@ pub fn bound(conversation: &mut Conversation) -> usize {
72
73
 
73
74
  pub struct SessionStore {
74
75
  inner: Mutex<HashMap<String, Entry>>,
76
+ /// One lock per session with a turn in flight. Two turns on one session
77
+ /// each loaded the same history and the second to finish overwrote the
78
+ /// first; a turn now waits for the one ahead of it.
79
+ turns: Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>,
80
+ /// Source of [`Entry::revision`]: store-wide, so a session that is
81
+ /// forgotten and saved again never repeats an earlier revision.
82
+ revisions: AtomicU64,
75
83
  capacity: usize,
76
84
  ttl: Duration,
77
85
  }
@@ -79,12 +87,20 @@ pub struct SessionStore {
79
87
  struct Entry {
80
88
  conversation: Conversation,
81
89
  touched: Instant,
90
+ revision: u64,
91
+ }
92
+
93
+ /// Held for the length of one turn on a session; see [`SessionStore::lock_turn`].
94
+ pub struct TurnGuard {
95
+ _guard: tokio::sync::OwnedMutexGuard<()>,
82
96
  }
83
97
 
84
98
  impl SessionStore {
85
99
  pub fn new(capacity: usize, ttl_secs: u64) -> Self {
86
100
  Self {
87
101
  inner: Mutex::new(HashMap::new()),
102
+ turns: Mutex::new(HashMap::new()),
103
+ revisions: AtomicU64::new(0),
88
104
  capacity: capacity.max(1),
89
105
  ttl: Duration::from_secs(ttl_secs.max(1)),
90
106
  }
@@ -95,21 +111,44 @@ impl SessionStore {
95
111
  }
96
112
 
97
113
  pub fn load(&self, key: &str) -> Option<Conversation> {
114
+ self.load_with_revision(key).0
115
+ }
116
+
117
+ /// The session and its revision, which changes on every save. A missing
118
+ /// or expired session is revision 0.
119
+ pub fn load_with_revision(&self, key: &str) -> (Option<Conversation>, u64) {
98
120
  let mut map = self.lock();
99
121
  let now = Instant::now();
100
122
  match map.get_mut(key) {
101
123
  Some(e) if now.duration_since(e.touched) <= self.ttl => {
102
124
  e.touched = now;
103
- Some(e.conversation.clone())
125
+ (Some(e.conversation.clone()), e.revision)
104
126
  }
105
127
  Some(_) => {
106
128
  map.remove(key);
107
- None
129
+ (None, 0)
108
130
  }
109
- None => None,
131
+ None => (None, 0),
110
132
  }
111
133
  }
112
134
 
135
+ /// Wait for any other turn on `key` to finish, then hold the session until
136
+ /// the guard drops. Turns on one session run one after another, in the
137
+ /// order they arrived (tokio's mutex is fair).
138
+ pub async fn lock_turn(&self, key: &str) -> TurnGuard {
139
+ let lock = {
140
+ let mut turns = match self.turns.lock() {
141
+ Ok(g) => g,
142
+ Err(p) => p.into_inner(),
143
+ };
144
+ // Drop the locks no turn holds or waits on, so the map is bounded
145
+ // by the turns in flight rather than by every session ever seen.
146
+ turns.retain(|k, l| k == key || Arc::strong_count(l) > 1);
147
+ turns.entry(key.to_string()).or_default().clone()
148
+ };
149
+ TurnGuard { _guard: lock.lock_owned().await }
150
+ }
151
+
113
152
  pub fn save(&self, key: String, mut conversation: Conversation) {
114
153
  let dropped = bound(&mut conversation);
115
154
  if dropped > 0 {
@@ -128,7 +167,8 @@ impl SessionStore {
128
167
  map.remove(&oldest);
129
168
  }
130
169
  }
131
- map.insert(key, Entry { conversation, touched: now });
170
+ let revision = self.revisions.fetch_add(1, Ordering::Relaxed) + 1;
171
+ map.insert(key, Entry { conversation, touched: now, revision });
132
172
  }
133
173
 
134
174
  pub fn forget(&self, key: &str) -> bool {
@@ -216,6 +256,37 @@ mod tests {
216
256
  assert_eq!(bound(&mut small), 0, "a small session is untouched");
217
257
  }
218
258
 
259
+ #[test]
260
+ fn every_save_moves_the_revision() {
261
+ let s = SessionStore::new(10, 60);
262
+ assert_eq!(s.load_with_revision("k").1, 0);
263
+ s.save("k".into(), conv(1));
264
+ let first = s.load_with_revision("k").1;
265
+ s.save("k".into(), conv(2));
266
+ let second = s.load_with_revision("k").1;
267
+ assert!(first > 0 && second > first);
268
+ s.forget("k");
269
+ s.save("k".into(), conv(1));
270
+ assert!(s.load_with_revision("k").1 > second, "a re-created session never repeats a revision");
271
+ }
272
+
273
+ #[tokio::test]
274
+ async fn turns_on_one_session_run_one_at_a_time() {
275
+ let s = Arc::new(SessionStore::new(10, 60));
276
+ let first = s.lock_turn("k").await;
277
+ let waiting = tokio::spawn({
278
+ let s = s.clone();
279
+ async move { s.lock_turn("k").await; }
280
+ });
281
+ let _other = s.lock_turn("other").await;
282
+ tokio::time::sleep(Duration::from_millis(50)).await;
283
+ assert!(!waiting.is_finished(), "a second turn on the same session must wait");
284
+ drop(first);
285
+ tokio::time::timeout(Duration::from_secs(2), waiting).await.unwrap().unwrap();
286
+ let _ = s.lock_turn("k").await;
287
+ assert!(s.turns.lock().unwrap().len() <= 2, "idle locks are dropped");
288
+ }
289
+
219
290
  #[test]
220
291
  fn capacity_evicts_the_least_recently_used() {
221
292
  let s = SessionStore::new(2, 60);
@@ -346,6 +346,12 @@ struct RunState {
346
346
  /// Where the conversation is saved: the session id scoped by the entry
347
347
  /// agent and the caller, so another principal's id cannot reach it.
348
348
  session_key: Option<String>,
349
+ /// The revision of the session this run loaded (0 for none), and where in
350
+ /// `conversation` this turn's own messages start. A run resumed after an
351
+ /// approval checks the revision: if other turns were saved meanwhile, its
352
+ /// turn is moved onto the newer history instead of overwriting it.
353
+ session_rev: u64,
354
+ turn_start: usize,
349
355
  /// Where step events go, and how many steps have been sent.
350
356
  events: Option<tokio::sync::mpsc::UnboundedSender<Value>>,
351
357
  emitted: usize,
@@ -410,14 +416,26 @@ impl AgentRuntime {
410
416
  .session_id
411
417
  .as_ref()
412
418
  .map(|sid| SessionStore::key(&def.name, &caller.id, sid));
413
- let mut conversation = match (&session_key, opts.reset_session) {
414
- (Some(key), false) => app.sessions().load(key).unwrap_or_default(),
419
+ // A top-level turn holds its session until it finishes, so a second
420
+ // turn on it waits rather than racing it. A nested run (an agent
421
+ // reached as a tool) is already inside its caller's turn and does not
422
+ // wait, which would deadlock an agent that calls itself.
423
+ let _turn = match (&session_key, opts.depth) {
424
+ (Some(key), 0) => Some(app.sessions().lock_turn(key).await),
425
+ _ => None,
426
+ };
427
+ let (mut conversation, session_rev) = match (&session_key, opts.reset_session) {
428
+ (Some(key), false) => {
429
+ let (c, rev) = app.sessions().load_with_revision(key);
430
+ (c.unwrap_or_default(), rev)
431
+ }
415
432
  (Some(key), true) => {
416
433
  app.sessions().forget(key);
417
- Conversation::default()
434
+ (Conversation::default(), 0)
418
435
  }
419
- _ => Conversation::default(),
436
+ _ => (Conversation::default(), 0),
420
437
  };
438
+ let turn_start = conversation.messages.len();
421
439
  let content = if opts.images.is_empty() {
422
440
  json!(input)
423
441
  } else {
@@ -486,6 +504,8 @@ impl AgentRuntime {
486
504
  compaction_retry_at: 0,
487
505
  session_id: opts.session_id,
488
506
  session_key,
507
+ session_rev,
508
+ turn_start,
489
509
  events: opts.events,
490
510
  emitted: 0,
491
511
  cost_usd: Some(0.0),
@@ -513,6 +533,11 @@ impl AgentRuntime {
513
533
  ) -> RunResult {
514
534
  let SuspendedRun { state: mut st, calls, gated, mut results, approval_id, .. } = suspended;
515
535
  let call = &calls[gated];
536
+ let _turn = match (&st.session_key, st.depth) {
537
+ (Some(key), 0) => Some(app.sessions().lock_turn(key).await),
538
+ _ => None,
539
+ };
540
+ rebase_onto_session(app, &mut st);
516
541
  app.recorder().run_started(&st.run_id, &st.def.name, &st.caller.id, st.depth);
517
542
  // The approved call runs before `drive` does; dropped there, the run
518
543
  // is cancelled just the same.
@@ -974,6 +999,9 @@ impl AgentRuntime {
974
999
  let summary = response.text;
975
1000
 
976
1001
  let before = st.conversation.messages.len();
1002
+ // This turn's messages move with the cut; a turn whose start was
1003
+ // summarised now starts at the summary.
1004
+ st.turn_start = if st.turn_start >= cut { st.turn_start - cut + 1 } else { 0 };
977
1005
  let tail = st.conversation.messages.split_off(cut);
978
1006
  st.conversation.messages = vec![Message {
979
1007
  role: "user".into(),
@@ -1193,6 +1221,24 @@ impl AgentRuntime {
1193
1221
  // Helpers
1194
1222
  // ---------------------------------------------------------------------------
1195
1223
 
1224
+ /// Before a suspended run continues, move its turn onto the session as it is
1225
+ /// now. Turns saved while it waited for a human (or a reset) would otherwise
1226
+ /// be overwritten when it finished, since it carried the history from before
1227
+ /// it suspended. Called with the session's turn lock held.
1228
+ fn rebase_onto_session(app: &App, st: &mut RunState) {
1229
+ let Some(key) = &st.session_key else { return };
1230
+ let (current, rev) = app.sessions().load_with_revision(key);
1231
+ if rev == st.session_rev {
1232
+ return;
1233
+ }
1234
+ let turn = st.conversation.messages.split_off(st.turn_start.min(st.conversation.messages.len()));
1235
+ let mut base = current.unwrap_or_default();
1236
+ st.turn_start = base.messages.len();
1237
+ base.messages.extend(turn);
1238
+ st.conversation = base;
1239
+ st.session_rev = rev;
1240
+ }
1241
+
1196
1242
  /// The catalogued code a run's outcome carries: none for a run that completed
1197
1243
  /// or is waiting on a human; the failing step's code for a failure.
1198
1244
  fn outcome_code(status: RunStatus, steps: &[Step]) -> Option<&'static str> {
@@ -1757,6 +1803,48 @@ mod tests {
1757
1803
  assert_eq!(provider.snapshots()[2].message_count, 1);
1758
1804
  }
1759
1805
 
1806
+ #[tokio::test]
1807
+ async fn a_turn_waits_for_the_turn_ahead_of_it_on_the_same_session() {
1808
+ let (app, _, provider) = app_with(ScriptedProvider::text("ok")).await;
1809
+ let held = app.sessions().lock_turn(&SessionStore::key("a", "u1", "s")).await;
1810
+ let opts = RunOptions { session_id: Some("s".into()), ..Default::default() };
1811
+ let turn = tokio::spawn({
1812
+ let app = app.clone();
1813
+ async move { app.invoke_agent("a", "hi", &caller(&[]), opts).await.unwrap() }
1814
+ });
1815
+ tokio::time::sleep(std::time::Duration::from_millis(50)).await;
1816
+ assert_eq!(provider.calls(), 0, "the second turn started while the first held the session");
1817
+ drop(held);
1818
+ let out = tokio::time::timeout(std::time::Duration::from_secs(2), turn).await.unwrap().unwrap();
1819
+ assert_eq!(out.status, RunStatus::Completed);
1820
+ }
1821
+
1822
+ #[tokio::test]
1823
+ async fn a_resumed_approval_keeps_the_turns_saved_while_it_waited() {
1824
+ // 2.6.0: the resumed run saved the history it suspended with, and the
1825
+ // turn taken while it waited was lost.
1826
+ let (app, _, provider) = app_with(ScriptedProvider::sequence(vec![
1827
+ ("tool", "danger", json!({})),
1828
+ ("text", "two", json!(null)),
1829
+ ("text", "approved", json!(null)),
1830
+ ]))
1831
+ .await;
1832
+ let opts = RunOptions { session_id: Some("s".into()), ..Default::default() };
1833
+ let first = app.invoke_agent("a", "first", &caller(&["*"]), opts.clone()).await.unwrap();
1834
+ let id = first.pending_approval.expect("suspended").approval_id;
1835
+ let second = app.invoke_agent("a", "second", &caller(&["*"]), opts).await.unwrap();
1836
+ assert_eq!(second.output, "two");
1837
+
1838
+ let resumed = app.resolve_approval(&id, true, "", &caller(&["*"])).await.unwrap();
1839
+ assert_eq!(resumed.output, "approved");
1840
+ assert_eq!(provider.snapshots()[2].message_count, 5, "the resumed step sees the newer turn");
1841
+ let kept = app.sessions().load(&SessionStore::key("a", "u1", "s")).unwrap().messages;
1842
+ let texts: Vec<String> = kept.iter().map(|m| render_message(&m.content)).collect();
1843
+ assert_eq!(kept.len(), 6, "{texts:?}");
1844
+ assert_eq!((texts[0].as_str(), texts[1].as_str()), ("second", "two"));
1845
+ assert_eq!((texts[2].as_str(), texts[5].as_str()), ("first", "approved"));
1846
+ }
1847
+
1760
1848
  #[tokio::test]
1761
1849
  async fn a_provider_error_fails_the_run_without_panicking() {
1762
1850
  let (app, audit, _) = app_with(ScriptedProvider::error("upstream exploded")).await;
@@ -60,8 +60,16 @@ pub struct App {
60
60
  devices: crate::devices::DeviceHub,
61
61
  /// Request counters, recent failures and agent runs: the live view.
62
62
  recorder: crate::status::Recorder,
63
+ /// One permit per open connection or WebSocket; `None` when uncapped.
64
+ connections: Option<Arc<tokio::sync::Semaphore>>,
65
+ /// Flipped once at shutdown. Every WebSocket holds a receiver, so "no
66
+ /// receivers left" is "every socket has said goodbye".
67
+ shutdown: tokio::sync::watch::Sender<bool>,
63
68
  }
64
69
 
70
+ /// A connection's place under `max_connections`, released on drop.
71
+ pub struct ConnectionSlot(#[allow(dead_code)] Option<tokio::sync::OwnedSemaphorePermit>);
72
+
65
73
  impl App {
66
74
  pub async fn build(manifest: Manifest, bridge: Arc<dyn PyBridge>) -> Result<Self, String> {
67
75
  manifest.validate()?;
@@ -167,6 +175,7 @@ impl App {
167
175
  .build()
168
176
  .map_err(|e| format!("http client build failed: {e}"))?;
169
177
  let manifest_start_halted = manifest.server.start_halted;
178
+ let manifest_max_connections = manifest.server.max_connections;
170
179
  let devices = crate::devices::DeviceHub::new(&manifest.devices, client.clone());
171
180
  let recorder = crate::status::Recorder::new(&manifest);
172
181
 
@@ -204,11 +213,39 @@ impl App {
204
213
  serde_json::json!({"reason": "started halted; release to enable actuators",
205
214
  "by": "boot", "since_unix": since})
206
215
  }))),
216
+ connections: (manifest_max_connections > 0)
217
+ .then(|| Arc::new(tokio::sync::Semaphore::new(manifest_max_connections))),
218
+ shutdown: tokio::sync::watch::Sender::new(false),
207
219
  devices,
208
220
  recorder,
209
221
  })
210
222
  }
211
223
 
224
+ /// Claim a place for a new connection, or `None` when `max_connections`
225
+ /// are already open.
226
+ pub fn admit_connection(&self) -> Option<ConnectionSlot> {
227
+ match &self.connections {
228
+ None => Some(ConnectionSlot(None)),
229
+ Some(sem) => sem.clone().try_acquire_owned().ok().map(|p| ConnectionSlot(Some(p))),
230
+ }
231
+ }
232
+
233
+ /// Resolves once shutdown has begun. Held by each WebSocket.
234
+ pub fn shutdown_watch(&self) -> tokio::sync::watch::Receiver<bool> {
235
+ self.shutdown.subscribe()
236
+ }
237
+
238
+ /// Tell every WebSocket to close (1001), then wait until they all have.
239
+ pub async fn close_sockets(&self) {
240
+ self.shutdown.send_replace(true);
241
+ self.shutdown.closed().await;
242
+ }
243
+
244
+ /// How many WebSockets are open.
245
+ pub fn open_sockets(&self) -> usize {
246
+ self.shutdown.receiver_count()
247
+ }
248
+
212
249
  /// Wrap in an `Arc` and record the self-reference behaviours need.
213
250
  ///
214
251
  /// Always use this rather than `Arc::new(app)`: a behaviour dispatched from
@@ -803,7 +840,11 @@ impl App {
803
840
  tool: Some(name.to_string()),
804
841
  detail: serde_json::json!({"error": &e}),
805
842
  });
806
- Ok(WebCortexResponse::coded(500, "WC003", e))
843
+ // A failure the bridge already coded ("WC406: …") keeps its code.
844
+ let code = crate::errors::code_in(e.get(..6).unwrap_or_default())
845
+ .filter(|_| e.as_bytes().get(5) == Some(&b':'))
846
+ .unwrap_or("WC003");
847
+ Ok(WebCortexResponse::coded(500, code, e))
807
848
  }
808
849
  }
809
850
  }
@@ -1010,8 +1051,9 @@ impl App {
1010
1051
  builder = builder.header(k, v);
1011
1052
  }
1012
1053
  }
1013
- if !req.query.is_empty() {
1014
- builder = builder.query(&req.query.iter().collect::<Vec<_>>());
1054
+ let pairs = req.query_pairs();
1055
+ if !pairs.is_empty() {
1056
+ builder = builder.query(&pairs);
1015
1057
  }
1016
1058
  if !req.body.is_empty() {
1017
1059
  builder = builder.body(req.body.clone());
@@ -1033,10 +1075,34 @@ impl App {
1033
1075
  .and_then(|v| v.to_str().ok())
1034
1076
  .unwrap_or("application/json")
1035
1077
  .to_string();
1036
- let body = res
1037
- .bytes()
1078
+ // Buffered, so bounded: a declared length over the cap is refused
1079
+ // before reading, and an undeclared one is cut off once it passes it.
1080
+ let cap = up.max_response_bytes;
1081
+ let too_large = || {
1082
+ tracing::warn!(upstream = %upstream_name, max_response_bytes = cap,
1083
+ "upstream response over max_response_bytes; not relayed");
1084
+ Ok(WebCortexResponse::coded(
1085
+ 502,
1086
+ "WC217",
1087
+ format!("upstream {upstream_name} answered with more than {cap} bytes"),
1088
+ ))
1089
+ };
1090
+ if res.content_length().is_some_and(|n| n > cap as u64) {
1091
+ return too_large();
1092
+ }
1093
+ let mut res = res;
1094
+ let mut buf = bytes::BytesMut::new();
1095
+ while let Some(chunk) = res
1096
+ .chunk()
1038
1097
  .await
1039
- .map_err(|e| format!("upstream {upstream_name} body read failed: {}", e.without_url()))?;
1098
+ .map_err(|e| format!("upstream {upstream_name} body read failed: {}", e.without_url()))?
1099
+ {
1100
+ if buf.len() + chunk.len() > cap {
1101
+ return too_large();
1102
+ }
1103
+ buf.extend_from_slice(&chunk);
1104
+ }
1105
+ let body = buf.freeze();
1040
1106
 
1041
1107
  Ok(WebCortexResponse {
1042
1108
  status,
@@ -1146,10 +1212,18 @@ impl App {
1146
1212
  };
1147
1213
 
1148
1214
  let mut query = std::collections::BTreeMap::new();
1215
+ let mut query_all = Vec::new();
1149
1216
  if body_less {
1150
1217
  for (k, v) in &obj {
1151
1218
  if !path_params.contains_key(k) {
1152
1219
  query.insert(k.clone(), json_to_path_string(v));
1220
+ // A list argument is the repeated key an HTTP caller would send.
1221
+ match v {
1222
+ serde_json::Value::Array(items) => {
1223
+ query_all.extend(items.iter().map(|i| (k.clone(), json_to_path_string(i))))
1224
+ }
1225
+ _ => query_all.push((k.clone(), json_to_path_string(v))),
1226
+ }
1153
1227
  }
1154
1228
  }
1155
1229
  }
@@ -1159,6 +1233,7 @@ impl App {
1159
1233
  path: concrete_path,
1160
1234
  path_params,
1161
1235
  query,
1236
+ query_all,
1162
1237
  headers: Default::default(),
1163
1238
  body,
1164
1239
  route_id: Some(route_id),
@@ -110,6 +110,10 @@ pub static CATALOGUE: &[ErrorInfo] = &[
110
110
  "A subsystem this route needs is not running in this process (for example the agent runtime). Check the server log at boot."),
111
111
  e!("WC216", "http", Some(408), "Request body too slow",
112
112
  "The client announced a body but did not finish sending it within request_timeout (agent_timeout on agent, behaviour and flow routes). Send the whole body promptly, or raise the limit on WebCortex(...)."),
113
+ e!("WC217", "http", Some(502), "Upstream response too large",
114
+ "A proxied upstream answered with a body over its max_response_bytes (64 MiB by default). Raise it on app.upstream(..., max_response_bytes=...) or page the upstream's response."),
115
+ e!("WC218", "http", Some(503), "Too many connections",
116
+ "The server already holds max_connections open connections (10,000 by default), WebSockets included. Retry shortly, close idle connections, or raise max_connections on WebCortex(...)."),
113
117
 
114
118
  // ---- WC3xx agents and providers -------------------------------------
115
119
  e!("WC300", "agent", Some(502), "Agent run failed",
@@ -160,6 +164,8 @@ pub static CATALOGUE: &[ErrorInfo] = &[
160
164
  "The run used max_steps before the model stopped asking for tools. Raise max_steps, or give the agent fewer, sharper tools."),
161
165
  e!("WC405", "limits", None, "MCP batch too large",
162
166
  "A JSON-RPC batch may hold at most 32 messages. Split it."),
167
+ e!("WC406", "limits", Some(500), "Returned generator too large",
168
+ "A handler, behaviour or tool returned a generator (or other lazy iterable) that went past WEBCORTEX_MAX_RESULT_ITEMS (default 100000) or WEBCORTEX_MAX_RESULT_BYTES (default 64 MiB). A response is sent whole, so return a bounded result: page it, or raise the limits."),
163
169
 
164
170
  // ---- WC5xx devices and actuators ------------------------------------
165
171
  e!("WC501", "devices", Some(404), "Unknown device",
@@ -13,7 +13,11 @@ pub struct WebCortexRequest {
13
13
  pub method: String,
14
14
  pub path: String,
15
15
  pub path_params: BTreeMap<String, String>,
16
+ /// One value per key: the last, when a key repeats.
16
17
  pub query: BTreeMap<String, String>,
18
+ /// Every query pair in order, repeats included (`?tag=a&tag=b`). Empty for
19
+ /// synthetic requests that only set [`Self::query`].
20
+ pub query_all: Vec<(String, String)>,
17
21
  pub headers: BTreeMap<String, String>,
18
22
  pub body: Bytes,
19
23
  /// Set once the router has matched. `None` for synthetic in-process calls.
@@ -40,6 +44,7 @@ impl WebCortexRequest {
40
44
  path: path.to_string(),
41
45
  path_params: BTreeMap::new(),
42
46
  query: BTreeMap::new(),
47
+ query_all: Vec::new(),
43
48
  headers: BTreeMap::new(),
44
49
  body: Bytes::new(),
45
50
  route_id: None,
@@ -255,16 +260,40 @@ impl WebCortexResponse {
255
260
  }
256
261
  }
257
262
 
263
+ /// The query string as a map: a repeated key keeps its last value.
258
264
  pub fn parse_query(raw: &str) -> BTreeMap<String, String> {
259
- let mut out = BTreeMap::new();
260
- for pair in raw.split('&').filter(|s| !s.is_empty()) {
261
- let (k, v) = match pair.split_once('=') {
262
- Some((k, v)) => (k, v),
263
- None => (pair, ""),
264
- };
265
- out.insert(percent_decode(k, true), percent_decode(v, true));
265
+ parse_query_pairs(raw).into_iter().collect()
266
+ }
267
+
268
+ /// Every pair in the query string, in order, repeats included.
269
+ pub fn parse_query_pairs(raw: &str) -> Vec<(String, String)> {
270
+ raw.split('&')
271
+ .filter(|s| !s.is_empty())
272
+ .map(|pair| {
273
+ let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
274
+ (percent_decode(k, true), percent_decode(v, true))
275
+ })
276
+ .collect()
277
+ }
278
+
279
+ impl WebCortexRequest {
280
+ /// Every value given for a query key, in order. Falls back to the single
281
+ /// value in [`Self::query`] for a request built without the pairs.
282
+ pub fn query_values(&self, name: &str) -> Vec<&str> {
283
+ if self.query_all.is_empty() {
284
+ return self.query.get(name).map(String::as_str).into_iter().collect();
285
+ }
286
+ self.query_all.iter().filter(|(k, _)| k == name).map(|(_, v)| v.as_str()).collect()
287
+ }
288
+
289
+ /// The pairs to forward: all of them when known, else the map.
290
+ pub fn query_pairs(&self) -> Vec<(&str, &str)> {
291
+ if self.query_all.is_empty() {
292
+ self.query.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect()
293
+ } else {
294
+ self.query_all.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect()
295
+ }
266
296
  }
267
- out
268
297
  }
269
298
 
270
299
  /// Decode `%XX` escapes, and `+` as a space when `plus_as_space` (query
@@ -366,4 +395,22 @@ mod tests {
366
395
  assert_eq!(percent_decode("%aé", false), "%aé");
367
396
  assert_eq!(percent_decode("x%é%2F", true), "x%é/");
368
397
  }
398
+
399
+ #[test]
400
+ fn repeated_query_keys_are_all_kept() {
401
+ let pairs = parse_query_pairs("tag=a&x=1&tag=b+c&tag");
402
+ assert_eq!(pairs.iter().filter(|(k, _)| k == "tag").count(), 3);
403
+ // The map keeps the last value, as it always has.
404
+ assert_eq!(parse_query("tag=a&tag=b")["tag"], "b");
405
+ let mut req = WebCortexRequest::synthetic("GET", "/");
406
+ req.query_all = pairs;
407
+ req.query = req.query_all.iter().cloned().collect();
408
+ assert_eq!(req.query_values("tag"), vec!["a", "b c", ""]);
409
+ assert_eq!(req.query_values("nope"), Vec::<&str>::new());
410
+ // A request built with only the map still answers.
411
+ let mut bare = WebCortexRequest::synthetic("GET", "/");
412
+ bare.query.insert("x".into(), "1".into());
413
+ assert_eq!(bare.query_values("x"), vec!["1"]);
414
+ assert_eq!(bare.query_pairs(), vec![("x", "1")]);
415
+ }
369
416
  }
@@ -702,8 +702,16 @@ pub struct ServerConfig {
702
702
  /// a machine that moves should wait for an operator to release it.
703
703
  #[serde(default)]
704
704
  pub start_halted: bool,
705
+ /// Ceiling on open connections, WebSockets included. Past it a new
706
+ /// connection is answered `503` and closed at once, so a flood of idle
707
+ /// sockets cannot exhaust file descriptors or memory. `0` means no cap.
708
+ #[serde(default = "default_max_connections")]
709
+ pub max_connections: usize,
705
710
  }
706
711
 
712
+ fn default_max_connections() -> usize {
713
+ 10_000
714
+ }
707
715
  fn default_max_depth() -> u32 {
708
716
  8
709
717
  }
@@ -751,6 +759,7 @@ impl Default for ServerConfig {
751
759
  session_ttl_secs: default_session_ttl(),
752
760
  approval_ttl_secs: default_approval_ttl(),
753
761
  start_halted: false,
762
+ max_connections: default_max_connections(),
754
763
  }
755
764
  }
756
765
  }
@@ -782,11 +791,19 @@ pub struct Upstream {
782
791
  pub bearer_env: Option<String>,
783
792
  #[serde(default = "default_timeout_ms")]
784
793
  pub timeout_ms: u64,
794
+ /// The largest upstream response body a proxy route will relay. The body
795
+ /// is buffered, so without a ceiling one huge (or endless) upstream
796
+ /// response held that much memory per request.
797
+ #[serde(default = "default_max_response_bytes")]
798
+ pub max_response_bytes: usize,
785
799
  }
786
800
 
787
801
  fn default_timeout_ms() -> u64 {
788
802
  30_000
789
803
  }
804
+ fn default_max_response_bytes() -> usize {
805
+ 64 * 1024 * 1024
806
+ }
790
807
 
791
808
  #[derive(Debug, Clone, Serialize, Deserialize)]
792
809
  pub struct Route {