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.
- package/AGENTS.md +45 -0
- package/CHANGELOG.md +59 -4
- package/PLAN.md +491 -0
- package/README.md +2 -2
- package/cli/commands/acp.ts +485 -0
- package/cli/commands/auth.ts +7 -4
- package/cli/commands/config.ts +41 -27
- package/cli/commands/exec.ts +33 -12
- package/cli/commands/mcp.ts +3 -2
- package/cli/commands/memory.ts +1 -1
- package/cli/commands/pricing.ts +6 -4
- package/cli/commands/providers.ts +18 -8
- package/cli/commands/sessions.ts +11 -4
- package/cli/commands/skills.ts +3 -3
- package/cli/commands/stats.ts +3 -1
- package/cli/commands.ts +6 -0
- package/cli/index.ts +82 -57
- package/cli/model-manager.ts +6 -1
- package/cli/router.ts +7 -0
- package/cli/setup.ts +341 -5
- package/cli/tui.ts +54 -18
- package/docs/ARCHITECTURE.html +29 -22
- package/docs/CONTROL-PLANE-MAP.md +139 -0
- package/docs/HARNESS.md +150 -0
- package/docs/PLAN_UIUX_V6.md +209 -0
- package/docs/README.md +1 -1
- package/docs/SUMMARY.md +52 -0
- package/docs/TERMINAL_CONTRACT.md +367 -0
- package/docs/UI_RENDER_PIPELINE.md +165 -0
- package/docs/USAGE.md +11 -0
- package/docs/agents.md +31 -0
- package/docs/architecture.md +3 -3
- package/docs/choosing-mode.md +34 -0
- package/docs/cli.md +130 -0
- package/docs/concepts.md +53 -0
- package/docs/config-providers.md +87 -0
- package/docs/config.md +63 -0
- package/docs/contributing.md +79 -0
- package/docs/environment.md +95 -0
- package/docs/exec.md +73 -0
- package/docs/getting-started.md +102 -0
- package/docs/glossary.md +37 -0
- package/docs/mcp-lsp.md +54 -0
- package/docs/memory-sessions.md +63 -0
- package/docs/policy-sandbox.md +72 -0
- package/docs/pricing-budget.md +49 -0
- package/docs/quickstart.md +60 -0
- package/docs/repl.md +67 -0
- package/docs/security-model.md +95 -0
- package/docs/security.md +91 -0
- package/docs/skills.md +48 -0
- package/docs/terminal.md +79 -0
- package/docs/tools.md +123 -0
- package/docs/troubleshooting.md +40 -0
- package/docs/verify-benchmark.md +58 -0
- package/package.json +8 -5
- package/src/app/provider-layer.ts +12 -4
- package/src/app/session.ts +6 -0
- package/src/app/tool-layer.ts +2 -1
- package/src/constants.ts +35 -0
- package/src/lib/net.ts +6 -1
- package/src/lsp/client.ts +41 -8
- package/src/mcp/http-transport.ts +52 -15
- package/src/mcp/transport.ts +32 -1
- package/src/memory/files.ts +6 -5
- package/src/policy/allowlist.ts +1 -1
- package/src/policy/bash-guard.ts +154 -14
- package/src/policy/compaction.ts +57 -3
- package/src/policy/context.ts +4 -0
- package/src/policy/jail.ts +49 -4
- package/src/policy/permission.ts +152 -12
- package/src/policy/pricing.ts +12 -9
- package/src/presentation/adapter.ts +721 -0
- package/src/presentation/events.ts +324 -0
- package/src/presentation/label.ts +140 -0
- package/src/presentation/model.ts +172 -0
- package/src/presentation/reducer.ts +486 -0
- package/src/presentation/store.ts +256 -0
- package/src/providers/anthropic.ts +22 -4
- package/src/providers/detect.ts +2 -1
- package/src/providers/router.ts +13 -0
- package/src/repo/repomap.ts +2 -29
- package/src/session/checkpoint.ts +27 -9
- package/src/session/journal.ts +27 -5
- package/src/skills/loader.ts +88 -5
- package/src/telemetry/trace.ts +36 -15
- package/src/tools/ask_user.ts +73 -4
- package/src/tools/bash.ts +15 -17
- package/src/tools/glob.ts +10 -11
- package/src/tools/lsp.ts +3 -56
- package/src/tools/memory.ts +13 -12
- package/src/tools/task.ts +1 -0
- package/src/ui/approval/prompt.ts +14 -6
- package/src/ui/assistant/simple.ts +137 -26
- package/src/ui/assistant/turn-status.ts +16 -3
- package/src/ui/contract.ts +119 -0
- package/src/ui/footer.ts +21 -2
- package/src/ui/i18n/en.ts +34 -6
- package/src/ui/i18n/id.ts +34 -6
- package/src/ui/i18n/locale.ts +3 -1
- package/src/ui/input/input.ts +51 -4
- package/src/ui/input/prompt-engine.ts +46 -4
- package/src/ui/render/collapse.ts +13 -13
- package/src/ui/render/diff.ts +7 -2
- package/src/ui/render/format.ts +16 -8
- package/src/ui/render/highlight.ts +7 -3
- package/src/ui/render/markdown.ts +5 -1
- package/src/ui/render/sanitize.ts +29 -2
- package/src/ui/render/table.ts +8 -5
- package/src/ui/render/theme.ts +18 -4
- package/src/ui/render/width.ts +89 -10
- package/src/ui/runtime/motion.ts +16 -0
- package/src/ui/runtime/screen.ts +45 -0
- package/src/ui/runtime/spinner.ts +50 -4
- package/src/ui/runtime/statusline.ts +50 -1
- package/src/ui/screens/form.ts +42 -15
- package/src/ui/screens/model-manager.ts +26 -18
- package/src/ui/screens/picker.ts +47 -23
- package/src/ui/screens/provider-manager.ts +18 -12
- package/src/ui/screens/wizard.ts +24 -8
- package/src/ui/tui/app.ts +233 -27
- package/src/ui/tui/transcript.ts +269 -65
- package/vendor/minicore/LICENSE +21 -0
- package/vendor/minicore/VENDOR.md +6 -3
- package/vendor/minicore/package.json +6 -3
- package/vendor/minicore/src/core/loop.ts +12 -2
- package/vendor/minicore/src/core/snapshot.ts +4 -0
- 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.
|
package/docs/glossary.md
ADDED
|
@@ -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.
|
package/docs/mcp-lsp.md
ADDED
|
@@ -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`).
|