minicode-ai 0.11.1 → 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 +89 -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 -71
  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 +2 -2
  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 +52 -19
  184. package/src/ui/i18n/en.ts +58 -6
  185. package/src/ui/i18n/id.ts +58 -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 +507 -169
  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 -169
  221. package/docs/USAGE.md +0 -11
@@ -0,0 +1,632 @@
1
+ // M5 — Execution backend adapter: interface + kapabilitas jujur + 4 backend.
2
+ //
3
+ // Kenapa berkas ini ada (P1 ADR-001, M5): runtime harus membedakan "apa yang
4
+ // seharusnya terjadi" (semantik runtime) dari "apa yang fisiknya mungkin"
5
+ // (mekanisme backend) TANPA mengetahui detail OS/proses/sandbox. Sebelum M5,
6
+ // pengetahuan itu tersebar di tools/bash.ts, sandbox/*, code_run, MCP/LSP
7
+ // client — tiap jalur punya kill/wait implisit sendiri.
8
+ //
9
+ // BUKAN: Execution FSM (M8), supervisor/retry (M9), persistence (M11),
10
+ // recovery (M12), scheduler bridge (M13), capability engine (M6), DAG/remote/
11
+ // live-resume. Aturan yang dikunci (jangan dilonggarkan tanpa ADR baru):
12
+ // - A/B/C/D TIDAK PERNAH sinonim. A+B = jaminan semantik runtime; C =
13
+ // kontrak backend spesifik; D = hanya bila terbukti via wait+close.
14
+ // `cancel requested ≠ terminated ≠ physical death proven`.
15
+ // - Tanpa retry di mana pun pada lapis ini (M9 yang memiliki retry).
16
+ // - Backend tak membuat executionId (M1); handle `be_*` = namespace backend
17
+ // sendiri, opaque, non-user-controlled, bukan lifecycle authority.
18
+ // - Opaque handle: caller tak pernah memegang raw ChildProcess.
19
+ // - Sandbox shims membungkus runner existing run-to-completion; kill
20
+ // preemptif mid-flight = unsupported yang DINYATAKAN (jujur, sesuai evidence
21
+ // code_run: abort menghentikan penungguan, container bisa hidup sampai
22
+ // timeout runner). Jangan klaim D untuk container.
23
+ // - MCP/LSP/background-jobs TIDAK dibungkus di sini (lifecycle berbeda:
24
+ // closeAll/closeAllLsp tetap pemilik; background = tool scope, detached = M7).
25
+ // - Security parity: spawn SELALU via sanitizeSpawnEnv + resolveTrustedExecutable
26
+ // (F-23), sama seperti jalur existing. Tak ada pelonggaran guard.
27
+
28
+ import { type ChildProcess, spawn, spawnSync } from "node:child_process"
29
+ import { randomUUID } from "node:crypto"
30
+ import { resolveTrustedExecutable } from "../lib/trusted-exec.ts"
31
+ import { sanitizeSpawnEnv } from "../policy/scrub.ts"
32
+ import { dockerAvailable, runInDocker } from "../sandbox/docker.ts"
33
+ import { osSandboxAvailable, osSandboxTypeName, runInOsSandbox } from "../sandbox/os.ts"
34
+
35
+ /** Backend fisik yang dikenal M5. Remote = deferred (bukan P1). */
36
+ export type BackendKind = "host" | "docker" | "bwrap" | "seatbelt"
37
+
38
+ /** Tingkat klaim kapabilitas — deklarasi jujur berbasis evidence, bukan asumsi. */
39
+ export type GuaranteeLevel = "SUPPORTED" | "BEST_EFFORT" | "UNSUPPORTED" | "UNKNOWN"
40
+
41
+ /**
42
+ * B (logical execution stopped) BUKAN kapabilitas backend — ia adalah semantik
43
+ * runtime (Kernel M8). Backend tak pernah menentukan lifecycle logis Execution;
44
+ * ia hanya menyampaikan observasi fisik (cancel/termination requested, exited,
45
+ * proven-dead, timeout, vanished, unknown, orphan) yang nanti diinterpretasi
46
+ * runtime. Nilai tunggal ini mencegah B terisi SUPPORTED/BEST_EFFORT seolah
47
+ * backend punya lifecycle authority (FINAL QA: B != backend capability).
48
+ */
49
+ export type LogicalStopLevel = "DELEGATED_TO_RUNTIME"
50
+
51
+ export interface BackendCapability {
52
+ /** A = stop waiting (observasi/pembatalan penungguan yang didukung backend). */
53
+ readonly a: GuaranteeLevel
54
+ /** B = SELALU DELEGATED_TO_RUNTIME (bukan kapabilitas backend). */
55
+ readonly b: LogicalStopLevel
56
+ /** C = backend termination requested (permintaan terminasi backend). */
57
+ readonly c: GuaranteeLevel
58
+ /** D = physical termination proven (kematian fisik terbukti). */
59
+ readonly d: GuaranteeLevel
60
+ readonly cpu: GuaranteeLevel
61
+ readonly memory: GuaranteeLevel
62
+ readonly pid: GuaranteeLevel
63
+ readonly network: GuaranteeLevel
64
+ readonly fs: GuaranteeLevel
65
+ /** Bukti per-baris (file:line / perilaku teramati). */
66
+ readonly notes: readonly string[]
67
+ }
68
+
69
+ /**
70
+ * Matriks kapabilitas evidence-based (M5 §14). Dibaca dari invocation aktual,
71
+ * bukan dari nama teknologi:
72
+ * - host: killTree grup/taskkill ADA (bash.ts:96-124); tanpa flag CPU/mem/pids;
73
+ * network hanya guard; FS hanya jail pre-check (TOCTOU terdokumentasi).
74
+ * - docker: invocation --cpus/--memory/--pids-limit/--network/--read-only ADA
75
+ * (docker.ts:58-87); kill eksplisit container TAK ADA (hanya wrapper SIGKILL).
76
+ * - bwrap: --unshare-net/--die-with-parent/--cap-drop/bind ADA, tanpa limit
77
+ * CPU/mem/pids (os.ts:104-135). seatbelt: deny default + deny network* ADA,
78
+ * policy = restriksi BUKAN kill guarantee (os.ts:91-98).
79
+ */
80
+ export const BACKEND_CAPABILITIES: Record<BackendKind, BackendCapability> = {
81
+ host: {
82
+ a: "SUPPORTED",
83
+ b: "DELEGATED_TO_RUNTIME",
84
+ c: "SUPPORTED",
85
+ d: "BEST_EFFORT",
86
+ cpu: "UNSUPPORTED",
87
+ memory: "UNSUPPORTED",
88
+ pid: "UNSUPPORTED",
89
+ network: "UNSUPPORTED",
90
+ fs: "BEST_EFFORT",
91
+ notes: [
92
+ "A: AbortSignal/close observation menghentikan waiter (bash.ts:334-348).",
93
+ "B: DELEGATED_TO_RUNTIME — logical stop diputuskan runtime (Kernel M8); backend hanya berhenti menunggu.",
94
+ "C: SIGTERM / taskkill /T /F / kill(-pid,SIGKILL) grup (bash.ts:96-124).",
95
+ "D: BEST_EFFORT — daemonized double-fork lolos grup; klaim hanya via wait+close.",
96
+ "CPU/memori/PID: tanpa flag enforcement di invocation host.",
97
+ "Network: hanya bash-guard (bukan isolasi).",
98
+ "FS: jail pre-check realpath; TOCTOU redirect-form terdokumentasi (bash.ts:215-222).",
99
+ ],
100
+ },
101
+ docker: {
102
+ a: "SUPPORTED",
103
+ b: "DELEGATED_TO_RUNTIME",
104
+ c: "BEST_EFFORT",
105
+ d: "BEST_EFFORT",
106
+ cpu: "SUPPORTED",
107
+ memory: "SUPPORTED",
108
+ pid: "SUPPORTED",
109
+ network: "SUPPORTED",
110
+ fs: "SUPPORTED",
111
+ notes: [
112
+ "A: timeout wrapper SIGKILL + close observation (docker.ts:116-127).",
113
+ "B: DELEGATED_TO_RUNTIME — logical stop diputuskan runtime.",
114
+ "C: BEST_EFFORT — kill eksplisit container TAK ADA di invocation; hanya wrapper.",
115
+ "D: BEST_EFFORT — close wrapper ≠ bukti container mati; jangan klaim D container.",
116
+ "CPU/mem/PID/net/FS: --cpus/--memory/--pids-limit 32/--network none/--read-only+cap-drop+user (docker.ts:58-87).",
117
+ ],
118
+ },
119
+ bwrap: {
120
+ a: "SUPPORTED",
121
+ b: "DELEGATED_TO_RUNTIME",
122
+ c: "SUPPORTED",
123
+ d: "BEST_EFFORT",
124
+ cpu: "UNSUPPORTED",
125
+ memory: "UNSUPPORTED",
126
+ pid: "UNSUPPORTED",
127
+ network: "SUPPORTED",
128
+ fs: "SUPPORTED",
129
+ notes: [
130
+ "A: timeout wrapper SIGKILL + close observation (os.ts:181-191).",
131
+ "B: DELEGATED_TO_RUNTIME — logical stop diputuskan runtime.",
132
+ "C: wrapper SIGKILL + --die-with-parent (os.ts:128-129).",
133
+ "D: BEST_EFFORT — tanpa wait-proof namespace; jangan klaim D.",
134
+ "CPU/mem/PID: tanpa flag limit di invocation.",
135
+ "Network: --unshare-net (bridge opt-out terdokumentasi).",
136
+ "FS: --ro-bind/--bind/--tmpfs/--cap-drop ALL.",
137
+ ],
138
+ },
139
+ seatbelt: {
140
+ a: "SUPPORTED",
141
+ b: "DELEGATED_TO_RUNTIME",
142
+ c: "SUPPORTED",
143
+ d: "BEST_EFFORT",
144
+ cpu: "UNSUPPORTED",
145
+ memory: "UNSUPPORTED",
146
+ pid: "UNSUPPORTED",
147
+ network: "SUPPORTED",
148
+ fs: "SUPPORTED",
149
+ notes: [
150
+ "A: timeout wrapper SIGKILL + close observation (os.ts:181-191).",
151
+ "B: DELEGATED_TO_RUNTIME — logical stop diputuskan runtime.",
152
+ "C: wrapper SIGKILL; policy seatbelt = RESTRIKSI, bukan kill guarantee.",
153
+ "D: BEST_EFFORT — jangan samakan policy dengan physical proof.",
154
+ "CPU/mem/PID: tanpa enforcement di profile.",
155
+ "Network: (deny network*); FS: (deny default)+(subpath cwd).",
156
+ ],
157
+ },
158
+ }
159
+
160
+ /** Handle opaque backend — namespace `be_*`, BUKAN executionId (M1). */
161
+ export interface BackendHandle {
162
+ readonly id: string
163
+ readonly kind: BackendKind
164
+ }
165
+
166
+ export interface BackendExecRequest {
167
+ readonly cmd: string
168
+ readonly cwd?: string
169
+ readonly timeoutMs?: number
170
+ readonly env?: Record<string, string>
171
+ }
172
+
173
+ /** Status observasi fisik — BUKAN lifecycle authority (itu M8). */
174
+ export type BackendObserveStatus = "running" | "exited" | "failed" | "unknown"
175
+
176
+ export interface BackendObservation {
177
+ readonly status: BackendObserveStatus
178
+ readonly exitCode?: number | null
179
+ readonly error?: string
180
+ }
181
+
182
+ export type BackendCancelResult =
183
+ | { readonly status: "cancel-requested"; readonly via: string }
184
+ | { readonly status: "already-settled"; readonly exitCode?: number | null }
185
+ | { readonly status: "unsupported"; readonly reason: string }
186
+
187
+ export type BackendTerminateResult =
188
+ | { readonly status: "termination-requested"; readonly via: string }
189
+ | { readonly status: "already-settled"; readonly exitCode?: number | null }
190
+ | { readonly status: "unsupported"; readonly reason: string }
191
+
192
+ export type BackendWaitResult =
193
+ | { readonly status: "completed"; readonly exitCode: number | null }
194
+ | { readonly status: "proven-dead"; readonly exitCode: number | null }
195
+ | { readonly status: "timeout" }
196
+ | { readonly status: "vanished" }
197
+ | { readonly status: "unknown"; readonly detail: string }
198
+ | { readonly status: "orphan"; readonly detail: string }
199
+
200
+ export interface BackendDisposeResult {
201
+ readonly disposed: true
202
+ /** True bila dispose membersihkan proses hidup (anti-yatim; best-effort). */
203
+ readonly cleanupKillAttempted: boolean
204
+ }
205
+
206
+ export type BackendAdmitResult =
207
+ | { readonly admitted: true }
208
+ | { readonly admitted: false; readonly reason: string }
209
+ export type BackendStartResult =
210
+ | { readonly started: true; readonly handle: BackendHandle }
211
+ | { readonly started: false; readonly reason: string }
212
+
213
+ export interface ExecutionBackend {
214
+ readonly kind: BackendKind
215
+ readonly capabilities: BackendCapability
216
+ admit(req: BackendExecRequest): BackendAdmitResult
217
+ start(req: BackendExecRequest): Promise<BackendStartResult>
218
+ observe(handle: BackendHandle): BackendObservation
219
+ cancel(handle: BackendHandle, reason: string): BackendCancelResult
220
+ terminate(handle: BackendHandle, reason: string): BackendTerminateResult
221
+ wait(handle: BackendHandle, timeoutMs?: number): Promise<BackendWaitResult>
222
+ dispose(handle: BackendHandle): BackendDisposeResult
223
+ /**
224
+ * R1 (P9.0): bebaskan SEMUA record milik instance backend INI, sekali panggil.
225
+ * Pemilik sahnya adalah composition saat shutdown — BUKAN sweeper: tanpa timer,
226
+ * tanpa siklus, tak pernah menyentuh instance backend lain. Dispose per-handle
227
+ * tetap milik pemanggil yang memulai eksekusi; ini jaring pengaman batas-umur-
228
+ * proses untuk record yang pemanggilnya tak pernah membuang.
229
+ */
230
+ disposeAll(): { disposed: number }
231
+ }
232
+
233
+ /** Bound default wait (ms). Konservatif; configurable per-call. */
234
+ export const DEFAULT_BACKEND_WAIT_MS = 5_000
235
+
236
+ /**
237
+ * [P1 M16] SATU allocator untuk id handle backend (namespace `be_`).
238
+ *
239
+ * Sebelumnya dua adapter (host + docker) masing-masing mencetak `be_<8 hex>`;
240
+ * itu dua sumber untuk satu namespace dan pemanggil bisa menulis handle dengan
241
+ * prefix berbeda di jalur berbeda. Sekarang satu fungsi, satu format.
242
+ */
243
+ function allocateBackendHandleId(): string {
244
+ return `be_${randomUUID().slice(0, 8)}`
245
+ }
246
+
247
+ // ── Mekanik kill bersama (cermin bash.ts:96-124 + F-23; didokumentasikan,
248
+ // bukan diimpor dari tool layer agar backend tak bergantung pada tools). ──
249
+
250
+ function killTree(proc: { pid?: number; kill(signal: number | NodeJS.Signals): boolean }): void {
251
+ try {
252
+ if (process.platform === "win32" && proc.pid !== undefined) {
253
+ const r = spawnSync(
254
+ resolveTrustedExecutable("taskkill"),
255
+ ["/pid", String(proc.pid), "/T", "/F"],
256
+ {
257
+ stdio: "ignore",
258
+ env: sanitizeSpawnEnv(process.env),
259
+ },
260
+ )
261
+ if (r.status === 0) return
262
+ } else if (proc.pid !== undefined) {
263
+ try {
264
+ process.kill(-proc.pid, "SIGKILL")
265
+ return
266
+ } catch {}
267
+ }
268
+ } catch {}
269
+ try {
270
+ proc.kill("SIGKILL")
271
+ } catch {}
272
+ }
273
+
274
+ // ── Host adapter: implementasi penuh di atas node:child_process ──
275
+
276
+ interface HostRecord {
277
+ proc: ChildProcess
278
+ startedAt: number
279
+ done: boolean
280
+ exitCode: number | null
281
+ error: string | null
282
+ killInitiatedByUs: boolean
283
+ waiters: Set<(r: BackendWaitResult) => void>
284
+ timer: ReturnType<typeof setTimeout> | null
285
+ }
286
+
287
+ function settleHostRecord(rec: HostRecord, result: BackendWaitResult): void {
288
+ if (rec.timer) {
289
+ clearTimeout(rec.timer)
290
+ rec.timer = null
291
+ }
292
+ for (const w of [...rec.waiters]) {
293
+ rec.waiters.delete(w)
294
+ try {
295
+ w(result)
296
+ } catch {}
297
+ }
298
+ }
299
+
300
+ function hostTerminalResult(rec: HostRecord): BackendWaitResult {
301
+ // completed = keluar sendiri; proven-dead = close sesudah kill dari kita.
302
+ // Keduanya HANYA dari event close yang terobservasi — bukan klaim buta.
303
+ if (rec.error && !rec.done) return { status: "unknown", detail: rec.error }
304
+ if (rec.killInitiatedByUs) return { status: "proven-dead", exitCode: rec.exitCode }
305
+ return { status: "completed", exitCode: rec.exitCode }
306
+ }
307
+
308
+ export function createHostBackend(): ExecutionBackend {
309
+ const records = new Map<string, HostRecord>()
310
+
311
+ const get = (handle: BackendHandle): HostRecord | null => {
312
+ if (handle.kind !== "host") return null
313
+ return records.get(handle.id) ?? null
314
+ }
315
+
316
+ return {
317
+ kind: "host",
318
+ capabilities: BACKEND_CAPABILITIES.host,
319
+
320
+ admit(req: BackendExecRequest): BackendAdmitResult {
321
+ if (!req || typeof req.cmd !== "string" || req.cmd.length === 0)
322
+ return { admitted: false, reason: "empty command" }
323
+ if (req.cwd !== undefined && typeof req.cwd !== "string")
324
+ return { admitted: false, reason: "invalid cwd" }
325
+ if (req.timeoutMs !== undefined && (!Number.isFinite(req.timeoutMs) || req.timeoutMs <= 0))
326
+ return { admitted: false, reason: "invalid timeoutMs" }
327
+ return { admitted: true }
328
+ },
329
+
330
+ start(req: BackendExecRequest): Promise<BackendStartResult> {
331
+ const admission = this.admit(req)
332
+ if (!admission.admitted)
333
+ return Promise.resolve({ started: false as const, reason: admission.reason })
334
+ return new Promise((resolveStart) => {
335
+ let settled = false
336
+ let proc: ChildProcess
337
+ try {
338
+ proc = spawn(req.cmd, {
339
+ shell: true,
340
+ cwd: req.cwd ?? process.cwd(),
341
+ env: sanitizeSpawnEnv(process.env, req.env),
342
+ // detached agar group-leader → killTree grup (cermin bash.ts:297-299).
343
+ detached: process.platform !== "win32",
344
+ })
345
+ } catch (e) {
346
+ resolveStart({
347
+ started: false as const,
348
+ reason: e instanceof Error ? e.message : String(e),
349
+ })
350
+ return
351
+ }
352
+ const id = allocateBackendHandleId()
353
+ const rec: HostRecord = {
354
+ proc,
355
+ startedAt: Date.now(),
356
+ done: false,
357
+ exitCode: null,
358
+ error: null,
359
+ killInitiatedByUs: false,
360
+ waiters: new Set(),
361
+ timer: null,
362
+ }
363
+ proc.on("error", (e) => {
364
+ rec.error = e.message
365
+ rec.done = true
366
+ settleHostRecord(rec, { status: "unknown", detail: e.message })
367
+ if (!settled) {
368
+ settled = true
369
+ // Gagal spawn SEBELUM hidup: failed-to-start, BUKAN terminated.
370
+ resolveStart({ started: false as const, reason: e.message })
371
+ }
372
+ })
373
+ proc.on("close", (code) => {
374
+ rec.exitCode = code
375
+ rec.done = true
376
+ settleHostRecord(rec, hostTerminalResult(rec))
377
+ })
378
+ records.set(id, rec)
379
+ // nextTick: beri kesempatan error sinkron (ENOENT) sebelum klaim started.
380
+ setImmediate(() => {
381
+ if (!settled) {
382
+ settled = true
383
+ resolveStart({ started: true as const, handle: { id, kind: "host" as const } })
384
+ }
385
+ })
386
+ })
387
+ },
388
+
389
+ observe(handle: BackendHandle): BackendObservation {
390
+ const rec = get(handle)
391
+ if (!rec) return { status: "unknown", error: "no such handle (disposed or foreign)" }
392
+ if (!rec.done) return { status: "running" }
393
+ if (rec.error && rec.exitCode === null) return { status: "failed", error: rec.error }
394
+ return { status: "exited", exitCode: rec.exitCode }
395
+ },
396
+
397
+ cancel(handle: BackendHandle, reason: string): BackendCancelResult {
398
+ const rec = get(handle)
399
+ if (!rec) return { status: "already-settled" }
400
+ if (rec.done) return { status: "already-settled", exitCode: rec.exitCode }
401
+ // Cooperative: SIGTERM (win32 langsung tree — cermin bash.ts:328-337).
402
+ // Ini REQUEST; kematian fisik HANYA via wait+close (D). Tanpa klaim D.
403
+ rec.killInitiatedByUs = true
404
+ try {
405
+ if (process.platform === "win32") killTree(rec.proc)
406
+ else rec.proc.kill("SIGTERM")
407
+ } catch {}
408
+ void reason
409
+ return {
410
+ status: "cancel-requested",
411
+ via: process.platform === "win32" ? "killTree-taskkill" : "SIGTERM",
412
+ }
413
+ },
414
+
415
+ terminate(handle: BackendHandle, reason: string): BackendTerminateResult {
416
+ const rec = get(handle)
417
+ if (!rec) return { status: "already-settled" }
418
+ if (rec.done) return { status: "already-settled", exitCode: rec.exitCode }
419
+ // Stronger attempt (bukan label ulang cancel): killTree grup.
420
+ rec.killInitiatedByUs = true
421
+ try {
422
+ killTree(rec.proc)
423
+ } catch {}
424
+ void reason
425
+ return {
426
+ status: "termination-requested",
427
+ via: process.platform === "win32" ? "taskkill-/T-/F" : "kill(-pid,SIGKILL)-group",
428
+ }
429
+ },
430
+
431
+ wait(
432
+ handle: BackendHandle,
433
+ timeoutMs: number = DEFAULT_BACKEND_WAIT_MS,
434
+ ): Promise<BackendWaitResult> {
435
+ const rec = get(handle)
436
+ if (!rec)
437
+ return Promise.resolve({
438
+ status: "unknown",
439
+ detail: "no such handle (disposed or foreign)",
440
+ })
441
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
442
+ return Promise.reject(
443
+ new Error("backend.wait: timeoutMs must be finite positive (bounded by contract)"),
444
+ )
445
+ if (rec.done) return Promise.resolve(hostTerminalResult(rec))
446
+ return new Promise((resolveWait) => {
447
+ const onTimeout = (): void => {
448
+ rec.waiters.delete(resolveWait)
449
+ rec.timer = null
450
+ // Timeout = berhenti menunggu (A). Proses mungkin hidup — tak diklaim mati.
451
+ resolveWait({ status: "timeout" })
452
+ }
453
+ rec.waiters.add(resolveWait)
454
+ // [RL-6] bersihkan timer tunggu sebelumnya agar tak bocor saat wait()
455
+ // dipanggil ulang pada record yang sama.
456
+ if (rec.timer) clearTimeout(rec.timer)
457
+ rec.timer = setTimeout(onTimeout, timeoutMs)
458
+ })
459
+ },
460
+
461
+ dispose(handle: BackendHandle): BackendDisposeResult {
462
+ const rec = get(handle)
463
+ if (!rec) return { disposed: true as const, cleanupKillAttempted: false }
464
+ records.delete(handle.id)
465
+ let cleanup = false
466
+ if (!rec.done) {
467
+ // Anti-yatim best-effort (cleanup resources, BUKAN keputusan lifecycle):
468
+ // hasil historis yang sudah dikembalikan tak berubah oleh ini.
469
+ try {
470
+ killTree(rec.proc)
471
+ cleanup = true
472
+ } catch {}
473
+ }
474
+ settleHostRecord(rec, { status: "unknown", detail: "disposed" })
475
+ return { disposed: true as const, cleanupKillAttempted: cleanup }
476
+ },
477
+
478
+ disposeAll(): { disposed: number } {
479
+ // R1: snapshot kunci dulu (dispose menghapus dari map), lalu pakai ulang
480
+ // dispose per-handle — semantik per-record IDENTIK (kill best-effort
481
+ // untuk yang hidup + waiter diselesaikan jujur "disposed"), tanpa
482
+ // duplikasi logika kill/settle.
483
+ let disposed = 0
484
+ for (const id of [...records.keys()]) {
485
+ this.dispose({ id, kind: "host" })
486
+ disposed++
487
+ }
488
+ return { disposed }
489
+ },
490
+ }
491
+ }
492
+
493
+ // ── Sandbox shims: deklarasi + run-to-completion wrap (jujur mid-flight) ──
494
+
495
+ interface ShimCompleted {
496
+ done: true
497
+ code: number | null
498
+ output: string
499
+ }
500
+
501
+ function createRunToCompletionShim(
502
+ kind: BackendKind,
503
+ available: () => boolean,
504
+ unavailableReason: string,
505
+ runToCompletion: (req: BackendExecRequest) => Promise<{ code: number | null; output: string }>,
506
+ ): ExecutionBackend {
507
+ const records = new Map<string, ShimCompleted>()
508
+ return {
509
+ kind,
510
+ capabilities: BACKEND_CAPABILITIES[kind],
511
+ admit(req: BackendExecRequest): BackendAdmitResult {
512
+ if (!req || typeof req.cmd !== "string" || req.cmd.length === 0)
513
+ return { admitted: false, reason: "empty command" }
514
+ // Fail-closed tanpa silent fallback (cermin bash.ts:253-260,278-285).
515
+ if (!available()) return { admitted: false, reason: unavailableReason }
516
+ return { admitted: true }
517
+ },
518
+ async start(req: BackendExecRequest): Promise<BackendStartResult> {
519
+ const admission = this.admit(req)
520
+ if (!admission.admitted) return { started: false as const, reason: admission.reason }
521
+ const id = allocateBackendHandleId()
522
+ try {
523
+ const res = await runToCompletion(req)
524
+ records.set(id, { done: true, code: res.code, output: res.output })
525
+ return { started: true as const, handle: { id, kind } }
526
+ } catch (e) {
527
+ return { started: false as const, reason: e instanceof Error ? e.message : String(e) }
528
+ }
529
+ },
530
+ observe(handle: BackendHandle): BackendObservation {
531
+ const rec = handle.kind === kind ? records.get(handle.id) : undefined
532
+ if (!rec) return { status: "unknown", error: "no such handle (disposed or foreign)" }
533
+ return { status: "exited", exitCode: rec.code }
534
+ },
535
+ cancel(handle: BackendHandle, _reason: string): BackendCancelResult {
536
+ const rec = handle.kind === kind ? records.get(handle.id) : undefined
537
+ if (!rec) return { status: "already-settled" }
538
+ // Runner existing run-to-completion: tak ada handle preemptif. DINYATAKAN
539
+ // unsupported (jujur, sesuai evidence code_run abort-hanya-menunggu).
540
+ void _reason
541
+ return {
542
+ status: "unsupported",
543
+ reason: "run-to-completion runner has no preemptive kill path (M5-out)",
544
+ }
545
+ },
546
+ terminate(handle: BackendHandle, _reason: string): BackendTerminateResult {
547
+ const rec = handle.kind === kind ? records.get(handle.id) : undefined
548
+ if (!rec) return { status: "already-settled" }
549
+ void _reason
550
+ return {
551
+ status: "unsupported",
552
+ reason: "run-to-completion runner has no preemptive kill path (M5-out)",
553
+ }
554
+ },
555
+ async wait(handle: BackendHandle): Promise<BackendWaitResult> {
556
+ const rec = handle.kind === kind ? records.get(handle.id) : undefined
557
+ if (!rec) return { status: "unknown", detail: "no such handle (disposed or foreign)" }
558
+ // Runner melaporkan completion — BUKAN physical-death proof container.
559
+ // D container tak pernah diklaim shim ini (matriks d=BEST_EFFORT).
560
+ return { status: "completed", exitCode: rec.code }
561
+ },
562
+ dispose(handle: BackendHandle): BackendDisposeResult {
563
+ const existed = handle.kind === kind && records.delete(handle.id)
564
+ void existed
565
+ return { disposed: true as const, cleanupKillAttempted: false }
566
+ },
567
+ disposeAll(): { disposed: number } {
568
+ // R1: shim run-to-completion tak punya proses preemptif untuk dibunuh —
569
+ // cukup bebaskan record. Snapshot kunci dulu (delete saat iterasi).
570
+ let disposed = 0
571
+ for (const id of [...records.keys()]) {
572
+ records.delete(id)
573
+ disposed++
574
+ }
575
+ return { disposed }
576
+ },
577
+ }
578
+ }
579
+
580
+ export function createDockerBackend(): ExecutionBackend {
581
+ return createRunToCompletionShim(
582
+ "docker",
583
+ () => dockerAvailable(),
584
+ "docker unavailable (no silent host fallback)",
585
+ (req) =>
586
+ runInDocker(req.cmd, req.cwd ?? process.cwd(), {
587
+ ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
588
+ ...(req.env ? { env: req.env } : {}),
589
+ }),
590
+ )
591
+ }
592
+
593
+ function bwrapSelected(): boolean {
594
+ return osSandboxAvailable() && osSandboxTypeName() === "bwrap"
595
+ }
596
+
597
+ function seatbeltSelected(): boolean {
598
+ return osSandboxAvailable() && osSandboxTypeName() === "seatbelt"
599
+ }
600
+
601
+ export function createBwrapBackend(): ExecutionBackend {
602
+ return createRunToCompletionShim(
603
+ "bwrap",
604
+ () => bwrapSelected(),
605
+ "bwrap unavailable on this platform",
606
+ (req) =>
607
+ runInOsSandbox(req.cmd, req.cwd ?? process.cwd(), {
608
+ ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
609
+ ...(req.env ? { env: req.env } : {}),
610
+ }),
611
+ )
612
+ }
613
+
614
+ export function createSeatbeltBackend(): ExecutionBackend {
615
+ return createRunToCompletionShim(
616
+ "seatbelt",
617
+ () => seatbeltSelected(),
618
+ "seatbelt unavailable on this platform",
619
+ (req) =>
620
+ runInOsSandbox(req.cmd, req.cwd ?? process.cwd(), {
621
+ ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
622
+ ...(req.env ? { env: req.env } : {}),
623
+ }),
624
+ )
625
+ }
626
+
627
+ export const BACKEND_FACTORIES: Record<BackendKind, () => ExecutionBackend> = {
628
+ host: createHostBackend,
629
+ docker: createDockerBackend,
630
+ bwrap: createBwrapBackend,
631
+ seatbelt: createSeatbeltBackend,
632
+ }