pi-ui-extend 0.1.17 → 0.1.18

package/external/pi-tools-suite/src/dcp/state.ts

@@ -176,6 +176,12 @@ export interface DcpState {
   tokensSaved: number
   /** Number of discrete pruning operations performed */
   totalPruneCount: number
+  /**
+   * Total number of tool calls observed during the session lifetime.
+   * Persisted so `/dcp stats` can show an approximate total even when the
+   * toolCalls map has been trimmed for compactness.
+   */
+  totalToolCallCount: number
   /** Compression block IDs already counted in tokensSaved/totalPruneCount. */
   accountedCompressionBlockIds: Set<number>
   /** compressionBlockId → raw active-token savings estimate for that block. */
@@ -229,6 +235,7 @@ export function createState(): DcpState {
     currentTurn: 0,
     tokensSaved: 0,
     totalPruneCount: 0,
+    totalToolCallCount: 0,
     accountedCompressionBlockIds: new Set(),
     compressionTokenSavings: new Map(),
     accountedPrunedToolIds: new Set(),
@@ -257,6 +264,7 @@ export function resetState(state: DcpState): void {
   state.currentTurn = 0
   state.tokensSaved = 0
   state.totalPruneCount = 0
+  state.totalToolCallCount = 0
   state.accountedCompressionBlockIds.clear()
   state.compressionTokenSavings.clear()
   state.accountedPrunedToolIds.clear()
@@ -268,12 +276,59 @@ export function resetState(state: DcpState): void {
   state.lastNudge = undefined
 }
 
+/**
+ * Compact tool record for persistence — strips outputText, outputDetails,
+ * and truncates/summarises inputArgs to keep serialized state bounded.
+ */
+export interface CompactToolRecord {
+  toolCallId: string
+  toolName: string
+  inputFingerprint: string
+  isError: boolean
+  turnIndex: number
+  timestamp: number
+  tokenEstimate: number
+  /**
+   * Extracted string values from inputArgs that could match file-protection
+   * patterns, persisted so `isProtectedByFilePattern` still works after
+   * session restore. Capped to avoid bloating state with huge arg values.
+   */
+  inputStringValues?: string[]
+}
+
+/**
+ * Maximum number of recent tool records retained in persisted state.
+ * Older records are still kept when referenced by active compression blocks,
+ * pruned tool IDs, or accounted prune IDs.
+ */
+export const PERSISTED_TOOL_CALLS_MAX_RECENT = 200
+
+/**
+ * Maximum length of individual string values extracted from inputArgs
+ * for file-pattern matching. Longer values are truncated.
+ */
+const INPUT_STRING_VALUE_MAX_LENGTH = 512
+
+/**
+ * Maximum number of inputStringValues to keep per tool record.
+ */
+const INPUT_STRING_VALUES_MAX_COUNT = 20
+
 export interface SerializedDcpState {
   compressionBlocks: CompressionBlock[]
   nextBlockId: number
   prunedToolIds: string[]
   prunedToolReasons: Array<[string, string]>
-  toolCalls: ToolRecord[]
+  /** Full tool records — present in legacy snapshots. */
+  toolCalls?: ToolRecord[]
+  /** Compact tool records — present in new compact snapshots. */
+  compactToolCalls?: CompactToolRecord[]
+  /**
+   * Total number of tool calls observed during the session, including those
+   * trimmed from the persisted snapshot. Allows `/dcp stats` to report
+   * approximate totals.
+   */
+  totalToolCallCount?: number
   tokensSaved: number
   totalPruneCount: number
   accountedCompressionBlockIds: number[]
@@ -297,6 +352,8 @@ export interface SerializedDcpState {
   nudgeCounter?: number
   /** Persisted since v?.?. Diagnostic turn of the last emitted nudge. */
   lastNudgeTurn?: number
+  /** Hash of the last persisted serialized state, used for dedup. */
+  _stateHash?: string
 }
 
 function isToolRecord(value: unknown): value is ToolRecord {
@@ -309,6 +366,16 @@ function isToolRecord(value: unknown): value is ToolRecord {
   )
 }
 
+function isCompactToolRecord(value: unknown): value is CompactToolRecord {
+  if (!value || typeof value !== "object") return false
+  const record = value as Partial<CompactToolRecord>
+  return (
+    typeof record.toolCallId === "string" &&
+    typeof record.toolName === "string" &&
+    typeof record.inputFingerprint === "string"
+  )
+}
+
 function isNudgeAnchor(value: unknown): value is DcpNudgeAnchor {
   if (!value || typeof value !== "object") return false
   const anchor = value as Partial<DcpNudgeAnchor>
@@ -334,14 +401,116 @@ function isLastNudge(value: unknown): value is DcpLastNudge {
   )
 }
 
+// ---------------------------------------------------------------------------
+// Compact tool-record helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively extract string values from a nested object, matching the
+ * logic in `pruner-tools.ts::collectStringValues`. Depth-limited to 6.
+ */
+function extractStringValues(value: unknown, out: string[] = [], depth = 0): string[] {
+  if (depth > 6) return out
+  if (typeof value === "string") {
+    out.push(value)
+    return out
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) extractStringValues(item, out, depth + 1)
+    return out
+  }
+  if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value as Record<string, unknown>)) {
+      extractStringValues(item, out, depth + 1)
+    }
+  }
+  return out
+}
+
+/**
+ * Produce a compact tool record for persistence: strip outputText,
+ * outputDetails, and reduce inputArgs to just extracted string values
+ * for file-pattern protection checking.
+ */
+export function compactifyToolRecord(record: ToolRecord): CompactToolRecord {
+  const stringValues = extractStringValues(record.inputArgs)
+  // Truncate individual values and limit total count
+  const cappedValues = stringValues
+    .slice(0, INPUT_STRING_VALUES_MAX_COUNT)
+    .map((v) => (v.length > INPUT_STRING_VALUE_MAX_LENGTH ? v.slice(0, INPUT_STRING_VALUE_MAX_LENGTH) : v))
+
+  const compact: CompactToolRecord = {
+    toolCallId: record.toolCallId,
+    toolName: record.toolName,
+    inputFingerprint: record.inputFingerprint,
+    isError: record.isError,
+    turnIndex: record.turnIndex,
+    timestamp: record.timestamp,
+    tokenEstimate: record.tokenEstimate,
+  }
+  if (cappedValues.length > 0) {
+    compact.inputStringValues = cappedValues
+  }
+  return compact
+}
+
+/**
+ * Determine which tool-call IDs are referenced by active compression blocks
+ * (via createdByToolCallId) or by pruned/accounted sets, and therefore must
+ * be retained even when trimming old records.
+ */
+function referencedToolCallIds(state: DcpState): Set<string> {
+  const refs = new Set<string>()
+  // Tool IDs referenced by active compression blocks
+  for (const block of state.compressionBlocks) {
+    if (block.active && block.createdByToolCallId) {
+      refs.add(block.createdByToolCallId)
+    }
+  }
+  // Pruned tool IDs
+  for (const id of state.prunedToolIds) refs.add(id)
+  // Accounted pruned tool IDs (superset of prunedToolIds in some cases)
+  for (const id of state.accountedPrunedToolIds) refs.add(id)
+  return refs
+}
+
 /** Serialize runtime state into a JSON-safe object for pi.appendEntry(). */
 export function serializeState(state: DcpState): SerializedDcpState {
+  // Build compact tool records, keeping referenced + recent ones.
+  const allRecords = Array.from(state.toolCalls.values())
+  const refs = referencedToolCallIds(state)
+
+  // Sort by timestamp descending so we can pick the most recent ones
+  const sorted = allRecords
+    .slice()
+    .sort((a, b) => b.timestamp - a.timestamp)
+
+  const compactToolCalls: CompactToolRecord[] = []
+  const seen = new Set<string>()
+
+  // First pass: always include referenced records
+  for (const record of sorted) {
+    if (refs.has(record.toolCallId)) {
+      compactToolCalls.push(compactifyToolRecord(record))
+      seen.add(record.toolCallId)
+    }
+  }
+
+  // Second pass: add recent records up to the limit
+  for (const record of sorted) {
+    if (seen.has(record.toolCallId)) continue
+    if (compactToolCalls.length >= PERSISTED_TOOL_CALLS_MAX_RECENT) break
+    compactToolCalls.push(compactifyToolRecord(record))
+    seen.add(record.toolCallId)
+  }
+
   return {
     compressionBlocks: state.compressionBlocks,
     nextBlockId: state.nextBlockId,
     prunedToolIds: Array.from(state.prunedToolIds),
     prunedToolReasons: Array.from(state.prunedToolReasons.entries()),
-    toolCalls: Array.from(state.toolCalls.values()),
+    compactToolCalls,
+    totalToolCallCount: allRecords.length,
     tokensSaved: state.tokensSaved,
     totalPruneCount: state.totalPruneCount,
     accountedCompressionBlockIds: Array.from(state.accountedCompressionBlockIds),
@@ -397,7 +566,34 @@ export function restoreState(state: DcpState, data: unknown): void {
     )
   }
 
-  if (Array.isArray(saved.toolCalls)) {
+  if (Array.isArray(saved.compactToolCalls)) {
+    // New compact format: restore CompactToolRecords as ToolRecords with
+    // synthetic inputArgs derived from inputStringValues.
+    state.toolCalls = new Map(
+      saved.compactToolCalls
+        .filter(isCompactToolRecord)
+        .map((compact) => {
+          const record: ToolRecord = {
+            toolCallId: compact.toolCallId,
+            toolName: compact.toolName,
+            // Reconstruct minimal inputArgs from persisted string values
+            // so isProtectedByFilePattern still works.
+            inputArgs: compact.inputStringValues
+              ? { _restoredValues: compact.inputStringValues }
+              : {},
+            inputFingerprint: compact.inputFingerprint,
+            isError: compact.isError,
+            turnIndex: compact.turnIndex,
+            timestamp: compact.timestamp,
+            tokenEstimate: compact.tokenEstimate,
+            // outputText and outputDetails intentionally not restored —
+            // they are only used during live compression block creation.
+          }
+          return [record.toolCallId, record] as const
+        }),
+    )
+  } else if (Array.isArray(saved.toolCalls)) {
+    // Legacy full format: restore as-is for backward compatibility.
     state.toolCalls = new Map(
       saved.toolCalls
         .filter(isToolRecord)
@@ -408,6 +604,14 @@ export function restoreState(state: DcpState, data: unknown): void {
   if (typeof saved.tokensSaved === "number") state.tokensSaved = saved.tokensSaved
   if (typeof saved.totalPruneCount === "number") state.totalPruneCount = saved.totalPruneCount
 
+  // Restore totalToolCallCount from the persisted snapshot, or fall back to
+  // the number of restored tool records (which may be a trimmed subset).
+  if (typeof saved.totalToolCallCount === "number" && saved.totalToolCallCount >= 0) {
+    state.totalToolCallCount = saved.totalToolCallCount
+  } else {
+    state.totalToolCallCount = state.toolCalls.size
+  }
+
   if (Array.isArray(saved.accountedCompressionBlockIds)) {
     state.accountedCompressionBlockIds = new Set(
       saved.accountedCompressionBlockIds.filter((id): id is number => typeof id === "number"),
@@ -519,3 +723,21 @@ export function createInputFingerprint(
   const sorted = sortObjectKeys(args)
   return `${toolName}::${JSON.stringify(sorted)}`
 }
+
+// ---------------------------------------------------------------------------
+// State hashing for save deduplication
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a fast hash of serialized state for deduplication.
+ * Uses a simple DJB2-like hash over the JSON string. This is not
+ * cryptographic — it's only used to avoid writing identical snapshots.
+ */
+export function hashSerializedState(serialized: SerializedDcpState): string {
+  const json = JSON.stringify(serialized)
+  let hash = 5381
+  for (let i = 0; i < json.length; i++) {
+    hash = ((hash << 5) + hash + json.charCodeAt(i)) | 0
+  }
+  return (hash >>> 0).toString(36)
+}

package/external/pi-tools-suite/src/default-pi-tools-suite-config.ts

@@ -9,6 +9,11 @@ export const DEFAULT_PI_TOOLS_SUITE_CONFIG_JSONC = String.raw`{
   // module will switch/restore Pi's thinking level as in-progress tasks change.
   "todoThinking": false,
   "terminalBell": { "sound": true },
+  // "telegramMirror": {
+  //   "enabled": true,
+  //   "botToken": "123456789:ABCdef...",
+  //   "chatId": 123456789
+  // },
   "dcp": {
     "enabled": true,
     "manualMode": { "enabled": false, "automaticStrategies": true },

package/external/pi-tools-suite/src/index.ts

@@ -22,6 +22,7 @@ const MODULES: Array<{ name: string; load: () => Promise<ExtensionModule> }> = [
 	{ name: "web-search", load: () => import("./web-search/index") },
 	{ name: "dcp", load: () => import("./dcp/index") },
 	{ name: "prompt-commands", load: () => import("./prompt-commands/index") },
+	{ name: "telegram-mirror", load: () => import("./telegram-mirror/index") },
 ];
 
 export default async function piToolsSuite(pi: ExtensionAPI) {

package/external/pi-tools-suite/src/telegram-mirror/README.md

@@ -0,0 +1,168 @@
+# telegram-mirror
+
+A pi-tools-suite module that exposes one or more running pi sessions as a
+single Telegram chat. Pi stays as the source of truth; Telegram is a remote
+second screen.
+
+## Opt-in
+
+The module is a no-op until you add a `telegramMirror` block to
+`~/.config/pi/pi-tools-suite.jsonc`:
+
+```jsonc
+{
+  // …other pi-tools-suite settings…
+  "telegramMirror": {
+    "enabled": true,
+    "botToken": "123456789:ABCdef…",   // from @BotFather
+    "chatId": 123456789                // numeric chat id of your private chat
+  }
+}
+```
+
+| Field       | Type              | Required | Notes                                                                                          |
+|-------------|-------------------|----------|------------------------------------------------------------------------------------------------|
+| `enabled`   | boolean           | no       | Defaults to `true` when the block is present and `botToken` + `chatId` are valid.              |
+| `botToken`  | string            | yes      | Telegram Bot API token from [@BotFather](https://t.me/BotFather). Empty string disables.       |
+| `chatId`    | number or string  | yes      | Numeric chat id of the private chat allowed to control the bot. Non-integer disables.          |
+
+When the block is present and valid, the module connects on the next `pi`
+start (or `/reload`).
+
+## How to get your chat id
+
+Open this URL in a browser (replace `<TOKEN>` with your bot token):
+
+```
+https://api.telegram.org/bot<TOKEN>/getUpdates
+```
+
+Send any message to your bot in Telegram, then refresh the URL. The JSON
+response contains `"chat": { "id": 123456789, … }` — that number is your
+`chatId`.
+
+Alternative: message [@userinfobot](https://t.me/userinfobot).
+
+The bot silently ignores every message from any other chat.
+
+## Multi-instance setup
+
+Telegram allows exactly one concurrent `getUpdates` call per bot token,
+so this module elects a **leader** when N pi processes share one bot:
+
+1. The first pi to start binds the unix socket at
+   `~/.pi/agent/extensions/pi-tools-suite/.run/telegram-mirror.sock`,
+   connects the bot, and starts polling.
+2. Subsequent pi processes connect to that socket as **followers**. They
+   forward their pix events to the leader over IPC and execute commands
+   received from the leader.
+3. If the leader dies (process exit, socket close, or heartbeat timeout),
+   followers race to bind the socket; the first to win becomes the new
+   leader. `activeId` resets on failover — run `/use N` again.
+
+No setup needed: this is fully automatic. Just run more `pi` processes.
+
+When you start a new pi, it logs `[telegram-mirror] registered with
+leader <label>` on stderr. The leader logs `[telegram-mirror] connected
+as @<botname> (leader)`.
+
+### Selecting the active instance
+
+In Telegram, use `/list` and `/use`:
+
+```
+/list
+→
+1. pi-ui-extend (#12345) (leader) \[active\]
+2. opencode (#67890)
+3. other-repo (#99999)
+
+Use /use N or /use <id> to switch.
+```
+
+```
+/use 2
+→ ✅ Active: opencode (#67890)
+```
+
+`/use` accepts a 1-based index from `/list` or a substring of the id/label.
+Events from non-active instances are dropped (silent).
+
+### Cleanup
+
+Socket file: `~/.pi/agent/extensions/pi-tools-suite/.run/telegram-mirror.sock`.
+
+If a pi crashes hard and leaves a stale socket, the next pi to start will
+unlink it automatically (bind fails → connect fails → unlink → retry).
+
+## Telegram → pix
+
+| Command           | Effect                                                 |
+|-------------------|--------------------------------------------------------|
+| Free text         | forwarded to the active pi instance as user message   |
+| `/list`           | show all known pi instances, mark active               |
+| `/use N` `/use X` | switch active instance (by index or id/label substring)|
+| `/abort` `/stop`  | cancel current turn on active                          |
+| `/compact`        | trigger context compaction on active                   |
+| `/status`         | show idle / streaming state of active                  |
+| `/say <msg>`      | explicit send (escape hatch for `/`-prefixed text)     |
+| `/disconnect`     | stop the bot cluster-wide (resume with `/reload` in pi)|
+| `/new`            | not supported via extension API — run `/new` in pi     |
+| `/help`           | show command list                                      |
+
+## Pix → Telegram
+
+The leader subscribes to pix streaming events (its own + followers' via IPC)
+and renders one Telegram message per agent turn — but **only for the active
+instance**:
+
+- `before_agent_start` → `user: <prompt>`
+- `message_update` (`text_delta`) → appended to the active message, edited
+  in place at ~1.2 s throttle (Telegram rate-limit friendly).
+- `tool_execution_start` → `🔧 tool: <args>` line.
+- `tool_execution_end` → `✅ tool: <summary>` or `❌` on error.
+- `agent_end` → final flush + `— done —` trailer.
+
+Messages are paginated at 4096 chars (Telegram's per-message limit).
+Markdown is converted to Telegram HTML with `**bold**`, `*italic*`,
+`` `code` ``, and fenced blocks.
+
+## Disable
+
+Either set `"enabled": false` in the `telegramMirror` block, remove the
+block entirely, or add `telegram-mirror` to the `disabledModules` array
+in the same config file, then `/reload` pi.
+
+## Known limitations
+
+- `/new` cannot start a fresh session from Telegram. The ExtensionAPI
+  exposes `newSession()` only on slash-command handler contexts, not on
+  event-handler contexts. Workaround: type `/new` in the pi TUI.
+- `pi.sendUserMessage` does not expand pi's own slash commands (calls
+  `prompt(..., { expandPromptTemplates: false })` internally), so text
+  starting with `/` is sent verbatim to the LLM. The module's own
+  `/abort`, `/compact`, `/list`, `/use`, etc. are intercepted before
+  `sendUserMessage` is called, so they work.
+- The leader uses long polling (35 s timeout) and keeps one outbound
+  request open. If your network blocks Telegram, you'll see repeating
+  `[telegram-mirror] polling: …` errors in stderr and the bot will back
+  off up to 60 s between retries.
+- On leader failover, the in-flight streaming output for the active turn
+  is lost (the new leader's renderer starts empty). `activeId` also
+  resets to the new leader; run `/use N` to switch back to a follower.
+- The cluster is single-host only (unix socket). To mirror across
+  machines, use separate bot tokens.
+- IPC events between session_start and leader-registration can be lost
+  for a brief window. Mid-stream output may be cut off.
+
+## Files
+
+| File            | Purpose                                                |
+|-----------------|--------------------------------------------------------|
+| `index.ts`      | module factory: role selection (leader/follower) + lifecycle |
+| `bot.ts`        | Telegram Bot API fetch client + long-poll loop         |
+| `ipc.ts`        | unix socket JSON-lines IPC + leader election           |
+| `multiplexer.ts`| leader-side registry + active-instance routing         |
+| `events.ts`     | pix event → sink adapters + ctx capture                |
+| `renderer.ts`   | per-turn buffer, throttled edit, pagination            |
+| `format.ts`     | markdown → Telegram HTML, chunking                     |