web-cortex-framework 2.4.0__tar.gz → 2.5.1__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 (51) hide show
  1. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/Cargo.lock +32 -31
  2. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/Cargo.toml +2 -2
  3. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/PKG-INFO +25 -6
  4. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/README.md +24 -5
  5. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/agent/provider.rs +26 -6
  6. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/agent/registry.rs +26 -0
  7. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/agent/vision.rs +87 -1
  8. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/agent.rs +116 -11
  9. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/app.rs +243 -50
  10. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/db.rs +13 -9
  11. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/devices.rs +132 -10
  12. web_cortex_framework-2.5.1/crates/webcortex-core/src/errors.rs +381 -0
  13. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/files.rs +3 -3
  14. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/http.rs +37 -6
  15. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/ledger.rs +5 -1
  16. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/lib.rs +10 -3
  17. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/manifest.rs +38 -4
  18. web_cortex_framework-2.5.1/crates/webcortex-core/src/mcp.rs +432 -0
  19. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/middleware.rs +77 -0
  20. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/openapi.rs +2 -3
  21. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/router.rs +2 -3
  22. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/server.rs +118 -19
  23. web_cortex_framework-2.5.1/crates/webcortex-core/src/status.rs +697 -0
  24. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/templates.rs +2 -2
  25. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/typegen.rs +2 -3
  26. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/ws.rs +40 -19
  27. web_cortex_framework-2.5.1/crates/webcortex-core/tests/diagnostics.rs +231 -0
  28. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-py/src/behaviour.rs +10 -15
  29. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-py/src/lib.rs +21 -0
  30. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/pyproject.toml +1 -1
  31. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/__init__.py +9 -1
  32. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/_bridge.py +16 -3
  33. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/app.py +21 -0
  34. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/cli.py +198 -15
  35. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/client.py +17 -2
  36. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/contextpack.py +12 -0
  37. web_cortex_framework-2.5.1/python/webcortex/diagnostics.py +435 -0
  38. web_cortex_framework-2.5.1/python/webcortex/errors.py +77 -0
  39. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/starters.py +14 -0
  40. web_cortex_framework-2.4.0/crates/webcortex-core/src/mcp.rs +0 -216
  41. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/LICENSE +0 -0
  42. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/Cargo.toml +0 -0
  43. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/agent/session.rs +0 -0
  44. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/audit.rs +0 -0
  45. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/auth.rs +0 -0
  46. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/bridge.rs +0 -0
  47. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/context.rs +0 -0
  48. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-core/src/flow.rs +0 -0
  49. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/crates/webcortex-py/Cargo.toml +0 -0
  50. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/media.py +0 -0
  51. {web_cortex_framework-2.4.0 → web_cortex_framework-2.5.1}/python/webcortex/schema.py +0 -0
@@ -771,9 +771,9 @@ dependencies = [
771
771
 
772
772
  [[package]]
773
773
  name = "http-body-util"
774
- version = "0.1.4"
774
+ version = "0.1.5"
775
775
  source = "registry+https://github.com/rust-lang/crates.io-index"
776
- checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
776
+ checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c"
777
777
  dependencies = [
778
778
  "bytes",
779
779
  "futures-core",
@@ -805,9 +805,9 @@ dependencies = [
805
805
 
806
806
  [[package]]
807
807
  name = "hyper"
808
- version = "1.11.0"
808
+ version = "1.12.0"
809
809
  source = "registry+https://github.com/rust-lang/crates.io-index"
810
- checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
810
+ checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c"
811
811
  dependencies = [
812
812
  "atomic-waker",
813
813
  "bytes",
@@ -843,16 +843,17 @@ dependencies = [
843
843
 
844
844
  [[package]]
845
845
  name = "hyper-util"
846
- version = "0.1.20"
846
+ version = "0.1.21"
847
847
  source = "registry+https://github.com/rust-lang/crates.io-index"
848
- checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
848
+ checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff"
849
849
  dependencies = [
850
- "base64 0.22.1",
850
+ "base64 0.23.1",
851
851
  "bytes",
852
852
  "futures-channel",
853
853
  "futures-util",
854
854
  "http",
855
855
  "http-body",
856
+ "httparse",
856
857
  "hyper",
857
858
  "ipnet",
858
859
  "libc",
@@ -1004,9 +1005,9 @@ dependencies = [
1004
1005
 
1005
1006
  [[package]]
1006
1007
  name = "jsonwebtoken"
1007
- version = "11.0.0"
1008
+ version = "11.1.0"
1008
1009
  source = "registry+https://github.com/rust-lang/crates.io-index"
1009
- checksum = "881733cbc631fc9e472e24447ce32a64bedf2da498d6d8570b08edc87de71f65"
1010
+ checksum = "e75fe14a82d81e5f5af639997db37d8b96045938a7ac6ab18cdbe1c7467e05e1"
1010
1011
  dependencies = [
1011
1012
  "base64 0.22.1",
1012
1013
  "ed25519-dalek",
@@ -1396,9 +1397,9 @@ dependencies = [
1396
1397
 
1397
1398
  [[package]]
1398
1399
  name = "pyo3"
1399
- version = "0.29.2"
1400
+ version = "0.29.3"
1400
1401
  source = "registry+https://github.com/rust-lang/crates.io-index"
1401
- checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
1402
+ checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
1402
1403
  dependencies = [
1403
1404
  "libc",
1404
1405
  "once_cell",
@@ -1410,18 +1411,18 @@ dependencies = [
1410
1411
 
1411
1412
  [[package]]
1412
1413
  name = "pyo3-build-config"
1413
- version = "0.29.2"
1414
+ version = "0.29.3"
1414
1415
  source = "registry+https://github.com/rust-lang/crates.io-index"
1415
- checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
1416
+ checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
1416
1417
  dependencies = [
1417
1418
  "target-lexicon",
1418
1419
  ]
1419
1420
 
1420
1421
  [[package]]
1421
1422
  name = "pyo3-ffi"
1422
- version = "0.29.2"
1423
+ version = "0.29.3"
1423
1424
  source = "registry+https://github.com/rust-lang/crates.io-index"
1424
- checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
1425
+ checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
1425
1426
  dependencies = [
1426
1427
  "libc",
1427
1428
  "pyo3-build-config",
@@ -1429,9 +1430,9 @@ dependencies = [
1429
1430
 
1430
1431
  [[package]]
1431
1432
  name = "pyo3-macros"
1432
- version = "0.29.2"
1433
+ version = "0.29.3"
1433
1434
  source = "registry+https://github.com/rust-lang/crates.io-index"
1434
- checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
1435
+ checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
1435
1436
  dependencies = [
1436
1437
  "proc-macro2",
1437
1438
  "pyo3-macros-backend",
@@ -1441,9 +1442,9 @@ dependencies = [
1441
1442
 
1442
1443
  [[package]]
1443
1444
  name = "pyo3-macros-backend"
1444
- version = "0.29.2"
1445
+ version = "0.29.3"
1445
1446
  source = "registry+https://github.com/rust-lang/crates.io-index"
1446
- checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
1447
+ checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
1447
1448
  dependencies = [
1448
1449
  "heck",
1449
1450
  "proc-macro2",
@@ -1473,9 +1474,9 @@ dependencies = [
1473
1474
 
1474
1475
  [[package]]
1475
1476
  name = "quinn-proto"
1476
- version = "0.11.16"
1477
+ version = "0.11.19"
1477
1478
  source = "registry+https://github.com/rust-lang/crates.io-index"
1478
- checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560"
1479
+ checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe"
1479
1480
  dependencies = [
1480
1481
  "bytes",
1481
1482
  "getrandom 0.4.3",
@@ -1704,9 +1705,9 @@ dependencies = [
1704
1705
 
1705
1706
  [[package]]
1706
1707
  name = "rustls"
1707
- version = "0.23.45"
1708
+ version = "0.23.46"
1708
1709
  source = "registry+https://github.com/rust-lang/crates.io-index"
1709
- checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
1710
+ checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
1710
1711
  dependencies = [
1711
1712
  "once_cell",
1712
1713
  "ring",
@@ -2274,9 +2275,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
2274
2275
 
2275
2276
  [[package]]
2276
2277
  name = "tokio"
2277
- version = "1.53.1"
2278
+ version = "1.53.3"
2278
2279
  source = "registry+https://github.com/rust-lang/crates.io-index"
2279
- checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
2280
+ checksum = "ce3335fa71841cda333a58d7615b03901380ecf09d59b3296d21f8bbac0dde4e"
2280
2281
  dependencies = [
2281
2282
  "bytes",
2282
2283
  "libc",
@@ -2541,9 +2542,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
2541
2542
 
2542
2543
  [[package]]
2543
2544
  name = "uuid"
2544
- version = "1.24.0"
2545
+ version = "1.26.1"
2545
2546
  source = "registry+https://github.com/rust-lang/crates.io-index"
2546
- checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
2547
+ checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
2547
2548
  dependencies = [
2548
2549
  "getrandom 0.4.3",
2549
2550
  "js-sys",
@@ -2571,9 +2572,9 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
2571
2572
 
2572
2573
  [[package]]
2573
2574
  name = "want"
2574
- version = "0.3.1"
2575
+ version = "0.3.2"
2575
2576
  source = "registry+https://github.com/rust-lang/crates.io-index"
2576
- checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
2577
+ checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b"
2577
2578
  dependencies = [
2578
2579
  "try-lock",
2579
2580
  ]
@@ -2661,7 +2662,7 @@ dependencies = [
2661
2662
 
2662
2663
  [[package]]
2663
2664
  name = "webcortex-core"
2664
- version = "2.4.0"
2665
+ version = "2.5.1"
2665
2666
  dependencies = [
2666
2667
  "base64 0.23.1",
2667
2668
  "bytes",
@@ -2689,7 +2690,7 @@ dependencies = [
2689
2690
 
2690
2691
  [[package]]
2691
2692
  name = "webcortex-py"
2692
- version = "2.4.0"
2693
+ version = "2.5.1"
2693
2694
  dependencies = [
2694
2695
  "bytes",
2695
2696
  "futures",
@@ -3,10 +3,10 @@ members = ["crates/webcortex-core", "crates/webcortex-py"]
3
3
  resolver = "3"
4
4
 
5
5
  [workspace.package]
6
- version = "2.4.0"
6
+ version = "2.5.1"
7
7
  edition = "2024"
8
8
  license = "Apache-2.0"
9
- rust-version = "1.85"
9
+ rust-version = "1.88"
10
10
  repository = "https://github.com/slimboi34/web_cortex_framework"
11
11
  homepage = "https://github.com/slimboi34/web_cortex_framework"
12
12
  documentation = "https://docs.rs/webcortex-core"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: web-cortex-framework
3
- Version: 2.4.0
3
+ Version: 2.5.1
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: Apache Software License
@@ -115,11 +115,13 @@ prints the lot in a form a coding model can extend.
115
115
  ## Start here
116
116
 
117
117
  ```bash
118
- uv venv --python 3.13 && uv pip install web-cortex-framework
118
+ uv venv --python 3.13 && source .venv/bin/activate # puts `webcortex` on PATH
119
+ uv pip install web-cortex-framework
119
120
 
120
- webcortex new myapp # --template api | fullstack | agent | behaviour | orchestration
121
+ webcortex new myapp # --template api | fullstack | agent | behaviour | orchestration | robotics | hub
121
122
  cd myapp
122
123
  export WEBCORTEX_API_KEY=$(webcortex keygen)
124
+ webcortex doctor # anything else to set first: other keys, model provider keys
123
125
  webcortex dev
124
126
  ```
125
127
 
@@ -136,7 +138,7 @@ interpreter at request time*. In practice that is most of a CRUD API and all of
136
138
  an orchestration.
137
139
 
138
140
  ```
139
- $ webcortex check
141
+ $ webcortex dev # the boot banner
140
142
  19 routes, 17 served without touching Python
141
143
  ```
142
144
 
@@ -457,8 +459,19 @@ one command that plugs the app into Claude Code, Claude Desktop or Cursor.
457
459
  $ webcortex context # the app, described for a coding model
458
460
  $ webcortex evolve "add reviews tied to books and a behaviour that summarises them" --model fast
459
461
  $ webcortex check # boot-time validation, with hints
462
+ $ webcortex doctor # keys present? models resolve? port free? e-stop?
463
+ $ webcortex status # what the running app is doing, and what just failed
464
+ $ webcortex explain WC402 # what an error code means and what to do
460
465
  ```
461
466
 
467
+ Every failure carries a stable code and a hint — in HTTP error bodies, agent runs, MCP
468
+ tool errors and the CLI — and the live view at `/_webcortex/status` (also the
469
+ `webcortex_status` MCP tool) shows recent failures by code and request id, runs in
470
+ flight, spend and devices. On eighteen scripted broken scenarios, 2.5.0 gives a code and
471
+ a hint for 18/18 where 2.4.0 gave none; see
472
+ [benchmarks/diagnostics/RESULTS.md](benchmarks/diagnostics/RESULTS.md) and
473
+ [docs/diagnostics.md](docs/diagnostics.md).
474
+
462
475
  The **context pack** is the app's shape — routes, tools and schemas, agents,
463
476
  behaviours, flows, context, memory, models, security posture — derived from the
464
477
  manifest in a few thousand tokens, plus a cheat sheet of the framework's API.
@@ -485,6 +498,10 @@ webcortex typegen generate a typed TypeScript client
485
498
  webcortex openapi the OpenAPI 3.1 document
486
499
  webcortex sql DDL for declared resources and memories
487
500
  webcortex keygen mint an API key
501
+ webcortex doctor check the app is ready to run (exit 1 on a failure)
502
+ webcortex status the running app's live view: requests, errors, runs, spend, devices
503
+ webcortex explain CODE what an error code means; --list for all of them
504
+ webcortex halt | release the emergency stop for actuators
488
505
  ```
489
506
 
490
507
  ## Security
@@ -510,7 +527,7 @@ tested, the known limits, and what v2 added to the surface.
510
527
 
511
528
  ## Status
512
529
 
513
- v2.4.0. Working and tested: the manifest IR, router, native ops (static /
530
+ v2.5.1. Working and tested: the manifest IR, router, native ops (static /
514
531
  query / proxy / page / files / flow), the free-threaded Python bridge,
515
532
  authentication and scopes, rate limiting, CORS, security headers, graceful
516
533
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -520,7 +537,9 @@ OpenAI-compatible, which covers local models), prompt caching, the spend
520
537
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
521
538
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
522
539
  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
540
+ ingest and streams, agents over WebSocket), and diagnostics (stable error codes
541
+ with hints on every failure, `webcortex doctor`, the live `/_webcortex/status`
542
+ view and its MCP tool). **490 tests** (155 Rust, 335 Python, including a
524
543
  54-test adversarial suite and offline end-to-end suites that drive the whole
525
544
  agent stack over HTTP), clippy clean.
526
545
 
@@ -87,11 +87,13 @@ prints the lot in a form a coding model can extend.
87
87
  ## Start here
88
88
 
89
89
  ```bash
90
- uv venv --python 3.13 && uv pip install web-cortex-framework
90
+ uv venv --python 3.13 && source .venv/bin/activate # puts `webcortex` on PATH
91
+ uv pip install web-cortex-framework
91
92
 
92
- webcortex new myapp # --template api | fullstack | agent | behaviour | orchestration
93
+ webcortex new myapp # --template api | fullstack | agent | behaviour | orchestration | robotics | hub
93
94
  cd myapp
94
95
  export WEBCORTEX_API_KEY=$(webcortex keygen)
96
+ webcortex doctor # anything else to set first: other keys, model provider keys
95
97
  webcortex dev
96
98
  ```
97
99
 
@@ -108,7 +110,7 @@ interpreter at request time*. In practice that is most of a CRUD API and all of
108
110
  an orchestration.
109
111
 
110
112
  ```
111
- $ webcortex check
113
+ $ webcortex dev # the boot banner
112
114
  19 routes, 17 served without touching Python
113
115
  ```
114
116
 
@@ -429,8 +431,19 @@ one command that plugs the app into Claude Code, Claude Desktop or Cursor.
429
431
  $ webcortex context # the app, described for a coding model
430
432
  $ webcortex evolve "add reviews tied to books and a behaviour that summarises them" --model fast
431
433
  $ webcortex check # boot-time validation, with hints
434
+ $ webcortex doctor # keys present? models resolve? port free? e-stop?
435
+ $ webcortex status # what the running app is doing, and what just failed
436
+ $ webcortex explain WC402 # what an error code means and what to do
432
437
  ```
433
438
 
439
+ Every failure carries a stable code and a hint — in HTTP error bodies, agent runs, MCP
440
+ tool errors and the CLI — and the live view at `/_webcortex/status` (also the
441
+ `webcortex_status` MCP tool) shows recent failures by code and request id, runs in
442
+ flight, spend and devices. On eighteen scripted broken scenarios, 2.5.0 gives a code and
443
+ a hint for 18/18 where 2.4.0 gave none; see
444
+ [benchmarks/diagnostics/RESULTS.md](benchmarks/diagnostics/RESULTS.md) and
445
+ [docs/diagnostics.md](docs/diagnostics.md).
446
+
434
447
  The **context pack** is the app's shape — routes, tools and schemas, agents,
435
448
  behaviours, flows, context, memory, models, security posture — derived from the
436
449
  manifest in a few thousand tokens, plus a cheat sheet of the framework's API.
@@ -457,6 +470,10 @@ webcortex typegen generate a typed TypeScript client
457
470
  webcortex openapi the OpenAPI 3.1 document
458
471
  webcortex sql DDL for declared resources and memories
459
472
  webcortex keygen mint an API key
473
+ webcortex doctor check the app is ready to run (exit 1 on a failure)
474
+ webcortex status the running app's live view: requests, errors, runs, spend, devices
475
+ webcortex explain CODE what an error code means; --list for all of them
476
+ webcortex halt | release the emergency stop for actuators
460
477
  ```
461
478
 
462
479
  ## Security
@@ -482,7 +499,7 @@ tested, the known limits, and what v2 added to the surface.
482
499
 
483
500
  ## Status
484
501
 
485
- v2.4.0. Working and tested: the manifest IR, router, native ops (static /
502
+ v2.5.1. Working and tested: the manifest IR, router, native ops (static /
486
503
  query / proxy / page / files / flow), the free-threaded Python bridge,
487
504
  authentication and scopes, rate limiting, CORS, security headers, graceful
488
505
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -492,7 +509,9 @@ OpenAI-compatible, which covers local models), prompt caching, the spend
492
509
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
493
510
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
494
511
  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
512
+ ingest and streams, agents over WebSocket), and diagnostics (stable error codes
513
+ with hints on every failure, `webcortex doctor`, the live `/_webcortex/status`
514
+ view and its MCP tool). **490 tests** (155 Rust, 335 Python, including a
496
515
  54-test adversarial suite and offline end-to-end suites that drive the whole
497
516
  agent stack over HTTP), clippy clean.
498
517
 
@@ -82,6 +82,12 @@ pub trait ModelProvider: Send + Sync + 'static {
82
82
  ) -> BoxFuture<'a, Result<ProviderResponse, String>>;
83
83
 
84
84
  fn name(&self) -> &'static str;
85
+
86
+ /// Where requests go, for `webcortex doctor --online`. `None` for
87
+ /// providers with no network endpoint (the fakes).
88
+ fn base_url(&self) -> Option<&str> {
89
+ None
90
+ }
85
91
  }
86
92
 
87
93
  fn full_system(req: &CompletionRequest<'_>) -> String {
@@ -134,6 +140,10 @@ impl ModelProvider for AnthropicProvider {
134
140
  "anthropic"
135
141
  }
136
142
 
143
+ fn base_url(&self) -> Option<&str> {
144
+ Some(&self.base_url)
145
+ }
146
+
137
147
  fn complete<'a>(
138
148
  &'a self,
139
149
  req: &'a CompletionRequest<'a>,
@@ -325,6 +335,10 @@ impl ModelProvider for OpenAiCompatProvider {
325
335
  self.label
326
336
  }
327
337
 
338
+ fn base_url(&self) -> Option<&str> {
339
+ Some(&self.base_url)
340
+ }
341
+
328
342
  fn complete<'a>(
329
343
  &'a self,
330
344
  req: &'a CompletionRequest<'a>,
@@ -594,21 +608,19 @@ pub fn parse_openai(payload: &Value, model: &str) -> Result<ProviderResponse, St
594
608
  /// return structured output" failures into successes.
595
609
  pub fn recover_json(text: &str) -> Option<Value> {
596
610
  let trimmed = text.trim();
597
- if let Ok(v) = serde_json::from_str::<Value>(trimmed) {
598
- if v.is_object() || v.is_array() {
611
+ if let Ok(v) = serde_json::from_str::<Value>(trimmed)
612
+ && (v.is_object() || v.is_array()) {
599
613
  return Some(v);
600
614
  }
601
- }
602
615
  let unfenced = trimmed
603
616
  .strip_prefix("```json")
604
617
  .or_else(|| trimmed.strip_prefix("```"))
605
618
  .and_then(|s| s.strip_suffix("```"))
606
619
  .map(str::trim);
607
- if let Some(inner) = unfenced {
608
- if let Ok(v) = serde_json::from_str::<Value>(inner) {
620
+ if let Some(inner) = unfenced
621
+ && let Ok(v) = serde_json::from_str::<Value>(inner) {
609
622
  return Some(v);
610
623
  }
611
- }
612
624
  // The first balanced `{ … }` in the text.
613
625
  let start = trimmed.find('{')?;
614
626
  let mut depth = 0i32;
@@ -991,6 +1003,14 @@ impl ModelProvider for FakeProvider {
991
1003
  );
992
1004
  }
993
1005
 
1006
+ // `fail:<message>` answers as a provider error would, so the failure
1007
+ // path (codes, hints, the status view) is testable offline. Write
1008
+ // the message the way a real provider error reads, e.g.
1009
+ // `fail:anthropic 529: overloaded`.
1010
+ if let Some(message) = text.trim().strip_prefix("fail:") {
1011
+ return Err(message.trim().to_string());
1012
+ }
1013
+
994
1014
  let mut calls = Vec::new();
995
1015
  let mut raw = Vec::new();
996
1016
  for (i, clause) in text.split(';').map(str::trim).enumerate() {
@@ -196,6 +196,32 @@ impl ProviderRegistry {
196
196
  })
197
197
  }
198
198
 
199
+ /// What `webcortex doctor` reports for one model name: the alias chain
200
+ /// resolved, the provider it routes to and its endpoint, or why it cannot
201
+ /// be used — the exact message, and catalogued code, a run would fail with.
202
+ pub fn diagnose(&self, name: &str) -> serde_json::Value {
203
+ let concrete = self.resolve_alias(name);
204
+ match self.route(&concrete) {
205
+ Ok((provider, wire)) => serde_json::json!({
206
+ "model": name,
207
+ "resolved": concrete,
208
+ "ok": true,
209
+ "provider": provider.name(),
210
+ "wire_name": wire,
211
+ "base_url": provider.base_url(),
212
+ "priced": self.price_for(&concrete).is_some(),
213
+ }),
214
+ Err(e) => serde_json::json!({
215
+ "model": name,
216
+ "resolved": concrete,
217
+ "ok": false,
218
+ "error": e,
219
+ "code": crate::errors::classify_run_error(&e),
220
+ "priced": self.price_for(&concrete).is_some(),
221
+ }),
222
+ }
223
+ }
224
+
199
225
  pub fn price_for(&self, model: &str) -> Option<Price> {
200
226
  // Try the exact name, then without a provider prefix.
201
227
  self.pricing
@@ -88,10 +88,68 @@ pub fn input_images(value: Option<&Value>) -> Result<Vec<Value>, String> {
88
88
  items
89
89
  .iter()
90
90
  .enumerate()
91
- .map(|(i, v)| image_block(v).map_err(|e| format!("images[{i}]: {e}")))
91
+ .map(|(i, v)| {
92
+ let block = image_block(v).map_err(|e| format!("images[{i}]: {e}"))?;
93
+ if let Some(url) = block["source"]["url"].as_str()
94
+ && names_an_internal_host(url) {
95
+ return Err(format!(
96
+ "images[{i}]: an image url may not point at a loopback, private, \
97
+ link-local or metadata address; send the bytes instead"
98
+ ));
99
+ }
100
+ Ok(block)
101
+ })
92
102
  .collect()
93
103
  }
94
104
 
105
+ /// True when a URL's host is a loopback, private, link-local, shared or
106
+ /// unspecified address, or a name for one such as `localhost`.
107
+ ///
108
+ /// An image URL sent by a caller is handed to the model provider, and an
109
+ /// OpenAI-compatible server (vLLM, LM Studio, …) fetches `image_url` itself,
110
+ /// from wherever it runs — so a caller could aim it at the inference host's
111
+ /// own network or a cloud metadata endpoint. Literal addresses are checked
112
+ /// after the URL parser normalises them (`0x7f.1`, `2130706433`, `[::ffff:…]`
113
+ /// are all caught); a public name that *resolves* to a private address is not,
114
+ /// which needs DNS and is the provider's to refuse.
115
+ pub fn names_an_internal_host(url: &str) -> bool {
116
+ use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
117
+ fn v4(ip: Ipv4Addr) -> bool {
118
+ let [a, b, ..] = ip.octets();
119
+ ip.is_loopback()
120
+ || ip.is_private()
121
+ || ip.is_link_local()
122
+ || ip.is_unspecified()
123
+ || ip.is_broadcast()
124
+ || a == 0
125
+ || (a == 100 && (64..128).contains(&b)) // shared / CGNAT
126
+ }
127
+ fn v6(ip: Ipv6Addr) -> bool {
128
+ let first = ip.segments()[0];
129
+ ip.is_loopback()
130
+ || ip.is_unspecified()
131
+ || (first & 0xfe00) == 0xfc00 // unique local
132
+ || (first & 0xffc0) == 0xfe80 // link-local
133
+ || ip.to_ipv4_mapped().is_some_and(v4)
134
+ }
135
+ let Ok(parsed) = reqwest::Url::parse(url) else { return true };
136
+ // The parser has already normalised the host: IPv4 in any notation comes
137
+ // back dotted-decimal, and IPv6 comes back bracketed.
138
+ let Some(host) = parsed.host_str() else { return true };
139
+ let host = host.trim_start_matches('[').trim_end_matches(']').trim_end_matches('.');
140
+ let host = host.to_ascii_lowercase();
141
+ match host.parse::<IpAddr>() {
142
+ Ok(IpAddr::V4(ip)) => v4(ip),
143
+ Ok(IpAddr::V6(ip)) => v6(ip),
144
+ Err(_) => {
145
+ host == "localhost"
146
+ || host.ends_with(".localhost")
147
+ || host.ends_with(".internal")
148
+ || host.ends_with(".local")
149
+ }
150
+ }
151
+ }
152
+
95
153
  /// True for a `{"$image": …}` marker object.
96
154
  fn is_marker(value: &Value) -> bool {
97
155
  value.as_object().is_some_and(|o| o.len() == 1 && o.contains_key(IMAGE_KEY))
@@ -345,4 +403,32 @@ mod tests {
345
403
  assert!(input_images(Some(&many)).is_err());
346
404
  assert!(input_images(Some(&json!([{"url": "ftp://x"}]))).unwrap_err().starts_with("images[0]"));
347
405
  }
406
+
407
+ #[test]
408
+ fn a_caller_cannot_aim_an_image_url_at_an_internal_address() {
409
+ for url in [
410
+ "http://169.254.169.254/latest/meta-data/",
411
+ "http://127.0.0.1:8000/x.png",
412
+ "http://0x7f.1/x.png",
413
+ "http://2130706433/x.png",
414
+ "http://10.0.0.5/x.png",
415
+ "http://192.168.1.10/cam.jpg",
416
+ "http://100.64.0.1/x.png",
417
+ "http://0.0.0.0/x.png",
418
+ "http://[::1]/x.png",
419
+ "http://[::ffff:127.0.0.1]/x.png",
420
+ "http://[fd00::1]/x.png",
421
+ "http://[fe80::1]/x.png",
422
+ "http://localhost/x.png",
423
+ "http://LOCALHOST./x.png",
424
+ "http://metadata.google.internal/x.png",
425
+ "http://printer.local/x.png",
426
+ ] {
427
+ let err = input_images(Some(&json!([{"url": url}]))).unwrap_err();
428
+ assert!(err.contains("may not point at"), "{url}: {err}");
429
+ }
430
+ for url in ["https://x.test/a.png", "https://8.8.8.8/a.png", "https://[2001:db8::1]/a.png"] {
431
+ assert!(input_images(Some(&json!([{"url": url}]))).is_ok(), "{url}");
432
+ }
433
+ }
348
434
  }