@llblab/pi-state-flow 0.13.3 → 0.14.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 +9 -9
- package/BACKLOG.md +0 -13
- package/CHANGELOG.md +15 -0
- package/README.md +7 -6
- package/dist/lib/config.d.ts +5 -2
- package/dist/lib/config.js +17 -16
- package/dist/lib/context.d.ts +8 -0
- package/dist/lib/context.js +24 -0
- package/dist/lib/continuation.js +4 -3
- package/dist/lib/durable.d.ts +1 -0
- package/dist/lib/durable.js +8 -3
- package/dist/lib/episode.d.ts +2 -0
- package/dist/lib/episode.js +4 -0
- package/dist/lib/extension.d.ts +5 -0
- package/dist/lib/extension.js +93 -35
- package/dist/lib/git.js +20 -23
- package/dist/lib/history.js +8 -4
- package/dist/lib/json.js +29 -3
- package/dist/lib/migration.js +34 -18
- package/dist/lib/protocol.js +14 -16
- package/dist/lib/query.d.ts +27 -1
- package/dist/lib/query.js +182 -10
- package/dist/lib/runtime.d.ts +2 -0
- package/dist/lib/runtime.js +34 -5
- package/dist/lib/snapshot.d.ts +5 -5
- package/dist/lib/snapshot.js +20 -24
- package/dist/lib/state.d.ts +6 -3
- package/dist/lib/state.js +5 -3
- package/dist/lib/status.js +1 -1
- package/dist/lib/storage.d.ts +2 -0
- package/dist/lib/storage.js +55 -20
- package/dist/lib/telegram.d.ts +8 -6
- package/dist/lib/telegram.js +10 -3
- package/dist/lib/transition.js +7 -3
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-memory/SKILL.md +11 -3
- package/docs/README.md +1 -0
- package/docs/architecture.md +5 -3
- package/docs/filesystem-recovery.md +3 -2
- package/docs/lazy-state.md +504 -0
- package/docs/usage.md +11 -8
- package/lib/config.ts +18 -15
- package/lib/context.ts +24 -0
- package/lib/continuation.ts +4 -3
- package/lib/durable.ts +8 -4
- package/lib/episode.ts +5 -0
- package/lib/extension.ts +86 -34
- package/lib/git.ts +23 -22
- package/lib/history.ts +8 -4
- package/lib/json.ts +31 -3
- package/lib/migration.ts +33 -16
- package/lib/protocol.ts +14 -16
- package/lib/query.ts +173 -9
- package/lib/runtime.ts +32 -4
- package/lib/snapshot.ts +22 -25
- package/lib/state.ts +11 -6
- package/lib/status.ts +1 -1
- package/lib/storage.ts +46 -18
- package/lib/telegram.ts +19 -6
- package/lib/transition.ts +7 -3
- package/package.json +1 -1
- package/skills/state-flow-memory/SKILL.md +11 -3
package/lib/storage.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
|
|
3
3
|
import { spawnSync } from "node:child_process";
|
|
4
4
|
import { createHash } from "node:crypto";
|
|
5
|
-
import { closeSync, lstatSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
|
|
5
|
+
import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
6
6
|
import { dirname, relative, resolve } from "node:path";
|
|
7
7
|
import {
|
|
8
8
|
assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases,
|
|
@@ -44,17 +44,42 @@ export function initializeFileStore(root: string): void {
|
|
|
44
44
|
mkdirSync(resolve(root), { recursive: true });
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
+
const PUBLICATION_LOCK_WAIT_MS = 2_000;
|
|
48
|
+
const PUBLICATION_LOCK_POLL_MS = 25;
|
|
49
|
+
const publicationLockWait = new Int32Array(new SharedArrayBuffer(4));
|
|
50
|
+
|
|
51
|
+
function liveForeignLockOwner(path: string): boolean {
|
|
52
|
+
let owner: string;
|
|
53
|
+
try { owner = readFileSync(path, "utf8").trim(); }
|
|
54
|
+
catch { return true; }
|
|
55
|
+
if (owner.length === 0) return true;
|
|
56
|
+
if (!/^[1-9]\d*$/.test(owner)) return false;
|
|
57
|
+
const pid = Number(owner);
|
|
58
|
+
if (!Number.isSafeInteger(pid) || pid === process.pid) return false;
|
|
59
|
+
try { process.kill(pid, 0); return true; }
|
|
60
|
+
catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
|
|
64
|
+
export function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number {
|
|
65
|
+
const deadline = Date.now() + PUBLICATION_LOCK_WAIT_MS;
|
|
66
|
+
while (true) {
|
|
67
|
+
try { return openSync(path, "wx", 0o600); }
|
|
68
|
+
catch (error) {
|
|
69
|
+
if ((error as NodeJS.ErrnoException).code !== "EEXIST" || !liveForeignLockOwner(path) || Date.now() >= deadline) throw unavailable(error);
|
|
70
|
+
Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
47
75
|
/** Git writers also acquire this lock before their common-Git-directory lock. */
|
|
48
76
|
export function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T {
|
|
49
77
|
const root = resolve(repositoryRoot);
|
|
50
78
|
assertStorageDirectory(root);
|
|
51
79
|
const path = resolve(root, ".state-flow-publication.lock");
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
} catch (error) {
|
|
56
|
-
throw new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
|
|
57
|
-
}
|
|
80
|
+
const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(
|
|
81
|
+
`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause },
|
|
82
|
+
));
|
|
58
83
|
try {
|
|
59
84
|
writeFileSync(descriptor, `${process.pid}\n`);
|
|
60
85
|
return action(root);
|
|
@@ -91,9 +116,9 @@ export function planTemporalPublication(
|
|
|
91
116
|
changedScopes.push(scope);
|
|
92
117
|
}
|
|
93
118
|
const provenanceUpdates: OwnedFileUpdate[] = [];
|
|
94
|
-
//
|
|
119
|
+
// Every scope metadata file owns provenance and temporal boundaries beside semantic files.
|
|
95
120
|
if (!runtimeOnly) {
|
|
96
|
-
for (const scope of
|
|
121
|
+
for (const scope of SCOPES) {
|
|
97
122
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
98
123
|
const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta)!.content, paths.meta);
|
|
99
124
|
const currentFile = files.get(paths.meta)!;
|
|
@@ -104,18 +129,21 @@ export function planTemporalPublication(
|
|
|
104
129
|
}
|
|
105
130
|
}
|
|
106
131
|
const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
107
|
-
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.
|
|
132
|
+
const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config)!.content, files.get(runtimePaths.runtime)!.content, cwd, sessionId, files.get(runtimePaths.meta)!.content);
|
|
108
133
|
if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined) throw new Error("Temporal semantic publication requires its session runtime cohort");
|
|
109
134
|
const runtimeUpdates: OwnedFileUpdate[] = [];
|
|
110
135
|
if (runtime !== undefined) {
|
|
111
|
-
const sources = serializeSessionRuntime(runtime, cwd, sessionId
|
|
136
|
+
const sources = serializeSessionRuntime(runtime, cwd, sessionId);
|
|
112
137
|
if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
|
|
113
|
-
if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.
|
|
114
|
-
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.
|
|
138
|
+
if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.runtime)!.content !== sources.runtime) {
|
|
139
|
+
runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
|
|
140
|
+
}
|
|
141
|
+
if (files.get(runtimePaths.runtime)!.identity === "missing" && files.get(runtimePaths.meta)!.content !== undefined
|
|
142
|
+
&& previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
|
|
143
|
+
const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
|
|
144
|
+
const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
|
|
145
|
+
runtimeUpdates.push({ path: runtimePaths.meta, content });
|
|
115
146
|
}
|
|
116
|
-
} else if (!runtimeOnly && changedScopes.includes("session")) {
|
|
117
|
-
const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
|
|
118
|
-
if (files.get(runtimePaths.meta)!.content !== content) runtimeUpdates.push({ path: runtimePaths.meta, content });
|
|
119
147
|
}
|
|
120
148
|
const changedPaths = new Set(changedScopes.flatMap((scope) => {
|
|
121
149
|
const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
|
|
@@ -153,14 +181,14 @@ function decodeFileCohort(cwd: string, sessionId: string, root: string, base: Te
|
|
|
153
181
|
scopes[scope] = stream;
|
|
154
182
|
}
|
|
155
183
|
const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
|
|
156
|
-
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.
|
|
184
|
+
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
|
|
157
185
|
if (!runtime || runtime.meta.publication !== "files") throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
|
|
158
186
|
const view = { scopes, lineage: runtime.meta.lineage };
|
|
159
187
|
validateTemporalState(view);
|
|
160
188
|
const provenance: Record<StateScope, ArtifactProvenanceRegistry> = {
|
|
161
189
|
global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
|
|
162
190
|
cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
|
|
163
|
-
session:
|
|
191
|
+
session: parseScopeProvenance(files.get(paths.meta), paths.meta),
|
|
164
192
|
};
|
|
165
193
|
return { runtime, view, provenance };
|
|
166
194
|
}
|
package/lib/telegram.ts
CHANGED
|
@@ -27,12 +27,18 @@ export interface StateFlowTelegramState {
|
|
|
27
27
|
contract: Record<string, unknown>;
|
|
28
28
|
working: Record<string, unknown>;
|
|
29
29
|
response: string;
|
|
30
|
+
lazy?: unknown;
|
|
30
31
|
}
|
|
31
32
|
|
|
33
|
+
export type StateFlowTelegramRichText =
|
|
34
|
+
| string
|
|
35
|
+
| StateFlowTelegramRichText[]
|
|
36
|
+
| { type: "bold" | "code"; text: StateFlowTelegramRichText };
|
|
37
|
+
|
|
32
38
|
export type StateFlowTelegramRichBlock =
|
|
33
|
-
| { type: "heading"; text:
|
|
34
|
-
| { type: "pre"; text:
|
|
35
|
-
| { type: "details"; summary:
|
|
39
|
+
| { type: "heading"; text: StateFlowTelegramRichText; size: 3 }
|
|
40
|
+
| { type: "pre"; text: StateFlowTelegramRichText; language?: string }
|
|
41
|
+
| { type: "details"; summary: StateFlowTelegramRichText; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
|
|
36
42
|
|
|
37
43
|
export interface StateFlowTelegramRichMessage {
|
|
38
44
|
blocks: StateFlowTelegramRichBlock[];
|
|
@@ -168,6 +174,9 @@ function renderStateFlowTelegramField(value: unknown): string {
|
|
|
168
174
|
const length = Math.floor((low + high) / 2);
|
|
169
175
|
const candidate = JSON.stringify({
|
|
170
176
|
truncated: true,
|
|
177
|
+
...(value !== null && typeof value === "object" && !Array.isArray(value)
|
|
178
|
+
? { keys: Object.keys(value) }
|
|
179
|
+
: {}),
|
|
171
180
|
preview: json.slice(0, length),
|
|
172
181
|
omittedChars: json.length - length,
|
|
173
182
|
}, null, 2);
|
|
@@ -182,14 +191,18 @@ function renderStateFlowTelegramField(value: unknown): string {
|
|
|
182
191
|
}
|
|
183
192
|
|
|
184
193
|
export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
|
|
185
|
-
const fields = ["artifacts", "contract", "working", "response"] as const;
|
|
194
|
+
const fields = ["artifacts", "contract", "working", "response", "lazy"] as const;
|
|
186
195
|
return {
|
|
187
196
|
blocks: [
|
|
188
|
-
{
|
|
197
|
+
{
|
|
198
|
+
type: "heading",
|
|
199
|
+
text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
|
|
200
|
+
size: 3,
|
|
201
|
+
},
|
|
189
202
|
...fields.map((field) => ({
|
|
190
203
|
type: "details" as const,
|
|
191
204
|
summary: { type: "code" as const, text: field },
|
|
192
|
-
blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field]) }],
|
|
205
|
+
blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
|
|
193
206
|
})),
|
|
194
207
|
],
|
|
195
208
|
skip_entity_detection: true,
|
package/lib/transition.ts
CHANGED
|
@@ -35,7 +35,7 @@ export interface StagedScopedTransition {
|
|
|
35
35
|
}
|
|
36
36
|
|
|
37
37
|
const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
|
|
38
|
-
const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
|
|
38
|
+
const PATCH_KEYS = new Set(["artifacts", "contract", "working", "lazy"]);
|
|
39
39
|
|
|
40
40
|
function compileReadArtifacts(
|
|
41
41
|
nextState: StateDocument,
|
|
@@ -123,14 +123,17 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
|
|
|
123
123
|
validatePatch(patch);
|
|
124
124
|
for (const key of Object.keys(patch)) {
|
|
125
125
|
if (!PATCH_KEYS.has(key)) {
|
|
126
|
-
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and
|
|
126
|
+
throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, and lazy are model-owned`);
|
|
127
127
|
}
|
|
128
128
|
}
|
|
129
|
-
for (const key of
|
|
129
|
+
for (const key of ["artifacts", "contract", "working"] as const) {
|
|
130
130
|
if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
|
|
131
131
|
throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
|
+
if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
|
|
135
|
+
throw new Error("Scoped State Flow patch field lazy cannot be null");
|
|
136
|
+
}
|
|
134
137
|
if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts);
|
|
135
138
|
}
|
|
136
139
|
|
|
@@ -140,6 +143,7 @@ function completePatch(patch: ScopePatch, response: string): StatePatch {
|
|
|
140
143
|
contract: patch.contract ?? {},
|
|
141
144
|
working: patch.working ?? {},
|
|
142
145
|
response,
|
|
146
|
+
...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy!) } : {}),
|
|
143
147
|
};
|
|
144
148
|
}
|
|
145
149
|
|
package/package.json
CHANGED
|
@@ -46,6 +46,8 @@ Separate a binding requirement from the method currently proposed to satisfy it.
|
|
|
46
46
|
|
|
47
47
|
When it affects continuation, retain what was proposed, accepted, rejected, corrected, explained, or left unresolved, and what the next response or action must address. Preserve enough referents for pending follow-ups to make sense.
|
|
48
48
|
|
|
49
|
+
Treat every completed work slice as a possible restart boundary. Its checkpoint should let a fresh executor recover the achieved outcome, surviving evidence, active commitments, decision-relevant uncertainty, and exact continuation without replaying the prior reasoning trajectory. Optimize decomposition for resumability as well as functional completion; if the next safe action depends on transient context that will disappear, the slice is not yet at a sufficient boundary.
|
|
50
|
+
|
|
49
51
|
Keep consequences, not a transcript or a personality dossier. Do not invent shared history or claim subjective continuity. A fresh run should not unnecessarily reopen a settled exchange or treat an unanswered proposal as approved.
|
|
50
52
|
|
|
51
53
|
### Preserve learning at its demonstrated boundary
|
|
@@ -70,11 +72,17 @@ A locator supports later retrieval; it does not replace content needed for the n
|
|
|
70
72
|
|
|
71
73
|
Do not rerun the underlying project merely to curate its memory. Leave an exact unresolved check when verification falls outside the requested boundary.
|
|
72
74
|
|
|
73
|
-
###
|
|
75
|
+
### Preserve priority and keep Lazy shallow
|
|
76
|
+
|
|
77
|
+
Treat array order in Lazy as semantic priority: earlier entries are higher priority. Preserve that order deliberately; do not reorder entries for aesthetics, incidental grouping, or normalization.
|
|
78
|
+
|
|
79
|
+
Minimize Lazy nesting, especially for top-level collections. Keep a top-level collection as a direct array when its members are the domain values. Represent a standalone item directly, normally as a string; use an object only when that item genuinely owns structured or nested fields. Do not add `items`, `owner`, `source`, or similar wrapper objects merely to describe the collection, and do not introduce nested arrays unless the domain itself requires a matrix or grouped sequence.
|
|
80
|
+
|
|
81
|
+
### Compact without flattening meaning
|
|
74
82
|
|
|
75
83
|
Merge redundant fragments and remove obsolete scaffolding, repeated argumentation, and routine progress. Do not rewrite unchanged state merely to normalize wording.
|
|
76
84
|
|
|
77
|
-
Do not erase a meaningful correction, uncertainty, commitment, negative result, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
|
|
85
|
+
Do not erase a meaningful correction, uncertainty, commitment, negative result, priority order, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
|
|
78
86
|
|
|
79
87
|
### Reconcile phase boundaries
|
|
80
88
|
|
|
@@ -90,7 +98,7 @@ Effective state does not prove which scope owns a value. When ownership matters
|
|
|
90
98
|
|
|
91
99
|
Before writing, review the proposed changes once within the requested boundary:
|
|
92
100
|
|
|
93
|
-
- Would a fresh executor know what must still hold, what changed, what remains unresolved, and
|
|
101
|
+
- Would a fresh executor know what must still hold, what changed, what remains unresolved, and the exact next action without replaying the prior cognitive trajectory?
|
|
94
102
|
- Could an omission cause a known failed attempt, an unnecessary repeated explanation, or loss of an active commitment?
|
|
95
103
|
- Could a retained claim impose an unapproved method, overgeneralize a result, or hide a live alternative?
|
|
96
104
|
|