decorated-pi 0.7.2 → 0.7.3

package/hooks/skeleton.ts

@@ -11,6 +11,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isDontBother } from "../settings.js";
 
 // ─── Event union ───────────────────────────────────────────────────────────
 
@@ -42,13 +43,24 @@ export type ComposeHandler<E extends HookEvent> = (
   pi: ExtensionAPI,
 ) => any | Promise<any>;
 
+/** Result: each handler sees the original event; the last non-undefined
+ *  return value wins. Matches runner.emit()'s behavior for `session_before_*`
+ *  events, where the runner collects a single `{ cancel?, compaction? }`
+ *  result from all extensions. Use for events whose contract is "the
+ *  extension either overrides or steps aside". */
+export type ResultHandler<E extends HookEvent> = (
+  event: any,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+) => any | Promise<any>;
+
 export interface Module {
   readonly name: string;
   readonly hooks: {
     session_start?: ParallelHandler<"session_start">[];
     session_shutdown?: ParallelHandler<"session_shutdown">[];
     session_compact?: ParallelHandler<"session_compact">[];
-    session_before_compact?: ParallelHandler<"session_before_compact">[];
+    session_before_compact?: ResultHandler<"session_before_compact">[];
     before_agent_start?: ComposeHandler<"before_agent_start">[];
     agent_start?: ParallelHandler<"agent_start">[];
     agent_end?: ParallelHandler<"agent_end">[];
@@ -61,10 +73,8 @@ export interface Module {
 // ─── Declarations ──────────────────────────────────────────────────────────
 
 export interface Dependency {
-  label: string;
-  check: () => boolean;
+  name: string;
   hint?: string;
-  /** Display/source tag for inspection and notifications. */
   module?: string;
 }
 
@@ -75,9 +85,12 @@ export interface Dependency {
  *  uses `Dependency.check` directly rather than collecting statuses. */
 export interface DependencyStatus {
   module: string;
+  /** Binary/config key, not necessarily the resolved absolute path. */
   label: string;
   state: "ok" | "missing";
   detail: string;
+  /** Resolved executable path when state is ok. */
+  path?: string;
 }
 
 // ─── Skeleton ──────────────────────────────────────────────────────────────
@@ -88,10 +101,23 @@ const COMPOSE_EVENTS = new Set<HookEvent>([
   "tool_result",
 ]);
 
+/** Events whose handler return value is propagated to the extension runner
+ *  (no chaining — each handler sees the original event, last non-undefined
+ *  return wins). Required for `session_before_compact`, whose contract is
+ *  `{ cancel?, compaction? }`; without this, hooks can't override pi's
+ *  default compaction. */
+const RESULT_EVENTS = new Set<HookEvent>([
+  "session_before_compact",
+]);
+
 export interface Skeleton {
   register(module: Module): void;
   /** Returns whether the dependency check passed right now. */
-  declareDependency(dep: Dependency): boolean;
+  /** Declare that a binary dependency is missing. Module calls this
+   *   after its own which() lookup failed. Skeleton dedupes by name,
+   *   honors `dependencies[name].dontBother`, and shows a single
+   *   "run /dp-settings" notification on session_start. */
+  declareMissing(dep: Omit<Dependency, "module"> & { module?: string }): void;
   install(pi: ExtensionAPI): void;
   inspect(): Inspection;
 }
@@ -99,7 +125,7 @@ export interface Skeleton {
 export interface Inspection {
   modules: string[];
   events: Record<string, Array<{ module: string; order: number }>>;
-  dependencies: Array<{ label: string; module?: string; hint?: string }>;
+  dependencies: Array<{ name: string; module?: string; hint?: string }>;
 }
 
 export function createSkeleton(): Skeleton {
@@ -125,13 +151,10 @@ export function createSkeleton(): Skeleton {
       collect(mod);
     },
 
-    declareDependency(dep) {
-      dependencies.push(dep);
-      try {
-        return dep.check();
-      } catch {
-        return false;
-      }
+    declareMissing(dep) {
+      // Dedupe by name — multiple modules may depend on the same binary.
+      if (dependencies.some((d) => d.name === dep.name)) return;
+      dependencies.push(dep as Dependency);
     },
 
     install(pi) {
@@ -147,6 +170,15 @@ export function createSkeleton(): Skeleton {
             }
             return current === event ? undefined : current;
           });
+        } else if (RESULT_EVENTS.has(event)) {
+          pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
+            let result;
+            for (const { handler } of handlers) {
+              const r = await handler(event, ctx, pi);
+              if (r !== undefined) result = r;
+            }
+            return result;
+          });
         } else {
           pi.on(event as any, async (event: any, ctx: ExtensionContext) => {
             for (const { handler } of handlers) await handler(event, ctx, pi);
@@ -165,13 +197,16 @@ export function createSkeleton(): Skeleton {
           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);
+            // dontBother flag silences the notification per-binary.
+            if (isDontBother(dep.name)) continue;
+            missing.push(dep.name);
           }
           if (missing.length) {
             try {
-              ctx.ui.notify(`[decorated-pi] missing dependencies: ${missing.join(", ")}`, "info");
+              ctx.ui.notify(
+                `[decorated-pi] Some dependencies are missing (${missing.length}). Run /dp-settings → Dependencies to configure.`,
+                "info",
+              );
             } catch {
               // Extension context may be stale if another reload/session switch happened.
             }
@@ -207,7 +242,7 @@ export function createSkeleton(): Skeleton {
       return {
         modules: modules.map((m) => m.name),
         events,
-        dependencies: dependencies.map((d) => ({ label: d.label, module: d.module, hint: d.hint })),
+        dependencies: dependencies.map((d) => ({ name: d.name, module: d.module, hint: d.hint })),
       };
     },
   };

package/hooks/smart-at.ts

@@ -93,7 +93,15 @@ export const smartAtModule: Module = {
     session_start: [
       async (_event: any, ctx: ExtensionContext) => {
         const cwd = String(ctx.cwd || "").trim();
-        const created = FileFinder.create({ basePath: cwd || "." });
+        // Always opt in to home/root scanning. These flags are opt-in guards
+        // in FFF — when cwd is a normal project, they're no-ops; when cwd
+        // IS $HOME or /, they let FFF index it. Without them, create() fails
+        // outright when cwd is a home/root, leaving the user without @-search.
+        const created = FileFinder.create({
+          basePath: cwd || ".",
+          enableHomeDirScanning: true,
+          enableFsRootScanning: true,
+        });
         if (!created.ok) {
           // FFF not available on this platform; silently skip.
           return;
@@ -102,11 +110,18 @@ export const smartAtModule: Module = {
         const finder = created.value;
         currentFinder = finder;
 
+        let scanWidgetVisible = false;
+
         // Start the scan in the background. We don't wait for it here so
-        // session_start returns immediately; the provider queries the
-        // (possibly partial) index and FFF returns whatever it has indexed
-        // so far. Full results appear as the scan progresses.
-        void finder.waitForScan(60_000);
+        // session_start returns immediately. If a scanning status was shown,
+        // clear it when the scan finishes even if no new autocomplete request
+        // is triggered afterwards.
+        void finder.waitForScan(60_000).then(() => {
+          if (currentFinder === finder && !finder.isDestroyed && scanWidgetVisible) {
+            scanWidgetVisible = false;
+            ctx.ui.setWidget("smart-at", undefined);
+          }
+        });
 
         ctx.ui.addAutocompleteProvider((orig: any) => ({
           getSuggestions: (
@@ -142,18 +157,47 @@ export const smartAtModule: Module = {
               return null;
             }
 
+            // 0 items during the initial scan means FFF is not ready yet.
+            // Autocomplete has no non-selectable dropdown state: returning an
+            // item would force SelectList to render a selectable "→ ..." row.
+            // So use a static below-editor widget while scanning, and clear it
+            // once the scan completes (see waitForScan above). After scanning,
+            // 0 items just means "no match".
+            if (r.value.items.length === 0) {
+              if (finder.isScanning()) {
+                scanWidgetVisible = true;
+                ctx.ui.setWidget(
+                  "smart-at",
+                  ["⏳ scanning…  (indexing files, please wait)"],
+                  { placement: "belowEditor" },
+                );
+              } else {
+                scanWidgetVisible = false;
+                ctx.ui.setWidget("smart-at", undefined);
+              }
+              return null;
+            }
+
             const result = buildResult(r.value.items, lowerQuery);
             if (!result) {
               ctx.ui.setWidget("smart-at", undefined);
               return null;
             }
 
+            scanWidgetVisible = false;
             ctx.ui.setWidget("smart-at", [WIDGET_FOOTER]);
             return Promise.resolve({ ...result, prefix });
           },
-          applyCompletion: (...args: any[]) => {
+          applyCompletion: (
+            lines: string[],
+            cl: number,
+            cc: number,
+            item: { value: string; label: string },
+            prefix: string,
+          ) => {
+            scanWidgetVisible = false;
             ctx.ui.setWidget("smart-at", undefined);
-            return orig.applyCompletion.apply(orig, args);
+            return orig.applyCompletion(lines, cl, cc, item, prefix);
           },
           shouldTriggerFileCompletion:
             orig.shouldTriggerFileCompletion?.bind(orig),

package/hooks/wakatime.ts

@@ -6,10 +6,11 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { execFile, execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { resolveDependency } from "../settings.js";
 import { fileURLToPath } from "node:url";
 import type { Module, Skeleton } from "./skeleton.js";
 
@@ -122,36 +123,21 @@ export function buildPluginString(version = PACKAGE_VERSION): string {
   return `pi/${version} pi/${version}`;
 }
 
+export function wakatimeDependencyExtendPath(): string[] {
+  return [path.join(os.homedir(), ".wakatime")];
+}
+
 function findWakatimeCliOnPath(): string | null {
-  try {
-    if (process.platform === "win32") {
-      const output = execFileSync("where", ["wakatime-cli"], { encoding: "utf-8" }).trim();
-      const first = output.split(/\r?\n/)[0]?.trim();
-      return first ? path.resolve(first) : null;
-    }
-    const shell = process.env.SHELL || "sh";
-    const output = execFileSync(shell, ["-lc", "command -v wakatime-cli"], { encoding: "utf-8" }).trim();
-    return output ? path.resolve(output) : null;
-  } catch {
-    return null;
-  }
+  return resolveDependency("wakatime-cli", { extendPath: wakatimeDependencyExtendPath() });
 }
 
 export function findWakatimeCli(options: {
   probePath?: () => string | null;
-  exists?: (candidate: string) => boolean;
-  fallbackPath?: string;
 } = {}): string | null {
   if (cachedWakatimeCliPath !== undefined) return cachedWakatimeCliPath;
   const probePath = options.probePath ?? findWakatimeCliOnPath;
-  const exists = options.exists ?? fs.existsSync;
-  const fromPath = probePath();
-  if (fromPath) {
-    cachedWakatimeCliPath = path.resolve(fromPath);
-    return cachedWakatimeCliPath;
-  }
-  const fallback = path.resolve(options.fallbackPath ?? WAKATIME_CLI_FALLBACK);
-  cachedWakatimeCliPath = exists(fallback) ? fallback : null;
+  const found = probePath();
+  cachedWakatimeCliPath = found ? path.resolve(found) : null;
   return cachedWakatimeCliPath;
 }
 
@@ -342,13 +328,14 @@ export function setupWakatimeWithApiKey(
 export function setupWakatime(sk: Skeleton, pi: ExtensionAPI): void {
   const apiKey = readWakatimeCfgApiKey();
   const cliPath = findWakatimeCli();
-  const ready = sk.declareDependency({
-    label: "wakatime-cli",
-    module: "wakatime",
-    check: () => findWakatimeCli() !== null,
-    hint: "Install wakatime-cli to track coding activity.",
-  });
-  if (!apiKey || !cliPath || !ready) return;
+  if (!cliPath) {
+    sk.declareMissing({
+      name: "wakatime-cli",
+      module: "wakatime",
+      hint: "Install wakatime-cli to track coding activity.",
+    });
+  }
+  if (!apiKey || !cliPath) return;
 
   const sendHeartbeat: HeartbeatSender = (hb, cwd) => sendHeartbeatViaCli(hb, apiKey, cliPath, cwd);
 

package/index.ts

@@ -214,7 +214,7 @@ export default async function (pi: ExtensionAPI) {
 
   // Compaction + RTK (these also install their own pi.on via setup<>()).
   setupCompaction(sk);
-  if (isModuleEnabled("rtk")) setupRtk(sk, pi);
+  if (isModuleEnabled("rtk")) setupRtk(sk);
   if (isModuleEnabled("wakatime")) setupWakatime(sk, pi);
 
   // ── Tools (conditional on module switches) ────────────────────────────
@@ -225,11 +225,13 @@ export default async function (pi: ExtensionAPI) {
       registerLspTools(pi, new LspServerManager());
     }
     for (const dep of lspDeps) {
-      sk.declareDependency({
-        label: `lsp:${dep.label}`,
-        module: `lsp:${dep.label}`,
-        check: () => collectLspDependencyStatuses(process.cwd()).some((s) => s.label === dep.label && s.state === "ok"),
-      });
+      if (dep.state !== "ok") {
+        sk.declareMissing({
+          name: dep.label,
+          module: "lsp",
+          hint: dep.detail,
+        });
+      }
     }
   }
   if (isModuleEnabled("ask")) registerAskTool(pi);
@@ -245,11 +247,13 @@ export default async function (pi: ExtensionAPI) {
     sk.register(mcpModule);
     const mcpDeps = collectMcpDependencyStatuses(process.cwd());
     for (const dep of mcpDeps) {
-      sk.declareDependency({
-        label: dep.module,
-        module: dep.module,
-        check: () => collectMcpDependencyStatuses(process.cwd()).some((s) => s.module === dep.module && s.state === "ok"),
-      });
+      if (dep.state !== "ok") {
+        sk.declareMissing({
+          name: dep.label,  // binary name (e.g. "codegraph")
+          module: "mcp",
+          hint: dep.detail,
+        });
+      }
     }
     const configs = resolveMcpConfigs(process.cwd()).filter(s => s.enabled);
     // Per-server readiness: cache hit → register from cache (fast).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decorated-pi",
-    "version": "0.7.2",
+    "version": "0.7.3",
     "description": "decorated-pi is a practical enhancement pack for pi coding agent — token-efficient workflow, cache-friendly design, and smarter tools.",
     "keywords": [
         "pi",

package/settings.ts

@@ -7,6 +7,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import type { Model } from "@earendil-works/pi-ai";
+import { which } from "./utils/which.js";
 
 const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent");
 const CONFIG_FILE = path.join(CONFIG_DIR, "decorated-pi.json");
@@ -69,15 +70,46 @@ export interface UsageIndexEntry {
   mtime: number;
 }
 
+/** Per-binary dependency override.
+ *
+ *  Keyed by binary name (e.g. "rtk", "wakatime-cli", "gopls",
+ *  "codegraph"). `path` injects an extra search location into which();
+ *  `dontBother` silences missing-dependency notifications for this binary. */
+export interface DependencySettings {
+  /** Absolute path to the binary (file) or a directory to search. Injected
+   *  into which()'s extendPath, so it's tried before $PATH. */
+  path?: string;
+  /** When true, skeleton's missing-dependency notification skips this
+   *  binary. Use for binaries the user doesn't care about. */
+  dontBother?: boolean;
+}
+
+export interface DependencyView extends DependencySettings {
+  /** Runtime-only shadow value: what the resolver actually found.
+   *  Not persisted to decorated-pi.json and not written by /dp-settings. */
+  resolvedPath?: string;
+  /** Runtime-only shadow value: whether the resolver checked/found it. */
+  resolvedState?: "ok" | "missing";
+}
+
 export interface DecoratedPiConfig {
   imageModelKey?: string | null;
   compactModelKey?: string | null;
+  dependencies?: Record<string, DependencySettings>;
   providers?: Record<string, ProviderCache>;
   modules?: ModuleSettings;
   mcpServers?: Record<string, McpServerEntry>;
   usageIndex?: Record<string, UsageIndexEntry>;
 }
 
+/** Runtime view = real config plus in-memory shadow fields. The shadow has
+ *  the same top-level shape as config, but may enrich selected leaves with
+ *  runtime-only data. It is never persisted and /dp-settings writes only the
+ *  real config through setter functions. */
+export interface DecoratedPiConfigView extends Omit<DecoratedPiConfig, "dependencies"> {
+  dependencies?: Record<string, DependencyView>;
+}
+
 export function loadConfig(): DecoratedPiConfig {
   try {
     if (fs.existsSync(CONFIG_FILE)) {
@@ -99,6 +131,11 @@ export function saveConfig(config: Partial<DecoratedPiConfig>) {
   fs.writeFileSync(CONFIG_FILE, JSON.stringify({ ...current, ...config }, null, 2), "utf-8");
 }
 
+// Runtime-only shadow for the whole config. It mirrors DecoratedPiConfig's
+// top-level shape but is never persisted; runtime modules update it, and
+// /dp-settings reads the merged view for display only.
+const configShadow: DecoratedPiConfigView = {};
+
 // ─── 辅助 ──────────────────────────────────────────────────────────────────
 
 export function formatModelKey(m: Model<any>): string {
@@ -165,6 +202,77 @@ export function getCompactModelKey(): string | null {
   return loadConfig().compactModelKey ?? null;
 }
 
+/** Look up a binary's configured path override. Returns null when not set. */
+export function getDependencyPath(name: string): string | null {
+  return loadConfig().dependencies?.[name]?.path ?? null;
+}
+
+/** Whether missing-dependency notifications are silenced for this binary. */
+export function isDontBother(name: string): boolean {
+  return loadConfig().dependencies?.[name]?.dontBother === true;
+}
+
+export function getConfigView(): DecoratedPiConfigView {
+  const real = loadConfig();
+  const dependencyNames = new Set([
+    ...Object.keys(real.dependencies ?? {}),
+    ...Object.keys(configShadow.dependencies ?? {}),
+  ]);
+  const dependencies: Record<string, DependencyView> = {};
+  for (const name of dependencyNames) {
+    dependencies[name] = {
+      ...(real.dependencies?.[name] ?? {}),
+      ...(configShadow.dependencies?.[name] ?? {}),
+    };
+  }
+  return {
+    ...real,
+    ...configShadow,
+    dependencies: Object.keys(dependencies).length ? dependencies : undefined,
+  };
+}
+
+export function getDependencyView(name: string): DependencyView {
+  return getConfigView().dependencies?.[name] ?? {};
+}
+
+export function listDependencyViewNames(extraNames: string[] = []): string[] {
+  return [...new Set([
+    ...extraNames,
+    ...Object.keys(getConfigView().dependencies ?? {}),
+  ])].sort();
+}
+
+export function recordDependencyResolution(name: string, resolvedPath: string | null): void {
+  if (!configShadow.dependencies) configShadow.dependencies = {};
+  configShadow.dependencies[name] = {
+    ...(configShadow.dependencies[name] ?? {}),
+    ...(resolvedPath
+      ? { resolvedState: "ok" as const, resolvedPath }
+      : { resolvedState: "missing" as const, resolvedPath: undefined }),
+  };
+}
+
+/** Resolve a binary using dependency config plus caller-specific search
+ *  locations. Modules call this at startup/runtime; it records a shadow
+ *  view for /dp-settings but does not persist anything.
+ *
+ *  Order:
+ *    1. dependencies[name].path (file or directory)
+ *    2. opts.extendPath entries (file or directory)
+ *    3. $PATH
+ */
+export function resolveDependency(name: string, opts?: { extendPath?: string[] }): string | null {
+  const override = getDependencyPath(name);
+  const extendPath = [
+    ...(override ? [override] : []),
+    ...(opts?.extendPath ?? []),
+  ];
+  const resolved = which(name, { extendPath });
+  recordDependencyResolution(name, resolved);
+  return resolved;
+}
+
 // ─── Setter ─────────────────────────────────────────────────────────────────
 
 export function setImageModelKey(key: string | null) {
@@ -175,6 +283,47 @@ export function setCompactModelKey(key: string | null) {
   saveConfig({ compactModelKey: key });
 }
 
+/** Set or clear a binary's path override. Pass null to remove the path.
+ *  Preserves any dontBother flag on the same entry (精准修改不覆盖). */
+export function setDependencyPath(name: string, path: string | null) {
+  const current = loadConfig();
+  const deps = { ...(current.dependencies ?? {}) };
+  const existing = deps[name] ?? {};
+  if (path === null) {
+    const { path: _drop, ...rest } = existing;
+    if (Object.keys(rest).length === 0) {
+      delete deps[name];
+    } else {
+      deps[name] = rest;
+    }
+  } else {
+    deps[name] = { ...existing, path };
+  }
+  // Path edits are config writes; invalidate runtime-only resolution for
+  // this binary so /dp-settings never shows a stale pre-edit shadow path.
+  if (configShadow.dependencies?.[name]) delete configShadow.dependencies[name];
+  saveConfig({ dependencies: deps });
+}
+
+/** Set or clear a binary's dontBother flag. Pass false to re-enable
+ *  missing-dependency notifications. Preserves any path override. */
+export function setDontBother(name: string, dontBother: boolean) {
+  const current = loadConfig();
+  const deps = { ...(current.dependencies ?? {}) };
+  const existing = deps[name] ?? {};
+  if (dontBother) {
+    deps[name] = { ...existing, dontBother: true };
+  } else {
+    const { dontBother: _drop, ...rest } = existing;
+    if (Object.keys(rest).length === 0) {
+      delete deps[name];
+    } else {
+      deps[name] = rest;
+    }
+  }
+  saveConfig({ dependencies: deps });
+}
+
 // ─── Module Switches ──────────────────────────────────────────────────────────
 
 const DEFAULT_MODULES: Required<ModuleSettings> = {
@@ -321,14 +470,23 @@ export function getAllModuleSettings(): Required<ModuleSettings> {
  * reload is actually necessary.
  */
 let loadedModuleSnapshot: Required<ModuleSettings> | null = null;
+let loadedDependenciesSnapshot: Record<string, DependencySettings> | null = null;
 
 export function captureModuleSnapshot(): void {
   loadedModuleSnapshot = getAllModuleSettings();
+  loadedDependenciesSnapshot = loadConfig().dependencies ?? {};
 }
 
 export function moduleSnapshotChanged(): boolean {
   if (!loadedModuleSnapshot) return true;
-  return JSON.stringify(loadedModuleSnapshot) !== JSON.stringify(getAllModuleSettings());
+  if (JSON.stringify(loadedModuleSnapshot) !== JSON.stringify(getAllModuleSettings())) return true;
+  // Dependencies changes don't strictly require reload (which() reads the
+  // config file on every call), but prompt for consistency — the user
+  // might be mid-session and expect the new path to be picked up by hooks
+  // that captured the binary path at startup (rtk/wakatime).
+  const currentDeps = loadConfig().dependencies ?? {};
+  if (JSON.stringify(loadedDependenciesSnapshot) !== JSON.stringify(currentDeps)) return true;
+  return false;
 }
 
 // ─── Usage index (增量同步元数据) ─────────────────────────────────────────────

package/tools/ask/index.ts

@@ -19,9 +19,6 @@ const askQuestionSchema = Type.Object({
   question: Type.String({ description: "Question text shown to the user." }),
   options: Type.Optional(Type.Array(Type.String(), { description: "Options for single or multi choice." })),
   default: Type.Optional(Type.String({ description: "Default answer. For multi, comma-separated values." })),
-  allowCustom: Type.Optional(Type.Boolean({
-    description: "For single/multi: append an \"Other\" row that toggles into a free-text input. Lets the user enter a custom answer not in the preset list.",
-  })),
 });
 
 function formatAnswer(q: AskQuestion, value: string | string[]): string {