@llblab/pi-state-flow 0.18.1 → 0.19.1

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.
Files changed (65) hide show
  1. package/AGENTS.md +26 -19
  2. package/BACKLOG.md +3 -3
  3. package/CHANGELOG.md +16 -0
  4. package/README.md +18 -6
  5. package/dist/index.d.ts +2 -1
  6. package/dist/index.js +1 -0
  7. package/dist/lib/artifact.d.ts +2 -2
  8. package/dist/lib/artifact.js +5 -5
  9. package/dist/lib/context.d.ts +3 -2
  10. package/dist/lib/context.js +13 -4
  11. package/dist/lib/continuation.d.ts +5 -5
  12. package/dist/lib/continuation.js +54 -40
  13. package/dist/lib/durable.js +20 -20
  14. package/dist/lib/extension.js +755 -325
  15. package/dist/lib/git.d.ts +2 -2
  16. package/dist/lib/git.js +14 -17
  17. package/dist/lib/protocol.d.ts +5 -1
  18. package/dist/lib/protocol.js +67 -24
  19. package/dist/lib/query.js +1 -1
  20. package/dist/lib/recovery.d.ts +16 -5
  21. package/dist/lib/recovery.js +32 -15
  22. package/dist/lib/runtime.d.ts +28 -2
  23. package/dist/lib/runtime.js +276 -26
  24. package/dist/lib/session.d.ts +5 -0
  25. package/dist/lib/session.js +36 -2
  26. package/dist/lib/snapshot.d.ts +3 -0
  27. package/dist/lib/snapshot.js +3 -0
  28. package/dist/lib/status.d.ts +1 -0
  29. package/dist/lib/status.js +3 -1
  30. package/dist/lib/storage.d.ts +11 -0
  31. package/dist/lib/storage.js +150 -24
  32. package/dist/lib/telegram.d.ts +14 -1
  33. package/dist/lib/telegram.js +52 -18
  34. package/dist/lib/transition.js +8 -8
  35. package/dist/package.json +1 -1
  36. package/dist/skills/state-flow-guide/SKILL.md +6 -2
  37. package/dist/skills/state-flow-memory/SKILL.md +3 -1
  38. package/docs/architecture.md +55 -9
  39. package/docs/compatibility.md +84 -44
  40. package/docs/filesystem-recovery.md +12 -2
  41. package/docs/fork-contract.md +6 -4
  42. package/docs/lazy-state.md +6 -4
  43. package/docs/performance.md +2 -2
  44. package/docs/temporal-acceptance.md +30 -8
  45. package/docs/usage.md +51 -14
  46. package/index.ts +3 -0
  47. package/lib/artifact.ts +5 -5
  48. package/lib/context.ts +13 -5
  49. package/lib/continuation.ts +57 -40
  50. package/lib/durable.ts +20 -20
  51. package/lib/extension.ts +719 -316
  52. package/lib/git.ts +16 -18
  53. package/lib/protocol.ts +63 -25
  54. package/lib/query.ts +1 -1
  55. package/lib/recovery.ts +34 -21
  56. package/lib/runtime.ts +290 -25
  57. package/lib/session.ts +37 -2
  58. package/lib/snapshot.ts +3 -0
  59. package/lib/status.ts +4 -1
  60. package/lib/storage.ts +141 -22
  61. package/lib/telegram.ts +60 -19
  62. package/lib/transition.ts +8 -8
  63. package/package.json +1 -1
  64. package/skills/state-flow-guide/SKILL.md +6 -2
  65. package/skills/state-flow-memory/SKILL.md +3 -1
@@ -1,8 +1,10 @@
1
- import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
1
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
2
2
  import { join, resolve } from "node:path";
3
- import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.ts";
3
+ import { parseScopeStream, resolveSessionAddress, sessionRuntimePaths, temporalScopePaths } from "./durable.ts";
4
4
  import { MAX_HISTORY_LIMIT } from "./history.ts";
5
+ import { diagnosticText } from "./protocol.ts";
5
6
  import { parseSessionRuntime } from "./snapshot.ts";
7
+ import { withStorageTransaction } from "./storage.ts";
6
8
  import { validateScopeLineage } from "./temporal.ts";
7
9
 
8
10
  export type ContinuationTransport = "local" | "sdk" | "telegram" | string;
@@ -62,7 +64,7 @@ export interface ContinuationSessionCandidate extends ContinuationCandidateSumma
62
64
  }
63
65
 
64
66
  export type ContinuationRecommender = (
65
- context: Readonly<ContinuationHostContext>,
67
+ context: Readonly<ContinuationHostContext>, signal?: AbortSignal,
66
68
  ) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
67
69
 
68
70
  /**
@@ -115,7 +117,9 @@ export async function resolveContinuationStartup(
115
117
  context: ContinuationHostContext,
116
118
  intent: ContinuationHostIntent,
117
119
  recommend: ContinuationRecommender,
120
+ signal?: AbortSignal,
118
121
  ): Promise<ContinuationStartupDecision> {
122
+ signal?.throwIfAborted();
119
123
  switch (intent.kind) {
120
124
  case "new":
121
125
  return { action: "new", reason: "explicit-new" };
@@ -127,8 +131,11 @@ export async function resolveContinuationStartup(
127
131
  return { action: "native", mode: "continue-recent" };
128
132
  case "no-session":
129
133
  return { action: "native", mode: "no-session" };
130
- case "default":
131
- return recommend(Object.freeze({ ...context }));
134
+ case "default": {
135
+ const recommendation = await recommend(Object.freeze({ ...context }), signal);
136
+ signal?.throwIfAborted();
137
+ return recommendation;
138
+ }
132
139
  }
133
140
  }
134
141
 
@@ -207,55 +214,65 @@ export function discoverNativeSessionHeaders(sessionDir: string): { headers: Nat
207
214
  return { headers, invalid };
208
215
  }
209
216
 
210
- function readRegular(path: string): string | undefined {
211
- if (!existsSync(path)) return undefined;
212
- if (!lstatSync(path).isFile()) throw new Error("State Flow continuation provenance must be a regular file");
213
- return readFileSync(path, "utf8");
214
- }
215
-
216
- /** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
217
- export function inspectStateFlowContinuationProvenance(
218
- header: NativeSessionHeader,
217
+ /** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
218
+ export async function inspectStateFlowContinuationProvenance(
219
+ header: Readonly<NativeSessionHeader>,
219
220
  repositoryRoot: string,
220
- ): Pick<ContinuationCandidateProvenance, "stateFlow" | "reason"> {
221
- const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
222
- const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
221
+ signal?: AbortSignal,
222
+ ): Promise<Pick<ContinuationCandidateProvenance, "stateFlow" | "reason">> {
223
+ signal?.throwIfAborted();
224
+ const selected = { ...header };
225
+ const root = resolve(repositoryRoot);
226
+ const sessionKey = resolveSessionAddress(selected.file, selected.id, selected.timestamp).key;
227
+ const paths = sessionRuntimePaths(selected.cwd, selected.id, root, sessionKey);
228
+ const absent = { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
223
229
  try {
224
- const config = readRegular(paths.config);
225
- const runtimeSource = readRegular(paths.runtime);
226
- const meta = readRegular(paths.meta);
227
- if (config === undefined && runtimeSource === undefined && meta === undefined) {
228
- return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
229
- }
230
- const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id);
231
- if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
232
- if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
233
- const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
234
- const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
235
- const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
236
- if (!global || !cwd || !session) throw new Error("incomplete canonical temporal cohort");
237
- // Shared streams are current, independently validated by their codecs, not frozen to this session's history.
238
- validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
239
- return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
230
+ if (!lstatSync(root, { throwIfNoEntry: false })) return absent;
231
+ const result = await withStorageTransaction(root, (tx) => {
232
+ const files = new Map(tx.capture(selected.cwd, selected.id, root, sessionKey).files.map((file) => [file.path, file.content]));
233
+ const privatePaths = temporalScopePaths(selected.cwd, selected.id, "session", root, sessionKey);
234
+ if ([paths.config, paths.runtime, privatePaths.meta, privatePaths.checkpoint, privatePaths.patches].every((path) => files.get(path) === undefined)) return absent;
235
+ const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
236
+ if (!runtime) throw new Error("incomplete canonical session runtime");
237
+ if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
238
+ const streams = (["global", "cwd", "session"] as const).map((scope) => {
239
+ const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
240
+ return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope,
241
+ scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));
242
+ });
243
+ if (streams.some((stream) => stream === undefined)) throw new Error("incomplete canonical temporal cohort");
244
+ // Shared streams remain current and independently valid; only the private stream binds to this lineage.
245
+ validateScopeLineage(streams[2]!, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
246
+ return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
247
+ }, signal);
248
+ signal?.throwIfAborted();
249
+ return result;
240
250
  } catch (error) {
241
- return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
251
+ signal?.throwIfAborted();
252
+ return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${diagnosticText(error)}` };
242
253
  }
243
254
  }
244
255
 
245
- export function buildContinuationCandidates(
256
+ export async function buildContinuationCandidates(
246
257
  headers: readonly NativeSessionHeader[],
247
- inspect: (header: Readonly<NativeSessionHeader>) => ContinuationCandidateProvenance | undefined,
248
- ): ContinuationSessionCandidate[] {
258
+ inspect: (header: Readonly<NativeSessionHeader>, signal?: AbortSignal) => ContinuationCandidateProvenance | undefined | Promise<ContinuationCandidateProvenance | undefined>,
259
+ signal?: AbortSignal,
260
+ ): Promise<ContinuationSessionCandidate[]> {
261
+ signal?.throwIfAborted();
262
+ const selected = headers.map((header) => Object.freeze({ ...header }));
249
263
  const candidates: ContinuationSessionCandidate[] = [];
250
- for (const header of headers) {
251
- const provenance = inspect(Object.freeze({ ...header }));
264
+ for (const header of selected) {
265
+ signal?.throwIfAborted();
266
+ const provenance = await inspect(header, signal);
267
+ signal?.throwIfAborted();
252
268
  if (!provenance) continue;
253
269
  candidates.push({
270
+ ...provenance,
271
+ stateFlow: { ...provenance.stateFlow },
254
272
  sessionFile: header.file,
255
273
  sessionId: header.id,
256
274
  lastActivity: header.lastActivity,
257
275
  cwd: header.cwd,
258
- ...provenance,
259
276
  });
260
277
  }
261
278
  return candidates;
package/lib/durable.ts CHANGED
@@ -45,7 +45,7 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
45
45
  join(directory, CHECKPOINT_FILE), join(directory, PATCHES_FILE), join(directory, META_FILE),
46
46
  ], root);
47
47
  if (checkpoint!.content !== undefined) return parseScopeStream(checkpoint!.content, patches!.content, "cwd", cwd, meta!.content) !== undefined;
48
- if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
48
+ if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${JSON.stringify(directory)}`);
49
49
  return false;
50
50
  }
51
51
 
@@ -174,7 +174,7 @@ export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRo
174
174
  export function loadScopeStream(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey = sessionId): ScopeStream | undefined {
175
175
  const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
176
176
  if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
177
- throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
177
+ throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
178
178
  }
179
179
  return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
180
180
  }
@@ -205,7 +205,7 @@ export function temporalStateFileUpdates(
205
205
  seen.add(scope);
206
206
  const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
207
207
  if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
208
- throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
208
+ throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
209
209
  }
210
210
  const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
211
211
  return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
@@ -248,11 +248,11 @@ function parseMetadataDocument(source: string | undefined, label: string): Recor
248
248
 
249
249
  /** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
250
250
  export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
251
- const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
251
+ const value = parseMetadataDocument(source, `State Flow provenance file: ${JSON.stringify(path)}`);
252
252
  if (Object.keys(value).length === 0) return {};
253
- if (value.version !== 1 && value.version !== 2) 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: ${JSON.stringify(path)}`);
254
254
  if (!Object.hasOwn(value, "artifacts")) return {};
255
- return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
255
+ return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${JSON.stringify(path)}`);
256
256
  }
257
257
 
258
258
  export interface ScopePaths {
@@ -345,7 +345,7 @@ function missing(error: unknown): boolean {
345
345
  function assertWithinRepository(path: string, repositoryRoot: string): void {
346
346
  const child = relative(repositoryRoot, path);
347
347
  if (child === "" || child === ".." || child.startsWith(`..${sep}`)) {
348
- throw new Error(`Durable State Flow path escapes its repository: ${path}`);
348
+ throw new Error(`Durable State Flow path escapes its repository: ${JSON.stringify(path)}`);
349
349
  }
350
350
  }
351
351
 
@@ -367,7 +367,7 @@ function assertDirectoryChain(repositoryRoot: string, directory: string, create:
367
367
  try {
368
368
  const metadata = lstatSync(current);
369
369
  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
370
- throw new Error(`Durable State Flow directory is not a regular directory: ${current}`);
370
+ throw new Error(`Durable State Flow directory is not a regular directory: ${JSON.stringify(current)}`);
371
371
  }
372
372
  } catch (error) {
373
373
  if (!missing(error)) throw error;
@@ -384,7 +384,7 @@ function readRegularBytes(path: string, repositoryRoot: string): Buffer | undefi
384
384
  try {
385
385
  descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
386
386
  if (!fstatSync(descriptor).isFile()) {
387
- throw new Error(`Durable State Flow path is not a regular file: ${path}`);
387
+ throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
388
388
  }
389
389
  return readFileSync(descriptor);
390
390
  } catch (error) {
@@ -392,7 +392,7 @@ function readRegularBytes(path: string, repositoryRoot: string): Buffer | undefi
392
392
  if (error instanceof Error
393
393
  && "code" in error
394
394
  && (error as NodeJS.ErrnoException).code === "ELOOP") {
395
- throw new Error(`Durable State Flow path is not a regular file: ${path}`);
395
+ throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
396
396
  }
397
397
  throw error;
398
398
  } finally {
@@ -416,7 +416,7 @@ function fileBase(path: string, repositoryRoot: string): DurableFileBase {
416
416
 
417
417
  function assertCurrentBytes(path: string, root: string, expected: Uint8Array | undefined): void {
418
418
  if (byteIdentity(readRegularBytes(path, root)) !== byteIdentity(expected)) {
419
- throw new Error(`State Flow file conflict at ${path}; preserve concurrent bytes and reconcile before retrying`);
419
+ throw new Error(`State Flow file conflict at ${JSON.stringify(path)}; concurrent bytes preserved`);
420
420
  }
421
421
  }
422
422
 
@@ -424,7 +424,7 @@ function assertCurrentBytes(path: string, root: string, expected: Uint8Array | u
424
424
  export function captureOwnedFileBases(paths: readonly string[], repositoryRoot: string): DurableFileBase[] {
425
425
  const root = resolve(repositoryRoot);
426
426
  return paths.map((path) => {
427
- if (!isStateFlowOwnedPath(path, root)) throw new Error(`Cannot capture a non-State Flow path: ${path}`);
427
+ if (!isStateFlowOwnedPath(path, root)) throw new Error(`Cannot capture a non-State Flow path: ${JSON.stringify(path)}`);
428
428
  return fileBase(resolve(path), root);
429
429
  });
430
430
  }
@@ -442,7 +442,7 @@ function prepareFile(path: string, repositoryRoot: string, content: string | und
442
442
  assertDirectoryChain(repositoryRoot, dirname(path), true);
443
443
  const original = readRegularBytes(path, repositoryRoot);
444
444
  if (expected !== undefined && byteIdentity(original) !== expected.identity) {
445
- throw new Error(`State Flow file conflict during preparation: ${path}`);
445
+ throw new Error(`State Flow file conflict during preparation: ${JSON.stringify(path)}`);
446
446
  }
447
447
  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
448
448
  const next = content === undefined ? undefined : Buffer.from(content);
@@ -502,7 +502,7 @@ export interface OwnedFileUpdate {
502
502
  export function assertOwnedFileUpdates(updates: readonly OwnedFileUpdate[], repositoryRoot: string): void {
503
503
  const root = resolve(repositoryRoot);
504
504
  for (const update of updates) {
505
- if (!isStateFlowOwnedPath(update.path, root)) throw new Error(`Cannot inspect a non-State Flow path: ${update.path}`);
505
+ if (!isStateFlowOwnedPath(update.path, root)) throw new Error(`Cannot inspect a non-State Flow path: ${JSON.stringify(update.path)}`);
506
506
  assertCurrentBytes(update.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
507
507
  }
508
508
  }
@@ -520,11 +520,11 @@ export function writeOwnedFileUpdates(
520
520
  try {
521
521
  for (const update of updates) {
522
522
  const path = resolve(update.path);
523
- if (!isStateFlowOwnedPath(path, root)) throw new Error(`Cannot update a non-State Flow path: ${path}`);
524
- if (seen.has(path)) throw new Error(`Duplicate State Flow file update: ${path}`);
523
+ if (!isStateFlowOwnedPath(path, root)) throw new Error(`Cannot update a non-State Flow path: ${JSON.stringify(path)}`);
524
+ if (seen.has(path)) throw new Error(`Duplicate State Flow file update: ${JSON.stringify(path)}`);
525
525
  seen.add(path);
526
526
  const base = byPath.get(path);
527
- if (base === undefined) throw new Error(`State Flow file update has no captured base: ${path}`);
527
+ if (base === undefined) throw new Error(`State Flow file update has no captured base: ${JSON.stringify(path)}`);
528
528
  prepared.push(prepareFile(path, root, update.content, base));
529
529
  }
530
530
  } catch (error) {
@@ -546,19 +546,19 @@ export function restoreDurableFileBases(
546
546
  for (const base of bases) {
547
547
  assertWithinRepository(base.path, root);
548
548
  if (!isStateFlowOwnedPath(base.path, root)) {
549
- throw new Error(`Cannot restore a non-State Flow path: ${base.path}`);
549
+ throw new Error(`Cannot restore a non-State Flow path: ${JSON.stringify(base.path)}`);
550
550
  }
551
551
  }
552
552
  for (const base of bases) {
553
553
  const update = expected.get(resolve(base.path));
554
- if (update === undefined) throw new Error(`Rollback has no published basis: ${base.path}`);
554
+ if (update === undefined) throw new Error(`Rollback has no published basis: ${JSON.stringify(base.path)}`);
555
555
  assertCurrentBytes(base.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
556
556
  if (base.identity === "missing") {
557
557
  rmSync(base.path, { force: true });
558
558
  continue;
559
559
  }
560
560
  const original = base.bytes ?? (base.content === undefined ? undefined : Buffer.from(base.content));
561
- if (original === undefined) throw new Error(`Durable State Flow base content is missing: ${base.path}`);
561
+ if (original === undefined) throw new Error(`Durable State Flow base content is missing: ${JSON.stringify(base.path)}`);
562
562
  assertDirectoryChain(root, dirname(base.path), true);
563
563
  const temporary = join(dirname(base.path), `.${basename(base.path)}.${process.pid}.${randomUUID()}.restore`);
564
564
  try {