@e4779/pi-fabric 0.105.0-fork.22 → 0.109.2-fork.23

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 (225) hide show
  1. package/README.md +3 -1
  2. package/dist/actors/global-registry.d.ts.map +1 -1
  3. package/dist/agents/manager.d.ts.map +1 -1
  4. package/dist/agents/result.d.ts.map +1 -1
  5. package/dist/agents/result.js +1 -1
  6. package/dist/agents/runner-registry.d.ts +1 -1
  7. package/dist/agents/runner-registry.d.ts.map +1 -1
  8. package/dist/agents.js +5 -5
  9. package/dist/chunks/{chunk-5MNLVHF5.js → chunk-3DUKKQHN.js} +28 -13
  10. package/dist/chunks/chunk-3DUKKQHN.js.map +7 -0
  11. package/dist/chunks/{chunk-GJVPP3NN.js → chunk-3SHUUBZJ.js} +4 -4
  12. package/dist/chunks/chunk-3SHUUBZJ.js.map +7 -0
  13. package/dist/chunks/{chunk-VON4TSO3.js → chunk-CZPQTISQ.js} +27 -2
  14. package/dist/chunks/chunk-CZPQTISQ.js.map +7 -0
  15. package/dist/chunks/{chunk-WLLXKS6I.js → chunk-DU6ZA44F.js} +4 -4
  16. package/dist/chunks/{chunk-QLFDPXK7.js → chunk-DV2JZSCI.js} +153 -27
  17. package/dist/chunks/chunk-DV2JZSCI.js.map +7 -0
  18. package/dist/chunks/{chunk-KQ6R5EWR.js → chunk-FRPNQZV2.js} +24 -22
  19. package/dist/chunks/chunk-FRPNQZV2.js.map +7 -0
  20. package/dist/chunks/{chunk-W7X4XEQU.js → chunk-GC2AUXG6.js} +2 -2
  21. package/dist/chunks/chunk-K6QXUGS5.js +30 -0
  22. package/dist/chunks/chunk-K6QXUGS5.js.map +7 -0
  23. package/dist/chunks/{chunk-VPRJOD4Y.js → chunk-LEDY5G2V.js} +2 -2
  24. package/dist/chunks/{chunk-OVBKQCYL.js → chunk-N2VKKA7O.js} +2 -2
  25. package/dist/chunks/{chunk-N5GUXC6F.js → chunk-P4KH4S4S.js} +2 -1
  26. package/dist/chunks/chunk-P4KH4S4S.js.map +7 -0
  27. package/dist/chunks/{chunk-TFFZVLR2.js → chunk-PF27MQY5.js} +55 -4
  28. package/dist/chunks/chunk-PF27MQY5.js.map +7 -0
  29. package/dist/chunks/{chunk-CGL7QP4A.js → chunk-PK4NIJEV.js} +10 -1
  30. package/dist/chunks/{chunk-CGL7QP4A.js.map → chunk-PK4NIJEV.js.map} +2 -2
  31. package/dist/chunks/{chunk-YRDCJZZW.js → chunk-RUO6L7RM.js} +1 -1
  32. package/dist/chunks/{chunk-YRDCJZZW.js.map → chunk-RUO6L7RM.js.map} +1 -1
  33. package/dist/chunks/{chunk-4RTHQGES.js → chunk-ST36EYHN.js} +4 -4
  34. package/dist/chunks/chunk-ST36EYHN.js.map +7 -0
  35. package/dist/chunks/{chunk-R5F6CHW2.js → chunk-UXEMIWYI.js} +12 -7
  36. package/dist/chunks/chunk-UXEMIWYI.js.map +7 -0
  37. package/dist/chunks/{chunk-SGFH5PYA.js → chunk-V2SKDVQX.js} +10 -9
  38. package/dist/chunks/chunk-V2SKDVQX.js.map +7 -0
  39. package/dist/chunks/{chunk-KYXZJNV6.js → chunk-VTK2FEH7.js} +3 -1
  40. package/dist/chunks/{chunk-KYXZJNV6.js.map → chunk-VTK2FEH7.js.map} +2 -2
  41. package/dist/chunks/{chunk-3QECYQGA.js → chunk-VYQV5JRT.js} +13 -1
  42. package/dist/chunks/chunk-VYQV5JRT.js.map +7 -0
  43. package/dist/chunks/{chunk-3KDUMDPZ.js → chunk-X3CHSIL2.js} +5 -5
  44. package/dist/chunks/{chunk-EXWS4ZS3.js → chunk-YJX27XBO.js} +100 -22
  45. package/dist/chunks/chunk-YJX27XBO.js.map +7 -0
  46. package/dist/components/configuration.js +2 -2
  47. package/dist/config.d.ts +16 -1
  48. package/dist/config.d.ts.map +1 -1
  49. package/dist/core/action-registry.d.ts +1 -1
  50. package/dist/core/action-registry.d.ts.map +1 -1
  51. package/dist/core/action-registry.js +2 -2
  52. package/dist/core/media-sanitize.d.ts.map +1 -1
  53. package/dist/core/native-tool-names.d.ts +9 -0
  54. package/dist/core/native-tool-names.d.ts.map +1 -0
  55. package/dist/core/native-tool-result.d.ts +11 -0
  56. package/dist/core/native-tool-result.d.ts.map +1 -0
  57. package/dist/core/system-guidance.d.ts +3 -3
  58. package/dist/core/system-guidance.d.ts.map +1 -1
  59. package/dist/durable/agent.d.ts +77 -0
  60. package/dist/durable/agent.d.ts.map +1 -0
  61. package/dist/durable/session.d.ts +19 -0
  62. package/dist/durable/session.d.ts.map +1 -0
  63. package/dist/durable/storage.d.ts +7 -0
  64. package/dist/durable/storage.d.ts.map +1 -0
  65. package/dist/durable/worker-host.d.ts +13 -0
  66. package/dist/durable/worker-host.d.ts.map +1 -0
  67. package/dist/durable/worker-host.js +1149 -0
  68. package/dist/durable/worker-host.js.map +7 -0
  69. package/dist/durable/worker-options.d.ts +17 -0
  70. package/dist/durable/worker-options.d.ts.map +1 -0
  71. package/dist/durable/worker.d.ts +3 -0
  72. package/dist/durable/worker.d.ts.map +1 -0
  73. package/dist/durable/worker.js +110 -0
  74. package/dist/durable/worker.js.map +7 -0
  75. package/dist/durable-controls.d.ts +27 -0
  76. package/dist/durable-controls.d.ts.map +1 -0
  77. package/dist/durable-input.d.ts +13 -0
  78. package/dist/durable-input.d.ts.map +1 -0
  79. package/dist/durable.d.ts +6 -0
  80. package/dist/durable.d.ts.map +1 -1
  81. package/dist/durable.js +194 -24
  82. package/dist/durable.js.map +4 -4
  83. package/dist/execution-service.d.ts +4 -0
  84. package/dist/execution-service.d.ts.map +1 -1
  85. package/dist/extension-bootstrap.js +5 -5
  86. package/dist/extension.d.ts.map +1 -1
  87. package/dist/fabric-exec-arguments.d.ts.map +1 -1
  88. package/dist/fabric-exec-tool.d.ts.map +1 -1
  89. package/dist/fabric-runtime-state.d.ts.map +1 -1
  90. package/dist/fabric-runtime-state.js +604 -284
  91. package/dist/fabric-runtime-state.js.map +4 -4
  92. package/dist/index.js +5 -5
  93. package/dist/jev/observation.js +2 -2
  94. package/dist/jev.js +3 -3
  95. package/dist/mcp.js +1 -1
  96. package/dist/memory/extractive-history.d.ts +29 -0
  97. package/dist/memory/extractive-history.d.ts.map +1 -0
  98. package/dist/memory/extractive-history.js +340 -0
  99. package/dist/memory/extractive-history.js.map +7 -0
  100. package/dist/memory/extractive-index.d.ts +46 -0
  101. package/dist/memory/extractive-index.d.ts.map +1 -0
  102. package/dist/native-codemode.d.ts +34 -0
  103. package/dist/native-codemode.d.ts.map +1 -0
  104. package/dist/native-discovery.d.ts +16 -0
  105. package/dist/native-discovery.d.ts.map +1 -0
  106. package/dist/native-discovery.js +19 -0
  107. package/dist/native-discovery.js.map +7 -0
  108. package/dist/native-image-artifacts.d.ts +4 -0
  109. package/dist/native-image-artifacts.d.ts.map +1 -0
  110. package/dist/native-image-artifacts.js +18 -0
  111. package/dist/native-image-artifacts.js.map +7 -0
  112. package/dist/native-tool-catalog.d.ts +21 -0
  113. package/dist/native-tool-catalog.d.ts.map +1 -0
  114. package/dist/native-tool-catalog.js +71 -0
  115. package/dist/native-tool-catalog.js.map +7 -0
  116. package/dist/protocol.d.ts +2 -0
  117. package/dist/protocol.d.ts.map +1 -1
  118. package/dist/protocol.js +1 -1
  119. package/dist/providers/agents-provider.d.ts.map +1 -1
  120. package/dist/providers/captured-tools-provider.d.ts +1 -1
  121. package/dist/providers/captured-tools-provider.d.ts.map +1 -1
  122. package/dist/providers/jev-provider.js +3 -3
  123. package/dist/providers/mcp-provider.d.ts +1 -1
  124. package/dist/providers/mcp-provider.d.ts.map +1 -1
  125. package/dist/providers/pi-native-mcp.d.ts.map +1 -1
  126. package/dist/providers/pi-tools-provider.d.ts.map +1 -1
  127. package/dist/residency/host.js +7 -7
  128. package/dist/residency/pi-entry.js +7 -7
  129. package/dist/runners.js +1 -1
  130. package/dist/runtime/core-override-guest-types.js +2 -2
  131. package/dist/runtime/dynamic-guest-types.d.ts +2 -0
  132. package/dist/runtime/dynamic-guest-types.d.ts.map +1 -1
  133. package/dist/runtime/dynamic-guest-types.js +5 -3
  134. package/dist/runtime/guest-types.d.ts +1 -1
  135. package/dist/runtime/guest-types.d.ts.map +1 -1
  136. package/dist/runtime/guest-types.js +1 -1
  137. package/dist/runtime/kernel.d.ts +5 -0
  138. package/dist/runtime/kernel.d.ts.map +1 -1
  139. package/dist/runtime/monty-runtime.js +1 -1
  140. package/dist/runtime/native-codemode-guest.d.ts +2 -0
  141. package/dist/runtime/native-codemode-guest.d.ts.map +1 -0
  142. package/dist/runtime/native-codemode-types.d.ts +2 -0
  143. package/dist/runtime/native-codemode-types.d.ts.map +1 -0
  144. package/dist/runtime/node-process-child-source.d.ts.map +1 -1
  145. package/dist/runtime/node-process-runtime.d.ts.map +1 -1
  146. package/dist/runtime/node-process-runtime.js +3 -3
  147. package/dist/runtime/quickjs-runtime.d.ts +1 -1
  148. package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
  149. package/dist/runtime/quickjs-runtime.js +3 -2
  150. package/dist/runtime/type-checker.d.ts +2 -0
  151. package/dist/runtime/type-checker.d.ts.map +1 -1
  152. package/dist/runtime/type-checker.js +5 -3
  153. package/dist/runtime/typescript-kernel.d.ts +1 -1
  154. package/dist/runtime/typescript-kernel.d.ts.map +1 -1
  155. package/dist/runtime/typescript-kernel.js +13 -11
  156. package/dist/runtime/typescript-kernel.js.map +2 -2
  157. package/dist/runtime-state-speculation.d.ts +4 -1
  158. package/dist/runtime-state-speculation.d.ts.map +1 -1
  159. package/dist/speculation/python-scanner.js +1 -1
  160. package/dist/speculation/python-scanner.js.map +2 -2
  161. package/dist/speculation/scanner.d.ts +2 -0
  162. package/dist/speculation/scanner.d.ts.map +1 -1
  163. package/dist/speculation/scanner.js +18 -4
  164. package/dist/speculation/scanner.js.map +2 -2
  165. package/dist/speculation/types.d.ts +1 -0
  166. package/dist/speculation/types.d.ts.map +1 -1
  167. package/dist/type-error-guidance.js +1 -1
  168. package/dist/ui/border-status-editor.d.ts +3 -0
  169. package/dist/ui/border-status-editor.d.ts.map +1 -1
  170. package/dist/ui/controller.d.ts.map +1 -1
  171. package/dist/ui/conversation.d.ts +1 -0
  172. package/dist/ui/conversation.d.ts.map +1 -1
  173. package/dist/ui/conversation.js +28 -5
  174. package/dist/ui/conversation.js.map +2 -2
  175. package/dist/ui/dashboard.d.ts +2 -0
  176. package/dist/ui/dashboard.d.ts.map +1 -1
  177. package/dist/ui/dashboard.js +20 -7
  178. package/dist/ui/dashboard.js.map +2 -2
  179. package/dist/ui/settings-section-context.d.ts +2 -0
  180. package/dist/ui/settings-section-context.d.ts.map +1 -1
  181. package/dist/ui/settings-sections-execution.d.ts.map +1 -1
  182. package/dist/ui/settings-sections-lifecycle.d.ts +1 -0
  183. package/dist/ui/settings-sections-lifecycle.d.ts.map +1 -1
  184. package/dist/ui/settings-sections.d.ts +2 -0
  185. package/dist/ui/settings-sections.d.ts.map +1 -1
  186. package/dist/ui/settings-values.d.ts +4 -1
  187. package/dist/ui/settings-values.d.ts.map +1 -1
  188. package/dist/ui/settings.d.ts.map +1 -1
  189. package/dist/ui/settings.js +61 -2
  190. package/dist/ui/settings.js.map +2 -2
  191. package/dist/worker/model-control.d.ts.map +1 -1
  192. package/dist/worker/model-control.js.map +2 -2
  193. package/dist/worker/options.d.ts.map +1 -1
  194. package/dist/worker/options.js +4 -3
  195. package/dist/worker/options.js.map +2 -2
  196. package/dist/worker/result.js +12 -0
  197. package/dist/worker/result.js.map +2 -2
  198. package/dist/worker.js +95 -8
  199. package/dist/worker.js.map +2 -2
  200. package/docs/agents.md +5 -5
  201. package/docs/codemode-parity.md +97 -0
  202. package/docs/configuration.md +31 -2
  203. package/docs/durable-pi.md +166 -38
  204. package/docs/extractive-history.md +171 -0
  205. package/docs/interface.md +1 -1
  206. package/docs/speculation.md +12 -3
  207. package/package.json +7 -16
  208. package/skillsets/typescript/fabric-exec/SKILL.md +4 -4
  209. package/dist/chunks/chunk-3QECYQGA.js.map +0 -7
  210. package/dist/chunks/chunk-4RTHQGES.js.map +0 -7
  211. package/dist/chunks/chunk-5MNLVHF5.js.map +0 -7
  212. package/dist/chunks/chunk-EXWS4ZS3.js.map +0 -7
  213. package/dist/chunks/chunk-GJVPP3NN.js.map +0 -7
  214. package/dist/chunks/chunk-KQ6R5EWR.js.map +0 -7
  215. package/dist/chunks/chunk-N5GUXC6F.js.map +0 -7
  216. package/dist/chunks/chunk-QLFDPXK7.js.map +0 -7
  217. package/dist/chunks/chunk-R5F6CHW2.js.map +0 -7
  218. package/dist/chunks/chunk-SGFH5PYA.js.map +0 -7
  219. package/dist/chunks/chunk-TFFZVLR2.js.map +0 -7
  220. package/dist/chunks/chunk-VON4TSO3.js.map +0 -7
  221. /package/dist/chunks/{chunk-WLLXKS6I.js.map → chunk-DU6ZA44F.js.map} +0 -0
  222. /package/dist/chunks/{chunk-W7X4XEQU.js.map → chunk-GC2AUXG6.js.map} +0 -0
  223. /package/dist/chunks/{chunk-VPRJOD4Y.js.map → chunk-LEDY5G2V.js.map} +0 -0
  224. /package/dist/chunks/{chunk-OVBKQCYL.js.map → chunk-N2VKKA7O.js.map} +0 -0
  225. /package/dist/chunks/{chunk-3KDUMDPZ.js.map → chunk-X3CHSIL2.js.map} +0 -0
@@ -0,0 +1,97 @@
1
+ # Native Pi codemode compatibility
2
+
3
+ Fabric supports two script API profiles in the TypeScript kernel. Both run in the configured QuickJS or trusted Node/Bun executor, through the same registry, approvals, Schema authorizers, host scopes, capability views, middleware, audits and cancellation. Neither nests Pi's `codemode` tool or enables another top-level execution path.
4
+
5
+ ## Profiles
6
+
7
+ `executor.codemodeProfile` defaults to `"additive"`. Set it to `"native"` in `~/.pi/agent/fabric.json` or a trusted project's `.pi/fabric.json`, or use `/fabric settings` → **Executor** → **Codemode API (TS)**:
8
+
9
+ ```json
10
+ { "executor": { "codemodeProfile": "native" } }
11
+ ```
12
+
13
+ | Surface | Additive (default) | Native (opt-in) |
14
+ | --- | --- | --- |
15
+ | `tools.<name>(args)` | Existing Fabric discovery members win; other registered names call native tools | Native tool calls, including tools named `search`, `list`, `call`, or `models` |
16
+ | `nativeTools.<name>(args)` | Unambiguous native tool view | Same native view as `tools` |
17
+ | `fabric.tools` | Existing Fabric discovery/generic API | Existing Fabric discovery/generic API |
18
+ | `pi.*`, `mcp.*`, `extensions.*` | Existing Fabric semantics | Existing Fabric semantics |
19
+ | `searchTools`, `describeTool`, `describeNamespace`, `ALL_TOOLS` | Existing Fabric-qualified compatibility discovery | Native callable identifiers and native discovery shapes |
20
+ | `nativeDiscovery` | Native discovery without changing existing globals | Same native discovery |
21
+ | Source | Checked/repaired TypeScript | Unmodified JavaScript async function body, without TypeScript checking or repair |
22
+ | `store` / `load` | Fabric's branch-local snapshot entries | Pi's branch-local `codemode-store` delta entries |
23
+
24
+ Top-level `await` and `return` work in both profiles. The native profile is for unchanged Pi script examples. It does not change the `fabric_exec` JSON input format, outer result rendering, resource limits or security policy. Python ignores this setting; its kernel and API remain unchanged.
25
+
26
+ ### Tool names and results
27
+
28
+ ```ts
29
+ // Works in both profiles:
30
+ const result = await tools.bash({ command: "git status --short" });
31
+ return result.output;
32
+ ```
33
+
34
+ Native calls use Pi identifiers: `tools.read`, `tools.write`, `tools.mcp__server__tool`, and sanitized registered extension names. Real Pi registration names (including hashed MCP identifiers) are authoritative. `nativeDiscovery.ALL_TOOLS` enumerates the visible names. Sanitization collisions fail explicitly; they never select an arbitrary tool. Recursive `codemode` / `fabric_exec` calls are excluded.
35
+
36
+ Native results are projected from the final middleware-filtered tool result:
37
+
38
+ - A tool with an output schema returns its `structuredContent`, including schema-backed error results. Native `bash` returns `{output, truncated, full_output_path?, exit_code, wall_time_seconds}`; a nonzero process exit is a result, not an exception.
39
+ - MCP returns its `CallToolResult`, retaining `content`, `structuredContent`, `isError` and metadata. Check `isError`; `Promise.allSettled` alone does not detect these tool errors.
40
+ - Tools without structured output return text. Native image reads return Pi's image block; call `image(block)` to display it.
41
+ - Blocked, invalid or unstructured failed calls reject. Content-only middleware redaction never restores the original structured payload.
42
+
43
+ These are **not aliases of the normalized Fabric results**. `pi.bash` still rejects nonzero exits unless `settle:true`, `pi.edit/write` still return Fabric envelopes, `extensions.*` still returns its captured envelope, and `mcp.*` still normalizes results and throws on MCP errors. Native foreground shell calls do not auto-detach at `executor.shellHangMs`; explicit Fabric background operations retain their existing contract.
44
+
45
+ ### Discovery and collisions
46
+
47
+ ```ts
48
+ // Safe under either profile, even with a native tool named "search":
49
+ const native = await nativeDiscovery.searchTools("issues", { limit: 5 });
50
+ const fabric = await globalThis.fabric.tools.search({ query: "issues" });
51
+ return { native, fabric };
52
+ ```
53
+
54
+ Native `searchTools` returns `{name,description}[]`, with callable identifiers and advisory declarations. `describeTool(name)` returns a declaration/description **string** or `undefined`. `describeNamespace(name)` returns `{name,description?,instructions?,tools:string[]}` or `undefined`. `ALL_TOOLS` uses those same native identifiers. Search uses BM25; declarations are bounded and dispatch schemas remain authoritative. Actual namespace instructions are exposed only for visible tools.
55
+
56
+ The additive globals retain their existing shapes: Fabric-qualified refs, object-valued `describeTool`, and object-valued namespace tool entries. Use `nativeDiscovery` for native shapes in additive mode. In native mode use `fabric.tools.search/describe/list/call` for Fabric discovery. A single property cannot simultaneously be Fabric's `tools.search` and a registered tool named `search`.
57
+
58
+ Fabric's catalog page remains bounded to 1000 actions. Host-registered callable tools beyond that page are resolved individually, so native registrations remain discoverable. For larger Fabric-owned provider catalogs, use provider-specific discovery and exact Fabric refs.
59
+
60
+ ## Models
61
+
62
+ `models === fabric.tools.models` in both profiles; in additive mode `models === tools.models` too. Calling `fabric.tools.models()` returns Fabric's legacy authenticated chat catalog. The model namespace exposes:
63
+
64
+ - `getModelsOfType(type, provider?)`
65
+ - `getAvailableOfType(type, provider?)`
66
+ - `getModelOfType(type, provider, id)`
67
+ - `classify({provider, id}, {state, questions})`
68
+ - `generateImages({provider, id}, {input})`
69
+
70
+ Types are `chat`, `classifier`, and `image`; chat execution is not exposed. Classifiers accept native `choice`, `score`, and `bool` questions; bool answers contain `probability`. Full catalog entries work as selectors. Registry lookups resolve the authoritative model; guest configuration, headers and credentials are never used. Authentication and cancellation use public host registry APIs. At most four classifier/image calls run concurrently per invocation, including mixed calls; waiting calls cancel with the script.
71
+
72
+ These remain registered `native.*` actions. Scoped hosts require `native:models` read/execute or `native:store` read/write grants as appropriate; pinned views must include the required actions. Native `stopReason` and `errorMessage` are retained, and reported usage is included even on provider errors. Direct `jev.evaluate` accounting is unchanged. Classifier strings are capped at 262144 characters, question/criteria/input collections at 1000, and serialized model requests/responses at 16777216 characters. Provider limits may be lower. Missing registry APIs produce explicit compatibility errors.
73
+
74
+ ## Branch-local script store
75
+
76
+ `store(key,value)` / `load(key)` are synchronous JSON helpers. `store(key,undefined)` deletes. Loads return detached values. One serialized value is limited to **262144 characters**, all values to **1048576**. This is not mesh state.
77
+
78
+ Additive mode reads/writes `fabric-codemode-store` snapshots. Native mode explicitly opts into Pi's `codemode-store` `{set,delete}` entries on the selected branch. The two stores are not silently merged. Switching profiles switches which store is visible. Native scripts and native Pi codemode can exchange state through these delta entries.
79
+
80
+ Initialization and staging pass through authorized `native.load` and `native.store`. Failed, aborted and timed-out scripts do not commit; additive type errors do not commit either. Malformed historical entries are ignored. Commit checks the captured session, leaf and runtime generation. Any intervening navigation or concurrent leaf change rejects the transaction; retry a stale writer explicitly. This conservative protection is stronger than bare Pi's store behavior. Standalone execution services must mount `nativeCodemode.setPersistence((type,data) => pi.appendEntry(type,data))` for state helpers.
81
+
82
+ ## Output and options
83
+
84
+ - `text(value)` emits strings directly, other values as JSON.
85
+ - `image(value)` accepts PNG/JPEG/GIF/WebP blocks, local base64 data URLs and `{image_url:string|{url}}`. It never fetches remote URLs. Explicit images are emitted as multimodal content and saved to host-owned temporary files; output reports their paths. A remote execution environment does not necessarily share that filesystem.
86
+ - `exit()` succeeds with prior output and staged state. As a thrown control signal it can be intercepted by a guest catch block.
87
+ - `console.log/info/warn/error/debug` and `print` remain available.
88
+
89
+ Partial output and explicit images survive errors and deadlines. Pending host calls cancel when the script ends; detached tasks retain their ownership contract. Explicit output is capped at 100000 emissions and 16777216 characters, in addition to Fabric output limits.
90
+
91
+ `maxOutputTokens` / `max_output_tokens` estimate four characters per token and are capped by `executor.maxOutputChars`. `timeout_ms` is a hard positive-integer deadline capped by `executor.maxTimeoutMs`; it can lower the configured deadline and cannot be extended or paused. `timeoutMs` retains its raises-only behavior. The hard deadline wins when both are supplied. A leading `// @options: {"max_output_tokens":2000,"timeout_ms":60000}` works; unsupported, invalid or conflicting options fail explicitly.
92
+
93
+ ## sPTC
94
+
95
+ Both profiles support speculative PTC on eligible isolated runtimes. Literal `tools.read(...)` and `nativeTools.read(...)` map to the same canonical `pi.read` authorization identity, but the native result projection is part of the speculative binding token. A native result can never answer a Fabric-view call or vice versa. Known Pi MCP aliases resolve through registration metadata, not guessed name splitting; unresolved aliases conservatively skip warming and execute normally.
96
+
97
+ Native reads retain all existing live approval/Schema gates, descriptor checks, mutation epochs, file freshness, cancellation, take-once consumption and side-channel replay. Alias use or mutation taints a native facade for the stream. Changing profiles through configuration resets stream/cache state. Node/Bun remain non-speculative, and Python speculation is unchanged. See [speculation](speculation.md).
@@ -32,6 +32,10 @@ Treat `node-process` and `bun-process` as an explicit escape hatch for trusted c
32
32
 
33
33
  Monty is always sandboxed, including under schema enforce, and does not require an installed CPython interpreter. Full CPython is an explicit trusted-native escape hatch with full local-user OS privileges outside schema enforce. Host approvals and audit cover bridge calls, not direct Python OS access. **Schema enforce preserves Python**; explicit CPython requires macOS `sandbox-exec` or Linux `bwrap` isolation; execution fails closed when isolation is unavailable, without falling back to unrestricted Python or TypeScript. `executor.memoryLimitBytes` uses `RLIMIT_AS` where the OS supports it, with a configuration ceiling of detected physical memory, not WASM32. This is an address-space limit, not a portable hard resident-memory cap. Process limits, timeouts, and cancellation are not a security sandbox; see [kernel isolation](kernels.md#isolation-and-resource-limits).
34
34
 
35
+ ### Native Pi codemode API
36
+
37
+ `executor.codemodeProfile` is `"additive"` by default: existing Fabric APIs stay unchanged, while `nativeTools` and nonconflicting `tools.<name>` methods provide native Pi tool results. Set `"native"` for unmodified Pi JavaScript examples: `tools` and the discovery globals use native semantics, while `fabric.tools` retains Fabric discovery. Both profiles preserve `pi.*`, `mcp.*`, `extensions.*`, approvals and sPTC safety. The setting is TypeScript-kernel-only; Python ignores it. See [native codemode compatibility](codemode-parity.md) for collisions, result contracts, images and state interoperability. The UI setting is **Executor → Codemode API (TS)**.
38
+
35
39
  ### Executor timeouts and ceilings
36
40
 
37
41
  `executor.timeoutMs` (default `120000`) bounds a whole `fabric_exec` program. Two mechanisms can raise it:
@@ -156,7 +160,7 @@ where absent values do not participate, and time spent inside a `humanWaitRefs`
156
160
  },
157
161
  "agents": {
158
162
  "enabled": true,
159
- "runner": "pi",
163
+ "runner": "pi-durable",
160
164
  "transport": "process",
161
165
  "claude": {
162
166
  "binary": "claude"
@@ -524,7 +528,7 @@ Reader checkpoints are lossless live state: they are **never pressure-evicted**.
524
528
 
525
529
  ## Agents
526
530
 
527
- `agents.runner` selects the default harness: `"pi"`, `"claude"`, `"veda"`, or the id of a runner registered through `pi-fabric/runners` ([custom runners](agents.md#custom-runners)). A well-formed id that no extension registers is kept, and launches fail closed until the runner is registered. Before the first turn of each session, Fabric warns once when the configured runner is still unregistered, suggests a close built-in or registered id for likely typos, and lists the registered runners. Malformed ids fall back to `"pi"`. `agents.model` is the optional Pi `provider/id` override. `agents.claude.model` is the optional canonical Claude runtime key. `agents.claude.binary` defaults to `claude`. You can supply an absolute path or a wrapper. `PI_FABRIC_CLAUDE_BINARY` overrides it for the current process. `/fabric settings` enumerates Claude models from that binary in the background and stores the two runner defaults independently. `agents.modelAdmission` defaults to `strict`: a Pi child run fails when the model it reports after selection differs from the requested key. Set it to `permissive` when a virtual provider key (for example a `pi-multiprovider` entry) resolves to a concrete backend at stream time; Fabric then records the reported attribution and continues, including when a later assistant frame names that backend. Permissive admission still fails a child that reports no model or starts work before admission.
531
+ `agents.runner` selects the default harness: `"pi-durable"` (default, [isolated durable Pi host](durable-pi.md)), `"pi"` (legacy Pi CLI), `"claude"`, `"veda"`, or the id of a runner registered through `pi-fabric/runners` ([custom runners](agents.md#custom-runners)). A well-formed id that no extension registers is kept, and launches fail closed until the runner is registered. Before the first turn of each session, Fabric warns once when the configured runner is still unregistered, suggests a close built-in or registered id for likely typos, and lists the registered runners. Malformed ids fall back to `"pi-durable"`. Explicit existing runner settings are preserved. `agents.model` is the optional Pi `provider/id` override. `agents.claude.model` is the optional canonical Claude runtime key. `agents.claude.binary` defaults to `claude`. You can supply an absolute path or a wrapper. `PI_FABRIC_CLAUDE_BINARY` overrides it for the current process. `/fabric settings` enumerates Claude models from that binary in the background and stores the two runner defaults independently. `agents.modelAdmission` defaults to `strict`: a Pi child run fails when the model it reports after selection differs from the requested key. Set it to `permissive` when a virtual provider key (for example a `pi-multiprovider` entry) resolves to a concrete backend at stream time; Fabric then records the reported attribution and continues, including when a later assistant frame names that backend. Permissive admission still fails a child that reports no model or starts work before admission.
528
532
 
529
533
  The `veda` runner drives the [Veda CLI](https://github.com/kennyfrc/veda) as the child harness. `agents.veda.binary` defaults to `veda`. An absolute path or wrapper works, and `PI_FABRIC_VEDA_BINARY` overrides it for the current process. `agents.veda.backend` selects which backend Veda wraps: `agy` (Antigravity CLI, the default), `codex`, `claude-code`, `droid`, `pi`, or another backend registered by the installed Veda build. Fabric passes this value through unchanged and never hardcodes AGY. `agents.veda.model` is an optional backend-specific model or Veda alias. When you omit it, Veda selects its own backend default. `agents.veda.persona` picks the global Veda persona: `navigator-plan`, `navigator-chat` (default), `reviewer`, `worker`, or a custom persona under `~/.config/veda/personas/<name>/AGENTS.md`. Per-run selection overrides it through `agents.run({ persona })`. You can also edit the Veda backend, persona, and model in the Fabric settings panel under Agents. Each child runs one headless `veda --json` prompt with an isolated `fabric-<run-id>` session, so parallel children never share Veda selection or conversation state. Veda sessions lack persistence, and steering is unsupported. Veda children are **not** recursively Fabric-equipped (`recursive: true` is rejected), and they cannot back persistent actors.
530
534
 
@@ -662,6 +666,31 @@ Each entry has three keys:
662
666
 
663
667
  The `fs` adapter derives each session's `revision` from the SHA-256 of the file bytes, so mtime-only touches keep follow pointers valid while content changes invalidate them. Enumeration is bounded by `memory.maxSessions` and reported through coverage reasons (`fs_source_max_sessions`, `fs_source_scan_capped`); a capped archive is never presented as complete. Ranking, branches, and expansion follow the normal engine paths described in [memory recall](memory-recall.md#portable-host-sources).
664
668
 
669
+ ## Extractive history (opt-in)
670
+
671
+ In `/fabric settings`, open **Extractive history**. Choose **Consent / mode** and a **Native classifier** from Pi core's registry. Model selection alone does not enable inference. This uses Pi core's `classify()` API, not Fabric's Jev connector.
672
+
673
+ ```json
674
+ {
675
+ "memory": {
676
+ "extractive": {
677
+ "enabled": false,
678
+ "provider": "typesafe",
679
+ "model": "jev-latest",
680
+ "maxViewBytes": 8192,
681
+ "maxCandidates": 128,
682
+ "maxSourceChars": 24000,
683
+ "maxEvaluationsPerTurn": 1,
684
+ "timeoutMs": 3000
685
+ }
686
+ }
687
+ }
688
+ ```
689
+
690
+ Set `enabled: true` to opt in. With `maxEvaluationsPerTurn: 1`, bounded active-branch user/assistant text is sent to the selected classifier and may incur API charges; there is no secret scanner. Set the budget to `0` for local deterministic extraction with no classifier calls. `memory.enabled: false` disables the feature too.
691
+
692
+ The bounded view preserves complete source quotes, attribution and omission notices. Scores indicate salience, **not truth**. Missing credentials, invalid answers and timeouts fall back deterministically; stale branch/session responses are discarded. It supplements request context without deleting history or replacing Pi compaction, and introduces no generative summarizer. See [Extractive history](extractive-history.md) for bounds and source navigation.
693
+
665
694
  ## Principal and scope
666
695
 
667
696
  Scope is host-issued and has no config key. A project or global setting cannot grant or widen a principal.
@@ -1,23 +1,86 @@
1
- # Opt-in Pi durable hosted runner
2
-
3
- `pi-fabric/durable` exports `createPiDurableRunner`, `PiDurableRunner`,
4
- `PiDurableRunnerOptions`, `PiDurableStorageOptions`, `PiDurableStorageLease`, and
5
- `PiDurableLocator`. It does not register a runner or change the default Pi runner.
6
- Importing the entry and constructing the factory do not load either optional runtime.
7
-
8
- This adapter targets the **published** experimental
9
- `@earendil-works/pi-durable@1.0.0` and `@earendil-works/chord@1.0.0` APIs.
10
- First start/attach checks both installed versions and loads them lazily. Missing or
11
- incompatible peers produce an explicit error. Host credentials remain in `Models`
12
- and the environment, never in the locator.
13
-
14
- ## Host setup
15
-
16
- Install the optional peers only in a host that uses this adapter:
17
-
18
- ```sh
19
- bun add @earendil-works/pi-durable@1.0.0 @earendil-works/chord@1.0.0
20
- ```
1
+ # Durable Pi runner
2
+
3
+ `agents.runner` defaults to **`pi-durable`**: an isolated Pi SDK process with a real
4
+ `AgentSession`, native RPC, and a `DurableAgent` backed by the published durable
5
+ Harness. Pinned worker dependencies ship with Fabric; registration and idle hooks
6
+ do not load the worker or engines.
7
+ No manual setup is required. Main's outer Pi session is unchanged.
8
+
9
+ The subprocess owns a pinned SDK installed as `pi-fabric-worker-sdk` (an npm
10
+ alias), because Pi-managed installs deliberately omit host-provided peers.
11
+ Only the durable worker maps Pi imports to that SDK and its dependencies; the
12
+ extension continues to use Main's host modules. If a partial/older installation
13
+ reports a missing worker SDK, reinstall or update Fabric to restore its runtime
14
+ dependencies. Installing Pi peers manually is not required. When Bun launches
15
+ the parent worker, the durable SDK host runs through `node` on PATH and requires
16
+ Node.js 24+, matching Fabric's declared engine. This keeps module resolution
17
+ isolated without passing `NODE_PATH` to tools or borrowing Main's SDK.
18
+
19
+ Set `agents.runner: "pi"` (or `runner: "pi"` per request) for the previous Pi CLI
20
+ worker. Existing explicit configurations and stored actor runners are not
21
+ rewritten. Pi JSONL remains the history interchange format. Custom Pi CLI wrappers
22
+ and `PI_FABRIC_PI_BINARY` apply only to the explicit legacy `pi` runner; the
23
+ durable worker uses the SDK and inherited process environment directly.
24
+
25
+ ## Full Pi/Fabric host
26
+
27
+ The default keeps native resource discovery, project trust, credentials/model
28
+ runtime, tools, extension hooks, images, virtual models, provider hooks, steering,
29
+ follow-ups, cancellation, and compaction. Fabric's existing process worker retains
30
+ model admission, schema validation, budgets, lineage, question routing, session
31
+ import/export, kernels, recursive Fabric, scopes, and write confinement. Actors
32
+ accept both Pi runners. Handoffs use the configured Pi runner; `rlm.query` defaults
33
+ to `pi-durable` and accepts an explicit `pi` override.
34
+
35
+ Unknown projects remain untrusted unless an existing policy or trusted bootstrap
36
+ extension grants trust. Extension-load errors fail closed; a permission guard is
37
+ never silently omitted.
38
+
39
+ ## Recovery boundaries
40
+
41
+ Private per-run JSONL stores flush payloads and commit markers. An OS-held SQLite
42
+ exclusive transaction prevents concurrent writers, including directory aliases;
43
+ process death releases it without timeout-based stealing or lock-file deletion.
44
+ Reopening the same run uses its initial run ID for idempotent submission and
45
+ resumes checkpoints. Completed work is not repeated. An interrupted unsafe tool
46
+ fails closed, including `fabric_exec`, writes, and shell commands.
47
+
48
+ Durability **does not restore arbitrary JavaScript continuations**, promise
49
+ general exactly-once external effects, or restart failed workers indefinitely.
50
+ The standard process/actor lifecycle controls stop/retry/retention. A new run is
51
+ new work; native RPC command IDs are response correlations, not deduplication keys
52
+ for arbitrary later prompts. Do not resend acknowledged controls as new commands.
53
+ Interrupted request/turn extension callbacks may be re-entered; callbacks with
54
+ external effects need their own idempotency policy. Restoring committed message
55
+ history does not redeliver message hooks or charge usage again. Normal session
56
+ switches receive fresh request identities and do not replay old answers.
57
+ Old leaf-adapter locators/journals are not silently migrated into worker stores.
58
+
59
+ Worker retries retain the original prompt identity, so a completed journal can
60
+ restore its answer even if the parent died before saving completion. Automatic
61
+ reattachment after the owning Fabric/resident process restarts currently covers
62
+ hosted adapters, not this built-in worker. Recovery of completed conversations
63
+ with additional steering/follow-up user messages also remains incomplete: strict
64
+ transcript correlation fails closed to avoid attributing a stale answer.
65
+ Control acknowledgements do not provide an end-to-end exactly-once delivery
66
+ contract; do not blindly resubmit a command whose acknowledgement was lost.
67
+
68
+ ## Advanced: manually registered leaf adapter
69
+
70
+ The rest of this guide concerns the restricted `pi-fabric/durable` factory, **not**
71
+ the built-in default. `createPiDurableRunner` still accepts host-supplied Models,
72
+ Registry, environment, and storage. Its default ID is now `pi-durable-leaf`; the
73
+ built-in `pi-durable` ID is reserved. Existing custom registrations should select
74
+ the separate ID explicitly.
75
+
76
+ Exports include `PiDurableRunner`, `PiDurableRunnerOptions`,
77
+ `PiDurableStorageOptions`, `PiDurableStorageLease`, `PiDurableLocator`, and
78
+ `PiDurableMessageOptions`. Import/construction stays lazy and does not register a
79
+ runner. First use checks pinned `@earendil-works/pi-durable@1.0.0` and
80
+ `@earendil-works/chord@1.0.0`. Credentials remain in Models/environment, never in
81
+ a locator.
82
+
83
+ ### Leaf host setup
21
84
 
22
85
  ```ts
23
86
  import { createPiDurableRunner } from "pi-fabric/durable";
@@ -27,21 +90,23 @@ import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
27
90
  // Supply a configured pi-ai Models collection and a durable Registry.
28
91
  // Install only trusted tool implementations in that registry.
29
92
  const runner = createPiDurableRunner({
30
- id: "pi-durable", // default; must not collide with another registration
93
+ id: "pi-durable-leaf", // separate from the built-in full host
31
94
  models,
32
95
  registry,
33
96
  env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd! }),
34
97
  allowedModels: [{ provider: "openai", modelId: "your-model-id" }],
98
+ defaultModel: { provider: "openai", modelId: "your-model-id" },
35
99
  storage: { kind: "jsonl", directory: "/absolute/private/durable-runs" },
36
100
  // Required for standard residency: "durable":
37
101
  // residentModule: "/absolute/path/to/host-registration.mjs",
38
102
  });
39
103
  const unregister = registerAgentRunner(runner);
40
104
 
41
- // An AgentManager / agents.run call must explicitly select this runner,
42
- // provider/model, and exact registered tool names:
43
- // { runner: "pi-durable", model: "openai/your-model-id",
44
- // task: "...", tools: ["read"], recursive: false, thinking: "off" }
105
+ // Select this runner explicitly, or set agents.runner to its registered id
106
+ // for a host that only uses the supported leaf-run capabilities.
107
+ // model can be omitted when defaultModel is configured above.
108
+ // { runner: "pi-durable-leaf", task: "...", tools: ["read"],
109
+ // recursive: false, thinking: "off" }
45
110
 
46
111
  // Detach only after the host has stopped delivering requests to this instance.
47
112
  await runner.close();
@@ -51,9 +116,31 @@ unregister();
51
116
  `residentModule` must be a real host-owned ES module that registers the adapter
52
117
  with the same storage and credentials in the resident process. Merely setting the
53
118
  path does not create a daemon. A session-resident runner needs no resident module.
54
- The factory does not discover providers or select a default model. Thinking is
55
- passed explicitly (omission means `off` at the adapter boundary); unsupported
56
- levels are rejected; the adapter does not clamp them.
119
+ The factory does not discover providers or credentials. `models()` advertises only
120
+ currently resolvable entries in `allowedModels`, with credential-free metadata.
121
+ An optional `defaultModel` must be allowlisted; without it an explicit model is
122
+ required. Model execution continues through the supplied `Models` collection.
123
+ Thinking is passed explicitly (omission means `off` at the adapter boundary);
124
+ unsupported levels are rejected; the adapter does not clamp them.
125
+
126
+ ## Leaf adapter supported requests
127
+
128
+ - **Image input:** `images` is submitted as native image blocks alongside the task.
129
+ The selected model must declare image input. PNG, JPEG, GIF and WebP are accepted
130
+ as padded base64, with at most 32 images and 16 MiB of base64 characters total.
131
+ Durable storage retains the images; Fabric's text transcript projection does not
132
+ reproduce their bytes. Images never enter the locator.
133
+ - **Structured output:** `schema` is included in the model instructions, and the
134
+ final answer is parsed and validated with Fabric's normal result validator.
135
+ Invalid output fails the run; valid output is reported as `structured` and
136
+ reaches the agent result's `value`. This is validation, not provider-enforced
137
+ constrained decoding. Schemas are bounded to 262144 JSON characters.
138
+ - **Steering and follow-up:** admitted messages extend the same Fabric run's
139
+ completion boundary. See below; a completed run cannot be reopened with a new
140
+ message. This is not persistent actor/session support.
141
+
142
+ The committed request fingerprint includes image content and output schema;
143
+ reattaching the same run ID with changed inputs is refused.
57
144
 
58
145
  ## Storage and ownership
59
146
 
@@ -121,7 +208,7 @@ Fabric persists the pure JSON locator before `start`. It contains backend/versio
121
208
  a storage identity hash, and Fabric run ID only. `start` commits a request manifest
122
209
  and submits with **requestId = Fabric run ID**. Repeated starts, including after
123
210
  reopen, reuse the committed submission. A changed task/model/tools/cwd/thinking/
124
- system prompt under that run ID is rejected.
211
+ system prompt/images/schema under that run ID is rejected.
125
212
 
126
213
  `attach` looks up the existing root and `submissionByRequest`; it never creates a
127
214
  conversation or submits an input. A locator with no admitted submission throws;
@@ -133,7 +220,9 @@ Committed conversation snapshots feed progress (turns, calls, current tool,
133
220
  partial text), cumulative model/tool usage, and transcript messages/tool events.
134
221
  Transcript attachment reconstructs the current committed history; it does not
135
222
  rerun effects or guarantee exactly-once transcript delivery across host restarts.
136
- The final submission maps to completed/text, aborted/stopped, or unanswered/failed.
223
+ The admitted submissions map to completed/text, aborted/stopped, or unanswered/failed.
224
+ Completion waits for the initial input and every accepted control message, and
225
+ returns their latest answer by answer-entry order (not message-admission order).
137
226
  Liveness is running, settled, cancelled, interrupted, or unknown. Unowned/missing
138
227
  work is unknown; explicit stop returns unconfirmed when no owned submission exists.
139
228
 
@@ -144,6 +233,31 @@ factory instance can attach afterward. `close` is idempotent, but a closed
144
233
  instance cannot reopen. This is a resource lifecycle surface, not a sleep/wake
145
234
  capability. Fabric's own explicit stop/shutdown/deadline policy is unchanged.
146
235
 
236
+ ## Durable steering and follow-up
237
+
238
+ `runner.steer(locator, message, options?)` places input at a tool boundary;
239
+ `runner.followUp(locator, message, options?)` queues the next generation after
240
+ the current answer. The public methods can take a host-issued stable identity:
241
+
242
+ ```ts
243
+ await runner.followUp(locator, "Also verify the migration", { requestId: "verify-1" });
244
+ ```
245
+
246
+ Retrying the same `requestId`, message and method is a no-op, including after
247
+ reattachment or completion. Reusing it for different work is rejected. Without
248
+ `requestId`, each invocation is a distinct message. Other message-option fields
249
+ are rejected, not ignored. Normal Fabric `agents.steer`/`agents.followUp` calls
250
+ are also supported; their delivery acknowledgement is not a new completion receipt.
251
+
252
+ Admission uses the upstream submission's atomic, persisted request identity.
253
+ Recovery discovers committed submissions directly from storage, including a
254
+ message admitted just before a crash; it never replays the message as a new
255
+ submission. A persisted completion boundary rejects new messages after settlement.
256
+ Limits are 128 control messages per run, 16384 characters per message and 256
257
+ characters per supplied `requestId`. A failed generation withdraws queued
258
+ follow-ups so the Fabric run does not wait indefinitely. `stop` also
259
+ aborts an executing follow-up, even if the original input is already answered.
260
+
147
261
  ## Tools and limitations
148
262
 
149
263
  Only names in `request.tools` are selected. Unknown names and unknown/disallowed
@@ -169,11 +283,22 @@ permits replay; the adapter never blanket-marks tools safe. A host-registered
169
283
  `fabric_exec` implementation is always forced unsafe even if the host accidentally
170
284
  marks it safe; no Fabric bridge is synthesized.
171
285
 
172
- Unsupported capabilities fail closed: recursive Fabric, kernels, branch/session
173
- seeding, actors/persistent sessions, write confinement, scopes, structured output
174
- schemas, image input, routed questions, explicit compaction, sleep/wake, steering,
175
- and follow-up. Steering/follow-up are intentionally absent: the published queue
176
- semantics are not claimed to extend Fabric's one-submission completion boundary.
286
+ Unsupported capabilities still fail closed: recursive Fabric, kernels,
287
+ branch/session seeding, actors/persistent sessions, write confinement, scopes,
288
+ routed questions, explicit compaction, and sleep/wake.
289
+
290
+ ## Full-host and leaf boundaries
291
+
292
+ The default is a **worker** adapter, preserving native permission and lifecycle
293
+ ownership. The manually registered leaf adapter remains **hosted**, with its
294
+ unsupported capability checks intact. Neither silently falls back to a native
295
+ Agent when durable execution fails.
296
+
297
+ Full-host coverage is in `tests/durable-agent.test.ts`,
298
+ `tests/durable-session.test.ts`, `tests/durable-worker-storage.test.ts`,
299
+ `tests/durable-worker-host.test.ts`, `tests/durable-worker-routing.test.ts`,
300
+ `tests/durable-worker-e2e.test.ts`, `tests/durable-fabric-exec.test.ts`,
301
+ `tests/handoff-continuation-worker.test.ts`, and `tests/durable-actors.test.ts`.
177
302
 
178
303
  ## Evidence
179
304
 
@@ -181,6 +306,9 @@ semantics are not claimed to extend Fabric's one-submission completion boundary.
181
306
  faux models, MemoryStorage and fsync JSONL: real AgentManager execution, duplicate
182
307
  admission, reopen/attach, cancellable unsafe interruption, a killed
183
308
  process/manual recovery/no replay, exclusive ownership, stale-lock refusal,
184
- close/open races, exact tools/model/thinking, usage/progress, cancellation and
185
- unsupported requests. `tests/optional-durable-startup.test.ts` independently
186
- checks dependency-free import and no automatic registration.
309
+ close/open races, exact tools/model/thinking, usage/progress, configured leaf
310
+ defaults, model-metadata privacy, images, schema validation, message ordering and
311
+ deduplication, queued-message recovery, cancellation and unsupported requests.
312
+ `tests/durable-input.test.ts` covers request snapshots and input bounds.
313
+ `tests/durable-controls.test.ts` covers the completion-versus-cancellation race.
314
+ `tests/optional-durable-startup.test.ts` checks lazy engine loading even with built-in runner registration.
@@ -0,0 +1,171 @@
1
+ # Classifier-assisted extractive history (Jev supported)
2
+
3
+ This **off-by-default** supplement selects verbatim source evidence from the
4
+ **current session's active branch**. It neither replaces the current prompt/raw
5
+ work nor changes Fabric's deterministic compactor, summaries or typed truths.
6
+ The session remains authoritative; this disposable view is not a facts database.
7
+
8
+ ## Opt in
9
+
10
+ Open `/fabric settings` → **Extractive history**.
11
+ **Consent / mode** offers:
12
+
13
+ - **Off**: no extractive module load or classifier calls at startup/idle/turns.
14
+ - **Deterministic only (no classifier)**: local selection without model access.
15
+ - **Enable classifier: send bounded user/assistant text; API charges**: explicit
16
+ consent to send historical text to the selected native classifier provider.
17
+
18
+ The screen warns about API charges, bounded user/assistant text, and absence of
19
+ secret scanning. Text can contain private data or secrets; this is **not** a
20
+ sanitizer. Thinking, tool calls, tool output, generated/custom messages and
21
+ compaction/branch-summary prose are excluded from this feature's classifier
22
+ input. These exclusions do not change the independent memory provider's policy.
23
+ There is no automatic project/global/cross-session retrieval.
24
+
25
+ **Native classifier** lists the host's current `getModelsOfType("classifier")`
26
+ catalog and reports authenticated/available classifiers from
27
+ `getAvailableOfType("classifier")`. Any registered classifier is selectable,
28
+ including local/custom providers. This is not the chat model picker. Selection
29
+ alone does not enable inference. Missing models/credentials produce a clear
30
+ local fallback; there is no silent alternate-model or connector fallback.
31
+
32
+ Equivalent JSON in a trusted `.pi/fabric.json` or personal `fabric.json`:
33
+
34
+ ```json
35
+ {
36
+ "memory": {
37
+ "enabled": true,
38
+ "extractive": {
39
+ "enabled": false,
40
+ "provider": "typesafe",
41
+ "model": "jev-latest",
42
+ "maxViewBytes": 8192,
43
+ "maxCandidates": 128,
44
+ "maxSourceChars": 24000,
45
+ "maxEvaluationsPerTurn": 1,
46
+ "timeoutMs": 3000
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ Changing `enabled` to `true` is the JSON opt-in to classification; use
53
+ `maxEvaluationsPerTurn: 0` for deterministic-only mode. `memory.enabled: false`
54
+ also disables the view. Provider and model ID are stored separately (model IDs
55
+ may contain `/`). Settings reload the live config, invalidate the old view and
56
+ abort a pending request. Extension reload/shutdown and session/branch changes
57
+ also invalidate it.
58
+
59
+ | Setting | Bounds / meaning |
60
+ | --- | --- |
61
+ | `maxViewBytes` | 1,024–32,768 UTF-8 bytes, including JSON framing and navigation |
62
+ | `maxCandidates` | 1–256 complete candidate bundles considered locally |
63
+ | `maxSourceChars` | 256–100,000; classifier context is conservatively bounded in **UTF-8 bytes**, including questions, rubric, IDs and JSON escaping (therefore also bounded in characters) |
64
+ | `maxEvaluationsPerTurn` | 0 or 1 native batch; never per-tool/context replay |
65
+ | `timeoutMs` | 100–10,000 ms, including availability/auth and classification |
66
+
67
+ Native inference batches contain at most **128** questions even when the local
68
+ pool is larger. Whole bundles that cannot fit are omitted, not prefix-clipped.
69
+ Very small budgets can produce a navigation-only view and no inference.
70
+
71
+ ## Evidence, not generated summaries
72
+
73
+ Each source is a role-labelled entry ID and its complete text parts. Paragraphs
74
+ and qualifiers are retained intact. A candidate contains one exchange plus its
75
+ preceding exchange, mechanically preserving local references such as “yes,
76
+ second one” without pretending to resolve arbitrary anaphora. Larger reference
77
+ chains may require raw expansion. Multimodal parts are not summarized.
78
+
79
+ A chronological binary range index retains the underlying candidate ranges.
80
+ Parent selection runs over those original candidates, **not** over the child
81
+ views' surviving selections. The local bounded pool samples temporal endpoints
82
+ and recursively bisected intervals, then uses TF-IDF cosine relevance, recency,
83
+ role-coverage preference and MMR diversity. MMR updates redundancy incrementally
84
+ with a quadratic bound in the capped candidate count. Role coverage is best
85
+ effort under whole-bundle byte limits, not permission to split a qualifier.
86
+
87
+ The optional native classifier sees only bounded original bundles, not parent
88
+ extracts or generated summaries. The current rubric asks native `bool` salience
89
+ questions and reads `probability`; it requires `stopReason: "stop"`, exactly the
90
+ requested keys, matching primitives, and finite values in [0,1]. A malformed
91
+ answer invalidates the whole batch. Internal primitive normalization supports
92
+ native score/confidence and choice/probabilities for future rubrics, but these
93
+ are **not** accepted as substitutes for the current bool questions.
94
+
95
+ Salience is just a small ranking contribution. False, high probability, or high
96
+ confidence never verifies a fact, accepts a command, or turns an assistant claim
97
+ into a successful tool outcome. Earlier corrections and conflicting claims can
98
+ coexist; there is no inferred authoritative supersession. No semantic regex
99
+ classifies facts, preferences, goals or commands.
100
+
101
+ ## Lifecycle, caching and failures
102
+
103
+ The implementation imports lazily at an enabled `before_agent_start` boundary.
104
+ It issues at most one batch for the current source user-entry turn. A `context`
105
+ hook prepends one replay-safe ephemeral custom data message: JSON-quoted,
106
+ explicitly **untrusted historical evidence**, not system instructions. It never
107
+ calls `sendMessage`/`appendEntry`, so its output cannot enter its own candidate
108
+ pool or become persisted compactor input. The raw outgoing prompt and work
109
+ remain intact. Quotation is provenance/framing, not a promise that a downstream
110
+ model is immune to prompt injection.
111
+
112
+ Successes **and failures** are cached against session, source-bundle content,
113
+ provider/model and rubric version. Caches are session-owned, in-memory,
114
+ disposable and bounded to 1,024 annotations. They are not restart-durable and
115
+ never delete source records. Config/session/branch changes, source hash or
116
+ lineage mismatch, and cancellation prevent stale injection; new tool output
117
+ does not trigger another classifier call. There is no ancestor inference.
118
+
119
+ Timeout, missing native API/model/auth, provider error, invalid keys/primitive,
120
+ nonfinite results, or exhausted per-turn budget use deterministic selection
121
+ with an explicit diagnostic. Aborted/stale work is discarded and never injected. The timeout races the request as well as signalling cancellation;
122
+ a provider that ignores abort may still finish or charge remotely.
123
+
124
+ Classifier calls go exclusively through `ctx.modelRegistry.getModelOfType`,
125
+ `getAvailableOfType`, and `classify`. No Fabric `JevClient`, Jev connector,
126
+ global store, source-file scanner or generated code is involved. Reported native
127
+ usage is attached as ephemeral `classifierUsage` metadata; this hook does **not**
128
+ claim to add it to Pi's durable billing/session totals.
129
+
130
+ ## Recover omitted evidence
131
+
132
+ The view reports total/selected/omitted bundle counts and chronological entry-ID
133
+ range hints. Its copy-ready `follow` invokes
134
+ `memory.recall({ scope: "session:<current-session>", branches: "active" })`.
135
+ Page `next` until null, check `coverage`, then dispatch a hit's `follow` for raw
136
+ expansion. This browses the whole selected branch, including interiors omitted
137
+ from every displayed tree node. Range endpoints are **hints**, not numeric
138
+ `entryRange` values and not a claim that two endpoint IDs recover the interior.
139
+
140
+ For an individual displayed address:
141
+
142
+ ```ts
143
+ await memory.expand({
144
+ session: "<session path or id from the view>",
145
+ branches: "active",
146
+ entryIds: ["<entryId>"]
147
+ });
148
+ ```
149
+
150
+ Follow expansion `next` for complete long entries. Raw retrieval remains an
151
+ independent API with its own coverage, authorization and integrity checks; it
152
+ can expose tool output according to its separately configured policy. An
153
+ unsaved/in-memory session without a memory-provider source may not resolve via
154
+ these pointers. Incomplete indexing is not proof that omitted evidence is
155
+ absent. See [memory recall](memory-recall.md) and [compaction](compaction.md).
156
+
157
+ ## Checks and limitations
158
+
159
+ Targeted tests: `tests/extractive-history.test.ts`,
160
+ `tests/extractive-extension.test.ts`, and `tests/extractive-settings.test.ts`.
161
+ They cover real provider follows, exact quotes/provenance, local references,
162
+ whole-bundle omission, Unicode byte bounds, source-pool parent selection,
163
+ strict native answers, failure caching, cancellation/branch/config staleness,
164
+ first-use/disabled imports, ephemeral context replay, and JSON/TUI persistence.
165
+
166
+ V1 has no visual tree browser, cross-session automatic selection, persistent
167
+ annotation store, generative summarizer, truth verifier, authoritative
168
+ correction resolver, secret scanner, or automatic inferred-command execution.
169
+ The range index's reselection API is local; model navigation uses existing
170
+ memory retrieval. Building the index and checking source freshness still scale
171
+ with the host-supplied active branch; NLP/inference/display work is bounded.
package/docs/interface.md CHANGED
@@ -20,7 +20,7 @@ See [Background tasks and monitors](background-tasks.md) for completion delivery
20
20
 
21
21
  Press **ctrl+shift+a** or run **`/fabric chat`** to open a full-screen conversation without going through the dashboard. `/fabric chat <id-or-name>` opens a specific agent or actor; Tab completes exact participant IDs, including nested agents. Ambiguous names or ID prefixes are rejected; use an exact participant ID to select the intended target. In the dashboard, **Shift+C** opens the selected participant.
22
22
 
23
- The first implicit open prefers a currently active child over stale history; later opens remember a valid selection. The view keeps a lossless native Pi transcript and a multiline Pi editor together, independently of the dashboard’s bounded transcript projection. It uses Pi’s real user, assistant, thinking, tool, skill, custom-message, and summary components, including registered tool renderers such as `fabric_exec`, with complete tool details and native expansion behavior. User backgrounds and editor rules span the terminal width, with Pi's configured output padding, editor padding, and code-block indentation inside them. Markdown and tool previews use the configured Shiki theme. A one-row gap belongs to the transcript's end, not the fixed input dock, so it scrolls away and leaves history unobstructed. While the selected participant is active, Pi's native standalone `Working` loader appears inside the transcript with its normal spacing and colors, above that final gap. The directory/name footer row includes a compact `read-only` badge when needed; status, model, and thinking metadata are not repeated in a separate header. The footer below the editor shows the selected participant's directory, known branch, model, thinking level, and run-scoped token/cache/cost statistics. Unknown usage and context occupancy are marked explicitly; Main's statistics are never substituted. Breadcrumbs preserve `Main → child → grandchild` lineage. Main and other participants keep running: opening, navigating, and closing the view never calls Pi's session-replacement API or starts another worker. Selecting Main restores the original Pi conversation, including its editor. Child drafts and scroll positions survive switching targets and reopening the view for the lifetime of this Pi session.
23
+ The first implicit open prefers a currently active child over stale history; later opens remember a valid selection. The view keeps a lossless native Pi transcript and a multiline Pi editor together, independently of the dashboard’s bounded transcript projection. It uses Pi’s real user, assistant, thinking, tool, skill, custom-message, and summary components, including registered tool renderers such as `fabric_exec`, with complete tool details and native expansion behavior. User backgrounds and editor rules span the terminal width, with Pi's configured output padding, editor padding, and code-block indentation inside them. Markdown and tool previews use the configured Shiki theme. A one-row gap belongs to the transcript's end, not the fixed input dock, so it scrolls away and leaves history unobstructed. While the selected participant is active, the native-style `Working` indicator stays in the editor border; the transcript uses a fallback only when that border is out of view. The directory/name footer row includes a compact `read-only` badge when needed; status, model, and thinking metadata are not repeated in a separate header. The footer below the editor shows the selected participant's directory, known branch, model, thinking level, and run-scoped token/cache/cost statistics. Unknown usage and context occupancy are marked explicitly; Main's statistics are never substituted. A themed, background-filled target badge sits on the upper-right editor border, replacing the standalone transcript breadcrumb. It preserves `Main > child > grandchild` lineage when space permits, prioritizes the active target on narrow terminals, and marks read-only targets. Native working and draft-scroll labels share the border without adding a row. Main and other participants keep running: opening, navigating, and closing the view never calls Pi's session-replacement API or starts another worker. Selecting Main restores the original Pi conversation, including its editor. Child drafts and scroll positions survive switching targets and reopening the view for the lifetime of this Pi session.
24
24
 
25
25
  The transcript also follows Pi 1.0's fullscreen scrollbar setting (`auto`, `always`, or `hidden`), theme colors, hover/drag behavior, and auto-hide timing. Only an always-visible scrollbar reserves a transcript column; the editor and footer keep their full width. The thumb describes the loaded history window; existing wheel, page, and top commands continue to fetch older history. While scrolled away from the tail, or when newer history is not loaded, the native-style **↓ Jump to latest message · End** indicator appears at the transcript bottom. Its shortcut label follows Pi's configured binding. Click it or use the shortcut to load the latest history and resume following, without losing the draft or editor focus. Selection drags do not activate it.
26
26