@pi-vault/pi-dcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-06-15
+
+### Added
+- Dynamic context pruning for Pi sessions, including stale duplicate tool-output removal.
+- Error-pruning strategies that clear old failed tool results after they stop being useful.
+- A `compress` tool with range-based and message-based compression modes.
+- DCP message IDs, compression block tracking, and proactive high-context nudges.
+- Slash commands for operational control: `dcp:help`, `dcp:context`, `dcp:stats`, `dcp:sweep`, `dcp:manual`, `dcp:decompress`, `dcp:recompress`, and `dcp:lifetime`.
+- Session-state persistence, lifetime statistics, debug logging, and status-bar reporting.
+- Vitest coverage across config loading, strategies, message transforms, compression state, commands, persistence, pipeline behavior, and end-to-end extension lifecycle integration.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanh Hoang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# pi-dcp
+
+Keep long Pi sessions usable by pruning stale tool output and nudging the model to compress old context before the window fills up.
+
+## Install
+
+Install from npm with Pi:
+
+```bash
+pi install npm:@pi-vault/pi-dcp
+```
+
+Then restart Pi.
+
+To try the repo locally before publishing:
+
+```bash
+pi -e /absolute/path/to/pi-dcp
+```
+
+## Configure
+
+Create `~/.pi/agent/extensions/dcp.json`:
+
+```json
+{
+  "enabled": true,
+  "debug": false,
+  "compress": {
+    "mode": "range",
+    "permission": "allow",
+    "maxContextPercent": 80,
+    "minContextPercent": 50,
+    "nudgeFrequency": 5
+  },
+  "strategies": {
+    "deduplication": { "enabled": true },
+    "purgeErrors": { "enabled": true, "turns": 4 }
+  }
+}
+```
+
+All fields are optional. If the file is missing, pi-dcp uses built-in defaults.
+
+## What it does
+
+- Removes stale duplicate tool outputs automatically
+- Prunes older error-heavy tool results that no longer help the model
+- Injects context warnings before the conversation gets too large
+- Exposes a `compress` tool so the model can summarize older context instead of losing it
+
+## Common commands
+
+- `dcp:help` — list available commands
+- `dcp:context` — show current context usage and active compression state
+- `dcp:stats` — show session token savings and compression counts
+- `dcp:sweep` — force-prune all currently eligible tool outputs
+- `dcp:manual on` — pause automatic compression and switch to manual control
+- `dcp:manual off` — resume automatic compression
+- `dcp:decompress <blockId>` — restore a compressed block
+- `dcp:recompress <blockId>` — reactivate a decompressed block
+- `dcp:lifetime` — show aggregate stats across saved sessions
+
+## Recommended usage
+
+1. Install the package and start with the default config.
+2. Let automatic pruning handle duplicate and stale outputs.
+3. Use `dcp:stats` when you want to confirm token savings.
+4. Turn on `dcp:manual on` if you want to decide when compression happens.
+5. Use `dcp:sweep` before a long design or debugging session if the context already contains a lot of dead tool output.
+
+## Debug logging
+
+Set `"debug": true` in `~/.pi/agent/extensions/dcp.json` to write logs to:
+
+```text
+{sessionDir}/dcp/logs/YYYY-MM-DD.log
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm run check
+pnpm run release:check
+```

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pi-vault/pi-dcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension for dynamic context pruning — incremental tool output pruning and conversation compression",
+  "author": "Lanh Hoang <lanhhoang@users.noreply.github.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/pi-vault/pi-dcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pi-vault/pi-dcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pi-vault/pi-dcp/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-package",
+    "pi-extension",
+    "pi-dcp",
+    "context-pruning",
+    "compression"
+  ],
+  "scripts": {
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "biome lint . && tsc --noEmit && vitest run",
+    "pack:dry-run": "pnpm pack --dry-run",
+    "release:check": "pnpm check && pnpm run pack:dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@earendil-works/pi-agent-core": "^0.79.4",
+    "@earendil-works/pi-coding-agent": "^0.79.4",
+    "@types/node": "^25.9.3",
+    "typebox": "^1.2.12",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/src/commands/context.ts

@@ -0,0 +1,25 @@
+import type { ContextUsage, SessionState } from "../state/types.ts";
+
+export function contextCommand(
+  state: SessionState,
+  contextUsage: ContextUsage | undefined,
+): string {
+  const lines: string[] = ["DCP Context Usage:"];
+
+  if (contextUsage && contextUsage.tokens != null && contextUsage.percent != null) {
+    lines.push(`  Tokens: ${contextUsage.tokens} / ${contextUsage.contextWindow} (${contextUsage.percent.toFixed(1)}%)`);
+  } else if (contextUsage) {
+    lines.push(`  Tokens: unavailable (context window: ${contextUsage.contextWindow})`);
+  } else {
+    lines.push("  Tokens: unavailable");
+  }
+
+  lines.push(`  Pruned tool outputs: ${state.prune.tools.size}`);
+  lines.push(`  Active compression blocks: ${state.prune.messages.activeBlockIds.size}`);
+  lines.push(`  Total blocks: ${state.prune.messages.blocksById.size}`);
+  lines.push(`  Tool cache entries: ${state.toolParameters.size}`);
+  lines.push(`  Current turn: ${state.currentTurn}`);
+  lines.push(`  Manual mode: ${state.manualMode || "off"}`);
+
+  return lines.join("\n");
+}

package/src/commands/decompress.ts

@@ -0,0 +1,21 @@
+import type { SessionState } from "../state/types.ts";
+
+export function decompressCommand(state: SessionState, args: string): string {
+  const blockIdStr = args.trim();
+  if (!blockIdStr) return "Usage: dcp:decompress <blockId>";
+
+  const blockId = Number.parseInt(blockIdStr, 10);
+  if (Number.isNaN(blockId)) return `Invalid block ID: ${blockIdStr}`;
+
+  const block = state.prune.messages.blocksById.get(blockId);
+  if (!block) return `Block ${blockId} not found.`;
+  if (!block.active) return `Block ${blockId} is already inactive.`;
+
+  block.active = false;
+  block.deactivatedByUser = true;
+  block.deactivatedAt = Date.now();
+  state.prune.messages.activeBlockIds.delete(blockId);
+  state.prune.messages.activeByAnchorIndex.delete(block.anchorIndex);
+
+  return `Block ${blockId} deactivated. Original messages will be restored on next context pass.`;
+}

package/src/commands/help.ts

@@ -0,0 +1,14 @@
+export function helpCommand(): string {
+  return [
+    "DCP Commands:",
+    "",
+    "  dcp:help                    - Show this help",
+    "  dcp:context                 - Show context usage breakdown",
+    "  dcp:stats                   - Show compression statistics",
+    "  dcp:sweep                   - Force-prune all eligible tool outputs",
+    "  dcp:manual [on|off]         - Toggle manual compression mode",
+    "  dcp:decompress <blockId>    - Deactivate a compression block",
+    "  dcp:recompress <blockId>    - Reactivate a deactivated block",
+    "  dcp:lifetime                - Show aggregate statistics across all sessions",
+  ].join("\n");
+}

package/src/commands/lifetime.ts

@@ -0,0 +1,13 @@
+import { loadAllSessionStats } from "../state/persistence.ts";
+
+export function lifetimeCommand(sessionsParentDir: string): string {
+  const stats = loadAllSessionStats(sessionsParentDir);
+
+  return [
+    "DCP Lifetime Statistics:",
+    `  Sessions tracked: ${stats.sessionCount} sessions`,
+    `  Total tokens saved: ${stats.totalTokensSaved}`,
+    `  Total tools pruned: ${stats.totalToolsPruned}`,
+    `  Total messages compressed: ${stats.totalMessagesCompressed}`,
+  ].join("\n");
+}

package/src/commands/manual.ts

@@ -0,0 +1,21 @@
+import type { SessionState } from "../state/types.ts";
+
+export function manualCommand(state: SessionState, args: string): string {
+  const arg = args.trim().toLowerCase();
+
+  if (!arg) {
+    return `Manual mode: ${state.manualMode || "off"}`;
+  }
+
+  if (arg === "on") {
+    state.manualMode = "active";
+    return "Manual mode: on. Automatic compression is paused.";
+  }
+
+  if (arg === "off") {
+    state.manualMode = false;
+    return "Manual mode: off. Automatic compression resumed.";
+  }
+
+  return "Usage: dcp:manual [on|off]";
+}

package/src/commands/recompress.ts

@@ -0,0 +1,22 @@
+import type { SessionState } from "../state/types.ts";
+
+export function recompressCommand(state: SessionState, args: string): string {
+  const blockIdStr = args.trim();
+  if (!blockIdStr) return "Usage: dcp:recompress <blockId>";
+
+  const blockId = Number.parseInt(blockIdStr, 10);
+  if (Number.isNaN(blockId)) return `Invalid block ID: ${blockIdStr}`;
+
+  const block = state.prune.messages.blocksById.get(blockId);
+  if (!block) return `Block ${blockId} not found.`;
+  if (block.active) return `Block ${blockId} is already active.`;
+  if (!block.deactivatedByUser) return `Block ${blockId} was not deactivated by user. Cannot reactivate.`;
+
+  block.active = true;
+  block.deactivatedByUser = false;
+  block.deactivatedAt = undefined;
+  state.prune.messages.activeBlockIds.add(blockId);
+  state.prune.messages.activeByAnchorIndex.set(block.anchorIndex, blockId);
+
+  return `Block ${blockId} reactivated. Compression will apply on next context pass.`;
+}

package/src/commands/register.ts

@@ -0,0 +1,79 @@
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SessionState } from "../state/types.ts";
+import type { DcpConfig } from "../config.ts";
+import { helpCommand } from "./help.ts";
+import { contextCommand } from "./context.ts";
+import { statsCommand } from "./stats.ts";
+import { sweepCommand } from "./sweep.ts";
+import { manualCommand } from "./manual.ts";
+import { decompressCommand } from "./decompress.ts";
+import { recompressCommand } from "./recompress.ts";
+import { lifetimeCommand } from "./lifetime.ts";
+
+export function registerDcpCommands(
+  pi: ExtensionAPI,
+  state: SessionState,
+  config: DcpConfig,
+): void {
+  pi.registerCommand("dcp:help", {
+    description: "Show DCP command help",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(helpCommand(), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:context", {
+    description: "Show context usage breakdown",
+    handler: async (_args, ctx) => {
+      const usage = ctx.getContextUsage();
+      ctx.ui.notify(
+        contextCommand(state, usage ?? undefined),
+        "info",
+      );
+    },
+  });
+
+  pi.registerCommand("dcp:stats", {
+    description: "Show compression statistics",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(statsCommand(state), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:sweep", {
+    description: "Force-prune all eligible tool outputs",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(sweepCommand(state, config), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:manual", {
+    description: "Toggle manual compression mode",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(manualCommand(state, args), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:decompress", {
+    description: "Deactivate a compression block",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(decompressCommand(state, args), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:recompress", {
+    description: "Reactivate a deactivated compression block",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(recompressCommand(state, args), "info");
+    },
+  });
+
+  pi.registerCommand("dcp:lifetime", {
+    description: "Show aggregate statistics across all sessions",
+    handler: async (_args, ctx) => {
+      const parentDir = path.resolve(ctx.sessionManager.getSessionDir(), "..");
+      ctx.ui.notify(lifetimeCommand(parentDir), "info");
+    },
+  });
+}

package/src/commands/stats.ts

@@ -0,0 +1,11 @@
+import type { SessionState } from "../state/types.ts";
+
+export function statsCommand(state: SessionState): string {
+  return [
+    "DCP Session Statistics:",
+    `  Tools pruned: ${state.stats.toolsPruned}`,
+    `  Total tokens saved (pruning): ${state.stats.totalPruneTokens}`,
+    `  Messages compressed: ${state.stats.messagesCompressed}`,
+    `  Prune token counter: ${state.stats.pruneTokenCounter}`,
+  ].join("\n");
+}

package/src/commands/sweep.ts

@@ -0,0 +1,8 @@
+import type { SessionState } from "../state/types.ts";
+import type { DcpConfig } from "../config.ts";
+import { sweepAll } from "../strategies/runner.ts";
+
+export function sweepCommand(state: SessionState, config: DcpConfig): string {
+  const result = sweepAll(state, config);
+  return `Sweep complete: ${result.pruned} tool outputs pruned, ~${result.tokensSaved} tokens saved.`;
+}

package/src/compress/handler.ts

@@ -0,0 +1,148 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionState } from "../state/types.ts";
+import type { DcpConfig } from "../config.ts";
+import { resolveBoundaryIndex, resolveSelection } from "./search.ts";
+import {
+  allocateBlockId,
+  allocateRunId,
+  applyCompressionState,
+  wrapCompressedSummary,
+  COMPRESSED_BLOCK_HEADER,
+} from "./state.ts";
+import { countTokens } from "../utils/tokens.ts";
+
+export interface CompressArgs {
+  topic: string;
+  mode: "range" | "message";
+  content?: Array<{
+    startId: string;
+    endId: string;
+    summary: string;
+  }>;
+  targets?: Array<{
+    messageId: string;
+    summary: string;
+  }>;
+}
+
+interface NormalizedEntry {
+  startIndex: number;
+  endIndex: number;
+  summary: string;
+  messageCount: number;
+}
+
+/**
+ * Handle any compress tool call regardless of mode.
+ * Normalizes input, resolves boundaries, applies compression state.
+ */
+export function handleCompress(
+  state: SessionState,
+  _config: DcpConfig,
+  messages: AgentMessage[],
+  args: CompressArgs,
+): string {
+  const entries = normalizeEntries(state, messages, args);
+  const runId = allocateRunId(state);
+  let totalCompressed = 0;
+
+  for (const entry of entries) {
+    const blockId = allocateBlockId(state);
+    const wrappedSummary = wrapCompressedSummary(blockId, entry.summary);
+    const summaryTokens = countTokens(wrappedSummary);
+    const compressMessageIndex = messages.length - 1;
+
+    applyCompressionState(state, {
+      blockId,
+      runId,
+      topic: args.topic,
+      batchTopic: args.topic,
+      mode: args.mode,
+      startIndex: entry.startIndex,
+      endIndex: entry.endIndex,
+      anchorIndex: entry.startIndex,
+      compressMessageIndex,
+      summary: wrappedSummary,
+      summaryTokens,
+      consumedBlockIds: [],
+    });
+
+    totalCompressed += entry.messageCount;
+  }
+
+  return `Compressed ${totalCompressed} messages into ${COMPRESSED_BLOCK_HEADER}.`;
+}
+
+/**
+ * Normalize range or message args into a common form.
+ * Validates input and resolves boundary IDs to indices.
+ */
+function normalizeEntries(
+  state: SessionState,
+  messages: AgentMessage[],
+  args: CompressArgs,
+): NormalizedEntry[] {
+  if (args.mode === "range") {
+    if (!args.content || args.content.length === 0) {
+      throw new Error("content array is required and must not be empty");
+    }
+
+    return args.content.map((entry) => {
+      if (!entry.startId || !entry.endId || !entry.summary) {
+        throw new Error(
+          "Each content entry requires startId, endId, and summary",
+        );
+      }
+
+      const startIndex = resolveBoundaryIndex(state, entry.startId);
+      if (startIndex === undefined) {
+        throw new Error(
+          `startId ${entry.startId} is not available. It may have been pruned or compressed. ` +
+            `Choose a message ID (m0001) or block ref (b1) visible in the current context.`,
+        );
+      }
+
+      const endIndex = resolveBoundaryIndex(state, entry.endId);
+      if (endIndex === undefined) {
+        throw new Error(
+          `endId ${entry.endId} is not available. It may have been pruned or compressed. ` +
+            `Choose a message ID (m0001) or block ref (b1) visible in the current context.`,
+        );
+      }
+
+      const selection = resolveSelection(messages, startIndex, endIndex);
+      return {
+        startIndex: selection.startIndex,
+        endIndex: selection.endIndex,
+        summary: entry.summary,
+        messageCount: selection.messageIndices.length,
+      };
+    });
+  }
+
+  // mode === "message"
+  if (!args.targets || args.targets.length === 0) {
+    throw new Error("targets array is required and must not be empty");
+  }
+
+  return args.targets.map((target) => {
+    if (!target.messageId || !target.summary) {
+      throw new Error("Each target requires messageId and summary");
+    }
+
+    const index = resolveBoundaryIndex(state, target.messageId);
+    if (index === undefined) {
+      throw new Error(
+        `messageId ${target.messageId} is not available. It may have been pruned or compressed. ` +
+          `Choose a message ID (m0001) visible in the current context.`,
+      );
+    }
+
+    return {
+      startIndex: index,
+      endIndex: index,
+      summary: target.summary,
+      messageCount: 1,
+    };
+  });
+}

package/src/compress/search.ts

@@ -0,0 +1,62 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionState } from "../state/types.ts";
+import { parseBoundaryId } from "../utils/message-ids.ts";
+
+/**
+ * Resolve a boundary ID (m0001 or b1) to a message array index.
+ */
+export function resolveBoundaryIndex(
+  state: SessionState,
+  boundaryId: string,
+): number | undefined {
+  const parsed = parseBoundaryId(boundaryId);
+  if (!parsed) return undefined;
+
+  if (parsed.type === "message") {
+    return state.messageIds.byRef.get(boundaryId);
+  }
+
+  if (parsed.type === "block") {
+    // Find the anchor index for this block
+    for (const [anchorIndex, blockId] of state.prune.messages.activeByAnchorIndex) {
+      if (blockId === parsed.blockId) return anchorIndex;
+    }
+    return undefined;
+  }
+
+  return undefined;
+}
+
+export interface SelectionResult {
+  messageIndices: number[];
+  startIndex: number;
+  endIndex: number;
+}
+
+/**
+ * Collect message indices in a range [startIndex, endIndex].
+ */
+export function resolveSelection(
+  messages: AgentMessage[],
+  startIndex: number,
+  endIndex: number,
+): SelectionResult {
+  if (startIndex > endIndex) {
+    throw new Error(
+      `startId appears after endId in the conversation. Start must come before end.`,
+    );
+  }
+
+  if (startIndex < 0 || endIndex >= messages.length) {
+    throw new Error(
+      `Boundary indices out of range. Valid range: 0-${messages.length - 1}`,
+    );
+  }
+
+  const messageIndices: number[] = [];
+  for (let i = startIndex; i <= endIndex; i++) {
+    messageIndices.push(i);
+  }
+
+  return { messageIndices, startIndex, endIndex };
+}