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,165 @@
|
|
|
1
|
+
# UI Render Pipeline — peta jalur provider stream → terminal
|
|
2
|
+
|
|
3
|
+
Dokumen ini hasil audit stabilitas UI/UX terminal 2026-09-18 (baseline v0.9.27).
|
|
4
|
+
Sumber kebenaran perilaku tetap `docs/TERMINAL_CONTRACT.md` (FROZEN); dokumen
|
|
5
|
+
ini memetakan IMPLEMENTASI aktual per tahap beserta kontrak event dan temuan
|
|
6
|
+
audit. Angka test di sini diukur di Windows + Bun 1.4.2, suite penuh hijau.
|
|
7
|
+
|
|
8
|
+
Konvensi: `file:line` menunjuk simbol yang dimaksud. Aturan repo tetap berlaku:
|
|
9
|
+
`cli/` boleh impor `src/ui/` dan `src/`; `src/` non-ui DILARANG impor
|
|
10
|
+
`src/ui/`; `src/ui/` DILARANG impor `cli/`, `src/` non-ui, `#minicore`
|
|
11
|
+
(dijaga `test/ui-boundary.test.ts`).
|
|
12
|
+
|
|
13
|
+
## 1. Jalur pipeline (9 tahap)
|
|
14
|
+
|
|
15
|
+
Tahap A — provider stream mentah: `src/providers/router.ts` (fallback +
|
|
16
|
+
`provider:text/extension/tool_call/finish`), `src/providers/guards.ts:32`
|
|
17
|
+
(timeout + text-cap + stream-guard tunggal), adapter `anthropic.ts`,
|
|
18
|
+
`responses.ts`, `effort.ts`. Dirakit di `src/app/provider-layer.ts`.
|
|
19
|
+
|
|
20
|
+
Tahap B — kernel emit ke `session.events`: `vendor/minicore/src/core/loop.ts`
|
|
21
|
+
(`turn:started`, `provider:text` per chunk, `provider:extension`
|
|
22
|
+
reasoning/usage/error, `context:compacted` reason `pressure:*`/`recovery`,
|
|
23
|
+
`step:started/completed`), `executor.ts` (`execution:started/completed`),
|
|
24
|
+
`session.ts` (`turn:completed` HANYA di jalur sukses).
|
|
25
|
+
|
|
26
|
+
Tahap C — tidak ada penerjemah `AgentEvent → UiEvent`: `src/ui/contract.ts:33`
|
|
27
|
+
`UiEvent` identik struktural dengan `AgentEvent` kernel; `cli/setup.ts`
|
|
28
|
+
menyerahkan `session.events` apa adanya ke `attachSimpleLogger` +
|
|
29
|
+
`attachTurnStatus` (dipasang segar per turn, dilepas di `finally` agar event
|
|
30
|
+
telat hening).
|
|
31
|
+
|
|
32
|
+
Tahap D — logger utama `src/ui/assistant/simple.ts:104`: append-only
|
|
33
|
+
scrollback, tanpa alternate screen. `provider:text` → `sanitizeAnsi` PER CHUNK
|
|
34
|
+
→ `streamBuffer` → `flushBuf` (line-buffered) → `flushLine` (fence-state +
|
|
35
|
+
`decorateMarkdown` + `formatWrapped`) → `stdout`. Jawaban bisa minimize
|
|
36
|
+
(buffer 1MB + marker, dibuka via `/expand`).
|
|
37
|
+
|
|
38
|
+
Tahap E — garis status transient `src/ui/assistant/turn-status.ts`: satu baris
|
|
39
|
+
`stderr`, hidup hanya di fase sunyi (latch `turnOn && !textOn`), hilang saat
|
|
40
|
+
teks mengalir, hidup lagi saat tool berikut. `endTurn()` deterministik dari
|
|
41
|
+
driver `finally` (kernel tak emit `completed` saat gagal/abort).
|
|
42
|
+
|
|
43
|
+
Tahap F — arbitrator `src/ui/runtime/statusline.ts`: satu pemilik transient
|
|
44
|
+
(`turn` vs `spinner`); tulis asing saat painter aktif dikomit
|
|
45
|
+
(clear → tulis → repaint) sehingga diagnostik tak hilang; overlap = signal,
|
|
46
|
+
bukan crash. `paintWrite` tak pernah melempar (fail-closed Bun Windows).
|
|
47
|
+
|
|
48
|
+
Tahap G — status bar `src/ui/footer.ts` dirender `src/ui/tui/app.ts` sebagai
|
|
49
|
+
baris dasar frame fullscreen. Footer/chrome lama (`src/ui/runtime/chrome.ts`,
|
|
50
|
+
DECSTBM scroll-region, `MINICODE_FOOTER`) DIHAPUS bersama lapisan TUI lama —
|
|
51
|
+
alternate screen menggantikannya; nol byte di non-TTY. Footer baca
|
|
52
|
+
`session.contextTokens` kernel (bukan spend kumulatif).
|
|
53
|
+
|
|
54
|
+
Tahap H — primitif render `src/ui/render/`: `sanitize.ts` (hanya SGR lolos),
|
|
55
|
+
`markdown.ts` + `highlight.ts` (fence-state per baris, konten utuh),
|
|
56
|
+
`width.ts` (kolom: CJK/emoji 2, potong aman-SGR), `wrap.ts` (lebar dibaca
|
|
57
|
+
per baris → aman resize), `theme.ts` (getter warna/glyph, jangan di-`const`),
|
|
58
|
+
`errors.ts` (pesan actionable + redact), `collapse.ts` (buffer `/expand`
|
|
59
|
+
200KB/entry, 500KB total), `diff.ts`/`table.ts`/`money.ts`/`format.ts`.
|
|
60
|
+
|
|
61
|
+
Tahap I — view murni vs controller: `src/ui/screens/` (props + callback,
|
|
62
|
+
tanpa IO) digerakkan `cli/` (`repl.ts`, `commands.ts`, `wizard.ts`,
|
|
63
|
+
`provider/model-manager.ts`, `approval/prompt.ts` via DI `ask`,
|
|
64
|
+
`setupWhenEmpty`, `setSubAgentSessionFactory`).
|
|
65
|
+
|
|
66
|
+
## 2. Kontrak Event → UI
|
|
67
|
+
|
|
68
|
+
Kolom: S = bisa di-stream, D = bisa duplikat, O = bisa out-of-order,
|
|
69
|
+
I = bisa diinterupsi, L = bisa tiba setelah completion.
|
|
70
|
+
|
|
71
|
+
| Event | Producer | Representasi UI | S | D | O | I | L |
|
|
72
|
+
|---|---|---|---|---|---|---|---|
|
|
73
|
+
| assistant text | provider stream | stdout wrap + fence 2-spasi | ya | tidak (E1) | tidak | ya (abort) | tidak (detach flush 1x, E6) |
|
|
74
|
+
| tool call | model → kernel | `› nama target` muted (compact: diam) | tidak | tidak | tidak | ya | tidak |
|
|
75
|
+
| tool result | tool → executor | ledger hijau/merah; minimize → `+ label` + buffer | tidak | tidak | tidak | ya | tidak |
|
|
76
|
+
| reasoning | provider extension | expanded: live per baris; minimized: `+ thinking` + buffer | ya | tidak | tidak | ya | tidak |
|
|
77
|
+
| thinking effort | picker `/model` | badge + level per model | tidak | tidak | tidak | tidak | tidak |
|
|
78
|
+
| usage | provider extension | verbose saja; masuk budget watcher | ya | tidak | ya (tail pasca-finish) | ya | ya (diabaikan aman) |
|
|
79
|
+
| compaction | kernel loop | `── compacted: <reason>` kuning, reason verbatim | tidak | tidak | tidak | tidak | tidak |
|
|
80
|
+
| permission request | executor → `ask` DI | header stdout + `askLine y/a/n`, fail-closed non-TTY | tidak | tidak | tidak | ya (deny) | tidak |
|
|
81
|
+
| permission denied | executor | error tool penuh, tak pernah minimize + reason | tidak | tidak | tidak | tidak | tidak |
|
|
82
|
+
| sub-agent | delegate_task → bus parent | ledger `›` biasa + usage; tanpa view khusus | tidak | tidak (jurnal skip forward) | tidak | ya | tidak |
|
|
83
|
+
| error provider | provider extension | `pendingError` consume-once → satu `✗` oleh driver | tidak | tidak (E15) | tidak | ya | tidak |
|
|
84
|
+
| warning | budget/recovery/verify | `[budget]`/`[recovery]`/`[verify]` kuning stderr | tidak | tidak (warned80 sekali) | tidak | tidak | tidak |
|
|
85
|
+
| completion | kernel loop | flush + `finalizeAnswer` + footer idle | tidak | tidak | tidak | tidak | tidak |
|
|
86
|
+
| abort | user/Ctrl+C/Esc | `(stopped)` + cleanup `finally` | tidak | tidak | tidak | — | tidak |
|
|
87
|
+
| timeout | kernel `createTimeout` | `✗ timeout` + turn dibuang transaksional | tidak | tidak | tidak | — | ya (late work ke turnStore privat, dibuang) |
|
|
88
|
+
| budget exceeded | watcher/driver | `[budget] … stopping turn` + abort ber-kind | tidak | tidak (fire-once) | tidak | — | tidak |
|
|
89
|
+
| provider failure | recovery policy | retry/compact/throw deterministik; cap retryAfter 30 dtk | tidak | tidak | tidak | tidak | tidak |
|
|
90
|
+
|
|
91
|
+
Mismatch yang dicari, hasil: tidak ada event runtime yang diabaikan UI secara
|
|
92
|
+
diam-diam (`bus-debug.ts` hanya subscribe 7 tipe untuk debug, bukan render).
|
|
93
|
+
Satu-satunya state turunan yang disengaja: footer memakai `contextTokens`
|
|
94
|
+
(estimasi jendela) sementara `/status` memisahkan Context/Input/Output/Total/
|
|
95
|
+
Cost/Budget — didokumentasikan di `docs/CONTROL-PLANE-MAP.md`, bukan mismatch.
|
|
96
|
+
|
|
97
|
+
## 3. State machine REPL (tidak eksplisit)
|
|
98
|
+
|
|
99
|
+
Tidak ada `enum` state; fase disimpulkan: `abort !== null` (busy),
|
|
100
|
+
`turnOn/textOn` (painter), `regionOn/detached` (chrome), plus ~14 flag
|
|
101
|
+
(`mode`, `escTimer`, `pending`, `nullStreak`, `warned80`, `activeSection`,
|
|
102
|
+
minimize toggles, buffer, `pendingError`, raw-mode listener). Invarian dijaga
|
|
103
|
+
`finally`/`detachUI`/`endTurn`, bukan type-state. Transisi ilegal yang
|
|
104
|
+
terbukti dicegah: painter saat teks mengalir, `endTurn` ganda, error ganda,
|
|
105
|
+
`+`/`-` di pipe, decoder bocor antar prompt, Tab membajak search.
|
|
106
|
+
Satu lubang nyata: listener approval `askLine` menempel DI ATAS `onBusyKey`
|
|
107
|
+
selama busy (byte Ctrl+C diterima keduanya) — aman fail-closed
|
|
108
|
+
(`raceAbort` → deny) tetapi observabilitas ganda. Lihat §5 temuan O1.
|
|
109
|
+
|
|
110
|
+
## 4. Temuan audit 2026-09-18 (eksperimen di /tmp, repo tak diubah)
|
|
111
|
+
|
|
112
|
+
F1 HIGH — SGR terbelah antar-chunk merusak output model. `sanitizeAnsi`
|
|
113
|
+
diterapkan PER CHUNK (`simple.ts:287`): `["\x1b[", "32mHello"]` tampil
|
|
114
|
+
literal `32mHello`. Bukti: harness E3 `out="32mHellom\n"`. Kelas sama untuk
|
|
115
|
+
OSC tak-terminasi (menelan sisa chunk). Perbaikan terkecil: tahan ekor
|
|
116
|
+
escape tak-lengkap di buffer dan sambung ke chunk berikut sebelum sanitasi.
|
|
117
|
+
|
|
118
|
+
F2 MEDIUM — SGR model bocor mentah ke stdout non-TTY. `"\x1b[31mRed\x1b[0m"`
|
|
119
|
+
satu chunk lolos `sanitizeAnsi` (by-design) lalu ditulis ke pipe apa adanya
|
|
120
|
+
(`out="\u001b[31mRed\u001b[0m\n"`), melanggar kontrak non-TTY deterministik.
|
|
121
|
+
Perbaikan terkecil: strip SGR (atau render via `c.*`) saat `!isTTY`.
|
|
122
|
+
|
|
123
|
+
F3 LOW — buffer thinking `/expand` membuang kepala diam-diam
|
|
124
|
+
(`thinkingBuf.slice(-200_000)` tanpa marker seperti `, capped 1MB` pada
|
|
125
|
+
answer). Informasi diagnostik hilang tanpa jejak.
|
|
126
|
+
|
|
127
|
+
O1 LOW — listener ganda approval vs busy-key (§3). Fail-closed, catat saja.
|
|
128
|
+
|
|
129
|
+
Status hardening (sesudah audit): F1 diperbaiki via `createStreamSanitizer`
|
|
130
|
+
+ `splitTrailingEscape` di `src/ui/render/sanitize.ts` (dipakai jalur teks
|
|
131
|
+
model/reasoning/bash di `simple.ts`, flush deterministik saat
|
|
132
|
+
completed/detach); F2 via kebijakan `stripSgr` non-TTY di `wOut`/`wErr` +
|
|
133
|
+
`rememberTurn` (cerminan `colorLevel` → `stdout.isTTY`); F3 via marker
|
|
134
|
+
`… (earlier thinking truncated)`; O1 didokumentasikan di `src/ui/tui/app.ts`
|
|
135
|
+
(busy-freeze + abort, tanpa refactor). Snap kiri/kanan: render pertama sesudah
|
|
136
|
+
geometri berubah
|
|
137
|
+
me-reset jangkar relatif askLine (`lastGeoCols/Rows` di `input.ts`) —
|
|
138
|
+
geometri lebar tak dilacak footer karena erase baris-absolut tak sound
|
|
139
|
+
pasca-reflow (terbukti model + ConPTY: reflow milik konsumen).
|
|
140
|
+
Dijaga `test/ansi-fragmentation.test.ts`
|
|
141
|
+
(termasuk properti semua-titik-belah ≡ whole-string),
|
|
142
|
+
`test/non-tty-output.test.ts`, `test/thinking-truncation.test.ts`,
|
|
143
|
+
`test/ui-combined.test.ts` (satu sistem: stream + tool + resize + footer),
|
|
144
|
+
`test/input-resize.test.ts` (gagal di kode lama: CUP ke anchor basi).
|
|
145
|
+
|
|
146
|
+
Batas yang TERVERIFIKASI BENAR (bukti harness + 178 test UI hijau):
|
|
147
|
+
token-by-token tepat-1x (E1), chunk 50KB utuh (E2), fence terbelah benar
|
|
148
|
+
termasuk yatim saat abort (E4/E4b), abort flush tepat-1x tanpa bocor ke turn
|
|
149
|
+
berikut (E6), urutan teks>tool>hasil (E7), permission fail-closed (E8),
|
|
150
|
+
kontrak budget murni vs gate (E9), tiga reason kompaksi tampil beda (E10),
|
|
151
|
+
forward sub-agent sebagai ledger biasa (E11), tool 5000-baris dipotong +
|
|
152
|
+
ANSI jahat dibuang (E12), decoder UTF-8 per-byte + ESC-split + paste 100KB
|
|
153
|
+
(E13), soak 50 turn tepat-1x 38ms +4.6MB tanpa ESC mentah (E14),
|
|
154
|
+
error consume-once + format actionable (E15), resize 120→20 mid-stream aman
|
|
155
|
+
(E5b), 10k events 151k ev/s tepat-1x (E17), CJK/emoji/wrap/truncate/fence
|
|
156
|
+
(E5), emphasis tak-seimbang lewat literal + tabel konten-tetap (fidelitas).
|
|
157
|
+
|
|
158
|
+
## 5. Residual risk (jujur, belum dibuktikan di audit ini)
|
|
159
|
+
|
|
160
|
+
Jalur TTY-live (painter denyut, footer sticky DECSTBM, overlay picker,
|
|
161
|
+
tombol busy) hanya tercakup harness fake-TTY + 178 test; tidak ada sesi TTY
|
|
162
|
+
nyata di audit ini. Chaos kombinasi (stream+resize+abort serentak di TTY)
|
|
163
|
+
dan soak 100+ turn multitool belum dijalankan. Sub-agent tanpa view khusus:
|
|
164
|
+
indukan dibedakan hanya dari nama tool (cukup untuk 1 level, belum diuji
|
|
165
|
+
visual untuk delegasi bertingkat — yang memang dilarang: tanpa nesting).
|
package/docs/USAGE.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Minicode User Guide
|
|
2
|
+
|
|
3
|
+
> **Status: arsip legacy.** Isi panduan monolit ini kini terpelihara di halaman docs terpisah (tabel di bawah). Jangan tambah konten baru di sini; perbaiki di halaman tujuannya.
|
|
4
|
+
>
|
|
5
|
+
> | Butuh… | Baca… |
|
|
6
|
+
> |---|---|
|
|
7
|
+
> | Mulai cepat | [Quickstart](quickstart.md), [Instalasi](getting-started.md) |
|
|
8
|
+
> | Flag & env | [CLI](cli.md), [Environment Variables](environment.md) |
|
|
9
|
+
> | Tool & MCP/LSP | [Tools](tools.md), [MCP & LSP](mcp-lsp.md) |
|
|
10
|
+
> | Memory, sesi, recovery | [Memory & Sessions](memory-sessions.md) |
|
|
11
|
+
> | Keamanan & policy | [Security Model](security-model.md), [Policy & Sandbox](policy-sandbox.md) |
|
package/docs/agents.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Sub-Agents & Tasks
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
## Konsep
|
|
5
|
+
|
|
6
|
+
Sub-agent = instans agent dengan **context terpisah** dari parent: memory, signal, dan budget sendiri. Pool concurrency 3 — maksimum 3 sub-agent hidup sekaligus — dan abort-aware (mewarisi AbortSignal parent; parent batal → anak berhenti).
|
|
7
|
+
|
|
8
|
+
Approval: `delegate_task` di-gate — TTY meminta persetujuan sekali per delegasi; non-TTY menolak. **Satu approval = delegasi ini saja**, tidak melebar ke delegasi lain.
|
|
9
|
+
|
|
10
|
+
## Mode anak: `explore` / `plan`
|
|
11
|
+
|
|
12
|
+
| Mode anak | Kemampuan |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `explore` | Subset read-only (12 tool) — cari/pahami kode, kembalikan temuan |
|
|
15
|
+
| `plan` | Read-only + `todo_read` (baca rencana parent), tetap tanpa mutasi dan tanpa `todo_write` |
|
|
16
|
+
|
|
17
|
+
Restriksi anak (selalu, tanpa kecuali): **tanpa** MCP, `git_commit`, memory-tulis, todo-tulis, job background, nesting (anak tidak bisa mendelegasi lagi). Plan-parent dipaksa explore saat mendelegasi.
|
|
18
|
+
|
|
19
|
+
## Kenapa dibatasi
|
|
20
|
+
|
|
21
|
+
Sub-agent menjalankan task tanpa Anda di depan layar. Kalau anak bisa commit atau memanggil MCP, satu prompt parent bisa menghasilkan efek yang tak Anda persetujui. Dengan membatasi anak ke read-only, efek samping tetap satu: eksekusi di parent — yang ledger-nya selalu Anda lihat.
|
|
22
|
+
|
|
23
|
+
## Recovery
|
|
24
|
+
|
|
25
|
+
Turn parent gagal **setelah** anak `committed`: jurnal menandai delegasi; saat resume model diberi warning `[recovery]` agar tidak mendelegasi ulang buta (efek anak sudah terjadi — yang benar adalah verifikasi hasilnya). Lihat [Keamanan](security.md) untuk jurnal recovery lengkap.
|
|
26
|
+
|
|
27
|
+
## Lanjut
|
|
28
|
+
|
|
29
|
+
- [Tools](tools.md) — semua tool yang boleh dipakai anak.
|
|
30
|
+
- [Policy & Sandbox](policy-sandbox.md) — mode permission parent vs anak.
|
|
31
|
+
- [Otomasi & CI](exec.md) — delegasi di non-TTY (ditolak, fail-closed).
|
package/docs/architecture.md
CHANGED
|
@@ -23,7 +23,7 @@ L3 vendor/minicore → kernel STATE/MODEL/ACTION/LOOP (freeze, zero-dep, via #m
|
|
|
23
23
|
|
|
24
24
|
## UI/UX terminal (kontrak FROZEN)
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Sesi interaktif (`minicode` di TTY mampu) SELALU membuka TUI **fullscreen alternate screen**: transkrip ala shell + status bar satu baris + popup komposit di atas transkrip yang tetap terlihat (redup). Jalur non-interaktif (one-shot prompt, `exec`, pipe/redirect/CI, `TERM=dumb`, layar < 10 baris) tetap shell-first: cetak polos append-only ke scrollback tanpa cursor control.
|
|
27
27
|
|
|
28
28
|
| Stream | Isi |
|
|
29
29
|
|---|---|
|
|
@@ -31,9 +31,9 @@ Minicode **shell-native CLI, bukan TUI**. Tanpa alternate screen/panel/header pe
|
|
|
31
31
|
| stderr | Progress/diagnostik: ledger tool (`› …` hijau/merah), reasoning (verbose), warning, error. Boleh transient bila TTY |
|
|
32
32
|
| Keduanya | Warna hanya bila TTY (`stdout.isTTY`); `NO_COLOR` menang; `TERM`/`COLORTERM` tidak menyalakan warna di pipe |
|
|
33
33
|
|
|
34
|
-
Satu-satunya arbitrator transient: `src/ui/runtime/statusline.ts` (`acquireTransientPaint` + `paintWrite`). Painter aktif (garis status turn vs spinner wizard) mutually exclusive; overlap = signal `[transient-paint]`, bukan crash. Foreign stderr writer (non-UI) boleh mentah — arbitrator mengkomitnya sebagai baris permanen bersih.
|
|
34
|
+
Satu-satunya arbitrator transient: `src/ui/runtime/statusline.ts` (`acquireTransientPaint` + `paintWrite`). Painter aktif (garis status turn vs spinner wizard) mutually exclusive; overlap = signal `[transient-paint]`, bukan crash. Foreign stderr writer (non-UI) boleh mentah — arbitrator mengkomitnya sebagai baris permanen bersih. `beginInteractiveScreen` menahan semua painter itu selama layar interaktif memegang terminal. 30 invariant (I1–I30) + peta test (`tui-app`, `screen-buffer`, `tui-popup`, `transient-arbitration`, `input-resize`, `exit-codes`, `acp`, `ui-boundary`) ada di `TERMINAL_CONTRACT.md`.
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
Enam primitif tampilan (semuanya di dalam TUI fullscreen saat interaktif): transkrip `minicode ›` + jawaban model + ledger ` › name target` hijau / ` › name: …` merah; status bar satu baris `✦ mode • model • cwd … ctx` (spark pulse saat busy, redup saat idle, konteks rata kanan; `src/ui/tui/app.ts` render per frame); popup komposit satu kotak (`/model`, `/provider`, `/sessions`, form, approval) via `openAltScreen`/`paintRegion`; thinking redup + penanda `… thinking` (isi via `/expand`); error `✗ pesan actionable` sekali per kegagalan (`takePendingError`). `✓`/`✗` tetap untuk status/konfirmasi perintah (sync, auth, config, spinner).
|
|
37
37
|
|
|
38
38
|
## Modul kunci
|
|
39
39
|
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Memilih Mode
|
|
2
|
+
|
|
3
|
+
Satu pertanyaan, satu jawaban: **mode mana untuk tujuan saya?**
|
|
4
|
+
|
|
5
|
+
## Kalau tujuan Anda X → gunakan Y
|
|
6
|
+
|
|
7
|
+
| Saya ingin… | Gunakan | Karena |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
|Memahami repo tanpa mengubah apa pun | `readonly` (atau `--tool-scope explore`) | Hanya 18 tool baca yang lolos; tulis/bash/commit/deligasi ditolak di gerbang |
|
|
10
|
+
| Minta agen membuat perubahan | `auto` (default) | Tulis terjail + bash aman langsung jalan; yang berisiko (commit, MCP, delegasi) tetap minta izin sekali |
|
|
11
|
+
| Menyetujui setiap perubahan | `ask` | Tiap tool non-sepele menunggu jawaban; `todo`/`bash_output` tak ditanya (bookkeeping sendiri) |
|
|
12
|
+
| Menyusun rencana tanpa eksekusi | `plan` | Baca + tulis rencana (`todo_write`) + delegasi yang dipaksa read-only; tanpa mutasi file/git/memori |
|
|
13
|
+
| Otomasi/CI tanpa manusia | One-shot/`exec` + mode default | `ask_user`/gated otomatis ditolak di non-TTY (fail-closed, bukan gantung); hindari prompt yang butuh klarifikasi |
|
|
14
|
+
| Otonom penuh di mesin sendiri | `allow-all` + `--sandbox docker` (atau OS) + `--budget` | Tanpa prompt, TETAPI jail path + bash-guard tetap aktif; sandbox memberi isolasi nyata |
|
|
15
|
+
|
|
16
|
+
## Rule of thumb
|
|
17
|
+
|
|
18
|
+
1. **Default `auto` sudah benar untuk kerja harian.** Pindah mode hanya bila tujuan berubah, bukan karena takut umum.
|
|
19
|
+
2. **`readonly` untuk baca, `plan` untuk berpikir.** Bedanya: `plan` boleh menulis rencana dan mendelegasikan penelahan; keduanya tak menyentuh file/git/memori Anda.
|
|
20
|
+
3. **`ask` untuk wilayah asing** — repo orang, perintah yang belum Anda pahami. Jawab `always` hanya untuk pasangan tool+args spesifik yang sudah Anda nilai.
|
|
21
|
+
4. **CI = non-interaktif = tanpa approval.** Jangan desain pipeline yang bergantung pada `ask_user` atau commit oleh agent; commit tetap keputusan manusia/Workflow.
|
|
22
|
+
5. **`allow-all` mematikan prompt, bukan batas.** Path jail dan pola bash berbahaya tetap menolak. Pasangkan dengan sandbox + budget bila otonom.
|
|
23
|
+
|
|
24
|
+
## Tradeoff yang jujur
|
|
25
|
+
|
|
26
|
+
- Semakin otonom → semakin cepat, semakin besar blast radius bila model salah paham. Tidak ada mode yang membuat model lebih bijak — mode hanya mengatur **apa yang boleh terjadi**.
|
|
27
|
+
- `allowlist` (otomatis saat tanpa sandbox OS) paling ketat untuk shell, tetapi model tetap bisa menulis file via tool terjail — pahami beda sumbunya: allowlist membatasi *perintah*, jail membatasi *file*.
|
|
28
|
+
- Ganti mode kapan pun: flag saat start, `/mode` atau Shift+Tab saat REPL berjalan.
|
|
29
|
+
|
|
30
|
+
## Lanjut
|
|
31
|
+
|
|
32
|
+
- [Security Model](security-model.md) — apa yang ditegakkan tiap mode.
|
|
33
|
+
- [Policy & Sandbox](policy-sandbox.md) — tabel semantik presisi + bukti guard.
|
|
34
|
+
- [Otomasi & CI](exec.md) — batasan headless.
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# CLI — Mode & Flags
|
|
2
|
+
|
|
3
|
+
Semua cara menjalankan Minicode: interaktif, sekali jalan, pipe, dan otomasi CI — plus flags dan environment.
|
|
4
|
+
|
|
5
|
+
## Mode
|
|
6
|
+
|
|
7
|
+
| Perintah | Fungsi |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `minicode` | Mode interaktif (REPL) + wizard bila belum ada provider |
|
|
10
|
+
| `minicode "prompt"` | Sekali jalan (headless) |
|
|
11
|
+
| `echo "prompt" \| minicode` | Via pipe |
|
|
12
|
+
| `minicode exec "prompt" [--json]` | Headless CI — event JSONL + baris `{"type":"summary"}` di stdout |
|
|
13
|
+
| `minicode acp` | Server JSON-RPC stdio untuk IDE (subset minimal: initialize/run/cancel/shutdown) |
|
|
14
|
+
| `minicode --interactive` | Paksa REPL |
|
|
15
|
+
| `minicode --provider <id> "prompt"` | Paksa provider agnostik tanpa ubah config (atau `provider::model`) |
|
|
16
|
+
| `minicode config add --baseUrl <url> --apiKey <key>` | Tambah provider LLM |
|
|
17
|
+
| `minicode config mcp add <id> --command <cmd> --args "<a1,a2>"` | Daftarkan MCP server stdio |
|
|
18
|
+
| `minicode config mcp add <id> --url <https://…>` | Daftarkan MCP server HTTP |
|
|
19
|
+
| `minicode config lsp add <ext> --command <cmd> --args "<a1,a2>"` | Daftarkan LSP server |
|
|
20
|
+
| `minicode auth login [provider]` | Login OAuth device-code |
|
|
21
|
+
| `minicode auth status\|logout\|list` | Kelola kredensial OAuth |
|
|
22
|
+
| `minicode pricing status\|sync\|show <model>\|clear` | Tabel harga estimasi biaya |
|
|
23
|
+
| `minicode skills list` | Daftar skill terpasang |
|
|
24
|
+
| `minicode sessions list` | Riwayat sesi |
|
|
25
|
+
| `minicode memory status [--json]` | Statistik vector RAG (rows, size, hit-rate) |
|
|
26
|
+
| `minicode doctor [--json]` | Diagnosis lokal |
|
|
27
|
+
| `minicode mcp serve` | Ekspos minicode sebagai MCP server |
|
|
28
|
+
|
|
29
|
+
Subcommand di-route di `cli/router.ts` (`stats`, `sessions`, `mcp`, `config`, `skills`, `providers`, `auth`, `pricing`, `exec`, `memory`, `doctor`, `acp`).
|
|
30
|
+
|
|
31
|
+
## Flags
|
|
32
|
+
|
|
33
|
+
| Flag | Deskripsi |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `--verbose` | Tampilkan reasoning & usage |
|
|
36
|
+
| `--verify` | Auto-verify + self-heal (detect: typecheck → test → tsconfig) |
|
|
37
|
+
| `--sandbox docker` | Bash di container ephemeral (`--network none`) |
|
|
38
|
+
| `--sandbox none` | Matikan sandbox otomatis (opt-out sadar) |
|
|
39
|
+
| `--sandbox os` | Paksa OS-native (bwrap/seatbelt). Sudah otomatis bila tersedia |
|
|
40
|
+
| `--ratelimit <rpm>` | Batas request LLM per menit |
|
|
41
|
+
| `--budget <usd>` | Batas biaya sesi; warn 80%, exit/break bila lewat; cost tak dikenal + pemakaian = over (fail-closed default) |
|
|
42
|
+
| `--budget-strict` | Penegasan eksplisit fail-closed di atas (back-compat) |
|
|
43
|
+
| `--tool-scope <s>` | `full` (default) \| `explore` = subset read-only 12 tool |
|
|
44
|
+
| `--plan` | Read-only plan mode |
|
|
45
|
+
| `--allowlist` | Bash hanya perintah aman |
|
|
46
|
+
| `--ask` | Tanya persetujuan setiap tool |
|
|
47
|
+
| `--allow-all` | Nonaktifkan semua sandbox (path jail tetap aktif) |
|
|
48
|
+
| `--model <name>` | Override model (`providerId::model` paksa provider) |
|
|
49
|
+
| `--provider <id>` | Paksa provider id agnostik |
|
|
50
|
+
| `--resume <id>` | Lanjutkan sesi (full history, bukan dump teks) |
|
|
51
|
+
| `--timeout <ms>` | Hard deadline per run (default 900000; 0 = Infinity) |
|
|
52
|
+
| `--cwd <path>` | Workspace root untuk tool file & jail |
|
|
53
|
+
| `--allow-local-config` | Percayai `.minicode/config.json` + allowlist lokal (default: diabaikan) |
|
|
54
|
+
| `--max-steps <n>` | Batas langkah tool (default 50) |
|
|
55
|
+
| `--context-window <n>` | Ukuran jendela konteks (token) |
|
|
56
|
+
| `--session <id>` | ID sesi (default random, disanitasi) |
|
|
57
|
+
|
|
58
|
+
Di REPL, **Shift+Tab** memutar permission (`auto` → `ask` → `plan` → `allowlist`) dan benar-benar mengubah keputusan, bukan label. Di baris kosong, **Tab** juga memutar mode (`auto` → `ask` → `plan` → `allowlist`).
|
|
59
|
+
|
|
60
|
+
## Kapan memakai apa
|
|
61
|
+
|
|
62
|
+
| Tujuan | Pakai |
|
|
63
|
+
|---|---|
|
|
64
|
+
| Kerja harian biasa | Default (`auto`) — tulis aman langsung jalan, yang berisiko minta izin |
|
|
65
|
+
| Repo asing / perintah belum dipahami | `--ask`, jawab `always` hanya untuk pasangan tool+args yang sudah dinilai |
|
|
66
|
+
| Review tanpa eksekusi | `--plan` (+ `--tool-scope explore` bila ingin subset baca 12 tool) |
|
|
67
|
+
| CI tanpa manusia | `exec --json` + `--budget`/`--max-steps`; hindari prompt yang butuh klarifikasi |
|
|
68
|
+
| Otonom penuh di mesin sendiri | `--allow-all` + `--sandbox docker` (atau OS) + `--budget` |
|
|
69
|
+
| Model mahal tak terkendali | `--budget 0.50` + `--budget-strict` + `pricing sync` |
|
|
70
|
+
|
|
71
|
+
Detail alasan tiap mode di [Memilih Mode](choosing-mode.md).
|
|
72
|
+
|
|
73
|
+
## Environment variables (ringkas)
|
|
74
|
+
|
|
75
|
+
Kepala tabel penuh ada di [Environment Variables](environment.md); yang paling sering dipakai:
|
|
76
|
+
|
|
77
|
+
| Variabel | Fungsi |
|
|
78
|
+
|---|---|
|
|
79
|
+
| `MINICODE_VERIFY_CMD` | Custom verify command |
|
|
80
|
+
| `MINICODE_SANDBOX` | `docker` \| `os` \| `none` |
|
|
81
|
+
| `MINICODE_SANDBOX_STRICT=1` | Tak pernah fallback host (default request eksplisit sudah fail-closed) |
|
|
82
|
+
| `MINICODE_SANDBOX_ALLOW_FALLBACK=1` | Izinkan fallback host secara eksplisit bila backend tak tersedia |
|
|
83
|
+
| `MINICODE_BUDGET_STRICT=1` | Sama dengan `--budget-strict` |
|
|
84
|
+
| `MINICODE_ALLOW_LOCAL_CONFIG=1` | Sama dengan `--allow-local-config` |
|
|
85
|
+
| `MINICODE_TOOL_SCOPE=explore` | Subset read-only |
|
|
86
|
+
| `MINICODE_GREP_ENGINE=js` | Paksa walker internal |
|
|
87
|
+
| `MINICODE_MEMORY_SCOPE` | `cwd` \| `global` \| `all` |
|
|
88
|
+
| `MINICODE_AUTO_MEMORY=0` | Matikan auto-simpan summary/snippet |
|
|
89
|
+
| `MINICODE_TELEMETRY=0` | Matikan `traces.jsonl` |
|
|
90
|
+
| `MINICODE_HOME` | Override home untuk DB lokal/global |
|
|
91
|
+
| `TAVILY_API_KEY` | Tavily web_search (fallback DDG bila kosong) |
|
|
92
|
+
| `NO_COLOR` | Matikan warna (menang atas TTY) |
|
|
93
|
+
| `MINICODE_ASCII=1` | Glyph ASCII untuk konsol tanpa UTF-8 |
|
|
94
|
+
| `MINICODE_STATUSLINE=rich` | Spinner tampilkan token + biaya sesi |
|
|
95
|
+
|
|
96
|
+
## Config `.minicode/config.json`
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"providers": [{ "id": "my-provider", "baseUrl": "...", "apiKey": "...", "models": ["gpt-4o"] }],
|
|
101
|
+
"mcpServers": [
|
|
102
|
+
{ "id": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] },
|
|
103
|
+
{ "id": "remote", "url": "https://mcp.example.com/mcp", "headers": { "authorization": "Bearer xxx" } }
|
|
104
|
+
],
|
|
105
|
+
"lspServers": [{ "ext": ".ts", "command": "typescript-language-server", "args": ["--stdio"] }],
|
|
106
|
+
"verifyCommand": "bun run typecheck",
|
|
107
|
+
"bashAllowlist": ["git status*", "bun test*", "npm run build*"]
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Global (`~/.minicode/config.json`) selalu dibaca. Lokal (`.minicode/config.json`)
|
|
112
|
+
adalah input repo tak terpercaya dan DIABAIKAN kecuali operator opt-in per
|
|
113
|
+
invokasi (`--allow-local-config` / `MINICODE_ALLOW_LOCAL_CONFIG=1`) — tanpa
|
|
114
|
+
itu MCP server lokal tidak di-spawn, endpoint provider lokal tidak dipakai,
|
|
115
|
+
`verifyCommand`/`bashAllowlist` lokal tidak berlaku. Tulis eksplisit
|
|
116
|
+
(`config add --local`) tak terpengaruh.
|
|
117
|
+
|
|
118
|
+
## Anti-injeksi flag
|
|
119
|
+
|
|
120
|
+
`cli/args.ts:53` berhenti di prompt word pertama: prompt `"review --allow-all"` tidak mengaktifkan flag. `--cwd`/value-flag setelah nama subcommand diparse per-subcommand agar tidak menembus boundary prompt.
|
|
121
|
+
|
|
122
|
+
## Exit codes
|
|
123
|
+
|
|
124
|
+
| Kode | Arti |
|
|
125
|
+
|---|---|
|
|
126
|
+
| `0` | Sukses, atau help yang memang diminta |
|
|
127
|
+
| `1` | Gagal runtime: provider error, budget lewat, turn gagal, setup gagal |
|
|
128
|
+
| `2` | Salah pakai: argumen hilang/malformed, subcommand asing |
|
|
129
|
+
|
|
130
|
+
Lookup yang gagal (provider/skill/sesi tak dikenal) = `1`: itu kegagalan operasi, bukan pemakaian. Skrip cukup cek `!= 0` untuk gagal; cek `== 2` untuk spesifik salah pakai.
|
package/docs/concepts.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Konsep & Desain
|
|
2
|
+
|
|
3
|
+
Minicode itu apa, kenapa dibangun begitu, dan kenapa beberapa hal sengaja tidak ada. Halaman ini latar belakangnya; langkah praktis ada di [Instalasi](getting-started.md).
|
|
4
|
+
|
|
5
|
+
## Dua benda, dua peran
|
|
6
|
+
|
|
7
|
+
| Nama | Apa |
|
|
8
|
+
|---|---|
|
|
9
|
+
| **MiniCore** | Kernel runtime `STATE / MODEL / ACTION / LOOP`. Inti di-freeze, zero-dependency, di-vendor ke `vendor/minicore` (19 file, ~72 KB). Bukan dependency — di-resolve lewat subpath imports `#minicore` |
|
|
10
|
+
| **Minicode** | Layer agencode di atasnya: tools, sub-agents, skills, hooks, policy/sandbox, providers, MCP/LSP, memory, sessions, repo-map, verifier, CLI shell-first |
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
## Loop ReAct
|
|
14
|
+
|
|
15
|
+
Setiap prompt berjalan sebagai loop `Thought → Action → Observation` sampai jawaban final, batas `--max-steps` (default 50), atau `--timeout` (default 15 menit). Model menerima system prompt berisi `# Environment` (cwd + platform), repo-map ringkas, dan memory yang relevan — lalu memilih tool, melihat hasilnya, dan memilih langkah berikutnya. Tidak ada grafik alur tersembunyi: apa pun yang agent lakukan tampil sebagai ledger di layar.
|
|
16
|
+
|
|
17
|
+
## Shell-first: non-interaktif polos, interaktif fullscreen
|
|
18
|
+
|
|
19
|
+
Minicode sengaja **tanpa framework TUI** (tanpa Ink/React, tanpa panel
|
|
20
|
+
permanen) dan membagi dua jalur secara tegas:
|
|
21
|
+
|
|
22
|
+
- **Non-interaktif** (one-shot prompt, `exec`, pipe/redirect/CI, `TERM=dumb`):
|
|
23
|
+
output mengalir **append-only ke scrollback** — hasil agen adalah artefak
|
|
24
|
+
terminal biasa yang bisa di-pipe, di-grep, dan tersimpan di scrollback Anda
|
|
25
|
+
sendiri.
|
|
26
|
+
- **Interaktif** (TTY mampu): satu tampilan **TUI fullscreen** alternate-screen
|
|
27
|
+
— transkrip ala shell + status bar satu baris + popup komposit; keluar =
|
|
28
|
+
buffer utama kembali persis (transkrip tidak di-dump ke scrollback).
|
|
29
|
+
- Warna hanya saat TTY; `NO_COLOR` selalu menang; output program tetap bersih dari cursor-control saat di-pipe.
|
|
30
|
+
|
|
31
|
+
Detail lengkap + kontrak FROZEN-nya di [Kontrak Terminal](terminal.md).
|
|
32
|
+
|
|
33
|
+
## Kejujuran sebagai fitur
|
|
34
|
+
|
|
35
|
+
Beberapa keputusan desain lahir dari tidak mau berpura-pura:
|
|
36
|
+
|
|
37
|
+
- **Angka tidak ditulis permanen** di dokumentasi — jalankan `bun test` / `bun run gate:coverage` / lihat CI. Halaman yang mengklaim jumlah test akan usang begitu dipush.
|
|
38
|
+
- **Kegagalan dilaporkan apa adanya**: `auth login` menampilkan error server tanpa dipercantik; `--sync` jujur `{updated, failed}`; sandbox yang tidak tersedia **tidak** dilabeli aman — default turun ke `allowlist` dengan alasan dicetak sekali.
|
|
39
|
+
- **Ukur, bukan klaim**: bash-guard divalidasi korpus serangan + fuzz ber-seed (jalankan `bun run gate:bash` / `bun run extreme:fuzz`). Lihat [Keamanan](security.md).
|
|
40
|
+
- **Skor benchmark dilaporkan apa adanya** beserta batas validitasnya (lingkungan, ukuran sampel). Lihat [Verify & Benchmark](verify-benchmark.md).
|
|
41
|
+
|
|
42
|
+
## Zero-dep runtime
|
|
43
|
+
|
|
44
|
+
Runtime tanpa dependency pihak ketiga; satu-satunya kebutuhan keras adalah **Bun** (`bun:sqlite` dipakai langsung — tidak jalan di Node.js). Parser markdown web, renderer tabel/diff, dan highlight juga mini buatan sendiri, bukan library. Manfaatnya: audit permukaan lebih kecil, install cepat, dan supply-chain yang bisa dibaca sambil duduk.
|
|
45
|
+
|
|
46
|
+
## Bahasa
|
|
47
|
+
|
|
48
|
+
Dokumentasi dan komentar kode berbahasa **Indonesia** dengan istilah teknis tetap English (`provider`, `checkpoint`, `sandbox`, `jail`). Lihat [Glosarium](glossary.md) untuk daftar istilah.
|
|
49
|
+
|
|
50
|
+
## Lanjut
|
|
51
|
+
|
|
52
|
+
- [Arsitektur](architecture.md) — tiga lapisan, boundary, alur satu prompt.
|
|
53
|
+
- [Quickstart](quickstart.md) — dari nol ke prompt pertama yang ter-verify.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Config & Provider
|
|
2
|
+
|
|
3
|
+
## 14 preset gateway
|
|
4
|
+
|
|
5
|
+
`Gateway >` hanya menampilkan `[0] Label` tanpa URL (minimalis, tanpa bocor endpoint).
|
|
6
|
+
|
|
7
|
+
| id | Label | Catatan |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `openai` | OpenAI | gpt, o-series |
|
|
10
|
+
| `anthropic` | Anthropic | Claude, streaming `tool_use` |
|
|
11
|
+
| `openrouter` | OpenRouter | Gateway 75+ model |
|
|
12
|
+
| `deepseek` | DeepSeek | chat/reasoner |
|
|
13
|
+
| `opencode-zen` | OpenCode Zen | Gateway |
|
|
14
|
+
| `google` | Google Gemini | Konteks 1M, `thought_signature` pass-through |
|
|
15
|
+
| `ollama` | Ollama | Lokal, gratis, tanpa key |
|
|
16
|
+
| `qwen` | Qwen | Alibaba Qwen3-Coder (satu-satunya dengan spec OAuth terdaftar) |
|
|
17
|
+
| `groq` | Groq | Inferensi cepat |
|
|
18
|
+
| `together` | Together AI | Model terbuka |
|
|
19
|
+
| `fireworks` | Fireworks AI | — |
|
|
20
|
+
| `mistral` | Mistral AI | — |
|
|
21
|
+
| `cohere` | Cohere | — |
|
|
22
|
+
| `generic` | OpenAI-compatible umum | vLLM / LM Studio |
|
|
23
|
+
| `custom` | Custom URL | Pseudo-preset untuk baseUrl sendiri |
|
|
24
|
+
|
|
25
|
+
Alur: wizard & `/provider` (add `[0] OpenAI` … `[14] Custom URL`) → API key ter-masking → auto-detect models via `GET /models` timeout 4 dtk → provider otomatis pindah saat pilih model beda provider (tanpa restart, via `reloadProviders()` setelah `Gateway >2`).
|
|
26
|
+
|
|
27
|
+
## Dua jalur autentikasi
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
# 1. API key
|
|
31
|
+
minicode config add --baseUrl https://api.openai.com/v1 --apiKey sk-…
|
|
32
|
+
|
|
33
|
+
# 2. OAuth device-code (tanpa API key, tanpa kartu kredit) — RFC 8628
|
|
34
|
+
minicode auth list # provider yang mendukung
|
|
35
|
+
minicode auth login qwen # kode singkat → buka URL → tunggu persetujuan
|
|
36
|
+
minicode auth status # kredensial + kapan kedaluwarsa
|
|
37
|
+
minicode auth logout qwen
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Token di `~/.minicode/auth.json` (chmod 600), bukan `config.json`. Refresh otomatis margin 60 dtk. Provider OAuth yang belum login dibuang dari daftar dengan peringatan, bukan dikirim dengan header kosong.
|
|
41
|
+
|
|
42
|
+
> Kejujuran: device flow teruji lengkap ke server OAuth lokal (18 test: pending/slow_down/denied/expired/clamp), tapi endpoint/clientId provider belum semua terkonfirmasi live. `auth login chatgpt` fail-fast di non-TTY. Jangan baca token aplikasi desktop orang lain — itu pencurian kredensial.
|
|
43
|
+
|
|
44
|
+
## Keyring OS (ganti plaintext config)
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
minicode config set-key openrouter # pindah API key ke OS store, config tinggal referensi
|
|
48
|
+
minicode config delete-key openrouter # lupakan (provider nonaktif sampai di-set ulang)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Windows memakai DPAPI user-scope (hanya user ini yang bisa membuka); selain itu berkas chmod 600 dengan label jujur `plain-file` (bukan keyring). Referensi hilang/rusak = provider di-skip dengan peringatan (fail-closed, seperti OAuth). Matikan paksa via `MINICODE_KEYSTORE_DISABLE=1`.
|
|
52
|
+
|
|
53
|
+
## Model & thinking effort
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
/model [cari] → picker provider::model, bisa difilter
|
|
57
|
+
Enter → pilih model (+ picker effort bila modelnya mendukung)
|
|
58
|
+
Esc → batal total
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Effort tersimpan di `ProviderEntry.reasoningEffort`, berlaku sesi berikutnya, tampil badge `[low|medium|high]`. **Default universal = omit** (tanpa param thinking): default bawaan tiap model sudah di-tune vendornya. Knob hanya dikirim ke keluarga terbukti, dalam bahasa native-nya: OpenAI reasoning (`o*`, `gpt-5/6` → `reasoning_effort`, level tervalidasi per model — pro = high saja); Claude ≤4.5 → budget `1024/2048/4096`; Claude ≥4.6/5 → adaptive + `output_config.effort`. **Selain itu tak pernah dikirimi param thinking** (DeepSeek, Gemini, Groq, Ollama, free-tier, custom). Bila model menolak param (400/500), request diulang sekali tanpa param + diingat per sesi + dicatat `[thinking]` di stderr. Picker effort hanya muncul untuk model yang mendukung; sisanya select langsung tanpa menyentuh effort tersimpan. `detectAndSave`/`auth login` mempertahankan effort (tidak reset diam-diam). Mutasi ditulis ke file scope asal (bukan hasil merge) agar tidak duplikat/shadowing.
|
|
62
|
+
|
|
63
|
+
Model override sekali jalan:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
minicode --model providerId::modelName "prompt"
|
|
67
|
+
minicode --provider openai "prompt"
|
|
68
|
+
minicode models --match gemini
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`MINICODE_PROVIDER_ORDER=openai,anthropic,deepseek` mengurutkan provider agnostik tanpa edit config.
|
|
72
|
+
|
|
73
|
+
## Pin eksplisit `provider::model` (kontrak)
|
|
74
|
+
|
|
75
|
+
Model berformat `providerId::modelName` = PIN: request hanya ke provider
|
|
76
|
+
itu — **tanpa fallback lintas provider dan tanpa substitusi diam-diam**.
|
|
77
|
+
Gagal = error jujur dari provider yang dipilih (limit/saldo/error server),
|
|
78
|
+
user memilih model lanjutannya sendiri via `/model`. Alasan: fallback
|
|
79
|
+
otomatis pernah melempar user dari model gratis ke model berbayar provider
|
|
80
|
+
lain (tagihan tak terduga). Model bare (tanpa `::`) tetap perilaku lama
|
|
81
|
+
(first-match + substitusi + fallback rate_limit/server/network).
|
|
82
|
+
|
|
83
|
+
## Build & router
|
|
84
|
+
|
|
85
|
+
Build provider terpusat di `src/providers/build.ts`. Router fallback untuk rate_limit/server/network (clone-error + base64 fix + retryAfter cap). Deteksi wire dari probe path `/responses` → hint `responses`; substring host hanya fallback. `max_tokens` 8192; stop `length` = peringatan eksplisit, bukan teks sunyi.
|
|
86
|
+
|
|
87
|
+
Responses API: `/v1/responses`, `previous_response_id` chaining per model, `store:false` default.
|
package/docs/config.md
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Config — File & Lokasi Data
|
|
2
|
+
|
|
3
|
+
Di mana pengaturan dan data Minicode tinggal, dan bagaimana file lokal yang tak tepercaya diperlakukan.
|
|
4
|
+
|
|
5
|
+
## Skema `.minicode/config.json`
|
|
6
|
+
|
|
7
|
+
```json
|
|
8
|
+
{
|
|
9
|
+
"providers": [{ "id": "my-provider", "baseUrl": "...", "apiKey": "...", "models": ["gpt-4o"] }],
|
|
10
|
+
"mcpServers": [
|
|
11
|
+
{ "id": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] },
|
|
12
|
+
{ "id": "remote", "url": "https://mcp.example.com/mcp", "headers": { "authorization": "Bearer xxx" } }
|
|
13
|
+
],
|
|
14
|
+
"lspServers": [{ "ext": ".ts", "command": "typescript-language-server", "args": ["--stdio"] }],
|
|
15
|
+
"verifyCommand": "bun run typecheck",
|
|
16
|
+
"bashAllowlist": ["git status*", "bun test*", "npm run build*"]
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- `providers` — bisa juga diisi lewat wizard/`minicode config add`/`/provider` (14 preset, lihat [Config & Provider](config-providers.md)).
|
|
21
|
+
- `mcpServers` — dua bentuk: stdio (`command`+`args`) dan HTTP (`url`+opsional `headers`). Detail transport di [MCP & LSP](mcp-lsp.md).
|
|
22
|
+
- `verifyCommand` — dipakai `--verify` bila auto-detect tidak menemukan (urutan deteksi: `typecheck` → `test` → `tsconfig`).
|
|
23
|
+
- `bashAllowlist` — pola koma/pola glob perintah bash yang dianggap aman (mode `allowlist`).
|
|
24
|
+
|
|
25
|
+
## Global vs lokal
|
|
26
|
+
|
|
27
|
+
| File | Lokasi | Catatan |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| Global | `~/.minicode/config.json` | Berlaku semua workspace |
|
|
30
|
+
| Lokal | `.minicode/config.json` | Per repo; **diabaikan secara default** — aktif dengan `--allow-local-config` / `MINICODE_ALLOW_LOCAL_CONFIG=1` |
|
|
31
|
+
|
|
32
|
+
Merge dengan **prioritas lokal menang**. Mutasi (add/update provider, MCP, LSP) ditulis ke file scope asal — bukan hasil merge — agar tidak duplikat/shadowing. Semua tulis file config atomik (tmp+rename randomUUID) + chmod 600.
|
|
33
|
+
|
|
34
|
+
**Kenapa lokal default-diabaikan:** `.minicode/config.json` sering ikut ter-commit; repo yang Anda clone bisa mendaftarkan MCP server atau menyedot prompt lewat config. Percayai hanya di workspace milik Anda.
|
|
35
|
+
|
|
36
|
+
## Token OAuth bukan di config
|
|
37
|
+
|
|
38
|
+
Kredensial OAuth di `~/.minicode/auth.json` (chmod 600) — terpisah dari config karena config lokal rawan ikut ter-commit sedangkan token rahasia berumur pendek. Provider OAuth menyimpan `apiKey: ""` di config dan mengambil token saat runtime. Detail di [Config & Provider](config-providers.md).
|
|
39
|
+
|
|
40
|
+
## Lokasi data
|
|
41
|
+
|
|
42
|
+
| Path | Isi |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `~/.minicode/config.json` | Config global |
|
|
45
|
+
| `~/.minicode/auth.json` | Token OAuth (chmod 600) |
|
|
46
|
+
| `.minicode/config.json` | Config lokal (default diabaikan) |
|
|
47
|
+
| `.minicode/sessions.db` | Sessions SQLite (WAL, capped + busy-retry) |
|
|
48
|
+
| `vector.db` | Index memory vector hybrid |
|
|
49
|
+
| `.minicode/repomap.json` | Cache repo-map (sig mtime) |
|
|
50
|
+
| `.minicode/traces.jsonl` | Telemetry per run (prompt di-scrub) |
|
|
51
|
+
| `.minicode/step-traces.jsonl` | Trace keputusan tool (sumber `minicode stats`) |
|
|
52
|
+
| `.minicode/checkpoints/` | Manifest checkpoint (cap 20 terbaru) |
|
|
53
|
+
| `.minicode/todos/<id>.json` + `.minicode/plans/<id>.md` | Rencana per sesi |
|
|
54
|
+
| `.minicode/.trash/` | Soft-delete `delete_file` (cap 100, gitignored) |
|
|
55
|
+
| `.minicode/MEMORY.md` + hierarki | File memory (global → lokal → root) |
|
|
56
|
+
|
|
57
|
+
Override home untuk semua DB lokal/global: `MINICODE_HOME` (terutama agar test hermetic di POSIX, di mana `homedir()` mengabaikan `$HOME`).
|
|
58
|
+
|
|
59
|
+
## Lanjut
|
|
60
|
+
|
|
61
|
+
- [Environment Variables](environment.md) — semua `MINICODE_*`.
|
|
62
|
+
- [Memory & Sessions](memory-sessions.md) — isi `vector.db`, sesi, checkpoint.
|
|
63
|
+
- [Policy & Sandbox](policy-sandbox.md) — kenapa tulis config selalu atomik + chmod 600.
|