@pi-vault/pi-dcp 0.1.0

package/src/compress/state.ts

@@ -0,0 +1,140 @@
+import type { SessionState, CompressionBlock } from "../state/types.ts";
+import { formatBlockRef } from "../utils/message-ids.ts";
+
+/**
+ * Prefix used in wrapped summary headers/footers.
+ * Format: `[Compressed Block b{id}]\n{summary}\n[End Block b{id}]`
+ *
+ * The block ref (e.g. "b1") serves as the model-visible anchor for
+ * referencing compressed content in subsequent compress calls.
+ */
+export const COMPRESSED_BLOCK_HEADER = "Compressed Block";
+
+export function allocateBlockId(state: SessionState): number {
+  const id = state.prune.messages.nextBlockId;
+  state.prune.messages.nextBlockId = id + 1;
+  return id;
+}
+
+export function allocateRunId(state: SessionState): number {
+  const id = state.prune.messages.nextRunId;
+  state.prune.messages.nextRunId = id + 1;
+  return id;
+}
+
+/**
+ * Wrap a summary with block delimiters visible to the model.
+ * The delimiters let the model reference this block by its ref (e.g. "b1")
+ * as a boundary in future compress calls.
+ */
+export function wrapCompressedSummary(blockId: number, summary: string): string {
+  const ref = formatBlockRef(blockId);
+  return `[${COMPRESSED_BLOCK_HEADER} ${ref}]\n${summary}\n[End Block ${ref}]`;
+}
+
+export interface ApplyCompressionParams {
+  blockId: number;
+  runId: number;
+  topic: string;
+  batchTopic?: string;
+  mode: "range" | "message";
+  startIndex: number;
+  endIndex: number;
+  anchorIndex: number;
+  compressMessageIndex: number;
+  summary: string;
+  summaryTokens: number;
+  consumedBlockIds: number[];
+}
+
+export function applyCompressionState(
+  state: SessionState,
+  params: ApplyCompressionParams,
+): { messageIndices: number[] } {
+  const now = Date.now();
+  const messageIndices: number[] = [];
+
+  // Create the block
+  const block: CompressionBlock = {
+    blockId: params.blockId,
+    runId: params.runId,
+    active: true,
+    deactivatedByUser: false,
+    compressedTokens: 0,
+    summaryTokens: params.summaryTokens,
+    durationMs: 0,
+    mode: params.mode,
+    topic: params.topic,
+    batchTopic: params.batchTopic,
+    startIndex: params.startIndex,
+    endIndex: params.endIndex,
+    anchorIndex: params.anchorIndex,
+    compressMessageIndex: params.compressMessageIndex,
+    includedBlockIds: [],
+    consumedBlockIds: params.consumedBlockIds,
+    parentBlockIds: [],
+    directMessageIndices: [],
+    directToolIds: [],
+    effectiveMessageIndices: [],
+    effectiveToolIds: [],
+    createdAt: now,
+    deactivatedAt: undefined,
+    deactivatedByBlockId: undefined,
+    summary: params.summary,
+  };
+
+  // Mark messages in range
+  let totalTokens = 0;
+  for (let i = params.startIndex; i <= params.endIndex; i++) {
+    messageIndices.push(i);
+
+    let entry = state.prune.messages.byMessageIndex.get(i);
+    if (!entry) {
+      entry = {
+        tokenCount: 0,
+        blockIds: [],
+        activeBlockIds: [],
+      };
+      state.prune.messages.byMessageIndex.set(i, entry);
+    }
+
+    if (!entry.blockIds.includes(params.blockId)) {
+      entry.blockIds.push(params.blockId);
+    }
+    if (!entry.activeBlockIds.includes(params.blockId)) {
+      entry.activeBlockIds.push(params.blockId);
+    }
+
+    totalTokens += entry.tokenCount;
+  }
+
+  block.compressedTokens = totalTokens;
+  block.directMessageIndices = messageIndices;
+  block.effectiveMessageIndices = messageIndices;
+
+  // Deactivate consumed blocks
+  for (const consumedId of params.consumedBlockIds) {
+    const consumed = state.prune.messages.blocksById.get(consumedId);
+    if (consumed) {
+      consumed.active = false;
+      consumed.deactivatedAt = now;
+      consumed.deactivatedByBlockId = params.blockId;
+      state.prune.messages.activeBlockIds.delete(consumedId);
+
+      // Find and remove anchor mapping
+      for (const [anchorIdx, bId] of state.prune.messages.activeByAnchorIndex) {
+        if (bId === consumedId) {
+          state.prune.messages.activeByAnchorIndex.delete(anchorIdx);
+        }
+      }
+    }
+    block.includedBlockIds.push(consumedId);
+  }
+
+  // Store the block
+  state.prune.messages.blocksById.set(params.blockId, block);
+  state.prune.messages.activeBlockIds.add(params.blockId);
+  state.prune.messages.activeByAnchorIndex.set(params.anchorIndex, params.blockId);
+
+  return { messageIndices };
+}

package/src/config.ts

@@ -0,0 +1,253 @@
+import * as fs from "node:fs";
+
+export interface DcpConfig {
+  enabled: boolean;
+  debug: boolean;
+  compress: CompressConfig;
+  manualMode: ManualModeConfig;
+  strategies: StrategiesConfig;
+  protectedFilePatterns: string[];
+  nudgeNotification: "off" | "minimal" | "detailed";
+}
+
+export interface CompressConfig {
+  mode: "range" | "message";
+  permission: "allow" | "deny";
+  maxContextPercent: number;
+  minContextPercent: number;
+  nudgeFrequency: number;
+  iterationNudgeThreshold: number;
+  nudgeForce: "strong" | "soft";
+  protectedTools: string[];
+  protectUserMessages: boolean;
+  protectTags: boolean;
+}
+
+export interface ManualModeConfig {
+  default: false | "active";
+  automaticStrategies: boolean;
+}
+
+export interface StrategiesConfig {
+  deduplication: DeduplicationConfig;
+  purgeErrors: PurgeErrorsConfig;
+}
+
+export interface DeduplicationConfig {
+  enabled: boolean;
+  protectedTools: string[];
+}
+
+export interface PurgeErrorsConfig {
+  enabled: boolean;
+  turns: number;
+  protectedTools: string[];
+}
+
+const DEFAULT_CONFIG: DcpConfig = {
+  enabled: true,
+  debug: false,
+  compress: {
+    mode: "range",
+    permission: "allow",
+    maxContextPercent: 80,
+    minContextPercent: 50,
+    nudgeFrequency: 5,
+    iterationNudgeThreshold: 15,
+    nudgeForce: "soft",
+    protectedTools: ["compress"],
+    protectUserMessages: false,
+    protectTags: false,
+  },
+  manualMode: {
+    default: false,
+    automaticStrategies: true,
+  },
+  strategies: {
+    deduplication: {
+      enabled: true,
+      protectedTools: [],
+    },
+    purgeErrors: {
+      enabled: true,
+      turns: 4,
+      protectedTools: [],
+    },
+  },
+  protectedFilePatterns: [],
+  nudgeNotification: "minimal",
+};
+
+/**
+ * Tool names always protected from pruning strategies.
+ * Pi's core tools that should never have their outputs removed.
+ */
+export const BASE_PROTECTED_TOOLS = [
+  "compress",
+  "bash",
+  "read",
+  "write",
+  "edit",
+  "grep",
+  "find",
+  "ls",
+];
+
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+  "enabled", "debug", "compress", "manualMode", "strategies",
+  "protectedFilePatterns", "nudgeNotification",
+]);
+
+const KNOWN_COMPRESS_KEYS = new Set([
+  "mode", "permission", "maxContextPercent", "minContextPercent",
+  "nudgeFrequency", "iterationNudgeThreshold", "nudgeForce",
+  "protectedTools", "protectUserMessages", "protectTags",
+]);
+
+export interface LoadConfigResult {
+  config: DcpConfig;
+  warnings: string[];
+}
+
+/**
+ * Load DCP configuration from a single JSON file.
+ * Falls back to defaults on missing file, parse error, or invalid content.
+ * Returns warnings for unknown keys and out-of-range values.
+ *
+ * @param configFilePath - Absolute path to dcp.json (typically resolved via getAgentDir())
+ */
+export function loadConfig(configFilePath: string): LoadConfigResult {
+  const config = structuredClone(DEFAULT_CONFIG);
+  const warnings: string[] = [];
+
+  const parsed = parseConfigFile(configFilePath);
+  if (parsed) {
+    // Check for unknown top-level keys
+    for (const key of Object.keys(parsed)) {
+      if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+        warnings.push(`Unknown config key "${key}" — ignored`);
+      }
+    }
+
+    // Check for unknown compress keys
+    if (parsed.compress && typeof parsed.compress === "object") {
+      for (const key of Object.keys(parsed.compress as object)) {
+        if (!KNOWN_COMPRESS_KEYS.has(key)) {
+          warnings.push(`Unknown compress key "${key}" — ignored`);
+        }
+      }
+    }
+
+    mergeConfig(config, parsed);
+  }
+
+  // Validate ranges
+  if (config.compress.maxContextPercent > 100) {
+    warnings.push(`maxContextPercent (${config.compress.maxContextPercent}) exceeds 100, reset to default`);
+    config.compress.maxContextPercent = DEFAULT_CONFIG.compress.maxContextPercent;
+  }
+  if (config.compress.minContextPercent > 100) {
+    warnings.push(`minContextPercent (${config.compress.minContextPercent}) exceeds 100, reset to default`);
+    config.compress.minContextPercent = DEFAULT_CONFIG.compress.minContextPercent;
+  }
+
+  if (config.compress.maxContextPercent <= config.compress.minContextPercent) {
+    config.compress.maxContextPercent = DEFAULT_CONFIG.compress.maxContextPercent;
+    config.compress.minContextPercent = DEFAULT_CONFIG.compress.minContextPercent;
+  }
+
+  return { config, warnings };
+}
+
+function parseConfigFile(
+  filePath: string,
+): Record<string, unknown> | undefined {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function mergeConfig(target: DcpConfig, source: Record<string, unknown>): void {
+  if (typeof source.enabled === "boolean") target.enabled = source.enabled;
+  if (typeof source.debug === "boolean") target.debug = source.debug;
+  if (typeof source.nudgeNotification === "string") {
+    if (["off", "minimal", "detailed"].includes(source.nudgeNotification)) {
+      target.nudgeNotification = source.nudgeNotification as
+        | "off"
+        | "minimal"
+        | "detailed";
+    }
+  }
+  if (Array.isArray(source.protectedFilePatterns)) {
+    target.protectedFilePatterns = source.protectedFilePatterns.filter(
+      (p): p is string => typeof p === "string",
+    );
+  }
+
+  if (source.compress && typeof source.compress === "object") {
+    const c = source.compress as Record<string, unknown>;
+    if (c.mode === "range" || c.mode === "message")
+      target.compress.mode = c.mode;
+    if (c.permission === "allow" || c.permission === "deny")
+      target.compress.permission = c.permission;
+    if (typeof c.maxContextPercent === "number" && c.maxContextPercent > 0)
+      target.compress.maxContextPercent = c.maxContextPercent;
+    if (typeof c.minContextPercent === "number" && c.minContextPercent > 0)
+      target.compress.minContextPercent = c.minContextPercent;
+    if (typeof c.nudgeFrequency === "number" && c.nudgeFrequency >= 1)
+      target.compress.nudgeFrequency = c.nudgeFrequency;
+    if (
+      typeof c.iterationNudgeThreshold === "number" &&
+      c.iterationNudgeThreshold >= 1
+    )
+      target.compress.iterationNudgeThreshold = c.iterationNudgeThreshold;
+    if (c.nudgeForce === "strong" || c.nudgeForce === "soft")
+      target.compress.nudgeForce = c.nudgeForce;
+    if (Array.isArray(c.protectedTools))
+      target.compress.protectedTools = c.protectedTools.filter(
+        (t): t is string => typeof t === "string",
+      );
+    if (typeof c.protectUserMessages === "boolean")
+      target.compress.protectUserMessages = c.protectUserMessages;
+    if (typeof c.protectTags === "boolean")
+      target.compress.protectTags = c.protectTags;
+  }
+
+  if (source.manualMode && typeof source.manualMode === "object") {
+    const m = source.manualMode as Record<string, unknown>;
+    if (m.default === false || m.default === "active")
+      target.manualMode.default = m.default;
+    if (typeof m.automaticStrategies === "boolean")
+      target.manualMode.automaticStrategies = m.automaticStrategies;
+  }
+
+  if (source.strategies && typeof source.strategies === "object") {
+    const s = source.strategies as Record<string, unknown>;
+    if (s.deduplication && typeof s.deduplication === "object") {
+      const d = s.deduplication as Record<string, unknown>;
+      if (typeof d.enabled === "boolean")
+        target.strategies.deduplication.enabled = d.enabled;
+      if (Array.isArray(d.protectedTools))
+        target.strategies.deduplication.protectedTools =
+          d.protectedTools.filter((t): t is string => typeof t === "string");
+    }
+    if (s.purgeErrors && typeof s.purgeErrors === "object") {
+      const p = s.purgeErrors as Record<string, unknown>;
+      if (typeof p.enabled === "boolean")
+        target.strategies.purgeErrors.enabled = p.enabled;
+      if (typeof p.turns === "number" && p.turns >= 1)
+        target.strategies.purgeErrors.turns = p.turns;
+      if (Array.isArray(p.protectedTools))
+        target.strategies.purgeErrors.protectedTools = p.protectedTools.filter(
+          (t): t is string => typeof t === "string",
+        );
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,217 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { loadConfig } from "./config.ts";
+import { handleCompress, type CompressArgs } from "./compress/handler.ts";
+import { COMPRESS_MESSAGE_PROMPT } from "./prompts/compress-message.ts";
+import { Logger } from "./logger.ts";
+import { DCP_SYSTEM_PROMPT } from "./prompts/system.ts";
+import { createSessionState, resetSessionState } from "./state/state.ts";
+import type { SessionState } from "./state/types.ts";
+import { registerDcpCommands } from "./commands/register.ts";
+import { saveSessionState, loadSessionState } from "./state/persistence.ts";
+import { runPipeline } from "./pipeline.ts";
+
+export default function createExtension(pi: ExtensionAPI): void {
+  const agentDir = getAgentDir();
+  const configFilePath = path.join(agentDir, "extensions", "dcp.json");
+
+  let { config } = loadConfig(configFilePath);
+  let logger: Logger = new Logger(config.debug);
+  const state: SessionState = createSessionState();
+  let latestMessages: AgentMessage[] = [];
+  let sessionDir: string = "";
+
+  function reloadConfig(logDir?: string): void {
+    const result = loadConfig(configFilePath);
+    config = result.config;
+    logger = new Logger(config.debug, logDir);
+    for (const w of result.warnings) {
+      logger.info("config", w);
+    }
+  }
+
+  if (!config.enabled) return;
+
+  registerDcpCommands(pi, state, config);
+
+  if (config.compress.mode === "message") {
+    pi.registerTool({
+      name: "compress",
+      label: "Compress",
+      description: COMPRESS_MESSAGE_PROMPT,
+      parameters: Type.Object({
+        topic: Type.String({
+          description: "Short label (3-5 words) for display",
+        }),
+        targets: Type.Array(
+          Type.Object({
+            messageId: Type.String({
+              description: "Message ID to compress (e.g. m0001)",
+            }),
+            summary: Type.String({
+              description: "Complete technical summary replacing message content",
+            }),
+          }),
+          { description: "Messages to compress" },
+        ),
+      }),
+      async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        const resultText = handleCompress(state, config, latestMessages, {
+          ...(params as Record<string, unknown>),
+          mode: "message",
+        } as CompressArgs);
+        return {
+          content: [{ type: "text" as const, text: resultText }],
+          details: {},
+        };
+      },
+    });
+  } else {
+    pi.registerTool({
+      name: "compress",
+      label: "Compress",
+      description:
+        "Compress conversation ranges into summaries. Use message IDs (m0001, m0002...) visible in context as boundaries.",
+      parameters: Type.Object({
+        topic: Type.String({ description: "Short label (3-5 words) for display" }),
+        content: Type.Array(
+          Type.Object({
+            startId: Type.String({
+              description: "Message or block ID marking range start (e.g. m0001, b2)",
+            }),
+            endId: Type.String({
+              description: "Message or block ID marking range end (e.g. m0012, b5)",
+            }),
+            summary: Type.String({
+              description: "Complete technical summary replacing all content in range",
+            }),
+          }),
+          { description: "Ranges to compress, each with start/end boundaries and summary" },
+        ),
+      }),
+      async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        const resultText = handleCompress(state, config, latestMessages, {
+          ...(params as Record<string, unknown>),
+          mode: "range",
+        } as CompressArgs);
+        return {
+          content: [{ type: "text" as const, text: resultText }],
+          details: {},
+        };
+      },
+    });
+  }
+
+  pi.on("before_agent_start", async (event, _ctx) => {
+    if (!config.enabled) return;
+    if (config.compress.permission === "deny") return;
+
+    return {
+      systemPrompt: (event.systemPrompt ?? "") + DCP_SYSTEM_PROMPT,
+    };
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    sessionDir = ctx.sessionManager.getSessionDir();
+    const logDir = path.join(sessionDir, "dcp", "logs");
+    reloadConfig(logDir);
+    if (!config.enabled) return;
+
+    resetSessionState(state);
+    state.sessionId = `pi-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+    state.manualMode = config.manualMode.default;
+
+    // Load persisted state if resuming
+    if (event.reason === "resume") {
+      const persisted = loadSessionState(sessionDir);
+      if (persisted) {
+        state.currentTurn = persisted.currentTurn;
+        state.stats = persisted.stats;
+        state.lastCompaction = persisted.lastCompaction;
+        logger.info("dcp", "resumed persisted state", { turn: state.currentTurn });
+      }
+    }
+
+    const usage = ctx.getContextUsage();
+    if (usage) {
+      state.modelContextWindow = usage.contextWindow;
+    }
+
+    logger.info("dcp", "session started", {
+      sessionId: state.sessionId,
+      reason: event.reason,
+      mode: config.compress.mode,
+    });
+  });
+
+  pi.on("session_compact", async (_event, _ctx) => {
+    state.prune.tools.clear();
+    state.prune.messages.byMessageIndex.clear();
+    state.prune.messages.blocksById.clear();
+    state.prune.messages.activeBlockIds.clear();
+    state.prune.messages.activeByAnchorIndex.clear();
+    state.messageIds.byIndex.clear();
+    state.messageIds.byRef.clear();
+    state.messageIds.nextRefIndex = 1;
+    state.lastCompaction = Date.now();
+    logger.info("dcp", "compaction detected, pruning state reset");
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    if (sessionDir) {
+      try {
+        saveSessionState(state, sessionDir);
+        logger.info("dcp", "session shutdown, state saved");
+      } catch (err) {
+        logger.info("dcp", "session shutdown, failed to save state", { error: String(err) });
+      }
+    } else {
+      logger.info("dcp", "session shutdown");
+    }
+  });
+
+  pi.on("turn_end", async (_event, _ctx) => {
+    state.currentTurn++;
+  });
+
+  pi.on("context", async (event, ctx) => {
+    if (!config.enabled) return;
+
+    const usage = ctx.getContextUsage();
+    if (usage) state.modelContextWindow = usage.contextWindow;
+    latestMessages = event.messages;
+
+    const result = runPipeline(
+      state,
+      config,
+      event.messages,
+      usage
+        ? {
+            tokens: usage.tokens,
+            contextWindow: usage.contextWindow,
+            percent: usage.percent,
+          }
+        : undefined,
+    );
+
+    if (result.strategyResult.pruned > 0) {
+      logger.info("strategies", "pruned tool outputs", {
+        count: result.strategyResult.pruned,
+        tokens: result.strategyResult.tokensSaved,
+      });
+    }
+
+    if (ctx.hasUI && state.stats.totalPruneTokens > 0) {
+      ctx.ui.setStatus(
+        "dcp",
+        `DCP: ${state.stats.totalPruneTokens} tokens saved`,
+      );
+    }
+
+    return { messages: result.messages };
+  });
+}

package/src/logger.ts

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export class Logger {
+  private enabled: boolean;
+  private logDir: string | undefined;
+
+  constructor(enabled: boolean, logDir?: string) {
+    this.enabled = enabled;
+    this.logDir = logDir;
+  }
+
+  info(source: string, message: string, data?: Record<string, unknown>): void {
+    this.write("INFO", source, message, data);
+  }
+
+  warn(source: string, message: string, data?: Record<string, unknown>): void {
+    this.write("WARN", source, message, data);
+  }
+
+  error(source: string, message: string, data?: Record<string, unknown>): void {
+    this.write("ERROR", source, message, data);
+  }
+
+  private write(
+    level: string,
+    source: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ): void {
+    if (!this.enabled || !this.logDir) return;
+
+    const now = new Date();
+    const timestamp = now.toISOString();
+    const dateStr = timestamp.slice(0, 10);
+
+    fs.mkdirSync(this.logDir, { recursive: true });
+
+    let line = `${timestamp} ${level.padEnd(5)} ${source}: ${message}`;
+    if (data) {
+      const pairs = Object.entries(data)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? `"${v}"` : String(v)}`)
+        .join(" ");
+      line += ` | ${pairs}`;
+    }
+
+    fs.appendFileSync(path.join(this.logDir, `${dateStr}.log`), `${line}\n`);
+  }
+}