pi-context-engine 0.5.3 → 0.7.0

package/README.md

@@ -37,7 +37,7 @@ runs fixed queries. Run it yourself; nothing is cherry-picked.
 
 ## What you get
 
-Ten tools the agent can call, plus four slash commands.
+Ten tools the agent can call, plus five slash commands.
 
 **Search**
 - **`context_search`**: hybrid vector + BM25 retrieval with confidence scores.
@@ -56,8 +56,8 @@ Ten tools the agent can call, plus four slash commands.
 - **`index_status`**: chunk count and measured savings.
 - **`reindex`**: refresh a path or the whole project.
 
-Commands: `/context-index [--full]`, `/context-status`, `/context-savings`,
-`/context-warmup`.
+Commands: `/context-index [--full] [--reset]`, `/context-status`, `/context-savings`,
+`/context-warmup`, `/context-dashboard`.
 
 **Shipped guidance.** The package also injects a ~900-token guidance section
 into the system prompt while `context_search` is active: how to formulate
@@ -119,6 +119,14 @@ unchanged repo took 237 ms.
   Migration runs (schema reset, embedding-dimension change) are exempt: their
   manifest stays untouched on disk until the run completes, so an interrupted
   migration resumes cleanly instead of stranding stale rows.
+- **One-command reset**: `/context-index --reset` deletes the index through the
+  engine while the session is running: sqlite handles are closed first, so it
+  succeeds where manual deletion of the storage directory fails with locked
+  file errors (EPERM on Windows). The report shows how many files and bytes
+  were freed, and memory, sessions, and the savings ledger survive. The
+  embedding cache is deleted too, so a rebuild re-embeds from scratch. The
+  next search rebuilds via the lazy kick, guarded by the same file budget as
+  every automatic run.
 - **Cold-start visibility**: the first build on an empty index announces its
   start (`building the first index…`) and always closes with a result line
   (`updated: N file(s)` or `no files to index`). This is the one background
@@ -142,6 +150,26 @@ unchanged repo took 237 ms.
   provisioning step (a devcontainer `postCreateCommand`, a CI cache setup),
   keeping first searches fast.
 
+### Web dashboard
+
+`/context-dashboard` starts a small read-only web server inside the pi process
+and opens it in your browser. Port is picked per session; set `dashboard.port`
+in config for a stable URL.
+
+- **Overview**: donut of measured savings, chunk/file counts, live indexing
+  state (polled every 5 s), and the active configuration.
+- **Files**: every indexed file with its chunk count, largest first.
+- **Sessions**: past sessions with per-turn summaries and tool events.
+- **Memory**: recorded decisions and code areas.
+- **Savings**: the per-bucket ledger with dollar estimates and a 30-day trend.
+- **Export**: one JSON download of all of the above.
+
+The dashboard is strictly read-only: every state change (reindex, reset,
+config) stays in pi commands. It binds to `127.0.0.1` only, serves GET
+requests only, and rejects requests whose `Host` header is not loopback, so a
+malicious page cannot read your index data via DNS rebinding. It stops when
+the session ends.
+
 ## Requirements
 
 - **Node 22+** on macOS, Linux or Windows.
@@ -212,6 +240,8 @@ indexer:
   watch: true             # reindex on file changes while the session runs (debounced, incremental)
 memory:
   redact_pii: true
+dashboard:
+  port: 0                # 0 = pick a free port; set one for a stable dashboard URL
 pricing:
   model: opus            # opus | sonnet | haiku | gpt-4o | gemini-2.5-pro | ...
 storage:
@@ -261,6 +291,10 @@ by default:
 Path arguments are validated against the project root, so a crafted `path` cannot
 read outside it.
 
+The web dashboard adds its own guards: loopback binding, GET-only routing, and
+`Host` header validation against DNS rebinding. With no mutating endpoints,
+there is nothing for a cross-site request to trigger.
+
 ## Supported languages
 
 **AST chunking** (tree-sitter): Python, JavaScript, TypeScript, TSX, PHP, Go,
@@ -278,13 +312,17 @@ This is a port, not a wrapper. Three deliberate changes:
   the `curl`-based Claude Code hooks. Session capture rides on pi's own events.
 - **No Python runtime**: embeddings run through transformers.js or Ollama, so
   installation is one npm command.
+- **Dashboard rebuilt, not ported**: upstream serves its dashboard from a
+  FastAPI app with a mutating REST surface. Ours is a read-only `node:http`
+  server (zero dependencies) with a fresh single-file page — same tabs, no
+  write endpoints.
 - **Two upstream bugs fixed**: chunk ids now include column offsets (identical
   spans on one line used to overwrite each other in the index), and the
   placeholder filter no longer suppresses unambiguous vendor keys that happen to
   contain a word like `example`.
 
-Not ported (yet): the web dashboard, output-compression rules, and editor
-bootstrapping for non-pi editors.
+Not ported (yet): output-compression rules and editor bootstrapping for
+non-pi editors.
 
 ## Development
 
@@ -294,6 +332,7 @@ npm run check          # typecheck + 251 unit tests
 npm run smoke:env      # tree-sitter + sqlite-vec capability check
 npm run smoke:loader   # load the extension through pi's jiti loader
 npm run smoke:real-world  # index this repo with the local embedder
+npx tsx scripts/smoke-dashboard.mts  # boot the dashboard, probe every route, write a static UI preview
 ```
 
 ## Credits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context-engine",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Semantic code context for pi: tree-sitter index + hybrid vector/BM25 retrieval + cross-session memory, all local. Port of code-context-engine (MIT, elara-labs) as a native pi extension.",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -105,6 +105,8 @@ export interface Config {
 	indexerWatch: boolean;
 	indexerRedactSecrets: boolean;
 	memoryRedactPii: boolean;
+	/** TCP port for the /context-dashboard web server. 0 = pick a free port (default). */
+	dashboardPort: number;
 	pricingModel: string;
 	pricingInput: number | null;
 	pricingOutput: number | null;
@@ -140,6 +142,7 @@ export function defaultConfig(): Config {
 		indexerWatch: true,
 		indexerRedactSecrets: true,
 		memoryRedactPii: true,
+		dashboardPort: 0,
 		pricingModel: "opus",
 		pricingInput: null,
 		pricingOutput: null,
@@ -176,6 +179,7 @@ const MAPPING: Record<string, keyof Config> = {
 	"indexer.watch": "indexerWatch",
 	"indexer.redact_secrets": "indexerRedactSecrets",
 	"memory.redact_pii": "memoryRedactPii",
+	"dashboard.port": "dashboardPort",
 	"storage.path": "storagePath",
 	"pricing.model": "pricingModel",
 	"pricing.input": "pricingInput",
@@ -221,6 +225,11 @@ function applyDict(config: Config, data: any): void {
 				throw new Error(`config ${dotted} must be a non-negative integer`);
 			}
 			config.indexerMaxAutoFiles = value;
+		} else if (attr === "dashboardPort") {
+			if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 65535) {
+				throw new Error(`config ${dotted} must be an integer between 0 and 65535 (0 = pick a free port)`);
+			}
+			config.dashboardPort = value;
 		} else if (attr === "pricingInput" || attr === "pricingOutput") {
 			if (value !== null && typeof value !== "number") throw new Error(`config ${dotted} must be a number or null`);
 			(config as any)[attr] = value;

package/src/dashboard/api.ts

@@ -0,0 +1,155 @@
+/**
+ * Read-only JSON snapshots for the web dashboard.
+ *
+ * Every function here is a pure reader over the engine's stores: no writes,
+ * no savings accounting, no embedder/model initialization (a dashboard
+ * refresh must never trigger a model download). Dollar estimates use the
+ * static/cached pricing table only — resolvePricing(config, false).
+ */
+import type { ContextEngine } from "../engine.js";
+import { resolvePricing } from "../pricing.js";
+
+export interface ExtDashboardState {
+	/** True while a background (auto/watcher) index run is in flight. */
+	indexing: boolean;
+}
+
+const num = (n: number): number => Math.max(0, Math.floor(n || 0));
+
+/** Cheap overview: index size, config summary and savings aggregates. No
+ * pricing resolution, no model init — polled every few seconds. */
+export function statusPayload(eng: ContextEngine, ext: ExtDashboardState) {
+	const stats = eng.getStats();
+	let fileCounts: Record<string, number> = {};
+	try {
+		fileCounts = eng.backend.fileChunkCounts();
+	} catch {
+		// index stores may not exist yet
+	}
+	const saved = num(stats.rawTokens - stats.servedTokens);
+	const fullSaved = num(stats.fullFileTokens - stats.servedTokens);
+	return {
+		project: eng.projectName,
+		projectDir: eng.projectDir,
+		storageDir: eng.storageBase,
+		sessionId: eng.sessionId,
+		chunks: eng.chunkCount(),
+		files: Object.keys(fileCounts).length,
+		indexing: ext.indexing,
+		config: {
+			embeddingModel: eng.config.embeddingModel,
+			topK: eng.config.retrievalTopK,
+			rerank: eng.config.retrievalRerank,
+			chunking: eng.config.indexerChunking,
+			autoIndex: eng.config.indexerAutoIndex,
+			watch: eng.config.indexerWatch,
+			compression: eng.config.compressionLevel,
+		},
+		stats: {
+			queries: stats.queries,
+			rawTokens: stats.rawTokens,
+			servedTokens: stats.servedTokens,
+			fullFileTokens: stats.fullFileTokens,
+			tokensSaved: saved,
+			fullFileTokensSaved: fullSaved,
+			savingsPct: stats.fullFileTokens > 0 ? Math.floor((fullSaved / stats.fullFileTokens) * 100) : null,
+		},
+	};
+}
+
+/** Bucket ledger + dollar estimates + per-day trend. Never fetches live
+ * pricing: the dashboard must stay offline-safe. */
+export async function savingsPayload(eng: ContextEngine) {
+	const { label, pricing } = await resolvePricing(eng.config, false);
+	const buckets: Record<string, { baseline: number; served: number; calls: number }> = eng.aggregateSavings() ?? {};
+	const toUsd = (tokens: number): number => (tokens / 1e6) * pricing.input;
+	const rows = Object.entries(buckets)
+		.map(([bucket, v]) => ({
+			bucket,
+			calls: v.calls,
+			baseline: v.baseline,
+			served: v.served,
+			saved: num(v.baseline - v.served),
+			savedUsd: toUsd(num(v.baseline - v.served)),
+		}))
+		.sort((a, b) => b.saved - a.saved);
+	let memory = null;
+	try {
+		memory = eng.getMemory();
+	} catch {
+		memory = null;
+	}
+	const byDay = (memory?.savingsByDay(30) ?? []).map((d) => ({
+		day: d.day,
+		saved: num(d.baseline - d.served),
+	}));
+	const stats = eng.getStats();
+	const fullSaved = num(stats.fullFileTokens - stats.servedTokens);
+	return {
+		pricing: { model: label, inputUsdPer1M: pricing.input, outputUsdPer1M: pricing.output },
+		totals: {
+			savedTokens: fullSaved,
+			savedUsd: toUsd(fullSaved),
+			savingsPct: stats.fullFileTokens > 0 ? Math.floor((fullSaved / stats.fullFileTokens) * 100) : null,
+		},
+		buckets: rows,
+		byDay,
+	};
+}
+
+/** Indexed files with chunk counts, largest first. */
+export function filesPayload(eng: ContextEngine, limit = 500) {
+	let counts: Record<string, number> = {};
+	try {
+		counts = eng.backend.fileChunkCounts();
+	} catch {
+		// no index yet
+	}
+	const rows = Object.entries(counts)
+		.map(([filePath, chunks]) => ({ filePath, chunks }))
+		.sort((a, b) => b.chunks - a.chunks || a.filePath.localeCompare(b.filePath));
+	return {
+		total: rows.length,
+		chunks: rows.reduce((acc, r) => acc + r.chunks, 0),
+		files: rows.slice(0, Math.max(1, Math.min(limit, 5000))),
+	};
+}
+
+export function sessionsPayload(eng: ContextEngine, limit = 50) {
+	const memory = eng.getMemory();
+	return {
+		sessions: memory ? memory.listSessions(limit) : [],
+		// JSON snapshots (SessionCapture) survive memory-db failures and carry
+		// decisions/code areas even when SQLite is unavailable.
+		activeSessionId: eng.sessionId,
+	};
+}
+
+export function timelinePayload(eng: ContextEngine, sessionId: string) {
+	const memory = eng.getMemory();
+	if (!memory) return { session: null, turns: [], events: [] };
+	const meta = memory.listSessions(500).find((s) => s.id === sessionId) ?? null;
+	const detail = memory.sessionDetail(sessionId);
+	return { session: meta, turns: detail.turns, events: detail.events };
+}
+
+export function decisionsPayload(eng: ContextEngine, limit = 100) {
+	const memory = eng.getMemory();
+	return {
+		decisions: memory?.listDecisions(limit) ?? [],
+		codeAreas: memory?.listCodeAreas(limit) ?? [],
+		consolidated: eng.sessionCapture.loadConsolidatedDecisions().slice(0, limit),
+	};
+}
+
+/** Everything, for /api/export. */
+export async function exportPayload(eng: ContextEngine, ext: ExtDashboardState) {
+	return {
+		generatedAt: new Date().toISOString(),
+		status: statusPayload(eng, ext),
+		savings: await savingsPayload(eng),
+		files: filesPayload(eng),
+		sessions: sessionsPayload(eng),
+		decisions: decisionsPayload(eng),
+	};
+}