minicode-ai 0.23.0 → 0.25.0

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 (75) hide show
  1. package/README.md +2 -2
  2. package/cli/tui.ts +28 -2
  3. package/docs/README.md +2 -2
  4. package/docs/SUMMARY.md +10 -19
  5. package/docs/TERMINAL_CONTRACT.md +82 -28
  6. package/docs/architecture.md +1 -1
  7. package/docs/autonomous-scheduler.md +283 -2
  8. package/docs/choosing-mode.md +4 -4
  9. package/docs/concepts.md +39 -3
  10. package/docs/config.md +90 -4
  11. package/docs/environment.md +3 -0
  12. package/docs/getting-started.md +58 -2
  13. package/docs/repl.md +1 -1
  14. package/docs/security.md +49 -2
  15. package/docs/tools.md +2 -1
  16. package/package.json +2 -36
  17. package/src/app/provider-layer.ts +1 -1
  18. package/src/config.ts +2 -0
  19. package/src/constants.ts +3 -0
  20. package/src/lib/safe-open.ts +21 -12
  21. package/src/memory/vector.ts +0 -31
  22. package/src/policy/context-window.ts +0 -33
  23. package/src/policy/no-progress.ts +1 -1
  24. package/src/policy/permission.ts +5 -0
  25. package/src/policy/scrub.ts +15 -2
  26. package/src/policy/tool-contract.ts +11 -9
  27. package/src/presentation/reducer.ts +1 -0
  28. package/src/providers/anthropic.ts +3 -3
  29. package/src/providers/detect.ts +27 -0
  30. package/src/providers/provision.ts +15 -1
  31. package/src/task/autonomous-policy.ts +7 -0
  32. package/src/task/graph-validate.ts +1 -1
  33. package/src/task/session-authority.ts +0 -5
  34. package/src/task/store.ts +0 -4
  35. package/src/tools/ask_user.ts +14 -1
  36. package/src/tools/bash.ts +57 -9
  37. package/src/tools/context.ts +10 -0
  38. package/src/tools/delete_file.ts +3 -2
  39. package/src/tools/edit.ts +5 -4
  40. package/src/tools/git.ts +70 -12
  41. package/src/tools/glob.ts +13 -5
  42. package/src/tools/grep.ts +26 -10
  43. package/src/tools/index.ts +3 -2
  44. package/src/tools/lsp.ts +15 -9
  45. package/src/tools/move_file.ts +4 -3
  46. package/src/tools/patch.ts +5 -4
  47. package/src/tools/read_file.ts +3 -2
  48. package/src/tools/read_image.ts +3 -2
  49. package/src/tools/task.ts +1 -0
  50. package/src/tools/todo.ts +4 -8
  51. package/src/tools/write_file.ts +4 -3
  52. package/src/ui/approval/prompt.ts +226 -77
  53. package/src/ui/footer.ts +41 -29
  54. package/src/ui/i18n/en.ts +4 -0
  55. package/src/ui/i18n/id.ts +4 -0
  56. package/src/ui/render/activity-group.ts +1 -0
  57. package/src/ui/render/ledger.ts +1 -9
  58. package/src/ui/render/logo.ts +0 -5
  59. package/src/ui/render/markdown-table.ts +0 -3
  60. package/src/ui/render/table-grid.ts +0 -3
  61. package/src/ui/render/theme.ts +31 -5
  62. package/src/ui/runtime/screen.ts +7 -1
  63. package/src/ui/screens/dialog.ts +45 -81
  64. package/src/ui/screens/form.ts +10 -10
  65. package/src/ui/screens/model-manager.ts +7 -10
  66. package/src/ui/screens/picker.ts +8 -11
  67. package/src/ui/screens/provider-manager.ts +9 -13
  68. package/src/ui/tui/app.ts +92 -9
  69. package/src/ui/tui/transcript.ts +4 -0
  70. package/docs/P14_OPEN_WORK.md +0 -290
  71. package/docs/config-providers.md +0 -87
  72. package/docs/glossary.md +0 -39
  73. package/docs/quickstart.md +0 -60
  74. package/docs/security-model.md +0 -96
  75. package/docs/terminal.md +0 -91
@@ -1,87 +0,0 @@
1
- # Config & Provider
2
-
3
- ## 15 preset gateway (termasuk Custom URL)
4
-
5
- `Gateway >` hanya menampilkan `[0] Label` tanpa URL (minimalis, tanpa bocor endpoint).
6
-
7
- | id | Label | Catatan |
8
- |---|---|---|
9
- | `openai` | OpenAI | gpt, o-series |
10
- | `anthropic` | Anthropic | Claude, streaming `tool_use` |
11
- | `openrouter` | OpenRouter | Gateway 75+ model |
12
- | `deepseek` | DeepSeek | chat/reasoner |
13
- | `opencode-zen` | OpenCode Zen | Gateway |
14
- | `google` | Google Gemini | Konteks 1M, `thought_signature` pass-through |
15
- | `ollama` | Ollama | Lokal, gratis, tanpa key |
16
- | `qwen` | Qwen | Alibaba Qwen3-Coder (satu-satunya dengan spec OAuth terdaftar) |
17
- | `groq` | Groq | Inferensi cepat |
18
- | `together` | Together AI | Model terbuka |
19
- | `fireworks` | Fireworks AI | — |
20
- | `mistral` | Mistral AI | — |
21
- | `cohere` | Cohere | — |
22
- | `generic` | OpenAI-compatible umum | vLLM / LM Studio |
23
- | `custom` | Custom URL | Pseudo-preset untuk baseUrl sendiri |
24
-
25
- Alur: wizard & `/provider` (add `[0] OpenAI` … `[14] Custom URL`) → API key ter-masking → auto-detect models via `GET /models` timeout 4 dtk → provider otomatis pindah saat pilih model beda provider (tanpa restart, via `reloadProviders()` setelah `Gateway >2`).
26
-
27
- ## Dua jalur autentikasi
28
-
29
- ```bash
30
- # 1. API key
31
- minicode config add --baseUrl https://api.openai.com/v1 --apiKey sk-…
32
-
33
- # 2. OAuth device-code (tanpa API key, tanpa kartu kredit) — RFC 8628
34
- minicode auth list # provider yang mendukung
35
- minicode auth login qwen # kode singkat → buka URL → tunggu persetujuan
36
- minicode auth status # kredensial + kapan kedaluwarsa
37
- minicode auth logout qwen
38
- ```
39
-
40
- Token di `~/.minicode/auth.json` (chmod 600), bukan `config.json`. Refresh otomatis margin 60 dtk. Provider OAuth yang belum login dibuang dari daftar dengan peringatan, bukan dikirim dengan header kosong.
41
-
42
- > Kejujuran: device flow teruji lengkap ke server OAuth lokal (pending/slow_down/denied/expired/clamp), tapi endpoint/clientId provider belum semua terkonfirmasi live. `auth login chatgpt` fail-fast di non-TTY. Jangan baca token aplikasi desktop orang lain — itu pencurian kredensial.
43
-
44
- ## Keyring OS (ganti plaintext config)
45
-
46
- ```bash
47
- minicode config set-key openrouter # pindah API key ke OS store, config tinggal referensi
48
- minicode config delete-key openrouter # lupakan (provider nonaktif sampai di-set ulang)
49
- ```
50
-
51
- Windows memakai DPAPI user-scope (hanya user ini yang bisa membuka); selain itu berkas chmod 600 dengan label jujur `plain-file` (bukan keyring). Referensi hilang/rusak = provider di-skip dengan peringatan (fail-closed, seperti OAuth). Matikan paksa via `MINICODE_KEYSTORE_DISABLE=1`.
52
-
53
- ## Model & thinking effort
54
-
55
- ```
56
- /model [cari] → picker provider::model, bisa difilter
57
- Enter → pilih model (+ picker effort bila modelnya mendukung)
58
- Esc → batal total
59
- ```
60
-
61
- Effort tersimpan di `ProviderEntry.reasoningEffort`, berlaku sesi berikutnya, tampil badge `[low|medium|high]`. **Default universal = omit** (tanpa param thinking): default bawaan tiap model sudah di-tune vendornya. Knob hanya dikirim ke keluarga terbukti, dalam bahasa native-nya: OpenAI reasoning (`o1`/`o3`/`o4`, `gpt-5`/`gpt-6` → `reasoning_effort`, level tervalidasi per model — pro = high saja); Claude ≤4.5 → budget `1024/2048/4096`; Claude ≥4.6/5 → adaptive + `output_config.effort`. **Selain itu tak pernah dikirimi param thinking** (DeepSeek, Gemini, Groq, Ollama, free-tier, custom). Bila model menolak param (400/500), request diulang sekali tanpa param + diingat per sesi + dicatat `[thinking]` di stderr. Picker effort hanya muncul untuk model yang mendukung; sisanya select langsung tanpa menyentuh effort tersimpan. `detectAndSave`/`auth login` mempertahankan effort (tidak reset diam-diam). Mutasi ditulis ke file scope asal (bukan hasil merge) agar tidak duplikat/shadowing.
62
-
63
- Model override sekali jalan:
64
-
65
- ```bash
66
- minicode --model providerId::modelName "prompt"
67
- minicode --provider openai "prompt"
68
- minicode models --match gemini
69
- ```
70
-
71
- `MINICODE_PROVIDER_ORDER=openai,anthropic,deepseek` mengurutkan provider agnostik tanpa edit config.
72
-
73
- ## Pin eksplisit `provider::model` (kontrak)
74
-
75
- Model berformat `providerId::modelName` = PIN: request hanya ke provider
76
- itu — **tanpa fallback lintas provider dan tanpa substitusi diam-diam**.
77
- Gagal = error jujur dari provider yang dipilih (limit/saldo/error server),
78
- user memilih model lanjutannya sendiri via `/model`. Alasan: fallback
79
- otomatis pernah melempar user dari model gratis ke model berbayar provider
80
- lain (tagihan tak terduga). Model bare (tanpa `::`) tetap perilaku lama
81
- (first-match + substitusi + fallback rate_limit/server/network).
82
-
83
- ## Build & router
84
-
85
- Build provider terpusat di `src/providers/build.ts`. Router fallback untuk rate_limit/server/network (clone-error + base64 fix + retryAfter cap). Deteksi wire dari probe path `/responses` → hint `responses`; substring host hanya fallback. `max_tokens` 8192; stop `length` = peringatan eksplisit, bukan teks sunyi.
86
-
87
- Responses API: `/v1/responses`, `previous_response_id` chaining per model, `store:false` default.
package/docs/glossary.md DELETED
@@ -1,39 +0,0 @@
1
- # Glosarium
2
-
3
- Istilah Minicode yang punya makna spesifik. Dokumentasi berbahasa Indonesia dengan istilah teknis English — halaman ini mengunci maknanya.
4
-
5
- | Istilah | Makna |
6
- |---|---|
7
- | **MiniCore** | Kernel runtime `STATE / MODEL / ACTION / LOOP` di-vendor ke `vendor/minicore`; inti beku, zero-dep, di-resolve via `#minicore` |
8
- | **Minicode** | Layer agencode di atas MiniCore: tools, agents, policy, providers, memory, sessions, CLI |
9
- | **Tool** | Kemampuan yang dipilih model dalam loop ReAct; tool MCP dapat ditambahkan dinamis sebagai `serverId.toolName` |
10
- | **Tool scope** | `full` atau subset read-only `explore` — flag `--tool-scope` |
11
- | **WorkMode** | Cara agent bekerja: `DISCUSS`, `PLAN`, atau `BUILD` (alias produk untuk identitas internal `EXECUTE`) |
12
- | **PermissionMode** | Pilihan pengawasan: `AUTO` menjalankan capability yang diotorisasi; `ASK` meminta persetujuan untuk aksi yang digate |
13
- | **Tool Access Policy** | Batas capability yang tersedia, seperti read-only, allowlist, atau profil akses warisan `--allow-all` |
14
- | **Gate** | Tool wajib persetujuan manusia saat TTY; non-TTY selalu tolak (mis. `git_commit`, MCP, `delegate_task`) |
15
- | **Path jail** | Pembatasan akses file ke workspace (realpath + symlink; `O_NOFOLLOW` pada POSIX dan pencocokan identitas handle `dev+ino` pada semua platform); aktif bahkan `--allow-all` |
16
- | **Bash-guard** | Normalisasi + blokir pola bash berbahaya sebelum eksekusi (quote-split, indirection, wrapper) |
17
- | **Sandbox OS** | bubblewrap (Linux) / seatbelt (macOS) — otomatis bila tersedia |
18
- | **Sandbox Docker** | Container ephemeral `--network none`, 512m, 1 CPU, `node:22-alpine` |
19
- | **Checkpoint** | Snapshot per turn via shadow-git: SHA tree di `refs/minicode/…` (O(delta), HEAD/index tak tersentuh) |
20
- | **Recovery journal** | `journal-<sesi>.jsonl`: `pending` → `committed`/`failed`/`unknown`; finalisasi menandai cakupan turn yang sudah durable |
21
- | **Session** | Riwayat tersimpan di `.minicode/sessions.db` (SQLite WAL); kompaksi dapat mengganti bagian lama dengan ringkasan + tail |
22
- | **Memory dua lapis** | `MEMORY.md` hierarki (selalu ke system prompt) + vector RAG hybrid (injeksi bila skor ≥ ambang) |
23
- | **RAG hybrid** | Pencarian memory cosine 0.7 + keyword 0.3, ranking MMR (λ 0.7), dedup >0.92 |
24
- | **Repo-map** | Simbol per file (regex 9 bahasa, fallback LSP) disuntik ke system prompt |
25
- | **Skill** | Prompt terpaket `.minicode/skills/*.md` dengan frontmatter `name`/`description` |
26
- | **Hook** | Skrip `pre/post-run` dari `~/.minicode/hooks` + `.minicode/hooks`; mati default, `MINICODE_HOOKS=1` |
27
- | **Env scrub** | `sanitizeSpawnEnv` menghapus kata-kunci kredensial dari env subprocess |
28
- | **Secret scrubber** | Redaksi `sk-`/`ghp_`/`AKIA`/PEM/JWT/Bearer sebelum teks ke LLM |
29
- | **Ledger** | Baris ` › name target` / ` › name: …` di stderr — jejak aksi agent |
30
- | **Scrollback** | Riwayat layar terminal; jalur non-interaktif minicode append-only di sana (interaktif pakai alternate screen) |
31
- | **Transient** | UI muncul-sekali yang menghapus dirinya (spinner, garis status turn) — vs transkrip yang menetap |
32
- | **Composition root** | `cli/index.ts` + `cli/setup.ts`: satu tempat wiring DI (provider, RAG, session, tools) |
33
- | **Seam aditif** | Satu-satunya patch yang dibolehkan ke kernel beku: `compactAsync`, `initialMessages`, `cwd` |
34
- | **Self-contained** | Tanpa clone repo lain — kernel di-vendor, runtime zero-dep, butuh Bun ≥ 1.1.13 |
35
-
36
- ## Lanjut
37
-
38
- - [Konsep & Desain](concepts.md) — narasi di balik istilah.
39
- - [Arsitektur](architecture.md) — bagaimana lapisan-lapisan itu tersusun.
@@ -1,60 +0,0 @@
1
- # Quickstart 5 menit
2
-
3
- Tujuan: dari nol sampai prompt pertama yang ter-verify, tanpa membaca seluruh manual.
4
-
5
- ## 1. Jalan pertama (1 menit)
6
-
7
- ```bash
8
- minicode
9
- ```
10
-
11
- Bila belum ada provider, wizard setup muncul. Isi berurutan: pilih gateway → tempel API key (ter-masking) → auto-detect models. Wizard memakai picker (panah + filter), bukan `readline` nomor — mengetik di luar rentang tidak lagi diam-diam memilih `[0]`.
12
-
13
- Alternatif tanpa API key:
14
-
15
- ```bash
16
- minicode auth login # device-code: kode singkat + URL, setujui di browser
17
- minicode auth status # lihat kredensial + kapan kedaluwarsa
18
- ```
19
-
20
- ## 2. Prompt pertama (2 menit)
21
-
22
- ```bash
23
- minicode --work-mode BUILD "buat http server hello world di server.ts" --verbose
24
- ```
25
-
26
- Yang terjadi: model menerima system prompt berisi `# Environment` (cwd + platform) + repo-map ringkas, lalu loop ReAct `Thought → Action → Observation` sampai jawaban final atau batas (`--max-steps` default 50, `--timeout` default 1 jam).
27
-
28
- Coba mode interaktif:
29
-
30
- ```bash
31
- minicode --interactive
32
- # minicode › jelaskan isi src/tools/index.ts
33
- # /model → picker provider::model, Enter = pilih + atur effort
34
- # /status → token + biaya kumulatif sesi
35
- # /exit → keluar (Esc ganda saat abort juga bisa)
36
- ```
37
-
38
- ## 3. Verify otomatis (2 menit)
39
-
40
- ```bash
41
- minicode --work-mode BUILD --verify "fix bugs lalu typecheck"
42
- ```
43
-
44
- Sebelum agen jalan, baseline diuji dulu. Bila baseline sudah merah, catatan Health-Check ditempel ke prompt awal agar agen memperbaiki dulu. Setelah run, verify dijalankan; bila gagal, agen self-heal maks 3 siklus. Output error dibungkus fence agar tidak jadi prompt injection. Custom command via `MINICODE_VERIFY_CMD` atau `verifyCommand` di config.
45
-
46
- ## Contoh pola harian
47
-
48
- ```bash
49
- minicode --ask "deploy script" # human-in-loop confirmation card
50
- minicode --sandbox docker "task" # bash di container ephemeral
51
- minicode --budget 0.50 "task besar" # warn 80%; pagu lewat → prompt baru ditolak + turn berjalan digugurkan
52
- minicode exec "prompt" --json # headless CI: JSONL stream + summary
53
- minicode "/review src/a.ts" # skill slash-command
54
- ```
55
-
56
- ## Berikutnya
57
-
58
- - [CLI](cli.md) untuk semua mode + flags.
59
- - [TUI](repl.md) untuk slash command dan keyboard.
60
- - [Config & Provider](config-providers.md) untuk pindah gateway dan model.
@@ -1,96 +0,0 @@
1
- # Security Model
2
-
3
- Model ancaman Minicode dalam satu halaman: apa yang dikontrol, apa yang dipercaya, dan apa batasnya. Tanpa kata "aman" absolut — setiap klaim di bawah menunjuk ke mekanisme yang bisa Anda baca dan uji.
4
-
5
- ## Prinsip
6
-
7
- Minicode mengontrol **kemampuan bertingkat** (layered capability control), bukan niat model. Model boleh salah paham; yang menentukan apa yang benar-benar terjadi adalah gerbang deterministik di bawahnya: izin → jail → guard → validasi → eksekusi → bukti.
8
-
9
- ## Execution Chain
10
-
11
- Setiap pemanggilan tool melewati rantai ini, berurutan:
12
-
13
- ```
14
- Permission → Jail → Bash Guard → Argument Validation → Executor → Journal / Recovery
15
- ```
16
-
17
- | Tahap | Fungsi |
18
- |---|---|
19
- | **Permission** | Mode izin (`src/policy/permission.ts`) memutuskan allow/deny/ask per pasangan tool+args. Berlaku SEBELUM efek apa pun. |
20
- | **Jail** | Path di luar workspace, symlink keluar, file sensitif (`.env`, `.git/config`), dan state milik minicode (`.minicode/*.db`, todos, jurnal, config) ditolak — **bahkan di `--allow-all`** (kecuali mode `unrestricted`, lihat §Mode dan akses di bawah). |
21
- | **Bash Guard** | Perintah shell dinormalisasi dulu (buang quote/wrapper/variabel sederhana), baru diperiksa polanya. Menolak env-dump, exfiltrasi upload, interpreter inline, destruksi luas. |
22
- | **Argument Validation** | Skema argumen divalidasi kernel sebelum eksekusi; argumen invalid ditolak tanpa efek. |
23
- | **Executor** | Menjalankan yang lolos: read paralel, write dibatasi konkurensinya, abort-aware, output dipotong dengan penanda (tak pernah diam-diam). |
24
- | **Journal / Recovery** | Tiap mutasi dicatat sebagai `pending` lalu `committed`/`failed`/`unknown`; finalisasi menandai cakupan turn durable. Resume tak pernah mengulang buta (lihat [Recovery](#recovery)). |
25
-
26
- ## Mode dan akses
27
-
28
- Pilihan yang terlihat oleh operator dipisah menjadi tiga sumbu:
29
-
30
- | Sumbu | Nilai | Dampak |
31
- |---|---|---|
32
- | **WorkMode** | `DISCUSS`, `PLAN`, `BUILD` (`EXECUTE` internal) | Membatasi ruang kerja agent. `DISCUSS` read-only; `PLAN` dapat menulis artefak rencana; `BUILD` tidak menambahkan ceiling. WorkMode hanya mempersempit akses. |
33
- | **PermissionMode** | `AUTO`, `ASK` | `AUTO` menjalankan capability yang sudah diotorisasi tanpa persetujuan rutin; `ASK` meminta persetujuan untuk pemanggilan yang digate. `ask_user` ditolak di `AUTO`. |
34
- | **Tool Access Policy** | kebijakan capability dan profil akses warisan | Menentukan tools yang tersedia. `readonly`, `plan`, `allowlist`, dan `allow-all` tetap menjadi identitas internal/kompatibilitas untuk batas akses, bukan mode persetujuan tambahan. |
35
-
36
- **Profil `allow-all` tetap terbatas.** Path jail, penolakan state milik runtime, bash-guard, dan validasi argumen tetap berlaku; profil ini tidak memberi akses host tanpa batas. Detail implementasi dan opsi CLI ada di [Policy & Sandbox](policy-sandbox.md).
37
-
38
- **Pengecualian eksplisit: `unrestricted`.** Satu-satunya mode yang melepas seluruh lapisan di atas — tanpa path jail, tanpa bash-guard, tanpa sandbox/allowlist. Diaktifkan eksplisit oleh operator lewat perintah TUI tersembunyi `/unrestric` (bukan flag CLI, sengaja tak muncul di `/help` maupun daftar `/`), berlaku **per-sesi saja** dan tak pernah persist. Gerbang keamanannya adalah kepercayaan operator kepada model — blast radius penuh (file apa pun di host, shell apa pun). Default tetap `DISCUSS`+`AUTO` dengan hard-deny aktif.
39
-
40
- ## Trust Boundaries
41
-
42
- | Sumber | Status | Artinya |
43
- |---|---|---|
44
- | Prompt Anda | Niat tepercaya | Tujuan dijalankan, TETAPI setiap efek tetap lewat rantai di atas |
45
- | Output model | Tak dipercaya untuk klaim | Teks/keputusan model bisa salah; bukti (hasil tool, test, HEAD) yang menentukan |
46
- | Hasil tool | Data | Dibaca model sebagai fakta observasi, bukan instruksi baru |
47
- | Data repository (kode, AGENTS.md, MEMORY, skill) | Data | Bisa berisi instruksi injeksi; system prompt menandainya tak-terpercaya |
48
- | Server MCP | External capability | Efek di sisi server arbitrer dan tak terlihat; persetujuan mengikuti mode dan authorization; pembatalan tak membatalkan efek yang sudah terjadi |
49
- | Provider / network | External | Prompt dan hasil melewati provider yang Anda pilih; tak ada telemetri/analitik dari Minicode sendiri |
50
- | Child agent | Terisolasi | Memori, sinyal, budget, dan jurnal sendiri; tool scope mengikuti kebijakan delegasi dan WorkMode parent (lihat [Sub-Agents & Tasks](agents.md)) |
51
- | Local config (`.minicode/config.json`) | Tak dipercaya default | Diabaikan kecuali `--allow-local-config`; repo clone-an tak bisa men-spawn server |
52
- | Skills / memory tersimpan | Data | Dibaca sebagai konteks, bukan kebijakan |
53
-
54
- ## Dangerous Capabilities
55
-
56
- Minicode **tidak menyediakan tool** untuk (terverifikasi di `src/tools/`):
57
-
58
- - `git push`, `fetch`, `pull`, `clone` — tak ada tool git jaringan sama sekali
59
- - `git reset`, `amend`, `rebase`, `checkout`, `branch -D`, `stash drop`
60
- - Eksekusi remote / deploy bawaan
61
-
62
- Catatan jujur: operasi itu tetap BISA diketik lewat `bash` (tunduk pada bash-guard + jail, BUKAN larangan). `git` via bash menjalankan konfigurasi repo apa adanya (hook/filter/driver milik repo). Tool baca `git_*` dinetralkan; `git_commit` menolak sebelum staging bila filter Git terkonfigurasi. Di repo tak-terpercaya, utamakan tool baca dan tinjau konfigurasi sebelum memakai Git manual.
63
-
64
- ## Recovery
65
-
66
- Setiap mutasi meninggalkan bukti, bukan janji (disebut *mutation journal* di kode: `src/session/journal.ts`):
67
-
68
- ```
69
- intent pending → committed/failed/unknown → finalisasi cakupan turn durable
70
- ```
71
-
72
- - `committed` yang turn-nya hilang → **tidak diulang**; model diberi catatan narasi.
73
- - `pending`/`failed`/`unknown` → direktif verifikasi; **dilarang redo buta**.
74
- - Klaim sukses pihak ketiga (MCP) diperlakukan sebagai "kata server", wajib baca-balik bila penting.
75
-
76
- Kejujuran yang disengaja: crash ambiguity TETAP MUNGKIN (filesystem dan database tak bisa commit atomik bersama). Yang dijamin adalah: ambiguitas selalu diperlakukan sebagai ambigu — diverifikasi dulu, tidak diasumsikan sukses maupun gagal.
77
-
78
- ## Limitations
79
-
80
- - **Repo hooks/filter/driver:** `git` via bash mengeksekusinya (semantik stock-git); tool baca `git_*` menetralkan filter, sedangkan `git_commit` menolak bila menemukan filter terkonfigurasi.
81
- - **Bash arbitrer:** guard adalah analisis statis; substitusi dinamis (`$(curl …)`) butuh sandbox OS/docker untuk isolasi nyata.
82
- - **Efek eksternal MCP:** setelah terjadi, tak bisa dibatalkan dari sini.
83
- - **Provider/network:** data melewati provider pilihan Anda; Minicode tak menambahkan transmisi sendiri.
84
- - **Perilaku model:** pemilihan tool, klaim sukses, dan kepatuhan intent adalah sifat model — orkestrasi menjamin bukti dan batas, bukan kebijaksanaan.
85
- - **Server LSP:** di-spawn dari perintah di config Anda; hanya daftarkan server yang Anda percaya.
86
- - **Repo tak-terpercaya:** perlakukan seperti menjalankan `git`/`bash` manual di sana — karena memang itu yang terjadi di balik tool.
87
-
88
- ## Security Contact
89
-
90
- Belum ada kontak keamanan privat. Laporkan masalah via [GitHub Issues](https://github.com/minilabs-id/minicode/issues) **tanpa menyertakan kredensial, token, atau data sensitif** — cukup langkah reproduksi minimal + output `minicode doctor`.
91
-
92
- ## Lanjut
93
-
94
- - [Policy & Sandbox](policy-sandbox.md) — detail tiap mode + guard.
95
- - [Keamanan](security.md) — threat model + bukti pengukuran.
96
- - [Memory & Sessions](memory-sessions.md) — jurnal, checkpoint, undo.
package/docs/terminal.md DELETED
@@ -1,91 +0,0 @@
1
- # Kontrak Terminal
2
-
3
-
4
- Kontrak ini **FROZEN**: setiap perubahan perilaku terminal wajib update dokumen
5
- ini + test peta proteksinya. Versi lengkap (kontrak internal kontributor, peta
6
- proteksi per invariant, residual risk yang disengaja) ada di
7
- [Terminal Contract](TERMINAL_CONTRACT.md).
8
-
9
- ## Satu tampilan interaktif: TUI fullscreen
10
-
11
- Sesi interaktif (`minicode` di TTY mampu) SELALU membuka TUI **alternate
12
- screen**: transkrip ala shell + status bar satu baris + popup komposit di atas
13
- transkrip yang tetap terlihat (redup). REPL linier, footer lengket (chrome
14
- scroll-region), overlay inline, dan jendela info **DIHAPUS** — tak ada mode,
15
- tak ada flag legacy (`--tui` usang = no-op). Keluar = buffer utama kembali
16
- persis; transkrip sesi tidak di-dump ke scrollback.
17
-
18
- Jalur **non-interaktif** (one-shot prompt, `exec`, pipe/redirect/CI,
19
- `TERM=dumb`, layar < 10 baris) tetap shell-first: cetak polos, append-only ke
20
- scrollback, tanpa alternate screen. Justru jalur inilah yang membuat hasil agen
21
- bisa di-pipe, di-grep, dan tinggal di scrollback Anda sendiri.
22
-
23
- ## Dua stream, dua isi
24
-
25
- | Stream | Isi |
26
- |---|---|
27
- | stdout | Output program: teks model (wrapped, fence 2-spasi; pipe-table menjadi grid selaras di TTY), receipt perubahan (`› write_file …`), artefak perintah. Bersih dari cursor-control saat non-TTY |
28
- | stderr | Progress/diagnostik: ledger tool (`› …` hijau/merah), reasoning (verbose), warning, error. Boleh transient bila TTY — ditahan saat layar interaktif memegang terminal |
29
-
30
- - Warna hanya bila TTY (`stdout.isTTY`); `NO_COLOR` menang; `TERM`/`COLORTERM` tidak menyalakan warna di pipe.
31
- - Error `pesan actionable` (berwarna merah, tanpa ikon sejak v0.17.0) sekali per kegagalan (`takePendingError`) — bukan spam di setiap langkah.
32
-
33
- ## Primitif tampilan
34
-
35
- 1. Transkrip fullscreen — prompt `minicode ›` saat editing + jawaban model + ledger, viewport ikut ekor otomatis; drag mouse membuat selection app-level, `Ctrl+C` menyalin, wheel dan `PgUp/PgDn` menggulir layar
36
- 2. Status bar satu baris — `✦ 00.00.00 mode model cwd` (timer `HH.MM.SS` di sebelah sparkle; redup idle, detik putih saat aktif, menit mulai terang di 60 dtk, jam di 1 jam; tanpa bullet separator; konteks rata kanan)
37
- 3. Popup komposit satu kotak — `/model`, `/provider`, `/sessions`, form, approval; Esc dua-tahap, kursor diparkir
38
- 4. Ledger — ` › name target` hijau / ` › name: …` merah
39
- 5. Teks model & thinking — mengalir redup (thinking), di-buffer untuk `/expand`
40
- 6. Error actionable — sekali per kegagalan
41
-
42
- ## Arbitrasi transient + hold layar interaktif
43
-
44
- Satu-satunya arbitrator transient: `src/ui/runtime/statusline.ts`
45
- (`acquireTransientPaint` + `paintWrite`). Painter aktif (garis status turn vs
46
- spinner wizard) mutually exclusive; overlap = signal `[transient-paint]`, bukan
47
- crash. Foreign stderr writer (non-UI) boleh mentah — arbitrator mengkomitnya
48
- sebagai baris permanen bersih.
49
-
50
- `beginInteractiveScreen()` menahan SEMUA painter transient selama layar
51
- interaktif memegang terminal (nol byte + baris painter dibersihkan sekali;
52
- nested + release idempoten). Pemegangnya: `askLine`/`askSecret`/`runPicker`
53
- (raw-mode) dan setiap handle `openAltScreen` (dilepas di `close()`). Tanpa ini
54
- tick `\r\x1b[2K` spinner menghapus baris prompt wizard (laporan "macet di
55
- Menyiapkan sesi…").
56
-
57
- Karena `screen.paint` kini mendiff secara inkremental, tulis ASING ke stderr
58
- selama alt-screen hidup (mis. `[hooks] skipped …`, warning provider) juga
59
- menandai terminal "kotor" — `statusline.consumeScreenDrift()` yang dikonsumsi
60
- layar untuk memaksa repaint penuh sekali pada paint berikutnya. `beginInteractiveScreen`
61
- memasang wrapper stderr pada depth 0→1 supaya sinyal ini aktif bahkan tanpa
62
- owner transient. Tanpa ini fragmen asing tetap menempel di baris yang kebetulan
63
- tak berubah.
64
-
65
- ## Invariant I1–I35
66
-
67
- Peta lengkap 35 invariant + test proteksinya (mis. `tui-app`, `screen-buffer`,
68
- `tui-popup`, `transient-arbitration`, `input-resize`, `exit-codes`, `acp`) ada di
69
- [Terminal Contract](TERMINAL_CONTRACT.md). Setiap fitur terminal baru tunduk
70
- pada invariant itu — mis. tak boleh menulis cursor-control ke stdout non-TTY,
71
- tak boleh mengandalkan alternate screen di jalur non-interaktif.
72
-
73
- Kontrak versi **v7.12** (2026-11-10) juga mencantumkan **peta gap proteksi**:
74
- klaim yang implementasinya benar tetapi belum punya assertion penjaga. Baca
75
- saga itu sebelum menyatakan "sudah dijaga".
76
-
77
- ## Aksesibilitas & konsol lawas
78
-
79
- `MINICODE_ASCII=1` (glyph `[OK]`/`>`/`.`), `MINICODE_A11Y=1` (live-region approval polos tanpa ANSI), `MINICODE_BELL=0`, `MINICODE_DROPDOWN=0` (hint inline), `MINICODE_MOTION=0` (spark statis, tanpa pulse). Daftar lengkap di [Environment Variables](environment.md).
80
-
81
- ### Sinyal fatal & pemulihan terminal
82
-
83
- Sesi TUI memasang handler SIGTERM/SIGHUP sendiri selama hidup (dilepas saat
84
- quit): sinyal = raw mode dimatikan + alt-screen ditutup + exit `128+n`
85
- (SIGTERM=143, SIGHUP=129) — terminal tidak tertinggal di buffer alt. `kill -9`
86
- tetap di luar jangkauan (ketik `reset`; residual kontrak #2).
87
-
88
- ## Lanjut
89
-
90
- - [Konsep & Desain](concepts.md) — kenapa interaktif pakai alt-screen, non-interaktif shell-first.
91
- - [TUI — Slash & Keyboard](repl.md) — interaksi harian di atas kontrak ini.