@llblab/pi-state-flow 0.22.0 → 0.24.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 +43 -56
- package/BACKLOG.md +14 -5
- package/CHANGELOG.md +17 -1
- package/LICENSE +21 -0
- package/README.md +8 -10
- package/dist/lib/compaction.d.ts +1 -1
- package/dist/lib/compaction.js +1 -1
- package/dist/lib/config.js +5 -4
- package/dist/lib/extension.js +244 -54
- package/dist/lib/git.d.ts +2 -2
- package/dist/lib/git.js +16 -5
- package/dist/lib/logging.d.ts +4 -1
- package/dist/lib/logging.js +1 -0
- package/dist/lib/session.d.ts +10 -1
- package/dist/lib/session.js +60 -1
- package/dist/lib/snapshot.d.ts +6 -0
- package/dist/lib/snapshot.js +8 -5
- package/dist/lib/telegram.d.ts +1 -1
- package/dist/lib/telegram.js +15 -10
- package/dist/package.json +12 -11
- package/dist/skills/state-flow-guide/SKILL.md +1 -1
- package/docs/README.md +1 -0
- package/docs/agent-contract-relocation.md +72 -0
- package/docs/architecture.md +30 -24
- package/docs/compatibility.md +4 -4
- package/docs/fork-contract.md +4 -2
- package/docs/temporal-acceptance.md +2 -2
- package/docs/usage.md +24 -19
- package/lib/compaction.ts +2 -2
- package/lib/config.ts +5 -4
- package/lib/extension.ts +227 -54
- package/lib/git.ts +14 -5
- package/lib/logging.ts +5 -1
- package/lib/session.ts +52 -1
- package/lib/snapshot.ts +7 -5
- package/lib/telegram.ts +15 -11
- package/package.json +12 -11
- package/skills/state-flow-guide/SKILL.md +1 -1
package/docs/usage.md
CHANGED
|
@@ -18,33 +18,34 @@ One session-owned `mode` selects these behaviors; there are no independent passi
|
|
|
18
18
|
|
|
19
19
|
Here, “bootstrap from state” means constructing model context from durable memory. The implementation's `meta.bootstrap` is narrower: the one transition run that retains an existing conversation while active mode is first enabled and that conversation is compiled into state. It is not a flag that must be re-entered on every active iteration. Native compaction is also separate from model-context projection; its safety checks and usage threshold still apply.
|
|
20
20
|
|
|
21
|
-
Active, Passive and Off select the current session's workflow and model-facing access
|
|
21
|
+
Active, Passive and Off select the current session's workflow and model-facing access, not a different storage algorithm. Native Off attachment defers memory acquisition, including creation of a fork's private memory, until explicit Passive/Active selection. Once acquired, a fork owns Session state copied from the selected parent boundary and lives independently in its selected mode. See [fork support](#fork-support-and-limits).
|
|
22
22
|
|
|
23
23
|
### Lifecycle operations
|
|
24
24
|
|
|
25
|
-
`/state-flow-active` activates the current Pi branch over validated current same-session memory, initializing absent storage when safe. No remote is required. Starting mid-conversation retains Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state. Repeating Active while already active leaves the in-progress run unchanged. On an attached branch, current-memory activation waits asynchronously for a coherent canonical cohort; pending repeats share the wait. Until acceptance, the existing inactive mode and any write fence remain in effect. Passive, Off or branch selection can withdraw obsolete activation; an error after acceptance does not undo accepted memory.
|
|
25
|
+
`/state-flow-active` activates the current Pi branch over validated current same-session memory, initializing absent storage when safe. No remote is required. Starting mid-conversation retains Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state. Repeating Active while already active leaves the in-progress run unchanged. On an attached branch, current-memory activation waits asynchronously for a coherent canonical cohort; pending repeats share the wait. Until acceptance, the existing inactive mode, deferred historical selection and any write fence remain in effect. Cancelling pending Active from Off preserves later acquisition choices; a superseding Passive still selects its retained private boundary rather than newer current memory, and ordinary cancellation creates no write fence. Passive, Off or branch selection can withdraw obsolete activation; an error after acceptance does not undo accepted memory.
|
|
26
26
|
|
|
27
|
-
- **New session:** Adopts global `mode`, defaulting to
|
|
28
|
-
- **Resume:**
|
|
29
|
-
- **Tree navigation:**
|
|
27
|
+
- **New session:** Adopts global `mode`, defaulting to Off. An inactive default is recorded once in Pi as `{mode:"off"}` or `{mode:"passive"}` without creating semantic storage. An Active default initializes a distinct empty Session layer over global/CWD memory, never another session's private continuation.
|
|
28
|
+
- **Resume:** Retains the selected session's mode; Passive/Active restore state and lineage, while Off attaches native policy only without probing semantic files or emitting recovery warnings. Later global default changes do not override it.
|
|
29
|
+
- **Tree navigation:** In Passive/Active, restores the selected retained private boundary over live shared scopes without checking out or resetting the shared store. Off defers this acquisition until explicit mode selection.
|
|
30
30
|
- **Abort inference:** Stops generation or an outstanding response-publication wait while already accepted patches remain durable for continued work and corrected direction in the same session. Cancellation before response acceptance keeps the previous response and unfinished run; cancellation after acceptance never rolls it back. It does not require immediate remote replication.
|
|
31
31
|
- **Native boundary continuation:** A companion may continue through Pi's `turn_end` or `agent_before_settle` boundary without a new user prompt. State Flow keeps projecting current memory and accepted response across those requests and subsequent patches; it does not restore the completed specification or request another turn itself.
|
|
32
|
-
- **Passive
|
|
33
|
-
- **
|
|
32
|
+
- **Passive:** `/state-flow-passive` enables both memory tools and projection. A proven pre-runtime branch records only `{mode}` in Pi and loads shared memory read-only. Accepted runtimes persist Passive and adopt unrelated shared drift without semantic/provenance writes or revision/step changes. Pending repeats share one acceptance.
|
|
33
|
+
- **Off:** `/state-flow-off` removes memory tools/context, cancels owned restoration/fork, activation, preparation, response, patch and Passive-persistence waits, and clears semantic caches immediately. It saves native policy and continuation/fork bookmarks only; existing canonical bytes, including the old stored runtime mode, stay untouched even when malformed or busy. Repeated Off is inert. Already accepted data is preserved; future explicit Passive/Active reacquires memory. Global defaults and other sessions remain unchanged.
|
|
34
|
+
- **If Passive cannot persist:** The selected Passive policy stays applied; Off itself never attempts canonical persistence. Accepted memory and native conversation remain intact; Off still exposes no State Flow context or tools. Pi records the selected mode and a write fence, not a replacement semantic checkpoint. Tree/reload/resume in Passive read validated current same-session memory without publishing or restoring an older selection. Off retains native policy and the write fence without reading memory; explicit Passive may acquire that read-only current authority later. Newer mode choices survive an in-flight read-only recovery. Repeating the same choice is inert; changing inactive mode updates only native policy and keeps the fence. Explicit Active clears the fence only after canonical acceptance. This fallback requires a writable Pi trace and never repairs storage; native fenced policy overrides an older canonical config.
|
|
34
35
|
- **Continue in Passive after Active:** The same physical session projects a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. Outside an unfinished bootstrap, a proven active boundary excludes completed earlier conversation; when native split-turn compaction removed the original request anchor, Stop instead preserves the available summary and tools without reconstructing discarded raw input. An unfinished bootstrap keeps all available native context, or the earlier passive boundary it received; repeated Start/Stop cannot move that boundary past uncompiled conversation. An interrupted run retains its captured anchor even after Pi becomes idle, falling back to all available context when that anchor is unknown. Other extensions' custom context survives. Only Stop after a completed idle run retains just later conversation plus foreign custom context. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Mid-tool Start and repeated Start/Stop retain the first user event already observed while disabled, so subsequent Stop does not mistake that busy run for idle. Active restart uses the retained projection for one bootstrap run. Off retains this boundary for a later Passive/Active selection but never projects it.
|
|
35
|
-
- **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest run—from its original request through steering, tools, foreign context and final answer—in active history and retains the complete append-only JSONL/tree. State Flow uses the native first-user anchor, independent of image-normalization hints or later steering; images and earlier tool results remain available to the model. Uncertain projection retains available context without changing that anchor. A missing or ambiguous native anchor skips compaction instead of choosing the last steering message. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
|
|
36
|
+
- **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest run—from its original request through steering, tools, foreign context and final answer—in active history and retains the complete append-only JSONL/tree. State Flow uses the native first-user anchor, independent of image-normalization hints or later steering; images and earlier tool results remain available to the model. Uncertain projection retains available context without changing that anchor. A missing or ambiguous native anchor skips compaction instead of choosing the last steering message. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/abort/error, Stop and pending input prevent State Flow-owned shortening; obsolete/inactive owned requests are canceled before their hook can fall through to a model summary, and late completion cannot clear a newer request; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
|
|
36
37
|
|
|
37
38
|
State Flow does not undo tool effects. After interruption or returning to an older branch, check the relevant workspace or external system before repeating consequential operations. Restored memory is not restored reality.
|
|
38
39
|
|
|
39
40
|
### Fork support and limits
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
Memory-enabled native fork replacement copies the source session checkpoint, retained patch tail and matching provenance into the new session's own storage. Off records child-owned pending-fork policy only, deferring header/store reads and copying until explicit Passive/Active, including after cold reload. Global/CWD values and provenance stay current; applying a smaller `historyLimit` may fold shared tails under CAS. An earlier fork selection copies that point's private state, not the parent's later private work. Parent-private data/history remain intact; the selected mode is retained, so an inactive source does not become Active automatically.
|
|
42
43
|
|
|
43
44
|
The child starts at step zero and a new temporal origin. Its copied tail obeys the configured retention limit, but pre-origin records are not additional aligned causal boundaries addressable through `effective[n]` or scoped paths. The child's own transitions build its hot window; owned checkpoints support normal reload/resume. Parent Stop projection is not inherited, including after child reload.
|
|
44
45
|
|
|
45
46
|
Initial copying requires a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing/unsafe evidence or CAS conflicts leave the copy unavailable rather than importing unrelated or newer private state. Explicit Start can retry an unaccepted copy in the same loaded fork after the cause is corrected.
|
|
46
47
|
|
|
47
|
-
Selecting a copied parent checkpoint through the child's `/tree` does not make it child-owned: historical restoration stays disabled without resetting existing child data. Select a child-owned checkpoint, resume the original session, or explicitly Start from the validated current child-owned memory; Start does not copy newer parent data. Cold recovery before the first child checkpoint
|
|
48
|
+
Selecting a copied parent checkpoint through the child's `/tree` does not make it child-owned: historical restoration stays disabled without resetting existing child data. Select a child-owned checkpoint, resume the original session, or explicitly Start from the validated current child-owned memory; Start does not copy newer parent data. Cold recovery before the first child checkpoint requires an Off-deferred pending-fork marker; otherwise it and startup paths lacking the fork event remain unsupported. In-memory parent locators and cross-CWD imports remain unsupported. File-only copying requires an exact still-available source cohort. See the [contract](fork-contract.md) and [SDK compatibility boundary](compatibility.md#public-host-seams); do not rewrite UUIDs or delete pointers to force recovery.
|
|
48
49
|
|
|
49
50
|
## Configuration
|
|
50
51
|
|
|
@@ -52,7 +53,7 @@ Optional global `config.json` at the root of the State Flow repository, normally
|
|
|
52
53
|
|
|
53
54
|
```json
|
|
54
55
|
{
|
|
55
|
-
"mode": "
|
|
56
|
+
"mode": "off",
|
|
56
57
|
"logging": false,
|
|
57
58
|
"showSuccessfulPatches": true,
|
|
58
59
|
"historyLimit": 7
|
|
@@ -60,12 +61,16 @@ Optional global `config.json` at the root of the State Flow repository, normally
|
|
|
60
61
|
```
|
|
61
62
|
|
|
62
63
|
The canonical store is `state-flow/` beneath the agent directory. Keeping configuration inside that repository removes the separate agent-level `state-flow.json`; SDK embeddings may still provide an explicit repository override.
|
|
63
|
-
- `mode`: `"active"`, `"passive"` or `"off"`; defaults to `"
|
|
64
|
-
- `logging`: Defaults to `false`. When enabled, records rejected
|
|
64
|
+
- `mode`: `"active"`, `"passive"` or `"off"`; defaults to `"off"`. Supplies the default only for genuinely new sessions. Active initializes missing storage when safe; Passive reads existing memory without publishing, and its first explicit patch may initialize absent storage without starting an episode or compaction. Off exposes neither memory tools nor State Flow context.
|
|
65
|
+
- `logging`: Defaults to `false`. When enabled, records rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
|
|
65
66
|
- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
|
|
66
67
|
- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
|
|
67
68
|
|
|
68
|
-
Session `config.json` uses the same `mode` key for its concrete choice; commands and Telegram change that session only. Before canonical runtime acceptance, Pi's native `{mode}` checkpoint owns the choice instead of a manufactured storage pair. Edit global defaults manually or through an authorized agent, not `patch_state`. Legacy flag decoding is read-only; see [mode compatibility](compatibility.md#mode-configuration-compatibility).
|
|
69
|
+
Session `config.json` uses the same `mode` key for its concrete choice; commands and Telegram change that session only. Before canonical runtime acceptance, Pi's native `{mode}` checkpoint owns the choice instead of a manufactured storage pair. Off remains native-only even after an accepted runtime: its mode/bookmark overrides the earlier canonical mode without requiring store access or granting semantic authority. Edit global defaults manually or through an authorized agent, not `patch_state`. Legacy flag decoding is read-only; see [mode compatibility](compatibility.md#mode-configuration-compatibility).
|
|
70
|
+
|
|
71
|
+
**Passive model-facing footprint:** When selected, Passive declares both memory tools even with no canonical store; its system-prompt section and projected memory message appear only after a validated memory view is loaded. New sessions default to Off, which exposes none of these State Flow model-facing surfaces. With unavailable memory the tools may still reject reads or writes; declared tools do not prove usable storage.
|
|
72
|
+
|
|
73
|
+
A source-bound UTF-8 byte probe of the 0.22.0 tree (`3242d762`, isolated `tests/harness.ts` and `tests/storage-fixture.ts`, default config, empty native transcript, `before_agent_start("Probe")` then `context`) measured the two `{name,description,parameters}` tool definitions as **1,728 JSON bytes**. A wholly absent store added **0 protocol and 0 projected-message bytes**. A validated empty Global state (`{}`) added **959 protocol bytes** and **321 serialized message bytes**; `global.working={sample:"x"}` added the same **959** plus **351 message bytes**. These component sizes include the projection marker in the message but exclude native prompt/tool wrappers, conversation, provider tokenization and variable user memory; they are not token-cost or cache-hit claims.
|
|
69
74
|
|
|
70
75
|
Settings are read once at extension load. After editing, use `/reload` or restart Pi. A missing file uses defaults without creating a configuration file; malformed JSON, unknown keys, or invalid values fail loading rather than silently selecting another store.
|
|
71
76
|
|
|
@@ -73,9 +78,9 @@ Settings are read once at extension load. After editing, use `/reload` or restar
|
|
|
73
78
|
|
|
74
79
|
### Diagnostic logging and privacy
|
|
75
80
|
|
|
76
|
-
Rejected
|
|
81
|
+
Rejected `patch_state` execution records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. The `barrier-block` category instead records only the blocked tool name, call id, reason and batch tool names (never sibling arguments or reasoning); Passive has no patch barrier, and logging off records no barrier blocks. Asynchronous push failures retain the available redacted Git error there regardless of `logging`; interactive warnings stay short and appear once per failure streak, then reset on success. If logging the push failure is unavailable, one warning exposes the available detail instead. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
|
|
77
82
|
|
|
78
|
-
Logs remain local unless you move them; rotation/deletion is operator-owned. State Flow-authored errors and warnings display as one compact line: long operands
|
|
83
|
+
Logs remain local unless you move them; rotation/deletion is operator-owned. State Flow-authored errors and warnings display as one compact line: flatten nested/aggregate causes into transportable text rather than relying on `Error.cause`. Elide long operands with `…` before shortening prose so the operation, exact offending scope, target basename/suffix and actionable reason remain visible; do not split Unicode pairs or mistake prose apostrophes for quoted paths. Enabled diagnostic records keep the full target and rejected input for investigation. An explicit Start retry reports its final failure once rather than repeating its startup warning. Tool failures still keep the required blank line beneath their heading. Treat logs and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
|
|
79
84
|
|
|
80
85
|
## Status and controls
|
|
81
86
|
|
|
@@ -87,7 +92,7 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Sta
|
|
|
87
92
|
|
|
88
93
|
Status omits the already-visible mode and generic ownership/configuration prose. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
|
|
89
94
|
|
|
90
|
-
The terminal indicator is accent `state-flow` plus dim `active` or `passive`; Off hides it. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the compact lowercase `g#c#s#` revision vector, without slashes or spaces between counters. That vector appears in `/state-flow-status` and Telegram's Effective inspection, not the compact indicators. When `pi-telegram` is available, its main-menu section shows `State Flow: active`, `State Flow: passive` or `State Flow: off`. Off exposes neither tool nor State Flow model context. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. During a failed-
|
|
95
|
+
The terminal indicator is accent `state-flow` plus dim `active` or `passive`; Off hides it. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the compact lowercase `g#c#s#` revision vector (for example, `g15c8s31`), without slashes or spaces between counters. That vector appears in `/state-flow-status` and Telegram's Effective inspection, not the compact indicators. When `pi-telegram` is available, its main-menu section shows `State Flow: active`, `State Flow: passive` or `State Flow: off`. Off exposes neither tool nor State Flow model context. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. During a failed-Passive write fence, memory-enabled inspection uses the accepted cache without a potentially conflicting refresh. Otherwise, Telegram inspection waits cancelably to load or refresh one coherent shared view, even when passive model tools are disabled. It does not initialize, publish, or advance storage. Data and displayed revisions belong to the same observation; absent/invalid memory stays unavailable. Stop, session/tree changes and shutdown cancel obsolete observations. The button acknowledges immediately, and a late failure appears in the menu instead of an expired callback popup. The submenu heading displays the current value in monospace. The bold Mode heading uses a long dash, description ending in a colon, and a blank line before its settings-style list. Each line uses a monospaced minus and lowercase monospaced mode value, then a plain colon and description. The descriptions progress from regular chat with no memory (Off, the new-session default), to ordinary chat with memory tools and an available combined memory view (Passive), to the same memory access with completed answers followed by memory-first continuation (Active); they do not claim a new physical Pi session or disable native compaction. The bold Inspect memory heading follows the same long-dash-description-colon and blank-line pattern. Its four lines use the same monospaced minus/value and plain colon format for `global`, `cwd`, `session` and `effective`, describing individual scopes and their combined view. Explicit Off inspection reads current stored memory through a disposable reader; Session and Effective require validated same-session private authority and cannot show a fabricated empty layer or revision. Shared Global/CWD inspection remains available independently of private failures. These reads install no model/runtime cache, change no bytes or mode, clear no write fence, and leave the selected historical/fork boundary intact for future Passive/Active acquisition; automatic Off callbacks never acquire memory. Current stored data is not proof that a selected past boundary is restorable. A horizontal radio row presents `Off | Passive | Active`: the selected option uses 🟡, 🟣 or 🟢 respectively, and each inactive option uses ⚫️. Four direct Global/CWD/Session/Effective buttons follow without another chooser. Ordinary successful controls add no redundant mode receipt; diagnostic outcomes remain visible. Telegram Active requested during a run waits for settlement; Passive and Off apply immediately. All controls use the same lifecycle owners as the terminal commands. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
|
|
91
96
|
|
|
92
97
|
## Storage and recovery
|
|
93
98
|
|
|
@@ -118,7 +123,7 @@ Missing artifact provenance inside an otherwise complete scope `meta.json` means
|
|
|
118
123
|
|
|
119
124
|
Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
|
|
120
125
|
|
|
121
|
-
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. The local attempt completes before settlement continues. Its capture waits cancelably when Pi supplies an operation signal; on Pi 0.87 that signal is absent at settlement, so an occupied backup/storage mutex explicitly defers backup until a later accepted turn instead of trapping Abort. Deferral neither changes memory nor starts a push.
|
|
126
|
+
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. The local attempt completes before settlement continues. Its capture waits cancelably when Pi supplies an operation signal; on Pi 0.87 that signal is absent at settlement, so an occupied backup/storage mutex explicitly defers backup until a later accepted turn instead of trapping Abort. Deferral neither changes memory nor starts a push. Off and shutdown cancel owned pending local attempts. Only cleanup of already-acquired locks/resources may continue; no new capture is admitted in Off. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Within one Pi process, an in-flight push per repository skips overlapping attempts; a later accepted turn retries the latest backup without a durable queue. Off terminates only its admitted push and suppresses canceled reporting; an overlapping caller cannot revoke another owner's push. Normal completion of the agent operation does not revoke independent push ownership. Shutdown cancels its own pushes and waits for that repository's in-flight push to close or time out. Already accepted local/remote commits are never rolled back by cancellation. Commit or push failure is diagnostic-only; repeated push failures warn once per failure streak and remain locally diagnosable. Git availability never changes semantic authority, step, or retained lineage.
|
|
122
127
|
|
|
123
128
|
### Moving a store and the 0.17 format boundary
|
|
124
129
|
|
|
@@ -134,7 +139,7 @@ Final-answer reconciliation also waits cancelably, then saves the response and c
|
|
|
134
139
|
|
|
135
140
|
Run preparation and missing-artifact maintenance wait cancelably before the first enabled inference, accepting current shared memory and lifecycle together. If preparation fails, State Flow aborts that native operation rather than sending a rejected or stale draft to the provider; previously accepted memory remains available. Cancellation can leave the new request without a specification checkpoint, so its native conversation is conservatively preserved through idle Stop/reload. Boundary continuation never replays a completed specification.
|
|
136
141
|
|
|
137
|
-
Telegram shared inspection also awaits exclusion read-only. Backup capture also uses the awaited API, with the no-signal settlement exception described above. Accepted-runtime Passive
|
|
142
|
+
Telegram shared inspection also awaits exclusion read-only. Backup capture also uses the awaited API, with the no-signal settlement exception described above. Accepted-runtime Passive selection changes local tools/context immediately, then awaits runtime-only persistence; pending repeats share one acceptance. Off cancels that wait and records native policy without acquiring the store. Selection/shutdown or a successful Start cancel obsolete Stop work. An available host operation signal can cancel persistence without restoring an older mode; idle commands do not necessarily have that signal. Current-head Start similarly waits before enabling mode, with Stop/selection/shutdown cancellation and any available native operation signal. Startup, tree, auto-start, fork and failed-Stop reload restoration, including Start's initial attachment and fork retry, also await exclusion; until acceptance, mode stays in the selected inactive policy and private memory reports the pending selection. Off remains Off; later inactive choices survive read-only recovery without cancelling it. Interrupted, malformed or unreadable locks are never stolen. Reconcile the owner rather than deleting locks or state directories merely because an operation is slow. File-cohort exclusion, exact prepared bytes and compare-and-swap checks are not kernel-atomic multi-file transactions against nonparticipating writers.
|
|
138
143
|
|
|
139
144
|
Fatal process termination can leave an incomplete canonical file cohort. Before repair, quiesce all store writers and preserve the complete store plus selected Pi retained-boundary references. Reconcile exact files against the last complete checkpoint/tail/metadata cohort; no automatic crash repair or power-loss durability is promised. Git backup has no semantic recovery authority.
|
|
140
145
|
|
package/lib/compaction.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type
|
|
1
|
+
import type { AgentMessage } from "@earendil-works/pi-agent-core";
|
|
2
|
+
import { estimateTokens, type CompactionResult } from "@earendil-works/pi-coding-agent";
|
|
3
3
|
|
|
4
4
|
export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
|
|
5
5
|
/** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
|
package/lib/config.ts
CHANGED
|
@@ -27,8 +27,8 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
|
|
|
27
27
|
const path = join(directory, "config.json");
|
|
28
28
|
const defaults: StateFlowConfig = {
|
|
29
29
|
directory,
|
|
30
|
-
mode: "
|
|
31
|
-
inactiveMode: "
|
|
30
|
+
mode: "off",
|
|
31
|
+
inactiveMode: "off",
|
|
32
32
|
logging: false,
|
|
33
33
|
showSuccessfulPatches: true,
|
|
34
34
|
historyLimit: DEFAULT_HISTORY_LIMIT,
|
|
@@ -53,11 +53,12 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
|
|
|
53
53
|
if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean") throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
|
|
54
54
|
if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || (value.historyLimit as number) < 0 || (value.historyLimit as number) > MAX_HISTORY_LIMIT)) throw new Error(`State Flow historyLimit must be an integer from 0 to ${MAX_HISTORY_LIMIT}: ${path}`);
|
|
55
55
|
const legacyInactive: InactiveMode = value.passiveBootstrap !== false || value.passiveTools !== false ? "passive" : "off";
|
|
56
|
-
const
|
|
56
|
+
const hasLegacyMode = Object.hasOwn(value, "autoStart") || Object.hasOwn(value, "passiveBootstrap") || Object.hasOwn(value, "passiveTools");
|
|
57
|
+
const mode = isStateFlowMode(value.mode) ? value.mode : value.autoStart === true ? "active" : hasLegacyMode ? legacyInactive : "off";
|
|
57
58
|
return {
|
|
58
59
|
directory,
|
|
59
60
|
mode,
|
|
60
|
-
inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : legacyInactive,
|
|
61
|
+
inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : hasLegacyMode ? legacyInactive : "off",
|
|
61
62
|
logging: value.logging === true,
|
|
62
63
|
showSuccessfulPatches: value.showSuccessfulPatches !== false,
|
|
63
64
|
historyLimit: typeof value.historyLimit === "number" ? value.historyLimit : DEFAULT_HISTORY_LIMIT,
|