decorated-pi 0.7.1 → 0.7.2

package/README.md

@@ -14,25 +14,30 @@ pi install /path/to/decorated-pi
 
 ### 1. Token Efficiency
 
-Multiple layers of token savings that compound across every session. **All integrated CLI tools only require installing their respective CLIs — zero config**.
+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.
+**RTK** — integrates [RTK](https://github.com/rtk-ai/rtk) to compress bash output into structured summaries, so the LLM never sees raw noise. **Just install the CLI, zero config**.
 
-**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`.
+**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`. **You should manage the code source index yourself, see[codegraph doc](https://github.com/colbymchenry/codegraph/blob/main/README.md)**.
 
 **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
+- **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`.
+> Configured via `/dp-model`.
 
-**Cache‑friendly design** — stable system prompt prefix:
+**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
 
+**Pi Native Prompt Slimming**
+
+- move the default Pi documentation block out of the system prompt and into a builtin `pi-docs` skill, so the docs reference loads on demand instead of sitting in every turn's prompt
+- unregister the native `write` tool, since `bash` can handle it
+
 ### 2. Smarter Tools
 
 Drop‑in replacements for Pi's built‑in tools, with better UX and fewer wasted turns.

package/hooks/inject-agents-md.ts

@@ -9,6 +9,17 @@ import { dirname, resolve, relative, join, normalize } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import type { Module } from "./skeleton.js";
 
+function isInsideSkillDir(filePath: string): boolean {
+    let dir = dirname(resolve(filePath));
+    while (true) {
+        if (existsSync(join(dir, "SKILL.md"))) return true;
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return false;
+}
+
 const CUSTOM_TYPE = "decorated-pi.subdir-agents";
 const AGENTS_NAMES = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
 
@@ -86,7 +97,12 @@ function findNewAgents(
     return results.reverse();
 }
 
-export const __subdirAgentsTest = { restoreFromBranch, findNewAgents };
+export const __subdirAgentsTest = { restoreFromBranch, findNewAgents, isInsideSkillDir };
+
+export const INJECT_AGENTS_MD_GUIDANCE = [
+    "### Context Loading, AGENTS.md / CLAUDE.md are auto-injected",
+    "- DO NOT read any **AGENTS.md** or **CLAUDE.md** files unless you're explicitly asked to, these files will loaded automatically if necessary.",
+].join("\n");
 
 export const injectAgentsMdModule: Module = {
     name: "inject-agents-md",
@@ -111,7 +127,9 @@ export const injectAgentsMdModule: Module = {
                 if (event.toolName !== "read" && event.toolName !== "edit")
                     return;
                 const path = (event.input as { path?: string })?.path;
-                if (path) pendingPaths.set(event.toolCallId, path);
+                if (!path) return;
+                if (isInsideSkillDir(resolve(path))) return;
+                pendingPaths.set(event.toolCallId, path);
             },
         ],
         tool_result: [
@@ -152,13 +170,3 @@ export const injectAgentsMdModule: Module = {
         ],
     },
 };
-
-/**
- * System-prompt guidance for the inject-agents-md hook — tells the
- * LLM not to waste tool calls re-reading AGENTS.md / CLAUDE.md, since
- * this hook already auto-injects them.
- */
-export const INJECT_AGENTS_MD_GUIDANCE = [
-    "### Context Loading, AGENTS.md / CLAUDE.md are auto-injected",
-    "- DO NOT read any **AGENTS.md** or **CLAUDE.md** files unless you're explicitly asked to, these files will loaded automatically if necessary.",
-].join("\n");

package/hooks/mcp.ts

@@ -21,7 +21,7 @@ interface ServerStatus {
   name: string;
   url: string;
   source: string;
-  state: "connecting" | "connected" | "failed" | "disabled" | "waiting_reload";
+  state: "connecting" | "connected" | "failed" | "disabled" | "waiting reload";
   toolCount: number;
   tools: Array<{ name: string; description?: string; inputSchema?: Record<string, unknown> }>;
   error?: string;
@@ -36,6 +36,45 @@ function canUseServer(config: McpServerConfig, cwd?: string): boolean {
   return config.canUseInProject(cwd ?? process.cwd());
 }
 
+function markServerFailed(config: McpServerConfig, error: string): void {
+  allServers.set(config.name, {
+    name: config.name,
+    url: config.url ?? config.command ?? "(unknown)",
+    source: config.source,
+    state: "failed",
+    toolCount: 0,
+    tools: [],
+    error,
+  });
+}
+
+function markServerConnected(config: McpServerConfig, tools: McpToolCache[]): void {
+  allServers.set(config.name, {
+    name: config.name,
+    url: config.url ?? config.command ?? "(unknown)",
+    source: config.source,
+    state: "connected",
+    toolCount: tools.length,
+    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+  });
+}
+
+function markServerState(
+  name: string,
+  state: "disabled" | "waiting reload" | "connecting",
+  config: { url?: string; command?: string; source: string } | undefined,
+): void {
+  allServers.set(name, {
+    name,
+    url: config?.url ?? config?.command ?? "(unknown)",
+    source: config?.source ?? "unknown",
+    state,
+    toolCount: 0,
+    tools: [],
+  });
+}
+
+
 async function connectAll(
   configs: McpServerConfig[],
   registry: any,
@@ -51,7 +90,7 @@ async function connectAll(
   // every caller's updates are visible.
   allServers.clear();
   for (const s of configs) {
-    allServers.set(s.name, { name: s.name, url: s.url ?? s.command ?? "(unknown)", source: s.source, state: "connecting", toolCount: 0, tools: [] });
+    markServerState(s.name, "connecting", s);
   }
 
   // Watchdog: the inner Promise.race in McpConnection.connect() has a
@@ -87,11 +126,7 @@ async function connectAll(
     if (watchdogFired) break; // remaining servers are already failed
 
     if (!canUseServer(server, cachedCwd || undefined)) {
-      allServers.set(server.name, {
-        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-        state: "failed", toolCount: 0, tools: [],
-        error: "Project is missing required artefacts for this server",
-      });
+      markServerFailed(server, "Project is missing required artefacts for this server");
       continue;
     }
 
@@ -108,11 +143,7 @@ async function connectAll(
         // failed state and do NOT write an empty cache, otherwise a
         // subsequent /reload will keep using the empty cache forever.
         try { await conn.disconnect(); } catch { /* ignore */ }
-        allServers.set(server.name, {
-          name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-          state: "failed", toolCount: 0, tools: [],
-          error: "Server connected but returned no tools (e.g. codegraph without a .codegraph index)",
-        });
+        markServerFailed(server, "Server connected but returned no tools (e.g. codegraph without a .codegraph index)");
         continue;
       }
       activeConnections.push(conn);
@@ -134,19 +165,13 @@ async function connectAll(
           schemaChanges.push(`${server.name} (${parts.join(', ')})`);
         }
       }
-      allServers.set(server.name, {
-        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-        state: "connected", toolCount: conn.tools.length, tools: actualTools,
-      });
       const tools: McpToolCache[] = conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+      markServerConnected(server, tools);
       updateServerCache(server.name, { tools, cachedAt: Date.now() }, cacheScopeForSource(server.source), cachedCwd || undefined);
     } catch (err) {
       if (watchdogFired) return { schemaChanges, hasNewServer };
       const msg = err instanceof Error ? err.message : String(err);
-      allServers.set(server.name, {
-        name: server.name, url: server.url ?? server.command ?? "(unknown)", source: server.source,
-        state: "failed", toolCount: 0, tools: [], error: msg,
-      });
+      markServerFailed(server, msg);
     }
   }
 
@@ -174,7 +199,7 @@ export function getMcpStatus(): ServerStatus[] {
     // or was toggled enabled after startup and needs /reload.
     result.push({
       name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source,
-      state: config.enabled ? "waiting_reload" : "disabled",
+      state: config.enabled ? "waiting reload" : "disabled",
       toolCount: cachedEntry?.tools.length ?? 0, tools: cachedEntry?.tools ?? [],
     });
   }
@@ -194,35 +219,23 @@ export async function updateConfigEnabled(serverName: string, enabled: boolean):
       activeConnections = activeConnections.filter(c => c.serverName !== serverName);
     }
     // Mark the server as disabled in allServers (or add it if absent).
-    allServers.set(serverName, {
-      name: serverName,
-      url: config?.url ?? config?.command ?? "(unknown)",
-      source: config?.source ?? "unknown",
-      state: "disabled",
-      toolCount: 0,
-      tools: [],
-    });
+    markServerState(serverName, "disabled", config ?? undefined);
     return;
   }
 
   // Re-enabling at runtime: the config is now enabled but tools aren't
   // registered until the next session_start. Mark it as waiting_reload
   // so the user sees exactly why the server isn't usable yet.
-  allServers.set(serverName, {
-    name: serverName,
-    url: config?.url ?? config?.command ?? "(unknown)",
-    source: config?.source ?? "unknown",
-    state: "waiting reload",
-    toolCount: 0,
-    tools: [],
-  });
+  markServerState(serverName, "waiting reload", config ?? undefined);
 }
 
 export async function refreshServerCache(serverName: string, registry: any): Promise<{ ok: boolean; error?: string }> {
   const config = resolveMcpConfigs(cachedCwd).find(s => s.name === serverName);
   if (!config) return { ok: false, error: `Server "${serverName}" not found in config.` };
   if (!canUseServer(config, cachedCwd || undefined)) {
-    return { ok: false, error: "Project is missing required artefacts for this server" };
+    const error = "Project is missing required artefacts for this server";
+    markServerFailed(config, error);
+    return { ok: false, error };
   }
   const existing = activeConnections.find(c => c.serverName === serverName);
   if (existing) {
@@ -236,21 +249,17 @@ export async function refreshServerCache(serverName: string, registry: any): Pro
     if (conn.tools.length === 0) {
       try { await conn.disconnect(); } catch { /* ignore */ }
       const error = "Server connected but returned no tools (e.g. codegraph without a .codegraph index)";
-      allServers.set(config.name, { name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source, state: "failed", toolCount: 0, tools: [], error });
+      markServerFailed(config, error);
       return { ok: false, error };
     }
     activeConnections.push(conn);
-    allServers.set(config.name, {
-      name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source,
-      state: "connected", toolCount: conn.tools.length,
-      tools: conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
-    });
     const tools: McpToolCache[] = conn.tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+    markServerConnected(config, tools);
     updateServerCache(config.name, { tools, cachedAt: Date.now() }, cacheScopeForSource(config.source), cachedCwd || undefined);
     return { ok: true };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    allServers.set(config.name, { name: config.name, url: config.url ?? config.command ?? "(unknown)", source: config.source, state: "failed", toolCount: 0, tools: [], error: msg });
+    markServerFailed(config, msg);
     return { ok: false, error: msg };
   }
 }
@@ -277,7 +286,10 @@ export function getCachedMcpConfigs(): McpServerConfig[] {
  * can find it.
  */
 export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerConfig, cwd?: string): Promise<void> {
-  if (!canUseServer(config, cwd)) return;
+  if (!canUseServer(config, cwd)) {
+    markServerFailed(config, "Project is missing required artefacts for this server");
+    return;
+  }
 
   const scope = cacheScopeForSource(config.source);
   const cache = loadScopedMcpCache(scope, cwd);
@@ -303,15 +315,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
       // Empty tool list means the server is not useful. Disconnect and
       // leave cache untouched so the next /reload retries the connection.
       try { await conn.disconnect(); } catch { /* ignore */ }
-      allServers.set(config.name, {
-        name: config.name,
-        url: config.url ?? config.command ?? "(unknown)",
-        source: config.source,
-        state: "failed",
-        toolCount: 0,
-        tools: [],
-        error: "Server connected but returned no tools (e.g. codegraph without a .codegraph index)",
-      });
+      markServerFailed(config, "Server connected but returned no tools (e.g. codegraph without a .codegraph index)");
       return;
     }
     activeConnections.push(conn);
@@ -320,6 +324,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
       description: t.description,
       inputSchema: t.inputSchema,
     }));
+    markServerConnected(config, tools);
     updateServerCache(config.name, { tools, cachedAt: Date.now() }, scope, cwd);
     for (const t of tools) {
       try {
@@ -328,15 +333,7 @@ export async function ensureMcpServerReady(pi: ExtensionAPI, config: McpServerCo
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    allServers.set(config.name, {
-      name: config.name,
-      url: config.url ?? config.command ?? "(unknown)",
-      source: config.source,
-      state: "failed",
-      toolCount: 0,
-      tools: [],
-      error: `No cache and initial connect failed: ${msg}`,
-    });
+    markServerFailed(config, `No cache and initial connect failed: ${msg}`);
   }
 }
 

package/hooks/pi-tool-filter.ts

@@ -2,6 +2,7 @@
  * pi-tool-filter — unregister pi native tools that are replaced by our extensions.
  *
  *   edit   → replaced by patch
+ *   write  → replaced by patch
  *   grep   → replaced by bash
  *   find   → replaced by bash
  *   ls     → replaced by bash
@@ -9,7 +10,7 @@
 
 import type { Module, Skeleton } from "./skeleton.js";
 
-const TOOLS_TO_DROP = new Set(["edit", "grep", "find", "ls"]);
+const TOOLS_TO_DROP = new Set(["edit", "write", "grep", "find", "ls"]);
 
 export const piToolFilterModule: Module = {
   name: "pi-tool-filter",

package/hooks/rtk.ts

@@ -160,12 +160,13 @@ export const rtkModule: Module = {
 
 export function setupRtk(sk: Skeleton, pi: ExtensionAPI): void {
   rtkBinary = findSystemRtk();
-  sk.declareDependency({
+  const ready = sk.declareDependency({
     label: "rtk",
+    module: "rtk",
     check: () => findSystemRtk() !== null,
     hint: "Install RTK so bash rewrite/tagging can activate.",
   });
-  if (!rtkBinary) return;
+  if (!ready) return;
 
   // Register a wrapped bash tool that shows [RTK] tag in TUI.
   const shellSettings = loadPiShellSettings(process.cwd());

package/hooks/skeleton.ts

@@ -2,9 +2,9 @@
  * Skeleton — the only place that calls pi.on(...) for hooks.
  *
  *   sk.register(module)         → installs module's hook handlers
- *   sk.declareDependency({...}) → skeleton checks on session_start
+ *   sk.declareDependency({...}) → check now, report on session_start
  *   sk.declareGuideline("...") → skeleton injects on before_agent_start
- *   sk.install(pi)             → call once, after all setup<X> calls
+ *   sk.install(pi)              → call once, after all setup<X> calls
  *
  * Handlers receive (event, ctx, pi) so they can call pi.* APIs
  * (setSessionName, registerTool, appendEntry, etc.).
@@ -64,6 +64,8 @@ export interface Dependency {
   label: string;
   check: () => boolean;
   hint?: string;
+  /** Display/source tag for inspection and notifications. */
+  module?: string;
 }
 
 /** Collected result shape for a module's declared dependency. Modules
@@ -88,7 +90,8 @@ const COMPOSE_EVENTS = new Set<HookEvent>([
 
 export interface Skeleton {
   register(module: Module): void;
-  declareDependency(dep: Dependency): void;
+  /** Returns whether the dependency check passed right now. */
+  declareDependency(dep: Dependency): boolean;
   install(pi: ExtensionAPI): void;
   inspect(): Inspection;
 }
@@ -96,13 +99,14 @@ export interface Skeleton {
 export interface Inspection {
   modules: string[];
   events: Record<string, Array<{ module: string; order: number }>>;
-  dependencies: Array<{ label: string; hint?: string }>;
+  dependencies: Array<{ label: string; module?: string; hint?: string }>;
 }
 
 export function createSkeleton(): Skeleton {
   const modules: Module[] = [];
   const registry = new Map<HookEvent, Array<{ module: string; handler: (event: any, ctx: ExtensionContext, pi: ExtensionAPI) => any }>>();
   const dependencies: Dependency[] = [];
+  let dependencyNotifyTimer: ReturnType<typeof setTimeout> | undefined;
 
   function collect(mod: Module) {
     for (const [event, handlers] of Object.entries(mod.hooks)) {
@@ -123,6 +127,11 @@ export function createSkeleton(): Skeleton {
 
     declareDependency(dep) {
       dependencies.push(dep);
+      try {
+        return dep.check();
+      } catch {
+        return false;
+      }
     },
 
     install(pi) {
@@ -146,21 +155,40 @@ export function createSkeleton(): Skeleton {
       }
 
       // Skeleton-owned: dependency check on session_start.
-      pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
+      // Defer with setTimeout(0) so the notification fires AFTER pi's
+      // startup/reload UI rebuild (rebuildChatFromMessages); otherwise it
+      // is appended to the chat and immediately wiped.
+      const runDependencyCheck = (ctx: ExtensionContext) => {
         if (!ctx.hasUI) return;
-        const hints: string[] = [];
-        let anyMissing = false;
-        for (const dep of dependencies) {
-          let ok = false;
-          try { ok = dep.check(); } catch { ok = false; }
-          if (!ok) {
-            anyMissing = true;
-            if (dep.hint) hints.push(`  [${dep.label}] ${dep.hint}`);
+        if (dependencyNotifyTimer) clearTimeout(dependencyNotifyTimer);
+        dependencyNotifyTimer = setTimeout(() => {
+          dependencyNotifyTimer = undefined;
+          const missing: string[] = [];
+          for (const dep of dependencies) {
+            let ok = false;
+            try { ok = dep.check(); } catch { ok = false; }
+            if (!ok) missing.push(dep.label);
           }
-        }
-        if (anyMissing) {
-          ctx.ui.notify(`[decorated-pi] missing dependencies:\n${hints.join("\n")}`, "info");
-        }
+          if (missing.length) {
+            try {
+              ctx.ui.notify(`[decorated-pi] missing dependencies: ${missing.join(", ")}`, "info");
+            } catch {
+              // Extension context may be stale if another reload/session switch happened.
+            }
+          }
+        }, 0);
+      };
+      pi.on("session_start", async (event: any, ctx: ExtensionContext) => {
+        // Only check on cold startup and explicit reload — other reasons
+        // (new/resume/fork) inherit the existing session's tool/runtime
+        // and don't need a fresh check.
+        if (event.reason !== "startup" && event.reason !== "reload") return;
+        runDependencyCheck(ctx);
+      });
+      pi.on("session_shutdown", async () => {
+        if (!dependencyNotifyTimer) return;
+        clearTimeout(dependencyNotifyTimer);
+        dependencyNotifyTimer = undefined;
       });
 
       // Skeleton-owned: system-prompt options sort for cache stability.
@@ -179,7 +207,7 @@ export function createSkeleton(): Skeleton {
       return {
         modules: modules.map((m) => m.name),
         events,
-        dependencies: dependencies.map((d) => ({ label: d.label, hint: d.hint })),
+        dependencies: dependencies.map((d) => ({ label: d.label, module: d.module, hint: d.hint })),
       };
     },
   };

package/hooks/smart-at.ts

@@ -5,6 +5,14 @@
  * FFF maintains an in-memory index, scores files by fuzzy match +
  * frecency + git status, and returns ranked results. We create one
  * FileFinder per session and query it directly for every @ prefix.
+ *
+ * KNOWN FFF LIMITATION (v0.9.4):
+ * FFF only returns directories that directly contain files. Intermediate
+ * folders that only hold subdirectories (e.g. product/module/apmanage/ where
+ * all files live in product/module/apmanage/deep/) will not appear in
+ * mixedSearch/directorySearch results, even though the files underneath do.
+ * We intentionally do NOT synthesize these directories on the TypeScript side
+ * to avoid extra complexity/cost; the fix belongs upstream.
  */
 
 import { FileFinder, type MixedItem } from "@ff-labs/fff-node";

package/hooks/wakatime.ts

@@ -342,12 +342,13 @@ export function setupWakatimeWithApiKey(
 export function setupWakatime(sk: Skeleton, pi: ExtensionAPI): void {
   const apiKey = readWakatimeCfgApiKey();
   const cliPath = findWakatimeCli();
-  sk.declareDependency({
+  const ready = sk.declareDependency({
     label: "wakatime-cli",
+    module: "wakatime",
     check: () => findWakatimeCli() !== null,
     hint: "Install wakatime-cli to track coding activity.",
   });
-  if (!apiKey || !cliPath) return;
+  if (!apiKey || !cliPath || !ready) return;
 
   const sendHeartbeat: HeartbeatSender = (hb, cwd) => sendHeartbeatViaCli(hb, apiKey, cliPath, cwd);