@llblab/pi-state-flow 0.26.2 → 0.26.3
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/CHANGELOG.md +4 -0
- package/README.md +2 -2
- package/dist/lib/context.d.ts +2 -2
- package/dist/lib/context.js +15 -7
- package/dist/lib/extension.js +5 -2
- package/dist/package.json +1 -1
- package/docs/architecture.md +2 -2
- package/docs/usage.md +2 -1
- package/lib/context.ts +15 -7
- package/lib/extension.ts +4 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
> Each release keeps at most 8 outcome records of at most 512 characters.
|
|
4
4
|
|
|
5
|
+
## 0.26.3: Passive Response Isolation
|
|
6
|
+
|
|
7
|
+
- `Passive context`: Automatic Passive memory heads, Stop handoffs and state-update receipts omit the `response` plane, including after reload and mode changes. Active still sees the previous accepted answer. Canonical response storage, explicit reads and native/user/tool history are unchanged; no migration or configuration change is required.
|
|
8
|
+
|
|
5
9
|
## 0.26.2: Automatic Response Guidance
|
|
6
10
|
|
|
7
11
|
- `Response ownership`: Active/bootstrap and Passive prompts explicitly forbid patching `response`; the `patch_state` guidelines forbid it in Global, CWD and Session, including clearing/deleting it, and explain that Active mode captures the final answer automatically. Runtime validation and answer capture are unchanged. No migration or configuration change is required.
|
package/README.md
CHANGED
|
@@ -81,7 +81,7 @@ New sessions default to **Off**. Choose Passive for ordinary conversation with m
|
|
|
81
81
|
### Active, passive, off
|
|
82
82
|
|
|
83
83
|
- `Active`: Memory tools are available, and the agent consolidates necessary final state changes before completing an iteration. Later iterations use accepted state and new input rather than completed prior reasoning.
|
|
84
|
-
- `Passive`: Both memory tools are available, and existing state is projected once a validated memory view is available. The agent patches on demand, and ordinary conversation context continues without State Flow's active iteration reset.
|
|
84
|
+
- `Passive`: Both memory tools are available, and existing state except `response` is projected once a validated memory view is available. The agent patches on demand, and ordinary conversation context continues without State Flow's active iteration reset.
|
|
85
85
|
- `Off`: The model sees neither memory tool nor any State Flow context, including a frozen passive handoff.
|
|
86
86
|
- Startup, reload and tree attachment do not read or restore memory.
|
|
87
87
|
- Selecting Off cancels pending memory waits and records only native policy/bookmarks.
|
|
@@ -115,7 +115,7 @@ Runtime views provide these documented planes:
|
|
|
115
115
|
- `contract`: Requirements, decisions, rejected approaches, constraints and interface commitments.
|
|
116
116
|
- `working`: Temporary context of those actions: observations, results and uncertainties.
|
|
117
117
|
- `artifacts`: Source-addressed descriptions and compiled knowledge.
|
|
118
|
-
- `response`: The exact latest accepted answer, including an empty string. The runtime captures it only in Session; Global/CWD receive no newly accepted answers, and stored scopes may omit it entirely. Effective uses the highest-priority nonempty value.
|
|
118
|
+
- `response`: The exact latest accepted answer, including an empty string. The runtime captures it only in Session; Global/CWD receive no newly accepted answers, and stored scopes may omit it entirely. Effective uses the highest-priority nonempty value. Active automatically projects it; Passive omits it from automatic context while keeping storage and explicit reads intact.
|
|
119
119
|
- `lazy`: Supporting memory available through explicit reads; its body is omitted from baseline model context.
|
|
120
120
|
|
|
121
121
|
Every plane is optional on disk:
|
package/dist/lib/context.d.ts
CHANGED
|
@@ -39,7 +39,7 @@ export interface ContextView {
|
|
|
39
39
|
phase: RehydrationPhase;
|
|
40
40
|
} | null;
|
|
41
41
|
}
|
|
42
|
-
export declare function contextView(state: SemanticState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView;
|
|
42
|
+
export declare function contextView(state: SemanticState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase, includeResponse?: boolean): ContextView;
|
|
43
43
|
/** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
|
|
44
44
|
export declare class ContextProjection {
|
|
45
45
|
private identity;
|
|
@@ -49,7 +49,7 @@ export declare class ContextProjection {
|
|
|
49
49
|
private notices;
|
|
50
50
|
reset(): void;
|
|
51
51
|
/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
|
|
52
|
-
acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints, cascades?: Partial<Record<StateScope, readonly OwnedPath[]
|
|
52
|
+
acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints, cascades?: Partial<Record<StateScope, readonly OwnedPath[]>>, includeResponse?: boolean): {
|
|
53
53
|
effective: ModelStateUpdate[];
|
|
54
54
|
lazy_navigation?: {
|
|
55
55
|
available: boolean;
|
package/dist/lib/context.js
CHANGED
|
@@ -129,8 +129,14 @@ function projectedStateUpdates(previous, current, patches, beforeNavigation, nav
|
|
|
129
129
|
}
|
|
130
130
|
return { effective, ...(navigation !== undefined && (beforeNavigation === undefined || !sameJson(beforeNavigation, navigation)) ? { lazy_navigation: navigation } : {}) };
|
|
131
131
|
}
|
|
132
|
-
|
|
133
|
-
|
|
132
|
+
function projectContextState(state, hints, includeResponse) {
|
|
133
|
+
const projected = projectStateForModel(state, hints);
|
|
134
|
+
if (!includeResponse)
|
|
135
|
+
delete projected.response;
|
|
136
|
+
return projected;
|
|
137
|
+
}
|
|
138
|
+
export function contextView(state, hints, invalidations, phase, includeResponse = true) {
|
|
139
|
+
return { state: projectContextState(state, hints, includeResponse), lazy_navigation: lazyNavigationHint(state),
|
|
134
140
|
artifact_invalidations: structuredClone(invalidations), knowledge_rehydration: phase === undefined ? null : { phase } };
|
|
135
141
|
}
|
|
136
142
|
/** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
|
|
@@ -148,11 +154,11 @@ export class ContextProjection {
|
|
|
148
154
|
this.notices = [];
|
|
149
155
|
}
|
|
150
156
|
/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
|
|
151
|
-
acceptPatch(before, after, patches, hints, cascades = {}) {
|
|
152
|
-
const state =
|
|
157
|
+
acceptPatch(before, after, patches, hints, cascades = {}, includeResponse = true) {
|
|
158
|
+
const state = projectContextState(after, hints, includeResponse);
|
|
153
159
|
const navigation = lazyNavigationHint(after);
|
|
154
160
|
const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
|
|
155
|
-
const updates = projectedStateUpdates(this.view?.state ??
|
|
161
|
+
const updates = projectedStateUpdates(this.view?.state ?? projectContextState(before, hints, includeResponse), state, patches, beforeNavigation, navigation);
|
|
156
162
|
// Suppress direct writes only when the accepted effective value matches.
|
|
157
163
|
// Overlap stays conservative except for explicit top-scope replacements:
|
|
158
164
|
// Session scalars/arrays mask every lower-scope value at that path.
|
|
@@ -319,12 +325,14 @@ function messageText(message) {
|
|
|
319
325
|
return contentText(message.content);
|
|
320
326
|
}
|
|
321
327
|
export function createPassiveContinuation(state, startedAt = Date.now(), activeRunStartedAt, preserveContext = false) {
|
|
328
|
+
const visibleState = structuredClone(state);
|
|
329
|
+
delete visibleState.response;
|
|
322
330
|
return {
|
|
323
331
|
startedAt,
|
|
324
|
-
state:
|
|
332
|
+
state: visibleState,
|
|
325
333
|
...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
|
|
326
334
|
...(preserveContext ? { preserveContext: true } : {}),
|
|
327
|
-
handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
|
|
335
|
+
handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state: visibleState, continuation: preserveContext
|
|
328
336
|
? "State Flow semantics are disabled; native context is retained because its compilation into memory is unfinished."
|
|
329
337
|
: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
|
|
330
338
|
};
|
package/dist/lib/extension.js
CHANGED
|
@@ -812,7 +812,7 @@ export default function stateFlowExtension(pi, options = {}) {
|
|
|
812
812
|
}
|
|
813
813
|
clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
|
|
814
814
|
updateUi(ctx);
|
|
815
|
-
const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, acquisition.hints, stage.cascades);
|
|
815
|
+
const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, acquisition.hints, stage.cascades, isActive());
|
|
816
816
|
const acknowledgement = changed
|
|
817
817
|
? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
|
|
818
818
|
: "\nState already current.";
|
|
@@ -1012,6 +1012,9 @@ export default function stateFlowExtension(pi, options = {}) {
|
|
|
1012
1012
|
}
|
|
1013
1013
|
/** Local policy, tools and UI change before any canonical wait. */
|
|
1014
1014
|
function applyInactiveMode(ctx, mode) {
|
|
1015
|
+
// Visibility changes before optional recovery waits; a frozen Active head must not survive Passive.
|
|
1016
|
+
if (snapshot.config.mode !== mode)
|
|
1017
|
+
contextProjection.reset();
|
|
1015
1018
|
snapshot = deactivateEpisode(snapshot, mode);
|
|
1016
1019
|
clearRunTransient();
|
|
1017
1020
|
syncStateFlowTools();
|
|
@@ -1345,7 +1348,7 @@ export default function stateFlowExtension(pi, options = {}) {
|
|
|
1345
1348
|
const effective = effectiveState;
|
|
1346
1349
|
const invalidations = acquisition.invalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
|
|
1347
1350
|
const phase = isActive() ? rehydrationPhase : undefined;
|
|
1348
|
-
const view = contextView(effective, acquisition.hints, invalidations, phase);
|
|
1351
|
+
const view = contextView(effective, acquisition.hints, invalidations, phase, isActive());
|
|
1349
1352
|
if (passiveContinuation) {
|
|
1350
1353
|
const retained = passiveContinuationMessages(messages, passiveContinuation);
|
|
1351
1354
|
if (!runtime?.view)
|
package/dist/package.json
CHANGED
package/docs/architecture.md
CHANGED
|
@@ -42,7 +42,7 @@ Runtime views select these documented semantic planes when present. Stored scope
|
|
|
42
42
|
- `contract` retains durable requirements, decisions, interfaces and rejected approaches.
|
|
43
43
|
- `working` is the temporary working context of those actions: verified current facts, results and uncertainties.
|
|
44
44
|
- `artifacts` maps exact source paths to compiled routing metadata.
|
|
45
|
-
- `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global/CWD do not receive newly accepted answers, and stored scopes may omit response entirely. An explicit nonempty Session answer overrides inherited values; an empty or absent response contributes nothing to projection.
|
|
45
|
+
- `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global/CWD do not receive newly accepted answers, and stored scopes may omit response entirely. An explicit nonempty Session answer overrides inherited values; an empty or absent response contributes nothing to Active projection. Automatic Passive context omits the response plane, including frozen Stop handoffs and state-update receipts. Canonical storage, explicit reads and native answer text are unchanged.
|
|
46
46
|
- `lazy` is an optional stored object root for ordinary JSON detail. It defaults to `{}` only in internal compatibility views, is omitted from baseline model state and is read explicitly.
|
|
47
47
|
- Automatic recent-transition projection also removes each whole `patch.lazy`, including deletions. Empty scoped patches and transitions disappear, and an empty projected window is omitted.
|
|
48
48
|
- Visible hot patches keep their original identities, order and positions. Canonical history and explicit current/historical reads are unchanged.
|
|
@@ -61,7 +61,7 @@ Later scopes win. A scope-local `null` deletion removes only that scope's key an
|
|
|
61
61
|
- Checkpoint/tail codecs select only known top-level fields on read and write; unknown fields are neither kept in runtime streams nor carried into later writes. Nested data within known planes stays intact.
|
|
62
62
|
- Retained record identities and positions survive even when filtering leaves an empty patch.
|
|
63
63
|
- `readTemporalView` selects present known fields at the requested boundary, then overlays scopes without inventing fields.
|
|
64
|
-
- Empty and absent responses mean the same for projection; clearing a nonempty response projects as a deletion.
|
|
64
|
+
- Empty and absent responses mean the same for Active projection; clearing a nonempty response projects as a deletion. Passive omits the plane regardless of its value.
|
|
65
65
|
- Explicit reads of absent documented top-level fields return `null`.
|
|
66
66
|
- `readTemporalState` and the embedding callback keep default-bearing compatibility views for internal registry consumers. Those defaults never become stored overrides or model context.
|
|
67
67
|
- Passive reads and Start do not fill checkpoint fields or create revisions for normalization; missing shared pairs initialize as empty objects.
|
package/docs/usage.md
CHANGED
|
@@ -13,7 +13,8 @@ State Flow has three distinct model-facing states. **Active versus passive chang
|
|
|
13
13
|
- The final meaningful semantic patch preserves the decisions, outcomes and continuation needed once the completed conversation leaves model projection.
|
|
14
14
|
- The next iteration starts from accepted state and its new input, not from the previous iteration's completed reasoning.
|
|
15
15
|
- The native trace stays inspectable: a clean model context does not mean deleting Pi history.
|
|
16
|
-
- **Passive:** Both memory tools are available, existing state is projected into context, and the agent may read or patch
|
|
16
|
+
- **Passive:** Both memory tools are available, existing state except the `response` plane is projected into context, and the agent may read or patch memory as useful.
|
|
17
|
+
- The last Active answer is not repeated in automatic memory context, Stop handoffs or state updates. Its stored value and explicit `read_state` access remain intact; native/user/tool history is not redacted.
|
|
17
18
|
- Ordinary conversation continuity remains: there is no active iteration-ending context reset and no mandatory consolidation pressure.
|
|
18
19
|
- Accepted patches still reach the same canonical store, with the same validation and ownership guarantees.
|
|
19
20
|
- **Off:** Neither memory tool is exposed to the model, and State Flow injects no protocol, bootstrap/state context or frozen passive handoff. Stored memory and the native conversation trace are not deleted.
|
package/lib/context.ts
CHANGED
|
@@ -121,8 +121,14 @@ export interface ContextView {
|
|
|
121
121
|
knowledge_rehydration: { phase: RehydrationPhase } | null;
|
|
122
122
|
}
|
|
123
123
|
|
|
124
|
-
|
|
125
|
-
|
|
124
|
+
function projectContextState(state: SemanticState, hints: ArtifactModelHints, includeResponse: boolean): SemanticState {
|
|
125
|
+
const projected = projectStateForModel(state, hints);
|
|
126
|
+
if (!includeResponse) delete projected.response;
|
|
127
|
+
return projected;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export function contextView(state: SemanticState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase, includeResponse = true): ContextView {
|
|
131
|
+
return { state: projectContextState(state, hints, includeResponse), lazy_navigation: lazyNavigationHint(state),
|
|
126
132
|
artifact_invalidations: structuredClone(invalidations), knowledge_rehydration: phase === undefined ? null : { phase } };
|
|
127
133
|
}
|
|
128
134
|
|
|
@@ -144,11 +150,11 @@ export class ContextProjection {
|
|
|
144
150
|
|
|
145
151
|
/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
|
|
146
152
|
acceptPatch(before: SemanticState, after: SemanticState, patches: AtomicScopePatches, hints: ArtifactModelHints,
|
|
147
|
-
cascades: Partial<Record<StateScope, readonly OwnedPath[]>> = {}) {
|
|
148
|
-
const state =
|
|
153
|
+
cascades: Partial<Record<StateScope, readonly OwnedPath[]>> = {}, includeResponse = true) {
|
|
154
|
+
const state = projectContextState(after, hints, includeResponse);
|
|
149
155
|
const navigation = lazyNavigationHint(after);
|
|
150
156
|
const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
|
|
151
|
-
const updates = projectedStateUpdates(this.view?.state ??
|
|
157
|
+
const updates = projectedStateUpdates(this.view?.state ?? projectContextState(before, hints, includeResponse), state, patches,
|
|
152
158
|
beforeNavigation, navigation);
|
|
153
159
|
// Suppress direct writes only when the accepted effective value matches.
|
|
154
160
|
// Overlap stays conservative except for explicit top-scope replacements:
|
|
@@ -303,12 +309,14 @@ function messageText(message: AgentMessage): string {
|
|
|
303
309
|
}
|
|
304
310
|
|
|
305
311
|
export function createPassiveContinuation(state: SemanticState, startedAt = Date.now(), activeRunStartedAt?: number, preserveContext = false): PassiveContinuation {
|
|
312
|
+
const visibleState = structuredClone(state);
|
|
313
|
+
delete visibleState.response;
|
|
306
314
|
return {
|
|
307
315
|
startedAt,
|
|
308
|
-
state:
|
|
316
|
+
state: visibleState,
|
|
309
317
|
...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
|
|
310
318
|
...(preserveContext ? { preserveContext: true as const } : {}),
|
|
311
|
-
handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
|
|
319
|
+
handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state: visibleState, continuation: preserveContext
|
|
312
320
|
? "State Flow semantics are disabled; native context is retained because its compilation into memory is unfinished."
|
|
313
321
|
: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
|
|
314
322
|
};
|
package/lib/extension.ts
CHANGED
|
@@ -821,7 +821,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
821
821
|
}
|
|
822
822
|
clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
|
|
823
823
|
updateUi(ctx);
|
|
824
|
-
const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, acquisition.hints, stage.cascades);
|
|
824
|
+
const updates = contextProjection.acceptPatch(previousEffective, effectiveState, patches, acquisition.hints, stage.cascades, isActive());
|
|
825
825
|
const acknowledgement = changed
|
|
826
826
|
? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
|
|
827
827
|
: "\nState already current.";
|
|
@@ -1007,6 +1007,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1007
1007
|
|
|
1008
1008
|
/** Local policy, tools and UI change before any canonical wait. */
|
|
1009
1009
|
function applyInactiveMode(ctx: ExtensionContext, mode: InactiveMode): void {
|
|
1010
|
+
// Visibility changes before optional recovery waits; a frozen Active head must not survive Passive.
|
|
1011
|
+
if (snapshot.config.mode !== mode) contextProjection.reset();
|
|
1010
1012
|
snapshot = deactivateEpisode(snapshot, mode);
|
|
1011
1013
|
clearRunTransient();
|
|
1012
1014
|
syncStateFlowTools();
|
|
@@ -1325,7 +1327,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1325
1327
|
const effective = effectiveState;
|
|
1326
1328
|
const invalidations = acquisition.invalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
|
|
1327
1329
|
const phase = isActive() ? rehydrationPhase : undefined;
|
|
1328
|
-
const view = contextView(effective, acquisition.hints, invalidations, phase);
|
|
1330
|
+
const view = contextView(effective, acquisition.hints, invalidations, phase, isActive());
|
|
1329
1331
|
if (passiveContinuation) {
|
|
1330
1332
|
const retained = passiveContinuationMessages(messages, passiveContinuation);
|
|
1331
1333
|
if (!runtime?.view) return { messages: retained };
|