@llblab/pi-state-flow 0.13.4 → 0.15.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.
Files changed (62) hide show
  1. package/AGENTS.md +10 -10
  2. package/BACKLOG.md +1 -14
  3. package/CHANGELOG.md +19 -0
  4. package/README.md +9 -7
  5. package/dist/lib/config.d.ts +5 -2
  6. package/dist/lib/config.js +17 -16
  7. package/dist/lib/context.d.ts +8 -0
  8. package/dist/lib/context.js +24 -0
  9. package/dist/lib/continuation.js +4 -3
  10. package/dist/lib/durable.d.ts +2 -1
  11. package/dist/lib/durable.js +15 -3
  12. package/dist/lib/episode.d.ts +2 -0
  13. package/dist/lib/episode.js +4 -0
  14. package/dist/lib/extension.d.ts +5 -0
  15. package/dist/lib/extension.js +93 -35
  16. package/dist/lib/git.js +17 -14
  17. package/dist/lib/history.js +8 -4
  18. package/dist/lib/json.js +29 -3
  19. package/dist/lib/migration.d.ts +2 -2
  20. package/dist/lib/migration.js +55 -21
  21. package/dist/lib/protocol.js +18 -17
  22. package/dist/lib/query.d.ts +27 -1
  23. package/dist/lib/query.js +182 -10
  24. package/dist/lib/runtime.d.ts +2 -0
  25. package/dist/lib/runtime.js +34 -5
  26. package/dist/lib/snapshot.d.ts +5 -5
  27. package/dist/lib/snapshot.js +20 -24
  28. package/dist/lib/state.d.ts +11 -3
  29. package/dist/lib/state.js +14 -4
  30. package/dist/lib/status.js +1 -1
  31. package/dist/lib/storage.js +13 -12
  32. package/dist/lib/telegram.d.ts +9 -6
  33. package/dist/lib/telegram.js +10 -3
  34. package/dist/lib/transition.js +8 -3
  35. package/dist/package.json +1 -1
  36. package/dist/skills/state-flow-memory/SKILL.md +16 -6
  37. package/docs/README.md +1 -0
  38. package/docs/architecture.md +14 -10
  39. package/docs/filesystem-recovery.md +3 -2
  40. package/docs/lazy-state.md +505 -0
  41. package/docs/usage.md +11 -8
  42. package/lib/config.ts +18 -15
  43. package/lib/context.ts +24 -0
  44. package/lib/continuation.ts +4 -3
  45. package/lib/durable.ts +14 -5
  46. package/lib/episode.ts +5 -0
  47. package/lib/extension.ts +86 -34
  48. package/lib/git.ts +18 -14
  49. package/lib/history.ts +8 -4
  50. package/lib/json.ts +31 -3
  51. package/lib/migration.ts +51 -20
  52. package/lib/protocol.ts +18 -17
  53. package/lib/query.ts +173 -9
  54. package/lib/runtime.ts +32 -4
  55. package/lib/snapshot.ts +22 -25
  56. package/lib/state.ts +22 -6
  57. package/lib/status.ts +1 -1
  58. package/lib/storage.ts +14 -11
  59. package/lib/telegram.ts +20 -6
  60. package/lib/transition.ts +8 -3
  61. package/package.json +1 -1
  62. package/skills/state-flow-memory/SKILL.md +16 -6
package/lib/context.ts CHANGED
@@ -7,6 +7,29 @@ import type { RehydrationPhase } from "./rehydration.ts";
7
7
  import { projectStateForModel, type MaterializedState } from "./state.ts";
8
8
 
9
9
  export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
10
+ const LAZY_HINT_PATH = "effective.lazy";
11
+ const LAZY_HINT_MAX_KEYS = 32;
12
+ const LAZY_HINT_MAX_JSON_CHARS = 1024;
13
+
14
+ type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
15
+
16
+ function lazyValueKind(value: Exclude<MaterializedState["lazy"], undefined>): LazyValueKind {
17
+ if (value === null) return "null";
18
+ if (Array.isArray(value)) return "array";
19
+ if (typeof value === "object") return "object";
20
+ return typeof value as Exclude<LazyValueKind, "array" | "object">;
21
+ }
22
+
23
+ /** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
24
+ export function lazyNavigationHint(state: MaterializedState): { available: boolean; path: string; keys?: Record<string, LazyValueKind> } {
25
+ const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
26
+ if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy)) return base;
27
+ const entries = Object.entries(state.lazy);
28
+ if (entries.length > LAZY_HINT_MAX_KEYS) return base;
29
+ const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
30
+ return JSON.stringify(keys).length <= LAZY_HINT_MAX_JSON_CHARS ? { ...base, keys } : base;
31
+ }
32
+
10
33
 
11
34
  /** Bounded context retained after semantic State Flow is stopped in this physical session. */
12
35
  export interface PassiveContinuation {
@@ -85,6 +108,7 @@ export function runtimeContextMessage(
85
108
  const context = {
86
109
  specification: snapshot.meta.specification,
87
110
  state: projectStateForModel(state),
111
+ lazy_navigation: lazyNavigationHint(state),
88
112
  ...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
89
113
  ...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
90
114
  ...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),
@@ -223,11 +223,12 @@ export function inspectStateFlowContinuationProvenance(
223
223
  const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
224
224
  try {
225
225
  const config = readRegular(paths.config);
226
+ const runtimeSource = readRegular(paths.runtime);
226
227
  const meta = readRegular(paths.meta);
227
- if (config === undefined && meta === undefined) {
228
+ if (config === undefined && runtimeSource === undefined && meta === undefined) {
228
229
  return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
229
230
  }
230
- const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
231
+ const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
231
232
  if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
232
233
  if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
233
234
  if (runtime.meta.publication === "files") {
@@ -238,7 +239,7 @@ export function inspectStateFlowContinuationProvenance(
238
239
  validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
239
240
  return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
240
241
  }
241
- const runtimePath = relative(resolve(repositoryRoot), paths.meta);
242
+ const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
242
243
  if (runtimePath.startsWith("..")) throw new Error("runtime provenance escapes repository");
243
244
  const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
244
245
  if (!owner) throw new Error("runtime owner commit is unavailable");
package/lib/durable.ts CHANGED
@@ -20,13 +20,14 @@ import {
20
20
  } from "./artifact.ts";
21
21
  import { canonicalJson, isJsonValue, isObject } from "./json.ts";
22
22
  import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
23
- import type { StateScope } from "./state.ts";
23
+ import { migratePreIntentState, type StateScope } from "./state.ts";
24
24
 
25
25
  const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
26
26
  const STATE_FILE = "state.json";
27
27
  const CHECKPOINT_FILE = "checkpoint.json";
28
28
  const PATCHES_FILE = "patches.jsonl";
29
29
  const META_FILE = "meta.json";
30
+ const RUNTIME_FILE = "runtime.json";
30
31
 
31
32
  /** Canonical semantic sources plus runtime-owned temporal metadata. */
32
33
  export interface ScopeStreamSources {
@@ -99,6 +100,7 @@ export function classifyScopeStream(
99
100
  }
100
101
  const temporal = meta?.temporal;
101
102
  if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
103
+ checkpoint = migratePreIntentState(checkpoint) ?? checkpoint;
102
104
  const owner = meta?.owner;
103
105
  if (scope === "cwd" && expectedCwd !== undefined
104
106
  && (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
@@ -125,6 +127,10 @@ export function classifyScopeStream(
125
127
  } else if (scope === "cwd" && expectedCwd !== undefined) {
126
128
  throw new Error("State Flow CWD scope identity is missing");
127
129
  }
130
+ if (isObject(legacyCheckpoint) && isObject(legacyCheckpoint.state)) {
131
+ const migrated = migratePreIntentState(legacyCheckpoint.state);
132
+ if (migrated) legacyCheckpoint = { ...legacyCheckpoint, state: migrated };
133
+ }
128
134
  const stream = { checkpoint: legacyCheckpoint, patches };
129
135
  validateScopeStream(stream, scope);
130
136
  return { kind: "present", stream };
@@ -159,9 +165,9 @@ export function temporalScopePaths(cwd: string, sessionId: string, scope: StateS
159
165
  return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
160
166
  }
161
167
 
162
- export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; meta: string } {
168
+ export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; runtime: string; meta: string } {
163
169
  const directory = sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory;
164
- return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
170
+ return { config: join(directory, "config.json"), runtime: join(directory, RUNTIME_FILE), meta: join(directory, META_FILE) };
165
171
  }
166
172
 
167
173
  /** Unsupported state.json presence never becomes an anchored checkpoint. */
@@ -178,7 +184,7 @@ export function captureTemporalFileBases(cwd: string, sessionId: string, reposit
178
184
  const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
179
185
  const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
180
186
  const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
181
- return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.meta])];
187
+ return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
182
188
  });
183
189
  return captureOwnedFileBases(paths, repositoryRoot);
184
190
  }
@@ -218,6 +224,9 @@ export function serializeScopeMetadata(
218
224
  cwdIdentity?: string, existingSource?: string,
219
225
  ): string {
220
226
  const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
227
+ if (scope === "session") {
228
+ for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap", "remotePublication", "revision", "temporalRevision", "publication"]) delete existing[key];
229
+ }
221
230
  const sources = serializeScopeStream(stream, scope, cwdIdentity);
222
231
  const value = {
223
232
  ...existing,
@@ -359,7 +368,7 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
359
368
  return cwdKey(segments[0]!)
360
369
  && sessionKey(segments[1]!)
361
370
  && (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
362
- || segments[2] === "config.json" || segments[2] === META_FILE);
371
+ || segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
363
372
  }
364
373
  return false;
365
374
  }
package/lib/episode.ts CHANGED
@@ -27,3 +27,8 @@ export function prepareRun(snapshot: Snapshot, prompt: string): boolean {
27
27
  snapshot.meta.validation = undefined;
28
28
  return true;
29
29
  }
30
+
31
+ /** Retain the full prompt only while its run remains recoverable and unfinished. */
32
+ export function completeRun(snapshot: Snapshot): void {
33
+ delete snapshot.meta.specification;
34
+ }
package/lib/extension.ts CHANGED
@@ -5,7 +5,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
5
5
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
6
6
  import { Text } from "@earendil-works/pi-tui";
7
7
  import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.ts";
8
- import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
8
+ import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
9
9
  import { ArtifactReadTracker } from "./acquisition.ts";
10
10
  import { loadStateFlowConfig } from "./config.ts";
11
11
  import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
@@ -18,7 +18,7 @@ import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatche
18
18
  import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
19
19
  import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
20
20
  import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
21
- import { prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
21
+ import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
22
22
  import { recoverSnapshot } from "./recovery.ts";
23
23
  import type { RehydrationPhase } from "./rehydration.ts";
24
24
  import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
@@ -26,8 +26,8 @@ import { coalescePublicationTarget, createPublicationQueue, type PublicationQueu
26
26
  import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
27
27
  import { runPublicationWorker } from "./publication.ts";
28
28
  import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
29
- import { isObject, sameJson } from "./json.ts";
30
- import { readStatePath } from "./query.ts";
29
+ import { canonicalJson, isObject, sameJson } from "./json.ts";
30
+ import { readProjectedState, readStatePath } from "./query.ts";
31
31
  import {
32
32
  cwdScopeKey,
33
33
  resolveSessionAddress,
@@ -50,6 +50,8 @@ export interface StateFlowExtensionOptions {
50
50
  knowledgeRoot?: string;
51
51
  onRuntime?: (accessor: { read(offset?: number, scope?: StateScope): MaterializedState }) => void;
52
52
  telegram?: { load?: StateFlowTelegramLoader };
53
+ /** Test/SDK capability override; repository config remains the Pi default. */
54
+ passive?: { bootstrap?: boolean; tools?: boolean };
53
55
  }
54
56
 
55
57
  export const PATCH_STATE_TOOL_NAME = "patch_state";
@@ -113,7 +115,12 @@ function separatedFailure(error: unknown): Error {
113
115
 
114
116
  export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
115
117
  const agentDir = options.agentDir ?? getAgentDir();
116
- const config = loadStateFlowConfig(agentDir);
118
+ const loadedConfig = loadStateFlowConfig(agentDir, options.repositoryRoot);
119
+ const config = {
120
+ ...loadedConfig,
121
+ passiveBootstrap: options.passive?.bootstrap ?? loadedConfig.passiveBootstrap,
122
+ passiveTools: options.passive?.tools ?? loadedConfig.passiveTools,
123
+ };
117
124
  let snapshot: Snapshot = emptySnapshot();
118
125
  let scopeStates: ScopedStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
119
126
  let branchHasSnapshot = false;
@@ -268,11 +275,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
268
275
  scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
269
276
  }
270
277
 
278
+ function passiveToolsAvailable(): boolean {
279
+ return snapshot.config.enabled || config.passiveTools;
280
+ }
281
+
271
282
  function syncStateFlowTools(): void {
272
283
  const active = pi.getActiveTools();
273
284
  const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
274
- if (owned.every((name) => active.includes(name) === snapshot.config.enabled)) return;
275
- pi.setActiveTools(snapshot.config.enabled
285
+ const available = passiveToolsAvailable();
286
+ if (owned.every((name) => active.includes(name) === available)) return;
287
+ pi.setActiveTools(available
276
288
  ? [...new Set([...active, ...owned])]
277
289
  : active.filter((name) => !owned.includes(name)));
278
290
  }
@@ -680,6 +692,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
680
692
  else if (snapshot.meta.bootstrap) bootstrapContinuation = continuation;
681
693
  }
682
694
  }
695
+ if (!snapshot.config.enabled && (config.passiveBootstrap || config.passiveTools) && !runtime?.view) {
696
+ try {
697
+ runtime?.loadPassive();
698
+ installScopeStates();
699
+ } catch (error) {
700
+ ctx.ui.notify(`State Flow passive memory is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
701
+ }
702
+ }
683
703
  if (snapshot.config.enabled) deferArtifactRefresh();
684
704
  syncStateFlowTools();
685
705
  updateUi(ctx);
@@ -796,34 +816,38 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
796
816
  pi.registerTool({
797
817
  name: READ_STATE_TOOL_NAME,
798
818
  label: "Read State",
799
- description: "Read State Flow through a unified path such as state, state[1], state.cwd[2], or state.global.patches[0]. The legacy offset/scope form remains accepted. Read-only and lazy; unavailable hot history is an error.",
800
- promptSnippet: "Read cached state or accepted scope patches with a unified path",
819
+ description: "Read exact State Flow values or historical semantic patches with one path or an ordered path list. Unscoped semantic paths read the effective overlay; effective makes that overlay explicit, while global, cwd, and session select ownership. Array selectors support zero-based indices and half-open [start..end] ranges. Projection value returns semantic data; keys returns minimal structure; patch intersects the selected path at its boundary.",
820
+ promptSnippet: "Read exact state values, structures, or historical semantic patches",
801
821
  parameters: Type.Object({
802
- path: Type.Optional(Type.String({ description: "Unified query path; current aliases use index 0" })),
803
- offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 7, description: "Legacy accepted-transition offset; defaults to 0" })),
804
- scope: Type.Optional(StringEnum(["effective", "global", "cwd", "session"] as const, { description: "Legacy projection at the same boundary; defaults to effective" })),
822
+ path: Type.Optional(Type.String({ description: "One semantic path; unscoped paths use effective, explicit roots may use effective/global/cwd/session and historical [N], and arrays support half-open [start..end] ranges" })),
823
+ paths: Type.Optional(Type.Array(Type.String(), { minItems: 1, description: "Ordered query paths evaluated as one all-or-error read" })),
824
+ projection: Type.Optional(StringEnum(["value", "keys", "patch"] as const, { description: "Value snapshot by default, structural keys with minimal meta, or the selected historical semantic patch" })),
805
825
  }, { additionalProperties: false }),
806
826
  async execute(_toolCallId, params, signal) {
807
827
  try {
808
- type ReadDetails = { path?: string; offset?: number; scope?: string; transitionId: string };
809
- if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
828
+ type ReadDetails = { path?: string; paths?: string[]; projection?: string; transitionId?: string };
829
+ if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
810
830
  if (signal?.aborted) throw new Error("State Flow read was aborted");
811
831
  if (!runtime?.view) throw new Error("State Flow temporal runtime is unavailable");
812
- if (params.path !== undefined) {
813
- if (params.offset !== undefined || params.scope !== undefined) throw new Error("read_state path cannot be combined with legacy offset or scope");
814
- const result = readStatePath(runtime.view, params.path);
832
+ if (params.path === undefined && params.paths === undefined) throw new Error("read_state requires path or paths");
833
+ if (params.path !== undefined && params.paths !== undefined) throw new Error("read_state accepts path or paths, not both");
834
+ {
835
+ const paths = params.paths ?? [params.path!];
836
+ if (paths.length === 1 && /^(?:global|cwd|session)\.patches(?:\[\d+\])?$/.test(paths[0]!)) {
837
+ if (params.projection !== undefined && params.projection !== "value") throw new Error("Scope patch paths support only the value projection");
838
+ const result = readStatePath(runtime.view, paths[0]!);
839
+ if (!("patch" in result)) throw new Error("Expected a scope patch path");
840
+ return {
841
+ content: [{ type: "text", text: `\n${JSON.stringify({ patch: result.patch })}` }],
842
+ details: { path: paths[0], transitionId: result.boundary.id } as ReadDetails,
843
+ };
844
+ }
845
+ const result = readProjectedState(runtime.view, paths, params.projection);
815
846
  return {
816
847
  content: [{ type: "text", text: `\n${JSON.stringify(result)}` }],
817
- details: { path: params.path, transitionId: result.boundary.id } as ReadDetails,
848
+ details: { ...(params.path === undefined ? { paths } : { path: params.path }), projection: params.projection ?? "value" } as ReadDetails,
818
849
  };
819
850
  }
820
- const { offset = 0, scope = "effective" } = params;
821
- const state = runtime.read(offset, scope === "effective" ? undefined : scope);
822
- const boundary = runtime.view.lineage.at(-1 - offset)!;
823
- return {
824
- content: [{ type: "text", text: `\n${JSON.stringify({ offset, scope, boundary, state: projectStateForModel(state) })}` }],
825
- details: { offset, scope, transitionId: boundary.id } as ReadDetails,
826
- };
827
851
  } catch (error) {
828
852
  throw separatedFailure(error);
829
853
  }
@@ -856,7 +880,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
856
880
  },
857
881
  async execute(toolCallId, params, signal, _onUpdate, ctx) {
858
882
  try {
859
- if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
883
+ if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
860
884
  if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
861
885
  if (!isObject(params)) throw new Error("patch_state requires an object");
862
886
  const allowed = new Set(["global", "cwd", "session", "final"]);
@@ -878,16 +902,27 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
878
902
  return { content: [{ type: "text", text: "\nState unchanged; iteration remains non-terminal." }], details: { final: false } };
879
903
  }
880
904
  if (params.final !== true) throw new Error('patch_state requires at least one scope patch or {"final":true}');
905
+ if (!snapshot.config.enabled) return { content: [{ type: "text", text: "\nState unchanged; passive turns have no terminal barrier." }], details: { final: false } };
881
906
  validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
882
907
  terminalEligible = true;
883
908
  return { content: [{ type: "text", text: "\nState iteration is terminal-eligible." }], details: { final: true } };
884
909
  }
885
- const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
910
+ if (!runtime?.view) {
911
+ runtime ??= createRuntime(ctx);
912
+ runtime.prepare();
913
+ const publication = runtime.initialize(snapshot, true, undefined, true);
914
+ recordPolicyPublication(publication, ctx);
915
+ installScopeStates();
916
+ branchHasSnapshot = true;
917
+ }
918
+ runtime.migrateLegacyStorage();
919
+ installScopeStates();
920
+ const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
886
921
  const semanticChange = (["global", "cwd", "session"] as const).some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
887
922
  const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
888
923
  if (!semanticChange && !provenanceChange) throw new Error('patch_state scope patches must materially update state or required provenance; omit them and use {"final":true} when unchanged');
889
924
  commitStage(stage, ctx, false);
890
- if (params.final === true) {
925
+ if (params.final === true && snapshot.config.enabled) {
891
926
  terminalEligible = true;
892
927
  }
893
928
  updateUi(ctx);
@@ -1051,11 +1086,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1051
1086
  bootstrap: snapshot.meta.bootstrap === true,
1052
1087
  startPending: telegramStartPending,
1053
1088
  }),
1054
- state: (scope) => projectStateForModel(
1055
- scope === "effective"
1089
+ state: (scope) => {
1090
+ const selected = scope === "effective"
1056
1091
  ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
1057
- : scopeStates[scope],
1058
- ),
1092
+ : scopeStates[scope];
1093
+ return {
1094
+ ...projectStateForModel(selected),
1095
+ ...(Object.hasOwn(selected, "lazy") ? { lazy: structuredClone(selected.lazy) } : {}),
1096
+ };
1097
+ },
1059
1098
  canStartNow: () => activeContext === undefined || activeContext.isIdle(),
1060
1099
  start: () => {
1061
1100
  if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -1080,7 +1119,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1080
1119
  void telegram.ensure();
1081
1120
 
1082
1121
  pi.on("before_agent_start", (event, ctx) => {
1083
- if (!snapshot.config.enabled) return;
1122
+ if (!snapshot.config.enabled) {
1123
+ if (!config.passiveBootstrap || !runtime?.view) return;
1124
+ return {
1125
+ systemPrompt: `${event.systemPrompt}\n\nState Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns do not require final:true and never trigger State Flow continuation or compaction.`,
1126
+ };
1127
+ }
1084
1128
  skillReads.clear();
1085
1129
  artifactReads.clear();
1086
1130
  if (artifactRefreshPending) refreshArtifactInvalidations(ctx);
@@ -1105,7 +1149,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1105
1149
  if (passiveContinuation) {
1106
1150
  return { messages: passiveContinuationMessages(event.messages as AgentMessage[], passiveContinuation) };
1107
1151
  }
1108
- if (!snapshot.config.enabled || snapshot.meta.specification === undefined) return;
1152
+ if (!snapshot.config.enabled) {
1153
+ if (!config.passiveBootstrap || !runtime?.view) return;
1154
+ const state = projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session));
1155
+ return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${canonicalJson({ state, lazy_navigation: lazyNavigationHint(state) })}`), ...(event.messages as AgentMessage[])] };
1156
+ }
1157
+ if (snapshot.meta.specification === undefined) return;
1109
1158
  const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
1110
1159
  const invalidations = artifactInvalidations.map(({ path, reason }) => ({ path, reason }));
1111
1160
  const recentTransitions = projectRecentTransitionsWithLimit(
@@ -1206,9 +1255,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1206
1255
  return;
1207
1256
  }
1208
1257
  let responseCommitted = false;
1258
+ const specification = snapshot.meta.specification;
1209
1259
  try {
1210
1260
  const response = finalizedAssistantResponse(event.message);
1211
1261
  const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime!.causalBasis());
1262
+ completeRun(snapshot);
1212
1263
  commitStage(stage, ctx, true);
1213
1264
  responseCommitted = true;
1214
1265
  bootstrapContinuation = undefined;
@@ -1217,6 +1268,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
1217
1268
  if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
1218
1269
  completedRunAccepted = !wasBootstrap;
1219
1270
  } catch (error) {
1271
+ if (!responseCommitted && specification !== undefined) snapshot.meta.specification = specification;
1220
1272
  recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
1221
1273
  ctx.ui.notify(responseCommitted
1222
1274
  ? `State Flow committed the final response; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`
package/lib/git.ts CHANGED
@@ -226,15 +226,15 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
226
226
  const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
227
227
  const readFile = revisionFileReader(root, revision, [
228
228
  ...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
229
- canonicalRuntime.config, canonicalRuntime.meta,
229
+ canonicalRuntime.config, canonicalRuntime.runtime,
230
230
  ]);
231
231
  const files: DurableFileBase[] = [];
232
232
  const scopes = {} as Record<StateScope, ScopeStream | undefined>;
233
233
  const provenance: Record<StateScope, ArtifactProvenanceRegistry> = { global: {}, cwd: {}, session: {} };
234
234
  for (const { scope, paths } of scopePaths) {
235
235
  const selected = revisionScopeFiles(readFile, paths);
236
- files.push(selected.checkpoint, selected.patches, ...(scope === "session" ? [] : [selected.meta]));
237
- if (scope !== "session") provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
236
+ files.push(selected.checkpoint, selected.patches, selected.meta);
237
+ provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
238
238
  try {
239
239
  scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope,
240
240
  scope === "cwd" ? cwd : undefined, selected.meta.content);
@@ -243,15 +243,18 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
243
243
  }
244
244
  }
245
245
  const readRuntime = (paths: ReturnType<typeof sessionRuntimePaths>) => ({
246
- paths, config: readFile(paths.config), meta: readFile(paths.meta),
246
+ paths, config: readFile(paths.config), runtime: readFile(paths.runtime), meta: readFile(paths.meta),
247
247
  });
248
- const { paths: runtimePaths, config, meta } = readRuntime(canonicalRuntime);
249
- files.push(config, meta);
250
- const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
248
+ const { paths: runtimePaths, config, runtime, meta } = readRuntime(canonicalRuntime);
249
+ files.push(config, runtime);
250
+ const document = parseSessionRuntime(config.content, runtime.content, cwd, sessionId, meta.content);
251
251
  if (document === undefined) return { base: { head: revision, files }, scopes, provenance };
252
- provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
252
+ if (Object.keys(provenance.session).length === 0 && document.meta.artifacts !== undefined) {
253
+ provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
254
+ }
255
+ const runtimeOwnerPath = runtime.content === undefined ? runtimePaths.meta : runtimePaths.runtime;
253
256
  const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
254
- relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
257
+ relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimeOwnerPath, root),
255
258
  ]).stdout.trim();
256
259
  assertReadableRevision(root, owner);
257
260
  let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
@@ -407,8 +410,7 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
407
410
  if (snapshot.meta.step !== selected.runtime.meta.step) throw new Error("Git adoption must preserve the semantic step");
408
411
  const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
409
412
  runtime.meta.temporalRevision = "self";
410
- const sources = serializeSessionRuntime(runtime, cwd, sessionId, selected.view.scopes.session,
411
- selected.base.files.find(({ path }) => path === sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey).meta)?.content);
413
+ const sources = serializeSessionRuntime(runtime, cwd, sessionId);
412
414
  initializeGitRepository(repositoryRoot);
413
415
  return withPublicationLock(repositoryRoot, (root) => {
414
416
  const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -417,13 +419,14 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
417
419
  const provenancePaths = new Set([
418
420
  temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
419
421
  temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
422
+ temporalScopePaths(cwd, sessionId, "session", root, sessionKey).meta,
420
423
  ]);
421
424
  // Preserve exact valid scope bytes; only runtime provenance changes representation.
422
425
  const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
423
426
  || path.endsWith("patches.jsonl")
424
427
  || (provenancePaths.has(path) && identity !== "missing"))
425
428
  .map(({ path, content }) => ({ path, content: content! }));
426
- updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
429
+ updates.push({ path: paths.config, content: sources.config }, { path: paths.runtime, content: sources.runtime });
427
430
  const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head!, path).content === content)
428
431
  ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
429
432
  if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
@@ -447,7 +450,7 @@ function includeUncommittedCohort(cwd: string, sessionId: string, root: string,
447
450
  return { scope, pair: desired([paths.checkpoint, paths.patches]) };
448
451
  });
449
452
  const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
450
- const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.meta]) : [];
453
+ const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.runtime]) : [];
451
454
  const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head,
452
455
  [...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
453
456
  const absentFromHead = (files: OwnedFileUpdate[]) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
@@ -480,7 +483,8 @@ export function publishTemporalStateToGit(
480
483
  if (runtime?.meta.publication === "files") throw new Error("Git publication requires explicit Git provenance");
481
484
  const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
482
485
  const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content,
483
- current.files.find(({ path }) => path === runtimePaths.meta)?.content, cwd, sessionId);
486
+ current.files.find(({ path }) => path === runtimePaths.runtime)?.content, cwd, sessionId,
487
+ current.files.find(({ path }) => path === runtimePaths.meta)?.content);
484
488
  if (previousRuntime?.meta.publication === "files") throw new Error("File-only storage requires explicit full-cohort Git adoption");
485
489
  const runtimeOnly = runtime?.meta.temporalRevision !== undefined && runtime.meta.temporalRevision !== "self";
486
490
  if (runtimeOnly) {
package/lib/history.ts CHANGED
@@ -22,7 +22,7 @@ export interface RecentTransition extends AcceptedTransition {
22
22
 
23
23
  export type RecentTransitionWindow = RecentTransition[];
24
24
  const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
25
- const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
25
+ const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "response", "lazy"]);
26
26
 
27
27
  /** Normalize accepted replacements into recursive-merge replay, including removals. */
28
28
  function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
@@ -49,9 +49,13 @@ function validateScopedPatch(value: unknown): asserts value is RecentScopePatch
49
49
  }
50
50
  validatePatch(value.patch);
51
51
  for (const [key, field] of Object.entries(value.patch)) {
52
- if (!PATCH_KEYS.has(key) || (key === "response"
53
- ? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
54
- throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
52
+ const valid = key === "response"
53
+ ? value.scope === "session" && typeof field === "string"
54
+ : key === "lazy"
55
+ ? field !== null
56
+ : PATCH_KEYS.has(key) && isObject(field);
57
+ if (!PATCH_KEYS.has(key) || !valid) {
58
+ throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
55
59
  }
56
60
  }
57
61
  }
package/lib/json.ts CHANGED
@@ -3,6 +3,32 @@ import { createHash } from "node:crypto";
3
3
  export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
4
4
  export interface JsonObject { [key: string]: JsonValue }
5
5
 
6
+ const ARRAY_INDEX_SELECTOR = /^\[(0|[1-9]\d*)\]$/;
7
+
8
+ function isIndexedArrayPatch(value: JsonObject): boolean {
9
+ const keys = Object.keys(value);
10
+ return keys.length > 0 && keys.every((key) => ARRAY_INDEX_SELECTOR.test(key));
11
+ }
12
+
13
+ function applyArrayPatch(state: JsonValue[], patch: JsonObject): JsonValue[] {
14
+ const next = structuredClone(state);
15
+ for (const [selector, value] of Object.entries(patch)) {
16
+ const match = ARRAY_INDEX_SELECTOR.exec(selector)!;
17
+ const index = Number(match[1]);
18
+ if (!Number.isSafeInteger(index) || index >= next.length) {
19
+ throw new Error(`State patch array index ${selector} is out of bounds for length ${next.length}`);
20
+ }
21
+ if (value === null) throw new Error(`State patch array index ${selector} cannot be deleted; replace the whole array instead`);
22
+ const current = next[index]!;
23
+ next[index] = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
24
+ ? applyArrayPatch(current, value)
25
+ : isObject(current) && isObject(value)
26
+ ? applyPatch(current, value)
27
+ : structuredClone(value);
28
+ }
29
+ return next;
30
+ }
31
+
6
32
  export function applyPatch(state: JsonObject, patch: JsonObject): JsonObject {
7
33
  const next: JsonObject = structuredClone(state);
8
34
  for (const [key, value] of Object.entries(patch)) {
@@ -11,9 +37,11 @@ export function applyPatch(state: JsonObject, patch: JsonObject): JsonObject {
11
37
  continue;
12
38
  }
13
39
  const current = next[key];
14
- const materialized = isObject(current) && isObject(value)
15
- ? applyPatch(current, value)
16
- : structuredClone(value);
40
+ const materialized = Array.isArray(current) && isObject(value) && isIndexedArrayPatch(value)
41
+ ? applyArrayPatch(current, value)
42
+ : isObject(current) && isObject(value)
43
+ ? applyPatch(current, value)
44
+ : structuredClone(value);
17
45
  Object.defineProperty(next, key, {
18
46
  value: materialized,
19
47
  enumerable: true,