pi-fovea 0.3.2 → 0.3.3

package/README.md

@@ -29,6 +29,28 @@ After each assistant turn the map re-syncs incrementally. Detection reads conten
 | `fovea_focus` | what is this? | centered on a symbol, route path, or env key: hot nodes as signatures, neighbors as one-liners |
 | `fovea_dwell` | what else? | diffuses the field one step further and returns the delta |
 | `fovea_impact` | what does this touch? | warms everything a file, symbol, or PR base reaches across languages |
+| `grep` *(default override)* | where does this concept lead? | the same graph-backed focus through grep's familiar `pattern/path/glob/...` signature |
+
+The **Replace grep** toggle makes Fovea own Pi's `grep` tool slot. It is on by default. Familiar calls such as `grep({ pattern: "CreateUser", path: "src" })` navigate the code graph first; use `bash` with `rg` only when you need exact matching lines. Disable the toggle to restore the previous grep implementation. Changing the toggle reloads extensions so pi-fabric captures the same override and `pi.grep(...)` follows it inside `fabric_exec`.
+
+### pi-fabric
+
+Captured extension tools live under Fabric's `extensions` provider. Use the direct proxy when the action is known:
+
+```ts
+const result = await extensions.fovea_focus({ query: "CreateUserHandler", maxTokens: 2000 });
+return result.text;
+```
+
+For dynamic discovery, pass an object to `tools.search` and keep the returned namespaced ref:
+
+```ts
+const [action] = await tools.search({ query: "fovea_focus", limit: 5 });
+if (!action) return "Fovea is not captured";
+return tools.call({ ref: action.ref, args: { query: "CreateUserHandler" } });
+```
+
+The stable explicit ref is `extensions.fovea_focus`, not bare `fovea_focus` or `fovea.fovea_focus`.
 
 Two slash commands on top:
 
@@ -99,6 +121,7 @@ Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override
 | `sync.ackClean` | `false` | toast after clean structural turns |
 | `sync.warmFileThreshold` | `2` | warmed files unseen by the model that justify turning red |
 | `tools.defaultBudget` | `2000` | fallback maxTokens for the fovea_* tools |
+| `tools.replaceGrep` | `true` | replace Pi's grep slot with graph-backed Fovea navigation |
 
 ## How routes are found
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/skills/pi-fovea/SKILL.md

@@ -32,8 +32,9 @@ Sync is **mutation-path agnostic**: pi's edit/write tools, a pi-fabric `fabric_e
 
 When writing or editing code **inside a `fabric_exec` program**, the fovea tools exist but the fabric sandbox has no built-in knowledge of them (it lazy-loads tools). Key points:
 
-- Inside `fabric_exec`, discover them once with `await tools.search("fovea")` and call them through `tools.call({ ref, args })` — e.g. `{ ref: "fovea_focus", args: { query: "CreateUserHandler" } }`. They are ordinary pi tools; there is no fabric-specific wrapper.
-- Prefer a single `fovea_impact` call over hand-rolled grep fan-outs when computing what an edit touches — the graph already resolved imports/calls across Go, TypeScript, Python, and Java.
+- Inside `fabric_exec`, captured extension tools use the `extensions` provider. For a known action call `await extensions.fovea_focus({ query: "CreateUserHandler", maxTokens: 6000 })`.
+- For dynamic discovery, use `const hits = await tools.search({ query: "fovea_focus" })`, then call the returned namespaced ref with `tools.call({ ref: hits[0].ref, args: { query: "CreateUserHandler", maxTokens: 6000 } })`. The stable explicit ref is `extensions.fovea_focus`; bare `fovea_focus` and `fovea.fovea_focus` are invalid.
+- Prefer a single `extensions.fovea_impact(...)` call over hand-rolled grep fan-outs when computing what an edit touches — the graph already resolved imports/calls across Go, TypeScript, Python, and Java.
 - Any file mutation performed by the program (including `pi.edit`/`pi.write` calls inside the sandbox) is picked up by turn sync automatically, so post-edit verification does not need a re-sketch.
 - The sketch `details` field carries counts (`files`, `nodes`, `anchors`); the hot-node list is the graph's highest-value entry points. On an unfamiliar repo, fetch it once and reuse instead of rediscovering entry points per call.
 
@@ -43,4 +44,4 @@ The same engine runs headlessly as the `fovea` binary (repo root scan, plus JSON
 
 ## Settings
 
-`/fovea settings` in the TUI, or `fovea.config.json` at repo or user level. Relevant knobs: `sync.enabled`, `sync.budget`, `sync.warmFileThreshold` (files that must escape before a red sync fires), `tools.defaultBudget`.
+`/fovea settings` in the TUI, or `fovea.json` under `~/.pi/agent/` or a trusted repo's `.pi/` directory. Relevant knobs: `sync.enabled`, `sync.budget`, `sync.warmFileThreshold` (files that must escape before a red sync fires), `tools.defaultBudget`, and `tools.replaceGrep` (default on; installs a grep-compatible Fovea override and reloads extensions).

package/src/core/config.ts

@@ -22,6 +22,8 @@ interface FoveaSyncConfig {
 interface FoveaToolsConfig {
   /** Budget applied when a fovea_* tool call omits maxTokens. */
   defaultBudget: number;
+  /** Replace Pi's grep slot with a graph-backed fovea_focus adapter. */
+  replaceGrep: boolean;
 }
 
 export interface FoveaConfig {
@@ -38,6 +40,7 @@ export const DEFAULT_FOVEA_CONFIG: FoveaConfig = {
   },
   tools: {
     defaultBudget: 2000,
+    replaceGrep: true,
   },
 };
 
@@ -81,6 +84,7 @@ const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
     },
     tools: {
       defaultBudget: intValue("tools.defaultBudget", tools.defaultBudget, base.tools.defaultBudget),
+      replaceGrep: boolValue(tools.replaceGrep, base.tools.replaceGrep),
     },
   };
 };

package/src/index.ts

@@ -17,6 +17,15 @@ const BudgetParam = Type.Optional(
 const RootParam = Type.Optional(
   Type.String({ description: "Repo root to map. Defaults to the session working directory." }),
 );
+const GrepParams = Type.Object({
+  pattern: Type.String({ description: "Symbol, route, environment key, or file query for the Fovea code graph." }),
+  path: Type.Optional(Type.String({ description: "Compatibility path hint. Used as a fallback graph seed when pattern finds no node." })),
+  glob: Type.Optional(Type.String({ description: "Accepted for grep-call compatibility; Fovea navigation is graph-based rather than glob-filtered." })),
+  ignoreCase: Type.Optional(Type.Boolean({ description: "Accepted for grep-call compatibility; Fovea symbol matching is already case-insensitive." })),
+  literal: Type.Optional(Type.Boolean({ description: "Accepted for grep-call compatibility; the pattern is interpreted as a graph query." })),
+  context: Type.Optional(Type.Number({ description: "Accepted for grep-call compatibility; graph neighbors replace line context." })),
+  limit: Type.Optional(Type.Number({ description: "Accepted for grep-call compatibility; output is controlled by tools.defaultBudget." })),
+});
 
 const text = (s: string) => ({ type: "text" as const, text: s });
 
@@ -31,11 +40,54 @@ export default function fovea(pi: ExtensionAPI) {
     return cfg;
   };
 
-  pi.on("session_start", async (event) => {
+  let grepOverrideRegistered = false;
+  const registerGrepOverride = (): void => {
+    if (grepOverrideRegistered) return;
+    grepOverrideRegistered = true;
+    pi.registerTool({
+      name: "grep",
+      label: "grep (Fovea)",
+      description:
+        "Navigate the pi-fovea code graph through grep's familiar argument shape. Finds symbols, routes, environment keys, files, and their warm dependencies; it does not perform literal line matching. Use bash with rg only when exact text or regex matches are required.",
+      promptSnippet: "Navigate the Fovea code graph with a grep-compatible query",
+      promptGuidelines: [
+        "Use grep for graph-backed repository navigation before exact text search; when the Fovea override is active, grep centers the code graph on pattern and returns warm dependencies rather than matching lines.",
+        "Use bash with rg only when an exact literal or regular-expression text match is required after the Fovea-backed grep result.",
+      ],
+      parameters: GrepParams,
+      async execute(_id, params, _signal, _onUpdate, ctx) {
+        const root = ctx.cwd;
+        const budget = configFor(root, ctx.isProjectTrusted()).tools.defaultBudget;
+        const pattern = params.pattern.trim();
+        const pathHint = params.path?.replace(/^@/, "").trim();
+        let query = pattern || pathHint || params.pattern;
+        try {
+          let result = focus(root, query, budget);
+          if (Number(result.details.seeds ?? 0) === 0 && pathHint && pathHint !== "." && pathHint !== query) {
+            query = pathHint;
+            result = focus(root, query, budget);
+          }
+          return {
+            content: [text(result.text.replace(/^fovea focus/, "fovea grep"))],
+            details: { ...result.details, backend: "fovea", query },
+          };
+        } catch (error) {
+          return {
+            content: [text(String(error instanceof Error ? error.message : error))],
+            details: { backend: "fovea", query },
+            isError: true,
+          };
+        }
+      },
+    });
+  };
+
+  pi.on("session_start", async (event, ctx) => {
     if (event.reason === "new" || event.reason === "fork") {
       resetSessions();
       resetSyncBaselines();
     }
+    if (configFor(ctx.cwd, ctx.isProjectTrusted()).tools.replaceGrep) registerGrepOverride();
   });
 
   // Turn-sync loop. The tracker below is a hint accumulator only: pi's
@@ -179,14 +231,18 @@ export default function fovea(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       const sub = args.trim().split(/\s+/)[0] ?? "status";
       if (sub === "settings") {
-        await openFoveaSettings(ctx, { onConfigApplied: () => configs.clear() });
+        const result = await openFoveaSettings(ctx, { onConfigApplied: () => configs.clear() });
+        if (result.grepRegistrationChanged) {
+          ctx.ui.notify("Reloading extensions to apply the grep tool change…", "info");
+          await ctx.reload();
+        }
         return;
       }
       try {
         const s = sketch(ctx.cwd, 256);
         const cfg = configFor(ctx.cwd, ctx.isProjectTrusted());
         ctx.ui.notify(
-          `pi-fovea: ${s.details.files ?? 0} files, ${s.details.nodes ?? 0} nodes, ${s.details.anchors ?? 0} anchors · sync ${cfg.sync.enabled ? "on" : "off"}`,
+          `pi-fovea: ${s.details.files ?? 0} files, ${s.details.nodes ?? 0} nodes, ${s.details.anchors ?? 0} anchors · sync ${cfg.sync.enabled ? "on" : "off"} · grep ${cfg.tools.replaceGrep ? "fovea" : "native"}`,
           "info",
         );
       } catch (e) {

package/src/ui/settings.ts

@@ -194,6 +194,11 @@ const buildItems = (
         "How many undisclosed files must warm up during sync to justify a red message. Higher = fewer interruptions; route anchor shifts always escalate.",
       submenu: numericSubmenu(theme, THRESHOLDS, "Warm file threshold", "Disclosed-file warming count that escalates sync to red."),
     }),
+    setting("tools.replaceGrep", "Replace grep", config.tools.replaceGrep ? "true" : "false", {
+      description:
+        "Register a grep-compatible tool backed by fovea_focus instead of literal text search. Default on; changing it reloads extensions so Pi and Fabric see the new tool slot.",
+      values: BOOLEANS,
+    }),
     setting("tools.defaultBudget", "Default tool budget", String(config.tools.defaultBudget), {
       description: "Token budget applied when a fovea_* tool call omits maxTokens.",
       submenu: numericSubmenu(theme, BUDGETS, "Default tool budget", "Fallback maxTokens for fovea tools."),
@@ -206,13 +211,17 @@ export interface FoveaSettingsDeps {
   onConfigApplied?: () => void;
 }
 
+export interface FoveaSettingsResult {
+  grepRegistrationChanged: boolean;
+}
+
 export const openFoveaSettings = async (
   context: ExtensionContext,
   deps: FoveaSettingsDeps = {},
-): Promise<void> => {
+): Promise<FoveaSettingsResult> => {
   if (context.mode !== "tui") {
     context.ui.notify("Fovea settings are available in TUI mode", "warning");
-    return;
+    return { grepRegistrationChanged: false };
   }
   const agentDir = getAgentDir();
   const scopes = {
@@ -221,6 +230,7 @@ export const openFoveaSettings = async (
     projectTrusted: context.isProjectTrusted(),
   };
   let config = loadFoveaConfig(scopes);
+  const initialReplaceGrep = config.tools.replaceGrep;
   let dirty = false;
 
   const apply = (id: string, value: unknown): void => {
@@ -249,6 +259,7 @@ export const openFoveaSettings = async (
   });
 
   if (dirty) context.ui.notify("Fovea settings saved.", "info");
+  return { grepRegistrationChanged: config.tools.replaceGrep !== initialReplaceGrep };
 };
 
 // Local in-place merge so subsequent edits in the same overlay start from the