@llblab/pi-state-flow 0.17.1 → 0.17.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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  > Each release keeps at most 8 outcome records of at most 512 characters.
4
4
 
5
+ ## 0.17.3: passive shared-memory concurrency
6
+
7
+ - `Passive concurrency`: First passive semantic or compilation-evidence writes now adopt untouched global/CWD updates made by another session after memory was loaded. Targeted shared-scope changes still reject stale writes with scope-specific diagnostics, and competing private-session writes remain fenced. No automatic patch replay, episode activation, storage-format change or weaker publication CAS is introduced.
8
+
9
+ ## 0.17.2: incremental memory model documentation
10
+
11
+ - `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.
12
+
5
13
  ## 0.17.1: precise patch diagnostics and clearer onboarding
6
14
 
7
15
  - `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.
package/README.md CHANGED
@@ -4,135 +4,147 @@
4
4
 
5
5
  **Incremental scoped context/memory compiler for Pi.**
6
6
 
7
- Long-running work needs continuity: what the agent chose to do, which constraints still apply, what it verified, and what remains unresolved. State Flow gives that knowledge an explicit, inspectable home instead of relying only on repeated conversation history.
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
- - **Intent first.** Active commitments stay visible alongside constraints, findings and unresolved work.
24
- - **Less completed history in model context.** Active mode replaces completed ordinary exchanges with current memory and compact recent transitions. It preserves the available current-run trajectory and other extensions' persistent custom context.
25
- - **An ordinary finish.** The agent patches memory when something useful changes, then answers normally. No finalization patch or extra State Flow reasoning loop.
26
- - **Files first.** Accepted state persists without Git. Optional Git backup cannot veto or roll back a state update.
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.
28
+
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).
27
30
 
28
- Memory is curated knowledge, not proof: an accurately stored observation can still become stale.
31
+ ## Installation and activation
29
32
 
30
- ## Get started
33
+ Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
31
34
 
32
- Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. The open-ended Pi peer range is not a claim that every future SDK version has been tested; see [compatibility](docs/compatibility.md).
35
+ From NPM:
33
36
 
34
37
  ```bash
35
38
  pi install npm:@llblab/pi-state-flow
36
39
  ```
37
40
 
38
- Or install from source with `pi install git:github.com/llblab/pi-state-flow`.
41
+ From Git:
42
+
43
+ ```bash
44
+ pi install git:github.com/llblab/pi-state-flow
45
+ ```
39
46
 
40
- In Pi:
47
+ Enable active State Flow on the current branch:
41
48
 
42
49
  ```text
43
50
  /state-flow-start
44
51
  ```
45
52
 
46
- Then work normally. Starting in an existing conversation preserves its context for one complete bootstrap run so the agent can compile what matters.
53
+ Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
47
54
 
48
- - `/state-flow-start` — Enable active memory projection on the current branch.
49
- - `/state-flow-status` — Inspect effective memory, retained history and known recovery issues without scanning artifact sources or changing state.
50
- - `/state-flow-stop` — End active episode semantics without deleting memory. An interrupted run keeps its frozen handoff and available tool trajectory.
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.
51
58
 
52
- **Active mode is opt-in. Passive memory is available by default:** existing memory can be projected and explicitly read or patched without an active episode or State Flow compaction. Stop returns to that configured passive behavior; it does not erase memory or necessarily remove memory tools. Set `autoStart` to promote genuinely new sessions automatically. See [configuration and lifecycle](docs/usage.md#configuration).
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).
53
60
 
54
- ## Memory with explicit ownership
61
+ ## State model
55
62
 
56
- Every scope uses the same six planes, in this order:
63
+ ### Scopes and effective memory
57
64
 
58
- - **`intents`** — Courses of action actually chosen, not every possible task. Remove them when fulfilled, abandoned or superseded.
59
- - **`contract`** — Durable requirements, decisions, constraints and interface commitments.
60
- - **`working`** — Current observations, verified results, uncertainties and next checks.
61
- - **`artifacts`** — Descriptions and compiled knowledge keyed by exact source path. Refreshes belong to the source's registered scope; Skills belong to CWD.
62
- - **`response`** — The latest complete answer, captured by the runtime rather than authored in a model patch.
63
- - **`lazy`** — Supporting memory available through explicit reads, with its body omitted from ordinary baseline projection.
65
+ Memory has three ownership scopes:
64
66
 
65
- Ownership overlays **global → CWD → session**:
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.
66
70
 
67
- - **Global:** Reusable cross-project knowledge and preferences.
68
- - **CWD:** Reusable knowledge for this project.
69
- - **Session:** This branch's commitments and continuation.
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.
70
72
 
71
- A scope-local deletion can reveal a lower-scope value again. Scope changes ownership and precedence, not instruction authority. Remembered text never becomes a system instruction.
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.
72
74
 
73
- ### Small patches, precise reads
75
+ ### Semantic planes
74
76
 
75
- `patch_state` accepts one or more scope patches atomically. For example:
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.
83
+ - `response`: The latest complete answer, captured by the runtime.
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.
76
91
 
77
92
  ```json
78
93
  {
94
+ "cwd": {
95
+ "contract": { "verification": { "command": "npm test" } }
96
+ },
79
97
  "session": {
80
- "intents": {
81
- "verifyRelease": { "action": "Check the release build before publishing" }
82
- },
83
- "contract": { "runtime": "Node.js >=22.19.0" },
84
- "working": { "build": "Not checked yet" }
98
+ "intents": { "verify": { "action": "Run the checks before publishing" } },
99
+ "working": { "checks": "Pending" }
85
100
  }
86
101
  }
87
102
  ```
88
103
 
89
- The keys immediately inside a scope are `intents`, `contract`, `working`, `artifacts` and `lazy`. Project-specific grouping belongs **inside** those planes, not in keys such as `project.contract`. Unknown-key errors name the actual rejected key and list the permitted fields.
90
-
91
- During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference receives the accepted memory. Ordinary answers need no bookkeeping patch; `response` is runtime-owned.
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.
92
105
 
93
- `read_state` retrieves only the requested value:
106
+ `read_state` provides targeted current and historical access:
94
107
 
95
108
  ```json
96
- { "path": "session.intents" }
109
+ { "paths": ["effective.contract", "cwd.working", "session.intents"] }
97
110
  ```
98
111
 
99
- Unscoped paths address effective memory. Explicit scopes, retained boundaries such as `effective[1].working`, array ranges and `keys`/`patch` projections support targeted inspection. The default history window is **7 accepted transitions**, configurable from **0 to 100**; discarded history is unavailable, not reconstructed from Git. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
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.
100
116
 
101
- ## Persistence without a Git dependency
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.
102
118
 
103
- State normally lives under `~/.pi/agent/state-flow/`, independently of registered artifact sources. Each scope's canonical `checkpoint.json`, `patches.jsonl` and `meta.json` own its current state and retained history. Session configuration and runtime metadata remain separate.
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).
104
120
 
105
- **Git is backup, not storage authority.** When the store is already a Git repository, an accepted active turn may produce a best-effort backup. Git backup needs a configured commit identity; canonical state does not. If backup fails, State Flow preserves accepted state and warns the user. It does not fall back between competing storage backends or wait for a remote push.
121
+ ## Persistence, backups and continuity
106
122
 
107
- Resume and tree navigation select the retained session boundary while global/CWD memory stays shared and current. New sessions get their own session layer; supported native forks copy selected session memory into a new owner. Expired or contradictory boundaries fail closed instead of silently substituting newer private state. See [fork limits](docs/usage.md#fork-support-and-limits).
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.
108
124
 
109
- **Upgrading from older storage formats:** 0.17 accepts only its canonical file contract and has no in-place predecessor converter. Preserve your store and read the [format/recovery boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or locations. A new path does not move existing memory automatically.
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.
110
126
 
111
- ## Keep memory useful
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).
112
128
 
113
- Two packaged Skills provide on-demand guidance:
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.
114
130
 
115
- - **`state-flow-guide`** — Concrete questions about reads, patches, scope inheritance, source acquisition and recovery.
116
- - **`state-flow-memory`** — Bounded curation when explicitly requested. Ask: **“Review and clean State Flow state.”**
131
+ ## Operational boundaries
117
132
 
118
- Normal handoffs reconcile touched memory; dedicated cleanup is not an automatic audit after every task. Preserve consequential uncertainty, verify ownership before removing data, and verify external destination acceptance before deleting a transferred source. Semantic references are navigation hints, not automatic hydration, execution or dependency tracking.
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.
119
134
 
120
- ## Where the boundary stays
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.
121
136
 
122
- - **Not a second agent.** No background reasoning, scheduler or replacement for Pi's session controls.
123
- - **Not live workspace truth.** Revalidate consequential observations before acting. Restored memory does not undo external tool effects.
124
- - **Not a token or latency guarantee.** State and the active trajectory are not size-capped; benefits depend on workload and curation. [Performance evidence](docs/performance.md) separates measured copying work from end-to-end cost.
125
- - **Not a transcript replacement.** Pi retains its full inspectable trace. Use ordinary Pi context when the model needs every historical exchange verbatim.
126
- - **Not secret storage.** Memory, diagnostic logs and backups may contain sensitive content. Deletion from current state does not erase older histories or remote copies. Use a dedicated store and review what you retain.
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.
127
138
 
128
139
  ## Documentation and development
129
140
 
130
- - [Usage and recovery](docs/usage.md) — Configuration, lifecycle, diagnostics and safe storage operations.
131
- - [Architecture](docs/architecture.md) — Semantic model, temporal boundaries, artifacts and public integration contracts.
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.
132
143
  - [SDK compatibility](docs/compatibility.md) — Tested stacks and verification limits.
144
+ - [Performance](docs/performance.md) — Measurements, workload definitions and limits.
133
145
  - [Acceptance map](docs/temporal-acceptance.md) — Properties tied to concrete tests.
134
146
  - [Documentation index](docs/README.md) — All maintained guides.
135
147
 
136
- For development, run `npm install` and `npm run validate`. The opt-in `npm run benchmark` workload is separate from the normal suite; see `benchmarks/README.md` in a source checkout.
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.
137
149
 
138
150
  Project context: [AGENTS.md](AGENTS.md), [BACKLOG.md](BACKLOG.md), [CHANGELOG.md](CHANGELOG.md).
@@ -423,7 +423,8 @@ export class TemporalRuntime {
423
423
  let basis = this.view;
424
424
  let base = this.base;
425
425
  let basisProvenance = this.provenanceByScope;
426
- if (this.semanticRevision) {
426
+ // First passive writes also reconcile their selected basis; origin-only acceptance keeps its strict CAS.
427
+ if (this.semanticRevision || accepted !== undefined || provenanceScopes.length > 0) {
427
428
  const changedScopes = new Set([
428
429
  ...(accepted?.transitions ?? []).map(({ scope }) => scope),
429
430
  ...provenanceScopes,
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.17.1",
3
+ "version": "0.17.3",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [
package/lib/runtime.ts CHANGED
@@ -438,7 +438,8 @@ export class TemporalRuntime {
438
438
  let basis = this.view;
439
439
  let base: TemporalFileBase = this.base;
440
440
  let basisProvenance = this.provenanceByScope;
441
- if (this.semanticRevision) {
441
+ // First passive writes also reconcile their selected basis; origin-only acceptance keeps its strict CAS.
442
+ if (this.semanticRevision || accepted !== undefined || provenanceScopes.length > 0) {
442
443
  const changedScopes = new Set<StateScope>([
443
444
  ...(accepted?.transitions ?? []).map(({ scope }) => scope),
444
445
  ...provenanceScopes,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.17.1",
3
+ "version": "0.17.3",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [