@e4779/pi-fabric 0.92.42-fork.7 → 0.96.4-fork.10
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/LAWS.bend +502 -0
- package/PROOF.bend +452 -0
- package/README.md +5 -1
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/dist/agents/handoff.d.ts +2 -1
- package/dist/agents/handoff.d.ts.map +1 -1
- package/dist/agents/manager.d.ts +2 -0
- package/dist/agents/manager.d.ts.map +1 -1
- package/dist/agents.js +6 -5
- package/dist/agents.js.map +1 -1
- package/dist/chunks/{chunk-3TXOQ5MG.js → chunk-3CJETB4S.js} +828 -204
- package/dist/chunks/chunk-3CJETB4S.js.map +7 -0
- package/dist/chunks/{chunk-IUCVOZRX.js → chunk-3SIXBW6A.js} +2 -2
- package/dist/chunks/chunk-4E63LJDD.js +468 -0
- package/dist/chunks/chunk-4E63LJDD.js.map +7 -0
- package/dist/chunks/{chunk-AAHHYDTO.js → chunk-4NF3S3NM.js} +1 -1
- package/dist/chunks/{chunk-AAHHYDTO.js.map → chunk-4NF3S3NM.js.map} +2 -2
- package/dist/chunks/{chunk-2SWRVIYJ.js → chunk-754HA6KO.js} +2 -2
- package/dist/chunks/{chunk-K6DHXXF5.js → chunk-B2IVWASP.js} +2 -2
- package/dist/chunks/{chunk-ZDNGXLEC.js → chunk-B4HECUJI.js} +2 -2
- package/dist/chunks/{chunk-H6DDV6E2.js → chunk-CSJSHBAT.js} +5 -5
- package/dist/chunks/{chunk-MW5VI7IW.js → chunk-D4B4CCTA.js} +2 -2
- package/dist/chunks/{chunk-EDL4JDW7.js → chunk-EBWMC3OO.js} +2 -2
- package/dist/chunks/{chunk-4NUTVNS2.js → chunk-F72MAIQY.js} +31 -368
- package/dist/chunks/chunk-F72MAIQY.js.map +7 -0
- package/dist/chunks/{chunk-W3FRE4VI.js → chunk-FDIEQEXS.js} +2 -2
- package/dist/chunks/{chunk-7A6NVHB5.js → chunk-FJSHRHOR.js} +7 -4
- package/dist/chunks/chunk-FJSHRHOR.js.map +7 -0
- package/dist/chunks/{chunk-PSNXUZMY.js → chunk-G2F2RDZI.js} +5 -47
- package/dist/chunks/chunk-G2F2RDZI.js.map +7 -0
- package/dist/chunks/{chunk-3WIGAX56.js → chunk-JCV54SSP.js} +2 -2
- package/dist/chunks/chunk-KS44WKJJ.js +51 -0
- package/dist/chunks/chunk-KS44WKJJ.js.map +7 -0
- package/dist/chunks/{chunk-3H7SDWZI.js → chunk-LNLQ2LX3.js} +22 -1
- package/dist/chunks/chunk-LNLQ2LX3.js.map +7 -0
- package/dist/chunks/{chunk-G4LADAYY.js → chunk-OINADFEF.js} +8 -3
- package/dist/chunks/chunk-OINADFEF.js.map +7 -0
- package/dist/chunks/{chunk-UQ4LTUH4.js → chunk-OUAC6O5C.js} +36 -9
- package/dist/chunks/chunk-OUAC6O5C.js.map +7 -0
- package/dist/chunks/{chunk-MQG5QKGI.js → chunk-Q5BMTL6A.js} +217 -95
- package/dist/chunks/chunk-Q5BMTL6A.js.map +7 -0
- package/dist/chunks/{chunk-IK6PPFWG.js → chunk-QFKHAAZA.js} +11 -11
- package/dist/chunks/chunk-QFKHAAZA.js.map +7 -0
- package/dist/chunks/{chunk-RTXZHKMS.js → chunk-QNMQJNXE.js} +7 -3
- package/dist/chunks/chunk-QNMQJNXE.js.map +7 -0
- package/dist/chunks/{chunk-U5FYOMG5.js → chunk-UBPFGMDQ.js} +6 -2
- package/dist/chunks/chunk-UBPFGMDQ.js.map +7 -0
- package/dist/chunks/{chunk-FLKGJPCN.js → chunk-ULQFHZJE.js} +4 -1
- package/dist/chunks/chunk-ULQFHZJE.js.map +7 -0
- package/dist/chunks/{chunk-7VAZ4N43.js → chunk-V3PIO7QL.js} +2 -2
- package/dist/chunks/{chunk-MGDLRV2R.js → chunk-VQGO4P7C.js} +2 -2
- package/dist/chunks/{chunk-XT4346N7.js → chunk-WXSELMFV.js} +9 -3
- package/dist/chunks/chunk-WXSELMFV.js.map +7 -0
- package/dist/chunks/{chunk-D5WKZONW.js → chunk-X3IRR7CV.js} +2 -2
- package/dist/chunks/{chunk-IJL3QK3J.js → chunk-Y57UHPIK.js} +1 -1
- package/dist/chunks/{chunk-IJL3QK3J.js.map → chunk-Y57UHPIK.js.map} +1 -1
- package/dist/chunks/{chunk-RKRVOBVO.js → chunk-YC3QQDZ3.js} +2 -2
- package/dist/chunks/{chunk-Q4XJ4PYL.js → chunk-ZRI433JP.js} +299 -83
- package/dist/chunks/chunk-ZRI433JP.js.map +7 -0
- package/dist/chunks/{chunk-36B4AIRT.js → chunk-ZTXZ6JDO.js} +2 -2
- package/dist/commands/fabric.d.ts.map +1 -1
- package/dist/compaction/bounds.d.ts +4 -0
- package/dist/compaction/bounds.d.ts.map +1 -1
- package/dist/compaction/branch-summary.d.ts.map +1 -1
- package/dist/compaction/dialogue.d.ts +24 -0
- package/dist/compaction/dialogue.d.ts.map +1 -0
- package/dist/compaction/hook.d.ts +6 -2
- package/dist/compaction/hook.d.ts.map +1 -1
- package/dist/compaction/hook.js +6 -5
- package/dist/compaction/instructions.d.ts +1 -0
- package/dist/compaction/instructions.d.ts.map +1 -1
- package/dist/compaction/projections.d.ts +3 -3
- package/dist/compaction/projections.d.ts.map +1 -1
- package/dist/compaction/qa.d.ts.map +1 -1
- package/dist/compaction/render.d.ts +11 -0
- package/dist/compaction/render.d.ts.map +1 -1
- package/dist/components/configuration.js +2 -3
- package/dist/components/effect-policy.d.ts +2 -0
- package/dist/components/effect-policy.d.ts.map +1 -1
- package/dist/components/effect-scope.d.ts.map +1 -1
- package/dist/components/supervisor.d.ts +1 -1
- package/dist/components/supervisor.d.ts.map +1 -1
- package/dist/core/action-registry.d.ts +14 -2
- package/dist/core/action-registry.d.ts.map +1 -1
- package/dist/core/action-registry.js +7 -5
- package/dist/core/provider-bindings.d.ts +8 -2
- package/dist/core/provider-bindings.d.ts.map +1 -1
- package/dist/core/provider-operations.d.ts +28 -0
- package/dist/core/provider-operations.d.ts.map +1 -0
- package/dist/core/provider-operations.js +201 -0
- package/dist/core/provider-operations.js.map +7 -0
- package/dist/core/shell-inbox.d.ts +13 -0
- package/dist/core/shell-inbox.d.ts.map +1 -0
- package/dist/core/shell-jobs.d.ts +51 -7
- package/dist/core/shell-jobs.d.ts.map +1 -1
- package/dist/core/shell-limits.d.ts +3 -0
- package/dist/core/shell-limits.d.ts.map +1 -0
- package/dist/core/shell-monitor.d.ts +51 -0
- package/dist/core/shell-monitor.d.ts.map +1 -0
- package/dist/entropy/index.js +8 -7
- package/dist/entropy/normal-form.d.ts.map +1 -1
- package/dist/execution-service.d.ts +1 -1
- package/dist/execution-service.d.ts.map +1 -1
- package/dist/fabric-runtime-state.d.ts +1 -1
- package/dist/fabric-runtime-state.d.ts.map +1 -1
- package/dist/fabric-runtime-state.js +1124 -325
- package/dist/fabric-runtime-state.js.map +4 -4
- package/dist/index.js +155 -44
- package/dist/index.js.map +3 -3
- package/dist/jev/observation.js +5 -3
- package/dist/jev.d.ts +0 -1
- package/dist/jev.d.ts.map +1 -1
- package/dist/jev.js +9 -13
- package/dist/memory/digest.d.ts.map +1 -1
- package/dist/memory/digest.js +2 -1
- package/dist/memory/discovery.js +6 -5
- package/dist/memory/expand-service.d.ts.map +1 -1
- package/dist/memory/file-worker.js +9 -8
- package/dist/memory/file-worker.js.map +1 -1
- package/dist/memory/index.d.ts.map +1 -1
- package/dist/memory/normalize.d.ts.map +1 -1
- package/dist/memory/normalize.js +5 -4
- package/dist/memory/search.js +7 -6
- package/dist/memory/worker-provider.js +10 -9
- package/dist/memory.js +9 -8
- package/dist/memory.js.map +1 -1
- package/dist/mesh/store.d.ts.map +1 -1
- package/dist/prewalk/handoff.d.ts +1 -1
- package/dist/prewalk/handoff.d.ts.map +1 -1
- package/dist/protocol.d.ts +2 -0
- package/dist/protocol.d.ts.map +1 -1
- package/dist/protocol.js +1 -1
- package/dist/providers/jev-provider.d.ts +1 -1
- package/dist/providers/jev-provider.d.ts.map +1 -1
- package/dist/providers/jev-provider.js +9 -7
- package/dist/providers/memory-provider.js +9 -8
- package/dist/providers/pi-tools-provider.d.ts.map +1 -1
- package/dist/providers/tasks-provider.d.ts +12 -0
- package/dist/providers/tasks-provider.d.ts.map +1 -0
- package/dist/residency/host.js +10 -9
- package/dist/residency/pi-entry.js +10 -9
- package/dist/residency/pi-entry.js.map +1 -1
- package/dist/runtime/core-override-guest-types.js +2 -2
- 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/monty-runtime.js +1 -2
- package/dist/runtime/monty-runtime.js.map +1 -1
- package/dist/runtime/typescript-kernel.js +2 -2
- package/dist/runtime-state-builtins.d.ts +1 -1
- package/dist/runtime-state-builtins.d.ts.map +1 -1
- package/dist/schema/controller.d.ts.map +1 -1
- package/dist/state/store.d.ts.map +1 -1
- package/dist/ui/controller.d.ts +1 -0
- package/dist/ui/controller.d.ts.map +1 -1
- package/dist/ui/conversation-targets.js +2 -2
- package/dist/ui/conversation.js +7 -7
- package/dist/ui/dashboard.js +9 -9
- package/dist/ui/highlight.d.ts.map +1 -1
- package/dist/ui/languages/bend.d.ts +4 -0
- package/dist/ui/languages/bend.d.ts.map +1 -0
- package/dist/ui/languages/bend.js +73 -0
- package/dist/ui/languages/bend.js.map +7 -0
- package/dist/ui/settings.js +1 -2
- package/dist/ui/settings.js.map +1 -1
- package/dist/ui/shell-hang-keys.d.ts.map +1 -1
- package/dist/ui/shell-tasks.d.ts +22 -0
- package/dist/ui/shell-tasks.d.ts.map +1 -0
- package/dist/ui/shell-tasks.js +161 -0
- package/dist/ui/shell-tasks.js.map +7 -0
- package/dist/ui/shiki-catalog.d.ts +2 -1
- package/dist/ui/shiki-catalog.d.ts.map +1 -1
- package/dist/ui/snapshot.d.ts.map +1 -1
- package/dist/ui/types.d.ts +1 -0
- package/dist/ui/types.d.ts.map +1 -1
- package/dist/ui/widget.d.ts.map +1 -1
- package/dist/verified/authority.d.ts +17 -0
- package/dist/verified/authority.d.ts.map +1 -0
- package/dist/verified/generated/authority-kernel.d.ts +10 -0
- package/dist/verified/generated/authority-kernel.js +116 -0
- package/dist/verified/generated/kernel.d.ts +31 -0
- package/dist/verified/generated/kernel.js +351 -0
- package/dist/verified/generated/lifecycle-kernel.d.ts +7 -0
- package/dist/verified/generated/lifecycle-kernel.js +155 -0
- package/dist/verified/generated/manifest.json +54 -0
- package/dist/verified/generated/provider-kernel.d.ts +9 -0
- package/dist/verified/generated/provider-kernel.js +80 -0
- package/dist/verified/generated/storage-kernel.d.ts +11 -0
- package/dist/verified/generated/storage-kernel.js +98 -0
- package/dist/verified/memory.d.ts +11 -0
- package/dist/verified/memory.d.ts.map +1 -0
- package/dist/verified/nat.d.ts +2 -0
- package/dist/verified/nat.d.ts.map +1 -0
- package/dist/verified/policy.d.ts +37 -0
- package/dist/verified/policy.d.ts.map +1 -0
- package/dist/verified/resources.d.ts +14 -0
- package/dist/verified/resources.d.ts.map +1 -0
- package/dist/verified/storage.d.ts +32 -0
- package/dist/verified/storage.d.ts.map +1 -0
- package/dist/worker/recovery-watchdog.d.ts +12 -0
- package/dist/worker/recovery-watchdog.d.ts.map +1 -0
- package/dist/worker/recovery-watchdog.js +41 -0
- package/dist/worker/recovery-watchdog.js.map +7 -0
- package/dist/worker.js +70 -20
- package/dist/worker.js.map +2 -2
- package/docs/agents.md +20 -14
- package/docs/architecture.md +1 -1
- package/docs/background-tasks.md +140 -0
- package/docs/compaction.md +91 -28
- package/docs/components.md +5 -1
- package/docs/configuration.md +6 -6
- package/docs/foreman.md +4 -4
- package/docs/harnesses.md +95 -0
- package/docs/interface.md +7 -0
- package/docs/jev.md +59 -52
- package/docs/kernels.md +2 -2
- package/docs/licenses/bend-apache-2.0.txt +202 -0
- package/docs/memory-recall.md +1 -1
- package/docs/programmatic-compaction.md +13 -2
- package/docs/provider-capabilities.md +197 -0
- package/docs/shell-middleware.md +3 -3
- package/docs/skills.md +1 -1
- package/docs/verified-kernels.md +278 -0
- package/package.json +14 -4
- package/proofs/abi.json +308 -0
- package/proofs/authority-abi.json +7 -0
- package/proofs/authority-kernel.bend +23 -0
- package/proofs/authority-proof.bend +74 -0
- package/proofs/authority-spec.bend +30 -0
- package/proofs/authority-state.bend +43 -0
- package/proofs/authority-types.d.ts +3 -0
- package/proofs/kernel.bend +139 -0
- package/proofs/lifecycle-abi.json +3 -0
- package/proofs/lifecycle-kernel.bend +11 -0
- package/proofs/lifecycle-proof.bend +249 -0
- package/proofs/lifecycle-spec.bend +261 -0
- package/proofs/lifecycle-types.d.ts +4 -0
- package/proofs/lifecycle.bend +119 -0
- package/proofs/provider-abi.json +4 -0
- package/proofs/provider-kernel.bend +14 -0
- package/proofs/provider-plans.bend +28 -0
- package/proofs/provider-spec.bend +14 -0
- package/proofs/provider-types.d.ts +5 -0
- package/proofs/resource-proof.bend +633 -0
- package/proofs/resource-spec.bend +133 -0
- package/proofs/resources.bend +160 -0
- package/proofs/state-kernel.bend +17 -0
- package/proofs/state-plans.bend +40 -0
- package/proofs/state-proof.bend +42 -0
- package/proofs/state-spec.bend +26 -0
- package/proofs/storage-abi.json +3 -0
- package/proofs/storage-kernel.bend +11 -0
- package/proofs/storage-plans.bend +100 -0
- package/proofs/storage-proof.bend +176 -0
- package/proofs/storage-spec.bend +70 -0
- package/proofs/storage-types.d.ts +8 -0
- package/proofs/types.d.ts +7 -0
- package/scripts/test-verified-kernels.mjs +107 -0
- package/scripts/verified-kernels.mjs +136 -0
- package/skillsets/python/fabric-jev/SKILL.md +13 -9
- package/skillsets/typescript/fabric-exec/SKILL.md +4 -2
- package/skillsets/typescript/fabric-jev/SKILL.md +13 -9
- package/dist/chunks/chunk-3H7SDWZI.js.map +0 -7
- package/dist/chunks/chunk-3TXOQ5MG.js.map +0 -7
- package/dist/chunks/chunk-4NUTVNS2.js.map +0 -7
- package/dist/chunks/chunk-77PDIBK2.js +0 -129
- package/dist/chunks/chunk-77PDIBK2.js.map +0 -7
- package/dist/chunks/chunk-7A6NVHB5.js.map +0 -7
- package/dist/chunks/chunk-FLKGJPCN.js.map +0 -7
- package/dist/chunks/chunk-G4LADAYY.js.map +0 -7
- package/dist/chunks/chunk-IK6PPFWG.js.map +0 -7
- package/dist/chunks/chunk-MQG5QKGI.js.map +0 -7
- package/dist/chunks/chunk-PSNXUZMY.js.map +0 -7
- package/dist/chunks/chunk-Q4XJ4PYL.js.map +0 -7
- package/dist/chunks/chunk-RTXZHKMS.js.map +0 -7
- package/dist/chunks/chunk-U5FYOMG5.js.map +0 -7
- package/dist/chunks/chunk-UQ4LTUH4.js.map +0 -7
- package/dist/chunks/chunk-XT4346N7.js.map +0 -7
- package/dist/jev/browser.d.ts +0 -37
- package/dist/jev/browser.d.ts.map +0 -1
- package/dist/jev/browser.js +0 -13
- package/dist/jev/browser.js.map +0 -7
- /package/dist/chunks/{chunk-IUCVOZRX.js.map → chunk-3SIXBW6A.js.map} +0 -0
- /package/dist/chunks/{chunk-2SWRVIYJ.js.map → chunk-754HA6KO.js.map} +0 -0
- /package/dist/chunks/{chunk-K6DHXXF5.js.map → chunk-B2IVWASP.js.map} +0 -0
- /package/dist/chunks/{chunk-ZDNGXLEC.js.map → chunk-B4HECUJI.js.map} +0 -0
- /package/dist/chunks/{chunk-H6DDV6E2.js.map → chunk-CSJSHBAT.js.map} +0 -0
- /package/dist/chunks/{chunk-MW5VI7IW.js.map → chunk-D4B4CCTA.js.map} +0 -0
- /package/dist/chunks/{chunk-EDL4JDW7.js.map → chunk-EBWMC3OO.js.map} +0 -0
- /package/dist/chunks/{chunk-W3FRE4VI.js.map → chunk-FDIEQEXS.js.map} +0 -0
- /package/dist/chunks/{chunk-3WIGAX56.js.map → chunk-JCV54SSP.js.map} +0 -0
- /package/dist/chunks/{chunk-7VAZ4N43.js.map → chunk-V3PIO7QL.js.map} +0 -0
- /package/dist/chunks/{chunk-MGDLRV2R.js.map → chunk-VQGO4P7C.js.map} +0 -0
- /package/dist/chunks/{chunk-D5WKZONW.js.map → chunk-X3IRR7CV.js.map} +0 -0
- /package/dist/chunks/{chunk-RKRVOBVO.js.map → chunk-YC3QQDZ3.js.map} +0 -0
- /package/dist/chunks/{chunk-36B4AIRT.js.map → chunk-ZTXZ6JDO.js.map} +0 -0
package/docs/architecture.md
CHANGED
|
@@ -99,7 +99,7 @@ preflight, and callers requiring all final errors to throw should omit `settle`.
|
|
|
99
99
|
|
|
100
100
|
## Model-context economy
|
|
101
101
|
|
|
102
|
-
Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed. Raw media never enters those text channels: image payloads in `fabric_exec` logs, results, and error text, in worker event lines, and in actor host events are replaced by a `{type: "image", mediaIndex, mimeType, redacted: true}` descriptor and hoisted out of band, so a nested `pi.read` image stays available to a multimodal model without pushing hundreds of KB of base64 into one serialized line. A child event line that only exceeds the 4 MB cap because it embeds raw base64 is sanitized
|
|
102
|
+
Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches Pi's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed. Raw media never enters those text channels: image payloads in `fabric_exec` logs, results, and error text, in worker event lines, and in actor host events are replaced by a `{type: "image", mediaIndex, mimeType, redacted: true}` descriptor and hoisted out of band, so a nested `pi.read` image stays available to a multimodal model without pushing hundreds of KB of base64 into one serialized line. A child event line that only exceeds the 4 MB cap because it embeds raw base64 is sanitized to avoid failing the run.
|
|
103
103
|
|
|
104
104
|
## Federated participant topology
|
|
105
105
|
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Background tasks and monitors
|
|
2
|
+
|
|
3
|
+
Fabric-managed `pi.bash` and `pi.powershell` commands have session-owned job IDs.
|
|
4
|
+
`background: true`, the shell hang threshold, or Ctrl+B twice detaches a command;
|
|
5
|
+
an explicit shell `timeout` remains a hard cap. Completed jobs have terminal states
|
|
6
|
+
(`exited`, `failed`, `killed`, `timed_out`), not the old `spilled` state. `exited`
|
|
7
|
+
means exit code zero, not that the user's assignment is verified.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const result = await pi.bash({cmd: "bun run build", background: true, description: "Build bundle"});
|
|
11
|
+
return result; // details.taskId, pid, logPath when detached
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Completion sends a bounded, batched automated event to the **owning Pi session**.
|
|
15
|
+
The same mechanism works inside a Fabric-enabled child: it does not route child
|
|
16
|
+
shell output directly into the parent's Main. No LLM is used to wait for a process.
|
|
17
|
+
Events are outcomes, not user input or approval. Idle wakeups do not compete with
|
|
18
|
+
already queued messages. Aborted/error turns suspend wakeups until new user input;
|
|
19
|
+
branch navigation discards delivery from old-frontier jobs. Session shutdown/reload
|
|
20
|
+
closes the inbox before aborting jobs, so cleanup cannot start a new turn.
|
|
21
|
+
Print-mode processes do not stay alive indefinitely just to receive late events.
|
|
22
|
+
|
|
23
|
+
## Agent awareness and yielding
|
|
24
|
+
|
|
25
|
+
Before each model request, Fabric projects one bounded live-task reminder into
|
|
26
|
+
context, independently of the returned `fabric_exec` value. Even if a program
|
|
27
|
+
discards the nested shell result, the owning agent can see that work is running.
|
|
28
|
+
The reminder is reconstructed from live session state after context compaction;
|
|
29
|
+
it is not a persisted transcript entry and **never triggers a turn** itself.
|
|
30
|
+
Unchanged task state keeps the same message; elapsed time and process output do
|
|
31
|
+
not churn it. It includes at most eight task IDs and short, quoted labels, with
|
|
32
|
+
an omitted count for additional jobs.
|
|
33
|
+
|
|
34
|
+
For ordinary detached commands and wake-enabled monitors, it tells the agent to
|
|
35
|
+
continue independent work or **end the turn if it needs their results**. Completion
|
|
36
|
+
(or a matching monitor event) can resume the owning agent; polling and sleep loops
|
|
37
|
+
are unnecessary. UI-only monitors are explicitly marked **no automatic wakeup**,
|
|
38
|
+
including on completion, so the agent must not yield expecting them to resume it.
|
|
39
|
+
Pending required results are not evidence that the assignment is complete.
|
|
40
|
+
|
|
41
|
+
Foreground, completed, stopping, and abandoned-branch jobs are excluded. Abort/error
|
|
42
|
+
suspension suppresses the reminder until new input, just like automatic delivery.
|
|
43
|
+
Reload/session shutdown removes the context hook along with the inbox. Awareness
|
|
44
|
+
works without a terminal and does not restore processes across Pi restarts.
|
|
45
|
+
|
|
46
|
+
## Inspection and control
|
|
47
|
+
|
|
48
|
+
- `/fabric tasks` or **Ctrl+Alt+T** opens the lazy inspector. A single task opens
|
|
49
|
+
directly. `/fabric tasks <id-or-unique-prefix>` opens a specific task.
|
|
50
|
+
- The widget shows up to three tasks, elapsed time, and the command or short
|
|
51
|
+
description. It stays alive after the Fabric program returns. Completion hints
|
|
52
|
+
expire after 30 seconds; retained jobs remain in the inspector.
|
|
53
|
+
- Enter opens detail; arrows/PageUp/PageDown scroll the bounded output tail; G
|
|
54
|
+
follows the tail; x twice within three seconds stops; Esc backs out/closes.
|
|
55
|
+
- Elapsed time and time since last output are separate. A quiet shell is not
|
|
56
|
+
automatically classified as stuck. Opening/closing the inspector doesn't stop it.
|
|
57
|
+
- `ui.enabled` and `ui.widget` retain their existing meaning. Rendering is TUI-only;
|
|
58
|
+
task tools and notifications do not require a terminal.
|
|
59
|
+
|
|
60
|
+
Tasks are a discoverable provider, **not a new sandbox global**:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
return await tools.call({ref: "tasks.list", args: {}});
|
|
64
|
+
return await tools.call({ref: "tasks.get", args: {id: taskId}});
|
|
65
|
+
return await tools.call({ref: "tasks.stop", args: {id: taskId}});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`get` returns metadata and an 8KB output tail and acknowledges pending agent delivery.
|
|
69
|
+
`stop` targets a stored job's abort controller, never an arbitrary or recycled PID.
|
|
70
|
+
Stopping a task does not wake the agent. Tasks are local to this runtime; IDs and
|
|
71
|
+
live processes are not restored across Pi restarts. Up to 256 completed handles
|
|
72
|
+
are retained for at most 24 hours. Logs use Fabric's private scratch retention.
|
|
73
|
+
The 1MiB in-memory tail and 8MiB disk log limits remain unchanged: a log is **not a
|
|
74
|
+
full-output archive**, and truncation is disclosed.
|
|
75
|
+
|
|
76
|
+
## Programmatic wait and watch
|
|
77
|
+
|
|
78
|
+
For a bounded controller such as `jev.run`/`spawn`, use event-driven task calls:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
const receipt = await tools.call({ref:"tasks.wait",args:{id:taskId,timeoutMs:30000}});
|
|
82
|
+
// For tasks started with monitor (prefer delivery:"ui" for code-owned supervision):
|
|
83
|
+
const batch = await tools.call({ref:"tasks.watch",args:{id:taskId,after:0,timeoutMs:5000}});
|
|
84
|
+
return {receipt,batch};
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- `wait` returns `{task,output,timedOut}`. It waits for terminal metadata, then reads the bounded tail; inspect `task.status` and `task.exitCode`. A successful terminal read acknowledges pending delivery like `get`. A timeout returns the current snapshot, not a failed-process verdict.
|
|
88
|
+
- `watch` requires an opt-in monitor. The launch-time `monitor.match` is the case-sensitive literal filter. It returns `{task,reason,lines,omitted,nextCursor}` when a new batch exists, the task finishes, or the observation ceiling expires. `reason` is `event`, `finished`, or `timeout`; a final event may precede `finished` on the next call.
|
|
89
|
+
- Start `after` at 0; pass the returned `nextCursor` on later calls. Only the latest batch (at most eight previews) is retained. `omitted` counts matching previews lost since the supplied cursor, including intermediate overwritten batches. A cursor from the future is rejected. Truncation markers and monitor filtering/deduplication still apply: this is not a lossless stdout/RPC channel.
|
|
90
|
+
- Defaults: wait 30 seconds, watch 5 seconds; each accepts `timeoutMs` from 1 to 300000. Ready evidence returns immediately. Neither timeout nor cancellation stops or renews the task. Store shutdown rejects pending observations and removes their subscriptions.
|
|
91
|
+
- No polling, inference, or extra wakeups are performed by wait/watch. Ordinary background tasks and wake-enabled monitors retain their existing notification behavior. Main usually yields for those notifications; a controller can use UI-only monitors and wait/watch without a model turn per event.
|
|
92
|
+
- A detached task belongs to the Pi session, not the observing Jev program. Stopping that program cancels its pending wait/watch, not the task. Preserve IDs, set finite process deadlines, and explicitly call `tasks.stop` when required.
|
|
93
|
+
|
|
94
|
+
## Opt-in monitors
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
return await pi.bash({
|
|
98
|
+
cmd: "./scripts/watch-ci.sh", // emits a line only when something interesting changes
|
|
99
|
+
description: "Watch CI",
|
|
100
|
+
monitor: {
|
|
101
|
+
delivery: "wake", // REQUIRED: "ui" or "wake"
|
|
102
|
+
match: "CI:", // optional case-sensitive literal substring, not regex
|
|
103
|
+
timeoutMs: 300000,
|
|
104
|
+
intervalMs: 5000,
|
|
105
|
+
},
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
A monitor implies background execution; `background: false` is rejected. The
|
|
110
|
+
ordinary shell runner, extension hooks, middleware filters, approvals and explicit
|
|
111
|
+
shell timeout still apply. `delivery: "ui"` only updates task inspection, including
|
|
112
|
+
completion; it never wakes the model. `"wake"` additionally delivers coalesced line
|
|
113
|
+
events and completion to the owning agent. Main configures/starts/stops/renews the
|
|
114
|
+
watch, while the process does the polling or subscribes to an external source.
|
|
115
|
+
Unchanged polls require **zero LLM turns** when the script emits nothing.
|
|
116
|
+
|
|
117
|
+
Limits:
|
|
118
|
+
|
|
119
|
+
- Five-minute default lifetime; 1 second minimum, 30 minutes maximum. Expiration
|
|
120
|
+
stops the command and produces one terminal outcome. Renewal is a new explicit
|
|
121
|
+
call; there is no automatic restart or hidden supervisor LLM.
|
|
122
|
+
- At most eight concurrent monitors per session. Output batches are spaced by
|
|
123
|
+
`intervalMs` (1–60 seconds, default 5 seconds). This is a **delivery** interval,
|
|
124
|
+
not the script's polling interval.
|
|
125
|
+
- UTF-8 chunks are framed incrementally. Lines retain their first 2048 characters;
|
|
126
|
+
matching applies to that bounded prefix. Empty lines and adjacent duplicate
|
|
127
|
+
matching lines are suppressed. Events keep at most eight 500-character previews
|
|
128
|
+
per batch; overflow is disclosed. A busy owner receives the newest batch per
|
|
129
|
+
task, not every historical line. Retained raw output is available in the log.
|
|
130
|
+
- Main interruption cancels monitors and suppresses automatic wakeups. Ordinary
|
|
131
|
+
detached commands retain their existing lifetime; their outcomes wait for input.
|
|
132
|
+
- Events and output are untrusted data. `wake` can incur model turns; use `ui` for
|
|
133
|
+
human-only observation and emit only meaningful changes for agent-facing watches.
|
|
134
|
+
|
|
135
|
+
Opaque captured shell overrides do not gain Fabric monitors: Fabric must not bypass
|
|
136
|
+
an SSH backend or security gate. Compatible [bash middleware](shell-middleware.md)
|
|
137
|
+
keeps its filtering/protection. PowerShell monitors require the host's tracked shell
|
|
138
|
+
operations API. The tasks provider is installed with the native Pi provider in full
|
|
139
|
+
code mode (and schema enforce, whose authorization rules still apply), not in
|
|
140
|
+
orchestration-only mode or closed-world managed hosts.
|
package/docs/compaction.md
CHANGED
|
@@ -64,18 +64,18 @@ defers overflow and manual compactions.
|
|
|
64
64
|
5. **Serialization is deterministic and bounded.** Identical branch entries and instructions produce byte-identical output. The rendered result is at most 32 KiB in UTF-8.
|
|
65
65
|
6. **The nominal model window is the safety boundary.** Fabric never treats it as a target to fill. Fabric calibrates Pi's structural token estimate against `preparation.tokensBefore`, retains the largest closure-safe suffix within Pi's bounded `keepRecentTokens` continuity budget, and treats the configured occupancy ratio, Pi response reserve, estimator-error margin, and pre-compaction size as hard ceilings. Undocumented provider headroom never enters the budget.
|
|
66
66
|
|
|
67
|
-
These invariants prevent summary-chain drift
|
|
67
|
+
These invariants prevent compounding summary-chain drift, not all semantic
|
|
68
68
|
forgetting. Pi replaces the previous rendered summary on each compaction.
|
|
69
|
-
Fabric
|
|
70
|
-
addresses, error state
|
|
71
|
-
|
|
69
|
+
Fabric re-derives recent dialogue, historical requests, cumulative successful
|
|
70
|
+
file addresses, and error state from raw branch history every time. The
|
|
71
|
+
protected dialogue window is bounded continuity, not permanent decision memory.
|
|
72
72
|
|
|
73
73
|
## Loss model and memory
|
|
74
74
|
|
|
75
75
|
Fabric compaction is **source-lossless and addressably lossless**. The model's bounded continuation view does not stay byte-for-byte lossless:
|
|
76
76
|
|
|
77
77
|
- Compaction appends a marker. It never deletes or rewrites raw session JSONL. The active parent-linked session branch remains ground truth.
|
|
78
|
-
- The model receives a bounded deterministic projection plus the recent raw continuity tail. Fabric preserves
|
|
78
|
+
- The model receives a bounded deterministic projection plus the recent raw continuity tail. Fabric preserves role-labelled recent dialogue, historical requests, declared Fabric run intent paired with aggregate outcomes, file operations, failures, status, and stable addresses through mechanical rules. Arbitrary old prose, tool-output bodies, and thinking may fall out of the inline view.
|
|
79
79
|
- Every sampled omission records a count and source entry-id range. `memory.expand` can re-read exact untruncated source by stable entry ID or operation address with source-hash and lineage checks.
|
|
80
80
|
- The memory index remains derived and disposable. Compaction works without successful indexing, and it never treats an incomplete index as ground truth. Exact expansion reads session JSONL.
|
|
81
81
|
|
|
@@ -92,7 +92,8 @@ active branch entries ─┬─► live window ─► calibrated token budget
|
|
|
92
92
|
```
|
|
93
93
|
|
|
94
94
|
- `normalize.ts` converts raw message and top-level `custom_message` entries to typed events. It selects custom content only from typed string or text parts, keeps JSON details depth/node/collection/string/byte bounded, and omits malformed details while otherwise valid content stays. Assistant thinking parts count as deliberation, so normalization never turns them into events. Summaries carry side effects and state, and truncated scratchpad text that could read as fact stays out. The compactor records how many thinking blocks it erased, so the omission stays auditable. Only `toolCallId` pairs each tool call with its result. A completed `fabric_exec` with a non-empty typed `display.name` contributes a bounded declared-intent event that carries its optional `display.description`, aggregate outcome, and call address. A `fabric_exec` result contributes nested events only through a valid `details.trace` V1 guard, or through the separate strict legacy `details.audits` adapter when no `trace` field exists.
|
|
95
|
-
- `
|
|
95
|
+
- `dialogue.ts` selects the last three eligible user exchanges and their preceding text-bearing assistant responses, independent of tool-event volume. Fully raw exchanges are excluded before the three-exchange limit; summarized and crossing exchanges remain eligible. It joins text parts from the same assistant entry, excludes thinking, and bounds complete multiline excerpts with explicit omitted-byte markers. It never infers acceptance or supersession from prose.
|
|
96
|
+
- `projections.ts` computes protected dialogue, historical request, file, operation-state, turn, status, and transcript views.
|
|
96
97
|
- `enrichers.ts` permits deterministic optional annotations. Fabric ships no built-in enrichers.
|
|
97
98
|
- `render.ts` independently bounds every rendered block and enforces the global UTF-8 limit.
|
|
98
99
|
- `hook.ts` computes the live cut, selects cumulative source, emits v2 details, and implements Pi/pi-vcc precedence.
|
|
@@ -126,25 +127,61 @@ boundary fits, Fabric uses compact-all (`firstKeptEntryId: ""`), and no kept
|
|
|
126
127
|
side remains to orphan either half. If the rendered deterministic summary
|
|
127
128
|
itself would push the calibrated projection over the target, Fabric cancels
|
|
128
129
|
the compaction to avoid persisting an expanding or over-budget result. If
|
|
129
|
-
model metadata is unavailable, the legacy
|
|
130
|
-
|
|
130
|
+
model metadata is unavailable, Fabric keeps the legacy closure-safe whole-turn
|
|
131
|
+
cut only when that tail fits `keepRecentTokens` (20,000 by default). Oversized
|
|
132
|
+
turns use the same bounded suffix selector, including assistant boundaries;
|
|
133
|
+
if no legal suffix fits, Fabric compacts everything. Preparation settings
|
|
134
|
+
still apply without a model window. This fallback emits no fabricated model
|
|
135
|
+
window or calibrated budget metadata. Its bound is on structural raw-tail
|
|
136
|
+
estimates plus the bounded summary, not unknown fixed provider overhead.
|
|
131
137
|
|
|
132
138
|
The live cut determines only what Pi keeps. The summary source is the raw
|
|
133
139
|
active-branch prefix before that new boundary. Normalization skips earlier
|
|
134
|
-
compaction and branch-summary prose within that prefix.
|
|
140
|
+
compaction and branch-summary prose within that prefix. For dialogue selection
|
|
141
|
+
only, Fabric also reads user/assistant text in the kept tail. If an exchange
|
|
142
|
+
crosses the cut, its summarized assistant response stays inline and its user
|
|
143
|
+
reply is addressed as `retained raw`, without duplicating the reply. Fully raw
|
|
144
|
+
exchanges need no summary copy and do not consume protected-window slots.
|
|
145
|
+
Newer raw instructions still take precedence over earlier summarized context.
|
|
146
|
+
This does not change cut selection.
|
|
147
|
+
|
|
148
|
+
Compacted trajectory handoffs use the resolved destination model window,
|
|
149
|
+
Fabric occupancy ceiling, and Pi's destination-specific compaction settings
|
|
150
|
+
when available. Settings are read at handoff use, respecting project trust.
|
|
151
|
+
Source-model usage does not calibrate a new executor; its budget uses structural
|
|
152
|
+
estimates until target usage exists. The finalized outer tool result and any
|
|
153
|
+
thinking-transfer digest enter the child log before compaction, so neither
|
|
154
|
+
escapes the cut and the outer call/result pair remains closure-safe. A failed
|
|
155
|
+
requested handoff compaction rejects the handoff and prevents the
|
|
156
|
+
uncompacted fork from launching. Without destination metadata, the bounded fallback applies.
|
|
135
157
|
|
|
136
158
|
## Bounded sections
|
|
137
159
|
|
|
138
|
-
Fabric
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
160
|
+
Fabric leads with protected recent dialogue, then explicit compaction requests
|
|
161
|
+
and historical requests. Each of the last three eligible summarized or
|
|
162
|
+
cross-boundary user exchanges gets up to 3968 bytes including role/address
|
|
163
|
+
headings. User text gets at least half the available text budget when needed;
|
|
164
|
+
short replies leave room for the preceding assistant response. Complete
|
|
165
|
+
multiline text survives whenever the exchange fits. Assistant replies are
|
|
166
|
+
labelled **Historical assistant response (not a verified outcome)**: they may
|
|
167
|
+
contain proposals, explanations, or old progress reports, not necessarily
|
|
168
|
+
current state or accepted instructions. New eligible exchanges can age an
|
|
169
|
+
exchange out; fully raw exchanges and more tool events alone cannot. There is
|
|
170
|
+
no reset keyword detector or task ledger.
|
|
171
|
+
|
|
172
|
+
Historical requests, files, operation-state, and earlier-turn collections still
|
|
173
|
+
use deterministic earliest-plus-latest sampling. Sampled omissions record a
|
|
174
|
+
count and source entry-id range. Protected excerpts instead report omitted
|
|
175
|
+
UTF-8 bytes alongside their entry addresses. Historical requests are evidence
|
|
176
|
+
of earlier instructions, not a reconstructed active mandate.
|
|
177
|
+
|
|
178
|
+
Rendered block ceilings include their headers. Historical blocks may receive
|
|
179
|
+
less under shared-budget pressure:
|
|
180
|
+
|
|
181
|
+
| Block | UTF-8 ceiling |
|
|
146
182
|
| --- | ---: |
|
|
147
|
-
| `[
|
|
183
|
+
| `[Recent user directions and discussion]` | 12288 bytes |
|
|
184
|
+
| `[Historical requests]` | 4096 bytes |
|
|
148
185
|
| `[Compaction Request]` | 3072 bytes |
|
|
149
186
|
| `[Files And Changes]` | 4608 bytes |
|
|
150
187
|
| `[Fabric Activity]` | 2048 bytes |
|
|
@@ -154,16 +191,25 @@ Rendered block limits include their headers:
|
|
|
154
191
|
| collapsed transcript | 5120 bytes |
|
|
155
192
|
| footer | 1536 bytes |
|
|
156
193
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
194
|
+
These ceilings are not simultaneous reservations. Fabric renders protected
|
|
195
|
+
dialogue and explicit requests first, then subtracts their actual UTF-8 size,
|
|
196
|
+
the footer, separators, and final newline from the unchanged 32 KiB ceiling.
|
|
197
|
+
Historical blocks keep their former ceilings whenever their capped content
|
|
198
|
+
fits the remaining space. Only under pressure are they reduced proportionally
|
|
199
|
+
to demand, reserving headers/omission markers or complete single-line blocks; sampling
|
|
200
|
+
slack passes to later blocks. Small or absent dialogue therefore does not
|
|
201
|
+
unconditionally shrink operational history. The raw-tail budget is unchanged,
|
|
202
|
+
and a final UTF-8 guard remains in place. Projection limits stay finite: three
|
|
203
|
+
eligible recent exchanges, 24 historical requests, 24 file addresses per
|
|
204
|
+
operation kind, 32 operation-state records, 48 Fabric activity records, 32
|
|
205
|
+
earlier turns, and 40 transcript events. Omitted source
|
|
161
206
|
remains executable-addressable through entry-id ranges and the footer recall
|
|
162
207
|
pointer.
|
|
163
208
|
|
|
164
209
|
## Sections
|
|
165
210
|
|
|
166
|
-
- **
|
|
211
|
+
- **Recent user directions and discussion**: complete bounded user/preceding-assistant exchanges, with roles and entry IDs. This is source evidence, not an inferred current-goal declaration.
|
|
212
|
+
- **Historical requests**: sampled older user requests, including the original objective once it leaves the recent window. The internal `goal` omission key remains for v2 compatibility.
|
|
167
213
|
- **Compaction Request**: canonicalized, bounded custom instructions. See below.
|
|
168
214
|
- **Files And Changes**: successful typed file-tool addresses grouped as Created, Written, Modified, or Read. `edit` counts as Modified. `write` counts as Written unless a typed result explicitly proves creation.
|
|
169
215
|
- **Fabric Activity**: completed named `fabric_exec` runs as bounded `name → outcome` records that place an em dash between the name and the optional description, followed in source order by phases and significant non-file nested operations, including bash, agents, workflow, mesh, state, MCP, and extension refs. Named runs expose the exact assistant call entry ID while sourced raw, and their typed fact address after branch rehydration. Nested phases and operations expose stable `entryId/subordinal` addresses. The name and outcome are mandatory for a rendered run. The optional description decays first under tighter views.
|
|
@@ -183,7 +229,7 @@ through a valid typed `preserve` item or another typed state transition.
|
|
|
183
229
|
The clean core retains only these mechanical text operations:
|
|
184
230
|
|
|
185
231
|
- select text from typed user, assistant, top-level custom-message, tool-result, Fabric display-name/description, command-argument, error, phase, ref, and path fields.
|
|
186
|
-
-
|
|
232
|
+
- join text parts belonging to one assistant entry; retain multiline dialogue text or select the first line for historical one-line views.
|
|
187
233
|
- trim/collapse whitespace and truncate by fixed character or UTF-8 byte limits.
|
|
188
234
|
- quote bounded user/custom/assistant/tool/error text without interpreting its content.
|
|
189
235
|
- compare typed action/path, action/command, or ref/JSON-arguments identities exactly for resolution.
|
|
@@ -224,6 +270,14 @@ validates scalar grammar and surrogate pairing. It checks the preserve count
|
|
|
224
270
|
before it iterates or canonicalizes values. Plain Pi and manual instructions
|
|
225
271
|
stay explicit bounded text and never run through the typed protocol parser.
|
|
226
272
|
|
|
273
|
+
Request rendering preserves complete items when they fit the 3 KiB block; it
|
|
274
|
+
does not apply the historical 1024-byte line cap or drop middle items. If the
|
|
275
|
+
block overflows, every item receives a bounded excerpt and explicit byte-loss
|
|
276
|
+
marker. `instructionPolicy.truncated` includes rendering loss, and
|
|
277
|
+
`renderedOmittedBytes` measures it separately from decoder truncation.
|
|
278
|
+
`preserve` remains one-shot input to that compaction, not a durable pin.
|
|
279
|
+
Neither `state.goal` nor state transitions are consulted to infer task intent.
|
|
280
|
+
|
|
227
281
|
## Compaction details v2
|
|
228
282
|
|
|
229
283
|
New summaries emit `details.compactor: "fabric"` and `details.version: 2` with:
|
|
@@ -232,7 +286,8 @@ New summaries emit `details.compactor: "fabric"` and `details.version: 2` with:
|
|
|
232
286
|
- branch, source-entry, event, and live-cut counts.
|
|
233
287
|
- prior recognized Fabric v1/v2 marker counts.
|
|
234
288
|
- per-projection omission counts, the typed preserve count (valid v1 requests cannot exceed the preserve limit), and the structural count of erased assistant thinking blocks.
|
|
235
|
-
- instruction mode, canonicalization, source size, truncation, and preserve counts.
|
|
289
|
+
- instruction mode, canonicalization, source size, decoder/rendering truncation, rendered omitted bytes, and preserve counts.
|
|
290
|
+
- `omittedCounts.dialogueBytes` for protected dialogue clipping (UTF-8 bytes, not event count). These additive fields are optional when reading older v2 records.
|
|
236
291
|
- stable kept/source entry-id addresses and the source timestamp.
|
|
237
292
|
- when continuity budgeting is active: effective window, occupancy ceiling ratio/tokens, continuity target, reserve and reduction ceilings, the binding constraint, Pi reserve/recent settings, raw estimate, calibration scale, fixed overhead, raw-tail budget, retained raw tokens, and Fabric's `projectedTokensAfter`. Pi core independently recomputes its own `estimatedTokensAfter` after persisting the compaction. Legacy v2 records with `strategy: "adaptive"` remain recognized.
|
|
238
293
|
|
|
@@ -304,7 +359,10 @@ never reads branch summary prose. Later compaction can then resolve
|
|
|
304
359
|
abandoned-branch failures against later exact successes, and custom context, files, and
|
|
305
360
|
activity survive navigation or forks without any prose parsing. Pi supplies
|
|
306
361
|
only the active path or the abandoned `entriesToSummarize` path to each
|
|
307
|
-
compiler, so sibling branches cannot contaminate one another.
|
|
362
|
+
compiler, so sibling branches cannot contaminate one another. Branch rendering
|
|
363
|
+
also protects dialogue available in that supplied path, but the existing typed
|
|
364
|
+
branch envelope does not carry arbitrary assistant responses. This patch does
|
|
365
|
+
not extend decision retention across abandoned branches lacking raw dialogue.
|
|
308
366
|
|
|
309
367
|
## pi-vcc precedence
|
|
310
368
|
|
|
@@ -336,10 +394,15 @@ from rendered sections. QA probes follow the same bounded sampling policy as
|
|
|
336
394
|
projections. The report checks directly rendered samples for content, and it
|
|
337
395
|
validates omitted collections for count and range addressability. Mutation tests
|
|
338
396
|
remove file, error, turn, latest Fabric run intent/outcome/address, and footer
|
|
339
|
-
information to verify that the report detects loss.
|
|
397
|
+
information to verify that the report detects loss. Additional source-derived
|
|
398
|
+
probes require complete bounded, role-labelled recent dialogue excerpts: losing
|
|
399
|
+
a later architecture paragraph, constraint, estimate, or user selection fails
|
|
400
|
+
QA even when historical activity and recall pointers survive. When checking a
|
|
401
|
+
split exchange, pass all normalized events and the summarized-prefix cut index
|
|
402
|
+
so QA can see the retained user reply as well.
|
|
340
403
|
|
|
341
404
|
Run:
|
|
342
405
|
|
|
343
406
|
```sh
|
|
344
|
-
|
|
407
|
+
bunx vitest run tests/compaction-qa.test.ts tests/compaction-dialogue.test.ts
|
|
345
408
|
```
|
package/docs/components.md
CHANGED
|
@@ -140,6 +140,10 @@ Declare instances at the root of `fabric.json`:
|
|
|
140
140
|
|
|
141
141
|
A definition may arrive after the configuration that references it. The unresolved instance stays `waiting` and lists `component:<name>` in `missing`. Component discovery activates the instance later. Once the runtime is active, trusted configuration edits reconcile automatically; `/fabric reload` is not required. When a later activation fails during a multi-entry reconciliation, Fabric rolls back the additions and replacements from that pass. Two live component records may never declare the same provider name. Fabric rejects the insertion or replacement before it disturbs either fiber.
|
|
142
142
|
|
|
143
|
+
### External connectors
|
|
144
|
+
|
|
145
|
+
Connector packages own their component definitions, provider schemas, transports, credentials, and model-facing guidance. Fabric has no connector-specific registration table or required UI action vocabulary. Install the connector's ordinary Pi extension: it registers through `FABRIC_COMPONENT_REGISTER_EVENT` and answers `FABRIC_COMPONENT_DISCOVER_EVENT`. Configure it with the same generic `components.describe` / `plan` / `apply` surface used by every other component. A configured but undiscovered definition remains `waiting`; configuration never imports arbitrary modules on its own. These generic extension contracts remain available, but existing browser/macOS CLIs do not require a component bridge; see [harness CLI composition and migration](harnesses.md).
|
|
146
|
+
|
|
143
147
|
### Live configuration control
|
|
144
148
|
|
|
145
149
|
Components are generic host primitives. Connector packages own browser, desktop, application, and transport behavior; neither component management nor Jev needs a built-in tool for each integration. Register the definition through the ordinary extension protocol, then configure instances through the same live control plane.
|
|
@@ -162,7 +166,7 @@ await components.apply({ ...plan.request, expectedRevision: plan.revision });
|
|
|
162
166
|
- Apply runs the loader transaction before persistence. A failed activation leaves disk untouched. A failed compare-before-write triggers runtime compensation, without overwriting the external edit. Failed compensation is reported, never claimed successful. This is not an atomic transaction across multiple processes, files, or remote effects.
|
|
163
167
|
- `components.reconcile()` re-reads trusted files without reinitializing Fabric. The active runtime also watches both file paths (250 ms stat interval, 50 ms debounce), including file creation, deletion, and atomic replacement. Content revisions suppress redundant reconciliation. The watcher reads only trusted layers and never repairs or quarantines malformed live files. Invalid edits retain the last applied state and appear in `components.list().configuration.error` and the UI. Its watchers and timers stop with the owning runtime.
|
|
164
168
|
- Before first use, bootstrap stays idle: no watcher imports optional engines or starts connectors. First use rereads component configuration. Activation does not imply that a connector has connected or requested OS permissions; connector packages own explicit, lazy acquisition and health reporting.
|
|
165
|
-
- `components.list().configuration` reports source paths, trust, selected layers, session override IDs, and warnings. An untrusted project file is reported as ignored without parsing it. Diagnostics report provenance
|
|
169
|
+
- `components.list().configuration` reports source paths, trust, selected layers, session override IDs, and warnings. An untrusted project file is reported as ignored without parsing it. Diagnostics report provenance, not raw configuration documents; activation errors remain author-supplied.
|
|
166
170
|
- Apply/reconcile are host-control operations, unavailable to committed guest views and in managed hosts or Schema enforce mode. Existing approval and schema policy gates still apply. Built-in `fabric.provider.*` components cannot be changed by this configuration API; their existing reload control remains separate.
|
|
167
171
|
|
|
168
172
|
Replacement uses the existing retire-before-activate path, not zero-downtime migration. New calls resolve the new generation after commit; unrelated providers and Jev runs are not restarted. Existing committed views may continue using the retired generation until release. Removal uses the same **drain** policy, not immediate security revocation. Owners must retain supporting connections/processes until provider `close()`. Connector session IDs and observed handles must not be silently moved between generations. Cancellation after activation begins does not abandon commit/compensation and cannot undo already-issued external effects.
|
package/docs/configuration.md
CHANGED
|
@@ -203,13 +203,13 @@ where absent values do not participate. Orchestration programs (`agents.run` / `
|
|
|
203
203
|
|
|
204
204
|
`jev` configures TypeSafe typed judgments and session-owned foreground/background programs. It is enabled by default but makes no inference requests until called. `/login jev` stores API-key credentials through Pi; `TYPESAFE_API_KEY` and an explicitly configured `jev.credentialCommand` argv are also supported. Bare `jev.model` aliases use TypeSafe; `typesafe/...` or `~typesafe/...` model IDs use OpenRouter's decisions endpoint with the existing `openrouter` credential (`/login openrouter`, `OPENROUTER_API_KEY`, or `TYPESAFE_OPENROUTER_API_KEY`); `typesafe-ai/...` model IDs use Vercel AI Gateway's TypeSafe-compatible endpoint with the existing `vercel-ai-gateway` credential (`/login vercel-ai-gateway` or `AI_GATEWAY_API_KEY`). Never store the resolved secret in `fabric.json`.
|
|
205
205
|
|
|
206
|
-
Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTokens`, `maxConcurrentRuns`, and `maxRetainedRuns`. Request controls are `model`, `requestTimeoutMs`, and `maxRequestBytes`. Per-program limits cannot raise these ceilings. See [Jev programs](jev.md) for
|
|
206
|
+
Host ceilings include `maxDurationMs`, `maxEvaluations`, `maxToolCalls`, `maxTokens`, `maxConcurrentRuns`, and `maxRetainedRuns`. Request controls are `model`, `requestTimeoutMs`, and `maxRequestBytes`. Per-program limits cannot raise these ceilings. Per-program `maxEvaluations: 0` disables program inference for deterministic shell orchestration. See [Jev programs](jev.md) for typed decisions, shell/task composition, and cancellation; harness CLIs need no component configuration. Jev is unavailable in Schema enforce and managed-host modes.
|
|
207
207
|
|
|
208
208
|
## Components
|
|
209
209
|
|
|
210
210
|
`components` is a root array of declarative supervised instances. Each `id` gives one instance a stable identity, and `component` names its definition in the versioned protocol. Fabric passes `config` to `activate(context, config)`. The `disabled` field removes an instance from the active graph and preserves its declaration. An empty array is the default, with a limit of 256 valid entries. The runtime installs enabled first-party providers as pinned `fabric.provider.*` components whose reserved IDs sit outside this array.
|
|
211
211
|
|
|
212
|
-
Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. Once the runtime is active, trusted file edits reconcile automatically without `/fabric reload`; idle bootstrap remains lazy and first use rereads the component configuration. Invalid live edits keep the last working state and are never repaired or renamed by the watcher. `components.describe`, `components.plan`, `components.apply`, and `components.reconcile` provide the same control plane to programs. Changes default to session scope; global/project persistence is explicit, and untrusted project writes are rejected
|
|
212
|
+
Unknown definitions stay visible as waiting. They do not fail the Fabric runtime. Late discovery activates them. Once the runtime is active, trusted file edits reconcile automatically without `/fabric reload`; idle bootstrap remains lazy and first use rereads the component configuration. Invalid live edits keep the last working state and are never repaired or renamed by the watcher. `components.describe`, `components.plan`, `components.apply`, and `components.reconcile` provide the same control plane to programs. Changes default to session scope; global/project persistence is explicit, and untrusted project writes are rejected, never redirected. Project component arrays replace global arrays; session overrides apply by ID on top. Definitions may declare `configSchema` for pre-activation validation. When a definition re-registers with `overwrite: true`, Fabric uses the same rollback-capable replacement path. See [components, effects, and committed capabilities](components.md#live-configuration-control).
|
|
213
213
|
|
|
214
214
|
## Speculation
|
|
215
215
|
|
|
@@ -239,7 +239,7 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
|
|
|
239
239
|
|
|
240
240
|
`prewalk.thinking` sets the optional reasoning effort for the trajectory child executor. Its values are `off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`, clamped to each model's supported levels. When you leave it unset, the executor inherits `agents.thinking`. In-place mode keeps Main's session level.
|
|
241
241
|
|
|
242
|
-
`prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion); a failed in-place return drops the arm
|
|
242
|
+
`prewalk.alwaysRearm` defaults to `false`. When enabled, prewalk returns to an armed, taskless state after each completed handoff (in-place return or trajectory completion); a failed in-place return drops the arm without completing it. Every Main session then starts armed automatically, non-interactively from `prewalk.model`, and `/fabric reload` re-arms Main as well. Child agents and actors never auto-arm from inherited settings; explicit arming is unaffected. `/fabric prewalk --off` cancels the armed state until the next session start or reload. Turns that settle without a handoff never disarm prewalk, regardless of this setting. The settings UI labels an unset model **Ask each time**. Non-interactive sessions must configure a model. In-place mode does not require child agents. Trajectory mode requires `agents.enabled`. It shows child spawn, progress, nested tools, metrics, and completion in Main's Fabric activity UI.
|
|
243
243
|
|
|
244
244
|
`prewalk.detectShellWrites` defaults to `true`. When armed, a `fabric_exec` boundary that ran a successful `pi.bash` or `pi.powershell` without an audited `pi.edit` / `pi.write` / `schema.commit` claims the handoff if file size or mtime stats drifted from the arm-time baseline. This routes shell heredocs and formatter binaries to the executor as well. The report's `trigger.files` lists the bounded drifted paths. An audited mutation consumes the shell-write drift window, so earlier edits cannot re-fire on a later read-only shell boundary. Fabric's own state directory never registers and does not consume the tracked-file cap. Other tool directories follow the project's ignore rules, so a Git work tree excludes them through `.gitignore`. Set this option to `false` to accept audited mutations only.
|
|
245
245
|
|
|
@@ -247,7 +247,7 @@ Unknown definitions stay visible as waiting. They do not fail the Fabric runtime
|
|
|
247
247
|
|
|
248
248
|
`prewalk.compactOnReturn` defaults to `true`. When an in-place continuation settles, Fabric requests a compaction with the configured `compaction.engine` and commits it while the executor is still the active model. Main's restored model receives the compacted transcript. Set this option to `false` when Main must receive the complete transcript.
|
|
249
249
|
|
|
250
|
-
Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. A process that restarts while a continuation is still pending restores that captured model from the persisted continuation at the next session start, before the session auto-arms. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too. When the return itself fails, the arm is dropped
|
|
250
|
+
Each in-place handoff captures Main's active model at the boundary and restores it when the continuation settles, when a new session is still on the executor, and when prewalk is cancelled (`/fabric prewalk --off` / `--disable`) or reloaded. A process that restarts while a continuation is still pending restores that captured model from the persisted continuation at the next session start, before the session auto-arms. Pi's public `setModel` extension API may also update the session model that a later session inherits, so restoring the captured Main model repairs that too. When the return itself fails, the arm is dropped, not re-armed and the failure is reported: the captured Main model is preserved so a later session start or `/fabric reload` retries the return, auto-arm is skipped while Main is still on the executor, and an explicit `/fabric prewalk` arm overrides.
|
|
251
251
|
|
|
252
252
|
## Models
|
|
253
253
|
|
|
@@ -410,7 +410,7 @@ The host asks four typed Noul questions in one request: whether the exact action
|
|
|
410
410
|
|
|
411
411
|
Lower thresholds permit more actions. **0 allows every valid judgment whose secrets and destructive verdicts are clean**, while 1 requires a safety probability of 1; a secrets or destructive probability at or above 0.5 escalates regardless of threshold, and so do missing user text, malformed answers, and errors. Reasons report the four numeric judgments and the effective threshold, not generated explanations. This is a policy cutoff, **not a calibrated security guarantee**. Use `ask` or `deny` when a probabilistic advisor is inappropriate.
|
|
412
412
|
|
|
413
|
-
Jev receives the exact bounded arguments, the **latest user message and subsequent assistant tool calls**, and a bounded projection of earlier session actions - direct tool calls and nested Fabric actions with their arguments, host-recorded failures marked `"ok":false`. Earlier turns' prose, thinking, images, and tool outputs are excluded, so vague follow-ups cannot borrow authority from omitted history and retrieved content cannot instruct the classifier. Missing user text still requires explicit approval without inference. Oversized arguments, transcript clipping, and projection limits are disclosed to Jev as `evidence`/`session.truncated` facts
|
|
413
|
+
Jev receives the exact bounded arguments, the **latest user message and subsequent assistant tool calls**, and a bounded projection of earlier session actions - direct tool calls and nested Fabric actions with their arguments, host-recorded failures marked `"ok":false`. Earlier turns' prose, thinking, images, and tool outputs are excluded, so vague follow-ups cannot borrow authority from omitted history and retrieved content cannot instruct the classifier. Missing user text still requires explicit approval without inference. Oversized arguments, transcript clipping, and projection limits are disclosed to Jev as `evidence`/`session.truncated` facts without aborting classification (16,000 argument characters, 6,000 per user message/tool-call batch, 24,000 total evidence characters, 12,000 session-projection characters). Starting a new explicit user turn resets the conversational evidence window; the session-action projection spans the session.
|
|
414
414
|
|
|
415
415
|
Selecting this remote classifier authorizes sending that evidence to TypeSafe; it can contain private paths, code, or values from tool arguments. Do not select it for data that must stay local. Classification is a host-side request, not a recursive `jev.evaluate` tool call, so it does not recursively invoke the network approval policy. Normal tool permissions still apply after classification. Missing auth, malformed answers, HTTP errors, cancellation and timeouts never fall back to another model or auto-allow. They use the existing explicit approval flow (or deny in headless mode).
|
|
416
416
|
|
|
@@ -428,7 +428,7 @@ Run housekeeping begins on actual agent storage use (not manager startup), conti
|
|
|
428
428
|
|
|
429
429
|
### Temporary output and reader scratch
|
|
430
430
|
|
|
431
|
-
New model-output spills and shell logs use private directories with a versioned `.fabric-scratch.json` ownership marker. They expire 24 hours after completion; oldest eligible caches may be removed sooner above **128 MiB or 256 items**, pooled across these two classes. Completed output is protected for its first hour. These aggregate limits are **soft** while files are active/recent or cannot be safely attributed. Model-output artifacts remain complete (not truncated)
|
|
431
|
+
New model-output spills and shell logs use private directories with a versioned `.fabric-scratch.json` ownership marker. They expire 24 hours after completion; oldest eligible caches may be removed sooner above **128 MiB or 256 items**, pooled across these two classes. Completed output is protected for its first hour. These aggregate limits are **soft** while files are active/recent or cannot be safely attributed. Model-output artifacts remain complete (not truncated). Their links are temporary.
|
|
432
432
|
|
|
433
433
|
Shell hang tracking keeps a **1 MiB RAM tail per running command**, then releases it on finish. Completed handles are capped at **256** and expire after 24 hours on subsequent store access. Each shell log is capped at **8 MiB including notices**; it starts with the retained pre-spill tail, not necessarily the command's beginning. The returned notice and log header explicitly say this is bounded, **not a full-output archive**; reaching the disk cap appends a truncation notice. Further output continues to the normal shell consumer but not the log. PID files are retired on finish; logs remain subject to the cache policy. A disk write error also stops logging without interrupting command execution; bounded logs never promise completeness.
|
|
434
434
|
|
package/docs/foreman.md
CHANGED
|
@@ -13,12 +13,12 @@ Fabric already has the required primitives for **session-bound, lifecycle-driven
|
|
|
13
13
|
| Independent long-running controller with local state | `jev.spawn`, `JevProgramManager` in `src/jev/manager.ts` | One persistent QuickJS program; Main does not wait. Session-owned, not restart-durable. |
|
|
14
14
|
| Observe coding progress at a decision point | `observe.events`, `program.nextEvent()`, `JevObservationHost` in `src/jev/observation.ts` | `turn_end` and `agent_settled` are the same local event names used by actors; no polling required. |
|
|
15
15
|
| Bounded observation, history, and instruction evidence | Explicit `observe.include`, queue/age/character bounds; schema-bounded program input and local history | Settlement itself carries no transcript. Cache opted-in turn evidence; never assume hidden history access. Repository instructions are an explicitly supplied snapshot. |
|
|
16
|
-
| Ten parallel semantic questions | One `jev.evaluate` request with ten `noul` questions; `src/jev/client.ts` validates answers | Implementation, tests, requirements, verification, readiness, progress, stuck, off-track, instruction drift, and human need. Code
|
|
16
|
+
| Ten parallel semantic questions | One `jev.evaluate` request with ten `noul` questions; `src/jev/client.ts` validates answers | Implementation, tests, requirements, verification, readiness, progress, stuck, off-track, instruction drift, and human need. Code selects actions; Jev does not. |
|
|
17
17
|
| Continue, steer, or request another pass | `program.advise` / `jev.advise` with `steer` or `followUp` and explicit `triggerTurn` | Same delivery semantics as actors, with additional Jev freshness and feedback gates. Advice is asynchronous, not a pre-tool veto. |
|
|
18
18
|
| Coding workers and independent verifiers | Existing `agents.spawn` / `agents.run`, tool allowlists, worktrees, status/log/wait | Main is the worker in this profile. Main can launch a verifier and execute approved targeted checks; the observer does not acquire worker-launch authority. |
|
|
19
19
|
| Stop/retry an owned child | Existing `agents.stop`, then an explicitly bounded fresh `agents.spawn` | Stop is not rollback; retries are policy, not a primitive. The default sidecar does not stop Main or retry workers automatically. |
|
|
20
20
|
| Structured progress and inspection | `program.emit`, `jev.status`, terminal envelopes | Latest 64 events in memory, not Foreman's atomic state file and append-only durable run store. |
|
|
21
|
-
| Persistent coordination when
|
|
21
|
+
| Persistent coordination when needed | Existing `mesh.put` CAS state, `mesh.publish`, durable actors and participant subscriptions | Requires explicit capabilities and trusted mesh configuration. A Jev run is not a mesh participant or a durable subscription target. |
|
|
22
22
|
| Bounded cost and interruption | Program limits, host ceilings, `jev.stop`, shared Main halt path | Main abort/Escape, tree navigation, and provider retirement cancel observers. Token usage is post-request, not a hard dollar cap. |
|
|
23
23
|
|
|
24
24
|
`FabricRuntimeState.dispatchHostEvent` feeds both actors and Jev from the same lifecycle, while `haltAdvisors` stops both. Jev is available with mesh disabled. Normal reasoning actors may receive a sanitized recent transcript and use broader host events; Jev deliberately requires an explicit text projection and exposes a smaller event allowlist. That difference is an authorization boundary, not a reason to add implicit transcript access.
|
|
@@ -35,7 +35,7 @@ The skill ships an executable starter in both kernel trees. The Python entry poi
|
|
|
35
35
|
4. `FINISH_REVIEW` is only a candidate for Main's acceptance review. Main must inspect independent verifier findings and actual targeted test/build results before claiming completion. Semantic scores and verifier prose are not passing checks.
|
|
36
36
|
5. The observer retires on new input, escalation, a finish-review candidate, inference failure, or its budgets. Terminal `completed` means the program returned valid output, not that the software job is complete. Main inspects `result.outcome`.
|
|
37
37
|
|
|
38
|
-
Requested limits are 15 minutes, 20 assessments, 600 host calls, 40,000 reported tokens, and 120 consumed events, clamped to trusted host ceilings. Inference failure ends the profile with a labeled escalation
|
|
38
|
+
Requested limits are 15 minutes, 20 assessments, 600 host calls, 40,000 reported tokens, and 120 consumed events, clamped to trusted host ceilings. Inference failure ends the profile with a labeled escalation, without spinning on 429/529 or guessing an answer. Read [Jev's budget and auth rules](jev.md) before launch. No live API test is necessary to install or verify the skill.
|
|
39
39
|
|
|
40
40
|
### Delivery is deliberately bounded
|
|
41
41
|
|
|
@@ -47,7 +47,7 @@ Escalation and limit outcomes stop the observer, not Main. Even an accepted paus
|
|
|
47
47
|
|
|
48
48
|
- Main replaces the Codex App Server worker. Existing Pi/Claude runners can be composed separately; no new Codex App Server transport is implied.
|
|
49
49
|
- Turn/settlement boundaries replace streamed subprocess output and periodic observations, as requested. Silence causes no inference.
|
|
50
|
-
- Bounded selected evidence replaces automatic Git/shell observation. The program has no shell authority and no secret/history access. If the instruction snapshot changes, review and explicitly replace the observer
|
|
50
|
+
- Bounded selected evidence replaces automatic Git/shell observation. The program has no shell authority and no secret/history access. If the instruction snapshot changes, review and explicitly replace the observer; do not assume it refreshed.
|
|
51
51
|
- Jev programs do not survive host restarts. In-memory status is not durable recovery. Existing mesh primitives can store explicit checkpoints, but they do not resume a lost QuickJS context or make effects exactly once.
|
|
52
52
|
- The skill does not weaken feedback prevention to reproduce an unbounded factory loop. Use a reasoning actor when persistent conversational supervision with its different context/lifecycle contract is desired.
|
|
53
53
|
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Harness CLI composition
|
|
2
|
+
|
|
3
|
+
Fabric follows `jev-fabric`'s shell-first boundary: compose existing programs,
|
|
4
|
+
not application-specific tool bridges. Browser Harness JS and macOS Harness own
|
|
5
|
+
their connections, persistent state, native APIs, permission checks, and guarded
|
|
6
|
+
interaction. Fabric supplies its existing shell and task supervision; Jev is an
|
|
7
|
+
optional typed decision-maker. No harness-specific Fabric extension, SDK module
|
|
8
|
+
path, component entry, or provider registration is required.
|
|
9
|
+
|
|
10
|
+
## Browser Harness JS
|
|
11
|
+
|
|
12
|
+
Load the harness-owned `cdp` skill. After the user authorizes a browser scope,
|
|
13
|
+
use its normal CLI through `pi.bash`, with `--no-auto-allow` so Fabric does not
|
|
14
|
+
silently approve a browser debugging prompt. For a reviewed snippet saved by
|
|
15
|
+
`pi.write`, the command shape is:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
return await pi.bash({cmd:"browser-harness-js --no-auto-allow < ./observe-browser.js",timeout:15,settle:true});
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
This is a composition pattern, not permission to connect or scan. The CLI owns a
|
|
22
|
+
persistent daemon, session, and explicit target routing; Fabric does not import
|
|
23
|
+
the SDK or create a second connection. Use the harness's authorized connection
|
|
24
|
+
setup and guarded controller at unknown UI boundaries. Preserve explicit target
|
|
25
|
+
scope and fresh observation handles. The CLI prints raw results, not a Fabric
|
|
26
|
+
provider envelope: validate the documented result, exit status, and size before
|
|
27
|
+
parsing. Empty output is not automatically valid JSON or proof of success.
|
|
28
|
+
|
|
29
|
+
A short CLI process exiting does not stop its daemon. Follow the harness's own
|
|
30
|
+
cleanup contract; stopping a Fabric task is not rollback or daemon shutdown.
|
|
31
|
+
Do not stop a shared daemon owned by another workflow.
|
|
32
|
+
|
|
33
|
+
## macOS Harness
|
|
34
|
+
|
|
35
|
+
Load the harness-owned `macos-harness` skill. Native access needs separately
|
|
36
|
+
approved OS permissions and explicit already-running app scope. The guarded
|
|
37
|
+
server is an ordinary command:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
macos-harness serve --app com.apple.TextEdit
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Keep **one** process alive for a multi-step workflow. Its stdin/stdout protocol
|
|
44
|
+
is newline-terminated UTF-8 JSON, `{id,method,args}` to `{id,result}` or
|
|
45
|
+
`{id,error}`; stderr contains diagnostics. A reviewed task-specific native script
|
|
46
|
+
can own the child, serialize requests, validate response IDs/errors, enforce
|
|
47
|
+
bounds/deadlines, and close stdin/terminate it during cleanup. Run that script
|
|
48
|
+
through the authorized shell, e.g. `pi.bash({cmd:"node ./desktop-task.mjs"})`.
|
|
49
|
+
This does not change Fabric's configured kernel or grant an unrestricted fallback.
|
|
50
|
+
|
|
51
|
+
`pi.bash` is not an interactive stdin handle. Do not launch `serve` as an isolated
|
|
52
|
+
background command and expect `tasks.watch` to become RPC. Monitors and log tails
|
|
53
|
+
are bounded observations and may omit/truncate data. Do not restart the server
|
|
54
|
+
between observe and act: native controller handles do not survive process exit.
|
|
55
|
+
For one-shot deterministic work, the harness's ordinary CLI/library can keep the
|
|
56
|
+
whole observe/act/check sequence in one invocation.
|
|
57
|
+
|
|
58
|
+
## Supervision and decisions
|
|
59
|
+
|
|
60
|
+
Use [background tasks](background-tasks.md) for finite shell deadlines,
|
|
61
|
+
`tasks.wait`, literal-filtered `tasks.watch`, and `tasks.stop`. UI-only monitors
|
|
62
|
+
never wake Main or invoke Jev. A program may explicitly evaluate a remaining
|
|
63
|
+
semantic question over minimized output; see [Jev](jev.md). Validate exact status
|
|
64
|
+
and protocol facts first, map typed answers to code-owned branches, and verify
|
|
65
|
+
postconditions after effects. Never run a model answer as shell code.
|
|
66
|
+
|
|
67
|
+
Preserve the harness's guards:
|
|
68
|
+
|
|
69
|
+
- `executed` means dispatched, not goal success; check fresh authoritative state.
|
|
70
|
+
- `stale` means re-observe; never reuse stale handles.
|
|
71
|
+
- `blocked` means resolve permission/scope or stop; raw APIs cannot bypass it.
|
|
72
|
+
- `outcome_unknown` means inspect, never blindly replay.
|
|
73
|
+
- Never approve permission dialogs, activate apps, or move the physical cursor
|
|
74
|
+
as a workaround. Keep secrets and unrelated private data out of model state.
|
|
75
|
+
|
|
76
|
+
Shell execution runs with host privileges. QuickJS program isolation is not a
|
|
77
|
+
sandbox around the shell or a substitute for the harness's authorization rules.
|
|
78
|
+
Cancellation is not rollback; detached processes/daemons have separate lifetimes.
|
|
79
|
+
|
|
80
|
+
## Migration
|
|
81
|
+
|
|
82
|
+
Remove unneeded `browser-harness` / `macos-harness` entries from your Fabric
|
|
83
|
+
configuration and stop loading their optional `pi/` extensions when switching
|
|
84
|
+
to CLI composition. Do this deliberately after stopping their work: no automatic
|
|
85
|
+
configuration rewrite or cleanup is performed. Replace `browser.*` / `macos.*`
|
|
86
|
+
program grants with only the shell/task actions actually needed.
|
|
87
|
+
|
|
88
|
+
There are no concrete harness exports in `pi-fabric/jev` and no compatibility
|
|
89
|
+
bridge to maintain. The generic [component protocol](components.md) remains
|
|
90
|
+
available for independently installed providers; this change does not remove it
|
|
91
|
+
or modify the sibling harness repositories. Harness-specific docs/skills in those
|
|
92
|
+
packages remain authoritative for their standalone CLIs.
|
|
93
|
+
|
|
94
|
+
Offline checks use local fixture processes and mocked judgments. They do not
|
|
95
|
+
connect to a personal browser, control apps, install tools, or spend API credits.
|