@llblab/pi-state-flow 0.23.0 → 0.25.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 +7 -6
- package/BACKLOG.md +13 -5
- package/CHANGELOG.md +16 -1
- package/LICENSE +21 -0
- package/README.md +117 -35
- package/dist/lib/acquisition.d.ts +24 -1
- package/dist/lib/acquisition.js +80 -1
- package/dist/lib/compaction.d.ts +18 -1
- package/dist/lib/compaction.js +41 -1
- package/dist/lib/extension.js +346 -303
- package/dist/lib/git.d.ts +31 -2
- package/dist/lib/git.js +74 -5
- package/dist/lib/operation.d.ts +37 -0
- package/dist/lib/operation.js +59 -0
- package/dist/lib/ownership.d.ts +31 -0
- package/dist/lib/ownership.js +117 -0
- package/dist/lib/protocol.js +7 -7
- package/dist/lib/query.js +1 -1
- 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/status.d.ts +2 -0
- package/dist/lib/status.js +28 -0
- package/dist/lib/transition.js +6 -1
- package/dist/package.json +10 -9
- package/dist/skills/state-flow-guide/SKILL.md +14 -6
- package/dist/skills/state-flow-memory/SKILL.md +2 -2
- package/docs/README.md +19 -9
- package/docs/agent-contract-relocation.md +4 -4
- package/docs/architecture.md +646 -89
- package/docs/compatibility.md +116 -37
- package/docs/filesystem-recovery.md +118 -21
- package/docs/fork-contract.md +70 -8
- package/docs/lazy-state.md +88 -14
- package/docs/performance.md +83 -66
- package/docs/temporal-acceptance.md +391 -62
- package/docs/usage.md +317 -61
- package/lib/acquisition.ts +85 -1
- package/lib/compaction.ts +49 -2
- package/lib/extension.ts +342 -301
- package/lib/git.ts +77 -5
- package/lib/operation.ts +75 -0
- package/lib/ownership.ts +120 -0
- package/lib/protocol.ts +7 -8
- package/lib/query.ts +1 -1
- package/lib/runtime.ts +1 -1
- package/lib/session.ts +52 -1
- package/lib/snapshot.ts +8 -7
- package/lib/status.ts +29 -0
- package/lib/transition.ts +5 -1
- package/package.json +10 -9
- package/skills/state-flow-guide/SKILL.md +14 -6
- package/skills/state-flow-memory/SKILL.md +2 -2
package/AGENTS.md
CHANGED
|
@@ -4,6 +4,7 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
|
|
|
4
4
|
|
|
5
5
|
## Ownership and semantics
|
|
6
6
|
|
|
7
|
+
- Require matching Pi coding-agent, agent-core, AI and TUI packages at ≥1.0.0; pin the local verification stack to 1.0.0 and preserve the documented limits of fixture evidence.
|
|
7
8
|
- 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
9
|
- 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
10
|
- 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).
|
|
@@ -17,25 +18,25 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
|
|
|
17
18
|
|
|
18
19
|
- 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
20
|
- 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
|
-
-
|
|
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
|
|
21
|
+
- Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. When memory is selected, restore 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).
|
|
22
|
+
- 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 when the host provides no settlement operation signal rather than blocking Abort; never move it to `turn_end` or add a durable push queue. Off cancels owned captures/pushes and suppresses late reporting; normal agent-operation completion must not cancel an independently admitted push, and foreign callers' pushes retain ownership. See [optional Git backup](docs/architecture.md#optional-git-backup).
|
|
22
23
|
- 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
24
|
- 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
25
|
- 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
|
|
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).
|
|
26
|
+
- Make Start await coherent current-head acceptance; unaccepted Off-to-Active retains deferred history and cannot confer current-memory authority on a superseding Passive choice. Passive selects local policy before asynchronous runtime-only persistence; preserve its independently owned fork/restoration work. Off instead cancels owned memory waits, clears semantic caches and records only native mode/continuation/fork bookkeeping without canonical I/O. Preserve already accepted publications and carried write fences; failed Passive persistence uses a native fence, 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).
|
|
27
|
+
- 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. Use per-request owned markers, cancel stale/inactive owned hooks without default summary fallback, and prevent old completion from clearing a new plan. 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
28
|
- 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
|
|
|
29
30
|
## Model and operator boundaries
|
|
30
31
|
|
|
31
32
|
- 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
|
+
- 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. Sole exception: a structured `{"$ref"}` inside an `intents` entry owns its same-scope `working`/`lazy` object-key target, so deleting that intent key deletes the target after authored operations in the same atomic cohort unless a remaining same-scope intent references it, an ancestor or a descendant. That bounded read of one scope's `intents` plane never validates, rejects, warns, archives or crosses scopes; textual `$path` mentions and structured references outside `intents` stay non-owning. See [model tools](docs/architecture.md#model-tools), [intent ownership](docs/lazy-state.md#intent-ownership) and [lazy navigation](docs/usage.md#lazy-navigation-and-historical-reading).
|
|
33
34
|
- 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
35
|
- 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
36
|
- 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
37
|
- 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
38
|
- 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
|
+
- Keep terminal status observational and mode-derived; no source maintenance or invented empty view on inspection. Explicit Off inspection uses disposable current-store readers, validates private/Effective authority, and must not install cache or alter deferred branch/fork policy; automatic callbacks and rejected queued tools remain memory-inert even with logging enabled. 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
|
|
|
40
41
|
## Delivery discipline
|
|
41
42
|
|
package/BACKLOG.md
CHANGED
|
@@ -1,20 +1,28 @@
|
|
|
1
1
|
# Backlog
|
|
2
2
|
|
|
3
|
-
The **0.
|
|
3
|
+
The **0.25.0: Intent-Owned Memory** scope is implemented and locally validated; outcomes are recorded in [CHANGELOG.md](CHANGELOG.md), with package, lockfile and changelog aligned at 0.25.0. This backlog keeps publication, installed-client evidence and later decisions open. Current contracts live in [architecture](docs/architecture.md), [usage](docs/usage.md) and [intent ownership](docs/lazy-state.md#intent-ownership).
|
|
4
4
|
|
|
5
5
|
## Carried gates
|
|
6
6
|
|
|
7
|
-
- **
|
|
7
|
+
- **0.25.0 publication (approval-gated):** Commit the prepared tree and push the exact `v0.25.0` tag; then verify the tag's successful release workflow, published GitHub Release and matching npm package before reporting release completion.
|
|
8
|
+
- **Installed 0.25.0 smoke (operator-owned):** After separately authorized installation/reload, use a disposable store. In `session` and in `cwd`: open an intent with owned `working` and `lazy` entries plus one textual mention, close it, and confirm the owned entries are gone, the mentioned one remains, the receipt lists the deletions and `/state-flow-status` shares update. Then supersede an intent in one patch and confirm its targets survive.
|
|
9
|
+
- **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 a later candidate cannot certify the old release. After an operator-authorized reload, confirm:
|
|
8
10
|
- terminal autocomplete exposes Active/Passive/Off and status;
|
|
9
11
|
- Telegram shows the single `off | passive | active` row plus the four inspection buttons;
|
|
10
12
|
- current-session mode agrees across tools, context and status, and survives reload.
|
|
11
13
|
Do not edit real global defaults or unrelated sessions.
|
|
12
14
|
- **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.
|
|
15
|
+
- **Installed 0.24.0 smoke (approval/operator-owned):** Local lifecycle, cancellation, background-work and callback/inspection acceptance is complete; real-client behavior remains separate evidence. After separately authorized installation/reload of the exact 0.24.0 release, use a disposable store to check Off attachment and pending-work cancellation, no late memory warnings, current read-only inspections without private placeholders, preserved deferred Passive/Active/fork acquisition, and unchanged terminal/Telegram mode controls. Do not use the live store, treat its reload as evidence for older published releases, or change unrelated operator sessions.
|
|
13
16
|
|
|
14
|
-
## Deferred beyond 0.
|
|
17
|
+
## Deferred beyond 0.25.0 (decision inputs, not commitments)
|
|
18
|
+
|
|
19
|
+
- **Convention uptake:** After some real use, read the `/state-flow-status` ownership shares; if most `working`/`lazy` entries stay unowned, revisit the protocol wording, not the mechanism.
|
|
20
|
+
- **Behavioural evaluation:** Live-model comparison of Active against native compaction on one long cyclic task. Needs a policy decision first; current benchmarks are synthetic and make no model calls.
|
|
21
|
+
- **Lifecycle real-use measurement (gated):** The operator install runs with `logging: true` and has no recorded `publication-conflict`, `finalization` or `barrier-block` entries; cooperating-writer waits, Stop fences and fork/restore contention are not instrumented. Removing any awaited layer for rarity first needs a decision to add opt-in counters.
|
|
22
|
+
- **Lifecycle state as one tagged union:** The 0.25.0 lifecycle review left 17 closure bindings in `lib/extension.ts`, each a justified selection, run or host fact. Remaining candidates: the seven branch-selection facts (`snapshot`, `runtime`, `branchStartsWithoutRuntime`, `selectedHistoryExpired`, `modePersistenceError`, `forkInitialization`, `deferredBranch`) as one Off-deferred/attached union, and `passiveContinuation`/`bootstrapContinuation` as one continuation slot once their exclusivity is proven. Decide only with a behavioural reason; no further mechanical moves are pending.
|
|
23
|
+
- **Skill compilation fidelity:** Hashes detect source change, not a lossy first compilation. Measure before adding anything.
|
|
15
24
|
- **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.
|
|
17
25
|
|
|
18
26
|
## Release boundary
|
|
19
27
|
|
|
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.
|
|
28
|
+
Release publication is owned by `.github/workflows/release.yml`. Align package, lockfile, tag and changelog at the release version, rebuild `dist/` from final sources, run `npm run validate` and the context validator after context edits, 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
|
@@ -2,7 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
> Each release keeps at most 8 outcome records of at most 512 characters.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 0.25.0: Intent-Owned Memory
|
|
6
|
+
|
|
7
|
+
- `Intent-owned memory`: Deleting an intent key now deletes the same-scope `working`/`lazy` object keys its structured `{"$ref"}` values own, after authored operations in the same atomic cohort and revision, unless a remaining intent of that scope references the target, an ancestor or a descendant. Other targets and textual `$path` mentions are skipped silently; nothing is rejected, warned about or archived. Records store the cascade as explicit deletions and receipts report it.
|
|
8
|
+
- `Work from intents`: Protocol, `patch_state` description, both Skills, README and docs present `intents` as the queue of chosen actions and `working` as their temporary context. Structured refs inside intents own; textual `$path` mentions only use. Before closing an intent, save survivors to unowned paths, with abandonment reasons in `contract`. Unowned entries stay legal. The always-injected protocol did not grow; duplicated read-path and barrier wording now lives only in the tool definitions.
|
|
9
|
+
- `Ownership status`: `/state-flow-status` adds a per-scope `Scope memory:` block with UTF-8 sizes of present planes and the share of top-level `working`/`lazy` entries owned by an open intent. Operator-only; no notices, thresholds or model-facing effects.
|
|
10
|
+
- `Composition root step one`: Completed-history compaction request state moves into `StateFlowCompactionRequests` and settled-turn backup/push state into `SettledTurnBackup`, cutting `lib/extension.ts` mutable closure bindings from 34 to 26 and adding an invariant ceiling. No behaviour change.
|
|
11
|
+
- `Lifecycle review`: `lib/extension.ts` mutable closure bindings drop from 26 to 17 under the invariant ceiling. Artifact invalidations/hints move into `ArtifactAcquisitionState`, five lifecycle operations share one `OwnedOperationSlot`, renewable lifetimes and the session-identity guard have one owner each, and `noUnusedLocals`/`noUnusedParameters` guard dead code. No behaviour change.
|
|
12
|
+
- `Readable documentation`: Human-facing guides use short sections, explicit operation steps and resource-specific recovery rules. They describe current behavior rather than release chronology; performance documentation retains reproducible workloads and metric limits, not obsolete measurements. The acceptance map includes intent ownership and lifecycle owners, and a test checks relative documentation links and anchors.
|
|
13
|
+
|
|
14
|
+
## 0.24.0: Memory-Inert Off and Pi 1.0
|
|
15
|
+
|
|
16
|
+
- `Memory-inert Off`: Off startup, resume, reload, tree navigation and automatic callbacks perform no semantic-store I/O or recovery reporting, even with logging enabled. Switching to Off cancels owned memory waits and clears model tools/context without altering accepted memory; native mode, continuation, write-fence and pending-fork policy survive.
|
|
17
|
+
- `Safe reacquisition`: Passive restores the selected retained private boundary over live shared memory; Active validates current same-session memory. Pending Active can be cancelled or superseded by Passive without losing deferred history or inventing a write fence. Cold pending forks still require their exact proven source; expired history fails closed and bootstrap handoffs remain intact.
|
|
18
|
+
- `Read-only inspection`: Explicit Off inspections use disposable current-store readers, never install model cache or mutate stored bytes, mode, fences or deferred selection. Session/Effective require validated same-session authority rather than fabricated empty or foreign private state; revisions describe the inspected view.
|
|
19
|
+
- `Owned background work`: Off/shutdown cancel only owned backup captures and Git pushes, drain resources without late warnings and preserve accepted commits. Completed agent operations do not cancel admitted background pushes. Stale State Flow compaction requests cancel without model-summary fallback; old completion cannot clear a newer plan, and native operator/threshold compaction remains unchanged.
|
|
20
|
+
- `Pi 1.0 and packaging`: Requires matching Pi packages at 1.0.0 or newer and pins local verification to 1.0.0. Token estimation uses coding-agent's public export, fixing the removed agent-core API; the transitive brace-expansion patch is locked to 5.0.12. The npm package declares MIT licensing and includes LICENSE. Canonical storage formats and scope ownership remain unchanged.
|
|
6
21
|
|
|
7
22
|
## 0.23.0: Off by Default and Mode Controls
|
|
8
23
|
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 llblab
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -4,13 +4,18 @@
|
|
|
4
4
|
|
|
5
5
|
**Incremental scoped context/memory compiler for Pi.**
|
|
6
6
|
|
|
7
|
-
When enabled, State Flow maintains explicit state across requests and sessions.
|
|
7
|
+
When enabled, State Flow maintains explicit state across requests and sessions. Instead of carrying every completed exchange into the next request, the agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The idea comes from the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), combined with Pi's native conversation context:
|
|
10
|
+
|
|
11
|
+
- **State carries continuity between user runs.**
|
|
12
|
+
- **Pi's native context carries the working trajectory within a run.**
|
|
13
|
+
|
|
14
|
+
The conversation is not reset after each model response or tool call. Pi keeps ownership of execution, session navigation and the full inspectable trace.
|
|
10
15
|
|
|
11
16
|
## How it works
|
|
12
17
|
|
|
13
|
-
In Active mode,
|
|
18
|
+
In Active mode, each user run starts with the effective memory plus the 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 conversation history.
|
|
14
19
|
|
|
15
20
|
```text
|
|
16
21
|
Current state + Request
|
|
@@ -22,15 +27,27 @@ Patched state + Answer
|
|
|
22
27
|
Updated state
|
|
23
28
|
```
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
What the model sees during a run:
|
|
31
|
+
|
|
32
|
+
- The request, intermediate responses, tool results and steering stay in context.
|
|
33
|
+
- The initial memory head stays byte-stable. Accepted changes arrive in patch results, and changing runtime notices are appended at the tail without moving earlier messages.
|
|
34
|
+
- Projection IDs tell current updates apart from retained historical results.
|
|
35
|
+
- A state patch neither rewrites the head nor discards the working trajectory.
|
|
36
|
+
- Persistent context-bearing messages from other extensions are preserved.
|
|
37
|
+
|
|
38
|
+
Passive memory uses the same approach across ordinary user turns and rebases only at native or mode boundaries.
|
|
39
|
+
|
|
40
|
+
Why this helps:
|
|
26
41
|
|
|
27
|
-
|
|
42
|
+
- It reduces reliance on repeated model-generated summaries of a growing transcript.
|
|
43
|
+
- Keeping the current trajectory lets prompt caches be reused while the relevant prefix is unchanged.
|
|
44
|
+
- Avoiding summary calls and repeated prompt processing can improve responsiveness. The effect depends on the model, provider, workload and how often state changes; there is no fixed latency guarantee.
|
|
28
45
|
|
|
29
|
-
Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary,
|
|
46
|
+
Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary, keeping the complete latest accepted run. Neither mechanism deletes Pi's append-only session trace. See [lifecycle behavior](docs/usage.md#session-behavior) and [performance evidence](docs/performance.md).
|
|
30
47
|
|
|
31
48
|
## Installation and activation
|
|
32
49
|
|
|
33
|
-
Requires **Pi 0.
|
|
50
|
+
Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
|
|
34
51
|
|
|
35
52
|
From NPM:
|
|
36
53
|
|
|
@@ -50,22 +67,28 @@ Enable active State Flow on the current branch:
|
|
|
50
67
|
/state-flow-active
|
|
51
68
|
```
|
|
52
69
|
|
|
53
|
-
Starting in an existing conversation
|
|
70
|
+
Starting in an existing conversation keeps its context for one complete bootstrap run, so the agent can compile what matters.
|
|
71
|
+
|
|
72
|
+
Commands:
|
|
54
73
|
|
|
55
74
|
- `/state-flow-active`: Select the active, state-driven iteration workflow.
|
|
56
75
|
- `/state-flow-passive`: Select ordinary conversation with both memory tools and existing-memory projection.
|
|
57
76
|
- `/state-flow-off`: Remove both memory tools and all State Flow model context, without deleting memory.
|
|
58
77
|
- `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
|
|
59
78
|
|
|
60
|
-
New sessions default to **Off
|
|
79
|
+
New sessions default to **Off**. Choose Passive for ordinary conversation with memory tools, or Active for state-driven episodes. A mode change affects only the current 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).
|
|
61
80
|
|
|
62
81
|
### Active, passive, off
|
|
63
82
|
|
|
64
|
-
- `Active`: Memory tools are available
|
|
65
|
-
- `Passive`: Both memory tools and existing
|
|
66
|
-
- `Off`:
|
|
83
|
+
- `Active`: Memory tools are available, and the agent consolidates necessary final state changes before completing an iteration. Later iterations use accepted state and new input rather than completed prior reasoning.
|
|
84
|
+
- `Passive`: Both memory tools are available, and existing state is projected once a validated memory view is available. The agent patches on demand, and ordinary conversation context continues without State Flow's active iteration reset.
|
|
85
|
+
- `Off`: The model sees neither memory tool nor any State Flow context, including a frozen passive handoff.
|
|
86
|
+
- Startup, reload and tree attachment do not read or restore memory.
|
|
87
|
+
- Selecting Off cancels pending memory waits and records only native policy/bookmarks.
|
|
88
|
+
- Choosing Passive or Active later acquires memory.
|
|
89
|
+
- Stored memory and Pi's native trace stay intact.
|
|
67
90
|
|
|
68
|
-
Modes select agent behavior
|
|
91
|
+
Modes select agent behavior; they do not change disk persistence or fork copying. Final consolidation needs no empty ceremonial patch, and context projection does not delete native history. See [mode semantics and bootstrap terminology](docs/usage.md#active-passive-and-configured-off).
|
|
69
92
|
|
|
70
93
|
## State model
|
|
71
94
|
|
|
@@ -77,30 +100,51 @@ Memory has three ownership scopes:
|
|
|
77
100
|
- `cwd`: Knowledge shared by sessions in the same working directory.
|
|
78
101
|
- `session`: State belonging to the current session and its selected branch.
|
|
79
102
|
|
|
80
|
-
They compose recursively in **global → CWD → session** order
|
|
103
|
+
They compose recursively in **global → CWD → session** order:
|
|
104
|
+
|
|
105
|
+
- More-specific values override broader ones, while object fields merge.
|
|
106
|
+
- Removing a local value can reveal an inherited value again.
|
|
81
107
|
|
|
82
|
-
The agent receives the **effective view** of this composition, not three unrelated memory dumps. It can read that view or inspect
|
|
108
|
+
The agent receives the **effective view** of this composition, not three unrelated memory dumps. It can read that view, or inspect one scope when ownership matters. `effective` is a computed view, not a fourth storage scope. Scope precedence does not turn memory into system-level instructions.
|
|
83
109
|
|
|
84
110
|
### Semantic planes
|
|
85
111
|
|
|
86
112
|
Runtime views provide these documented planes:
|
|
87
113
|
|
|
88
|
-
- `intents`:
|
|
89
|
-
- `contract`: Requirements, decisions, constraints and interface commitments.
|
|
90
|
-
- `working`:
|
|
114
|
+
- `intents`: The queue of chosen actions. Work from intents: a structured `{"$ref"}` inside an intent owns a same-scope `working`/`lazy` key, and deleting the intent deletes what it owns unless another intent still references it. Textual `$path` mentions only use; unowned entries remain legal.
|
|
115
|
+
- `contract`: Requirements, decisions, rejected approaches, constraints and interface commitments.
|
|
116
|
+
- `working`: Temporary context of those actions: observations, results and uncertainties.
|
|
91
117
|
- `artifacts`: Source-addressed descriptions and compiled knowledge.
|
|
92
|
-
- `response`: The exact latest accepted answer, including an empty string
|
|
93
|
-
- `lazy`: Supporting memory available through explicit reads
|
|
118
|
+
- `response`: The exact latest accepted answer, including an empty string. The runtime captures it only in Session; Global/CWD receive no newly accepted answers, and stored scopes may omit it entirely. Effective uses the highest-priority nonempty value.
|
|
119
|
+
- `lazy`: Supporting memory available through explicit reads; its body is omitted from baseline model context.
|
|
120
|
+
|
|
121
|
+
Every plane is optional on disk:
|
|
122
|
+
|
|
123
|
+
- Stored checkpoints and patches may omit any documented plane, including `intents`, `lazy` or `response`.
|
|
124
|
+
- Current and historical views assemble only the known fields actually present in the selected scopes; absent fields are not filled in. Empty `response` counts as absent.
|
|
125
|
+
- Readers ignore unknown top-level fields, and writers emit only known fields. Nested data inside known planes is unrestricted.
|
|
126
|
+
- Reading or starting never rewrites data just to normalize it, and a missing field is not a storage-format error.
|
|
127
|
+
|
|
128
|
+
These planes organize ordinary JSON; there is no project-specific schema. The model updates every plane except `response`, which is runtime-owned.
|
|
94
129
|
|
|
95
|
-
|
|
130
|
+
Revisions:
|
|
96
131
|
|
|
97
|
-
|
|
132
|
+
- Global and CWD revisions are shared by their canonical stores; Session has its own revision.
|
|
133
|
+
- Effective has no single owner: its identity is the `g#c#s#` vector.
|
|
134
|
+
- One atomic patch advances each materially changed scope once.
|
|
98
135
|
|
|
99
|
-
|
|
136
|
+
Memory remains fallible: storing an observation does not make it current or correct.
|
|
137
|
+
|
|
138
|
+
Registered Pi Skills may be compiled into source-addressed artifacts when durable guidance is useful. Pi's resource provenance decides the owner: user Skills map to global, project Skills to CWD and temporary Skills to session. A matching source hash needs no update. An uncompiled read stays ordinary volatile context and does not block unrelated patches.
|
|
100
139
|
|
|
101
140
|
## Incremental updates and history
|
|
102
141
|
|
|
103
|
-
`patch_state` updates one or more named scopes atomically
|
|
142
|
+
`patch_state` updates one or more named scopes atomically:
|
|
143
|
+
|
|
144
|
+
- It waits cancelably for the store lock, then applies authored Global/CWD patches to the current canonical values, so other writers' untouched fields survive.
|
|
145
|
+
- Overlapping assignments follow successful acceptance order. Correct repeats succeed without new semantic revisions.
|
|
146
|
+
- Session remains private.
|
|
147
|
+
- Object patches merge recursively, and `null` deletes an object key instead of being stored.
|
|
104
148
|
|
|
105
149
|
```json
|
|
106
150
|
{
|
|
@@ -114,7 +158,7 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
|
|
|
114
158
|
}
|
|
115
159
|
```
|
|
116
160
|
|
|
117
|
-
During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or
|
|
161
|
+
During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or extra State Flow reasoning loop.
|
|
118
162
|
|
|
119
163
|
`read_state` provides targeted current and historical access:
|
|
120
164
|
|
|
@@ -127,29 +171,67 @@ During an active episode, a material patch is an inference barrier: sibling tool
|
|
|
127
171
|
- `cwd.patches[0]`: The latest retained CWD semantic patch.
|
|
128
172
|
- `effective.lazy.memory[0..3]`: A bounded slice of a stored collection.
|
|
129
173
|
|
|
130
|
-
|
|
174
|
+
How much history is kept:
|
|
175
|
+
|
|
176
|
+
- Historical materializations and scope patch histories use the configurable **`historyLimit`**, from **0 to 100**, default **7**.
|
|
177
|
+
- Offsets count accepted semantic transitions, not user messages or a separate counter per scope.
|
|
178
|
+
- Requested history must still exist in the active lineage; raising the limit cannot recreate discarded history.
|
|
179
|
+
- Older patches fold into the checkpoint without removing current values.
|
|
131
180
|
|
|
132
|
-
Array ranges, structural `keys` reads and path-intersected `patch` projections
|
|
181
|
+
Array ranges, structural `keys` reads and path-intersected `patch` projections let the agent explore memory without loading whole collections. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
|
|
133
182
|
|
|
134
183
|
## Persistence, backups and continuity
|
|
135
184
|
|
|
136
|
-
The default store is `~/.pi/agent/state-flow/`, independent of registered source files.
|
|
185
|
+
The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Each scope keeps its state, retained changes and metadata in canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files. Session configuration and runtime identity are stored separately.
|
|
186
|
+
|
|
187
|
+
**Persistence is optimistic across abrupt shutdown.**
|
|
188
|
+
|
|
189
|
+
- Short publication exclusion keeps independent shared fields from cooperating writers; on overlap, the last accepted write wins.
|
|
190
|
+
- Per-file atomic replacement does not guarantee power-loss survival or crash-atomic recovery.
|
|
191
|
+
- This is an [accepted limitation](docs/filesystem-recovery.md#power-loss-durability), not a release gate; no additional recovery journal or storage format is planned.
|
|
192
|
+
|
|
193
|
+
**Git backups are optional.** When the store is a configured Git repository:
|
|
194
|
+
|
|
195
|
+
- Accepted active turns may create versioned backups of State Flow-owned files.
|
|
196
|
+
- If the store is busy and Pi provides no cancellable settlement wait, the backup is explicitly deferred. A later accepted turn retries, without changing memory or blocking native Abort.
|
|
197
|
+
- If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there, asynchronously and without force.
|
|
198
|
+
- Within one Pi process, at most one push per repository runs at a time. Overlapping attempts are skipped, and a later accepted turn pushes the latest backup.
|
|
199
|
+
- Off cancels pending captures and its admitted push, without rolling back accepted state or backup commits; canceled work emits no late memory warnings.
|
|
200
|
+
- Shutdown cancels owned pushes and waits for that repository's active push to close or time out.
|
|
201
|
+
- Commit failures warn locally. Repeated push failures produce one concise warning until a push succeeds, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory.
|
|
202
|
+
- Backup needs a Git commit identity; accepting and persisting state does not.
|
|
203
|
+
- Git history can be inspected separately, but it is not the authority for `read_state` or for automatic restoration of expired semantic boundaries.
|
|
204
|
+
|
|
205
|
+
**Resume, tree navigation and forks:**
|
|
206
|
+
|
|
207
|
+
- Memory-enabled resume and tree navigation restore the selected retained session boundary over the current shared global/CWD memory. Off defers this acquisition.
|
|
208
|
+
- A new session gets its own session layer.
|
|
209
|
+
- Supported native forks copy the selected session state into a new owner without changing the parent's private data.
|
|
210
|
+
- Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration.
|
|
211
|
+
- Explicit Start is a mode change, not historical restoration. It activates the 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.
|
|
212
|
+
- Malformed storage, unsafe fork copying and concurrent writes remain fenced.
|
|
213
|
+
|
|
214
|
+
See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
|
|
137
215
|
|
|
138
|
-
**
|
|
216
|
+
**For SDK and launcher integrations:**
|
|
139
217
|
|
|
140
|
-
|
|
218
|
+
- [Advisory continuation APIs](docs/architecture.md#session-continuation) inspect provenance and build candidates asynchronously with host cancellation. They neither open native sessions nor install automatic resume.
|
|
219
|
+
- Run preparation and missing-artifact maintenance wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction).
|
|
141
220
|
|
|
142
|
-
|
|
221
|
+
How mode changes interact with storage:
|
|
143
222
|
|
|
144
|
-
|
|
223
|
+
- Selecting Passive switches local policy/context immediately and awaits runtime-only persistence. Passive keeps independently owned restoration/fork work. If its persistence fails, local policy stays and publication is fenced until an accepted activation.
|
|
224
|
+
- Off cancels owned memory waits and saves only native mode/continuation/fork bookkeeping, without validating or rewriting canonical storage. It also cancels restoration/fork work and defers later acquisition.
|
|
225
|
+
- Explicit Off inspection may read current stored values through a disposable validated reader. It does not activate memory, install cache or change the selected historical/fork boundary. Missing private authority stays unavailable.
|
|
226
|
+
- Active waits for a coherent capture and acceptance; another mode or selection can withdraw its wait.
|
|
145
227
|
|
|
146
|
-
|
|
228
|
+
State Flow accepts only the canonical store contract and provides no in-place format converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-supported-formats) before changing versions or moving a store.
|
|
147
229
|
|
|
148
230
|
## Operational boundaries
|
|
149
231
|
|
|
150
|
-
State Flow adds memory, not another agent controller. It does not
|
|
232
|
+
State Flow adds memory, not another agent controller. It does not add background reasoning, a scheduler, automatic reference hydration or rollback of external tool effects. State and the current trajectory are not size-capped; performance depends on how much useful information the agent retains.
|
|
151
233
|
|
|
152
|
-
The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile
|
|
234
|
+
The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile the memory they touch; dedicated cleanup is not an automatic audit after each task.
|
|
153
235
|
|
|
154
236
|
Treat state, diagnostic logs and backups as private data. Revalidate consequential observations before acting, and verify a transfer's destination before deleting its source. Removing a value from current state does not erase older histories or remote copies.
|
|
155
237
|
|
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity } from "./artifact.ts";
|
|
1
|
+
import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity, type ArtifactProvenanceRegistry } from "./artifact.ts";
|
|
2
|
+
import type { AtomicScopePatches, ScopedSemanticStates, ScopedStates, StateScope } from "./state.ts";
|
|
2
3
|
/** Why the caller is considering source-body acquisition. */
|
|
3
4
|
export type ArtifactAcquisitionIntent = "routine" | "new-session" | "relevant-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
|
|
4
5
|
export type ArtifactAcquisitionReason = ArtifactInvalidationReason | "materialized-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
|
|
@@ -37,3 +38,25 @@ export declare class ArtifactReadTracker {
|
|
|
37
38
|
* stay on materialized state; only a concrete source need permits rereading.
|
|
38
39
|
*/
|
|
39
40
|
export declare function decideArtifactAcquisition(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, options: ArtifactAcquisitionOptions): ArtifactAcquisitionDecision;
|
|
41
|
+
export declare const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
|
|
42
|
+
/**
|
|
43
|
+
* One selected branch's ordinary-artifact acquisition plan: runtime-observed
|
|
44
|
+
* invalidations, their model hints and the read tracker correlated to them.
|
|
45
|
+
* The tracker's candidates always equal the current invalidation plan.
|
|
46
|
+
*/
|
|
47
|
+
export declare class ArtifactAcquisitionState {
|
|
48
|
+
#private;
|
|
49
|
+
readonly reads: ArtifactReadTracker;
|
|
50
|
+
get invalidations(): readonly ArtifactInvalidationRequest[];
|
|
51
|
+
get hints(): Record<string, string>;
|
|
52
|
+
/** Drop the invalidation plan; hints remain until the next refresh. */
|
|
53
|
+
clearInvalidations(): void;
|
|
54
|
+
/** Forget plan and hints when no memory view is selected. */
|
|
55
|
+
reset(): void;
|
|
56
|
+
/** Re-observe exact registered sources for the selected scope artifacts. */
|
|
57
|
+
refresh(states: ScopedStates, provenance: (scope: StateScope) => ArtifactProvenanceRegistry): void;
|
|
58
|
+
/** Accepted compilations leave the plan; correlated read evidence is single-use. */
|
|
59
|
+
acceptAcquired(paths?: ReadonlySet<string>): void;
|
|
60
|
+
}
|
|
61
|
+
/** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
|
|
62
|
+
export declare function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches;
|
package/dist/lib/acquisition.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, } from "./artifact.js";
|
|
1
|
+
import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, ORDINARY_ARTIFACT_COMPILER, } from "./artifact.js";
|
|
2
2
|
import { isObject } from "./json.js";
|
|
3
3
|
function readPath(toolName, args) {
|
|
4
4
|
return toolName === "read" && isObject(args) && typeof args.path === "string"
|
|
@@ -89,3 +89,82 @@ export function decideArtifactAcquisition(source, metadata, compiler, options) {
|
|
|
89
89
|
return { kind: "read-source", reason: "maintenance" };
|
|
90
90
|
}
|
|
91
91
|
}
|
|
92
|
+
export const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
|
|
93
|
+
const SCOPES = ["global", "cwd", "session"];
|
|
94
|
+
/**
|
|
95
|
+
* One selected branch's ordinary-artifact acquisition plan: runtime-observed
|
|
96
|
+
* invalidations, their model hints and the read tracker correlated to them.
|
|
97
|
+
* The tracker's candidates always equal the current invalidation plan.
|
|
98
|
+
*/
|
|
99
|
+
export class ArtifactAcquisitionState {
|
|
100
|
+
reads = new ArtifactReadTracker();
|
|
101
|
+
#invalidations = [];
|
|
102
|
+
#hints = {};
|
|
103
|
+
get invalidations() { return this.#invalidations; }
|
|
104
|
+
get hints() { return this.#hints; }
|
|
105
|
+
/** Drop the invalidation plan; hints remain until the next refresh. */
|
|
106
|
+
clearInvalidations() { this.#setInvalidations([]); }
|
|
107
|
+
/** Forget plan and hints when no memory view is selected. */
|
|
108
|
+
reset() {
|
|
109
|
+
this.#hints = {};
|
|
110
|
+
this.#setInvalidations([]);
|
|
111
|
+
}
|
|
112
|
+
/** Re-observe exact registered sources for the selected scope artifacts. */
|
|
113
|
+
refresh(states, provenance) {
|
|
114
|
+
const paths = new Set();
|
|
115
|
+
for (const scope of SCOPES)
|
|
116
|
+
for (const path of Object.keys(states[scope].artifacts))
|
|
117
|
+
paths.add(path);
|
|
118
|
+
const observations = new Map(inspectRegisteredArtifactPaths(paths).map((observation) => [observation.path, observation]));
|
|
119
|
+
const hints = {};
|
|
120
|
+
const invalidations = new Map();
|
|
121
|
+
for (const scope of SCOPES) {
|
|
122
|
+
const registry = provenance(scope);
|
|
123
|
+
for (const [path, metadata] of Object.entries(states[scope].artifacts)) {
|
|
124
|
+
// A narrower owner replaces broader evidence for the same path.
|
|
125
|
+
delete hints[path];
|
|
126
|
+
invalidations.delete(path);
|
|
127
|
+
if (metadata.kind === "skill")
|
|
128
|
+
continue;
|
|
129
|
+
const observed = observations.get(path);
|
|
130
|
+
if (observed?.kind !== "present")
|
|
131
|
+
continue;
|
|
132
|
+
const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, registry[path]);
|
|
133
|
+
if (need.kind !== "requires-compilation")
|
|
134
|
+
continue;
|
|
135
|
+
if (need.reason === "source-changed")
|
|
136
|
+
hints[path] = SOURCE_CHANGED_HINT;
|
|
137
|
+
invalidations.set(path, { path, scope, reason: need.reason });
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
this.#hints = hints;
|
|
141
|
+
this.#setInvalidations([...invalidations.values()].sort((left, right) => left.path.localeCompare(right.path)));
|
|
142
|
+
}
|
|
143
|
+
/** Accepted compilations leave the plan; correlated read evidence is single-use. */
|
|
144
|
+
acceptAcquired(paths = new Set(this.reads.successful.keys())) {
|
|
145
|
+
this.#setInvalidations(this.#invalidations.filter(({ path }) => !paths.has(path)));
|
|
146
|
+
this.reads.clear();
|
|
147
|
+
}
|
|
148
|
+
#setInvalidations(invalidations) {
|
|
149
|
+
this.#invalidations = invalidations;
|
|
150
|
+
this.reads.setCandidates(invalidations);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
/** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
|
|
154
|
+
export function missingArtifactRemovals(states) {
|
|
155
|
+
const owners = new Map();
|
|
156
|
+
for (const scope of SCOPES)
|
|
157
|
+
for (const path of Object.keys(states[scope].artifacts ?? {})) {
|
|
158
|
+
owners.set(path, [...owners.get(path) ?? [], scope]);
|
|
159
|
+
}
|
|
160
|
+
const removals = {};
|
|
161
|
+
for (const observation of inspectRegisteredArtifactPaths(owners.keys())) {
|
|
162
|
+
if (observation.kind !== "missing")
|
|
163
|
+
continue;
|
|
164
|
+
for (const scope of owners.get(observation.path) ?? []) {
|
|
165
|
+
const artifacts = (removals[scope]?.artifacts ?? {});
|
|
166
|
+
removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return removals;
|
|
170
|
+
}
|
package/dist/lib/compaction.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type CompactionResult } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
export declare 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.";
|
|
3
3
|
/** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
|
|
4
4
|
export declare const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24000;
|
|
@@ -47,4 +47,21 @@ export declare function stateFlowCompactionResult(plan: StateFlowCompactionPlan,
|
|
|
47
47
|
}): CompactionResult<StateFlowCompactionDetails> | {
|
|
48
48
|
cancel: true;
|
|
49
49
|
} | undefined;
|
|
50
|
+
type CompactionEvent = Parameters<typeof stateFlowCompactionResult>[2];
|
|
51
|
+
/** Completed-history compaction request state owned by one extension instance. */
|
|
52
|
+
export declare class StateFlowCompactionRequests {
|
|
53
|
+
#private;
|
|
54
|
+
get inFlight(): boolean;
|
|
55
|
+
get stopped(): boolean;
|
|
56
|
+
/** Permanently refuse owned requests (shutdown). */
|
|
57
|
+
stop(): void;
|
|
58
|
+
/** Drop the run-local plan; a stale callback can no longer clear a newer one. */
|
|
59
|
+
clear(): void;
|
|
60
|
+
/** Install a plan and return its unique per-request marker. */
|
|
61
|
+
begin(plan: StateFlowCompactionPlan): string;
|
|
62
|
+
/** Native completion clears only its own request. */
|
|
63
|
+
finish(marker: string): void;
|
|
64
|
+
/** Answer session_before_compact: foreign requests pass, stale or unpermitted owned ones cancel. */
|
|
65
|
+
resolve(event: CompactionEvent, permitted: boolean): ReturnType<typeof stateFlowCompactionResult>;
|
|
66
|
+
}
|
|
50
67
|
export {};
|