@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 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
+ ![pi-state-flow banner](https://raw.githubusercontent.com/llblab/pi-state-flow/main/banner.jpg)
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "private": false,
5
5
  "description": "State Flow terminal-handoff runtime for Pi, inspired by SKILL.state",
6
6
  "keywords": [