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,234 @@
1
+ // P2.12 — penemuan daemon: endpoint + lease kehidupan.
2
+ //
3
+ // Kenapa file, bukan registry terpusat: daemon adalah milik SATU workspace
4
+ // (`<cwd>/.minicode`), sama seperti sesinya. Registry lintas-workspace akan
5
+ // membuat sesi proyek A terlihat dari proyek B — kebocoran scope yang tak
6
+ // diminta siapa pun.
7
+ //
8
+ // Dua aturan keras:
9
+ // 1. PID BUKAN otoritas. PID dapat didaur ulang oleh OS; mencocokkan PID
10
+ // "masih hidup" = klaim yang bisa salah. PID dicatat untuk diagnosis
11
+ // manusia, TIDAK PERNAH untuk memutuskan.
12
+ // 2. Recency BUKAN liveness. File yang masih hangat bisa jadi milik proses
13
+ // yang baru saja crash. Status "alive" hanya boleh datang dari probe
14
+ // koneksi yang berhasil; lease segar hanya menghasilkan "suspect" —
15
+ // ada kandidat, belum terbukti.
16
+
17
+ import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"
18
+ import { resolve } from "node:path"
19
+ import { resolveLocalDbPath } from "../lib/db-path.ts"
20
+
21
+ export const ENDPOINT_FILE = "daemon-endpoint.json"
22
+ export const LEASE_FILE = "daemon-lease.json"
23
+
24
+ /** Lease dianggap basi bila lebih tua dari ini (heartbeat jauh lebih sering). */
25
+ export const LEASE_STALE_MS = 15_000
26
+
27
+ export interface DaemonEndpoint {
28
+ version: 1
29
+ port: number
30
+ host: string
31
+ /** Incarnation daemon — diputar setiap start; kembar = bukan milik kita. */
32
+ incarnation: string
33
+ startedAt: number
34
+ /** Label workspace (dibasuh) — diagnosis, bukan kunci keputusan. */
35
+ workspace: string
36
+ /**
37
+ * AKAR KEPERCAYAAN LOKAL (base64url, 32 byte acak).
38
+ *
39
+ * Daemon tak dapat menunggu "capability" dari klien yang belum terautentikasi
40
+ * — itu lingkaran. Jadi berkas endpoint (0600, di dalam `.minicode/` yang
41
+ * gitignored) menjadi sumber kepercayaan: siapa pun yang bisa membacanya
42
+ * berada di level akses yang sama dengan kepemilikan repo itu sendiri, dan
43
+ * dari situ ia MENERBITKAN capability bercakupan + ber-TTL.
44
+ *
45
+ * Konsekuensi yang disadari: secret ada di disk. Imbalannya: secret tidak
46
+ * pernah lewat IPC, capability yang beredar tetap terbatas cakupan dan
47
+ * waktu, dan restart memutar inkarnasi sehingga capability lama mati.
48
+ */
49
+ bootstrap: string
50
+ }
51
+
52
+ export interface DaemonLease {
53
+ version: 1
54
+ incarnation: string
55
+ /** Diagnosis manusia saja — TIDAK PERNAH jadi dasar keputusan. */
56
+ pid: number
57
+ updatedAt: number
58
+ }
59
+
60
+ export type DiscoveryStatus = "none" | "stale" | "suspect" | "foreign"
61
+
62
+ export interface DiscoveryResult {
63
+ status: DiscoveryStatus
64
+ endpoint: DaemonEndpoint | null
65
+ lease: DaemonLease | null
66
+ /** Alasan manusia (sanitasi) untuk status non-ok. */
67
+ reason?: string
68
+ endpointPath: string
69
+ leasePath: string
70
+ }
71
+
72
+ function endpointPath(cwd?: string): string {
73
+ return resolveLocalDbPath(ENDPOINT_FILE, cwd)
74
+ }
75
+
76
+ function leasePath(cwd?: string): string {
77
+ return resolveLocalDbPath(LEASE_FILE, cwd)
78
+ }
79
+
80
+ /** Tulis atomik (tmp + rename) supaya pembaca tak pernah melihat file separuh. */
81
+ function writeAtomic(path: string, value: unknown, mode = 0o600): void {
82
+ const tmp = `${path}.${process.pid}.tmp`
83
+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode })
84
+ renameSync(tmp, path)
85
+ }
86
+
87
+ export function writeEndpoint(ep: DaemonEndpoint, cwd?: string): string {
88
+ const p = endpointPath(cwd)
89
+ mkdirSync(resolve(p, ".."), { recursive: true, mode: 0o700 })
90
+ writeAtomic(p, ep, 0o600)
91
+ return p
92
+ }
93
+
94
+ export function readEndpoint(cwd?: string): DaemonEndpoint | null {
95
+ const p = endpointPath(cwd)
96
+ if (!existsSync(p)) return null
97
+ try {
98
+ const raw = JSON.parse(readFileSync(p, "utf8")) as DaemonEndpoint
99
+ if (
100
+ raw?.version !== 1 ||
101
+ typeof raw.port !== "number" ||
102
+ !Number.isInteger(raw.port) ||
103
+ raw.port <= 0 ||
104
+ raw.port > 65535 ||
105
+ typeof raw.incarnation !== "string" ||
106
+ raw.incarnation.length === 0 ||
107
+ typeof raw.bootstrap !== "string" ||
108
+ raw.bootstrap.length < 32
109
+ ) {
110
+ return null
111
+ }
112
+ return { ...raw, host: typeof raw.host === "string" ? raw.host : "127.0.0.1" }
113
+ } catch {
114
+ return null
115
+ }
116
+ }
117
+
118
+ export function writeLease(l: DaemonLease, cwd?: string): string {
119
+ const p = leasePath(cwd)
120
+ mkdirSync(resolve(p, ".."), { recursive: true, mode: 0o700 })
121
+ writeAtomic(p, l, 0o600)
122
+ return p
123
+ }
124
+
125
+ export function readLease(cwd?: string): DaemonLease | null {
126
+ const p = leasePath(cwd)
127
+ if (!existsSync(p)) return null
128
+ try {
129
+ const raw = JSON.parse(readFileSync(p, "utf8")) as DaemonLease
130
+ if (raw?.version !== 1 || typeof raw.incarnation !== "string") return null
131
+ if (typeof raw.updatedAt !== "number") return null
132
+ return { ...raw, pid: typeof raw.pid === "number" ? raw.pid : -1 }
133
+ } catch {
134
+ return null
135
+ }
136
+ }
137
+
138
+ /**
139
+ * Penemuan = kueri turunan (baca endpoint + lease) + penilaian kehidupan.
140
+ *
141
+ * Menghasilkan status, BUKAN boolean "ada/tidak": caller yang memutuskan
142
+ * "hidup" haruslah yang melakukan probe koneksi. Fungsi ini sengaja tak punya
143
+ * akses jaringan agar tidak bisa "membuktikan" kehidupan yang tak ia uji.
144
+ */
145
+ export function discover(cwd?: string, now = Date.now()): DiscoveryResult {
146
+ const endpointPathResolved = endpointPath(cwd)
147
+ const leasePathResolved = leasePath(cwd)
148
+ const endpoint = readEndpoint(cwd)
149
+ const lease = readLease(cwd)
150
+
151
+ if (!endpoint && !lease) {
152
+ return {
153
+ status: "none",
154
+ endpoint: null,
155
+ lease: null,
156
+ endpointPath: endpointPathResolved,
157
+ leasePath: leasePathResolved,
158
+ }
159
+ }
160
+ if (!endpoint) {
161
+ return {
162
+ status: "stale",
163
+ endpoint: null,
164
+ lease,
165
+ reason: "lease ada tanpa endpoint (daemon mati tak rapi)",
166
+ endpointPath: endpointPathResolved,
167
+ leasePath: leasePathResolved,
168
+ }
169
+ }
170
+ if (!lease) {
171
+ return {
172
+ status: "stale",
173
+ endpoint,
174
+ lease: null,
175
+ reason: "endpoint ada tanpa lease (belum pernah heartbeat)",
176
+ endpointPath: endpointPathResolved,
177
+ leasePath: leasePathResolved,
178
+ }
179
+ }
180
+ // Incarnation beda = file endpoint ditulis daemon lain, lease belum
181
+ // menyusul (atau sebaliknya) — dua "kepala" berbeda = keadaan tak konsisten,
182
+ // bukan daemon yang sehat.
183
+ if (lease.incarnation !== endpoint.incarnation) {
184
+ return {
185
+ status: "foreign",
186
+ endpoint,
187
+ lease,
188
+ reason: "incarnation endpoint != lease",
189
+ endpointPath: endpointPathResolved,
190
+ leasePath: leasePathResolved,
191
+ }
192
+ }
193
+ const age = now - lease.updatedAt
194
+ if (!Number.isFinite(age) || age > LEASE_STALE_MS) {
195
+ return {
196
+ status: "stale",
197
+ endpoint,
198
+ lease,
199
+ reason: `lease ${Math.round(age)}ms > ${LEASE_STALE_MS}ms (segarnya habis)`,
200
+ endpointPath: endpointPathResolved,
201
+ leasePath: leasePathResolved,
202
+ }
203
+ }
204
+ // Segar = kandidat. BUKAN "hidup" — caller wajib probe.
205
+ return {
206
+ status: "suspect",
207
+ endpoint,
208
+ lease,
209
+ endpointPath: endpointPathResolved,
210
+ leasePath: leasePathResolved,
211
+ }
212
+ }
213
+
214
+ /**
215
+ * Hapus endpoint/lease HANYA bila milik incarnation kita.
216
+ *
217
+ * Tanpa penguncian incarnation, daemon yang baru start bisa menghapus berkas
218
+ * milik penggantinya (atau sebaliknya) saat shutdown lambat — yang tersisa
219
+ * adalah daemon hidup tanpa penemuan, terlihat "mati" padahal jalan.
220
+ */
221
+ export function clearDiscovery(incarnation: string, cwd?: string): boolean {
222
+ let removed = 0
223
+ for (const p of [endpointPath(cwd), leasePath(cwd)]) {
224
+ try {
225
+ const raw = JSON.parse(readFileSync(p, "utf8")) as { incarnation?: string }
226
+ if (raw?.incarnation !== incarnation) continue
227
+ unlinkSync(p)
228
+ removed++
229
+ } catch {
230
+ // File sudah tak ada / tak terbaca — bukan kegagalan yang perlu dilaporkan.
231
+ }
232
+ }
233
+ return removed > 0
234
+ }
@@ -0,0 +1,155 @@
1
+ // P2.12 — sumber event per sesi untuk konsumen (snapshot + replay + live-tail).
2
+ //
3
+ // Kenapa sebuah antarmuka kecil: `CliSession` ada di `cli/` dan lapisan
4
+ // MELARANG `src/**` non-ui mengimpor `cli/`. Daemon boleh membaca toko durable
5
+ // dan memasang listener live, tetapi tidak boleh menarik tipe milik CLI. Yang
6
+ // daemon butuh hanya empat hal — kepala, frontier, baca rentang, langganan
7
+ // live — sehingga diwakili antarmuka sempit yang bisa diisi dari dua arah.
8
+
9
+ import type { DomainEvent } from "../presentation/events.ts"
10
+ import {
11
+ DEFAULT_THREAD_ID,
12
+ getActiveRun,
13
+ getThreadHead,
14
+ loadPresentationEventsRange,
15
+ messageHead,
16
+ presentationHead,
17
+ readWriterEpoch,
18
+ } from "../session/persistence.ts"
19
+ import type { Provenance, SessionFrontiers, SessionSnapshot } from "./protocol.ts"
20
+
21
+ /** Batas event dalam satu snapshot — memori daemon tak boleh ikut ukuran sesi. */
22
+ export const SNAPSHOT_EVENT_LIMIT = 400
23
+
24
+ /** Batas per halaman replay — konsumen minta lanjut bila masih kurang. */
25
+ export const REPLAY_PAGE_LIMIT = 200
26
+
27
+ export interface SessionFeed {
28
+ readonly sid: string
29
+ /** true bila daemon ini mem-host penulis sesi ini (bukan sekadar pembaca). */
30
+ readonly hosted: boolean
31
+ head(): number
32
+ frontiers(): SessionFrontiers
33
+ /** Baca durable dari `fromSeq` (inklusif), terbatas `limit`. */
34
+ readRange(
35
+ fromSeq: number,
36
+ limit: number,
37
+ ): { events: DomainEvent[]; rejected: number; head: number }
38
+ /** Pasang listener live; kembalikan fungsi lepas. Tak ada live bila !hosted. */
39
+ liveSubscribe(fn: (event: DomainEvent) => void): () => void
40
+ }
41
+
42
+ function durableFrontiers(sid: string, cwd?: string): SessionFrontiers {
43
+ const run = getActiveRun(sid, cwd)
44
+ return {
45
+ writerEpoch: readWriterEpoch(sid, cwd),
46
+ presentationHead: presentationHead(sid, cwd),
47
+ messageHead: messageHead(sid, cwd),
48
+ runId: run?.run_id ?? null,
49
+ runStatus: run?.status ?? null,
50
+ }
51
+ }
52
+
53
+ /**
54
+ * Feed baca-saja: sesi yang TIDAK di-host daemon ini (mis. sedang ditulis
55
+ * proses CLI lain). `liveSubscribe` sengaja no-op — berpura-pura dapat live
56
+ * dari sesi yang bukan milik kita akan membuat konsumen yakin ia melihat
57
+ * sesuatu yang padahal datang dari sumber yang salah.
58
+ */
59
+ export function createStoreFeed(sid: string, cwd?: string): SessionFeed {
60
+ return {
61
+ sid,
62
+ hosted: false,
63
+ head: () => presentationHead(sid, cwd),
64
+ frontiers: () => durableFrontiers(sid, cwd),
65
+ readRange: (fromSeq, limit) => loadPresentationEventsRange(sid, fromSeq, limit, cwd),
66
+ liveSubscribe: () => () => {},
67
+ }
68
+ }
69
+
70
+ export interface HostedFeedSource {
71
+ /** Kepala presentasi HIDUP (dari reducer sesi), bukan dari DB. */
72
+ head: () => number
73
+ frontiers: () => SessionFrontiers
74
+ /** Langganan live dari composition root (`onPresentationEvent`). */
75
+ subscribe: (fn: (event: DomainEvent) => void) => () => void
76
+ }
77
+
78
+ /**
79
+ * Feed sesi yang di-host daemon ini: baca durable untuk replay + langganan
80
+ * live untuk tail. Durable tetap dibaca dari toko (bukan dari memori sesi)
81
+ * supaya angka frontier yang dikirim konsumen = apa yang benar-benar durable.
82
+ */
83
+ export function createHostedFeed(sid: string, src: HostedFeedSource, cwd?: string): SessionFeed {
84
+ return {
85
+ sid,
86
+ hosted: true,
87
+ head: () => src.head(),
88
+ frontiers: () => src.frontiers(),
89
+ readRange: (fromSeq, limit) => loadPresentationEventsRange(sid, fromSeq, limit, cwd),
90
+ liveSubscribe: (fn) => src.subscribe(fn),
91
+ }
92
+ }
93
+
94
+ export interface SnapshotResult {
95
+ snapshot: SessionSnapshot
96
+ /** true bila ada baris tak lolos decode — konsumen HARUS diberi tahu. */
97
+ rejected: number
98
+ }
99
+
100
+ /**
101
+ * Susun snapshot. SENGAJA non-atomik antar toko (kontrak §): frontier diambil
102
+ * dari query terpisah dari baris presentasi, sehingga angka yang dikirim boleh
103
+ * saja satu langkah di depan/di belakang isi `presentation`.
104
+ *
105
+ * Yang dijanjikan hanyalah: setiap angka adalah hasil pembacaan yang jujur
106
+ * beserta provenance-nya. Yang DILARANG menyimpulkan: "snapshot ini = state
107
+ * sesi pada satu titik waktu tunggal" — tidak ada transaksi yang menjamin itu.
108
+ */
109
+ export function buildSnapshot(
110
+ feed: SessionFeed,
111
+ now = Date.now(),
112
+ precomputedFrontiers?: SessionFrontiers,
113
+ ): SnapshotResult {
114
+ // [Audit #2 C.F3] Terima frontier yang sudah dihitung pemanggil (mis.
115
+ // server.ts sudah mengambil feed.frontiers() untuk baris `frontiers`) agar tak
116
+ // menghitung dua kali.
117
+ const frontiers = precomputedFrontiers ?? feed.frontiers()
118
+ const head = feed.head()
119
+ const from = Math.max(0, head - SNAPSHOT_EVENT_LIMIT + 1)
120
+ const { events, rejected, head: durableHead } = feed.readRange(from, SNAPSHOT_EVENT_LIMIT)
121
+ return {
122
+ snapshot: {
123
+ sid: feed.sid,
124
+ // Frontier dan baris bisa berbeda langkah (non-atomik, by design):
125
+ // laporkan kepala durable terbaca supaya konsumen tahu isi `presentation`
126
+ // berhenti di mana, terpisah dari frontier yang lebih baru.
127
+ frontiers: {
128
+ ...frontiers,
129
+ presentationHead: Math.max(frontiers.presentationHead, durableHead),
130
+ },
131
+ presentation: events,
132
+ provenance: "REPLAY",
133
+ capturedAt: now,
134
+ },
135
+ rejected,
136
+ }
137
+ }
138
+
139
+ /**
140
+ * Provenance untuk satu baris replay. Selalu "REPLAY" — baris ini datang dari
141
+ * disk, bukan dari penulis hidup; menandainya LIVE akan membuat konsumen
142
+ * mencampur jalur observasi dan menarik kesimpulan "masih berjalan" dari data
143
+ * mati.
144
+ */
145
+ export const REPLAY_PROVENANCE: Provenance = "REPLAY"
146
+
147
+ export function defaultFrontiers(sid: string, cwd?: string): SessionFrontiers {
148
+ const base = durableFrontiers(sid, cwd)
149
+ // Kepala thread default ikut dilaporkan agar konsumen membedakan "sesi
150
+ // kosong" dari "sesi dengan thread lain yang sedang menulis".
151
+ return {
152
+ ...base,
153
+ messageHead: Math.max(base.messageHead, getThreadHead(sid, DEFAULT_THREAD_ID, cwd)),
154
+ }
155
+ }
@@ -0,0 +1,94 @@
1
+ // P2.12 — framing berpalang panjang untuk IPC loopback.
2
+ //
3
+ // Kenapa bukan newline-JSON: payload snapshot membawa riwayat presentasi yang
4
+ // boleh saja berisi `\n` di dalam string ter-escape maupun (bila salah escape)
5
+ // newline literal dari output model. Parser berbasis newline akan terpecah di
6
+ // tengah frame dan menyambung dua pesan jadi satu — klasik corruption yang
7
+ // berujung "event aneh" yang tak pernah bisa direproduksi. Palang 4 byte besar
8
+ // + ukuran eksplisit membuat pemisahan deterministik, dan batas `MAX_FRAME_BYTES`
9
+ // menutup jalur kehabisan memori dari peer yang mengirim header raksasa.
10
+
11
+ import { DAEMON_PROTOCOL, MAX_FRAME_BYTES } from "./protocol.ts"
12
+
13
+ /** Frame = [u32be length][utf8 json]. length = panjang payload, bukan total. */
14
+ export function encodeFrame(value: unknown): Buffer {
15
+ const body = Buffer.from(JSON.stringify(value), "utf8")
16
+ if (body.length > MAX_FRAME_BYTES) {
17
+ throw new FrameError("FRAME_TOO_LARGE", `frame ${body.length} > ${MAX_FRAME_BYTES}`)
18
+ }
19
+ const out = Buffer.allocUnsafe(4 + body.length)
20
+ out.writeUInt32BE(body.length, 0)
21
+ body.copy(out, 4)
22
+ return out
23
+ }
24
+
25
+ export class FrameError extends Error {
26
+ readonly code: string
27
+ constructor(code: string, message: string) {
28
+ // Kode ikut di pesan: pemanggil (dan pengujian) hanya punya teks error,
29
+ // dan "apa yang ditolak" harus terbaca tanpa harus menyimpan referensi
30
+ // ke instance pengecualian.
31
+ super(`${code}: ${message}`)
32
+ this.name = "FrameError"
33
+ this.code = code
34
+ }
35
+ }
36
+
37
+ /**
38
+ * Dekoder streaming. Satu instance per koneksi; `push()` menerima chunk bebas
39
+ * ukuran dan memuntahkan pesan utuh. Sengaja menyimpan sisa buffer MINIMAL
40
+ * (hanya byte yang belum jadi frame) — antrean terkendali ada di lapisan
41
+ * subscription, bukan di sini.
42
+ */
43
+ export class FrameDecoder {
44
+ #buf: Buffer = Buffer.alloc(0)
45
+
46
+ push(chunk: Buffer): unknown[] {
47
+ this.#buf = this.#buf.length === 0 ? chunk : Buffer.concat([this.#buf, chunk])
48
+ const out: unknown[] = []
49
+ for (;;) {
50
+ if (this.#buf.length < 4) break
51
+ const len = this.#buf.readUInt32BE(0)
52
+ if (len > MAX_FRAME_BYTES) {
53
+ this.#buf = Buffer.alloc(0)
54
+ throw new FrameError("FRAME_TOO_LARGE", `declared ${len} > ${MAX_FRAME_BYTES}`)
55
+ }
56
+ if (this.#buf.length < 4 + len) break
57
+ const body = this.#buf.subarray(4, 4 + len)
58
+ this.#buf = this.#buf.subarray(4 + len)
59
+ let parsed: unknown
60
+ try {
61
+ parsed = JSON.parse(body.toString("utf8"))
62
+ } catch {
63
+ throw new FrameError("BAD_JSON", "frame payload bukan JSON valid")
64
+ }
65
+ out.push(parsed)
66
+ }
67
+ // Pertahankan memori sekecil mungkin: buffer kosong tidak boleh menahan
68
+ // referensi ke chunk besar dari konsumen yang sudah diproses.
69
+ if (this.#buf.length === 0) this.#buf = Buffer.alloc(0)
70
+ return out
71
+ }
72
+
73
+ get pendingBytes(): number {
74
+ return this.#buf.length
75
+ }
76
+ }
77
+
78
+ /** Validasi kasar pesan masuk sebelum disentuh dispatcher. */
79
+ export function isRecord(v: unknown): v is Record<string, unknown> {
80
+ return typeof v === "object" && v !== null && !Array.isArray(v)
81
+ }
82
+
83
+ export function assertProtocol(hello: unknown): number {
84
+ if (!isRecord(hello) || typeof hello.protocol !== "number") {
85
+ throw new FrameError("PROTOCOL_ERROR", "hello.protocol wajib number")
86
+ }
87
+ if (hello.protocol !== DAEMON_PROTOCOL) {
88
+ throw new FrameError(
89
+ "PROTOCOL_ERROR",
90
+ `protocol ${hello.protocol} != ${DAEMON_PROTOCOL} (daemon menolak konsumen versi lain)`,
91
+ )
92
+ }
93
+ return hello.protocol
94
+ }