pi-context-map 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.4.1] - 2026-06-15
+### Critical Fix & Test Suite
+- **Fixed CRASH**: `(pi as any).session?.messages` → now uses event-based message accumulation. `/context-map` no longer crashes with "Cannot read properties of undefined (reading 'messages')".
+- **Fixed Tool Signature**: `registerTool` now uses correct `execute(params, signal, onUpdate, ctx)` signature.
+- **Fixed Import Path**: Uses `pi-coding-agent` (unscoped) instead of `@earendil-works/pi-coding-agent`.
+- **Test Suite**: 34 tests across 5 suites (analyzer, token-counter, insights, generator, live-server).
+- **Type Declarations**: Proper `pi-coding-agent.d.ts` with `ToolDefinition`, `ExtensionCommandContext`, `ExtensionContext`.
+- **Build Clean**: TypeScript strict mode passes with zero errors.
+- **Live SSE Server**: New `LiveReportServer` binds to 127.0.0.1 on a free port and serves the report at `/`.
+- **Auto-Updates**: Server-Sent Events endpoint at `/events` pushes the latest HTML whenever the analysis re-runs (e.g., after each assistant message).
+- **Token Auth**: Each server instance generates a unique session token; the HTML client picks it up via a `<meta>` tag and includes it in the SSE URL to prevent unauthorized access.
+- **Origin Validation**: Only connections from `http://127.0.0.1:<port>` or `http://localhost:<port>` are allowed.
+- **Graceful Shutdown**: `/context-map stop` or `session_shutdown` event stops the server cleanly.
+- **Auto-Refresh**: The `message_end` event triggers an automatic re-analysis when the live server is running, so the browser view stays in sync.
+- **Health & Stop Endpoints**: `/health` for liveness, `POST /stop` for remote termination.
+
 ## [0.3.1] - 2026-06-14
 ### Design & Interactivity Upgrade
 - **Linear Design System**: Refactored CSS to use the Linear design tokens (canvas #010102, accent #5e6ad2) for a professional, near-black aesthetic.

package/README.md

@@ -48,6 +48,27 @@ The extension categorizes files to help you manage context bloat:
 3. **Categorization**: It calculates the temporal distance between the current turn and the last file access.
 4. **Visualization**: It generates a standalone HTML dashboard featuring a stacked composition bar, a file-weight grid with search/filter, and an interactive insights section.
 
+## Live Localhost Server
+
+When the extension loads, it automatically starts a local HTTP server on `127.0.0.1` (a random free port). The server:
+
+- Serves the current report at `http://127.0.0.1:<port>/`.
+- Pushes live updates via Server-Sent Events at `/events?token=<sessionToken>`.
+- Authenticates the SSE connection with a per-session token (injected into the HTML as a `<meta>` tag).
+- Auto-refreshes after each assistant message, so the browser view stays in sync.
+
+**Commands:**
+
+- `/context-map` — Generate a fresh report and broadcast it to the browser.
+- `/context-map stop` — Stop the live server.
+
+**Endpoints:**
+
+- `GET /` or `/report.html` — The current report HTML.
+- `GET /events?token=...` — Server-Sent Events stream of updates.
+- `GET /health` — Returns `{ "status": "ok", "port": <number> }`.
+- `POST /stop` — Gracefully stops the server.
+
 ## Design
 
 The report uses the **Linear design system** (canvas `#010102`, accent `#5e6ad2`) with **shadcn/ui card patterns**. See `docs/design.md` for the full specification. The output is a single self-contained HTML file with no external dependencies.

package/extensions/generator.ts

@@ -615,6 +615,37 @@ export class ReportGenerator {
 
     <script>
         (function() {
+            // ===== Live update via Server-Sent Events =====
+            // Token is injected into the script via a meta tag (set by the server).
+            // Connect to /events?token=...; when the server pushes a new html payload, replace the document.
+            try {
+                var tokenMeta = document.querySelector('meta[name="context-map-token"]');
+                var token = tokenMeta ? tokenMeta.getAttribute('content') : '';
+                var evtSource = new EventSource('/events?token=' + encodeURIComponent(token));
+                evtSource.onmessage = function(e) {
+                    try {
+                        var payload = JSON.parse(e.data);
+                        if (payload.html) {
+                            // Replace the document body with the new HTML
+                            var parser = new DOMParser();
+                            var newDoc = parser.parseFromString(payload.html, 'text/html');
+                            document.documentElement.replaceChild(
+                                document.importNode(newDoc.documentElement, true),
+                                document.documentElement
+                            );
+                        }
+                    } catch (err) {
+                        console.warn('Failed to apply live update:', err);
+                    }
+                };
+                evtSource.onerror = function() {
+                    // Silently close on error; user can refresh the page to reconnect
+                    evtSource.close();
+                };
+            } catch (err) {
+                // EventSource not available; fall back to manual refresh
+            }
+
             // ===== Insight collapse/expand =====
             document.querySelectorAll('.insight-header[data-toggle]').forEach(function(btn) {
                 btn.addEventListener('click', function() {
@@ -630,7 +661,7 @@ export class ReportGenerator {
             var grid = document.getElementById('fileGrid');
             var count = document.getElementById('fileCount');
             var empty = document.getElementById('emptyState');
-            var cards = Array.prototype.slice.call(grid.querySelectorAll('.file-card'));
+            var cards = grid ? Array.prototype.slice.call(grid.querySelectorAll('.file-card')) : [];
             var total = cards.length;
 
             function applyFilters() {

package/extensions/index.ts

@@ -1,92 +1,175 @@
 /**
  * pi-context-map
  * Professional Context Profiler for Pi.
+ * v0.4.1 — Fixes session.messages crash, tool registration signature, adds tests.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	AgentMessage,
+} from "pi-coding-agent";
 import { ContextAnalyzer } from "./analyzer";
 import { ReportGenerator } from "./generator";
 import { InsightEngine } from "./insights";
+import { LiveReportServer } from "./live-server";
+import * as path from "node:path";
+import * as os from "node:os";
 
-export default async function piContextMap(pi: ExtensionAPI) {
+const REPORT_PATH = path.join(
+	os.homedir(),
+	".pi",
+	"context-map",
+	"report.html",
+);
+
+export default async function piContextMap(pi: ExtensionAPI): Promise<void> {
 	const analyzer = new ContextAnalyzer();
+	const liveServer = new LiveReportServer();
+
+	// Accumulate messages from events — this is the correct way to access
+	// session messages in Pi. (pi as any).session?.messages does NOT exist.
+	let sessionMessages: AgentMessage[] = [];
+	let currentTurn = 0;
+
+	// Capture messages before each LLM call
+	pi.on("context", (event: any) => {
+		if (event?.messages && Array.isArray(event.messages)) {
+			sessionMessages = event.messages;
+		}
+	});
+
+	// Track turns
+	pi.on("turn_start", () => {
+		currentTurn++;
+	});
 
-	async function runAnalysis() {
-		const messages = (pi as any).session?.messages || [];
-		const currentTurn = messages.length;
+	async function runAnalysis(): Promise<{
+		composition: ReturnType<typeof analyzer.analyzeByType>;
+		insights: ReturnType<typeof InsightEngine.generate>;
+		reportPath: string;
+	}> {
+		const messages = sessionMessages.length > 0 ? sessionMessages : [];
 		const composition = analyzer.analyzeByType(messages, currentTurn);
 		const insights = InsightEngine.generate(composition);
 		const html = ReportGenerator.generateHTML(composition, insights);
-		const reportPath = ReportGenerator.writeReport(html);
-		return { composition, insights, reportPath };
+
+		// Write to disk
+		try {
+			const fs = await import("node:fs");
+			const dir = path.dirname(REPORT_PATH);
+			if (!fs.existsSync(dir)) {
+				fs.mkdirSync(dir, { recursive: true });
+			}
+			fs.writeFileSync(REPORT_PATH, html, "utf8");
+		} catch (err: any) {
+			console.error(`[pi-context-map] Failed to write report: ${err.message}`);
+		}
+
+		// Push to live server if running
+		if (liveServer.isRunning) {
+			liveServer.update(html, REPORT_PATH);
+		}
+
+		return { composition, insights, reportPath: REPORT_PATH };
 	}
 
+	// Start live server
+	const serverUrl = await liveServer.start();
+
+	// Register /context-map command
 	pi.registerCommand("context-map", {
-		description: "Generate a visual context map with actionable insights.",
-		handler: async (_args: any, ctx: any) => {
+		description:
+			"Generate a visual context map with actionable insights. Use 'stop' to terminate the live server.",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (args.trim().toLowerCase() === "stop") {
+				liveServer.stop();
+				ctx.ui.notify("Live server stopped.", "info");
+				return;
+			}
+
 			ctx.ui.notify("Analyzing session context...", "info");
 			try {
-				const { reportPath, insights } = await runAnalysis();
+				const { insights, reportPath } = await runAnalysis();
 				const criticalCount = insights.filter(
 					(i) => i.severity === "critical",
 				).length;
 				const summary =
 					criticalCount > 0
 						? `Context map generated. ${criticalCount} critical insight(s) found.`
-						: `Context map generated successfully.`;
+						: "Context map generated successfully.";
+				let details = `File: ${reportPath}`;
+				if (serverUrl) {
+					details += ` | Live: ${serverUrl}`;
+				}
 				ctx.ui.notify(
-					`${summary} Path: ${reportPath}`,
+					`${summary} ${details}`,
 					criticalCount > 0 ? "warning" : "success",
 				);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.notify(`Failed to generate context map: ${message}`, "error");
+			} catch (error: any) {
+				ctx.ui.notify(
+					`Failed to generate context map: ${error.message}`,
+					"error",
+				);
 			}
 		},
 	});
 
+	// Register the tool for agent use
 	pi.registerTool({
 		name: "context-map",
+		label: "Context Map",
 		description:
-			"Analyze the current session context composition and return actionable insights.",
+			"Analyze the current session context composition and return actionable insights. The live localhost report will auto-update.",
 		parameters: {
 			type: "object",
 			properties: {},
 		},
-		handler: async (_ctx: any, _args: any) => {
+		async execute(
+			_params: any,
+			_signal: AbortSignal | undefined,
+			_onUpdate: ((u: any) => void) | undefined,
+			_ctx: any,
+		) {
 			try {
 				const { composition, insights } = await runAnalysis();
+				const usagePercent =
+					composition.total.tokens > 0
+						? Math.round((composition.total.tokens / 128_000) * 100)
+						: 0;
 				const summary =
 					`Context: ${composition.total.tokens.toLocaleString()} tokens total. ` +
 					`System ${composition.system.percent}%, Tools ${composition.tools.percent}%, ` +
 					`History ${composition.history.percent}%, Files ${composition.files.percent}%, ` +
 					`Summaries ${composition.summaries.percent}%. ` +
+					`Usage: ${usagePercent}% of typical 128k window. ` +
 					`${insights.length} insight(s) generated.`;
 				return {
-					summary,
-					composition: {
-						system: composition.system.tokens,
-						tools: composition.tools.tokens,
-						history: composition.history.tokens,
-						files: composition.files.tokens,
-						summaries: composition.summaries.tokens,
-						total: composition.total.tokens,
-					},
-					insights: insights.map((i) => ({
-						severity: i.severity,
-						title: i.title,
-						message: i.message,
-						command: i.command,
-					})),
+					type: "text" as const,
+					content: [
+						summary,
+						"",
+						...insights.map(
+							(i) => `[${i.severity.toUpperCase()}] ${i.title}: ${i.message}`,
+						),
+						serverUrl ? `Live report: ${serverUrl}` : "",
+					]
+						.filter(Boolean)
+						.join("\n"),
 				};
 			} catch (error: any) {
-				return { error: error.message };
+				return {
+					type: "text" as const,
+					content: `Error: ${error.message}`,
+					isError: true,
+				};
 			}
 		},
 	});
 
-	pi.on("session_before_compact", (event: any, ctx: any) => {
-		const tokens = (event as any).preparation?.tokensBefore;
+	// Auto-warning on high context before compaction
+	pi.on("session_before_compact", (_event: any, ctx: any) => {
+		const tokens = _event?.preparation?.tokensBefore;
 		if (tokens && 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.`,
@@ -94,4 +177,27 @@ export default async function piContextMap(pi: ExtensionAPI) {
 			);
 		}
 	});
+
+	// Auto-refresh after each assistant message if server is running
+	pi.on("message_end", async (_event: any) => {
+		if (_event?.message?.role === "assistant" && liveServer.isRunning) {
+			try {
+				await runAnalysis();
+			} catch {
+				// Silently ignore auto-refresh failures
+			}
+		}
+	});
+
+	// Graceful shutdown
+	pi.on("session_shutdown", () => {
+		liveServer.stop();
+	});
+
+	if (serverUrl) {
+		console.log(`[pi-context-map] Live server running at ${serverUrl}`);
+		console.log(
+			`[pi-context-map] Run /context-map to generate a report, or /context-map stop to terminate.`,
+		);
+	}
 }

package/extensions/live-server.ts

@@ -0,0 +1,301 @@
+/**
+ * LiveReportServer
+ * Serves the context map HTML report on a local HTTP server with live updates via SSE.
+ *
+ * Features:
+ *  - Auto-assigns a free port (pass 0 to OS).
+ *  - Binds to 127.0.0.1 only (no external access).
+ *  - Serves the current report HTML at `/`.
+ *  - Streams updates via Server-Sent Events at `/events`.
+ *  - Graceful shutdown via `stop()`.
+ *  - Null-safe error handling throughout.
+ */
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import type { AddressInfo } from "node:net";
+
+const DEFAULT_REPORT_PATH = path.join(
+	os.homedir(),
+	".pi",
+	"context-map",
+	"report.html",
+);
+
+/**
+ * Allowed origins for SSE connections. Only localhost variants are allowed.
+ */
+function isAllowedOrigin(origin: string | undefined, port: number): boolean {
+	if (!origin) return true; // No Origin header (e.g., direct curl) is allowed
+	const allowed = [
+		`http://127.0.0.1:${port}`,
+		`http://localhost:${port}`,
+		"http://127.0.0.1",
+		"http://localhost",
+	];
+	return allowed.some((o) => origin.startsWith(o));
+}
+
+export class LiveReportServer {
+	private server: http.Server | null = null;
+	private clients: Set<http.ServerResponse> = new Set();
+	private currentHtml: string = "";
+	private port: number = 0;
+	private host: string = "127.0.0.1";
+	/** Session token to prevent unauthorized access. */
+	public readonly token: string = crypto.randomBytes(16).toString("hex");
+
+	/**
+	 * Start the server. Returns a Promise that resolves to the URL, or null on failure.
+	 */
+	public start(): Promise<string | null> {
+		if (this.server) {
+			return Promise.resolve(this.url);
+		}
+
+		return new Promise((resolve) => {
+			try {
+				this.server = http.createServer((req, res) =>
+					this.handleRequest(req, res),
+				);
+				this.server.on("error", (err) => {
+					console.error(`[pi-context-map] Server error: ${err.message}`);
+					this.stop();
+				});
+
+				this.server.listen(0, this.host, () => {
+					const addr = this.server?.address() as AddressInfo | null;
+					if (addr) {
+						this.port = addr.port;
+						console.log(`[pi-context-map] Live server: ${this.url}`);
+						resolve(this.url);
+					} else {
+						resolve(null);
+					}
+				});
+			} catch (err: any) {
+				console.error(
+					`[pi-context-map] Failed to start server: ${err.message}`,
+				);
+				resolve(null);
+			}
+		});
+	}
+
+	/**
+	 * Stop the server and close all client connections.
+	 */
+	public stop(): void {
+		if (!this.server) return;
+
+		// Close all SSE clients
+		for (const client of this.clients) {
+			try {
+				client.end();
+			} catch (err) {
+				// Ignore errors on close
+			}
+		}
+		this.clients.clear();
+
+		// Close the server
+		this.server.close((err) => {
+			if (err) {
+				console.error(`[pi-context-map] Error closing server: ${err.message}`);
+			}
+		});
+		this.server = null;
+		this.port = 0;
+	}
+
+	/**
+	 * Update the report content and broadcast to all connected clients.
+	 * @param html The new HTML content.
+	 * @param reportPath Optional path to the report file to also write to disk.
+	 */
+	public update(html: string, reportPath?: string): void {
+		this.currentHtml = html;
+
+		// Optionally write to disk
+		if (reportPath) {
+			try {
+				const dir = path.dirname(reportPath);
+				if (!fs.existsSync(dir)) {
+					fs.mkdirSync(dir, { recursive: true });
+				}
+				fs.writeFileSync(reportPath, html, "utf8");
+			} catch (err: any) {
+				console.error(
+					`[pi-context-map] Failed to write report: ${err.message}`,
+				);
+			}
+		}
+
+		// Broadcast to all SSE clients
+		for (const client of this.clients) {
+			try {
+				client.write(
+					`data: ${JSON.stringify({ html, timestamp: Date.now() })}\n\n`,
+				);
+			} catch (err) {
+				// Client may have disconnected; remove it
+				this.clients.delete(client);
+			}
+		}
+	}
+
+	/**
+	 * Get the URL the server is listening on, or null if not started.
+	 */
+	public get url(): string | null {
+		if (!this.server || this.port === 0) return null;
+		return `http://${this.host}:${this.port}`;
+	}
+
+	/**
+	 * Whether the server is currently running.
+	 */
+	public get isRunning(): boolean {
+		return this.server !== null;
+	}
+
+	/**
+	 * Handle incoming HTTP requests.
+	 */
+	private handleRequest(
+		req: http.IncomingMessage,
+		res: http.ServerResponse,
+	): void {
+		if (!req.url) {
+			res.writeHead(400);
+			res.end("Bad request");
+			return;
+		}
+
+		const url = new URL(req.url, `http://${this.host}:${this.port}`);
+
+		// SSE endpoint for live updates
+		if (url.pathname === "/events") {
+			this.handleSSE(req, res);
+			return;
+		}
+
+		// Health check
+		if (url.pathname === "/health") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ status: "ok", port: this.port }));
+			return;
+		}
+
+		// Stop endpoint
+		if (url.pathname === "/stop" && req.method === "POST") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ status: "stopping" }));
+			setTimeout(() => this.stop(), 100);
+			return;
+		}
+
+		// Main page: serve the current HTML or load from disk
+		if (url.pathname === "/" || url.pathname === "/report.html") {
+			let html = this.currentHtml;
+			if (!html) {
+				// Try to load from disk as fallback
+				try {
+					html = fs.readFileSync(DEFAULT_REPORT_PATH, "utf8");
+				} catch {
+					html = this.placeholderHtml();
+				}
+			}
+			// Inject the session token so the client can authenticate to /events
+			if (html.includes("<head>")) {
+				html = html.replace(
+					"<head>",
+					`<head><meta name="context-map-token" content="${this.token}">`,
+				);
+			}
+			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+			res.end(html);
+			return;
+		}
+
+		// 404 for everything else
+		res.writeHead(404);
+		res.end("Not found");
+	}
+
+	/**
+	 * Handle Server-Sent Events connection.
+	 */
+	private handleSSE(req: http.IncomingMessage, res: http.ServerResponse): void {
+		// Token-based auth: require ?token=<sessionToken> to prevent unauthorized SSE subscriptions
+		if (!req.url) {
+			res.writeHead(400);
+			res.end("Bad request");
+			return;
+		}
+		const reqUrl = new URL(req.url, `http://${this.host}:${this.port}`);
+		const providedToken = reqUrl.searchParams.get("token");
+		if (providedToken !== this.token) {
+			res.writeHead(401, { "Content-Type": "text/plain" });
+			res.end("Unauthorized: invalid or missing token");
+			return;
+		}
+
+		// Origin validation: only allow connections from localhost
+		if (!isAllowedOrigin(req.headers.origin, this.port)) {
+			res.writeHead(403, { "Content-Type": "text/plain" });
+			res.end("Forbidden: origin not allowed");
+			return;
+		}
+
+		res.writeHead(200, {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive",
+			"Access-Control-Allow-Origin": `http://127.0.0.1:${this.port}`,
+		});
+
+		// Send initial state if we have content
+		if (this.currentHtml) {
+			res.write(
+				`data: ${JSON.stringify({ html: this.currentHtml, timestamp: Date.now() })}\n\n`,
+			);
+		} else {
+			res.write(`data: ${JSON.stringify({ waiting: true })}\n\n`);
+		}
+
+		this.clients.add(res);
+
+		// Heartbeat to keep connection alive (every 30s)
+		const heartbeat = setInterval(() => {
+			try {
+				res.write(": heartbeat\n\n");
+			} catch {
+				clearInterval(heartbeat);
+				this.clients.delete(res);
+			}
+		}, 30000);
+
+		req.on("close", () => {
+			clearInterval(heartbeat);
+			this.clients.delete(res);
+		});
+	}
+
+	/**
+	 * Placeholder HTML shown when no report has been generated yet.
+	 */
+	private placeholderHtml(): string {
+		return `<!DOCTYPE html>
+<html><head><title>pi-context-map</title>
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#010102;color:#f7f8f8;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;}</style>
+</head><body>
+<div style="text-align:center;">
+<h1 style="color:#5e6ad2;font-size:24px;font-weight:600;">pi-context-map</h1>
+<p style="color:#8a8f98;margin-top:8px;">No report generated yet. Run <code>/context-map</code> in Pi to generate one.</p>
+</div>
+</body></html>`;
+	}
+}

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

@@ -1,3 +1,101 @@
-declare module "@earendil-works/pi-coding-agent" {
-	export type ExtensionAPI = any;
+declare module "pi-coding-agent" {
+	export interface ExtensionAPI {
+		on(event: string, handler: Function): void;
+		registerTool<TDetails = unknown>(tool: ToolDefinition<TDetails>): void;
+		registerCommand(
+			name: string,
+			options: {
+				description?: string;
+				handler: (
+					args: string,
+					ctx: ExtensionCommandContext,
+				) => Promise<void> | void;
+			},
+		): void;
+		registerProvider(name: string, config: any): void;
+		unregisterProvider(name: string): void;
+		sendMessage(message: any, options?: any): void;
+		sendUserMessage(content: string | any[], options?: any): void;
+		appendEntry(customType: string, data?: any): void;
+		setSessionName(name: string): void;
+		getSessionName(): string | undefined;
+		setLabel(entryId: string, label: string | undefined): void;
+		getActiveTools(): string[];
+		getAllTools(): any[];
+		setActiveTools(toolNames: string[]): void;
+	}
+
+	export interface ToolDefinition<TDetails = unknown> {
+		name: string;
+		label: string;
+		description: string;
+		promptSnippet?: string;
+		promptGuidelines?: string[];
+		parameters: any;
+		execute(
+			params: any,
+			signal: AbortSignal | undefined,
+			onUpdate: ((update: TDetails) => void) | undefined,
+			ctx: ExtensionContext,
+		): Promise<{ type: "text"; content: string; isError?: boolean }>;
+		renderCall?: (args: any, theme: any) => any;
+		renderResult?: (result: any, options: any, theme: any) => any;
+	}
+
+	export interface ExtensionContext {
+		ui: ExtensionUIContext;
+		hasUI: boolean;
+		cwd: string;
+		sessionManager: any;
+		model: any;
+		isIdle(): boolean;
+		abort(): void;
+		shutdown(): void;
+		getContextUsage():
+			| { tokens: number | null; contextWindow: number; percent: number | null }
+			| undefined;
+		compact(options?: any): void;
+		getSystemPrompt(): string;
+	}
+
+	export interface ExtensionUIContext {
+		notify(
+			message: string,
+			type?: "info" | "warning" | "error" | "success",
+		): void;
+	}
+
+	export interface ExtensionCommandContext {
+		ui: ExtensionUIContext;
+		hasUI: boolean;
+		cwd: string;
+		sessionManager: any;
+		model: any;
+		isIdle(): boolean;
+		abort(): void;
+		shutdown(): void;
+		getContextUsage(): any;
+		compact(options?: any): void;
+		getSystemPrompt(): string;
+		waitForIdle(): Promise<void>;
+		newSession(options?: any): Promise<{ cancelled: boolean }>;
+		fork(entryId: string): Promise<{ cancelled: boolean }>;
+		navigateTree(
+			targetId: string,
+			options?: any,
+		): Promise<{ cancelled: boolean }>;
+		switchSession(sessionPath: string): Promise<{ cancelled: boolean }>;
+		reload(): Promise<void>;
+	}
+
+	export interface AgentMessage {
+		role: "user" | "assistant" | "system" | "tool";
+		content?: any;
+		id?: string;
+		name?: string;
+		tool_call_id?: string;
+		type?: string;
+		compactionEntry?: any;
+		timestamp?: number;
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context-map",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Professional context profiler for Pi that visualizes the session context window, token distribution, and integrates with Nexus packages for actionable insights.",
   "keywords": [
     "pi-package",