@llblab/pi-state-flow 0.22.0 → 0.23.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 +42 -56
- package/BACKLOG.md +13 -5
- package/CHANGELOG.md +10 -0
- package/README.md +4 -6
- package/dist/lib/config.js +5 -4
- package/dist/lib/extension.js +6 -8
- package/dist/lib/logging.d.ts +4 -1
- package/dist/lib/logging.js +1 -0
- package/dist/lib/telegram.d.ts +1 -1
- package/dist/lib/telegram.js +15 -10
- package/dist/package.json +3 -3
- 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 +20 -18
- package/docs/compatibility.md +2 -2
- package/docs/temporal-acceptance.md +2 -2
- package/docs/usage.md +11 -7
- package/lib/config.ts +5 -4
- package/lib/extension.ts +6 -8
- package/lib/logging.ts +5 -1
- package/lib/telegram.ts +15 -11
- package/package.json +3 -3
- package/skills/state-flow-guide/SKILL.md +1 -1
package/AGENTS.md
CHANGED
|
@@ -1,58 +1,44 @@
|
|
|
1
1
|
# Agent Instructions
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
- Accept
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
- `/state-flow-passive` and `/state-flow-off` select their local tools/context policy before attempting canonical persistence; a rejected write never cancels that choice. Off never projects a frozen handoff. For an accepted runtime, await `withLifecycleTransaction` to persist only the current session/branch's selected `config.mode` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. Freeze the passive handoff and switch local policy/tools/UI before waiting; derive lifecycle input and recheck selected runtime/owner/policy after acquisition. Pending inactive choices share one operation whose acceptance persists the latest mode; repeated already-retained choices are inert. Selection, shutdown and successful Start cancel obsolete Stop work; a rejected Start must not cancel it. Combine an available Pi signal with Stop-owned cancellation, drain pending Stop on shutdown, and install caches/checkpoint inside acceptance before yielding. Pre-acceptance failure keeps the selected inactive mode and fences writes; post-acceptance failure cannot roll back accepted memory or replay native writes. A proven pre-runtime branch instead appends only its `{mode}` Pi checkpoint; a cached passive view never authorizes runtime publication or a retained-boundary checkpoint. Only accepted canonical publication ends that pre-runtime condition. Preserve failed-selection fences, passive access, and later explicit Start/passive patch behavior. Lifecycle-only writes adopt unrelated live shared drift at a fresh origin when needed, without touching semantic/provenance files or counters; same-session races and precomputed stale provenance writes still fail closed. Do not opportunistically fold tails or prune evidence during lifecycle persistence, even if another writer loaded a larger history limit. Refresh the host cache after adoption, freeze Stop's handoff from that accepted cache, and inspect newly adopted registered paths before the next enabled inference. Retain a frozen handoff plus the active user-run trajectory (including later tool results), post-stop conversation, and foreign context-bearing custom messages across same-physical-session reload/resume/tree. Exclude completed pre-run conversation only when the active boundary is proven. If a recorded active anchor is missing, nonfinite or ambiguous after native projection/compaction, reuse the active context selector and retain available summaries and tool trajectory; never fall back to the idle cutoff or reconstruct discarded raw entries. Only Stop after a completed idle run applies the post-stop cutoff. Unaccepted preparation and native conversation after the latest valid checkpoint also prevent an idle cutoff, even when a boundary continuation has no specification. Same-physical-session restoration conservatively retains such uncompiled context through the existing bootstrap flag; it neither invents a run anchor nor restores discarded raw entries. An unfinished bootstrap preserves all available native context unless an earlier passive boundary already bounded it; repeated mode toggles keep that earlier boundary until bootstrap completion. Persist this choice in the existing native Stop marker as optional `preserveContext: true`. After interruption, retain the captured native run anchor even when Pi is idle, or all available context when capture is absent. Active restart replaces passive mode but uses that bounded boundary for its one bootstrap run; new and forked physical sessions inherit neither projection. Neither command rewrites global `mode` or policy for future new sessions.
|
|
46
|
-
- A failed Stop records only local policy and a write fence in the existing native passive-stop marker: exact session `owner`, selected inactive `mode`, non-empty `persistenceError`, and `preserveContext: true`. Never append a substitute semantic checkpoint or reset canonical state. Preserve accepted cached memory and all available native context; same-session reload reads validated current memory without restoring/publishing an older selection. Corrupt or missing evidence remains unavailable, never invented empty private memory. Keep the fence until a later accepted checkpoint from explicit Start; Repeating the same degraded mode is inert; a different inactive choice updates native policy without clearing the fence. Status distinguishes unavailable memory from unavailable publication, and inspection may show the accepted cache without attempting a conflicting refresh. Forks retain disabled source policy but inherit neither the parent's fence nor its projection. Durable fallback requires a writable native Pi trace.
|
|
47
|
-
- After an accepted non-bootstrap run settles with no pending input, State Flow may request native manual compaction under a generation-private marker only when public `getContextUsage()` reports at least 24,000 tokens. Keep the complete latest accepted run from its already captured first-user anchor, including steering and tool results; never substitute the last user message. Require one matching native user timestamp before the final assistant, otherwise skip rather than guessing. Store only retained boundary/step identity in details, and never duplicate state in the summary. Unknown or smaller usage skips compaction; a benign native refusal releases the attempt for later work. Await the native compaction completion/error callback inside the settled handler before returning, so Pi's deferred companion prompt dispatch cannot race an in-flight manual compaction; do not add a timer, queue or continuation owner. Skip prefixes containing foreign custom metadata or native `custom_message` context. Never customize user manual or native threshold/overflow compaction, discard unfinished pre-patch work, create a State Flow origin, or rewrite Pi's append-only JSONL/tree.
|
|
48
|
-
- Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Contribute initial active/passive protocol through Pi's native `systemPromptOptions.sections.state_flow`, not a returned forced `systemPrompt`; refresh only that owned section at `context_with_system` from current mode so in-flight Stop/Start and boundary continuations do not retain stale instructions. Keep section projection pure in the context domain, preserve unchanged arrays/native deltas and non-system identities, and never invent missing system frames. Preserve companion sections, tool declarations, native trace and explicit foreign forced-prompt precedence. Foreign comment handling remains owned by other extensions.
|
|
49
|
-
- Do not claim strict boundedness for state, the current run trajectory, the turn specification, or the external full trace.
|
|
50
|
-
- Remain extension-agnostic in core semantics, storage, and inference: core modules never import, name, special-case, or encode policy for another extension or transport. One optional leaf presentation adapter (`lib/telegram.ts`) may import public `pi-telegram` membranes to show only `State Flow: active`, `State Flow: passive` or `State Flow: off` on its main-menu section button. Its submenu title names the selected mode in `<code>`, then describes all three choices with pi-telegram's `<code>-</code> <code>value</code>` settings-card grammar before one horizontal lowercase `off | passive | active` option row with only the current option marked and four direct Global/CWD/Session/Effective inspection buttons; there is no scope chooser. Controls share the owners of `state-flow-off`, `state-flow-passive` and `state-flow-active`. Owner-scope Rich snapshots show `#revision`, Effective shows the `g#c#s#` vector. Ordinary successful selections do not append a redundant mode receipt; warnings and failures remain visible. Inspection awaits `TemporalRuntime.refreshShared` for one coherent shared cohort, preserves the exact selected private basis, and never publishes or advances a revision. Telegram observation may lazily load existing shared canonical state even when passive model tools are disabled, but never initializes or mutates it; absent/invalid memory stays unavailable rather than becoming an invented empty Rich state. Return data and matching revisions together, revoke pending observations on Stop/selection/shutdown, and check their signal again before presentation. Acknowledge the callback before waiting; show escaped late diagnostics in the existing menu instead of answering an expired callback. The inspection-capable port also permits awaited `select(mode)` results with optional revocation signals; acknowledge controls before waiting without delaying local Stop on the network response. Discard revoked results, superseded callback views and disposed-section work; render late failures escaped in the existing menu without a second callback answer. Support synchronous mode-selection ports as well. Obsolete start/stop callback keyboards may refresh the view but never silently select a mode. Installing a control's own read-only cache must preserve its successful receipt; cancellation, replacement memory and newer selections still revoke obsolete work. Registration must fail open when the transport is absent or its registry is unready and must never alter core behavior.
|
|
51
|
-
- Activate both State Flow model tools in Active or Passive, and neither in Off; preserve every unrelated active tool when toggling them. Passive reads never initialize storage, while an explicit passive patch may initialize absent canonical storage without enabling an episode, continuation, or compaction. Unsupported predecessor storage is never converted. Keep mutation confined to `patch_state` and historical observation read-only.
|
|
52
|
-
- Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
|
|
53
|
-
- Keep opt-in performance executables and workers in top-level `benchmarks/`; their correctness regressions stay in `tests/`. Benchmark workloads may reuse synthetic test fixtures, remain excluded from runtime packaging, and retain source-bound measurement identities across relocations.
|
|
54
|
-
- In native scripted-provider tests, assert callback completion outside the provider as well as checking input inside it: Pi may convert an assertion thrown by a provider into an assistant error rather than rejecting the test's prompt. Do not count swallowed provider assertions as successful evidence.
|
|
55
|
-
- Await startup/tree lifecycle handlers in fixtures before inspecting their completed state. In contended-store cancellation tests, dispatch replacement selection without awaiting it, prove the obsolete operation withdraws while exclusion remains held, then release storage and join the replacement. Keep old-operation trace/notice checks distinct from legitimate replacement UI completion.
|
|
56
|
-
- Keep generated `dist/` in the release Git tree; do not re-add it to `.gitignore`. Rebuild from final sources and package metadata before release, include the resulting files in the release commit, and verify source/build parity as well as npm inventory. Git inclusion and npm `files` inclusion are distinct obligations.
|
|
57
|
-
- Keep maintained README/docs focused on current behavior, supported contracts and verification limits. Version comparisons, removed intermediates and implementation chronology belong in CHANGELOG, not current compatibility/architecture guidance.
|
|
58
|
-
- Run `npm run validate` after retained code changes, then run the canonical ABCd context validator after context edits.
|
|
3
|
+
The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compaction paragraph to its owning contract or test. Keep this file as durable development policy, not a second copy of the product manuals.
|
|
4
|
+
|
|
5
|
+
## Ownership and semantics
|
|
6
|
+
|
|
7
|
+
- Keep `index.ts` minimal, independent domains in `lib/` with same-named tests, architecture checks in `tests/invariants.test.ts`, and Pi lifecycle composition in `lib/extension.ts`; delegate low-level mechanics to their owners. See [composition](docs/architecture.md#composition).
|
|
8
|
+
- Keep Off the genuinely new-session default, with Passive and Active opt-in; Off removes State Flow model tools/context without deleting memory. Modes belong to the current session; global mode is only a new-session default. Passive declares both tools even without memory, but contributes protocol/projected state only with a validated view. See [mode behavior](docs/usage.md#active-passive-and-configured-off) and [configuration](docs/usage.md#configuration).
|
|
9
|
+
- Preserve Pi's native tool loop, trace and foreign context; the context domain alone projects the raw scope overlay. Freeze/rebase the head only at specified boundaries, retain current-run trajectory and stable-position tail notices, and never give projection IDs or guessed user anchors publication/compaction authority. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [projection evidence](docs/performance.md#context-projection-and-trajectory-selection).
|
|
10
|
+
- Store only present known `intents`, `contract`, `working`, `artifacts`, `response`, `lazy` fields; preserve nested data and retained causal identities. Missing planes and empty response do not become fabricated stored defaults; malformed evidence fails closed. Keep lazy bodies out of automatic projection and Session as the sole author of new responses. See [semantic state](docs/architecture.md#semantic-state) and [temporal model](docs/architecture.md#temporal-model).
|
|
11
|
+
- Respect global → CWD → session ownership, scope-local deletion and inherited fallbacks; scope does not confer instruction authority. Registered Skill ownership follows Pi source provenance, not path shape. See [semantic state](docs/architecture.md#semantic-state) and [artifact routing](docs/architecture.md#artifact-routing).
|
|
12
|
+
- Artifacts name exact registered source paths; observe only regular non-symlink files, never discover directories or read unrelated bodies. Preserve hidden per-scope provenance, exact-owner compilation, stable fingerprint checks and separate Skill hashes; unavailable sources are not proof of deletion. See [artifact routing](docs/architecture.md#artifact-routing).
|
|
13
|
+
- Preserve session config/runtime, per-scope metadata, lineage and provenance outside model-patchable state; decode legacy mode evidence read-only, never mix representations or normalize storage eagerly. See [storage and identity](docs/architecture.md#storage-and-identity) and [mode compatibility](docs/compatibility.md#mode-configuration-compatibility).
|
|
14
|
+
- Keep one opaque composed causal lineage, anchored checkpoint/tail materialization, configured hot-history folding and independent owner revisions; never invent earlier history or rebuild discarded offsets. Historical reads are observational, and `effective[n]`/owner materializations select the same causal boundary. See [temporal model](docs/architecture.md#temporal-model) and [model tools](docs/architecture.md#model-tools).
|
|
15
|
+
|
|
16
|
+
## Publication and lifecycle
|
|
17
|
+
|
|
18
|
+
- Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority, while incomplete/private evidence fails closed. Never repair through ad-hoc writes. See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
|
|
19
|
+
- Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and guarded rollback. Never hold exclusion across inference, source acquisition or Git; do not steal interrupted locks, claim kernel-atomic multi-file publication or promise power-loss durability. See [asynchronous transaction](docs/architecture.md#asynchronous-storage-transaction) and [durability boundary](docs/filesystem-recovery.md#power-loss-durability).
|
|
20
|
+
- Restore selected private retained boundaries over live shared scopes and copy exact proven source-session history into a fresh fork owner; never substitute current, empty, Git or another branch on expiry/failure. Explicit Start instead validates current same-session authority. Only accepted candidates install cache, checkpoint and mode. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
|
|
21
|
+
- Persist each material semantic change and its affected revisions exactly once, including accepted Session responses. Optional settled-turn Git backup may capture only already-accepted owned files, leave unrelated index/worktree data intact and push without force or semantic side effects. Defer busy backup on Pi 0.87 rather than blocking Abort; never move it to `turn_end` or add a durable push queue. See [optional Git backup](docs/architecture.md#optional-git-backup).
|
|
22
|
+
- Accept one atomic `patch_state` cohort across supplied scopes against current shared memory; reject empty scopes, unknown/retired grammar and model-authored `response`. Correct no-ops create no transition. Enforce the single-call inference barrier before sibling tools execute and retain conservative model-facing reconciliation when a result cannot be predicted. See [model tools](docs/architecture.md#model-tools) and [Pi lifecycle](docs/architecture.md#pi-lifecycle).
|
|
23
|
+
- Reconcile the actual accepted ordinary answer at `turn_end` with response-owned cancellation and one accepted lifecycle publication; do not request private repair inference, ceremonial finalization patches or roll back accepted memory after cancellation. See [Pi lifecycle](docs/architecture.md#pi-lifecycle).
|
|
24
|
+
- Capture specifications without writes at `before_agent_start`, then await one cancellable preparation acceptance before active inference; abort failed context preparation through Pi's public hook. Keep user text at user authority and state as fallible data. Preserve an existing conversation for exactly one bootstrap run, not forever. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [pre-inference cancellation](docs/compatibility.md#pre-inference-cancellation).
|
|
25
|
+
- Make Start await coherent current-head acceptance, and let Passive/Off select local policy before asynchronous runtime-only persistence. Preserve independently owned fork/restoration work and latest inactive choices; a failed Stop fences writes with a native marker, never a substitute semantic checkpoint. Off exposes no frozen handoff. See [lifecycle planes](docs/architecture.md#lifecycle-planes) and [lifecycle operations](docs/usage.md#lifecycle-operations).
|
|
26
|
+
- Request completed-history native compaction only after an accepted non-bootstrap settled run, public usage ≥24,000 tokens and a uniquely captured first-user anchor; retain the complete latest run and foreign context. Await its native callback before returning, and leave Pi manual/threshold compaction and append-only history alone. See [lifecycle planes](docs/architecture.md#lifecycle-planes).
|
|
27
|
+
- Contribute only State Flow's compact normative system-prompt section through Pi's section membrane; refresh it with current mode without overwriting foreign sections, forced-prompt precedence or native message identities. Never invent a continuation scheduler. See [lifecycle planes](docs/architecture.md#lifecycle-planes) and [host context compatibility](docs/compatibility.md#context-tools-and-provider-input).
|
|
28
|
+
|
|
29
|
+
## Model and operator boundaries
|
|
30
|
+
|
|
31
|
+
- Treat state as a decision-relevant handoff, not a transcript: distinguish user requirements, confirmed decisions, observations, hypotheses, chosen intents and remaining checks. Revalidate volatile external effects before repeating actions; memory is neither an action ledger nor proof of current reality. See [operational guidance](docs/architecture.md#operational-guidance-and-memory-curation) and the [memory Skill](skills/state-flow-memory/SKILL.md).
|
|
32
|
+
- Resolve semantic `$` paths and structured references only when needed; never confer authority or existence by reference alone, scan to find broken references, automatically search all history or restore deleted values from hints. See [model tools](docs/architecture.md#model-tools) and [lazy navigation](docs/usage.md#lazy-navigation-and-historical-reading).
|
|
33
|
+
- Keep Skill acquisition optional and exact-path/provenance-derived; successful reads alone are volatile, and attempted durable compilations require scoped validated output plus runtime-owned hash evidence. See [artifact routing](docs/architecture.md#artifact-routing).
|
|
34
|
+
- Reconcile touched state without automatic whole-store audits. Dedicated curation needs a user request; intra-store moves use one verified multi-scope patch, and external transfers need verified destination acceptance before source deletion. See [operational guidance](docs/architecture.md#operational-guidance-and-memory-curation) and the [memory Skill](skills/state-flow-memory/SKILL.md).
|
|
35
|
+
- Keep opt-in diagnostic categories, failure elision/privacy and barrier-only names-only records outside canonical state; logging failures cannot change accepted state. Preserve a blank line between every tool name and its output. See [diagnostic privacy](docs/usage.md#diagnostic-logging-and-privacy) and [barrier diagnostics](docs/architecture.md#pi-lifecycle).
|
|
36
|
+
- Keep public patch outputs and staged drafts detached from caller/accepted values; private path-copying must not leak mutable objects or weaken CAS. Reject stored null in documented semantic planes while preserving valid nested object-key deletions. See [storage and identity](docs/architecture.md#storage-and-identity) and [model tools](docs/architecture.md#model-tools).
|
|
37
|
+
- Do not add project schemas, state/patch byte caps, dynamic growth pressure, action authorization, automatic reference hydration or strict boundedness claims for state, the turn specification, the current-run trajectory or Pi's external trace. See [model tools](docs/architecture.md#model-tools) and [operational boundaries](README.md#operational-boundaries).
|
|
38
|
+
- Keep terminal status observational and mode-derived; no source maintenance or invented empty view on inspection. Optional Git, Telegram and diagnostics degrade without fabricated success or weakened memory ownership. The optional `lib/telegram.ts` presentation leaf alone may consume pi-telegram's public membranes; core semantics/storage/inference remain transport-agnostic. See [status and controls](docs/usage.md#status-and-controls) and [observability](docs/architecture.md#observability).
|
|
39
|
+
|
|
40
|
+
## Delivery discipline
|
|
41
|
+
|
|
42
|
+
- Keep the exact-tag [release workflow](.github/workflows/release.yml) as sole npm Trusted Publisher and GitHub Release owner; align version, lockfile, tag and changelog, with no long-lived npm-token fallback. Keep generated `dist/` tracked, rebuild after final source/package edits and verify source/build parity and npm inventory. See [validation boundaries](docs/architecture.md#validation-boundaries).
|
|
43
|
+
- Keep opt-in measurements under `benchmarks/`, excluded from normal tests/packaging, with source-bound workload identities. Native scripted-provider tests assert callback completion outside the provider; startup/tree and cancellation fixtures await the right ownership boundary. See [benchmark guide](benchmarks/README.md) and [temporal witnesses](docs/temporal-acceptance.md#required-properties-and-witnesses).
|
|
44
|
+
- Keep README/docs current rather than copying chronology out of CHANGELOG; preserve SKILL.state attribution for inherited explicit-state ideas. Exercise malformed/predecessor storage only in temporary repositories, never the user's active data. Run `npm run validate` after retained code changes and the canonical ABCd context validator after context edits. See [documentation index](docs/README.md) and [validation procedure](docs/compatibility.md#validation-procedure).
|
package/BACKLOG.md
CHANGED
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
# Backlog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The **0.23.0** release scope is recorded in [CHANGELOG.md](CHANGELOG.md); this backlog keeps installed-client evidence and later decisions open. Canonical storage, CAS, `historyLimit`, temporal semantics, projection and the model-facing protocol remain unchanged; already retained session modes and explicit global/legacy policies stay authoritative. Current contracts live in [architecture](docs/architecture.md) and [usage](docs/usage.md).
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Carried gates
|
|
6
6
|
|
|
7
|
-
- **
|
|
8
|
-
-
|
|
7
|
+
- **Installed 0.22.0 smoke (operator-owned):** Perform the carried check if it is not yet recorded, only against the exact released 0.22.0 installation; a reload of the modified 0.23.0 candidate cannot certify the old release. After an operator-authorized reload, confirm:
|
|
8
|
+
- terminal autocomplete exposes Active/Passive/Off and status;
|
|
9
|
+
- Telegram shows the single `off | passive | active` row plus the four inspection buttons;
|
|
10
|
+
- current-session mode agrees across tools, context and status, and survives reload.
|
|
11
|
+
Do not edit real global defaults or unrelated sessions.
|
|
12
|
+
- **Installed 0.23.0 smoke (operator-owned):** After separately authorized installation/reload, confirm an unconfigured *new* session is Off without semantic writes, retained choices and explicit global modes survive, and Telegram shows one `Off | Passive | Active` radio row with the selected 🟡/🟣/🟢 marker and ⚫️ inactive markers, followed by four direct scope inspections. Isolate test storage; do not use the live store as a fixture. SDK tests alone do not certify installed-client rendering.
|
|
13
|
+
|
|
14
|
+
## Deferred beyond 0.23.0 (decision inputs, not commitments)
|
|
15
|
+
- **Compaction threshold:** `STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24_000` is documented as a margin above Pi's default 20,000-token retained suffix. Make it configurable only if a real workload or non-default Pi retention settings demonstrate a mismatch.
|
|
16
|
+
- **Lifecycle complexity review:** Measure how often cooperating-writer waits, Stop fences and fork/restore contention occur in real use before adding further awaited lifecycle layers. Use the result to decide whether any existing layer can be simplified.
|
|
9
17
|
|
|
10
18
|
## Release boundary
|
|
11
19
|
|
|
12
|
-
Release publication is owned by `.github/workflows/release.yml`.
|
|
20
|
+
Release publication is owned by `.github/workflows/release.yml`. Align package, lockfile, tag and changelog at the release version, rebuild `dist/` from final sources, and verify the exact tag's successful workflow, published GitHub Release and matching npm package before reporting release completion. Installed-instance reload remains a separate operator action.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,16 @@
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.23.0: Off by Default and Mode Controls
|
|
8
|
+
|
|
9
|
+
- `Passive footprint clarified`: When selected, Passive always declares both memory tools, but contributes protocol and projected memory only with a validated view; a source-bound empty/nonempty byte probe documents the distinction without claiming provider token costs. Off removes State Flow's model-facing tools and context.
|
|
10
|
+
- `Barrier diagnostics`: With opt-in logging, blocked Active tool calls now record `barrier-block` with the exact reason, call identity and batch tool names, never sibling arguments or reasoning. Passive has no barrier; logging-off blocks remain unrecorded. Blocking and canonical state behavior are unchanged.
|
|
11
|
+
- `Focused onboarding`: README keeps installation, three-mode behavior and state model; status and Telegram rendering details live in usage, including a concrete revision-vector example.
|
|
12
|
+
- `Toolchain ranges`: Declare `typescript` `^7.0.2` and `@types/node` `^26.4.0` in package and lockfile metadata, matching installed/locked versions instead of floating `latest` across major refreshes.
|
|
13
|
+
- `Contract map and compaction`: Reduce `AGENTS.md` from 8,141 to about 1,300 words, with one-line owner links; relocate missing normative detail to architecture/usage and map all 56 former paragraphs to current contracts or tests. Keep storage semantics and `tests/invariants.test.ts` unchanged.
|
|
14
|
+
- `Off by default`: New sessions without a configured mode now adopt Off without initializing semantic storage; explicit global modes and legacy flag mappings still apply, and resumed sessions keep their selected mode. Passive and Active remain opt-in; stored memory is not erased.
|
|
15
|
+
- `Telegram mode radios`: Replace the lowercase mode row and redundant list with `Off | Passive | Active` radio labels (⚫️ inactive; 🟡/🟣/🟢 selected). Matching Mode and Inspect memory headings and blank-line-separated settings-style lists explain the workflow progression and scope buttons, including inspection in Off. Callback routing and four direct scope buttons remain unchanged.
|
|
16
|
+
|
|
7
17
|
## 0.22.0: Sparse State and Session Modes
|
|
8
18
|
|
|
9
19
|
- `Sparse semantic memory`: Checkpoints and retained patches may omit documented planes. Readers and writers select only known top-level fields while preserving nested data, causal identities and history boundaries. Current and historical views omit absent fields and empty responses; explicit reads of absent documented fields return `null`. Reads and activation do not normalize stored bytes; malformed data and unproven authority still fail closed.
|
package/README.md
CHANGED
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
|
|
5
5
|
**Incremental scoped context/memory compiler for Pi.**
|
|
6
6
|
|
|
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.
|
|
7
|
+
When enabled, 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
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
11
|
## How it works
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
In Active mode, 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.
|
|
14
14
|
|
|
15
15
|
```text
|
|
16
16
|
Current state + Request
|
|
@@ -57,9 +57,7 @@ Starting in an existing conversation retains its context for one complete bootst
|
|
|
57
57
|
- `/state-flow-off`: Remove both memory tools and all State Flow model context, without deleting memory.
|
|
58
58
|
- `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
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. Every materially changed owner advances its independent scope revision even in passive mode. Terminal status shows accent `state-flow` followed by dim `active` or `passive`; it is hidden in Off. `/state-flow-status` shows the `g15c8s31` vector and effective semantic JSON, with blank lines between top-level planes. Telegram's section button shows `State Flow: active`, `State Flow: passive` or `State Flow: off` without a vector. The submenu title repeats that value in monospace; its option descriptions use the settings-card `<code>-</code> <code>value</code>` grammar. Requested Global, CWD and Session snapshots show their own `#revision`, while Effective shows the vector. Inspection waits cancelably for a coherent shared view, with matching data and revisions, without publishing state or advancing a counter. Global `mode` defaults to `"passive"` and applies only to new sessions; resumed branches retain their own mode. Commands and Telegram never change that default or other sessions. See [configuration](docs/usage.md#configuration).
|
|
60
|
+
New sessions default to **Off**; select Passive for ordinary conversation with memory tools, or Active for state-driven episodes. Passive projects state only after a validated memory view is available. Off removes State Flow's model-facing tools and context without deleting memory. Mode changes affect only this session; the global default applies only to new sessions. See [mode semantics](docs/usage.md#active-passive-and-configured-off), [configuration](docs/usage.md#configuration) and [status and controls](docs/usage.md#status-and-controls).
|
|
63
61
|
|
|
64
62
|
### Active, passive, off
|
|
65
63
|
|
|
@@ -143,7 +141,7 @@ The default store is `~/.pi/agent/state-flow/`, independent of registered source
|
|
|
143
141
|
|
|
144
142
|
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 never silently substitute newer private state during restoration. Explicit Start is a mode change, not historical restoration: it activates validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated. Malformed storage, unsafe fork copying and concurrent writes remain fenced. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
|
|
145
143
|
|
|
146
|
-
SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Selecting Passive or Off switches local policy/context immediately and awaits runtime-only persistence. Active waits for coherent capture/acceptance; another mode or selection can withdraw its wait.
|
|
144
|
+
SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Selecting Passive or Off switches local policy/context immediately and awaits runtime-only persistence. Active waits for coherent capture/acceptance; another mode or selection can withdraw its wait. Startup, recovery and exact restoration/fork also await their independently owned memory operation; mode changes never cancel required copying. A failed write preserves the selected inactive mode and fences publication until accepted activation.
|
|
147
145
|
|
|
148
146
|
The canonical storage-format boundary introduced in 0.17 still applies: current versions accept only the canonical store contract and provide 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.
|
|
149
147
|
|
package/dist/lib/config.js
CHANGED
|
@@ -12,8 +12,8 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
|
|
|
12
12
|
const path = join(directory, "config.json");
|
|
13
13
|
const defaults = {
|
|
14
14
|
directory,
|
|
15
|
-
mode: "
|
|
16
|
-
inactiveMode: "
|
|
15
|
+
mode: "off",
|
|
16
|
+
inactiveMode: "off",
|
|
17
17
|
logging: false,
|
|
18
18
|
showSuccessfulPatches: true,
|
|
19
19
|
historyLimit: DEFAULT_HISTORY_LIMIT,
|
|
@@ -47,11 +47,12 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
|
|
|
47
47
|
if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || value.historyLimit < 0 || value.historyLimit > MAX_HISTORY_LIMIT))
|
|
48
48
|
throw new Error(`State Flow historyLimit must be an integer from 0 to ${MAX_HISTORY_LIMIT}: ${path}`);
|
|
49
49
|
const legacyInactive = value.passiveBootstrap !== false || value.passiveTools !== false ? "passive" : "off";
|
|
50
|
-
const
|
|
50
|
+
const hasLegacyMode = Object.hasOwn(value, "autoStart") || Object.hasOwn(value, "passiveBootstrap") || Object.hasOwn(value, "passiveTools");
|
|
51
|
+
const mode = isStateFlowMode(value.mode) ? value.mode : value.autoStart === true ? "active" : hasLegacyMode ? legacyInactive : "off";
|
|
51
52
|
return {
|
|
52
53
|
directory,
|
|
53
54
|
mode,
|
|
54
|
-
inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : legacyInactive,
|
|
55
|
+
inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : hasLegacyMode ? legacyInactive : "off",
|
|
55
56
|
logging: value.logging === true,
|
|
56
57
|
showSuccessfulPatches: value.showSuccessfulPatches !== false,
|
|
57
58
|
historyLimit: typeof value.historyLimit === "number" ? value.historyLimit : DEFAULT_HISTORY_LIMIT,
|
package/dist/lib/extension.js
CHANGED
|
@@ -1290,16 +1290,14 @@ export default function stateFlowExtension(pi, options = {}) {
|
|
|
1290
1290
|
const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
|
|
1291
1291
|
if (patchCalls > 0) {
|
|
1292
1292
|
if (patchCalls !== 1) {
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
};
|
|
1293
|
+
const reason = "A State Flow barrier response must contain exactly one patch_state call";
|
|
1294
|
+
recordDiagnostic(reason, "barrier-block", ctx, { tool: event.toolName, toolCallId: event.toolCallId, batchToolNames: batch });
|
|
1295
|
+
return { block: true, reason };
|
|
1297
1296
|
}
|
|
1298
1297
|
if (event.toolName !== PATCH_STATE_TOOL_NAME) {
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
};
|
|
1298
|
+
const reason = "Blocked by the patch_state barrier; reconsider this action after State Flow rematerializes context";
|
|
1299
|
+
recordDiagnostic(reason, "barrier-block", ctx, { tool: event.toolName, toolCallId: event.toolCallId, batchToolNames: batch });
|
|
1300
|
+
return { block: true, reason };
|
|
1303
1301
|
}
|
|
1304
1302
|
}
|
|
1305
1303
|
skillReads.recordCall(event.toolCallId, event.toolName, event.input);
|
package/dist/lib/logging.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization";
|
|
1
|
+
export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block";
|
|
2
2
|
/** Minimal structural block; only ordinary text keeps its exact content. */
|
|
3
3
|
export interface StateFlowDiagnosticBlock {
|
|
4
4
|
type: string;
|
|
@@ -15,6 +15,8 @@ export interface StateFlowDiagnosticRecord {
|
|
|
15
15
|
input?: unknown;
|
|
16
16
|
tool?: string;
|
|
17
17
|
toolCallId?: string;
|
|
18
|
+
/** Names only, in native assistant-batch order; never sibling arguments. */
|
|
19
|
+
batchToolNames?: string[];
|
|
18
20
|
}
|
|
19
21
|
/** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
|
|
20
22
|
export declare function projectDiagnosticContent(content: unknown): StateFlowDiagnosticBlock[];
|
|
@@ -26,6 +28,7 @@ export interface DiagnosticExtras {
|
|
|
26
28
|
input?: unknown;
|
|
27
29
|
tool?: string;
|
|
28
30
|
toolCallId?: string;
|
|
31
|
+
batchToolNames?: readonly string[];
|
|
29
32
|
}
|
|
30
33
|
/** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
|
|
31
34
|
export declare class StateFlowDiagnosticWriter {
|
package/dist/lib/logging.js
CHANGED
|
@@ -77,6 +77,7 @@ export class StateFlowDiagnosticWriter {
|
|
|
77
77
|
...(extras.input === undefined ? {} : { input: extras.input }),
|
|
78
78
|
...(extras.tool === undefined ? {} : { tool: extras.tool }),
|
|
79
79
|
...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
|
|
80
|
+
...(extras.batchToolNames === undefined ? {} : { batchToolNames: [...extras.batchToolNames] }),
|
|
80
81
|
});
|
|
81
82
|
return true;
|
|
82
83
|
}
|
package/dist/lib/telegram.d.ts
CHANGED
|
@@ -112,7 +112,7 @@ export interface StateFlowTelegramAdapter {
|
|
|
112
112
|
/** Main-menu section label shows only the current session mode. */
|
|
113
113
|
export declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string;
|
|
114
114
|
export declare const STATE_FLOW_MODES: readonly ["off", "passive", "active"];
|
|
115
|
-
/**
|
|
115
|
+
/** One radio-style mode row followed directly by read-only scope actions. */
|
|
116
116
|
export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
|
|
117
117
|
export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
|
|
118
118
|
/** Default loader; injectable so tests and embedded hosts can control transport presence. */
|
package/dist/lib/telegram.js
CHANGED
|
@@ -24,13 +24,9 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url)
|
|
|
24
24
|
export function formatStateFlowSectionLabel(snapshot) {
|
|
25
25
|
return `🌀 State Flow: ${snapshot.mode}`;
|
|
26
26
|
}
|
|
27
|
-
/** Match pi-telegram's settings-card value descriptions. */
|
|
28
|
-
const STATE_FLOW_SECTION_HELP = [
|
|
29
|
-
"<code>-</code> <code>off</code>: no memory tools or state bootstrap.",
|
|
30
|
-
"<code>-</code> <code>passive</code> (default): memory tools and context with ordinary conversation.",
|
|
31
|
-
"<code>-</code> <code>active</code>: state-driven episodes.",
|
|
32
|
-
].join("\n");
|
|
33
27
|
export const STATE_FLOW_MODES = ["off", "passive", "active"];
|
|
28
|
+
const STATE_FLOW_MODE_LABELS = { off: "Off", passive: "Passive", active: "Active" };
|
|
29
|
+
const STATE_FLOW_SELECTED_MARKERS = { off: "🟡", passive: "🟣", active: "🟢" };
|
|
34
30
|
function isStateFlowModeAction(value) {
|
|
35
31
|
return STATE_FLOW_MODES.includes(value);
|
|
36
32
|
}
|
|
@@ -39,19 +35,28 @@ function modeReceiptNotice(mode, result) {
|
|
|
39
35
|
return undefined;
|
|
40
36
|
return result.message;
|
|
41
37
|
}
|
|
42
|
-
/**
|
|
38
|
+
/** One radio-style mode row followed directly by read-only scope actions. */
|
|
43
39
|
export function buildStateFlowSectionView(snapshot, callbackData) {
|
|
44
40
|
const modes = STATE_FLOW_MODES.map((mode) => ({
|
|
45
|
-
text: `${mode === snapshot.mode ?
|
|
41
|
+
text: `${mode === snapshot.mode ? STATE_FLOW_SELECTED_MARKERS[mode] : "⚫️"} ${STATE_FLOW_MODE_LABELS[mode]}`,
|
|
46
42
|
callback_data: callbackData(mode),
|
|
47
43
|
}));
|
|
48
44
|
return {
|
|
49
45
|
text: [
|
|
50
46
|
`<b>🌀 State Flow:</b> <code>${snapshot.mode}</code>`,
|
|
51
47
|
"",
|
|
52
|
-
"
|
|
48
|
+
"<b>Mode</b> — choose a workflow (switching modes never erases stored memory):",
|
|
53
49
|
"",
|
|
54
|
-
|
|
50
|
+
"<code>-</code> <code>off</code> (default): regular chat without State Flow memory tools or context.",
|
|
51
|
+
"<code>-</code> <code>passive</code>: regular chat with memory tools; available combined memory enters the agent's context.",
|
|
52
|
+
"<code>-</code> <code>active</code>: same memory access; each completed answer closes a cycle, and the next request starts from saved state, not the full chat.",
|
|
53
|
+
"",
|
|
54
|
+
"<b>Inspect memory</b> — view stored state even in Off:",
|
|
55
|
+
"",
|
|
56
|
+
"<code>-</code> <code>global</code>: memory shared across projects and sessions.",
|
|
57
|
+
"<code>-</code> <code>cwd</code>: memory shared by sessions in this directory.",
|
|
58
|
+
"<code>-</code> <code>session</code>: private memory for this session, kept on resume.",
|
|
59
|
+
"<code>-</code> <code>effective</code>: merged Global, CWD and Session state; the agent can use it when memory is enabled and available.",
|
|
55
60
|
].join("\n"),
|
|
56
61
|
parseMode: "html",
|
|
57
62
|
replyMarkup: { inline_keyboard: [
|
package/dist/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@llblab/pi-state-flow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.23.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
|
|
6
6
|
"keywords": [
|
|
@@ -76,7 +76,7 @@
|
|
|
76
76
|
"@earendil-works/pi-ai": "0.87.0",
|
|
77
77
|
"@earendil-works/pi-coding-agent": "0.87.0",
|
|
78
78
|
"@earendil-works/pi-tui": "0.87.0",
|
|
79
|
-
"@types/node": "
|
|
80
|
-
"typescript": "
|
|
79
|
+
"@types/node": "^26.4.0",
|
|
80
|
+
"typescript": "^7.0.2"
|
|
81
81
|
}
|
|
82
82
|
}
|
|
@@ -15,7 +15,7 @@ State Flow's on-demand operational reference. Resolve the usage question or iden
|
|
|
15
15
|
|
|
16
16
|
Passive tools access memory without starting an episode. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
|
|
17
17
|
|
|
18
|
-
Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to
|
|
18
|
+
Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode without operator authorization.
|
|
19
19
|
|
|
20
20
|
## Map
|
|
21
21
|
|