# copilot-jev

**Jev (TypeSafe AI) sebagai partner keputusan untuk Copilot CLI.**

LLM berpikir. Jev memutuskan. Kode mengeksekusi. Ketiganya bekerja bersama.

```
Copilot CLI (LLM)  ->  riset, perencanaan, penulisan, menyunting kode
Jev (System One)   ->  routing, scoring, approval, escalation
Kode               ->  mengeksekusi keputusan
```

Jev tidak menggantikan Copilot CLI — ia melengkapinya. Pekerjaan bahasa tetap
di LLM; keputusan berulang dipindahkan ke model yang dirancang khusus untuk
itu, dengan biaya $0,042 per juta token dan latency milidetik.

Repositori ini berisi dokumentasi berbahasa Indonesia sekaligus implementasi
yang benar-benar berjalan: task router, MCP server untuk Copilot CLI, skill,
demo terukur, dan uji otomatis.

**Terukur di mesin ini** (`jev-1.13.0`, 24 September 2026):

| | |
|---|---|
| Satu alur research → write → review | 5 panggilan, **$0,000221**, latency median 374 ms |
| Biaya per keputusan | $0,0000099 → **$0,099 per 10.000 keputusan** |
| Fan-out vs panggilan terpisah | **2,4x lebih murah, 1,6x lebih cepat** |

Detail dan cara mengukurnya sendiri: [07 — Biaya & latency](docs/07-biaya-dan-latency.md).

---

## Pasang sebagai agent skill

Skill `jev` memberi coding agent apa pun konteks penuh tentang API TypeSafe:
tiga primitive, batas kerasnya, pola fan-out, ambang confidence, dan jebakan
Noul yang tidak punya `confidence`.

### Claude Code

```bash
claude plugin marketplace add devnolife/copilot-jev
claude plugin install jev@copilot-jev
```

Invokasi langsung: `/copilot-jev:jev`

### Agent lain via skills.sh

```bash
npx skills add devnolife/copilot-jev --skill jev --agent github-copilot
```

Tanpa `--agent`, installer akan menanyakan agent mana yang dituju. Pemasangan
bersifat project-local (ke `.agents/skills/jev/`); tambahkan `-g` untuk global.

Identifier agent yang sering dipakai — gunakan **satu flag per agent**:

| Agent | `--agent` |
|---|---|
| GitHub Copilot | `github-copilot` |
| Claude Code | `claude-code` |
| Codex | `codex` |
| Cursor | `cursor` |
| Windsurf | `windsurf` |
| Gemini CLI | `gemini-cli` |
| Cline / Roo / Kilo | `cline` / `roo` / `kilo` |
| Semua agent | `*` |

Daftar lengkap (80+ agent) muncul bila Anda memberi nilai yang tidak dikenal.

Lihat isi repo tanpa memasang:

```bash
npx skills add devnolife/copilot-jev --list
```

### GitHub Copilot CLI

Cara termudah lewat skills.sh di atas. Atau manual:

```bash
git clone https://github.com/devnolife/copilot-jev
cp -r copilot-jev/skills/jev ~/.copilot/skills/jev      # global
```

Repo ini juga sudah menyertakan `.github/skills/jev/` sehingga skill langsung
aktif bila Anda bekerja di dalam repo ini. Cek dengan `/skills`.

### Manual (agent apa pun)

Salin seluruh isi [`skills/jev/`](skills/jev/) — termasuk folder
`reference/` — ke direktori skill agent Anda.

### Lewat prompt

Tempelkan ini ke agent Anda:

> Pasang skill Jev dari https://github.com/devnolife/copilot-jev. Kalau kamu
> Claude Code, jalankan `claude plugin marketplace add devnolife/copilot-jev`
> lalu `claude plugin install jev@copilot-jev`. Kalau agent lain, jalankan
> `npx skills add devnolife/copilot-jev --skill jev`. Pakai satu metode saja.
> Kamu juga bisa membaca skill-nya langsung di
> https://raw.githubusercontent.com/devnolife/copilot-jev/main/skills/jev/SKILL.md

### Memakainya

Sebut eksplisit dalam prompt:

```
Pakai skill jev. Telusuri proyek ini dan cari tempat di mana parsing rapuh
atau prompt "kembalikan JSON" bisa diganti keputusan bertipe.
```

---

---

## Mulai cepat

```powershell
cd D:\devnolife\copilot-jev
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Copy-Item .env.example .env      # lalu isi TYPESAFE_API_KEY
```

Periksa semuanya sekaligus:

```powershell
python scripts\doctor.py
```

Skrip ini memeriksa versi Python, dependensi, API key, registrasi MCP, skill,
seluruh uji otomatis, server MCP, dan — bila API key tersedia — satu panggilan
Jev sungguhan. Ia menyebutkan dengan tepat apa yang masih kurang.

Jalankan task router:

```powershell
python chief.py --goal "Compare three AI-agent tools for tomorrow's briefing" `
                --done "No sources collected yet"
```

Jalankan demo terukur:

```powershell
python demo\run_demo.py
```

> Butuh Python **>= 3.10** dan paket **`typesafe-sdk`** (bukan `typesafe`).
> Lihat [koreksi terhadap thread sumber](docs/03-setup.md#koreksi-penting-terhadap-thread-sumber).

---

## Dokumentasi

| | |
|---|---|
| [01 — Konsep](docs/01-konsep-jev.md) | Jevons Paradox, System One vs LLM, arti kalibrasi |
| [02 — Primitives](docs/02-primitives.md) | Choice, Score, Noul + bentuk request/response |
| [03 — Setup](docs/03-setup.md) | Instalasi, API key, dan koreksi thread |
| [04 — chief.py](docs/04-chief-router.md) | Task router mandiri dan cara kerjanya |
| [05 — Integrasi Copilot CLI](docs/05-integrasi-copilot-cli.md) | MCP server + skill |
| [06 — Praktik terbaik](docs/06-pola-praktik-terbaik.md) | 11 aturan yang menentukan berhasil/tidaknya |
| [07 — Biaya & latency](docs/07-biaya-dan-latency.md) | Harga, aritmetika, cara mengukur |
| [08 — Troubleshooting](docs/08-troubleshooting.md) | 401/422/429/529 dan masalah umum |

---

## Tiga cara memakainya

### 1. Lewat MCP di Copilot CLI

Server `jev` sudah terdaftar di `~/.copilot/mcp-config.json`. Jalankan `/mcp`
di Copilot CLI untuk memastikannya aktif.

| Tool | Fungsi |
|---|---|
| `jev_ask` | **Utamakan ini.** Banyak pertanyaan, satu panggilan. |
| `jev_choice` | Pilih satu dari daftar opsi (maks 255). |
| `jev_score` | Nilai terhadap rubrik 2–10 level. |
| `jev_noul` | Pertanyaan benar/salah. |
| `jev_usage` | Ringkasan biaya & latency. |

Verifikasi mandiri:

```powershell
python scripts\verify_mcp.py
```

### 2. Lewat skill

Skill `jev` memberi agent konteks penuh tentang API TypeSafe. Lihat
[Pasang sebagai agent skill](#pasang-sebagai-agent-skill) di atas untuk cara
memasangnya di Claude Code, Codex, Cursor, Copilot CLI, dan lainnya.

### 3. Lewat kode Python

```python
from jev.client import JevClient
from jev.router import ChiefRouter, build_state

with JevClient() as client:
    result = ChiefRouter(client).decide(
        build_state(goal, completed_work, sources=sources, draft=draft)
    )

result.next_worker.value        # "research"
result.next_worker.certainty    # 0.83
result.next_worker.action       # "act" | "caution" | "escalate"
```

---

## Struktur

```
copilot-jev/
├─ skills/jev/                # SKILL.md kanonik + reference/  <- sumber kebenaran
├─ .claude-plugin/            # manifest Claude Code marketplace
├─ .github/
│  ├─ skills/jev/             # salinan tersinkron untuk Copilot CLI
│  └─ workflows/ci.yml        # uji + cek sinkronisasi skill
├─ chief.py                   # task router mandiri -> queue/
├─ mcp_server.py              # decision layer untuk Copilot CLI
├─ src/jev/
│  ├─ questions.py            # SEMUA pertanyaan + ambang batas  <- review di sini
│  ├─ router.py               # gerbang confidence tiga jalur
│  ├─ client.py               # wrapper + retry + telemetry
│  ├─ budget.py               # limit aksi/biaya + completion check
│  ├─ telemetry.py            # catatan biaya & latency
│  └─ config.py               # env + harga
├─ demo/run_demo.py           # loop research -> write -> review
├─ scripts/
│  ├─ doctor.py               # periksa seluruh instalasi dalam satu perintah
│  ├─ verify_mcp.py           # uji server MCP via stdio
│  ├─ sync_skill.py           # jaga SKILL.md tetap sinkron antar agent
│  └─ measure.py              # bandingkan fan-out vs panggilan terpisah
├─ tests/                     # 62 uji offline + 8 uji live
└─ docs/                      # dokumentasi 01-08
```

**Titik penyetelan utama ada di `src/jev/questions.py`.** Semua teks pertanyaan
dan konstanta ambang sengaja dikumpulkan di sana, karena itulah bagian yang
paling perlu direview manusia.

---

## Prinsip yang dipegang kode ini

1. **Kirim bukti, bukan ringkasan.** `"researcher finished"` tidak bisa dinilai.
2. **Satu panggilan, banyak pertanyaan.** `state` hanya dibayar sekali.
3. **Refresh opsi secara dinamis.** Opsi mati menurunkan confidence percuma.
4. **Opsi tinggal satu? Jangan panggil Jev.** Itu keputusan deterministik.
5. **Ambang mengikuti risiko**, bukan satu angka untuk semua.
6. **Noul tidak punya `confidence`** — turunkan dari `abs(noul - 0.5) * 2`.
7. **"DONE" bukan verifikasi.** Buktikan outcome-nya di kode.
8. **Ukur biaya dan latency**, jangan menebak.

Penjelasan lengkap: [06 — Praktik terbaik](docs/06-pola-praktik-terbaik.md).

---

## Uji

```powershell
python -m pytest              # 62 uji offline (tanpa API key)
python -m pytest -m live -v   # 8 uji terhadap API sungguhan
```

Uji live otomatis dilewati bila `TYPESAFE_API_KEY` belum diset.

---

## Keamanan

- API key **hanya** di `.env` (sudah di-gitignore) atau environment variable.
  Tidak pernah di kode, dokumentasi, maupun `mcp-config.json`.
- Jangan set `TYPESAFE_LOG_LEVEL=debug` pada data nyata: pada level itu SDK
  mencetak body request dan response **tanpa redaksi**.
- `state` yang Anda kirim tetap pergi ke API TypeSafe. Perlakukan seperti
  layanan pihak ketiga lainnya.

---

## Jev adalah partner Copilot CLI

Keduanya mengerjakan hal yang berbeda dan saling melengkapi: Copilot CLI
memahami maksud, menyusun rencana, dan menulis; Jev memilih, menilai, dan
memutuskan dengan angka. Pekerjaan bahasa tetap di LLM, keputusan berulang
pindah ke model yang memang dirancang untuk itu.

Konsekuensinya: tidak ada setelan `model: "jev-latest"` yang membuat Copilot
CLI berjalan di atas Jev — dan itu memang bukan tujuannya. Pasangkan keduanya,
jangan tukar salah satunya.

---

## Sumber

- [Dokumentasi resmi TypeSafe AI](https://docs.typesafe.ai)
- [API reference](https://docs.typesafe.ai/api) · [Playground](https://console.typesafe.ai/playground) · [API keys](https://console.typesafe.ai/keys)
- Thread [@0xCodila](https://x.com/0xCodila/status/2100984487802708306) — pengantar konsep
  (beberapa detail teknisnya dikoreksi di [docs/03](docs/03-setup.md#koreksi-penting-terhadap-thread-sumber))