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.
Files changed (221) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -4
  4. package/cli/args.ts +46 -0
  5. package/cli/commands/acp.ts +163 -10
  6. package/cli/commands/config.ts +33 -18
  7. package/cli/commands/daemon.ts +515 -0
  8. package/cli/commands/exec.ts +145 -53
  9. package/cli/commands/openwork.ts +986 -0
  10. package/cli/commands/sessions.ts +4 -1
  11. package/cli/commands/stats.ts +34 -4
  12. package/cli/commands.ts +217 -2
  13. package/cli/index.ts +146 -14
  14. package/cli/recovery-warning.ts +115 -0
  15. package/cli/router.ts +32 -1
  16. package/cli/setup.ts +2332 -171
  17. package/cli/tui.ts +113 -7
  18. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  19. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  20. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  21. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  22. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  23. package/docs/OUTPUT_UX_RULES.md +449 -0
  24. package/docs/PLAN_UIUX_V6.md +2 -2
  25. package/docs/README.md +4 -3
  26. package/docs/TERMINAL_CONTRACT.md +278 -66
  27. package/docs/architecture.md +89 -7
  28. package/docs/changelog.md +1 -1
  29. package/docs/choosing-mode.md +2 -2
  30. package/docs/cli.md +9 -5
  31. package/docs/concepts.md +1 -1
  32. package/docs/contributing.md +9 -2
  33. package/docs/environment.md +6 -2
  34. package/docs/exec.md +46 -5
  35. package/docs/memory-sessions.md +2 -0
  36. package/docs/policy-sandbox.md +1 -1
  37. package/docs/pricing-budget.md +1 -1
  38. package/docs/quickstart.md +2 -2
  39. package/docs/repl.md +6 -2
  40. package/docs/security-model.md +1 -1
  41. package/docs/security.md +1 -1
  42. package/docs/skills.md +2 -2
  43. package/docs/terminal.md +9 -5
  44. package/docs/tools.md +1 -1
  45. package/package.json +35 -5
  46. package/src/app/session.ts +261 -15
  47. package/src/app/tool-layer.ts +94 -7
  48. package/src/daemon/approvals.ts +361 -0
  49. package/src/daemon/capability.ts +145 -0
  50. package/src/daemon/children.ts +142 -0
  51. package/src/daemon/client.ts +267 -0
  52. package/src/daemon/control.ts +350 -0
  53. package/src/daemon/discovery.ts +234 -0
  54. package/src/daemon/feed.ts +155 -0
  55. package/src/daemon/framing.ts +94 -0
  56. package/src/daemon/host.ts +316 -0
  57. package/src/daemon/protocol.ts +217 -0
  58. package/src/daemon/resource.ts +170 -0
  59. package/src/daemon/sanitize.ts +57 -0
  60. package/src/daemon/server.ts +627 -0
  61. package/src/daemon/store.ts +317 -0
  62. package/src/daemon/subscription.ts +270 -0
  63. package/src/daemon/telemetry.ts +81 -0
  64. package/src/hooks/run.ts +12 -1
  65. package/src/lib/atomic-write.ts +29 -3
  66. package/src/lib/db-path.ts +26 -0
  67. package/src/lib/keystore.ts +544 -42
  68. package/src/lib/net.ts +43 -1
  69. package/src/lib/safe-open.ts +116 -1
  70. package/src/lib/session-id.ts +15 -0
  71. package/src/lsp/client.ts +123 -5
  72. package/src/mcp/client.ts +139 -17
  73. package/src/mcp/server.ts +177 -50
  74. package/src/mcp/transport.ts +16 -19
  75. package/src/memory/vector.ts +770 -55
  76. package/src/policy/allowlist.ts +14 -2
  77. package/src/policy/bash-guard.ts +105 -10
  78. package/src/policy/compaction.ts +82 -5
  79. package/src/policy/consequence-engine.ts +220 -0
  80. package/src/policy/context.ts +132 -0
  81. package/src/policy/executor.ts +187 -121
  82. package/src/policy/no-progress.ts +559 -0
  83. package/src/policy/permission.ts +4 -8
  84. package/src/policy/pricing.ts +17 -3
  85. package/src/policy/scrub.ts +69 -2
  86. package/src/policy/tool-contract.ts +515 -0
  87. package/src/policy/usage.ts +310 -24
  88. package/src/policy/verifier.ts +6 -3
  89. package/src/policy/work-mode.ts +182 -0
  90. package/src/presentation/adapter.ts +533 -26
  91. package/src/presentation/events.ts +151 -0
  92. package/src/presentation/model.ts +180 -27
  93. package/src/presentation/projection.ts +858 -0
  94. package/src/presentation/reducer.ts +645 -310
  95. package/src/presentation/store.ts +12 -7
  96. package/src/providers/anthropic.ts +18 -10
  97. package/src/providers/responses.ts +17 -7
  98. package/src/runtime/capability.ts +409 -0
  99. package/src/runtime/child-execution.ts +274 -0
  100. package/src/runtime/composition.ts +958 -0
  101. package/src/runtime/dispatch.ts +591 -0
  102. package/src/runtime/execution-backend.ts +632 -0
  103. package/src/runtime/execution-events.ts +272 -0
  104. package/src/runtime/execution-id.ts +230 -0
  105. package/src/runtime/execution-journal.ts +926 -0
  106. package/src/runtime/execution-kernel.ts +456 -0
  107. package/src/runtime/execution-registry.ts +379 -0
  108. package/src/runtime/process-supervision.ts +276 -0
  109. package/src/runtime/production-execution.ts +551 -0
  110. package/src/runtime/production-runtime.ts +217 -0
  111. package/src/runtime/recovery-safety.ts +70 -0
  112. package/src/runtime/recovery.ts +477 -0
  113. package/src/runtime/runtime-capabilities.ts +179 -0
  114. package/src/runtime/runtime-diagnostics.ts +141 -0
  115. package/src/runtime/runtime-host.ts +365 -0
  116. package/src/runtime/runtime-status-facts.ts +222 -0
  117. package/src/runtime/runtime-status-provider.ts +74 -0
  118. package/src/runtime/runtime-status.ts +459 -0
  119. package/src/runtime/runtime-task-admission.ts +101 -0
  120. package/src/runtime/supervisor.ts +444 -0
  121. package/src/session/authority.ts +168 -0
  122. package/src/session/checkpoint.ts +88 -1
  123. package/src/session/context-adapter.ts +251 -0
  124. package/src/session/context-assembly.ts +242 -0
  125. package/src/session/context-identity.ts +389 -0
  126. package/src/session/context-projection.ts +248 -0
  127. package/src/session/context-selector.ts +500 -0
  128. package/src/session/cross-session-adoption.ts +249 -0
  129. package/src/session/full-history-fold.ts +171 -0
  130. package/src/session/identity.ts +192 -0
  131. package/src/session/journal.ts +805 -102
  132. package/src/session/open-work-intent.ts +732 -0
  133. package/src/session/open-work.ts +767 -0
  134. package/src/session/pending-tools.ts +94 -0
  135. package/src/session/persistence.ts +3569 -127
  136. package/src/session/runtime-header.ts +208 -0
  137. package/src/session/shadow-git.ts +13 -5
  138. package/src/session/verification.ts +1623 -0
  139. package/src/task/assignment.ts +136 -0
  140. package/src/task/autonomous-adapter.ts +168 -0
  141. package/src/task/autonomous-context.ts +630 -0
  142. package/src/task/autonomous-policy.ts +490 -0
  143. package/src/task/continuity.ts +179 -0
  144. package/src/task/execution-cancellation.ts +165 -0
  145. package/src/task/graph-validate.ts +379 -0
  146. package/src/task/graph.ts +305 -0
  147. package/src/task/identity.ts +230 -0
  148. package/src/task/model.ts +417 -0
  149. package/src/task/production-scheduler.ts +293 -0
  150. package/src/task/readiness.ts +229 -0
  151. package/src/task/scheduler-observability.ts +387 -0
  152. package/src/task/scheduler.ts +1197 -0
  153. package/src/task/scheduling-policy.ts +165 -0
  154. package/src/task/session-authority.ts +148 -0
  155. package/src/task/session-ownership.ts +211 -0
  156. package/src/task/store.ts +2887 -0
  157. package/src/task/sync.ts +343 -0
  158. package/src/task/trigger.ts +260 -0
  159. package/src/tools/bash.ts +377 -211
  160. package/src/tools/code_run.ts +1 -1
  161. package/src/tools/delete_file.ts +1 -1
  162. package/src/tools/edit.ts +33 -6
  163. package/src/tools/evidence.ts +30 -0
  164. package/src/tools/git.ts +4 -4
  165. package/src/tools/glob.ts +12 -3
  166. package/src/tools/grep.ts +1 -1
  167. package/src/tools/lsp.ts +4 -4
  168. package/src/tools/mcp_call.ts +11 -4
  169. package/src/tools/memory.ts +153 -18
  170. package/src/tools/move_file.ts +1 -1
  171. package/src/tools/patch.ts +1 -1
  172. package/src/tools/read_file.ts +1 -1
  173. package/src/tools/read_image.ts +1 -1
  174. package/src/tools/submit_result.ts +1 -1
  175. package/src/tools/task.ts +437 -41
  176. package/src/tools/todo.ts +662 -35
  177. package/src/tools/web_fetch.ts +4 -2
  178. package/src/tools/web_search.ts +9 -3
  179. package/src/tools/write_file.ts +1 -1
  180. package/src/ui/assistant/simple.ts +123 -50
  181. package/src/ui/assistant/turn-status.ts +17 -3
  182. package/src/ui/contract.ts +184 -0
  183. package/src/ui/footer.ts +54 -18
  184. package/src/ui/i18n/en.ts +62 -6
  185. package/src/ui/i18n/id.ts +62 -6
  186. package/src/ui/input/prompt-engine.ts +120 -25
  187. package/src/ui/render/errors.ts +39 -1
  188. package/src/ui/render/markdown-table.ts +455 -0
  189. package/src/ui/render/markdown.ts +22 -1
  190. package/src/ui/render/table-grid.ts +184 -0
  191. package/src/ui/render/table.ts +15 -76
  192. package/src/ui/runtime/screen.ts +7 -2
  193. package/src/ui/runtime/statusline.ts +25 -6
  194. package/src/ui/tui/app.ts +598 -133
  195. package/src/ui/tui/transcript.ts +531 -89
  196. package/vendor/minicore/VENDOR.md +1 -1
  197. package/vendor/minicore/src/core/budget.ts +25 -25
  198. package/vendor/minicore/src/core/compact.ts +75 -75
  199. package/vendor/minicore/src/core/errors.ts +59 -59
  200. package/vendor/minicore/src/core/events.ts +73 -73
  201. package/vendor/minicore/src/core/executor.ts +139 -139
  202. package/vendor/minicore/src/core/history.ts +31 -31
  203. package/vendor/minicore/src/core/index.ts +41 -41
  204. package/vendor/minicore/src/core/loop.ts +355 -355
  205. package/vendor/minicore/src/core/permission.ts +22 -22
  206. package/vendor/minicore/src/core/provider.ts +39 -39
  207. package/vendor/minicore/src/core/recovery.ts +35 -35
  208. package/vendor/minicore/src/core/session.ts +327 -327
  209. package/vendor/minicore/src/core/snapshot.ts +146 -146
  210. package/vendor/minicore/src/core/tokens.ts +107 -107
  211. package/vendor/minicore/src/core/tool.ts +115 -115
  212. package/vendor/minicore/src/core/types.ts +50 -50
  213. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  214. package/AGENTS.md +0 -45
  215. package/PLAN.md +0 -491
  216. package/docs/ARCHITECTURE.html +0 -1248
  217. package/docs/CONTROL-PLANE-MAP.md +0 -139
  218. package/docs/HARNESS.md +0 -150
  219. package/docs/SUMMARY.md +0 -52
  220. package/docs/UI_RENDER_PIPELINE.md +0 -165
  221. 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.