@llblab/pi-state-flow 0.2.0 → 0.2.2
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/CHANGELOG.md +8 -0
- package/README.md +6 -20
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.2: README structure hotfix
|
|
4
|
+
|
|
5
|
+
- Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
|
|
6
|
+
|
|
7
|
+
## 0.2.1: README banner hotfix
|
|
8
|
+
|
|
9
|
+
- Add the project banner to the README.
|
|
10
|
+
|
|
3
11
|
## 0.2.0: Modular runtime hardening
|
|
4
12
|
|
|
5
13
|
- Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
|
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
> Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2)
|
|
4
4
|
|
|
5
|
+

|
|
6
|
+
|
|
5
7
|
An opt-in Pi extension for explicit, validated state handoffs between complete agent runs.
|
|
6
8
|
|
|
7
9
|
State Flow preserves Pi's native tool loop inside each user request:
|
|
@@ -33,26 +35,6 @@ pi install git:github.com/llblab/pi-state-flow
|
|
|
33
35
|
|
|
34
36
|
Pi packages execute with full user permissions; review the source before installing, as with any extension.
|
|
35
37
|
|
|
36
|
-
## Quick start
|
|
37
|
-
|
|
38
|
-
Start Pi, then start an episode and send your task:
|
|
39
|
-
|
|
40
|
-
```text
|
|
41
|
-
/state-flow-start
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
State Flow is opt-in: installation alone does not alter model context. Confirm the active episode with `/state-flow-status`, and use `/state-flow-stop` to disable it and erase its materialized episode state.
|
|
45
|
-
|
|
46
|
-
For a one-off trial without installing the package:
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
pi -e npm:@llblab/pi-state-flow
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Architecture
|
|
53
|
-
|
|
54
|
-
`index.ts` is only the package composition and public-export boundary. Independent runtime domains live under `lib/`: `json` owns lossless JSON and patches, `state` owns the materialized state shape, `episode` owns explicit start/stop and user-run boundaries, `snapshot` owns persistence migration, `session` owns active-branch snapshot discovery and bootstrap detection, `recovery` falls back to the newest valid active-branch checkpoint, `status` owns deterministic operator-facing status rendering, `context` owns trajectory projection, private-feedback filtering, and synthetic runtime-context construction, `skills` owns Skill acquisition rules and mutable lifecycle correlation, `terminal` owns the handoff protocol, `validation` owns bounded retry decisions, `transition` owns atomic staging and compare-and-swap commits, and `extension` coordinates these domains with Pi. Every domain has a same-named test under `tests/`; lifecycle scenarios are colocated with the domain whose contract they exercise, `tests/extension.test.ts` remains focused on composition, shared setup lives in `tests/harness.ts`, and cross-domain constraints live in `tests/invariants.test.ts`.
|
|
55
|
-
|
|
56
38
|
## Usage
|
|
57
39
|
|
|
58
40
|
```text
|
|
@@ -180,6 +162,10 @@ The normative protocol remains in the system prompt throughout a tool/retry chai
|
|
|
180
162
|
- This mode remains a poor fit for auditing or outputs that require complete historical trajectories across user requests.
|
|
181
163
|
- Token, cache, latency, and success-rate advantages still require controlled Pi benchmarks.
|
|
182
164
|
|
|
165
|
+
## Architecture
|
|
166
|
+
|
|
167
|
+
`index.ts` is only the package composition and public-export boundary. Independent runtime domains live under `lib/`: `json` owns lossless JSON and patches, `state` owns the materialized state shape, `episode` owns explicit start/stop and user-run boundaries, `snapshot` owns persistence migration, `session` owns active-branch snapshot discovery and bootstrap detection, `recovery` falls back to the newest valid active-branch checkpoint, `status` owns deterministic operator-facing status rendering, `context` owns trajectory projection, private-feedback filtering, and synthetic runtime-context construction, `skills` owns Skill acquisition rules and mutable lifecycle correlation, `terminal` owns the handoff protocol, `validation` owns bounded retry decisions, `transition` owns atomic staging and compare-and-swap commits, and `extension` coordinates these domains with Pi. Every domain has a same-named test under `tests/`; lifecycle scenarios are colocated with the domain whose contract they exercise, `tests/extension.test.ts` remains focused on composition, shared setup lives in `tests/harness.ts`, and cross-domain constraints live in `tests/invariants.test.ts`.
|
|
168
|
+
|
|
183
169
|
## Validation
|
|
184
170
|
|
|
185
171
|
```bash
|