@llblab/pi-state-flow 0.22.0 → 0.24.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 +43 -56
- package/BACKLOG.md +14 -5
- package/CHANGELOG.md +17 -1
- package/LICENSE +21 -0
- package/README.md +8 -10
- package/dist/lib/compaction.d.ts +1 -1
- package/dist/lib/compaction.js +1 -1
- package/dist/lib/config.js +5 -4
- package/dist/lib/extension.js +244 -54
- package/dist/lib/git.d.ts +2 -2
- package/dist/lib/git.js +16 -5
- package/dist/lib/logging.d.ts +4 -1
- package/dist/lib/logging.js +1 -0
- package/dist/lib/session.d.ts +10 -1
- package/dist/lib/session.js +60 -1
- package/dist/lib/snapshot.d.ts +6 -0
- package/dist/lib/snapshot.js +8 -5
- package/dist/lib/telegram.d.ts +1 -1
- package/dist/lib/telegram.js +15 -10
- package/dist/package.json +12 -11
- package/dist/skills/state-flow-guide/SKILL.md +1 -1
- package/docs/README.md +1 -0
- package/docs/agent-contract-relocation.md +72 -0
- package/docs/architecture.md +30 -24
- package/docs/compatibility.md +4 -4
- package/docs/fork-contract.md +4 -2
- package/docs/temporal-acceptance.md +2 -2
- package/docs/usage.md +24 -19
- package/lib/compaction.ts +2 -2
- package/lib/config.ts +5 -4
- package/lib/extension.ts +227 -54
- package/lib/git.ts +14 -5
- package/lib/logging.ts +5 -1
- package/lib/session.ts +52 -1
- package/lib/snapshot.ts +7 -5
- package/lib/telegram.ts +15 -11
- package/package.json +12 -11
- package/skills/state-flow-guide/SKILL.md +1 -1
package/lib/session.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { parseRetainedPiCheckpoint, type InactiveMode } from "./snapshot.ts";
|
|
1
|
+
import { parseRetainedPiCheckpoint, readCheckpointMode, type InactiveMode, type StateFlowMode } from "./snapshot.ts";
|
|
2
2
|
|
|
3
3
|
export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
|
|
4
4
|
|
|
@@ -22,6 +22,8 @@ export interface PassiveStopBoundary {
|
|
|
22
22
|
persistenceError?: string;
|
|
23
23
|
/** The inactive mode selected by that failed change; legacy markers omit it. */
|
|
24
24
|
mode?: InactiveMode;
|
|
25
|
+
/** Native-only Off choice; canonical runtime mode is deliberately not updated. */
|
|
26
|
+
memoryDeferred?: true;
|
|
25
27
|
}
|
|
26
28
|
|
|
27
29
|
export interface SnapshotDiscovery {
|
|
@@ -44,6 +46,55 @@ export function discoverSnapshotData(branch: readonly BranchEntry[]): SnapshotDi
|
|
|
44
46
|
return { candidates, errors };
|
|
45
47
|
}
|
|
46
48
|
|
|
49
|
+
/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
|
|
50
|
+
export function findBranchPolicy(
|
|
51
|
+
branch: readonly BranchEntry[], sessionId: string | undefined, stopEntryType: string | undefined, inactiveMode: InactiveMode,
|
|
52
|
+
): { mode: StateFlowMode; persistenceError?: string } | undefined {
|
|
53
|
+
let stopReset = false;
|
|
54
|
+
for (let index = branch.length - 1; index >= 0; index--) {
|
|
55
|
+
try {
|
|
56
|
+
const entry = branch[index];
|
|
57
|
+
if (entry?.type !== "custom") continue;
|
|
58
|
+
if (entry.customType === SNAPSHOT_ENTRY_TYPE) {
|
|
59
|
+
const mode = readCheckpointMode(entry.data, inactiveMode);
|
|
60
|
+
if (mode !== undefined) return { mode };
|
|
61
|
+
const data = entry.data as { disabled?: unknown; mode?: unknown; enabled?: unknown } | undefined;
|
|
62
|
+
if (data?.disabled === true && !Object.hasOwn(data, "mode") && !Object.hasOwn(data, "enabled")) return { mode: inactiveMode };
|
|
63
|
+
} else if (stopEntryType !== undefined && entry.customType === stopEntryType) {
|
|
64
|
+
const data = entry.data as PassiveStopBoundary & { owner?: unknown; reset?: unknown } | undefined;
|
|
65
|
+
if (!data || stopReset || (sessionId === undefined ? typeof data.owner !== "string" || !data.owner.trim() : data.owner !== sessionId)) continue;
|
|
66
|
+
if (data.reset === true) { stopReset = true; continue; }
|
|
67
|
+
if (Number.isSafeInteger(data.at) && data.at >= 0 && data.memoryDeferred === true && data.mode === "off") {
|
|
68
|
+
return { mode: "off", ...(typeof data.persistenceError === "string" && data.persistenceError.trim() ? { persistenceError: data.persistenceError } : {}) };
|
|
69
|
+
}
|
|
70
|
+
if (Number.isSafeInteger(data.at) && data.at >= 0 && typeof data.persistenceError === "string" && data.persistenceError.trim()) {
|
|
71
|
+
return { mode: data.mode === "off" || data.mode === "passive" ? data.mode : inactiveMode, persistenceError: data.persistenceError };
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
} catch {
|
|
75
|
+
// Malformed native policy cannot prevent another explicit retained choice from being read.
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
return undefined;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Native policy bookkeeping retains an unacquired fork across extension reloads. */
|
|
82
|
+
export function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean {
|
|
83
|
+
for (let index = branch.length - 1; index >= 0; index--) {
|
|
84
|
+
try {
|
|
85
|
+
const entry = branch[index];
|
|
86
|
+
if (entry?.type !== "custom" || entry.customType !== entryType) continue;
|
|
87
|
+
const data = entry.data as { owner?: unknown; reset?: unknown; forkPending?: unknown } | undefined;
|
|
88
|
+
if (data?.owner !== sessionId) continue;
|
|
89
|
+
if (data.reset === true) return false;
|
|
90
|
+
if (data.forkPending === true) return true;
|
|
91
|
+
} catch {
|
|
92
|
+
// Unrelated native entries grant no fork authority.
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return false;
|
|
96
|
+
}
|
|
97
|
+
|
|
47
98
|
export function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[] {
|
|
48
99
|
return discoverSnapshotData(branch).candidates;
|
|
49
100
|
}
|
package/lib/snapshot.ts
CHANGED
|
@@ -26,10 +26,12 @@ export interface SnapshotConfig {
|
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
/**
|
|
29
|
-
* Read
|
|
30
|
-
*
|
|
29
|
+
* Read only mode policy, without validating or accessing semantic checkpoint metadata.
|
|
30
|
+
* Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
|
|
31
|
+
* Legacy `enabled:false` follows the caller's inactive policy.
|
|
31
32
|
*/
|
|
32
|
-
function
|
|
33
|
+
export function readCheckpointMode(value: unknown, inactiveMode: InactiveMode = "passive"): StateFlowMode | undefined {
|
|
34
|
+
if (!isObject(value)) return undefined;
|
|
33
35
|
if (Object.hasOwn(value, "mode")) return Object.hasOwn(value, "enabled") || !isStateFlowMode(value.mode) ? undefined : value.mode;
|
|
34
36
|
return typeof value.enabled === "boolean" ? value.enabled ? "active" : inactiveMode : undefined;
|
|
35
37
|
}
|
|
@@ -134,7 +136,7 @@ export function parseSessionRuntime(
|
|
|
134
136
|
let runtime: unknown;
|
|
135
137
|
try {
|
|
136
138
|
const settings: unknown = JSON.parse(config);
|
|
137
|
-
const mode = isObject(settings) && Object.keys(settings).length === 1 ?
|
|
139
|
+
const mode = isObject(settings) && Object.keys(settings).length === 1 ? readCheckpointMode(settings, "passive") : undefined;
|
|
138
140
|
if (mode === undefined) throw new Error("Invalid State Flow runtime configuration or counters");
|
|
139
141
|
runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
|
|
140
142
|
} catch (error) {
|
|
@@ -230,7 +232,7 @@ export function parseRetainedPiCheckpoint(value: unknown, inactiveMode: Inactive
|
|
|
230
232
|
if (keys.length === 1 && value.disabled === true) return { mode: inactiveMode };
|
|
231
233
|
if (keys.length === 1 && (value.mode === "passive" || value.mode === "off")) return { mode: value.mode };
|
|
232
234
|
const allowed = new Set(["boundary", "mode", "enabled", "step", "bootstrap", "specification"]);
|
|
233
|
-
const mode =
|
|
235
|
+
const mode = readCheckpointMode(value, inactiveMode);
|
|
234
236
|
if (keys.some((key) => !allowed.has(key))
|
|
235
237
|
|| typeof value.boundary !== "string" || value.boundary.trim().length === 0
|
|
236
238
|
|| mode === undefined
|
package/lib/telegram.ts
CHANGED
|
@@ -135,14 +135,9 @@ export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot)
|
|
|
135
135
|
return `🌀 State Flow: ${snapshot.mode}`;
|
|
136
136
|
}
|
|
137
137
|
|
|
138
|
-
/** Match pi-telegram's settings-card value descriptions. */
|
|
139
|
-
const STATE_FLOW_SECTION_HELP = [
|
|
140
|
-
"<code>-</code> <code>off</code>: no memory tools or state bootstrap.",
|
|
141
|
-
"<code>-</code> <code>passive</code> (default): memory tools and context with ordinary conversation.",
|
|
142
|
-
"<code>-</code> <code>active</code>: state-driven episodes.",
|
|
143
|
-
].join("\n");
|
|
144
|
-
|
|
145
138
|
export const STATE_FLOW_MODES = ["off", "passive", "active"] as const satisfies readonly StateFlowMode[];
|
|
139
|
+
const STATE_FLOW_MODE_LABELS: Record<StateFlowMode, string> = { off: "Off", passive: "Passive", active: "Active" };
|
|
140
|
+
const STATE_FLOW_SELECTED_MARKERS: Record<StateFlowMode, string> = { off: "🟡", passive: "🟣", active: "🟢" };
|
|
146
141
|
|
|
147
142
|
function isStateFlowModeAction(value: string): value is StateFlowMode {
|
|
148
143
|
return (STATE_FLOW_MODES as readonly string[]).includes(value);
|
|
@@ -153,22 +148,31 @@ function modeReceiptNotice(mode: StateFlowMode, result: StateFlowTelegramControl
|
|
|
153
148
|
return result.message;
|
|
154
149
|
}
|
|
155
150
|
|
|
156
|
-
/**
|
|
151
|
+
/** One radio-style mode row followed directly by read-only scope actions. */
|
|
157
152
|
export function buildStateFlowSectionView(
|
|
158
153
|
snapshot: StateFlowTelegramSnapshot,
|
|
159
154
|
callbackData: (action: string, payload?: string) => string,
|
|
160
155
|
): StateFlowTelegramView {
|
|
161
156
|
const modes: StateFlowTelegramButton[] = STATE_FLOW_MODES.map((mode) => ({
|
|
162
|
-
text: `${mode === snapshot.mode ?
|
|
157
|
+
text: `${mode === snapshot.mode ? STATE_FLOW_SELECTED_MARKERS[mode] : "⚫️"} ${STATE_FLOW_MODE_LABELS[mode]}`,
|
|
163
158
|
callback_data: callbackData(mode),
|
|
164
159
|
}));
|
|
165
160
|
return {
|
|
166
161
|
text: [
|
|
167
162
|
`<b>🌀 State Flow:</b> <code>${snapshot.mode}</code>`,
|
|
168
163
|
"",
|
|
169
|
-
"
|
|
164
|
+
"<b>Mode</b> — choose a workflow (switching modes never erases stored memory):",
|
|
165
|
+
"",
|
|
166
|
+
"<code>-</code> <code>off</code> (default): regular chat without State Flow memory tools or context.",
|
|
167
|
+
"<code>-</code> <code>passive</code>: regular chat with memory tools; available combined memory enters the agent's context.",
|
|
168
|
+
"<code>-</code> <code>active</code>: same memory access; each completed answer closes a cycle, and the next request starts from saved state, not the full chat.",
|
|
169
|
+
"",
|
|
170
|
+
"<b>Inspect memory</b> — view stored state even in Off:",
|
|
170
171
|
"",
|
|
171
|
-
|
|
172
|
+
"<code>-</code> <code>global</code>: memory shared across projects and sessions.",
|
|
173
|
+
"<code>-</code> <code>cwd</code>: memory shared by sessions in this directory.",
|
|
174
|
+
"<code>-</code> <code>session</code>: private memory for this session, kept on resume.",
|
|
175
|
+
"<code>-</code> <code>effective</code>: merged Global, CWD and Session state; the agent can use it when memory is enabled and available.",
|
|
172
176
|
].join("\n"),
|
|
173
177
|
parseMode: "html",
|
|
174
178
|
replyMarkup: { inline_keyboard: [
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@llblab/pi-state-flow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.24.0",
|
|
4
|
+
"license": "MIT",
|
|
4
5
|
"private": false,
|
|
5
6
|
"description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
|
|
6
7
|
"keywords": [
|
|
@@ -66,17 +67,17 @@
|
|
|
66
67
|
"node": ">=22.19.0"
|
|
67
68
|
},
|
|
68
69
|
"peerDependencies": {
|
|
69
|
-
"@earendil-works/pi-agent-core": ">=0.
|
|
70
|
-
"@earendil-works/pi-ai": ">=0.
|
|
71
|
-
"@earendil-works/pi-coding-agent": ">=0.
|
|
72
|
-
"@earendil-works/pi-tui": ">=0.
|
|
70
|
+
"@earendil-works/pi-agent-core": ">=1.0.0",
|
|
71
|
+
"@earendil-works/pi-ai": ">=1.0.0",
|
|
72
|
+
"@earendil-works/pi-coding-agent": ">=1.0.0",
|
|
73
|
+
"@earendil-works/pi-tui": ">=1.0.0"
|
|
73
74
|
},
|
|
74
75
|
"devDependencies": {
|
|
75
|
-
"@earendil-works/pi-agent-core": "0.
|
|
76
|
-
"@earendil-works/pi-ai": "0.
|
|
77
|
-
"@earendil-works/pi-coding-agent": "0.
|
|
78
|
-
"@earendil-works/pi-tui": "0.
|
|
79
|
-
"@types/node": "
|
|
80
|
-
"typescript": "
|
|
76
|
+
"@earendil-works/pi-agent-core": "1.0.0",
|
|
77
|
+
"@earendil-works/pi-ai": "1.0.0",
|
|
78
|
+
"@earendil-works/pi-coding-agent": "1.0.0",
|
|
79
|
+
"@earendil-works/pi-tui": "1.0.0",
|
|
80
|
+
"@types/node": "^26.4.0",
|
|
81
|
+
"typescript": "^7.0.2"
|
|
81
82
|
}
|
|
82
83
|
}
|
|
@@ -15,7 +15,7 @@ State Flow's on-demand operational reference. Resolve the usage question or iden
|
|
|
15
15
|
|
|
16
16
|
Passive tools access memory without starting an episode. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
|
|
17
17
|
|
|
18
|
-
Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to
|
|
18
|
+
Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode without operator authorization.
|
|
19
19
|
|
|
20
20
|
## Map
|
|
21
21
|
|