web-cortex-framework 2.3.0__tar.gz → 2.5.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 (51) hide show
  1. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/Cargo.lock +32 -31
  2. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/Cargo.toml +2 -2
  3. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/PKG-INFO +20 -3
  4. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/README.md +19 -2
  5. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/agent/provider.rs +92 -43
  6. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/agent/registry.rs +26 -0
  7. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/agent/vision.rs +87 -1
  8. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/agent.rs +117 -11
  9. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/app.rs +204 -48
  10. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/db.rs +13 -9
  11. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/devices.rs +132 -10
  12. web_cortex_framework-2.5.0/crates/webcortex-core/src/errors.rs +381 -0
  13. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/files.rs +3 -3
  14. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/flow.rs +1 -0
  15. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/http.rs +37 -6
  16. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/lib.rs +6 -2
  17. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/manifest.rs +14 -3
  18. web_cortex_framework-2.5.0/crates/webcortex-core/src/mcp.rs +393 -0
  19. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/middleware.rs +77 -0
  20. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/openapi.rs +2 -3
  21. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/router.rs +2 -3
  22. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/server.rs +106 -19
  23. web_cortex_framework-2.5.0/crates/webcortex-core/src/status.rs +673 -0
  24. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/templates.rs +2 -2
  25. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/typegen.rs +2 -3
  26. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/ws.rs +3 -4
  27. web_cortex_framework-2.5.0/crates/webcortex-core/tests/diagnostics.rs +163 -0
  28. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-py/src/behaviour.rs +14 -15
  29. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-py/src/lib.rs +23 -0
  30. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/pyproject.toml +1 -1
  31. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/__init__.py +9 -1
  32. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/_bridge.py +16 -3
  33. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/app.py +42 -0
  34. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/cli.py +171 -13
  35. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/client.py +17 -2
  36. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/contextpack.py +12 -0
  37. web_cortex_framework-2.5.0/python/webcortex/diagnostics.py +412 -0
  38. web_cortex_framework-2.5.0/python/webcortex/errors.py +77 -0
  39. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/starters.py +12 -0
  40. web_cortex_framework-2.3.0/crates/webcortex-core/src/mcp.rs +0 -216
  41. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/LICENSE +0 -0
  42. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/Cargo.toml +0 -0
  43. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/agent/session.rs +0 -0
  44. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/audit.rs +0 -0
  45. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/auth.rs +0 -0
  46. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/bridge.rs +0 -0
  47. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/context.rs +0 -0
  48. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-core/src/ledger.rs +0 -0
  49. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/crates/webcortex-py/Cargo.toml +0 -0
  50. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/python/webcortex/media.py +0 -0
  51. {web_cortex_framework-2.3.0 → web_cortex_framework-2.5.0}/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.3.0"
2665
+ version = "2.5.0"
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.3.0"
2693
+ version = "2.5.0"
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.3.0"
6
+ version = "2.5.0"
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.3.0
3
+ Version: 2.5.0
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: Apache Software License
@@ -457,8 +457,19 @@ one command that plugs the app into Claude Code, Claude Desktop or Cursor.
457
457
  $ webcortex context # the app, described for a coding model
458
458
  $ webcortex evolve "add reviews tied to books and a behaviour that summarises them" --model fast
459
459
  $ webcortex check # boot-time validation, with hints
460
+ $ webcortex doctor # keys present? models resolve? port free? e-stop?
461
+ $ webcortex status # what the running app is doing, and what just failed
462
+ $ webcortex explain WC402 # what an error code means and what to do
460
463
  ```
461
464
 
465
+ Every failure carries a stable code and a hint — in HTTP error bodies, agent runs, MCP
466
+ tool errors and the CLI — and the live view at `/_webcortex/status` (also the
467
+ `webcortex_status` MCP tool) shows recent failures by code and request id, runs in
468
+ flight, spend and devices. On eighteen scripted broken scenarios, 2.5.0 gives a code and
469
+ a hint for 18/18 where 2.4.0 gave none; see
470
+ [benchmarks/diagnostics/RESULTS.md](benchmarks/diagnostics/RESULTS.md) and
471
+ [docs/diagnostics.md](docs/diagnostics.md).
472
+
462
473
  The **context pack** is the app's shape — routes, tools and schemas, agents,
463
474
  behaviours, flows, context, memory, models, security posture — derived from the
464
475
  manifest in a few thousand tokens, plus a cheat sheet of the framework's API.
@@ -485,6 +496,10 @@ webcortex typegen generate a typed TypeScript client
485
496
  webcortex openapi the OpenAPI 3.1 document
486
497
  webcortex sql DDL for declared resources and memories
487
498
  webcortex keygen mint an API key
499
+ webcortex doctor check the app is ready to run (exit 1 on a failure)
500
+ webcortex status the running app's live view: requests, errors, runs, spend, devices
501
+ webcortex explain CODE what an error code means; --list for all of them
502
+ webcortex halt | release the emergency stop for actuators
488
503
  ```
489
504
 
490
505
  ## Security
@@ -510,7 +525,7 @@ tested, the known limits, and what v2 added to the surface.
510
525
 
511
526
  ## Status
512
527
 
513
- v2.3.0. Working and tested: the manifest IR, router, native ops (static /
528
+ v2.5.0. Working and tested: the manifest IR, router, native ops (static /
514
529
  query / proxy / page / files / flow), the free-threaded Python bridge,
515
530
  authentication and scopes, rate limiting, CORS, security headers, graceful
516
531
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -520,7 +535,9 @@ OpenAI-compatible, which covers local models), prompt caching, the spend
520
535
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
521
536
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
522
537
  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
538
+ ingest and streams, agents over WebSocket), and diagnostics (stable error codes
539
+ with hints on every failure, `webcortex doctor`, the live `/_webcortex/status`
540
+ view and its MCP tool). **490 tests** (155 Rust, 335 Python, including a
524
541
  54-test adversarial suite and offline end-to-end suites that drive the whole
525
542
  agent stack over HTTP), clippy clean.
526
543
 
@@ -429,8 +429,19 @@ one command that plugs the app into Claude Code, Claude Desktop or Cursor.
429
429
  $ webcortex context # the app, described for a coding model
430
430
  $ webcortex evolve "add reviews tied to books and a behaviour that summarises them" --model fast
431
431
  $ webcortex check # boot-time validation, with hints
432
+ $ webcortex doctor # keys present? models resolve? port free? e-stop?
433
+ $ webcortex status # what the running app is doing, and what just failed
434
+ $ webcortex explain WC402 # what an error code means and what to do
432
435
  ```
433
436
 
437
+ Every failure carries a stable code and a hint — in HTTP error bodies, agent runs, MCP
438
+ tool errors and the CLI — and the live view at `/_webcortex/status` (also the
439
+ `webcortex_status` MCP tool) shows recent failures by code and request id, runs in
440
+ flight, spend and devices. On eighteen scripted broken scenarios, 2.5.0 gives a code and
441
+ a hint for 18/18 where 2.4.0 gave none; see
442
+ [benchmarks/diagnostics/RESULTS.md](benchmarks/diagnostics/RESULTS.md) and
443
+ [docs/diagnostics.md](docs/diagnostics.md).
444
+
434
445
  The **context pack** is the app's shape — routes, tools and schemas, agents,
435
446
  behaviours, flows, context, memory, models, security posture — derived from the
436
447
  manifest in a few thousand tokens, plus a cheat sheet of the framework's API.
@@ -457,6 +468,10 @@ webcortex typegen generate a typed TypeScript client
457
468
  webcortex openapi the OpenAPI 3.1 document
458
469
  webcortex sql DDL for declared resources and memories
459
470
  webcortex keygen mint an API key
471
+ webcortex doctor check the app is ready to run (exit 1 on a failure)
472
+ webcortex status the running app's live view: requests, errors, runs, spend, devices
473
+ webcortex explain CODE what an error code means; --list for all of them
474
+ webcortex halt | release the emergency stop for actuators
460
475
  ```
461
476
 
462
477
  ## Security
@@ -482,7 +497,7 @@ tested, the known limits, and what v2 added to the surface.
482
497
 
483
498
  ## Status
484
499
 
485
- v2.3.0. Working and tested: the manifest IR, router, native ops (static /
500
+ v2.5.0. Working and tested: the manifest IR, router, native ops (static /
486
501
  query / proxy / page / files / flow), the free-threaded Python bridge,
487
502
  authentication and scopes, rate limiting, CORS, security headers, graceful
488
503
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -492,7 +507,9 @@ OpenAI-compatible, which covers local models), prompt caching, the spend
492
507
  ledger, the audit trail, OpenAPI, the MCP server, TypeScript generation, the
493
508
  context pack and `evolve`, images in and out of agent runs and MCP, actuators
494
509
  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
510
+ ingest and streams, agents over WebSocket), and diagnostics (stable error codes
511
+ with hints on every failure, `webcortex doctor`, the live `/_webcortex/status`
512
+ view and its MCP tool). **490 tests** (155 Rust, 335 Python, including a
496
513
  54-test adversarial suite and offline end-to-end suites that drive the whole
497
514
  agent stack over HTTP), clippy clean.
498
515
 
@@ -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,49 +335,17 @@ 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>,
331
345
  ) -> BoxFuture<'a, Result<ProviderResponse, String>> {
332
346
  Box::pin(async move {
333
347
  let agent = req.agent;
334
- let mut messages: Vec<Value> = Vec::new();
335
- let system = full_system(req);
336
- if !system.is_empty() {
337
- messages.push(json!({"role": "system", "content": system}));
338
- }
339
- for m in &req.conversation.messages {
340
- messages.extend(to_openai_messages(&m.role, &m.content));
341
- }
342
-
343
- let mut body = json!({
344
- "model": agent.model,
345
- "max_tokens": agent.max_tokens,
346
- "messages": messages,
347
- });
348
- if let Some(t) = agent.temperature {
349
- body["temperature"] = json!(t);
350
- }
351
- if !req.tools.is_empty() {
352
- body["tools"] = Value::Array(
353
- req.tools
354
- .iter()
355
- .map(|t| {
356
- json!({
357
- "type": "function",
358
- "function": {
359
- "name": t.name,
360
- "description": t.description,
361
- "parameters": t.input_schema,
362
- }
363
- })
364
- })
365
- .collect(),
366
- );
367
- if let Some(name) = req.force_tool {
368
- body["tool_choice"] = json!({"type": "function", "function": {"name": name}});
369
- }
370
- }
348
+ let body = openai_body(req);
371
349
 
372
350
  let mut builder = self
373
351
  .client
@@ -402,6 +380,54 @@ impl ModelProvider for OpenAiCompatProvider {
402
380
  }
403
381
  }
404
382
 
383
+ /// The Chat Completions request for one step.
384
+ pub fn openai_body(req: &CompletionRequest) -> Value {
385
+ let agent = req.agent;
386
+ let mut messages: Vec<Value> = Vec::new();
387
+ let system = full_system(req);
388
+ if !system.is_empty() {
389
+ messages.push(json!({"role": "system", "content": system}));
390
+ }
391
+ for m in &req.conversation.messages {
392
+ messages.extend(to_openai_messages(&m.role, &m.content));
393
+ }
394
+
395
+ let mut body = json!({
396
+ "model": agent.model,
397
+ "max_tokens": agent.max_tokens,
398
+ "messages": messages,
399
+ });
400
+ if let Some(t) = agent.temperature {
401
+ body["temperature"] = json!(t);
402
+ }
403
+ // Only when the app set it. `none` is how a local thinking model (Qwen,
404
+ // Gemma 4, MiniCPM through Ollama) is told to answer instead of deliberate.
405
+ if let Some(r) = &agent.reasoning {
406
+ body["reasoning_effort"] = json!(r);
407
+ }
408
+ if !req.tools.is_empty() {
409
+ body["tools"] = Value::Array(
410
+ req.tools
411
+ .iter()
412
+ .map(|t| {
413
+ json!({
414
+ "type": "function",
415
+ "function": {
416
+ "name": t.name,
417
+ "description": t.description,
418
+ "parameters": t.input_schema,
419
+ }
420
+ })
421
+ })
422
+ .collect(),
423
+ );
424
+ if let Some(name) = req.force_tool {
425
+ body["tool_choice"] = json!({"type": "function", "function": {"name": name}});
426
+ }
427
+ }
428
+ body
429
+ }
430
+
405
431
  /// Translate one canonical (Anthropic-shaped) message into OpenAI messages.
406
432
  /// A user turn holding tool results becomes one `tool` message per result.
407
433
  ///
@@ -582,21 +608,19 @@ pub fn parse_openai(payload: &Value, model: &str) -> Result<ProviderResponse, St
582
608
  /// return structured output" failures into successes.
583
609
  pub fn recover_json(text: &str) -> Option<Value> {
584
610
  let trimmed = text.trim();
585
- if let Ok(v) = serde_json::from_str::<Value>(trimmed) {
586
- 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()) {
587
613
  return Some(v);
588
614
  }
589
- }
590
615
  let unfenced = trimmed
591
616
  .strip_prefix("```json")
592
617
  .or_else(|| trimmed.strip_prefix("```"))
593
618
  .and_then(|s| s.strip_suffix("```"))
594
619
  .map(str::trim);
595
- if let Some(inner) = unfenced {
596
- 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) {
597
622
  return Some(v);
598
623
  }
599
- }
600
624
  // The first balanced `{ … }` in the text.
601
625
  let start = trimmed.find('{')?;
602
626
  let mut depth = 0i32;
@@ -979,6 +1003,14 @@ impl ModelProvider for FakeProvider {
979
1003
  );
980
1004
  }
981
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
+
982
1014
  let mut calls = Vec::new();
983
1015
  let mut raw = Vec::new();
984
1016
  for (i, clause) in text.split(';').map(str::trim).enumerate() {
@@ -1033,6 +1065,23 @@ mod tests {
1033
1065
  assert_eq!(body(&agent)["temperature"], json!(0.2f32));
1034
1066
  }
1035
1067
 
1068
+ #[test]
1069
+ fn reasoning_is_sent_as_reasoning_effort_only_on_the_openai_format() {
1070
+ let mut agent: AgentDef =
1071
+ serde_json::from_value(json!({"name": "a", "model": "ollama/qwen3.5:4b"})).unwrap();
1072
+ let conversation = Conversation::default();
1073
+ fn request<'a>(agent: &'a AgentDef, conversation: &'a Conversation) -> CompletionRequest<'a> {
1074
+ CompletionRequest { agent, conversation, tools: &[], force_tool: None, system_suffix: "" }
1075
+ }
1076
+ assert!(openai_body(&request(&agent, &conversation)).get("reasoning_effort").is_none());
1077
+ agent.reasoning = Some("none".into());
1078
+ assert_eq!(openai_body(&request(&agent, &conversation))["reasoning_effort"], json!("none"));
1079
+ assert!(
1080
+ anthropic_body(&request(&agent, &conversation)).get("reasoning_effort").is_none(),
1081
+ "the Anthropic format has no such field"
1082
+ );
1083
+ }
1084
+
1036
1085
  #[test]
1037
1086
  fn parses_a_text_response() {
1038
1087
  let payload = json!({
@@ -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
  }