@e4779/pi-fabric 0.131.0-fork.32 → 0.132.6-fork.34

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 (232) hide show
  1. package/README.md +1 -1
  2. package/dist/activity/store.d.ts.map +1 -1
  3. package/dist/actors/feedback.d.ts +5 -0
  4. package/dist/actors/feedback.d.ts.map +1 -0
  5. package/dist/actors/global-registry.d.ts.map +1 -1
  6. package/dist/actors/manager.d.ts.map +1 -1
  7. package/dist/agents/completion-inbox.d.ts +2 -1
  8. package/dist/agents/completion-inbox.d.ts.map +1 -1
  9. package/dist/agents/manager.d.ts.map +1 -1
  10. package/dist/agents/request.d.ts.map +1 -1
  11. package/dist/agents/transports/herdr-core-socket.d.ts +13 -0
  12. package/dist/agents/transports/herdr-core-socket.d.ts.map +1 -0
  13. package/dist/agents/transports/herdr-core-transport.d.ts +10 -0
  14. package/dist/agents/transports/herdr-core-transport.d.ts.map +1 -0
  15. package/dist/agents.js +5 -1
  16. package/dist/agents.js.map +1 -1
  17. package/dist/async-settlement.d.ts +1 -1
  18. package/dist/async-settlement.d.ts.map +1 -1
  19. package/dist/audit/details.d.ts +2 -0
  20. package/dist/audit/details.d.ts.map +1 -1
  21. package/dist/chunks/{chunk-HSEZPCL5.js → chunk-2OC4YJOL.js} +3 -3
  22. package/dist/chunks/{chunk-TXCNZCZP.js → chunk-2QJ4MNS6.js} +2 -2
  23. package/dist/chunks/{chunk-QOEOKW2X.js → chunk-3QH6JAE3.js} +2 -2
  24. package/dist/chunks/{chunk-3XT5WHSG.js → chunk-4Y5KEJP4.js} +3 -3
  25. package/dist/chunks/{chunk-RAA3FAYZ.js → chunk-5PSEJOJB.js} +2 -2
  26. package/dist/chunks/{chunk-XFOSUGLU.js → chunk-66UTGL7T.js} +2 -2
  27. package/dist/chunks/{chunk-WWTGWGH7.js → chunk-6ZPEPRUV.js} +27 -9
  28. package/dist/chunks/chunk-6ZPEPRUV.js.map +7 -0
  29. package/dist/chunks/{chunk-7TB7NXSL.js → chunk-7CIQQOOD.js} +11 -3
  30. package/dist/chunks/{chunk-7TB7NXSL.js.map → chunk-7CIQQOOD.js.map} +2 -2
  31. package/dist/chunks/{chunk-3PKZSIRA.js → chunk-ASOJYFKU.js} +8 -4
  32. package/dist/chunks/chunk-ASOJYFKU.js.map +7 -0
  33. package/dist/chunks/{chunk-PUBHBEYO.js → chunk-B2FIGOPI.js} +2 -2
  34. package/dist/chunks/{chunk-ZFWICFNJ.js → chunk-DGUXJSYA.js} +41 -17
  35. package/dist/chunks/chunk-DGUXJSYA.js.map +7 -0
  36. package/dist/chunks/{chunk-WGMCNCP6.js → chunk-F3D7GTBK.js} +228 -90
  37. package/dist/chunks/chunk-F3D7GTBK.js.map +7 -0
  38. package/dist/chunks/{chunk-X7QETPBC.js → chunk-F6GIK5GO.js} +8 -8
  39. package/dist/chunks/{chunk-LKYLD5SN.js → chunk-FMEOJJ6Y.js} +3 -2
  40. package/dist/chunks/chunk-FMEOJJ6Y.js.map +7 -0
  41. package/dist/chunks/{chunk-4PBW54I2.js → chunk-GGQ43B7T.js} +3 -3
  42. package/dist/chunks/{chunk-MSDL7U6Q.js → chunk-JSHIS7GO.js} +2 -2
  43. package/dist/chunks/{chunk-VNWQIGQL.js → chunk-JWERGULW.js} +421 -254
  44. package/dist/chunks/chunk-JWERGULW.js.map +7 -0
  45. package/dist/chunks/{chunk-HRDMBGMY.js → chunk-K4VRQ7WZ.js} +4 -4
  46. package/dist/chunks/{chunk-5BOTHX47.js → chunk-LP5EVMBB.js} +157 -4
  47. package/dist/chunks/chunk-LP5EVMBB.js.map +7 -0
  48. package/dist/chunks/{chunk-4KX6BIPL.js → chunk-LRSZFYUC.js} +2 -2
  49. package/dist/chunks/chunk-LRSZFYUC.js.map +7 -0
  50. package/dist/chunks/{chunk-56NMRVTV.js → chunk-MGFSQXAJ.js} +23 -23
  51. package/dist/chunks/{chunk-56NMRVTV.js.map → chunk-MGFSQXAJ.js.map} +2 -2
  52. package/dist/chunks/{chunk-RWKQ5SRW.js → chunk-MTAFECXB.js} +2 -2
  53. package/dist/chunks/{chunk-UFMYN5TA.js → chunk-MX53BRAC.js} +2 -2
  54. package/dist/chunks/{chunk-7CIES6X2.js → chunk-NGXAEGD2.js} +12 -2
  55. package/dist/chunks/chunk-NGXAEGD2.js.map +7 -0
  56. package/dist/chunks/{chunk-IOGDTIGN.js → chunk-NSV7WTCT.js} +3 -3
  57. package/dist/chunks/{chunk-IOGDTIGN.js.map → chunk-NSV7WTCT.js.map} +1 -1
  58. package/dist/chunks/{chunk-3VK6UGAN.js → chunk-O5SHIUIL.js} +6 -1
  59. package/dist/chunks/chunk-O5SHIUIL.js.map +7 -0
  60. package/dist/chunks/{chunk-4WKD3YM3.js → chunk-OILZ4PDY.js} +3 -3
  61. package/dist/chunks/{chunk-H57KPL3V.js → chunk-S2JWFXW5.js} +2 -2
  62. package/dist/chunks/{chunk-HFDJWLMS.js → chunk-SOEUGSY4.js} +2 -2
  63. package/dist/chunks/{chunk-YHFWMAQ5.js → chunk-TEMKDJJY.js} +151 -52
  64. package/dist/chunks/chunk-TEMKDJJY.js.map +7 -0
  65. package/dist/chunks/{chunk-KIFOEBYJ.js → chunk-VEXCD3RA.js} +2 -2
  66. package/dist/chunks/{chunk-GS67KDMV.js → chunk-VN7AE3EY.js} +2 -2
  67. package/dist/chunks/{chunk-MPMEK3IQ.js → chunk-WYLBWFAO.js} +2 -2
  68. package/dist/chunks/{chunk-6GWDGTHC.js → chunk-YLO62DWD.js} +4 -4
  69. package/dist/chunks/{chunk-4BYS4ZLY.js → chunk-YN4K3FNB.js} +5 -5
  70. package/dist/chunks/{chunk-OJ4HAALD.js → chunk-YO5UIWDY.js} +3 -3
  71. package/dist/chunks/{chunk-7N7IC3Z2.js → chunk-ZCXW3GR7.js} +2 -2
  72. package/dist/chunks/{chunk-36XQFTEN.js → chunk-ZY375C2U.js} +2 -2
  73. package/dist/commands/fabric-handler.js +2 -2
  74. package/dist/commands/fabric-handler.js.map +1 -1
  75. package/dist/commands/fabric.d.ts.map +1 -1
  76. package/dist/compaction/claim-events.js +8 -8
  77. package/dist/compaction/hook.js +6 -6
  78. package/dist/compaction/owner.js +7 -7
  79. package/dist/compaction/threshold.d.ts.map +1 -1
  80. package/dist/components/configuration.js +3 -3
  81. package/dist/config.d.ts +1 -1
  82. package/dist/config.d.ts.map +1 -1
  83. package/dist/core/action-registry.d.ts +1 -1
  84. package/dist/core/action-registry.d.ts.map +1 -1
  85. package/dist/core/action-registry.js +8 -8
  86. package/dist/core/attached-monitors.d.ts +39 -0
  87. package/dist/core/attached-monitors.d.ts.map +1 -0
  88. package/dist/core/call-presentation.d.ts +14 -0
  89. package/dist/core/call-presentation.d.ts.map +1 -0
  90. package/dist/core/execution-guidelines.d.ts +6 -0
  91. package/dist/core/execution-guidelines.d.ts.map +1 -0
  92. package/dist/core/guidance-delivery.d.ts +19 -0
  93. package/dist/core/guidance-delivery.d.ts.map +1 -0
  94. package/dist/core/observation-actions.d.ts +9 -0
  95. package/dist/core/observation-actions.d.ts.map +1 -0
  96. package/dist/core/prompt-guidance.d.ts +1 -0
  97. package/dist/core/prompt-guidance.d.ts.map +1 -1
  98. package/dist/core/prompt-guidance.js +50 -1
  99. package/dist/core/prompt-guidance.js.map +3 -3
  100. package/dist/core/provider-operations.js +1 -1
  101. package/dist/core/shell-inbox.d.ts +1 -1
  102. package/dist/core/shell-inbox.d.ts.map +1 -1
  103. package/dist/core/shell-jobs.d.ts +17 -1
  104. package/dist/core/shell-jobs.d.ts.map +1 -1
  105. package/dist/core/shell-monitor.d.ts +1 -0
  106. package/dist/core/shell-monitor.d.ts.map +1 -1
  107. package/dist/durable/agent.d.ts.map +1 -1
  108. package/dist/durable/worker-host.js +1 -1
  109. package/dist/durable-extension.d.ts +2 -2
  110. package/dist/durable-extension.d.ts.map +1 -1
  111. package/dist/durable-extension.js +215 -1
  112. package/dist/durable-extension.js.map +3 -3
  113. package/dist/durable-host.js +1 -1
  114. package/dist/durable.d.ts.map +1 -1
  115. package/dist/durable.js +5 -4
  116. package/dist/durable.js.map +2 -2
  117. package/dist/entropy/index.js +9 -9
  118. package/dist/extension-bootstrap.d.ts.map +1 -1
  119. package/dist/extension-bootstrap.js +12 -12
  120. package/dist/extension.d.ts.map +1 -1
  121. package/dist/fabric-exec-tool.d.ts.map +1 -1
  122. package/dist/fabric-runtime-state.d.ts.map +1 -1
  123. package/dist/fabric-runtime-state.js +410 -230
  124. package/dist/fabric-runtime-state.js.map +4 -4
  125. package/dist/feedback.d.ts +5 -0
  126. package/dist/feedback.d.ts.map +1 -0
  127. package/dist/index.js +21 -21
  128. package/dist/jev/client.js +2 -2
  129. package/dist/jev/observation.js +5 -5
  130. package/dist/jev.js +10 -10
  131. package/dist/main-agent.d.ts +2 -1
  132. package/dist/main-agent.d.ts.map +1 -1
  133. package/dist/memory/discovery.js +6 -6
  134. package/dist/memory/file-worker.js +8 -8
  135. package/dist/memory/normalize.js +5 -5
  136. package/dist/memory/search.js +6 -6
  137. package/dist/memory/worker-provider.js +9 -9
  138. package/dist/memory.js +9 -9
  139. package/dist/providers/agents-actions.d.ts.map +1 -1
  140. package/dist/providers/agents-message-router.d.ts.map +1 -1
  141. package/dist/providers/agents-provider.d.ts +2 -0
  142. package/dist/providers/agents-provider.d.ts.map +1 -1
  143. package/dist/providers/jev-provider.js +10 -10
  144. package/dist/providers/memory-provider.js +8 -8
  145. package/dist/providers/tasks-provider.d.ts +3 -1
  146. package/dist/providers/tasks-provider.d.ts.map +1 -1
  147. package/dist/residency/host.js +9 -9
  148. package/dist/residency/pi-entry.js +9 -9
  149. package/dist/runtime/core-override-guest-types.js +2 -2
  150. package/dist/runtime/cpython-runtime.js +1 -1
  151. package/dist/runtime/guest-types.d.ts +1 -1
  152. package/dist/runtime/guest-types.d.ts.map +1 -1
  153. package/dist/runtime/guest-types.js +1 -1
  154. package/dist/runtime/monty-runtime.js +2 -2
  155. package/dist/runtime/node-process-runtime.js +3 -3
  156. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  157. package/dist/runtime/quickjs-runtime.js +2 -2
  158. package/dist/runtime/typescript-kernel.js +5 -5
  159. package/dist/runtime-state-builtins.d.ts +2 -0
  160. package/dist/runtime-state-builtins.d.ts.map +1 -1
  161. package/dist/topology/participant-directory.d.ts.map +1 -1
  162. package/dist/topology/peer-presence.d.ts.map +1 -1
  163. package/dist/topology/provider-participants.d.ts +1 -0
  164. package/dist/topology/provider-participants.d.ts.map +1 -1
  165. package/dist/type-error-guidance.js +1 -1
  166. package/dist/ui/code-preview-shell.d.ts +1 -0
  167. package/dist/ui/code-preview-shell.d.ts.map +1 -1
  168. package/dist/ui/dashboard-model.d.ts.map +1 -1
  169. package/dist/ui/dashboard.js +8 -5
  170. package/dist/ui/dashboard.js.map +2 -2
  171. package/dist/ui/fabric-render.d.ts +1 -0
  172. package/dist/ui/fabric-render.d.ts.map +1 -1
  173. package/dist/ui/settings-values.d.ts +1 -1
  174. package/dist/ui/settings-values.d.ts.map +1 -1
  175. package/dist/ui/settings.js +3 -3
  176. package/dist/ui/settings.js.map +2 -2
  177. package/dist/ui/shell-tasks.d.ts.map +1 -1
  178. package/dist/ui/shell-tasks.js +20 -4
  179. package/dist/ui/shell-tasks.js.map +2 -2
  180. package/dist/ui/widget.d.ts +8 -4
  181. package/dist/ui/widget.d.ts.map +1 -1
  182. package/dist/verified/generated/manifest.json +12 -3
  183. package/dist/verified/generated/prompt-guidance.d.ts +4 -0
  184. package/dist/verified/generated/prompt-guidance.js +17 -0
  185. package/docs/agents.md +26 -6
  186. package/docs/background-tasks.md +98 -14
  187. package/docs/configuration.md +2 -0
  188. package/docs/interface.md +3 -1
  189. package/docs/jev.md +1 -1
  190. package/docs/verified-kernels.md +23 -0
  191. package/package.json +9 -9
  192. package/proofs/index.ts +2 -0
  193. package/proofs/prompt-guidance.ts +38 -0
  194. package/scripts/verified-kernels.ts +1 -1
  195. package/skillsets/python/fabric-council/SKILL.md +25 -14
  196. package/skillsets/typescript/fabric-council/SKILL.md +24 -15
  197. package/skillsets/typescript/fabric-exec/references/agents.md +5 -5
  198. package/dist/chunks/chunk-3PKZSIRA.js.map +0 -7
  199. package/dist/chunks/chunk-3VK6UGAN.js.map +0 -7
  200. package/dist/chunks/chunk-4KX6BIPL.js.map +0 -7
  201. package/dist/chunks/chunk-5BOTHX47.js.map +0 -7
  202. package/dist/chunks/chunk-7CIES6X2.js.map +0 -7
  203. package/dist/chunks/chunk-LKYLD5SN.js.map +0 -7
  204. package/dist/chunks/chunk-VNWQIGQL.js.map +0 -7
  205. package/dist/chunks/chunk-WGMCNCP6.js.map +0 -7
  206. package/dist/chunks/chunk-WWTGWGH7.js.map +0 -7
  207. package/dist/chunks/chunk-YHFWMAQ5.js.map +0 -7
  208. package/dist/chunks/chunk-ZFWICFNJ.js.map +0 -7
  209. /package/dist/chunks/{chunk-HSEZPCL5.js.map → chunk-2OC4YJOL.js.map} +0 -0
  210. /package/dist/chunks/{chunk-TXCNZCZP.js.map → chunk-2QJ4MNS6.js.map} +0 -0
  211. /package/dist/chunks/{chunk-QOEOKW2X.js.map → chunk-3QH6JAE3.js.map} +0 -0
  212. /package/dist/chunks/{chunk-3XT5WHSG.js.map → chunk-4Y5KEJP4.js.map} +0 -0
  213. /package/dist/chunks/{chunk-RAA3FAYZ.js.map → chunk-5PSEJOJB.js.map} +0 -0
  214. /package/dist/chunks/{chunk-XFOSUGLU.js.map → chunk-66UTGL7T.js.map} +0 -0
  215. /package/dist/chunks/{chunk-PUBHBEYO.js.map → chunk-B2FIGOPI.js.map} +0 -0
  216. /package/dist/chunks/{chunk-X7QETPBC.js.map → chunk-F6GIK5GO.js.map} +0 -0
  217. /package/dist/chunks/{chunk-4PBW54I2.js.map → chunk-GGQ43B7T.js.map} +0 -0
  218. /package/dist/chunks/{chunk-MSDL7U6Q.js.map → chunk-JSHIS7GO.js.map} +0 -0
  219. /package/dist/chunks/{chunk-HRDMBGMY.js.map → chunk-K4VRQ7WZ.js.map} +0 -0
  220. /package/dist/chunks/{chunk-RWKQ5SRW.js.map → chunk-MTAFECXB.js.map} +0 -0
  221. /package/dist/chunks/{chunk-UFMYN5TA.js.map → chunk-MX53BRAC.js.map} +0 -0
  222. /package/dist/chunks/{chunk-4WKD3YM3.js.map → chunk-OILZ4PDY.js.map} +0 -0
  223. /package/dist/chunks/{chunk-H57KPL3V.js.map → chunk-S2JWFXW5.js.map} +0 -0
  224. /package/dist/chunks/{chunk-HFDJWLMS.js.map → chunk-SOEUGSY4.js.map} +0 -0
  225. /package/dist/chunks/{chunk-KIFOEBYJ.js.map → chunk-VEXCD3RA.js.map} +0 -0
  226. /package/dist/chunks/{chunk-GS67KDMV.js.map → chunk-VN7AE3EY.js.map} +0 -0
  227. /package/dist/chunks/{chunk-MPMEK3IQ.js.map → chunk-WYLBWFAO.js.map} +0 -0
  228. /package/dist/chunks/{chunk-6GWDGTHC.js.map → chunk-YLO62DWD.js.map} +0 -0
  229. /package/dist/chunks/{chunk-4BYS4ZLY.js.map → chunk-YN4K3FNB.js.map} +0 -0
  230. /package/dist/chunks/{chunk-OJ4HAALD.js.map → chunk-YO5UIWDY.js.map} +0 -0
  231. /package/dist/chunks/{chunk-7N7IC3Z2.js.map → chunk-ZCXW3GR7.js.map} +0 -0
  232. /package/dist/chunks/{chunk-36XQFTEN.js.map → chunk-ZY375C2U.js.map} +0 -0
@@ -34,6 +34,7 @@ a set of small policy kernels, **not a proof of every subsystem invariant**.
34
34
  | State and Schema | `policy.ts`: `headReadable`, `certificateAccepted`, `consume` | `state/store.ts`, `schema/controller.ts` | `head_sound`, `pending_without_marker_hidden`, `committed_head_visible`, `pending_head_visible`, `certificate_sound`, `certificate_complete`, `consume_once`, `consume_retires` |
35
35
  | External mesh grants | `grants.ts`: `meshGrantTake` | `verified/grants.ts`, `mesh/grants.ts` | Exact scoped admission, expiry/refusal precedence, exact decrement, refusal preservation and kind/topic forwarding |
36
36
  | Speculation bookkeeping | `speculation.ts`: `speculationAdmission`, `speculationCheck`, `speculationAccounting`; `policy.ts`: `consume` | `verified/speculation.ts`, `speculation/store.ts` | Exact admission caps, checkpoint refusal precedence, one-use entry reservation, exact event counters and epoch successor |
37
+ | Portable prompt guidance | `prompt-guidance.ts`: `promptGuidance` | `core/guidance-delivery.ts`, `extension.ts` | Exactly one portable destination while active, no inactive injection, structured routing, forced/legacy fallback |
37
38
  | Actor name decision | `actor-name.ts`: `actorName` | `actors/name-policy.ts`, `actors/manager.ts`, `actors/directory.ts` | Active dominates stopped, stopped is refused absent active, neither is available; host snapshot only, not a reservation |
38
39
  | Agent budget admission | `budget.ts`: `budgetAdmission` | `verified/budget.ts`, `agents/manager.ts` | Strict threshold safety/completeness, equality refusal, invalid observations refused |
39
40
  | Effect diagnostics | `policy.ts`: `unknownConflict`, `knownConflict` | `components/effect-policy.ts` | `unknown_conflict_exact`, `unknown_conflict_symmetric`, `known_conflict_exact` |
@@ -300,6 +301,28 @@ reducer proves that provider promises account for every subprocess or remote
300
301
  effect. Arbitrary inverses, ambient effects, liveness, schedule confluence and
301
302
  author-defined observational equivalence are not claimed.
302
303
 
304
+ ### Portable execution guidance
305
+
306
+ Fabric's execution rules have one authored source in `core/execution-guidelines.ts`.
307
+ The tool metadata exposes them to Pi, and the first-use prompt hook moves only
308
+ those exact rules into the named `fabric` section (or the explicit append when
309
+ a prompt is forced or the host has no sections). This keeps providers that
310
+ project custom sections but discard Pi's generated rules, such as
311
+ `pi-claude-bridge`, from losing batching and bounded-output instructions.
312
+ Unrelated tool rules remain in their original place. Preparation is pure: the
313
+ hook commits the relocation only after all renderers succeed, and removes exact
314
+ owned bullet lines from already-rendered forced/legacy prompts before appending
315
+ the current rules. Stale rules from a previous kernel selection are owned too.
316
+
317
+ The compiled `promptGuidance` decision proves an active render selects exactly
318
+ one portable destination and removes duplicate native ownership; an inactive
319
+ render keeps native ownership and injects nothing. Forced prompts always take
320
+ the append, even when a sections object exists. These are routing laws, not
321
+ proofs about prose semantics, provider compliance, or model token savings.
322
+ Exact string preservation, language variants, other extensions' rules, stable
323
+ re-renders, and Pi's actual named-section/forced-prompt pipeline are tested
324
+ offline. No model inference is needed.
325
+
303
326
  ## Reproducible bridge
304
327
 
305
328
  `gdp-wired` is an exact devDependency. Installed Fabric needs neither the prover
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@e4779/pi-fabric",
3
- "version": "0.131.0-fork.32",
3
+ "version": "0.132.6-fork.34",
4
4
  "description": "A programmable tool and agent runtime for Pi",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -143,9 +143,9 @@
143
143
  "image": "https://raw.githubusercontent.com/fabric-runtime/pi-fabric/main/media/banner.svg"
144
144
  },
145
145
  "dependencies": {
146
- "@earendil-works/chord": "1.4.0",
147
- "@earendil-works/pi-codemode": "1.4.0",
148
- "@earendil-works/pi-durable": "1.4.0",
146
+ "@earendil-works/chord": "1.5.0",
147
+ "@earendil-works/pi-codemode": "1.5.0",
148
+ "@earendil-works/pi-durable": "1.5.0",
149
149
  "@jitl/quickjs-singlefile-mjs-release-sync": "^0.32.0",
150
150
  "@lezer/common": "^1.5.2",
151
151
  "@lezer/python": "^1.1.19",
@@ -155,7 +155,7 @@
155
155
  "cross-spawn": "^7.0.6",
156
156
  "diff": "^9.0.0",
157
157
  "mcporter": "^0.12.3",
158
- "pi-fabric-worker-sdk": "npm:@earendil-works/pi-coding-agent@1.4.0",
158
+ "pi-fabric-worker-sdk": "npm:@earendil-works/pi-coding-agent@1.5.0",
159
159
  "quickjs-emscripten-core": "^0.32.0",
160
160
  "shiki": "4.4.3",
161
161
  "typescript": "^6.0.3",
@@ -172,10 +172,10 @@
172
172
  "@earendil-works/pi-durable": ">=1.4.0"
173
173
  },
174
174
  "devDependencies": {
175
- "@earendil-works/pi-agent-core": "1.4.0",
176
- "@earendil-works/pi-ai": "1.4.0",
177
- "@earendil-works/pi-coding-agent": "1.4.0",
178
- "@earendil-works/pi-tui": "1.4.0",
175
+ "@earendil-works/pi-agent-core": "1.5.0",
176
+ "@earendil-works/pi-ai": "1.5.0",
177
+ "@earendil-works/pi-coding-agent": "1.5.0",
178
+ "@earendil-works/pi-tui": "1.5.0",
179
179
  "@types/cross-spawn": "^6.0.6",
180
180
  "@types/node": "^26.1.2",
181
181
  "esbuild": "^0.25.12",
package/proofs/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  // The registered kernels. Each module is proved, refused in every broken
2
2
  // variant, cross-checked against its builders, and compiled to
3
3
  // `src/verified/generated/<module>.js`.
4
+ import { promptGuidanceKernels, PROMPT_GUIDANCE_BUGS } from "./prompt-guidance.js";
4
5
  import { actorNameKernels, ACTOR_NAME_BUGS } from "./actor-name.js";
5
6
  import { authorityKernels, AUTHORITY_BUGS } from "./authority.js";
6
7
  import { compactionKernels, CUT_BUGS } from "./compaction.js";
@@ -37,4 +38,5 @@ export const modules: readonly KernelModule[] = [
37
38
  { stem: "speculation", source: "proofs/speculation.ts", kernels: speculationKernels as any, bugs: SPECULATION_BUGS },
38
39
  { stem: "actor-name", source: "proofs/actor-name.ts", kernels: actorNameKernels as any, bugs: ACTOR_NAME_BUGS },
39
40
  { stem: "budget", source: "proofs/budget.ts", kernels: budgetKernels as any, bugs: BUDGET_BUGS },
41
+ { stem: "prompt-guidance", source: "proofs/prompt-guidance.ts", kernels: promptGuidanceKernels as any, bugs: PROMPT_GUIDANCE_BUGS },
40
42
  ];
@@ -0,0 +1,38 @@
1
+ // Provider-neutral routing: a provider may discard Pi's generated rules but
2
+ // preserve named sections or an explicitly appended prompt. No text semantics
3
+ // are assumed here; the adapter tests pin the exact strings and host behavior.
4
+ import { bool, fun } from "gdp-wired";
5
+ import type { Kernel } from "./kernel.js";
6
+
7
+ type PromptGuidanceBug = "drop portable rules" | "duplicate delivery" | "ignore forced prompt" | "inject while inactive" | "keep duplicate native rules";
8
+
9
+ const decision = (bug?: PromptGuidanceBug) => fun("portable prompt guidance")
10
+ .inputs({ active: bool, sections: bool, forced: bool })
11
+ .returns(({ active, sections, forced }) => ({
12
+ section: bug === "drop portable rules" ? active.and(active.not())
13
+ : bug === "inject while inactive" ? sections.and(forced.not())
14
+ : bug === "ignore forced prompt" ? active.and(sections)
15
+ : active.and(sections, forced.not()),
16
+ append: bug === "duplicate delivery" ? active
17
+ : bug === "drop portable rules" ? active.and(active.not())
18
+ : bug === "ignore forced prompt" ? active.and(sections.not())
19
+ : active.and(sections.not().or(forced)),
20
+ native: bug === "keep duplicate native rules" ? active.or(active.not()) : active.not(),
21
+ }));
22
+
23
+ export const promptGuidanceKernels = (bug?: PromptGuidanceBug): Kernel[] => {
24
+ const f = decision(bug);
25
+ return [{ id: "promptGuidance", fun: f, decisions: [
26
+ f.law("active guidance has exactly one portable destination and no duplicate native rules",
27
+ ({ active }) => active, (o) => o.section.or(o.append).and(o.section.and(o.append).not(), o.native.not())),
28
+ f.law("inactive guidance keeps native ownership and injects nothing",
29
+ ({ active }) => active.not(), (o) => o.native.and(o.section.not(), o.append.not())),
30
+ f.law("an unforced structured prompt carries guidance in its section",
31
+ ({ active, sections, forced }) => active.and(sections, forced.not()), (o) => o.section.and(o.append.not())),
32
+ f.law("a forced or legacy prompt carries guidance in its append",
33
+ ({ active, sections, forced }) => active.and(sections.not().or(forced)), (o) => o.append.and(o.section.not())),
34
+ ] }];
35
+ };
36
+ export const PROMPT_GUIDANCE_BUGS: PromptGuidanceBug[] = [
37
+ "drop portable rules", "duplicate delivery", "ignore forced prompt", "inject while inactive", "keep duplicate native rules",
38
+ ];
@@ -13,7 +13,7 @@ const root = fileURLToPath(new URL("../", import.meta.url));
13
13
  const read = (path: string): string => readFileSync(resolve(root, path), "utf8");
14
14
  const hash = (text: string): string => createHash("sha256").update(text).digest("hex");
15
15
  const receipt = "src/verified/generated/manifest.json";
16
- const stems = ["policy", "compaction", "resources", "lifecycle", "storage", "provider", "authority", "grants", "speculation", "budget", "actor-name"];
16
+ const stems = ["policy", "compaction", "resources", "lifecycle", "storage", "provider", "authority", "grants", "speculation", "budget", "actor-name", "prompt-guidance"];
17
17
  const sources = ["proofs/index.ts", "proofs/kernel.ts", ...stems.map((stem) => `proofs/${stem}.ts`), "scripts/verified-kernels.ts", "scripts/verified-kernel-pool.ts", "scripts/verified-kernel-worker.ts"];
18
18
  const artifacts = stems.flatMap((stem) => [`src/verified/generated/${stem}.js`, `src/verified/generated/${stem}.d.ts`]);
19
19
  const pinned = (): string => {
@@ -102,25 +102,36 @@ if not completed:
102
102
  return dict(summary, status="failed", failures=failures, result=None)
103
103
  # Park completed reports in mesh before synthesis: an audit trail that survives this
104
104
  # program, and full-text recovery when synthesis fails or a budget runs out.
105
- reports_key = "council/" + datetime.now(timezone.utc).strftime("%Y-%m-%d-%H-%M-%S") + "/reports"
106
- try:
107
- await mesh.put({
108
- "key": reports_key,
109
- "value": [
110
- {"role": item.get("role"), **({"model": item["model"]} if item.get("model") else {}), "report": item["report"]}
111
- for item in completed
112
- ],
113
- })
114
- reports = reports_key
115
- except Exception as error:
116
- reports = {"error": str(error)}
105
+ # ifVersion=0 makes each put create-only, so a same-second council moves to the
106
+ # next key suffix instead of overwriting an earlier run's reports.
107
+ _parked = [
108
+ {"role": item.get("role"), **({"model": item["model"]} if item.get("model") else {}), "report": item["report"]}
109
+ for item in completed
110
+ ]
111
+ reports = None
112
+ _park_error = None
113
+ for _attempt in range(4):
114
+ _suffix = "" if _attempt == 0 else "-" + str(_attempt + 1)
115
+ reports_key = "council/" + datetime.now(timezone.utc).strftime("%Y-%m-%d-%H-%M-%S") + _suffix + "/reports"
116
+ try:
117
+ await mesh.put(key=reports_key, value=_parked, ifVersion=0)
118
+ reports = reports_key
119
+ break
120
+ except Exception as error:
121
+ _park_error = error
122
+ # Only a same-timestamp collision retries with the next suffix; any other
123
+ # storage failure surfaces immediately as the {"error": ...} object.
124
+ if "compare-and-swap" not in str(error):
125
+ break
126
+ if reports is None:
127
+ reports = {"error": str(_park_error)}
117
128
  if len(completed) == 1:
118
129
  return dict(summary, status="partial", failures=failures, result=completed[0]["report"], reports=reports, synthesisSkipped="Only one role completed; another agent adds no diversity.")
119
130
  try:
120
131
  result = await ask("Synthesize only the completed reports into one decision. Reject unsupported claims, preserve material disagreements, and attribute concerns to roles. Never infer views of failed roles.\nTask:\n" + π.task + "\nReports:\n" + json.dumps(completed), "council synthesis", {"model": synthesis_model} if synthesis_model else None)
121
132
  return dict(summary, status="partial" if failures else "success", failures=failures, result=result, reports=reports)
122
133
  except Exception as error:
123
- return dict(summary, status="partial", failures=failures, result=None, synthesisError=str(error), reports=reports, fallback=[{"role": item.get("role"), "status": "completed", "report": item["report"][:1200]} for item in completed])
134
+ return dict(summary, status="partial", failures=failures, result=None, synthesisError=str(error), reports=reports, fallback=[{"role": item.get("role"), "status": "completed", "report": item["report"] if isinstance(reports, dict) else item["report"][:1200]} for item in completed])
124
135
  ```
125
136
 
126
- Reserve at least the role count plus one agent call. Concurrency remains host-limited; usage settles afterward, not as a hard token reservation. Model keys must match a Pi registry key from `tools.models()` exactly, ignoring case; the program refuses a `models.aliases` name or a partial id, and checks every key before any agent runs. Whenever at least one seat completes, full role reports are parked to mesh under a `council/<timestamp>/reports` key carried by every outcome as `reports`: `mesh.get` it for audit or to retry a budget-starved synthesis with one plain agent, and `mesh.delete` it when no longer needed; on synthesis failure the fallback carries report heads plus that mesh key, so full texts never need to land in context. Every result lists `seats` with each role's pinned model, thinking, and status, plus `synthesisModel` when one was pinned. These are the models the program requested; keeping a run on its pinned model is the host's job. Successful synthesis returns only the compact decision, coverage, seats, and failures; raw reports return only on synthesis failure. A partial result is useful evidence with named gaps, not permission for an automatic whole-council rerun. Retry only the failed role or synthesis when needed. Do not use a council for a lookup.
137
+ Reserve at least the role count plus one agent call. Concurrency remains host-limited; usage settles afterward, not as a hard token reservation. Model keys must match a Pi registry key from `tools.models()` exactly, ignoring case; the program refuses a `models.aliases` name or a partial id, and checks every key before any agent runs. Whenever at least one seat completes, full role reports are parked to mesh under a create-only `council/<timestamp>/reports` key carried by every outcome as `reports` — a same-second collision parks under the next suffix (`-2`, `-3`, …) rather than overwriting: `mesh.get` it for audit or to retry a budget-starved synthesis with one plain agent, and `mesh.delete` it when no longer needed; on synthesis failure the fallback result carries report heads plus that mesh key, not the full texts; the synthesis prompt still embeds every completed report, so synthesis input grows with total report size. When mesh storage itself fails, `reports` is an `{"error": ...}` object instead of a key — never pass it to `mesh.get` or `mesh.delete` — and the synthesis-failure fallback then carries the full untruncated reports. A single completed role returns its full report directly as `result` without a synthesis call. Every result lists `seats` with each role's pinned model, thinking, and status, plus `synthesisModel` when one was pinned. These are the models the program requested; keeping a run on its pinned model is the host's job. Successful synthesis returns the compact decision, coverage, seats, failures, and `reports` (the mesh key, or the storage error object when parking failed); raw reports return on synthesis failure or when one role completes and synthesis is skipped. A partial result is useful evidence with named gaps, not permission for an automatic whole-council rerun. Retry only the failed role or synthesis when needed. Do not use a council for a lookup.
@@ -113,20 +113,29 @@ if (completed.length === 0) {
113
113
  }
114
114
  // Park completed reports in mesh before synthesis: an audit trail that survives this
115
115
  // program, and full-text recovery when synthesis fails or a budget runs out.
116
- const reportsKey = `council/${new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-")}/reports`;
117
- let reports: string | { error: string } = reportsKey;
118
- try {
119
- await mesh.put({
120
- key: reportsKey,
121
- value: completed.map((outcome) => ({
122
- role: outcome.role,
123
- ...(outcome.model ? { model: outcome.model } : {}),
124
- report: outcome.report,
125
- })),
126
- });
127
- } catch (error) {
128
- reports = { error: error instanceof Error ? error.message : String(error) };
116
+ // ifVersion: 0 makes each put create-only, so a same-second council moves to the
117
+ // next key suffix instead of overwriting an earlier run's reports.
118
+ const parked = completed.map((outcome) => ({
119
+ role: outcome.role,
120
+ ...(outcome.model ? { model: outcome.model } : {}),
121
+ report: outcome.report,
122
+ }));
123
+ let reports: string | { error: string } | null = null;
124
+ let parkError = "";
125
+ for (let attempt = 0; attempt < 4 && reports === null; attempt++) {
126
+ const suffix = attempt === 0 ? "" : `-${attempt + 1}`;
127
+ const reportsKey = `council/${new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-")}${suffix}/reports`;
128
+ try {
129
+ await mesh.put({ key: reportsKey, value: parked, ifVersion: 0 });
130
+ reports = reportsKey;
131
+ } catch (error) {
132
+ parkError = error instanceof Error ? error.message : String(error);
133
+ // Only a same-timestamp collision retries with the next suffix; any other
134
+ // storage failure surfaces immediately as the { error } object.
135
+ if (!parkError.includes("compare-and-swap")) break;
136
+ }
129
137
  }
138
+ if (reports === null) reports = { error: parkError };
130
139
  if (completed.length === 1) {
131
140
  return {
132
141
  status: "partial",
@@ -168,13 +177,13 @@ try {
168
177
  fallback: completed.map((outcome) => ({
169
178
  role: outcome.role,
170
179
  status: "completed",
171
- report: outcome.report.slice(0, 1200),
180
+ report: typeof reports === "string" ? outcome.report.slice(0, 1200) : outcome.report,
172
181
  })),
173
182
  };
174
183
  }
175
184
  ```
176
185
 
177
- Pass the task as `strings.task`, the JSON role array as `strings.roles`, and the synthesis model key as `strings.synthesis`; an empty `strings.synthesis` keeps the session default. A role is a string or `{ "role": "security", "model": "provider/id", "thinking": "high" }`, and a role without `model` runs on the session default. Model keys must match a Pi registry key from `tools.models()` exactly, ignoring case; the skill refuses a `models.aliases` name or a partial id, and checks every key before any agent runs. Every result lists `seats`, each with its role, pinned model and thinking, and status, plus `synthesisModel` when one was pinned. These are the models the skill requested; keeping a run on its pinned model is the host's job. Successful synthesis returns only the compact decision, coverage, seats, and failures. Whenever at least one seat completes, the full role reports are parked to mesh under a `council/<timestamp>/reports` key and every outcome carries it as `reports`: `mesh.get` it for audit or to retry a budget-starved synthesis with one plain agent, and `mesh.delete` it when no longer needed. On synthesis failure the fallback carries report heads plus that mesh key, so full texts never need to land in context; one surviving role returns directly without spending another agent call.
186
+ Pass the task as `strings.task`, the JSON role array as `strings.roles`, and the synthesis model key as `strings.synthesis`; an empty `strings.synthesis` keeps the session default. A role is a string or `{ "role": "security", "model": "provider/id", "thinking": "high" }`, and a role without `model` runs on the session default. Model keys must match a Pi registry key from `tools.models()` exactly, ignoring case; the skill refuses a `models.aliases` name or a partial id, and checks every key before any agent runs. Every result lists `seats`, each with its role, pinned model and thinking, and status, plus `synthesisModel` when one was pinned. These are the models the skill requested; keeping a run on its pinned model is the host's job. Successful synthesis returns the compact decision, coverage, seats, failures, and `reports` (the mesh key, or the storage error object when parking failed). Whenever at least one seat completes, the full role reports are parked to mesh under a create-only `council/<timestamp>/reports` key — a same-second collision parks under the next suffix rather than overwriting — and every outcome carries it as `reports`: check `typeof reports === "string"` first, because a failed `mesh.put` yields an `{ error }` object instead of a key — never pass that to `mesh.get` or `mesh.delete`, and the synthesis-failure fallback then carries the full untruncated reports. Otherwise `mesh.get` the key for audit or to retry a budget-starved synthesis with one plain agent, and `mesh.delete` it when no longer needed. On synthesis failure the fallback result carries report heads plus that mesh key, not the full texts; the synthesis prompt still embeds every completed report, so synthesis input grows with total report size. One surviving role returns directly without spending another agent call.
178
187
 
179
188
  Concurrent calls can overshoot an observational `tokenBudget` because usage settles afterward. Reserve at least `seats.length + 1` top-level agent calls when synthesis may run, and use a finite role set rather than relying on token accounting as a hard concurrent ceiling. A budget-exhausted synthesis loses nothing: the parked reports are complete, so re-run only the synthesis step.
180
189
 
@@ -21,7 +21,7 @@ For Pi leaf or recursive agents, selecting `cwd` neither grants nor requires pro
21
21
  - `runner` is `pi`, `claude`, or `veda` and defaults to `agents.runner` (`pi`). The `veda` runner drives the Veda CLI as a one-shot headless child; `agents.veda.backend` selects Veda’s underlying CLI (`agy`, `codex`, `claude-code`, `droid`, `pi`, or another backend registered by the installed Veda build), while `persona` selects its behavior. An explicit `agents.run({ model })` overrides `agents.veda.model`; if both are omitted, Veda selects its backend default (see `docs/agents.md`). Extensions may register more runner ids through `pi-fabric/runners`; requests needing a capability the runner does not declare fail before launch. A result with `outcome: "indeterminate"` means Fabric cannot confirm whether the work ran; it is never retried automatically, so inspect before re-running.
22
22
  - `kernel` is `"typescript"`, `"python"`, or `"inherit"`. Omitted/`inherit` takes the caller's `executor.kernel`; a concrete value lets the model or skill choose its strongest language for the **child**. It never switches the current `fabric_exec` program. Concrete values require Pi with Fabric extensions; Claude/Veda/`extensions: false` reject them, while omitted/`inherit` leaves those runners native with no `kernel` in status. Supported handles/results/status expose the resolved language. Workflow, RLM, and council requests forward `kernel` too. Python uses the caller's configured `executor.pythonRuntime` backend (`monty` by default); there is no public per-request backend selector. Monty is sandboxed and fails closed if its optional dependency is missing. CPython requires explicit configuration and outside schema enforce is trusted native code, not QuickJS isolation.
23
23
  - The caller's resolved language and configured Python backend are frozen before worker launch or durable/trajectory transfer. Recursive and alternate-cwd children inherit them through validated worker environment overrides after config merge, not the destination cwd's language defaults. Explicit kernels and inherited Python ensure Fabric is loaded even outside full-code mode. See [execution kernels](../../../../docs/kernels.md).
24
- - `transport` is one of `auto`, `process`, `tmux`, `screen`, `localterm`, `herdr` (default `process`). `auto` tries Herdr when the parent runs inside a Herdr workspace, then LocalTerm, tmux, screen, and process.
24
+ - `transport` is one of `auto`, `process`, `tmux`, `screen`, `localterm`, `herdr`, `herdr-core` (default `process`). `auto` first tries Herdr Core with injected `HC_TERMINAL_ID`/`HC_TERMINAL_SOCKET` and a reachable generation-1 service, then Herdr inside a Herdr workspace, LocalTerm, tmux, screen, and process. Explicit `herdr-core` requires the same Core context; it never starts a server. Core handles use terminal addresses and `hc attach tN`, not workspace/tab/pane IDs.
25
25
  - Pi `model` values resolve only within the execution owner's visible `tools.models()` / `agents.models({ runner: "pi" })` set; omitted uses `agents.model` or inherits the host model. Explicit values go through the `agents.switchModel` selector resolution: `models.aliases` names, exact matches, then the closest fuzzy match (pi-model-sort recency ties break toward the recently used model). Unresolved values and exhausted aliases fail before launch, and actor defaults or per-activation overrides are revalidated at their actual owner. Catalog-fresh or custom ids must first be visible in that registry. Claude values are `claude/<value>` keys from `agents.models({ runner: "claude" })`; omitted uses `agents.claude.model` or Claude Code's runtime default. Veda model strings continue to pass through to its backend unchanged. `agents.models()` defaults to the configured runner; `agents.models({ runner, model })` returns only the entries whose `key` equals `model` exactly (no alias or fuzzy resolution, `[]` when absent); Claude discovery is a local CLI control handshake and makes no model inference request.
26
26
  - `modelMatch: "exact"` (Pi runners only) selects a listed `provider/id` without aliases, closest or fuzzy matching, or alias thinking. Missing, malformed or unlisted models and non-Pi runners are refused before launch; `handoff`, `create`, and actor activations do not accept it. Admission is strict, and a child guard detects session model switches and some rewrites of known API payloads. **This is not a security guarantee or final-dispatch enforcement:** later hooks, unknown API payloads, providers and extension-made calls can route data elsewhere. Attribution may detect drift only after a call; do not rely on this mode to prevent data disclosure. See `docs/agents.md`. Omit `modelMatch` for default resolution.
27
27
  - `systemPrompt` is appended to the child's system prompt (Veda gets it as a `<system_instructions>` block); blank is ignored and durable `spawn` refuses it.
@@ -71,7 +71,7 @@ Lifecycle subscriptions are durable, source-qualified mesh routes. They let Main
71
71
  - `agents.subscribe({ from, events, to?, delivery, triggerTurn, once? })` creates a subscription. `from` is an exact participant id; `"main"` means the caller's lineage root. `to` defaults to that Main id.
72
72
  - `agents.subscriptions({ from?, to? })` lists project subscriptions.
73
73
  - `agents.unsubscribe({ id })` removes one.
74
- - `delivery` is `steer` or `followUp`. State `triggerTurn: true | false` explicitly; it controls whether delivery to an idle Main starts a turn.
74
+ - `delivery` is `steer` or `followUp`. Incoming Main feedback normalizes both to hidden steering (with a bounded sender notification); one-shot and actor target controls keep their existing semantics. State `triggerTurn: true | false` explicitly; false never starts idle Main. Actor output also uses hidden steering for legacy follow-up policies; `mailbox` and `nextTurn` remain intentional deferral choices.
75
75
  - `once: true` removes the subscription after its first successful matching delivery. Omitted keeps it active.
76
76
  - Creation starts at the current mesh sequence, so old lifecycle events are not replayed. Delivery cursors persist across owner restarts. Delivery is at-least-once across a crash between message insertion and cursor persistence; use the lifecycle event `id` to deduplicate side effects.
77
77
 
@@ -142,7 +142,7 @@ Every live root, one-shot/recursive agent, and persistent actor is represented i
142
142
  - `agents.peers()` remains the compatibility view of other live roots as `Peer <session-prefix>`. It is derived from `agents.members`, not maintained by a second registry.
143
143
  - A `<fabric-peers>` message in the transcript is a host notice, not a user request: it lists the other root sessions sharing this project's files by label and participant id, and is sent only when that set changes. Treat file or git changes you did not make as possibly theirs, and pass a listed id to `agents.steer` to coordinate.
144
144
  - `agents.status({ id })` accepts any known participant id. Local runs/actors return full local detail; remote participants return their bounded directory summary.
145
- - `agents.steer({ id, message, data? })` and `agents.followUp(...)` target Main, a live one-shot child, or an actor without discarding context.
145
+ - `agents.steer({ id, message, data? })` and `agents.followUp(...)` target Main, a live one-shot child, or an actor without discarding context. Incoming Main feedback always uses hidden steering, including when the sender requested `followUp`; the full message and structured data remain in context and audit, while UI notifications contain only a bounded sender/text preview. One-shot and actor mailbox controls retain their chosen operation.
146
146
  - `agents.stop({ id })` can stop a local or remotely owned agent/actor when its participant advertises `"stop"`. It returns the local agent result, local actor info, or an acknowledged remote control result according to the target.
147
147
  - Provider-registered work appears as `kind: "provider"` members with ids `provider:<provider>:<id>`. `agents.stop`, `agents.steer`, and `agents.followUp` accept those ids and call the provider; stop returns `{ ref, outcome: "confirmed" | "unconfirmed", detail? }`. Cancelling or timing out a program stops the non-detached provider work it started.
148
148
  - `agents.setSteeringMode({ id, mode })` / `agents.setFollowUpMode({ id, mode })` remain local one-shot controls.
@@ -155,7 +155,7 @@ const main = await agents.main();
155
155
  const project = await agents.members({ scope: "project" });
156
156
  const peerRoot = project.find((participant) => participant.kind === "root" && participant.id !== main.id);
157
157
  if (peerRoot) await agents.steer({ id: peerRoot.id, message: "Coordinate on the shared migration." });
158
- await agents.followUp({ id: main.id, message: "After the audit, reconcile the worker findings." });
158
+ await agents.steer({ id: main.id, message: "Reconcile the worker findings." });
159
159
  const handle = await agents.spawn({ task: "Audit auth flows.", tools: ["read", "grep", "find", "ls"] });
160
160
  // Watch progress, then redirect between turns without losing the child's context.
161
161
  const s = await agents.status({ id: handle.id });
@@ -190,7 +190,7 @@ call override → session binding → project default → Fabric or runner defau
190
190
  - `topics` lists durable mesh topics to subscribe to (see `mesh.md`).
191
191
  - `responseMode` is `text` (every non-empty response becomes an outbox message) or `directive` (validated `{ action, message?, data? }` where `action` is `silent`, `message`, or `stop`; the actor decides whether to intervene).
192
192
  - `delivery` is `mailbox`, `steer`, `followUp`, or `nextTurn`. An actor cannot escalate it in a response; the owner can replace it with `agents.setDeliveryPolicy({ id, delivery, triggerTurn, scope? })`.
193
- - `triggerTurn` is mandatory for `steer`/`followUp`: `true` starts Main when idle; `false` is passive and the delivered message visibly says it will not start Main. `mailbox`/`nextTurn` never start Main. `coalesce` is on by default.
193
+ - `triggerTurn` is mandatory for `steer`/`followUp`: `true` starts Main when idle; `false` is passive and the hidden context message says it will not start Main. The UI receives only a bounded sender notification, not a chat bubble. `mailbox`/`nextTurn` never start Main. `coalesce` is on by default.
194
194
  - `validWhile` is an optional pure synchronous predicate checked before an activation runs and again before its result is delivered. It receives immutable `{ activation, current }` facts. Return `false` or `{ valid: false, reason? }` to record the activation as stale and suppress delivery; an invalidated blocking `agents.ask()` rejects. The predicate source persists with project actors and global templates, so it cannot use closures, tools, promises, or host APIs.
195
195
  - `timeoutMs` follows the same floor as one-shot agents: omit it normally and set it only above `agents.timeoutMs` when an activation needs longer.
196
196
  - `tools` is the actor's persisted allowlist and defaults to `agents.defaultTools`. Replace it for future activations with `agents.setTools({ id, tools })`; an empty list disables optional tools. Pi actors retain the host-required `fabric_exec` tool unless created with `extensions: false`. Use `scope: "global"` to update a reusable template instead.