@llblab/pi-state-flow 0.10.2 → 0.11.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/BACKLOG.md +0 -43
- package/CHANGELOG.md +4 -0
- package/README.md +1 -1
- package/lib/extension.ts +5 -0
- package/lib/telegram.ts +96 -3
- package/package.json +1 -1
package/BACKLOG.md
CHANGED
|
@@ -2,49 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
Completed release work belongs in [CHANGELOG.md](CHANGELOG.md).
|
|
4
4
|
|
|
5
|
-
## 0.10.2 hotfix: Native boundaries and patch robustness
|
|
6
|
-
|
|
7
|
-
- **Outcome:** Correct runtime friction without weakening State Flow's semantic or durability guarantees: early post-acceptance compaction uses public context-token readiness and retains one complete accepted iteration, while non-terminal `patch_state.final` input degrades to an ordinary scoped update instead of failing. Model-facing guidance remains canonical and teaches only omission or `final:true`; tolerant Boolean normalization is a runtime resilience layer, not another advertised protocol form.
|
|
8
|
-
- **Scope gate:** The hotfix stays extension-owned: retain State Flow-initiated early compaction through public Pi APIs, replace byte-based readiness with public context usage, and keep one complete latest iteration after successful shortening. Do not require or modify Pi itself.
|
|
9
|
-
- **Compaction failure class:** State Flow previously admitted compaction from `JSON.stringify(activeEntries) >= 80_000`, although serialized bytes do not prove that Pi's configured recent-token suffix leaves a removable prefix. It also retained only the latest accepted assistant response. The hotfix uses public context-token usage with a 24,000-token floor and retains the complete latest accepted user iteration; custom Pi retention settings may still decline safely and permit a later retry.
|
|
10
|
-
- **Patch failure class:** The public `patch_state` schema declares `final` as an optional Boolean, but execution rejects every supplied value except literal `true`. A model therefore produced a schema-valid `{ cwd: {...}, final: false }` non-terminal patch during a DEOS Grow Loop run and received `patch_state final must be exactly true when supplied`. The semantic patch was unambiguous and otherwise valid; rejecting it spent another tool turn and diagnostic record solely to enforce omission syntax.
|
|
11
|
-
- **Ownership contract:** Pi owns native preparation, configured compaction settings, one prepared branch snapshot, cut-point validity, persistence, lifecycle events, and transcript projection. State Flow owns post-acceptance compaction admission, durable revision/step details, foreign-context protection, generation/leaf fencing, and `patch_state` normalization. The advertised TypeBox schema and model context remain the smallest canonical language; runtime may accept a bounded unambiguous compatibility superset without teaching it to the model.
|
|
12
|
-
|
|
13
|
-
### Checkpoint A: Token-guided early compaction
|
|
14
|
-
|
|
15
|
-
- **Acceptance checkpoint:** After an eligible accepted run settles, State Flow initiates its own early native compaction only when public `getContextUsage()` reports enough context. A successful request retains the complete latest accepted user iteration and durable handoff; unknown or short usage remains untouched without invoking Pi.
|
|
16
|
-
- [x] **Replace byte readiness:** Removed `STATE_FLOW_COMPACTION_MIN_ACTIVE_BYTES` and the serialized-entry byte gate. The extension now requires at least 24,000 estimated context tokens—a modest margin above Pi's default 20,000-token retained suffix—while preserving enabled, accepted, non-bootstrap, idle, empty-queue, durable-base, generation, and resolution guards.
|
|
17
|
-
- [x] **Retain one complete iteration:** The custom compaction boundary now starts at the latest accepted user request, preserving its assistant/tool trajectory and final response instead of retaining only the answer.
|
|
18
|
-
- [x] **Keep foreign context safe:** Foreign context-bearing custom entries block shortening only when they precede the retained iteration; entries within the retained iteration remain visible.
|
|
19
|
-
- [x] **Keep benign refusal recoverable:** Unknown or sub-threshold usage skips compaction. A native refusal under custom Pi retention settings releases the attempt so later accepted work can retry without affecting state.
|
|
20
|
-
- [x] **Documentation and protocol:** Project protocol, architecture, usage guidance, changelog, and tests now describe token readiness and complete-iteration retention. User manual and native threshold/overflow compaction remain Pi-owned.
|
|
21
|
-
|
|
22
|
-
### Checkpoint B: Quiet non-terminal patch degradation
|
|
23
|
-
|
|
24
|
-
- **Acceptance checkpoint:** Model-facing contracts expose one canonical rule: omit `final` during ongoing work and set `final:true` only when the iteration may finish. Runtime treats explicit false as benign non-terminal intent and may normalize only unambiguous Boolean-like primitives before schema validation. No non-terminal value suppresses or reverses an existing eligibility latch, creates semantic work, changes transition identity or persistence behavior, or produces an invalid-patch diagnostic merely because no scope accompanied it.
|
|
25
|
-
- [x] **Normalize explicit false:** `final:false` now accompanies useful global/CWD/session patches without latching or clearing terminal eligibility; pre-latch and post-latch tests preserve atomic state semantics.
|
|
26
|
-
- [x] **Bound tolerant coercion:** `prepareArguments` normalizes only `true`, `false`, `1`, `0`, and case-insensitive trimmed `"true"`/`"false"`. Arrays, objects, null, unknown strings, empty strings, and other numbers remain invalid; raw JavaScript truthiness is not used.
|
|
27
|
-
- [x] **Keep false-only inert:** `{final:false}` and normalized false-like-only calls return an acknowledged non-terminal no-op without semantic transition, eligibility, response, publication, or diagnostic. Bare `{}`, empty supplied scopes, unknown fields, null semantic values, and material scope no-ops remain invalid.
|
|
28
|
-
- [x] **Keep model guidance canonical:** Tool descriptions, prompt snippets/guidelines, injected context, fallback prompts, `AGENTS.md`, the bundled memory Skill, and user-facing documentation teach only omission during ongoing work and `final:true` for terminal eligibility. Compatibility aliases remain implementation/test knowledge.
|
|
29
|
-
- [x] **Reconcile diagnostics:** Invalid-input tests now use genuinely malformed values. Unit and real-Pi regressions prove scoped false/false-like updates are accepted without an invalid-patch record and remain terminal-ineligible until a later `final:true`.
|
|
30
|
-
|
|
31
|
-
### Checkpoint C: Continuous state stewardship
|
|
32
|
-
|
|
33
|
-
- **Acceptance checkpoint:** State Flow makes memory care part of ordinary model responsibility without creating an automatic background agent, arbitrary maintenance counter, full-state rewrite ritual, or second mutation path. Every handoff curates newly affected state, while explicit project/feature/release phase changes trigger one bounded ownership and obsolescence pass before terminal completion.
|
|
34
|
-
- [x] **Strengthen the baseline contract:** The compact runtime protocol, `patch_state` prompt metadata, `AGENTS.md`, and bundled memory Skill now make narrowest-scope placement, touched-branch reconciliation, supersession, and obsolete-progress deletion ordinary responsibilities while keeping detailed migration procedure in the Skill.
|
|
35
|
-
- [x] **Define phase-boundary care:** Feature/release/campaign completion, project switches, and active-version changes now require one bounded reconciliation that removes transient prior-work state while retaining still-operative consequences.
|
|
36
|
-
- [x] **Make scope movement ordinary:** The runtime contract and Skill define global/CWD/session applicability, targeted scoped reads when effective ownership is unclear, and destination-write/readback/source-delete/readback migration ordering.
|
|
37
|
-
- [x] **Bound routine cost:** Ordinary turns curate only touched and obviously stale or mis-scoped visible branches. Full reconciliation is event-driven, with no background loop, arbitrary counter, size trigger, maintenance ledger, timestamp, or score.
|
|
38
|
-
- [x] **Align Skill activation:** `state-flow-memory` now covers explicit requests and runtime-required phase boundaries while remaining one bounded, materialized-first, evidence-aware cohort that cannot launch itself or authorize external promotion.
|
|
39
|
-
- [x] **Live behavior witness:** A clean temporary Pi 0.85.1 session with the release extension created scoped fixture memory, then a real model moved project-specific campaign state from global to CWD through destination-write/readback/source-delete/readback, removed completed session progress, retained the cross-project rule plus active commitment/uncertainty, and left unrelated state untouched. Durable scope tails verify the claimed movement and deletion.
|
|
40
|
-
|
|
41
|
-
### Checkpoint D: Integrated hotfix candidate
|
|
42
|
-
|
|
43
|
-
- **Acceptance checkpoint:** Token-guided early compaction, quiet non-terminal patch degradation, and continuous state stewardship form one coherent release candidate, and validation proves all three without reopening completed 0.10.1 work.
|
|
44
|
-
- [x] **Compatibility and versions:** The release preserves the existing public Pi API floor; `getContextUsage()` is present in the 0.84.4 public extension types, the complete suite passes on 0.85.1, and package/lockfile metadata agree on 0.10.2 without a new host capability dependency.
|
|
45
|
-
- [x] **Regression validation:** Focused compaction and real-Pi witnesses pass; `npm run validate` passes 446/446 on Pi 0.85.1, context validation reports zero errors, and the 46-file dry-run package includes the renamed protocol and compaction domains. Real-Pi lifecycle coverage proves retained complete-iteration history and skipped short usage; patch/logging tests prove useful `final:false`; the clean real-model witness proves bounded phase-boundary cleanup.
|
|
46
|
-
- [ ] **Release follow-through:** After the combined candidate is validated, release the State Flow hotfix through its guarded direct-main/tag automation and update the exact Pi Kit pin and synchronized lock/inventory surfaces.
|
|
47
|
-
|
|
48
5
|
## Candidate evolution
|
|
49
6
|
|
|
50
7
|
- [ ] **Read-only global bootstrap layer:** Project the existing global materialization into enabled and non-enabled sessions by default, so even one-shot work starts carrying established cross-project facts, preferences, routing, and conventions. The global scope is the highest-value, lowest-cost half of the memory, while writing carries the protocol and curation tax; making the read side unconditional gives continuity without enabling mutation.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.11.0: Telegram state inspection
|
|
8
|
+
|
|
9
|
+
- `Telegram inspection`: The State Flow submenu now offers `👁 Show state` with Global, CWD, Session, and Effective choices. Selecting one scope sends exactly that projected materialized slice as a standalone Telegram Native Rich Message whose semantic fields use collapsible `details` and JSON `pre` blocks; inspection is read-only and the optional adapter remains fail-open without a compatible pi-telegram membrane.
|
|
10
|
+
|
|
7
11
|
## 0.10.2: Token-guided compaction and patch resilience
|
|
8
12
|
|
|
9
13
|
- `Compaction readiness`: Early State Flow compaction now uses Pi's public context-token estimate with a 24,000-token floor instead of serialized-entry bytes, skipping unknown or short contexts without invoking native compaction. Successful shortening retains the complete latest accepted user iteration rather than only its final answer, while durable state and append-only session history remain intact.
|
package/README.md
CHANGED
|
@@ -53,7 +53,7 @@ Continue working normally. The agent receives the state protocol and uses `patch
|
|
|
53
53
|
|
|
54
54
|
State Flow is **opt-in**. Starting in an existing conversation keeps its active context for one migration run. To enable genuinely new sessions automatically, set `"autoStart": true` in the optional [configuration](docs/usage.md#configuration).
|
|
55
55
|
|
|
56
|
-
With `pi-telegram` installed, its main menu also exposes the same Start/Stop controls.
|
|
56
|
+
With a compatible `pi-telegram` installed, its main menu also exposes the same Start/Stop controls and a `👁 Show state` chooser for Global, CWD, Session, or Effective memory. Selecting one scope sends exactly that materialized slice as a standalone native Rich Message with collapsible semantic fields; inspection is read-only and does not create a State Flow transition.
|
|
57
57
|
|
|
58
58
|
## What carries forward
|
|
59
59
|
|
package/lib/extension.ts
CHANGED
|
@@ -1001,6 +1001,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1001
1001
|
bootstrap: snapshot.meta.bootstrap === true,
|
|
1002
1002
|
startPending: telegramStartPending,
|
|
1003
1003
|
}),
|
|
1004
|
+
state: (scope) => projectStateForModel(
|
|
1005
|
+
scope === "effective"
|
|
1006
|
+
? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
|
|
1007
|
+
: scopeStates[scope],
|
|
1008
|
+
),
|
|
1004
1009
|
canStartNow: () => activeContext === undefined || activeContext.isIdle(),
|
|
1005
1010
|
start: () => {
|
|
1006
1011
|
if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
|
package/lib/telegram.ts
CHANGED
|
@@ -16,6 +16,24 @@ export interface StateFlowTelegramSnapshot {
|
|
|
16
16
|
startPending: boolean;
|
|
17
17
|
}
|
|
18
18
|
|
|
19
|
+
export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
|
|
20
|
+
|
|
21
|
+
export interface StateFlowTelegramState {
|
|
22
|
+
artifacts: Record<string, unknown>;
|
|
23
|
+
contract: Record<string, unknown>;
|
|
24
|
+
working: Record<string, unknown>;
|
|
25
|
+
response: string;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export type StateFlowTelegramRichBlock =
|
|
29
|
+
| { type: "pre"; text: string; language?: string }
|
|
30
|
+
| { type: "details"; summary: string | { type: "bold" | "code"; text: string }; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
|
|
31
|
+
|
|
32
|
+
export interface StateFlowTelegramRichMessage {
|
|
33
|
+
blocks: StateFlowTelegramRichBlock[];
|
|
34
|
+
skip_entity_detection?: boolean;
|
|
35
|
+
}
|
|
36
|
+
|
|
19
37
|
export interface StateFlowTelegramButton {
|
|
20
38
|
text: string;
|
|
21
39
|
callback_data: string;
|
|
@@ -30,6 +48,7 @@ export interface StateFlowTelegramView {
|
|
|
30
48
|
export interface StateFlowTelegramSectionContext {
|
|
31
49
|
callbackData(action: string, payload?: string): string;
|
|
32
50
|
edit(view: StateFlowTelegramView): Promise<void>;
|
|
51
|
+
openRich(message: StateFlowTelegramRichMessage): Promise<void>;
|
|
33
52
|
answerCallback(text?: string): Promise<void>;
|
|
34
53
|
}
|
|
35
54
|
|
|
@@ -61,6 +80,7 @@ export interface StateFlowTelegramControlResult {
|
|
|
61
80
|
|
|
62
81
|
export interface StateFlowTelegramPort {
|
|
63
82
|
snapshot(): StateFlowTelegramSnapshot;
|
|
83
|
+
state(scope: StateFlowTelegramScope): StateFlowTelegramState;
|
|
64
84
|
canStartNow(): boolean;
|
|
65
85
|
start(): StateFlowTelegramControlResult;
|
|
66
86
|
stop(): StateFlowTelegramControlResult;
|
|
@@ -103,10 +123,72 @@ export function buildStateFlowSectionView(
|
|
|
103
123
|
return {
|
|
104
124
|
text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
|
|
105
125
|
parseMode: "html",
|
|
106
|
-
replyMarkup: { inline_keyboard: [
|
|
126
|
+
replyMarkup: { inline_keyboard: [
|
|
127
|
+
[{ text: "👁 Show state", callback_data: callbackData("show-state") }],
|
|
128
|
+
[action],
|
|
129
|
+
] },
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
export function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView {
|
|
134
|
+
return {
|
|
135
|
+
text: "<b>👁 Show state:</b>",
|
|
136
|
+
parseMode: "html",
|
|
137
|
+
replyMarkup: { inline_keyboard: [
|
|
138
|
+
["global", "cwd"].map((scope) => ({ text: scope === "global" ? "Global" : "CWD", callback_data: callbackData("inspect", scope) })),
|
|
139
|
+
["session", "effective"].map((scope) => ({ text: scope === "session" ? "Session" : "Effective", callback_data: callbackData("inspect", scope) })),
|
|
140
|
+
] },
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
// The complete message serializes each preformatted field one additional time;
|
|
145
|
+
// 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
|
|
146
|
+
const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
|
|
147
|
+
|
|
148
|
+
function renderStateFlowTelegramField(value: unknown): string {
|
|
149
|
+
const json = JSON.stringify(value, null, 2);
|
|
150
|
+
if (json.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) return json;
|
|
151
|
+
let low = 0;
|
|
152
|
+
let high = json.length;
|
|
153
|
+
let rendered = "";
|
|
154
|
+
while (low <= high) {
|
|
155
|
+
const length = Math.floor((low + high) / 2);
|
|
156
|
+
const candidate = JSON.stringify({
|
|
157
|
+
truncated: true,
|
|
158
|
+
preview: json.slice(0, length),
|
|
159
|
+
omittedChars: json.length - length,
|
|
160
|
+
}, null, 2);
|
|
161
|
+
if (candidate.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
|
|
162
|
+
rendered = candidate;
|
|
163
|
+
low = length + 1;
|
|
164
|
+
} else {
|
|
165
|
+
high = length - 1;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
return rendered;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
export function renderStateFlowRichState(scope: StateFlowTelegramScope, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
|
|
172
|
+
const title = scope === "cwd" ? "CWD" : `${scope[0].toUpperCase()}${scope.slice(1)}`;
|
|
173
|
+
const fields = ["artifacts", "contract", "working", "response"] as const;
|
|
174
|
+
return {
|
|
175
|
+
blocks: [{
|
|
176
|
+
type: "details",
|
|
177
|
+
summary: { type: "bold", text: title },
|
|
178
|
+
blocks: fields.map((field) => ({
|
|
179
|
+
type: "details",
|
|
180
|
+
summary: { type: "code", text: field },
|
|
181
|
+
blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
|
|
182
|
+
})),
|
|
183
|
+
}],
|
|
184
|
+
skip_entity_detection: true,
|
|
107
185
|
};
|
|
108
186
|
}
|
|
109
187
|
|
|
188
|
+
function isStateFlowTelegramScope(value: string): value is StateFlowTelegramScope {
|
|
189
|
+
return value === "global" || value === "cwd" || value === "session" || value === "effective";
|
|
190
|
+
}
|
|
191
|
+
|
|
110
192
|
function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
|
|
111
193
|
return {
|
|
112
194
|
id: STATE_FLOW_TELEGRAM_ID,
|
|
@@ -115,10 +197,21 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
|
|
|
115
197
|
render: (ctx: StateFlowTelegramSectionContext) =>
|
|
116
198
|
buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
|
|
117
199
|
handleCallback: async (ctx: StateFlowTelegramCallbackContext) => {
|
|
118
|
-
// cancel/refresh remain routable for keyboards sent by earlier versions
|
|
119
|
-
if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh") return "pass" as const;
|
|
200
|
+
// cancel/refresh remain routable for keyboards sent by earlier versions.
|
|
201
|
+
if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect") return "pass" as const;
|
|
120
202
|
let notice: string | undefined;
|
|
121
203
|
try {
|
|
204
|
+
if (ctx.action === "show-state") {
|
|
205
|
+
await ctx.answerCallback();
|
|
206
|
+
await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
|
|
207
|
+
return "handled" as const;
|
|
208
|
+
}
|
|
209
|
+
if (ctx.action === "inspect") {
|
|
210
|
+
if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
|
|
211
|
+
await ctx.openRich(renderStateFlowRichState(ctx.payload, port.state(ctx.payload)));
|
|
212
|
+
await ctx.answerCallback();
|
|
213
|
+
return "handled" as const;
|
|
214
|
+
}
|
|
122
215
|
if (ctx.action === "start") {
|
|
123
216
|
if (port.canStartNow()) notice = port.start().message;
|
|
124
217
|
else {
|