@llblab/pi-state-flow 0.18.0 → 0.19.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 +23 -17
- package/BACKLOG.md +5 -3
- package/CHANGELOG.md +17 -0
- package/README.md +19 -7
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -0
- package/dist/lib/artifact.d.ts +2 -2
- package/dist/lib/artifact.js +5 -5
- package/dist/lib/context.d.ts +3 -2
- package/dist/lib/context.js +7 -2
- package/dist/lib/continuation.d.ts +5 -5
- package/dist/lib/continuation.js +54 -40
- package/dist/lib/durable.js +20 -20
- package/dist/lib/extension.js +772 -331
- package/dist/lib/git.d.ts +6 -2
- package/dist/lib/git.js +43 -18
- package/dist/lib/logging.d.ts +3 -0
- package/dist/lib/logging.js +33 -7
- package/dist/lib/protocol.d.ts +4 -0
- package/dist/lib/protocol.js +65 -23
- package/dist/lib/recovery.d.ts +16 -5
- package/dist/lib/recovery.js +32 -15
- package/dist/lib/runtime.d.ts +28 -2
- package/dist/lib/runtime.js +276 -26
- package/dist/lib/session.d.ts +5 -0
- package/dist/lib/session.js +36 -2
- package/dist/lib/snapshot.d.ts +3 -0
- package/dist/lib/snapshot.js +3 -0
- package/dist/lib/status.d.ts +1 -0
- package/dist/lib/status.js +3 -1
- package/dist/lib/storage.d.ts +11 -0
- package/dist/lib/storage.js +150 -24
- package/dist/lib/telegram.d.ts +14 -1
- package/dist/lib/telegram.js +52 -18
- package/dist/lib/transition.js +8 -8
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +3 -1
- package/docs/architecture.md +53 -7
- package/docs/compatibility.md +84 -44
- package/docs/filesystem-recovery.md +12 -2
- package/docs/fork-contract.md +6 -4
- package/docs/performance.md +11 -3
- package/docs/temporal-acceptance.md +28 -8
- package/docs/usage.md +43 -16
- package/index.ts +3 -0
- package/lib/artifact.ts +5 -5
- package/lib/context.ts +8 -3
- package/lib/continuation.ts +57 -40
- package/lib/durable.ts +20 -20
- package/lib/extension.ts +734 -322
- package/lib/git.ts +40 -19
- package/lib/logging.ts +31 -6
- package/lib/protocol.ts +60 -24
- package/lib/recovery.ts +34 -21
- package/lib/runtime.ts +290 -25
- package/lib/session.ts +37 -2
- package/lib/snapshot.ts +3 -0
- package/lib/status.ts +4 -1
- package/lib/storage.ts +141 -22
- package/lib/telegram.ts +60 -19
- package/lib/transition.ts +8 -8
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +3 -1
package/dist/lib/continuation.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
import { closeSync, constants,
|
|
1
|
+
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
|
|
2
2
|
import { join, resolve } from "node:path";
|
|
3
|
-
import {
|
|
3
|
+
import { parseScopeStream, resolveSessionAddress, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
|
|
4
4
|
import { MAX_HISTORY_LIMIT } from "./history.js";
|
|
5
|
+
import { diagnosticText } from "./protocol.js";
|
|
5
6
|
import { parseSessionRuntime } from "./snapshot.js";
|
|
7
|
+
import { withStorageTransaction } from "./storage.js";
|
|
6
8
|
import { validateScopeLineage } from "./temporal.js";
|
|
7
9
|
/**
|
|
8
10
|
* Preserve host-owned explicit session intent and consult State Flow only for
|
|
@@ -48,7 +50,8 @@ export function recommendContinuationFromProvenance(identity, candidates) {
|
|
|
48
50
|
return { action: "new", reason: "ineligible" };
|
|
49
51
|
return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
|
|
50
52
|
}
|
|
51
|
-
export async function resolveContinuationStartup(context, intent, recommend) {
|
|
53
|
+
export async function resolveContinuationStartup(context, intent, recommend, signal) {
|
|
54
|
+
signal?.throwIfAborted();
|
|
52
55
|
switch (intent.kind) {
|
|
53
56
|
case "new":
|
|
54
57
|
return { action: "new", reason: "explicit-new" };
|
|
@@ -60,8 +63,11 @@ export async function resolveContinuationStartup(context, intent, recommend) {
|
|
|
60
63
|
return { action: "native", mode: "continue-recent" };
|
|
61
64
|
case "no-session":
|
|
62
65
|
return { action: "native", mode: "no-session" };
|
|
63
|
-
case "default":
|
|
64
|
-
|
|
66
|
+
case "default": {
|
|
67
|
+
const recommendation = await recommend(Object.freeze({ ...context }), signal);
|
|
68
|
+
signal?.throwIfAborted();
|
|
69
|
+
return recommendation;
|
|
70
|
+
}
|
|
65
71
|
}
|
|
66
72
|
}
|
|
67
73
|
const MAX_SESSION_HEADER_BYTES = 64 * 1024;
|
|
@@ -124,54 +130,62 @@ export function discoverNativeSessionHeaders(sessionDir) {
|
|
|
124
130
|
}
|
|
125
131
|
return { headers, invalid };
|
|
126
132
|
}
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
|
|
136
|
-
const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
|
|
137
|
-
const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
|
|
133
|
+
/** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
|
|
134
|
+
export async function inspectStateFlowContinuationProvenance(header, repositoryRoot, signal) {
|
|
135
|
+
signal?.throwIfAborted();
|
|
136
|
+
const selected = { ...header };
|
|
137
|
+
const root = resolve(repositoryRoot);
|
|
138
|
+
const sessionKey = resolveSessionAddress(selected.file, selected.id, selected.timestamp).key;
|
|
139
|
+
const paths = sessionRuntimePaths(selected.cwd, selected.id, root, sessionKey);
|
|
140
|
+
const absent = { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
|
|
138
141
|
try {
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
const
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
142
|
+
if (!lstatSync(root, { throwIfNoEntry: false }))
|
|
143
|
+
return absent;
|
|
144
|
+
const result = await withStorageTransaction(root, (tx) => {
|
|
145
|
+
const files = new Map(tx.capture(selected.cwd, selected.id, root, sessionKey).files.map((file) => [file.path, file.content]));
|
|
146
|
+
const privatePaths = temporalScopePaths(selected.cwd, selected.id, "session", root, sessionKey);
|
|
147
|
+
if ([paths.config, paths.runtime, privatePaths.meta, privatePaths.checkpoint, privatePaths.patches].every((path) => files.get(path) === undefined))
|
|
148
|
+
return absent;
|
|
149
|
+
const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
|
|
150
|
+
if (!runtime)
|
|
151
|
+
throw new Error("incomplete canonical session runtime");
|
|
152
|
+
if (!runtime.config.enabled)
|
|
153
|
+
return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
|
|
154
|
+
const streams = ["global", "cwd", "session"].map((scope) => {
|
|
155
|
+
const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
|
|
156
|
+
return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope, scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));
|
|
157
|
+
});
|
|
158
|
+
if (streams.some((stream) => stream === undefined))
|
|
159
|
+
throw new Error("incomplete canonical temporal cohort");
|
|
160
|
+
// Shared streams remain current and independently valid; only the private stream binds to this lineage.
|
|
161
|
+
validateScopeLineage(streams[2], "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
|
|
162
|
+
return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
|
|
163
|
+
}, signal);
|
|
164
|
+
signal?.throwIfAborted();
|
|
165
|
+
return result;
|
|
158
166
|
}
|
|
159
167
|
catch (error) {
|
|
160
|
-
|
|
168
|
+
signal?.throwIfAborted();
|
|
169
|
+
return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${diagnosticText(error)}` };
|
|
161
170
|
}
|
|
162
171
|
}
|
|
163
|
-
export function buildContinuationCandidates(headers, inspect) {
|
|
172
|
+
export async function buildContinuationCandidates(headers, inspect, signal) {
|
|
173
|
+
signal?.throwIfAborted();
|
|
174
|
+
const selected = headers.map((header) => Object.freeze({ ...header }));
|
|
164
175
|
const candidates = [];
|
|
165
|
-
for (const header of
|
|
166
|
-
|
|
176
|
+
for (const header of selected) {
|
|
177
|
+
signal?.throwIfAborted();
|
|
178
|
+
const provenance = await inspect(header, signal);
|
|
179
|
+
signal?.throwIfAborted();
|
|
167
180
|
if (!provenance)
|
|
168
181
|
continue;
|
|
169
182
|
candidates.push({
|
|
183
|
+
...provenance,
|
|
184
|
+
stateFlow: { ...provenance.stateFlow },
|
|
170
185
|
sessionFile: header.file,
|
|
171
186
|
sessionId: header.id,
|
|
172
187
|
lastActivity: header.lastActivity,
|
|
173
188
|
cwd: header.cwd,
|
|
174
|
-
...provenance,
|
|
175
189
|
});
|
|
176
190
|
}
|
|
177
191
|
return candidates;
|
package/dist/lib/durable.js
CHANGED
|
@@ -22,7 +22,7 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
|
|
|
22
22
|
if (checkpoint.content !== undefined)
|
|
23
23
|
return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
|
|
24
24
|
if (patches.content !== undefined)
|
|
25
|
-
throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
|
|
25
|
+
throw new Error(`State Flow tail has no provable checkpoint: ${JSON.stringify(directory)}`);
|
|
26
26
|
return false;
|
|
27
27
|
}
|
|
28
28
|
/** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
|
|
@@ -124,7 +124,7 @@ export function sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey =
|
|
|
124
124
|
export function loadScopeStream(cwd, sessionId, scope, repositoryRoot, sessionKey = sessionId) {
|
|
125
125
|
const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
|
|
126
126
|
if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
|
|
127
|
-
throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
|
|
127
|
+
throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
|
|
128
128
|
}
|
|
129
129
|
return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
|
|
130
130
|
}
|
|
@@ -147,7 +147,7 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
|
|
|
147
147
|
seen.add(scope);
|
|
148
148
|
const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
|
|
149
149
|
if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
|
|
150
|
-
throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
|
|
150
|
+
throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
|
|
151
151
|
}
|
|
152
152
|
const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
|
|
153
153
|
return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
|
|
@@ -190,14 +190,14 @@ function parseMetadataDocument(source, label) {
|
|
|
190
190
|
}
|
|
191
191
|
/** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
|
|
192
192
|
export function parseScopeProvenance(source, path) {
|
|
193
|
-
const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
|
|
193
|
+
const value = parseMetadataDocument(source, `State Flow provenance file: ${JSON.stringify(path)}`);
|
|
194
194
|
if (Object.keys(value).length === 0)
|
|
195
195
|
return {};
|
|
196
196
|
if (value.version !== 1 && value.version !== 2)
|
|
197
|
-
throw new Error(`Invalid State Flow provenance document: ${path}`);
|
|
197
|
+
throw new Error(`Invalid State Flow provenance document: ${JSON.stringify(path)}`);
|
|
198
198
|
if (!Object.hasOwn(value, "artifacts"))
|
|
199
199
|
return {};
|
|
200
|
-
return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
|
|
200
|
+
return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${JSON.stringify(path)}`);
|
|
201
201
|
}
|
|
202
202
|
/** Dedicated runtime storage, independent from Markdown source discovery. */
|
|
203
203
|
export function getDurableRepositoryRoot(agentDir = getAgentDir()) {
|
|
@@ -273,7 +273,7 @@ function missing(error) {
|
|
|
273
273
|
function assertWithinRepository(path, repositoryRoot) {
|
|
274
274
|
const child = relative(repositoryRoot, path);
|
|
275
275
|
if (child === "" || child === ".." || child.startsWith(`..${sep}`)) {
|
|
276
|
-
throw new Error(`Durable State Flow path escapes its repository: ${path}`);
|
|
276
|
+
throw new Error(`Durable State Flow path escapes its repository: ${JSON.stringify(path)}`);
|
|
277
277
|
}
|
|
278
278
|
}
|
|
279
279
|
/** Reject symlinked directory components instead of following them during reads or writes. */
|
|
@@ -295,7 +295,7 @@ function assertDirectoryChain(repositoryRoot, directory, create) {
|
|
|
295
295
|
try {
|
|
296
296
|
const metadata = lstatSync(current);
|
|
297
297
|
if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
|
|
298
|
-
throw new Error(`Durable State Flow directory is not a regular directory: ${current}`);
|
|
298
|
+
throw new Error(`Durable State Flow directory is not a regular directory: ${JSON.stringify(current)}`);
|
|
299
299
|
}
|
|
300
300
|
}
|
|
301
301
|
catch (error) {
|
|
@@ -315,7 +315,7 @@ function readRegularBytes(path, repositoryRoot) {
|
|
|
315
315
|
try {
|
|
316
316
|
descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
317
317
|
if (!fstatSync(descriptor).isFile()) {
|
|
318
|
-
throw new Error(`Durable State Flow path is not a regular file: ${path}`);
|
|
318
|
+
throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
|
|
319
319
|
}
|
|
320
320
|
return readFileSync(descriptor);
|
|
321
321
|
}
|
|
@@ -325,7 +325,7 @@ function readRegularBytes(path, repositoryRoot) {
|
|
|
325
325
|
if (error instanceof Error
|
|
326
326
|
&& "code" in error
|
|
327
327
|
&& error.code === "ELOOP") {
|
|
328
|
-
throw new Error(`Durable State Flow path is not a regular file: ${path}`);
|
|
328
|
+
throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
|
|
329
329
|
}
|
|
330
330
|
throw error;
|
|
331
331
|
}
|
|
@@ -348,7 +348,7 @@ function fileBase(path, repositoryRoot) {
|
|
|
348
348
|
}
|
|
349
349
|
function assertCurrentBytes(path, root, expected) {
|
|
350
350
|
if (byteIdentity(readRegularBytes(path, root)) !== byteIdentity(expected)) {
|
|
351
|
-
throw new Error(`State Flow file conflict at ${path};
|
|
351
|
+
throw new Error(`State Flow file conflict at ${JSON.stringify(path)}; concurrent bytes preserved`);
|
|
352
352
|
}
|
|
353
353
|
}
|
|
354
354
|
/** Capture exact owned bytes for one compare-and-swap publication cohort. */
|
|
@@ -356,7 +356,7 @@ export function captureOwnedFileBases(paths, repositoryRoot) {
|
|
|
356
356
|
const root = resolve(repositoryRoot);
|
|
357
357
|
return paths.map((path) => {
|
|
358
358
|
if (!isStateFlowOwnedPath(path, root))
|
|
359
|
-
throw new Error(`Cannot capture a non-State Flow path: ${path}`);
|
|
359
|
+
throw new Error(`Cannot capture a non-State Flow path: ${JSON.stringify(path)}`);
|
|
360
360
|
return fileBase(resolve(path), root);
|
|
361
361
|
});
|
|
362
362
|
}
|
|
@@ -365,7 +365,7 @@ function prepareFile(path, repositoryRoot, content, expected) {
|
|
|
365
365
|
assertDirectoryChain(repositoryRoot, dirname(path), true);
|
|
366
366
|
const original = readRegularBytes(path, repositoryRoot);
|
|
367
367
|
if (expected !== undefined && byteIdentity(original) !== expected.identity) {
|
|
368
|
-
throw new Error(`State Flow file conflict during preparation: ${path}`);
|
|
368
|
+
throw new Error(`State Flow file conflict during preparation: ${JSON.stringify(path)}`);
|
|
369
369
|
}
|
|
370
370
|
const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
|
|
371
371
|
const next = content === undefined ? undefined : Buffer.from(content);
|
|
@@ -425,7 +425,7 @@ export function assertOwnedFileUpdates(updates, repositoryRoot) {
|
|
|
425
425
|
const root = resolve(repositoryRoot);
|
|
426
426
|
for (const update of updates) {
|
|
427
427
|
if (!isStateFlowOwnedPath(update.path, root))
|
|
428
|
-
throw new Error(`Cannot inspect a non-State Flow path: ${update.path}`);
|
|
428
|
+
throw new Error(`Cannot inspect a non-State Flow path: ${JSON.stringify(update.path)}`);
|
|
429
429
|
assertCurrentBytes(update.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
|
|
430
430
|
}
|
|
431
431
|
}
|
|
@@ -439,13 +439,13 @@ export function writeOwnedFileUpdates(updates, bases, repositoryRoot) {
|
|
|
439
439
|
for (const update of updates) {
|
|
440
440
|
const path = resolve(update.path);
|
|
441
441
|
if (!isStateFlowOwnedPath(path, root))
|
|
442
|
-
throw new Error(`Cannot update a non-State Flow path: ${path}`);
|
|
442
|
+
throw new Error(`Cannot update a non-State Flow path: ${JSON.stringify(path)}`);
|
|
443
443
|
if (seen.has(path))
|
|
444
|
-
throw new Error(`Duplicate State Flow file update: ${path}`);
|
|
444
|
+
throw new Error(`Duplicate State Flow file update: ${JSON.stringify(path)}`);
|
|
445
445
|
seen.add(path);
|
|
446
446
|
const base = byPath.get(path);
|
|
447
447
|
if (base === undefined)
|
|
448
|
-
throw new Error(`State Flow file update has no captured base: ${path}`);
|
|
448
|
+
throw new Error(`State Flow file update has no captured base: ${JSON.stringify(path)}`);
|
|
449
449
|
prepared.push(prepareFile(path, root, update.content, base));
|
|
450
450
|
}
|
|
451
451
|
}
|
|
@@ -464,13 +464,13 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
|
|
|
464
464
|
for (const base of bases) {
|
|
465
465
|
assertWithinRepository(base.path, root);
|
|
466
466
|
if (!isStateFlowOwnedPath(base.path, root)) {
|
|
467
|
-
throw new Error(`Cannot restore a non-State Flow path: ${base.path}`);
|
|
467
|
+
throw new Error(`Cannot restore a non-State Flow path: ${JSON.stringify(base.path)}`);
|
|
468
468
|
}
|
|
469
469
|
}
|
|
470
470
|
for (const base of bases) {
|
|
471
471
|
const update = expected.get(resolve(base.path));
|
|
472
472
|
if (update === undefined)
|
|
473
|
-
throw new Error(`Rollback has no published basis: ${base.path}`);
|
|
473
|
+
throw new Error(`Rollback has no published basis: ${JSON.stringify(base.path)}`);
|
|
474
474
|
assertCurrentBytes(base.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
|
|
475
475
|
if (base.identity === "missing") {
|
|
476
476
|
rmSync(base.path, { force: true });
|
|
@@ -478,7 +478,7 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
|
|
|
478
478
|
}
|
|
479
479
|
const original = base.bytes ?? (base.content === undefined ? undefined : Buffer.from(base.content));
|
|
480
480
|
if (original === undefined)
|
|
481
|
-
throw new Error(`Durable State Flow base content is missing: ${base.path}`);
|
|
481
|
+
throw new Error(`Durable State Flow base content is missing: ${JSON.stringify(base.path)}`);
|
|
482
482
|
assertDirectoryChain(root, dirname(base.path), true);
|
|
483
483
|
const temporary = join(dirname(base.path), `.${basename(base.path)}.${process.pid}.${randomUUID()}.restore`);
|
|
484
484
|
try {
|