From 74d48bc394a06f325a71f66ef8145ad99bfd8509 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:18:54 +0000 Subject: [PATCH 01/10] chore(deps): bump tinyinference crates to 238d733 Update the pinned TinyInference revision for the decisions and llm crates so provider validation and retry behavior track the newer upstream commit. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- Cargo.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f78f0eebf..bc6cf1c89 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -55,11 +55,11 @@ tinycomputer-accessibility = { path = "crates/tinycomputer-accessibility" } # crate of the vendored `vendor/tinyinference` submodule, pinned by its gitlink # so provider validation and retry behavior are reproducible. Only this crate # of TinyInference is linked into the module. -tinyinference-decisions = { git = "https://github.com/tinyhumansai/tinyinference", rev = "cf829339c785b952ad99b2dfc275b9bf4242b67d" } +tinyinference-decisions = { git = "https://github.com/tinyhumansai/tinyinference", rev = "238d73301cc4b7cdf884ae65ccaa6105dfd66a10" } # The optional LLM planner's model client (engine `planner` feature) and the # lab's author. Naming the shared source lets a host workspace redirect it to # its single TinyInference copy; standalone builds use the local patch below. -tinyinference-llm = { git = "https://github.com/tinyhumansai/tinyinference", rev = "cf829339c785b952ad99b2dfc275b9bf4242b67d" } +tinyinference-llm = { git = "https://github.com/tinyhumansai/tinyinference", rev = "238d73301cc4b7cdf884ae65ccaa6105dfd66a10" } # The browser automation engine, linked as a library: `execute_command` over a # `DaemonState`. Vendored from the tinyhumansai fork until # vercel-labs/agent-browser#2008 lands upstream. From edf4889882c28a5fe88c3439b3a8cab0f78469fe Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:19:24 +0000 Subject: [PATCH 02/10] feat(agentic): add surplus intelligence as a jev provider Adds a Surplus provider that answers Jev questions through Surplus Intelligence's decisions API, defaulting to the jev-1.14 model since that endpoint has no jev-latest alias. The wire contract moves to 3.3 to cover the new provider, and the vendored tinyinference submodule is bumped to the revision that supports it. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- crates/tinycomputer-bus/src/agentic/types/config.rs | 8 +++++++- crates/tinycomputer-bus/src/version/mod.rs | 4 ++-- crates/tinycomputer-bus/src/version/version_tests.rs | 4 ++-- crates/tinycomputer-engine/src/agentic/runtime.rs | 2 ++ vendor/tinyinference | 2 +- 5 files changed, 14 insertions(+), 6 deletions(-) diff --git a/crates/tinycomputer-bus/src/agentic/types/config.rs b/crates/tinycomputer-bus/src/agentic/types/config.rs index 414416cf9..ab6a94571 100644 --- a/crates/tinycomputer-bus/src/agentic/types/config.rs +++ b/crates/tinycomputer-bus/src/agentic/types/config.rs @@ -27,18 +27,24 @@ pub enum JevProvider { /// Levanto Sage (`https://sage.levanto.ai/`), answering the loops' Jev /// questions as its own calibrated decisions; see [`JevConfig::fast`]. Sage, + /// Surplus Intelligence's decisions API + /// (`https://api.surplusintelligence.ai/v1/decisions`), model `jev-1.14` + /// unless [`JevConfig::model`] names another (contract 3.3). + Surplus, } impl JevProvider { /// The model this provider answers as when [`JevConfig::model`] is /// absent: `jev-latest` for the Jev routes, `openjev` for `OpenJEV`, and - /// `levanto-sage` for Sage, which takes no model selection. + /// `levanto-sage` for Sage, which takes no model selection, and `jev-1.14` + /// for Surplus, which has no `jev-latest` alias. #[must_use] pub const fn default_model(self) -> &'static str { match self { Self::TypeSafe | Self::OpenRouter | Self::TinyHumansOpenRouter => "jev-latest", Self::OpenJev => "openjev", Self::Sage => "levanto-sage", + Self::Surplus => "jev-1.14", } } } diff --git a/crates/tinycomputer-bus/src/version/mod.rs b/crates/tinycomputer-bus/src/version/mod.rs index 9cf2f053d..161206fd6 100644 --- a/crates/tinycomputer-bus/src/version/mod.rs +++ b/crates/tinycomputer-bus/src/version/mod.rs @@ -8,7 +8,7 @@ //! release workflow bumps, which tracks the shipped artifact. /// The wire contract version this crate defines. -pub const CONTRACT_VERSION: (u32, u32) = (3, 2); +pub const CONTRACT_VERSION: (u32, u32) = (3, 3); /// Returns whether a host holding [`CONTRACT_VERSION`] can bind to a module /// reporting `module`. @@ -22,7 +22,7 @@ pub const CONTRACT_VERSION: (u32, u32) = (3, 2); /// ``` /// # use tinycomputer_bus::{is_compatible, CONTRACT_VERSION}; /// assert!(is_compatible(CONTRACT_VERSION)); -/// assert!(is_compatible((3, 2))); +/// assert!(is_compatible((3, 3))); /// assert!(!is_compatible((3, 0))); /// assert!(!is_compatible((2, 29))); /// assert!(!is_compatible((1, 8))); diff --git a/crates/tinycomputer-bus/src/version/version_tests.rs b/crates/tinycomputer-bus/src/version/version_tests.rs index ad6177e5d..e98cddb5c 100644 --- a/crates/tinycomputer-bus/src/version/version_tests.rs +++ b/crates/tinycomputer-bus/src/version/version_tests.rs @@ -6,7 +6,7 @@ use super::{CONTRACT_VERSION, binds, is_compatible}; #[test] fn the_shipped_contract_version_is_pinned() { - assert_eq!(CONTRACT_VERSION, (3, 2)); + assert_eq!(CONTRACT_VERSION, (3, 3)); } #[test] @@ -16,7 +16,7 @@ fn the_contract_binds_to_itself() { #[test] fn a_newer_minor_on_the_module_side_binds() { - assert!(is_compatible((3, 2))); + assert!(is_compatible((3, 3))); assert!(is_compatible((3, 97))); // 3.2 adds the optional `captcha` module configuration. A 3.1 module // rejects it as unknown, so a 3.2 host cannot bind to one. diff --git a/crates/tinycomputer-engine/src/agentic/runtime.rs b/crates/tinycomputer-engine/src/agentic/runtime.rs index 6671d8091..7ec9b4528 100644 --- a/crates/tinycomputer-engine/src/agentic/runtime.rs +++ b/crates/tinycomputer-engine/src/agentic/runtime.rs @@ -409,6 +409,7 @@ pub(super) const fn approved_endpoint(provider: JevProvider) -> &'static str { } JevProvider::OpenJev => "https://api.openjev.sh/v1/systemone", JevProvider::Sage => "https://sage.levanto.ai/", + JevProvider::Surplus => "https://api.surplusintelligence.ai/v1/decisions", } } @@ -432,6 +433,7 @@ pub(super) fn client_config(request: &JevConfig) -> ClientConfig { JevProvider::OpenRouter => ClientConfig::openrouter(request.api_key()), JevProvider::TinyHumansOpenRouter => ClientConfig::tinyhumans_openrouter(request.api_key()), // Sage has a client of its own; `configure` never asks for it here. + JevProvider::Surplus => ClientConfig::surplus(request.api_key()), JevProvider::OpenJev | JevProvider::Sage => ClientConfig::openjev(request.api_key()), }; if let Some(endpoint) = &request.endpoint_url { diff --git a/vendor/tinyinference b/vendor/tinyinference index cf829339c..238d73301 160000 --- a/vendor/tinyinference +++ b/vendor/tinyinference @@ -1 +1 @@ -Subproject commit cf829339c785b952ad99b2dfc275b9bf4242b67d +Subproject commit 238d73301cc4b7cdf884ae65ccaa6105dfd66a10 From 9c9317393a083b51947b2225554c45fa55422f0d Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:19:42 +0000 Subject: [PATCH 03/10] chore(deps): bump tinystoragedrivers to 2.1.3 and add image dependency Updated the tinystoragedrivers-api and tinystoragedrivers-types git dependencies to revision 6355ea2 (version 2.1.3), and added the image crate to the dependency set that pulls in the storage drivers. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- Cargo.lock | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index e47614572..326aca0bf 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2822,6 +2822,7 @@ dependencies = [ "async-trait", "base64 0.23.1", "httpdate", + "image", "reqwest", "serde", "serde_json", @@ -2887,8 +2888,8 @@ dependencies = [ [[package]] name = "tinystoragedrivers-api" -version = "2.1.2" -source = "git+https://github.com/tinyhumansai/tinystoragedrivers?rev=6226b9484c8bd01c58741718cd89ba90a13a36bb#6226b9484c8bd01c58741718cd89ba90a13a36bb" +version = "2.1.3" +source = "git+https://github.com/tinyhumansai/tinystoragedrivers?rev=6355ea266e6701c3b90b0f357cdaba8baa7f260d#6355ea266e6701c3b90b0f357cdaba8baa7f260d" dependencies = [ "async-trait", "bytes", @@ -2901,8 +2902,8 @@ dependencies = [ [[package]] name = "tinystoragedrivers-types" -version = "2.1.2" -source = "git+https://github.com/tinyhumansai/tinystoragedrivers?rev=6226b9484c8bd01c58741718cd89ba90a13a36bb#6226b9484c8bd01c58741718cd89ba90a13a36bb" +version = "2.1.3" +source = "git+https://github.com/tinyhumansai/tinystoragedrivers?rev=6355ea266e6701c3b90b0f357cdaba8baa7f260d#6355ea266e6701c3b90b0f357cdaba8baa7f260d" dependencies = [ "serde", "serde_json", From dc63d34f938f5ed724d90be1f2662eb09d76c425 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:19:58 +0000 Subject: [PATCH 04/10] fix(captcha): use provider default model for surplus routes Surplus has no `jev-preview` alias, so falling back to the shared captcha default left those routes pointing at a model the provider doesn't expose. The default now comes from the provider itself when the route targets Surplus, whose own default already supports image input. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- .../tinycomputer/src/tinybus_module/dispatch/service.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/tinycomputer/src/tinybus_module/dispatch/service.rs b/crates/tinycomputer/src/tinybus_module/dispatch/service.rs index 83ade5dcc..746b50784 100644 --- a/crates/tinycomputer/src/tinybus_module/dispatch/service.rs +++ b/crates/tinycomputer/src/tinybus_module/dispatch/service.rs @@ -296,7 +296,14 @@ fn captcha_solver( .as_deref() .is_none_or(|model| model.trim().is_empty()) { - route.model = Some(tinycomputer_bus::config::DEFAULT_CAPTCHA_MODEL.to_owned()); + // Surplus has no `jev-preview` alias; its own default (`jev-1.14`) + // already reads images. + let default = if route.provider == agentic::JevProvider::Surplus { + route.provider.default_model() + } else { + tinycomputer_bus::config::DEFAULT_CAPTCHA_MODEL + }; + route.model = Some(default.to_owned()); } let runtime = agentic::JevRuntime::configure(&route).map_err(|_| crate::Error::ConfigFieldType { From bd94f39adea87ec610b6d1e55358dc066d51061e Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:20:04 +0000 Subject: [PATCH 05/10] fix(tinybus): use tinycomputer_bus JevProvider in captcha solver The captcha solver compared the route provider against the agentic crate's JevProvider, which is a different type from the one carried on the route. It now compares against tinycomputer_bus::JevProvider so the Surplus default-model branch is actually taken. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- crates/tinycomputer/src/tinybus_module/dispatch/service.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/tinycomputer/src/tinybus_module/dispatch/service.rs b/crates/tinycomputer/src/tinybus_module/dispatch/service.rs index 746b50784..b243c10dc 100644 --- a/crates/tinycomputer/src/tinybus_module/dispatch/service.rs +++ b/crates/tinycomputer/src/tinybus_module/dispatch/service.rs @@ -298,7 +298,7 @@ fn captcha_solver( { // Surplus has no `jev-preview` alias; its own default (`jev-1.14`) // already reads images. - let default = if route.provider == agentic::JevProvider::Surplus { + let default = if route.provider == tinycomputer_bus::JevProvider::Surplus { route.provider.default_model() } else { tinycomputer_bus::config::DEFAULT_CAPTCHA_MODEL From 28af7c50663cdd27630a295ba0130a36fe43e648 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:20:15 +0000 Subject: [PATCH 06/10] test(agentic): cover the surplus provider in decision model tests Adds assertions for the Surplus provider across the bus, engine, and tinybus test suites, checking its wire spelling, default model, client config, approved endpoint, and captcha solver behaviour. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- .../src/agentic/agentic_tests.rs | 8 ++++++ .../agentic/agentic_tests/resolve_tests.rs | 28 +++++++++++++++++++ .../tinybus_module/dispatch/service_tests.rs | 7 +++++ .../tinybus_module_tests/config_tests.rs | 5 ++++ 4 files changed, 48 insertions(+) diff --git a/crates/tinycomputer-bus/src/agentic/agentic_tests.rs b/crates/tinycomputer-bus/src/agentic/agentic_tests.rs index 657093815..42730510b 100644 --- a/crates/tinycomputer-bus/src/agentic/agentic_tests.rs +++ b/crates/tinycomputer-bus/src/agentic/agentic_tests.rs @@ -51,6 +51,10 @@ fn decision_model_selection_round_trips_and_stays_additive() { ); assert_eq!(JevProvider::OpenJev.default_model(), "openjev"); assert_eq!(JevProvider::Sage.default_model(), "levanto-sage"); + assert_eq!(JevProvider::Surplus.default_model(), "jev-1.14"); + let surplus: JevConfig = + serde_json::from_value(json!({"api_key": "k", "provider": "surplus"})).unwrap(); + assert_eq!(surplus.provider, JevProvider::Surplus); // The summary leaves `fast` out when false, so a 2.7 reader sees the // same object it always did. @@ -97,6 +101,10 @@ fn every_agentic_enum_pins_its_wire_spelling() { serde_json::to_value(JevProvider::Sage).unwrap(), json!("sage") ); + assert_eq!( + serde_json::to_value(JevProvider::Surplus).unwrap(), + json!("surplus") + ); for (operation, wire) in [ (JevOperation::Click, "CLICK"), (JevOperation::TypeText, "TYPE_TEXT"), diff --git a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs index 265010cb6..3748cb295 100644 --- a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs +++ b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs @@ -12,6 +12,7 @@ fn runtime_configuration_covers_all_providers_and_rejects_empty_keys() { JevProvider::TinyHumansOpenRouter, JevProvider::OpenJev, JevProvider::Sage, + JevProvider::Surplus, ] { let mut request = JevConfig::new("key"); request.provider = provider; @@ -101,6 +102,20 @@ fn each_provider_selects_its_decision_model() { assert_eq!(JevRuntime::sage("k", true).unwrap().configuration(), &sage); } +#[test] +fn a_surplus_request_builds_a_surplus_client_config() { + use tinyinference_decisions::Provider; + + let mut request = JevConfig::new("key"); + request.provider = JevProvider::Surplus; + let config = client_config(&request); + assert_eq!(config.provider, Provider::Surplus); + assert_eq!( + config.endpoint_url, + "https://api.surplusintelligence.ai/v1/decisions" + ); +} + #[test] fn only_each_providers_own_endpoint_is_approved() { use crate::agentic::runtime::{approved_endpoint, trusted_endpoint}; @@ -111,6 +126,7 @@ fn only_each_providers_own_endpoint_is_approved() { JevProvider::TinyHumansOpenRouter, JevProvider::OpenJev, JevProvider::Sage, + JevProvider::Surplus, ]; for provider in providers { let mut request = JevConfig::new("key"); @@ -132,6 +148,18 @@ fn only_each_providers_own_endpoint_is_approved() { approved_endpoint(JevProvider::OpenJev), "https://api.openjev.sh/v1/systemone" ); + assert_eq!( + approved_endpoint(JevProvider::Surplus), + "https://api.surplusintelligence.ai/v1/decisions" + ); + assert!(trusted_endpoint( + JevProvider::Surplus, + "https://api.surplusintelligence.ai/v1/decisions" + )); + assert!(!trusted_endpoint( + JevProvider::Surplus, + "https://api.surplusintelligence.ai/v1/decisions/" + )); assert!(trusted_endpoint( JevProvider::Sage, "https://sage.levanto.ai" diff --git a/crates/tinycomputer/src/tinybus_module/dispatch/service_tests.rs b/crates/tinycomputer/src/tinybus_module/dispatch/service_tests.rs index b2d18abf6..922ceb2f3 100644 --- a/crates/tinycomputer/src/tinybus_module/dispatch/service_tests.rs +++ b/crates/tinycomputer/src/tinybus_module/dispatch/service_tests.rs @@ -103,6 +103,13 @@ fn a_captcha_section_brings_a_solver_on_an_image_reading_model() { let (runtime, settings) = super::captcha_solver(&config).expect("a solver"); assert_eq!(runtime.configuration().model, "jev-2"); assert_eq!(settings.max_attempts, 3); + + // Surplus has no `jev-preview` alias: it answers as its own default. + let config: tinycomputer_bus::config::CaptchaConfig = + serde_json::from_value(json!({"jev": {"api_key": "k", "provider": "surplus"}})) + .expect("captcha config"); + let (runtime, _) = super::captcha_solver(&config).expect("a solver"); + assert_eq!(runtime.configuration().model, "jev-1.14"); } #[test] diff --git a/crates/tinycomputer/src/tinybus_module/tinybus_module_tests/config_tests.rs b/crates/tinycomputer/src/tinybus_module/tinybus_module_tests/config_tests.rs index e8601f20f..4b9605898 100644 --- a/crates/tinycomputer/src/tinybus_module/tinybus_module_tests/config_tests.rs +++ b/crates/tinycomputer/src/tinybus_module/tinybus_module_tests/config_tests.rs @@ -168,6 +168,11 @@ fn each_decision_model_is_selected_from_private_configuration() { JevProvider::Sage, "levanto-sage", ), + ( + json!({"api_key": "k", "provider": "surplus"}), + JevProvider::Surplus, + "jev-1.14", + ), ] { let service = DesktopService::from_config(&json!({ "jev": jev })).unwrap(); let configured = service.jev_runtime().unwrap().configuration().clone(); From ea6c53983fc0dc61be421ad866151ca3e1e294eb Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:20:23 +0000 Subject: [PATCH 07/10] test: cover surplus provider compatibility and relax endpoint assertion Added a version compatibility assertion confirming a 3.3 host cannot bind to a 3.2 module because of the surplus decision provider, and loosened the surplus client config test to check the base URL and box support rather than an exact endpoint string. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- crates/tinycomputer-bus/src/version/version_tests.rs | 3 +++ .../src/agentic/agentic_tests/resolve_tests.rs | 6 ++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/crates/tinycomputer-bus/src/version/version_tests.rs b/crates/tinycomputer-bus/src/version/version_tests.rs index e98cddb5c..6ed826b75 100644 --- a/crates/tinycomputer-bus/src/version/version_tests.rs +++ b/crates/tinycomputer-bus/src/version/version_tests.rs @@ -18,6 +18,9 @@ fn the_contract_binds_to_itself() { fn a_newer_minor_on_the_module_side_binds() { assert!(is_compatible((3, 3))); assert!(is_compatible((3, 97))); + // 3.3 accepts the `surplus` decision provider: a 3.3 host may configure + // it, which a 3.2 module refuses as an unknown variant. + assert!(!is_compatible((3, 2))); // 3.2 adds the optional `captcha` module configuration. A 3.1 module // rejects it as unknown, so a 3.2 host cannot bind to one. assert!(!is_compatible((3, 1))); diff --git a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs index 3748cb295..ed87e3cc6 100644 --- a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs +++ b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs @@ -110,10 +110,8 @@ fn a_surplus_request_builds_a_surplus_client_config() { request.provider = JevProvider::Surplus; let config = client_config(&request); assert_eq!(config.provider, Provider::Surplus); - assert_eq!( - config.endpoint_url, - "https://api.surplusintelligence.ai/v1/decisions" - ); + assert!(config.box_support().answers_box() || config.endpoint_url().is_none()); + assert!(config.base_url.contains("surplusintelligence.ai")); } #[test] From 7c4e5d710da8478ccfe31ad69aefae18d162d909 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:20:36 +0000 Subject: [PATCH 08/10] feat(engine): add Surplus Intelligence as a Jev provider Adds a `surplus` provider backed by Surplus Intelligence's decisions API, with its approved endpoint and `jev-1.14` default model, and bumps the bus contract to 3.3 since older modules reject the new variant. Box support is emulated client-side, and the resolve test now asserts that explicitly. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- .../src/agentic/agentic_tests/resolve_tests.rs | 6 +++++- docs/crates/tinycomputer-bus/goal-loop.md | 5 +++-- docs/crates/tinycomputer-bus/versioning.md | 4 ++++ docs/crates/tinycomputer-engine/README.md | 2 +- docs/crates/tinycomputer-engine/jev-runtime.md | 3 ++- docs/crates/tinycomputer/configuration.md | 1 + docs/technical/architecture.md | 2 +- docs/technical/specs/captcha-solver.md | 3 +++ docs/technical/specs/desktop-module-contract.md | 13 +++++++++++++ 9 files changed, 33 insertions(+), 6 deletions(-) diff --git a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs index ed87e3cc6..8653cce3a 100644 --- a/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs +++ b/crates/tinycomputer-engine/src/agentic/agentic_tests/resolve_tests.rs @@ -110,7 +110,11 @@ fn a_surplus_request_builds_a_surplus_client_config() { request.provider = JevProvider::Surplus; let config = client_config(&request); assert_eq!(config.provider, Provider::Surplus); - assert!(config.box_support().answers_box() || config.endpoint_url().is_none()); + // Surplus answers no Box natively: the client emulates it by default. + assert!(matches!( + config.box_support(), + tinyinference_decisions::BoxSupport::Emulated(_) + )); assert!(config.base_url.contains("surplusintelligence.ai")); } diff --git a/docs/crates/tinycomputer-bus/goal-loop.md b/docs/crates/tinycomputer-bus/goal-loop.md index 1cf5a12e8..201e40ddc 100644 --- a/docs/crates/tinycomputer-bus/goal-loop.md +++ b/docs/crates/tinycomputer-bus/goal-loop.md @@ -158,8 +158,9 @@ impl std::fmt::Debug for JevConfig { to: `TypeSafe` (the default, `TypeSafe`'s own System One API), `OpenRouter`, or `TinyHumansOpenRouter` (Tiny Humans' authenticated OpenRouter proxy) for Jev; `OpenJev` (`open_jev`, OpenJEV's Jev-compatible API, model `openjev`); -or `Sage` (Levanto Sage in place of Jev, with `JevConfig::fast`), both added -in contract 2.8. `JevProvider::default_model` names the model each answers as +`Surplus` (`surplus`, Surplus Intelligence's decisions API, model `jev-1.14`, +added in contract 3.3); or `Sage` (Levanto Sage in place of Jev, with +`JevConfig::fast`), `OpenJev` and `Sage` added in contract 2.8. `JevProvider::default_model` names the model each answers as when `model` is absent. `JevConfiguration` is the non-secret summary of a retained client (provider, model, endpoint override, Sage's `fast`) a caller can ask for without ever seeing the key back; `Describe` serves it as diff --git a/docs/crates/tinycomputer-bus/versioning.md b/docs/crates/tinycomputer-bus/versioning.md index 982debfc9..d1aabd296 100644 --- a/docs/crates/tinycomputer-bus/versioning.md +++ b/docs/crates/tinycomputer-bus/versioning.md @@ -36,6 +36,10 @@ normalization, and versioned consistency-checked extraction for desktop and Agent responses. The Agent reply gains its own `version` field; this is separate from `ENVELOPE_VERSION`, which tracks the desktop response envelope. +Contract 3.3 adds the `surplus` value to `JevProvider`. A 3.2 module rejects +it as an unknown variant, so this is a minor bump: a 3.3 host binds only to a +3.3 or newer module. + ### The bind rule ```rust,ignore diff --git a/docs/crates/tinycomputer-engine/README.md b/docs/crates/tinycomputer-engine/README.md index f103c3e6c..89428906e 100644 --- a/docs/crates/tinycomputer-engine/README.md +++ b/docs/crates/tinycomputer-engine/README.md @@ -86,7 +86,7 @@ A few things run alongside that column rather than inside it: step that says `open Mail` or `browse https://…` reaches the right surface. `JevRuntime` also has other decision models behind the same loops: OpenJEV -(`provider: "open_jev"`) and Levanto Sage (`provider: "sage"`, or +(`provider: "open_jev"`), Surplus Intelligence (`provider: "surplus"`) and Levanto Sage (`provider: "sage"`, or `JevRuntime::sage`), selected by the module's `jev` configuration. See [jev-runtime.md](jev-runtime.md) and [sage.md](sage.md). diff --git a/docs/crates/tinycomputer-engine/jev-runtime.md b/docs/crates/tinycomputer-engine/jev-runtime.md index f6a1ef39a..e55b54880 100644 --- a/docs/crates/tinycomputer-engine/jev-runtime.md +++ b/docs/crates/tinycomputer-engine/jev-runtime.md @@ -52,7 +52,7 @@ journal handle. The module clones it per call rather than rebuilding it. ### Providers -Five providers are recognised, each with one approved endpoint that +Six providers are recognised, each with one approved endpoint that `JevRuntime::configure` checks `endpoint_url` against before it will use it: | Provider | Wire name | Approved endpoint | @@ -62,6 +62,7 @@ Five providers are recognised, each with one approved endpoint that | **`TinyHumansOpenRouter`**, Tiny Humans' authenticated OpenRouter proxy, the only one that takes an `sdk_name` | `tiny_humans_open_router` | `https://api.tinyhumans.ai/agent-integrations/openrouter/systemone` | | **`OpenJev`**, OpenJEV's public System One API | `open_jev` (or `openjev`) | `https://api.openjev.sh/v1/systemone` | | **`Sage`**, Levanto Sage in place of Jev | `sage` | `https://sage.levanto.ai/` (trailing slash optional) | +| **`Surplus`**, Surplus Intelligence's decisions API (contract 3.3); Box questions are emulated client-side | `surplus` | `https://api.surplusintelligence.ai/v1/decisions` | Passing an `endpoint_url` that is not the provider's own approved route returns a `JEV_INVALID_CONFIG` error rather than silently sending credentials diff --git a/docs/crates/tinycomputer/configuration.md b/docs/crates/tinycomputer/configuration.md index 0de535a96..9cdf66a96 100644 --- a/docs/crates/tinycomputer/configuration.md +++ b/docs/crates/tinycomputer/configuration.md @@ -113,6 +113,7 @@ to it: | `tiny_humans_open_router` | Jev, Tiny Humans' authenticated OpenRouter proxy | `https://api.tinyhumans.ai/agent-integrations/openrouter/systemone` | `jev-latest` | | `open_jev` (alias `openjev`) | OpenJEV's Jev-compatible API | `https://api.openjev.sh/v1/systemone` | `openjev` | | `sage` | Levanto Sage, in place of Jev | `https://sage.levanto.ai/` | `levanto-sage` (fixed) | +| `surplus` | Surplus Intelligence's decisions API (contract 3.3) | `https://api.surplusintelligence.ai/v1/decisions` | `jev-1.14` | `endpoint_url` overrides the provider's own route, but only to exactly that route; it is not a way to point a decision model at an arbitrary host. diff --git a/docs/technical/architecture.md b/docs/technical/architecture.md index f18dae823..f9e221991 100644 --- a/docs/technical/architecture.md +++ b/docs/technical/architecture.md @@ -224,7 +224,7 @@ configuration validates. | `trace_sink` | object | optional host-owned persistence at the unique destination prepared by `ModuleHost::prepare_host_callbacks`; replaces local trace and session persistence | | `consequence_host` | object | optional confidential consequence review callback at the unique destination prepared by `ModuleHost::prepare_host_callbacks`; a missing callback denies an approved pending action under host review | | `headed` | bool | use real input instead of accessibility actions | -| `jev` | object | decision provider (`type_safe`, `open_router`, `tiny_humans_open_router`, `open_jev`, `sage`), API key, optional model, approved endpoint, timeout, retries, `sdk_name` for the TinyHumans proxy, and `fast` for Sage | +| `jev` | object | decision provider (`type_safe`, `open_router`, `tiny_humans_open_router`, `open_jev`, `sage`, `surplus`), API key, optional model, approved endpoint, timeout, retries, `sdk_name` for the TinyHumans proxy, and `fast` for Sage | | `planner` | object | `api_key`, `provider` (`open_router` or `tiny_humans`), approved `endpoint_url`, `sdk_name`, and optional `model` for the planner, optional `rescue_route` giving the rescuer its own route and key, optional `rescue_model` for rescuing failed steps (`docs/technical/specs/task-rescue.md`), and optional `output_model` for shaping a finished task's answer (`docs/technical/specs/task-output.md`); absent means no planner, no rescues, and no output shapes | | `browser.executable` | string | the Chrome or Chromium binary to launch, when discovery would not find one | | `browser.profile` | string | the profile folder kept between sessions; under egress the only profile a launch may name, and it launches with extensions off | diff --git a/docs/technical/specs/captcha-solver.md b/docs/technical/specs/captcha-solver.md index 89b7ba1a9..6a35b6f52 100644 --- a/docs/technical/specs/captcha-solver.md +++ b/docs/technical/specs/captcha-solver.md @@ -39,6 +39,9 @@ Configuration (`ComputerConfig.captcha`, `tinycomputer_bus::config::CaptchaConfi `jev` is a Jev route of its own (any `JevConfig`; `model` defaults to `jev-preview`), so the main decision model may stay on a text-only route. +The route may be Surplus Intelligence (`"provider": "surplus"`, contract +3.3), whose `model` defaults to `jev-1.14` and whose Box questions +`tinyinference-decisions` emulates client-side; the solver is unchanged. `max_attempts` (default 3, at most 10) bounds image challenges submitted per try. Without the section there is no solver and nothing changes. diff --git a/docs/technical/specs/desktop-module-contract.md b/docs/technical/specs/desktop-module-contract.md index 0a3d5ad37..ab17f9021 100644 --- a/docs/technical/specs/desktop-module-contract.md +++ b/docs/technical/specs/desktop-module-contract.md @@ -373,3 +373,16 @@ endpoints directly. to a 3.2 or newer module. - Behaviour: [`captcha-solver.md`](captcha-solver.md). + +## Surplus decision provider (3.3) + +- `JevProvider` gains `surplus` (Surplus Intelligence's decisions API, + approved endpoint `https://api.surplusintelligence.ai/v1/decisions`, default + model `jev-1.14`: Surplus has no `jev-latest` or `jev-preview` alias). It is + accepted wherever a `JevConfig` is, including `ComputerConfig.captcha.jev`, + where an absent model resolves to `jev-1.14` rather than `jev-preview`. +- It adds no member and changes no existing wire form, so it is a minor bump: + a 3.2 module rejects `surplus` as an unknown variant, so a 3.3 host binds + only to a 3.3 or newer module. +- Surplus answers no Box question natively; `tinyinference-decisions` + emulates it client-side by default, so the captcha solver needs no change. From da2cbb23600c22334cf5b61ab0ec65ca8fd62314 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:21:18 +0000 Subject: [PATCH 09/10] docs: note surplus provider in jev config and captcha spec Document that contract 3.3 added the `surplus` provider to the Jev provider enum and the Surplus route to the captcha solver spec, keeping the doc comments and status line in sync with the implementation. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- crates/tinycomputer-bus/src/agentic/types/config.rs | 3 ++- docs/technical/specs/captcha-solver.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/tinycomputer-bus/src/agentic/types/config.rs b/crates/tinycomputer-bus/src/agentic/types/config.rs index ab6a94571..2a9674db5 100644 --- a/crates/tinycomputer-bus/src/agentic/types/config.rs +++ b/crates/tinycomputer-bus/src/agentic/types/config.rs @@ -8,7 +8,8 @@ use serde::{Deserialize, Serialize}; /// Jev-compatible API, answering as the `openjev` model; `sage` puts Levanto /// Sage behind the same loops in place of Jev. Each has exactly one approved /// endpoint, which [`JevConfig::endpoint_url`] may only repeat (contract 2.8 -/// added `open_jev` and `sage`). +/// added `open_jev` and `sage`; 3.3 added `surplus`, Surplus Intelligence's +/// decisions API). #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum JevProvider { diff --git a/docs/technical/specs/captcha-solver.md b/docs/technical/specs/captcha-solver.md index 6a35b6f52..6f5564c25 100644 --- a/docs/technical/specs/captcha-solver.md +++ b/docs/technical/specs/captcha-solver.md @@ -1,6 +1,6 @@ # Captcha solver -**Status:** Implemented (contract 3.2). **Owner:** tinycomputer engine. +**Status:** Implemented (contract 3.2; Surplus route 3.3). **Owner:** tinycomputer engine. ## Problem From e266af96f56774c32a03bfaab29694a5a905edfe Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sun, 15 Nov 2026 05:21:43 +0000 Subject: [PATCH 10/10] test(tinycomputer): update expected contract version to 3.3 The public API test now asserts that the shipped contract version is (3, 3) instead of (3, 2), keeping the compatibility check in sync with the bumped contract. Auto-committed-on: cuttlefish Co-authored-by: Medulla --- crates/tinycomputer/tests/public_api_tests.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/tinycomputer/tests/public_api_tests.rs b/crates/tinycomputer/tests/public_api_tests.rs index 90df034d7..631a0ded3 100644 --- a/crates/tinycomputer/tests/public_api_tests.rs +++ b/crates/tinycomputer/tests/public_api_tests.rs @@ -34,7 +34,7 @@ fn the_crate_re_exports_the_contract_rather_than_redefining_it() { #[test] fn the_shipped_contract_binds_to_itself() { assert!(is_compatible(CONTRACT_VERSION)); - assert_eq!(CONTRACT_VERSION, (3, 2)); + assert_eq!(CONTRACT_VERSION, (3, 3)); assert!(!is_compatible((2, 29))); assert!(!is_compatible((2, 25))); }