shariq-pi-extensions 0.2.9 → 0.2.11

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/cursor-provider/README.md

@@ -22,12 +22,12 @@ Secrets are passed directly to the SDK and are never placed in command arguments
 - Refreshes Cursor's authenticated model catalog and caches only Composer and Cursor Grok metadata for the next extension reload.
 - Exposes image input for every registered Cursor model.
 - Maps Composer fast mode and Cursor Grok reasoning effort to native model parameters.
-- Uses the SDK's local hosted-model runtime in an isolated temporary workspace with ambient Cursor settings disabled.
+- Uses the SDK's local hosted-model runtime with warm agent instance pooling and ambient Cursor settings (`settingSources: []`) disabled.
 - Disables Cursor's built-in workspace tools and exposes Pi's active tools as native SDK custom tools. Tool execution remains owned by Pi.
 - Streams native text and thinking deltas, structured tool calls, stop reasons, and Cursor-reported input/output/cache/reasoning usage.
-- Propagates cancellation and timeouts, enables safe SDK transport retries, and maps common authentication, rate-limit, quota, capacity, timeout, and context failures to actionable Pi errors.
+- Propagates cancellation and timeouts, enables safe SDK transport retries, redacts credential literals from error traces, and maps common authentication, rate-limit, quota, capacity, timeout, and context failures to actionable Pi errors.
 - Forwards base64 image payloads separately from the textual conversation transcript.
-- Removes temporary workspace and SDK state after each request.
+- Automatically cleans up warm agent workspaces on idle TTL and session shutdown.
 
 ## Cursor dashboard
 

package/extensions/cursor-provider/cursor/stream.ts

@@ -21,6 +21,8 @@ import {
 import { loadCursorCatalog, resolveCursorModelSelection } from "./models.ts";
 
 const TOOL_DELEGATION_RESULT = "Tool execution was delegated to Pi. End this run without further output.";
+const MAX_CACHED_AGENTS = 8;
+const AGENT_IDLE_TTL_MS = 10 * 60 * 1_000;
 
 function asJsonValue(value: unknown): SDKJsonValue {
   return JSON.parse(JSON.stringify(value ?? null)) as SDKJsonValue;
@@ -30,6 +32,13 @@ function asArguments(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
 }
 
+export function redactCursorError(value: unknown): string {
+  return String(value ?? "Cursor request failed")
+    .replace(/crsr_[A-Za-z0-9_-]+/g, "[REDACTED]")
+    .replace(/(authorization|api[-_ ]?key|token)([\s:=]+)([^\s,;]+)/gi, "$1$2[REDACTED]")
+    .slice(0, 4096);
+}
+
 export function serializeCursorContext(context: Context): { text: string; images: SDKImage[] } {
   const lines = [
     "Continue the Pi conversation below as the assistant.",
@@ -45,6 +54,9 @@ export function serializeCursorContext(context: Context): { text: string; images
 
   for (const message of context.messages) {
     lines.push(`<message role=${JSON.stringify(message.role)}>`);
+    if (message.role === "toolResult") {
+      lines.push(`[Tool result for ${(message as any).toolCallId || "unknown"}; error=${Boolean((message as any).isError)}]`);
+    }
     if (typeof message.content === "string") {
       lines.push(message.content);
     } else if (Array.isArray(message.content)) {
@@ -58,9 +70,6 @@ export function serializeCursorContext(context: Context): { text: string; images
         }
       }
     }
-    if (message.role === "toolResult") {
-      lines.push(`[Tool result for ${(message as any).toolCallId}; error=${Boolean((message as any).isError)}]`);
-    }
     lines.push("</message>");
   }
   lines.push("</conversation>");
@@ -81,7 +90,7 @@ function usageFromCursor(usage: TokenUsage | undefined, output: AssistantMessage
 }
 
 export function formatCursorError(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = redactCursorError(error instanceof Error ? error.message : error);
   if (/401|403|unauth|api key|credential/i.test(message)) return "Cursor authentication failed. Run `/login cursor`, then retry.";
   if (/429|rate.?limit/i.test(message)) return "Cursor rate limit reached. Wait for the reported reset, then retry.";
   if (/quota|usage limit|billing|credit|exhaust/i.test(message)) return "Cursor usage limit reached. Open `/cursor` for account status and reset information.";
@@ -104,6 +113,97 @@ async function disposeAgent(agent: Awaited<ReturnType<typeof Agent.create>> | un
   }
 }
 
+interface ActiveToolHandler {
+  onToolCall(toolName: string, args: unknown, toolCallId?: string): void;
+}
+
+interface CachedAgentEntry {
+  agent: Awaited<ReturnType<typeof Agent.create>>;
+  workspace: string;
+  activeHandlerRef: { current: ActiveToolHandler | null };
+  lastUsedAt: number;
+}
+
+const agentPool = new Map<string, CachedAgentEntry>();
+
+async function disposeCachedEntry(entry: CachedAgentEntry): Promise<void> {
+  await disposeAgent(entry.agent);
+  await rm(entry.workspace, { recursive: true, force: true }).catch(() => undefined);
+}
+
+export async function clearCursorAgentPool(): Promise<void> {
+  const entries = [...agentPool.values()];
+  agentPool.clear();
+  await Promise.allSettled(entries.map(disposeCachedEntry));
+}
+
+async function getOrInitWarmAgent(
+  apiKey: string,
+  selection: ReturnType<typeof resolveCursorModelSelection>,
+  tools: Context["tools"],
+  activeHandler: ActiveToolHandler,
+  enableRetries: boolean,
+): Promise<{ agent: Awaited<ReturnType<typeof Agent.create>>; activeHandlerRef: { current: ActiveToolHandler | null } }> {
+  const toolSignatures = (tools ?? []).map((t) => ({ name: t.name, schema: t.parameters ?? null }));
+  const cacheKey = JSON.stringify({ key: apiKey, model: selection, tools: toolSignatures });
+
+  const existing = agentPool.get(cacheKey);
+  if (existing) {
+    existing.lastUsedAt = Date.now();
+    existing.activeHandlerRef.current = activeHandler;
+    return { agent: existing.agent, activeHandlerRef: existing.activeHandlerRef };
+  }
+
+  // Evict oldest or expired agents if pool is full
+  const now = Date.now();
+  for (const [key, entry] of [...agentPool.entries()]) {
+    if (now - entry.lastUsedAt > AGENT_IDLE_TTL_MS) {
+      agentPool.delete(key);
+      void disposeCachedEntry(entry);
+    }
+  }
+  if (agentPool.size >= MAX_CACHED_AGENTS) {
+    const oldestKey = [...agentPool.entries()].sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)[0]?.[0];
+    if (oldestKey) {
+      const oldest = agentPool.get(oldestKey);
+      agentPool.delete(oldestKey);
+      if (oldest) void disposeCachedEntry(oldest);
+    }
+  }
+
+  const workspace = await mkdtemp(join(tmpdir(), "pi-cursor-sdk-"));
+  const activeHandlerRef = { current: activeHandler as ActiveToolHandler | null };
+
+  const customTools: Record<string, SDKCustomTool> = {};
+  for (const tool of tools ?? []) {
+    customTools[tool.name] = {
+      description: tool.description,
+      inputSchema: asJsonValue(tool.parameters ?? { type: "object" }) as Record<string, SDKJsonValue>,
+      async execute(args, toolContext) {
+        activeHandlerRef.current?.onToolCall(tool.name, args, toolContext.toolCallId);
+        return { content: [{ type: "text", text: TOOL_DELEGATION_RESULT }], isError: true };
+      },
+    };
+  }
+
+  const agent = await Agent.create({
+    apiKey,
+    model: selection,
+    tools: tools?.length ? ["mcp"] : [],
+    local: {
+      cwd: workspace,
+      store: new JsonlLocalAgentStore(join(workspace, "state")),
+      customTools,
+      settingSources: [],
+      enableAgentRetries: enableRetries,
+    },
+  });
+
+  const entry: CachedAgentEntry = { agent, workspace, activeHandlerRef, lastUsedAt: Date.now() };
+  agentPool.set(cacheKey, entry);
+  return { agent, activeHandlerRef };
+}
+
 export function streamCursorSdk(model: Model<any>, context: Context, options?: ProviderStreamOptions) {
   const stream = createAssistantMessageEventStream();
   const output: AssistantMessage = {
@@ -119,8 +219,6 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
   stream.push({ type: "start", partial: output });
 
   void (async () => {
-    let workspace: string | undefined;
-    let agent: Awaited<ReturnType<typeof Agent.create>> | undefined;
     let run: Run | undefined;
     let timeout: ReturnType<typeof setTimeout> | undefined;
     let textIndex: number | undefined;
@@ -168,47 +266,31 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
       const apiKey = options?.apiKey?.trim();
       if (!apiKey) throw new Error("Cursor is not authenticated. Run `/login cursor`.");
       if (options?.signal?.aborted) throw new Error("Cursor request cancelled.");
-      workspace = await mkdtemp(join(tmpdir(), "pi-cursor-sdk-"));
-      const customTools: Record<string, SDKCustomTool> = {};
-      for (const tool of context.tools ?? []) {
-        customTools[tool.name] = {
-          description: tool.description,
-          inputSchema: asJsonValue(tool.parameters ?? { type: "object" }) as Record<string, SDKJsonValue>,
-          async execute(args, toolContext) {
-            if (!delegated) {
-              delegated = true;
-              endText();
-              endReasoning();
-              const toolCall = {
-                type: "toolCall" as const,
-                id: toolContext.toolCallId || `cursor_${randomUUID()}`,
-                name: tool.name,
-                arguments: asArguments(args),
-              };
-              const contentIndex = output.content.length;
-              output.content.push(toolCall);
-              stream.push({ type: "toolcall_start", contentIndex, partial: output });
-              stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(toolCall.arguments), partial: output });
-              stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
-              queueMicrotask(() => { void run?.cancel().catch(() => undefined); });
-            }
-            return { content: [{ type: "text", text: TOOL_DELEGATION_RESULT }], isError: true };
-          },
-        };
-      }
 
-      const selection = resolveCursorModelSelection(model, typeof options?.reasoning === "string" ? options.reasoning : undefined, loadCursorCatalog());
-      agent = await Agent.create({
-        apiKey,
-        model: selection,
-        tools: context.tools?.length ? ["mcp"] : [],
-        local: {
-          cwd: workspace,
-          store: new JsonlLocalAgentStore(join(workspace, "state")),
-          customTools,
-          enableAgentRetries: options?.maxRetries !== 0,
+      const activeHandler: ActiveToolHandler = {
+        onToolCall(toolName, args, toolCallId) {
+          if (!delegated) {
+            delegated = true;
+            endText();
+            endReasoning();
+            const toolCall = {
+              type: "toolCall" as const,
+              id: toolCallId || `cursor_${randomUUID()}`,
+              name: toolName,
+              arguments: asArguments(args),
+            };
+            const contentIndex = output.content.length;
+            output.content.push(toolCall);
+            stream.push({ type: "toolcall_start", contentIndex, partial: output });
+            stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(toolCall.arguments), partial: output });
+            stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
+            queueMicrotask(() => { void run?.cancel().catch(() => undefined); });
+          }
         },
-      });
+      };
+
+      const selection = resolveCursorModelSelection(model, typeof options?.reasoning === "string" ? options.reasoning : undefined, loadCursorCatalog());
+      const { agent } = await getOrInitWarmAgent(apiKey, selection, context.tools, activeHandler, options?.maxRetries !== 0);
 
       const request = serializeCursorContext(context);
       run = await agent.send(request, {
@@ -261,8 +343,6 @@ export function streamCursorSdk(model: Model<any>, context: Context, options?: P
       stream.end();
     } finally {
       if (timeout) clearTimeout(timeout);
-      await disposeAgent(agent);
-      if (workspace) await rm(workspace, { recursive: true, force: true }).catch(() => undefined);
     }
   })();
 

package/extensions/cursor-provider/index.ts

@@ -9,7 +9,7 @@ import {
   loadCursorCatalog,
   toCursorPiModels,
 } from "./cursor/models.ts";
-import { streamCursorSdk } from "./cursor/stream.ts";
+import { clearCursorAgentPool, streamCursorSdk } from "./cursor/stream.ts";
 import { fetchCursorUsage } from "./cursor/usage.ts";
 
 export default async function cursorProviderExtension(pi: ExtensionAPI) {
@@ -50,6 +50,10 @@ export default async function cursorProviderExtension(pi: ExtensionAPI) {
     (ctx.modelRegistry as any).authStorage?.reload?.();
   });
 
+  pi.on("session_shutdown", async () => {
+    await clearCursorAgentPool();
+  });
+
   pi.registerCommand("cursor", {
     description: "Open Cursor account, monthly usage, and limits dashboard",
     handler: async (_args, ctx) => {
@@ -83,6 +87,7 @@ export default async function cursorProviderExtension(pi: ExtensionAPI) {
     deactivate: async () => {
       try {
         pi.unregisterProvider(CURSOR_PROVIDER_ID);
+        await clearCursorAgentPool();
       } catch {
         // Ignore teardown after partial startup.
       }

package/extensions/smart-compaction/README.md

@@ -0,0 +1,46 @@
+# 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": "medium",
+  "maxSummaryTokens": 16384
+}
+```

package/extensions/smart-compaction/config.ts

@@ -0,0 +1,67 @@
+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?: "off" | "low" | "medium" | "high";
+  maxSummaryTokens?: number;
+}
+
+export const DEFAULT_SMART_COMPACTION_CONFIG: SmartCompactionConfig = {
+  version: 1,
+  enabled: true,
+  model: "inherit",
+  thinkingLevel: "medium",
+  maxSummaryTokens: 16384,
+};
+
+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 && ["off", "low", "medium", "high"].includes(raw.thinkingLevel)
+        ? raw.thinkingLevel
+        : DEFAULT_SMART_COMPACTION_CONFIG.thinkingLevel,
+      maxSummaryTokens: typeof raw.maxSummaryTokens === "number" && raw.maxSummaryTokens > 0
+        ? raw.maxSummaryTokens
+        : DEFAULT_SMART_COMPACTION_CONFIG.maxSummaryTokens,
+    };
+  } 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 ?? "medium",
+    maxSummaryTokens: config.maxSummaryTokens ?? 16384,
+  };
+  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,141 @@
+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">;
+  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 requestedMaxTokens = config.maxSummaryTokens ?? 16384;
+  const maxTokens = model.maxTokens > 0 ? Math.min(requestedMaxTokens, model.maxTokens) : requestedMaxTokens;
+
+  const completeOptions: Record<string, unknown> = {
+    maxTokens,
+    signal,
+    cacheRetention: "none",
+    sessionId: uuidv7(),
+  };
+
+  if (model.reasoning && config.thinkingLevel && config.thinkingLevel !== "off") {
+    completeOptions.reasoning = config.thinkingLevel;
+  }
+
+  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,184 @@
+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 status = [
+          `Smart Compaction: ${config.enabled ? "ENABLED" : "DISABLED"}`,
+          `Model: ${config.model} (${config.model === "inherit" ? (cmdCtx.model ? `${cmdCtx.model.provider}/${cmdCtx.model.id}` : "inherit") : config.model})`,
+          `Thinking Level: ${config.thinkingLevel ?? "medium"}`,
+          `Max Tokens: ${config.maxSummaryTokens ?? 4096}`,
+          "",
+          "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.9",
+  "version": "0.2.11",
   "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"
     ],