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,289 @@
|
|
|
1
|
+
# Output Event Model
|
|
2
|
+
|
|
3
|
+
**Status:** Phase 2 core state/replay contract landed; renderer/wire protocol masih target
|
|
4
|
+
**Tanggal:** 2026-09-25
|
|
5
|
+
**Audit sumber:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`
|
|
6
|
+
|
|
7
|
+
## Status implementasi
|
|
8
|
+
|
|
9
|
+
Phase 1 mengimplementasikan `user.message`, exhaustive bridge payload, dan marker
|
|
10
|
+
`PROPOSED_EVENT_TYPES` untuk event yang belum memiliki producer. Phase 2 core kini
|
|
11
|
+
menyimpan collection semantic lengkap, menghitung summary dari evidence, lalu
|
|
12
|
+
memuat ulang dari `presentation_events`; renderer dan machine protocol belum
|
|
13
|
+
dipindahkan penuh.
|
|
14
|
+
|
|
15
|
+
## 1. Tujuan
|
|
16
|
+
|
|
17
|
+
Model ini mendefinisikan fakta semantic yang boleh melewati runtime → policy →
|
|
18
|
+
renderer. Model ini bukan renderer contract dan bukan terminal output. TTY, linear,
|
|
19
|
+
JSONL, ACP, dan consumer masa depan harus membaca event yang sama lalu memilih
|
|
20
|
+
proyeksi yang berbeda.
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
runtime fact
|
|
24
|
+
→ semantic event
|
|
25
|
+
→ deterministic reducer
|
|
26
|
+
→ presentation state
|
|
27
|
+
→ policy projection
|
|
28
|
+
→ renderer
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 2. Envelope kanonik
|
|
32
|
+
|
|
33
|
+
Implementasi internal dapat memakai nama field yang sudah ada (`eventSeq`, `ts`).
|
|
34
|
+
Bentuk wire eksternal harus versioned:
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
interface OutputEventEnvelope {
|
|
38
|
+
schema: "minicode.output.v1"
|
|
39
|
+
eventId: string
|
|
40
|
+
type: OutputEventType
|
|
41
|
+
timestamp: string
|
|
42
|
+
sessionId: string
|
|
43
|
+
turnId?: number
|
|
44
|
+
stepId?: number
|
|
45
|
+
correlationId?: string
|
|
46
|
+
parentId?: string
|
|
47
|
+
source: "runtime" | "app" | "derived"
|
|
48
|
+
severity: "info" | "warning" | "error" | "critical"
|
|
49
|
+
status: "started" | "active" | "completed" | "failed" | "denied" | "cancelled" | "interrupted" | "partial" | "recovered"
|
|
50
|
+
visibility: Array<"normal" | "verbose" | "debug" | "machine">
|
|
51
|
+
payload: OutputEventPayload
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Aturan field
|
|
56
|
+
|
|
57
|
+
- `eventId` adalah identitas stabil event untuk consumer; bukan renderer-generated
|
|
58
|
+
string. Implementasi awal boleh memakai session/event sequence yang deterministik.
|
|
59
|
+
- `eventSeq` internal tetap urutan observasi per sesi, bukan causality.
|
|
60
|
+
- `correlationId` menunjuk tool call, approval, atau operasi mayor yang sedang berjalan.
|
|
61
|
+
- `parentId` hanya diisi untuk causality eksplisit: retry, child tool, atau turn parent.
|
|
62
|
+
- `source` membedakan fakta kernel, app-layer event, dan derived projection.
|
|
63
|
+
- `severity` tidak sama dengan `status`: `denied` adalah status, bukan severity.
|
|
64
|
+
- `visibility` dapat memiliki lebih dari satu mode; machine projection tidak boleh
|
|
65
|
+
bergantung pada scraping human text.
|
|
66
|
+
- `payload` tidak boleh menyimpan secret, credential, raw ANSI yang tidak perlu, atau
|
|
67
|
+
payload besar. Payload besar memakai `ContentRef`.
|
|
68
|
+
|
|
69
|
+
## 3. Taxonomy
|
|
70
|
+
|
|
71
|
+
### Session dan user
|
|
72
|
+
|
|
73
|
+
| Tipe | Producer | Meaning | Durable | Visibility default |
|
|
74
|
+
|---|---|---|---|---|
|
|
75
|
+
| `session.started` | composition root | sesi aplikasi siap | ya | machine/debug |
|
|
76
|
+
| `session.ended` | composition root | sesi ditutup/cleanup | ya | machine/debug |
|
|
77
|
+
| `user.message.received` | controller | input user dan prompt sanitized | ya sesuai session | normal |
|
|
78
|
+
| `user.approval.requested` | policy | approval harus diputuskan | ya | normal/machine |
|
|
79
|
+
| `user.approval.settled` | policy | keputusan allow/deny/cancel | ya | normal/machine |
|
|
80
|
+
|
|
81
|
+
`user.message.received` adalah semantic event, bukan string yang ditambahkan langsung
|
|
82
|
+
ke transcript. TUI boleh tetap melakukan echo visual, tetapi echo tersebut harus
|
|
83
|
+
merujuk pada entry yang sama.
|
|
84
|
+
|
|
85
|
+
### Task dan plan
|
|
86
|
+
|
|
87
|
+
| Tipe | Producer | Meaning | Durable |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| `task.started` | adapter/driver | satu `session.run` dimulai | ya |
|
|
90
|
+
| `task.progress` | policy/tool/app | perubahan status yang bermakna | tidak; state terakhir tetap durable |
|
|
91
|
+
| `task.completed` | adapter/driver | turn selesai normal | ya |
|
|
92
|
+
| `task.failed` | adapter/driver | turn gagal dengan cause | ya |
|
|
93
|
+
| `task.cancelled` | adapter/driver | user/timeout/budget/parent cancel | ya |
|
|
94
|
+
| `plan.created` | planner/tool | rencana kerja yang akan datang | ya bila adopted |
|
|
95
|
+
| `plan.updated` | planner/tool | perubahan langkah/urutan | ya |
|
|
96
|
+
| `plan.step.started` | planner/tool | langkah aktif | ya |
|
|
97
|
+
| `plan.step.completed` | planner/tool | langkah selesai | ya |
|
|
98
|
+
|
|
99
|
+
`plan.*` tidak boleh merekam “membaca file”, “menjalankan grep”, atau “berpikir”.
|
|
100
|
+
Itu adalah activity. Plan hanya menyatakan future work yang sudah diputuskan.
|
|
101
|
+
|
|
102
|
+
### Model dan reasoning
|
|
103
|
+
|
|
104
|
+
| Tipe | Producer | Meaning | Durable |
|
|
105
|
+
|---|---|---|---|
|
|
106
|
+
| `assistant.message.delta` | provider loop | potongan teks live | tidak |
|
|
107
|
+
| `assistant.message.completed` | adapter dari final result | assistant final message | ya |
|
|
108
|
+
| `assistant.message.truncated` | derived/content policy | final message dipotong oleh cap | ya |
|
|
109
|
+
| `assistant.reasoning.delta` | provider loop | potongan reasoning live | tidak |
|
|
110
|
+
| `assistant.reasoning.completed` | adapter/provider finalization | reasoning final/ref | ya; full payload best effort |
|
|
111
|
+
| `context.compacted` | MiniCore loop | context model dipadatkan | ya sebagai system event |
|
|
112
|
+
|
|
113
|
+
Delta tidak boleh menjadi satu-satunya bukti completion. Jika proses berhenti setelah
|
|
114
|
+
delta, rebuild harus menandai state sebagai `interrupted` atau `partial`, bukan
|
|
115
|
+
mengarang final message.
|
|
116
|
+
|
|
117
|
+
### Tool dan filesystem
|
|
118
|
+
|
|
119
|
+
| Tipe | Producer | Meaning | Durable |
|
|
120
|
+
|---|---|---|---|
|
|
121
|
+
| `tool.started` | adapter dari execution | operasi tool dimulai | ya |
|
|
122
|
+
| `tool.progress` | tool/app, opsional | status internal berubah | tidak |
|
|
123
|
+
| `tool.completed` | adapter | operasi sukses | ya |
|
|
124
|
+
| `tool.failed` | adapter | operasi gagal | ya |
|
|
125
|
+
| `tool.denied` | adapter/policy | policy/permission menolak | ya |
|
|
126
|
+
| `tool.cancelled` | adapter | operasi dibatalkan | ya |
|
|
127
|
+
| `file.changed` | journal/checkpoint | ada paths yang committed | ya |
|
|
128
|
+
| `test.completed` | adapter/tool evidence | hasil test terstruktur | ya |
|
|
129
|
+
| `finding.detected` | `submit_result` terstruktur | temuan/evidence semantic eksplisit | ya bila berasal dari agent |
|
|
130
|
+
| `result.produced` | task finalizer | hasil/actionable conclusion | ya |
|
|
131
|
+
| `checkpoint.created` | checkpoint adapter | checkpoint evidence dan linkage turn | ya |
|
|
132
|
+
| `plan.updated` | planner/tool | rencana dan status langkah | ya bila adopted |
|
|
133
|
+
| `diagnostic.raised` | adapter/policy | diagnostic actionable | ya |
|
|
134
|
+
|
|
135
|
+
Tool `completed` harus membawa `summary`, `durationMs`, `expandRef`, dan bila ada
|
|
136
|
+
`receipt`. Tool `failed` harus membawa `cause`, `message`, `hint`, dan `expandRef`.
|
|
137
|
+
Tool `denied` harus membawa `reason`; `denied` tidak boleh berubah menjadi generic
|
|
138
|
+
`failed` hanya karena satu renderer tidak tahu policy.
|
|
139
|
+
|
|
140
|
+
### Error, recovery, dan lifecycle
|
|
141
|
+
|
|
142
|
+
| Tipe | Meaning | Normal | Verbose | Debug/machine |
|
|
143
|
+
|---|---|---|---|---|
|
|
144
|
+
| `diagnostic.raised` | warning/configuration/recovery | ringkas | kategori + next action | cause/trace |
|
|
145
|
+
| `error.raised` | kegagalan yang perlu tindakan | actionable | source + detail | payload scrubbed |
|
|
146
|
+
| `recovery.started` | retry/fallback/compaction | “recovering” | strategi | reason/delay |
|
|
147
|
+
| `recovery.completed` | berhasil pulih | “recovered” | hasil | result |
|
|
148
|
+
| `recovery.failed` | strategi habis | status terminal | cause | full category |
|
|
149
|
+
|
|
150
|
+
Kategori error yang harus dibedakan:
|
|
151
|
+
|
|
152
|
+
- `USER_ERROR`
|
|
153
|
+
- `CONFIGURATION_ERROR`
|
|
154
|
+
- `PERMISSION_ERROR`
|
|
155
|
+
- `TOOL_ERROR`
|
|
156
|
+
- `FILESYSTEM_ERROR`
|
|
157
|
+
- `NETWORK_ERROR`
|
|
158
|
+
- `PROVIDER_ERROR`
|
|
159
|
+
- `MODEL_ERROR`
|
|
160
|
+
- `AGENT_ERROR`
|
|
161
|
+
- `INTERNAL_ERROR`
|
|
162
|
+
|
|
163
|
+
Recoverability adalah field terpisah:
|
|
164
|
+
|
|
165
|
+
- `RECOVERABLE`
|
|
166
|
+
- `RETRYABLE`
|
|
167
|
+
- `ACTION_REQUIRED`
|
|
168
|
+
- `FATAL`
|
|
169
|
+
- `UNKNOWN`
|
|
170
|
+
|
|
171
|
+
## 4. State machine
|
|
172
|
+
|
|
173
|
+
### Task
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
started → active → completed
|
|
177
|
+
├────→ failed
|
|
178
|
+
├────→ cancelled
|
|
179
|
+
└────→ partial → active | completed | failed
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`cancelled`, `failed`, dan `interrupted` tidak boleh saling menggantikan.
|
|
183
|
+
`interrupted` hanya boleh muncul dari rebuild ketika durable evidence menunjukkan
|
|
184
|
+
proses berhenti sebelum terminal event.
|
|
185
|
+
|
|
186
|
+
### Tool
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
started → running → completed
|
|
190
|
+
├→ failed
|
|
191
|
+
├→ denied
|
|
192
|
+
└→ cancelled
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
First-terminal-wins: terminal kedua untuk `toolCallId` yang sama diabaikan dan
|
|
196
|
+
dicatat sebagai anomaly. Tool yang tidak punya `started` tetap boleh direkonstruksi
|
|
197
|
+
sebagai `incomplete`, tetapi harus ditandai di diagnostics.
|
|
198
|
+
|
|
199
|
+
### Approval
|
|
200
|
+
|
|
201
|
+
```text
|
|
202
|
+
requested → settled { allow | allow-always | deny | cancelled }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Saat parent task settle, approval `requested` yang masih terbuka harus di-force-close
|
|
206
|
+
menjadi `cancelled(parent-ended)`. Saat rebuild/crash, hal yang sama terjadi dengan
|
|
207
|
+
alasan parent-ended; outcome tidak boleh tetap `requested`.
|
|
208
|
+
|
|
209
|
+
## 5. Ordering, correlation, causality, hierarchy
|
|
210
|
+
|
|
211
|
+
Empat concept dipisahkan:
|
|
212
|
+
|
|
213
|
+
1. **Ordering:** urutan observasi event. Adaptor menetapkan `eventSeq`; ini bukan
|
|
214
|
+
urutan penyebab.
|
|
215
|
+
2. **Correlation:** ID yang stabil: `toolCallId`, `approvalId`, `correlationId`.
|
|
216
|
+
3. **Causality:** link eksplisit `supersedes`, `parentToolCallId`, atau approval link.
|
|
217
|
+
4. **Hierarchy:** `sessionId → turnId → stepId → toolCallId`; child session membawa
|
|
218
|
+
parent link.
|
|
219
|
+
|
|
220
|
+
Tidak boleh menyimpulkan “B menyebabkan A” hanya karena `B.eventSeq > A.eventSeq`.
|
|
221
|
+
Tool paralel boleh tiba/selesai dalam urutan berbeda; setiap call tetap punya ID dan
|
|
222
|
+
duration sendiri.
|
|
223
|
+
|
|
224
|
+
## 6. Durable versus live
|
|
225
|
+
|
|
226
|
+
| Kategori | Contoh | Simpan | Rebuild |
|
|
227
|
+
|---|---|---|---|
|
|
228
|
+
| Lifecycle | task/tool terminal, approval | ya | ya |
|
|
229
|
+
| Final semantic content | message, result, plan, finding | ya | ya |
|
|
230
|
+
| Evidence ringkas | receipt, test summary, checkpoint | ya | ya |
|
|
231
|
+
| Live stream | model/reasoning delta, progress | tidak | tidak diperlukan |
|
|
232
|
+
| Derived heartbeat | spinner, elapsed tick | tidak | dihitung dari timestamp |
|
|
233
|
+
| Large content | tool output penuh | ref/store best effort | resolver bila tersedia |
|
|
234
|
+
|
|
235
|
+
`eventSeq` boleh dipotong pada delta, tetapi harus tetap menghasilkan replay yang
|
|
236
|
+
deterministik untuk event durable. Rebuild tidak boleh memerlukan token-by-token history.
|
|
237
|
+
|
|
238
|
+
## 7. Trust dan sanitasi
|
|
239
|
+
|
|
240
|
+
- Event internal boleh menyimpan diagnostic context, tetapi payload machine/wire harus
|
|
241
|
+
melalui `scrubSecrets()` dan JSON-safe encoding.
|
|
242
|
+
- Nama tool, path, command, provider label, dan output model adalah untrusted display
|
|
243
|
+
data. Sanitasi control sequence dilakukan di boundary ingestion atau projection,
|
|
244
|
+
bukan hanya di satu renderer.
|
|
245
|
+
- `NO_COLOR` dan non-TTY berarti SGR tidak boleh menjadi makna. Status tetap punya
|
|
246
|
+
glyph + kata atau struktur teks.
|
|
247
|
+
- Selection/copy payload berasal dari source map yang sudah disanitasi; tidak boleh
|
|
248
|
+
menyalin escape, padding, atau border tabel.
|
|
249
|
+
- Event diagnostic internal default `debug`; warning yang actionable default
|
|
250
|
+
`normal`; payload mentah default `debug/machine` dengan scrub.
|
|
251
|
+
|
|
252
|
+
Phase 2 now wires producers for `reasoning.completed`, `plan.updated`,
|
|
253
|
+
`finding.detected`, `result.produced`, `diagnostic.raised`, `test.completed`, and
|
|
254
|
+
`checkpoint.created`. Only `tool.progress` remains proposed because it is
|
|
255
|
+
intentionally live-only.
|
|
256
|
+
|
|
257
|
+
## 8. Invariant
|
|
258
|
+
|
|
259
|
+
- I-A01: renderer tidak memiliki kebenaran runtime maupun presentation.
|
|
260
|
+
- I-A02: setiap execution user-visible membawa `toolCallId` stabil end-to-end.
|
|
261
|
+
- I-A03: setiap tool terminal memiliki tepat satu final status.
|
|
262
|
+
- I-A04: state tidak menyimpan terminal geometry, timer, widget, atau payload besar.
|
|
263
|
+
- I-A05: reducer murni; event yang sama menghasilkan state yang sama.
|
|
264
|
+
- I-A06: payload besar selalu `ContentRef` dan evict selalu ber-marker.
|
|
265
|
+
- I-A07: retry adalah call baru dengan link `supersedes`, bukan attempt ID buatan.
|
|
266
|
+
- I-A08: approval tidak boleh tetap requested setelah parent settle/rebuild.
|
|
267
|
+
- I-A09: causality hanya melalui link eksplisit.
|
|
268
|
+
- I-A10: TUI/linear/exec/ACP memakai status, identity, duration, cause, receipt, dan
|
|
269
|
+
lifecycle yang sama.
|
|
270
|
+
- I-A11: context compaction tidak menghapus presentation history.
|
|
271
|
+
- I-A12: `interrupted`, `failed`, dan `cancelled` eksplisit berbeda.
|
|
272
|
+
|
|
273
|
+
## 9. Status migrasi dari implementasi sekarang
|
|
274
|
+
|
|
275
|
+
| Implementasi sekarang | Target event | Migrasi |
|
|
276
|
+
|---|---|---|
|
|
277
|
+
| `turn:started` | `task.started` | adapter map, pertahankan turn ID |
|
|
278
|
+
| `turn:completed` | `task.completed` | tambahkan summary/receipt-derived fields |
|
|
279
|
+
| `noteRunSettled` | `task.failed/cancelled` | jadikan satu settlement path |
|
|
280
|
+
| `provider:text` | `assistant.message.delta` | stream policy di projection |
|
|
281
|
+
| `TurnResult.finalText` | `assistant.message.completed` | event final eksplisit |
|
|
282
|
+
| `execution:*` | `tool.*` | normalisasi di adapter |
|
|
283
|
+
| permission hooks | `approval.requested/settled` | outcome enum tunggal |
|
|
284
|
+
| journal callback | `file.changed` | link ke activity/turn |
|
|
285
|
+
| `tool.progress` | `tool.progress` | optional live-only, jangan durable |
|
|
286
|
+
| `context:compacted` | `context.compacted` | system entry, bukan compaction history |
|
|
287
|
+
|
|
288
|
+
Selama migrasi, raw event tetap boleh dibaca untuk diagnostics; setiap surface
|
|
289
|
+
user-facing baru harus berasal dari canonical projection.
|
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
# Output Architecture Implementation Plan
|
|
2
|
+
|
|
3
|
+
**Status:** Phase 1–8 landed; canonical presentation policy is active on all user-facing surfaces. Legacy ACP `type:"tool"` remains a compatibility window.
|
|
4
|
+
**Tanggal:** 2026-09-25
|
|
5
|
+
**Related:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`, `docs/OUTPUT_EVENT_MODEL.md`, `docs/OUTPUT_PROTOCOL_SPEC.md`, `docs/OUTPUT_RENDERING_SPEC.md`, `docs/OUTPUT_UX_RULES.md`
|
|
6
|
+
|
|
7
|
+
## 1. Keputusan
|
|
8
|
+
|
|
9
|
+
Migrasi bersifat incremental dan dapat dibalik:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
raw runtime events
|
|
13
|
+
→ canonical semantic events
|
|
14
|
+
→ pure PresentationState
|
|
15
|
+
→ policy projection
|
|
16
|
+
→ TUI / linear / exec / ACP
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Tidak melakukan rewrite `vendor/minicore/**`, tidak mengganti terminal primitives,
|
|
20
|
+
dan tidak menghapus jalur lama sebelum parity contract serta satu rollout flag-on
|
|
21
|
+
terbukti.
|
|
22
|
+
|
|
23
|
+
## 2. Baseline saat plan dibuat
|
|
24
|
+
|
|
25
|
+
- Mouse wheel/drag app-level selection, `/copy [n]`, Esc-only abort, popup lifecycle,
|
|
26
|
+
sanitasi, width, and terminal ownership are already implemented in the working tree.
|
|
27
|
+
- Current baseline after Phase 2–8: 2587 pass, 22 skip, 0 fail; coverage 84.52% funcs /
|
|
28
|
+
85.53% lines; pack 23/23; web build/check pass.
|
|
29
|
+
- `PresentationAdapter`/reducer drive all user-facing surfaces through the
|
|
30
|
+
canonical state; raw ledger TUI and the rollback flag were removed in Phase 8.
|
|
31
|
+
- `rebuildFromDurable()` is production-wired from the durable presentation event
|
|
32
|
+
table, with child-session event persistence and interrupted-state recovery.
|
|
33
|
+
- The pack size guard is 3.5 MiB (re-baselined from 2.25 MiB with owner approval in Quality Remediation Stage 8.1, because the runtime payload itself grew past the old 2.25 MiB line — see `scripts/pack-budget.ts` for the measurement basis): six required audit artifacts add about 80 KB; the guard still rejects forbidden runtime/test content and accidental dependency inclusion.
|
|
34
|
+
- OAP-001, OAP-002, OAP-004–OAP-010, OAP-012, and OAP-013 remain carried forward;
|
|
35
|
+
Phase 2 closes the state/receipt/replay slice, not renderer migration.
|
|
36
|
+
|
|
37
|
+
## 3. Hasil Phase 1
|
|
38
|
+
|
|
39
|
+
- `user.message` sekarang durable di `DomainEvent` dan direduksi ke
|
|
40
|
+
`ConversationEntry` tanpa menggandakan turn.
|
|
41
|
+
- `toPresentationEvent()` di `cli/setup.ts` memetakan seluruh 20
|
|
42
|
+
`DomainEventType`, termasuk model/reasoning/file/test/context/progress.
|
|
43
|
+
- `PROPOSED_EVENT_TYPES` menandai `reasoning.completed`, `tool.progress`, dan
|
|
44
|
+
`test.completed` sebagai event tanpa producer; mapper tidak mengarangnya.
|
|
45
|
+
- `unsupportedProjection` diagnostics dan fixture exhaustive menjaga bridge
|
|
46
|
+
agar event baru tidak diam-diam dropped.
|
|
47
|
+
- Historical Phase 1 snapshot: 2581 pass / 22 skip / 0 fail. At that point the
|
|
48
|
+
renderer still used the raw bus and Phase 4 had not started.
|
|
49
|
+
|
|
50
|
+
## 3.1 Hasil Phase 2 core
|
|
51
|
+
|
|
52
|
+
- `PresentationState` sekarang memiliki collection conversation, reasoning, system,
|
|
53
|
+
plan, finding, result, diagnostic, serta marker eviction bounded.
|
|
54
|
+
- `deriveTurnSummary()` menghitung status tool, unique normalized paths, test
|
|
55
|
+
aggregate, checkpoint, duration dari timestamp, dan late evidence tanpa clock/IO.
|
|
56
|
+
- `file.changed`/`test.completed` yang tiba sebelum atau sesudah activity terminal
|
|
57
|
+
tetap masuk sebagai evidence; checkpoint callback sekarang memancarkan
|
|
58
|
+
`checkpoint.created` semantic event.
|
|
59
|
+
- `presentation_events` SQLite table menyimpan durable event idempotent, scrubbed,
|
|
60
|
+
dan TERMINAL/branch/TTL/delete-aware; setup memuat dan rebuild-nya sebelum
|
|
61
|
+
adapter-seq baru dibuat.
|
|
62
|
+
- Historical migration detail: before Phase 8,
|
|
63
|
+
`MINICODE_PRESENTATION_V2=0` disabled shadow projection/replay while the raw
|
|
64
|
+
content stream remained available. Child sessions also wrote their own
|
|
65
|
+
semantic event log.
|
|
66
|
+
- Regression tests: semantic collections, summary late evidence, cross-session
|
|
67
|
+
identity, bounded eviction, persistence idempotency/scrubbing, checkpoint bridge,
|
|
68
|
+
adapter provider, branch/child/delete/TTL lifecycle, dan resume rebuild.
|
|
69
|
+
- Setiap event terminal kini memakai `eventSeq` unik; basis bersama sebelumnya
|
|
70
|
+
membuat `INSERT OR IGNORE` durable melewatkan event berikutnya.
|
|
71
|
+
- Phase 2 parity landed: contract restart/child/resume/branch/delete/TTL diuji;
|
|
72
|
+
`finding.detected` terbit dari `result.findings` eksplisit pada
|
|
73
|
+
`submit_result`; `test.completed` hanya terbit dari verify output yang memiliki
|
|
74
|
+
hitungan pass/fail terstruktur.
|
|
75
|
+
|
|
76
|
+
## 3.2 Hasil Phase 3–8
|
|
77
|
+
|
|
78
|
+
- Phase 3: modul policy murni `src/presentation/projection.ts` (seleksi node per
|
|
79
|
+
mode, deskripsi activity/turn, running pin + ambang elapsed, envelope
|
|
80
|
+
`minicode.output.v1`, kategori error machine, digest divergensi) + 14 test
|
|
81
|
+
policy tabel-driven.
|
|
82
|
+
- Phase 4/5: TUI dan linear memakai keputusan policy via injeksi `cli/`
|
|
83
|
+
(`PresentationPolicy`); parity test policy-vs-legacy identik; label turn-status
|
|
84
|
+
via `activityFor`; test inventaris writer OAP-008.
|
|
85
|
+
- Phase 6: `exec --json` streaming envelope kanonik + summary berversi + setup
|
|
86
|
+
failure selalu ber-envelope; ACP lifecycle penuh + cancel terminal + persist
|
|
87
|
+
headless; sanitasi ANSI + scrub di tepi mesin.
|
|
88
|
+
- Phase 7: `persistCurrent` di jalur headless exec/ACP; resume notice tetap
|
|
89
|
+
stderr mesin-aman; ambang coverage naik ke 84/85.
|
|
90
|
+
- Phase 8: rollback flag dihapus, raw ledger TUI + `targetForFallback` dihapus
|
|
91
|
+
(3 test dimigrasi ke event presentasi); legacy `type:"tool"` ACP dipertahankan
|
|
92
|
+
satu jendela kompat; queue durable dibatasi, result generic diringkas, dan
|
|
93
|
+
buffer/render TUI dibatasi; full gate hijau.
|
|
94
|
+
|
|
95
|
+
## 4. Fase migrasi
|
|
96
|
+
|
|
97
|
+
Every phase has a rollback boundary. A phase is complete only when its tests and
|
|
98
|
+
the repository gates are green.
|
|
99
|
+
|
|
100
|
+
### Phase 0 — Baseline and contract lock
|
|
101
|
+
|
|
102
|
+
**Goal:** make the current behavior measurable before changing its source.
|
|
103
|
+
|
|
104
|
+
**Files/modules:** `test/presentation-*.test.ts`, `test/tui-*.test.ts`,
|
|
105
|
+
`test/acp.test.ts`, `test/exec-json-envelope.test.ts`, `test/pty.test.ts`,
|
|
106
|
+
`docs/TERMINAL_CONTRACT.md`.
|
|
107
|
+
|
|
108
|
+
**Dependencies:** none.
|
|
109
|
+
|
|
110
|
+
**Behavior changes:** none.
|
|
111
|
+
|
|
112
|
+
**Risks:** flaky fake TTY/ConPTY tests may hide platform-specific output drift.
|
|
113
|
+
|
|
114
|
+
**Tests/gates:** capture golden fixtures for normal/verbose/exec/ACP; run full test,
|
|
115
|
+
coverage, pack, and web check; record skip reasons explicitly.
|
|
116
|
+
|
|
117
|
+
**Migration/rollback:** documentation/test-only; revert isolated fixture commit if
|
|
118
|
+
fixture is unstable.
|
|
119
|
+
|
|
120
|
+
### Phase 1 — Canonical event boundary and exhaustive projection
|
|
121
|
+
|
|
122
|
+
**Goal:** make all semantic events explicit and stop silent bridge drops.
|
|
123
|
+
|
|
124
|
+
**Files/modules:** `src/presentation/events.ts`, `src/presentation/adapter.ts`,
|
|
125
|
+
`src/ui/contract.ts`, `cli/setup.ts`; approval hooks in
|
|
126
|
+
`src/ui/approval/prompt.ts` and policy path only as needed.
|
|
127
|
+
|
|
128
|
+
**Dependencies:** OAP-002/OAP-003 decisions; preserve raw event compatibility.
|
|
129
|
+
|
|
130
|
+
**Behavior changes:** add `user.message`, `reasoning.completed`, file/test/context/
|
|
131
|
+
diagnostic projection where a real producer exists; retain current raw event names
|
|
132
|
+
during migration. Missing producer events are marked proposed, not fabricated.
|
|
133
|
+
|
|
134
|
+
**Risks:** double-emission if adapter and existing sinks both publish terminal lines;
|
|
135
|
+
exhaustive mapper may expose existing anomalies.
|
|
136
|
+
|
|
137
|
+
**Tests/gates:** every DomainEvent has producer-or-proposed status; every event type
|
|
138
|
+
has a consumer/projection test; duplicate/late/out-of-order fixtures; no throw from
|
|
139
|
+
mapper.
|
|
140
|
+
|
|
141
|
+
**Migration/rollback:** flag and raw TUI ledger were removed in Phase 8; the
|
|
142
|
+
runtime EventBus remains only for streaming content and debug/trace transport.
|
|
143
|
+
|
|
144
|
+
### Phase 2 — Complete presentation state and truthful summaries
|
|
145
|
+
|
|
146
|
+
**Status:** landed; state/reducer is replayable and renderer authority is wired.
|
|
147
|
+
|
|
148
|
+
**Goal:** make `PresentationState` a replayable semantic model, not a partial index.
|
|
149
|
+
|
|
150
|
+
**Files/modules:** `src/presentation/model.ts`, `reducer.ts`, `store.ts`,
|
|
151
|
+
`label.ts`, `adapter.ts`, `src/tools/submit_result.ts`, journal/checkpoint
|
|
152
|
+
adapters in `cli/setup.ts`, dan child wiring di `cli/index.ts`.
|
|
153
|
+
|
|
154
|
+
**Dependencies:** Phase 1; durable store format.
|
|
155
|
+
|
|
156
|
+
**Behavior changes:** add user/conversation, reasoning, system, plan, finding, result,
|
|
157
|
+
and diagnostic collections; compute `filesChanged`, receipts, test summary, and
|
|
158
|
+
checkpoint from events/journal rather than constants.
|
|
159
|
+
|
|
160
|
+
**Risks:** increased memory and migration of `/expand`/copy semantics; payload cap must
|
|
161
|
+
remain explicit.
|
|
162
|
+
|
|
163
|
+
**Tests/gates:** replay durable == live minus deltas; state bounded; evict marker;
|
|
164
|
+
receipt counts truthful; restart test from session/journal evidence; reducer purity
|
|
165
|
+
and no clock/IO grep.
|
|
166
|
+
|
|
167
|
+
**Migration/rollback:** keep old `getPresentationSnapshot()` output as a compatibility
|
|
168
|
+
adapter until all consumers pass.
|
|
169
|
+
|
|
170
|
+
### Phase 3 — Shared projection policy
|
|
171
|
+
|
|
172
|
+
**Status:** landed (`src/presentation/projection.ts` + `test/presentation-policy.test.ts` + parity harness TUI/linear).
|
|
173
|
+
|
|
174
|
+
**Goal:** one state to normal/verbose/debug/machine projections.
|
|
175
|
+
|
|
176
|
+
**Files/modules:** new pure projection module under `src/presentation/`, label/format
|
|
177
|
+
boundaries; no import from `src/ui` into `src/presentation`.
|
|
178
|
+
|
|
179
|
+
**Dependencies:** Phase 2; i18n keys and status vocabulary.
|
|
180
|
+
|
|
181
|
+
**Behavior changes:** visual verbosity and disclosure become policy decisions; TUI
|
|
182
|
+
layout, linear wrapping, and machine JSON remain different renderers but share
|
|
183
|
+
semantic node selection.
|
|
184
|
+
|
|
185
|
+
**Risks:** normal output becoming too sparse or verbose output becoming noisy.
|
|
186
|
+
|
|
187
|
+
**Tests/gates:** table-driven node policy tests; normal/verbose/debug/machine
|
|
188
|
+
snapshots; semantic parity assertions; no renderer status parsing.
|
|
189
|
+
|
|
190
|
+
**Migration/rollback:** projection ran beside the legacy path during rollout and
|
|
191
|
+
reported divergence; Phase 8 removed the rollout seam after parity.
|
|
192
|
+
|
|
193
|
+
### Phase 4 — TUI projection (completed rollout)
|
|
194
|
+
|
|
195
|
+
**Status:** landed (policy di-inject via `cli/tui.ts`; raw TUI ledger and its rollback path were removed in Phase 8; parity tests remain as regression protection).
|
|
196
|
+
|
|
197
|
+
**Goal:** move TUI transcript/activity/selection to canonical state without breaking
|
|
198
|
+
current screen ownership.
|
|
199
|
+
|
|
200
|
+
**Files/modules:** `src/ui/tui/transcript.ts`, `src/ui/tui/app.ts`,
|
|
201
|
+
`src/ui/runtime/screen.ts` only where lifecycle wiring needs an explicit snapshot;
|
|
202
|
+
`cli/tui.ts` composition.
|
|
203
|
+
|
|
204
|
+
**Dependencies:** Phases 1–3; current selection/source-map tests; frozen terminal
|
|
205
|
+
contract.
|
|
206
|
+
|
|
207
|
+
**Behavior changes:** canonical terminal activity, summary, error, reasoning state;
|
|
208
|
+
existing transcript cap, evict marker, prompt/footer geometry, popup, wheel, drag,
|
|
209
|
+
Ctrl+C, Esc, and busy rules remain unchanged.
|
|
210
|
+
|
|
211
|
+
**Risks:** live deltas may arrive before durable model completion; selection anchors
|
|
212
|
+
can be evicted; resize may re-render different text source.
|
|
213
|
+
|
|
214
|
+
**Tests/gates:** existing TUI tests plus canonical-vs-legacy fixture; stream+resize+
|
|
215
|
+
abort+popup+selection fuzz; PTY on POSIX; transparent ConPTY skip.
|
|
216
|
+
|
|
217
|
+
**Migration/rollback:** the rollout flag was removed in Phase 8 after the parity
|
|
218
|
+
gate and release 0.12.0.
|
|
219
|
+
|
|
220
|
+
### Phase 5 — Linear/one-shot projection and writer policy
|
|
221
|
+
|
|
222
|
+
**Status:** landed (keputusan status/suffix linear dari policy; `turn-status` label via `activityFor` DI; `test/writer-inventory.test.ts` mengunci OAP-008).
|
|
223
|
+
|
|
224
|
+
**Goal:** remove semantic decisions from `simple.ts` while preserving stdout/stderr
|
|
225
|
+
behavior and copy contents.
|
|
226
|
+
|
|
227
|
+
**Files/modules:** `src/ui/assistant/simple.ts`, `turn-status.ts`,
|
|
228
|
+
`src/ui/runtime/statusline.ts`, approval/command controllers, `cli/commands.ts`.
|
|
229
|
+
|
|
230
|
+
**Dependencies:** Phase 3; stream ownership inventory; i18n/table/selection contract.
|
|
231
|
+
|
|
232
|
+
**Behavior changes:** activity, error, summary, reasoning, and table disclosure from
|
|
233
|
+
projection; writer category decides stdout/stderr/transient.
|
|
234
|
+
|
|
235
|
+
**Risks:** duplicate ledger lines, reasoning duplication, non-TTY SGR regression,
|
|
236
|
+
answer `/copy` mismatch, direct console output from builtin commands.
|
|
237
|
+
|
|
238
|
+
**Tests/gates:** normal/verbose text fixtures, `NO_COLOR`, non-TTY, split stream,
|
|
239
|
+
abort/EOF, copy equivalence, table parity, direct-writer guard.
|
|
240
|
+
|
|
241
|
+
**Migration/rollback:** the rollout flag was removed after the parity gate in
|
|
242
|
+
Phase 8; raw handlers remain only where they carry streaming content, not
|
|
243
|
+
semantic status decisions.
|
|
244
|
+
|
|
245
|
+
### Phase 6 — Exec and ACP machine projection
|
|
246
|
+
|
|
247
|
+
**Status:** landed (`exec --json` = envelope `minicode.output.v1` + summary berversi; ACP lifecycle penuh + cancel terminal + persist headless; legacy `type:"tool"` hanya bila lifecycle absen).
|
|
248
|
+
|
|
249
|
+
**Goal:** give CI/IDE consumers a stable semantic protocol.
|
|
250
|
+
|
|
251
|
+
**Files/modules:** `cli/commands/exec.ts`, `cli/commands/acp.ts`,
|
|
252
|
+
`src/ui/contract.ts`, `src/presentation/` machine mapper, `src/policy/scrub.ts` use.
|
|
253
|
+
|
|
254
|
+
**Dependencies:** Phase 1 event envelope; Phase 2 snapshots; protocol spec.
|
|
255
|
+
|
|
256
|
+
**Behavior changes:** versioned `minicode.output.v1`; canonical lifecycle in exec/ACP;
|
|
257
|
+
human semantic raw event output is debug-only while text deltas remain a transport;
|
|
258
|
+
setup failure always emits terminal machine summary; ACP cancel/shutdown guarantees
|
|
259
|
+
explicit terminal response.
|
|
260
|
+
|
|
261
|
+
**Risks:** breaking existing integrations; duplicate text/lifecycle records; scrub
|
|
262
|
+
changes alter payload shape.
|
|
263
|
+
|
|
264
|
+
**Tests/gates:** wire-level JSON/ACP fixtures, malformed input, setup failure, cancel
|
|
265
|
+
race, shutdown race, secret/control-byte scrub, no ANSI/stdout contamination, exit
|
|
266
|
+
codes 0/1/2.
|
|
267
|
+
|
|
268
|
+
**Migration/rollback:** support legacy event names for one compatibility window;
|
|
269
|
+
switch machine flag independently from TUI/linear only if contract tests allow.
|
|
270
|
+
|
|
271
|
+
### Phase 7 — Durable resume and legacy direct-writer migration
|
|
272
|
+
|
|
273
|
+
**Status:** landed (`persistCurrent` di jalur headless exec/ACP; setup-failure selalu ber-envelope; writer inventory test; resume notice tetap stderr mesin-aman).
|
|
274
|
+
|
|
275
|
+
**Goal:** make crash/restart observable through the same semantic model and centralize
|
|
276
|
+
permanent/diagnostic writer categories.
|
|
277
|
+
|
|
278
|
+
**Files/modules:** `session/persistence`, `session/journal`, `turn-marker`,
|
|
279
|
+
`checkpoint`, `cli/setup.ts`, CLI controllers, popup/form/input fallbacks.
|
|
280
|
+
|
|
281
|
+
**Dependencies:** Phase 2; chosen durable event format; no changes to kernel vendor.
|
|
282
|
+
|
|
283
|
+
**Behavior changes:** resume rebuilds state; interrupted/partial markers visible;
|
|
284
|
+
new direct writes require category/owner.
|
|
285
|
+
|
|
286
|
+
**Risks:** migration from existing session files; old sessions lack event metadata;
|
|
287
|
+
foreign stderr writer compatibility.
|
|
288
|
+
|
|
289
|
+
**Tests/gates:** crash marker + pending journal + resume; exit/signal cleanup; writer
|
|
290
|
+
inventory test; machine/non-TTY safety.
|
|
291
|
+
|
|
292
|
+
**Migration/rollback:** old session path remains fallback; disable only new writer
|
|
293
|
+
route, not persistence.
|
|
294
|
+
|
|
295
|
+
### Phase 8 — Shadow removal and cleanup
|
|
296
|
+
|
|
297
|
+
**Status:** landed — flag `MINICODE_PRESENTATION_V2` dihapus, raw ledger TUI dihapus (migrasi 3 test ke event presentasi), parity policy-vs-legacy tetap hijau; legacy `type:"tool"` ACP dipertahankan satu jendela kompat.
|
|
298
|
+
|
|
299
|
+
**Goal:** after rollout, eliminate duplicate truth and dead paths.
|
|
300
|
+
|
|
301
|
+
**Files/modules:** remove raw presentation subscriptions from user-facing surfaces,
|
|
302
|
+
retire legacy label/collapse/diagnostic classification only after usage inventory.
|
|
303
|
+
|
|
304
|
+
**Dependencies:** one release or equivalent validated rollout; all gates green.
|
|
305
|
+
|
|
306
|
+
**Behavior changes:** output remains same as canonical projection; direct diagnostic
|
|
307
|
+
fallback only for explicitly external writers.
|
|
308
|
+
|
|
309
|
+
**Risks:** hidden consumers or scripts relying on legacy raw output.
|
|
310
|
+
|
|
311
|
+
**Tests/gates:** full suite, PTY, protocol compatibility fixtures, `git diff --check`,
|
|
312
|
+
architecture/UI boundary tests, pack/web checks.
|
|
313
|
+
|
|
314
|
+
**Migration/rollback:** revert the isolated removal commit; do not combine cleanup with
|
|
315
|
+
semantic changes.
|
|
316
|
+
|
|
317
|
+
## 5. Finding-to-phase map
|
|
318
|
+
|
|
319
|
+
| Finding | Primary phase | Secondary gate |
|
|
320
|
+
|---|---:|---|
|
|
321
|
+
| OAP-001 dual truth | 1–4 | parity fixtures |
|
|
322
|
+
| OAP-002 lifecycle loss | 1 | adapter failure/cancel tests |
|
|
323
|
+
| OAP-003 partial bridge | 1 | exhaustive projection test |
|
|
324
|
+
| OAP-004 incomplete model | 2 | replay/model tests |
|
|
325
|
+
| OAP-005 summary/receipt | 2 | journal/checkpoint test |
|
|
326
|
+
| OAP-006 machine protocol | 6 | wire contract |
|
|
327
|
+
| OAP-007 durable rebuild | 7 | resume/crash test |
|
|
328
|
+
| OAP-008 direct writers | 5/7 | writer inventory |
|
|
329
|
+
| OAP-009 visibility | 3 | mode fixtures |
|
|
330
|
+
| OAP-010 classification | 1/3 | canonical outcome tests |
|
|
331
|
+
| OAP-011 unused vocabulary | 1 | producer inventory |
|
|
332
|
+
| OAP-012 user/plan/finding | 2/3 | semantic node tests |
|
|
333
|
+
| OAP-013 docs drift | 0/10 | docs link/protection test |
|
|
334
|
+
|
|
335
|
+
## 6. Validation scenarios
|
|
336
|
+
|
|
337
|
+
| # | Scenario | Required verification |
|
|
338
|
+
|---:|---|---|
|
|
339
|
+
| 1 | Simple coding task | one final message, no duplicate completion, machine summary |
|
|
340
|
+
| 2 | Multi-file edit | receipt paths, truthful file count, chronological order |
|
|
341
|
+
| 3 | Tool success | tool completed + duration + expand ref |
|
|
342
|
+
| 4 | Tool failure | failed cause/hint, no generic success |
|
|
343
|
+
| 5 | Permission denial | denied category/reason, headless explicit |
|
|
344
|
+
| 6 | Cancellation | task/tool cancelled, stream flushed/discarded once |
|
|
345
|
+
| 7 | Retry | new call + deterministic supersedes relation |
|
|
346
|
+
| 8 | Long-running task | active state, elapsed, no fake spam |
|
|
347
|
+
| 9 | Parallel analysis | grouped/aggregated, independent IDs |
|
|
348
|
+
| 10 | Large tool output | cap marker, content ref, expand behavior |
|
|
349
|
+
| 11 | Narrow terminal | 20/30/80 columns, no overflow, cursor safe |
|
|
350
|
+
| 12 | Resize | 120→30→80, transcript/source mapping stable |
|
|
351
|
+
| 13 | Ctrl+C | TUI copy-or-noop, Esc cancellation, raw cleanup |
|
|
352
|
+
| 14 | No-color/limited ANSI | status words, ASCII fallback, no meaning loss |
|
|
353
|
+
| 15 | Verbose | useful detail without internal dump |
|
|
354
|
+
| 16 | Debug | scrubbed IDs/payloads and anomaly counters |
|
|
355
|
+
| 17 | Machine-readable | versioned NDJSON/ACP, no human stream contamination |
|
|
356
|
+
|
|
357
|
+
For every scenario verify semantic correctness, hierarchy, scrollback, error clarity,
|
|
358
|
+
noise, copyability, and mode consistency.
|
|
359
|
+
|
|
360
|
+
## 7. Rollout and rollback
|
|
361
|
+
|
|
362
|
+
- The rollout is complete: policy is injected at the composition root, raw TUI
|
|
363
|
+
semantic ledger and the feature flag are removed, and streaming content remains
|
|
364
|
+
a transport concern.
|
|
365
|
+
- Before any future semantic cleanup, run the parity and writer-inventory gates;
|
|
366
|
+
do not reintroduce a second status authority.
|
|
367
|
+
- If a protocol field is consumed, preserve compatibility aliases for one window.
|
|
368
|
+
- Update `docs/TERMINAL_CONTRACT.md` only when observable terminal behavior changes;
|
|
369
|
+
update its test map in the same change.
|
|
370
|
+
- Update `docs/ARCHITECTURE.html` when structure/dependencies change.
|
|
371
|
+
|
|
372
|
+
## 8. Completion criteria
|
|
373
|
+
|
|
374
|
+
The architecture is complete only when:
|
|
375
|
+
|
|
376
|
+
- semantic events are independent from rendering;
|
|
377
|
+
- runtime state is not accidentally exposed as normal UI;
|
|
378
|
+
- normal/verbose/debug/machine projections use one model;
|
|
379
|
+
- findings, plans, activities, errors, and results are distinct;
|
|
380
|
+
- permission, cancellation, timeout, partial, and interrupted states are explicit;
|
|
381
|
+
- parallel work is aggregated;
|
|
382
|
+
- TUI scrollback, copy/paste, Windows, no-color, and resize contracts remain intact;
|
|
383
|
+
- machine output is structured and versioned;
|
|
384
|
+
- durable resume can rebuild semantic state;
|
|
385
|
+
- legacy direct-print paths are inventoried and removed only after parity;
|
|
386
|
+
- all mandatory repository gates pass.
|
|
387
|
+
|
|
388
|
+
## 9. Current next action
|
|
389
|
+
|
|
390
|
+
Phase 1–8 landed. The current follow-up is limited to documentation drift and
|
|
391
|
+
post-change validation; keep future cleanup isolated from semantic changes.
|