@llblab/pi-state-flow 0.17.0 → 0.17.1

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,11 @@
2
2
 
3
3
  > Each release keeps at most 8 outcome records of at most 512 characters.
4
4
 
5
+ ## 0.17.1: precise patch diagnostics and clearer onboarding
6
+
7
+ - `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.
8
+ - `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.
9
+
5
10
  ## 0.17.0: canonical memory and native Pi integration
6
11
 
7
12
  - `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,7 +4,7 @@
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
+ 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.
8
8
 
9
9
  > Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2).
10
10
 
@@ -20,25 +20,22 @@ Updated state + Answer
20
20
  Next request
21
21
  ```
22
22
 
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.
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.
24
27
 
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.
28
+ Memory is curated knowledge, not proof: an accurately stored observation can still become stale.
26
29
 
27
- ## Quick start
30
+ ## Get started
28
31
 
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.
30
-
31
- From npm:
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).
32
33
 
33
34
  ```bash
34
35
  pi install npm:@llblab/pi-state-flow
35
36
  ```
36
37
 
37
- From git:
38
-
39
- ```bash
40
- pi install git:github.com/llblab/pi-state-flow
41
- ```
38
+ Or install from source with `pi install git:github.com/llblab/pi-state-flow`.
42
39
 
43
40
  In Pi:
44
41
 
@@ -46,51 +43,96 @@ In Pi:
46
43
  /state-flow-start
47
44
  ```
48
45
 
49
- Continue working normally. The agent receives the state protocol and uses `patch_state` to maintain memory.
46
+ Then work normally. Starting in an existing conversation preserves its context for one complete bootstrap run so the agent can compile what matters.
47
+
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.
51
+
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).
53
+
54
+ ## Memory with explicit ownership
55
+
56
+ Every scope uses the same six planes, in this order:
57
+
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.
64
+
65
+ Ownership overlays **global → CWD → session**:
66
+
67
+ - **Global:** Reusable cross-project knowledge and preferences.
68
+ - **CWD:** Reusable knowledge for this project.
69
+ - **Session:** This branch's commitments and continuation.
70
+
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.
72
+
73
+ ### Small patches, precise reads
74
+
75
+ `patch_state` accepts one or more scope patches atomically. For example:
76
+
77
+ ```json
78
+ {
79
+ "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" }
85
+ }
86
+ }
87
+ ```
88
+
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.
92
+
93
+ `read_state` retrieves only the requested value:
94
+
95
+ ```json
96
+ { "path": "session.intents" }
97
+ ```
50
98
 
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.
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).
53
100
 
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).
101
+ ## Persistence without a Git dependency
55
102
 
56
- ## What carries forward
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.
57
104
 
58
- The same semantic planes exist at every scope:
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.
59
106
 
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.
64
- - `response`: The latest complete answer, captured by the runtime.
65
- - `lazy`: Durable, versioned memory omitted from ordinary context until explicitly read.
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).
66
108
 
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.
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.
68
110
 
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`.
111
+ ## Keep memory useful
70
112
 
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.
113
+ Two packaged Skills provide on-demand guidance:
72
114
 
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.
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.”**
74
117
 
75
- ## Boundaries worth knowing
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.
76
119
 
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.
120
+ ## Where the boundary stays
84
121
 
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.
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.
86
127
 
87
- ## Read more
128
+ ## Documentation and development
88
129
 
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.
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.
132
+ - [SDK compatibility](docs/compatibility.md) — Tested stacks and verification limits.
133
+ - [Acceptance map](docs/temporal-acceptance.md) — Properties tied to concrete tests.
134
+ - [Documentation index](docs/README.md) — All maintained guides.
93
135
 
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.
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.
95
137
 
96
- Project context: [AGENTS.md](AGENTS.md) · [BACKLOG.md](BACKLOG.md) · [CHANGELOG.md](CHANGELOG.md).
138
+ 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.1",
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.1",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [