@llblab/pi-kit 0.27.2 → 0.27.4

package/AGENTS.md

@@ -20,6 +20,7 @@
 
 - Start work from `BACKLOG.md` and inspect the included package manifests before changing pins or resource paths.
 - Keep `dependencies`, `bundledDependencies`, Pi resource paths, README inventory, tests, and lockfile synchronized.
+- An explicitly requested bundled-extension release also authorizes synchronizing and releasing the kit in the same task; do not stop at local preparation. Follow the guarded repository release flow. Installation and live-client reload remain separately authorized.
 - Bundle every included Pi package so npm installation is self-contained under this package's module root. Keep repository-local `legacy-peer-deps=true` so host-provided Pi peers are not resolved into the kit's lockfile; Pi supplies them at runtime.
 - Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
 - Do not copy extension source, Skills, or documentation into this repository.

package/BACKLOG.md

@@ -1,11 +1,11 @@
 # Backlog
 
-The 0.27.2 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.
-
 - **Installed 0.27.0 smoke (operator-owned):** After separately authorized installation/reload, check the exact released kit's terminal controls and optional Telegram rendering with disposable State Flow storage. Packed SDK validation does not certify the operator's running clients. Do not reconnect Telegram, change Pi settings or use live memory/usage/Recipe stores as fixtures without separate authorization.

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.
+
 ## 0.27.2: State Flow Cascade Receipts
 
 - `Cascade Receipts`: Advances the exact State Flow pin to published `0.25.1`. Accepted receipts now list every intent-cascaded owner path, including nested lazy keys, without exposing bodies or eliding the list as predictable. The lifecycle-state ceiling also counts const-bound operation slots and lifetimes. 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.1` | Scoped context/memory compiler with intent-owned self-cleaning memory, memory-inert Off and ownership status |
+| [`@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.1/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.2` composition includes published State Flow `0.25.1` with complete cascade receipts, Codex Usage `0.12.1` and Claude Usage `0.2.1` with Telegram Fast status, alongside Telegram `0.51.6` and the Pi 1.0 cohort. The packed bundle loads all seven extensions on Pi 1.0.0 with no credentials or external requests. This 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.1: Cascade Receipts** scope is implemented; outcomes belong in [CHANGELOG.md](CHANGELOG.md). This backlog retains release 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,6 +10,9 @@ The **0.25.1: Cascade Receipts** scope is implemented; outcomes belong in [CHANG
 
 ## Carried gates
 
+- **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.
 
@@ -20,5 +23,4 @@ The **0.25.1: Cascade Receipts** scope is implemented; outcomes belong in [CHANG
 
 ## Release boundary
 
-- **Publication (approval-gated).** After explicit authorization, commit the prepared 0.25.1 package, lockfile, changelog and rebuilt `dist/`, tag the exact commit `v0.25.1`, and push. Verify the exact-tag release workflow, non-draft GitHub Release and matching npm version/commit before closing this gate. Local readiness requires `npm run validate` and the context validator; it does not certify installed clients.
-- **Installation/reload (operator-owned).** Requires separate authorization and disposable storage. Grow Loop preparation does not cross publication or live-client gates.
+Installation/reload requires separate authorization and disposable storage. Local validation and publication do not certify installed clients.

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

@@ -2,6 +2,14 @@
 
 > 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.
+
 ## 0.25.1: Cascade Receipts
 
 - `Composition ceiling`: One invariant now counts mutable closure bindings plus `OwnedOperationSlot` and `RenewableLifetime` instances in `lib/extension.ts`, including const-bound holders, against the current total of 24 (17 + 5 + 2). Existing named owner assertions remain. Mutation checks reject an added binding, operation slot or lifetime; lifecycle source and behavior are unchanged.

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

@@ -730,13 +730,15 @@ export default function stateFlowExtension(pi, options = {}) {
             cwd: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional project semantic patch" })),
             session: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional session semantic patch" })),
         }, { additionalProperties: false }),
-        renderResult(result, { isPartial }, theme, context) {
+        renderCall(args, theme, context) {
+            const title = theme.fg("toolTitle", theme.bold(PATCH_STATE_TOOL_NAME));
+            if (!config.showSuccessfulPatches && !context.isError)
+                return new Text(title, 0, 0);
+            return new Text(`${title}\n${separatedOutput(theme.fg("dim", formatPatchStateArguments(args)))}`, 0, 0);
+        },
+        renderResult(result) {
             const text = result.content.find((block) => block.type === "text")?.text ?? "";
-            if (context.isError)
-                return new Text(separatedOutput(text), 0, 0);
-            if (isPartial || !config.showSuccessfulPatches)
-                return new Text(text, 0, 0);
-            return new Text(separatedOutput(theme.fg("dim", formatPatchStateArguments(context.args))), 0, 0);
+            return new Text(separatedOutput(text), 0, 0);
         },
         async execute(toolCallId, params, signal, _onUpdate, ctx) {
             signal = signal ? AbortSignal.any([signal, memoryToolLifetime.signal]) : memoryToolLifetime.signal;

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.1",
+  "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

@@ -145,7 +145,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
   - Passive reads existing memory without publishing; its first explicit patch may initialize absent storage without starting an episode or compaction.
   - Off exposes neither memory tools nor State Flow context.
 - `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
-- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections. Set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
+- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `patch_state` rows show pretty-printed JSON arguments once in the call, with blank lines between adjacent memory sections; the result shows the acceptance or no-op acknowledgement, never a second patch. Set it to `false` to hide call arguments and keep the compact acknowledgement. Rejected calls retain their arguments and error acknowledgement; State Flow adds no private validation turn.
 - `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**, and bounds materialized-history and scope patch-history offsets.
   - Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window become unavailable.
   - Zero keeps only current checkpoints.
@@ -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/extension.ts

@@ -746,11 +746,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			cwd: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional project semantic patch" })),
 			session: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional session semantic patch" })),
 		}, { additionalProperties: false }),
-		renderResult(result, { isPartial }, theme, context) {
+		renderCall(args, theme, context) {
+			const title = theme.fg("toolTitle", theme.bold(PATCH_STATE_TOOL_NAME));
+			if (!config.showSuccessfulPatches && !context.isError) return new Text(title, 0, 0);
+			return new Text(`${title}\n${separatedOutput(theme.fg("dim", formatPatchStateArguments(args)))}`, 0, 0);
+		},
+		renderResult(result) {
 			const text = result.content.find((block) => block.type === "text")?.text ?? "";
-			if (context.isError) return new Text(separatedOutput(text), 0, 0);
-			if (isPartial || !config.showSuccessfulPatches) return new Text(text, 0, 0);
-			return new Text(separatedOutput(theme.fg("dim", formatPatchStateArguments(context.args))), 0, 0);
+			return new Text(separatedOutput(text), 0, 0);
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			signal = signal ? AbortSignal.any([signal, memoryToolLifetime.signal]) : memoryToolLifetime.signal;

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.1",
+  "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.2",
+  "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.1",
+    "@llblab/pi-state-flow": "0.25.3",
     "@llblab/pi-telegram": "0.51.6",
     "@llblab/skills": "1.15.0"
   },