decorated-pi 0.5.5 → 0.6.0

package/.codegraph/daemon.pid

@@ -0,0 +1,6 @@
+{
+  "pid": 3967873,
+  "version": "0.9.9",
+  "socketPath": "/home/liuchang/workspace/pi-extensions/decorated-pi/.codegraph/daemon.sock",
+  "startedAt": 1781237871587
+}

package/AGENTS.md

@@ -0,0 +1,92 @@
+# decorated-pi — pi extension
+
+## Architecture
+
+### Three top-level categories
+
+```
+decorated-pi/
+├── AGENTS.md
+├── package.json
+├── settings.ts              # ~/.pi/agent/decorated-pi.json read/write
+├── tools/                   # LLM-callable tools
+├── hooks/                   # agent-loop event handlers
+├── commands/                # slash commands
+├── providers/               # LLM providers
+└── test/                    # vitest specs
+```
+
+| Category | Role | Knows about |
+|----------|------|-------------|
+| `tools/` | Endpoints the LLM calls | other modules via import only |
+| `hooks/` | Reacts to agent-loop events | primitives, other hooks via skeleton |
+| `commands/` | User-typed `/...` commands | `settings.ts` only |
+
+**Hard rules**:
+- A tool never registers a hook (no `pi.on(...)` in `tools/*.ts`).
+- A hook does not care whether the triggering tool was registered by us or by pi core.
+- A command does not participate in the agent loop. Its only shared state with tools is `settings.ts`.
+- The skeleton (`hooks/skeleton.ts`) is the only place that calls `pi.on(...)` for hooks.
+
+### Skeleton — `hooks/skeleton.ts`
+
+```
+       pi core
+          │
+          │  events
+          ▼
+   ┌──────────────┐
+   │   skeleton   │  ← only place that calls pi.on(...)
+   │              │
+   │  · collect   │
+   │  · order     │
+   │  · dispatch  │
+   │  · owns:     │
+   │    - deps    │
+   │    - prompt  │
+   └──────┬───────┘
+          │
+          ▼
+   registered hooks
+```
+
+**Rules**:
+- Registration order = execution order.
+- Two handler modes: **parallel** (return values ignored) for lifecycle events; **compose** (next handler sees previous return) for transformation chains (`before_agent_start` mutates `systemPrompt`, `tool_call` mutates `input.command`, `tool_result` mutates `content`).
+- The skeleton also owns dependency checking and system-prompt guideline injection — hooks declare them, skeleton enforces them at the right event.
+
+### `dp-settings`
+
+The only shared state is `settings.ts`. Commands write; `index.ts` reads on `/reload` to decide which tools to register. Neither side imports the other.
+
+### Adding a new feature
+
+**New tool**:
+1. `tools/<name>.ts` exporting `register<Name>Tool(pi)`.
+2. In `index.ts`: `if (isModuleEnabled("<name>")) register<Name>Tool(pi);`
+3. *(Optional)* In `commands/dp-settings.ts`: add the module label so users can toggle it via `/dp-settings`. Without this the tool is always on; users would have to edit `settings.json` directly to disable.
+
+If the tool has its own state, protocol client, or dynamic sub-tools, organize it as a directory instead of a single file: `tools/<name>/{client,manager,...}.ts` plus `tools/<name>/index.ts` exporting `register<Name>Tools(pi)`. See `tools/mcp/` and `tools/lsp/` for examples.
+
+**New hook**:
+1. `hooks/<name>.ts` exporting `<name>Module` and optionally `setup<X>(sk)`.
+2. In `hooks/index.ts`: export the setup wrapper.
+3. In `index.ts`: call `setup<X>(sk)` in the right slot (order = execution order).
+4. Inside the setup, call `sk.declareDependency` / `sk.declareGuideline` if needed.
+
+**New command**:
+1. `commands/<name>.ts` exporting `register<Name>Command(pi)`.
+2. In `index.ts`: call `register<Name>Command(pi)`.
+
+## Test
+
+```bash
+npm test
+```
+
+Organization rules:
+
+- Tests mirror the source layout one-to-one: `extensions/<area>/<name>.ts` → `test/<name>.test.ts`.
+- All spec files live flat in `test/` (no nested folders). For a tool that is a directory (e.g. `tools/mcp/`), the spec is `test/mcp.test.ts` covering the whole module.
+- Sub-features of the same module may get their own file: `test/mcp-externalize.test.ts` for a specific concern of MCP, `test/patch.test.ts` for the patch tool.
+- Every new feature or bug fix ships with a test — run `npm test` before considering the change done.

package/README.md

@@ -1,6 +1,6 @@
 # decorated-pi
 
-`decorated-pi` is a practical enhancement pack for [Pi](https://github.com/earendil-works/pi) — smarter tools that are token efficient and cache friendly.
+`decorated-pi` is a practical enhancement pack for [Pi](https://github.com/earendil-works/pi) — token-efficient workflow, cache-friendly design, and smarter tools.
 
 ## Install
 
@@ -12,21 +12,41 @@ pi install /path/to/decorated-pi
 
 ## Features
 
-### 1. Patch Tool
+### 1. Token Efficiency
 
-Replaces Pi's built-in `edit` with a stronger `patch` tool that adds unique safety and usability improvements on top of the native tools.
+Multiple layers of token savings that compound across every session.
+
+**RTK** — integrates [RTK](https://github.com/rtk-ai/rtk) to compress bash output into structured summaries, so the LLM never sees raw noise.
+
+**codegraph** — integrates [codegraph](https://github.com/colbymchenry/codegraph) to offer a code map of your project, so the LLM can navigate symbols and call graphs without chaining `ls` → `grep` → `read`.
+
+**Auxiliary Models** — offloads heavy-but-dumb tasks to cheaper models so your primary model only pays for the hard work:
+
+- **Image read fallback** — detects image type via magic bytes, calls a configured vision-capable model, and injects the analysis text, so your main model never touches image tokens
+- **Compact model** — handles context compaction with a smaller model instead of burning main-model capacity
+
+Configured via `/dp-model`.
+
+**Cache‑friendly design** — stable system prompt prefix:
+
+- tool definitions, guidelines, and skills are sorted alphabetically so the system prompt is identical across sessions
+- volatile elements like `Current date: …` are stripped before prompt assembly
+- MCP tool schemas are persisted to a local cache, so the tool list stays stable regardless of network conditions or server availability
+
+### 2. Smarter Tools
+
+Drop‑in replacements for Pi's built‑in tools, with better UX and fewer wasted turns.
+
+#### Patch Tool
 
 | Capability | Pi native `edit` | `patch` |
 | ------ | :---: | :---: |
-| Syntax‑highlighted overwrite | ✅ streaming | ✅ incremental |
 | **Anchor‑based search** | ❌ extending `oldText` for uniqueness | ✅ `anchor` bounds scope for precise matching |
 | **Fuzzy whitespace match** | ❌ only reports "not found" | ✅ auto‑corrects tab↔space / trailing whitespace mismatches |
 | **Edit fault diagnostics** | ❌ only reports "not found" | ✅ pinpoint faults for LLM comprehension |
 | **Stale‑read protection** | ❌ Blind to external changes | ✅ `read` captures mtime, `patch` rejects stale targets |
 
-### 2. Smarter `@` File Search
-
-Replaces Pi's built-in `@` file completion with smarter matching and noise filtering:
+#### Smarter `@` File Search
 
 | Aspect | Pi native `@` | `decorated-pi` |
 | ------ | :---: | :---: |
@@ -35,48 +55,15 @@ Replaces Pi's built-in `@` file completion with smarter matching and noise filte
 | **Default suggestions** | ❌ all files visible on empty query | ✅ only visible project files |
 | **Match precision** | ❌ case‑insensitive simple scoring | ✅ multi‑level case‑sensitive scoring |
 
-### 3. 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.
-
-Example redaction on a `read` / `bash` output:
-
-```json
-{
-  "aws_access_key_id": "AKI**************PLE",
-  "github_token": "ghp***************def",
-  "database_password": "Sup#######t99",
-  "api_key": "sk_**************f5a",
-  "random_secret": "a1b??????5f5"
-}
-```
-
-> `*` = known pattern, `#` = config key regex, `?` = entropy heuristic.
-
-### 4. Auxiliary Models
-
-Offloads auxiliary ops to cheaper models, reducing cost on every session. 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).
-
-### 5. Progressive Context from `AGENTS.md` / `CLAUDE.md`
-
-Extension capability: context is disclosed progressively as the agent works across different parts of the project.
+#### LSP support
 
-- When reading or editing a file, discovers `AGENTS.md` / `CLAUDE.md` in that file's directory and ancestor directories
-- Newly discovered guidance is injected into tool results, scoped to the current context
-
-### 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.
+Covers what codegraph can't: real-time compiler and lint errors.
 
 - **`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. Built-in MCP Client
+### 3. MCP Ecosystem
 
 Zero-config MCP client with built-in servers:
 
@@ -84,9 +71,9 @@ Zero-config MCP client with built-in servers:
 | --- | --- | --- |
 | Context7 | `context7_*` | `https://mcp.context7.com/mcp` |
 | Exa | `exa_*` | `https://mcp.exa.ai/mcp` |
+| codegraph | `codegraph_*` | bundled binary |
 
-**Custom servers** in `.pi/agent/mcp.json` (project) or `~/.pi/agent/decorated-pi.json` (global). Project overrides global.
-Tool prompts and schemas are cached locally so MCP tools are available immediately on startup, even before servers connect.
+**Custom servers** in `.pi/agent/mcp.json` (project) or `~/.pi/agent/decorated-pi.json` (global). Project overrides global. Tool prompts and schemas are cached locally so MCP tools are available immediately on startup — no manual `/reload` required even on first install.
 
 ```json
 {
@@ -108,34 +95,36 @@ Tool prompts and schemas are cached locally so MCP tools are available immediate
 }
 ```
 
-Use `/mcp` to view connection status and registered tools.
-
-### 8. Extend Providers
+Use `/mcp` to view connection status and toggle servers.
 
-Extend providers are registered via `/login` → "Use a subscription":
+### 4. Secret Redaction
 
-| Provider | Base URL |
-| ---------- | ----------- |
-| Ollama Cloud | `ollama.com/v1` |
-| Baidu Qianfan | `qianfan.baidubce.com/v2/coding` |
-| ARK Coding | `ark.cn-beijing.volces.com/api/coding/v3` |
+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.
 
-### 9. Other
+Example redaction on a `read` / `bash` output:
 
-- **RTK** — integrates [RTK](https://github.com/rtk-ai/rtk) for token-efficient command output.
-- **WakaTime** — tracks coding activity via [WakaTime](https://wakatime.com).
+```json
+{
+  "aws_access_key_id": "AKI**************PLE",
+  "github_token": "ghp***************def",
+  "database_password": "Sup#######t99",
+  "api_key": "sk_**************f5a",
+  "random_secret": "a1b??????5f5"
+}
+```
 
-## Configuration
+> `*` = known pattern, `#` = config key regex, `?` = entropy heuristic.
 
-Runtime settings are stored in:
+### 5. Other
 
-```text
-~/.pi/agent/decorated-pi.json
-```
+- `/usage` — token stats with cache‑hit rate, per‑model breakdown (Session / Today / This Week / This Month / All Time)
+- Progressive context — supports subdirectory `AGENTS.md` / `CLAUDE.md` discovery and injection
+- `/retry` — continue after interruption
+- **WakaTime** — coding activity tracking via [WakaTime](https://wakatime.com)
 
-### Module Loading
+## Configuration
 
-Modules can be toggled on/off by `/dp-settings`. Changes take effect after `/reload`.
+Runtime settings in `~/.pi/agent/decorated-pi.json`. Modules can be toggled via `/dp-settings` (changes take effect after `/reload`).
 
 ```json
 {

package/commands/dp-model.ts

@@ -0,0 +1,23 @@
+/**
+ * /dp-model — pick image / compact model.
+ * UI lives in extensions/ui/model-picker.ts (shared with /mcp status etc).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ModelPickerComponent } from "../ui/model-picker.js";
+
+export function registerDpModelCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("dp-model", {
+    description: "Configure image and compact models",
+    handler: async (_args, ctx) => {
+      if (ctx.hasUI) {
+        await ctx.ui.custom<void>(
+          (tui, theme, _kb, done) =>
+            new ModelPickerComponent(tui, theme, ctx.modelRegistry, () => done(undefined))
+        );
+        return;
+      }
+      ctx.ui.notify("dp-model requires interactive mode.", "warning");
+    },
+  });
+}

package/commands/dp-settings.ts

@@ -0,0 +1,23 @@
+/**
+ * /dp-settings — toggle module on/off.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ModuleSettingsComponent } from "../ui/module-settings.js";
+
+export function registerDpSettingsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("dp-settings", {
+    description: "Toggle decorated-pi modules on/off",
+    handler: async (_args, ctx) => {
+      if (ctx.hasUI) {
+        await ctx.ui.custom<void>(
+          (tui, theme, _kb, done) =>
+            new ModuleSettingsComponent(tui, theme, () => done(undefined))
+        );
+        ctx.ui.notify("Module settings updated. /reload to apply.", "warning");
+        return;
+      }
+      ctx.ui.notify("dp-settings requires interactive mode.", "warning");
+    },
+  });
+}

package/commands/mcp-status.ts

@@ -0,0 +1,62 @@
+/**
+ * /mcp — show MCP servers, toggle, refresh.
+ *
+ * Wires the pure UI component (ui/mcp-status.ts) to the hook layer
+ * (hooks/mcp.ts) by injecting callbacks. The UI itself knows nothing
+ * about hooks/config persistence.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { McpStatusComponent, type McpServerView } from "../ui/mcp-status.js";
+import { getMcpStatus, refreshServerCache, updateConfigEnabled } from "../hooks/mcp.js";
+import { toggleMcpServerEnabled } from "../tools/mcp/config.js";
+
+export function registerMcpStatusCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("mcp", {
+    description: "Show active MCP servers and their tools",
+    handler: async (_args, ctx) => {
+      if (ctx.hasUI) {
+        await ctx.ui.custom<void>(
+          (tui, theme, _kb, done) =>
+            new McpStatusComponent(tui, theme, {
+              read: () => getMcpStatus() as McpServerView[],
+              toggle: async (name, enabled) => {
+                const scope: "global" | "project" = "global";
+                const ok = toggleMcpServerEnabled(name, enabled, scope, ctx.cwd || undefined);
+                if (ok) {
+                  // Await so the connection (if disabling) is fully torn down
+                  // before /reload. Otherwise teardownMcp() may hang on a
+                  // zombie conn and stall session_shutdown.
+                  await updateConfigEnabled(name, enabled);
+                }
+                return ok;
+              },
+              refresh: (name) => refreshServerCache(name, ctx.modelRegistry),
+            }, done)
+        );
+        return;
+      }
+      const servers = getMcpStatus();
+      if (servers.length === 0) {
+        ctx.ui.notify("No MCP servers configured.", "info");
+        return;
+      }
+      const lines: string[] = [`MCP servers (${servers.length}):`, ""];
+      for (const s of servers) {
+        lines.push(`• ${s.name} (${s.source})`);
+        lines.push(`  URL: ${s.url}`);
+        if (s.state === "connecting") lines.push(`  Status: connecting...`);
+        else if (s.state === "failed") lines.push(`  Status: failed — ${s.error ?? "unknown error"}`);
+        else {
+          lines.push(`  Tools: ${s.toolCount}`);
+          for (const tool of s.tools) {
+            const desc = tool.description ? ` — ${tool.description.slice(0, 60)}` : "";
+            lines.push(`    - ${tool.name}${desc}`);
+          }
+        }
+        lines.push("");
+      }
+      pi.sendMessage({ customType: "mcp-status", content: lines.join("\n"), display: true }, { triggerTurn: false });
+    },
+  });
+}

package/commands/retry.ts

@@ -0,0 +1,19 @@
+/**
+ * /retry — continue after interruption.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function registerRetryCommand(pi: ExtensionAPI): void {
+  let retryInProgress = false;
+  pi.registerCommand("retry", {
+    description: "Continue after interruption",
+    handler: async (_args, ctx) => {
+      if (retryInProgress) { ctx.ui.notify("Retry is already in progress", "warning"); return; }
+      if (!ctx.isIdle()) ctx.abort();
+      retryInProgress = true;
+      pi.sendMessage({ customType: "retry-trigger", content: "Continue.", display: false }, { triggerTurn: true });
+    },
+  });
+  pi.on("agent_start", () => { retryInProgress = false; });
+}