pi-context-map 0.1.4 → 0.3.0

package/dist/index.js

@@ -1,50 +0,0 @@
-"use strict";
-/**
- * pi-context-map
- * Pi extension to visualize session context window and token distribution.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = default_1;
-const analyzer_1 = require("./analyzer");
-const generator_1 = require("./generator");
-function default_1(pi) {
-    const analyzer = new analyzer_1.ContextAnalyzer();
-    // Register the /context-map command
-    pi.registerCommand("context-map", {
-        description: "Generate a visual map of the current session context window.",
-        handler: (_args, ctx) => {
-            ctx.ui.notify("Analyzing session context...", "info");
-            try {
-                // 1. Extract messages and current turn
-                // Note: We assume ctx.session.messages is available.
-                // If not, we may need to fetch them via another API or use provided event data.
-                const messages = ctx.session.messages || [];
-                const currentTurn = messages.length;
-                if (messages.length === 0) {
-                    ctx.ui.notify("No session history found to map.", "warning");
-                    return;
-                }
-                // 2. Analyze context
-                const map = analyzer.analyze(messages, currentTurn);
-                // 3. Generate HTML Report
-                const html = generator_1.ReportGenerator.generateHTML(map);
-                const reportPath = generator_1.ReportGenerator.writeReport(html);
-                ctx.ui.notify(`Context map generated successfully! \nPath: ${reportPath}`, "success");
-                // Providing a link or instruction to open the report
-                ctx.ui.notify("You can open the report.html in your browser to see the visualization.", "info");
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(`Failed to generate context map: ${message}`, "error");
-            }
-        },
-    });
-    // Optional: Notify the user when a significant amount of context is loaded
-    pi.on("session_before_compact", (event, ctx) => {
-        const { preparation } = event;
-        const tokens = preparation.tokensBefore;
-        if (tokens > 100_000) {
-            ctx.ui.notify(`High context load detected (${(tokens / 1000).toFixed(1)}k tokens). Try /context-map to see what's consuming space.`, "info");
-        }
-    });
-}

package/docs/proposal.md

@@ -1,41 +0,0 @@
-# Proposal: pi-context-map
-
-## 1. Problem Statement
-As Pi sessions grow in complexity, the "Context Window" becomes a black box. Users and agents often lose track of:
-- Which files are currently consuming the most tokens.
-- When a file was last "refreshed" (read) by the agent.
-- The distribution of tokens between history, system prompts, and tool outputs.
-
-This leads to "context bloat," where the agent becomes sluggish or forgets critical instructions because the window is filled with stale file content.
-
-## 2. Goal
-Create a Pi extension that provides a **real-time, visual map of the current session's context**. It should transform the abstract concept of a "token window" into a concrete, actionable dashboard.
-
-## 3. Core Features
-### A. `/context-map` Command
-A command that generates a visual report of the current context.
-
-### B. Context Analysis
-- **File Inventory**: List all files currently in context.
-- **Weight Tracking**: Approximate token count per file.
-- **Status Mapping**:
-    - `Active`: Read/Modified in the last 3 turns.
-    - `Stale`: Read 4-10 turns ago.
-    - `Legacy`: Read >10 turns ago (candidate for compaction).
-- **Operation History**: Mark if a file was Read 🟢, Written 🟠, or Edited 🟡.
-
-### C. Visual Output
-The extension will generate an `index.html` report (stored in `.pi/context-map/report.html`) featuring:
-- **Token Budget Bar**: Visual breakdown of context usage.
-- **File Treemap/List**: Files sized by their token weight.
-- **Temporal Timeline**: A simple timeline showing when files entered the context.
-
-## 4. Success Criteria
-- The user can run `/context-map` and immediately see which file is the "token hog."
-- The user can identify "stale" files that can be removed to free up space.
-- Zero performance degradation during normal session operation.
-- Full compatibility with `pi-ultra-compact` (since both manage context).
-
-## 5. Non-Goals
-- This is a *visualization* tool, not an *automatic* context cleaner (though it provides the data needed for a user to trigger compaction).
-- It will not modify the actual LLM context window, only report on it.

package/docs/spec.md

@@ -1,57 +0,0 @@
-# Technical Specification: pi-context-map
-
-## 1. Architecture Overview
-`pi-context-map` is a Pi extension that analyzes the session message history to derive a "map" of the active context. It operates as a read-only analysis tool triggered by a user command.
-
-## 2. Data Extraction Logic
-When `/context-map` is called, the extension will:
-1. **Scan Messages**: Iterate through all messages in the current session history.
-2. **Identify File Ops**:
-    - Scan `tool_use` blocks for `read`, `write`, `edit`, and `bash` (regex for file paths).
-    - Map each file to its most recent occurrence (turn number).
-3. **Calculate Weights**:
-    - For each file found, retrieve its content length from the corresponding `tool_result` if available.
-    - Estimate tokens using a heuristic: $\text{tokens} \approx \text{chars} / 4$.
-4. **Assign Status**:
-    - **Active**: Turn difference $\le 3$.
-    - **Stale**: $3 <$ Turn difference $\le 10$.
-    - **Legacy**: Turn difference $> 10$.
-
-## 3. Component Design
-
-### A. `ContextAnalyzer` (Class)
-- `analyze(messages: Message[])`: Returns a `ContextMap` object.
-- `calculateTokens(text: string)`: Returns estimated token count.
-- `getFileMetadata(path: string)`: Tracks the operation type and timestamp.
-
-### B. `ReportGenerator` (Class)
-- `generateHTML(map: ContextMap)`: Produces a standalone HTML string.
-- `writeReport(html: string)`: Saves the report to `.pi/context-map/report.html` and opens it.
-
-### C. `ExtensionEntry` (Main)
-- `pi.registerCommand("context-map", ...)`: The entry point.
-- `pi.on("session_before_compact", ...)`: (Optional) Could trigger a map update before compaction.
-
-## 4. Visual Specification (HTML Dashboard)
-The report will be a single-file HTML dashboard with:
-- **Header**: Session ID, Total Estimated Tokens, and Timestamp.
-- **Context Budget**: A CSS-based stacked bar showing:
-    - `[ System ] [ History ] [ Files ] [ Tool Outputs ]`
-- **File Grid**:
-    - Cards for each file.
-    - Size proportional to token weight.
-    - Color-coded by status (Green $\to$ Yellow $\to$ Red).
-    - Icons for operation type (👁️ for read, ✍️ for edit).
-- **Stats Table**:
-    - File Path | Tokens | Last Turn | Status.
-
-## 5. Implementation Details
-- **Language**: TypeScript.
-- **Dependencies**: `@earendil-works/pi-coding-agent`, `node:fs`, `node:path`.
-- **Complexity**: 
-    - Time: $O(N)$ where $N$ is number of messages.
-    - Space: $O(F)$ where $F$ is number of unique files in context.
-
-## 6. Error Handling
-- **Missing Tool Results**: If a file was read but the result is missing (e.g., due to previous compaction), mark weight as "Unknown" and status as "Stale".
-- **Large Repos**: Limit the map to the top 100 largest files to prevent the HTML report from crashing the browser.

package/src/index.ts

@@ -1,67 +0,0 @@
-/**
- * pi-context-map
- * Pi extension to visualize session context window and token distribution.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { ContextAnalyzer } from "./analyzer";
-import { ReportGenerator } from "./generator";
-
-export default function (pi: ExtensionAPI) {
-	const analyzer = new ContextAnalyzer();
-
-	// Register the /context-map command
-	pi.registerCommand("context-map", {
-		description: "Generate a visual map of the current session context window.",
-		handler: (_args, ctx) => {
-			ctx.ui.notify("Analyzing session context...", "info");
-
-			try {
-				// 1. Extract messages and current turn
-				// Note: We assume ctx.session.messages is available.
-				// If not, we may need to fetch them via another API or use provided event data.
-				const messages = ctx.session.messages || [];
-				const currentTurn = messages.length;
-
-				if (messages.length === 0) {
-					ctx.ui.notify("No session history found to map.", "warning");
-					return;
-				}
-
-				// 2. Analyze context
-				const map = analyzer.analyze(messages, currentTurn);
-
-				// 3. Generate HTML Report
-				const html = ReportGenerator.generateHTML(map);
-				const reportPath = ReportGenerator.writeReport(html);
-
-				ctx.ui.notify(
-					`Context map generated successfully! \nPath: ${reportPath}`,
-					"success",
-				);
-
-				// Providing a link or instruction to open the report
-				ctx.ui.notify(
-					"You can open the report.html in your browser to see the visualization.",
-					"info",
-				);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.notify(`Failed to generate context map: ${message}`, "error");
-			}
-		},
-	});
-
-	// Optional: Notify the user when a significant amount of context is loaded
-	pi.on("session_before_compact", (event, ctx) => {
-		const { preparation } = event;
-		const tokens = preparation.tokensBefore;
-
-		if (tokens > 100_000) {
-			ctx.ui.notify(
-				`High context load detected (${(tokens / 1000).toFixed(1)}k tokens). Try /context-map to see what's consuming space.`,
-				"info",
-			);
-		}
-	});
-}

package/src/types/pi-coding-agent.d.ts

@@ -1,31 +0,0 @@
-declare module "@earendil-works/pi-coding-agent" {
-	export interface ExtensionAPI {
-		registerCommand(
-			name: string,
-			options: {
-				description: string;
-				handler: (
-					args: string | undefined,
-					ctx: ExtensionContext,
-				) => Promise<void> | void;
-			},
-		): void;
-		on(
-			event: string,
-			handler: (event: any, ctx: ExtensionContext) => Promise<void> | void,
-		): void;
-	}
-
-	export interface ExtensionContext {
-		ui: {
-			notify(
-				message: string,
-				level: "info" | "success" | "warning" | "error",
-			): void;
-		};
-		session: {
-			messages: any[];
-		};
-		modelRegistry: any;
-	}
-}

package/tasks.md

@@ -1,32 +0,0 @@
-# Implementation Tasks: pi-context-map
-
-## Phase 1: Foundation
-- [ ] Initialize `package.json` and TypeScript config.
-- [ ] Create project folder structure (`src/`, `docs/`).
-
-## Phase 2: Core Logic (`ContextAnalyzer`)
-- [ ] Implement message scanning logic to find file operations.
-- [ ] Implement token estimation heuristic.
-- [ ] Implement status assignment (Active/Stale/Legacy).
-- [ ] Create unit tests for analyzer logic.
-
-## Phase 3: Visualization (`ReportGenerator`)
-- [ ] Design the HTML dashboard template.
-- [ ] Implement data-to-HTML mapping.
-- [ ] Implement file writing to `.pi/context-map/report.html`.
-
-## Phase 4: Pi Integration
-- [ ] Register `/context-map` command.
-- [ ] Implement command handler that triggers analysis $\to$ report $\to$ notification.
-- [ ] Add "Open Report" link in the Pi notification.
-
-## Phase 5: QA & Polishing
-- [ ] Test with high-token sessions.
-- [ ] Verify accuracy of token weights.
-- [ ] Run Pi Lens diagnostics to ensure zero blockers.
-- [ ] Polish HTML CSS for "Architect" look.
-
-## Phase 6: Release
-- [ ] Update README.md.
-- [ ] Publish to npm.
-- [ ] Final GitHub release.

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true,
-    "baseUrl": ".",
-    "paths": {
-      "*": ["src/types/*"]
-    }
-  },
-  "include": ["src/**/*"],
-  "typeRoots": ["./node_modules/@types", "src/types"]
-}