@llblab/pi-state-flow 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +7 -20
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.3: Document protocol and validation limitations
4
+
5
+ - Document that duplicate-comment detection also rejects literal State Flow envelope examples inside fenced or inline code in terminal answers, and provide a plain-JSON workaround.
6
+ - Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
7
+ - No runtime behavior changes.
8
+
9
+ ## 0.2.2: README structure hotfix
10
+
11
+ - Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
12
+
3
13
  ## 0.2.1: README banner hotfix
4
14
 
5
15
  - Add the project banner to the README.
package/README.md CHANGED
@@ -35,26 +35,6 @@ pi install git:github.com/llblab/pi-state-flow
35
35
 
36
36
  Pi packages execute with full user permissions; review the source before installing, as with any extension.
37
37
 
38
- ## Quick start
39
-
40
- Start Pi, then start an episode and send your task:
41
-
42
- ```text
43
- /state-flow-start
44
- ```
45
-
46
- 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.
47
-
48
- For a one-off trial without installing the package:
49
-
50
- ```bash
51
- pi -e npm:@llblab/pi-state-flow
52
- ```
53
-
54
- ## Architecture
55
-
56
- `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`.
57
-
58
38
  ## Usage
59
39
 
60
40
  ```text
@@ -176,12 +156,17 @@ The normative protocol remains in the system prompt throughout a tool/retry chai
176
156
 
177
157
  - State commits exactly once per successful complete agent run, at terminal `message_end`/`turn_end`.
178
158
  - Tool-bearing responses do not require or commit patches and retain ordinary Pi tool behavior, including multiple sequential calls. The runtime removes an accidental leading terminal envelope only when its JSON, fields, separator, and non-empty response are all structurally valid; malformed or quoted examples remain untouched.
159
+ - Terminal answers cannot contain another complete State Flow comment, even inside a fenced code block or inline code: duplicate detection scans the entire answer body, not Markdown structure. When explaining the protocol while State Flow is enabled, describe the fields or show plain JSON without the HTML comment delimiters. The literal envelope examples in this README are documentation, not valid content to copy into a terminal answer body.
179
160
  - A failed tool remains in the current run trajectory for ordinary model reconciliation before terminal commit.
180
161
  - If a run never reaches a valid terminal handoff, its external tool effects may exist while persistent State Flow state remains at the previous commit.
181
162
  - The terminal envelope exists in ordinary assistant text until `message_end`; `message_update`, RPC, JSON, or other streaming consumers can observe it. Never place secrets in State Flow state.
182
163
  - This mode remains a poor fit for auditing or outputs that require complete historical trajectories across user requests.
183
164
  - Token, cache, latency, and success-rate advantages still require controlled Pi benchmarks.
184
165
 
166
+ ## Architecture
167
+
168
+ `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`.
169
+
185
170
  ## Validation
186
171
 
187
172
  ```bash
@@ -189,6 +174,8 @@ npm install
189
174
  npm run validate
190
175
  ```
191
176
 
177
+ Validation covers TypeScript checking, automated tests, and an extension import smoke check. Lifecycle tests use a mock Pi event harness; they do not establish behavior under the real Pi scheduler, queued prompts, abort/compaction interactions, or combinations of extensions. Those scenarios still need integration checks. Structural patch validation also cannot prove that a handoff preserved every important requirement or compiled a Skill faithfully.
178
+
192
179
  ## Project status
193
180
 
194
181
  - [Open work](BACKLOG.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "private": false,
5
5
  "description": "State Flow terminal-handoff runtime for Pi, inspired by SKILL.state",
6
6
  "keywords": [