pi-fovea 0.13.0 → 0.13.2

package/README.md

@@ -172,7 +172,7 @@ details.
 
 ## Turn sync
 
-Continuous sync is on by default. Before an agent starts, Fovea establishes its
+Continuous sync is enabled and visible by default. Before an agent starts, Fovea establishes its
 baseline or injects any outside drift ahead of the first model call. After
 every assistant turn it compares symbols, calls, imports, literals, and anchors
 again. Content hashes keep the unchanged fast path cheap. Edits that touch only
@@ -186,7 +186,9 @@ It lists the causal channels behind each link: calls, imports, shared literals,
 tests, or co-change history. By default it also embeds the refreshed focus
 context of the top drift target (push). With `sync.pushFocus` off, the update
 ends with a suggested focus probe for the next call (pull). Clean turns stay
-silent. Enable `sync.ackClean` if you want an ack for those.
+silent. Enable `sync.ackClean` if you want an ack for those. Set `sync.mode` to
+`"hidden"` to keep red sync context working behind the scenes without rendering it
+in the transcript, or to `"disabled"` to turn continuous sync off.
 
 Runtime controls:
 
@@ -195,7 +197,8 @@ Runtime controls:
 - `/fovea reload`: hot-reload extensions and activate newly installed source
 - `/fovea settings`: configure sync, budgets, and hybrid grep
 
-Turn sync off per repo or globally through settings, or with:
+Choose enabled, hidden, or disabled per repo or globally through settings. The
+environment override still turns sync off with:
 
 ```sh
 FOVEA_TURN_SYNC=off pi
@@ -209,7 +212,7 @@ with `fabric.json`.
 
 | Key | Default | Meaning |
 | --- | :-----: | ------- |
-| `sync.enabled` | `true` | pre-agent and post-turn continuous sync |
+| `sync.mode` | `"enabled"` | `"enabled"` shows model-visible sync messages, `"hidden"` keeps them model-visible but out of the transcript, and `"disabled"` turns sync off. Legacy `sync.enabled` booleans still parse. |
 | `sync.budget` | `512` | token cap for proactive steering context |
 | `sync.ackClean` | `false` | toast after clean structural turns |
 | `sync.steerThreshold` | `0.15` | total surprise (channel-weighted heat above the session sync memory) that justifies proactive model steering |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",
@@ -52,8 +52,8 @@
     "fovea": "dist/cli.mjs"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.0",
-    "@earendil-works/pi-tui": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.1",
     "tsx": "^4.19.0",

package/src/core/config.ts

@@ -8,9 +8,12 @@ import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import fs from "node:fs";
 import path from "node:path";
 
+export const SYNC_MODES = ["enabled", "hidden", "disabled"] as const;
+export type SyncMode = (typeof SYNC_MODES)[number];
+
 interface FoveaSyncConfig {
-  /** turn_end feedback loop on/off (the default-on, opt-out knob). */
-  enabled: boolean;
+  /** Continuous sync delivery: visible, model-only, or fully disabled. */
+  mode: SyncMode;
   /** Token budget for proactive model steering context. */
   budget: number;
   /** Also send a tiny model-visible ack on clean turns (default false: silent green). */
@@ -47,7 +50,7 @@ export interface FoveaConfig {
 
 export const DEFAULT_FOVEA_CONFIG: FoveaConfig = {
   sync: {
-    enabled: true,
+    mode: "enabled",
     budget: 512,
     ackClean: false,
     // Masses are heat units leaked outside the changed files (1 unit seeded
@@ -97,10 +100,8 @@ const clamp = (id: string, value: number): number => {
 const boolValue = (value: unknown, fallback: boolean): boolean =>
   typeof value === "boolean" ? value : fallback;
 
-const grepModeValue = (value: unknown, fallback: GrepMode): GrepMode =>
-  typeof value === "string" && (GREP_MODES as readonly string[]).includes(value)
-    ? (value as GrepMode)
-    : fallback;
+const enumValue = <T extends string>(value: unknown, values: readonly T[], fallback: T): T =>
+  typeof value === "string" && values.includes(value as T) ? value as T : fallback;
 
 const intValue = (id: string, value: unknown, fallback: number): number =>
   clamp(id, typeof value === "number" && Number.isFinite(value) ? value : fallback);
@@ -118,7 +119,12 @@ const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
   const tools = (typeof src.tools === "object" && src.tools !== null ? src.tools : {}) as Record<string, unknown>;
   return {
     sync: {
-      enabled: boolValue(sync.enabled, base.sync.enabled),
+      // Legacy `enabled` booleans map to visible/disabled. An explicit mode wins.
+      mode: enumValue(
+        sync.mode,
+        SYNC_MODES,
+        typeof sync.enabled === "boolean" ? (sync.enabled ? "enabled" : "disabled") : base.sync.mode,
+      ),
       budget: intValue("sync.budget", sync.budget, base.sync.budget),
       ackClean: boolValue(sync.ackClean, base.sync.ackClean),
       steerThreshold: floatValue("sync.steerThreshold", sync.steerThreshold, base.sync.steerThreshold),
@@ -128,8 +134,9 @@ const applyPartial = (base: FoveaConfig, partial: unknown): FoveaConfig => {
       defaultBudget: intValue("tools.defaultBudget", tools.defaultBudget, base.tools.defaultBudget),
       // Legacy `replaceGrep` (v0.10): true -> "replace", false -> "off". An
       // explicit `grepMode` always wins over the legacy key.
-      grepMode: grepModeValue(
+      grepMode: enumValue(
         tools.grepMode,
+        GREP_MODES,
         typeof tools.replaceGrep === "boolean" ? (tools.replaceGrep ? "replace" : "off") : base.tools.grepMode,
       ),
       grepAugmentBudget: intValue("tools.grepAugmentBudget", tools.grepAugmentBudget, base.tools.grepAugmentBudget),
@@ -155,7 +162,7 @@ export const loadFoveaConfig = (scopes: FoveaConfigScopes): FoveaConfig => {
   }
   // Environment override mirrors pi-fabric's PI_* precedence over stored values.
   const off = process.env.FOVEA_TURN_SYNC;
-  if (off === "off" || off === "0" || off === "false") config = { ...config, sync: { ...config.sync, enabled: false } };
+  if (off === "off" || off === "0" || off === "false") config = { ...config, sync: { ...config.sync, mode: "disabled" } };
   return config;
 };
 

package/src/index.ts

@@ -68,6 +68,8 @@ const requestsNativeGrep = (params: {
     !ROUTE_PATH.test(params.pattern.trim()));
 
 const text = (s: string) => ({ type: "text" as const, text: s });
+const syncRuns = (config: FoveaConfig): boolean => config.sync.mode !== "disabled";
+const syncDisplays = (config: FoveaConfig): boolean => config.sync.mode === "enabled";
 
 const NODE_KINDS = new Set<NodeKind>([
   "function", "method", "class", "interface", "type", "field", "decl", "file", "anchor",
@@ -264,7 +266,7 @@ export default function fovea(pi: ExtensionAPI) {
     const rels = turnFiles
       .map((p) => (p.startsWith(root + "/") ? p.slice(root.length + 1) : p))
       .filter((p) => !p.startsWith("/"));
-    if (!rels.length || !cfg.sync.enabled) return;
+    if (!rels.length || !syncRuns(cfg)) return;
     const files = [...rels];
     const existing = warmTimers.get(root);
     if (existing) clearTimeout(existing);
@@ -299,7 +301,7 @@ export default function fovea(pi: ExtensionAPI) {
   pi.on("before_agent_start", async (_event, ctx) => {
     try {
       const cfg = configFor(ctx.cwd, ctx.isProjectTrusted());
-      if (!cfg.sync.enabled) return;
+      if (!syncRuns(cfg)) return;
       const outcome = await sync(
         ctx.cwd,
         { files: [], budget: cfg.sync.budget, steerThreshold: cfg.sync.steerThreshold, pushFocus: cfg.sync.pushFocus },
@@ -315,7 +317,7 @@ export default function fovea(pi: ExtensionAPI) {
           message: {
             customType: "pi-fovea-sync",
             content: outcome.text,
-            display: true,
+            display: syncDisplays(cfg),
             details: outcome.details,
           },
         };
@@ -337,7 +339,7 @@ export default function fovea(pi: ExtensionAPI) {
         .map((p) => (p.startsWith(ctx.cwd + "/") ? p.slice(ctx.cwd.length + 1) : p))
         .filter((p) => !p.startsWith("/"));
       turnFiles = [];
-      if (!cfg.sync.enabled) return;
+      if (!syncRuns(cfg)) return;
       const outcome = await sync(
         ctx.cwd,
         { files: rels, budget: cfg.sync.budget, steerThreshold: cfg.sync.steerThreshold, pushFocus: cfg.sync.pushFocus },
@@ -352,7 +354,7 @@ export default function fovea(pi: ExtensionAPI) {
         pi.sendMessage({
           customType: "pi-fovea-sync",
           content: outcome.text,
-          display: true,
+          display: syncDisplays(cfg),
           details: outcome.details,
         }, { deliverAs: "steer", triggerTurn: true });
       } else if (!outcome.details.baseline && cfg.sync.ackClean && ctx.hasUI) {
@@ -549,7 +551,7 @@ export default function fovea(pi: ExtensionAPI) {
           `${failedCount ? ` · !${failedCount} files failed extraction` : ""}` +
           `${unreadableCount ? ` · !${unreadableCount} files unreadable` : ""}` +
           `${oversizedCount ? ` · !${oversizedCount} files over size cap` : ""} · ` +
-          `sync ${cfg.sync.enabled ? "continuous" : "off"} · grep ${cfg.tools.grepMode} · ` +
+          `sync ${cfg.sync.mode} · grep ${cfg.tools.grepMode} · ` +
           `${astGrep.code === 0 ? astGrep.stdout.trim() : "ast-grep unavailable"}`,
           "info",
         );

package/src/ui/settings.ts

@@ -29,6 +29,7 @@ import {
 import {
   buildPartialFromId,
   loadFoveaConfig,
+  SYNC_MODES,
   saveFoveaConfig,
   type FoveaConfig,
   type FoveaConfigScope,
@@ -235,10 +236,10 @@ const buildItems = (
   theme: Theme,
   config: FoveaConfig,
 ): SettingItem[] => [
-  setting("sync.enabled", "Continuous sync", config.sync.enabled ? "true" : "false", {
+  setting("sync.mode", "Continuous sync", config.sync.mode, {
     description:
-      "Check semantic drift before agent start and after every turn; inject or steer before the model continues. FOVEA_TURN_SYNC=off overrides.",
-    values: BOOLEANS,
+      "enabled shows sync messages; hidden delivers them to the model without rendering them in the transcript; disabled turns sync off. FOVEA_TURN_SYNC=off overrides.",
+    values: SYNC_MODES,
   }),
   setting("sync.budget", "Sync budget", String(config.sync.budget), {
     description: "Max tokens for proactive repository steering sent to the model.",