minicode-ai 0.11.0 → 0.13.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/CHANGELOG.md +98 -0
- package/LICENSE +21 -21
- package/README.md +4 -4
- package/cli/args.ts +46 -0
- package/cli/commands/acp.ts +163 -10
- package/cli/commands/config.ts +33 -18
- package/cli/commands/daemon.ts +515 -0
- package/cli/commands/exec.ts +145 -53
- package/cli/commands/openwork.ts +986 -0
- package/cli/commands/sessions.ts +4 -1
- package/cli/commands/stats.ts +34 -4
- package/cli/commands.ts +217 -2
- package/cli/index.ts +146 -14
- package/cli/recovery-warning.ts +115 -0
- package/cli/router.ts +32 -1
- package/cli/setup.ts +2332 -171
- package/cli/tui.ts +113 -7
- package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
- package/docs/OUTPUT_EVENT_MODEL.md +289 -0
- package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
- package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
- package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
- package/docs/OUTPUT_UX_RULES.md +449 -0
- package/docs/PLAN_UIUX_V6.md +2 -2
- package/docs/README.md +4 -3
- package/docs/TERMINAL_CONTRACT.md +278 -66
- package/docs/architecture.md +89 -7
- package/docs/changelog.md +1 -1
- package/docs/choosing-mode.md +2 -2
- package/docs/cli.md +9 -5
- package/docs/concepts.md +1 -1
- package/docs/contributing.md +9 -2
- package/docs/environment.md +6 -2
- package/docs/exec.md +46 -5
- package/docs/memory-sessions.md +2 -0
- package/docs/policy-sandbox.md +1 -1
- package/docs/pricing-budget.md +1 -1
- package/docs/quickstart.md +2 -2
- package/docs/repl.md +6 -2
- package/docs/security-model.md +1 -1
- package/docs/security.md +1 -1
- package/docs/skills.md +2 -2
- package/docs/terminal.md +9 -5
- package/docs/tools.md +1 -1
- package/package.json +35 -5
- package/src/app/session.ts +261 -15
- package/src/app/tool-layer.ts +94 -7
- package/src/daemon/approvals.ts +361 -0
- package/src/daemon/capability.ts +145 -0
- package/src/daemon/children.ts +142 -0
- package/src/daemon/client.ts +267 -0
- package/src/daemon/control.ts +350 -0
- package/src/daemon/discovery.ts +234 -0
- package/src/daemon/feed.ts +155 -0
- package/src/daemon/framing.ts +94 -0
- package/src/daemon/host.ts +316 -0
- package/src/daemon/protocol.ts +217 -0
- package/src/daemon/resource.ts +170 -0
- package/src/daemon/sanitize.ts +57 -0
- package/src/daemon/server.ts +627 -0
- package/src/daemon/store.ts +317 -0
- package/src/daemon/subscription.ts +270 -0
- package/src/daemon/telemetry.ts +81 -0
- package/src/hooks/run.ts +12 -1
- package/src/lib/atomic-write.ts +29 -3
- package/src/lib/db-path.ts +26 -0
- package/src/lib/keystore.ts +544 -42
- package/src/lib/net.ts +43 -1
- package/src/lib/safe-open.ts +116 -1
- package/src/lib/session-id.ts +15 -0
- package/src/lsp/client.ts +123 -5
- package/src/mcp/client.ts +139 -17
- package/src/mcp/server.ts +177 -50
- package/src/mcp/transport.ts +16 -19
- package/src/memory/vector.ts +770 -55
- package/src/policy/allowlist.ts +14 -2
- package/src/policy/bash-guard.ts +105 -10
- package/src/policy/compaction.ts +82 -5
- package/src/policy/consequence-engine.ts +220 -0
- package/src/policy/context.ts +132 -0
- package/src/policy/executor.ts +187 -121
- package/src/policy/no-progress.ts +559 -0
- package/src/policy/permission.ts +4 -8
- package/src/policy/pricing.ts +17 -3
- package/src/policy/scrub.ts +69 -2
- package/src/policy/tool-contract.ts +515 -0
- package/src/policy/usage.ts +310 -24
- package/src/policy/verifier.ts +6 -3
- package/src/policy/work-mode.ts +182 -0
- package/src/presentation/adapter.ts +533 -26
- package/src/presentation/events.ts +151 -0
- package/src/presentation/model.ts +180 -27
- package/src/presentation/projection.ts +858 -0
- package/src/presentation/reducer.ts +645 -310
- package/src/presentation/store.ts +12 -7
- package/src/providers/anthropic.ts +18 -10
- package/src/providers/responses.ts +17 -7
- package/src/runtime/capability.ts +409 -0
- package/src/runtime/child-execution.ts +274 -0
- package/src/runtime/composition.ts +958 -0
- package/src/runtime/dispatch.ts +591 -0
- package/src/runtime/execution-backend.ts +632 -0
- package/src/runtime/execution-events.ts +272 -0
- package/src/runtime/execution-id.ts +230 -0
- package/src/runtime/execution-journal.ts +926 -0
- package/src/runtime/execution-kernel.ts +456 -0
- package/src/runtime/execution-registry.ts +379 -0
- package/src/runtime/process-supervision.ts +276 -0
- package/src/runtime/production-execution.ts +551 -0
- package/src/runtime/production-runtime.ts +217 -0
- package/src/runtime/recovery-safety.ts +70 -0
- package/src/runtime/recovery.ts +477 -0
- package/src/runtime/runtime-capabilities.ts +179 -0
- package/src/runtime/runtime-diagnostics.ts +141 -0
- package/src/runtime/runtime-host.ts +365 -0
- package/src/runtime/runtime-status-facts.ts +222 -0
- package/src/runtime/runtime-status-provider.ts +74 -0
- package/src/runtime/runtime-status.ts +459 -0
- package/src/runtime/runtime-task-admission.ts +101 -0
- package/src/runtime/supervisor.ts +444 -0
- package/src/session/authority.ts +168 -0
- package/src/session/checkpoint.ts +88 -1
- package/src/session/context-adapter.ts +251 -0
- package/src/session/context-assembly.ts +242 -0
- package/src/session/context-identity.ts +389 -0
- package/src/session/context-projection.ts +248 -0
- package/src/session/context-selector.ts +500 -0
- package/src/session/cross-session-adoption.ts +249 -0
- package/src/session/full-history-fold.ts +171 -0
- package/src/session/identity.ts +192 -0
- package/src/session/journal.ts +805 -102
- package/src/session/open-work-intent.ts +732 -0
- package/src/session/open-work.ts +767 -0
- package/src/session/pending-tools.ts +94 -0
- package/src/session/persistence.ts +3569 -127
- package/src/session/runtime-header.ts +208 -0
- package/src/session/shadow-git.ts +13 -5
- package/src/session/verification.ts +1623 -0
- package/src/task/assignment.ts +136 -0
- package/src/task/autonomous-adapter.ts +168 -0
- package/src/task/autonomous-context.ts +630 -0
- package/src/task/autonomous-policy.ts +490 -0
- package/src/task/continuity.ts +179 -0
- package/src/task/execution-cancellation.ts +165 -0
- package/src/task/graph-validate.ts +379 -0
- package/src/task/graph.ts +305 -0
- package/src/task/identity.ts +230 -0
- package/src/task/model.ts +417 -0
- package/src/task/production-scheduler.ts +293 -0
- package/src/task/readiness.ts +229 -0
- package/src/task/scheduler-observability.ts +387 -0
- package/src/task/scheduler.ts +1197 -0
- package/src/task/scheduling-policy.ts +165 -0
- package/src/task/session-authority.ts +148 -0
- package/src/task/session-ownership.ts +211 -0
- package/src/task/store.ts +2887 -0
- package/src/task/sync.ts +343 -0
- package/src/task/trigger.ts +260 -0
- package/src/tools/bash.ts +377 -211
- package/src/tools/code_run.ts +1 -1
- package/src/tools/delete_file.ts +1 -1
- package/src/tools/edit.ts +33 -6
- package/src/tools/evidence.ts +30 -0
- package/src/tools/git.ts +4 -4
- package/src/tools/glob.ts +12 -3
- package/src/tools/grep.ts +1 -1
- package/src/tools/lsp.ts +4 -4
- package/src/tools/mcp_call.ts +11 -4
- package/src/tools/memory.ts +153 -18
- package/src/tools/move_file.ts +1 -1
- package/src/tools/patch.ts +1 -1
- package/src/tools/read_file.ts +1 -1
- package/src/tools/read_image.ts +1 -1
- package/src/tools/submit_result.ts +1 -1
- package/src/tools/task.ts +437 -41
- package/src/tools/todo.ts +662 -35
- package/src/tools/web_fetch.ts +4 -2
- package/src/tools/web_search.ts +9 -3
- package/src/tools/write_file.ts +1 -1
- package/src/ui/assistant/simple.ts +123 -50
- package/src/ui/assistant/turn-status.ts +17 -3
- package/src/ui/contract.ts +184 -0
- package/src/ui/footer.ts +54 -18
- package/src/ui/i18n/en.ts +62 -6
- package/src/ui/i18n/id.ts +62 -6
- package/src/ui/input/prompt-engine.ts +120 -25
- package/src/ui/render/errors.ts +39 -1
- package/src/ui/render/markdown-table.ts +455 -0
- package/src/ui/render/markdown.ts +22 -1
- package/src/ui/render/table-grid.ts +184 -0
- package/src/ui/render/table.ts +15 -76
- package/src/ui/runtime/screen.ts +7 -2
- package/src/ui/runtime/statusline.ts +25 -6
- package/src/ui/tui/app.ts +598 -133
- package/src/ui/tui/transcript.ts +531 -89
- package/vendor/minicore/VENDOR.md +1 -1
- package/vendor/minicore/src/core/budget.ts +25 -25
- package/vendor/minicore/src/core/compact.ts +75 -75
- package/vendor/minicore/src/core/errors.ts +59 -59
- package/vendor/minicore/src/core/events.ts +73 -73
- package/vendor/minicore/src/core/executor.ts +139 -139
- package/vendor/minicore/src/core/history.ts +31 -31
- package/vendor/minicore/src/core/index.ts +41 -41
- package/vendor/minicore/src/core/loop.ts +355 -355
- package/vendor/minicore/src/core/permission.ts +22 -22
- package/vendor/minicore/src/core/provider.ts +39 -39
- package/vendor/minicore/src/core/recovery.ts +35 -35
- package/vendor/minicore/src/core/session.ts +327 -327
- package/vendor/minicore/src/core/snapshot.ts +146 -146
- package/vendor/minicore/src/core/tokens.ts +107 -107
- package/vendor/minicore/src/core/tool.ts +115 -115
- package/vendor/minicore/src/core/types.ts +50 -50
- package/vendor/minicore/src/providers/openai-compat.ts +417 -417
- package/AGENTS.md +0 -45
- package/PLAN.md +0 -491
- package/docs/ARCHITECTURE.html +0 -1248
- package/docs/CONTROL-PLANE-MAP.md +0 -139
- package/docs/HARNESS.md +0 -150
- package/docs/SUMMARY.md +0 -52
- package/docs/UI_RENDER_PIPELINE.md +0 -165
- package/docs/USAGE.md +0 -11
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
# Output Protocol Specification
|
|
2
|
+
|
|
3
|
+
**Status:** landed — `exec --json` memakai envelope `minicode.output.v1`, ACP memakai framing JSON-RPC + mapping semantik yang sama; legacy `type:"tool"` hanya bila lifecycle absen
|
|
4
|
+
**Tanggal:** 2026-09-25
|
|
5
|
+
**Audit sumber:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`
|
|
6
|
+
|
|
7
|
+
## 1. Prinsip
|
|
8
|
+
|
|
9
|
+
Protocol ini mendefinisikan apa yang dikirim ke setiap consumer, bukan bagaimana
|
|
10
|
+
terminal menggambar. Satu semantic state dapat memiliki beberapa proyeksi:
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
PresentationState
|
|
14
|
+
├─ normal human projection
|
|
15
|
+
├─ verbose human projection
|
|
16
|
+
├─ debug diagnostic projection
|
|
17
|
+
└─ machine projection
|
|
18
|
+
├─ exec JSONL
|
|
19
|
+
└─ ACP JSON-RPC notifications
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Status, identity, duration, error cause, receipt, dan lifecycle tidak berubah karena
|
|
23
|
+
mode berubah. Yang berubah hanya level detail, layout, dan transport.
|
|
24
|
+
|
|
25
|
+
## 2. Klasifikasi output
|
|
26
|
+
|
|
27
|
+
### Human permanent
|
|
28
|
+
|
|
29
|
+
Teks assistant, ringkasan, receipt perubahan, hasil command yang memang diminta user.
|
|
30
|
+
Default: stdout pada non-TTY, atau transcript TUI pada interactive TTY.
|
|
31
|
+
|
|
32
|
+
### Human diagnostic
|
|
33
|
+
|
|
34
|
+
Warning, recovery, permission notice, verify result, setup failure, provider error.
|
|
35
|
+
Default: stderr pada TTY; pada TUI menjadi transcript/system/diagnostic node.
|
|
36
|
+
|
|
37
|
+
### Machine
|
|
38
|
+
|
|
39
|
+
`exec --json` dan `acp` stdout. Tidak boleh bercampur dengan teks manusia, ANSI,
|
|
40
|
+
spinner, help, atau warning. Error setup tetap harus menghasilkan envelope terminal
|
|
41
|
+
supaya CI tidak melihat stream kosong.
|
|
42
|
+
|
|
43
|
+
### Debug
|
|
44
|
+
|
|
45
|
+
Raw event/payload yang diminta `MINICODE_DEBUG_BUS=1` atau debug mode. Tidak aktif
|
|
46
|
+
secara default dan tidak boleh dianggap machine contract.
|
|
47
|
+
|
|
48
|
+
## 3. Stream contract
|
|
49
|
+
|
|
50
|
+
| Stream | TTY interactive | Non-TTY/machine |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| stdout | transcript/frame TUI, bukan raw shell | program output hanya |
|
|
53
|
+
| stderr | diagnostic/transient yang diizinkan | human error bila mode human; kosong/diatur untuk machine |
|
|
54
|
+
| cursor control | hanya owner screen/input | nol |
|
|
55
|
+
| alternate screen | hanya TUI | nol |
|
|
56
|
+
| SGR | boleh bila color gate | tidak perlu; `NO_COLOR` menang |
|
|
57
|
+
| raw OSC/CSI dari untrusted text | Forbidden | Forbidden |
|
|
58
|
+
|
|
59
|
+
`App` adalah pemilik tunggal frame TUI. Foreign writer ke stdout tidak boleh aktif
|
|
60
|
+
saat `TuiApp` memegang layar; diagnostic stderr yang tidak transient harus masuk ke
|
|
61
|
+
transcript atau competing-ownership guard.
|
|
62
|
+
|
|
63
|
+
## 4. Normal projection
|
|
64
|
+
|
|
65
|
+
Normal menjawab: apa yang terjadi, apakah perlu tindakan, apa hasil akhirnya.
|
|
66
|
+
|
|
67
|
+
Default tampil:
|
|
68
|
+
|
|
69
|
+
- task start/current state yang masih berjalan;
|
|
70
|
+
- meaningful progress, diaggregat parallel operation;
|
|
71
|
+
- tool receipt singkat bila ada efek nyata;
|
|
72
|
+
- finding/result/actionable plan;
|
|
73
|
+
- terminal error dengan next action;
|
|
74
|
+
- cancellation/timeout/partial status.
|
|
75
|
+
|
|
76
|
+
Default sembunyikan atau ringkas:
|
|
77
|
+
|
|
78
|
+
- raw args lengkap;
|
|
79
|
+
- internal IDs, event sequence, journal paths;
|
|
80
|
+
- token counter dan provider trace;
|
|
81
|
+
- raw tool stdout/stderr;
|
|
82
|
+
- reasoning detail;
|
|
83
|
+
- event payload dan checkpoint detail.
|
|
84
|
+
|
|
85
|
+
## 5. Verbose projection
|
|
86
|
+
|
|
87
|
+
Verbose menjawab: apa yang sebenarnya dilakukan agen.
|
|
88
|
+
|
|
89
|
+
Tambahan:
|
|
90
|
+
|
|
91
|
+
- nama tool dan target;
|
|
92
|
+
- duration setiap operation;
|
|
93
|
+
- command/file detail yang sudah disanitasi;
|
|
94
|
+
- receipt path, test summary, retry chain;
|
|
95
|
+
- reasoning expanded;
|
|
96
|
+
- recovery attempts dan kategori error;
|
|
97
|
+
- delta event aggregate, bukan raw database dump.
|
|
98
|
+
|
|
99
|
+
Verbose tidak boleh mengubah status terminal. Tool denied tetap denied; output yang
|
|
100
|
+
lebih panjang bukan izin untuk mengarang lifecycle.
|
|
101
|
+
|
|
102
|
+
## 6. Debug projection
|
|
103
|
+
|
|
104
|
+
Debug menjawab: apa yang terjadi di dalam runtime.
|
|
105
|
+
|
|
106
|
+
Tambahan:
|
|
107
|
+
|
|
108
|
+
- `eventId`, `correlationId`, `parentId`;
|
|
109
|
+
- event sequence dan timestamp;
|
|
110
|
+
- redacted raw payload;
|
|
111
|
+
- state transition/anomaly counters;
|
|
112
|
+
- checkpoint/journal references;
|
|
113
|
+
- renderer/source decision trace.
|
|
114
|
+
|
|
115
|
+
Debug payload wajib melewati secret scrub. Debug tidak boleh merusak stdout machine
|
|
116
|
+
atau menimpa frame TUI; debug human dikirim ke stderr/trace yang di-scope.
|
|
117
|
+
|
|
118
|
+
## 7. Machine projection
|
|
119
|
+
|
|
120
|
+
### Envelope
|
|
121
|
+
|
|
122
|
+
Semua event machine SHOULD menggunakan bentuk:
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"schema": "minicode.output.v1",
|
|
127
|
+
"eventId": "s1:1:17",
|
|
128
|
+
"type": "tool.completed",
|
|
129
|
+
"timestamp": "2026-09-25T12:00:00.000Z",
|
|
130
|
+
"sessionId": "s1",
|
|
131
|
+
"turnId": 1,
|
|
132
|
+
"correlationId": "call-1",
|
|
133
|
+
"source": "runtime",
|
|
134
|
+
"severity": "info",
|
|
135
|
+
"status": "completed",
|
|
136
|
+
"visibility": ["machine"],
|
|
137
|
+
"payload": {
|
|
138
|
+
"toolCallId": "call-1",
|
|
139
|
+
"name": "write_file",
|
|
140
|
+
"qualified": "write_file",
|
|
141
|
+
"target": "src/example.ts",
|
|
142
|
+
"durationMs": 42
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`eventId` contoh hanya format contract; implementasi harus memakai generator yang
|
|
148
|
+
deterministik untuk test dan stabil untuk consumer. `target` contoh bukan data nyata.
|
|
149
|
+
|
|
150
|
+
### Exec JSONL
|
|
151
|
+
|
|
152
|
+
`exec --json` harus:
|
|
153
|
+
|
|
154
|
+
- menulis satu JSON object per line;
|
|
155
|
+
- tidak menulis help, spinner, warning, ANSI, atau human ledger ke stdout;
|
|
156
|
+
- menulis setiap event canonical, bukan raw kernel shape;
|
|
157
|
+
- menyimpan `type: "summary"` sebagai record terminal dengan `ok: true|false`;
|
|
158
|
+
- membersihkan seluruh payload sebelum write;
|
|
159
|
+
- setup failure tetap menulis summary `ok:false` pada stdout lalu human error ke
|
|
160
|
+
stderr dan exit 1;
|
|
161
|
+
- malformed client/input tidak membuat stdout kosong tanpa penjelasan.
|
|
162
|
+
|
|
163
|
+
Record terminal `summary` harus membawa:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"schema": "minicode.output.v1",
|
|
168
|
+
"type": "summary",
|
|
169
|
+
"ok": false,
|
|
170
|
+
"error": {
|
|
171
|
+
"category": "CONFIGURATION_ERROR",
|
|
172
|
+
"message": "provider is not configured",
|
|
173
|
+
"action": "configure a provider"
|
|
174
|
+
},
|
|
175
|
+
"prompt": "scrubbed prompt"
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Prompt adalah data user-visible, tetapi harus disanitasi/scrubbed dan tidak boleh
|
|
180
|
+
mengandung secret.
|
|
181
|
+
|
|
182
|
+
Field opsional aditif pada record terminal didokumentasikan per jalurnya. Saat
|
|
183
|
+
ini `verify` (hasil verifikasi terakhir) hanya berlaku pada **success summary**
|
|
184
|
+
(`ok:true`) — failure summary (`ok:false`) **tidak** menyertakannya, termasuk
|
|
185
|
+
pada jalur yang mungkin sudah memiliki hasil verifikasi sebelumnya. Perbedaan
|
|
186
|
+
ini adalah kontrak yang sengaja diterima untuk P11; perluasan `verify` ke
|
|
187
|
+
failure summary memerlukan keputusan protokol tersendiri. Field wajib yang
|
|
188
|
+
terdaftar di atas tidak berubah. Detail kontrak: `docs/exec.md` §Ringkasan
|
|
189
|
+
mesin.
|
|
190
|
+
|
|
191
|
+
### ACP JSON-RPC
|
|
192
|
+
|
|
193
|
+
ACP memakai transport JSON-RPC, bukan transport lain. Notification semantic
|
|
194
|
+
minimum:
|
|
195
|
+
|
|
196
|
+
- `turn.started`
|
|
197
|
+
- `turn.completed`
|
|
198
|
+
- `turn.failed`
|
|
199
|
+
- `turn.cancelled`
|
|
200
|
+
- `tool.started`
|
|
201
|
+
- `tool.completed`
|
|
202
|
+
- `tool.failed`
|
|
203
|
+
- `tool.denied`
|
|
204
|
+
- `tool.cancelled`
|
|
205
|
+
- `approval.requested`
|
|
206
|
+
- `approval.settled`
|
|
207
|
+
|
|
208
|
+
Text delta tetap dapat dikirim sebagai:
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{"type":"text","delta":"..."}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Text delta tidak menggantikan lifecycle. `cancel` harus menghasilkan terminal task
|
|
215
|
+
state dan/atau JSON-RPC error yang eksplisit; `shutdown` tidak boleh meninggalkan run
|
|
216
|
+
aktif. Approval headless harus `deny` dengan reason `headless`, bukan pseudo-sukses.
|
|
217
|
+
|
|
218
|
+
## 8. Lifecycle wire rules
|
|
219
|
+
|
|
220
|
+
1. `started` sebelum terminal untuk task/tool/approval.
|
|
221
|
+
2. Terminal event tepat satu; duplicate/late event tidak membuat record user-facing
|
|
222
|
+
kedua.
|
|
223
|
+
3. `eventId`/correlation ID harus cukup untuk mengaitkan delta, receipt, dan status.
|
|
224
|
+
4. Denial bukan `isError:true` tanpa kategori di machine output.
|
|
225
|
+
5. Cancellation dan timeout wajib berbeda dari failure.
|
|
226
|
+
6. Jika proses berhenti sebelum terminal, client dapat membangun ulang
|
|
227
|
+
`interrupted` dari durable snapshot atau melihat turn incomplete secara eksplisit.
|
|
228
|
+
7. Child agent event tidak boleh terlihat sebagai tool root tambahan; scope/parent
|
|
229
|
+
link harus tersedia untuk consumer yang membutuhkan detail.
|
|
230
|
+
|
|
231
|
+
## 9. Error grammar
|
|
232
|
+
|
|
233
|
+
Error user-facing harus menjawab secara berurutan:
|
|
234
|
+
|
|
235
|
+
```text
|
|
236
|
+
APA YANG TERJADI
|
|
237
|
+
APA YANG SEDANG DILAKUKAN
|
|
238
|
+
MENGAPA GAGAL
|
|
239
|
+
APA YANG BISA DILAKUKAN NEXT
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Contoh:
|
|
243
|
+
|
|
244
|
+
```text
|
|
245
|
+
✕ Build failed
|
|
246
|
+
TypeScript reported errors in 2 files.
|
|
247
|
+
→ Fix the reported errors, then retry.
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Kategori internal tampil di verbose/debug; normal tidak boleh membuang actionable
|
|
251
|
+
reason. Provider JSON tidak boleh dicetak mentah sebagai pesan utama.
|
|
252
|
+
|
|
253
|
+
## 10. Copyability
|
|
254
|
+
|
|
255
|
+
Human output harus tetap berguna tanpa warna:
|
|
256
|
+
|
|
257
|
+
- status punya glyph + kata;
|
|
258
|
+
- path/command dapat disalin tanpa escape;
|
|
259
|
+
- tabel TTY boleh terformat rapi, tetapi machine/non-TTY mempertahankan source sanitized;
|
|
260
|
+
- selection text mengambil logical source, bukan frame terminal;
|
|
261
|
+
- clipboard OSC52 hanya menerima payload sanitized dan memiliki failure fallback;
|
|
262
|
+
- `NO_COLOR` tidak mengubah status atau urutan.
|
|
263
|
+
|
|
264
|
+
## 11. Compatibility dan versioning
|
|
265
|
+
|
|
266
|
+
- `schema` wajib naik versi bila field mandatory berubah atau event type berubah.
|
|
267
|
+
- Field baru bersifat optional selama satu versi major.
|
|
268
|
+
- Event lama yang masih dibutuhkan selama migrasi dapat dipetakan, tetapi tidak boleh
|
|
269
|
+
menciptakan semantik yang berbeda antar-surface.
|
|
270
|
+
- `exec` dan ACP boleh berbeda transport/framing, tetapi harus memakai event semantic
|
|
271
|
+
yang sama.
|
|
272
|
+
- Raw kernel event bukan public machine contract.
|
|
273
|
+
|
|
274
|
+
## 12. Acceptance tests protocol
|
|
275
|
+
|
|
276
|
+
- Simple task: summary dan event lifecycle lengkap.
|
|
277
|
+
- Tool denied: category `denied`, bukan generic failed.
|
|
278
|
+
- Tool failed: cause/hint tersedia di machine projection.
|
|
279
|
+
- Cancellation: turn/tool terminal cancelled, tidak ada text event terminal.
|
|
280
|
+
- Timeout: reason timeout dan tidak ada duplicate error.
|
|
281
|
+
- Partial output: marker truncation dan reference, bukan dump tersembunyi.
|
|
282
|
+
- Secret/control bytes: tidak masuk stdout machine atau clipboard.
|
|
283
|
+
- Non-TTY: tidak ada ANSI/cursor/alternate screen.
|
|
284
|
+
- ACP setup failure: response JSON error, stdout tetap machine-safe.
|
|
285
|
+
- Parallel tools: setiap call memiliki correlation ID dan terminal state sendiri.
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Output Rendering Specification
|
|
2
|
+
|
|
3
|
+
**Status:** implemented renderer boundary; canonical policy active, with streaming content transport and one ACP compatibility window.
|
|
4
|
+
**Tanggal:** 2026-09-25
|
|
5
|
+
**Audit sumber:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`
|
|
6
|
+
|
|
7
|
+
## 1. Prinsip boundary
|
|
8
|
+
|
|
9
|
+
Renderer berubah dari string consumer menjadi consumer dari semantic projection:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
PresentationState + ContentStore
|
|
13
|
+
↓
|
|
14
|
+
ProjectionPolicy(mode, viewport, locale)
|
|
15
|
+
↓
|
|
16
|
+
RendererInput (nodes + source refs + interaction state)
|
|
17
|
+
↓
|
|
18
|
+
TUI / linear / machine renderer
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Renderer boleh:
|
|
22
|
+
|
|
23
|
+
- menghitung layout kolom, wrap, tinggi baris, dan posisi cursor;
|
|
24
|
+
- memilih warna, glyph fallback, dan density;
|
|
25
|
+
- menangani hover, selection, scroll, popup, dan keyboard;
|
|
26
|
+
- memakai `sanitizeAnsi` sebagai defense-in-depth.
|
|
27
|
+
|
|
28
|
+
Renderer tidak boleh:
|
|
29
|
+
|
|
30
|
+
- menentukan status dengan `includes("denied")`, regex, atau warna;
|
|
31
|
+
- membangun turn summary sendiri;
|
|
32
|
+
- menyimpan truth runtime/approval/durasi;
|
|
33
|
+
- meng-clip source text berdasarkan pixel/frame yang sudah dirender;
|
|
34
|
+
- menentukan bahwa machine consumer boleh membaca human string.
|
|
35
|
+
|
|
36
|
+
## 2. Inventaris renderer aktual
|
|
37
|
+
|
|
38
|
+
| Module | Tanggung jawab sekarang | Keterkaitan | Target |
|
|
39
|
+
|---|---|---|---|
|
|
40
|
+
| `src/ui/tui/transcript.ts` | Streaming content buffer, source map, markdown table, canonical tool ledger, evict, selection | Raw content bus + presentation snapshot/events + policy DI | View adapter; no semantic status parsing |
|
|
41
|
+
| `src/ui/tui/app.ts` | Input, viewport, layout, screen ownership, popup lifecycle, clipboard | Controller + painter | Controller/painter boundary unchanged |
|
|
42
|
+
| `src/ui/assistant/simple.ts` | Stream sanitizer, answer/tool state, collapse, table, copy, stdout/stderr | Presentation events + policy DI + streaming text | Normal/verbose projection writer |
|
|
43
|
+
| `src/ui/assistant/turn-status.ts` | Infer active phase dan heartbeat | Policy-derived activity label | Transient view only |
|
|
44
|
+
| `src/ui/runtime/screen.ts` | Alternate screen, atomic paint, region | Terminal primitive | Tetap dipertahankan |
|
|
45
|
+
| `src/ui/runtime/statusline.ts` | Arbitrasi transient stderr | Transport owner | Tetap, plus writer policy |
|
|
46
|
+
| `cli/commands/exec.ts` | Canonical lifecycle JSONL, text delta, versioned summary | Presentation events + text transport | Canonical machine projection |
|
|
47
|
+
| `cli/commands/acp.ts` | Canonical lifecycle ACP, sanitized text delta | Presentation events + compatibility fallback | Canonical lifecycle projection |
|
|
48
|
+
| `src/ui/approval/prompt.ts` | Human prompt/decision | DI/sink + policy-compatible fallback | Same decision event |
|
|
49
|
+
|
|
50
|
+
## 3. Kontrak input renderer
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
interface RendererInput {
|
|
54
|
+
snapshot: PresentationSnapshot
|
|
55
|
+
mode: "normal" | "verbose" | "debug" | "machine"
|
|
56
|
+
viewport: { columns: number; rows: number; locale: "en" | "id" }
|
|
57
|
+
content: ContentResolver
|
|
58
|
+
clock: RendererClock
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`PresentationSnapshot` harus read-only. `ContentResolver` mengembalikan `ContentEntry`
|
|
63
|
+
dengan marker retention; tidak mengembalikan seluruh raw database tanpa batas.
|
|
64
|
+
`RendererClock` adalah satu-satunya sumber waktu visual; `Date.now()` tidak boleh
|
|
65
|
+
dipanggil dari node builder atau state reducer.
|
|
66
|
+
|
|
67
|
+
### Projection node
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
type ProjectionNode =
|
|
71
|
+
| { kind: "user"; text: string; source: SourceRef }
|
|
72
|
+
| { kind: "message"; text: string; source: SourceRef; streaming: boolean }
|
|
73
|
+
| { kind: "activity"; activity: ActivityEntry }
|
|
74
|
+
| { kind: "finding"; finding: FindingEntry; evidence: EvidenceRef[] }
|
|
75
|
+
| { kind: "plan"; plan: PlanEntry }
|
|
76
|
+
| { kind: "result"; result: ResultEntry }
|
|
77
|
+
| { kind: "warning" | "error" | "diagnostic"; error: SemanticError }
|
|
78
|
+
| { kind: "system"; text: string; source: SourceRef }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Node membawa semantic payload. `priority`, `collapse`, `visibility`, dan
|
|
82
|
+
`groupKey` menentukan policy; node tidak membawa keputusan terminal.
|
|
83
|
+
|
|
84
|
+
## 4. Projection policy
|
|
85
|
+
|
|
86
|
+
| Node/status | Normal | Verbose | Debug | Machine |
|
|
87
|
+
|---|---|---|---|---|
|
|
88
|
+
| Task running | satu activity/current state | duration + target | event IDs | typed lifecycle |
|
|
89
|
+
| Tool completed | receipt singkat | receipt + duration | full metadata | typed completed |
|
|
90
|
+
| Tool denied | warning + reason | policy path | raw category redacted | typed denied |
|
|
91
|
+
| Reasoning | collapsed/dots | expanded | raw redacted chunks | structured ref/status |
|
|
92
|
+
| Plan | upcoming steps | step status | internal links | typed plan |
|
|
93
|
+
| Finding | finding + evidence ringkas | evidence detail | full evidence | typed finding |
|
|
94
|
+
| Diagnostic | actionable only | category + next step | trace/counter | typed diagnostic |
|
|
95
|
+
| Context compacted | system warning | reason detail | trace | typed event |
|
|
96
|
+
|
|
97
|
+
Policy tidak boleh mengubah final status. `machine` boleh lebih ringkas secara visual,
|
|
98
|
+
tetapi tidak boleh kehilangan terminal state atau category.
|
|
99
|
+
|
|
100
|
+
## 5. TUI renderer
|
|
101
|
+
|
|
102
|
+
### Ownership
|
|
103
|
+
|
|
104
|
+
`TuiApp` tetap memiliki:
|
|
105
|
+
|
|
106
|
+
- alternate-screen lifecycle;
|
|
107
|
+
- keyboard/mouse decoder;
|
|
108
|
+
- viewport scroll dan selection;
|
|
109
|
+
- popup suspend/resume;
|
|
110
|
+
- full-frame paint dan cursor parking.
|
|
111
|
+
|
|
112
|
+
`TuiApp` tidak lagi menjadi sumber status tool. Ia menerima status dari snapshot/
|
|
113
|
+
projection melalui `TuiHost`, dengan fallback deny bila DI tidak tersedia.
|
|
114
|
+
|
|
115
|
+
### Frame
|
|
116
|
+
|
|
117
|
+
Frame terdiri dari:
|
|
118
|
+
|
|
119
|
+
1. transcript viewport;
|
|
120
|
+
2. optional inline `/` dropdown;
|
|
121
|
+
3. composer/prompt atau activity row;
|
|
122
|
+
4. satu spacer;
|
|
123
|
+
5. status bar.
|
|
124
|
+
|
|
125
|
+
`screen.ts` tetap satu-satunya alt-screen owner. `paintRegion()` hanya untuk popup;
|
|
126
|
+
popup tidak boleh membuat listener stdin kedua.
|
|
127
|
+
|
|
128
|
+
### TUI semantic projection
|
|
129
|
+
|
|
130
|
+
- User message: satu entry user dengan source range.
|
|
131
|
+
- Assistant stream: live buffer yang di-cap; final node dipisah dari stream.
|
|
132
|
+
- Activity: started → running → terminal, dengan glyph + status word.
|
|
133
|
+
- Tool child: default dikelompokkan ke parent `delegate_task`; child detail tersedia
|
|
134
|
+
pada verbose/debug.
|
|
135
|
+
- Context compaction: system entry, tidak menghapus history.
|
|
136
|
+
- Summary: system node dari canonical turn summary, bukan hasil hitung ulang widget.
|
|
137
|
+
- Error: node dengan category/cause/hint; tidak hanya string merah.
|
|
138
|
+
|
|
139
|
+
### Selection dan clipboard
|
|
140
|
+
|
|
141
|
+
Selection adalah view concern, tetapi sumbernya adalah `SourceRef` semantic:
|
|
142
|
+
|
|
143
|
+
- anchor/focus menyimpan source ID + logical offset;
|
|
144
|
+
- row visual menyimpan source range + display columns;
|
|
145
|
+
- wrap, CJK/emoji, SGR, table border, dan evict diuji;
|
|
146
|
+
- click prompt hanya memindahkan cursor;
|
|
147
|
+
- `Ctrl+C` copy hanya jika selection valid; tanpa selection no-op;
|
|
148
|
+
- `Esc` clear selection dulu, lalu abort/batal;
|
|
149
|
+
- OSC52 menerima plain sanitized payload dan failure state eksplisit.
|
|
150
|
+
|
|
151
|
+
Selection tidak boleh menyalin terminal control sequence atau table padding. Terminal
|
|
152
|
+
native selection bukan acceptance contract karena mouse tracking aktif.
|
|
153
|
+
|
|
154
|
+
## 6. Linear renderer
|
|
155
|
+
|
|
156
|
+
Linear renderer menerima `ProjectionNode[]`/snapshot yang sama:
|
|
157
|
+
|
|
158
|
+
- stdout: permanent output dan answer/result;
|
|
159
|
+
- stderr: activity, reasoning (verbose), warning, error;
|
|
160
|
+
- non-TTY: `stripSgr`, no cursor control, no alternate screen;
|
|
161
|
+
- TTY: satu compact ledger per operation, parallel child group;
|
|
162
|
+
- markdown table: semantic table hanya di TTY; non-TTY mempertahankan source sanitized;
|
|
163
|
+
- copy buffer: isi yang benar-benar terlihat, dengan cap dan marker.
|
|
164
|
+
|
|
165
|
+
`simple.ts` tidak lagi menentukan status dari raw result. Ia menerima activity
|
|
166
|
+
snapshot/event canonical, lalu hanya memilih glyph, stream, dan disclosure level.
|
|
167
|
+
|
|
168
|
+
## 7. Machine renderers
|
|
169
|
+
|
|
170
|
+
### Exec
|
|
171
|
+
|
|
172
|
+
Exec tidak memakai human renderer. Mapper canonical:
|
|
173
|
+
|
|
174
|
+
- canonical event → JSON object;
|
|
175
|
+
- terminal summary → object `type:summary`;
|
|
176
|
+
- scrub sebelum serialize/write;
|
|
177
|
+
- setup failure → summary `ok:false` pada stdout + human error stderr;
|
|
178
|
+
- tidak ada `console.log` dari builtin selama machine mode.
|
|
179
|
+
|
|
180
|
+
### ACP
|
|
181
|
+
|
|
182
|
+
ACP juga tidak mengurai terminal text. Lifecycle projection menggunakan event
|
|
183
|
+
canonical, sedangkan `text` delta tetap transport-compatible. Jika lifecycle
|
|
184
|
+
subscription tidak tersedia dalam compatibility window, hanya `tool.started`
|
|
185
|
+
diemit sebagai `type:"tool"` legacy; consumer harus menandainya sebagai
|
|
186
|
+
fallback dan tidak boleh menyusun status terminal dari raw text.
|
|
187
|
+
|
|
188
|
+
## 8. Diagnostics dan direct writes
|
|
189
|
+
|
|
190
|
+
Direct write bukan otomatis salah; ia harus diklasifikasi:
|
|
191
|
+
|
|
192
|
+
| Writer | Kategori | Route target |
|
|
193
|
+
|---|---|---|
|
|
194
|
+
| `TuiApp`/screen | TUI frame | stdout owner screen |
|
|
195
|
+
| `simple` permanent | human | stdout |
|
|
196
|
+
| `turn-status`/spinner | transient | statusline owner |
|
|
197
|
+
| approval/askLine | human input | prompt/overlay owner |
|
|
198
|
+
| CLI setup/recovery/verify | diagnostic | stderr atau transcript |
|
|
199
|
+
| exec/ACP | machine | protocol sink |
|
|
200
|
+
| debug bus | debug | stderr/trace |
|
|
201
|
+
|
|
202
|
+
Writer baru harus mendaftarkan category dan owner. `statusline.ts` tetap menjadi
|
|
203
|
+
arbitrator untuk transient, tetapi bukan pengganti semantic routing.
|
|
204
|
+
|
|
205
|
+
## 9. Geometry, text, dan fallback
|
|
206
|
+
|
|
207
|
+
- `displayWidth()` menghitung terminal columns; CJK/emoji = dua kolom.
|
|
208
|
+
- Sanitasi control bytes dilakukan sebelum output; SGR boleh hanya bila color gate.
|
|
209
|
+
- Resize dibaca saat paint, bukan saat event.
|
|
210
|
+
- `NO_COLOR`/legacy Windows memakai glyph ASCII atau status word.
|
|
211
|
+
- Narrow terminal memakai truncation/wrap yang menjaga path/target penting.
|
|
212
|
+
- TTY table boleh aligned; machine/non-TTY tidak boleh berubah makna.
|
|
213
|
+
- Copy/paste tidak bergantung pada warna.
|
|
214
|
+
|
|
215
|
+
## 10. Parity matrix
|
|
216
|
+
|
|
217
|
+
| Semantic | TUI | Linear | Exec | ACP |
|
|
218
|
+
|---|---|---|---|---|
|
|
219
|
+
| tool completed | ledger success | ledger success | `tool.completed` | `tool.completed` |
|
|
220
|
+
| tool denied | deny glyph/word | warning + reason | `tool.denied` | `tool.denied` |
|
|
221
|
+
| turn cancelled | stopped/abort state | stopped/error | `turn.cancelled` + summary | `turn.cancelled`/error |
|
|
222
|
+
| file receipt | activity/source | receipt line | typed receipt | typed receipt |
|
|
223
|
+
| context compacted | system entry | warning | typed system event | typed system event |
|
|
224
|
+
| duration | pinned/summary | suffix | field | field |
|
|
225
|
+
| parent/child | grouped | grouped | IDs/link | IDs/link |
|
|
226
|
+
|
|
227
|
+
Parity diuji pada semantic object sebelum snapshot string. Test output tetap diperlukan
|
|
228
|
+
untuk regressions visual dan protocol.
|
|
229
|
+
|
|
230
|
+
## 11. Migration seams
|
|
231
|
+
|
|
232
|
+
1. `PresentationAdapter` dapat tetap emit raw-compatible events.
|
|
233
|
+
2. `ProjectionBridge` aktif untuk semua surface; flag `MINICODE_PRESENTATION_V2` dihapus di Phase 8.
|
|
234
|
+
3. TUI/linear dapat membandingkan canonical projection dengan legacy output pada test.
|
|
235
|
+
4. Exec/ACP memakai canonical projection lebih dulu karena machine parity paling mudah
|
|
236
|
+
diukur.
|
|
237
|
+
5. After one release and green golden tests, raw semantic subscriptions were
|
|
238
|
+
removed from user-facing TUI. Raw EventBus remains for streaming content and
|
|
239
|
+
diagnostics/trace only.
|
|
240
|
+
|
|
241
|
+
## 12. Definition of done renderer
|
|
242
|
+
|
|
243
|
+
- Tidak ada renderer yang meng-status-kan teks.
|
|
244
|
+
- TUI/linear/exec/ACP menghasilkan semantic fields yang sama.
|
|
245
|
+
- Sanitasi, width, lifecycle, machine stream, dan clipboard invariants tetap hijau.
|
|
246
|
+
- Tidak ada direct write baru yang tidak terkategori.
|
|
247
|
+
- Legacy path removal tidak mengubah exit code atau terminal contract tanpa update
|
|
248
|
+
`docs/TERMINAL_CONTRACT.md` dan peta test.
|