@llblab/pi-kit 0.27.5 → 0.28.0

package/node_modules/@llblab/pi-telegram/scripts/check-downgrade.mjs

@@ -22,14 +22,21 @@
  */
 
 import {
-  existsSync,
   lstatSync,
   readFileSync,
-  readdirSync,
+  opendirSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
+import { decodeTelegramSessionDirectoryName, resolveTelegramTempDir } from "../dist/lib/paths.js";
 
+const MAX_DIRECTORY_ENTRIES = 10_000;
+const MAX_FILES = 4_096;
+const MAX_BYTES = 64 * 1024 * 1024;
+let remainingEntries = MAX_DIRECTORY_ENTRIES;
+let remainingFiles = MAX_FILES;
+let remainingBytes = MAX_BYTES;
+const SESSION_SNAPSHOT_PATTERN = /^(?:journal\.[a-f0-9]{16}|inbox)(?:\.[a-zA-Z0-9._-]+)?\.json$/u;
 const SNAPSHOT_PATTERN = /^(?:inbox|follower-inbox-[a-f0-9]{16})(?:\.[a-zA-Z0-9._-]+)?\.json$/u;
 const SEGMENT_NAME_PATTERN = /^\d{16}\.json$/u;
 const AUTHORITY_STATES = new Set(["pending", "retry-wait", "queued", "failed"]);
@@ -114,8 +121,24 @@ function isNonNegativeInteger(value) {
   return Number.isSafeInteger(value) && value >= 0;
 }
 
-function readJson(path) {
+function listDirectory(path) {
+  const directory = opendirSync(path);
+  const names = [];
   try {
+    for (;;) {
+      const entry = directory.readSync();
+      if (!entry) return names.sort();
+      if (--remainingEntries < 0) throw new Error("journal directory listing limit exhausted");
+      names.push(entry.name);
+    }
+  } finally { directory.closeSync(); }
+}
+
+function readJson(path, stat) {
+  try {
+    if (--remainingFiles < 0 || stat.size > remainingBytes)
+      throw new Error("journal file/byte inspection limit exhausted");
+    remainingBytes -= stat.size;
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
     block(
@@ -306,46 +329,56 @@ function validateSegment(value) {
 }
 
 const agentDir = resolveAgentDir();
-const runtimeDir = join(agentDir, "tmp", "telegram");
-if (!existsSync(runtimeDir)) {
-  console.log("SAFE: no Telegram runtime directory exists.");
-  process.exit(0);
-}
-
+const runtimeDir = resolveTelegramTempDir(agentDir);
 let runtimeNames;
+let observedRuntime = false;
 try {
-  runtimeNames = readdirSync(runtimeDir);
+  if (!lstatSync(runtimeDir).isDirectory()) throw new Error("non-directory Telegram runtime or link");
+  observedRuntime = true;
+  runtimeNames = listDirectory(runtimeDir);
 } catch (error) {
-  block(
-    `cannot verify Telegram runtime directory ${runtimeDir}: ${error instanceof Error ? error.message : String(error)}`,
-  );
+  if (error?.code === "ENOENT" && !observedRuntime) {
+    console.log("SAFE: no Telegram runtime directory exists.");
+    process.exit(0);
+  }
+  block(`cannot verify Telegram runtime directory ${runtimeDir}: ${error instanceof Error ? error.message : String(error)}`);
   process.exit(1);
 }
 
-const snapshotNames = runtimeNames.filter((name) => SNAPSHOT_PATTERN.test(name));
-const snapshotSet = new Set(snapshotNames);
-for (const name of runtimeNames) {
-  const snapshotName = name.endsWith(".segments")
-    ? name.slice(0, -".segments".length)
-    : undefined;
-  if (snapshotName && SNAPSHOT_PATTERN.test(snapshotName)) {
-    if (!snapshotSet.has(snapshotName)) {
-      block(
-        `cannot verify orphan journal segments without ${join(runtimeDir, snapshotName)}`,
-      );
+function collectSnapshots(directory, names, pattern, strict = false) {
+  const snapshots = names.filter(name => pattern.test(name));
+  const snapshotSet = new Set(snapshots);
+  for (const name of names) {
+    // Legacy recovery folders hold no journal authority; current releases delete them.
+    if (name.toLowerCase() === "recovery") continue;
+    const snapshotName = name.endsWith(".segments") ? name.slice(0, -".segments".length) : undefined;
+    if (snapshotName && pattern.test(snapshotName)) {
+      if (!snapshotSet.has(snapshotName)) block(`cannot verify orphan journal segments without ${join(directory, snapshotName)}`);
+      continue;
     }
-    continue;
-  }
-  if (
-    (name.startsWith("inbox") || name.startsWith("follower-inbox")) &&
-    !SNAPSHOT_PATTERN.test(name)
-  ) {
-    block(`cannot verify unrecognized journal-like artifact ${join(runtimeDir, name)}`);
+    if (!pattern.test(name) && (strict || /^(?:inbox|follower-inbox|journal\.)/iu.test(name)))
+      block(`cannot verify unrecognized journal-like artifact ${join(directory, name)}`);
   }
+  return snapshots.map(name => join(directory, name));
 }
 
-for (const name of snapshotNames) {
-  const path = join(runtimeDir, name);
+const snapshotPaths = collectSnapshots(runtimeDir, runtimeNames, SNAPSHOT_PATTERN);
+for (const name of runtimeNames.filter(name => name.toLowerCase() === "sessions")) {
+  const root = join(runtimeDir, name);
+  try {
+    if (name !== "sessions" || !lstatSync(root).isDirectory()) throw new Error("noncanonical session root or link/type");
+    for (const sessionName of listDirectory(root)) {
+      const directory = join(root, sessionName);
+      if (decodeTelegramSessionDirectoryName(sessionName) === undefined || !lstatSync(directory).isDirectory()) {
+        block(`cannot verify session folder ${directory}`);
+        continue;
+      }
+      snapshotPaths.push(...collectSnapshots(directory, listDirectory(directory), SESSION_SNAPSHOT_PATTERN, true));
+    }
+  } catch (error) { block(`cannot verify session journals ${root}: ${String(error)}`); }
+}
+
+for (const path of snapshotPaths) {
   let pathStat;
   try {
     pathStat = lstatSync(path);
@@ -357,7 +390,7 @@ for (const name of snapshotNames) {
     block(`cannot verify non-file journal snapshot ${path}`);
     continue;
   }
-  const snapshot = validateSnapshot(readJson(path));
+  const snapshot = validateSnapshot(readJson(path, pathStat));
   if (!snapshot) {
     block(`cannot verify malformed journal snapshot ${path}`);
     continue;
@@ -367,14 +400,19 @@ for (const name of snapshotNames) {
   let botIdentity = snapshot.botIdentity;
   const entries = snapshot.entries;
   const segmentDir = `${path}.segments`;
-  if (existsSync(segmentDir)) {
+  let segmentDirectoryStat;
+  try { segmentDirectoryStat = lstatSync(segmentDir); }
+  catch (error) {
+    if (error?.code !== "ENOENT") block(`cannot verify journal segments ${segmentDir}: ${String(error)}`);
+  }
+  if (segmentDirectoryStat) {
     let segmentNames;
     try {
-      if (!lstatSync(segmentDir).isDirectory()) {
+      if (!segmentDirectoryStat.isDirectory()) {
         block(`cannot verify non-directory journal segments ${segmentDir}`);
         continue;
       }
-      segmentNames = readdirSync(segmentDir);
+      segmentNames = listDirectory(segmentDir);
     } catch (error) {
       block(`cannot verify journal segments ${segmentDir}: ${String(error)}`);
       continue;
@@ -389,7 +427,6 @@ for (const name of snapshotNames) {
       SEGMENT_NAME_PATTERN.test(candidate),
     ).sort()) {
       const nameRevision = Number(segmentName.slice(0, 16));
-      if (nameRevision <= revision) continue;
       const segmentPath = join(segmentDir, segmentName);
       let segmentStat;
       try {
@@ -398,9 +435,9 @@ for (const name of snapshotNames) {
         block(`cannot verify journal segment ${segmentPath}: ${String(error)}`);
         break;
       }
-      const segment = segmentStat.isFile()
-        ? validateSegment(readJson(segmentPath))
-        : undefined;
+      if (!segmentStat.isFile()) { block(`cannot verify non-file journal segment ${segmentPath}`); break; }
+      if (nameRevision <= revision) continue;
+      const segment = validateSegment(readJson(segmentPath, segmentStat));
       if (
         !segment ||
         segment.revision !== nameRevision ||
@@ -426,10 +463,10 @@ for (const name of snapshotNames) {
   }
   if (entries.size > 0) {
     block(
-      `${path} retains ${entries.size} unresolved update(s); drain with 0.28.x before downgrade.`,
+      `${path} retains ${entries.size} unresolved update(s); drain with a compatible runtime before downgrade.`,
     );
   }
 }
 
 if (process.exitCode) process.exit(1);
-console.log(`SAFE: ${snapshotNames.length} Telegram journal(s) contain no unresolved updates.`);
+console.log(`SAFE: ${snapshotPaths.length} Telegram journal(s) contain no unresolved updates.`);

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -46,7 +46,7 @@ A disabled control is not an action: it needs no prompt or selected style and mu
 
 Prompts must name any target, operation, constraint, or freshness identity whose omission could change the action. Reuse visible context only when it remains unambiguous under delayed or reordered clicks. Never encode volatile output that should be freshly inspected.
 
-Every generated human-readable action label must use `emoji + space + text`; emoji-free text labels are invalid. Choose the emoji by action semantics, keep its meaning consistent, and never rely on emoji or color alone. Coordinates, established symbolic controls, and intentionally spatial glyphs already satisfy the marker role through their domain grammar. If prompt buttons are unavailable, preserve the same choices as a numbered list.
+Every generated human-readable action label must use `emoji + space + text`; emoji-free text labels are invalid. Choose the emoji by action semantics, keep its meaning consistent, and never rely on emoji or color alone. State/value controls follow their UI-kit grammar; unmarked inactive list items are not action labels. Coordinates, established symbolic controls, and intentionally spatial glyphs already satisfy the marker role through their domain grammar. If prompt buttons are unavailable, preserve the same choices as a numbered list.
 
 ## Layout Kernel
 
@@ -97,10 +97,10 @@ Show concise failure evidence and emit valid recovery controls such as diagnose,
 Before sending:
 
 - At least one useful button is present whenever the transport supports prompt buttons.
-- Every human-readable button label begins with a semantic emoji and one ASCII space.
+- Every human-readable action label begins with a semantic emoji and one ASCII space; state/value controls follow their owning documented grammar.
 - State, actions, owner, and target agree.
 - Live claims are fresh; adaptation and incompleteness are explicit.
-- Every prompt is sufficient and every label follows its semantic emoji rule.
+- Every prompt is sufficient; labels follow their control grammar.
 - Row grouping reflects real hierarchy or peer relationships.
 - High-impact actions require confirmation.
 - No secret or hidden reasoning appears.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/diagnosis.md

@@ -6,12 +6,12 @@ Inspect in this order:
 
 1. `/telegram-status` for compact health in the Pi TUI.
 2. `/telegram-status --debug` for bounded human-readable diagnostics in the Pi TUI.
-3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence.
-4. `state.<profile>.json` and `logs.<profile>.jsonl` for a named profile.
+3. `~/.pi/agent/tmp/pi-telegram/state.json` (per-profile `transport`, `workspace` canonical bindings and `runtime` roster/diagnostics sections) and `logs.jsonl` (profile-labelled redacted evidence); rotated history is `logs/logs._prev.jsonl`.
+4. For a named profile, read its `profiles.<name>` entry and filter log records by `profile`; service journals are `journals/<kind>.<profile sha256>.json`.
 
 These slash commands are registered Pi commands, not shell executables or agent tools. If the agent cannot invoke them through a supported Pi surface, read the diagnostic files directly; do not run them in Bash or inject terminal input.
 
-When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve its equivalent `tmp/telegram` directory.
+When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve its equivalent `tmp/pi-telegram` directory.
 
 A `persistent-conflict` polling stop means the bounded competing-`getUpdates` threshold triggered full transport stand-down, not cancellation of accepted local Pi work. The terminal diagnostic distinguishes lost local ownership from a competing client despite an apparently owned lock. Check other profiles, agent directories, installations, or non-Pi clients sharing the bot; after removing the competition, reconnect through the supported Pi command. Do not restart repeatedly or alter lock files to compete for the stream.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.27.5",
+  "version": "0.28.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -46,8 +46,8 @@
     "@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.4",
-    "@llblab/pi-telegram": "0.51.6",
+    "@llblab/pi-state-flow": "0.25.5",
+    "@llblab/pi-telegram": "0.52.0",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [