@llblab/pi-state-flow 0.17.0 → 0.17.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
@@ -2,6 +2,15 @@
2
2
 
3
3
  > Each release keeps at most 8 outcome records of at most 512 characters.
4
4
 
5
+ ## 0.17.2: incremental memory model documentation
6
+
7
+ - `README`: Explains the combination of durable state between user runs and native working context within each run. Clarifies global/CWD/session composition into effective memory, configurable historical access and optional Git backups, with a simpler flow diagram and a compact semantic-plane reference. Runtime behavior is unchanged.
8
+
9
+ ## 0.17.1: precise patch diagnostics and clearer onboarding
10
+
11
+ - `Patch diagnostics`: Unknown scope-patch keys are reported by their exact JSON-quoted name, with permitted fields listed in intent-first order: intents, contract, working, artifacts, lazy. Accepted patch structure and runtime-owned response protection are unchanged. Thanks to @Jipok for the feedback in #5.
12
+ - `README`: Rebuilds the introduction around intent-first memory, explicit scope ownership, small patches and precise reads. Clarifies opt-in active versus default passive behavior, file-authoritative persistence, optional Git backup and the 0.17 format boundary without promising token savings or automatic migration.
13
+
5
14
  ## 0.17.0: canonical memory and native Pi integration
6
15
 
7
16
  - `Pi 0.87 integration`: Aligns SDK pins and lockfile. Native sections compose with companion hooks and refresh on in-run mode changes; context edits and image profiles remain SDK-owned. User anchors survive normalization, steering and in-run Start/Stop; uncertain boundaries retain available summaries/tools without restoring omitted input. Owned compaction keeps the complete accepted run, skips foreign prefixes and awaits completion/refusal before deferred follow-ups. Native trace remains intact.
package/README.md CHANGED
@@ -4,93 +4,147 @@
4
4
 
5
5
  **Incremental scoped context/memory compiler for Pi.**
6
6
 
7
- Keep decisions, constraints, verified findings, and next steps without sending every completed tool exchange back to the model. State Flow compiles curated context and memory into explicit state; Pi still owns the conversation, the native tool loop, and the complete inspectable trace.
7
+ State Flow maintains explicit state across requests and sessions. The agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory rather than carrying every completed exchange into the next request.
8
8
 
9
- > Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2).
9
+ Drawing on the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), State Flow combines durable state with Pi's native conversation context. In this hybrid, **state carries continuity between user runs; Pi's native context carries the working trajectory within a run.** The conversation is not reset after each model response or tool call. Pi retains ownership of execution, session navigation and the full inspectable trace.
10
10
 
11
- ## The idea
11
+ ## How it works
12
+
13
+ A user run starts with effective memory and a new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed ordinary conversation history.
12
14
 
13
15
  ```text
14
- Current state + New request
15
- ↓
16
- Pi's native tool loop
17
- ↓
18
- Updated state + Answer
19
- ↓
20
- Next request
16
+ Current state + Request
17
+ ↓
18
+ Pi's native tool loop
19
+ ↓
20
+ Patched state + Answer
21
+ ↓
22
+ Updated state
21
23
  ```
22
24
 
23
- During a request, the model retains the current tool trajectory. Between requests, State Flow replaces completed ordinary conversation history in model context with the current state and recent transitions. It does not delete Pi's session history.
25
+ Within a run, the available request, intermediate responses, tool results and steering remain in context. A state patch updates memory without discarding that working trajectory. Persistent context-bearing messages from other extensions are preserved as well.
26
+
27
+ This reduces reliance on repeated model-generated summaries of an accumulating transcript. Retaining the current trajectory also allows prompt-cache reuse while the relevant prefix remains unchanged. Avoiding summary calls and repeated prompt processing can improve responsiveness; the result depends on the model, provider, workload and frequency of state changes, not a fixed latency guarantee.
24
28
 
25
- The agent curates what matters; the extension validates, persists, and projects the accepted state. This is working memory, not automatic proof that a remembered fact is true.
29
+ Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary, retaining the complete latest accepted run. Neither mechanism deletes Pi's append-only session trace. See [lifecycle behavior](docs/usage.md#session-behavior) and [performance evidence](docs/performance.md).
26
30
 
27
- ## Quick start
31
+ ## Installation and activation
28
32
 
29
- Requires Pi `0.87.0` or newer and Node.js `22.19.0` or newer. There is no declared upper Pi version bound; see the [SDK compatibility matrix](docs/compatibility.md) for exact tested stacks. Git is optional; using it requires a configured commit identity.
33
+ Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
30
34
 
31
- From npm:
35
+ From NPM:
32
36
 
33
37
  ```bash
34
38
  pi install npm:@llblab/pi-state-flow
35
39
  ```
36
40
 
37
- From git:
41
+ From Git:
38
42
 
39
43
  ```bash
40
44
  pi install git:github.com/llblab/pi-state-flow
41
45
  ```
42
46
 
43
- In Pi:
47
+ Enable active State Flow on the current branch:
44
48
 
45
49
  ```text
46
50
  /state-flow-start
47
51
  ```
48
52
 
49
- Continue working normally. The agent receives the state protocol and uses `patch_state` to maintain memory.
53
+ Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
54
+
55
+ - `/state-flow-start`: Enable active state updates and memory-based context projection.
56
+ - `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
57
+ - `/state-flow-stop`: End active episode semantics without deleting memory; an interrupted run retains its frozen handoff and available trajectory.
58
+
59
+ Active mode is **opt-in**. Passive memory projection and the memory tools are enabled by default: existing state can be read or explicitly patched without an active episode or State Flow compaction. Stop returns to the configured passive behavior. `autoStart` can enable active mode for genuinely new sessions; resumed branches restore their own enablement. See [configuration](docs/usage.md#configuration).
60
+
61
+ ## State model
62
+
63
+ ### Scopes and effective memory
50
64
 
51
- - `/state-flow-status`: Inspect the selected effective state, bounded history, already-known runtime hints/invalidations, and recovery failures without scanning artifact sources or mutating state.
52
- - `/state-flow-stop`: Disable updates on this branch without deleting retained state. A new passive branch records only a disabled checkpoint in Pi, without initializing canonical storage.
65
+ Memory has three ownership scopes:
53
66
 
54
- Active State Flow episodes remain **opt-in**, while passive durable memory bootstrap and tools are available by default. Passive access does not start an episode or trigger State Flow compaction. Starting an active episode in an existing conversation keeps its context for one bootstrap run; set `"autoStart": true` to promote genuinely new sessions automatically. See [configuration](docs/usage.md#configuration).
67
+ - `global`: Knowledge and preferences shared across projects.
68
+ - `cwd`: Knowledge shared by sessions in the same working directory.
69
+ - `session`: State belonging to the current session and its selected branch.
55
70
 
56
- ## What carries forward
71
+ They compose recursively in **global → CWD → session** order. More-specific values override lower-scope values, while object fields merge. Removing a local value can reveal an inherited value again.
57
72
 
58
- The same semantic planes exist at every scope:
73
+ The agent receives the **effective view** of this composition, not three unrelated memory dumps. It can read that view or inspect an individual scope when ownership matters. `effective` is a computed view, not a fourth storage scope. Scope precedence does not elevate memory into system-level instructions.
59
74
 
60
- - `intents`: Courses of action the agent has actually committed to pursue.
61
- - `contract`: Requirements, decisions, constraints, and interface commitments.
62
- - `working`: Observations, results, unresolved questions, and possible next steps.
63
- - `artifacts`: Source-addressed descriptions and reusable compiled knowledge, refreshed in their observed global/CWD/session owner; Skills belong to CWD.
75
+ ### Semantic planes
76
+
77
+ Every scope uses the same shape:
78
+
79
+ - `intents`: Active commitments to future action.
80
+ - `contract`: Requirements, decisions, constraints and interface commitments.
81
+ - `working`: Observations, results, uncertainties and current continuation.
82
+ - `artifacts`: Source-addressed descriptions and compiled knowledge.
64
83
  - `response`: The latest complete answer, captured by the runtime.
65
- - `lazy`: Durable, versioned memory omitted from ordinary context until explicitly read.
84
+ - `lazy`: Supporting memory available through explicit reads, with its body omitted from baseline model context.
85
+
86
+ These planes organize ordinary JSON rather than imposing a project-specific schema. The model updates the semantic planes except `response`, which is runtime-owned. Memory remains fallible: storing an observation does not make it current or correct.
87
+
88
+ ## Incremental updates and history
89
+
90
+ `patch_state` updates one or more named scopes atomically. Unmentioned values remain unchanged; object patches merge recursively, and `null` deletes an object key rather than becoming stored data.
91
+
92
+ ```json
93
+ {
94
+ "cwd": {
95
+ "contract": { "verification": { "command": "npm test" } }
96
+ },
97
+ "session": {
98
+ "intents": { "verify": { "action": "Run the checks before publishing" } },
99
+ "working": { "checks": "Pending" }
100
+ }
101
+ }
102
+ ```
103
+
104
+ During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or additional State Flow reasoning loop.
105
+
106
+ `read_state` provides targeted current and historical access:
107
+
108
+ ```json
109
+ { "paths": ["effective.contract", "cwd.working", "session.intents"] }
110
+ ```
111
+
112
+ - `working`: Current effective working memory; unscoped paths are effective aliases.
113
+ - `effective[1].working`: Working memory at the preceding accepted transition boundary, when retained.
114
+ - `cwd.patches[0]`: The latest retained CWD semantic patch.
115
+ - `effective.lazy.memory[0..3]`: A bounded slice of a stored collection.
116
+
117
+ Historical materializations and scope patch histories use the configurable **`historyLimit`**, from **0 to 100**, with a default of **7**. Materialized offsets refer to accepted semantic transitions, not user messages or an independent counter for each scope. Requested history must still exist in the active lineage; increasing the limit cannot recreate discarded history. Older patches fold into the checkpoint without removing current values.
118
+
119
+ Array ranges, structural `keys` reads and path-intersected `patch` projections support progressive access without loading whole memory collections. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
120
+
121
+ ## Persistence, backups and continuity
122
+
123
+ The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files hold each scope's state, retained changes and metadata; session configuration and runtime identity are stored separately.
66
124
 
67
- Memory overlays **global → project CWD → session**. Put reusable cross-project knowledge in global, project knowledge in CWD, and branch/run continuation in session. Hot planes carry what must matter now; `lazy` retains what may matter later without hydrating its body into every prompt. An intent stays hot only while its course remains chosen and disappears when fulfilled, abandoned, superseded, or impossible. It may refer to supporting detail through a structured `{"$ref":"cwd.lazy.plan"}` value or a `$`-prefixed state path inside ordinary prose, such as `$effective.lazy.memory[7]`. Both remain semantic content interpreted by the agent: State Flow never parses, validates, hydrates, executes, or completes them automatically. The agent never scans references for breakage. Only when current work already follows one and a single value path is missing does State Flow perform a bounded exact reverse lookup. Matching durable sources produce a top-level `{value:null, hint:[...]}` sentinel whose typed hint names runtime-verified current owning paths and asks the agent to reconcile them. Keys, patch, batch, and unmatched reads retain ordinary all-or-error behavior; no match does not prove that the agent invented the path. The agent may then repair or remove a proven stale locator in its owning value.
125
+ **Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. Backup needs a Git commit identity; accepting and persisting state does not. A backup failure produces a warning without rejecting or rolling back accepted memory. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
68
126
 
69
- **Resuming an existing Pi session restores its selected State Flow state and enablement.** Only the session layer is session-local; global/CWD remain shared and current. Session files must match their retained runtime lineage, but another session's shared update does not invalidate continuation. A genuinely new session starts with an empty session layer rather than another session's work. Tree navigation follows the selected branch, not whichever state happens to be at Git `HEAD`.
127
+ Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries fail closed rather than silently substituting newer state. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
70
128
 
71
- The agent uses `read_state` for exact current or historical paths. Unscoped paths read the effective overlay; `global`, `cwd`, and `session` address ownership directly; `[n]` selects a retained accepted transition boundary up to the configured `historyLimit` (default 7). Bounded array ranges and `value`, `keys`, or `patch` projections support progressive reads without hydrating whole lazy collections. Discarded semantic history is unavailable and is not reconstructed from backup.
129
+ Version 0.17 accepts only the current canonical storage contract and has no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
72
130
 
73
- Two packaged Skills keep guidance proportional: `state-flow-guide` resolves concrete operational questions about reading, patching, inheritance, acquisition, completion, and recovery; `state-flow-memory` performs one bounded curation only on explicit request. Neither runs background maintenance. After a meaningful feature, release, or project boundary—or whenever retained state becomes noisy—ask: **“Review and clean State Flow state.”** The curation pass inspects ownership, removes only proven stale or duplicate semantics, preserves consequential knowledge, and stops after verification.
131
+ ## Operational boundaries
74
132
 
75
- ## Boundaries worth knowing
133
+ State Flow adds memory, not another agent controller. It does not introduce background reasoning, a scheduler, automatic reference hydration or rollback of external tool effects. State and the current trajectory are not size-capped; performance depends on how much useful information the agent retains.
76
134
 
77
- - `Not a second agent loop`: State Flow adds memory to Pi; it does not run background reasoning or replace session controls.
78
- - `Not a transcript archive in the prompt`: Prefer ordinary Pi when each request needs all historical exchanges verbatim.
79
- - `Not live workspace truth`: Remembered observations can become stale; revalidate consequential facts before acting.
80
- - `Physical forks copy private memory`: Native fork replacement copies the selected session checkpoint/tail into a new owner while retaining current shared memory. The child starts its own history; older parent checkpoints are not child history. See [fork support and limits](docs/usage.md#fork-support-and-limits).
81
- - `Not a token or latency guarantee`: State and the current trajectory are not size-capped. Benefits depend on workload and memory quality; see [performance evidence](docs/performance.md).
82
- - `Use a dedicated store`: By default state lives in `~/.pi/agent/state-flow/`. Canonical files own semantics; optional settled-turn Git backup stages only State Flow-owned paths. Do not point the store at an unrelated working repository.
83
- - `Treat memory as private`: State and diagnostic logs may contain session content. Keep secrets out, and review data before configuring a remote. Removing a value does not erase Git history or other copies.
135
+ The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile touched memory; dedicated cleanup is not an automatic audit after each task.
84
136
 
85
- Pi packages run with your user permissions. Without Git, current state and its proven hot history persist to files, but arbitrary older branches may be unavailable. See [storage and recovery](docs/usage.md#storage-and-recovery) before moving stores.
137
+ Treat state, diagnostic logs and backups as private data. Revalidate consequential observations before acting, and verify a transfer's destination before deleting its source. Removing a value from current state does not erase older histories or remote copies.
86
138
 
87
- ## Read more
139
+ ## Documentation and development
88
140
 
89
- - [Usage and recovery](docs/usage.md): Configuration, session behavior, diagnostics, privacy, and storage recovery.
90
- - [Architecture](docs/architecture.md): Semantic state, temporal history, barriers, artifacts, and integration contracts.
91
- - [Performance](docs/performance.md): Reproducible workloads, measured costs, and what the measurements do not prove.
92
- - [Documentation index](docs/README.md): All maintained guides, including the temporal acceptance map.
141
+ - [Usage and recovery](docs/usage.md) — Configuration, lifecycle, diagnostics and storage operations.
142
+ - [Architecture](docs/architecture.md) — Semantic model, temporal boundaries, artifacts and integration contracts.
143
+ - [SDK compatibility](docs/compatibility.md) — Tested stacks and verification limits.
144
+ - [Performance](docs/performance.md) — Measurements, workload definitions and limits.
145
+ - [Acceptance map](docs/temporal-acceptance.md) — Properties tied to concrete tests.
146
+ - [Documentation index](docs/README.md) — All maintained guides.
93
147
 
94
- For development, run `npm install` and `npm run validate`. `npm run benchmark` runs the opt-in synthetic workload in `benchmarks/`, separate from the normal test suite. In a source checkout, see `benchmarks/README.md` for lifecycle/publisher selection.
148
+ For development, run `npm install` and `npm run validate`. `npm run benchmark` is opt-in and separate from the normal suite; see `benchmarks/README.md` in a source checkout.
95
149
 
96
- Project context: [AGENTS.md](AGENTS.md) · [BACKLOG.md](BACKLOG.md) · [CHANGELOG.md](CHANGELOG.md).
150
+ Project context: [AGENTS.md](AGENTS.md), [BACKLOG.md](BACKLOG.md), [CHANGELOG.md](CHANGELOG.md).
@@ -3,7 +3,7 @@ import { createAcceptedTransition } from "./history.js";
3
3
  import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
4
4
  import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
5
5
  const SCOPES = new Set(["global", "cwd", "session"]);
6
- const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "lazy"]);
6
+ const PATCH_KEYS = new Set(["intents", "contract", "working", "artifacts", "lazy"]);
7
7
  function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
8
8
  for (const read of successfulArtifactReads) {
9
9
  const output = patch.artifacts[read.path];
@@ -77,7 +77,7 @@ function validateScopePatch(scope, patch) {
77
77
  validatePatch(patch);
78
78
  for (const key of Object.keys(patch)) {
79
79
  if (!PATCH_KEYS.has(key)) {
80
- throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, intents, and lazy are model-owned`);
80
+ throw new Error(`Unknown State Flow patch key ${JSON.stringify(key)}; expected one of: ${[...PATCH_KEYS].join(", ")}`);
81
81
  }
82
82
  }
83
83
  for (const key of ["artifacts", "contract", "working", "intents"]) {
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.17.0",
3
+ "version": "0.17.2",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [
@@ -10,7 +10,7 @@ The current repository-local stack uses Linux/x64, Node 26.8.1, Git 2.55.0, and
10
10
 
11
11
  | Pi SDK stack | Validation | Evidence status |
12
12
  | --- | --- | --- |
13
- | 0.87.0 | Build, typecheck, import, package dry-run, 437/437 tests | Current full-suite baseline |
13
+ | 0.87.0 | Build, typecheck, import, package dry-run, 438/438 tests | Current full-suite baseline |
14
14
  | 0.84.4 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
15
15
  | 0.85.1 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
16
16
 
package/lib/transition.ts CHANGED
@@ -35,7 +35,7 @@ export interface StagedScopedTransition {
35
35
  }
36
36
 
37
37
  const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
38
- const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "lazy"]);
38
+ const PATCH_KEYS = new Set(["intents", "contract", "working", "artifacts", "lazy"]);
39
39
 
40
40
  function compileReadArtifacts(
41
41
  nextState: StateDocument,
@@ -123,7 +123,7 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
123
123
  validatePatch(patch);
124
124
  for (const key of Object.keys(patch)) {
125
125
  if (!PATCH_KEYS.has(key)) {
126
- throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, intents, and lazy are model-owned`);
126
+ throw new Error(`Unknown State Flow patch key ${JSON.stringify(key)}; expected one of: ${[...PATCH_KEYS].join(", ")}`);
127
127
  }
128
128
  }
129
129
  for (const key of ["artifacts", "contract", "working", "intents"] as const) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.17.0",
3
+ "version": "0.17.2",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [