aside-jev

Let Aside agents decide with TypeSafe Jev — not with free-form LLM clicks.

Jev is TypeSafe’s System One model: it does not generate text. You send state + typed questions (Choice / Score / Noul) and get calibrated values your code can branch on (typically 70–500ms).

aside-jev wires that model into Aside workflows as an MCP server + skill:

1. Aside observes / executes the browser (aside mcp).

2. Your agent builds the decision (state + questions, or an app-owned action table).

3. Jev returns a typed answer (e.g. one candidate id).

4. Your agent executes only that answer via Aside, then verifies independently.

This is not a Cua integration. Cua’s jev-use demo is just one recipe that also calls Jev.
Here the runtime is Aside; the decision model is Jev.

Why Jev (not another chat model)

Docs: Introduction · Python SDK · API POST /v1/systemone

Related MCP server: Querytree MCP Server

Install

uv tool install "aside-jev @ git+https://github.com/himomohi/aside-jev"
# or
git clone https://github.com/himomohi/aside-jev.git
cd aside-jev && ./scripts/install.sh

export TYPESAFE_API_KEY=…   # also accepts TYPESAFEAI_API_KEY

Mock path needs no key (CI / demos).

MCP next to Aside

{
  "mcpServers": {
    "aside": { "command": "aside", "args": ["mcp"] },
    "aside-jev": {
      "command": "aside-jev",
      "args": ["serve"],
      "env": { "TYPESAFE_API_KEY": "${TYPESAFE_API_KEY}" }
    }
  }
}

On this machine a wrapper ~/.local/bin/aside-jev-mcp can source ~/.config/typesafe/api.env then run aside-jev serve.

Skill: skills/aside-jev/ → copied to ~/.aside/skills/ by scripts/install.sh.

MCP tools

General decisions (jev_system_one)

{
  "state": { "url": "…", "goal": "submit form", "snapshot": "…" },
  "questions": {
    "done": { "type": "noul", "instructions": "The form is already submitted" },
    "risk": {
      "type": "score",
      "instructions": "How risky is the next click",
      "criteria": ["safe", "reversible", "destructive"]
    },
    "next": {
      "type": "choice",
      "instructions": "Best next macro-step",
      "criteria": {
        "fill_fields": "Fill empty required fields",
        "submit": "Submit the form",
        "stop": "Stop and ask the user"
      }
    }
  }
}

Action IDs for Aside (jev_choose / jev_step)

Your agent enumerates complete actions (tool + args). Jev only returns one id. Aside runs that row. Unknown ids fail closed. Always include abstain.

aside-jev choose \
  --goal "fill the verification field" \
  --candidates examples/demo_candidates.json \
  --observation examples/demo_observation.json \
  --provider mock \
  --prefer type-verification-value

Safety model

1. App owns options — Choice criteria / candidate rows are defined in code.

2. Jev returns values — never selectors, never free tool names.

3. Validate before execute — unknown id → error / abstain.

4. Threshold in your code — use confidence / noul bands (auto / confirm / human).

5. Verify independently — DOM / API / /state, not model prose.

6. Keys in env only — never argv, source, or logs.

Development

uv sync --extra dev
uv run pytest -q

Python ≥ 3.11 · MIT · depends on typesafe-sdk (TypeSafeClient.system_one, model jev-latest).

Related

• TypeSafe Jev docs: https://docs.typesafe.ai

• Aside browser agent: aside mcp / aside repl

• Cua jev-use is an unrelated demo that also calls Jev with a different executor — not required here.