minicode-ai 0.10.0 → 0.11.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 (128) hide show
  1. package/AGENTS.md +45 -0
  2. package/CHANGELOG.md +59 -4
  3. package/PLAN.md +491 -0
  4. package/README.md +2 -2
  5. package/cli/commands/acp.ts +485 -0
  6. package/cli/commands/auth.ts +7 -4
  7. package/cli/commands/config.ts +41 -27
  8. package/cli/commands/exec.ts +33 -12
  9. package/cli/commands/mcp.ts +3 -2
  10. package/cli/commands/memory.ts +1 -1
  11. package/cli/commands/pricing.ts +6 -4
  12. package/cli/commands/providers.ts +18 -8
  13. package/cli/commands/sessions.ts +11 -4
  14. package/cli/commands/skills.ts +3 -3
  15. package/cli/commands/stats.ts +3 -1
  16. package/cli/commands.ts +6 -0
  17. package/cli/index.ts +82 -57
  18. package/cli/model-manager.ts +6 -1
  19. package/cli/router.ts +7 -0
  20. package/cli/setup.ts +341 -5
  21. package/cli/tui.ts +54 -18
  22. package/docs/ARCHITECTURE.html +29 -22
  23. package/docs/CONTROL-PLANE-MAP.md +139 -0
  24. package/docs/HARNESS.md +150 -0
  25. package/docs/PLAN_UIUX_V6.md +209 -0
  26. package/docs/README.md +1 -1
  27. package/docs/SUMMARY.md +52 -0
  28. package/docs/TERMINAL_CONTRACT.md +367 -0
  29. package/docs/UI_RENDER_PIPELINE.md +165 -0
  30. package/docs/USAGE.md +11 -0
  31. package/docs/agents.md +31 -0
  32. package/docs/architecture.md +3 -3
  33. package/docs/choosing-mode.md +34 -0
  34. package/docs/cli.md +130 -0
  35. package/docs/concepts.md +53 -0
  36. package/docs/config-providers.md +87 -0
  37. package/docs/config.md +63 -0
  38. package/docs/contributing.md +79 -0
  39. package/docs/environment.md +95 -0
  40. package/docs/exec.md +73 -0
  41. package/docs/getting-started.md +102 -0
  42. package/docs/glossary.md +37 -0
  43. package/docs/mcp-lsp.md +54 -0
  44. package/docs/memory-sessions.md +63 -0
  45. package/docs/policy-sandbox.md +72 -0
  46. package/docs/pricing-budget.md +49 -0
  47. package/docs/quickstart.md +60 -0
  48. package/docs/repl.md +67 -0
  49. package/docs/security-model.md +95 -0
  50. package/docs/security.md +91 -0
  51. package/docs/skills.md +48 -0
  52. package/docs/terminal.md +79 -0
  53. package/docs/tools.md +123 -0
  54. package/docs/troubleshooting.md +40 -0
  55. package/docs/verify-benchmark.md +58 -0
  56. package/package.json +8 -5
  57. package/src/app/provider-layer.ts +12 -4
  58. package/src/app/session.ts +6 -0
  59. package/src/app/tool-layer.ts +2 -1
  60. package/src/constants.ts +35 -0
  61. package/src/lib/net.ts +6 -1
  62. package/src/lsp/client.ts +41 -8
  63. package/src/mcp/http-transport.ts +52 -15
  64. package/src/mcp/transport.ts +32 -1
  65. package/src/memory/files.ts +6 -5
  66. package/src/policy/allowlist.ts +1 -1
  67. package/src/policy/bash-guard.ts +154 -14
  68. package/src/policy/compaction.ts +57 -3
  69. package/src/policy/context.ts +4 -0
  70. package/src/policy/jail.ts +49 -4
  71. package/src/policy/permission.ts +152 -12
  72. package/src/policy/pricing.ts +12 -9
  73. package/src/presentation/adapter.ts +721 -0
  74. package/src/presentation/events.ts +324 -0
  75. package/src/presentation/label.ts +140 -0
  76. package/src/presentation/model.ts +172 -0
  77. package/src/presentation/reducer.ts +486 -0
  78. package/src/presentation/store.ts +256 -0
  79. package/src/providers/anthropic.ts +22 -4
  80. package/src/providers/detect.ts +2 -1
  81. package/src/providers/router.ts +13 -0
  82. package/src/repo/repomap.ts +2 -29
  83. package/src/session/checkpoint.ts +27 -9
  84. package/src/session/journal.ts +27 -5
  85. package/src/skills/loader.ts +88 -5
  86. package/src/telemetry/trace.ts +36 -15
  87. package/src/tools/ask_user.ts +73 -4
  88. package/src/tools/bash.ts +15 -17
  89. package/src/tools/glob.ts +10 -11
  90. package/src/tools/lsp.ts +3 -56
  91. package/src/tools/memory.ts +13 -12
  92. package/src/tools/task.ts +1 -0
  93. package/src/ui/approval/prompt.ts +14 -6
  94. package/src/ui/assistant/simple.ts +137 -26
  95. package/src/ui/assistant/turn-status.ts +16 -3
  96. package/src/ui/contract.ts +119 -0
  97. package/src/ui/footer.ts +21 -2
  98. package/src/ui/i18n/en.ts +34 -6
  99. package/src/ui/i18n/id.ts +34 -6
  100. package/src/ui/i18n/locale.ts +3 -1
  101. package/src/ui/input/input.ts +51 -4
  102. package/src/ui/input/prompt-engine.ts +46 -4
  103. package/src/ui/render/collapse.ts +13 -13
  104. package/src/ui/render/diff.ts +7 -2
  105. package/src/ui/render/format.ts +16 -8
  106. package/src/ui/render/highlight.ts +7 -3
  107. package/src/ui/render/markdown.ts +5 -1
  108. package/src/ui/render/sanitize.ts +29 -2
  109. package/src/ui/render/table.ts +8 -5
  110. package/src/ui/render/theme.ts +18 -4
  111. package/src/ui/render/width.ts +89 -10
  112. package/src/ui/runtime/motion.ts +16 -0
  113. package/src/ui/runtime/screen.ts +45 -0
  114. package/src/ui/runtime/spinner.ts +50 -4
  115. package/src/ui/runtime/statusline.ts +50 -1
  116. package/src/ui/screens/form.ts +42 -15
  117. package/src/ui/screens/model-manager.ts +26 -18
  118. package/src/ui/screens/picker.ts +47 -23
  119. package/src/ui/screens/provider-manager.ts +18 -12
  120. package/src/ui/screens/wizard.ts +24 -8
  121. package/src/ui/tui/app.ts +233 -27
  122. package/src/ui/tui/transcript.ts +269 -65
  123. package/vendor/minicore/LICENSE +21 -0
  124. package/vendor/minicore/VENDOR.md +6 -3
  125. package/vendor/minicore/package.json +6 -3
  126. package/vendor/minicore/src/core/loop.ts +12 -2
  127. package/vendor/minicore/src/core/snapshot.ts +4 -0
  128. package/vendor/minicore/src/providers/openai-compat.ts +76 -25
@@ -0,0 +1,79 @@
1
+ # Contributing
2
+
3
+ Lisensi **MIT** (lihat `LICENSE`). Kontribusi publik diterima. Praktik aktif: **komentar Indonesia** yang menjelaskan *mengapa* (bukan *apa*), istilah teknis tetap English.
4
+
5
+ ## Setup dev
6
+
7
+ ```bash
8
+ git clone https://github.com/startupmini/minicode && cd minicode
9
+ bun install
10
+ bun test # offline/hermetic; live & docker di-skip otomatis
11
+ bun x tsc --noEmit
12
+ bun run lint
13
+ bun run gate:coverage
14
+ ```
15
+
16
+ Butuh `bun >= 1.1.13` (`bun:sqlite` tidak jalan di Node; kode juga memakai
17
+ `AbortSignal.any()` yang absen di Bun 1.0.x — `minicode` gagal cepat dengan
18
+ pesan versi bila runtime terlalu lama).
19
+
20
+ Catatan instalasi dev:
21
+
22
+ - `@lydell/node-pty` DIPIN EKSAK di `bun.lock` (bukan caret): modul native
23
+ berprebuild per platform, khusus test PTY; upgrade beta berikutnya wajib
24
+ validasi probe PTY ulang di Linux + Windows. Sengaja devDependency agar
25
+ instalasi user `npm install -g` tidak ikut mengunduh biner native test-only.
26
+ - PTY tidak tersedia di sebagian mesin Windows (ConPTY) — test PTY di-SKIP
27
+ nyata via `test.skipIf` (bukan pass palsu, lihat F1 di CHANGELOG); CI Linux
28
+ justru GAGAL bila PTY tersedia-di-harapkan tapi tak bisa dibuka.
29
+
30
+ ## Gate (urutan ini, semua hijau sebelum selesai)
31
+
32
+ ```bash
33
+ bun x tsc --noEmit && bun run lint && bun test && bun run gate:coverage && bun run gate:pack
34
+ ```
35
+
36
+ Coverage naik → naikkan minimum di `scripts/coverage-gate.ts` (saat ini **82 funcs / 84,5 lines** + 15 lantai per-berkas modul kritis). Ambang coverage dikunci ke suite CEPAT (`bun test` di CI); gerbang lambat/stokastik tak boleh menaikkan ambang.
37
+
38
+ ## Gate cepat vs lambat (F4.2)
39
+
40
+ ```bash
41
+ bun run gate:fast # tsc + lint + test + coverage + pack + bash + bench:smoke + audit:harness (per-commit/CI)
42
+ bun run gate:slow # extreme fuzz + shadow-git stress + MCP adversarial (nightly slow.yml + manual)
43
+ ```
44
+
45
+ Lambat/stokastik (fuzz multi-seed, stress, docker) tinggal di `slow.yml` — kegagalannya sinyal investigasi, bukan penolakan PR. CI per-commit (`ci.yml`) hanya menjalankan yang deterministik.
46
+
47
+ Gerbang lain:
48
+
49
+ ```bash
50
+ bun run gate:bash # 62 pola serangan + 24 perintah sah → 0 bypass / 0 over-block
51
+ bun run extreme # fuzz + shadow-git + MCP jahat
52
+ bun run bench:smoke # fake, CI-safe
53
+ bun run vendor:check # vendor/minicore sinkron dengan ../minicore
54
+ ```
55
+
56
+ ## Batas lapisan (dijaga `test/ui-boundary.test.ts`)
57
+
58
+ - `cli/` boleh impor `src/ui/` dan `src/`; `src/` non-ui **dilarang** impor `src/ui/`; `src/ui/` **dilarang** impor `cli/`, `src/` non-ui, `#minicore`.
59
+ - Lintas-lapisan via DI dari composition root (`cli/index.ts`, `cli/setup.ts`): `ask`, `setupWhenEmpty`, `setSubAgentSessionFactory`. Tanpa injeksi default selalu deny / fail-closed.
60
+ - `providers → config` satu arah (provisioning di `src/providers/provision.ts`, `src/config.ts` murni IO).
61
+ - Layar `src/ui/screens/` = view murni (props + callback), controller di `cli/`.
62
+ - Jalur non-interaktif shell-first (append-only scrollback); sesi interaktif SELALU TUI alternate-screen (kontrak I16, tanpa opsi linear).
63
+ - Ubah struktur/dependensi antarlapisan → wajib update `docs/ARCHITECTURE.html`.
64
+
65
+ ## Aturan kode
66
+
67
+ - Kernel `vendor/minicore/src/core/*` beku. Hanya seam aditif backward-compatible (`compactAsync`, `initialMessages`, `cwd`). Butuh primitif baru? Buktikan dulu tidak bisa sebagai Tool/Provider/Policy.
68
+ - Limit terpusat di `src/constants.ts` (`LIMITS`) — tanpa magic number tersebar.
69
+ - Semua spawn via `sanitizeSpawnEnv`; semua tulis file via `atomicWriteText`.
70
+ - Satu sumber pola ANSI: `ANSI_PATTERN`/`stripAnsi` di `src/ui/render/theme.ts`.
71
+ - Production code zero `as any` / `as never`.
72
+ - `c`/`glyphs` di `src/ui/render/theme.ts` adalah **getter** runtime — jangan simpan ke `const` module scope.
73
+ - Lebar terminal = kolom, bukan karakter: pakai `displayWidth` dkk. dari `src/ui/render/width.ts` (CJK/emoji = 2 kolom).
74
+ - Teks model/tool/berkas = input tak tepercaya: `sanitizeAnsi` dulu.
75
+ - `cwd` tool dari `ToolContext.cwd`, bukan `process.cwd()`.
76
+ - Line ending LF, encoding UTF-8 tanpa BOM, format `biome` (2 spasi, 100 kolom, double quotes). `bun run lint:fix` sebelum commit.
77
+ - Angka mesin jangan ditulis di markdown (biarkan CI/perintah yang menghasilkannya). Bila temukan angka usang, koreksi + sebutkan koreksinya.
78
+ - Test: tiap fix security/correctness bawa regression test yang **gagal di kode lama**. Tool dua jalur (mis. `grep`) diuji kedua jalurnya. Fuzz `prompt-engine` via `test/fuzz-prompt.test.ts`.
79
+ - Jangan commit kecuali diminta; jangan pernah commit rahasia. Sebelum commit: `git status`, `git diff`, `git log --oneline -10`; stage hanya yang dimaksud.
@@ -0,0 +1,95 @@
1
+ # Environment Variables
2
+
3
+ Variabel yang paling menentukan perilaku (sisanya referensi di bawah):
4
+
5
+ - **Batas otonomi di mesin sendiri:** `MINICODE_SANDBOX` + `MINICODE_SANDBOX_STRICT=1` (tolak bash bila isolasi tak ada) + `MINICODE_BUDGET_STRICT=1` (cost tak dikenal = over budget).
6
+ - **Privasi/minim jejak:** `MINICODE_TELEMETRY=0` (tanpa traces), `MINICODE_AUTO_MEMORY=0` (tanpa auto-simpan memori).
7
+ - **Repo asing:** JANGAN set `MINICODE_ALLOW_LOCAL_CONFIG=1` kecuali workspace milik Anda.
8
+ - **Konsol lawas/aksesibilitas:** `MINICODE_ASCII=1`, `MINICODE_A11Y=1`, `MINICODE_BELL=0`, `NO_COLOR`.
9
+
10
+ ## Runtime & limits
11
+
12
+ | Variabel | Fungsi |
13
+ |---|---|
14
+ | `MINICODE_TIMEOUT_MS` | Default timeout (ms) bila `--timeout` tidak diset; `0` = Infinity |
15
+ | `MINICODE_PLAN` | `1` → mode plan (tanpa `--plan`) |
16
+ | `MINICODE_PERMISSION` | `allowlist` → mode permission |
17
+ | `MINICODE_TOOL_SCOPE` | `explore` → subset read-only 12 tool (sama `--tool-scope explore`) |
18
+ | `MINICODE_HOOKS` | `1` → jalankan hook `pre/post-run` dari `~/.minicode/hooks/*.js` & `.minicode/hooks/*.js` (konteks di env `MINICODE_HOOK_CTX`; env hook disanitasi tanpa secret; dilewati bila sesi dibatalkan) |
19
+ | `MINICODE_SESSION_TTL_DAYS` | TTL sesi (default 30; `0` = selamanya) |
20
+ | `MINICODE_HOME` | Override home untuk DB lokal/global (sessions + vector); default `~` |
21
+ | `MINICODE_TELEMETRY` | `0`/`false`/`off` → matikan penulisan traces.jsonl |
22
+ | `MINICODE_VERIFY_CMD` | Custom verify command (ganti `detectVerifyCommand`) |
23
+ | `MINICODE_BASH_ALLOWLIST` | Kustom allowlist bash (koma-pisah, ganti DEFAULT) |
24
+
25
+ ## Bahasa, diagnosis & kunci
26
+
27
+ | Variabel | Fungsi |
28
+ |---|---|
29
+ | `MINICODE_LANG` | `en`/`id` → bahasa UI (prioritas lengkap di kontrak terminal §i18n: `/lang` > env ini > state.json > locale OS > en) |
30
+ | `MINICODE_DEBUG_STARTUP` | `1` → cetak durasi tiap tahap setup sesi ke stderr (diagnosis startup lambat; diagnostik saja, bukan perilaku) |
31
+ | `MINICODE_MINIMIZE_ANSWER` | set (nilai apa pun) → JANGAN auto-minimize section jawaban model (nilai unset = minimize default) |
32
+ | `MINICODE_KEYSTORE_DISABLE` | `1` → matikan keystore OS seluruhnya (jatuh ke penyimpanan file; untuk CI/headless yang tak punya keychain/DPAPI) |
33
+ | `MINICODE_KEYSTORE_FORCE_DPAPI` | set (nilai apa pun) → paksa jalur DPAPI/Windows walau di non-Windows (khusus test portabilitas; bukan konfigurasi produksi) |
34
+ | `MINICODE_MINIMIZE_TOOL` | set (nilai apa pun) → JANGAN auto-minimize section tool di TUI (nilai unset = minimize default) |
35
+
36
+ ## Sandbox
37
+
38
+ | Variabel | Fungsi |
39
+ |---|---|
40
+ | `MINICODE_SANDBOX` | `docker` \| `os` (alias `bwrap`/`seatbelt`) \| `none` |
41
+ | `MINICODE_SANDBOX_STRICT` | `1` → tak pernah fallback host (redundan dengan default fail-closed untuk request eksplisit, tetap dihormati) |
42
+ | `MINICODE_SANDBOX_ALLOW_FALLBACK` | `1` → satu-satunya jalan fallback host yang sadar bila backend tak tersedia |
43
+ | `MINICODE_SANDBOX_IMAGE` | Image Docker (default `node:22-alpine` — hanya bawa node; python butuh image sendiri) |
44
+ | `MINICODE_SANDBOX_MEMORY` | Memory cap (default `512m`) |
45
+ | `MINICODE_GREP_ENGINE` | `js` → paksa walker internal, jangan pakai ripgrep |
46
+
47
+ ## Provider & memory
48
+
49
+ | Variabel | Fungsi |
50
+ |---|---|
51
+ | `MINICODE_PROVIDER_ORDER` | Urutkan provider agnostik tanpa edit config: `openai,anthropic,deepseek` |
52
+ | `MINICODE_EMBED_MODEL` | Model embedding untuk memory/vector (default `text-embedding-3-small`) |
53
+ | `MINICODE_COMPACT_KEEP_TURNS` | Override keepRecentTurns kompaksi (bilangan ≥1; invalid → default kernel + warn) |
54
+ | `MINICODE_MEMORY_SCOPE` | Scope baca memory: `cwd` (default) \| `global` \| `all` (gabung, tanpa silent shadowing) |
55
+ | `MINICODE_AUTO_MEMORY` | `0` → matikan auto-simpan summary/snippet ke memory (opt-out) |
56
+ | `MINICODE_REPOMAP` | `regex` → paksa repo-map regex (skip LSP) |
57
+ | `TAVILY_API_KEY` | API key untuk Tavily web_search (fallback DuckDuckGo bila kosong) |
58
+
59
+ ## Budget & config
60
+
61
+ | Variabel | Fungsi |
62
+ |---|---|
63
+ | `MINICODE_BUDGET_STRICT` | `1` → penegasan eksplisit fail-closed (cost tak dikenal + pemakaian = over; kini juga default `--budget`) |
64
+ | `MINICODE_ALLOW_LOCAL_CONFIG` | `1` → percayai config lokal workspace (default: diabaikan) |
65
+
66
+ ## Terminal & aksesibilitas
67
+
68
+ | Variabel | Fungsi |
69
+ |---|---|
70
+ | `MINICODE_ASCII` | `1` → paksa glyph ASCII (`[OK]`, `>`, `.`) untuk konsol tanpa UTF-8 |
71
+ | `MINICODE_COMPACT` | `1` → tool call ringkas, `0` → expanded. Default: compact di REPL, expanded di one-shot/exec (juga `/compact`, Ctrl+O) |
72
+ | `MINICODE_JUSTIFY` | `0` → matikan rata kanan-kiri pada keluaran teks model |
73
+ | `MINICODE_DROPDOWN` | `0` → matikan floating dropdown, pakai hint inline (konsol legacy) |
74
+ | `MINICODE_MOTION` | `0` → matikan animasi status (pulse spark saat turn berjalan jadi glyph statis) — aksesibilitas/rekaman layar/SSH lambat |
75
+ | `MINICODE_BELL` | `0` → matikan bell `\x07` saat approval (aksesibilitas) |
76
+ | `MINICODE_STATUSLINE` | `rich` → statusline turn menampilkan token kumulatif + biaya sesi (default hemat) |
77
+ | `MINICODE_A11Y` | `1` → live-region approval untuk screen reader (baris polos tanpa ANSI) |
78
+ | `MINICODE_SHOW_THINKING` | `1` → tampilkan reasoning model (`--verbose` atau env) |
79
+ | `MINICODE_THINKING` | `off` → kirim `enable_thinking:false` ke OpenAI-compat (DeepSeek) |
80
+ | `NO_COLOR` | Set apa pun selain `0` → matikan seluruh warna |
81
+
82
+ ## API key fallback
83
+
84
+ | Variabel | Fungsi |
85
+ |---|---|
86
+ | `AGENT_API_KEY`, `AGENT_BASE_URL`, `AGENT_MODEL` | Fallback generik OpenAI-compat (dipakai provider-layer, memory, task) |
87
+ | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY` | Fallback API key |
88
+ | `DEEPSEEK_BASE_URL` | Base URL DeepSeek (default `https://api.deepseek.com/v1`, untuk compaction) |
89
+ | `ANTHROPIC_MODEL` | Model Anthropic bila tidak diset eksplisit |
90
+
91
+ ## Lanjut
92
+
93
+ - [CLI](cli.md) — padanannya dalam bentuk flag `--`.
94
+ - [Config](config.md) — config file + lokasi data.
95
+ - [Keamanan](security.md) — env scrub subprocess.
package/docs/exec.md ADDED
@@ -0,0 +1,73 @@
1
+ # Otomasi & CI
2
+
3
+ ## Tiga mode non-interaktif
4
+
5
+ | Bentuk | Kapan dipakai |
6
+ |---|---|
7
+ | `minicode "prompt"` | Sekali jalan; output teks model + ledger ke terminal |
8
+ | `echo "prompt" \| minicode` | Prompt datang dari pipeline/another tool |
9
+ | `minicode exec "prompt" --json` | CI: event JSONL di stdout + baris terakhir `{"type":"summary"}` |
10
+
11
+ `exec --json` memancarkan satu JSON per event (langkah tool, output, error) dan **summary** terstruktur di akhir — cukup untuk diparse pipeline tanpa screen-scraping. Kegagalan *setup* (mis. tanpa provider) pun membawa satu baris `{"type":"summary","ok":false,…}` di stdout — stream tak pernah kosong; pesan manusia tetap di stderr, exit `1`.
12
+
13
+ ## Server JSON-RPC untuk IDE: `minicode acp`
14
+
15
+ `minicode acp` membaca satu JSON per baris di stdin dan menulis respons/notifikasi satu JSON per baris di stdout (stderr murni diagnostik manusia). Subset minimal Fase 5 — **bukan klaim kompatibel ACP penuh**:
16
+
17
+ | Method | Params | Balasan |
18
+ |---|---|---|
19
+ | `initialize` | `{client}` | `{server:"minicode-acp", capabilities:{run, streamText, cancel, approval:"deny-headless"}}` |
20
+ | `run` | `{prompt*, cwd?, model?, maxSteps?, timeoutMs?, budget?, mode:"auto"\|"plan"}` | notifikasi `{type:"text",delta}` + `{type:"tool",name}`, lalu `{ok,tokens,steps,turns,text}` atau `{error}` |
21
+ | `cancel` | — | `{cancelled:true/false}` (menggugurkan run berjalan) |
22
+ | `shutdown` | — | keluar 0 |
23
+
24
+ Batasan v1 yang jujur: tiap `run` = sesi BARU (tanpa thread/resume); SATU run dalam terbang (run kedua ditolak, bukan antre); tool gated DITOLAK tanpa TTY (fail-closed, sama seperti CI) — IDE yang butuh tulis/eksekusi memakai mode auto dengan allowlist atau prompt yang self-contained.
25
+
26
+ ```bash
27
+ printf '%s\n' '{"id":1,"method":"initialize"}' '{"id":2,"method":"shutdown"}' | minicode acp
28
+ ```
29
+
30
+ ## Hasil terstruktur: `submit_result`
31
+
32
+ Tool `submit_result` menghasilkan JSON akhir terstruktur, dipanggil paling banyak 1× per run, dengan mode `NO_PROMPT` (tidak minta konfirmasi). Di `exec --json`, isi hasil diteruskan **verbatim** — pengganti `response_format` ala API. Cocok untuk tugas yang hasilnya dikonsumsi program lain, bukan manusia.
33
+
34
+ ## Klarifikasi mid-run: `ask_user`
35
+
36
+ `ask_user` menanyakan manusia di tengah run. Gated + dirender lewat injeksi `promptAskText`; **fail-closed di non-TTY** — di CI tanpa TTY, pertanyaan tidak akan menggantung build tanpa jejak, tool ditolak dengan pesan jelas. Desain CI: jangan bergantung pada `ask_user`; tulis prompt yang self-contained.
37
+
38
+ ## Batas runtime
39
+
40
+ | Kendali | Default | Catatan |
41
+ |---|---|---|
42
+ | `--max-steps <n>` | 50 | Batas langkah tool per run |
43
+ | `--timeout <ms>` | 900000 (15 menit) | Hard deadline per run; `0` = Infinity |
44
+ | `--ratelimit <rpm>` | — | Token bucket request LLM per menit |
45
+ | `--budget <usd>` | — | Warn 80%; lewat → one-shot `exit(1)`, REPL break loop; `exec` menegakkan sama seperti one-shot |
46
+
47
+ `MINICODE_TIMEOUT_MS` mengisi default bila `--timeout` tidak diset.
48
+
49
+ ## Contoh pipeline CI
50
+
51
+ ```bash
52
+ # gate PR: verify + budget ketat + hasil JSON
53
+ minicode exec "perbaiki lint di src/ lalu jalankan bun run lint" --json \
54
+ --verify --budget 0.50 --budget-strict --max-steps 40
55
+
56
+ # pakai provider tertentu tanpa mengubah config
57
+ minicode exec "ringkas diff ini" --json --provider openai --model gpt-4o
58
+
59
+ # prompt dari file
60
+ minicode exec "$(cat task.md)" --json
61
+ ```
62
+
63
+ ## Catatan keamanan untuk CI
64
+
65
+ - Config lokal `.minicode/config.json` **diabaikan secara default** (`--allow-local-config` untuk percayai) — repo clone-an tidak bisa men-spawn MCP atau menyedot prompt. Di runner yang Anda kendalikan penuh, boleh diaktifkan.
66
+ - `git_commit` dan semua tool MCP **di-gate**: di non-TTY selalu ditolak. CI yang butuh commit harus lewat jalur lain (mis. workflow git, bukan agent).
67
+ - Env kredensial di-scrub dari subprocess; `GITHUB_TOKEN` dkk. tidak bocor ke tool `bash`. Detail di [Keamanan](security.md).
68
+
69
+ ## Lanjut
70
+
71
+ - [CLI](cli.md) — semua flags.
72
+ - [Verify & Benchmark](verify-benchmark.md) — `--verify` + self-heal untuk pipeline.
73
+ - [Environment Variables](environment.md) — referensi penuh `MINICODE_*`.
@@ -0,0 +1,102 @@
1
+ # Instalasi
2
+
3
+ Prasyarat tunggal: **`bun >= 1.1.13`** — runtime Minicode, bukan Node.js. `npm` hanya dipakai untuk distribusi, bukan untuk menjalankan. (Lantai versi: kode memakai `AbortSignal.any()` yang absen di Bun 1.0.x; `minicode` gagal cepat dengan pesan jelas bila versi lebih lama.)
4
+
5
+ > Kernel MiniCore ikut repo di `vendor/minicore`, jadi **tanpa clone tambahan**. Clone sibling `../minicore` hanya dibutuhkan bila kamu mau sync ulang kernel via `bun run vendor:minicore`.
6
+
7
+ ## Install (untuk awam — tanpa Node/Bun sekalipun)
8
+
9
+ **Langkah 1 — Pasang Bun** (sekali saja, tutup-buka terminal lagi setelahnya):
10
+
11
+ ```powershell
12
+ # Windows PowerShell
13
+ powershell -c "irm bun.sh/install.ps1 | iex"
14
+ # kalau gagal karena ExecutionPolicy, coba:
15
+ npm install -g bun
16
+ ```
17
+
18
+ ```bash
19
+ # macOS / Linux
20
+ curl -fsSL https://bun.sh/install | bash
21
+ ```
22
+
23
+ Cek: `bun --version` harus keluar `1.4.x`. Kalau masih `command not found`, tutup-buka terminal dulu (PATH baru ke-load setelah restart).
24
+
25
+ **Langkah 2 — Pasang Minicode:**
26
+
27
+ ```bash
28
+ npm install -g minicode-ai
29
+ # bin: minicode
30
+ minicode --version # harus 0.11.x
31
+ ```
32
+
33
+ Kenapa butuh keduanya? `npm` = toko distribusi, `Bun` = mesin yang menjalankan. Tanpa Bun, `minicode` gagal dengan `'bun' is not recognized`.
34
+
35
+ Untuk kontributor (kerja dari source):
36
+
37
+ ```bash
38
+ git clone https://github.com/startupmini/minicode && cd minicode
39
+ bun install && bun link
40
+ ```
41
+
42
+ Opsional tapi disarankan: `rg` (ripgrep) di PATH mempercepat tool `grep`. Tanpa `rg`, walker internal dipakai dengan hasil identik (paksa jalur itu untuk uji dengan `MINICODE_GREP_ENGINE=js`).
43
+
44
+ Verifikasi:
45
+
46
+ ```bash
47
+ minicode doctor # runtime, provider, pricing, memory, sandbox, config
48
+ bun test # offline/hermetic; live & docker di-skip otomatis
49
+ ```
50
+
51
+ Setup wizard berjalan otomatis saat `minicode` pertama kali bila belum ada provider.
52
+
53
+ ## Matriks OS
54
+
55
+ | OS | Sandbox otomatis | Default permission | Catatan |
56
+ |---|---|---|---|
57
+ | Linux + bubblewrap | Ya, tanpa flag | `auto` | Paling terisolasi untuk `bash` |
58
+ | macOS + seatbelt | Ya, tanpa flag | `auto` | Sama, via seatbelt |
59
+ | Windows (semua) / tanpa bwrap-seatbelt | Tidak tersedia | Turun ke `allowlist` + alasan dicetak sekali | Lebih baik membatasi perintah daripada label aman palsu. Pilih sendiri dengan `--allow-all` / `--ask`, matikan dengan `--sandbox none`, atau pakai `--sandbox docker` |
60
+
61
+ Docker **tidak** dipakai otomatis meski tersedia — menarik image tanpa diminta terlalu invasif untuk default.
62
+
63
+ ## Update & uninstall
64
+
65
+ Membuka `minicode` interaktif (TTY) selalu cek versi terbaru ke registry:
66
+ bila ada, paket di-install (`npm install -g minicode-ai@latest`) lalu
67
+ minicode restart sendiri ke versi baru — tanpa update manual. Berlaku hanya
68
+ untuk salinan ter-install (checkout source tidak disentuh) dan tidak pernah
69
+ memblokir: install gagal/offline = lanjut versi lama + pesan manual.
70
+ One-shot, `exec`, pipe, dan CI hanya menampilkan notifikasi (tanpa install).
71
+
72
+ > Model ancaman yang jujur: auto-update mengeksekusi kode dari registry
73
+ > tanpa verifikasi tanda tangan client-side (attestasi Sigstore npm butuh
74
+ > infrastruktur verifikasi di luar jangkauan CLI zero-dep — sudah diteliti,
75
+ > bundelnya tak membawa identitas repo yang bisa dicek offline). Percayakan
76
+ > TLS registry + rilis hanya dari CI repo ini; yang butuh jaminan lebih,
77
+ > matikan auto-update (`MINICODE_AUTO_UPDATE=0`) dan update manual setelah
78
+ > memeriksa rilis di GitHub.
79
+
80
+ ```bash
81
+ npm update -g minicode-ai # manual, bila auto-update dimatikan
82
+ minicode sync # refresh model baru dari semua provider
83
+ minicode pricing sync # refresh cache harga (3.162 model, ~213 KB)
84
+ ```
85
+
86
+ Opt-out: `NO_UPDATE_CHECK=1` atau `MINICODE_AUTO_UPDATE=0`.
87
+
88
+ Clone contributor: `cd minicode && git pull && bun install`.
89
+
90
+ Uninstall = `npm uninstall -g minicode-ai` (atau hapus clone + `bun unlink` bila memakai link). Config global tetap di `~/.minicode/` sampai kamu hapus manual; config lokal di `.minicode/` per repo. Uninstall tidak pernah menghapus state, sesi, memori, atau file proyekmu.
91
+
92
+ ## Lokasi data
93
+
94
+ - Config global `~/.minicode/config.json` + lokal `.minicode/config.json` (merge, lokal menang, tulis atomik + chmod 600).
95
+ - Token OAuth di `~/.minicode/auth.json` (chmod 600) — **bukan** di `config.json`, karena config lokal sering ikut ter-commit.
96
+ - Sessions `.minicode/sessions.db` (WAL), vector memory `vector.db`, repo-map `.minicode/repomap.json`, traces `.minicode/traces.jsonl`, checkpoint `.minicode/checkpoints/`, trash `.minicode/.trash/`.
97
+ - Override home untuk DB dengan `MINICODE_HOME` (berguna agar test hermetic di POSIX).
98
+
99
+ ## Berikutnya
100
+
101
+ - [Quickstart 5 menit](quickstart.md) — wizard → prompt pertama → verify.
102
+ - [Troubleshooting](troubleshooting.md) — bila `doctor` merah atau sandbox tidak jalan.
@@ -0,0 +1,37 @@
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 (37 bawaan + MCP dinamis `serverId.toolName`) |
10
+ | **Tool scope** | `full` (semua 37) atau `explore` (subset read-only 12 tool) — flag `--tool-scope` |
11
+ | **Permission mode** | Keputusan siapa yang memutuskan aksi: `auto / readonly / plan / allowlist / ask / allow-all` |
12
+ | **Gate** | Tool wajib persetujuan manusia saat TTY; non-TTY selalu tolak (mis. `git_commit`, MCP, `delegate_task`) |
13
+ | **Path jail** | Pembatasan akses file ke workspace (realpath + symlink + TOCTOU `O_NOFOLLOW`); aktif bahkan `--allow-all` |
14
+ | **Bash-guard** | Normalisasi + blokir pola bash berbahaya sebelum eksekusi (quote-split, indirection, wrapper) |
15
+ | **Sandbox OS** | bubblewrap (Linux) / seatbelt (macOS) — otomatis bila tersedia |
16
+ | **Sandbox Docker** | Container ephemeral `--network none`, 512m, 1 CPU, `node:22-alpine` |
17
+ | **Checkpoint** | Snapshot per turn via shadow-git: SHA tree di `refs/minicode/…` (O(delta), HEAD/index tak tersentuh) |
18
+ | **Recovery journal** | `journal-<sesi>.jsonl`: `pending` → `committed` → `finalized`; sumber direktif verifikasi saat resume |
19
+ | **Session** | Riwayat percakapan di `.minicode/sessions.db` (SQLite WAL); `--resume` lanjut full history |
20
+ | **Memory dua lapis** | `MEMORY.md` hierarki (selalu ke system prompt) + vector RAG hybrid (injeksi bila skor ≥ ambang) |
21
+ | **RAG hybrid** | Pencarian memory cosine 0.7 + keyword 0.3, ranking MMR (λ 0.7), dedup >0.92 |
22
+ | **Repo-map** | Simbol per file (regex 9 bahasa, fallback LSP) disuntik ke system prompt |
23
+ | **Skill** | Prompt terpaket `.minicode/skills/*.md` dengan frontmatter `name`/`description` |
24
+ | **Hook** | Skrip `pre/post-run` dari `~/.minicode/hooks` + `.minicode/hooks`; mati default, `MINICODE_HOOKS=1` |
25
+ | **Env scrub** | `sanitizeSpawnEnv` menghapus kata-kunci kredensial dari env subprocess |
26
+ | **Secret scrubber** | Redaksi `sk-`/`ghp_`/`AKIA`/PEM/JWT/Bearer sebelum teks ke LLM |
27
+ | **Ledger** | Baris ` › name target` / ` › name: …` di stderr — jejak aksi agent |
28
+ | **Scrollback** | Riwayat layar terminal; jalur non-interaktif minicode append-only di sana (interaktif pakai alternate screen) |
29
+ | **Transient** | UI muncul-sekali yang menghapus dirinya (spinner, garis status turn) — vs transkrip yang menetap |
30
+ | **Composition root** | `cli/index.ts` + `cli/setup.ts`: satu tempat wiring DI (provider, RAG, session, tools) |
31
+ | **Seam aditif** | Satu-satunya patch yang dibolehkan ke kernel beku: `compactAsync`, `initialMessages`, `cwd` |
32
+ | **Self-contained** | Tanpa clone repo lain — kernel di-vendor, runtime zero-dep, butuh Bun ≥ 1.0 |
33
+
34
+ ## Lanjut
35
+
36
+ - [Konsep & Desain](concepts.md) — narasi di balik istilah.
37
+ - [Arsitektur](architecture.md) — bagaimana lapisan-lapisan itu tersusun.
@@ -0,0 +1,54 @@
1
+ # MCP & LSP
2
+
3
+ Sambungkan Minicode ke tool server eksternal (MCP) dan language server (LSP) untuk kemampuan di luar bawaan.
4
+
5
+ ## MCP — dua transport
6
+
7
+ ```bash
8
+ # stdio — server lokal yang di-spawn minicode
9
+ minicode config mcp add fs --command npx --args "-y,@modelcontextprotocol/server-filesystem,."
10
+
11
+ # Streamable HTTP — server remote (spec 2025-03-26, SSE juga ditangani)
12
+ minicode config mcp add ctx7 --url https://mcp.example.com/mcp --header "authorization=Bearer xxx"
13
+
14
+ # localhost butuh opt-in eksplisit (anti-SSRF)
15
+ minicode config mcp add lokal --url http://127.0.0.1:3000/mcp --allow-private
16
+ ```
17
+
18
+ Setelah terdaftar, `mcp_list` menampilkan **tools, resources, prompts** sekaligus:
19
+
20
+ | Tool | Spec | Catatan |
21
+ |---|---|---|
22
+ | `mcp_list` | `tools/list` + `resources/list` + `prompts/list` | read-only, tidak di-gate |
23
+ | `mcp_call` | `tools/call` | di-gate |
24
+ | `mcp_read` | `resources/read` | di-gate (konten pihak ketiga = jalur prompt-injection). Biner diganti penanda ukuran |
25
+ | `mcp_prompt` | `prompts/get` | di-gate, server merender argumen |
26
+
27
+ Tool dinamis `serverId.toolName` otomatis muncul. `resources`/`prompts` opsional di spec: server "Method not found" tetap terhubung dengan tool utuh.
28
+
29
+ Keamanan HTTP: host privat ditolak kecuali `--allow-private` (penjaga sama dengan `web_fetch`: DNS pinning). Redirect tidak diikuti. Ukuran dibatasi. Balasan dicocokkan per request id. Header `Authorization` tidak masuk log.
30
+
31
+ Izin: semua MCP bertitik selalu di-gate — `auto` minta konfirmasi sekali per tool (`[a] Always` persist ke allowlist); `readonly`/`plan`/`allowlist` menolak. Tanpa wildcard auto-allow (proteksi supply-chain).
32
+
33
+ Model kepercayaan: permission hanya kontrol *pemanggilan*. Capability di balik server (filesystem, network, proses, API) tak bisa diketahui statis — anggap setiap `mcp_call` external capability arbitrer. Pembatalan hentikan penungguan, tapi tidak bunuh proses stdio maupun batalkan efek yang sudah terjadi.
34
+
35
+ Ekspos balik (stdio saja — tanpa mode HTTP, jadi tak ada permukaan jaringan):
36
+
37
+ ```bash
38
+ minicode mcp serve # curated tools + permission aktif
39
+ minicode mcp serve --cwd <dir> # workspace root (jail + eksekusi + jurnal memakai root yang sama)
40
+ minicode mcp serve --allow-all # tanpa prompt, tetapi jail + bash-guard tetap enforced
41
+ minicode mcp serve --all-tools # termasuk delegate/memory/MCP internal (opt-in operator)
42
+ ```
43
+
44
+ Semantik server mode: tiap `tools/call` lewat validateArgs kernel → permission (mode `auto`, atau `allow-all` bila flag) → eksekusi → jurnal mutasi (`mcp-server`) → respons. Argumen invalid ditolak sebelum eksekusi; error di-scrub; output di-cap + ditandai bila dipotong. ID request JSON-RPC dipakai untuk idempotency: duplikat konkuren dieksekusi sekali, retry id sama me-replay hasil (proses hidup) atau error eksplisit `already executed`/`failed`/`unknown` (lintas restart, dari bukti jurnal) — tak pernah eksekusi ulang buta. `notifications/cancelled` membatalkan request individual; maksimal 32 in-flight. Tanpa turn/session kernel: tak ada persistensi percakapan, checkpoint, atau undo untuk operasi server.
45
+
46
+ ## LSP
47
+
48
+ ```bash
49
+ minicode config lsp add .ts --command typescript-language-server --args --stdio
50
+ ```
51
+
52
+ Setelah terdaftar: `lsp_diagnostics`, `lsp_definition`, `lsp_references`, `lsp_hover`, `lsp_symbols`, `lsp_workspace_symbols`. Diagnostics otomatis di `edit`/`write_file` bila server terkonfigurasi. `didClose` cleanup.
53
+
54
+ Bila LSP tidak jalan: pastikan server terinstall dan command benar. Repo-map regex tetap jalan sebagai fallback (`MINICODE_REPOMAP=regex`).
@@ -0,0 +1,63 @@
1
+ # Memory & Sessions
2
+
3
+ ## Memory dua lapis
4
+
5
+ 1. `MEMORY.md` hierarki (global → lokal → root → `CLAUDE.md` → `.minicode/rules/*.md`) selalu dimuat ke system prompt.
6
+ 2. Index vektor hybrid (`vector.db`, cosine 0.7 + keyword 0.3) di-inject sebagai `# Relevant memory` bila skor ≥ ambang (0.20 hybrid / 0.25 keyword-only). Ranking MMR (λ 0.7) + dedup cosine >0.92 agar prompt tidak penuh parafrase. Entri >2000 char dipecah chunk overlap 200.
7
+
8
+ Kategori: `fact|decision|preference|snippet|summary` + `tags`. Default `fact`; boost `decision` +0.1 bila query match. `write_memory {category?, tags?}`.
9
+
10
+ Scope baca: `cwd` (default) | `global` | `all` (gabung, tanpa silent shadowing). Atur via `MINICODE_MEMORY_SCOPE`.
11
+
12
+ Retensi hierarkis per kategori: `fact`/`decision`/`preference` 180 hari, `summary` 90 hari, `snippet` 14 hari; maks 5000 baris, prune + `VACUUM` periodik tiap tulis. `access_count` per row.
13
+
14
+ ```bash
15
+ minicode memory status [--json] # rows, bytes DB/WAL/SHM, sebaran model/dim, hit-rate RAG
16
+ ```
17
+
18
+ Auto-simpan: summary persist + snippet verify sukses. Opt-out `MINICODE_AUTO_MEMORY=0`.
19
+
20
+ Embedding: default `text-embedding-3-small` (`MINICODE_EMBED_MODEL`). Dim-mismatch → warn sekali + fallback keyword-only. FTS5 (`porter unicode61`) + trigger sync; fallback LIKE bila MATCH gagal.
21
+
22
+ ## Sessions
23
+
24
+ Sesi di `.minicode/sessions.db` (WAL, capped + busy-retry async). `--resume <id>` melanjutkan full history (termasuk `toolCallId`/`name`); workspace dibandingkan ke checkpoint terakhir dan divergensi dilaporkan (bukan replay buta). TTL 30 hari (`MINICODE_SESSION_TTL_DAYS=0` = selamanya). `minicode sessions purge` hapus manual. Branch via `branchSession` (fork history+turns).
25
+
26
+ ## Checkpoint & Undo
27
+
28
+ Setiap turn otomatis checkpoint. Dua mode otomatis:
29
+
30
+ **Repo git (utama).** Snapshot sebagai **SHA tree git** — O(delta), tanpa cap jumlah file. Index/`HEAD` tak pernah disentuh (tanpa add/commit/checkout/reset/stash pada state user). Ref di `refs/minicode/<sesi>/…` menunjuk *tree* sehingga tak muncul di `git log`. Aman dari `gc` (ref mem-pin object). `core.autocrlf=false` dipaksa. Restore hanya sentuh path berbeda.
31
+
32
+ Batas: snapshot memakai `git add -A`, jadi file ber-`.gitignore` tidak ikut (disengaja agar `node_modules` tak ikut).
33
+
34
+ **Non-repo (fallback).** Snapshot isi file dengan cap `WORKSPACE_SNAPSHOT_LIMIT`.
35
+
36
+ `/undo` ke sebelum turn, `/redo` ke sesudahnya. Manifest `.minicode/checkpoints/` cap 20 terbaru. Turn tanpa perubahan tidak membuat checkpoint. Pointer dari marker jurnal (bukan kebenaran mutlak) — crash di tengah diadopsi dari marker valid berikutnya.
37
+
38
+ ## Recovery journal
39
+
40
+ Setiap mutasi (tulis/edit/hapus, `bash`, `git_commit`, `mcp_call`, `code_run`, `delegate_task`, memory tulis/hapus) dicatat di `.minicode/journal-<sesi>.jsonl` — di kode disebut *mutation journal*: `pending` → `committed`/`failed` → `finalized` (setelah turn durable di SQLite). Saat resume, dibaca **sebelum** seed kernel:
41
+
42
+ - `committed` yang turn-nya hilang → tidak diulang; model diberi catatan narasi.
43
+ - `pending`/`failed` → direktif verifikasi; dilarang redo buta.
44
+ - `committed` MCP = *external-acknowledged*, wajib baca-balik.
45
+
46
+ Jurnal bukan transaksi atomik; `pending` = ambigu (efek mungkin sudah terjadi). Hanya hash + path relatif (tanpa isi/kredensial). File dibuat eager saat sesi terpasang. Jurnal anak terpisah per sesi anak. `sessions purge` ikut hapus jurnal basi.
47
+
48
+ ## Konteks & compaction
49
+
50
+ Model hanya melihat jendela riwayat terbatas (**konteks**). Saat percakapan menekan jendela itu, Minicode **memadatkan** (compaction): turn lama diganti satu ringkasan, turn terbaru dipertahankan utuh. Anda melihatnya sebagai baris `── compacted: …` di output.
51
+
52
+ - **Kapan terjadi:** otomatis saat tekanan konteks, sebelum batas jendela tercapai. Bila sesudah padat masih kurang, run gagal eksplisit (`context window exceeded`) — bukan sunyi.
53
+ - **Yang dipertahankan:** ringkasan fakta — path file, signature, snippet penting, hasil tool, error, next steps. Ringkasan sebelumnya dibawa verbatim (tidak diringkas ulang) agar makna tak melenceng tiap siklus.
54
+ - **Yang mungkin hilang:** teks lengkap turn lama (dipotong ~250 char/baris saat diringkas), detail output tool, urutan persis percakapan.
55
+ - **Riwayat asli tidak disimpan ganda:** sesi berjalan dan sesi tersimpan mengikuti state terbaru (ringkasan + turn baru). Yang perlu durable lintas sesi, tulis eksplisit via `write_memory`.
56
+ - **Ringkasan lebih cerdas bila ada kunci DeepSeek** (`DEEPSEEK_API_KEY`): ringkasan dibuat LLM (timeout 10 dtk); tanpanya dipakai ringkasan mekanikal. Keduanya memagar konten tak-terpercaya sebagai data + secret-scrub sebelum diringkas.
57
+ - **Beda dengan memory:** ringkasan konteks hidup di sesi berjalan; `write_memory`/vector hidup lintas sesi dan bisa di-retrieval. Ringkasan juga disimpan sebagai memori kategori `summary` — matikan via `MINICODE_AUTO_MEMORY=0` bila tak diinginkan.
58
+
59
+ ## Repo intelligence & telemetry
60
+
61
+ System prompt memuat repo-map regex (9 bahasa) + fallback LSP `workspace/symbol`. Cache `.minicode/repomap.json` (sig mtime). File diurut import-graph (60 files, 2.5k chars). `MINICODE_REPOMAP=regex` skip LSP. Tree-sitter sengaja tidak dipakai (alasan terukur di `extractSymbolsAsync`).
62
+
63
+ Telemetry `.minicode/traces.jsonl` — satu baris per run (tokens, steps, cost, durasi); prompt di-scrub; chmod 600; rotate 1000 baris. Opt-out `MINICODE_TELEMETRY=0`. `minicode stats` tampilkan deny-rate dari `step-traces.jsonl`.
@@ -0,0 +1,72 @@
1
+ # Policy & Sandbox
2
+
3
+ Siapa boleh apa: enam mode izin, penjaga perintah shell, dan isolasi eksekusi — plus batas jujurnya.
4
+
5
+ ## 6 permission mode
6
+
7
+ `type PermissionMode = "auto"|"readonly"|"plan"|"allow-all"|"ask"|"allowlist"` (`permission.ts`). Keputusan data-driven per mode.
8
+
9
+ | Mode | Semantik |
10
+ |---|---|
11
+ | `auto` | Readonly + gated-prompt + file/internal-write allow; `code_run`/`bash` dengan guard. `delegate_task`/`mcp_call`/semua MCP bertitik di-gate (prompt saat TTY, tolak tanpa TTY) |
12
+ | `ask` | Readonly + `NO_PROMPT_TOOLS` auto-allow; sisanya prompt/TTY + allowlist persist |
13
+ | `readonly` | Hanya 18 tool `READONLY_TOOLS` |
14
+ | `plan` | `readonly` + `todo_write` + `delegate_task` (anak dipaksa explore/read-only) + `submit_result`. Tetap tanpa mutasi file/git/memory |
15
+ | `allowlist` | Bash hanya pola `DEFAULT_BASH_ALLOWLIST`/env; file-write/internal-write sesuai set. Diwariskan ke sub-agent (parent allowlist → anak allowlist, bukan auto) |
16
+ | `allow-all` | Allow semua; **tetap** tolak bash berbahaya + path jail tetap aktif |
17
+
18
+ Cycle Tab/Shift+Tab hanya 5 (`auto,ask,plan,allowlist,allow-all` — `allow-all` dilewati agar tak aktif tak sengaja). Mode bisa dioverride: `--plan`, `--allowlist`, `--ask`, `--allow-all`, `MINICODE_PLAN=1`, `MINICODE_PERMISSION=allowlist`, `Shift+Tab` runtime.
19
+
20
+ Set terkait: `INTERNAL_WRITE_TOOLS`, `FILE_WRITE_TOOLS`, `GATED_TOOLS` (+ `*.*` MCP), `NO_PROMPT_TOOLS`. `move_file`/`delete_file` dijail di permission layer (berlaku semua mode termasuk `--allow-all`).
21
+
22
+ ## Bash-guard ternormalisasi
23
+
24
+ `src/policy/bash-guard.ts`: quote pemisah kata dibuang dan assignment sederhana disubstitusi **sebelum** pemeriksaan.
25
+
26
+ | Dulu lolos | Sekarang |
27
+ |---|---|
28
+ | `cat .e""nv` | ditolak |
29
+ | `X=.env; cat $X` | ditolak |
30
+ | `p=python3; $p -c 1` | ditolak |
31
+ | `node --eval "1"` | ditolak |
32
+ | `env`, `set`, `export -p` | ditolak |
33
+ | `curl -F file=@~/.ssh/id_rsa` | ditolak |
34
+ | `type ..\..\windows\system32\config\sam`, `Get-Content .../ntds.dit` | ditolak (hive Windows + `reg save|export` hive + `vssadmin create|delete shadow` + `ntdsutil`; `reg query`, `vssadmin list`, `system.txt` biasa tetap lolos) |
35
+ | `write_file .minicode/<apa-pun>` | ditolak fail-closed (kunci penuh segmen `.minicode/`; kecuali restore `.trash/` → workspace dan skrip `.minicode/hooks/`) |
36
+ | `bash <(curl x)` | ditolak |
37
+ | `rm -rf ..`, `rm --recursive --force /`, `rm -rf /; :` | ditolak |
38
+ | `command env`, `nice env`, dkk. (wrapper) | deteksi env-dump ter-anchor ke awal | ditolak via `stripCommandWrappers` (buang wrapper berlapis) |
39
+
40
+ Allowlist (juga default bila tanpa sandbox): `git status/diff/log/branch/show`, `bun test/run/x tsc`, `npm run/exec`, `npx`, `ls cat head tail wc grep rg find which echo pwd`. Tulis via shell (`mkdir cp mv rm touch`) ditahan — pakai `write_file`/`edit` yang ter-jail. `npm exec`/`npx`/`bun run`/`bun x` tak boleh ada ekspansi shell (`$`, backtick) atau redirection.
41
+
42
+ Ukur, bukan klaim — jalankan sendiri untuk angka terkini:
43
+
44
+ ```bash
45
+ bun run gate:bash # korpus manual pola serangan + perintah sah (0 bypass / 0 over-block = lulus)
46
+ bun run extreme:fuzz # mutasi kombinatorial ber-seed
47
+ ```
48
+
49
+ Fuzz membangkitkan varian dari transformasi yang shell anggap setara (quote-split, indirection, wrapper, flag panjang, chaining); temuan terkunci sebagai regression test.
50
+
51
+ > Batas jujur: analisis statis atas bahasa Turing-complete. `$(curl …)` dinamis tak bisa diselesaikan tanpa eksekusi — untuk itu sandbox OS ada.
52
+
53
+ ## Sandbox otomatis
54
+
55
+ | Kondisi | Yang terjadi |
56
+ |---|---|
57
+ | bwrap (Linux) / seatbelt (macOS) tersedia | Bash di dalamnya, tanpa flag |
58
+ | Tidak tersedia (termasuk semua Windows) | Default turun ke `allowlist` + alasan dicetak sekali |
59
+ | `--allow-all` / `--ask` / `--plan` / `--allowlist` diberikan | Pilihan dihormati, tanpa peringatan |
60
+ | `--sandbox none` | Opt-out sadar; tanpa downgrade |
61
+ | `--sandbox docker` | Container ephemeral (`--network none`, 512m, 1 CPU, `node:22-alpine`) |
62
+ | `--sandbox docker` tapi daemon mati | TOLAK sebelum jalan (fail-closed) + cara opt-in fallback eksplisit; tidak pura-pura terisolasi |
63
+
64
+ `MINICODE_SANDBOX_STRICT=1` = tak pernah fallback host (redundan dengan default fail-closed untuk request eksplisit, tetap dihormati). `MINICODE_SANDBOX_ALLOW_FALLBACK=1` = satu-satunya jalan fallback host yang sadar bila backend tak tersedia. `MINICODE_SANDBOX_IMAGE` ganti image (default `node:22-alpine` hanya bawa node). `code_run` selalu lewat sandbox runner dan menolak bila backend tak tersedia.
65
+
66
+ ## Lapisan lain
67
+
68
+ - **Path jail** realpath-based + symlink `realpath` di permission layer; `.env`/`.git/config`/`node_modules`/hive Windows deny; `.minicode/` terkunci penuh untuk tool tulis berdasarkan target NYATA (realpath best-effort `isOwnedStateReal` — junction/symlink internal ke `.minicode/` ikut ditahan; kecuali restore `.trash/` + skrip `hooks/`); bash-guard menahan PEMBUATAN link yang operannya sensitif/owned-state; TOCTOU `O_NOFOLLOW` (`src/lib/safe-open.ts`: `resolveSafePath` untuk penulis, `safeOpenRead` untuk pembaca; POSIX-only, Windows pre-check).
69
+ - **Env scrub** `sanitizeSpawnEnv`: strip kata-kunci kredensial dari merge final; `GITHUB_WORKSPACE`/`REDIS_HOST`/`AWS_REGION` tetap ada, `GITHUB_TOKEN`/`AWS_SECRET_ACCESS_KEY`/`DATABASE_URL` tetap di-strip.
70
+ - **web_fetch/web_search**: redirect manual 5 hop + DNS pinning 30 dtk + body 2 MB.
71
+ - **Secret scrubber**: `sk-`, `ghp_`, `AKIA`, PEM, JWT, Bearer, `api_key=...` di-redact sebelum ke LLM (read_file/bash/grep) — tanpa whitelist kata.
72
+ - **Config/allowlist**: atomic randomUUID tmp+rename + chmod 600. MCP serve curated tools + permission aktif.
@@ -0,0 +1,49 @@
1
+ # Pricing & Budget
2
+
3
+
4
+ ## Harga offline + sync
5
+
6
+ 25 harga bawaan tersedia offline. Untuk cakupan luas, tarik sendiri — **tidak ada fetch otomatis** di jalur run (jalur run hanya baca cache lokal agar tidak menambah latensi/bocor pola pemakaian):
7
+
8
+ ```bash
9
+ minicode pricing sync # 3.162 model dari models.dev (~213 KB cache)
10
+ minicode pricing status # sumber aktif + umur cache + tanda (stale) >30 hari
11
+ minicode pricing show claude-sonnet-4-5
12
+ minicode pricing clear # kembali ke bawaan
13
+ ```
14
+
15
+ Pencocokan per-segmen (pemisah `/` dan `:`), kunci terpanjang menang. `deepseek/deepseek-chat:free` cocok, `claude-sonnet-4-5` menang atas `claude-sonnet-4`, `my-gpt-4o-wrapper` tidak cocok `gpt-4o`. Sufiks `:free` selalu $0 kecuali ada entri eksplisit.
16
+
17
+ Satu id sering beda harga antar provider (`qwen3-coder-plus` ada di 6 provider, dua $0 karena langganan). Overlay membuang kandidat gratis bila ada yang berbayar lalu ambil **median**, supaya `--budget` tidak menganggap semuanya gratis. Opus dikoreksi `$15/$75 → $5/$25` (sebelumnya 3× lipat merusak budget).
18
+
19
+ Semua angka **estimasi**: biaya riil tergantung provider, paket, diskon.
20
+
21
+ ## Budget
22
+
23
+ ```bash
24
+ minicode --budget 0.50 "task besar"
25
+ minicode --budget 0.05 --budget-strict "task ketat"
26
+ ```
27
+
28
+ - Peringatan kuning 80%.
29
+ - Lewat budget: one-shot `exit(1)`, REPL `break` loop, `exec` menegakkan sama seperti one-shot (pernah ada bug `exec` mengabaikan `--budget`, sudah diperbaiki).
30
+ - Pagu juga diputus MID-TURN: watcher biaya live (`watchBudgetLimit` di `cli/setup.ts`) menggugurkan turn yang sedang berjalan begitu lewat — dulu tool loop / siklus self-heal bisa belanja tanpa batas dalam satu turn. Abort budget membawa identitas kind `budget_exceeded` (bukan `aborted` generik) agar terbedakan dari Ctrl+C user.
31
+ - Cost tak dikenal (model tanpa harga) + ADA pemakaian = fail-closed secara DEFAULT: dianggap over budget, bukan diabaikan (dulu hanya di `--budget-strict`; perilaku lama membuat `--budget` diam-diam mati untuk model baru). Nol token (belum belanja, mis. pre-check prompt baru) tetap lolos.
32
+ - `--budget-strict` / `MINICODE_BUDGET_STRICT=1` = penegasan eksplisit perilaku fail-closed di atas (back-compat; perilaku sama dengan default).
33
+ - Harga negatif/NaN/Infinity dari overlay lokal ditolak saat ekstraksi (bukan biaya negatif yang mengurangi total).
34
+ - Tampil di bawah $1 memakai 4 desimal (`$0.0601 > $0.0500`), bukan `$0.00` yang menyesatkan.
35
+ - `/status` dan (opt-in `MINICODE_STATUSLINE=rich`) spinner menampilkan token kumulatif + biaya sesi. Kumulatif sesi dipisah dari per-turn (`get()` vs `getSession()`) — bug lama membuat `/cost` selalu 0 setelah turn pertama.
36
+
37
+ ## Membaca angka token
38
+
39
+ `/status` menampilkan LIMA angka dengan arti berbeda — jangan dicampur:
40
+
41
+ | Baris | Sumber | Arti |
42
+ |---|---|---|
43
+ | `Context` | kernel (`estimateSessionContext`) | Estimasi ukuran jendela SAAT INI (yang masih muat diproses) |
44
+ | `Turn` | `usage.get()` | Token turn TERAKHIR saja (di-reset tiap turn) |
45
+ | `Input`/`Output` | event usage provider | Pemakaian kumulatif sesi per arah |
46
+ | `Total` | `usage.getSession()` | Kumulatif sesi = Input + Output (tak pernah di-reset) |
47
+ | `Cost` | tabel harga offline | Estimasi, atau `N/A` bila model tak dikenal — **tanpa fetch** |
48
+
49
+ Aturan praktis: `Turn` besar + `Context` kecil = turn ini boros di jendela sempit (saatnya `/compact` atau `/clear`); `Total` besar + `Cost: N/A` = model tanpa harga, `--budget` fail-closed (dianggap over). Kurva token per sesi bisa direplay dari `.minicode/step-traces.jsonl` (kolom `totalTokens` per baris, monoton naik); `minicode stats` menampilkan peak-nya (`Peak tok`).