decorated-pi 0.5.4 → 0.6.0

package/{extensions → tools}/lsp/client.ts

@@ -8,7 +8,6 @@ import {
 } from "./protocol.js";
 import type {
   LspDiagnostic,
-  LspDocumentSymbol,
   LspHover,
   LspLocation,
   LspPosition,
@@ -199,14 +198,6 @@ export class LspClient {
     );
   }
 
-  async documentSymbols(uri: string, timeoutMs?: number): Promise<LspDocumentSymbol[]> {
-    return normalizeDocumentSymbols(
-      await this.#request("textDocument/documentSymbol", {
-        textDocument: { uri },
-      }, timeoutMs),
-    );
-  }
-
   async rename(
     uri: string,
     position: LspPosition,
@@ -260,22 +251,6 @@ function normalizeLocations(result: unknown): LspLocation[] {
   });
 }
 
-function normalizeDocumentSymbols(result: unknown): LspDocumentSymbol[] {
-  if (!result || !Array.isArray(result) || result.length === 0) return [];
-  const first = result[0];
-  if ("range" in first && "selectionRange" in first) {
-    return result as LspDocumentSymbol[];
-  }
-  return result.map((entry: any) => ({
-    name: entry.name,
-    kind: entry.kind,
-    range: entry.location.range,
-    selectionRange: entry.location.range,
-    containerName: entry.containerName,
-    uri: entry.location.uri,
-  }));
-}
-
 function uriToPath(uri: string): string {
   try {
     return uri.startsWith("file:") ? new URL(uri).pathname : uri;

package/{extensions → tools}/lsp/format.ts

@@ -5,10 +5,10 @@
  * Runtime tools.ts has its own inline copies.
  */
 import { fileURLToPath } from "node:url";
-import type { LspDiagnostic, LspHover, LspLocation, LspDocumentSymbol } from "./types.js";
+import type { LspDiagnostic, LspHover, LspLocation } from "./types.js";
 import { LspClientStartError } from "./client.js";
 
-export type { LspDiagnostic, LspHover, LspLocation, LspDocumentSymbol } from "./types.js";
+export type { LspDiagnostic, LspHover, LspLocation } from "./types.js";
 export { LspClientStartError } from "./client.js";
 
 // ─── Error formatting ────────────────────────────────────────────────────
@@ -112,103 +112,6 @@ function fileUrlToPath(uri: string): string {
   try { return uri.startsWith("file:") ? fileURLToPath(uri) : uri; } catch { return uri; }
 }
 
-// ─── Symbols ──────────────────────────────────────────────────────────────
-
-const SYMBOL_KIND_LABELS: Record<number, string> = {
-  2: "module", 3: "namespace", 5: "class", 6: "method", 7: "property",
-  8: "field", 9: "constructor", 11: "interface", 12: "function",
-  13: "variable", 14: "constant", 23: "struct", 24: "event",
-};
-
-export function symbol_kind_label(kind: number): string {
-  return SYMBOL_KIND_LABELS[kind] ?? "symbol";
-}
-
-export function format_document_symbols(file: string, symbols: LspDocumentSymbol[]): string {
-  if (symbols.length === 0) return `${file}: no symbols`;
-  const lines = [`${file}: ${symbols.length} top-level symbol(s)`];
-  appendSymbols(lines, symbols, 1);
-  return lines.join("\n");
-}
-
-function appendSymbols(lines: string[], symbols: LspDocumentSymbol[], depth: number) {
-  for (const s of symbols) {
-    const indent = "  ".repeat(depth);
-    const detail = s.detail ? ` — ${s.detail}` : "";
-    const range = `${s.range.start.line + 1}:${s.range.start.character + 1}`;
-    lines.push(`${indent}${symbol_kind_label(s.kind)} ${s.name}${detail} @ ${range}`);
-    if (s.children?.length) appendSymbols(lines, s.children, depth + 1);
-  }
-}
-
-interface SymbolMatchOptions {
-  max_results: number;
-  top_level_only: boolean;
-  exact_match: boolean;
-  kinds: Set<string>;
-  language: string;
-}
-
-export interface SymbolMatch { symbol: LspDocumentSymbol; depth: number }
-
-export function find_symbol_matches(
-  symbols: LspDocumentSymbol[],
-  query: string,
-  options: SymbolMatchOptions,
-): SymbolMatch[] {
-  const normalized = query.trim().toLowerCase();
-  if (!normalized) return [];
-  const matches: SymbolMatch[] = [];
-  const expandName = (name: string): string[] => {
-    const trimmed = name.trim().toLowerCase();
-    if (!trimmed) return [];
-    const expanded = new Set([trimmed]);
-    if (options.language === "cpp" && trimmed.includes("::")) {
-      const parts = trimmed.split("::").map(p => p.trim()).filter(Boolean);
-      if (parts.length > 0) expanded.add(parts[parts.length - 1]!);
-    }
-    return [...expanded];
-  };
-
-  const matchesQuery = (s: LspDocumentSymbol): boolean => {
-    const name = s.name.trim().toLowerCase();
-    const detail = (s.detail ?? "").trim().toLowerCase();
-    if (options.exact_match) {
-      const exactValues = [...expandName(s.name), ...(detail ? [detail] : [])];
-      return exactValues.some(v => v === normalized);
-    }
-    return name.includes(normalized) || detail.includes(normalized);
-  };
-  const matchesKind = (s: LspDocumentSymbol): boolean =>
-    options.kinds.size === 0 || options.kinds.has(symbol_kind_label(s.kind));
-  const visit = (entries: LspDocumentSymbol[], depth: number) => {
-    for (const symbol of entries) {
-      if (matchesKind(symbol) && matchesQuery(symbol)) {
-        matches.push({ symbol, depth });
-        if (matches.length >= options.max_results) return;
-      }
-      if (!options.top_level_only && symbol.children?.length) {
-        visit(symbol.children, depth + 1);
-        if (matches.length >= options.max_results) return;
-      }
-    }
-  };
-  visit(symbols, 1);
-  return matches;
-}
-
-export function format_symbol_matches(file: string, query: string, matches: SymbolMatch[]): string {
-  if (matches.length === 0) return `${file}: no symbols matching "${query}"`;
-  const lines = [`${file}: ${matches.length} symbol match(es) for "${query}"`];
-  for (const { symbol, depth } of matches) {
-    const indent = "  ".repeat(depth);
-    const detail = symbol.detail ? ` — ${symbol.detail}` : "";
-    const range = `${symbol.range.start.line + 1}:${symbol.range.start.character + 1}`;
-    lines.push(`${indent}${symbol_kind_label(symbol.kind)} ${symbol.name}${detail} @ ${range}`);
-  }
-  return lines.join("\n");
-}
-
 // ─── Collapse (for tools test) ────────────────────────────────────────────
 
 export function collapse_lsp_text(text: string, maxLines = 20) {

package/{extensions → tools}/lsp/index.ts

@@ -1,7 +1,7 @@
 /**
  * LSP Extension — language server integration for Pi.
  *
- * Provides: lsp_diagnostics, lsp_document_symbols.
+ * Provides: lsp_diagnostics.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { LspServerManager } from "./manager.js";

package/{extensions → tools}/lsp/servers.ts

@@ -4,7 +4,7 @@
 import { existsSync, readdirSync, type Dirent } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
-import type { DependencyStatus } from "../rtk";
+import type { DependencyStatus } from "../../hooks/skeleton.js";
 
 // ─── File extension → language mapping ────────────────────────────────────
 

package/{extensions → tools}/lsp/tools.ts

@@ -4,7 +4,7 @@
 import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { LspServerManager, LspToolError, formatToolError } from "./manager.js";
+import { LspServerManager, formatToolError } from "./manager.js";
 
 // ─── TUI rendering ─────────────────────────────────────────────────────────
 
@@ -53,24 +53,6 @@ function err(details: any): ToolResult {
   return ok(formatToolError(details), { ok: false, error: details });
 }
 
-async function withFile(
-  manager: LspServerManager,
-  file: string,
-  fn: (s: { abs: string; uri: string; state: any }) => Promise<string>,
-  options: { timeoutMs?: number } = {},
-): Promise<ToolResult> {
-  const resolved = await manager.resolveFileState(file, { timeoutMs: options.timeoutMs });
-  if (!resolved.ok) return err(resolved.error);
-  const { result } = resolved;
-  try {
-    const text = await fn(result);
-    return ok(text, { ok: true, language: result.state.language, workspace_root: result.state.workspaceRoot });
-  } catch (error) {
-    if (error instanceof LspToolError) return err(error.details);
-    return err({ kind: "tool_execution_failed", file: result.abs, language: result.state.language, workspace_root: result.state.workspaceRoot, command: result.state.command, install_hint: result.state.installHint, message: error instanceof Error ? error.message : String(error) });
-  }
-}
-
 function withTimeout(promise: Promise<ToolResult>, ms: number, label: string): Promise<ToolResult> {
   return Promise.race([
     promise,
@@ -84,25 +66,6 @@ function severityLabel(s: number): string {
   return s === 1 ? "error" : s === 2 ? "warning" : s === 3 ? "info" : "hint";
 }
 
-function symbolKindLabel(kind: number): string {
-  const labels: Record<number, string> = { 2:"module",3:"namespace",5:"class",6:"method",7:"property",8:"field",9:"constructor",11:"interface",12:"function",13:"variable",14:"constant",23:"struct",24:"event" };
-  return labels[kind] ?? "symbol";
-}
-
-function formatDocumentSymbols(file: string, symbols: any[]): string {
-  if (symbols.length === 0) return `${file}: no symbols`;
-  const lines = [`${file}: ${symbols.length} top-level symbol(s)`];
-  const append = (syms: any[], depth: number) => {
-    for (const s of syms) {
-      const detail = s.detail ? ` — ${s.detail}` : "";
-      lines.push(`${"  ".repeat(depth)}${symbolKindLabel(s.kind)} ${s.name}${detail} @ ${s.range.start.line + 1}:${s.range.start.character + 1}`);
-      if (s.children?.length) append(s.children, depth + 1);
-    }
-  };
-  append(symbols, 1);
-  return lines.join("\n");
-}
-
 // ─── Register tools ───────────────────────────────────────────────────────
 
 export function registerLspTools(pi: ExtensionAPI, manager: LspServerManager) {
@@ -156,34 +119,6 @@ export function registerLspTools(pi: ExtensionAPI, manager: LspServerManager) {
       })(), totalTimeout, "LSP diagnostics");
     },
   });
-
-  // ── lsp_document_symbols ───────────────────────────────────────────────
-  pi.registerTool({
-    name: "lsp_document_symbols",
-    label: "LSP: document symbols",
-    description: "List symbols in a file (functions, classes, variables) using the language server.",
-    promptSnippet: "List functions, classes, and variables in a file",
-    promptGuidelines: [
-      "Prefer lsp_document_symbols to find functions, classes, or variables in code instead of grep.",
-      "Supported languages: typescript, c, cpp, python, rust, go, ruby, java, lua, svelte.",
-    ],
-    renderResult: renderLspResult,
-    parameters: Type.Object({
-      path: Type.String({ description: "Path to the file (relative or absolute)." }),
-      timeout_ms: Type.Optional(Type.Number({ description: "Overall max ms including server startup. Default 10000." })),
-    }),
-    execute: async (_id, params, _signal, _update, _ctx): Promise<ToolResult> => {
-      const timeoutMs = params.timeout_ms ?? 10_000;
-      return withTimeout(
-        withFile(manager, params.path, async (result) => {
-          const symbols = await result.state.client.documentSymbols(result.uri, timeoutMs);
-          return formatDocumentSymbols(result.abs, symbols);
-        }, { timeoutMs }),
-        timeoutMs,
-        "LSP document symbols",
-      );
-    },
-  });
 }
 
 // ─── Formatting ────────────────────────────────────────────────────────────

package/{extensions → tools}/lsp/types.ts

@@ -29,14 +29,3 @@ export interface LspHover {
   contents: unknown;
   range?: LspRange;
 }
-
-export interface LspDocumentSymbol {
-  name: string;
-  kind: number;
-  range: LspRange;
-  selectionRange?: LspRange;
-  containerName?: string;
-  detail?: string;
-  children?: LspDocumentSymbol[];
-  uri?: string;
-}

package/tools/mcp/builtin/codegraph.ts

@@ -0,0 +1,45 @@
+/**
+ * codegraph builtin MCP server — config + system-prompt guidance.
+ *
+ * Injected by `index.ts` → `buildGuidelines()` when the codegraph
+ * module is enabled (see `isModuleEnabled("codegraph")` in settings).
+ */
+import type { McpServerConfig } from "../config.js";
+import { isCodegraphModuleEnabled } from "../../../settings.js";
+
+export const CODEGRAPH_BUILTIN: Omit<McpServerConfig, "source"> = {
+    name: "codegraph",
+    command: "codegraph",
+    args: ["serve", "--mcp"],
+    enabled: false, // overridden by isCodegraphModuleEnabled() at resolve time
+    description:
+        "Local code knowledge graph (colbymchenry/codegraph). Enable via /dp-settings.",
+};
+
+/** Predicate for `resolveMcpConfigs` to gate the codegraph server. */
+export function codegraphEnabled(): boolean {
+    return isCodegraphModuleEnabled();
+}
+
+export const CODEGRAPH_GUIDANCE = [
+    "### CodeGraph, code source map",
+    "- This project's `codegraph_*` MCP tools are enabled. The graph is a pre-built index; grep/glob/Read of source code is repeating work the index already did.",
+    "",
+    "#### When to reach for it",
+    '- Starting any task that touches code → `codegraph_explore("how does X work")` or `codegraph_files`',
+    "- Looking for where a symbol is defined → `codegraph_search <name>`",
+    "- Reading a function's body → `codegraph_node <name>` (or `codegraph_explore`)",
+    "- Tracing call flow → `codegraph_callers` / `codegraph_callees`",
+    "- Assessing refactor risk → `codegraph_impact <name>`",
+    "",
+    "#### Do NOT do this",
+    "- `ls`, `find`, `grep -rn`, `rg` to discover symbols → use `codegraph_search`",
+    "- `read` of an entire file to find a function → use `codegraph_explore` first",
+    '- Reading 3+ files to understand a module → use `codegraph_explore("how does X work")`',
+    "- `bash` with `cat`, `head`, `sed` to view source → use `codegraph_node` or `read` (single file only)",
+    "",
+    "#### If it errors",
+    '- "Project not initialized" → ask the user to run `codegraph init -i` in their terminal',
+    "- Empty results → fall back to grep/Read (the index is best-effort, not authoritative)",
+    "- Tool timeout → `codegraph_status` to check; if indexer is dead, fall back",
+].join("\n");

package/tools/mcp/builtin/context7.ts

@@ -0,0 +1,10 @@
+/**
+ * context7 builtin MCP server definition.
+ */
+import type { McpServerConfig } from "../config.js";
+
+export const CONTEXT7_BUILTIN: Omit<McpServerConfig, "source"> = {
+  name: "context7",
+  url: "https://mcp.context7.com/mcp",
+  enabled: true,
+};

package/tools/mcp/builtin/exa.ts

@@ -0,0 +1,10 @@
+/**
+ * exa builtin MCP server definition.
+ */
+import type { McpServerConfig } from "../config.js";
+
+export const EXA_BUILTIN: Omit<McpServerConfig, "source"> = {
+  name: "exa",
+  url: "https://mcp.exa.ai/mcp",
+  enabled: true,
+};

package/tools/mcp/builtin/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Builtin MCP servers — aggregate. Each server has its own file; this
+ * module re-exports them and the all-server list.
+ */
+import type { McpServerConfig } from "../config.js";
+import { CONTEXT7_BUILTIN } from "./context7.js";
+import { EXA_BUILTIN } from "./exa.js";
+import { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE } from "./codegraph.js";
+
+export { CONTEXT7_BUILTIN } from "./context7.js";
+export { EXA_BUILTIN } from "./exa.js";
+export { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE, codegraphEnabled } from "./codegraph.js";
+
+/** All builtin servers — flat list for `resolveMcpConfigs` to merge. */
+export const BUILTIN_MCP_SERVERS: Omit<McpServerConfig, "source">[] = [
+  CONTEXT7_BUILTIN,
+  EXA_BUILTIN,
+  CODEGRAPH_BUILTIN,
+];

package/tools/mcp/cache.ts

@@ -0,0 +1,124 @@
+/**
+ * MCP server metadata cache — persisted tool descriptions and schemas.
+ * Stored at `~/.pi/agent/mcp-cache.json` (global) and `<cwd>/.pi/agent/mcp-cache.json` (project).
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { McpServerConfig } from "./config.js";
+
+export interface McpToolCache {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpServerCache {
+  description?: string;
+  tools: McpToolCache[];
+  cachedAt: number;
+}
+
+export interface McpCache {
+  servers: Record<string, McpServerCache>;
+}
+
+function globalCachePath(): string {
+  return path.join(os.homedir(), ".pi/agent/mcp-cache.json");
+}
+
+function projectCachePath(cwd: string): string {
+  return path.join(cwd, ".pi/agent/mcp-cache.json");
+}
+
+function scopedCachePath(scope: "global" | "project", cwd?: string): string {
+  return scope === "project" && cwd ? projectCachePath(cwd) : globalCachePath();
+}
+
+function readCacheFile(p: string): McpCache | null {
+  try {
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, "utf-8")) as McpCache;
+  } catch {
+    return null;
+  }
+}
+
+function writeCacheFile(p: string, cache: McpCache): void {
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(cache, null, 2), "utf-8");
+  fs.renameSync(tmp, p);
+}
+
+/** Load merged cache: global + project. */
+export function loadMcpCache(cwd?: string): McpCache | null {
+  const merged: McpCache = { servers: {} };
+
+  const globalCache = readCacheFile(globalCachePath());
+  if (globalCache) {
+    merged.servers = { ...merged.servers, ...globalCache.servers };
+  }
+
+  if (cwd) {
+    const projectCache = readCacheFile(projectCachePath(cwd));
+    if (projectCache) {
+      merged.servers = { ...merged.servers, ...projectCache.servers };
+    }
+  }
+
+  return merged;
+}
+
+export function loadScopedMcpCache(scope: "global" | "project", cwd?: string): McpCache | null {
+  return readCacheFile(scopedCachePath(scope, cwd));
+}
+
+/** Save cache to global or project scope. */
+export function saveMcpCache(cache: McpCache, scope: "global" | "project", cwd?: string): void {
+  writeCacheFile(scopedCachePath(scope, cwd), cache);
+}
+
+/** Update a single server's entry in the appropriate cache. */
+export function updateServerCache(
+  serverName: string,
+  entry: McpServerCache,
+  scope: "global" | "project",
+  cwd?: string,
+): void {
+  const p = scopedCachePath(scope, cwd);
+  const existing = readCacheFile(p) || { servers: {} };
+  existing.servers[serverName] = entry;
+  writeCacheFile(p, existing);
+}
+
+function cleanupOneCache(p: string, names: Set<string>): void {
+  const cache = readCacheFile(p);
+  if (!cache) return;
+  let changed = false;
+  for (const name of Object.keys(cache.servers)) {
+    if (!names.has(name)) {
+      delete cache.servers[name];
+      changed = true;
+    }
+  }
+  if (changed) writeCacheFile(p, cache);
+}
+
+export function cleanupStaleCache(configs: McpServerConfig[], cwd?: string): void {
+  const names = new Set(configs.map(c => c.name));
+  cleanupOneCache(globalCachePath(), names);
+  if (cwd) {
+    const projectCache = projectCachePath(cwd);
+    const projectMcpJson = path.join(cwd, ".pi/agent/mcp.json");
+    // If project mcp.json doesn't exist, remove project cache entirely
+    if (!fs.existsSync(projectMcpJson)) {
+      if (fs.existsSync(projectCache)) {
+        fs.unlinkSync(projectCache);
+      }
+    } else {
+      cleanupOneCache(projectCache, names);
+    }
+  }
+}

package/{extensions → tools}/mcp/client.ts

@@ -2,8 +2,8 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import type { McpServerConfig } from "./builtin.js";
-import { isSseUrl } from "./builtin.js";
+import type { McpServerConfig } from "./config.js";
+import { isSseUrl } from "./config.js";
 
 export interface McpToolSpec {
   name: string;