@llblab/pi-state-flow 0.17.3 → 0.18.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 +8 -8
- package/CHANGELOG.md +14 -0
- package/README.md +6 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/lib/durable.d.ts +1 -0
- package/dist/lib/durable.js +7 -3
- package/dist/lib/extension.js +80 -10
- package/dist/lib/git.d.ts +6 -0
- package/dist/lib/git.js +94 -1
- package/dist/lib/protocol.js +11 -14
- package/dist/lib/runtime.d.ts +2 -0
- package/dist/lib/runtime.js +11 -0
- package/dist/lib/skills.d.ts +19 -2
- package/dist/lib/skills.js +52 -11
- package/dist/lib/status.d.ts +4 -2
- package/dist/lib/status.js +6 -2
- package/dist/lib/telegram.d.ts +6 -1
- package/dist/lib/telegram.js +20 -7
- package/dist/lib/temporal.d.ts +5 -0
- package/dist/lib/temporal.js +27 -3
- package/dist/lib/transition.js +38 -17
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +1 -1
- package/dist/skills/state-flow-memory/SKILL.md +1 -1
- package/docs/architecture.md +13 -11
- package/docs/lazy-state.md +2 -2
- package/docs/temporal-acceptance.md +5 -3
- package/docs/usage.md +6 -6
- package/index.ts +2 -2
- package/lib/durable.ts +8 -3
- package/lib/extension.ts +85 -10
- package/lib/git.ts +83 -1
- package/lib/protocol.ts +11 -13
- package/lib/runtime.ts +11 -0
- package/lib/skills.ts +65 -11
- package/lib/status.ts +9 -4
- package/lib/telegram.ts +24 -7
- package/lib/temporal.ts +29 -3
- package/lib/transition.ts +37 -17
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +1 -1
- package/skills/state-flow-memory/SKILL.md +1 -1
package/docs/architecture.md
CHANGED
|
@@ -40,7 +40,7 @@ Every materialized scope has exactly this shape:
|
|
|
40
40
|
- `contract` retains durable requirements, decisions, interfaces and rejected approaches.
|
|
41
41
|
- `working` retains verified current facts, unresolved work and exact continuation.
|
|
42
42
|
- `artifacts` maps exact source paths to compiled routing metadata.
|
|
43
|
-
- `response` is the latest
|
|
43
|
+
- `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global and CWD retain the required key as an empty structural placeholder so canonical scopes keep one shape; the effective overlay receives `response` only from Session.
|
|
44
44
|
- `lazy` is a required object root for ordinary JSON detail, omitted from baseline model state and read explicitly.
|
|
45
45
|
|
|
46
46
|
Effective state recursively overlays:
|
|
@@ -67,9 +67,9 @@ The checkpoint is an older anchored materialization. The tail contains at most t
|
|
|
67
67
|
|
|
68
68
|
Persisted streams and lineage are validated against the format maximum before applying a newly configured lower limit. Restore/reload/fork accepts only boundaries inside the configured window, then folds excess scope tails during canonical origin acceptance. That representation-only folding preserves selected private state and current shared values/provenance; a fork never rewrites parent-private files. Zero keeps only current checkpoints, and a later increase does not reconstruct discarded records or lineage.
|
|
69
69
|
|
|
70
|
-
`effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary
|
|
70
|
+
`effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary; the history index remains a composed-lineage offset, not a scope revision. Separately, each materially changed owner advances its persisted semantic revision once. Global and CWD counters remain shared across their canonical writers, Session remains private, and Effective is identified by the current `G#/C#/S#` revision vector. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
|
|
71
71
|
|
|
72
|
-
A changed accepted response is runtime-owned semantic state and advances history. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
|
|
72
|
+
A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer becomes `""` and finalizes normally rather than producing a recovery error. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
|
|
73
73
|
|
|
74
74
|
## Pi lifecycle
|
|
75
75
|
|
|
@@ -79,7 +79,7 @@ Tool preflight follows Pi's public `getLeafEntry()` / `getEntry(parentId)` links
|
|
|
79
79
|
|
|
80
80
|
`read_state` reads one cached effective or scoped projection at current index zero or a retained causal index through the configured `historyLimit`. It never publishes or advances history.
|
|
81
81
|
|
|
82
|
-
Before answering, the model uses `patch_state` only when future-relevant durable state must change.
|
|
82
|
+
Before answering, the model uses `patch_state` only when future-relevant durable state must change. The exact accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`, including `""` when the accepted answer is empty; no terminal eligibility latch, finalization patch, repair inference, or fallback budget exists. If required ordinary-artifact compilation prevents reconciliation, State Flow reports the failure without generating another inference. Optional Skill acquisition never blocks unrelated reconciliation. State Flow does not parse `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
|
|
83
83
|
|
|
84
84
|
## Lifecycle planes
|
|
85
85
|
|
|
@@ -93,7 +93,7 @@ Stopping State Flow ends active episode semantics, restores the configured passi
|
|
|
93
93
|
|
|
94
94
|
A proven pre-runtime branch has no accepted runtime to persist: Stop appends State Flow's existing `{disabled:true}` checkpoint in Pi without creating canonical files. Its cached passive view remains readable under the configured policy, but is not runtime authority. Accepted canonical publication, including a later Start or passive patch, ends this pre-runtime condition; failed selected-boundary recovery never qualifies for it.
|
|
95
95
|
|
|
96
|
-
Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition;
|
|
96
|
+
Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition; the runtime adopts their already-advanced owner revisions without incrementing them, while semantic files and all provenance files remain unchanged. Cached reads may constrain wider tails left by another writer without rewriting them. Same-session file races and explicitly requested stale provenance writes still fail closed under CAS. The host refreshes its scope cache after adoption: Stop freezes the accepted view, and new-run registered-artifact maintenance runs against that view before inference.
|
|
97
97
|
|
|
98
98
|
The existing native passive-stop marker stores the stop timestamp and an optional `from` timestamp identifying the active run's first user message. Native user events are observed independently of State Flow enablement, so starting mid-tool and repeated Start/Stop retain the actual first-user timestamp. Native user-run preparation and session-start/tree events reset capture; semantic mode changes do not. No new marker field, stored format or projection-derived lifecycle authority is introduced. Transcript bodies remain in Pi's trace rather than being copied into another state store. A recorded active anchor uses the same conservative selector as active inference: if native compaction removed it, or matching is ambiguous/nonfinite, retain the available native summary and tool trajectory without guessing a post-stop boundary or rereading discarded raw entries. Idle and legacy markers without an active anchor still retain only post-stop conversation plus foreign custom context. The initial system prompt is composed at `before_agent_start`; Stop does not rewrite an already-issued request, while the next provider request receives the current owned protocol section as described below.
|
|
99
99
|
|
|
@@ -128,7 +128,7 @@ meta.json
|
|
|
128
128
|
|
|
129
129
|
CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
|
|
130
130
|
|
|
131
|
-
Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage,
|
|
131
|
+
Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns its independent semantic revision, checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, the internal branch step, session identity, and the full specification only while a run is unfinished. Predecessor combined session metadata is unsupported; session `meta.json`, `config.json`, and `runtime.json` must already satisfy their canonical ownership contracts. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. A pre-revision 0.17 scope initializes its counter from the still-retained semantic tail and persists that baseline on its next owned write; folded ancestry is not guessed. Revision-aware writes emit scope metadata version 2 while continuing to read version 1. The version fence makes an older writer refuse a scope after its first revision-aware write instead of silently dropping the counter; all cooperating instances should still upgrade together. Pi checkpoints retain only a semantic boundary plus lifecycle fields, or a proven ordinary-disabled marker. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
|
|
132
132
|
|
|
133
133
|
In-memory patching detaches one basis at its public boundary, then privately path-copies changed object/array containers while sharing untouched nodes only inside that owned draft. Incoming replacement values remain detached; staging no longer makes redundant cohort/per-scope pre-clones. Mutable staged responses and artifact registries stay isolated from accepted scopes, and commit/public temporal reads retain their detachment boundaries. This is not cross-version mutable sharing or a new disk generation format; see [copy-work evidence](performance.md#memory-only-owned-draft-cow).
|
|
134
134
|
|
|
@@ -144,7 +144,9 @@ After response reconciliation and Pi's retry/queue processing, `agent_before_set
|
|
|
144
144
|
|
|
145
145
|
Only exact backed-up owned paths are synchronized in the caller's index, preserving unrelated staged additions, modifications, deletions, index-only content, and worktree edits. HEAD-owned paths remain candidates when their deletion is already staged. Unchanged trees and unowned-only initial backups are skipped; failed index synchronization rolls back only the backup ref, never canonical files. Failure cannot suppress the answer or trigger another inference. Notification-only `agent_settled` does not perform backup writes.
|
|
146
146
|
|
|
147
|
-
|
|
147
|
+
After a successful backup attempt, State Flow resolves only the attached branch's explicitly configured remote and destination ref, snapshots the exact current commit, and starts one non-interactive, non-force push outside all backup and canonical locks. Settlement does not await network completion. Failure is diagnostic-only; no queue is persisted, and the next accepted settled turn attempts the latest current backup again. A repository without an explicitly configured branch remote remains local-only.
|
|
148
|
+
|
|
149
|
+
Durable push queues, publication workers, leases, retry generations, queue filesystem state, and publication-policy metadata remain absent. Git revision restore, immutable-revision fork APIs, and the legacy semantic Git backend have been removed from `TemporalRuntime`; all initialization, passive loading, model patches, runtime-only persistence, retained-boundary restoration, and retained-boundary forks use canonical files only.
|
|
148
150
|
|
|
149
151
|
Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoints are unsupported and remain untouched.
|
|
150
152
|
|
|
@@ -165,17 +167,17 @@ Runtime-owned compilation evidence is retained per scope in `meta.json`; current
|
|
|
165
167
|
|
|
166
168
|
The public `classifyArtifactCompilationNeed` owns acquisition/rehydration and ordinary-artifact Pi decisions. An observed fingerprint needs matching valid retained fingerprint evidence; missing/malformed fingerprints, malformed compiler evidence, or a changed compiler request compilation without removing semantics. Changed size or signed nanosecond mtime (including pre-epoch dates) preserves the value and adds a runtime-only model `hint`. Fingerprint-only decisions ignore unused legacy hashes; explicit current-hash observations and the separate Skill hash protocol remain checked. Rehydration read plans carry detached fingerprints and optional hashes, never invented identities.
|
|
167
169
|
|
|
168
|
-
Invalidation notices identify the selected `global`, `cwd`, or `session` owner. Guidance and missing-output errors direct compilation to that exact scope/path, without relocating the entry or creating a global copy. Successful exact reads require stable fingerprints before/after acquisition and at publication, then publish compiler output and provenance to that owner under scope causal-basis CAS. Generic maintenance computes no content hash. Effective Skill entries mask lower ordinary entries and
|
|
170
|
+
Invalidation notices identify the selected `global`, `cwd`, or `session` owner. Guidance and missing-output errors direct compilation to that exact scope/path, without relocating the entry or creating a global copy. Successful exact reads require stable fingerprints before/after acquisition and at publication, then publish compiler output and provenance to that owner under scope causal-basis CAS. Generic maintenance computes no content hash. Effective Skill entries mask lower ordinary entries and retain their separate hash protocol.
|
|
169
171
|
|
|
170
172
|
Compilation is routing, not a substitute for source text. Full source is read only for a concrete unresolved gap, exact source/edit operation, fingerprint invalidation, contradiction/failure, or explicit request. The rehydration planner supports new-bootstrap, resume-bootstrap and later-step phases without hidden directory traversal.
|
|
171
173
|
|
|
172
|
-
Skills
|
|
174
|
+
Skill acquisition applies only to exact registered Pi Skills. State Flow resolves identity and ownership through the public slash-command inventory rather than file-path conventions: Pi `user`, `project` and `temporary` source scopes map to State Flow `global`, `cwd` and `session`. A successful read with matching current source hash needs no new compilation. Otherwise the tool result names the exact optional target. Attempted durable output requires `kind: "skill"` and a non-empty compilation describing applicability, constraints and failure conditions; an omitted output leaves the read volatile and does not block unrelated patches or ordinary completion. Source bodies do not persist in state. Matching provenance proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
|
|
173
175
|
|
|
174
176
|
## Operational guidance and memory curation
|
|
175
177
|
|
|
176
178
|
The packaged Skills deliberately separate two responsibilities. `state-flow-guide` is the on-demand operational reference for concrete read, patch, inheritance, acquisition, completion, and recovery questions; it does not initiate memory audits or unsolicited cleanup. `state-flow-memory` performs one explicitly requested bounded curation over stale knowledge, commitments, continuation, ownership, and external handoffs; phase completion does not activate an audit.
|
|
177
179
|
|
|
178
|
-
Curation
|
|
180
|
+
Curation may persist reusable guidance from a registered Skill at its provenance-derived scope. Within one store, a proven scope move inspects both owners, resolves conflicts, and commits destination/source changes through one atomic multi-scope patch, followed by ownership/overlay verification. Existing Skill artifacts written under the former CWD-only policy are not silently promoted: a later registered read identifies the current owner, while explicit curation may move proven reusable content and remove the old owner atomically.
|
|
179
181
|
|
|
180
182
|
External transfers use the destination's native interface and receipts; accepted-copy verification precedes source deletion in a later State Flow patch. State Flow defines no promotion registry, status schema, record type, or dedicated promotion tool; destination uncertainty simply leaves the source intact.
|
|
181
183
|
|
|
@@ -232,7 +234,7 @@ Agent configuration is read once per extension load; session runtime configurati
|
|
|
232
234
|
|
|
233
235
|
## Observability
|
|
234
236
|
|
|
235
|
-
Status is a projection of the selected runtime and semantic view, not a second store. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter
|
|
237
|
+
Status is a projection of the selected runtime and semantic view, not a second store. Compact terminal and Telegram main-menu status render `G#/C#/S#` only while active; passive Telegram renders `State Flow: off`. Requested Global, CWD and Session Rich snapshots show their independent `#revision`, while Effective shows the vector. Global/CWD Rich views omit the empty structural response placeholder; Session and Effective expose the Session-owned response. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter calls the same Start/Stop owners, and its inspectors remain available in either mode. Inspection may refresh live Global/CWD streams in memory so foreign accepted revisions become visible, but never publishes or increments a revision. If model-facing passive access is disabled and no runtime is selected, inspection may lazily load existing canonical shared state under the same read-only rule. Registration is fail-open and disposal belongs to session shutdown. Local diagnostics stay outside semantic state and cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).
|
|
236
238
|
|
|
237
239
|
## Validation boundaries
|
|
238
240
|
|
package/docs/lazy-state.md
CHANGED
|
@@ -42,11 +42,11 @@ global | CWD | session
|
|
|
42
42
|
├── contract
|
|
43
43
|
├── working
|
|
44
44
|
├── artifacts
|
|
45
|
-
├── response (session-owned
|
|
45
|
+
├── response (session-owned; empty structural slot in Global/CWD)
|
|
46
46
|
└── lazy
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
`intents`, `contract`, `working`, `artifacts
|
|
49
|
+
`intents`, `contract`, `working`, and `artifacts` remain hot in every scope. Session-owned `response` is also hot; Global and CWD keep only its required empty structural slot, and Effective inherits the Session value. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
|
|
50
50
|
|
|
51
51
|
- It is canonical semantic JSON, validated and versioned with its owning scope.
|
|
52
52
|
- It is excluded from the ordinary baseline effective-state body.
|
|
@@ -17,12 +17,14 @@ This is a maintained property-to-test map for the current canonical-file contrac
|
|
|
17
17
|
11. **Barrier shifts current to offset 1:** `tests/integration.test.ts` — “real Pi patch_state barriers rematerialize every scope before the next inference” observes the predecessor immediately after a barrier.
|
|
18
18
|
12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects path offset eight without a transition” adds model-tool access to the predecessor.
|
|
19
19
|
13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
|
|
20
|
-
14. **Accepted response changes are transitions:** `tests/extension.test.ts`
|
|
21
|
-
15. **No-op mutation signals are rejected:**
|
|
20
|
+
14. **Accepted response changes are transitions:** `tests/extension.test.ts` verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference, and “an empty accepted answer finalizes the run and stores an empty response” proves `""` is accepted after an earlier barrier. `tests/transition.test.ts` proves the empty value is an ordinary Session-owned semantic change when it replaces prior text.
|
|
21
|
+
15. **No-op mutation signals are rejected:** “accepts only canonical materially changing atomic scope patches” rejects empty scope patches and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
|
|
22
22
|
16. **Configured hot-history bounds:** `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition. `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
|
|
23
23
|
17. **Selected history fails closed:** `tests/recovery.test.ts` proves every failure resolving a selected retained boundary refuses without falling through to older boundaries or disabled markers. `tests/extension.test.ts` covers all passive bootstrap/tool combinations; the native “real Pi expired selection cannot reset private state through passive Start, Stop, patch, or reload” witness preserves exact canonical bytes and Pi checkpoints while allowing shared reads. Fork identity/CWD repair witnesses retry the original source with passive access both enabled and disabled.
|
|
24
24
|
18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction and rejects an expired sibling after fresh-origin navigation” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
|
|
25
25
|
19. **Stop changes config, not semantic history:** `tests/runtime.test.ts` lifecycle-only witnesses use a separate process to advance global/CWD semantics or provenance, including wider foreign retention, then prove exact semantic/sidecar preservation, unchanged steps, idempotent Stop, and same-session/stale-evidence refusal. Native Stop/new-request witnesses verify the accepted shared view reaches handoff/inference without a lifecycle semantic write, while a shared write racing after inference still fails closed. Mid-tool Stop tests preserve ordinary/bootstrap trajectories through tree, reload, resume, and restart. The native “real Pi retains a native split-turn continuation through late tools” Stop/no-Stop controls actually remove the original user with native threshold compaction, then require summary, paired reads and foreign context in model input. The Stop case also checks frozen semantics/step, unchanged trace prefix, tree/reload/cold resume/bootstrap restart, no resurrection of discarded input, and persistent foreign context after the next active run. Pure passive-selector tests cover missing, colliding and nonfinite recorded active anchors without changing idle/legacy cutoffs. `tests/storage.test.ts` fences lifecycle-only writes to config/runtime files; `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries.
|
|
26
|
+
20. **Passive observability omits active status without hiding owner revisions:** `tests/status.test.ts` proves an accepted passive patch advances semantic history while compact terminal status stays absent. `tests/telegram.test.ts` drives the real extension port after Stop, requires the passive main-menu identity to render `State Flow: off`, verifies an owner Rich-state heading uses its independent `#revision` and Effective uses `G#/C#/S#`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage.
|
|
27
|
+
21. **Independent revisions survive folding and foreign writers:** `tests/temporal.test.ts` proves each materially changed scope advances once for sparse and multi-scope cohorts, response-only transitions advance only Session, no-ops advance none, selected retained history restores the matching revision, and folding never resets it. `tests/durable.test.ts` covers revision serialization plus the pre-revision 0.17 retained-tail baseline. `tests/runtime.test.ts` uses an independent file-backed writer to advance Global, then refreshes the first runtime without file mutation and proves `G1/C0/S1` becomes `G1/C0/S2` after one private Session patch.
|
|
26
28
|
|
|
27
29
|
## Additional preservation boundaries
|
|
28
30
|
|
|
@@ -47,7 +49,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
|
|
|
47
49
|
- `tests/context.test.ts` and `tests/extension.test.ts` prohibit process queries during ordinary context/history reads. `tests/transition.test.ts` rejects stale staging even when semantic values coincide across different causal boundaries.
|
|
48
50
|
- `tests/status.test.ts` distinguishes selected temporal history depth from retained per-scope tails and unavailable materialization from an empty state.
|
|
49
51
|
- `tests/artifact.test.ts` and extension/native integration witnesses prove exact registered-path inspection, `size + mtimeNs` evidence, non-destructive unavailable/symlink handling, owning-scope removal, runtime-only changed-source hints, and stable-read acceptance without directory discovery. The native newly-adopted-artifact witness proves run preparation refreshes live shared state before proven-missing maintenance and the first inference. Artifact/acquisition/rehydration tests and “real Pi ordinary artifact invalidations share the public fingerprint classifier” cover equal/changed/missing/malformed fingerprints, pre-epoch timestamps, compiler invalidation, detached read plans, legacy hash handling, and effective Skill masking while preserving Skill hashing.
|
|
50
|
-
- `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner.
|
|
52
|
+
- `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner. Registered-Skill unit and native witnesses use Pi's public command source metadata to map user/project/temporary Skills to global/CWD/session, ignore unregistered `SKILL.md` reads, skip matching hashes, permit unrelated patches while compilation remains optional, retain strict attempted-output validation, and publish source-hash provenance to the exact reported owner.
|
|
51
53
|
- `tests/transition.test.ts` rejects authored provenance fields and field deletions in every scope through both staging entrypoints, without requiring a preceding read; legacy semantic edits and whole-artifact deletion remain valid. The native “real Pi rejects no-read provenance forgery atomically and accepts a corrected model patch” witness proves whole-cohort rejection and recovery, while existing artifact/Skill tests preserve runtime-owned compilation evidence and legacy decoding.
|
|
52
54
|
- `tests/storage.test.ts` covers exact file-cohort references, file CAS/rollback, and shared writer exclusion. `tests/runtime.test.ts` and native Pi lifecycle tests cover retained-boundary restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. Canonical files supply current state and bounded hot history; arbitrary cold revision recovery is unsupported.
|
|
53
55
|
- `tests/runtime.test.ts` and native integration cover retained-boundary restoration and fork after lowering `historyLimit` to 0/1: current shared values/provenance and selected private state survive folding, parent-private fork files remain unchanged, out-of-window selections fail closed, and later increases do not reconstruct discarded history. `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. `tests/extension.test.ts` proves registered artifacts are reconciled only at enabled inference boundaries. The global default is manual; CWD materialization alone no longer grants automatic activation.
|
package/docs/usage.md
CHANGED
|
@@ -64,14 +64,14 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
|
|
|
64
64
|
|
|
65
65
|
`/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
|
|
66
66
|
|
|
67
|
-
- Selected CWD/session keys, step, temporal head, recovery failures, and available hot history.
|
|
67
|
+
- Selected CWD/session keys, internal step, independent scope revisions, temporal head, recovery failures, and available hot history.
|
|
68
68
|
- Per-scope retained patch tails and artifact counts, plus one JSON representation of effective global → CWD → session memory. Individual scope JSON is available through `read_state`, not duplicated in status.
|
|
69
69
|
- Already-known runtime hints or pending artifact invalidations; status does not discover or validate sources.
|
|
70
70
|
- Memory-bearing scopes. Promotion-shaped values receive no special interpretation.
|
|
71
71
|
|
|
72
72
|
Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
|
|
73
73
|
|
|
74
|
-
The terminal indicator is `state-flow
|
|
74
|
+
The terminal indicator is `state-flow G15/C8/S31` only in active mode. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the `G#/C#/S#` revision vector. When `pi-telegram` is available, its main-menu section shows that vector only while active and `State Flow: off` while passive. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. Telegram inspection may lazily load or refresh live shared state from other instances even when passive model tools are disabled, but it does not initialize, publish, or advance storage. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
|
|
75
75
|
|
|
76
76
|
## Storage and recovery
|
|
77
77
|
|
|
@@ -92,19 +92,19 @@ Exactly one surviving pair member is corruption and fails closed. Present malfor
|
|
|
92
92
|
|
|
93
93
|
After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to the unavailable session layer or permission to publish an empty replacement. Session reads, every `patch_state`, and Stop refuse without changing canonical files or appending substitute checkpoints. Status retains the restoration error even when shared reads work. Start retries the original selection; repair its missing or invalid evidence, select a still-retained boundary, or use a genuinely new Pi session instead of forcing a reset.
|
|
94
94
|
|
|
95
|
-
Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease. See the complete [filesystem recovery contract](filesystem-recovery.md).
|
|
95
|
+
Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease; failed replication is attempted again only after a later accepted turn. See the complete [filesystem recovery contract](filesystem-recovery.md).
|
|
96
96
|
|
|
97
97
|
### Canonical files and optional Git backup
|
|
98
98
|
|
|
99
99
|
Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
|
|
100
100
|
|
|
101
|
-
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available.
|
|
101
|
+
After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Commit or push failure is diagnostic-only, and the next accepted turn retries the latest backup without a durable queue. Git availability never changes semantic authority, step, or retained lineage.
|
|
102
102
|
|
|
103
103
|
### Moving a store and the 0.17 format boundary
|
|
104
104
|
|
|
105
105
|
An SDK `repositoryRoot` override or a different `PI_CODING_AGENT_DIR` selects a location; it does not relocate existing state or retained history. Copy the complete canonical store while all writers are quiescent, or use a genuinely new Pi session for an independent store. Copying only current checkpoints without their tails and metadata cannot preserve retained boundaries.
|
|
106
106
|
|
|
107
|
-
State Flow 0.17 accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
|
|
107
|
+
State Flow 0.17 accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract. A canonical 0.17 scope written before independent revisions remains readable: its initial counter uses only the retained semantic tail and is persisted in metadata version 2 on the next owned write, without inventing folded ancestry. Version 1 remains readable; older writers refuse version 2 through the existing provenance-version fence, so cooperating instances should upgrade together. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
|
|
108
108
|
|
|
109
109
|
### Conflicts and interrupted publication
|
|
110
110
|
|
|
@@ -118,6 +118,6 @@ An untouched shared scope may be adopted from newer proven live state at a fresh
|
|
|
118
118
|
|
|
119
119
|
The agent should use sufficient materialized knowledge before rereading files. Read for a concrete gap, exact-source/edit operation, evidenced invalidation, contradiction/failure, explicit request, or bounded maintenance—not simply because a new session began.
|
|
120
120
|
|
|
121
|
-
Artifact maintenance inspects only exact paths already registered in global, CWD, or session state, using `size + mtimeNs` without directory traversal or generic content hashing. Proven-missing paths are pruned from their exact owning scopes; unavailable, relative, directory, and symlink paths are preserved. Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation updates hidden provenance. Skill reads
|
|
121
|
+
Artifact maintenance inspects only exact paths already registered in global, CWD, or session state, using `size + mtimeNs` without directory traversal or generic content hashing. Proven-missing paths are pruned from their exact owning scopes; unavailable, relative, directory, and symlink paths are preserved. Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation updates hidden provenance. Only exact registered Pi Skill reads enter the separate hash protocol. Public Pi source provenance maps user Skills to global, project Skills to CWD and temporary Skills to session; matching compiled hashes require no update, and an uncompiled read remains volatile without blocking unrelated patches. Model patches cannot author or delete runtime provenance or hints.
|
|
122
122
|
|
|
123
123
|
The packaged `state-flow-guide` Skill answers concrete operational questions about reads, patches, inheritance, acquisition, completion, and recovery without initiating cleanup. The separate `state-flow-memory` Skill handles explicitly requested bounded curation and externally verified transfers. Feature/release/project boundaries may motivate recommending cleanup, not starting an audit. Ordinary handoffs reconcile touched state; neither Skill is a background maintenance loop. External transfers use the destination's native receipt and preserve the source whenever acceptance is uncertain. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).
|
package/index.ts
CHANGED
|
@@ -71,7 +71,7 @@ export {
|
|
|
71
71
|
temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
|
|
72
72
|
} from "./lib/durable.ts";
|
|
73
73
|
export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
|
|
74
|
-
export { backupCurrentStateFlowFiles } from "./lib/git.ts";
|
|
74
|
+
export { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./lib/git.ts";
|
|
75
75
|
export {
|
|
76
76
|
createAcceptedTransition,
|
|
77
77
|
DEFAULT_HISTORY_LIMIT,
|
|
@@ -139,5 +139,5 @@ export {
|
|
|
139
139
|
type StateFlowTelegramSnapshot,
|
|
140
140
|
type StateFlowTelegramView
|
|
141
141
|
} from "./lib/telegram.ts";
|
|
142
|
-
export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";
|
|
142
|
+
export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
|
|
143
143
|
export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";
|
package/lib/durable.ts
CHANGED
|
@@ -50,6 +50,7 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
|
|
|
50
50
|
}
|
|
51
51
|
|
|
52
52
|
export interface ScopeTemporalMetadata {
|
|
53
|
+
revision: number;
|
|
53
54
|
checkpoint: ScopeStream["checkpoint"]["through"];
|
|
54
55
|
patches: ScopeStream["patches"][number]["transition"][];
|
|
55
56
|
}
|
|
@@ -68,6 +69,7 @@ export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwd
|
|
|
68
69
|
checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
|
|
69
70
|
patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
|
|
70
71
|
temporal: {
|
|
72
|
+
revision: stream.revision,
|
|
71
73
|
checkpoint: structuredClone(stream.checkpoint.through),
|
|
72
74
|
patches: stream.patches.map((record) => structuredClone(record.transition)),
|
|
73
75
|
},
|
|
@@ -124,6 +126,9 @@ export function classifyScopeStream(
|
|
|
124
126
|
const boundaries = temporal.patches;
|
|
125
127
|
if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
|
|
126
128
|
const stream = {
|
|
129
|
+
// 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
|
|
130
|
+
// semantic tail; discarded ancestry cannot be reconstructed without inventing history.
|
|
131
|
+
revision: temporal.revision === undefined ? patches.length : temporal.revision,
|
|
127
132
|
checkpoint: { through: temporal.checkpoint, state: checkpoint },
|
|
128
133
|
patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
|
|
129
134
|
};
|
|
@@ -219,7 +224,7 @@ export function serializeScopeMetadata(
|
|
|
219
224
|
const sources = serializeScopeStream(stream, scope, cwdIdentity);
|
|
220
225
|
const value = {
|
|
221
226
|
...existing,
|
|
222
|
-
version:
|
|
227
|
+
version: 2,
|
|
223
228
|
...(registry === undefined ? {} : { artifacts: serializeArtifactProvenanceRegistry(registry) }),
|
|
224
229
|
temporal: sources.temporal,
|
|
225
230
|
...(scope === "cwd" ? { owner: { cwd: resolve(cwdIdentity!) } } : {}),
|
|
@@ -229,7 +234,7 @@ export function serializeScopeMetadata(
|
|
|
229
234
|
|
|
230
235
|
/** Compatibility serializer retained for metadata-only callers. */
|
|
231
236
|
export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
|
|
232
|
-
return `${canonicalJson({ version:
|
|
237
|
+
return `${canonicalJson({ version: 2, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
|
|
233
238
|
}
|
|
234
239
|
|
|
235
240
|
function parseMetadataDocument(source: string | undefined, label: string): Record<string, unknown> {
|
|
@@ -245,7 +250,7 @@ function parseMetadataDocument(source: string | undefined, label: string): Recor
|
|
|
245
250
|
export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
|
|
246
251
|
const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
|
|
247
252
|
if (Object.keys(value).length === 0) return {};
|
|
248
|
-
if (value.version !== 1) throw new Error(`Invalid State Flow provenance document: ${path}`);
|
|
253
|
+
if (value.version !== 1 && value.version !== 2) throw new Error(`Invalid State Flow provenance document: ${path}`);
|
|
249
254
|
if (!Object.hasOwn(value, "artifacts")) return {};
|
|
250
255
|
return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
|
|
251
256
|
}
|
package/lib/extension.ts
CHANGED
|
@@ -25,7 +25,7 @@ import {
|
|
|
25
25
|
type SessionAddress,
|
|
26
26
|
} from "./durable.ts";
|
|
27
27
|
import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
|
|
28
|
-
import { backupCurrentStateFlowFiles } from "./git.ts";
|
|
28
|
+
import { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./git.ts";
|
|
29
29
|
import { projectRecentTransitionsWithLimit } from "./history.ts";
|
|
30
30
|
import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
|
|
31
31
|
import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
|
|
@@ -35,11 +35,12 @@ import { recoverSnapshot } from "./recovery.ts";
|
|
|
35
35
|
import type { RehydrationPhase } from "./rehydration.ts";
|
|
36
36
|
import { SharedScopeRemovalConflictError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
|
|
37
37
|
import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
|
|
38
|
-
import { SkillReadTracker } from "./skills.ts";
|
|
38
|
+
import { hasCompiledSkillArtifact, hashSkillSource, registeredSkillResolver, SkillReadTracker, type SuccessfulSkillRead } from "./skills.ts";
|
|
39
39
|
import { emptySnapshot, migrationFailure, type Snapshot } from "./snapshot.ts";
|
|
40
40
|
import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type ScopedStates, type StateScope } from "./state.ts";
|
|
41
41
|
import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
|
|
42
|
-
import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
|
|
42
|
+
import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
|
|
43
|
+
import { temporalScopeRevisions, type ScopeRevisions } from "./temporal.ts";
|
|
43
44
|
import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, type StagedScopedTransition } from "./transition.ts";
|
|
44
45
|
|
|
45
46
|
export interface StateFlowExtensionOptions {
|
|
@@ -85,9 +86,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
85
86
|
let activeContext: ExtensionContext | undefined;
|
|
86
87
|
let rehydrationPhase: RehydrationPhase | undefined;
|
|
87
88
|
const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
|
|
88
|
-
const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) =>
|
|
89
|
+
const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
|
|
89
90
|
let backupPending = false;
|
|
90
|
-
const skillReads = new SkillReadTracker()
|
|
91
|
+
const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
|
|
92
|
+
? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
|
|
93
|
+
: undefined);
|
|
91
94
|
const artifactReads = new ArtifactReadTracker();
|
|
92
95
|
let artifactInvalidations: ArtifactInvalidationRequest[] = [];
|
|
93
96
|
let artifactHints: Record<string, string> = {};
|
|
@@ -98,6 +101,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
98
101
|
return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
|
|
99
102
|
}
|
|
100
103
|
|
|
104
|
+
function notifyActiveContext(message: string): void {
|
|
105
|
+
try {
|
|
106
|
+
activeContext?.ui.notify(message, "warning");
|
|
107
|
+
} catch {
|
|
108
|
+
// An asynchronous push attempt can outlive the Pi context that launched it.
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
|
|
101
112
|
function createRuntime(ctx: ExtensionContext): TemporalRuntime {
|
|
102
113
|
return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
|
|
103
114
|
}
|
|
@@ -132,8 +143,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
132
143
|
if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
|
|
133
144
|
}
|
|
134
145
|
|
|
146
|
+
function scopeRevisions(): ScopeRevisions {
|
|
147
|
+
return runtime?.view
|
|
148
|
+
? temporalScopeRevisions(runtime.view)
|
|
149
|
+
: { global: 0, cwd: 0, session: 0 };
|
|
150
|
+
}
|
|
151
|
+
|
|
135
152
|
function updateUi(ctx: ExtensionContext): void {
|
|
136
|
-
ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
|
|
153
|
+
ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
|
|
137
154
|
}
|
|
138
155
|
|
|
139
156
|
function clearRunTransient(): void {
|
|
@@ -200,6 +217,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
200
217
|
if (Object.keys(removals).length > 0) {
|
|
201
218
|
const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
|
|
202
219
|
commitStage(stage, ctx, false);
|
|
220
|
+
updateUi(ctx);
|
|
203
221
|
}
|
|
204
222
|
refreshArtifactHints();
|
|
205
223
|
}
|
|
@@ -213,6 +231,18 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
213
231
|
return snapshot.config.enabled || config.passiveTools;
|
|
214
232
|
}
|
|
215
233
|
|
|
234
|
+
function refreshTelegramStateView(scope: StateFlowTelegramScope): void {
|
|
235
|
+
if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
|
|
236
|
+
if (!runtime?.view) {
|
|
237
|
+
if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
|
|
238
|
+
runtime ??= createRuntime(activeContext);
|
|
239
|
+
runtime.loadPassive();
|
|
240
|
+
} else if (scope !== "session") {
|
|
241
|
+
runtime.refreshShared();
|
|
242
|
+
}
|
|
243
|
+
installScopeStates();
|
|
244
|
+
}
|
|
245
|
+
|
|
216
246
|
function syncStateFlowTools(): void {
|
|
217
247
|
const active = pi.getActiveTools();
|
|
218
248
|
const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
|
|
@@ -234,6 +264,27 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
234
264
|
if (publication) recordPublication(publication, ctx);
|
|
235
265
|
}
|
|
236
266
|
|
|
267
|
+
function skillReadIsCurrent(read: SuccessfulSkillRead): boolean {
|
|
268
|
+
return read.hash !== undefined && runtime?.view !== undefined && hasCompiledSkillArtifact(
|
|
269
|
+
scopeStates[read.scope].artifacts,
|
|
270
|
+
runtime.artifactProvenance(read.scope)[read.path],
|
|
271
|
+
read.path,
|
|
272
|
+
read.hash,
|
|
273
|
+
);
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
function dropCurrentSkillReads(): void {
|
|
277
|
+
for (const read of skillReads.successful.values()) {
|
|
278
|
+
if (skillReadIsCurrent(read)) skillReads.delete(read.path);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
function skillAcquisitionHint(read: SuccessfulSkillRead): string | undefined {
|
|
283
|
+
if (read.hash === undefined || skillReadIsCurrent(read)) return undefined;
|
|
284
|
+
const target = `${read.scope}.artifacts[${JSON.stringify(read.path)}]`;
|
|
285
|
+
return `State Flow acquisition: this registered Skill belongs at ${target}. If durable compiled guidance is useful, include a non-empty description, kind:"skill", and compilation object there. Unrelated semantic patches do not need to include it.`;
|
|
286
|
+
}
|
|
287
|
+
|
|
237
288
|
function commitStage(stage: StagedScopedTransition, ctx: ExtensionContext, finalizeRun: boolean): boolean {
|
|
238
289
|
const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
|
|
239
290
|
let committed: boolean;
|
|
@@ -253,7 +304,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
253
304
|
installScopeStates();
|
|
254
305
|
artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
|
|
255
306
|
artifactReads.setCandidates(artifactInvalidations);
|
|
256
|
-
|
|
307
|
+
dropCurrentSkillReads();
|
|
257
308
|
artifactReads.clear();
|
|
258
309
|
persist();
|
|
259
310
|
return true;
|
|
@@ -287,6 +338,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
287
338
|
head: structuredClone(view.lineage.at(-1)!),
|
|
288
339
|
historyDepth: view.lineage.length - 1,
|
|
289
340
|
tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
|
|
341
|
+
revisions: temporalScopeRevisions(view),
|
|
290
342
|
} }),
|
|
291
343
|
staleArtifacts,
|
|
292
344
|
...(durableStateError === undefined ? {} : { durableStateError }),
|
|
@@ -667,16 +719,18 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
667
719
|
snapshot: () => ({
|
|
668
720
|
enabled: snapshot.config.enabled,
|
|
669
721
|
step: snapshot.meta.step,
|
|
722
|
+
revisions: scopeRevisions(),
|
|
670
723
|
bootstrap: snapshot.meta.bootstrap === true,
|
|
671
724
|
startPending: telegramStartPending,
|
|
672
725
|
}),
|
|
673
726
|
state: (scope) => {
|
|
674
|
-
|
|
727
|
+
refreshTelegramStateView(scope);
|
|
675
728
|
const selected = scope === "effective"
|
|
676
729
|
? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
|
|
677
730
|
: scopeStates[scope];
|
|
678
731
|
return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
|
|
679
732
|
},
|
|
733
|
+
revisions: () => scopeRevisions(),
|
|
680
734
|
canStartNow: () => activeContext === undefined || activeContext.isIdle(),
|
|
681
735
|
start: () => {
|
|
682
736
|
if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
|
|
@@ -801,9 +855,20 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
801
855
|
pi.on("tool_execution_end", (event) => {
|
|
802
856
|
if (!snapshot.config.enabled) return;
|
|
803
857
|
skillReads.recordEnd(event.toolCallId, event.toolName, event.isError);
|
|
858
|
+
dropCurrentSkillReads();
|
|
804
859
|
artifactReads.recordEnd(event.toolCallId, event.toolName, event.isError);
|
|
805
860
|
});
|
|
806
861
|
|
|
862
|
+
pi.on("tool_result", (event) => {
|
|
863
|
+
if (!snapshot.config.enabled) return;
|
|
864
|
+
const read = skillReads.recordResult(event.toolName, event.input, event.isError);
|
|
865
|
+
if (!read) return;
|
|
866
|
+
dropCurrentSkillReads();
|
|
867
|
+
const hint = skillAcquisitionHint(read);
|
|
868
|
+
if (!hint) return;
|
|
869
|
+
return { content: [...event.content, { type: "text", text: `\n${hint}` }] };
|
|
870
|
+
});
|
|
871
|
+
|
|
807
872
|
pi.on("message_end", (event, ctx): any => {
|
|
808
873
|
// Observe actual user events even while disabled; Start/Stop cannot invent or erase them.
|
|
809
874
|
if (event.message.role === "user" && runAnchorTimestamp === undefined) runAnchorTimestamp = event.message.timestamp;
|
|
@@ -866,7 +931,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
866
931
|
if (!backupPending) return;
|
|
867
932
|
backupPending = false;
|
|
868
933
|
try {
|
|
869
|
-
if (existsSync(join(repositoryRoot, ".git")))
|
|
934
|
+
if (existsSync(join(repositoryRoot, ".git"))) {
|
|
935
|
+
backupCurrentStateFlowFiles(repositoryRoot);
|
|
936
|
+
const pushSessionId = sessionAddress(ctx).id;
|
|
937
|
+
const pushCwd = ctx.cwd;
|
|
938
|
+
void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
|
|
939
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
940
|
+
diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
|
|
941
|
+
notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
|
|
942
|
+
});
|
|
943
|
+
}
|
|
870
944
|
} catch (error) {
|
|
871
945
|
const message = error instanceof Error ? error.message : String(error);
|
|
872
946
|
recordDiagnostic(message, "publication-conflict", ctx);
|
|
@@ -907,10 +981,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
907
981
|
runAnchorTimestamp = undefined;
|
|
908
982
|
restoreActiveBranch(ctx);
|
|
909
983
|
});
|
|
910
|
-
pi.on("session_shutdown", (_event,
|
|
984
|
+
pi.on("session_shutdown", (_event, _ctx) => {
|
|
911
985
|
telegramStartPending = false;
|
|
912
986
|
compactionStopped = true;
|
|
913
987
|
completedRunAccepted = false;
|
|
988
|
+
activeContext = undefined;
|
|
914
989
|
telegram.dispose();
|
|
915
990
|
});
|
|
916
991
|
}
|
package/lib/git.ts
CHANGED
|
@@ -2,13 +2,19 @@
|
|
|
2
2
|
import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
3
3
|
import { tmpdir } from "node:os";
|
|
4
4
|
import { dirname, join, relative, resolve, sep } from "node:path";
|
|
5
|
-
import { spawnSync } from "node:child_process";
|
|
5
|
+
import { spawn, spawnSync } from "node:child_process";
|
|
6
6
|
import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.ts";
|
|
7
7
|
import { acquirePublicationLock, withStoragePublicationLock } from "./storage.ts";
|
|
8
8
|
|
|
9
9
|
const GIT_TIMEOUT_MS = 15_000;
|
|
10
10
|
const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
|
|
11
11
|
|
|
12
|
+
function redactGitDiagnostic(value: string): string {
|
|
13
|
+
return value
|
|
14
|
+
.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
|
|
15
|
+
.replace(/([?&](?:access_token|auth|password|token)=)[^&\s]+/gi, "$1***");
|
|
16
|
+
}
|
|
17
|
+
|
|
12
18
|
interface GitResult {
|
|
13
19
|
status: number;
|
|
14
20
|
stdout: string;
|
|
@@ -134,6 +140,22 @@ function currentBranchRef(repositoryRoot: string): string {
|
|
|
134
140
|
return result.stdout.trim();
|
|
135
141
|
}
|
|
136
142
|
|
|
143
|
+
function configuredPushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
|
|
144
|
+
const branchRef = currentBranchRef(repositoryRoot);
|
|
145
|
+
const branch = branchRef.slice("refs/heads/".length);
|
|
146
|
+
const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
|
|
147
|
+
if (configuredRemote.status > 1) throw new Error(configuredRemote.stderr || "Cannot inspect State Flow backup remote configuration");
|
|
148
|
+
if (configuredRemote.status !== 0 || configuredRemote.stdout.trim().length === 0) return undefined;
|
|
149
|
+
const remote = configuredRemote.stdout.trim();
|
|
150
|
+
if (remote === ".") throw new Error("State Flow backup replication requires a non-local Git remote");
|
|
151
|
+
const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
|
|
152
|
+
if (configuredMerge.status > 1) throw new Error(configuredMerge.stderr || "Cannot inspect State Flow backup branch configuration");
|
|
153
|
+
const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
|
|
154
|
+
? configuredMerge.stdout.trim()
|
|
155
|
+
: branchRef;
|
|
156
|
+
return { remote, ref };
|
|
157
|
+
}
|
|
158
|
+
|
|
137
159
|
function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string | undefined): string | undefined {
|
|
138
160
|
const branchRef = currentBranchRef(repositoryRoot);
|
|
139
161
|
if (currentHead(repositoryRoot) !== expectedHead) throw new Error("State Flow backup Git base changed concurrently");
|
|
@@ -183,3 +205,63 @@ function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string |
|
|
|
183
205
|
export function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined {
|
|
184
206
|
return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
|
|
185
207
|
}
|
|
208
|
+
|
|
209
|
+
/** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
|
|
210
|
+
export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
|
|
211
|
+
return new Promise((resolvePush, rejectPush) => {
|
|
212
|
+
let root: string;
|
|
213
|
+
let commit: string | undefined;
|
|
214
|
+
let destination: { remote: string; ref: string } | undefined;
|
|
215
|
+
try {
|
|
216
|
+
root = assertRepositoryRoot(repositoryRoot);
|
|
217
|
+
commit = currentHead(root);
|
|
218
|
+
destination = configuredPushDestination(root);
|
|
219
|
+
} catch (error) {
|
|
220
|
+
rejectPush(error);
|
|
221
|
+
return;
|
|
222
|
+
}
|
|
223
|
+
if (commit === undefined || destination === undefined) {
|
|
224
|
+
resolvePush(undefined);
|
|
225
|
+
return;
|
|
226
|
+
}
|
|
227
|
+
const child = spawn("git", ["-C", root, "push", "--porcelain", "--", destination.remote, `${commit}:${destination.ref}`], {
|
|
228
|
+
detached: process.platform !== "win32",
|
|
229
|
+
stdio: ["ignore", "ignore", "pipe"],
|
|
230
|
+
windowsHide: true,
|
|
231
|
+
env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
|
|
232
|
+
});
|
|
233
|
+
let stderr = "";
|
|
234
|
+
let failure: Error | undefined;
|
|
235
|
+
let settled = false;
|
|
236
|
+
function terminate(error: Error): void {
|
|
237
|
+
failure ??= error;
|
|
238
|
+
if (child.exitCode !== null || child.signalCode !== null) {
|
|
239
|
+
child.stderr?.destroy();
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
if (!child.pid) return;
|
|
243
|
+
try {
|
|
244
|
+
if (process.platform === "win32") child.kill("SIGKILL");
|
|
245
|
+
else process.kill(-child.pid, "SIGKILL");
|
|
246
|
+
} catch {
|
|
247
|
+
// Keep waiting for close: signalling failure is not proof that the process ended.
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
const timeout = setTimeout(() => terminate(new Error(`Git backup push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
|
|
251
|
+
function finish(error?: Error): void {
|
|
252
|
+
if (settled) return;
|
|
253
|
+
settled = true;
|
|
254
|
+
clearTimeout(timeout);
|
|
255
|
+
if (error) rejectPush(error);
|
|
256
|
+
else resolvePush({ commit: commit!, ...destination! });
|
|
257
|
+
}
|
|
258
|
+
child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
|
|
259
|
+
child.on("error", (error) => {
|
|
260
|
+
failure ??= error;
|
|
261
|
+
if (!child.pid) finish(error);
|
|
262
|
+
});
|
|
263
|
+
child.once("exit", () => { if (failure) child.stderr?.destroy(); });
|
|
264
|
+
child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
|
|
265
|
+
: new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
|
|
266
|
+
});
|
|
267
|
+
}
|