@e4779/pi-fabric 0.92.24-fork.4 → 0.92.41-fork.6

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 (271) hide show
  1. package/README.md +2 -1
  2. package/dist/actors/host-event-payload.d.ts.map +1 -1
  3. package/dist/actors/types.d.ts +1 -1
  4. package/dist/actors/types.d.ts.map +1 -1
  5. package/dist/agents/completion-inbox.d.ts +15 -0
  6. package/dist/agents/completion-inbox.d.ts.map +1 -0
  7. package/dist/agents/handoff.d.ts.map +1 -1
  8. package/dist/agents/manager.d.ts +1 -0
  9. package/dist/agents/manager.d.ts.map +1 -1
  10. package/dist/agents/request.d.ts +4 -0
  11. package/dist/agents/request.d.ts.map +1 -1
  12. package/dist/agents/thinking-transfer.d.ts.map +1 -1
  13. package/dist/agents/transports/process-utils.d.ts.map +1 -1
  14. package/dist/agents.js +3 -2
  15. package/dist/agents.js.map +1 -1
  16. package/dist/build-identity.d.ts +21 -0
  17. package/dist/build-identity.d.ts.map +1 -0
  18. package/dist/chunks/{chunk-RERA6YWA.js → chunk-2A2NWQ36.js} +13 -5
  19. package/dist/chunks/chunk-2A2NWQ36.js.map +7 -0
  20. package/dist/chunks/{chunk-OTCASLY2.js → chunk-2QAOC3BO.js} +1 -1
  21. package/dist/chunks/chunk-2QAOC3BO.js.map +7 -0
  22. package/dist/chunks/{chunk-2PZWDVJB.js → chunk-2SWRVIYJ.js} +21 -9
  23. package/dist/chunks/chunk-2SWRVIYJ.js.map +7 -0
  24. package/dist/chunks/{chunk-4JETKRFE.js → chunk-36B4AIRT.js} +2 -2
  25. package/dist/chunks/{chunk-KFZYTGF5.js → chunk-3TXOQ5MG.js} +60 -46
  26. package/dist/chunks/chunk-3TXOQ5MG.js.map +7 -0
  27. package/dist/chunks/{chunk-VWSXAEX6.js → chunk-4NUTVNS2.js} +44 -202
  28. package/dist/chunks/chunk-4NUTVNS2.js.map +7 -0
  29. package/dist/chunks/{chunk-VYXFSUWU.js → chunk-77PDIBK2.js} +12 -1
  30. package/dist/chunks/{chunk-VYXFSUWU.js.map → chunk-77PDIBK2.js.map} +2 -2
  31. package/dist/chunks/{chunk-X7G62ZGH.js → chunk-7BG5COXB.js} +8 -3
  32. package/dist/chunks/{chunk-X7G62ZGH.js.map → chunk-7BG5COXB.js.map} +2 -2
  33. package/dist/chunks/{chunk-IYQ5MNCW.js → chunk-7VAZ4N43.js} +42 -24
  34. package/dist/chunks/chunk-7VAZ4N43.js.map +7 -0
  35. package/dist/chunks/chunk-A4VP7HDF.js +226 -0
  36. package/dist/chunks/chunk-A4VP7HDF.js.map +7 -0
  37. package/dist/chunks/chunk-B54Z662X.js +127 -0
  38. package/dist/chunks/chunk-B54Z662X.js.map +7 -0
  39. package/dist/chunks/{chunk-4SSMGBF4.js → chunk-CGL7QP4A.js} +58 -8
  40. package/dist/chunks/chunk-CGL7QP4A.js.map +7 -0
  41. package/dist/chunks/{chunk-32BNQ75J.js → chunk-FLKGJPCN.js} +99 -3
  42. package/dist/chunks/chunk-FLKGJPCN.js.map +7 -0
  43. package/dist/chunks/{chunk-QX3TUAWO.js → chunk-GGETIGM5.js} +487 -707
  44. package/dist/chunks/chunk-GGETIGM5.js.map +7 -0
  45. package/dist/chunks/{chunk-WVH324VF.js → chunk-IJL3QK3J.js} +3 -1
  46. package/dist/chunks/chunk-IJL3QK3J.js.map +7 -0
  47. package/dist/chunks/{chunk-3CPWRPCE.js → chunk-IK6PPFWG.js} +17 -6
  48. package/dist/chunks/chunk-IK6PPFWG.js.map +7 -0
  49. package/dist/chunks/{chunk-ZMIJ6AT4.js → chunk-IUCVOZRX.js} +3 -3
  50. package/dist/chunks/{chunk-3ZX76BVU.js → chunk-K6DHXXF5.js} +12 -10
  51. package/dist/chunks/chunk-K6DHXXF5.js.map +7 -0
  52. package/dist/chunks/{chunk-NPHCGLGH.js → chunk-MW5VI7IW.js} +135 -31
  53. package/dist/chunks/chunk-MW5VI7IW.js.map +7 -0
  54. package/dist/chunks/{chunk-BOTRGFQQ.js → chunk-NHMICIEU.js} +26 -19
  55. package/dist/chunks/chunk-NHMICIEU.js.map +7 -0
  56. package/dist/chunks/{chunk-Y7KNRAFL.js → chunk-PMSIZLV6.js} +29 -3
  57. package/dist/chunks/chunk-PMSIZLV6.js.map +7 -0
  58. package/dist/chunks/{chunk-7OH6DD3S.js → chunk-Q4XJ4PYL.js} +529 -168
  59. package/dist/chunks/chunk-Q4XJ4PYL.js.map +7 -0
  60. package/dist/chunks/chunk-RKRVOBVO.js +134 -0
  61. package/dist/chunks/chunk-RKRVOBVO.js.map +7 -0
  62. package/dist/chunks/{chunk-M3S7XITB.js → chunk-TGAVMUOS.js} +29 -13
  63. package/dist/chunks/chunk-TGAVMUOS.js.map +7 -0
  64. package/dist/chunks/chunk-TX6E5W7H.js +50 -0
  65. package/dist/chunks/chunk-TX6E5W7H.js.map +7 -0
  66. package/dist/chunks/{chunk-X3OD47CL.js → chunk-UR2K6WK6.js} +8 -11
  67. package/dist/chunks/chunk-UR2K6WK6.js.map +7 -0
  68. package/dist/chunks/{chunk-Z63R5GVN.js → chunk-WHBJDTCR.js} +6 -2
  69. package/dist/chunks/chunk-WHBJDTCR.js.map +7 -0
  70. package/dist/chunks/{chunk-RRGTKHXZ.js → chunk-X7XFT57O.js} +9 -140
  71. package/dist/chunks/{chunk-RRGTKHXZ.js.map → chunk-X7XFT57O.js.map} +4 -4
  72. package/dist/chunks/chunk-YV2PHCDB.js +108 -0
  73. package/dist/chunks/chunk-YV2PHCDB.js.map +7 -0
  74. package/dist/chunks/chunk-Z64PRP7A.js +156 -0
  75. package/dist/chunks/chunk-Z64PRP7A.js.map +7 -0
  76. package/dist/components/configuration.d.ts +42 -0
  77. package/dist/components/configuration.d.ts.map +1 -0
  78. package/dist/components/configuration.js +19 -0
  79. package/dist/components/configuration.js.map +7 -0
  80. package/dist/components/control.d.ts +76 -0
  81. package/dist/components/control.d.ts.map +1 -0
  82. package/dist/components/loader.d.ts +12 -0
  83. package/dist/components/loader.d.ts.map +1 -1
  84. package/dist/components/provider-component.d.ts +1 -1
  85. package/dist/components/provider-component.d.ts.map +1 -1
  86. package/dist/components/supervisor.d.ts.map +1 -1
  87. package/dist/components/types.d.ts +2 -0
  88. package/dist/components/types.d.ts.map +1 -1
  89. package/dist/components/validation.d.ts +6 -0
  90. package/dist/components/validation.d.ts.map +1 -0
  91. package/dist/config.d.ts +14 -2
  92. package/dist/config.d.ts.map +1 -1
  93. package/dist/core/action-registry.d.ts +9 -0
  94. package/dist/core/action-registry.d.ts.map +1 -1
  95. package/dist/core/action-registry.js +6 -4
  96. package/dist/core/approval-controller.d.ts +5 -1
  97. package/dist/core/approval-controller.d.ts.map +1 -1
  98. package/dist/core/auto-approval-classifier.d.ts +11 -0
  99. package/dist/core/auto-approval-classifier.d.ts.map +1 -1
  100. package/dist/core/compact-controller.d.ts.map +1 -1
  101. package/dist/core/fabric-state-paths.d.ts +2 -0
  102. package/dist/core/fabric-state-paths.d.ts.map +1 -0
  103. package/dist/core/media-sanitize.d.ts +46 -0
  104. package/dist/core/media-sanitize.d.ts.map +1 -0
  105. package/dist/core/model-resolution.d.ts +23 -5
  106. package/dist/core/model-resolution.d.ts.map +1 -1
  107. package/dist/core/semantic-search.d.ts +56 -0
  108. package/dist/core/semantic-search.d.ts.map +1 -0
  109. package/dist/core/shell-jobs.d.ts.map +1 -1
  110. package/dist/core/shell-middleware.d.ts +4 -0
  111. package/dist/core/shell-middleware.d.ts.map +1 -0
  112. package/dist/execution-service.d.ts +3 -1
  113. package/dist/execution-service.d.ts.map +1 -1
  114. package/dist/fabric-exec-tool.d.ts.map +1 -1
  115. package/dist/fabric-runtime-state.d.ts +2 -0
  116. package/dist/fabric-runtime-state.d.ts.map +1 -1
  117. package/dist/fabric-runtime-state.js +1595 -239
  118. package/dist/fabric-runtime-state.js.map +4 -4
  119. package/dist/fabric-state.d.ts +2 -0
  120. package/dist/fabric-state.d.ts.map +1 -1
  121. package/dist/index.d.ts.map +1 -1
  122. package/dist/index.js +284 -60
  123. package/dist/index.js.map +4 -4
  124. package/dist/jev/browser.d.ts.map +1 -1
  125. package/dist/jev/browser.js +1 -1
  126. package/dist/jev/client.d.ts +8 -2
  127. package/dist/jev/client.d.ts.map +1 -1
  128. package/dist/jev/client.js +3 -2
  129. package/dist/jev/config.d.ts.map +1 -1
  130. package/dist/jev/model-key.d.ts +9 -2
  131. package/dist/jev/model-key.d.ts.map +1 -1
  132. package/dist/jev/observation.js +4 -3
  133. package/dist/jev/routes.d.ts +69 -0
  134. package/dist/jev/routes.d.ts.map +1 -0
  135. package/dist/jev/validation.d.ts.map +1 -1
  136. package/dist/jev.d.ts +1 -0
  137. package/dist/jev.d.ts.map +1 -1
  138. package/dist/jev.js +35 -9
  139. package/dist/mcp.d.ts.map +1 -1
  140. package/dist/mcp.js +9 -2
  141. package/dist/mcp.js.map +2 -2
  142. package/dist/output-budget.d.ts.map +1 -1
  143. package/dist/prewalk/arm.d.ts.map +1 -1
  144. package/dist/prewalk/controller.d.ts +57 -6
  145. package/dist/prewalk/controller.d.ts.map +1 -1
  146. package/dist/prewalk/fs-drift.d.ts.map +1 -1
  147. package/dist/prewalk/handoff.d.ts +5 -25
  148. package/dist/prewalk/handoff.d.ts.map +1 -1
  149. package/dist/prewalk/messages.d.ts +24 -0
  150. package/dist/prewalk/messages.d.ts.map +1 -0
  151. package/dist/prewalk/model-switch.d.ts +3 -0
  152. package/dist/prewalk/model-switch.d.ts.map +1 -0
  153. package/dist/prewalk/plan.d.ts +46 -0
  154. package/dist/prewalk/plan.d.ts.map +1 -0
  155. package/dist/prewalk/return.d.ts +16 -0
  156. package/dist/prewalk/return.d.ts.map +1 -0
  157. package/dist/protocol.d.ts +11 -1
  158. package/dist/protocol.d.ts.map +1 -1
  159. package/dist/protocol.js +3 -1
  160. package/dist/providers/agents-actions.d.ts.map +1 -1
  161. package/dist/providers/agents-provider.d.ts.map +1 -1
  162. package/dist/providers/captured-tools-provider.d.ts.map +1 -1
  163. package/dist/providers/components-provider.d.ts +5 -3
  164. package/dist/providers/components-provider.d.ts.map +1 -1
  165. package/dist/providers/jev-provider.d.ts +2 -0
  166. package/dist/providers/jev-provider.d.ts.map +1 -1
  167. package/dist/providers/jev-provider.js +8 -7
  168. package/dist/providers/mcp-descriptor-cache.d.ts +2 -0
  169. package/dist/providers/mcp-descriptor-cache.d.ts.map +1 -1
  170. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  171. package/dist/providers/prewalk-provider.d.ts +19 -0
  172. package/dist/providers/prewalk-provider.d.ts.map +1 -0
  173. package/dist/repeat-guard.d.ts +4 -0
  174. package/dist/repeat-guard.d.ts.map +1 -1
  175. package/dist/residency/actor-client.d.ts +2 -2
  176. package/dist/residency/actor-client.d.ts.map +1 -1
  177. package/dist/residency/actor-client.js +2 -2
  178. package/dist/residency/client.d.ts +3 -0
  179. package/dist/residency/client.d.ts.map +1 -1
  180. package/dist/residency/host.d.ts.map +1 -1
  181. package/dist/residency/host.js +10 -8
  182. package/dist/residency/pi-entry.js +10 -8
  183. package/dist/residency/pi-entry.js.map +1 -1
  184. package/dist/residency/protocol.d.ts +15 -2
  185. package/dist/residency/protocol.d.ts.map +1 -1
  186. package/dist/runtime/core-override-guest-types.js +2 -2
  187. package/dist/runtime/cpython-runtime.d.ts +2 -0
  188. package/dist/runtime/cpython-runtime.d.ts.map +1 -1
  189. package/dist/runtime/cpython-runtime.js +7 -3
  190. package/dist/runtime/cpython-runtime.js.map +2 -2
  191. package/dist/runtime/guest-types.d.ts +1 -1
  192. package/dist/runtime/guest-types.d.ts.map +1 -1
  193. package/dist/runtime/guest-types.js +1 -1
  194. package/dist/runtime/monty-runtime.js +5 -3
  195. package/dist/runtime/monty-runtime.js.map +2 -2
  196. package/dist/runtime/node-process-runtime.d.ts.map +1 -1
  197. package/dist/runtime/node-process-runtime.js +3 -3
  198. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  199. package/dist/runtime/quickjs-runtime.js +1 -1
  200. package/dist/runtime/typescript-kernel.js +8 -8
  201. package/dist/runtime-state-builtins.d.ts.map +1 -1
  202. package/dist/schema/policy.d.ts.map +1 -1
  203. package/dist/ui/code-preview-shell.d.ts.map +1 -1
  204. package/dist/ui/controller.d.ts.map +1 -1
  205. package/dist/ui/conversation-native-reader.d.ts.map +1 -1
  206. package/dist/ui/conversation-native-reader.js.map +2 -2
  207. package/dist/ui/dashboard.js +2 -2
  208. package/dist/ui/settings-section-context.d.ts +1 -0
  209. package/dist/ui/settings-section-context.d.ts.map +1 -1
  210. package/dist/ui/settings-sections-agents.d.ts.map +1 -1
  211. package/dist/ui/settings-sections-execution.d.ts +1 -1
  212. package/dist/ui/settings-sections-execution.d.ts.map +1 -1
  213. package/dist/ui/settings-sections.d.ts +1 -0
  214. package/dist/ui/settings-sections.d.ts.map +1 -1
  215. package/dist/ui/settings-values.d.ts +1 -0
  216. package/dist/ui/settings-values.d.ts.map +1 -1
  217. package/dist/ui/settings.d.ts.map +1 -1
  218. package/dist/ui/settings.js +57 -17
  219. package/dist/ui/settings.js.map +2 -2
  220. package/dist/ui/spinner.d.ts +8 -1
  221. package/dist/ui/spinner.d.ts.map +1 -1
  222. package/dist/ui/widget.d.ts +12 -1
  223. package/dist/ui/widget.d.ts.map +1 -1
  224. package/dist/worker.js +1 -3
  225. package/dist/worker.js.map +2 -2
  226. package/docs/agents.md +35 -11
  227. package/docs/architecture.md +1 -1
  228. package/docs/components.md +30 -1
  229. package/docs/configuration.md +23 -15
  230. package/docs/foreman.md +65 -0
  231. package/docs/jev.md +77 -4
  232. package/docs/programmatic-compaction.md +12 -7
  233. package/docs/shell-middleware.md +61 -0
  234. package/docs/skills.md +2 -1
  235. package/package.json +5 -4
  236. package/skillsets/python/fabric-exec/SKILL.md +1 -1
  237. package/skillsets/python/fabric-exec/references/agents.md +1 -1
  238. package/skillsets/python/fabric-exec/references/mcp.md +1 -1
  239. package/skillsets/python/fabric-foreman/SKILL.md +249 -0
  240. package/skillsets/python/fabric-guide/SKILL.md +2 -1
  241. package/skillsets/python/fabric-jev/SKILL.md +2 -2
  242. package/skillsets/typescript/fabric-exec/SKILL.md +9 -3
  243. package/skillsets/typescript/fabric-exec/references/agents.md +5 -3
  244. package/skillsets/typescript/fabric-foreman/SKILL.md +240 -0
  245. package/skillsets/typescript/fabric-guide/SKILL.md +2 -1
  246. package/skillsets/typescript/fabric-jev/SKILL.md +2 -2
  247. package/dist/chunks/chunk-2IAVP4O2.js +0 -447
  248. package/dist/chunks/chunk-2IAVP4O2.js.map +0 -7
  249. package/dist/chunks/chunk-2PZWDVJB.js.map +0 -7
  250. package/dist/chunks/chunk-32BNQ75J.js.map +0 -7
  251. package/dist/chunks/chunk-3CPWRPCE.js.map +0 -7
  252. package/dist/chunks/chunk-3ZX76BVU.js.map +0 -7
  253. package/dist/chunks/chunk-4SSMGBF4.js.map +0 -7
  254. package/dist/chunks/chunk-7OH6DD3S.js.map +0 -7
  255. package/dist/chunks/chunk-BOTRGFQQ.js.map +0 -7
  256. package/dist/chunks/chunk-IYQ5MNCW.js.map +0 -7
  257. package/dist/chunks/chunk-KFZYTGF5.js.map +0 -7
  258. package/dist/chunks/chunk-M3S7XITB.js.map +0 -7
  259. package/dist/chunks/chunk-NPHCGLGH.js.map +0 -7
  260. package/dist/chunks/chunk-OTCASLY2.js.map +0 -7
  261. package/dist/chunks/chunk-QX3TUAWO.js.map +0 -7
  262. package/dist/chunks/chunk-RERA6YWA.js.map +0 -7
  263. package/dist/chunks/chunk-TSRKCXNI.js +0 -17
  264. package/dist/chunks/chunk-TSRKCXNI.js.map +0 -7
  265. package/dist/chunks/chunk-VWSXAEX6.js.map +0 -7
  266. package/dist/chunks/chunk-WVH324VF.js.map +0 -7
  267. package/dist/chunks/chunk-X3OD47CL.js.map +0 -7
  268. package/dist/chunks/chunk-Y7KNRAFL.js.map +0 -7
  269. package/dist/chunks/chunk-Z63R5GVN.js.map +0 -7
  270. /package/dist/chunks/{chunk-4JETKRFE.js.map → chunk-36B4AIRT.js.map} +0 -0
  271. /package/dist/chunks/{chunk-ZMIJ6AT4.js.map → chunk-IUCVOZRX.js.map} +0 -0
package/docs/agents.md CHANGED
@@ -26,13 +26,36 @@ You can give `fabric_exec` optional `agentBudget` and `tokenBudget` limits. Conf
26
26
 
27
27
  `agents.wait({id})` waits for a spawned agent; `agents.join({id})` is an alias with identical arguments, result, progress, and notification behavior. Use `wait` as the canonical spelling. The hosted `AgentService` and `AgentServiceClient` expose both methods too. [Jev programs](jev.md) follow the same `wait`/`join` naming.
28
28
 
29
+ ### Background completion inbox
30
+
31
+ `agents.spawn` returns immediately; independent work can continue without polling. With `agents.notifyOnComplete` enabled (the default), a concise UI notice appears when a detached run finishes. Full outcomes remain in agent activity and logs. Unread results are batched into Main's context after the current assistant turn's entire tool batch, rather than queued behind its final answer. If Main is idle, unread results wake it once.
32
+
33
+ `agents.wait`/`join`, terminal `agents.status`, and cleanup acknowledge the result and retract any pending notification, including completion that arrived before the wait. Running status and UI/list polling do not acknowledge results. Acknowledgment means the Fabric program received the result: return the relevant outcome to Main when it needs to reason about it. Prefer `wait` over a polling loop.
34
+
35
+ Durable spawns use the same inbox. Undelivered envelopes survive disconnects; receipts survive reconnects. Escape or an errored Main turn parks pending results until new input rather than immediately restarting Main. Explicit lifecycle subscriptions, actor messages, and trajectory handoffs retain their separate delivery policies. A terminal run can still report incomplete work; Main must inspect its result.
36
+
37
+ ### Reuse discovered model keys
38
+
39
+ Use `agents.models({ runner: "pi" })` and copy the returned `key` verbatim, or use an explicitly configured `models.aliases` name. Reuse the `model` returned by a successful spawn rather than reconstructing it from an agent's display name. For example, an agent named “Sol” need not share the version number of one named “Astra”. Prior success with one key does not validate a different key.
40
+
41
+ `provider/model` selectors prefer an exact visible match. A near-miss ID resolves to the closest available model on the **same provider**, using Fabric's existing similarity ranking; ties prefer recent usage, then canonical key order. For example, `openai-codex/gpt-6-sol` resolves to `openai-codex/gpt-5.6-sol` when that is the closest visible model. The returned handle's `model` and the worker's `requestedModel` contain the canonical selection. Unknown providers and names without sufficient resemblance still fail before launch. Model IDs containing `/` stay provider-scoped. Configured aliases keep their ordered, exact-target fallback chains.
42
+
43
+ For independent launches, await `Promise.allSettled` and inspect every result. An uncaught `Promise.all` rejection ends the Fabric program and can abort sibling calls still in flight; it does not prove every requested model was unavailable. Already completed calls are not rolled back, so retain successful handles rather than retrying the entire batch.
44
+
45
+ ```ts
46
+ const results = await Promise.allSettled(requests.map(request => agents.spawn(request)));
47
+ return results.map(result => result.status === "fulfilled"
48
+ ? { ok: true, handle: result.value }
49
+ : { ok: false, error: String(result.reason) });
50
+ ```
51
+
29
52
  ### Requested models are authoritative
30
53
 
31
54
  For Pi workers, Fabric reapplies the resolved `provider/model` over RPC **after startup extensions finish**, reapplies the requested thinking level, and independently reads `get_state` before sending the task. A successful `set_model` response alone is insufficient: it can echo the requested model even when an extension switches away during `model_select`. Thinking is reported at Pi's effective, capability-clamped level.
32
55
 
33
56
  Startup waits for a correlated RPC readiness response. Startup, model admission, and task execution share the run's configured `timeoutMs`; there is no separate 15-second admission cap. RPC readiness does not guarantee a fast `set_model`: authentication checks and async `model_select` hooks can still wait on provider initialization or shared resources during concurrent launches. A slow handshake may use the remaining run budget, but it never resets or extends the overall deadline.
34
57
 
35
- Unavailable models, rejected/malformed RPC responses, or a remaining model mismatch fail the run without sending its task. A startup or admission stall exhausts the overall deadline with `timed_out`, also without sending the task. Queued controls wait for admission too. Fabric does not substitute an MRU model or silently fall back. Standalone `AgentManager` callers can also supply a unique exact bare model ID; ambiguous IDs must be provider-qualified.
58
+ Selectors with no available match, rejected/malformed RPC responses, or a remaining model mismatch fail the run without sending its task. A startup or admission stall exhausts the overall deadline with `timed_out`, also without sending the task. Queued controls wait for admission too. After parent-side selector resolution, the worker must use that canonical model: it does not substitute an MRU model or fall back during admission. Standalone `AgentManager` callers can also supply a unique exact bare model ID; ambiguous IDs must be provider-qualified.
36
59
 
37
60
  `requestedModel` preserves launch intent in run records; `model` follows verified child state and actual assistant attribution. The manager and participant UI preserve that observed value; the launch label cannot overwrite it. If assistant attribution drifts after admission, Fabric terminates the child and reports both requested and observed models in the failure. This verifies Pi's local provider/model identity, not a remote provider's internal routing.
38
61
 
@@ -182,21 +205,22 @@ Host extensions that must serialize work after prewalk can use the acknowledged
182
205
 
183
206
  The default value of `prewalk.mode` is `"in-place"`:
184
207
 
185
- 1. Fabric detects a successful `pi.edit`, `pi.write`, or `schema.commit`, then lets the full outer program settle. A successful `pi.bash` or `pi.powershell` can also trigger detection when no audited mutation occurred. In that case, a stat-baseline diff of the work tree identifies shell writes such as heredocs, `sed -i`, and formatter binaries as a filesystem trigger (`fs.drift`). Set `prewalk.detectShellWrites` to `false` to disable this behavior.
186
- 2. At the finalized outer result boundary, Fabric selects `prewalk.model` on Main.
187
- 3. Fabric queues a hidden follow-up. It tells Main to continue the current task, complete the remaining implementation, check related call sites, and run verification.
188
- 4. The terminating outer tool prevents an automatic turn on the old model. Pi drains the queued follow-up and continues the same Main session on the executor model.
189
- 5. After the continuation settles, Fabric compacts the session with the configured compaction engine. Set `prewalk.compactOnReturn` to `false` to skip this step. Fabric then restores the Main model captured at the boundary.
208
+ 1. The arm owes a recorded plan before any handoff. With `prewalk.requirePlan` (default on), a mutation boundary reached without one is withheld: Fabric delivers a hidden plan checkpoint to Main that asks for `prewalk.plan({ outcome, steps, verification, risks })` inside `fabric_exec`. That recorded plan is the readiness signal: Fabric snapshots it at claim time and delivers it in the hidden continuation (in-place) or the executor task (trajectory), so the executor receives it even if the action result is discarded or the outer output is truncated. Main keeps working on the frontier model, nothing is selected or switched, and the arm stays armed.
209
+ 2. Fabric detects the next successful `pi.edit`, `pi.write`, or `schema.commit`, then lets the full outer program settle. An audited mutation also consumes the shell-write drift window, so those edits cannot re-fire as `fs.drift` on a later read-only shell boundary. A successful `pi.bash` or `pi.powershell` can also trigger detection when no audited mutation occurred. In that case, a stat-baseline diff of the work tree identifies shell writes such as heredocs, `sed -i`, and formatter binaries as a filesystem trigger (`fs.drift`). Set `prewalk.detectShellWrites` to `false` to disable this behavior.
210
+ 3. At the finalized outer result boundary, Fabric selects `prewalk.model` on Main.
211
+ 4. Fabric sends one hidden continuation as a passive context message. It tells Main to continue the current task, complete the remaining implementation, check related call sites, and run verification. That single message carries the captured task text, the recorded plan when one exists, and — when the reasoning channel is not replayable — a bounded advisory digest of the frontier model's deliberation. Fabric also keeps it as the claim's canonical payload, and the request-context hook injects it into any request that would otherwise run without it.
212
+ 5. The boundary does not terminate the outer tool. The same Main session keeps running on the executor model and its next request follows naturally, carrying the continuation exactly once. Claiming a prewalk-in-place handoff therefore suppresses `terminate` from the boundary result. Competing user steers drain in order into that request instead of delaying the continuation, and no completion-only turn follows. The passive message is persisted after the boundary turn's tool results, so later turns and runs read it from the transcript.
213
+ 6. After the continuation settles, Fabric compacts the session with the configured compaction engine. Set `prewalk.compactOnReturn` to `false` to skip this step. Fabric then restores the Main model captured at the boundary.
190
214
 
191
- In-place mode uses Main directly and keeps one transcript. It works with `agents.enabled` set to `false`. Pi's public extension model switch can leave the executor selected on Main, including in a later session that inherits it, so Fabric restores the captured Main model when the continuation settles, when a new session is still on that executor, and when prewalk is cancelled or reloaded. A switch can fail before continuation when the model is unavailable or unauthenticated. The outer result then reports the cause. Fabric queues a hidden follow-up that asks Main to report the failure and propose the next action.
215
+ In-place mode uses Main directly and keeps one transcript. It works with `agents.enabled` set to `false`. Pi's public extension model switch can leave the executor selected on Main, including in a later session that inherits it, so Fabric restores the captured Main model when the continuation settles, when a new session is still on that executor, and when prewalk is cancelled or reloaded. A switch can fail before continuation when the model is unavailable or unauthenticated. The outer result then reports the cause, and because the in-place boundary does not terminate, Main keeps running on its captured model and explains the failure in that same run; no queued follow-up repeats it. The return after a settled continuation can also fail. Fabric then drops the arm instead of re-arming, keeps the failure visible, and preserves the captured Main model: a later session start or `/fabric reload` retries the return, auto-arm stays skipped while Main is still on the executor, and an explicit `/fabric prewalk` arm overrides.
192
216
 
193
217
  Set `prewalk.mode` to `"trajectory"` to use child-based behavior. Fabric forks the exact finalized outer call and result into a Pi child. It starts the selected executor in the shared workspace and waits. When the child finishes, Fabric replaces the boundary result with the executor report and queues a hidden continuation. Main verifies the implementation with the applicable checks and provides a summary. It does not repeat completed executor work, and it relays links, PR numbers, and commit hashes verbatim. If the child fails, stops, or times out, Fabric queues a hidden follow-up that reports the result and proposes an action. Main always tells the user how execution ended and what the child completed. Every boundary reports a result. The executor uses `prewalk.thinking` for reasoning effort. When unset, it inherits `agents.thinking`. The parent Fabric card and activity UI display the synthetic `agents.handoff` call, child identity, live status or current tool, nested preview, metrics, and terminal result. Users can see progress during the wait. Trajectory mode requires enabled agents. Explicit `agents.handoff()` also uses this behavior.
194
218
 
195
- **Thinking transfer across models.** Providers define the shape of stored thinking blocks. Codex uses encrypted reasoning items. Anthropic requires valid signatures. Replaying these blocks to another provider can place them in unusable request fields or cause failure. Fabric applies a family policy when it writes the trajectory child session. It uses `preserved` when the executor has the same provider and API family as the source model. For openai-completions reasoning targets, it uses `re-signed`. This policy keeps the thinking text and normalizes the signature to `reasoning_content`, which lets preserve-thinking servers receive earlier reasoning. For other targets, Fabric uses `stripped`. Fabric removes the thinking blocks and foreign thought signatures, then adds a bounded digest custom message with entry IDs for continuity. The digest covers deliberation only. Fabric records the policy and counts under `thinkingTransfer` in the child's `pi-fabric-handoff` custom entry. In-place prewalk cannot rewrite Pi's session log. When channels are incompatible, it sends the same digest in a hidden follow-up. Fabric never modifies the source session.
219
+ **Thinking transfer across models.** Providers define the shape of stored thinking blocks. Codex uses encrypted reasoning items. Anthropic requires valid signatures. Replaying these blocks to another provider can place them in unusable request fields or cause failure. Fabric applies a family policy when it writes the trajectory child session. It uses `preserved` when the executor has the same provider and API family as the source model. For openai-completions reasoning targets, it uses `re-signed`. This policy keeps the thinking text and normalizes the signature to `reasoning_content`, which lets preserve-thinking servers receive earlier reasoning. For other targets, Fabric uses `stripped`. Fabric removes the thinking blocks and foreign thought signatures, then adds a bounded digest custom message with entry IDs for continuity. The digest covers the current task's deliberation from the boundary model only — never an earlier task's or another model's reasoning — and is omitted when no current task boundary carries usable thinking. Fabric records the policy and counts under `thinkingTransfer` in the child's `pi-fabric-handoff` custom entry. In-place prewalk cannot rewrite Pi's session log. When channels are incompatible, it embeds the same digest in the hidden continuation message. Fabric never modifies the source session.
196
220
 
197
- Prewalk does not add system-prompt instructions. It queues its hidden continuation only after a matching mutation boundary. The continuation is not an open-ended prompt on each turn. A turn that settles without a handoff leaves prewalk armed. A matching mutation consumes the arm through an in-place switch or trajectory spawn. A completed explicit `agents.handoff()` also consumes it, as does `/fabric prewalk --off`. Fabric drops the settled turn's captured task text so that it captures the next prompt as new input. Both modes require full code mode. Schema enforce mode does not support them.
221
+ Prewalk does not add system-prompt instructions. It queues its hidden continuation only after a matching mutation boundary, so the continuation is not an open-ended prompt on each turn. The plan checkpoint is one hidden custom message per boundary that still owes a plan, delivered as a steer so it lands before the frontier model's next call, and it is never a system prompt. Readiness comes from the `prewalk.plan` action, and the claimed handoff carries the plan explicitly: the executor sees the full recorded plan in its first continuation request or task, not only a nested tool result. While a handoff is in flight, `prewalk.status` also reports the claim's `claimedReadiness` (`planned`, `disabled`, or `unplanned`), distinguishing a plan that was recorded and consumed from an arm that never recorded one. A boundary keeps withholding while the plan is missing and asks at most twice for a task, then hands off unplanned with a visible warning so an armed session cannot stall. A recorded plan survives a failed handoff and is dropped when the captured task changes; re-arming, cancelling, or reloading Fabric resets readiness so the next task plans again. Use `prewalk.status` inside `fabric_exec` for the arm state and its readiness flags. It also reports the loaded build identity of the extension entry and the lazy runtime module against the files currently on disk (`runtime.entry`, `runtime.lazyRuntime`, each with `loadedSha256`, `diskSha256`, and `stale`). Pi's loader native-imports `type: module` ESM extensions, and `/reload` clears only its factory cache, not the process ESM registry: an extension path the process has already imported keeps its first evaluation until the session process restarts. After rebuilding pi-fabric, restart the session to run the new build; `prewalk.status` is the one-call check for whether the loaded runtime is stale. A turn that settles without a handoff leaves prewalk armed. A matching mutation consumes the arm through an in-place switch or trajectory spawn. A completed explicit `agents.handoff()` also consumes it, as does `/fabric prewalk --off`. Fabric drops the settled turn's captured task text so that it captures the next prompt as new input. Both modes require full code mode. Schema enforce mode does not support them.
198
222
 
199
- The filesystem fallback compares each file's size and mtime with a baseline captured when prewalk was armed. Fabric refreshes the baseline after every considered boundary and settle. In Git work trees, it lists files through the index, so ignored build output does not register. In trees without Git, it walks the files and skips only `.git` and `node_modules`. Artifact writes then count as drift. The diff cannot identify who made a change. An external editor save during a shell-running window also counts. The fallback scans only programs that ran `pi.bash`, so read-only turns have no scan cost and cannot trigger it. Stat drift can occur without a content change, for example from rare `touch` churn. This drift triggers prewalk. The report lists affected files in `trigger.files`.
223
+ The filesystem fallback compares each file's size and mtime with a baseline captured when prewalk was armed. Fabric refreshes the baseline after every considered boundary and settle. In Git work trees, it lists files through the index, so ignored build output does not register. In trees without Git, it walks the files and skips only `.git` and `node_modules`. Both listings exclude Fabric's own state directory before the tracked-file cap, so runtime cache writes are bookkeeping that neither triggers prewalk nor consumes the tracking budget. Other tools keep their own directories, and Fabric does not encode them: a Git work tree follows the project's ignore rules, so adding a tool directory to `.gitignore` removes it from the listing. Artifact writes elsewhere then count as drift. The diff cannot identify who made a change. An external editor save during a shell-running window also counts. The fallback scans only programs that ran `pi.bash`, so read-only turns have no scan cost and cannot trigger it. Stat drift can occur without a content change, for example from rare `touch` churn. This drift triggers prewalk. The report lists affected files in `trigger.files`.
200
224
 
201
225
  ### Claude Code runner
202
226
 
@@ -263,7 +287,7 @@ await agents.switchModel({ model: "cheap" });
263
287
 
264
288
  The selector resolves in order: a `models.aliases` entry (a string alias is one target; an array is a fallback chain where the first authenticated target wins), an exact `provider/id`, an exact model id, then the closest match across provider, id, and display name. Closeness ties fall to the most recently used model, read from the [pi-model-sort](https://github.com/monotykamary/pi-model-sort) extension's usage store when it is installed, and then to the highest-sorting key, mirroring pi's newest-alias convention. An optional `provider` argument narrows every stage. Selectors with no resemblance to an authenticated entry and exhausted alias chains throw; the session model stays unchanged. `agents.models()` enumerates the authenticated registry entries this resolution runs against. The result reports the active model, the previous one, and how the selector resolved: `via` is the alias name for configured aliases, or `closest`, `recent`, or `latest` for fuzzy picks. A call naming the active model returns `{ switched: false, reason: "already-active" }`. The switch applies to the next model turn and later, unlike `prewalk`, which temporarily installs an executor model at a mutation boundary and then restores the boundary model.
265
289
 
266
- Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff`, plus actor defaults and activation overrides, resolve through the same selector logic (aliases, closest match, recency). The execution owner's `agents.models({ runner: "pi" })` result is authoritative: unresolved exact IDs, fuzzy selectors with no match, and exhausted aliases fail with a session-availability error. Fabric revalidates the canonical model at the worker launch boundary, including remote and durable actor execution, so stale bindings cannot start a model that is no longer visible. Catalog-fresh or custom IDs must appear in the owner's visible registry before a Pi participant can use them. Claude and Veda model values keep their runner-specific behavior.
290
+ Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff`, plus actor defaults and activation overrides, resolve through the same selector logic (aliases, closest match, recency). The execution owner's `agents.models({ runner: "pi" })` result is authoritative: provider-qualified near-misses are matched only on that provider, selectors with no similar visible candidate and exhausted aliases fail with a session-availability error. Fabric revalidates the canonical model at the worker launch boundary, including remote and durable actor execution, so stale bindings cannot start a model that is no longer visible. Catalog-fresh or custom IDs must appear in the owner's visible registry before a Pi participant can use them. Claude and Veda model values keep their runner-specific behavior.
267
291
 
268
292
  This is the host-level equivalent of the `pi-model-switch` extension's `switch_model` tool, with aliases moved into Fabric configuration so project and agent scopes behave like every other Fabric section.
269
293
 
@@ -99,7 +99,7 @@ preflight, and callers requiring all final errors to throw should omit `settle`.
99
99
 
100
100
  ## Model-context economy
101
101
 
102
- Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed.
102
+ Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed. Raw media never enters those text channels: image payloads in `fabric_exec` logs, results, and error text, in worker event lines, and in actor host events are replaced by a `{type: "image", mediaIndex, mimeType, redacted: true}` descriptor and hoisted out of band, so a nested `pi.read` image stays available to a multimodal model without pushing hundreds of KB of base64 into one serialized line. A child event line that only exceeds the 4 MB cap because it embeds raw base64 is sanitized instead of failing the run.
103
103
 
104
104
  ## Federated participant topology
105
105
 
@@ -138,7 +138,36 @@ Declare instances at the root of `fabric.json`:
138
138
  }
139
139
  ```
140
140
 
141
- A definition may arrive after the configuration that references it. The unresolved instance stays `waiting` and lists `component:<name>` in `missing`. Component discovery activates the instance later. `/fabric reload` reconciles changed entries. When a later activation fails during a multi-entry reconciliation, Fabric rolls back the additions and replacements from that pass. Two live component records may never declare the same provider name. Fabric rejects the insertion or replacement before it disturbs either fiber.
141
+ A definition may arrive after the configuration that references it. The unresolved instance stays `waiting` and lists `component:<name>` in `missing`. Component discovery activates the instance later. Once the runtime is active, trusted configuration edits reconcile automatically; `/fabric reload` is not required. When a later activation fails during a multi-entry reconciliation, Fabric rolls back the additions and replacements from that pass. Two live component records may never declare the same provider name. Fabric rejects the insertion or replacement before it disturbs either fiber.
142
+
143
+ ### Live configuration control
144
+
145
+ Components are generic host primitives. Connector packages own browser, desktop, application, and transport behavior; neither component management nor Jev needs a built-in tool for each integration. Register the definition through the ordinary extension protocol, then configure instances through the same live control plane.
146
+
147
+ A definition may declare `configSchema`, using the same JSON Schema validation engine as tool arguments. Fabric validates config before activation or replacement, including direct supervisor calls. Schema defaults are annotations, not injected values. Without a schema, legacy definitions keep their activation-time validation. `components.describe` returns the schema even when no instance exists; it is a configuration contract, not a connectivity or health check. Effective tool grants are still obtained from the mounted provider's action descriptors.
148
+
149
+ ```ts
150
+ const definition = await components.describe({ component: "issue-observer" });
151
+ const plan = await components.plan({
152
+ entries: [{ id: "issues", component: definition.name, config: { prefix: "repo:owner/project" } }],
153
+ });
154
+ // Inspect plan.changes, warnings, and sources before applying. Normal approvals still apply.
155
+ await components.apply({ ...plan.request, expectedRevision: plan.revision });
156
+ ```
157
+
158
+ - `entries` upserts complete entries by ID; it does not replace unrelated entries or merge nested config. `remove` removes IDs. An ID may occur only once in one request.
159
+ - Scope defaults to `session`: no file is written. Session overlays survive file reconciliation and settings saves; they end on runtime/session reload or shutdown. `reset: ["issues"]` in session scope removes an overlay and restores the file-configured value. A session removal masks that ID until reset. The session layer is limited to 256 overrides, including removal masks; the effective manifest is also limited to 256 entries.
160
+ - Explicit `scope: "global"` or `"project"` persists only the component array in that layer, preserving unrelated settings. Project arrays shadow global arrays, just like normal configuration. Plans report shadowing; persistent writes do not implicitly clear session overlays. Project writes require current project trust and never silently fall back to global.
161
+ - Plans report a revision, declared requirements/provisions, sources, and warnings without running component activation. Apply revalidates and rejects stale revisions after concurrent changes. Missing definitions can be configured and remain waiting. A successful apply may therefore return waiting instances; inspect their status before use.
162
+ - Apply runs the loader transaction before persistence. A failed activation leaves disk untouched. A failed compare-before-write triggers runtime compensation, without overwriting the external edit. Failed compensation is reported, never claimed successful. This is not an atomic transaction across multiple processes, files, or remote effects.
163
+ - `components.reconcile()` re-reads trusted files without reinitializing Fabric. The active runtime also watches both file paths (250 ms stat interval, 50 ms debounce), including file creation, deletion, and atomic replacement. Content revisions suppress redundant reconciliation. The watcher reads only trusted layers and never repairs or quarantines malformed live files. Invalid edits retain the last applied state and appear in `components.list().configuration.error` and the UI. Its watchers and timers stop with the owning runtime.
164
+ - Before first use, bootstrap stays idle: no watcher imports optional engines or starts connectors. First use rereads component configuration. Activation does not imply that a connector has connected or requested OS permissions; connector packages own explicit, lazy acquisition and health reporting.
165
+ - `components.list().configuration` reports source paths, trust, selected layers, session override IDs, and warnings. An untrusted project file is reported as ignored without parsing it. Diagnostics report provenance rather than raw configuration documents; activation errors remain author-supplied.
166
+ - Apply/reconcile are host-control operations, unavailable to committed guest views and in managed hosts or Schema enforce mode. Existing approval and schema policy gates still apply. Built-in `fabric.provider.*` components cannot be changed by this configuration API; their existing reload control remains separate.
167
+
168
+ Replacement uses the existing retire-before-activate path, not zero-downtime migration. New calls resolve the new generation after commit; unrelated providers and Jev runs are not restarted. Existing committed views may continue using the retired generation until release. Removal uses the same **drain** policy, not immediate security revocation. Owners must retain supporting connections/processes until provider `close()`. Connector session IDs and observed handles must not be silently moved between generations. Cancellation after activation begins does not abandon commit/compensation and cannot undo already-issued external effects.
169
+
170
+ The host protocol exports `FabricComponentChangeRequest` and `FabricComponentChangePlan` types. Guest provider declarations expose all four new methods; newly mounted namespaces can be called immediately through `tools.call({ref,args})` in the same program. This avoids assuming a new static proxy existed when that program was typechecked.
142
171
 
143
172
  ## Model-facing guidance components
144
173
 
@@ -53,7 +53,7 @@ Monty is always sandboxed, including under schema enforce, and does not require
53
53
 
54
54
  Every raised deadline is capped by `executor.maxTimeoutMs` (default `900000`, i.e. 15 minutes: the former undocumented clamp, now explicit), which itself can be raised up to the hard implementation maximum of 24 hours. Values above a cap are visibly normalized down to the cap during config load and the effective values are shown in `/fabric` settings, never silently surprising. A per-invocation request or ref floor takes effect even when the ref is unknown to Fabric, so captured tools, MCP calls, and future host calls all run within an intentionally longer deadline without Fabric knowing their argument semantics. Existing `pi.bash` behavior (extending the deadline from an explicit `timeout` argument) is unchanged, and deadline expiry still cancels the active host call and any child process it owns.
55
55
 
56
- `executor.shellHangMs` (default `120000` / 2 minutes, max `600000` / 10 minutes, `0` disables) is a nested-shell wait budget, not a program deadline. When a `pi.bash` / `pi.powershell` await exceeds it, Fabric **settles the await successfully** (`ok: true`) with a still-running notice, pid, and live output path while the process keeps writing that file. `background: true` (alias `run_in_background`) detaches immediately with the same envelope. Inspect with `pi.read(logPath)` and stop by running `kill <pid>` through `pi.bash`. Do not poll. An explicit shell `timeout` remains a hard cap. **ctrl+b twice** spills early (tmux-safe); **ctrl+k** kills the waiting command. Session shutdown aborts leftover processes.
56
+ `executor.shellHangMs` (default `120000` / 2 minutes, max `600000` / 10 minutes, `0` disables) is a nested-shell wait budget, not a program deadline. When a `pi.bash` / `pi.powershell` await exceeds it, Fabric **settles the await successfully** (`ok: true`) with a still-running notice, pid, and live output path while the process keeps writing that file. `background: true` (alias `run_in_background`) detaches immediately with the same envelope. Inspect with `pi.read(logPath)` and stop by running `kill <pid>` through `pi.bash`. Do not poll. An explicit shell `timeout` remains a hard cap. **ctrl+b twice** spills early (tmux-safe); **ctrl+k** kills the waiting command. Session shutdown aborts leftover processes. Captured shell overrides normally keep their own execution semantics; an extension can opt into [Fabric-owned bash execution with middleware](shell-middleware.md) to preserve its environment/output filters while gaining the same background handling.
57
57
 
58
58
  The precedence across all sources is:
59
59
 
@@ -201,7 +201,7 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
201
201
 
202
202
  ## Jev System One
203
203
 
204
- `jev` configures TypeSafe typed judgments and session-owned foreground/background programs. It is enabled by default but makes no inference requests until called. `/login jev` stores API-key credentials through Pi; `TYPESAFE_API_KEY` and an explicitly configured `jev.credentialCommand` argv are also supported. Never store the resolved secret in `fabric.json`.
204
+ `jev` configures TypeSafe typed judgments and session-owned foreground/background programs. It is enabled by default but makes no inference requests until called. `/login jev` stores API-key credentials through Pi; `TYPESAFE_API_KEY` and an explicitly configured `jev.credentialCommand` argv are also supported. Bare `jev.model` aliases use TypeSafe; `typesafe/...` or `~typesafe/...` model IDs use OpenRouter's decisions endpoint with the existing `openrouter` credential (`/login openrouter`, `OPENROUTER_API_KEY`, or `TYPESAFE_OPENROUTER_API_KEY`); `typesafe-ai/...` model IDs use Vercel AI Gateway's TypeSafe-compatible endpoint with the existing `vercel-ai-gateway` credential (`/login vercel-ai-gateway` or `AI_GATEWAY_API_KEY`). Never store the resolved secret in `fabric.json`.
205
205
 
206
206
  Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTokens`, `maxConcurrentRuns`, and `maxRetainedRuns`. Request controls are `model`, `requestTimeoutMs`, and `maxRequestBytes`. Per-program limits cannot raise these ceilings. See [Jev programs](jev.md) for defaults, typed schemas, cancellation, and the optional `browser-harness` component. Jev is unavailable in Schema enforce and managed-host modes.
207
207
 
@@ -209,7 +209,7 @@ Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTok
209
209
 
210
210
  `components` is a root array of declarative supervised instances. Each `id` gives one instance a stable identity, and `component` names its definition in the versioned protocol. Fabric passes `config` to `activate(context, config)`. The `disabled` field removes an instance from the active graph and preserves its declaration. An empty array is the default, with a limit of 256 valid entries. The runtime installs enabled first-party providers as pinned `fabric.provider.*` components whose reserved IDs sit outside this array.
211
211
 
212
- Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. `/fabric reload` reconciles entry changes as a transaction. When a definition re-registers with `overwrite: true`, Fabric uses the same rollback-capable replacement path. See [components, effects, and committed capabilities](components.md).
212
+ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. Once the runtime is active, trusted file edits reconcile automatically without `/fabric reload`; idle bootstrap remains lazy and first use rereads the component configuration. Invalid live edits keep the last working state and are never repaired or renamed by the watcher. `components.describe`, `components.plan`, `components.apply`, and `components.reconcile` provide the same control plane to programs. Changes default to session scope; global/project persistence is explicit, and untrusted project writes are rejected rather than redirected. Project component arrays replace global arrays; session overrides apply by ID on top. Definitions may declare `configSchema` for pre-activation validation. When a definition re-registers with `overwrite: true`, Fabric uses the same rollback-capable replacement path. See [components, effects, and committed capabilities](components.md#live-configuration-control).
213
213
 
214
214
  ## Speculation
215
215
 
@@ -239,24 +239,27 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
239
239
 
240
240
  `prewalk.thinking` sets the optional reasoning effort for the trajectory child executor. Its values are `off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`, clamped to each model's supported levels. When you leave it unset, the executor inherits `agents.thinking`. In-place mode keeps Main's session level.
241
241
 
242
- `prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion). Every Main session then starts armed automatically, non-interactively from `prewalk.model`, and `/fabric reload` re-arms Main as well. Child agents and actors never auto-arm from inherited settings; explicit arming is unaffected. `/fabric prewalk --off` cancels the armed state until the next session start or reload. Turns that settle without a handoff never disarm prewalk, regardless of this setting. The settings UI labels an unset model **Ask each time**. Non-interactive sessions must configure a model. In-place mode does not require child agents. Trajectory mode requires `agents.enabled`. It shows child spawn, progress, nested tools, metrics, and completion in Main's Fabric activity UI.
242
+ `prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion); a failed in-place return drops the arm instead of completing it. Every Main session then starts armed automatically, non-interactively from `prewalk.model`, and `/fabric reload` re-arms Main as well. Child agents and actors never auto-arm from inherited settings; explicit arming is unaffected. `/fabric prewalk --off` cancels the armed state until the next session start or reload. Turns that settle without a handoff never disarm prewalk, regardless of this setting. The settings UI labels an unset model **Ask each time**. Non-interactive sessions must configure a model. In-place mode does not require child agents. Trajectory mode requires `agents.enabled`. It shows child spawn, progress, nested tools, metrics, and completion in Main's Fabric activity UI.
243
243
 
244
- `prewalk.detectShellWrites` defaults to `true`. When armed, a `fabric_exec` boundary that ran a successful `pi.bash` or `pi.powershell` without an audited `pi.edit` / `pi.write` / `schema.commit` claims the handoff if file size or mtime stats drifted from the arm-time baseline. This routes shell heredocs and formatter binaries to the executor as well. The report's `trigger.files` lists the bounded drifted paths. Set it to `false` to accept audited mutations only.
244
+ `prewalk.detectShellWrites` defaults to `true`. When armed, a `fabric_exec` boundary that ran a successful `pi.bash` or `pi.powershell` without an audited `pi.edit` / `pi.write` / `schema.commit` claims the handoff if file size or mtime stats drifted from the arm-time baseline. This routes shell heredocs and formatter binaries to the executor as well. The report's `trigger.files` lists the bounded drifted paths. An audited mutation consumes the shell-write drift window, so earlier edits cannot re-fire on a later read-only shell boundary. Fabric's own state directory never registers and does not consume the tracked-file cap. Other tool directories follow the project's ignore rules, so a Git work tree excludes them through `.gitignore`. Set this option to `false` to accept audited mutations only.
245
+
246
+ `prewalk.requirePlan` defaults to `true`. An armed task owes a recorded plan before its mutation boundary can hand off, whether the trigger is an audited `pi.edit` / `pi.write` / `schema.commit` or shell drift under `detectShellWrites`. A boundary reached without a plan is withheld: Fabric delivers a hidden plan checkpoint to Main that asks for `prewalk.plan({ outcome, steps, verification, risks })` inside `fabric_exec`. That recorded plan is the readiness signal: Fabric snapshots it at claim time and delivers it in the executor's hidden continuation or child task, so delivery does not depend on the outer tool result surviving. The arm stays armed across the checkpoint and the frontier model keeps working. Fabric asks at most twice per task, then hands off unplanned with a visible warning so an armed session cannot stall. A recorded plan survives a failed handoff that returns to armed, and Fabric drops it when the captured task changes; cancelling, re-arming, or reloading Fabric resets readiness so the next task plans again. Checkpoint delivery is a hidden custom message, never a system prompt. Set this option to `false` to hand off on the first mutation. `prewalk.status` inside `fabric_exec` reports `planRequired`, `planReady`, and the reminder count for the current session.
245
247
 
246
248
  `prewalk.compactOnReturn` defaults to `true`. When an in-place continuation settles, Fabric requests a compaction with the configured `compaction.engine` and commits it while the executor is still the active model. Main's restored model receives the compacted transcript. Set this option to `false` when Main must receive the complete transcript.
247
249
 
248
- Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too.
250
+ Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. A process that restarts while a continuation is still pending restores that captured model from the persisted continuation at the next session start, before the session auto-arms. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too. When the return itself fails, the arm is dropped instead of re-armed and the failure is reported: the captured Main model is preserved so a later session start or `/fabric reload` retries the return, auto-arm is skipped while Main is still on the executor, and an explicit `/fabric prewalk` arm overrides.
249
251
 
250
252
  ## Models
251
253
 
252
- `models.aliases` names model selectors for `agents.switchModel` and for Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff` (see [Agents](agents.md#switching-mains-session-model)). Each alias is either one `provider/model` target or an ordered fallback chain; resolution walks the chain and uses the first authenticated target. Alias names match case-insensitively and take priority over bare model ids and fuzzy matching. Aliases live in normal Fabric configuration, so a project `.pi/fabric.json` can extend the agent-level `fabric.json`; entries with malformed names or targets are ignored at load.
254
+ `models.aliases` names model selectors for `agents.switchModel` and for Pi-runner `model` arguments on `agents.run`, `agents.spawn`, `agents.create`, and `agents.handoff` (see [Agents](agents.md#switching-mains-session-model)). Each alias is either one `provider/model` target, an ordered fallback chain, or an object `{"model": <target or chain>, "thinking": <level>}`. Resolution walks the chain and uses the first authenticated target. Alias names match case-insensitively and take priority over bare model ids and fuzzy matching. Aliases live in normal Fabric configuration, so a project `.pi/fabric.json` can extend the agent-level `fabric.json`; entries with malformed names or targets are ignored at load, and an unrecognized `thinking` level is dropped while the alias survives. An alias `thinking` level is the default effort for every run that selects it: an explicit `thinking` on the call or actor wins, and `agents.thinking` applies only when the alias sets none. `agents.switchModel` changes only the session model, so an alias thinking level does not apply there.
253
255
 
254
256
  ```json
255
257
  {
256
258
  "models": {
257
259
  "aliases": {
258
260
  "cheap": "google/gemini-2.5-flash",
259
- "budget": ["openai/gpt-5-mini", "google/gemini-2.5-flash"]
261
+ "budget": ["openai/gpt-5-mini", "google/gemini-2.5-flash"],
262
+ "shallow": { "model": "google/gemini-2.5-flash", "thinking": "low" }
260
263
  }
261
264
  }
262
265
  }
@@ -387,7 +390,7 @@ The classifier receives the exact action, bounded prepared arguments, cwd, user-
387
390
 
388
391
  ### Jev as the auto-mode classifier
389
392
 
390
- Select **Jev (TypeSafe safety classifier)** in **Approvals → Auto model** after `/login jev`, or configure:
393
+ Select a Jev entry in **Approvals → Auto model** after `/login jev` (TypeSafe route), `/login openrouter` (OpenRouter route), or `/login vercel-ai-gateway` (Vercel AI Gateway route), or configure:
391
394
 
392
395
  ```json
393
396
  {
@@ -401,17 +404,17 @@ Select **Jev (TypeSafe safety classifier)** in **Approvals → Auto model** afte
401
404
  }
402
405
  ```
403
406
 
404
- Jev is an auth-only provider, not a chat model. This picker offers `pi-fabric/typesafe/jev-latest` and `pi-fabric/typesafe/jev-1.13` only in the approvals list, plus the configured `jev.model` if different. Legacy `jev/<model-id>` overrides normalize to `pi-fabric/typesafe/<model-id>` when loaded. `/login jev` credentials and raw TypeSafe request IDs (`jev-latest`, `jev-1.13`) are unchanged. **Inherit** still means the active Pi chat model, never Jev. Selecting Jev for approvals is independent of `jev.enabled`, which controls Fabric's Jev tool provider.
407
+ Jev is an auth-only provider, not a chat model. This picker offers `pi-fabric/typesafe/jev-latest`, `pi-fabric/typesafe/jev-1.13`, `pi-fabric/typesafe/jev-1.13.0`, and `pi-fabric/typesafe/jev-preview` only in the approvals list, plus the configured `jev.model` if different. It also offers OpenRouter-served `pi-fabric/openrouter/jev-latest` and `pi-fabric/openrouter/jev-1.13`, which reuse the existing `openrouter` credential (`/login openrouter`, `OPENROUTER_API_KEY`, or `TYPESAFE_OPENROUTER_API_KEY`); OpenRouter has no `jev-preview` alias and serves Jev on its Decisions API, not `/chat/completions`. Vercel AI Gateway-served `pi-fabric/vercel-ai-gateway/jev-latest` reuses the existing `vercel-ai-gateway` credential (`/login vercel-ai-gateway` or `AI_GATEWAY_API_KEY`) and resolves to `typesafe-ai/jev` on the gateway's TypeSafe-compatible endpoint. Legacy `jev/<model-id>` overrides normalize to `pi-fabric/typesafe/<model-id>` when loaded. `/login jev` credentials and raw TypeSafe request IDs (`jev-latest`, `jev-1.13`) are unchanged. **Inherit** still means the active Pi chat model, never Jev. Selecting Jev for approvals is independent of `jev.enabled`, which controls Fabric's Jev tool provider.
405
408
 
406
- The host asks one typed Noul question about whether the exact action is routine, reversible, task-aligned, and safe to run without human approval. It auto-allows when the returned probability is **at least `jev.autoApprovalThreshold` (default 0.50)**. Selecting a Jev model reveals **Approvals → Jev minimum probability**, an editable number from 0 to 1 in both terminal and RPC settings. The setting persists in the selected global/project scope, remains saved when switching models, and applies only to Jev classification. For example, `"jev": { "autoApprovalThreshold": 0.95 }` requires a probability of at least 0.95. Missing, non-numeric, non-finite, or out-of-range configuration values use the 0.50 default; valid decimals and zero are preserved. Upgrading from the former fixed 0.99 cutoff uses 0.50 unless you explicitly configure another value.
409
+ The host asks four typed Noul questions in one request: whether the exact action is safe to run without human approval, whether it touches secrets or sensitive data, whether it is destructive or irreversible without a user-named target, and whether it targets only artifacts this session created. Auto-allow requires the safety probability to be **at least `jev.autoApprovalThreshold` (default 0.50)** **and** the secrets and destructive probabilities to stay below 0.5; all four verdicts and the effective threshold are recorded with the decision. Selecting a Jev model reveals **Approvals → Jev minimum probability**, an editable number from 0 to 1 in both terminal and RPC settings. The setting persists in the selected global/project scope, remains saved when switching models, and applies only to Jev classification. For example, `"jev": { "autoApprovalThreshold": 0.95 }` requires a probability of at least 0.95. Missing, non-numeric, non-finite, or out-of-range configuration values use the 0.50 default; valid decimals and zero are preserved. Upgrading from the former fixed 0.99 cutoff uses 0.50 unless you explicitly configure another value.
407
410
 
408
- Lower thresholds permit more actions; **0 allows every valid judgment**, while 1 requires a probability of 1. Scores below the threshold require explicit approval. Missing evidence and errors still escalate regardless of threshold. Reasons report the numeric judgment and effective threshold, not generated explanations. This is a policy cutoff, **not a calibrated security guarantee**. Use `ask` or `deny` when a probabilistic advisor is inappropriate.
411
+ Lower thresholds permit more actions. **0 allows every valid judgment whose secrets and destructive verdicts are clean**, while 1 requires a safety probability of 1; a secrets or destructive probability at or above 0.5 escalates regardless of threshold, and so do missing user text, malformed answers, and errors. Reasons report the four numeric judgments and the effective threshold, not generated explanations. This is a policy cutoff, **not a calibrated security guarantee**. Use `ask` or `deny` when a probabilistic advisor is inappropriate.
409
412
 
410
- Jev receives the exact bounded arguments plus the **latest user message and subsequent assistant tool calls**. Earlier turns, assistant prose, thinking, images, and tool outputs are excluded. Vague follow-ups cannot borrow authority from omitted history. Missing user text, non-serializable arguments, or truncation of this evidence require explicit approval without inference (16,000 argument characters, 6,000 per user message/tool-call batch, 24,000 total evidence characters). Starting a new explicit user turn resets this evidence window.
413
+ Jev receives the exact bounded arguments, the **latest user message and subsequent assistant tool calls**, and a bounded projection of earlier session actions - direct tool calls and nested Fabric actions with their arguments, host-recorded failures marked `"ok":false`. Earlier turns' prose, thinking, images, and tool outputs are excluded, so vague follow-ups cannot borrow authority from omitted history and retrieved content cannot instruct the classifier. Missing user text still requires explicit approval without inference. Oversized arguments, transcript clipping, and projection limits are disclosed to Jev as `evidence`/`session.truncated` facts instead of aborting classification (16,000 argument characters, 6,000 per user message/tool-call batch, 24,000 total evidence characters, 12,000 session-projection characters). Starting a new explicit user turn resets the conversational evidence window; the session-action projection spans the session.
411
414
 
412
415
  Selecting this remote classifier authorizes sending that evidence to TypeSafe; it can contain private paths, code, or values from tool arguments. Do not select it for data that must stay local. Classification is a host-side request, not a recursive `jev.evaluate` tool call, so it does not recursively invoke the network approval policy. Normal tool permissions still apply after classification. Missing auth, malformed answers, HTTP errors, cancellation and timeouts never fall back to another model or auto-allow. They use the existing explicit approval flow (or deny in headless mode).
413
416
 
414
- Authentication uses `/login jev`, `TYPESAFE_API_KEY`, then trusted `jev.credentialCommand`; the command is resolved per classification and not cached across decisions. `jev.maxRequestBytes` and `jev.requestTimeoutMs` apply, with a 30-second classifier timeout ceiling and no automatic retries. Typed token usage is included in approval accounting. TypeSafe does not return prices: cost fields are zero/unpriced, **not evidence that inference is free**.
417
+ Authentication uses `/login jev`/`TYPESAFE_API_KEY` on the TypeSafe route, the existing `openrouter` credential (`/login openrouter`, `OPENROUTER_API_KEY`, or `TYPESAFE_OPENROUTER_API_KEY`) on the OpenRouter route, and the existing `vercel-ai-gateway` credential (`/login vercel-ai-gateway` or `AI_GATEWAY_API_KEY`) on the Vercel AI Gateway route, then trusted `jev.credentialCommand`; the command is resolved per classification and not cached across decisions. `jev.maxRequestBytes` and `jev.requestTimeoutMs` apply, with a 30-second classifier timeout ceiling and no automatic retries. Typed token usage is included in approval accounting. TypeSafe does not return prices: cost fields are zero/unpriced, **not evidence that inference is free**.
415
418
 
416
419
  ## Temporal retention
417
420
 
@@ -452,7 +455,7 @@ Other agent settings:
452
455
  - `defaultTools`: the default tool allowlist for children.
453
456
  - `budgetUsd`: shared append-only cost ledger across a recursion tree (0 disables).
454
457
  - `maxTokensPerChild`: cumulative token bound per child (0 disables).
455
- - `notifyOnComplete`: send a follow-up completion message for a detached `agents.spawn()`.
458
+ - `notifyOnComplete`: show concise detached `agents.spawn()` completion notices and batch unread results for Main at a safe tool-turn boundary (or wake idle Main). `wait`/`join` and terminal `status` retract pending notifications; running/UI status does not. Escape/error parks results until new input.
456
459
  - `sessionExport`: export each agent run's usage as an attributed pi-format session file (on by default).
457
460
  - `sessionExportDir`: override the export store root (default `~/.pi-fabric/agent`, with `PI_FABRIC_AGENT_DIR` taking precedence).
458
461
 
@@ -492,12 +495,17 @@ Fabric handles staleness in stale-while-revalidate style. Sessions adopt the cac
492
495
  - `mcp.cache.enabled`: turn the descriptor cache on (default: true). When false, discovery lists tools live with a 60s in-memory TTL, matching the pre-cache behavior.
493
496
  - `mcp.cache.revalidate`: background re-listing scope at session start, one of `"changed"` (only added or reconfigured servers, the default), `"all"`, or `"off"` (explicit `tools.list({ provider: "mcp", namespace })` probes still fetch exactly that server).
494
497
  - `mcp.cache.revalidateBudgetMs`: wall-clock budget for one background revalidation pass (default 60000). A leftover queue tail restarts with a fresh budget.
498
+ - `mcp.jev.semanticSearch`: opt-in Jev ranking for `tools.search({ query, searchMode: "semantic" })` (default false). Default `tools.search` stays local and lexical. Enable it under **/fabric settings → MCP → Jev semantic search**.
499
+ - `mcp.jev.blockedServers`: MCP servers whose tool metadata must not be sent to Jev. Empty (the default) allows every server, including ones that are not cached yet. **/fabric settings → MCP → Block from Jev** lists cached servers so you can opt individual ones out.
500
+ - `mcp.jev.semanticCandidateLimit`: max tools sent to Jev (2–127, default 127). Half the slots are lexical hits; the rest recover tools the query would not name.
501
+ - `mcp.jev.semanticMinProbability`: minimum head probability to accept a match (0–1, default 0.2). Below that, or if Jev chooses `none`, search abstains. Timeout, rate-limit, and 5xx responses fall back to lexical ranking and mark `backend.degraded`.
495
502
 
496
503
  See the [TypeScript MCP reference](../skillsets/typescript/fabric-exec/references/mcp.md) or [Python MCP reference](../skillsets/python/fabric-exec/references/mcp.md) for the selected call surface.
497
504
 
498
505
  ## UI
499
506
 
500
507
  - `ui.widget` is `auto`, `always`, or `hidden`. `auto` shows active or retained Fabric runs and worker activity. Active one-shot agents and actor workers occupy rows. Their recent nested tools appear beneath them when enabled.
508
+ - `ui.maxRows` defaults to `6` and clamps the widget to `1..20` rows. The effective budget is also bounded by half the live terminal height, so a short pane or a tmux split cannot let the animated box fill the viewport and keep pi's scroll region moving under the editor. Rows beyond the budget collapse into a dim `+N` marker on the last line.
501
509
  - `ui.showAgentToolPreview` defaults to `true` and controls the child-agent and actor tool rows in both the parent `fabric_exec` card and the widget. Recursive agents render their full descendant tree, bounded by the preview depth/node budget. The version 2 config migration renamed this key from `ui.showNestedToolCalls`.
502
510
  - `ui.toolDisplay` is `"compact"` (default) or `"full"`. Compact elevates the declared display name and description and keeps bounded nested tool detail visible; full retains the outer Fabric program transcript. Pi's tool-expand keybinding (`ctrl+o` by default) expands a compact card to the full transcript and collapses it again. Invalid values fall back to `"compact"`. If configuration fails to load, rendering falls back to full so a degraded startup never hides the transcript. Change it under `/fabric settings` → **UI**; successful changes apply immediately to live and completed cards.
503
511
  - `ui.updateDebounceMs` defaults to `100`. It applies one execution-wide coalescing interval to every live `fabric_exec` card update: nested calls, progress text, and agent tool previews. Continuous streams emit at most once per interval, so a long call no longer postpones every render until completion. Set it to `0` to emit every update. Accepted values clamp to `0..2000`. The version 3 config migration renamed this key from `ui.nestedToolDebounceMs`.
@@ -0,0 +1,65 @@
1
+ # Fabric Foreman
2
+
3
+ `/skill:fabric-foreman <goal>` puts a fast typed decision loop above Main's slower coding loop. Choose `agent_settled` for economical decision points or `turn_end` for per-turn assessment. Main continues working while the Jev program watches; no second generative model runs for every observation.
4
+
5
+ This adapts [thruwire/foreman](https://github.com/thruwire/foreman)'s ten-question semantic supervision and deterministic policy to Fabric's existing lifecycle. Comparison baseline: upstream commit `3de1556a59b7a7e14daa1f89b2fc49080bbb8cce`, especially its [README](https://github.com/thruwire/foreman/blob/3de1556a59b7a7e14daa1f89b2fc49080bbb8cce/README.md), [runtime](https://github.com/thruwire/foreman/blob/3de1556a59b7a7e14daa1f89b2fc49080bbb8cce/docs/runtime.md), and [steering](https://github.com/thruwire/foreman/blob/3de1556a59b7a7e14daa1f89b2fc49080bbb8cce/docs/steering.md). It is not a port of the Codex App Server transport or a claim of assessment accuracy.
6
+
7
+ ## Primitive audit
8
+
9
+ Fabric already has the required primitives for **session-bound, lifecycle-driven supervision**. No new runtime API, event name, registration, or configuration switch is needed.
10
+
11
+ | Foreman responsibility | Fabric primitive / implementation | Boundary |
12
+ | --- | --- | --- |
13
+ | Independent long-running controller with local state | `jev.spawn`, `JevProgramManager` in `src/jev/manager.ts` | One persistent QuickJS program; Main does not wait. Session-owned, not restart-durable. |
14
+ | Observe coding progress at a decision point | `observe.events`, `program.nextEvent()`, `JevObservationHost` in `src/jev/observation.ts` | `turn_end` and `agent_settled` are the same local event names used by actors; no polling required. |
15
+ | Bounded observation, history, and instruction evidence | Explicit `observe.include`, queue/age/character bounds; schema-bounded program input and local history | Settlement itself carries no transcript. Cache opted-in turn evidence; never assume hidden history access. Repository instructions are an explicitly supplied snapshot. |
16
+ | Ten parallel semantic questions | One `jev.evaluate` request with ten `noul` questions; `src/jev/client.ts` validates answers | Implementation, tests, requirements, verification, readiness, progress, stuck, off-track, instruction drift, and human need. Code—not Jev—selects actions. |
17
+ | Continue, steer, or request another pass | `program.advise` / `jev.advise` with `steer` or `followUp` and explicit `triggerTurn` | Same delivery semantics as actors, with additional Jev freshness and feedback gates. Advice is asynchronous, not a pre-tool veto. |
18
+ | Coding workers and independent verifiers | Existing `agents.spawn` / `agents.run`, tool allowlists, worktrees, status/log/wait | Main is the worker in this profile. Main can launch a verifier and execute approved targeted checks; the observer does not acquire worker-launch authority. |
19
+ | Stop/retry an owned child | Existing `agents.stop`, then an explicitly bounded fresh `agents.spawn` | Stop is not rollback; retries are policy, not a primitive. The default sidecar does not stop Main or retry workers automatically. |
20
+ | Structured progress and inspection | `program.emit`, `jev.status`, terminal envelopes | Latest 64 events in memory, not Foreman's atomic state file and append-only durable run store. |
21
+ | Persistent coordination when actually needed | Existing `mesh.put` CAS state, `mesh.publish`, durable actors and participant subscriptions | Requires explicit capabilities and trusted mesh configuration. A Jev run is not a mesh participant or a durable subscription target. |
22
+ | Bounded cost and interruption | Program limits, host ceilings, `jev.stop`, shared Main halt path | Main abort/Escape, tree navigation, and provider retirement cancel observers. Token usage is post-request, not a hard dollar cap. |
23
+
24
+ `FabricRuntimeState.dispatchHostEvent` feeds both actors and Jev from the same lifecycle, while `haltAdvisors` stops both. Jev is available with mesh disabled. Normal reasoning actors may receive a sanitized recent transcript and use broader host events; Jev deliberately requires an explicit text projection and exposes a smaller event allowlist. That difference is an authorization boundary, not a reason to add implicit transcript access.
25
+
26
+ The public types and host APIs are exported by `pi-fabric/jev` (`src/jev.ts`); guest declarations live in `src/jev/guest-types.ts`, and provider actions in `src/providers/jev-provider.ts`. See [Jev](jev.md) for their exact contracts and [agents](agents.md) for worker/actor control. All effects keep the normal approval, authorization, and capability-pinning paths.
27
+
28
+ ## Profile behavior
29
+
30
+ The skill ships an executable starter in both kernel trees. The Python entry point submits the same TypeScript Jev artifact; it does not change the configured outer kernel. The program grants only `jev.evaluate` and, in steer mode, `jev.advise`.
31
+
32
+ 1. Main derives a bounded goal, acceptance ledger, and applicable instruction excerpt; the user consents to sharing them and selected future turn text with TypeSafe.
33
+ 2. The program consumes `turn_end` into a four-turn window. At the selected cadence it requires the latest turn to match the current revision, remain within 30 seconds, and be untruncated. Settlement metadata alone cannot establish completion. Duplicate settlement of the same revision costs no second evaluation.
34
+ 3. One request scores all ten questions. Human need and bounds outrank drift/stuck correction; readiness, verification, and ordinary progress come later. Fixed policy messages request one corrective step, independent verification, continued implementation, or human attention. One initial correction has a 30-second grace period before persistent drift becomes an escalation outcome.
35
+ 4. `FINISH_REVIEW` is only a candidate for Main's acceptance review. Main must inspect independent verifier findings and actual targeted test/build results before claiming completion. Semantic scores and verifier prose are not passing checks.
36
+ 5. The observer retires on new input, escalation, a finish-review candidate, inference failure, or its budgets. Terminal `completed` means the program returned valid output, not that the software job is complete. Main inspects `result.outcome`.
37
+
38
+ Requested limits are 15 minutes, 20 assessments, 600 host calls, 40,000 reported tokens, and 120 consumed events, clamped to trusted host ceilings. Inference failure ends the profile with a labeled escalation rather than spinning on 429/529 or guessing an answer. Read [Jev's budget and auth rules](jev.md) before launch. No live API test is necessary to install or verify the skill.
39
+
40
+ ### Delivery is deliberately bounded
41
+
42
+ The profile uses `delivery: "steer", triggerTurn: true, maxAdvice: 1`, or record-only with neither delivery nor the `jev.advise` grant. Across **all** Jev observers, Fabric permits at most one delivery attempt per external user input. Automatic continuations do not re-arm it. Classification may continue, but later messages may be suppressed; progress events record the actual delivery result. Do not bypass the guard with `agents.steer`, repeated launches, or another transport.
43
+
44
+ Escalation and limit outcomes stop the observer, not Main. Even an accepted pause directive is advisory; a suppressed one cannot be assumed to have paused anything. This profile is not a safety gate or a fully autonomous stop/retry factory. Child control is already available when separately authorized, but should have explicit ownership, concurrency, grace, retry, deadline, and cleanup rules. Do not stop unrelated peers or route Main controls around advice policy.
45
+
46
+ ### Intentional differences from upstream
47
+
48
+ - Main replaces the Codex App Server worker. Existing Pi/Claude runners can be composed separately; no new Codex App Server transport is implied.
49
+ - Turn/settlement boundaries replace streamed subprocess output and periodic observations, as requested. Silence causes no inference.
50
+ - Bounded selected evidence replaces automatic Git/shell observation. The program has no shell authority and no secret/history access. If the instruction snapshot changes, review and explicitly replace the observer rather than assume it refreshed.
51
+ - Jev programs do not survive host restarts. In-memory status is not durable recovery. Existing mesh primitives can store explicit checkpoints, but they do not resume a lost QuickJS context or make effects exactly once.
52
+ - The skill does not weaken feedback prevention to reproduce an unbounded factory loop. Use a reasoning actor when persistent conversational supervision with its different context/lifecycle contract is desired.
53
+
54
+ ## Acceptance ledger and verification
55
+
56
+ | Check | Evidence |
57
+ | --- | --- |
58
+ | Both kernel commands load, remain user-only, resolve pointers, and submit the same artifact | `tests/kernel-skills.test.ts`, `tests/skill-docs.test.ts`, `tests/foreman-skills.test.ts` |
59
+ | No inference before a boundary; both cadences use opted-in evidence and batch ten Noul questions | `tests/foreman-skills.test.ts` through the real Jev provider and QuickJS runtime with synthetic transport |
60
+ | Deterministic continue, resume, steer/grace, verify, finish-review, human escalation, and bounds | Same executable skill tests, not a reimplementation of the policy |
61
+ | Missing/truncated/stale context, duplicate settlement, inference errors, and cancellation never imply success | Skill tests plus `tests/jev-observation.test.ts` |
62
+ | Approval/capability gates, feedback suppression, shared host event delivery and halt | `tests/jev-observation.test.ts`, `tests/jev-host-integration.test.ts` |
63
+ | Packaged compiled public API and event-driven advice still work | Fresh `bun run build`, then `bun run test:jev:dist` |
64
+
65
+ Run only these targeted checks, not the entire repository suite. Threshold accuracy needs separate, consented evaluation on representative tasks; deterministic tests establish control flow, not semantic correctness.
package/docs/jev.md CHANGED
@@ -8,12 +8,18 @@ For guided authoring, invoke `/skill:fabric-jev <task>`. It is user-opt-in and a
8
8
 
9
9
  On Pi 0.85.1 or newer, `/login jev` prompts privately for a TypeSafe API key and stores an ordinary API-key credential under `jev` in Pi's `auth.json`. `/logout` removes it. Jev registers an **auth-only provider with no chat models**; it does not appear as a selectable text-generating model.
10
10
 
11
- Resolution order:
11
+ Jev has three upstream routes. Bare aliases (`jev-latest`, `jev-1.13`, `jev-1.13.0`, `jev-preview`) post to TypeSafe's `/v1/systemone`. OpenRouter decisions IDs (`typesafe/jev-1.13`, `~typesafe/jev-latest`) post to OpenRouter's `/api/alpha/decisions` and reuse the **existing `openrouter` credential** — the same `auth.json` entry as your chat models, so `/login openrouter` covers both. OpenRouter serves Jev on its Decisions API, not `/chat/completions`, and has no `jev-preview` alias. Vercel AI Gateway model IDs (`typesafe-ai/jev`, or the `jev-latest` alias) post to its TypeSafe-compatible `/typesafe/v1/systemone` endpoint and reuse the **existing `vercel-ai-gateway` credential** (`/login vercel-ai-gateway`, `AI_GATEWAY_API_KEY`); the request and response shapes stay TypeSafe's own, so only the base URL and key change. No second provider is registered.
12
+
13
+ TypeSafe route resolution order:
12
14
 
13
15
  1. Pi's provider authentication (`auth.json`, then `TYPESAFE_API_KEY`, including supported Pi runtime overrides).
14
16
  2. `TYPESAFE_API_KEY` directly when running without Pi's auth service.
15
17
  3. An explicitly configured host-side command, if neither is available.
16
18
 
19
+ The Vercel AI Gateway route resolves Pi's `vercel-ai-gateway` provider authentication first (`auth.json`, then `AI_GATEWAY_API_KEY`), then `AI_GATEWAY_API_KEY`, then the same trusted `jev.credentialCommand`.
20
+
21
+ The OpenRouter route resolves Pi's `openrouter` provider authentication first (`auth.json`, then `OPENROUTER_API_KEY`), then `OPENROUTER_API_KEY` or `TYPESAFE_OPENROUTER_API_KEY`, then the same trusted `jev.credentialCommand`.
22
+
17
23
  For Localterm, set this in your trusted `fabric.json` (never put the resolved secret into model-visible code):
18
24
 
19
25
  ```json
@@ -30,9 +36,9 @@ The command uses argv, not a shell. It runs only when inference needs a key, wit
30
36
 
31
37
  ## Auto-mode tool safety
32
38
 
33
- Jev can also serve as the host's auto-approval classifier, independently of programs and observers. Choose **Approvals → Auto model → Jev (TypeSafe safety classifier)** in `/fabric settings`, or set `approvals.model` to `"pi-fabric/typesafe/jev-latest"` (or pin `"pi-fabric/typesafe/jev-1.13"`) and the relevant risk policies to `"auto"`. Authenticate with `/login jev`, `TYPESAFE_API_KEY`, or the trusted credential command above.
39
+ Jev can also serve as the host's auto-approval classifier, independently of programs and observers. Choose **Approvals → Auto model** in `/fabric settings`, or set `approvals.model` to `"pi-fabric/typesafe/jev-latest"` and the relevant risk policies to `"auto"`. The picker also offers the pinned `pi-fabric/typesafe/jev-1.13`, `pi-fabric/typesafe/jev-1.13.0`, and `pi-fabric/typesafe/jev-preview` aliases (all resolve to the same build today), plus OpenRouter-served `pi-fabric/openrouter/jev-latest` and `pi-fabric/openrouter/jev-1.13`, and Vercel AI Gateway-served `pi-fabric/vercel-ai-gateway/jev-latest`. Authenticate with `/login jev` and `TYPESAFE_API_KEY` on the TypeSafe route, `/login openrouter` and `OPENROUTER_API_KEY` on the OpenRouter route, or `/login vercel-ai-gateway` and `AI_GATEWAY_API_KEY` on the Vercel AI Gateway route.
34
40
 
35
- The host uses a typed Noul safety judgment, not generated text or a chat-model adapter. Probabilities at or above `jev.autoApprovalThreshold` auto-allow (default **0.50**); lower scores and errors require explicit approval. When a Jev model is selected, **Approvals → Jev minimum probability** lets you enter any finite value from 0 to 1. Higher values are more conservative; 0 allows every valid judgment. This is a probabilistic advisor, not a hard security boundary or a correctness guarantee. Read [auto approval configuration](configuration.md#jev-as-the-auto-mode-classifier) for the bounded current-turn evidence, outbound data disclosure, credential behavior, timeout and usage rules. Jev remains absent from ordinary chat-model pickers.
41
+ The host asks four typed Noul questions in one request - safety, secrets exposure, destructive effect, and whether the action targets only artifacts this session created - and never uses generated text or a chat-model adapter. Auto-allow requires the safety probability at or above `jev.autoApprovalThreshold` (default **0.50**) **and** the secrets and destructive probabilities below 0.5; lower scores, a positive secrets or destructive judgment, missing user text, and errors require explicit approval. When a Jev model is selected, **Approvals → Jev minimum probability** lets you enter any finite value from 0 to 1. Higher values are more conservative; 0 allows every judgment whose secrets and destructive verdicts are clean. This is a probabilistic advisor, not a hard security boundary or a correctness guarantee. Read [auto approval configuration](configuration.md#jev-as-the-auto-mode-classifier) for the current-turn evidence, session-action projection, outbound data disclosure, credential behavior, timeout and usage rules. Jev remains absent from ordinary chat-model pickers.
36
42
 
37
43
  ## Direct judgments
38
44
 
@@ -135,8 +141,75 @@ Foreground cancellation cancels the run. Cancelling a `wait` only cancels that w
135
141
 
136
142
  Status retains the latest 64 events (4 KiB each); use `sequence` and `nextSequence` to detect gaps. Logs are capped at 4 KiB; program input and final JSON output are each capped at 32 KiB. Terminal runs are retained in a bounded in-memory history; old IDs eventually expire. There is no unlimited hidden transcript or per-tick reasoning agent.
137
143
 
144
+ ## Realtime loops
145
+
146
+ A realtime controller is one program: observe, judge, act, pace, repeat. Two decision shapes cover the published realtime examples: [Jev Ultrafast](https://github.com/browser-use/jev-ultrafast) and [jev-doom-agent](https://github.com/lukaske/jev-doom-agent).
147
+
148
+ - **Operation plus speculative targets.** One request asks which operation to run and, separately, which target each operation would use. Code applies only the target head matching the chosen operation. This is the browser-agent shape: a dynamic element table, one network round trip, one executed action.
149
+ - **Factorized control axes.** One request asks several independent questions whose answers execute together, for example movement / view / trigger / interaction. This is the shape of the browser-native Doom example.
150
+
151
+ Both are ordinary `jev.evaluate` batches: keep independent questions in one request, and keep the mapping from answers to effects in code. A counterfactual head that is not executed is still a judgment; never let unused heads write state.
152
+
153
+ ### Observation stays structured state
154
+
155
+ Read the application's own state — a page bridge through `browser.cdp` and `Runtime.evaluate`, or a small application-specific provider — and project it into a compact object with a revision. Include the facts the judgment needs and nothing else: player/entity/environment fields, the previous action, and bounded history are usually enough. Screenshots are not part of the typed request contract; keep pixels out of `state`, and never send secrets.
156
+
157
+ ### Code owns the motor layer
158
+
159
+ Jev selects a tactic; code decides how to execute it. A timed pulse with an epoch guard is what survives a realtime loop: apply an input mask, hold it for a bounded interval, release it only while it is still the newest pulse, then re-observe.
160
+
161
+ ```ts
162
+ let epoch = 0;
163
+ async function pulse(mask: string, durationMs: number) {
164
+ const mine = ++epoch;
165
+ await tools.call({ ref: "app.control", args: { mask, epoch: mine } });
166
+ await program.sleep(durationMs);
167
+ if (mine === epoch) await tools.call({ ref: "app.release", args: { epoch: mine } });
168
+ }
169
+ ```
170
+
171
+ Revalidate the revision you decided from before applying anything. A rejected or stale action means re-observe and re-decide, not retry blindly.
172
+
173
+ ### Degraded mode must be labeled
174
+
175
+ A realtime loop needs a deterministic fallback for every degraded decision: a failed request, an invalid response, or confidence below your threshold. Compute the fallback in code, replace the judgment, and record it, so the UI and telemetry never present it as a model decision.
176
+
177
+ ```ts
178
+ let degraded = false;
179
+ try {
180
+ const decision = await jev.evaluate({ state, questions });
181
+ if (decision.answers.action.confidence < 0.5) degraded = true;
182
+ else frame = decision.answers.action.choice;
183
+ } catch { degraded = true; }
184
+ if (degraded) { frame = deterministicFallback(state); await program.emit({ fallback: true, frame }); }
185
+ ```
186
+
187
+ Confidence is neither truth nor authorization; a low-confidence answer is a reason to fall back, not a reason to act. Fabric validates the response before it returns it — an invalid choice, probability set, or confidence rejects the evaluation instead of surfacing a partial answer, so `catch` is part of the loop.
188
+
189
+ ### Budget arithmetic for sustained loops
190
+
191
+ Default per-run limits are 60 seconds, 100 evaluations, 1,000 host calls, and 100,000 reported tokens. `program.sleep` and `program.emit` are host calls and count against `maxToolCalls`, so a paced loop spends budget even when it is not touching the world. At 10 Hz with observe, evaluate, control, release, and sleep, that is five host calls per tick: the default 1,000 host calls last about 20 seconds, and the default 100 evaluations about 10 seconds. A sustained run needs explicit limits and a raised host ceiling:
192
+
193
+ ```json
194
+ {
195
+ "jev": { "maxDurationMs": 3600000, "maxEvaluations": 100000, "maxToolCalls": 1000000, "maxTokens": 100000000 }
196
+ }
197
+ ```
198
+
199
+ Per-program `limits` are clamped to these ceilings (24 hours, 100,000 evaluations, 1,000,000 host calls). Duration and evaluation count are the real liveness bounds; the wall-clock deadline and terminal state are always reported in the run envelope.
200
+
201
+ ### Telemetry and shutdown
202
+
203
+ Spawn the loop with `jev.spawn` so Main stays responsive and can inspect it. The event ring holds the latest 64 events (4 KiB each) — roughly six seconds at 10 Hz — so drain it with `jev.status({ id, after })` from the supervising turn or persist it host-side; terminal runs live only in a bounded history. At most one evaluation may be in flight per program, so batch independent questions instead of hedging decisions, and run two engines as two programs (`jev.maxConcurrentRuns`).
204
+
205
+ Stop a loop with `jev.stop({ id })`, provider reload/unload, or a code-owned terminal rule such as death, goal reached, or a no-match judgment. Cancellation aborts in-flight inference and host calls, but it is not rollback of effects already issued.
206
+
207
+ `tests/jev-realtime-loop.test.ts` is the deterministic reference for both shapes, the pulse/epoch pattern, labeled degraded mode, a death stop, and status/stop on a paced run.
208
+
138
209
  ## Main-turn advisors and supervisors
139
210
 
211
+ For a ready-to-use coding-supervision policy, invoke `/skill:fabric-foreman <goal>`. It uses these same primitives with per-turn or settlement cadence, ten batched judgments, and bounded deterministic interventions. See [the Foreman capability comparison](foreman.md).
212
+
140
213
  `jev.spawn({program,input,observe})` can subscribe to the owning Main session. This is an **event-driven sidecar**, not another reasoning agent or a polling loop. It works with mesh disabled. It is not a mesh participant, a cross-session subscription, or restart-durable storage; do not pass its run ID to `agents.subscribe`.
141
214
 
142
215
  The program retains local state, awaits `program.nextEvent()`, asks typed questions, then records a judgment with `program.emit`. To intervene, explicitly configure `observe.delivery` and declare `jev.advise` in `requires`. `program.advise({eventId,message})` supplies the current run ID; the public equivalent is `jev.advise({id,eventId,message})`. Observer launch also requires read approval for future Main event access. Advice is an `agent`-risk emission and passes normal approvals, authorization, and pinned capability checks. Jev selects judgments; program code writes the message and policy.
@@ -284,6 +357,6 @@ PI_FABRIC_JEV_LIVE=1 PI_FABRIC_JEV_LOCALTERM=1 bunx vitest run tests/jev-live.te
284
357
 
285
358
  After `bun run build`, `bun run test:jev:dist` checks the compiled public entry point, auth-only registration, foreground CDP composition with a simulated session, and background stop/wait, agent/Jev join aliases, and event-driven Main advice.
286
359
 
287
- No real browser state or secrets are printed by these probes. Live tests exercise all three primitives, foreground/background inference loops, and a feedback controller using changing synthetic screen observations and source control IDs. Unit tests exercise the Browser Harness adapter with an injected session; they do not attach to a personal browser.
360
+ No real browser state or secrets are printed by these probes. Live tests exercise all three primitives, foreground/background inference loops, and a feedback controller using changing synthetic screen observations and source control IDs. `tests/jev-realtime-loop.test.ts` replays both realtime shapes offline: batched target heads with one request per tick, factorized control axes with pulse/epoch motor control, labeled degraded decisions, a death stop, and status/stop on a paced loop. Unit tests exercise the Browser Harness adapter with an injected session; they do not attach to a personal browser.
288
361
 
289
362
  Public host APIs and types are exported from `pi-fabric/jev`. Fabric lifecycle and trust semantics are detailed in [components.md](components.md). Current TypeSafe contracts: [API](https://docs.typesafe.ai/api), [Choice](https://docs.typesafe.ai/primitives/choice), [Noul](https://docs.typesafe.ai/primitives/noul), [Score](https://docs.typesafe.ai/primitives/score), and [confidence](https://docs.typesafe.ai/confidence).
@@ -119,10 +119,14 @@ never become typed protocol input.
119
119
  waits for the next settled boundary.
120
120
  - On pi's `onComplete`, Fabric clears the intent and `last` records
121
121
  `status: "committed"` with the summary and token counts.
122
- - On pi's `onError` with `"Compaction cancelled"` or `"Already compacted"`,
123
- Fabric clears the intent and `last` records `status: "cancelled"` with the
124
- raw pi message in `error`. No compaction happened, and the outcome stays
125
- observable without being silently dropped.
122
+ - On pi's `onError` with `"Compaction cancelled"`, `"Already compacted"`,
123
+ or `"Nothing to compact (session too small)"`, Fabric clears the intent
124
+ and `last` records `status: "cancelled"` with the raw pi message in
125
+ `error`. No compaction happened — the too-small message is Pi rejecting a
126
+ manual compaction whose session sits below `keepRecentTokens`, so every
127
+ message would be kept anyway — and the outcome stays observable without
128
+ being silently dropped. Only exact messages are benign: an error merely
129
+ containing one of the phrases stays `failed`.
126
130
  - On any other error, Fabric clears the intent and `last` records
127
131
  `status: "failed"` with the message. A synchronous throw from `compact()`
128
132
  itself follows the same failure path.
@@ -173,8 +177,9 @@ return await agents.wait({ id: handle.id });
173
177
  best-effort events to the durable `fabric.compact` topic on each transition.
174
178
  Recorded intents publish `kind: "requested"`, and settled intents publish
175
179
  `kind: "committed" | "cancelled" | "failed"`. Pi's benign
176
- `"Compaction cancelled"` and `"Already compacted"` outcomes publish with
177
- `kind: "cancelled"`. Other Fabric participants, such as persistent actors
180
+ `"Compaction cancelled"`, `"Already compacted"`, and `"Nothing to
181
+ compact (session too small)"` outcomes publish with `kind: "cancelled"`.
182
+ Other Fabric participants, such as persistent actors
178
183
  and peer sessions, can subscribe to observe compaction transitions.
179
184
  Activity-only sessions with the mesh disabled silently skip this step.
180
185
  - **Status query**: `compact.status()` gives the context-independent,
@@ -194,7 +199,7 @@ safety needs no configuration.
194
199
 
195
200
  | File | Role |
196
201
  | --- | --- |
197
- | `src/core/compact-controller.ts` | Pending-intent controller with `request`, `cancel`, `status`, and `maybeCommit`. Uses a single replaceable slot, typed preserve encoding, an in-flight guard, and a quiet clear on cancelled or already-compacted outcomes. |
202
+ | `src/core/compact-controller.ts` | Pending-intent controller with `request`, `cancel`, `status`, and `maybeCommit`. Uses a single replaceable slot, typed preserve encoding, an in-flight guard, and a quiet clear on benign no-op outcomes (cancelled, already compacted, or session too small). |
198
203
  | `src/providers/compact-provider.ts` | Fabric provider that exposes a bounded TypeBox-validated `request` (write, including optional `preserve: string[]`), `status` (read), and `cancel` (read). Registered always, with activity audit. |
199
204
  | `src/fabric-state.ts` | Constructs the controller with mesh-publish hooks, registers the provider, and resets on re-init or shutdown. |
200
205
  | `src/index.ts` | Invokes `state.compact.maybeCommit(context)` in the existing `agent_settled` handler. |