@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.
- package/README.md +3 -1
- package/dist/actors/global-registry.d.ts.map +1 -1
- package/dist/agents/manager.d.ts.map +1 -1
- package/dist/agents/result.d.ts.map +1 -1
- package/dist/agents/result.js +1 -1
- package/dist/agents/runner-registry.d.ts +1 -1
- package/dist/agents/runner-registry.d.ts.map +1 -1
- package/dist/agents.js +5 -5
- package/dist/chunks/{chunk-5MNLVHF5.js → chunk-3DUKKQHN.js} +28 -13
- package/dist/chunks/chunk-3DUKKQHN.js.map +7 -0
- package/dist/chunks/{chunk-GJVPP3NN.js → chunk-3SHUUBZJ.js} +4 -4
- package/dist/chunks/chunk-3SHUUBZJ.js.map +7 -0
- package/dist/chunks/{chunk-VON4TSO3.js → chunk-CZPQTISQ.js} +27 -2
- package/dist/chunks/chunk-CZPQTISQ.js.map +7 -0
- package/dist/chunks/{chunk-WLLXKS6I.js → chunk-DU6ZA44F.js} +4 -4
- package/dist/chunks/{chunk-QLFDPXK7.js → chunk-DV2JZSCI.js} +153 -27
- package/dist/chunks/chunk-DV2JZSCI.js.map +7 -0
- package/dist/chunks/{chunk-KQ6R5EWR.js → chunk-FRPNQZV2.js} +24 -22
- package/dist/chunks/chunk-FRPNQZV2.js.map +7 -0
- package/dist/chunks/{chunk-W7X4XEQU.js → chunk-GC2AUXG6.js} +2 -2
- package/dist/chunks/chunk-K6QXUGS5.js +30 -0
- package/dist/chunks/chunk-K6QXUGS5.js.map +7 -0
- package/dist/chunks/{chunk-VPRJOD4Y.js → chunk-LEDY5G2V.js} +2 -2
- package/dist/chunks/{chunk-OVBKQCYL.js → chunk-N2VKKA7O.js} +2 -2
- package/dist/chunks/{chunk-N5GUXC6F.js → chunk-P4KH4S4S.js} +2 -1
- package/dist/chunks/chunk-P4KH4S4S.js.map +7 -0
- package/dist/chunks/{chunk-TFFZVLR2.js → chunk-PF27MQY5.js} +55 -4
- package/dist/chunks/chunk-PF27MQY5.js.map +7 -0
- package/dist/chunks/{chunk-CGL7QP4A.js → chunk-PK4NIJEV.js} +10 -1
- package/dist/chunks/{chunk-CGL7QP4A.js.map → chunk-PK4NIJEV.js.map} +2 -2
- package/dist/chunks/{chunk-YRDCJZZW.js → chunk-RUO6L7RM.js} +1 -1
- package/dist/chunks/{chunk-YRDCJZZW.js.map → chunk-RUO6L7RM.js.map} +1 -1
- package/dist/chunks/{chunk-4RTHQGES.js → chunk-ST36EYHN.js} +4 -4
- package/dist/chunks/chunk-ST36EYHN.js.map +7 -0
- package/dist/chunks/{chunk-R5F6CHW2.js → chunk-UXEMIWYI.js} +12 -7
- package/dist/chunks/chunk-UXEMIWYI.js.map +7 -0
- package/dist/chunks/{chunk-SGFH5PYA.js → chunk-V2SKDVQX.js} +10 -9
- package/dist/chunks/chunk-V2SKDVQX.js.map +7 -0
- package/dist/chunks/{chunk-KYXZJNV6.js → chunk-VTK2FEH7.js} +3 -1
- package/dist/chunks/{chunk-KYXZJNV6.js.map → chunk-VTK2FEH7.js.map} +2 -2
- package/dist/chunks/{chunk-3QECYQGA.js → chunk-VYQV5JRT.js} +13 -1
- package/dist/chunks/chunk-VYQV5JRT.js.map +7 -0
- package/dist/chunks/{chunk-3KDUMDPZ.js → chunk-X3CHSIL2.js} +5 -5
- package/dist/chunks/{chunk-EXWS4ZS3.js → chunk-YJX27XBO.js} +100 -22
- package/dist/chunks/chunk-YJX27XBO.js.map +7 -0
- package/dist/components/configuration.js +2 -2
- package/dist/config.d.ts +16 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/core/action-registry.d.ts +1 -1
- package/dist/core/action-registry.d.ts.map +1 -1
- package/dist/core/action-registry.js +2 -2
- package/dist/core/media-sanitize.d.ts.map +1 -1
- package/dist/core/native-tool-names.d.ts +9 -0
- package/dist/core/native-tool-names.d.ts.map +1 -0
- package/dist/core/native-tool-result.d.ts +11 -0
- package/dist/core/native-tool-result.d.ts.map +1 -0
- package/dist/core/system-guidance.d.ts +3 -3
- package/dist/core/system-guidance.d.ts.map +1 -1
- package/dist/durable/agent.d.ts +77 -0
- package/dist/durable/agent.d.ts.map +1 -0
- package/dist/durable/session.d.ts +19 -0
- package/dist/durable/session.d.ts.map +1 -0
- package/dist/durable/storage.d.ts +7 -0
- package/dist/durable/storage.d.ts.map +1 -0
- package/dist/durable/worker-host.d.ts +13 -0
- package/dist/durable/worker-host.d.ts.map +1 -0
- package/dist/durable/worker-host.js +1149 -0
- package/dist/durable/worker-host.js.map +7 -0
- package/dist/durable/worker-options.d.ts +17 -0
- package/dist/durable/worker-options.d.ts.map +1 -0
- package/dist/durable/worker.d.ts +3 -0
- package/dist/durable/worker.d.ts.map +1 -0
- package/dist/durable/worker.js +110 -0
- package/dist/durable/worker.js.map +7 -0
- package/dist/durable-controls.d.ts +27 -0
- package/dist/durable-controls.d.ts.map +1 -0
- package/dist/durable-input.d.ts +13 -0
- package/dist/durable-input.d.ts.map +1 -0
- package/dist/durable.d.ts +6 -0
- package/dist/durable.d.ts.map +1 -1
- package/dist/durable.js +194 -24
- package/dist/durable.js.map +4 -4
- package/dist/execution-service.d.ts +4 -0
- package/dist/execution-service.d.ts.map +1 -1
- package/dist/extension-bootstrap.js +5 -5
- package/dist/extension.d.ts.map +1 -1
- package/dist/fabric-exec-arguments.d.ts.map +1 -1
- package/dist/fabric-exec-tool.d.ts.map +1 -1
- package/dist/fabric-runtime-state.d.ts.map +1 -1
- package/dist/fabric-runtime-state.js +604 -284
- package/dist/fabric-runtime-state.js.map +4 -4
- package/dist/index.js +5 -5
- package/dist/jev/observation.js +2 -2
- package/dist/jev.js +3 -3
- package/dist/mcp.js +1 -1
- package/dist/memory/extractive-history.d.ts +29 -0
- package/dist/memory/extractive-history.d.ts.map +1 -0
- package/dist/memory/extractive-history.js +340 -0
- package/dist/memory/extractive-history.js.map +7 -0
- package/dist/memory/extractive-index.d.ts +46 -0
- package/dist/memory/extractive-index.d.ts.map +1 -0
- package/dist/native-codemode.d.ts +34 -0
- package/dist/native-codemode.d.ts.map +1 -0
- package/dist/native-discovery.d.ts +16 -0
- package/dist/native-discovery.d.ts.map +1 -0
- package/dist/native-discovery.js +19 -0
- package/dist/native-discovery.js.map +7 -0
- package/dist/native-image-artifacts.d.ts +4 -0
- package/dist/native-image-artifacts.d.ts.map +1 -0
- package/dist/native-image-artifacts.js +18 -0
- package/dist/native-image-artifacts.js.map +7 -0
- package/dist/native-tool-catalog.d.ts +21 -0
- package/dist/native-tool-catalog.d.ts.map +1 -0
- package/dist/native-tool-catalog.js +71 -0
- package/dist/native-tool-catalog.js.map +7 -0
- package/dist/protocol.d.ts +2 -0
- package/dist/protocol.d.ts.map +1 -1
- package/dist/protocol.js +1 -1
- package/dist/providers/agents-provider.d.ts.map +1 -1
- package/dist/providers/captured-tools-provider.d.ts +1 -1
- package/dist/providers/captured-tools-provider.d.ts.map +1 -1
- package/dist/providers/jev-provider.js +3 -3
- package/dist/providers/mcp-provider.d.ts +1 -1
- package/dist/providers/mcp-provider.d.ts.map +1 -1
- package/dist/providers/pi-native-mcp.d.ts.map +1 -1
- package/dist/providers/pi-tools-provider.d.ts.map +1 -1
- package/dist/residency/host.js +7 -7
- package/dist/residency/pi-entry.js +7 -7
- package/dist/runners.js +1 -1
- package/dist/runtime/core-override-guest-types.js +2 -2
- package/dist/runtime/dynamic-guest-types.d.ts +2 -0
- package/dist/runtime/dynamic-guest-types.d.ts.map +1 -1
- package/dist/runtime/dynamic-guest-types.js +5 -3
- package/dist/runtime/guest-types.d.ts +1 -1
- package/dist/runtime/guest-types.d.ts.map +1 -1
- package/dist/runtime/guest-types.js +1 -1
- package/dist/runtime/kernel.d.ts +5 -0
- package/dist/runtime/kernel.d.ts.map +1 -1
- package/dist/runtime/monty-runtime.js +1 -1
- package/dist/runtime/native-codemode-guest.d.ts +2 -0
- package/dist/runtime/native-codemode-guest.d.ts.map +1 -0
- package/dist/runtime/native-codemode-types.d.ts +2 -0
- package/dist/runtime/native-codemode-types.d.ts.map +1 -0
- package/dist/runtime/node-process-child-source.d.ts.map +1 -1
- package/dist/runtime/node-process-runtime.d.ts.map +1 -1
- package/dist/runtime/node-process-runtime.js +3 -3
- package/dist/runtime/quickjs-runtime.d.ts +1 -1
- package/dist/runtime/quickjs-runtime.d.ts.map +1 -1
- package/dist/runtime/quickjs-runtime.js +3 -2
- package/dist/runtime/type-checker.d.ts +2 -0
- package/dist/runtime/type-checker.d.ts.map +1 -1
- package/dist/runtime/type-checker.js +5 -3
- package/dist/runtime/typescript-kernel.d.ts +1 -1
- package/dist/runtime/typescript-kernel.d.ts.map +1 -1
- package/dist/runtime/typescript-kernel.js +13 -11
- package/dist/runtime/typescript-kernel.js.map +2 -2
- package/dist/runtime-state-speculation.d.ts +4 -1
- package/dist/runtime-state-speculation.d.ts.map +1 -1
- package/dist/speculation/python-scanner.js +1 -1
- package/dist/speculation/python-scanner.js.map +2 -2
- package/dist/speculation/scanner.d.ts +2 -0
- package/dist/speculation/scanner.d.ts.map +1 -1
- package/dist/speculation/scanner.js +18 -4
- package/dist/speculation/scanner.js.map +2 -2
- package/dist/speculation/types.d.ts +1 -0
- package/dist/speculation/types.d.ts.map +1 -1
- package/dist/type-error-guidance.js +1 -1
- package/dist/ui/border-status-editor.d.ts +3 -0
- package/dist/ui/border-status-editor.d.ts.map +1 -1
- package/dist/ui/controller.d.ts.map +1 -1
- package/dist/ui/conversation.d.ts +1 -0
- package/dist/ui/conversation.d.ts.map +1 -1
- package/dist/ui/conversation.js +28 -5
- package/dist/ui/conversation.js.map +2 -2
- package/dist/ui/dashboard.d.ts +2 -0
- package/dist/ui/dashboard.d.ts.map +1 -1
- package/dist/ui/dashboard.js +20 -7
- package/dist/ui/dashboard.js.map +2 -2
- package/dist/ui/settings-section-context.d.ts +2 -0
- package/dist/ui/settings-section-context.d.ts.map +1 -1
- package/dist/ui/settings-sections-execution.d.ts.map +1 -1
- package/dist/ui/settings-sections-lifecycle.d.ts +1 -0
- package/dist/ui/settings-sections-lifecycle.d.ts.map +1 -1
- package/dist/ui/settings-sections.d.ts +2 -0
- package/dist/ui/settings-sections.d.ts.map +1 -1
- package/dist/ui/settings-values.d.ts +4 -1
- package/dist/ui/settings-values.d.ts.map +1 -1
- package/dist/ui/settings.d.ts.map +1 -1
- package/dist/ui/settings.js +61 -2
- package/dist/ui/settings.js.map +2 -2
- package/dist/worker/model-control.d.ts.map +1 -1
- package/dist/worker/model-control.js.map +2 -2
- package/dist/worker/options.d.ts.map +1 -1
- package/dist/worker/options.js +4 -3
- package/dist/worker/options.js.map +2 -2
- package/dist/worker/result.js +12 -0
- package/dist/worker/result.js.map +2 -2
- package/dist/worker.js +95 -8
- package/dist/worker.js.map +2 -2
- package/docs/agents.md +5 -5
- package/docs/codemode-parity.md +97 -0
- package/docs/configuration.md +31 -2
- package/docs/durable-pi.md +166 -38
- package/docs/extractive-history.md +171 -0
- package/docs/interface.md +1 -1
- package/docs/speculation.md +12 -3
- package/package.json +7 -16
- package/skillsets/typescript/fabric-exec/SKILL.md +4 -4
- package/dist/chunks/chunk-3QECYQGA.js.map +0 -7
- package/dist/chunks/chunk-4RTHQGES.js.map +0 -7
- package/dist/chunks/chunk-5MNLVHF5.js.map +0 -7
- package/dist/chunks/chunk-EXWS4ZS3.js.map +0 -7
- package/dist/chunks/chunk-GJVPP3NN.js.map +0 -7
- package/dist/chunks/chunk-KQ6R5EWR.js.map +0 -7
- package/dist/chunks/chunk-N5GUXC6F.js.map +0 -7
- package/dist/chunks/chunk-QLFDPXK7.js.map +0 -7
- package/dist/chunks/chunk-R5F6CHW2.js.map +0 -7
- package/dist/chunks/chunk-SGFH5PYA.js.map +0 -7
- package/dist/chunks/chunk-TFFZVLR2.js.map +0 -7
- package/dist/chunks/chunk-VON4TSO3.js.map +0 -7
- /package/dist/chunks/{chunk-WLLXKS6I.js.map → chunk-DU6ZA44F.js.map} +0 -0
- /package/dist/chunks/{chunk-W7X4XEQU.js.map → chunk-GC2AUXG6.js.map} +0 -0
- /package/dist/chunks/{chunk-VPRJOD4Y.js.map → chunk-LEDY5G2V.js.map} +0 -0
- /package/dist/chunks/{chunk-OVBKQCYL.js.map → chunk-N2VKKA7O.js.map} +0 -0
- /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).
|
package/docs/configuration.md
CHANGED
|
@@ -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"
|
|
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.
|
package/docs/durable-pi.md
CHANGED
|
@@ -1,23 +1,86 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
`pi-
|
|
4
|
-
`
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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", //
|
|
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
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
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
|
|
55
|
-
|
|
56
|
-
|
|
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
|
|
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,
|
|
173
|
-
seeding, actors/persistent sessions, write confinement, scopes,
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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,
|
|
185
|
-
|
|
186
|
-
|
|
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,
|
|
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
|
|