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
@@ -138,9 +138,13 @@ export function createContentStore(): ContentStore {
138
138
  if (prev) totalChars -= prev.text.length
139
139
  const cut = trimToCap(text)
140
140
  entries.set(key, {
141
- ref: { toolCallId: ref.toolCallId, idx: ref.idx },
141
+ ref: { toolCallId: ref.toolCallId, idx: ref.idx, ...(ref.kind ? { kind: ref.kind } : {}) },
142
142
  text: cut,
143
- meta: { ...meta, truncated: meta.truncated || cut.length < text.length },
143
+ meta: {
144
+ ...meta,
145
+ kind: ref.kind ?? meta.kind,
146
+ truncated: meta.truncated || cut.length < text.length,
147
+ },
144
148
  })
145
149
  totalChars += cut.length
146
150
  dead.delete(key)
@@ -167,14 +171,13 @@ export function createContentStore(): ContentStore {
167
171
  const local = entries.get(contentKey(ref))
168
172
  if (local)
169
173
  return { ref: local.ref, text: local.text, meta: { ...local.meta, source: "store" } }
170
- // Fallback durable HANYA untuk output (reasoning di luar retensi = hilang).
171
- if (durable) {
174
+ if (durable && (ref.kind === undefined || ref.kind === "output" || ref.kind === "diff")) {
172
175
  const text = durable(ref.toolCallId)
173
176
  if (text != null && text !== "") {
174
177
  return {
175
178
  text,
176
179
  meta: {
177
- kind: "output",
180
+ kind: ref.kind === "diff" ? "diff" : "output",
178
181
  stream: "stderr",
179
182
  truncated: false,
180
183
  source: "durable",
@@ -186,7 +189,7 @@ export function createContentStore(): ContentStore {
186
189
  return {
187
190
  text: "",
188
191
  meta: {
189
- kind: "output",
192
+ kind: ref.kind ?? "output",
190
193
  stream: "stderr",
191
194
  truncated: false,
192
195
  source: "retention",
@@ -197,7 +200,9 @@ export function createContentStore(): ContentStore {
197
200
  },
198
201
  expand(toolCallId, durable) {
199
202
  const prefix = `${toolCallId}#`
200
- const keys = [...entries.keys()].filter((k) => k.startsWith(prefix)).sort()
203
+ const keys = [...entries.keys()]
204
+ .filter((k) => k.startsWith(prefix))
205
+ .sort((a, b) => Number(a.slice(prefix.length)) - Number(b.slice(prefix.length)))
201
206
  const out: ContentEntry[] = []
202
207
  for (const k of keys) {
203
208
  const hit = entries.get(k)
@@ -124,8 +124,8 @@ export function createAnthropicProvider(config: AnthropicConfig): ModelProvider
124
124
  try {
125
125
  response = await fetch(endpoint, { method: "POST", headers, body, signal })
126
126
  } catch (e) {
127
- if ((e as Error).name === "AbortError") throw e
128
- throw new ProviderError("network", (e as Error).message)
127
+ if (e instanceof Error && e.name === "AbortError") throw e
128
+ throw new ProviderError("network", e instanceof Error ? e.message : String(e))
129
129
  }
130
130
  if (!response.ok) {
131
131
  const txt = await response.text().catch(() => "")
@@ -144,12 +144,15 @@ export function createAnthropicProvider(config: AnthropicConfig): ModelProvider
144
144
  if (!data) continue
145
145
  // handle different event types
146
146
  const raw = data as AnthropicRaw
147
- if (currentEvent === "content_block_delta") {
147
+ // [ST-4] Bila proxy/gateway menghapus header baris `event:`, pakai
148
+ // `raw.type` dari body sebagai fallback jenis event.
149
+ const evType = raw.type ?? currentEvent
150
+ if (evType === "content_block_delta") {
148
151
  const delta = raw.delta
149
152
  if (delta?.type === "text_delta" && typeof delta.text === "string") {
150
153
  yield { type: "text", text: delta.text }
151
154
  }
152
- } else if (currentEvent === "message_delta") {
155
+ } else if (evType === "message_delta") {
153
156
  const d = raw.delta
154
157
  const stop = d?.stop_reason
155
158
  if (stop) {
@@ -178,7 +181,7 @@ export function createAnthropicProvider(config: AnthropicConfig): ModelProvider
178
181
  },
179
182
  }
180
183
  }
181
- } else if (raw.type === "message_start") {
184
+ } else if (evType === "message_start") {
182
185
  const usage = raw.message?.usage
183
186
  if (usage) {
184
187
  yield {
@@ -195,13 +198,16 @@ export function createAnthropicProvider(config: AnthropicConfig): ModelProvider
195
198
  }
196
199
  }
197
200
  // content_block_start for tool_use
198
- if (raw.type === "content_block_start") {
201
+ if (evType === "content_block_start") {
199
202
  const block = raw.content_block
200
203
  if (block?.type === "tool_use") {
201
- pendingTools.set(raw.index ?? 0, { id: block.id!, name: block.name!, args: "" })
204
+ // [ST-5] Non-null guard: blok malformed tanpa id/name dikunci, bukan
205
+ // dipaksa `block.id!`/`block.name!` yang bisa menyimpan undefined.
206
+ if (typeof block.id !== "string" || typeof block.name !== "string") continue
207
+ pendingTools.set(raw.index ?? 0, { id: block.id, name: block.name, args: "" })
202
208
  }
203
209
  }
204
- if (raw.type === "content_block_delta") {
210
+ if (evType === "content_block_delta") {
205
211
  const d = raw.delta
206
212
  if (d?.type === "input_json_delta") {
207
213
  const idx = raw.index ?? 0
@@ -212,7 +218,7 @@ export function createAnthropicProvider(config: AnthropicConfig): ModelProvider
212
218
  yield { type: "extension", kind: "reasoning", data: { text: d.thinking } }
213
219
  }
214
220
  }
215
- if (raw.type === "content_block_stop") {
221
+ if (evType === "content_block_stop") {
216
222
  const idx = raw.index ?? 0
217
223
  const p = pendingTools.get(idx)
218
224
  if (p) {
@@ -291,7 +297,9 @@ export function toAnthropicMessages(messages: readonly Message[]): unknown[] {
291
297
  }
292
298
  out.push({
293
299
  role: "assistant",
294
- content: content.length ? content : [{ type: "text", text: "" }],
300
+ // [ST-1] Blok text KOSONG `""` memicu HTTP 400 Anthropic; pakai placeholder
301
+ // non-kosong `" "` untuk pesan assistant tanpa konten & tanpa tool_use.
302
+ content: content.length ? content : [{ type: "text", text: " " }],
295
303
  })
296
304
  } else {
297
305
  const c = m as unknown as { toolCallId: string; content: unknown; isError?: boolean }
@@ -127,8 +127,8 @@ export function createResponsesProvider(config: ResponsesConfig): ModelProvider
127
127
  try {
128
128
  res = await fetch(endpoint, { method: "POST", headers, body, signal })
129
129
  } catch (e) {
130
- if ((e as Error).name === "AbortError") throw e
131
- throw new ProviderError("network", (e as Error).message)
130
+ if (e instanceof Error && e.name === "AbortError") throw e
131
+ throw new ProviderError("network", e instanceof Error ? e.message : String(e))
132
132
  }
133
133
  if (!res.ok) {
134
134
  const txt = await res.text().catch(() => "")
@@ -263,6 +263,15 @@ export function createResponsesProvider(config: ResponsesConfig): ModelProvider
263
263
  }
264
264
  }
265
265
  }
266
+ const reasoningText =
267
+ (dtype === "response.reasoning_summary_text.delta" ||
268
+ dtype === "response.reasoning_text.delta") &&
269
+ typeof data.delta === "string"
270
+ ? data.delta
271
+ : ""
272
+ if (reasoningText) {
273
+ yield { type: "extension", kind: "reasoning", data: { text: reasoningText } }
274
+ }
266
275
  const rawDelta: unknown = (data.delta as unknown) ?? data
267
276
  const drec = (
268
277
  typeof rawDelta === "object" && rawDelta !== null
@@ -328,11 +337,12 @@ export function createResponsesProvider(config: ResponsesConfig): ModelProvider
328
337
  typeof data.arguments === "string" ? data.arguments : "",
329
338
  )
330
339
  }
331
- const text =
332
- (typeof rawDelta === "string" ? rawDelta : undefined) ??
333
- drec.text ??
334
- drec.content ??
335
- drec.output_text
340
+ const text = reasoningText
341
+ ? undefined
342
+ : ((typeof rawDelta === "string" ? rawDelta : undefined) ??
343
+ drec.text ??
344
+ drec.content ??
345
+ drec.output_text)
336
346
  if (typeof text === "string" && text) yield { type: "text", text }
337
347
  const finish =
338
348
  (data as { finish_reason?: string }).finish_reason ??
@@ -0,0 +1,409 @@
1
+ // M6 — Capability split: request ≠ grant; decision ≠ delivery.
2
+ //
3
+ // Kenapa berkas ini ada (P1 ADR-007): repo memiliki authorization (permission
4
+ // handler allow/deny/ask), enforcement (jail/guard/scrub/sandbox), dan klasifikasi
5
+ // tool (autonomous matrix) — tetapi tak ada representasi eksplisit yang membedakan
6
+ // "boleh diminta" dari "apa yang diberikan", sehingga subset child⊆parent dan
7
+ // approval-narrowness tak dapat dibuktikan. Modul ini adalah representasi +
8
+ // proof engine, BUKAN rewrite policy.
9
+ //
10
+ // BUKAN: Execution FSM (M8), supervisor (M9), recovery (M12), scheduler bridge
11
+ // (M13), persistence redesign, capability enforcement (tetap jail/guard/scrub/
12
+ // sandbox/M5-backend), production wiring (itu M7/M14). Aturan yang dikunci:
13
+ // - childGrant ⊆ parentGrant SELALU (proof, bukan konvensi). Eskalasi = deny.
14
+ // - Grant immutable (frozen) + bound ke executionId + ownerId (bukan token:
15
+ // executionId/ownerId = identifier, BUKAN authority/secret).
16
+ // - Approval sempit-by-construction: tanpa tool+operation+execution binding,
17
+ // approval tak mencakup apa pun (blanket "approve bash" = tak berdaya).
18
+ // - Perbandingan scope LEKSIKAL murni (tanpa FS): symlink/TOCTOU enforcement
19
+ // tetap milik jail.ts/safe-open (M6 comparison ≠ enforcement).
20
+ // - Secret heuristic di sini LEKSIKAL (cermin scrub.ts); penyamaran tetap
21
+ // milik scrub. Env bukan sumber authority.
22
+ // - Tak ada import policy/scheduler/persistence/backend — modul murni agar
23
+ // dapat diuji tanpa infra dan tak menyeret domain.
24
+
25
+ import { randomUUID } from "node:crypto"
26
+
27
+ /** Operasi capability. Rank: read < write < execute < admin; network = dimensi sendiri. */
28
+ export type CapabilityOperation = "read" | "write" | "execute" | "network" | "admin"
29
+
30
+ const OP_RANK: Record<Exclude<CapabilityOperation, "network">, number> = {
31
+ read: 1,
32
+ write: 2,
33
+ execute: 3,
34
+ admin: 4,
35
+ }
36
+
37
+ export interface FsScope {
38
+ readonly kind: "fs"
39
+ /** Scope path (workspace-absolut ternormalisasi leksikal; lihat normalizeScopePath). */
40
+ readonly path: string
41
+ }
42
+ export interface NetScope {
43
+ readonly kind: "net"
44
+ /** Host yang diizinkan. Absent = unrestricted (hanya valid bila parent unrestricted). */
45
+ readonly hosts?: readonly string[]
46
+ }
47
+ export interface EnvScope {
48
+ readonly kind: "env"
49
+ /** Nama variabel eksplisit. Kosong = tanpa akses env. */
50
+ readonly names: readonly string[]
51
+ }
52
+ export interface ProcScope {
53
+ readonly kind: "proc"
54
+ /** Hanya proses anak sendiri. Nilai lain = masa depan, kini ditolak. */
55
+ readonly scope: "own"
56
+ }
57
+ export type CapabilityResource = FsScope | NetScope | EnvScope | ProcScope
58
+
59
+ export interface Capability {
60
+ readonly operation: CapabilityOperation
61
+ readonly resource: CapabilityResource
62
+ /** Tag constraint monotonik (mis. "sandbox:docker", "net:denied"): child ∩ ⊇ parent. */
63
+ readonly constraints?: readonly string[]
64
+ }
65
+
66
+ /** "Butuh X" — klaim kebutuhan, bukan pemberian. */
67
+ export interface CapabilityRequest {
68
+ readonly tool: string
69
+ readonly operation: CapabilityOperation
70
+ readonly resource: CapabilityResource
71
+ readonly executionId: string
72
+ readonly ownerId: string
73
+ }
74
+
75
+ export type AuthorizationOutcome = "allow" | "deny" | "ask"
76
+
77
+ export interface AuthorizationDecision {
78
+ readonly outcome: AuthorizationOutcome
79
+ readonly reason: string
80
+ }
81
+
82
+ /** Provenance grant — traceable tanpa secret/prompt (auditability M6). */
83
+ export interface GrantProvenance {
84
+ readonly requestedBy: string
85
+ readonly authorizedBy: string
86
+ readonly derivedFrom?: string
87
+ readonly reason: string
88
+ }
89
+
90
+ export interface CapabilityGrant {
91
+ /** Trace id (`cg_*`, namespace sendiri — BUKAN executionId, BUKAN secret). */
92
+ readonly id: string
93
+ readonly executionId: string
94
+ readonly ownerId: string
95
+ readonly capabilities: readonly Capability[]
96
+ readonly provenance: GrantProvenance
97
+ }
98
+
99
+ /** Approval sempit: tanpa binding tool+operation+execution = tak mencakup apa pun. */
100
+ export interface ApprovalScope {
101
+ readonly id: string
102
+ readonly tool: string
103
+ readonly operation?: CapabilityOperation
104
+ readonly pathScope?: string
105
+ readonly executionId: string
106
+ readonly nonce: string
107
+ }
108
+
109
+ // ── Normalisasi path leksikal (TANPA FS — enforcement milik jail/safe-open) ──
110
+
111
+ /**
112
+ * Normalisasi scope path: separator → `/`, collapse `.`/`..` leksikal,
113
+ * trailing slash dibuang, win32 case-insensitive (lowercase).
114
+ * Menolak NUL. TIDAK me-resolve symlink (itu jail); scope `..` yang lolos
115
+ * di atas root leksikal dipertahankan apa adanya agar containment menolaknya.
116
+ */
117
+ export function normalizeScopePath(path: string): string {
118
+ if (typeof path !== "string" || path.length === 0) throw new Error("capability: empty path")
119
+ if (path.includes("\0")) throw new Error("capability: NUL byte in path")
120
+ const isWin = process.platform === "win32"
121
+ let p = path.replace(/\\/g, "/")
122
+ const parts: string[] = []
123
+ for (const seg of p.split("/")) {
124
+ if (seg === "" || seg === ".") continue
125
+ if (seg === "..") {
126
+ if (parts.length > 0 && parts[parts.length - 1] !== "..") parts.pop()
127
+ else parts.push("..")
128
+ continue
129
+ }
130
+ parts.push(seg)
131
+ }
132
+ p = (path.startsWith("/") ? "/" : "") + parts.join("/")
133
+ if (p === "") p = "."
134
+ return isWin ? p.toLowerCase() : p
135
+ }
136
+
137
+ /** True bila childPath di dalam/di parentPath (bentuk ternormalisasi). */
138
+ export function isPathWithin(parentPath: string, childPath: string): boolean {
139
+ const parent = normalizeScopePath(parentPath)
140
+ const child = normalizeScopePath(childPath)
141
+ if (child === parent) return true
142
+ if (parent === ".") return !child.startsWith("..")
143
+ return child.startsWith(parent.endsWith("/") ? parent : `${parent}/`)
144
+ }
145
+
146
+ // ── Perbandingan kapabilitas (proof child ⊆ parent) ──
147
+
148
+ function operationCovers(parentOp: CapabilityOperation, childOp: CapabilityOperation): boolean {
149
+ // Dimensi network: child "network" butuh parent "network" persis; parent
150
+ // "network" mencakup child "read" (fetch = network read), bukan write/execute.
151
+ if (childOp === "network") return parentOp === "network"
152
+ if (parentOp === "network") return childOp === "read"
153
+ return OP_RANK[childOp] <= OP_RANK[parentOp]
154
+ }
155
+
156
+ function resourceCovers(parent: CapabilityResource, child: CapabilityResource): boolean {
157
+ if (parent.kind !== child.kind) return false
158
+ switch (parent.kind) {
159
+ case "fs":
160
+ return isPathWithin(parent.path, (child as FsScope).path)
161
+ case "net": {
162
+ const childHosts = (child as NetScope).hosts
163
+ // Parent unrestricted (hosts absent) mencakup semua; child unrestricted
164
+ // hanya bila parent unrestricted. Daftar eksplisit harus subset.
165
+ if (parent.hosts === undefined) return true
166
+ if (childHosts === undefined) return false
167
+ return childHosts.every((h) => (parent.hosts as readonly string[]).includes(h))
168
+ }
169
+ case "env": {
170
+ const childNames = (child as EnvScope).names
171
+ return childNames.every((n) => (parent as EnvScope).names.includes(n))
172
+ }
173
+ case "proc":
174
+ return (child as ProcScope).scope === (parent as ProcScope).scope
175
+ }
176
+ }
177
+
178
+ function constraintsCover(
179
+ parent: readonly string[] | undefined,
180
+ child: readonly string[] | undefined,
181
+ ): boolean {
182
+ const p = parent ?? []
183
+ const c = new Set(child ?? [])
184
+ return p.every((t) => c.has(t))
185
+ }
186
+
187
+ /** True bila setiap kapabilitas child dicover ≥1 kapabilitas parent. */
188
+ export function isCapabilitySubset(child: Capability, parent: Capability): boolean {
189
+ return (
190
+ operationCovers(parent.operation, child.operation) &&
191
+ resourceCovers(parent.resource, child.resource) &&
192
+ constraintsCover(parent.constraints, child.constraints)
193
+ )
194
+ }
195
+
196
+ /** True bila setiap kapabilitas grant-child dicover grant-parent. */
197
+ export function isGrantSubset(child: CapabilityGrant, parent: CapabilityGrant): boolean {
198
+ if (child.ownerId !== parent.ownerId) return false
199
+ return child.capabilities.every((c) => parent.capabilities.some((p) => isCapabilitySubset(c, p)))
200
+ }
201
+
202
+ // ── Secret heuristic leksikal (cermin scrub.ts; enforcement milik scrub) ──
203
+
204
+ const SECRET_NAME_RE =
205
+ /(?:API[_-]?KEYS?|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CREDENTIALS?|AUTH|BEARER)/i
206
+
207
+ export function isSecretName(name: unknown): boolean {
208
+ return typeof name === "string" && SECRET_NAME_RE.test(name)
209
+ }
210
+
211
+ // ── Konstruksi grant (frozen; validasi bentuk) ──
212
+
213
+ function freezeGrant(g: CapabilityGrant): CapabilityGrant {
214
+ return Object.freeze({
215
+ ...g,
216
+ capabilities: Object.freeze([...g.capabilities]),
217
+ provenance: Object.freeze({ ...g.provenance }),
218
+ })
219
+ }
220
+
221
+ function assertCapability(cap: Capability): void {
222
+ if (!cap || typeof cap.operation !== "string") throw new Error("capability: invalid operation")
223
+ const res = cap.resource as CapabilityResource | undefined
224
+ if (!res || typeof res.kind !== "string") throw new Error("capability: invalid resource")
225
+ if (res.kind === "fs") {
226
+ normalizeScopePath((res as FsScope).path)
227
+ } else if (res.kind === "net") {
228
+ for (const h of (res as NetScope).hosts ?? []) {
229
+ if (typeof h !== "string" || h.length === 0) throw new Error("capability: invalid net host")
230
+ }
231
+ } else if (res.kind === "env") {
232
+ for (const n of (res as EnvScope).names) {
233
+ if (typeof n !== "string" || n.length === 0) throw new Error("capability: invalid env name")
234
+ }
235
+ } else if (res.kind === "proc") {
236
+ if ((res as ProcScope).scope !== "own") throw new Error("capability: proc scope must be 'own'")
237
+ } else {
238
+ throw new Error("capability: unknown resource kind")
239
+ }
240
+ }
241
+
242
+ export function createGrant(input: {
243
+ executionId: string
244
+ ownerId: string
245
+ capabilities: readonly Capability[]
246
+ provenance: GrantProvenance
247
+ }): CapabilityGrant {
248
+ if (!input.executionId || !input.ownerId)
249
+ throw new Error("capability: grant needs executionId + ownerId")
250
+ if (
251
+ !input.provenance?.requestedBy ||
252
+ !input.provenance?.authorizedBy ||
253
+ !input.provenance?.reason
254
+ )
255
+ throw new Error("capability: grant needs provenance (requestedBy/authorizedBy/reason)")
256
+ for (const cap of input.capabilities) assertCapability(cap)
257
+ return freezeGrant({
258
+ id: `cg_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
259
+ executionId: input.executionId,
260
+ ownerId: input.ownerId,
261
+ capabilities: [...input.capabilities],
262
+ provenance: { ...input.provenance },
263
+ })
264
+ }
265
+
266
+ // ── Approval narrowness (sempit-by-construction) ──
267
+
268
+ /**
269
+ * Approval mencakup request bila: tool sama + execution SAMA (tanpa reuse
270
+ * lintas execution/sesi — P7) + operation SAMA (absent = tak mencakup apa pun
271
+ * selain... tidak: absent operation = tak mencakup request ber-op apa pun) +
272
+ * path (bila request ber-path fs): approval.pathScope harus contain, atau
273
+ * approval tanpa pathScope hanya mencakup request tanpa path.
274
+ * Blanket {tool} tanpa operation/execution-binding = tak berdaya (by design).
275
+ */
276
+ export function approvalCovers(approval: ApprovalScope, request: CapabilityRequest): boolean {
277
+ if (!approval || !request) return false
278
+ if (approval.tool !== request.tool) return false
279
+ if (approval.executionId !== request.executionId) return false
280
+ if (approval.operation === undefined || approval.operation !== request.operation) return false
281
+ if (request.resource.kind === "fs") {
282
+ if (approval.pathScope === undefined) return false
283
+ try {
284
+ return isPathWithin(approval.pathScope, request.resource.path)
285
+ } catch {
286
+ return false
287
+ }
288
+ }
289
+ return true
290
+ }
291
+
292
+ // ── Decision: allow / deny / ask (NILAI keputusan; prompting tetap permission handler) ──
293
+
294
+ export type CapabilityEvaluation =
295
+ | { readonly decision: "allow"; readonly grant: CapabilityGrant; readonly reason: string }
296
+ | { readonly decision: "deny"; readonly reason: string }
297
+ | { readonly decision: "ask"; readonly reason: string }
298
+
299
+ /**
300
+ * Evaluasi request terhadap parent grant (+ approval opsional):
301
+ * - tanpa parent = deny (deny-by-default, cermin autonomous UNKNOWN→DENY);
302
+ * - request tercover parent = allow + grant sesuai request (provenance policy);
303
+ * - approval mencakup = allow + grant (provenance approval);
304
+ * - selain itu = ask (butuh manusia — DIREPRESENTASIKAN, tak dieksekusi di sini).
305
+ * Grant yang dihasilkan terikat executionId request (tanpa reuse lintas execution).
306
+ */
307
+ export function evaluateRequest(
308
+ request: CapabilityRequest,
309
+ parent: CapabilityGrant | null,
310
+ approval?: ApprovalScope,
311
+ ): CapabilityEvaluation {
312
+ if (!request?.tool || !request.executionId || !request.ownerId)
313
+ return { decision: "deny", reason: "malformed request" }
314
+ try {
315
+ assertCapability({ operation: request.operation, resource: request.resource })
316
+ } catch {
317
+ return { decision: "deny", reason: "malformed capability" }
318
+ }
319
+ if (parent) {
320
+ if (parent.ownerId !== request.ownerId)
321
+ return { decision: "deny", reason: "owner mismatch (explicit higher authority required)" }
322
+ const covered = parent.capabilities.some((p) =>
323
+ isCapabilitySubset({ operation: request.operation, resource: request.resource }, p),
324
+ )
325
+ if (covered) {
326
+ return {
327
+ decision: "allow",
328
+ reason: "covered by parent grant",
329
+ grant: createGrant({
330
+ executionId: request.executionId,
331
+ ownerId: request.ownerId,
332
+ capabilities: [{ operation: request.operation, resource: request.resource }],
333
+ provenance: {
334
+ requestedBy: request.tool,
335
+ authorizedBy: `policy:parent-grant:${parent.id}`,
336
+ derivedFrom: parent.id,
337
+ reason: "subset of parent",
338
+ },
339
+ }),
340
+ }
341
+ }
342
+ } else {
343
+ return { decision: "deny", reason: "no parent grant (deny by default)" }
344
+ }
345
+ if (approval && approvalCovers(approval, request)) {
346
+ return {
347
+ decision: "allow",
348
+ reason: `covered by approval ${approval.id}`,
349
+ grant: createGrant({
350
+ executionId: request.executionId,
351
+ ownerId: request.ownerId,
352
+ capabilities: [{ operation: request.operation, resource: request.resource }],
353
+ provenance: {
354
+ requestedBy: request.tool,
355
+ authorizedBy: `approval:${approval.id}`,
356
+ reason: "narrow approval match",
357
+ },
358
+ }),
359
+ }
360
+ }
361
+ return { decision: "ask", reason: "requires human approval (represented, not executed here)" }
362
+ }
363
+
364
+ // ── Attenuasi parent → child (M7 memakai; M6 menyediakan proof) ──
365
+
366
+ /**
367
+ * Turunkan grant child dari parent: child capabilities HARUS subset parent,
368
+ * owner SAMA (lintas owner = butuh higher authority eksplisit = masa depan),
369
+ * constraints child ⊇ parent (tak boleh buang sandbox/net-denied).
370
+ * Gagal = deny + reason (tak pernah upgrade diam-diam).
371
+ */
372
+ export function attenuateGrant(
373
+ parent: CapabilityGrant,
374
+ childSpec: {
375
+ executionId: string
376
+ ownerId: string
377
+ capabilities: readonly Capability[]
378
+ requestedBy: string
379
+ },
380
+ ): { granted: CapabilityGrant } | { denied: string } {
381
+ if (childSpec.ownerId !== parent.ownerId)
382
+ return { denied: "owner mismatch (explicit higher authority required)" }
383
+ try {
384
+ for (const cap of childSpec.capabilities) assertCapability(cap)
385
+ } catch {
386
+ return { denied: "malformed child capability" }
387
+ }
388
+ const childProbe: CapabilityGrant = {
389
+ id: "probe",
390
+ executionId: childSpec.executionId,
391
+ ownerId: childSpec.ownerId,
392
+ capabilities: childSpec.capabilities,
393
+ provenance: { requestedBy: childSpec.requestedBy, authorizedBy: "probe", reason: "probe" },
394
+ }
395
+ if (!isGrantSubset(childProbe, parent)) return { denied: "child exceeds parent grant" }
396
+ return {
397
+ granted: createGrant({
398
+ executionId: childSpec.executionId,
399
+ ownerId: childSpec.ownerId,
400
+ capabilities: childSpec.capabilities,
401
+ provenance: {
402
+ requestedBy: childSpec.requestedBy,
403
+ authorizedBy: `policy:parent-grant:${parent.id}`,
404
+ derivedFrom: parent.id,
405
+ reason: "attenuated subset",
406
+ },
407
+ }),
408
+ }
409
+ }