@llblab/pi-state-flow 0.24.0 → 0.25.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.
- package/AGENTS.md +1 -1
- package/BACKLOG.md +15 -12
- package/CHANGELOG.md +14 -0
- package/README.md +116 -34
- package/dist/lib/acquisition.d.ts +24 -1
- package/dist/lib/acquisition.js +80 -1
- package/dist/lib/compaction.d.ts +17 -0
- package/dist/lib/compaction.js +40 -0
- package/dist/lib/context.d.ts +4 -2
- package/dist/lib/context.js +7 -2
- package/dist/lib/extension.js +149 -298
- package/dist/lib/git.d.ts +29 -0
- package/dist/lib/git.js +58 -0
- package/dist/lib/operation.d.ts +37 -0
- package/dist/lib/operation.js +59 -0
- package/dist/lib/ownership.d.ts +31 -0
- package/dist/lib/ownership.js +117 -0
- package/dist/lib/protocol.d.ts +1 -1
- package/dist/lib/protocol.js +8 -8
- package/dist/lib/query.js +1 -1
- package/dist/lib/status.d.ts +2 -0
- package/dist/lib/status.js +28 -0
- package/dist/lib/transition.d.ts +3 -0
- package/dist/lib/transition.js +8 -1
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +15 -7
- package/dist/skills/state-flow-memory/SKILL.md +2 -2
- package/docs/README.md +19 -9
- package/docs/agent-contract-relocation.md +4 -4
- package/docs/architecture.md +645 -91
- package/docs/compatibility.md +116 -37
- package/docs/filesystem-recovery.md +118 -21
- package/docs/fork-contract.md +68 -8
- package/docs/lazy-state.md +90 -14
- package/docs/performance.md +83 -66
- package/docs/temporal-acceptance.md +391 -62
- package/docs/usage.md +317 -62
- package/lib/acquisition.ts +85 -1
- package/lib/compaction.ts +47 -0
- package/lib/context.ts +9 -2
- package/lib/extension.ts +161 -295
- package/lib/git.ts +63 -0
- package/lib/operation.ts +75 -0
- package/lib/ownership.ts +120 -0
- package/lib/protocol.ts +8 -9
- package/lib/query.ts +1 -1
- package/lib/runtime.ts +1 -1
- package/lib/snapshot.ts +1 -2
- package/lib/status.ts +29 -0
- package/lib/transition.ts +9 -1
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +15 -7
- package/skills/state-flow-memory/SKILL.md +2 -2
package/lib/acquisition.ts
CHANGED
|
@@ -6,8 +6,11 @@ import {
|
|
|
6
6
|
type ArtifactInvalidationRequest,
|
|
7
7
|
type ArtifactSourceFingerprint,
|
|
8
8
|
type ArtifactSourceIdentity,
|
|
9
|
+
ORDINARY_ARTIFACT_COMPILER,
|
|
10
|
+
type ArtifactProvenanceRegistry,
|
|
9
11
|
} from "./artifact.ts";
|
|
10
|
-
import { isObject } from "./json.ts";
|
|
12
|
+
import { isObject, type JsonObject } from "./json.ts";
|
|
13
|
+
import type { AtomicScopePatches, ScopedSemanticStates, ScopedStates, StateScope } from "./state.ts";
|
|
11
14
|
|
|
12
15
|
/** Why the caller is considering source-body acquisition. */
|
|
13
16
|
export type ArtifactAcquisitionIntent =
|
|
@@ -154,3 +157,84 @@ export function decideArtifactAcquisition(
|
|
|
154
157
|
return { kind: "read-source", reason: "maintenance" };
|
|
155
158
|
}
|
|
156
159
|
}
|
|
160
|
+
|
|
161
|
+
export const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
|
|
162
|
+
|
|
163
|
+
const SCOPES = ["global", "cwd", "session"] as const;
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* One selected branch's ordinary-artifact acquisition plan: runtime-observed
|
|
167
|
+
* invalidations, their model hints and the read tracker correlated to them.
|
|
168
|
+
* The tracker's candidates always equal the current invalidation plan.
|
|
169
|
+
*/
|
|
170
|
+
export class ArtifactAcquisitionState {
|
|
171
|
+
readonly reads = new ArtifactReadTracker();
|
|
172
|
+
#invalidations: ArtifactInvalidationRequest[] = [];
|
|
173
|
+
#hints: Record<string, string> = {};
|
|
174
|
+
|
|
175
|
+
get invalidations(): readonly ArtifactInvalidationRequest[] { return this.#invalidations; }
|
|
176
|
+
get hints(): Record<string, string> { return this.#hints; }
|
|
177
|
+
|
|
178
|
+
/** Drop the invalidation plan; hints remain until the next refresh. */
|
|
179
|
+
clearInvalidations(): void { this.#setInvalidations([]); }
|
|
180
|
+
|
|
181
|
+
/** Forget plan and hints when no memory view is selected. */
|
|
182
|
+
reset(): void {
|
|
183
|
+
this.#hints = {};
|
|
184
|
+
this.#setInvalidations([]);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Re-observe exact registered sources for the selected scope artifacts. */
|
|
188
|
+
refresh(states: ScopedStates, provenance: (scope: StateScope) => ArtifactProvenanceRegistry): void {
|
|
189
|
+
const paths = new Set<string>();
|
|
190
|
+
for (const scope of SCOPES) for (const path of Object.keys(states[scope].artifacts)) paths.add(path);
|
|
191
|
+
const observations = new Map(inspectRegisteredArtifactPaths(paths).map((observation) => [observation.path, observation]));
|
|
192
|
+
const hints: Record<string, string> = {};
|
|
193
|
+
const invalidations = new Map<string, ArtifactInvalidationRequest>();
|
|
194
|
+
for (const scope of SCOPES) {
|
|
195
|
+
const registry = provenance(scope);
|
|
196
|
+
for (const [path, metadata] of Object.entries(states[scope].artifacts)) {
|
|
197
|
+
// A narrower owner replaces broader evidence for the same path.
|
|
198
|
+
delete hints[path];
|
|
199
|
+
invalidations.delete(path);
|
|
200
|
+
if (metadata.kind === "skill") continue;
|
|
201
|
+
const observed = observations.get(path);
|
|
202
|
+
if (observed?.kind !== "present") continue;
|
|
203
|
+
const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, registry[path]);
|
|
204
|
+
if (need.kind !== "requires-compilation") continue;
|
|
205
|
+
if (need.reason === "source-changed") hints[path] = SOURCE_CHANGED_HINT;
|
|
206
|
+
invalidations.set(path, { path, scope, reason: need.reason });
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
this.#hints = hints;
|
|
210
|
+
this.#setInvalidations([...invalidations.values()].sort((left, right) => left.path.localeCompare(right.path)));
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Accepted compilations leave the plan; correlated read evidence is single-use. */
|
|
214
|
+
acceptAcquired(paths: ReadonlySet<string> = new Set(this.reads.successful.keys())): void {
|
|
215
|
+
this.#setInvalidations(this.#invalidations.filter(({ path }) => !paths.has(path)));
|
|
216
|
+
this.reads.clear();
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
#setInvalidations(invalidations: ArtifactInvalidationRequest[]): void {
|
|
220
|
+
this.#invalidations = invalidations;
|
|
221
|
+
this.reads.setCandidates(invalidations);
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
|
|
226
|
+
export function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches {
|
|
227
|
+
const owners = new Map<string, StateScope[]>();
|
|
228
|
+
for (const scope of SCOPES) for (const path of Object.keys(states[scope].artifacts ?? {})) {
|
|
229
|
+
owners.set(path, [...owners.get(path) ?? [], scope]);
|
|
230
|
+
}
|
|
231
|
+
const removals: AtomicScopePatches = {};
|
|
232
|
+
for (const observation of inspectRegisteredArtifactPaths(owners.keys())) {
|
|
233
|
+
if (observation.kind !== "missing") continue;
|
|
234
|
+
for (const scope of owners.get(observation.path) ?? []) {
|
|
235
|
+
const artifacts = (removals[scope]?.artifacts ?? {}) as JsonObject;
|
|
236
|
+
removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return removals;
|
|
240
|
+
}
|
package/lib/compaction.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
1
2
|
import type { AgentMessage } from "@earendil-works/pi-agent-core";
|
|
2
3
|
import { estimateTokens, type CompactionResult } from "@earendil-works/pi-coding-agent";
|
|
3
4
|
|
|
@@ -97,3 +98,49 @@ export function stateFlowCompactionResult(
|
|
|
97
98
|
details: structuredClone(plan.details),
|
|
98
99
|
};
|
|
99
100
|
}
|
|
101
|
+
|
|
102
|
+
const STATE_FLOW_COMPACTION_MARKER_PREFIX = "state-flow-boundary:";
|
|
103
|
+
|
|
104
|
+
type CompactionEvent = Parameters<typeof stateFlowCompactionResult>[2];
|
|
105
|
+
|
|
106
|
+
/** Completed-history compaction request state owned by one extension instance. */
|
|
107
|
+
export class StateFlowCompactionRequests {
|
|
108
|
+
#plan: StateFlowCompactionPlan | undefined;
|
|
109
|
+
#marker: string | undefined;
|
|
110
|
+
#inFlight = false;
|
|
111
|
+
#stopped = false;
|
|
112
|
+
readonly #prefix = `${STATE_FLOW_COMPACTION_MARKER_PREFIX}${randomUUID()}:`;
|
|
113
|
+
|
|
114
|
+
get inFlight(): boolean { return this.#inFlight; }
|
|
115
|
+
get stopped(): boolean { return this.#stopped; }
|
|
116
|
+
|
|
117
|
+
/** Permanently refuse owned requests (shutdown). */
|
|
118
|
+
stop(): void { this.#stopped = true; }
|
|
119
|
+
|
|
120
|
+
/** Drop the run-local plan; a stale callback can no longer clear a newer one. */
|
|
121
|
+
clear(): void {
|
|
122
|
+
this.#plan = undefined;
|
|
123
|
+
this.#inFlight = false;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** Install a plan and return its unique per-request marker. */
|
|
127
|
+
begin(plan: StateFlowCompactionPlan): string {
|
|
128
|
+
this.#plan = plan;
|
|
129
|
+
const marker = this.#marker = `${this.#prefix}${randomUUID()}`;
|
|
130
|
+
this.#inFlight = true;
|
|
131
|
+
return marker;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Native completion clears only its own request. */
|
|
135
|
+
finish(marker: string): void {
|
|
136
|
+
if (this.#marker === marker) this.clear();
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Answer session_before_compact: foreign requests pass, stale or unpermitted owned ones cancel. */
|
|
140
|
+
resolve(event: CompactionEvent, permitted: boolean): ReturnType<typeof stateFlowCompactionResult> {
|
|
141
|
+
if (event.reason !== "manual" || !event.customInstructions?.startsWith(STATE_FLOW_COMPACTION_MARKER_PREFIX)) return undefined;
|
|
142
|
+
const marker = this.#marker;
|
|
143
|
+
if (!permitted || this.#stopped || !this.#plan || !marker || event.customInstructions !== marker) return { cancel: true };
|
|
144
|
+
return stateFlowCompactionResult(this.#plan, marker, event);
|
|
145
|
+
}
|
|
146
|
+
}
|
package/lib/context.ts
CHANGED
|
@@ -4,6 +4,7 @@ import { projectArtifactForModel, type ArtifactInvalidationNotice, type Artifact
|
|
|
4
4
|
import type { RecentTransitionWindow } from "./history.ts";
|
|
5
5
|
import { applyPatch, isObject, presentationJson, sameJson, type JsonObject, type JsonValue } from "./json.ts";
|
|
6
6
|
import type { Snapshot } from "./snapshot.ts";
|
|
7
|
+
import { formatOwnedPath, type OwnedPath } from "./ownership.ts";
|
|
7
8
|
import type { RehydrationPhase } from "./rehydration.ts";
|
|
8
9
|
import { projectSemanticPatch, projectStateForModel, type AtomicScopePatches, type SemanticState, type StateScope } from "./state.ts";
|
|
9
10
|
|
|
@@ -138,7 +139,8 @@ export class ContextProjection {
|
|
|
138
139
|
}
|
|
139
140
|
|
|
140
141
|
/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
|
|
141
|
-
acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints
|
|
142
|
+
acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints,
|
|
143
|
+
cascades: Partial<Record<StateScope, readonly OwnedPath[]>> = {}) {
|
|
142
144
|
const state = projectStateForModel(after, hints);
|
|
143
145
|
const navigation = lazyNavigationHint(after);
|
|
144
146
|
const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
|
|
@@ -228,7 +230,12 @@ export class ContextProjection {
|
|
|
228
230
|
if (predictable && seen.size > 0 && sameJson(Object.fromEntries(expected), navigation.keys)) delete updates.lazy_navigation;
|
|
229
231
|
}
|
|
230
232
|
if (this.view) this.view = { ...this.view, state, lazy_navigation: navigation };
|
|
231
|
-
|
|
233
|
+
// Owner paths remain informative even when effective state/navigation is masked
|
|
234
|
+
// or the model could predict every direct write. Never expose target values.
|
|
235
|
+
const cascaded = (["global", "cwd", "session"] as const).flatMap((scope) =>
|
|
236
|
+
(cascades[scope] ?? []).map((path) => formatOwnedPath(scope, path)));
|
|
237
|
+
return updates.effective.length || updates.lazy_navigation || cascaded.length
|
|
238
|
+
? { projection: this.identity, ...updates, ...(cascaded.length ? { cascaded } : {}) } : undefined;
|
|
232
239
|
}
|
|
233
240
|
|
|
234
241
|
project(messages: AgentMessage[], current: ContextView, makeHead: () => AgentMessage, initial?: ContextView): AgentMessage[] {
|