@llblab/pi-state-flow 0.1.4 → 0.2.0
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/AGENTS.md +2 -1
- package/CHANGELOG.md +23 -0
- package/README.md +32 -15
- package/index.ts +4 -669
- package/lib/context.ts +88 -0
- package/lib/episode.ts +29 -0
- package/lib/extension.ts +238 -0
- package/lib/json.ts +78 -0
- package/lib/recovery.ts +38 -0
- package/lib/session.ts +49 -0
- package/lib/skills.ts +58 -0
- package/lib/snapshot.ts +103 -0
- package/lib/state.ts +20 -0
- package/lib/status.ts +16 -0
- package/lib/terminal.ts +139 -0
- package/lib/transition.ts +47 -0
- package/lib/validation.ts +27 -0
- package/package.json +27 -7
package/AGENTS.md
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
# Agent Instructions
|
|
2
2
|
|
|
3
|
+
- Keep independent domain modules under `lib/`, mirror every domain with a same-named file under `tests/`, place cross-domain architecture checks in `tests/invariants.test.ts`, and keep `index.ts` as a minimal composition/public-export boundary.
|
|
3
4
|
- Keep the extension opt-in and preserve clear attribution to SKILL.state wherever the inherited explicit-state approach is described.
|
|
4
5
|
- Preserve Pi's native tool loop and complete inspectable session trace; project completed-run history only at user-run boundaries. Retain persistent and current-run context-bearing custom messages from other extensions, plus the complete current-run trajectory, except State Flow's own validation feedback when it is represented separately.
|
|
5
6
|
- Expose one fully materialized state with exactly `contract`, `working`, and `response`; the first two are flexible memory objects and the third is the latest complete user-facing answer string.
|
|
@@ -9,7 +10,7 @@
|
|
|
9
10
|
- Treat each successful `SKILL.md` read as episode-level acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty `contract.compiled_skills[exactReadPath]`, keep its nested representation fully flexible without `coverage`/`rules` schema, reject the terminal commit when missing, treat complete matching compilations as authoritative, and forbid routine rereads without an uncovered detail, incomplete compilation, concrete source-change evidence, reconciliation failure, or explicit user request.
|
|
10
11
|
- Make the model audit and optimize complete state at every handoff: reorganize inefficient structure, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, speculative, or low-value keys while preserving active commitments and evidence.
|
|
11
12
|
- Accept empty `contract` and `working` patches when nothing future-relevant changed and memory is already efficient; never force invented bookkeeping. Always require `response`. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
|
|
12
|
-
- Keep validation retries hidden from finalized user-facing messages; expose diagnostic detail only through transcript-private feedback and persisted runtime state, while documenting that streaming observers can still see generated terminal envelopes. Tool-bearing retry turns must preserve cumulative validation-attempt accounting. If
|
|
13
|
+
- Keep validation retries hidden from finalized user-facing messages; expose diagnostic detail only through transcript-private feedback and persisted runtime state, while documenting that streaming observers can still see generated terminal envelopes. Tool-bearing retry turns must preserve cumulative validation-attempt accounting. If retries are exhausted, aborted, or cannot continue before the agent settles, keep State Flow enabled and the last committed state intact; abandon only the transient validation chain so the next user run rotates normally.
|
|
13
14
|
- Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in materialized state including arrays is invalid.
|
|
14
15
|
- Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.
|
|
15
16
|
- Rotate the turn-stable specification on every non-retry user run, but not during its tool or terminal-validation retry chain. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,28 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0: Modular runtime hardening
|
|
4
|
+
|
|
5
|
+
- Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
|
|
6
|
+
- Tighten the normative runtime protocol and enforce a regression-tested character budget; omit absent validation feedback from synthetic runtime context instead of serializing a redundant `null`.
|
|
7
|
+
- Redistribute lifecycle coverage from the former monolithic extension suite into the corresponding mirrored domain suites, leaving `extension.test.ts` focused on composition and using one shared test harness.
|
|
8
|
+
- Split the runtime into independent `json`, `state`, `episode`, `snapshot`, `session`, `recovery`, `status`, `context`, `skills`, `terminal`, `validation`, `transition`, and `extension` modules under `lib/`; isolate explicit episode transitions, active-branch selection and recovery, status rendering, bounded retry decisions, atomic state staging, and compare-and-swap commits; mirror each domain under `tests/`, enforce an acyclic dependency graph with cross-domain invariant tests, and reduce `index.ts` to composition and public exports.
|
|
9
|
+
- Register lifecycle commands in the canonical start, status, stop order.
|
|
10
|
+
- Centralize synthetic runtime-context construction and private validation-message filtering in the independently tested context domain, keeping user-controlled specifications out of system-prompt composition.
|
|
11
|
+
- Keep State Flow enabled and preserve the last committed state when terminal-validation retries are exhausted; only the transient retry chain is abandoned so the next user request can continue reliably.
|
|
12
|
+
- Track Skill reads through an independently tested lifecycle correlator in Pi's actual `tool_execution_start` → `tool_call` event order while retaining the mutable intercepted input reference, so later argument rewrites are attributed to the executed path.
|
|
13
|
+
- Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
|
|
14
|
+
- Bound restored iteration and validation-attempt counters before incrementing them, reject exhausted live iteration counters explicitly, and cover both safe-integer boundaries so malformed branch metadata cannot corrupt retry accounting or status output.
|
|
15
|
+
- Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
|
|
16
|
+
- Fall back past malformed newer checkpoints to the newest valid active-branch snapshot, while still failing closed on cyclic or hostile snapshot objects when no valid checkpoint remains.
|
|
17
|
+
- Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
|
|
18
|
+
- Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.
|
|
19
|
+
|
|
20
|
+
## 0.1.5: Skill attribution and state model clarification
|
|
21
|
+
|
|
22
|
+
- Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
|
|
23
|
+
- Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
|
|
24
|
+
- Remove the obsolete `/reload` step from the usage instructions.
|
|
25
|
+
|
|
3
26
|
## 0.1.4: Release verification hotfix
|
|
4
27
|
|
|
5
28
|
- Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
|
package/README.md
CHANGED
|
@@ -15,24 +15,47 @@ user request
|
|
|
15
15
|
|
|
16
16
|
The current run keeps its user message, assistant tool calls, tool results, and persistent or current-run context-bearing custom messages from other Pi extensions model-visible. Only after the terminal handoff does the next run replace that trajectory with one materialized state. Pi's complete session trace remains inspectable.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## Installation
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
Requirements: Pi `0.84.4–0.84.x` and Node.js `22.19.0` or newer.
|
|
21
|
+
|
|
22
|
+
Install from npm:
|
|
21
23
|
|
|
22
24
|
```bash
|
|
23
25
|
pi install npm:@llblab/pi-state-flow
|
|
24
26
|
```
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
Or install from GitHub:
|
|
27
29
|
|
|
28
30
|
```bash
|
|
29
31
|
pi install git:github.com/llblab/pi-state-flow
|
|
30
32
|
```
|
|
31
33
|
|
|
34
|
+
Pi packages execute with full user permissions; review the source before installing, as with any extension.
|
|
35
|
+
|
|
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
|
+
|
|
32
56
|
## Usage
|
|
33
57
|
|
|
34
58
|
```text
|
|
35
|
-
/reload
|
|
36
59
|
/state-flow-start
|
|
37
60
|
```
|
|
38
61
|
|
|
@@ -46,7 +69,7 @@ The extension registers no model tools. Tool-bearing assistant responses use ord
|
|
|
46
69
|
Complete user-facing answer
|
|
47
70
|
```
|
|
48
71
|
|
|
49
|
-
At `message_end`, the runtime requires that private comment at the start of the single terminal text block, followed by exactly one blank line. It removes only the comment and separator and stages all three state fields. At `turn_end`, it reconciles `response` with Pi's finalized assistant message after all chained `message_end` handlers, concatenating any text blocks without inserting characters, then commits. If a later handler removes all answer text or adds a tool call after terminal validation, the same hidden regeneration chain runs. Arbitrary response Markdown remains outside the HTML comment, so its own content cannot terminate the private frame. Invalid terminal commits are regenerated through hidden feedback up to three times
|
|
72
|
+
At `message_end`, the runtime requires that private comment at the start of the single terminal text block, followed by exactly one blank line. It removes only the comment and separator and stages all three state fields. At `turn_end`, it reconciles `response` with Pi's finalized assistant message after all chained `message_end` handlers, concatenating any text blocks without inserting characters, then commits. If a later handler removes all answer text or adds a tool call after terminal validation, the same hidden regeneration chain runs. Arbitrary response Markdown remains outside the HTML comment, so its own content cannot terminate the private frame. Invalid terminal commits are regenerated through hidden feedback up to three times. If all retries fail, State Flow remains enabled, preserves the last committed snapshot, abandons only the transient validation chain, and lets the next user request start cleanly from that state. Tool-bearing turns do not reset the attempt count. Aborting a regeneration has the same non-destructive behavior.
|
|
50
73
|
|
|
51
74
|
Commands:
|
|
52
75
|
|
|
@@ -58,7 +81,7 @@ Commands:
|
|
|
58
81
|
|
|
59
82
|
The compact Pi status renders an accent `state-flow` label followed by the dimmed committed iteration number, for example `state-flow #7`. `/state-flow-status` reports iteration metadata, then separates the complete pretty-formatted materialized state JSON with a blank line for operator analysis.
|
|
60
83
|
|
|
61
|
-
`/state-flow-stop` clears the specification, materialized state, validation feedback, and committed-run counter. A later `/state-flow-start` always begins a fresh episode. State follows the active Pi session branch and is restored immediately after `/tree` navigation
|
|
84
|
+
`/state-flow-stop` clears the specification, materialized state, validation feedback, and committed-run counter. A later `/state-flow-start` always begins a fresh episode. State follows the active Pi session branch and is restored immediately after `/tree` navigation. If the newest checkpoint is malformed, restoration walks backward to the newest valid checkpoint instead of resetting an otherwise recoverable episode. Entering a branch with no State Flow snapshot leaves the mode disabled there.
|
|
62
85
|
|
|
63
86
|
## Materialized state
|
|
64
87
|
|
|
@@ -90,6 +113,8 @@ This removes `working.move`, replaces `working.result`, preserves every other me
|
|
|
90
113
|
|
|
91
114
|
State and patch size have no byte, growth, pressure, or project-schema limit. Patch history remains only in the Pi trace, not in model context.
|
|
92
115
|
|
|
116
|
+
These three fields are the complete **materialized State Flow state**, but they are not the only state that can shape model behavior. A situational fourth, exogenous state lives outside the handoff: the current project, workspace, tools, processes, and runtime environment. It can change while work is in progress—including through the model's own tool effects—and later observations of those changes can alter subsequent behavior. State Flow neither snapshots nor rolls back this external state; `working` should retain only the decision-relevant facts needed to reconnect the next run to it.
|
|
117
|
+
|
|
93
118
|
## Terminal handoff quality
|
|
94
119
|
|
|
95
120
|
The terminal patch is a required handoff, not a progress phrase or transcript summary. The next run may see only this state plus its new user prompt. A fresh model should be able to continue without rereading, rediscovering, re-deriving decisions, or repeating failed approaches.
|
|
@@ -120,7 +145,7 @@ A successful `SKILL.md` read is treated as episode-level acquisition. Before ter
|
|
|
120
145
|
}
|
|
121
146
|
```
|
|
122
147
|
|
|
123
|
-
No `coverage`/`rules` schema is imposed. The model chooses the smallest structure that faithfully preserves the Skill's useful behavior. Raw Skill text is not copied. The runtime checks only that the exact successfully executed source path
|
|
148
|
+
No `coverage`/`rules` schema is imposed. The model chooses the smallest structure that faithfully preserves the Skill's useful behavior. Raw Skill text is not copied. The runtime checks only that the exact successfully executed source path has a non-empty compilation and rejects a terminal commit when it is missing. Attribution follows Pi's lifecycle order: it retains the mutable `tool_call` input reference so later interception rewrites resolve to the path actually executed, with `tool_execution_start` arguments as a compatibility fallback.
|
|
124
149
|
|
|
125
150
|
A complete matching compilation is authoritative episode memory and replaces routine rereading. Rereading is justified only by an explicitly uncovered detail, an incomplete compilation, concrete source-change evidence, a contradiction or execution failure requiring reconciliation, or an explicit user request. The mere possibility that a source changed is not sufficient. A justified reread refreshes the compilation and removes obsolete rules.
|
|
126
151
|
|
|
@@ -155,14 +180,6 @@ The normative protocol remains in the system prompt throughout a tool/retry chai
|
|
|
155
180
|
- This mode remains a poor fit for auditing or outputs that require complete historical trajectories across user requests.
|
|
156
181
|
- Token, cache, latency, and success-rate advantages still require controlled Pi benchmarks.
|
|
157
182
|
|
|
158
|
-
## Distribution
|
|
159
|
-
|
|
160
|
-
Version `0.1.4` supports public npm, local, and source/GitHub distribution from the canonical `llblab/pi-state-flow` repository. Version tags trigger `.github/workflows/release.yml`, which validates the exact tag, publishes through npm Trusted Publisher with provenance, verifies the public package, and then creates the matching GitHub Release.
|
|
161
|
-
|
|
162
|
-
Configure the npm Trusted Publisher with owner `llblab`, repository `pi-state-flow`, workflow filename `release.yml`, and no environment. No long-lived npm token is used.
|
|
163
|
-
|
|
164
|
-
Compatibility is bounded to Pi `0.84.x` from `0.84.4` onward and Node.js `22.19.0` or newer.
|
|
165
|
-
|
|
166
183
|
## Validation
|
|
167
184
|
|
|
168
185
|
```bash
|