Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 8 additions & 0 deletions crates/tinycomputer-bus/src/agentic/agentic_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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"),
Expand Down
11 changes: 9 additions & 2 deletions crates/tinycomputer-bus/src/agentic/types/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -27,18 +28,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",
}
}
}
Expand Down
4 changes: 2 additions & 2 deletions crates/tinycomputer-bus/src/version/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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)));
Expand Down
7 changes: 5 additions & 2 deletions crates/tinycomputer-bus/src/version/version_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -16,8 +16,11 @@ 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.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)));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -101,6 +102,22 @@ 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);
// 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"));
}

#[test]
fn only_each_providers_own_endpoint_is_approved() {
use crate::agentic::runtime::{approved_endpoint, trusted_endpoint};
Expand All @@ -111,6 +128,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");
Expand All @@ -132,6 +150,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"
Expand Down
2 changes: 2 additions & 0 deletions crates/tinycomputer-engine/src/agentic/runtime.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}
}

Expand All @@ -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 {
Expand Down
9 changes: 8 additions & 1 deletion crates/tinycomputer/src/tinybus_module/dispatch/service.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 == tinycomputer_bus::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 {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
),
] {
let service = DesktopService::from_config(&json!({ "jev": jev })).unwrap();
let configured = service.jev_runtime().unwrap().configuration().clone();
Expand Down
2 changes: 1 addition & 1 deletion crates/tinycomputer/tests/public_api_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)));
}
Expand Down
5 changes: 3 additions & 2 deletions docs/crates/tinycomputer-bus/goal-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/crates/tinycomputer-bus/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/crates/tinycomputer-engine/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
3 changes: 2 additions & 1 deletion docs/crates/tinycomputer-engine/jev-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/crates/tinycomputer/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/technical/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
5 changes: 4 additions & 1 deletion docs/technical/specs/captcha-solver.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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.

Expand Down
13 changes: 13 additions & 0 deletions docs/technical/specs/desktop-module-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion vendor/tinyinference
Loading