web-cortex-framework 2.2.0__tar.gz → 2.3.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 (45) hide show
  1. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/Cargo.lock +48 -2
  2. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/Cargo.toml +4 -1
  3. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/PKG-INFO +39 -3
  4. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/README.md +38 -2
  5. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/Cargo.toml +1 -0
  6. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/agent.rs +27 -0
  7. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/app.rs +108 -0
  8. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/auth.rs +5 -0
  9. web_cortex_framework-2.3.0/crates/webcortex-core/src/devices.rs +718 -0
  10. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/lib.rs +2 -0
  11. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/manifest.rs +177 -0
  12. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/server.rs +36 -2
  13. web_cortex_framework-2.3.0/crates/webcortex-core/src/ws.rs +341 -0
  14. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/pyproject.toml +1 -1
  15. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/__init__.py +1 -1
  16. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/app.py +192 -0
  17. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/cli.py +10 -1
  18. web_cortex_framework-2.3.0/python/webcortex/client.py +292 -0
  19. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/contextpack.py +14 -0
  20. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/starters.py +91 -2
  21. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/LICENSE +0 -0
  22. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/agent/provider.rs +0 -0
  23. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/agent/registry.rs +0 -0
  24. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/agent/session.rs +0 -0
  25. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/agent/vision.rs +0 -0
  26. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/audit.rs +0 -0
  27. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/bridge.rs +0 -0
  28. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/context.rs +0 -0
  29. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/db.rs +0 -0
  30. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/files.rs +0 -0
  31. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/flow.rs +0 -0
  32. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/http.rs +0 -0
  33. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/ledger.rs +0 -0
  34. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/mcp.rs +0 -0
  35. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/middleware.rs +0 -0
  36. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/openapi.rs +0 -0
  37. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/router.rs +0 -0
  38. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/templates.rs +0 -0
  39. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-core/src/typegen.rs +0 -0
  40. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-py/Cargo.toml +0 -0
  41. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-py/src/behaviour.rs +0 -0
  42. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/crates/webcortex-py/src/lib.rs +0 -0
  43. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/_bridge.py +0 -0
  44. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/media.py +0 -0
  45. {web_cortex_framework-2.2.0 → web_cortex_framework-2.3.0}/python/webcortex/schema.py +0 -0
@@ -286,6 +286,12 @@ dependencies = [
286
286
  "syn 2.0.119",
287
287
  ]
288
288
 
289
+ [[package]]
290
+ name = "data-encoding"
291
+ version = "2.11.1"
292
+ source = "registry+https://github.com/rust-lang/crates.io-index"
293
+ checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"
294
+
289
295
  [[package]]
290
296
  name = "der"
291
297
  version = "0.7.10"
@@ -1824,6 +1830,17 @@ dependencies = [
1824
1830
  "serde",
1825
1831
  ]
1826
1832
 
1833
+ [[package]]
1834
+ name = "sha1"
1835
+ version = "0.11.0"
1836
+ source = "registry+https://github.com/rust-lang/crates.io-index"
1837
+ checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
1838
+ dependencies = [
1839
+ "cfg-if",
1840
+ "cpufeatures 0.3.0",
1841
+ "digest 0.11.3",
1842
+ ]
1843
+
1827
1844
  [[package]]
1828
1845
  name = "sha2"
1829
1846
  version = "0.10.9"
@@ -2304,6 +2321,18 @@ dependencies = [
2304
2321
  "tokio",
2305
2322
  ]
2306
2323
 
2324
+ [[package]]
2325
+ name = "tokio-tungstenite"
2326
+ version = "0.30.0"
2327
+ source = "registry+https://github.com/rust-lang/crates.io-index"
2328
+ checksum = "17a073bfed563fa236697a068031408a93cd9522e08abf9933ead3e73411bd71"
2329
+ dependencies = [
2330
+ "futures-util",
2331
+ "log",
2332
+ "tokio",
2333
+ "tungstenite",
2334
+ ]
2335
+
2307
2336
  [[package]]
2308
2337
  name = "tokio-util"
2309
2338
  version = "0.7.19"
@@ -2431,6 +2460,22 @@ version = "0.2.5"
2431
2460
  source = "registry+https://github.com/rust-lang/crates.io-index"
2432
2461
  checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
2433
2462
 
2463
+ [[package]]
2464
+ name = "tungstenite"
2465
+ version = "0.30.0"
2466
+ source = "registry+https://github.com/rust-lang/crates.io-index"
2467
+ checksum = "e48ac77174b19c110a50ab2128b24215ac9cb40e0e12e093fb602d175c569d22"
2468
+ dependencies = [
2469
+ "bytes",
2470
+ "data-encoding",
2471
+ "http",
2472
+ "httparse",
2473
+ "log",
2474
+ "rand 0.10.2",
2475
+ "sha1",
2476
+ "thiserror",
2477
+ ]
2478
+
2434
2479
  [[package]]
2435
2480
  name = "typenum"
2436
2481
  version = "1.20.1"
@@ -2616,7 +2661,7 @@ dependencies = [
2616
2661
 
2617
2662
  [[package]]
2618
2663
  name = "webcortex-core"
2619
- version = "2.2.0"
2664
+ version = "2.3.0"
2620
2665
  dependencies = [
2621
2666
  "base64 0.23.1",
2622
2667
  "bytes",
@@ -2636,6 +2681,7 @@ dependencies = [
2636
2681
  "sqlx",
2637
2682
  "subtle",
2638
2683
  "tokio",
2684
+ "tokio-tungstenite",
2639
2685
  "tracing",
2640
2686
  "tracing-subscriber",
2641
2687
  "uuid",
@@ -2643,7 +2689,7 @@ dependencies = [
2643
2689
 
2644
2690
  [[package]]
2645
2691
  name = "webcortex-py"
2646
- version = "2.2.0"
2692
+ version = "2.3.0"
2647
2693
  dependencies = [
2648
2694
  "bytes",
2649
2695
  "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.2.0"
6
+ version = "2.3.0"
7
7
  edition = "2024"
8
8
  license = "Apache-2.0"
9
9
  rust-version = "1.85"
@@ -39,6 +39,9 @@ subtle = "2"
39
39
  base64 = "0.23"
40
40
  uuid = { version = "1", features = ["v4", "fast-rng"] }
41
41
  mime_guess = "2"
42
+ # WebSockets: devices stream frames in, subscribers and agents stream out. Only the
43
+ # server handshake is used; the HTTP upgrade itself is hyper's.
44
+ tokio-tungstenite = { version = "0.30", default-features = false, features = ["handshake"] }
42
45
 
43
46
  [profile.release]
44
47
  opt-level = 3
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: web-cortex-framework
3
- Version: 2.2.0
3
+ Version: 2.3.0
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: Apache Software License
@@ -392,6 +392,41 @@ app.agent("operator", tools=["camera", "move_arm"], scopes=["observe", "operate"
392
392
 
393
393
  See [Vision and robotics](docs/vision-and-robotics.md).
394
394
 
395
+ ## The device hub: cameras in, insights out
396
+
397
+ WebCortex sits between devices and agents, and the Rust core does the work.
398
+ Cameras and sensors stream in, agents see what they send, and what the agents
399
+ conclude streams out to anyone subscribed.
400
+
401
+ ```python
402
+ app.camera("dock", max_fps=10) # pushed: browser, Pi, ESP32, curl
403
+ app.camera("lobby", source="http://192.168.1.40/snapshot.jpg") # pulled: any IP camera
404
+ app.sensor("dock_env") # telemetry only
405
+
406
+ app.agent("inspector", tools=["dock_snapshot", "dock_env_telemetry"], max_images=2)
407
+ app.watch("dock_watch", device="dock", agent="inspector", every=15,
408
+ input="Anything unsafe at the dock?", max_runs_per_hour=120,
409
+ webhook="https://ops.example.com/hooks/dock")
410
+ ```
411
+
412
+ - **Connect anything.** WebSocket (`/devices/dock/ws`: binary messages are
413
+ frames, text is telemetry), HTTP POST, or an IP camera's snapshot URL. Open
414
+ `/devices/dock/connect` on a phone or laptop and its camera becomes the
415
+ device.
416
+ - **No Python per frame.** Ring buffers, sniffing, per-device rate limits and
417
+ broadcast fan-out all live in Rust.
418
+ - **Agents see it.** `dock_snapshot` is a tool that returns the live frame as
419
+ an image the model sees, over MCP too.
420
+ - **Watchers are the middle of the hub.** When the picture changes, the agent
421
+ looks, and its insight goes to every `/devices/dock/stream` subscriber, to a
422
+ webhook, and to the audit log. Spend is capped per hour.
423
+ - **Agents over WebSocket.** Any agent route accepts a socket: send a turn,
424
+ receive each step live, then the result.
425
+ - **A stdlib Python client** (`webcortex.client`): `DeviceConnection` for
426
+ drivers, `subscribe()` for consumers, `AgentSocket` for services.
427
+
428
+ `webcortex new site -t hub` scaffolds it. See [The device hub](docs/device-hub.md).
429
+
395
430
  ## Security defaults
396
431
 
397
432
  Deny-by-default throughout; relaxing something costs a line, tightening it costs
@@ -475,7 +510,7 @@ tested, the known limits, and what v2 added to the surface.
475
510
 
476
511
  ## Status
477
512
 
478
- v2.2.0. Working and tested: the manifest IR, router, native ops (static /
513
+ v2.3.0. Working and tested: the manifest IR, router, native ops (static /
479
514
  query / proxy / page / files / flow), the free-threaded Python bridge,
480
515
  authentication and scopes, rate limiting, CORS, security headers, graceful
481
516
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -484,7 +519,8 @@ compaction, context providers, memory, flows, two providers (Anthropic and
484
519
  OpenAI-compatible, which covers local models), prompt caching, the spend
485
520
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
486
521
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
487
- and the emergency stop. **403 tests** (124 Rust, 279 Python, including a
522
+ and the emergency stop, the device hub (cameras, sensors, watchers, WebSocket
523
+ ingest and streams, agents over WebSocket). **427 tests** (132 Rust, 295 Python, including a
488
524
  54-test adversarial suite and offline end-to-end suites that drive the whole
489
525
  agent stack over HTTP), clippy clean.
490
526
 
@@ -364,6 +364,41 @@ app.agent("operator", tools=["camera", "move_arm"], scopes=["observe", "operate"
364
364
 
365
365
  See [Vision and robotics](docs/vision-and-robotics.md).
366
366
 
367
+ ## The device hub: cameras in, insights out
368
+
369
+ WebCortex sits between devices and agents, and the Rust core does the work.
370
+ Cameras and sensors stream in, agents see what they send, and what the agents
371
+ conclude streams out to anyone subscribed.
372
+
373
+ ```python
374
+ app.camera("dock", max_fps=10) # pushed: browser, Pi, ESP32, curl
375
+ app.camera("lobby", source="http://192.168.1.40/snapshot.jpg") # pulled: any IP camera
376
+ app.sensor("dock_env") # telemetry only
377
+
378
+ app.agent("inspector", tools=["dock_snapshot", "dock_env_telemetry"], max_images=2)
379
+ app.watch("dock_watch", device="dock", agent="inspector", every=15,
380
+ input="Anything unsafe at the dock?", max_runs_per_hour=120,
381
+ webhook="https://ops.example.com/hooks/dock")
382
+ ```
383
+
384
+ - **Connect anything.** WebSocket (`/devices/dock/ws`: binary messages are
385
+ frames, text is telemetry), HTTP POST, or an IP camera's snapshot URL. Open
386
+ `/devices/dock/connect` on a phone or laptop and its camera becomes the
387
+ device.
388
+ - **No Python per frame.** Ring buffers, sniffing, per-device rate limits and
389
+ broadcast fan-out all live in Rust.
390
+ - **Agents see it.** `dock_snapshot` is a tool that returns the live frame as
391
+ an image the model sees, over MCP too.
392
+ - **Watchers are the middle of the hub.** When the picture changes, the agent
393
+ looks, and its insight goes to every `/devices/dock/stream` subscriber, to a
394
+ webhook, and to the audit log. Spend is capped per hour.
395
+ - **Agents over WebSocket.** Any agent route accepts a socket: send a turn,
396
+ receive each step live, then the result.
397
+ - **A stdlib Python client** (`webcortex.client`): `DeviceConnection` for
398
+ drivers, `subscribe()` for consumers, `AgentSocket` for services.
399
+
400
+ `webcortex new site -t hub` scaffolds it. See [The device hub](docs/device-hub.md).
401
+
367
402
  ## Security defaults
368
403
 
369
404
  Deny-by-default throughout; relaxing something costs a line, tightening it costs
@@ -447,7 +482,7 @@ tested, the known limits, and what v2 added to the surface.
447
482
 
448
483
  ## Status
449
484
 
450
- v2.2.0. Working and tested: the manifest IR, router, native ops (static /
485
+ v2.3.0. Working and tested: the manifest IR, router, native ops (static /
451
486
  query / proxy / page / files / flow), the free-threaded Python bridge,
452
487
  authentication and scopes, rate limiting, CORS, security headers, graceful
453
488
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -456,7 +491,8 @@ compaction, context providers, memory, flows, two providers (Anthropic and
456
491
  OpenAI-compatible, which covers local models), prompt caching, the spend
457
492
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
458
493
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
459
- and the emergency stop. **403 tests** (124 Rust, 279 Python, including a
494
+ and the emergency stop, the device hub (cameras, sensors, watchers, WebSocket
495
+ ingest and streams, agents over WebSocket). **427 tests** (132 Rust, 295 Python, including a
460
496
  54-test adversarial suite and offline end-to-end suites that drive the whole
461
497
  agent stack over HTTP), clippy clean.
462
498
 
@@ -32,6 +32,7 @@ subtle.workspace = true
32
32
  base64.workspace = true
33
33
  uuid.workspace = true
34
34
  mime_guess.workspace = true
35
+ tokio-tungstenite.workspace = true
35
36
 
36
37
  [features]
37
38
  default = ["sqlite"]
@@ -250,6 +250,9 @@ pub struct RunOptions {
250
250
  pub reset_session: bool,
251
251
  /// Canonical image blocks sent with the input (see [`vision`]).
252
252
  pub images: Vec<Value>,
253
+ /// Receives `{"type": "step", …}` as each step happens, for a client that
254
+ /// wants to watch the run rather than wait for it (the agent WebSocket).
255
+ pub events: Option<tokio::sync::mpsc::UnboundedSender<Value>>,
253
256
  }
254
257
 
255
258
  // ---------------------------------------------------------------------------
@@ -326,6 +329,24 @@ struct RunState {
326
329
  /// Where the conversation is saved: the session id scoped by the entry
327
330
  /// agent and the caller, so another principal's id cannot reach it.
328
331
  session_key: Option<String>,
332
+ /// Where step events go, and how many steps have been sent.
333
+ events: Option<tokio::sync::mpsc::UnboundedSender<Value>>,
334
+ emitted: usize,
335
+ }
336
+
337
+ impl RunState {
338
+ /// Send every step not yet sent. A closed receiver is not an error: the
339
+ /// client went away, and the run still finishes and is still recorded.
340
+ fn emit(&mut self) {
341
+ if let Some(tx) = &self.events {
342
+ for step in &self.steps[self.emitted.min(self.steps.len())..] {
343
+ let _ = tx.send(json!({
344
+ "type": "step", "run_id": self.run_id, "agent": self.def.name, "step": step,
345
+ }));
346
+ }
347
+ }
348
+ self.emitted = self.steps.len();
349
+ }
329
350
  }
330
351
 
331
352
  enum CallsOutcome {
@@ -436,6 +457,8 @@ impl AgentRuntime {
436
457
  compaction_retry_at: 0,
437
458
  session_id: opts.session_id,
438
459
  session_key,
460
+ events: opts.events,
461
+ emitted: 0,
439
462
  };
440
463
 
441
464
  let tools = self.tool_specs(app, &state.def);
@@ -500,6 +523,7 @@ impl AgentRuntime {
500
523
  let max_steps = st.entry.max_steps.unwrap_or(12);
501
524
 
502
525
  loop {
526
+ st.emit();
503
527
  if st.usage.steps >= max_steps {
504
528
  return self.finish(app, st, RunStatus::StepLimit, None);
505
529
  }
@@ -590,6 +614,7 @@ impl AgentRuntime {
590
614
  duration_ms: started.elapsed().as_millis() as u64,
591
615
  });
592
616
 
617
+ st.emit();
593
618
  if !response.text.is_empty() {
594
619
  st.output = response.text.clone();
595
620
  }
@@ -722,6 +747,7 @@ impl AgentRuntime {
722
747
  error,
723
748
  duration_ms,
724
749
  });
750
+ st.emit();
725
751
  tool_result_with_images(&call.id, &shown, is_error, images)
726
752
  }
727
753
 
@@ -1029,6 +1055,7 @@ impl AgentRuntime {
1029
1055
  pending: Option<PendingApproval>,
1030
1056
  ) -> RunResult {
1031
1057
  st.usage.tree_tokens = st.budget.used();
1058
+ st.emit();
1032
1059
  self.audit
1033
1060
  .record(AuditEvent::agent_finished(&st.run_id, &st.def.name, status, &st.usage));
1034
1061
  app.ledger().count_run();
@@ -56,6 +56,8 @@ pub struct App {
56
56
  /// The emergency stop. While set, every route declared `actuator` refuses
57
57
  /// to run, whoever asks and however they arrive.
58
58
  halt: Mutex<Option<serde_json::Value>>,
59
+ /// Cameras and sensors: frames, telemetry, insights and their subscribers.
60
+ devices: crate::devices::DeviceHub,
59
61
  }
60
62
 
61
63
  impl App {
@@ -163,6 +165,7 @@ impl App {
163
165
  .build()
164
166
  .map_err(|e| format!("http client build failed: {e}"))?;
165
167
  let manifest_start_halted = manifest.server.start_halted;
168
+ let devices = crate::devices::DeviceHub::new(&manifest.devices, client.clone());
166
169
 
167
170
  Ok(Self {
168
171
  manifest,
@@ -192,6 +195,7 @@ impl App {
192
195
  serde_json::json!({"reason": "started halted; release to enable actuators",
193
196
  "by": "boot", "since_unix": 0})
194
197
  })),
198
+ devices,
195
199
  })
196
200
  }
197
201
 
@@ -291,6 +295,38 @@ impl App {
291
295
  Ok(runtime.resume_approval(self, run, approve, note).await)
292
296
  }
293
297
 
298
+ pub fn devices(&self) -> &crate::devices::DeviceHub {
299
+ &self.devices
300
+ }
301
+
302
+ /// The shared outbound HTTP client: upstreams, pulled cameras, webhooks.
303
+ pub fn http_client(&self) -> &reqwest::Client {
304
+ &self.client
305
+ }
306
+
307
+ /// Match a request to its route and check the caller may reach it, without
308
+ /// running it. The WebSocket upgrade uses this, so a socket is held to the
309
+ /// same scopes as the route it is mounted on.
310
+ pub fn authorize(&self, method: &str, path: &str, principal: &Principal) -> Result<&Route, WebCortexResponse> {
311
+ let matched = self.router.find(method, path).map_err(|e| match e {
312
+ MatchError::NotFound => WebCortexResponse::error(404, format!("no route for {method} {path}")),
313
+ MatchError::MethodNotAllowed => WebCortexResponse::error(405, format!("{method} not allowed on {path}")),
314
+ })?;
315
+ let route = self
316
+ .routes_by_id
317
+ .get(&matched.route_id)
318
+ .ok_or_else(|| WebCortexResponse::error(500, "router matched an unknown route id"))?;
319
+ let missing = principal.missing_scopes(&Self::required_scopes(route));
320
+ if !missing.is_empty() {
321
+ let status = if principal.is_anonymous() { 401 } else { 403 };
322
+ return Err(WebCortexResponse::error(
323
+ status,
324
+ format!("missing required scope(s): {}", missing.join(", ")),
325
+ ));
326
+ }
327
+ Ok(route)
328
+ }
329
+
294
330
  /// Engage the emergency stop. Idempotent; a second halt updates the reason.
295
331
  pub fn halt(&self, reason: &str, by: &Principal) {
296
332
  let since = std::time::SystemTime::now()
@@ -521,9 +557,80 @@ impl App {
521
557
  }
522
558
  self.run_flow(flow, req).await
523
559
  }
560
+
561
+ Op::Device { device, action } => self.serve_device(device, *action, req).await,
524
562
  }
525
563
  }
526
564
 
565
+ async fn serve_device(
566
+ &self,
567
+ name: &str,
568
+ action: crate::manifest::DeviceAction,
569
+ req: WebCortexRequest,
570
+ ) -> Result<WebCortexResponse, String> {
571
+ use crate::manifest::DeviceAction as A;
572
+ let device = self
573
+ .devices
574
+ .get(name)
575
+ .ok_or_else(|| format!("unknown device {name:?}"))?;
576
+ let html = |page: &str| WebCortexResponse {
577
+ status: 200,
578
+ headers: vec![("content-type".into(), "text/html; charset=utf-8".into())],
579
+ body: bytes::Bytes::from(page.replace("__DEVICE__", &crate::devices::escape_html(name))),
580
+ };
581
+ Ok(match action {
582
+ A::Snapshot => match self.devices.snapshot(device).await {
583
+ Ok(v) => WebCortexResponse::json(200, &v),
584
+ Err(e) => WebCortexResponse::error(if device.def.source.is_some() { 502 } else { 404 }, e),
585
+ },
586
+ A::Image => match self.devices.current_frame(device).await {
587
+ Ok(Some(frame)) => WebCortexResponse {
588
+ status: 200,
589
+ headers: vec![
590
+ ("content-type".into(), frame.media_type.into()),
591
+ ("cache-control".into(), "no-store".into()),
592
+ ("x-webcortex-seq".into(), frame.seq.to_string()),
593
+ ],
594
+ body: frame.data.clone(),
595
+ },
596
+ Ok(None) => WebCortexResponse::error(404, format!("device {name:?} has not sent a frame yet")),
597
+ Err(e) => WebCortexResponse::error(502, e),
598
+ },
599
+ A::Telemetry => {
600
+ let t = device.telemetry();
601
+ WebCortexResponse::json(200, &serde_json::json!({
602
+ "device": name,
603
+ "telemetry": t.as_ref().map(|(_, v)| (**v).clone()),
604
+ "age_ms": t.map(|(at, _)| crate::devices::now_ms().saturating_sub(at)),
605
+ }))
606
+ }
607
+ A::Insights => WebCortexResponse::json(
608
+ 200,
609
+ &serde_json::json!({"device": name, "insights": device.insights()}),
610
+ ),
611
+ A::IngestFrame => match device.push_frame(req.body.clone()) {
612
+ Ok(seq) => WebCortexResponse::json(200, &serde_json::json!({"device": name, "seq": seq})),
613
+ Err(e) => WebCortexResponse::error(e.status(), e.message()),
614
+ },
615
+ A::IngestTelemetry => {
616
+ let Ok(value) = req.json_body() else {
617
+ return Ok(WebCortexResponse::error(400, "telemetry must be a JSON body"));
618
+ };
619
+ match device.push_telemetry(value) {
620
+ Ok(()) => WebCortexResponse::json(200, &serde_json::json!({"device": name, "ok": true})),
621
+ Err(e) => WebCortexResponse::error(e.status(), e.message()),
622
+ }
623
+ }
624
+ A::SocketIngest | A::SocketStream => {
625
+ let mut res = WebCortexResponse::error(426, "this route is a WebSocket; connect with Upgrade: websocket");
626
+ res.headers.push(("upgrade".into(), "websocket".into()));
627
+ res
628
+ }
629
+ A::ConnectPage => html(crate::devices::CONNECT_PAGE),
630
+ A::ViewPage => html(crate::devices::VIEW_PAGE),
631
+ })
632
+ }
633
+
527
634
  async fn run_flow(&self, name: &str, req: WebCortexRequest) -> Result<WebCortexResponse, String> {
528
635
  let def = self
529
636
  .manifest
@@ -729,6 +836,7 @@ impl App {
729
836
  session_id,
730
837
  reset_session,
731
838
  images,
839
+ events: None,
732
840
  };
733
841
  let result = runtime.run(self, def, &req.principal, &input, opts).await;
734
842
  Ok(run_result_response(&result))
@@ -188,6 +188,11 @@ impl Authenticator {
188
188
  /// A malformed or expired credential is an error, not a silent downgrade to
189
189
  /// anonymous: a client that sent a token deserves to be told it was
190
190
  /// rejected rather than mysteriously receiving 403s later.
191
+ /// The header an API key is read from (lower-case).
192
+ pub fn api_key_header(&self) -> &str {
193
+ &self.api_key_header
194
+ }
195
+
191
196
  pub fn authenticate(
192
197
  &self,
193
198
  headers: &BTreeMap<String, String>,