decorated-pi 0.2.2 → 0.4.0

package/README.md

@@ -1,65 +1,64 @@
 # decorated-pi
 
-`decorated-pi` is a Pi extension that adds safety gates, LSP tools, image/compaction model helpers, smarter `@` file search, dynamic subdirectory `AGENTS.md` loading, and a few workflow quality-of-life improvements.
+`decorated-pi` is a practical enhancement pack for [Pi](https://github.com/earendil-works/pi).
+
+## Install
+
+```bash
+pi install npm:decorated-pi
+pi install git:github.com/lcwecker/decorated-pi
+pi install /path/to/decorated-pi
+```
 
 ## Features
 
-### 1. Safety Layer
-
-- **Dangerous bash guard**
-  - asks for confirmation on destructive commands such as:
-    - `rm`
-    - `sudo`
-    - `svn commit/revert`
-    - `git reset/restore/clean/push/revert`
-    - `npm publish`
-    - `>` / `1>` / `2>` / `&>` / `tee` overwrite existing files
-  - Hints the agent to use `edit` instead of `write` on non-empty files
-- **Protected paths**
-  - Blocks read/write access (via `write`/`edit`/`read` tools or `cat`/`head`/`tail`/`grep`/`rg` etc. bash commands) to sensitive locations such as `.env`, `.git/`, `.ssh/`, `*.pem`, `*.key`, etc.
-- **Secret redaction**
-  - Dual-layer detection: 40+ known-format patterns (AWS, GitHub, OpenAI, etc.) + Adjusted Shannon Entropy analysis for unknown formats. Based on [opencode-secrets-protect](https://github.com/jscheel/opencode-secrets-protect) (MIT)
-
-### 2. Smart `@` File Search
-
-Replaces Pi's default file search with a faster project-aware search strategy:
-
-- Uses `git ls-files` in git repos
-- Falls back to `fd` outside git repos
-- Caches results for 10 seconds
-- Scores primarily on **filename match quality**, not full-path fuzziness
-- Penalizes hidden/cache/build directories
-- Hides hidden paths from empty-query results
-
-### 3. LSP Tool Suite
-
-Based on [@spences10/pi-lsp](https://github.com/spences10/my-pi/tree/main/packages/pi-lsp) by Scott Spence (MIT License), with additions:
-
-- C/C++ (clangd) and Lua support
-- `lsp_find_symbol`, `lsp_rename`, multi-file support merged into `lsp_diagnostics`
-- Force-sync on `didChange` (no stale diagnostics)
-
-Registered tools:
-
-- `lsp_diagnostics`
-- `lsp_find_symbol`
-- `lsp_hover`
-- `lsp_definition`
-- `lsp_references`
-- `lsp_document_symbols`
-- `lsp_rename`
-
-Supported languages:
-
-- c/cpp
-- go
-- java
-- lua
-- python
-- ruby
-- rust
-- svelte
-- typescript
+### 1. Patch Tool
+
+Replaces Pi's built-in `edit` / `write` with a stronger `patch` tool:
+
+- **anchor mechanism** — narrows the search range by specifying a unique string that appears before `old_str`, preventing mismatches in files with repeated patterns
+- **mtime tracking** — records file modification time on `read`, rejects `patch` if the file changed since last read, preventing blind or stale edits
+- **explicit overwrite** — offer atomic `overwrite: true` mode for overwrite files or full-file creation to prevent unintened overwrite
+
+### 2. Secret redaction
+
+Three-layer detection: high-confidence known-format patterns (AWS, GitHub, OpenAI, etc.), config-key regex matching, and adjusted Shannon entropy heuristics for unknown secret-like values.
+
+### 3. Built-in MCP Client
+
+Zero-config MCP client with two built-in servers:
+
+| Server | Tool Prefix | Source |
+| --- | --- | --- |
+| Context7 | `context7_*` | `https://mcp.context7.com/mcp` |
+| Exa | `exa_*` | `https://mcp.exa.ai/mcp` |
+
+**Project-level config** — add custom MCP servers by placing an `mcp.json` or `.mcp.json` (also `.pi/mcp.json`, `.agents/mcp.json`, `.claude/mcp.json` and their `.`-prefixed variants) anywhere in your project tree. Servers found closer to `cwd` take precedence over ancestor directories.
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "url": "https://my-mcp.example.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+**Global config** — persist custom servers in `~/.pi/agent/decorated-pi.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": { "url": "https://my-mcp.example.com/mcp" }
+  }
+}
+```
+
+**Priority**: project > global > builtin. A server with the same name from a higher-priority source overrides lower ones.
+
+Use `/mcp` to view connection status and registered tools.
 
 ### 4. Auxiliary Models (Image + Compact)
 
@@ -68,15 +67,32 @@ Uses cheaper models for auxiliary tasks, configured via `/dp-model`:
 - **Image read fallback** — when the model reads an image file, detects type via magic bytes, calls a configured vision-capable model, and replaces the read result with image analysis text (jpeg, png, gif, webp)
 - **Compact model** — uses a configured model for context compaction (instead of the main model), auto-resumes after compaction.
 
-### 5. Dynamic Subdirectory `AGENTS.md` / `CLAUDE.md`
+### 5. Smart `@` File Search
+
+Replaces Pi's default file search with a faster, project-aware search strategy:
+
+- Uses project-aware file discovery
+- Prioritizes filename-based matches for more intuitive results
+- Reduces clutter from hidden, cache, and build directories
+- Keeps default suggestions focused on visible project files
+
+### 6. LSP Tool Suite
+
+A cleaned-up, minimal LSP toolset. The extension keeps only the two LSP tools that cover the most practical coding workflows: checking diagnostics after edits and inspecting file structure before focused changes.
+
+- **`lsp_diagnostics`** — file diagnostics with severity filtering
+- **`lsp_document_symbols`** — file symbol outline
+
+Supported languages: c/cpp, go, java, lua, json, python, ruby, rust, svelte, typescript
+
+### 7. Dynamic Subdirectory `AGENTS.md` / `CLAUDE.md`
 
 When the agent reads or edits a file:
 
 - discovers `AGENTS.md` / `CLAUDE.md` in the file's directory and ancestor directories
 - injects newly discovered guidance into tool results
-- persists discovered files into the session so they are restored on resume
 
-### 6. Extend Providers
+### 8. Extend Providers
 
 Extend providers are registered via `/login` → "Use a subscription":
 
@@ -86,16 +102,6 @@ Extend providers are registered via `/login` → "Use a subscription":
 | Baidu Qianfan | `qianfan.baidubce.com/v2/coding` |
 | ARK Coding | `ark.cn-beijing.volces.com/api/coding/v3` |
 
-## Install
-
-```bash
-pi install /path/to/decorated-pi #local
-pi install npm:decorated-pi #npm
-pi install git:github.com/lcwecker/decorated-pi #github
-```
-
-Then reload Pi
-
 ## Configuration
 
 Runtime settings are stored in:
@@ -110,24 +116,26 @@ Modules can be toggled on/off. Changes take effect after `/reload`.
 
 | Module | Default | Effect when disabled |
 | -------- | --------- | --------------------- |
-| `safety` | `true` | No command guard, no protected path check, no secret redaction |
+| `patch` | `true` | Reverts to Pi's built-in `edit` / `write` tools |
+| `safety` | `true` | No secret redaction on `read` / `bash` output |
 | `lsp` | `true` | All `lsp_*` tools unregistered — no diagnostics, hover, etc. |
 | `smart-at` | `true` | Fallback to Pi's built-in `@` file completion |
+| `mcp` | `true` | All `{server}_*` MCP tools unregistered |
 
 Use `/dp-settings` to toggle, or edit the config file directly:
 
 ```json
 {
   "modules": {
+    "patch": true,
     "safety": true,
     "lsp": false,
-    "smart-at": true
+    "smart-at": true,
+    "mcp": true
   }
 }
 ```
 
-Omitted keys default to `true` (enabled).
-
 ## License
 
 MIT

package/extensions/file-times.ts

@@ -0,0 +1,124 @@
+/**
+ * File mtime tracking for stale-read protection.
+ *
+ * - `read` tool records mtime when the LLM reads a file
+ * - `patch` tool checks mtime before editing — rejects if file changed since last read
+ * - `patch` tool updates mtime after a successful write
+ * - Markers are persisted to session custom entries and restored from the
+ *   current branch after the last compaction boundary.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const FILE_TIMES_CUSTOM_TYPE = "decorated-pi.file-times";
+
+export interface FileTimeMarkerData {
+  path: string;
+  mtimeMs: number;
+}
+
+interface SessionLikeEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/** Last-known mtime for each absolute file path (ms since epoch). */
+const readMarkers = new Map<string, number>();
+
+/** Get current file mtime in ms. Throws if file doesn't exist. */
+function getFileMtime(absPath: string): number {
+  const stat = fs.statSync(absPath);
+  return stat.mtimeMs;
+}
+
+/** Record that the LLM has seen the current version of a file.
+ *  Called after `read` tool completes and after `patch` writes. */
+export function recordReadTime(absPath: string): void {
+  if (!fs.existsSync(absPath)) return;
+  readMarkers.set(absPath, getFileMtime(absPath));
+}
+
+/** Check if file has been modified since last read.
+ *  Returns an error message if stale, or undefined if ok to edit. */
+export function checkStaleFile(absPath: string, displayPath: string): string | undefined {
+  // If file doesn't exist on disk, always allow — creating a new file
+  // doesn't require reading it first, and recreating a deleted file is safe.
+  if (!fs.existsSync(absPath)) {
+    return undefined;
+  }
+
+  const lastRead = readMarkers.get(absPath);
+  if (lastRead === undefined) {
+    // File exists but never read — must read first to avoid blind edits
+    return (
+      `File not read yet: ${displayPath}. ` +
+      `Please read the file with the read tool before editing.`
+    );
+  }
+
+  const currentMtime = getFileMtime(absPath);
+  if (currentMtime > lastRead) {
+    return (
+      `File modified since last read: ${displayPath}. ` +
+      `Please re-read the file with the read tool before editing.`
+    );
+  }
+
+  return undefined;
+}
+
+function toStoredPath(cwd: string, absPath: string): string {
+  const normalizedCwd = path.normalize(cwd);
+  const normalizedAbs = path.normalize(absPath);
+  const rel = path.relative(normalizedCwd, normalizedAbs);
+  if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) return rel;
+  return normalizedAbs;
+}
+
+function lastCompactionIndex(entries: SessionLikeEntry[]): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]?.type === "compaction") return i;
+  }
+  return -1;
+}
+
+function isFileTimeMarkerData(value: unknown): value is FileTimeMarkerData {
+  return !!value
+    && typeof value === "object"
+    && typeof (value as any).path === "string"
+    && typeof (value as any).mtimeMs === "number";
+}
+
+/** Build a session-persisted marker payload for the current file version. */
+export function createFileTimeMarkerData(cwd: string, absPath: string): FileTimeMarkerData | undefined {
+  if (!fs.existsSync(absPath)) return undefined;
+  return {
+    path: toStoredPath(cwd, absPath),
+    mtimeMs: getFileMtime(absPath),
+  };
+}
+
+/** Restore markers from the current branch, ignoring anything before the last compaction. */
+export function restoreReadMarkersFromBranch(entries: SessionLikeEntry[], cwd: string): void {
+  clearReadMarkers();
+  const start = lastCompactionIndex(entries) + 1;
+  for (const entry of entries.slice(start)) {
+    if (entry.type !== "custom" || entry.customType !== FILE_TIMES_CUSTOM_TYPE) continue;
+    if (!isFileTimeMarkerData(entry.data)) continue;
+    const absPath = resolveAbsolutePath(cwd, entry.data.path);
+    readMarkers.set(absPath, entry.data.mtimeMs);
+  }
+}
+
+/** Clear all tracked file times (e.g., on session start or compaction). */
+export function clearReadMarkers(): void {
+  readMarkers.clear();
+}
+
+/** Resolve a relative path to absolute (for consistent map keys). */
+export function resolveAbsolutePath(cwd: string, filePath: string): string {
+  if (path.isAbsolute(filePath)) return path.normalize(filePath);
+  return path.normalize(path.resolve(cwd, filePath));
+}

package/extensions/guidance.ts

@@ -9,9 +9,11 @@ export function setupGuidance(pi: ExtensionAPI) {
     const guidance = [
       DECORATED_PI_GUIDANCE_MARKER,
       "",
-      "Before taking any action on a user's prompt, briefly restate your understanding of what the user wants. If ambiguous, ask clarifying questions. Only proceed after intent is clear.",
-      "",
-      "For medium-to-large tasks (more than 3 steps or touching multiple files/systems), break the task into discrete steps. For small tasks (1-2 steps), do it directly.",
+      "- Before acting on a user's prompt, ensure you fully understand their needs. If the intent is ambiguous, ask clarifying questions. Proceed only when the intent is clear.",
+      "- Look before you leap! Ensure you have conducted thorough research before taking any action.",
+      "- Exercise caution when performing any **write** operations, especially when you are in a research or exploration phase.",
+      "- You don't need to read **AGENTS.md** or **CLAUDE.md** files unless you're explicitly asked to, these files will loaded automatically if neccessary.",
+      "- CAUTION: Do not perform write operations in the following directories unless explicitly instructed: `node_modules`, `venv`, `env`, `__pycache__`, `.git` or any other hidden directories.",
     ].join("\n");
 
     return {

package/extensions/index.ts

@@ -4,27 +4,31 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { setupSafety } from "./safety/index.js";
-import { setupExtendModel } from "./extend-model";
+import { setupModelIntegration } from "./model-integration";
 import { setupSlash } from "./slash";
 import { setupSubdirAgents } from "./subdir-agents";
 import { setupSessionTitle } from "./session-title";
+import { setupIO } from "./io";
 import { setupGuidance } from "./guidance";
 import { setupLsp } from "./lsp/index";
 import { setupProviders } from "./providers/index";
 import { setupSmartAt } from "./smart-at";
+import { setupMcp } from "./mcp/index.js";
 import { isModuleEnabled } from "./settings";
 
 export default function (pi: ExtensionAPI) {
   // Always loaded — core commands and providers
   setupSlash(pi);
   setupProviders(pi);
-  setupExtendModel(pi);
+  setupModelIntegration(pi);
   setupSubdirAgents(pi);
   setupSessionTitle(pi);
   setupGuidance(pi);
 
   // Configurable modules
+  if (isModuleEnabled("patch"))     setupIO(pi);
   if (isModuleEnabled("safety"))    setupSafety(pi);
   if (isModuleEnabled("lsp"))       setupLsp(pi);
   if (isModuleEnabled("smart-at"))  setupSmartAt(pi);
+  if (isModuleEnabled("mcp"))       setupMcp(pi);
 }