@pi-vault/pi-dcp 0.1.0

package/src/state/state.ts

@@ -0,0 +1,102 @@
+import type {
+  MessageIdState,
+  Nudges,
+  Prune,
+  PruneMessagesState,
+  SessionState,
+  SessionStats,
+} from "./types.ts";
+
+export function createSessionState(): SessionState {
+  return {
+    sessionId: null,
+    manualMode: false,
+    compressPermission: undefined,
+    pendingManualTrigger: null,
+    prune: createPrune(),
+    nudges: createNudges(),
+    stats: createStats(),
+    toolParameters: new Map(),
+    toolIdList: [],
+    messageIds: createMessageIdState(),
+    lastCompaction: 0,
+    currentTurn: 0,
+    modelContextWindow: undefined,
+  };
+}
+
+export function resetSessionState(state: SessionState): void {
+  state.sessionId = null;
+  state.manualMode = false;
+  state.compressPermission = undefined;
+  state.pendingManualTrigger = null;
+  state.prune.tools.clear();
+  resetPruneMessages(state.prune.messages);
+  state.nudges.contextLimitAnchors.clear();
+  state.nudges.turnAnchors.clear();
+  state.nudges.iterationAnchors.clear();
+  state.stats.pruneTokenCounter = 0;
+  state.stats.totalPruneTokens = 0;
+  state.stats.toolsPruned = 0;
+  state.stats.messagesCompressed = 0;
+  state.toolParameters.clear();
+  state.toolIdList = [];
+  state.messageIds.byIndex.clear();
+  state.messageIds.byRef.clear();
+  state.messageIds.nextRefIndex = 1;
+  state.lastCompaction = 0;
+  state.currentTurn = 0;
+  state.modelContextWindow = undefined;
+}
+
+function createPrune(): Prune {
+  return {
+    tools: new Map(),
+    messages: createPruneMessages(),
+  };
+}
+
+function createPruneMessages(): PruneMessagesState {
+  return {
+    byMessageIndex: new Map(),
+    blocksById: new Map(),
+    activeBlockIds: new Set(),
+    activeByAnchorIndex: new Map(),
+    nextBlockId: 1,
+    nextRunId: 1,
+  };
+}
+
+function resetPruneMessages(m: PruneMessagesState): void {
+  m.byMessageIndex.clear();
+  m.blocksById.clear();
+  m.activeBlockIds.clear();
+  m.activeByAnchorIndex.clear();
+  m.nextBlockId = 1;
+  m.nextRunId = 1;
+}
+
+function createNudges(): Nudges {
+  return {
+    contextLimitAnchors: new Set(),
+    turnAnchors: new Set(),
+    iterationAnchors: new Set(),
+  };
+}
+
+function createStats(): SessionStats {
+  return {
+    pruneTokenCounter: 0,
+    totalPruneTokens: 0,
+    toolsPruned: 0,
+    messagesCompressed: 0,
+  };
+}
+
+function createMessageIdState(): MessageIdState {
+  return {
+    byIndex: new Map(),
+    byRef: new Map(),
+    nextRefIndex: 1,
+  };
+}

package/src/state/tool-cache.ts

@@ -0,0 +1,87 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionState, ToolParameterEntry } from "./types.ts";
+
+/**
+ * Scan messages and populate state.toolParameters with metadata for each tool call.
+ * Called on every context event to keep the cache current.
+ *
+ * Pi message model:
+ * - Tool calls are in `assistant` messages: content[].type === "toolCall"
+ * - Tool results are separate `toolResult` messages with toolCallId, isError
+ */
+export function syncToolCache(
+  state: SessionState,
+  messages: AgentMessage[],
+): void {
+  // First pass: collect tool results
+  const resultsByCallId = new Map<string, { isError: boolean; errorText?: string }>();
+  for (const msg of messages) {
+    if (msg.role !== "toolResult") continue;
+    resultsByCallId.set(msg.toolCallId, {
+      isError: msg.isError,
+      errorText: msg.isError ? extractToolResultText(msg) : undefined,
+    });
+  }
+
+  // Second pass: collect tool calls from assistant messages
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+    if (!Array.isArray(msg.content)) continue;
+
+    for (const part of msg.content) {
+      if (typeof part !== "object" || part === null) continue;
+      const p = part as unknown as Record<string, unknown>;
+      if (p.type !== "toolCall" || typeof p.id !== "string") continue;
+
+      const callId = p.id as string;
+      if (state.toolParameters.has(callId)) continue;
+
+      const result = resultsByCallId.get(callId);
+      const entry: ToolParameterEntry = {
+        tool: (p.name as string) ?? "unknown",
+        parameters: p.arguments ?? {},
+        status: result ? (result.isError ? "error" : "completed") : "pending",
+        error: result?.errorText,
+        turn: state.currentTurn,
+        tokenCount: undefined,
+      };
+
+      state.toolParameters.set(callId, entry);
+    }
+  }
+}
+
+/**
+ * Build ordered list of tool call IDs from messages.
+ */
+export function buildToolIdList(
+  state: SessionState,
+  messages: AgentMessage[],
+): void {
+  const ids: string[] = [];
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+    if (!Array.isArray(msg.content)) continue;
+
+    for (const part of msg.content) {
+      if (typeof part !== "object" || part === null) continue;
+      const p = part as unknown as Record<string, unknown>;
+      if (p.type === "toolCall" && typeof p.id === "string") {
+        ids.push(p.id as string);
+      }
+    }
+  }
+  state.toolIdList = ids;
+}
+
+function extractToolResultText(msg: AgentMessage): string | undefined {
+  if (msg.role !== "toolResult") return undefined;
+  if (!Array.isArray(msg.content)) return undefined;
+  const texts: string[] = [];
+  for (const part of msg.content) {
+    if (typeof part === "object" && part !== null && (part as unknown as Record<string, unknown>).type === "text") {
+      texts.push((part as unknown as Record<string, unknown>).text as string);
+    }
+  }
+  return texts.join("\n") || undefined;
+}

package/src/state/types.ts

@@ -0,0 +1,138 @@
+/**
+ * DCP session state types.
+ *
+ * Adapted from OpenCode DCP for Pi's AgentMessage-based message model.
+ * All Maps/Sets are used in-memory; persistence serializes to plain objects.
+ */
+
+export interface SessionState {
+  /** Current session identifier (set on session_start). */
+  sessionId: string | null;
+  /** Manual mode: false = auto, "active" = manual, "compress-pending" = trigger queued. */
+  manualMode: false | "active" | "compress-pending";
+  /** Effective compress permission for this session. */
+  compressPermission: "allow" | "deny" | undefined;
+  /** Pending manual compress trigger. */
+  pendingManualTrigger: PendingManualTrigger | null;
+  /** Pruning state (tools + message compression). */
+  prune: Prune;
+  /** Nudge anchor tracking. */
+  nudges: Nudges;
+  /** Token savings statistics. */
+  stats: SessionStats;
+  /** Tool parameter cache for deduplication and purge-errors. */
+  toolParameters: Map<string, ToolParameterEntry>;
+  /** Ordered list of tool call IDs in current context. */
+  toolIdList: string[];
+  /** Message ID assignment state. */
+  messageIds: MessageIdState;
+  /** Timestamp of last compaction detected. */
+  lastCompaction: number;
+  /** Current conversation turn number. */
+  currentTurn: number;
+  /** Model context window size (from Pi's ctx.getContextUsage). */
+  modelContextWindow: number | undefined;
+}
+
+export interface PendingManualTrigger {
+  sessionId: string;
+  prompt: string;
+}
+
+export interface Prune {
+  /** Tool call IDs marked for output pruning, mapped to estimated token count. */
+  tools: Map<string, number>;
+  /** Compression block state. */
+  messages: PruneMessagesState;
+}
+
+export interface PruneMessagesState {
+  /** Per-message compression metadata. */
+  byMessageIndex: Map<number, PrunedMessageEntry>;
+  /** All compression blocks by ID. */
+  blocksById: Map<number, CompressionBlock>;
+  /** Currently active block IDs. */
+  activeBlockIds: Set<number>;
+  /** Anchor message index -> active block ID. */
+  activeByAnchorIndex: Map<number, number>;
+  /** Next block ID to allocate. */
+  nextBlockId: number;
+  /** Next run ID to allocate. */
+  nextRunId: number;
+}
+
+export interface PrunedMessageEntry {
+  /** Estimated token count of the original message. */
+  tokenCount: number;
+  /** Block IDs that cover this message (may have multiple from nesting). */
+  blockIds: number[];
+  /** Block IDs that are currently active on this message. */
+  activeBlockIds: number[];
+}
+
+export interface CompressionBlock {
+  blockId: number;
+  runId: number;
+  active: boolean;
+  deactivatedByUser: boolean;
+  compressedTokens: number;
+  summaryTokens: number;
+  durationMs: number;
+  mode: "range" | "message" | undefined;
+  topic: string;
+  batchTopic: string | undefined;
+  startIndex: number;
+  endIndex: number;
+  anchorIndex: number;
+  compressMessageIndex: number;
+  includedBlockIds: number[];
+  consumedBlockIds: number[];
+  parentBlockIds: number[];
+  directMessageIndices: number[];
+  directToolIds: string[];
+  effectiveMessageIndices: number[];
+  effectiveToolIds: string[];
+  createdAt: number;
+  deactivatedAt: number | undefined;
+  deactivatedByBlockId: number | undefined;
+  summary: string;
+}
+
+export interface ToolParameterEntry {
+  tool: string;
+  parameters: unknown;
+  status: "pending" | "running" | "completed" | "error" | undefined;
+  error: string | undefined;
+  turn: number;
+  tokenCount: number | undefined;
+}
+
+export interface Nudges {
+  contextLimitAnchors: Set<number>;
+  turnAnchors: Set<number>;
+  iterationAnchors: Set<number>;
+}
+
+export interface SessionStats {
+  pruneTokenCounter: number;
+  totalPruneTokens: number;
+  toolsPruned: number;
+  messagesCompressed: number;
+}
+
+export interface MessageIdState {
+  byIndex: Map<number, string>;
+  /** Reverse lookup: ref string -> message index. O(1) resolution. */
+  byRef: Map<string, number>;
+  nextRefIndex: number;
+}
+
+/**
+ * Context usage snapshot from Pi's ctx.getContextUsage().
+ * tokens and percent can be null when usage data is unavailable.
+ */
+export interface ContextUsage {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}

package/src/strategies/deduplication.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool call signature utilities for deduplication.
+ *
+ * Creates deterministic signatures from tool name + parameters,
+ * used by the strategy runner to group duplicate calls.
+ */
+
+export function createToolSignature(
+  toolName: string,
+  parameters: unknown,
+): string {
+  const normalized = normalizeParams(parameters);
+  return `${toolName}::${JSON.stringify(normalized)}`;
+}
+
+export function normalizeParams(value: unknown): unknown {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(normalizeParams);
+
+  const obj = value as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    const v = normalizeParams(obj[key]);
+    if (v !== undefined) {
+      sorted[key] = v;
+    }
+  }
+  return sorted;
+}

package/src/strategies/protected-patterns.ts

@@ -0,0 +1,77 @@
+/**
+ * Glob matching and tool/file path protection for pruning strategies.
+ *
+ * Custom glob implementation (no external dependency) supporting:
+ * - `*` matches any chars except `/`
+ * - `**` matches any chars including `/`
+ * - `?` matches single char except `/`
+ */
+
+export function matchesGlob(input: string, pattern: string): boolean {
+  return globToRegex(pattern).test(input);
+}
+
+function globToRegex(pattern: string): RegExp {
+  let result = "^";
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === "*") {
+      if (pattern[i + 1] === "*") {
+        if (pattern[i + 2] === "/") {
+          result += "(?:.*/)?";
+          i += 3;
+        } else {
+          result += ".*";
+          i += 2;
+        }
+      } else {
+        result += "[^/]*";
+        i += 1;
+      }
+    } else if (c === "?") {
+      result += "[^/]";
+      i += 1;
+    } else if (".+^${}()|[]\\".includes(c)) {
+      result += "\\" + c;
+      i += 1;
+    } else {
+      result += c;
+      i += 1;
+    }
+  }
+  result += "$";
+  return new RegExp(result);
+}
+
+export function isToolNameProtected(
+  toolName: string,
+  protectedPatterns: string[],
+): boolean {
+  for (const pattern of protectedPatterns) {
+    if (pattern === toolName) return true;
+    if (pattern.includes("*") || pattern.includes("?")) {
+      if (matchesGlob(toolName, pattern)) return true;
+    }
+  }
+  return false;
+}
+
+export function getFilePathsFromParameters(
+  _toolName: string,
+  parameters: Record<string, unknown>,
+): string[] {
+  const paths: string[] = [];
+  if (typeof parameters.filePath === "string") {
+    paths.push(parameters.filePath);
+  }
+  return paths;
+}
+
+export function isFilePathProtected(
+  filePaths: string[],
+  patterns: string[],
+): boolean {
+  if (filePaths.length === 0 || patterns.length === 0) return false;
+  return filePaths.some((fp) => patterns.some((p) => matchesGlob(fp, p)));
+}

package/src/strategies/purge-errors.ts

@@ -0,0 +1,18 @@
+/**
+ * Staleness predicate for error tool results.
+ *
+ * Used by the strategy runner to identify error outputs
+ * old enough to be pruned from context.
+ */
+
+export function isStaleError(
+  entry: {
+    status: "pending" | "running" | "completed" | "error" | undefined;
+    turn: number;
+  },
+  currentTurn: number,
+  turnThreshold: number,
+): boolean {
+  if (entry.status !== "error") return false;
+  return currentTurn - entry.turn >= turnThreshold;
+}

package/src/strategies/runner.ts

@@ -0,0 +1,149 @@
+import { BASE_PROTECTED_TOOLS, type DcpConfig } from "../config.ts";
+import type { SessionState } from "../state/types.ts";
+import {
+  isToolNameProtected,
+  getFilePathsFromParameters,
+  isFilePathProtected,
+} from "./protected-patterns.ts";
+import { createToolSignature } from "./deduplication.ts";
+import { isStaleError } from "./purge-errors.ts";
+
+export interface StrategyResult {
+  pruned: number;
+  tokensSaved: number;
+}
+
+/**
+ * Run all enabled pruning strategies against the current tool cache.
+ * Owns: guard checks, protected-tools resolution, eligibility filtering, stat bookkeeping.
+ */
+export function runStrategies(
+  state: SessionState,
+  config: DcpConfig,
+): StrategyResult {
+  if (state.toolIdList.length === 0) {
+    return { pruned: 0, tokensSaved: 0 };
+  }
+  if (state.manualMode === "active" && !config.manualMode.automaticStrategies) {
+    return { pruned: 0, tokensSaved: 0 };
+  }
+
+  let pruned = 0;
+  let tokensSaved = 0;
+
+  // --- Deduplication ---
+  if (config.strategies.deduplication.enabled) {
+    const protectedTools = [
+      ...BASE_PROTECTED_TOOLS,
+      ...config.strategies.deduplication.protectedTools,
+    ];
+
+    const unpruned = state.toolIdList.filter(
+      (id) => !state.prune.tools.has(id),
+    );
+
+    // Group by signature
+    const groups = new Map<string, string[]>();
+    for (const callId of unpruned) {
+      const entry = state.toolParameters.get(callId);
+      if (!entry) continue;
+      if (isToolNameProtected(entry.tool, protectedTools)) continue;
+
+      const filePaths = getFilePathsFromParameters(
+        entry.tool,
+        entry.parameters as Record<string, unknown>,
+      );
+      if (isFilePathProtected(filePaths, config.protectedFilePatterns))
+        continue;
+
+      const sig = createToolSignature(entry.tool, entry.parameters);
+      const group = groups.get(sig) ?? [];
+      group.push(callId);
+      groups.set(sig, group);
+    }
+
+    // Prune all but last in each group
+    for (const [, callIds] of groups) {
+      if (callIds.length <= 1) continue;
+      for (let i = 0; i < callIds.length - 1; i++) {
+        const callId = callIds[i];
+        const entry = state.toolParameters.get(callId);
+        const tokens = entry?.tokenCount ?? 0;
+        state.prune.tools.set(callId, tokens);
+        pruned++;
+        tokensSaved += tokens;
+      }
+    }
+  }
+
+  // --- Purge Errors ---
+  if (config.strategies.purgeErrors.enabled) {
+    const protectedTools = [
+      ...BASE_PROTECTED_TOOLS,
+      ...config.strategies.purgeErrors.protectedTools,
+    ];
+    const turnThreshold = config.strategies.purgeErrors.turns;
+    const unpruned = state.toolIdList.filter(
+      (id) => !state.prune.tools.has(id),
+    );
+
+    for (const callId of unpruned) {
+      const entry = state.toolParameters.get(callId);
+      if (!entry) continue;
+      if (isToolNameProtected(entry.tool, protectedTools)) continue;
+      if (!isStaleError(entry, state.currentTurn, turnThreshold)) continue;
+
+      const filePaths = getFilePathsFromParameters(
+        entry.tool,
+        entry.parameters as Record<string, unknown>,
+      );
+      if (isFilePathProtected(filePaths, config.protectedFilePatterns))
+        continue;
+
+      const tokens = entry.tokenCount ?? 0;
+      state.prune.tools.set(callId, tokens);
+      pruned++;
+      tokensSaved += tokens;
+    }
+  }
+
+  // Update stats once
+  state.stats.totalPruneTokens += tokensSaved;
+  state.stats.toolsPruned += pruned;
+
+  return { pruned, tokensSaved };
+}
+
+/**
+ * Sweep variant: prune all non-protected completed tool outputs.
+ * Used by the dcp:sweep command.
+ */
+export function sweepAll(
+  state: SessionState,
+  config: DcpConfig,
+): StrategyResult {
+  const protectedTools = new Set([
+    ...BASE_PROTECTED_TOOLS,
+    ...config.compress.protectedTools,
+  ]);
+
+  let pruned = 0;
+  let tokensSaved = 0;
+
+  for (const [toolCallId, entry] of state.toolParameters) {
+    if (state.prune.tools.has(toolCallId)) continue;
+    if (protectedTools.has(entry.tool)) continue;
+    if (entry.status !== "completed") continue;
+
+    const tokens = entry.tokenCount ?? 0;
+    state.prune.tools.set(toolCallId, tokens);
+    pruned++;
+    tokensSaved += tokens;
+  }
+
+  state.stats.toolsPruned += pruned;
+  state.stats.totalPruneTokens += tokensSaved;
+  state.stats.pruneTokenCounter += tokensSaved;
+
+  return { pruned, tokensSaved };
+}

package/src/utils/message-content.ts

@@ -0,0 +1,85 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+/**
+ * Find the index of the first text part in a content array.
+ * Returns -1 if no text part exists.
+ */
+function findTextPartIndex(content: unknown[]): number {
+  return content.findIndex(
+    (p) =>
+      typeof p === "object" &&
+      p !== null &&
+      (p as unknown as Record<string, unknown>).type === "text",
+  );
+}
+
+/**
+ * Append text to the first text part of a message.
+ * Idempotent: skips if marker string is already present in the text part.
+ * Handles E9 string content, array content, and missing text parts.
+ * Returns the original message by reference if no change was made.
+ */
+export function appendText(
+  msg: AgentMessage,
+  text: string,
+  marker?: string,
+): AgentMessage {
+  if (!("content" in msg)) return msg;
+
+  // E9: UserMessage.content can be a plain string
+  if (typeof msg.content === "string") {
+    if (marker && msg.content.includes(marker)) return msg;
+    return {
+      ...msg,
+      content: [{ type: "text" as const, text: `${msg.content}${text}` }],
+    } as AgentMessage;
+  }
+
+  if (!Array.isArray(msg.content)) return msg;
+
+  const idx = findTextPartIndex(msg.content);
+  if (idx === -1) return msg;
+
+  const textPart = msg.content[idx] as unknown as {
+    type: string;
+    text: string;
+  };
+  if (marker && textPart.text.includes(marker)) return msg;
+
+  const newContent = [...msg.content];
+  newContent[idx] = {
+    ...textPart,
+    text: `${textPart.text}${text}`,
+  } as (typeof newContent)[number];
+
+  return { ...msg, content: newContent } as AgentMessage;
+}
+
+/**
+ * Transform all text parts in a message via a mapping function.
+ * Returns the original message by reference if fn returns identical strings.
+ */
+export function mapText(
+  msg: AgentMessage,
+  fn: (text: string) => string,
+): AgentMessage {
+  if (!("content" in msg)) return msg;
+  if (!Array.isArray(msg.content)) return msg;
+
+  let changed = false;
+  const newContent = msg.content.map((part) => {
+    if (typeof part !== "object" || part === null) return part;
+    const p = part as unknown as Record<string, unknown>;
+    if (p.type !== "text" || typeof p.text !== "string") return part;
+
+    const mapped = fn(p.text as string);
+    if (mapped !== p.text) {
+      changed = true;
+      return { ...part, text: mapped };
+    }
+    return part;
+  });
+
+  if (!changed) return msg;
+  return { ...msg, content: newContent } as AgentMessage;
+}