@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/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-only compatibility for session config and native checkpoints written before `mode`:
30
- * `enabled:true` stays active; `enabled:false` stays the caller's inactive policy.
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 decodeLegacyMode(value: JsonObject, inactiveMode: InactiveMode): StateFlowMode | undefined {
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 ? decodeLegacyMode(settings, "passive") : undefined;
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 = decodeLegacyMode(value, inactiveMode);
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
- /** Compact option values followed directly by read-only scope actions. */
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 ? "🟢 " : ""}${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
- "Choose how this session uses State Flow memory and context. Switching modes never erases stored memory.",
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
- STATE_FLOW_SECTION_HELP,
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.22.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.87.0",
70
- "@earendil-works/pi-ai": ">=0.87.0",
71
- "@earendil-works/pi-coding-agent": ">=0.87.0",
72
- "@earendil-works/pi-tui": ">=0.87.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.87.0",
76
- "@earendil-works/pi-ai": "0.87.0",
77
- "@earendil-works/pi-coding-agent": "0.87.0",
78
- "@earendil-works/pi-tui": "0.87.0",
79
- "@types/node": "latest",
80
- "typescript": "latest"
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 Passive for new sessions and never overrides retained choices. Do not change mode without operator authorization.
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