@llblab/pi-kit 0.27.3 → 0.27.4

package/BACKLOG.md

@@ -1,9 +1,10 @@
 # Backlog
 
-The 0.27.3 composition is recorded in [CHANGELOG.md](./CHANGELOG.md). Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`.
+The 0.27.4 composition is recorded in [CHANGELOG.md](./CHANGELOG.md). Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`.
 
 ## Carried checks
 
+- **Installed 0.27.4 inspection smoke (operator-owned):** After separately authorized installation/reload, inspect a large nested State Flow field in disposable storage. Confirm readable JSON layout, separate truncation notices and intact genuine string escapes. Packed validation does not certify installed Telegram clients.
 - **Installed 0.27.3 single patch display smoke (operator-owned):** After separately authorized installation/reload, confirm one argument block followed by changed/no-op acknowledgements, compact configuration and visible rejected arguments/errors in disposable State Flow storage.
 - **Installed 0.27.2 cascade receipt smoke (operator-owned):** After separately authorized installation/reload, close an intent owning a nested lazy key in disposable State Flow storage and confirm the receipt lists its owner path under `cascaded`, without the body. Packed validation does not certify installed clients.
 - **Installed 0.27.1 Fast status smoke (operator-owned):** After separately authorized installation/reload, check Telegram menu Fast on/off and model switching for Codex and Claude Opus; unsupported Claude families must not show Fast. Use disposable settings and mocked quota where possible; do not mutate live stores or reconnect Telegram without separate authorization.

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.27.4: Readable State Flow Inspection
+
+- `Readable Inspection`: Advances the exact State Flow pin to published `0.25.3`. Large Telegram inspection fields now show pretty-printed JSON prefixes directly, with separate truncation notices instead of escaped `preview` strings. Genuine JSON string escapes and storage semantics are preserved. Other pins, resources and load order are unchanged.
+
 ## 0.27.3: State Flow Single Patch Display
 
 - `Single Patch Display`: Advances the exact State Flow pin to published `0.25.2`. Interactive patch rows show JSON arguments once, followed by the actual acceptance, no-op or error acknowledgement. Compact configuration still hides successful arguments. Other pins, resources, load order and storage semantics are unchanged.

package/README.md

@@ -17,7 +17,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.3.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.12.1` | Shared Codex quota/Business credit status and persistent priority Fast toggle, mirrored in Telegram |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.9.0` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.25.2` | Scoped context/memory compiler with intent-owned memory, cascade receipts, memory-inert Off, ownership status and single patch display |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.25.3` | Scoped context/memory compiler with intent-owned memory, cascade receipts, memory-inert Off, single patch display and readable Telegram inspection |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.6` | Telegram companion with connection resume, Workspace slot recovery, follower Threads, filterable Skills, files, voice, and controls |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
@@ -25,7 +25,7 @@ Versions are exact by design. An upstream release does not change an installed k
 
 ## Install
 
-Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.25.2/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
+Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.25.3/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
 
 From npm:
 
@@ -45,7 +45,7 @@ Prefer the kit instead of separately loading the same packages. If you already u
 
 ## Development
 
-The `0.27.3` composition includes published State Flow `0.25.2` with single patch display; all other pins, resources and load order remain unchanged. `npm run validate` checks exact installed pins, declared resources, dependency audit and bundled inventory. It does not certify installed-client rendering; carried checks remain in [Backlog](./BACKLOG.md).
+The `0.27.4` composition includes published State Flow `0.25.3` with readable Telegram inspection; all other pins, resources and load order remain unchanged. `npm run validate` checks exact installed pins, declared resources, dependency audit and bundled inventory. It does not certify installed-client rendering; carried checks remain in [Backlog](./BACKLOG.md).
 
 ```bash
 npm install

package/node_modules/@llblab/pi-state-flow/BACKLOG.md

@@ -1,6 +1,6 @@
 # Backlog
 
-The **0.25.2: Single Patch Display** hotfix is prepared; implementation outcomes belong in [CHANGELOG.md](CHANGELOG.md). This backlog retains publication and installed-client gates and deferred decisions. Cascade semantics, canonical storage, stored patch records and lifecycle behaviour remain unchanged.
+The **0.25.3: Readable Telegram Inspection** hotfix is prepared; outcomes belong in [CHANGELOG.md](CHANGELOG.md). This backlog retains installed-client gates and deferred decisions. Cascade semantics, canonical storage, stored patch records and lifecycle behaviour remain unchanged.
 
 ## Out of scope
 
@@ -10,7 +10,8 @@ The **0.25.2: Single Patch Display** hotfix is prepared; implementation outcomes
 
 ## Carried gates
 
-- **0.25.2 publication.** Verify the exact-tag workflow, GitHub Release and npm commit identity before closing this gate.
+- **0.25.3 publication.** Validate and publish through the exact-tag workflow; verify GitHub Release and npm commit, then synchronize and release Pi Kit.
+- **Installed 0.25.3 inspection smoke (operator-owned).** After separately authorized installation/reload, inspect a large nested field: real layout newlines/quotes, separate omitted-character notice and intact genuine JSON string escapes. Use disposable storage; local adapter tests do not certify installed Telegram clients.
 - **Installed 0.25.2 smoke (operator-owned).** Disposable store: confirm one patch argument block followed by changed/no-op acknowledgements, compact rows with `showSuccessfulPatches: false`, and visible rejected arguments/errors.
 - **Installed 0.25.1 smoke (operator-owned).** Disposable store: close an intent that owns a nested lazy key and confirm the receipt lists it under `cascaded`. May be combined with the open 0.25.0 smoke.
 - **Installed 0.22.0, 0.23.0, 0.24.0 and 0.25.0 smokes** remain open as recorded.

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.25.3: Readable Telegram Inspection
+
+- `Readable inspection`: Telegram memory inspection shows large fields as direct pretty-printed JSON prefixes instead of JSON-encoded `preview` strings with escaped layout and quotes. A separate notice reports omitted characters. Transport-aware budgeting preserves the Rich message ceiling and Unicode boundaries; genuine JSON string escapes, stored state and exact `read_state` results remain unchanged.
+
 ## 0.25.2: Single Patch Display
 
 - `Single patch display`: Interactive `patch_state` rows show JSON arguments once in the call, followed by the actual acceptance, no-op or error acknowledgement instead of a second patch. `showSuccessfulPatches: false` hides call arguments while retaining compact acknowledgements; rejected arguments remain visible. Atomic publication, stored state and model-facing `state_updates` receipts are unchanged.

package/node_modules/@llblab/pi-state-flow/dist/lib/telegram.js

@@ -73,35 +73,32 @@ const STATE_FLOW_SCOPE_LABELS = {
     session: "💬 Session",
     effective: "🧬 Effective",
 };
-// The complete message serializes each preformatted field one additional time;
-// 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
+// Budget the transport-serialized text, leaving room for six fields and notices
+// below Telegram's 32,768-character Rich message ceiling.
 const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
 function renderStateFlowTelegramField(value) {
     const json = JSON.stringify(value, null, 2);
-    if (json.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS)
-        return json;
+    if (JSON.stringify(json).length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
+        return [{ type: "pre", language: "json", text: json }];
+    }
     let low = 0;
-    let high = json.length;
-    let rendered = "";
+    let high = Math.min(json.length, STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS);
     while (low <= high) {
         const length = Math.floor((low + high) / 2);
-        const candidate = JSON.stringify({
-            truncated: true,
-            ...(value !== null && typeof value === "object" && !Array.isArray(value)
-                ? { keys: Object.keys(value) }
-                : {}),
-            preview: json.slice(0, length),
-            omittedChars: json.length - length,
-        }, null, 2);
-        if (candidate.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
-            rendered = candidate;
+        if (JSON.stringify(json.slice(0, length)).length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
             low = length + 1;
         }
         else {
             high = length - 1;
         }
     }
-    return rendered;
+    // Do not split a Unicode surrogate pair at the preview boundary.
+    if (/[\uD800-\uDBFF]/.test(json.charAt(high - 1)))
+        high -= 1;
+    return [
+        { type: "pre", language: "json", text: json.slice(0, high) },
+        { type: "pre", text: `Truncated preview — ${json.length - high} characters omitted.` },
+    ];
 }
 export function renderStateFlowRichState(scope, revisions, state) {
     const fields = scope === "global" || scope === "cwd"
@@ -120,7 +117,7 @@ export function renderStateFlowRichState(scope, revisions, state) {
             ...fields.filter((field) => state[field] !== undefined && state[field] !== "").map((field) => ({
                 type: "details",
                 summary: { type: "code", text: field },
-                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
+                blocks: renderStateFlowTelegramField(state[field]),
             })),
         ],
         skip_entity_detection: true,

package/node_modules/@llblab/pi-state-flow/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",

package/node_modules/@llblab/pi-state-flow/docs/usage.md

@@ -224,6 +224,7 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
 **Memory inspection:**
 
 - Owner-scope Rich snapshots show `#revision`; Effective shows the vector.
+- Fields show pretty-printed JSON directly. Large fields show a bounded JSON prefix with a separate truncation notice and omitted-character count, not a JSON-encoded `preview` string. The preview may end mid-value; actual escapes inside JSON string values remain intact. These presentation limits never truncate stored memory or successful `read_state` results.
 - During a failed-Passive write fence, memory-enabled inspection uses the accepted cache without a potentially conflicting refresh.
 - Otherwise, inspection waits cancelably to load or refresh one coherent shared view, even when passive model tools are disabled. It does not initialize, publish or advance storage.
 - Data and displayed revisions come from the same observation; absent or invalid memory stays unavailable.

package/node_modules/@llblab/pi-state-flow/lib/telegram.ts

@@ -191,34 +191,31 @@ const STATE_FLOW_SCOPE_LABELS: Record<StateFlowTelegramScope, string> = {
 	effective: "🧬 Effective",
 };
 
-// The complete message serializes each preformatted field one additional time;
-// 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
+// Budget the transport-serialized text, leaving room for six fields and notices
+// below Telegram's 32,768-character Rich message ceiling.
 const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
 
-function renderStateFlowTelegramField(value: unknown): string {
+function renderStateFlowTelegramField(value: unknown): StateFlowTelegramRichBlock[] {
 	const json = JSON.stringify(value, null, 2);
-	if (json.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) return json;
+	if (JSON.stringify(json).length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
+		return [{ type: "pre", language: "json", text: json }];
+	}
 	let low = 0;
-	let high = json.length;
-	let rendered = "";
+	let high = Math.min(json.length, STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS);
 	while (low <= high) {
 		const length = Math.floor((low + high) / 2);
-		const candidate = JSON.stringify({
-			truncated: true,
-			...(value !== null && typeof value === "object" && !Array.isArray(value)
-				? { keys: Object.keys(value) }
-				: {}),
-			preview: json.slice(0, length),
-			omittedChars: json.length - length,
-		}, null, 2);
-		if (candidate.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
-			rendered = candidate;
+		if (JSON.stringify(json.slice(0, length)).length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
 			low = length + 1;
 		} else {
 			high = length - 1;
 		}
 	}
-	return rendered;
+	// Do not split a Unicode surrogate pair at the preview boundary.
+	if (/[\uD800-\uDBFF]/.test(json.charAt(high - 1))) high -= 1;
+	return [
+		{ type: "pre", language: "json", text: json.slice(0, high) },
+		{ type: "pre", text: `Truncated preview — ${json.length - high} characters omitted.` },
+	];
 }
 
 export function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
@@ -238,7 +235,7 @@ export function renderStateFlowRichState(scope: StateFlowTelegramScope, revision
 			...fields.filter((field) => state[field] !== undefined && state[field] !== "").map((field) => ({
 				type: "details" as const,
 				summary: { type: "code" as const, text: field },
-				blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field]) }],
+				blocks: renderStateFlowTelegramField(state[field]),
 			})),
 		],
 		skip_entity_detection: true,

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "license": "MIT",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.27.3",
+  "version": "0.27.4",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -46,7 +46,7 @@
     "@llblab/pi-clean-room": "0.3.0",
     "@llblab/pi-codex-usage": "0.12.1",
     "@llblab/pi-grow-loop": "0.9.0",
-    "@llblab/pi-state-flow": "0.25.2",
+    "@llblab/pi-state-flow": "0.25.3",
     "@llblab/pi-telegram": "0.51.6",
     "@llblab/skills": "1.15.0"
   },