shariq-pi-extensions 0.2.10 → 0.2.12

package/README.md

@@ -33,6 +33,7 @@ The package contains:
 - persistent task goals
 - configurable steer, interrupt, or follow-up input behavior
 - dedicated multi-agent orchestration
+- Smart Compaction with high-fidelity checkpointing, delta-merging, and custom model routing
 - Pi Memory
 - per-response TPS, TTFT, elapsed-time, and output status
 - Context Usage display

package/docs/EXTENSIONS.md

@@ -46,6 +46,12 @@ The Orchestration extension coordinates explicitly requested large tasks through
 
 The model-facing `create_orchestration` tool starts planning only after an explicit orchestration request. `get_orchestration` reports status without advancing work. Interrupted runs recover paused under `<agent-dir>/orchestration/`.
 
+### [Smart Compaction](../extensions/smart-compaction/README.md)
+
+Replaces standard context compaction with a high-fidelity continuity engine. It intercepts `session_before_compact` events and synthesizes multi-turn conversations into structured checkpoint summaries capturing primary goals and negative constraints, progress ledgers (`Done`/`In Progress`/`Blocked`), verbatim code snippets for active/uncommitted edits, exact error root causes, architectural decisions, resume anchors, and deterministic `<read-files>`/`<modified-files>` metadata.
+
+Successive compactions utilize an incremental Delta-Merge to eliminate context degradation over long sessions. `/compaction-model` selects any custom compaction model (e.g. `factory/gemini-3.7-flash`, `cursor/cursor-grok-4.5-fast`) or defaults to inheriting the active session model (`inherit`). `/smart-compaction` toggles or inspects compaction configuration stored in `<agent-dir>/smart-compaction.json`.
+
 ### [Background terminals](../extensions/background-terminals/README.md)
 
 Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.

package/extensions/smart-compaction/README.md

@@ -0,0 +1,49 @@
+# Smart Compaction Extension
+
+A high-fidelity context continuity synthesizer for Pi sessions that replaces standard compaction with an advanced multi-phase checkpoint engine.
+
+## Overview
+
+When a coding agent session reaches context limits, standard compaction often degrades in subtle code nuances, drops uncommitted code snippets, or suffers from "telephone game" information loss across successive compactions.
+
+**Smart Compaction** solves this by generating structured, high-density checkpoint summaries organized into 6 vital engineering dimensions:
+
+1. **🎯 Primary Goal & Nuanced Intent** — Retains full user objectives, styling preferences, scope boundaries, and explicit negative constraints.
+2. **📋 Progress Ledger** — Strict `[x] Done`, `[ ] In Progress`, and `[!] Blocked` tracking.
+3. **🛠️ Code Changes & In-Progress Snippets** — Captures verbatim code snippets of active work and recent edits so a successor agent resumes without re-reading or guessing.
+4. **💥 Errors, Root Causes & Fixes** — Full error traces, root cause diagnostics, and verified solutions.
+5. **🧠 Key Decisions & Hypotheses** — Architectural choices, trade-offs, and discarded hypotheses.
+6. **📍 Resume Anchor & Immediate Next Action** — Verbatim quote or exact resume state with the single immediate next action.
+7. **📂 Programmatic File Operations** — Append deterministic `<read-files>` and `<modified-files>` XML blocks extracted from tool calls.
+
+## Incremental Delta-Merging
+
+When multiple compactions occur in a single long-running session, Smart Compaction utilizes a **Delta-Merge** pipeline that carries forward historical foundations while accumulating new progress, code modifications, and error solutions—eliminating context bleed over 5+ compaction cycles.
+
+## Model Selection
+
+Smart Compaction can use the **active session model** (default: `inherit`) or any dedicated fast/cost-effective model (e.g. `factory/gemini-3.7-flash`, `antigravity/gemini-2.5-flash`, `cursor/cursor-grok-4.5-fast`).
+
+## Commands
+
+- `/compaction-model` — Open interactive model picker to select the compaction model, or switch back to `inherit`.
+- `/compaction-model <provider/model>` — Set a specific compaction model directly.
+- `/smart-compaction` — View status and settings.
+- `/smart-compaction enable | disable` — Toggle smart compaction on or off.
+
+## Configuration
+
+Settings are persisted in `~/.pi/agent/smart-compaction.json`:
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "model": "inherit",
+  "thinkingLevel": "inherit"
+}
+```
+
+- `model`: `"inherit"` (uses current active session model) or explicit `"provider/model-id"`.
+- `thinkingLevel`: `"inherit"` (uses current session's thinking level) or `"off" | "low" | "medium" | "high" | "max"`.
+- `maxSummaryTokens`: optional override integer; if omitted, dynamically defaults to the model's full native output capacity (65,536–128,000+ tokens) so summaries are never artificially truncated.

package/extensions/smart-compaction/config.ts

@@ -0,0 +1,66 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface SmartCompactionConfig {
+  version: 1;
+  enabled: boolean;
+  model: string; // "inherit" or "provider/model-id"
+  thinkingLevel?: "inherit" | "off" | "low" | "medium" | "high" | "max";
+  maxSummaryTokens?: number; // optional override; defaults to model's full capacity
+}
+
+export const DEFAULT_SMART_COMPACTION_CONFIG: SmartCompactionConfig = {
+  version: 1,
+  enabled: true,
+  model: "inherit",
+  thinkingLevel: "inherit",
+};
+
+export function smartCompactionConfigPath(): string {
+  return path.join(getAgentDir(), "smart-compaction.json");
+}
+
+export function loadSmartCompactionConfig(file = smartCompactionConfigPath()): SmartCompactionConfig {
+  try {
+    if (!fs.existsSync(file)) return { ...DEFAULT_SMART_COMPACTION_CONFIG };
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<SmartCompactionConfig>;
+    return {
+      version: 1,
+      enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_SMART_COMPACTION_CONFIG.enabled,
+      model: typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : DEFAULT_SMART_COMPACTION_CONFIG.model,
+      thinkingLevel: raw.thinkingLevel && ["inherit", "off", "low", "medium", "high", "max"].includes(raw.thinkingLevel)
+        ? (raw.thinkingLevel as SmartCompactionConfig["thinkingLevel"])
+        : DEFAULT_SMART_COMPACTION_CONFIG.thinkingLevel,
+      maxSummaryTokens: typeof raw.maxSummaryTokens === "number" && raw.maxSummaryTokens > 0
+        ? raw.maxSummaryTokens
+        : undefined,
+    };
+  } catch {
+    return { ...DEFAULT_SMART_COMPACTION_CONFIG };
+  }
+}
+
+export function saveSmartCompactionConfig(config: SmartCompactionConfig, file = smartCompactionConfigPath()): void {
+  const directory = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const document: SmartCompactionConfig = {
+    version: 1,
+    enabled: config.enabled,
+    model: config.model || "inherit",
+    thinkingLevel: config.thinkingLevel ?? "inherit",
+    maxSummaryTokens: config.maxSummaryTokens,
+  };
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    fs.chmodSync(file, 0o600);
+  } finally {
+    try {
+      fs.rmSync(temporary, { force: true });
+    } catch {
+      // Best effort cleanup.
+    }
+  }
+}

package/extensions/smart-compaction/engine.ts

@@ -0,0 +1,150 @@
+import { uuidv7, type Api, type Context, type Model, type Usage } from "@earendil-works/pi-ai";
+import type { ExtensionContext, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
+import type { SmartCompactionConfig } from "./config.ts";
+import {
+  formatFileOperationsXml,
+  SMART_COMPACTION_INITIAL_PROMPT,
+  SMART_COMPACTION_SYSTEM_PROMPT,
+  SMART_COMPACTION_UPDATE_PROMPT,
+  serializeConversationForCompaction,
+} from "./prompt.ts";
+
+export function resolveCompactionModel(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  configuredModelString?: string,
+): { model: Model<Api>; isInherited: boolean } {
+  const trimmed = configuredModelString?.trim();
+  if (!trimmed || trimmed === "inherit") {
+    if (!ctx.model) {
+      throw new Error("No active session model available to inherit for compaction.");
+    }
+    return { model: ctx.model, isInherited: true };
+  }
+
+  // Parse "provider/model" or modelId
+  let candidate: Model<Api> | undefined;
+  if (trimmed.includes("/")) {
+    const [provider, ...rest] = trimmed.split("/");
+    candidate = ctx.modelRegistry.find(provider, rest.join("/"));
+  } else {
+    const available = ctx.modelRegistry.getAvailable();
+    candidate = available.find((m) => m.id === trimmed || `${m.provider}/${m.id}` === trimmed);
+  }
+
+  if (candidate) {
+    return { model: candidate, isInherited: false };
+  }
+
+  if (ctx.model) {
+    return { model: ctx.model, isInherited: true };
+  }
+
+  throw new Error(`Configured compaction model "${trimmed}" was not found in model registry.`);
+}
+
+export interface RunSmartCompactionOptions {
+  event: SessionBeforeCompactEvent;
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry" | "thinkingLevel">;
+  config: SmartCompactionConfig;
+}
+
+export interface SmartCompactionOutput {
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  usage?: Usage;
+  details?: Record<string, unknown>;
+}
+
+export async function runSmartCompaction(
+  options: RunSmartCompactionOptions,
+): Promise<SmartCompactionOutput> {
+  const { event, ctx, config } = options;
+  const { preparation, signal, customInstructions } = event;
+  signal?.throwIfAborted();
+
+  const { model, isInherited } = resolveCompactionModel(ctx, config.model);
+
+  const messagesToSummarize = [
+    ...(preparation.messagesToSummarize ?? []),
+    ...(preparation.turnPrefixMessages ?? []),
+  ];
+
+  // Serialize messages for the context summary
+  const conversationText = serializeConversationForCompaction(messagesToSummarize);
+
+  const previousSummary = preparation.previousSummary?.trim();
+  const baseInstruction = previousSummary ? SMART_COMPACTION_UPDATE_PROMPT : SMART_COMPACTION_INITIAL_PROMPT;
+
+  let promptContent = `<conversation>\n${conversationText}\n</conversation>\n\n`;
+  if (previousSummary) {
+    promptContent += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
+  }
+  promptContent += baseInstruction;
+
+  if (customInstructions?.trim()) {
+    promptContent += `\n\n## Additional User Instructions:\n${customInstructions.trim()}`;
+  }
+
+  const context: Context = {
+    systemPrompt: SMART_COMPACTION_SYSTEM_PROMPT,
+    messages: [
+      {
+        role: "user",
+        content: [{ type: "text", text: promptContent }],
+        timestamp: Date.now(),
+      },
+    ],
+  };
+
+  const completeOptions: Record<string, unknown> = {
+    signal,
+    cacheRetention: "none",
+    sessionId: uuidv7(),
+  };
+
+  // If user explicitly configured a maxSummaryTokens override, pass it.
+  // Otherwise, omit maxTokens so the provider uses the model's full native maximum output capacity (e.g. 128k, 65k).
+  if (typeof config.maxSummaryTokens === "number" && config.maxSummaryTokens > 0) {
+    completeOptions.maxTokens = config.maxSummaryTokens;
+  }
+
+  // Resolve reasoning effort / thinking level
+  if (model.reasoning) {
+    const desiredThinking = config.thinkingLevel === "inherit" || !config.thinkingLevel
+      ? ctx.thinkingLevel
+      : config.thinkingLevel;
+
+    if (desiredThinking && desiredThinking !== "off") {
+      completeOptions.reasoning = desiredThinking;
+    }
+  }
+
+  const response = await ctx.modelRegistry.complete(model, context, completeOptions as any);
+  signal?.throwIfAborted();
+
+  const rawSummaryText = response.content
+    .filter((part): part is { type: "text"; text: string } => part.type === "text")
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+
+  if (!rawSummaryText) {
+    throw new Error("Compaction model returned an empty summary.");
+  }
+
+  const fileOpsXml = formatFileOperationsXml(preparation.fileOps);
+  const finalSummary = `${rawSummaryText}${fileOpsXml}`;
+
+  return {
+    summary: finalSummary,
+    firstKeptEntryId: preparation.firstKeptEntryId,
+    tokensBefore: preparation.tokensBefore,
+    usage: response.usage,
+    details: {
+      customCompactor: "smart-compaction",
+      model: `${model.provider}/${model.id}`,
+      isInherited,
+    },
+  };
+}

package/extensions/smart-compaction/index.ts

@@ -0,0 +1,192 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  ExtensionUIContext,
+  SessionBeforeCompactEvent,
+} from "@earendil-works/pi-coding-agent";
+import {
+  loadSmartCompactionConfig,
+  saveSmartCompactionConfig,
+  type SmartCompactionConfig,
+} from "./config.ts";
+import { runSmartCompaction } from "./engine.ts";
+
+const STATUS_KEY = "smart-compaction";
+
+export interface SmartCompactionExtensionOptions {
+  configFile?: string;
+}
+
+export function createSmartCompactionExtension(options: SmartCompactionExtensionOptions = {}) {
+  return (pi: ExtensionAPI) => {
+    let config: SmartCompactionConfig = loadSmartCompactionConfig(options.configFile);
+    let ui: ExtensionUIContext | undefined;
+
+    const updateStatus = () => {
+      if (!ui) return;
+      if (!config.enabled) {
+        ui.setStatus(STATUS_KEY, undefined);
+        return;
+      }
+      const modelLabel = config.model === "inherit" ? "inherit" : config.model.split("/").pop() ?? config.model;
+      ui.setStatus(STATUS_KEY, `compact: ${modelLabel}`);
+    };
+
+    pi.on("session_start", (_event, ctx) => {
+      ui = ctx.ui;
+      updateStatus();
+    });
+
+    pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
+      if (!config.enabled) {
+        return undefined;
+      }
+
+      try {
+        const compaction = await runSmartCompaction({
+          event,
+          ctx,
+          config,
+        });
+        return { compaction };
+      } catch (error) {
+        if (event.signal.aborted) {
+          throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui?.notify(`Smart Compaction failed: ${message}. Falling back to default compactor.`, "warning");
+        return undefined;
+      }
+    });
+
+    pi.on("session_compact", (event, ctx) => {
+      if (event.fromExtension) {
+        const details = event.compactionEntry.details as Record<string, unknown> | undefined;
+        if (details?.customCompactor === "smart-compaction") {
+          const model = String(details.model ?? "session model");
+          ctx.ui?.notify(`Smart Compaction completed (${model})`, "info");
+        }
+      }
+    });
+
+    // Slash command: /compaction-model
+    pi.registerCommand("compaction-model", {
+      description: "Select or view the model used for smart context compaction (default: inherit).",
+      handler: async (args: string, cmdCtx: ExtensionCommandContext) => {
+        const requested = args.trim();
+
+        if (requested) {
+          if (requested === "inherit") {
+            config.model = "inherit";
+            saveSmartCompactionConfig(config, options.configFile);
+            updateStatus();
+            cmdCtx.ui.notify("Compaction model set to: inherit (active session model)", "info");
+            return;
+          }
+
+          // Validate if model exists in registry
+          const available = cmdCtx.modelRegistry.getAvailable();
+          const match = available.find(
+            (m) => m.id === requested || `${m.provider}/${m.id}` === requested,
+          );
+
+          if (!match) {
+            cmdCtx.ui.notify(`Model "${requested}" not found in available models. Setting anyway.`, "warning");
+          }
+
+          config.model = match ? `${match.provider}/${match.id}` : requested;
+          saveSmartCompactionConfig(config, options.configFile);
+          updateStatus();
+          cmdCtx.ui.notify(`Compaction model set to: ${config.model}`, "info");
+          return;
+        }
+
+        if (cmdCtx.hasUI) {
+          const available = cmdCtx.modelRegistry.getAvailable();
+          const choices = [
+            `inherit (active session model: ${cmdCtx.model ? `${cmdCtx.model.provider}/${cmdCtx.model.id}` : "none"})`,
+            ...available.map((m) => `${m.provider}/${m.id}`),
+          ];
+
+          const selected = await cmdCtx.ui.select(
+            `Select Compaction Model (current: ${config.model})`,
+            choices,
+          );
+
+          if (!selected) return;
+
+          if (selected.startsWith("inherit")) {
+            config.model = "inherit";
+          } else {
+            config.model = selected;
+          }
+
+          saveSmartCompactionConfig(config, options.configFile);
+          updateStatus();
+          cmdCtx.ui.notify(`Compaction model set to: ${config.model}`, "info");
+          return;
+        }
+
+        cmdCtx.ui.notify(
+          `Compaction model: ${config.model}. Usage: /compaction-model [inherit|<provider/model>]`,
+          "info",
+        );
+      },
+    });
+
+    // Slash command: /smart-compaction
+    pi.registerCommand("smart-compaction", {
+      description: "Manage smart context compaction settings (enable/disable/status).",
+      handler: async (args: string, cmdCtx: ExtensionCommandContext) => {
+        const sub = args.trim().toLowerCase();
+        if (sub === "enable" || sub === "on") {
+          config.enabled = true;
+          saveSmartCompactionConfig(config, options.configFile);
+          updateStatus();
+          cmdCtx.ui.notify("Smart Compaction enabled.", "info");
+          return;
+        }
+        if (sub === "disable" || sub === "off") {
+          config.enabled = false;
+          saveSmartCompactionConfig(config, options.configFile);
+          updateStatus();
+          cmdCtx.ui.notify("Smart Compaction disabled (using default compactor).", "info");
+          return;
+        }
+        if (sub.startsWith("model ")) {
+          const target = args.trim().slice(6).trim();
+          config.model = target || "inherit";
+          saveSmartCompactionConfig(config, options.configFile);
+          updateStatus();
+          cmdCtx.ui.notify(`Smart Compaction model set to: ${config.model}`, "info");
+          return;
+        }
+
+        // Default status
+        const currentModelDesc = config.model === "inherit"
+          ? `inherit (${cmdCtx.model ? `${cmdCtx.model.provider}/${cmdCtx.model.id}` : "active session model"})`
+          : config.model;
+        const currentThinkingDesc = config.thinkingLevel === "inherit"
+          ? `inherit (${cmdCtx.thinkingLevel ?? "session default"})`
+          : (config.thinkingLevel ?? "inherit");
+        const maxTokensDesc = config.maxSummaryTokens ? `${config.maxSummaryTokens}` : "unlimited (full model output capacity)";
+
+        const status = [
+          `Smart Compaction: ${config.enabled ? "ENABLED" : "DISABLED"}`,
+          `Model: ${currentModelDesc}`,
+          `Thinking Level: ${currentThinkingDesc}`,
+          `Max Output Tokens: ${maxTokensDesc}`,
+          "",
+          "Commands:",
+          "  /smart-compaction enable | disable",
+          "  /compaction-model [inherit | <provider/model>]",
+        ].join("\n");
+
+        cmdCtx.ui.notify(status, "info");
+      },
+    });
+  };
+}
+
+export default createSmartCompactionExtension();

package/extensions/smart-compaction/prompt.ts

@@ -0,0 +1,194 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+export const SMART_COMPACTION_SYSTEM_PROMPT = `You are a high-fidelity context continuity synthesizer for an autonomous coding agent.
+Your task is to analyze the preceding conversation and produce a comprehensive, structured checkpoint summary.
+The successor agent will rely SOLELY on your summary to resume complex engineering tasks without losing context, nuance, or mid-stream progress.
+
+CRITICAL DIRECTIVES:
+1. Preserve exact file paths, shell commands, and error messages verbatim.
+2. Include actual code snippets for active work or uncommitted changes—never just describe what code was changed.
+3. Explicitly maintain all user-stated negative constraints (e.g., "do not modify X", "never use Y").
+4. Do NOT execute tools or continue the conversation. Respond ONLY with the requested structured summary.`;
+
+export const SMART_COMPACTION_INITIAL_PROMPT = `Analyze the conversation in the <conversation> tags above and produce a structured context checkpoint summary.
+
+Use this EXACT format and include all numbered sections:
+
+## 1. Primary Goal & Nuanced Intent
+- **Objective**: Detailed statement of what the user is trying to accomplish.
+- **Constraints & Preferences**: All explicit user constraints, negative rules, styling conventions, and architectural boundaries (or "(none)").
+
+## 2. Progress Ledger
+### Done
+- [x] [Completed task, file modification, or command]
+
+### In Progress
+- [ ] [Active task or mid-stream operation]
+
+### Blocked / Open Issues
+- [Any active errors, blockers, or pending decisions]
+
+## 3. Code Changes & In-Progress Snippets
+For every modified, created, or in-flight file:
+- **\`path/to/file\`**: State why it was changed and provide verbatim code snippets of the latest edits or new functions so work can resume immediately without re-reading.
+
+## 4. Errors, Root Causes & Fixes
+- **Error**: [Verbatim error message or failed command output]
+- **Root Cause**: [Exact reason for the failure]
+- **Fix**: [How it was fixed or the approach currently being attempted]
+(Or "None" if no errors occurred)
+
+## 5. Key Decisions & Hypotheses
+- **[Decision / Architecture]**: [Rationale, alternatives considered, and discarded approaches]
+
+## 6. Resume Anchor & Immediate Next Action
+- **Last State**: Precisely what was happening before this summary request.
+- **Next Concrete Step**: The single immediate next action to take, directly aligned with the user's latest request.
+
+Keep the prose economical and high-density. Do NOT pad with fluff.`;
+
+export const SMART_COMPACTION_UPDATE_PROMPT = `The <conversation> tags above contain NEW conversation turns that occurred after the checkpoint in <previous-summary>.
+Synthesize the new turns into the existing summary using a unified Delta-Merge.
+
+DELTA-MERGING RULES:
+1. PRESERVE all historical goals, constraints, and decisions from <previous-summary>.
+2. UPDATE the Progress Ledger: check off items that have finished and add new in-flight tasks.
+3. ACCUMULATE Code Changes: add new code snippets for newly modified files while retaining existing relevant snippets.
+4. RECORD new errors, root causes, and resolutions encountered in the new turns.
+5. UPDATE the Resume Anchor and Next Step to reflect the current active frontier.
+6. PRESERVE exact file paths, commands, and code snippets verbatim.
+
+Use this EXACT format:
+
+## 1. Primary Goal & Nuanced Intent
+- **Objective**: [Preserve initial goal, add new objectives if scope expanded]
+- **Constraints & Preferences**: [Preserve existing constraints, add newly stated ones]
+
+## 2. Progress Ledger
+### Done
+- [x] [Previously completed items AND newly completed items]
+
+### In Progress
+- [ ] [Current active tasks]
+
+### Blocked / Open Issues
+- [Active blockers or "None"]
+
+## 3. Code Changes & In-Progress Snippets
+[Accumulated modified/created files with verbatim code snippets of recent work]
+
+## 4. Errors, Root Causes & Fixes
+[Accumulated errors, root causes, and fixes from the full session]
+
+## 5. Key Decisions & Hypotheses
+[Accumulated architectural decisions and trade-offs]
+
+## 6. Resume Anchor & Immediate Next Action
+- **Last State**: [Exact state immediately before this checkpoint]
+- **Next Concrete Step**: [The single immediate next action]`;
+
+const MAX_TOOL_RESULT_CHARS = 2500;
+
+function truncateText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const remaining = text.length - maxChars;
+  return `${text.slice(0, maxChars)}\n\n[... ${remaining} characters truncated for summary ...]`;
+}
+
+function extractTextContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (part && typeof part === "object" && "text" in part && typeof part.text === "string") {
+          return part.text;
+        }
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}
+
+export function serializeConversationForCompaction(messages: AgentMessage[]): string {
+  const parts: string[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      const text = extractTextContent((msg as any).content);
+      if (text) parts.push(`[User]:\n${text}`);
+    } else if (msg.role === "assistant") {
+      const content = (msg as any).content;
+      const thinkingBlocks: string[] = [];
+      const toolCallBlocks: string[] = [];
+      const textBlocks: string[] = [];
+
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (!block || typeof block !== "object") continue;
+          if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking.trim()) {
+            thinkingBlocks.push(block.thinking.trim());
+          } else if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+            textBlocks.push(block.text.trim());
+          } else if (block.type === "toolCall") {
+            const args = block.arguments as Record<string, unknown>;
+            const formattedArgs = Object.entries(args ?? {})
+              .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+              .join(", ");
+            toolCallBlocks.push(`${block.name}(${formattedArgs})`);
+          }
+        }
+      } else if (typeof content === "string" && content.trim()) {
+        textBlocks.push(content.trim());
+      }
+
+      if (thinkingBlocks.length > 0) {
+        const combinedThinking = thinkingBlocks.join("\n");
+        parts.push(`[Assistant Thinking]:\n${truncateText(combinedThinking, 1500)}`);
+      }
+      if (textBlocks.length > 0) {
+        parts.push(`[Assistant]:\n${textBlocks.join("\n")}`);
+      }
+      if (toolCallBlocks.length > 0) {
+        parts.push(`[Assistant Tool Calls]:\n${toolCallBlocks.join("\n")}`);
+      }
+    } else if (msg.role === "toolResult") {
+      const text = extractTextContent((msg as any).content);
+      if (text) {
+        parts.push(`[Tool Result]:\n${truncateText(text, MAX_TOOL_RESULT_CHARS)}`);
+      }
+    } else if (msg.role === "custom") {
+      const text = extractTextContent((msg as any).content);
+      if (text) parts.push(`[System Event]:\n${text}`);
+    } else if (msg.role === "bashExecution") {
+      const cmd = (msg as any).command ?? "";
+      const out = (msg as any).output ?? "";
+      parts.push(`[Command Executed]:\n$ ${cmd}\n${truncateText(out, 1500)}`);
+    } else if (msg.role === "compactionSummary" || msg.role === "branchSummary") {
+      const summary = (msg as any).summary ?? "";
+      if (summary) parts.push(`[Prior Summary]:\n${summary}`);
+    }
+  }
+
+  return parts.join("\n\n---\n\n");
+}
+
+export function formatFileOperationsXml(fileOps?: { read?: Iterable<string>; written?: Iterable<string>; edited?: Iterable<string> }): string {
+  if (!fileOps) return "";
+  const readSet = new Set(fileOps.read ?? []);
+  const modifiedSet = new Set([...(fileOps.written ?? []), ...(fileOps.edited ?? [])]);
+  const readOnly = [...readSet].filter((f) => !modifiedSet.has(f)).sort();
+  const modified = [...modifiedSet].sort();
+
+  const sections: string[] = [];
+  if (readOnly.length > 0) {
+    sections.push(`<read-files>\n${readOnly.join("\n")}\n</read-files>`);
+  }
+  if (modified.length > 0) {
+    sections.push(`<modified-files>\n${modified.join("\n")}\n</modified-files>`);
+  }
+  if (sections.length === 0) return "";
+  return `\n\n${sections.join("\n\n")}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",
@@ -52,6 +52,7 @@
       "./extensions/performance-status/index.ts",
       "./extensions/pi-memory/index.ts",
       "./extensions/shell-shortcuts/index.ts",
+      "./extensions/smart-compaction/index.ts",
       "./extensions/subagents/index.ts",
       "./extensions/web-fetch/index.ts"
     ],