@e4779/pi-fabric 0.92.28-fork.5 → 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 (236) hide show
  1. package/README.md +2 -1
  2. package/dist/actors/types.d.ts +1 -1
  3. package/dist/actors/types.d.ts.map +1 -1
  4. package/dist/agents/completion-inbox.d.ts +15 -0
  5. package/dist/agents/completion-inbox.d.ts.map +1 -0
  6. package/dist/agents/handoff.d.ts.map +1 -1
  7. package/dist/agents/manager.d.ts +1 -0
  8. package/dist/agents/manager.d.ts.map +1 -1
  9. package/dist/agents/thinking-transfer.d.ts.map +1 -1
  10. package/dist/agents/transports/process-utils.d.ts.map +1 -1
  11. package/dist/agents.js +3 -3
  12. package/dist/build-identity.d.ts +21 -0
  13. package/dist/build-identity.d.ts.map +1 -0
  14. package/dist/chunks/{chunk-CIODQX77.js → chunk-2A2NWQ36.js} +3 -3
  15. package/dist/chunks/{chunk-OTCASLY2.js → chunk-2QAOC3BO.js} +1 -1
  16. package/dist/chunks/chunk-2QAOC3BO.js.map +7 -0
  17. package/dist/chunks/{chunk-BYOGRJME.js → chunk-2SWRVIYJ.js} +10 -7
  18. package/dist/chunks/chunk-2SWRVIYJ.js.map +7 -0
  19. package/dist/chunks/{chunk-ZHJNWM6A.js → chunk-36B4AIRT.js} +2 -2
  20. package/dist/chunks/{chunk-JOEFBOFN.js → chunk-3TXOQ5MG.js} +55 -45
  21. package/dist/chunks/chunk-3TXOQ5MG.js.map +7 -0
  22. package/dist/chunks/{chunk-G7UJLM33.js → chunk-4NUTVNS2.js} +40 -6
  23. package/dist/chunks/chunk-4NUTVNS2.js.map +7 -0
  24. package/dist/chunks/{chunk-X7G62ZGH.js → chunk-7BG5COXB.js} +8 -3
  25. package/dist/chunks/{chunk-X7G62ZGH.js.map → chunk-7BG5COXB.js.map} +2 -2
  26. package/dist/chunks/{chunk-IYQ5MNCW.js → chunk-7VAZ4N43.js} +42 -24
  27. package/dist/chunks/chunk-7VAZ4N43.js.map +7 -0
  28. package/dist/chunks/{chunk-KI277YNS.js → chunk-A4VP7HDF.js} +10 -2
  29. package/dist/chunks/chunk-A4VP7HDF.js.map +7 -0
  30. package/dist/chunks/chunk-B54Z662X.js +127 -0
  31. package/dist/chunks/chunk-B54Z662X.js.map +7 -0
  32. package/dist/chunks/{chunk-QLV2IZ3F.js → chunk-CGL7QP4A.js} +58 -7
  33. package/dist/chunks/chunk-CGL7QP4A.js.map +7 -0
  34. package/dist/chunks/{chunk-WG24VI7K.js → chunk-FLKGJPCN.js} +44 -2
  35. package/dist/chunks/chunk-FLKGJPCN.js.map +7 -0
  36. package/dist/chunks/{chunk-M7W57BRC.js → chunk-GGETIGM5.js} +487 -707
  37. package/dist/chunks/chunk-GGETIGM5.js.map +7 -0
  38. package/dist/chunks/{chunk-FAMBJFFF.js → chunk-IJL3QK3J.js} +3 -1
  39. package/dist/chunks/chunk-IJL3QK3J.js.map +7 -0
  40. package/dist/chunks/{chunk-RZKN534S.js → chunk-IK6PPFWG.js} +17 -6
  41. package/dist/chunks/chunk-IK6PPFWG.js.map +7 -0
  42. package/dist/chunks/{chunk-D6YSBP3R.js → chunk-IUCVOZRX.js} +3 -3
  43. package/dist/chunks/{chunk-ULLIZPBH.js → chunk-K6DHXXF5.js} +9 -7
  44. package/dist/chunks/chunk-K6DHXXF5.js.map +7 -0
  45. package/dist/chunks/{chunk-NPHCGLGH.js → chunk-MW5VI7IW.js} +135 -31
  46. package/dist/chunks/chunk-MW5VI7IW.js.map +7 -0
  47. package/dist/chunks/{chunk-RWDKJ24D.js → chunk-NHMICIEU.js} +2 -2
  48. package/dist/chunks/{chunk-M3ZNZ6EZ.js → chunk-PMSIZLV6.js} +2 -1
  49. package/dist/chunks/chunk-PMSIZLV6.js.map +7 -0
  50. package/dist/chunks/{chunk-RAEGNBRA.js → chunk-Q4XJ4PYL.js} +529 -168
  51. package/dist/chunks/chunk-Q4XJ4PYL.js.map +7 -0
  52. package/dist/chunks/{chunk-7TX532EG.js → chunk-RKRVOBVO.js} +2 -2
  53. package/dist/chunks/{chunk-M3S7XITB.js → chunk-TGAVMUOS.js} +29 -13
  54. package/dist/chunks/chunk-TGAVMUOS.js.map +7 -0
  55. package/dist/chunks/{chunk-JNMTTJMQ.js → chunk-TX6E5W7H.js} +1 -1
  56. package/dist/chunks/{chunk-JNMTTJMQ.js.map → chunk-TX6E5W7H.js.map} +1 -1
  57. package/dist/chunks/{chunk-X3OD47CL.js → chunk-UR2K6WK6.js} +8 -11
  58. package/dist/chunks/chunk-UR2K6WK6.js.map +7 -0
  59. package/dist/chunks/{chunk-Z63R5GVN.js → chunk-WHBJDTCR.js} +6 -2
  60. package/dist/chunks/chunk-WHBJDTCR.js.map +7 -0
  61. package/dist/chunks/{chunk-RRGTKHXZ.js → chunk-X7XFT57O.js} +9 -140
  62. package/dist/chunks/{chunk-RRGTKHXZ.js.map → chunk-X7XFT57O.js.map} +4 -4
  63. package/dist/chunks/chunk-YV2PHCDB.js +108 -0
  64. package/dist/chunks/chunk-YV2PHCDB.js.map +7 -0
  65. package/dist/chunks/chunk-Z64PRP7A.js +156 -0
  66. package/dist/chunks/chunk-Z64PRP7A.js.map +7 -0
  67. package/dist/components/configuration.js +5 -4
  68. package/dist/components/provider-component.d.ts +1 -1
  69. package/dist/components/provider-component.d.ts.map +1 -1
  70. package/dist/config.d.ts +10 -0
  71. package/dist/config.d.ts.map +1 -1
  72. package/dist/core/action-registry.d.ts +8 -0
  73. package/dist/core/action-registry.d.ts.map +1 -1
  74. package/dist/core/action-registry.js +6 -4
  75. package/dist/core/approval-controller.d.ts +5 -1
  76. package/dist/core/approval-controller.d.ts.map +1 -1
  77. package/dist/core/auto-approval-classifier.d.ts +11 -0
  78. package/dist/core/auto-approval-classifier.d.ts.map +1 -1
  79. package/dist/core/compact-controller.d.ts.map +1 -1
  80. package/dist/core/fabric-state-paths.d.ts +2 -0
  81. package/dist/core/fabric-state-paths.d.ts.map +1 -0
  82. package/dist/core/media-sanitize.d.ts +3 -2
  83. package/dist/core/media-sanitize.d.ts.map +1 -1
  84. package/dist/core/model-resolution.d.ts +3 -2
  85. package/dist/core/model-resolution.d.ts.map +1 -1
  86. package/dist/core/semantic-search.d.ts +56 -0
  87. package/dist/core/semantic-search.d.ts.map +1 -0
  88. package/dist/core/shell-jobs.d.ts.map +1 -1
  89. package/dist/core/shell-middleware.d.ts +4 -0
  90. package/dist/core/shell-middleware.d.ts.map +1 -0
  91. package/dist/execution-service.d.ts.map +1 -1
  92. package/dist/fabric-exec-tool.d.ts.map +1 -1
  93. package/dist/fabric-runtime-state.d.ts +2 -0
  94. package/dist/fabric-runtime-state.d.ts.map +1 -1
  95. package/dist/fabric-runtime-state.js +1213 -208
  96. package/dist/fabric-runtime-state.js.map +4 -4
  97. package/dist/fabric-state.d.ts +2 -0
  98. package/dist/fabric-state.d.ts.map +1 -1
  99. package/dist/index.d.ts.map +1 -1
  100. package/dist/index.js +226 -49
  101. package/dist/index.js.map +4 -4
  102. package/dist/jev/client.d.ts +8 -2
  103. package/dist/jev/client.d.ts.map +1 -1
  104. package/dist/jev/client.js +3 -2
  105. package/dist/jev/config.d.ts.map +1 -1
  106. package/dist/jev/model-key.d.ts +9 -2
  107. package/dist/jev/model-key.d.ts.map +1 -1
  108. package/dist/jev/observation.js +4 -4
  109. package/dist/jev/routes.d.ts +69 -0
  110. package/dist/jev/routes.d.ts.map +1 -0
  111. package/dist/jev/validation.d.ts.map +1 -1
  112. package/dist/jev.d.ts +1 -0
  113. package/dist/jev.d.ts.map +1 -1
  114. package/dist/jev.js +34 -9
  115. package/dist/mcp.d.ts.map +1 -1
  116. package/dist/mcp.js +9 -2
  117. package/dist/mcp.js.map +2 -2
  118. package/dist/prewalk/arm.d.ts.map +1 -1
  119. package/dist/prewalk/controller.d.ts +57 -6
  120. package/dist/prewalk/controller.d.ts.map +1 -1
  121. package/dist/prewalk/fs-drift.d.ts.map +1 -1
  122. package/dist/prewalk/handoff.d.ts +5 -25
  123. package/dist/prewalk/handoff.d.ts.map +1 -1
  124. package/dist/prewalk/messages.d.ts +24 -0
  125. package/dist/prewalk/messages.d.ts.map +1 -0
  126. package/dist/prewalk/model-switch.d.ts +3 -0
  127. package/dist/prewalk/model-switch.d.ts.map +1 -0
  128. package/dist/prewalk/plan.d.ts +46 -0
  129. package/dist/prewalk/plan.d.ts.map +1 -0
  130. package/dist/prewalk/return.d.ts +16 -0
  131. package/dist/prewalk/return.d.ts.map +1 -0
  132. package/dist/protocol.d.ts +10 -1
  133. package/dist/protocol.d.ts.map +1 -1
  134. package/dist/protocol.js +3 -1
  135. package/dist/providers/agents-actions.d.ts.map +1 -1
  136. package/dist/providers/agents-provider.d.ts.map +1 -1
  137. package/dist/providers/jev-provider.d.ts +2 -0
  138. package/dist/providers/jev-provider.d.ts.map +1 -1
  139. package/dist/providers/jev-provider.js +8 -8
  140. package/dist/providers/mcp-descriptor-cache.d.ts +2 -0
  141. package/dist/providers/mcp-descriptor-cache.d.ts.map +1 -1
  142. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  143. package/dist/providers/prewalk-provider.d.ts +19 -0
  144. package/dist/providers/prewalk-provider.d.ts.map +1 -0
  145. package/dist/repeat-guard.d.ts +4 -0
  146. package/dist/repeat-guard.d.ts.map +1 -1
  147. package/dist/residency/actor-client.js +2 -2
  148. package/dist/residency/client.d.ts +3 -0
  149. package/dist/residency/client.d.ts.map +1 -1
  150. package/dist/residency/host.d.ts.map +1 -1
  151. package/dist/residency/host.js +10 -9
  152. package/dist/residency/pi-entry.js +10 -9
  153. package/dist/residency/pi-entry.js.map +1 -1
  154. package/dist/residency/protocol.d.ts +4 -0
  155. package/dist/residency/protocol.d.ts.map +1 -1
  156. package/dist/runtime/core-override-guest-types.js +2 -2
  157. package/dist/runtime/cpython-runtime.d.ts +2 -0
  158. package/dist/runtime/cpython-runtime.d.ts.map +1 -1
  159. package/dist/runtime/cpython-runtime.js +7 -3
  160. package/dist/runtime/cpython-runtime.js.map +2 -2
  161. package/dist/runtime/guest-types.d.ts +1 -1
  162. package/dist/runtime/guest-types.d.ts.map +1 -1
  163. package/dist/runtime/guest-types.js +1 -1
  164. package/dist/runtime/monty-runtime.js +5 -4
  165. package/dist/runtime/monty-runtime.js.map +2 -2
  166. package/dist/runtime/node-process-runtime.js +3 -3
  167. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  168. package/dist/runtime/quickjs-runtime.js +1 -1
  169. package/dist/runtime/typescript-kernel.js +5 -5
  170. package/dist/runtime-state-builtins.d.ts.map +1 -1
  171. package/dist/ui/code-preview-shell.d.ts.map +1 -1
  172. package/dist/ui/conversation-native-reader.d.ts.map +1 -1
  173. package/dist/ui/conversation-native-reader.js.map +2 -2
  174. package/dist/ui/dashboard.js +2 -2
  175. package/dist/ui/settings-section-context.d.ts +1 -0
  176. package/dist/ui/settings-section-context.d.ts.map +1 -1
  177. package/dist/ui/settings-sections-agents.d.ts.map +1 -1
  178. package/dist/ui/settings-sections-execution.d.ts +1 -1
  179. package/dist/ui/settings-sections-execution.d.ts.map +1 -1
  180. package/dist/ui/settings-sections.d.ts +1 -0
  181. package/dist/ui/settings-sections.d.ts.map +1 -1
  182. package/dist/ui/settings-values.d.ts +1 -0
  183. package/dist/ui/settings-values.d.ts.map +1 -1
  184. package/dist/ui/settings.d.ts.map +1 -1
  185. package/dist/ui/settings.js +57 -18
  186. package/dist/ui/settings.js.map +2 -2
  187. package/dist/ui/spinner.d.ts +8 -1
  188. package/dist/ui/spinner.d.ts.map +1 -1
  189. package/dist/worker.js +3 -13
  190. package/dist/worker.js.map +2 -2
  191. package/docs/agents.md +35 -11
  192. package/docs/configuration.md +18 -12
  193. package/docs/foreman.md +65 -0
  194. package/docs/jev.md +11 -3
  195. package/docs/programmatic-compaction.md +12 -7
  196. package/docs/shell-middleware.md +61 -0
  197. package/docs/skills.md +2 -1
  198. package/package.json +5 -4
  199. package/skillsets/python/fabric-exec/SKILL.md +1 -1
  200. package/skillsets/python/fabric-exec/references/agents.md +1 -1
  201. package/skillsets/python/fabric-exec/references/mcp.md +1 -1
  202. package/skillsets/python/fabric-foreman/SKILL.md +249 -0
  203. package/skillsets/python/fabric-guide/SKILL.md +2 -1
  204. package/skillsets/python/fabric-jev/SKILL.md +2 -2
  205. package/skillsets/typescript/fabric-exec/SKILL.md +4 -2
  206. package/skillsets/typescript/fabric-exec/references/agents.md +3 -3
  207. package/skillsets/typescript/fabric-foreman/SKILL.md +240 -0
  208. package/skillsets/typescript/fabric-guide/SKILL.md +2 -1
  209. package/skillsets/typescript/fabric-jev/SKILL.md +2 -2
  210. package/dist/chunks/chunk-2IAVP4O2.js +0 -447
  211. package/dist/chunks/chunk-2IAVP4O2.js.map +0 -7
  212. package/dist/chunks/chunk-BJOJX2UW.js +0 -59
  213. package/dist/chunks/chunk-BJOJX2UW.js.map +0 -7
  214. package/dist/chunks/chunk-BYOGRJME.js.map +0 -7
  215. package/dist/chunks/chunk-FAMBJFFF.js.map +0 -7
  216. package/dist/chunks/chunk-G7UJLM33.js.map +0 -7
  217. package/dist/chunks/chunk-IYQ5MNCW.js.map +0 -7
  218. package/dist/chunks/chunk-JOEFBOFN.js.map +0 -7
  219. package/dist/chunks/chunk-KI277YNS.js.map +0 -7
  220. package/dist/chunks/chunk-M3S7XITB.js.map +0 -7
  221. package/dist/chunks/chunk-M3ZNZ6EZ.js.map +0 -7
  222. package/dist/chunks/chunk-M7W57BRC.js.map +0 -7
  223. package/dist/chunks/chunk-NPHCGLGH.js.map +0 -7
  224. package/dist/chunks/chunk-OTCASLY2.js.map +0 -7
  225. package/dist/chunks/chunk-QLV2IZ3F.js.map +0 -7
  226. package/dist/chunks/chunk-RAEGNBRA.js.map +0 -7
  227. package/dist/chunks/chunk-RZKN534S.js.map +0 -7
  228. package/dist/chunks/chunk-ULLIZPBH.js.map +0 -7
  229. package/dist/chunks/chunk-WG24VI7K.js.map +0 -7
  230. package/dist/chunks/chunk-X3OD47CL.js.map +0 -7
  231. package/dist/chunks/chunk-Z63R5GVN.js.map +0 -7
  232. /package/dist/chunks/{chunk-CIODQX77.js.map → chunk-2A2NWQ36.js.map} +0 -0
  233. /package/dist/chunks/{chunk-ZHJNWM6A.js.map → chunk-36B4AIRT.js.map} +0 -0
  234. /package/dist/chunks/{chunk-D6YSBP3R.js.map → chunk-IUCVOZRX.js.map} +0 -0
  235. /package/dist/chunks/{chunk-RWDKJ24D.js.map → chunk-NHMICIEU.js.map} +0 -0
  236. /package/dist/chunks/{chunk-7TX532EG.js.map → chunk-RKRVOBVO.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
 
@@ -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
 
@@ -239,13 +239,15 @@ 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
 
@@ -388,7 +390,7 @@ The classifier receives the exact action, bounded prepared arguments, cwd, user-
388
390
 
389
391
  ### Jev as the auto-mode classifier
390
392
 
391
- 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:
392
394
 
393
395
  ```json
394
396
  {
@@ -402,17 +404,17 @@ Select **Jev (TypeSafe safety classifier)** in **Approvals → Auto model** afte
402
404
  }
403
405
  ```
404
406
 
405
- 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.
406
408
 
407
- 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.
408
410
 
409
- 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.
410
412
 
411
- 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.
412
414
 
413
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).
414
416
 
415
- 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**.
416
418
 
417
419
  ## Temporal retention
418
420
 
@@ -453,7 +455,7 @@ Other agent settings:
453
455
  - `defaultTools`: the default tool allowlist for children.
454
456
  - `budgetUsd`: shared append-only cost ledger across a recursion tree (0 disables).
455
457
  - `maxTokensPerChild`: cumulative token bound per child (0 disables).
456
- - `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.
457
459
  - `sessionExport`: export each agent run's usage as an attributed pi-format session file (on by default).
458
460
  - `sessionExportDir`: override the export store root (default `~/.pi-fabric/agent`, with `PI_FABRIC_AGENT_DIR` taking precedence).
459
461
 
@@ -493,6 +495,10 @@ Fabric handles staleness in stale-while-revalidate style. Sessions adopt the cac
493
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.
494
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).
495
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`.
496
502
 
497
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.
498
504
 
@@ -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
 
@@ -202,6 +208,8 @@ Stop a loop with `jev.stop({ id })`, provider reload/unload, or a code-owned ter
202
208
 
203
209
  ## Main-turn advisors and supervisors
204
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
+
205
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`.
206
214
 
207
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.
@@ -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. |
@@ -0,0 +1,61 @@
1
+ # Cooperative bash middleware
2
+
3
+ A captured `bash` override normally owns execution. Fabric cannot safely substitute
4
+ its local runner for an arbitrary override (for example, an SSH backend or a
5
+ security gate). Consequently such overrides do not automatically gain Fabric's
6
+ background jobs.
7
+
8
+ An extension implementing **standard local bash plus environment/output filters**
9
+ can explicitly hand nested `pi.bash` execution to Fabric by attaching a host-local
10
+ capability to its registered `ToolDefinition`:
11
+
12
+ ```ts
13
+ import type { BashOperations } from "@earendil-works/pi-coding-agent";
14
+
15
+ const middleware = {
16
+ version: 1 as const,
17
+ options: { spawnHook, shellPath, commandPrefix },
18
+ wrapOperations: (local: BashOperations): BashOperations => redactOutput(local),
19
+ };
20
+
21
+ pi.registerTool(Object.assign(standaloneBashDefinition, {
22
+ [Symbol.for("pi-fabric:bash-middleware:v1")]: middleware,
23
+ }));
24
+ ```
25
+
26
+ `FABRIC_BASH_MIDDLEWARE` and `FabricBashMiddlewareV1` are also exported from
27
+ `pi-fabric/protocol`. Extensions may mirror the symbol key to avoid a runtime
28
+ package dependency. Neither callbacks nor secret values belong in tool argument
29
+ schemas, guest payloads, or discovery metadata.
30
+
31
+ ## Ownership and filter order
32
+
33
+ - The standalone definition remains registered. Without compatible Fabric, Pi
34
+ executes it normally, so it must still include the same protections itself.
35
+ - Opt-in explicitly replaces the override's `execute` and argument preparation
36
+ for nested `pi.bash` calls with Fabric's standard local-shell semantics. The
37
+ schema gains `cwd` and `background`; aliases, lifecycle hooks, policy blocking,
38
+ hard timeouts, cancellation, and session-owned job cleanup remain active.
39
+ - `options` accepts `shellPath`, `commandPrefix`, `spawnHook`, and
40
+ `exposeSessionEnvironment` (Pi's `BashToolOptions` except `operations`). The spawn
41
+ hook runs on a copy of the host environment including Pi session metadata;
42
+ remove child-only secrets without mutating the host's provider credentials.
43
+ - Fabric supplies the local operations backend. `wrapOperations` must delegate
44
+ command/cwd, environment, timeout, and abort signal to it. It may filter streamed
45
+ output **before** forwarding `onData`; Fabric's job buffer/log and Pi's
46
+ truncation file see only these filtered bytes. Handle split UTF-8/secret chunks
47
+ and flush safely on exit, errors, and cancellation.
48
+ - A handoff never disables an explicit `timeout`: it can still kill an already
49
+ backgrounded child. `executor.shellHangMs: 0` disables automatic handoff, not
50
+ explicit `background: true`.
51
+ - Middleware factories and hooks may close over current policy. Fabric reads the
52
+ active captured definition for each invocation rather than caching a prior
53
+ extension generation. The selected protection remains pinned across that
54
+ invocation's awaited lifecycle hooks. There is no load-order handshake or need to register another `bash` tool.
55
+ - Invalid capabilities or failing factories reject the call; Fabric never retries
56
+ through an unfiltered runner. Closed-world managed hosts still execute their
57
+ authorized override, not Fabric's native process backend.
58
+
59
+ Version 1 is intentionally bash-only. It is trusted extension cooperation, not a
60
+ sandbox or a security boundary. Unrelated overrides and direct `extensions.bash`
61
+ calls retain their original behavior.
package/docs/skills.md CHANGED
@@ -8,7 +8,7 @@ Pi Fabric uses a core-first, user-opt-in skill hierarchy.
8
8
  - The user invokes every advanced workflow. Each one declares `disable-model-invocation: true` and stays out of the model catalog. Agent policy forbids reading one autonomously or delegating from one user-only skill to another. The policy governs agent behavior. It is not a filesystem authorization boundary.
9
9
  - `/skill:fabric-guide` is the user-only router. It names one exact advanced command and stops there. The router never invokes the recommendation.
10
10
  - Each user-facing description summarizes its command. Only the selected execution reference spends always-on model context.
11
- - Both `skillsets/typescript/` and `skillsets/python/` contain the same thirteen canonical skill names, each with its own reference files. Fabric contributes only the selected tree through Pi resource discovery. Changing the kernel reloads Pi resources; see [kernel-specific skills](kernels.md#kernel-specific-skills-and-guidance). Third-party skills remain under Pi's normal discovery rules.
11
+ - Both `skillsets/typescript/` and `skillsets/python/` contain the same fourteen canonical skill names, each with its own reference files. Fabric contributes only the selected tree through Pi resource discovery. Changing the kernel reloads Pi resources; see [kernel-specific skills](kernels.md#kernel-specific-skills-and-guidance). Third-party skills remain under Pi's normal discovery rules.
12
12
 
13
13
  The parent agent behaves like regular Pi until the user explicitly opts into orchestration, recursion, Schema, Jev programs, ambient actors, or swarm coordination.
14
14
 
@@ -43,6 +43,7 @@ A mandatory pointer serves legibility and single-source maintenance. Per-run tok
43
43
  - `/skill:fabric-rlm`: decompose context recursively.
44
44
  - `/skill:fabric-schema`: gate mutation behind evidence.
45
45
  - `/skill:fabric-jev`: compose typed System One judgments, bounded foreground/background loops, and event-driven Main-turn advisors; see [Jev](jev.md).
46
+ - `/skill:fabric-foreman`: supervise Main’s coding work with batched Jev judgments and deterministic policy, per turn or at settlement; see [Foreman](foreman.md).
46
47
  - `/skill:fabric-advisor`: get persistent peer advice.
47
48
  - `/skill:fabric-supervisor`: supervise a persistent goal.
48
49
  - `/skill:fabric-spec`: supervise spec compliance persistently.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@e4779/pi-fabric",
3
- "version": "0.92.28-fork.5",
3
+ "version": "0.92.41-fork.6",
4
4
  "description": "A programmable tool and agent runtime for Pi",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -98,7 +98,7 @@
98
98
  "image": "https://raw.githubusercontent.com/monotykamary/pi-fabric/main/media/banner.svg"
99
99
  },
100
100
  "dependencies": {
101
- "@earendil-works/pi-ai": "0.85.1",
101
+ "@earendil-works/pi-ai": "0.87.0",
102
102
  "@jitl/quickjs-singlefile-mjs-release-sync": "^0.32.0",
103
103
  "@lezer/common": "^1.5.2",
104
104
  "@lezer/python": "^1.1.19",
@@ -119,8 +119,9 @@
119
119
  "@earendil-works/pi-tui": ">=0.80.6"
120
120
  },
121
121
  "devDependencies": {
122
- "@earendil-works/pi-coding-agent": "0.85.1",
123
- "@earendil-works/pi-tui": "0.85.1",
122
+ "@earendil-works/pi-agent-core": "0.87.0",
123
+ "@earendil-works/pi-coding-agent": "0.87.0",
124
+ "@earendil-works/pi-tui": "0.87.0",
124
125
  "@types/cross-spawn": "^6.0.6",
125
126
  "@types/node": "^26.1.2",
126
127
  "esbuild": "^0.25.12",
@@ -65,7 +65,7 @@ Advanced agent/mesh workflows require explicit user intent. Branch pointers: rea
65
65
 
66
66
  Use `await tools.call(ref="jev.evaluate", args={...})` for typed Choice/Noul/Score judgments. `jev.run`/`jev.spawn` take `{"program": ..., "input": ...}`; `jev.status` takes optional `{"id": ..., "after": ...}`, and `jev.wait`/`jev.stop` take `{"id": ...}`. Results are dictionaries: evaluate returns `model`, `answers`, and token `usage`; run/wait/stop return a run envelope with `id`, `state`, `result`/`error`, counts, usage, and bounded progress. Spawn initially returns `running` and optionally accepts `observe` for event-driven Main-turn advisors. Inside the TypeScript artifact, `program.nextEvent()` waits without polling; `program.advise({eventId,message})` requires `jev.advise` plus explicit delivery. The public `jev.advise` call takes `{"id": ..., "eventId": ..., "message": ...}` and returns `{"delivered": bool, "reason": ...}` (reason only when suppressed); agent approvals, freshness, and feedback gates apply. Return the observer ID without waiting inside Main. Status without id reports credential presence and run summaries without retrieving a key.
67
67
 
68
- The outer Fabric program remains Python. Jev's `program.code` is a TypeScript artifact executed by its dedicated QuickJS manager, not a Python runtime or shell escape hatch. Runs are session-owned, not restart-durable; cancelling wait cancels only the wait, and stop cannot roll back effects. Credentials stay host-side via `/login jev`, `TYPESAFE_API_KEY`, or a trusted command. Jev is unavailable in Schema enforce and managed hosts. State sent to TypeSafe consumes credits; confidence is not authorization.
68
+ The outer Fabric program remains Python. Jev's `program.code` is a TypeScript artifact executed by its dedicated QuickJS manager, not a Python runtime or shell escape hatch. Runs are session-owned, not restart-durable; cancelling wait cancels only the wait, and stop cannot roll back effects. Credentials stay host-side via `/login jev`/`TYPESAFE_API_KEY` for direct aliases, the existing openrouter credential for `typesafe/…` ids, the existing `vercel-ai-gateway` credential for `typesafe-ai/…` ids, or a trusted command. Jev is unavailable in Schema enforce and managed hosts. State sent to TypeSafe consumes credits; confidence is not authorization.
69
69
 
70
70
  Recommend `/skill:fabric-jev` for guided authoring; never load it autonomously. Only after direct invocation, `<skill-dir>/../fabric-jev/SKILL.md` is its workflow pointer. `<skill-dir>/../../../docs/jev.md` is a branch pointer for exact host contracts, limits, and browser composition.
71
71
 
@@ -23,7 +23,7 @@ Request fields include task, name, runner, kernel, transport, model, persona, th
23
23
  - `worktree=True` creates a retained dedicated Git worktree in the selected repository. Verify canonical repository identity, never infer it from directory naming. Abort with zero changes on mismatch. Partition concurrent edit ownership; never edit shared files concurrently. Inspect and stop active work before cleanup; leave unrelated worktrees alone.
24
24
  - `schema` requests validated structured output. `thinking` is configured/clamped reasoning effort.
25
25
 
26
- `agents.spawn` returns a handle; `wait`, `status`, `stop`, and `cleanup` take its id. Detached runs notify Main on terminal completion by default; `wait` makes the run foreground and suppresses that notification. `residency="durable"` is a spawn-only opt-in to outlive Main, requiring trusted mesh and no Schema enforce.
26
+ `agents.spawn` returns a handle; `wait`, `status`, `stop`, and `cleanup` take its id. Unread detached results are batched after the current tool turn, or wake idle Main once; concise UI notices appear immediately. `wait`/`join` and terminal `status` acknowledge results and retract pending notifications, even after completion. Running status and UI/list polling do not acknowledge them. Return the relevant outcome to Main from your program; prefer `wait` over status polling. Escape/error parks results until new input. `residency="durable"` is a spawn-only opt-in to outlive Main, requiring trusted mesh and no Schema enforce; unread deliveries and acknowledgments survive reconnects.
27
27
 
28
28
  ```python
29
29
  handle = await agents.spawn(task="Map the persistence layer.", tools=["read", "grep", "find", "ls"])
@@ -20,4 +20,4 @@ return await mcp.call(server="my-server", tool="weird-tool-name", args={"q": "x"
20
20
  return await tools.describe(ref="mcp.context7.resolve_library_id")
21
21
  ```
22
22
 
23
- Inspect inputSchema first and outputSchema when supplied. `tools.search` discovers current refs; `tools.call(ref=..., args=...)` invokes a computed one. `mcp.disableOAuth` permits cached credentials but prevents new interactive OAuth; calls respect mcp.callTimeoutMs. mcp.enabled=False disables this surface. Never expose credentials in model results.
23
+ Inspect inputSchema first and outputSchema when supplied. `tools.search` discovers current refs; `tools.search(query=..., searchMode="semantic")` is opt-in Jev ranking (enable under /fabric settings → MCP; block individual cached servers there). `tools.call(ref=..., args=...)` invokes a computed one. `mcp.disableOAuth` permits cached credentials but prevents new interactive OAuth; calls respect mcp.callTimeoutMs. mcp.enabled=False disables this surface. Never expose credentials in model results.