@zhushanwen/pi-context-engineering 0.1.2 → 0.1.4

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zhushanwen/pi-context-engineering",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Progressive context compression for Pi — L0 zero-cost cleanup, L1 rule-based condensation, L2 emergency truncation, with recall mechanism.",
   "type": "module",
   "main": "src/index.ts",
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "keywords": [
@@ -22,9 +22,13 @@
   ],
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "scripts": {
-    "typecheck": "npx tsc --noEmit"
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
   }
 }

package/src/__tests__/compressor.test.ts

@@ -1,24 +1,25 @@
-import { describe, it, expect } from "vitest";
+import { describe, expect,it } from "vitest";
+
 import {
+  type AgentMessage,
+  type AssistantMessage,
+  type BashExecutionMessage,
   compressContext,
-  validateToolPairing,
+  type ContextUsage,
+  findCompactBoundary,
   getToolResultText,
-  processMicrocompact,
   processBudget,
-  findCompactBoundary,
-  type AgentMessage,
+  processMicrocompact,
+  type TextContent,
+  type ThinkingContent,
   type ToolCall,
-  type AssistantMessage,
   type ToolResultMessage,
-  type BashExecutionMessage,
   type UserMessage,
-  type TextContent,
-  type ThinkingContent,
-  type ContextUsage,
+  validateToolPairing,
 } from "../compressor";
-import { createRecallStore } from "../recall-store";
-import { createFrozenFreshState } from "../frozen-fresh";
 import { DEFAULT_CONFIG } from "../config";
+import { createFrozenFreshState } from "../frozen-fresh";
+import { createRecallStore } from "../recall-store";
 
 // ── Test helpers ──
 

package/src/__tests__/frozen-fresh.test.ts

@@ -1,4 +1,5 @@
-import { describe, it, expect } from "vitest";
+import { describe, expect,it } from "vitest";
+
 import { createFrozenFreshState } from "../frozen-fresh";
 
 describe("FrozenFreshState", () => {

package/src/__tests__/integration.test.ts

@@ -1,22 +1,23 @@
-import { describe, it, expect } from "vitest";
+import { describe, expect,it } from "vitest";
+
+import { handleContextEngineeringCommand, handleContextStatsCommand } from "../commands";
 import {
-  compressContext,
-  validateToolPairing,
-  getToolResultText,
   type AgentMessage,
-  type ToolCall,
   type AssistantMessage,
-  type ToolResultMessage,
   type BashExecutionMessage,
-  type UserMessage,
+  compressContext,
+  type ContextUsage,
+  getToolResultText,
   type TextContent,
   type ThinkingContent,
-  type ContextUsage,
+  type ToolCall,
+  type ToolResultMessage,
+  type UserMessage,
+  validateToolPairing,
 } from "../compressor";
-import { createRecallStore } from "../recall-store";
-import { DEFAULT_CONFIG, type ContextEngineeringConfig } from "../config";
+import { type ContextEngineeringConfig,DEFAULT_CONFIG } from "../config";
 import { createFrozenFreshState } from "../frozen-fresh";
-import { handleContextEngineeringCommand, handleContextStatsCommand } from "../commands";
+import { createRecallStore } from "../recall-store";
 
 // ── Helpers ──
 

package/src/commands.ts

@@ -1,9 +1,12 @@
+import type { CompressionStats } from "./compressor";
 import type { ContextEngineeringConfig } from "./config";
 import { parseLevelArgs } from "./config";
-import type { CompressionStats } from "./compressor";
 
 // ── 格式化辅助 ──
 
+// 百分比转换因子（小数 → 整数百分比）
+const PERCENT_FACTOR = 100;
+
 function formatConfigSummary(config: ContextEngineeringConfig): string {
   const lines = [
     "Context Engineering Plugin",
@@ -64,7 +67,7 @@ function formatConfigSummary(config: ContextEngineeringConfig): string {
   if (config.l2.enabled) {
     lines.push("L2 (Emergency compression):");
     lines.push("  Enabled: true");
-    const thresholdPercent = Math.round(config.l2.emergencyThreshold * 100);
+    const thresholdPercent = Math.round(config.l2.emergencyThreshold * PERCENT_FACTOR);
     lines.push(
       `  Threshold: ${thresholdPercent}% | Protect recent: ${config.l2.protectRecentTurns} turns`,
     );
@@ -143,6 +146,8 @@ export function handleContextEngineeringCommand(
       config.l2.enabled = onOff;
       return `L2 (Emergency compression) ${action === "on" ? "enabled" : "disabled"}.`;
   }
+  // Defensive fallback — should be unreachable if parseLevelArgs validates correctly
+  return USAGE_HELP;
 }
 
 export function handleContextStatsCommand(stats: CompressionStats): string {

package/src/compressor.ts

@@ -1,148 +1,54 @@
 // compressor.ts — L0/L1/L2 compression engine with tool pairing validation
 
-import type { L0Config, L1Config, L2Config, McConfig, BudgetConfig, ContextEngineeringConfig } from "./config.ts";
-import type { RecallStore } from "./recall-store.ts";
+import type { BudgetConfig, ContextEngineeringConfig,L0Config, L1Config, L2Config, McConfig } from "./config.ts";
 import type { FrozenFreshState } from "./frozen-fresh.ts";
+import type { RecallStore } from "./recall-store.ts";
+
+// Re-export types from types.ts for backward compatibility
+export type {
+  AgentMessage,
+  AssistantMessage,
+  BashExecutionMessage,
+  BudgetStats,
+  CompactionSummaryMessage,
+  CompressionStats,
+  ContextUsage,
+  ImageContent,
+  L0Stats,
+  McStats,
+  TextContent,
+  ThinkingContent,
+  ToolCall,
+  ToolResultMessage,
+  TurnBoundary,
+  UserMessage,
+} from "./types.ts";
+
+// Import types for internal use
+import type {
+  AgentMessage,
+  BudgetStats,
+  CompressionStats,
+  ContextUsage,
+  L0Stats,
+  McStats,
+  TextContent,
+  ThinkingContent,
+  ToolResultMessage,
+  TurnBoundary,
+} from "./types.ts";
 
 // chars→tokens 估算因子和 fallback 上下文窗口大小
 const CHARS_PER_TOKEN = 4;
 const DEFAULT_CONTEXT_WINDOW = 200_000;
 
-// ── Message types (structural subset of pi-ai + Pi coding agent) ──
-
-export interface TextContent {
-  type: "text";
-  text: string;
-}
-
-export interface ThinkingContent {
-  type: "thinking";
-  thinking: string;
-  thinkingSignature?: string;
-  redacted?: boolean;
-}
-
-export interface ImageContent {
-  type: "image";
-  data: string;
-  mimeType: string;
-}
-
-export interface ToolCall {
-  type: "toolCall";
-  id: string;
-  name: string;
-  arguments: Record<string, unknown>;
-}
-
-export interface UserMessage {
-  role: "user";
-  content: string | (TextContent | ImageContent)[];
-  timestamp: number;
-}
-
-export interface AssistantMessage {
-  role: "assistant";
-  content: (TextContent | ThinkingContent | ToolCall)[];
-  api: string;
-  provider: string;
-  model: string;
-  usage: {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    totalTokens: number;
-    cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
-  };
-  stopReason: string;
-  timestamp: number;
-}
-
-export interface ToolResultMessage {
-  role: "toolResult";
-  toolCallId: string;
-  toolName: string;
-  content: (TextContent | ImageContent)[];
-  details?: unknown;
-  isError: boolean;
-  timestamp: number;
-}
-
-export interface BashExecutionMessage {
-  role: "bashExecution";
-  command: string;
-  output: string;
-  exitCode: number | undefined;
-  cancelled: boolean;
-  truncated: boolean;
-  fullOutputPath?: string;
-  timestamp: number;
-  excludeFromContext?: boolean;
-}
-
-export interface CompactionSummaryMessage {
-  role: "compactionSummary";
-  summary: string;
-  tokensBefore: number;
-  timestamp: number;
-}
-
-export type AgentMessage =
-  | UserMessage
-  | AssistantMessage
-  | ToolResultMessage
-  | BashExecutionMessage
-  | CompactionSummaryMessage;
-
-export interface ContextUsage {
-  tokens: number | null;
-  contextWindow: number;
-  percent: number | null;
-}
-
-// ── Exported data types ──
-
-export interface TurnBoundary {
-  startIndex: number;
-  endIndex: number; // 不含
-  timestamp: number;
-}
-
-export interface L0Stats {
-  expired: number;
-  truncated: number;
-  thinkingCleared: number;
-}
-
-export interface CompressionStats {
-  l0Expired: number;
-  l0Truncated: number;
-  l0ThinkingCleared: number;
-  l1Condensed: number;
-  l2Triggered: boolean;
-  validationFailed: boolean;
-  mcTriggered: boolean;
-  mcCleared: number;
-  budgetPersisted: number;
-}
-
-// ── Turn boundary detection ──
-
 // MC: 可被 Microcompact 清理的工具集
 export const COMPACTABLE_TOOLS = new Set([
   "read", "bash", "bash_background", "grep", "glob",
   "web_search", "web_fetch", "edit", "write",
 ]);
 
-export interface McStats {
-  triggered: boolean;
-  cleared: number;
-}
-
-export interface BudgetStats {
-  persisted: number;
-}
+// ── Turn boundary detection ──
 
 export function findTurnBoundaries(messages: AgentMessage[]): TurnBoundary[] {
   if (messages.length === 0) return [];

package/src/config.ts

@@ -119,20 +119,21 @@ export function loadConfig(
   settingsPath?: string,
 ): ContextEngineeringConfig {
   const filePath =
-    settingsPath ?? join(homedir(), ".pi", "agent", "settings.json");
+    settingsPath ?? join(homedir(), ".pi", "agent", "extensions", "context-engineering", "config.json");
 
   let raw: string;
   try {
     raw = readFileSync(filePath, "utf-8");
-  } catch {
-    return { ...DEFAULT_CONFIG };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { ...DEFAULT_CONFIG };
+    throw new Error(`Failed to read config ${filePath}: ${(err as Error).message}`);
   }
 
   let parsed: Record<string, unknown>;
   try {
     parsed = JSON.parse(raw) as Record<string, unknown>;
-  } catch {
-    return { ...DEFAULT_CONFIG };
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${filePath}: ${(err as Error).message}`);
   }
 
   const override = parsed["context-engineering"];
@@ -148,11 +149,14 @@ export function loadConfig(
 
 // ── 命令参数解析 ──
 
+// 命令参数最小部分数（target + action）
+const MIN_COMMAND_TOKENS = 2;
+
 export function parseLevelArgs(
   args: string,
 ): { target: "global" | "l0" | "l1" | "l2" | "mc" | "budget"; action: "on" | "off" } | null {
   const tokens = args.trim().split(/\s+/);
-  if (tokens.length < 2) {
+  if (tokens.length < MIN_COMMAND_TOKENS) {
     return null;
   }
 

package/src/index.ts

@@ -4,15 +4,16 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 
-import { loadConfig, type ContextEngineeringConfig } from "./config";
-import { createRecallStore, type RecallStore } from "./recall-store";
-import { createFrozenFreshState, type FrozenFreshState } from "./frozen-fresh";
+import { handleContextEngineeringCommand, handleContextStatsCommand } from "./commands";
 import {
+  type AgentMessage as CompressorMessage,
   compressContext,
   type CompressionStats,
-  type AgentMessage as CompressorMessage,
+  type ContextUsage as CompressorContextUsage,
 } from "./compressor";
-import { handleContextEngineeringCommand, handleContextStatsCommand } from "./commands";
+import { type ContextEngineeringConfig,loadConfig } from "./config";
+import { createFrozenFreshState, type FrozenFreshState } from "./frozen-fresh";
+import { createRecallStore, type RecallStore } from "./recall-store";
 
 const RecallParams = Type.Object({
   id: Type.String({ description: "Context ID (ctx-xxxxxxxx) to recall" }),
@@ -62,13 +63,13 @@ export default function contextEngineeringExtension(pi: ExtensionAPI): void {
     frozenFreshState = createFrozenFreshState();
   });
 
-  pi.on("context", (event: any, ctx: any) => {
+  pi.on("context", (event: { messages: unknown[] }, ctx: { getContextUsage(): unknown }) => {
     try {
       // Pi Extension API types differ from our internal message types.
       // Both sides define the same shape but TypeScript can't verify across packages.
       // If Pi's message format changes, compressContext will gracefully fail via the catch below.
       const msgs = event.messages as unknown as CompressorMessage[];
-      const result = compressContext(msgs, config, store, ctx.getContextUsage() as unknown as Parameters<typeof compressContext>[3], frozenFreshState);
+      const result = compressContext(msgs, config, store, ctx.getContextUsage() as unknown as CompressorContextUsage, frozenFreshState);
       addStats(cumulativeStats, result.stats);
       return { messages: result.messages as unknown as (typeof event.messages)[number][] };
     } catch (err) {
@@ -80,13 +81,17 @@ export default function contextEngineeringExtension(pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("session_tree", async () => {
+    // 切换分支后，cumulativeStats 将在下次 context 事件时自然更新
+  });
+
   pi.registerTool({
     name: "recall_context",
     label: "Recall Compressed Context",
     description: "Recall original content compressed by context engineering. Use when you need the full content of an expired, truncated, or condensed tool result.",
     promptSnippet: "recall_context(id) — retrieve original content compressed by context engineering",
     parameters: RecallParams,
-    execute: async (_tcId: string, params: any, _sig: any, _upd: any, _ctx: any) => recallResult(params.id, store),
+    execute: async (_tcId: string, params: { id: string }, _sig: unknown, _upd: unknown, _ctx: unknown) => recallResult(params.id, store),
   });
 
   pi.registerCommand("context-engineering", {

package/src/types.ts

@@ -0,0 +1,133 @@
+// types.ts — Shared type definitions for context-engineering extension
+
+// ── Message content block types ──
+
+export interface TextContent {
+  type: "text";
+  text: string;
+}
+
+export interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+  thinkingSignature?: string;
+  redacted?: boolean;
+}
+
+export interface ImageContent {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+
+export interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+// ── Message types (structural subset of pi-ai + Pi coding agent) ──
+
+export interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;
+}
+
+export interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+  };
+  stopReason: string;
+  timestamp: number;
+}
+
+export interface ToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: unknown;
+  isError: boolean;
+  timestamp: number;
+}
+
+export interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  timestamp: number;
+  excludeFromContext?: boolean;
+}
+
+export interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+
+export type AgentMessage =
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CompactionSummaryMessage;
+
+// ── Domain types ──
+
+export interface ContextUsage {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+
+export interface TurnBoundary {
+  startIndex: number;
+  endIndex: number; // 不含
+  timestamp: number;
+}
+
+// ── Stats types ──
+
+export interface L0Stats {
+  expired: number;
+  truncated: number;
+  thinkingCleared: number;
+}
+
+export interface CompressionStats {
+  l0Expired: number;
+  l0Truncated: number;
+  l0ThinkingCleared: number;
+  l1Condensed: number;
+  l2Triggered: boolean;
+  validationFailed: boolean;
+  mcTriggered: boolean;
+  mcCleared: number;
+  budgetPersisted: number;
+}
+
+export interface McStats {
+  triggered: boolean;
+  cleared: number;
+}
+
+export interface BudgetStats {
+  persisted: number;
+}