@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.
- package/AGENTS.md +10 -10
- package/BACKLOG.md +1 -14
- package/CHANGELOG.md +19 -0
- package/README.md +9 -7
- 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 +2 -1
- package/dist/lib/durable.js +15 -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 +17 -14
- package/dist/lib/history.js +8 -4
- package/dist/lib/json.js +29 -3
- package/dist/lib/migration.d.ts +2 -2
- package/dist/lib/migration.js +55 -21
- package/dist/lib/protocol.js +18 -17
- 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 +11 -3
- package/dist/lib/state.js +14 -4
- package/dist/lib/status.js +1 -1
- package/dist/lib/storage.js +13 -12
- package/dist/lib/telegram.d.ts +9 -6
- package/dist/lib/telegram.js +10 -3
- package/dist/lib/transition.js +8 -3
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-memory/SKILL.md +16 -6
- package/docs/README.md +1 -0
- package/docs/architecture.md +14 -10
- package/docs/filesystem-recovery.md +3 -2
- package/docs/lazy-state.md +505 -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 +14 -5
- package/lib/episode.ts +5 -0
- package/lib/extension.ts +86 -34
- package/lib/git.ts +18 -14
- package/lib/history.ts +8 -4
- package/lib/json.ts +31 -3
- package/lib/migration.ts +51 -20
- package/lib/protocol.ts +18 -17
- package/lib/query.ts +173 -9
- package/lib/runtime.ts +32 -4
- package/lib/snapshot.ts +22 -25
- package/lib/state.ts +22 -6
- package/lib/status.ts +1 -1
- package/lib/storage.ts +14 -11
- package/lib/telegram.ts +20 -6
- package/lib/transition.ts +8 -3
- package/package.json +1 -1
- 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) }),
|
package/lib/continuation.ts
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
|
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
|
-
|
|
275
|
-
|
|
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
|
|
800
|
-
promptSnippet: "Read
|
|
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: "
|
|
803
|
-
|
|
804
|
-
|
|
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;
|
|
809
|
-
if (!
|
|
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
|
|
813
|
-
|
|
814
|
-
|
|
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,
|
|
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 (!
|
|
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
|
-
|
|
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) =>
|
|
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)
|
|
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
|
|
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.
|
|
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,
|
|
237
|
-
|
|
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,
|
|
250
|
-
const document = parseSessionRuntime(config.content,
|
|
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
|
|
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(
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
53
|
-
? value.scope
|
|
54
|
-
|
|
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 =
|
|
15
|
-
?
|
|
16
|
-
:
|
|
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,
|