pi-fovea 0.3.1 → 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.1",
+  "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",
@@ -28,6 +28,9 @@
     "extensions": [
       "./src/index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg"
   },
   "exports": {
@@ -36,6 +39,7 @@
   "files": [
     "src",
     "cli.ts",
+    "skills",
     "media",
     "README.md",
     "LICENSE"

package/skills/pi-fovea/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pi-fovea
+description: Token-efficient repo navigation with the pi-fovea code graph. Use when you need to survey an unfamiliar repository, trace where a symbol or route lives and what depends on it, assess the blast radius of a change before editing, or re-orient after files have been edited mid-session (by any tool path, including bash and pi-fabric fabric_exec programs).
+---
+
+# pi-fovea
+
+pi-fovea maintains a cross-language code graph of the working repository — routes, symbols, imports, calls, string/env literals — and exposes it through progressive disclosure: cheap silhouettes first, detail only where you point it. It costs almost nothing until you ask, and it re-syncs automatically whenever file content drifts, no matter which tool made the edit.
+
+## The loop
+
+1. **`fovea_sketch`** — silhouettes only. Route/anchor inventory plus directory blobs ranked by heat. Start here in an unfamiliar repo. ~256–1024 tokens.
+2. **`fovea_focus` `<query>`** — point at a symbol name, route path (`/api/users/{id}`), env key, or file path. Hot nodes come back with full signatures; warm neighbors as one-liners; the periphery stays collapsed. Already-shown nodes are suppressed, so repeated focus calls stay cheap.
+3. **`fovea_dwell`** — optional second look. If a focus footer says more nodes are lit below the token threshold, dwell (diffusion time ×2) surfaces exactly those newcomers.
+4. **`fovea_impact`** — blast radius. Seed with explicit repo-relative `files`, symbol names for what-if analysis, or uncommitted changes (`base` works PR-style against a ref). Output is the predicted co-change cascade ordered by warmth.
+
+All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
+
+## Working rules
+
+- **Never bulk-read to find things.** Read what focus surfaced; let the graph answer "where is X" and "what uses X" instead of spawning searches.
+- **Impact before destructive edits.** One `fovea_impact` call is cheaper than rediscovering dependents by breaking them.
+- **Sketch is the safe opening bid.** If unsure, pay for a sketch; it almost never exceeds a few hundred tokens.
+
+## Turn sync
+
+After each assistant turn, pi-fovea diffs content hashes against its baseline. If edits moved route anchors or warmed files outside the session's disclosed set, a `[fovea turn sync]` message arrives in the next turn with the delta; otherwise everything stays silent. Treat that message as ground truth about mid-session state changes.
+
+Sync is **mutation-path agnostic**: pi's edit/write tools, a pi-fabric `fabric_exec` program's inner `pi.edit`, a bash heredoc, a subagent, or an editor save outside the session all register identically. Content hashes are the source of truth; tool events are not consulted for detection. In repos with no `.git` directory this is also the only drift signal — do not fall back to `git status` assumptions.
+
+## Using with pi-fabric (fabric_exec)
+
+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`, 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.
+
+## CLI
+
+The same engine runs headlessly as the `fovea` binary (repo root scan, plus JSON and TSV modes). Prefer the in-session tools unless you need scripting or a second opinion outside the extension's session state.
+
+## Settings
+
+`/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