decorated-pi 0.5.4 → 0.6.0

package/{extensions → hooks}/wakatime.ts

@@ -1,12 +1,8 @@
 /**
- * WakaTime — coding activity heartbeats for Pi sessions
+ * wakatime — coding activity heartbeats.
  *
- * Reads API key from ~/.wakatime.cfg and sends heartbeats to WakaTime using a
- * small runtime state machine:
- *   - before_agent_start → mark app activity
- *   - tool_result        → switch active entity/category based on real work
- *   - agent_end          → stop immediate activity, keepalive handles continuity
- *   - keepalive timer    → extend continuous activity while not idle
+ * Reads API key from ~/.wakatime.cfg and sends heartbeats via wakatime-cli.
+ * Owns its own timer state and the "active" entity.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -15,12 +11,11 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { Module, Skeleton } from "./skeleton.js";
 
 const MACHINE_NAME = os.hostname();
 const PACKAGE_VERSION = readPackageVersion();
 
-// ─── Config ────────────────────────────────────────────────────────────────
-
 const WAKATIME_CFG = path.join(os.homedir(), ".wakatime.cfg");
 const WAKATIME_CLI_FALLBACK = path.join(os.homedir(), ".wakatime", "wakatime-cli");
 const API_URL = "https://api.wakatime.com/api/v1";
@@ -31,7 +26,7 @@ const TIMER_TICK_MS = 15 * 1000;
 function readPackageVersion(): string {
   try {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const pkgPath = path.join(here, "..", "package.json");
+    const pkgPath = path.join(here, "package.json");
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
     return pkg.version?.trim() || "unknown";
   } catch {
@@ -49,11 +44,7 @@ export function readWakatimeCfgApiKey(configPath = WAKATIME_CFG): string | undef
   }
 }
 
-function getApiKey(): string | undefined {
-  return readWakatimeCfgApiKey();
-}
-
-// ─── Heartbeat types ───────────────────────────────────────────────────────
+// ─── Heartbeat types ──────────────────────────────────────────────────────
 
 interface Heartbeat {
   entity: string;
@@ -81,7 +72,7 @@ let timer: ReturnType<typeof setInterval> | null = null;
 let terminalInputUnsub: (() => void) | null = null;
 let cachedWakatimeCliPath: string | null | undefined;
 
-// ─── Helpers ───────────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────
 
 function extToLanguage(filePath: string): string | undefined {
   const ext = path.extname(filePath).toLowerCase();
@@ -122,12 +113,8 @@ function countLines(absPath: string): number | undefined {
 export function classifyBash(command: string | undefined): Heartbeat["category"] {
   const cmd = String(command ?? "").trim();
   if (!cmd) return "ai coding";
-  if (/\b(make|cmake|ninja|npm run build|pnpm build|yarn build|cargo build|go build)\b/i.test(cmd)) {
-    return "building";
-  }
-  if (/\b(pytest|vitest|jest|npm test|pnpm test|yarn test|go test|ctest|cargo test)\b/i.test(cmd)) {
-    return "running tests";
-  }
+  if (/\b(make|cmake|ninja|npm run build|pnpm build|yarn build|cargo build|go build)\b/i.test(cmd)) return "building";
+  if (/\b(pytest|vitest|jest|npm test|pnpm test|yarn test|go test|ctest|cargo test)\b/i.test(cmd)) return "running tests";
   return "ai coding";
 }
 
@@ -156,7 +143,6 @@ export function findWakatimeCli(options: {
   fallbackPath?: string;
 } = {}): string | null {
   if (cachedWakatimeCliPath !== undefined) return cachedWakatimeCliPath;
-
   const probePath = options.probePath ?? findWakatimeCliOnPath;
   const exists = options.exists ?? fs.existsSync;
   const fromPath = probePath();
@@ -164,28 +150,17 @@ export function findWakatimeCli(options: {
     cachedWakatimeCliPath = path.resolve(fromPath);
     return cachedWakatimeCliPath;
   }
-
   const fallback = path.resolve(options.fallbackPath ?? WAKATIME_CLI_FALLBACK);
   cachedWakatimeCliPath = exists(fallback) ? fallback : null;
   return cachedWakatimeCliPath;
 }
 
-export function buildCliArgs(
-  hb: Heartbeat,
-  apiKey: string,
-  cwd?: string,
-  plugin = buildPluginString(),
-): string[] {
+export function buildCliArgs(hb: Heartbeat, apiKey: string, cwd?: string, plugin = buildPluginString()): string[] {
   const args = [
-    "--entity", hb.entity,
-    "--entity-type", hb.type,
-    "--category", hb.category,
-    "--plugin", plugin,
-    "--key", apiKey,
-    "--time", String(hb.time),
+    "--entity", hb.entity, "--entity-type", hb.type, "--category", hb.category,
+    "--plugin", plugin, "--key", apiKey, "--time", String(hb.time),
     "--hostname", MACHINE_NAME,
   ];
-
   const shouldSendProjectFolder = hb.type === "app" || !!hb.project || typeof hb.project_root_count === "number";
   if (cwd && shouldSendProjectFolder) args.push("--project-folder", cwd);
   if (hb.project) args.push("--project", hb.project);
@@ -197,55 +172,32 @@ export function buildCliArgs(
 
 function sendHeartbeatViaCli(hb: Heartbeat, apiKey: string, cliPath: string, cwd?: string): void {
   const args = buildCliArgs(hb, apiKey, cwd);
-  execFile(cliPath, args, {
-    timeout: 10_000,
-    windowsHide: true,
-  }, () => {
-    // Silent: activity tracking must never interrupt the agent.
-  });
+  execFile(cliPath, args, { timeout: 10_000, windowsHide: true }, () => {});
 }
 
 export function heartbeatChanged(a: Omit<Heartbeat, "time">, b: Omit<Heartbeat, "time">): boolean {
-  return (
-    a.entity !== b.entity ||
-    a.type !== b.type ||
-    a.category !== b.category ||
-    a.project !== b.project ||
-    a.project_root_count !== b.project_root_count ||
-    a.language !== b.language
-  );
+  return a.entity !== b.entity || a.type !== b.type || a.category !== b.category
+    || a.project !== b.project || a.project_root_count !== b.project_root_count
+    || a.language !== b.language;
 }
 
-function switchActive(
-  next: Omit<Heartbeat, "time">,
-  sendHeartbeat: HeartbeatSender,
-  options: { immediate?: boolean; isWrite?: boolean; cwd?: string } = {},
-): void {
+function switchActive(next: Omit<Heartbeat, "time">, sendHeartbeat: HeartbeatSender, options: { immediate?: boolean; isWrite?: boolean; cwd?: string } = {}) {
   const now = Date.now();
   const changed = !active || heartbeatChanged(active.heartbeat, next);
-
-  active = {
-    heartbeat: next,
-    cwd: options.cwd,
-    lastActivityAt: now,
-    lastHeartbeatAt: active?.lastHeartbeatAt ?? 0,
-  };
-
+  active = { heartbeat: next, cwd: options.cwd, lastActivityAt: now, lastHeartbeatAt: active?.lastHeartbeatAt ?? 0 };
   if (changed || options.immediate || options.isWrite) {
     sendHeartbeat({ ...next, time: now / 1000, is_write: options.isWrite }, options.cwd);
     active.lastHeartbeatAt = now;
   }
 }
 
-function sendOneShot(hb: Omit<Heartbeat, "time">, sendHeartbeat: HeartbeatSender, isWrite?: boolean, cwd?: string): void {
+function sendOneShot(hb: Omit<Heartbeat, "time">, sendHeartbeat: HeartbeatSender, isWrite?: boolean, cwd?: string) {
   sendHeartbeat({ ...hb, time: Date.now() / 1000, is_write: isWrite }, cwd);
 }
 
-function touchActivity(): void {
-  if (active) active.lastActivityAt = Date.now();
-}
+function touchActivity() { if (active) active.lastActivityAt = Date.now(); }
 
-function ensureTimer(sendHeartbeat: HeartbeatSender): void {
+function ensureTimer(sendHeartbeat: HeartbeatSender) {
   if (timer) return;
   timer = setInterval(() => {
     if (!active) return;
@@ -257,38 +209,22 @@ function ensureTimer(sendHeartbeat: HeartbeatSender): void {
   }, TIMER_TICK_MS);
 }
 
-function clearTimer(): void {
+function clearTimer() {
   if (timer) clearInterval(timer);
   timer = null;
 }
 
 export function buildAppHeartbeat(cwd: string, category: Heartbeat["category"] = "ai coding"): Omit<Heartbeat, "time"> {
   const root = path.resolve(cwd);
-  return {
-    entity: "pi",
-    type: "app",
-    category,
-    project: path.basename(root) || undefined,
-    project_root_count: countPathParts(root),
-  };
+  return { entity: "pi", type: "app", category, project: path.basename(root) || undefined, project_root_count: countPathParts(root) };
 }
 
 export function buildFileHeartbeat(absPath: string, cwd: string, category: Heartbeat["category"] = "ai coding"): Omit<Heartbeat, "time"> {
   const meta = buildProjectMeta(absPath, cwd);
-  return {
-    entity: absPath,
-    type: "file",
-    category,
-    project: meta.project,
-    project_root_count: meta.project_root_count,
-    language: extToLanguage(absPath),
-    lines: countLines(absPath),
-  };
+  return { entity: absPath, type: "file", category, project: meta.project, project_root_count: meta.project_root_count, language: extToLanguage(absPath), lines: countLines(absPath) };
 }
 
-// ─── Setup ──────────────────────────────────────────────────────────────────
-
-export function resetWakatimeStateForTests(): void {
+export function resetWakatimeStateForTests() {
   active = null;
   clearTimer();
   if (terminalInputUnsub) terminalInputUnsub();
@@ -296,6 +232,42 @@ export function resetWakatimeStateForTests(): void {
   cachedWakatimeCliPath = undefined;
 }
 
+// ─── Module + setup ──────────────────────────────────────────────────────
+
+export const wakatimeModule: Module = {
+  name: "wakatime",
+  hooks: {
+    session_start: [
+      (_event, ctx) => {
+        active = null;
+        // Timer is set up in setupWakatime (needs API key + CLI).
+      },
+    ],
+    session_shutdown: [
+      () => {
+        active = null;
+        clearTimer();
+        if (terminalInputUnsub) terminalInputUnsub();
+        terminalInputUnsub = null;
+      },
+    ],
+    before_agent_start: [
+      (_event, ctx) => {
+        const cwd = ctx.cwd ?? process.cwd();
+        // Caller (setupWakatime) provides the actual sender; this module's
+        // before_agent_start is a no-op when not configured.
+        if (active && (Date.now() - active.lastActivityAt) <= IDLE_TIMEOUT_MS) {
+          active.heartbeat = buildAppHeartbeat(cwd, active.heartbeat.category);
+          active.lastActivityAt = Date.now();
+        }
+      },
+    ],
+    agent_end: [
+      () => { touchActivity(); },
+    ],
+  },
+};
+
 export function setupWakatimeWithApiKey(
   pi: ExtensionAPI,
   apiKey: string | undefined,
@@ -312,7 +284,6 @@ export function setupWakatimeWithApiKey(
     if (terminalInputUnsub) terminalInputUnsub();
     terminalInputUnsub = null;
     if (!ctx.hasUI) return;
-
     terminalInputUnsub = ctx.ui.onTerminalInput(() => {
       const cwd = ctx.cwd ?? process.cwd();
       const recent = active && (Date.now() - active.lastActivityAt) <= IDLE_TIMEOUT_MS;
@@ -335,69 +306,96 @@ export function setupWakatimeWithApiKey(
 
   pi.on("before_agent_start", (_event, ctx) => {
     const cwd = ctx.cwd ?? process.cwd();
-
-    // Keep the long-lived active heartbeat on the app entity (`pi`) so
-    // keepalive time accrues to the Pi editor itself. File heartbeats are sent
-    // separately as one-shots below; if we replaced `active` with a file entity,
-    // the dashboard would attribute nearly all time to the last touched file and
-    // Pi editor time would collapse toward zero.
     switchActive(buildAppHeartbeat(cwd), sendHeartbeat, { immediate: true, cwd });
   });
 
+  // File-level heartbeats as one-shots in tool_result (don't replace the active keepalive).
   pi.on("tool_result", (event, ctx) => {
     const cwd = ctx.cwd ?? process.cwd();
     const input = (event as any).input;
-
-    // File-level operations send one-shot heartbeats but never replace the
-    // keepalive entity — the app heartbeat stays active for accurate editor
-    // time attribution on the WakaTime dashboard.
     if (event.toolName === "read") {
       const filePath = input?.path ?? input?.file ?? input?.file_path;
       if (typeof filePath !== "string" || !filePath.trim()) return;
       const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
       sendOneShot(buildFileHeartbeat(absPath, cwd), sendHeartbeat, undefined, cwd);
       touchActivity();
-      return;
-    }
-
-    if (event.toolName === "patch") {
+    } else if (event.toolName === "patch") {
       const filePath = input?.path;
       if (typeof filePath !== "string" || !filePath.trim()) return;
       const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
       sendOneShot(buildFileHeartbeat(absPath, cwd), sendHeartbeat, true, cwd);
       touchActivity();
-      return;
+    } else if (event.toolName === "lsp_diagnostics") {
+      touchActivity();
+    } else if (event.toolName === "bash") {
+      const category = classifyBash(input?.command);
+      switchActive(buildAppHeartbeat(cwd, category), sendHeartbeat, { cwd });
+      touchActivity();
+    } else {
+      touchActivity();
     }
+  });
 
-    if (event.toolName === "lsp_document_symbols") {
-      const filePath = input?.path;
-      if (typeof filePath !== "string" || !filePath.trim()) return;
+  pi.on("agent_end", (_event, _ctx) => { touchActivity(); });
+}
+
+export function setupWakatime(sk: Skeleton, pi: ExtensionAPI): void {
+  const apiKey = readWakatimeCfgApiKey();
+  const cliPath = findWakatimeCli();
+  sk.declareDependency({
+    label: "wakatime-cli",
+    check: () => findWakatimeCli() !== null,
+    hint: "Install wakatime-cli to track coding activity.",
+  });
+  if (!apiKey || !cliPath) return;
+
+  const sendHeartbeat: HeartbeatSender = (hb, cwd) => sendHeartbeatViaCli(hb, apiKey, cliPath, cwd);
+
+  // Hook into session_start to set up timer + terminal input.
+  pi.on("session_start", (_event, ctx) => {
+    active = null;
+    ensureTimer(sendHeartbeat);
+    if (terminalInputUnsub) terminalInputUnsub();
+    terminalInputUnsub = null;
+    if (!ctx.hasUI) return;
+    terminalInputUnsub = ctx.ui.onTerminalInput(() => {
+      const cwd = ctx.cwd ?? process.cwd();
+      const recent = active && (Date.now() - active.lastActivityAt) <= IDLE_TIMEOUT_MS;
+      const isAppHeartbeat = active?.heartbeat.type === "app" && active.heartbeat.entity === "pi";
+      if (!recent || !isAppHeartbeat) {
+        switchActive(buildAppHeartbeat(cwd), sendHeartbeat, { immediate: true, cwd });
+      } else {
+        touchActivity();
+      }
+      return undefined;
+    });
+  });
+
+  // Tool result: auto-detect file operations, classify bash, touch activity
+  pi.on("tool_result", (event, ctx) => {
+    const cwd = ctx.cwd ?? process.cwd();
+    const input = (event as any).input;
+
+    // Auto-detect file operations from input shape
+    const filePath = input?.path ?? input?.file ?? input?.file_path;
+    if (typeof filePath === "string" && filePath.trim()) {
       const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
       sendOneShot(buildFileHeartbeat(absPath, cwd), sendHeartbeat, undefined, cwd);
       touchActivity();
       return;
     }
 
-    if (event.toolName === "lsp_diagnostics") {
-      touchActivity();
-      return;
-    }
-
+    // Bash needs special classification
     if (event.toolName === "bash") {
       const category = classifyBash(input?.command);
-      switchActive(buildAppHeartbeat(cwd, category), sendHeartbeat, { cwd });
+      if (active) active.heartbeat = { ...active.heartbeat, category };
+      touchActivity();
       return;
     }
 
+    // Everything else: just touch activity
     touchActivity();
   });
 
-  pi.on("agent_end", (_event, _ctx) => {
-    // Do not clear immediately; keepalive continues briefly until idle timeout.
-    touchActivity();
-  });
-}
-
-export function setupWakatime(pi: ExtensionAPI) {
-  setupWakatimeWithApiKey(pi, getApiKey(), findWakatimeCli());
+  sk.register(wakatimeModule);
 }

package/index.ts

@@ -1 +1,155 @@
-export { default } from "./extensions/index";
+/**
+ * decorated-pi — entry point.
+ *
+ * Three categories:
+ *   - tools/    : LLM-callable tools
+ *   - hooks/    : event handlers (registered via skeleton)
+ *   - commands/ : slash commands
+ *
+ * Plus:
+ *   - system-prompt guidelines: hard-coded base + per-module imports,
+ *     concatenated in array order, injected via pi.on("before_agent_start", ...)
+ *     in `installGuidelines` below.
+ *
+ * Skeleton is the only place that calls pi.on(...) for hooks. Tools,
+ * commands, and guideline injection register themselves directly with pi.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createSkeleton } from "./hooks/skeleton.js";
+
+import { setupRedact, REDACT_GUIDANCE } from "./hooks/redact.js";
+import { externalizeModule } from "./hooks/externalize.js";
+import { normalizeCodeblocksModule } from "./hooks/normalize-codeblocks.js";
+import { trackMtimeModule } from "./hooks/track-mtime.js";
+import { injectAgentsMdModule, INJECT_AGENTS_MD_GUIDANCE } from "./hooks/inject-agents-md.js";
+import { imageVisionModule } from "./hooks/image-vision.js";
+import { smartAtModule } from "./hooks/smart-at.js";
+import { sessionTitleModule } from "./hooks/session-title.js";
+import { piToolFilterModule } from "./hooks/pi-tool-filter.js";
+import { setupCompaction } from "./hooks/compaction.js";
+import { mcpModule } from "./hooks/mcp.js";
+import { setupWakatime, wakatimeModule } from "./hooks/wakatime.js";
+import { setupRtk } from "./hooks/rtk.js";
+
+import { registerPatchTool } from "./tools/patch/index.js";
+import { registerLspTools } from "./tools/lsp/tools.js";
+import { LspServerManager } from "./tools/lsp/manager.js";
+import { resolveMcpConfigs } from "./tools/mcp/config.js";
+import { ensureMcpServerReady } from "./hooks/mcp.js";
+import { CODEGRAPH_GUIDANCE } from "./tools/mcp/builtin/codegraph.js";
+
+import { registerDpModelCommand } from "./commands/dp-model.js";
+import { registerDpSettingsCommand } from "./commands/dp-settings.js";
+import { registerMcpStatusCommand } from "./commands/mcp-status.js";
+import { registerRetryCommand } from "./commands/retry.js";
+import { registerUsageCommand } from "./commands/usage.js";
+
+import { isModuleEnabled } from "./settings.js";
+
+// ─── System-prompt guidelines (hard-coded base, per-module imports) ────────
+//
+// Array order = prompt order. Add a new module's guidance by importing
+// its constant and pushing it here. No priority / sort logic — just push.
+
+const BASE_GUIDANCE = [
+  "## Decorated Pi Guidance",
+  "",
+  "### Workflow, how to approach tasks",
+  "- Before acting on a prompt: 1. ensure you fully understand the user's intent — if ambiguous, ask clarifying questions; 2. have researched the existing state — read files, search, investigate. Proceed only when both are clear.",
+  "- Exercise caution when performing any **write** operations, especially when you are in a research or exploration phase.",
+  "- Before modifying code, match the user's existing code style (naming, formatting, patterns). Do not re-modify lines the user has manually edited since your last change.",
+  "",
+  "### Filesystem Safety, where NOT to write",
+  "- 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");
+
+/** Build the list of guideline strings to inject, in prompt order.
+ *  Always-on rules first, then per-module guidelines (skipping disabled
+ *  modules). Add new per-module guidelines by importing the constant
+ *  here and pushing it inside an `isModuleEnabled(...)` guard. */
+function buildGuidelines(): string[] {
+  const out: string[] = [
+    BASE_GUIDANCE,
+    REDACT_GUIDANCE,             // from hooks/redact.ts — always on (safety module)
+    INJECT_AGENTS_MD_GUIDANCE,   // from hooks/inject-agents-md.ts — always on (smart-at module)
+  ];
+  if (isModuleEnabled("codegraph")) out.push(CODEGRAPH_GUIDANCE);
+  return out;
+}
+
+/** Install a single before_agent_start handler that appends every
+ *  guideline in order, stripping the volatile "Current date: …" line
+ *  for cache stability. Idempotent — re-injection is a no-op via marker. */
+function installGuidelines(pi: ExtensionAPI): void {
+  const blocks = buildGuidelines();
+  const joined = blocks.join("\n\n");
+  const marker = "## Decorated Pi Guidance";
+
+  pi.on("before_agent_start", async (event: any) => {
+    if (!event.systemPrompt) return undefined;
+    let prompt: string = event.systemPrompt.replace(/\nCurrent date: \d{4}-\d{2}-\d{2}/, "");
+    if (prompt.includes(marker)) return undefined; // already injected this turn
+    return { systemPrompt: `${prompt}\n\n${joined}` };
+  });
+}
+
+export default async function (pi: ExtensionAPI) {
+  // ── Skeleton (hooks) ───────────────────────────────────────────────────
+  const sk = createSkeleton();
+
+  // Order matters for tool_result compose chain:
+  //   1. redact → normalize-codeblocks → externalize → track-mtime → inject-agents-md → image-vision → wakatime
+  // The first module registered for a given event runs first (compose chain).
+  setupRedact(sk);
+  sk.register(normalizeCodeblocksModule);
+  sk.register(externalizeModule);
+  sk.register(trackMtimeModule);
+  sk.register(injectAgentsMdModule);
+  sk.register(imageVisionModule);
+
+  // session_start handlers (parallel)
+  // pi-tool-filter must register first so native tools are dropped before
+  // anything else inspects the tool list.
+  sk.register(piToolFilterModule);
+  sk.register(sessionTitleModule);
+  sk.register(smartAtModule);
+  sk.register(wakatimeModule);
+
+  // Compaction + RTK (these also install their own pi.on via setup<>()).
+  setupCompaction(sk);
+  setupRtk(sk, pi);
+  setupWakatime(sk, pi);
+
+  // ── Tools (conditional on module switches) ────────────────────────────
+  if (isModuleEnabled("patch")) registerPatchTool(pi);
+  if (isModuleEnabled("lsp")) registerLspTools(pi, new LspServerManager());
+
+  // MCP: hook AND tool are gated together. Disabling the module
+  // means no session_start handler runs, no tools register, and no
+  // background connections are attempted.
+  if (isModuleEnabled("mcp")) {
+    sk.register(mcpModule);
+    const configs = resolveMcpConfigs(process.cwd()).filter(s => s.enabled);
+    // Per-server readiness: cache hit → register from cache (fast).
+    // Cache miss → connect synchronously, write cache, then register
+    // live tools. This blocks startup only for cache-miss servers.
+    for (const config of configs) {
+      await ensureMcpServerReady(pi, config, process.cwd());
+    }
+  }
+
+  // ── System-prompt guidelines (single handler, array order = prompt order) ──
+  installGuidelines(pi);
+
+  // ── Commands ──────────────────────────────────────────────────────────
+  registerDpModelCommand(pi);
+  registerDpSettingsCommand(pi);
+  registerMcpStatusCommand(pi);
+  registerRetryCommand(pi);
+  registerUsageCommand(pi);
+
+  // ── Install skeleton (last) ────────────────────────────────────────────
+  sk.install(pi);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "decorated-pi",
-    "version": "0.5.4",
-    "description": "decorated-pi is a practical enhancement pack for pi — smarter tools that are token efficient and cache friendly.",
+    "version": "0.6.0",
+    "description": "decorated-pi is a practical enhancement pack for pi coding agent — token-efficient workflow, cache-friendly design, and smarter tools.",
     "keywords": [
         "pi",
         "pi-package",
@@ -33,7 +33,7 @@
     },
     "pi": {
         "extensions": [
-            "./extensions/index.ts"
+            "./index.ts"
         ]
     },
     "devDependencies": {
@@ -45,6 +45,7 @@
     "scripts": {
         "prepack": "depcheck --fail-on-missing",
         "test": "vitest run",
-        "prepublishOnly": "npm install --no-audit --no-fund && npm test && depcheck --fail-on-missing && publint"
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm install --no-audit --no-fund && npm test && npm run typecheck && depcheck --fail-on-missing && publint"
     }
 }

package/{extensions/settings.ts → settings.ts}

@@ -42,6 +42,13 @@ export interface ModuleSettings {
   mcp?: boolean;
   wakatime?: boolean;
   "rtk"?: boolean;
+  codegraph?: boolean;
+}
+
+export interface UsageIndexEntry {
+  inode: number;
+  size: number;
+  mtime: number;
 }
 
 export interface DecoratedPiConfig {
@@ -50,6 +57,7 @@ export interface DecoratedPiConfig {
   providers?: Record<string, ProviderCache>;
   modules?: ModuleSettings;
   mcpServers?: Record<string, McpServerEntry>;
+  usageIndex?: Record<string, UsageIndexEntry>;
 }
 
 export function loadConfig(): DecoratedPiConfig {
@@ -151,6 +159,7 @@ const DEFAULT_MODULES: Required<ModuleSettings> = {
   mcp: true,
   wakatime: true,
   "rtk": true,
+  codegraph: false,  // opt-in: heavy binary, not everyone wants it
 };
 
 export function isModuleEnabled(name: keyof ModuleSettings): boolean {
@@ -168,3 +177,26 @@ export function getAllModuleSettings(): Required<ModuleSettings> {
   const modules = loadConfig().modules ?? {};
   return { ...DEFAULT_MODULES, ...modules };
 }
+
+// ─── Codegraph (drives the builtin MCP server's auto-enable) ───────────────
+
+/**
+ * True when the user has enabled the codegraph module via /dp-settings.
+ * Default is OFF (opt-in) — `modules.codegraph` defaults to `false`.
+ * When true, the builtin MCP server is enabled and the CodeGraph
+ * guidance section is injected into the system prompt.
+ */
+export function isCodegraphModuleEnabled(): boolean {
+  return isModuleEnabled("codegraph");
+}
+
+// ─── Usage index (增量同步元数据) ─────────────────────────────────────────────
+
+/** 缓存的上次同步状态: { 文件路径 → { inode, size, mtime } } */
+export function loadUsageIndex(): Record<string, UsageIndexEntry> {
+  return loadConfig().usageIndex ?? {};
+}
+
+export function saveUsageIndex(index: Record<string, UsageIndexEntry>) {
+  saveConfig({ usageIndex: index });
+}